1/****************************************************************************
2 *
3 * ftincrem.h
4 *
5 * FreeType incremental loading (specification).
6 *
7 * Copyright (C) 2002-2023 by
8 * David Turner, Robert Wilhelm, and Werner Lemberg.
9 *
10 * This file is part of the FreeType project, and may only be used,
11 * modified, and distributed under the terms of the FreeType project
12 * license, LICENSE.TXT. By continuing to use, modify, or distribute
13 * this file you indicate that you have read the license and
14 * understand and accept it fully.
15 *
16 */
17
18
19#ifndef FTINCREM_H_
20#define FTINCREM_H_
21
22#include <freetype/freetype.h>
23#include <freetype/ftparams.h>
24
25#ifdef FREETYPE_H
26#error "freetype.h of FreeType 1 has been loaded!"
27#error "Please fix the directory search order for header files"
28#error "so that freetype.h of FreeType 2 is found first."
29#endif
30
31
32FT_BEGIN_HEADER
33
34 /**************************************************************************
35 *
36 * @section:
37 * incremental
38 *
39 * @title:
40 * Incremental Loading
41 *
42 * @abstract:
43 * Custom Glyph Loading.
44 *
45 * @description:
46 * This section contains various functions used to perform so-called
47 * 'incremental' glyph loading. This is a mode where all glyphs loaded
48 * from a given @FT_Face are provided by the client application.
49 *
50 * Apart from that, all other tables are loaded normally from the font
51 * file. This mode is useful when FreeType is used within another
52 * engine, e.g., a PostScript Imaging Processor.
53 *
54 * To enable this mode, you must use @FT_Open_Face, passing an
55 * @FT_Parameter with the @FT_PARAM_TAG_INCREMENTAL tag and an
56 * @FT_Incremental_Interface value. See the comments for
57 * @FT_Incremental_InterfaceRec for an example.
58 *
59 */
60
61
62 /**************************************************************************
63 *
64 * @type:
65 * FT_Incremental
66 *
67 * @description:
68 * An opaque type describing a user-provided object used to implement
69 * 'incremental' glyph loading within FreeType. This is used to support
70 * embedded fonts in certain environments (e.g., PostScript
71 * interpreters), where the glyph data isn't in the font file, or must be
72 * overridden by different values.
73 *
74 * @note:
75 * It is up to client applications to create and implement
76 * @FT_Incremental objects, as long as they provide implementations for
77 * the methods @FT_Incremental_GetGlyphDataFunc,
78 * @FT_Incremental_FreeGlyphDataFunc and
79 * @FT_Incremental_GetGlyphMetricsFunc.
80 *
81 * See the description of @FT_Incremental_InterfaceRec to understand how
82 * to use incremental objects with FreeType.
83 *
84 */
85 typedef struct FT_IncrementalRec_* FT_Incremental;
86
87
88 /**************************************************************************
89 *
90 * @struct:
91 * FT_Incremental_MetricsRec
92 *
93 * @description:
94 * A small structure used to contain the basic glyph metrics returned by
95 * the @FT_Incremental_GetGlyphMetricsFunc method.
96 *
97 * @fields:
98 * bearing_x ::
99 * Left bearing, in font units.
100 *
101 * bearing_y ::
102 * Top bearing, in font units.
103 *
104 * advance ::
105 * Horizontal component of glyph advance, in font units.
106 *
107 * advance_v ::
108 * Vertical component of glyph advance, in font units.
109 *
110 * @note:
111 * These correspond to horizontal or vertical metrics depending on the
112 * value of the `vertical` argument to the function
113 * @FT_Incremental_GetGlyphMetricsFunc.
114 *
115 */
116 typedef struct FT_Incremental_MetricsRec_
117 {
118 FT_Long bearing_x;
119 FT_Long bearing_y;
120 FT_Long advance;
121 FT_Long advance_v; /* since 2.3.12 */
122
123 } FT_Incremental_MetricsRec;
124
125
126 /**************************************************************************
127 *
128 * @struct:
129 * FT_Incremental_Metrics
130 *
131 * @description:
132 * A handle to an @FT_Incremental_MetricsRec structure.
133 *
134 */
135 typedef struct FT_Incremental_MetricsRec_* FT_Incremental_Metrics;
136
137
138 /**************************************************************************
139 *
140 * @type:
141 * FT_Incremental_GetGlyphDataFunc
142 *
143 * @description:
144 * A function called by FreeType to access a given glyph's data bytes
145 * during @FT_Load_Glyph or @FT_Load_Char if incremental loading is
146 * enabled.
147 *
148 * Note that the format of the glyph's data bytes depends on the font
149 * file format. For TrueType, it must correspond to the raw bytes within
150 * the 'glyf' table. For PostScript formats, it must correspond to the
151 * **unencrypted** charstring bytes, without any `lenIV` header. It is
152 * undefined for any other format.
153 *
154 * @input:
155 * incremental ::
156 * Handle to an opaque @FT_Incremental handle provided by the client
157 * application.
158 *
159 * glyph_index ::
160 * Index of relevant glyph.
161 *
162 * @output:
163 * adata ::
164 * A structure describing the returned glyph data bytes (which will be
165 * accessed as a read-only byte block).
166 *
167 * @return:
168 * FreeType error code. 0~means success.
169 *
170 * @note:
171 * If this function returns successfully the method
172 * @FT_Incremental_FreeGlyphDataFunc will be called later to release the
173 * data bytes.
174 *
175 * Nested calls to @FT_Incremental_GetGlyphDataFunc can happen for
176 * compound glyphs.
177 *
178 */
179 typedef FT_Error
180 (*FT_Incremental_GetGlyphDataFunc)( FT_Incremental incremental,
181 FT_UInt glyph_index,
182 FT_Data* adata );
183
184
185 /**************************************************************************
186 *
187 * @type:
188 * FT_Incremental_FreeGlyphDataFunc
189 *
190 * @description:
191 * A function used to release the glyph data bytes returned by a
192 * successful call to @FT_Incremental_GetGlyphDataFunc.
193 *
194 * @input:
195 * incremental ::
196 * A handle to an opaque @FT_Incremental handle provided by the client
197 * application.
198 *
199 * data ::
200 * A structure describing the glyph data bytes (which will be accessed
201 * as a read-only byte block).
202 *
203 */
204 typedef void
205 (*FT_Incremental_FreeGlyphDataFunc)( FT_Incremental incremental,
206 FT_Data* data );
207
208
209 /**************************************************************************
210 *
211 * @type:
212 * FT_Incremental_GetGlyphMetricsFunc
213 *
214 * @description:
215 * A function used to retrieve the basic metrics of a given glyph index
216 * before accessing its data. This allows for handling font types such
217 * as PCL~XL Format~1, Class~2 downloaded TrueType fonts, where the glyph
218 * metrics (`hmtx` and `vmtx` tables) are permitted to be omitted from
219 * the font, and the relevant metrics included in the header of the glyph
220 * outline data. Importantly, this is not intended to allow custom glyph
221 * metrics (for example, Postscript Metrics dictionaries), because that
222 * conflicts with the requirements of outline hinting. Such custom
223 * metrics must be handled separately, by the calling application.
224 *
225 * @input:
226 * incremental ::
227 * A handle to an opaque @FT_Incremental handle provided by the client
228 * application.
229 *
230 * glyph_index ::
231 * Index of relevant glyph.
232 *
233 * vertical ::
234 * If true, return vertical metrics.
235 *
236 * ametrics ::
237 * This parameter is used for both input and output. The original
238 * glyph metrics, if any, in font units. If metrics are not available
239 * all the values must be set to zero.
240 *
241 * @output:
242 * ametrics ::
243 * The glyph metrics in font units.
244 *
245 */
246 typedef FT_Error
247 (*FT_Incremental_GetGlyphMetricsFunc)
248 ( FT_Incremental incremental,
249 FT_UInt glyph_index,
250 FT_Bool vertical,
251 FT_Incremental_MetricsRec *ametrics );
252
253
254 /**************************************************************************
255 *
256 * @struct:
257 * FT_Incremental_FuncsRec
258 *
259 * @description:
260 * A table of functions for accessing fonts that load data incrementally.
261 * Used in @FT_Incremental_InterfaceRec.
262 *
263 * @fields:
264 * get_glyph_data ::
265 * The function to get glyph data. Must not be null.
266 *
267 * free_glyph_data ::
268 * The function to release glyph data. Must not be null.
269 *
270 * get_glyph_metrics ::
271 * The function to get glyph metrics. May be null if the font does not
272 * require it.
273 *
274 */
275 typedef struct FT_Incremental_FuncsRec_
276 {
277 FT_Incremental_GetGlyphDataFunc get_glyph_data;
278 FT_Incremental_FreeGlyphDataFunc free_glyph_data;
279 FT_Incremental_GetGlyphMetricsFunc get_glyph_metrics;
280
281 } FT_Incremental_FuncsRec;
282
283
284 /**************************************************************************
285 *
286 * @struct:
287 * FT_Incremental_InterfaceRec
288 *
289 * @description:
290 * A structure to be used with @FT_Open_Face to indicate that the user
291 * wants to support incremental glyph loading. You should use it with
292 * @FT_PARAM_TAG_INCREMENTAL as in the following example:
293 *
294 * ```
295 * FT_Incremental_InterfaceRec inc_int;
296 * FT_Parameter parameter;
297 * FT_Open_Args open_args;
298 *
299 *
300 * // set up incremental descriptor
301 * inc_int.funcs = my_funcs;
302 * inc_int.object = my_object;
303 *
304 * // set up optional parameter
305 * parameter.tag = FT_PARAM_TAG_INCREMENTAL;
306 * parameter.data = &inc_int;
307 *
308 * // set up FT_Open_Args structure
309 * open_args.flags = FT_OPEN_PATHNAME | FT_OPEN_PARAMS;
310 * open_args.pathname = my_font_pathname;
311 * open_args.num_params = 1;
312 * open_args.params = &parameter; // we use one optional argument
313 *
314 * // open the font
315 * error = FT_Open_Face( library, &open_args, index, &face );
316 * ...
317 * ```
318 *
319 */
320 typedef struct FT_Incremental_InterfaceRec_
321 {
322 const FT_Incremental_FuncsRec* funcs;
323 FT_Incremental object;
324
325 } FT_Incremental_InterfaceRec;
326
327
328 /**************************************************************************
329 *
330 * @type:
331 * FT_Incremental_Interface
332 *
333 * @description:
334 * A pointer to an @FT_Incremental_InterfaceRec structure.
335 *
336 */
337 typedef FT_Incremental_InterfaceRec* FT_Incremental_Interface;
338
339
340 /* */
341
342
343FT_END_HEADER
344
345#endif /* FTINCREM_H_ */
346
347
348/* END */
349