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 | |
32 | FT_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 = ¶meter; // 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 | |
343 | FT_END_HEADER |
344 | |
345 | #endif /* FTINCREM_H_ */ |
346 | |
347 | |
348 | /* END */ |
349 | |