|
1 /***************************************************************************/ |
|
2 /* */ |
|
3 /* ftincrem.h */ |
|
4 /* */ |
|
5 /* FreeType incremental loading (specification). */ |
|
6 /* */ |
|
7 /* Copyright 2002, 2003, 2006, 2007, 2008, 2010 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 <ft2build.h> |
|
23 #include FT_FREETYPE_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 interpreters), |
|
71 * where the glyph data isn't in the font file, or must be overridden by |
|
72 * different values. |
|
73 * |
|
74 * @note: |
|
75 * It is up to client applications to create and implement @FT_Incremental |
|
76 * objects, as long as they provide implementations for the methods |
|
77 * @FT_Incremental_GetGlyphDataFunc, @FT_Incremental_FreeGlyphDataFunc |
|
78 * and @FT_Incremental_GetGlyphMetricsFunc. |
|
79 * |
|
80 * See the description of @FT_Incremental_InterfaceRec to understand how |
|
81 * to use incremental objects with FreeType. |
|
82 * |
|
83 */ |
|
84 typedef struct FT_IncrementalRec_* FT_Incremental; |
|
85 |
|
86 |
|
87 /*************************************************************************** |
|
88 * |
|
89 * @struct: |
|
90 * FT_Incremental_MetricsRec |
|
91 * |
|
92 * @description: |
|
93 * A small structure used to contain the basic glyph metrics returned |
|
94 * by the @FT_Incremental_GetGlyphMetricsFunc method. |
|
95 * |
|
96 * @fields: |
|
97 * bearing_x :: |
|
98 * Left bearing, in font units. |
|
99 * |
|
100 * bearing_y :: |
|
101 * Top bearing, in font units. |
|
102 * |
|
103 * advance :: |
|
104 * Horizontal component of glyph advance, in font units. |
|
105 * |
|
106 * advance_v :: |
|
107 * Vertical component of glyph advance, in font units. |
|
108 * |
|
109 * @note: |
|
110 * These correspond to horizontal or vertical metrics depending on the |
|
111 * value of the `vertical' argument to the function |
|
112 * @FT_Incremental_GetGlyphMetricsFunc. |
|
113 * |
|
114 */ |
|
115 typedef struct FT_Incremental_MetricsRec_ |
|
116 { |
|
117 FT_Long bearing_x; |
|
118 FT_Long bearing_y; |
|
119 FT_Long advance; |
|
120 FT_Long advance_v; /* since 2.3.12 */ |
|
121 |
|
122 } FT_Incremental_MetricsRec; |
|
123 |
|
124 |
|
125 /*************************************************************************** |
|
126 * |
|
127 * @struct: |
|
128 * FT_Incremental_Metrics |
|
129 * |
|
130 * @description: |
|
131 * A handle to an @FT_Incremental_MetricsRec structure. |
|
132 * |
|
133 */ |
|
134 typedef struct FT_Incremental_MetricsRec_* FT_Incremental_Metrics; |
|
135 |
|
136 |
|
137 /*************************************************************************** |
|
138 * |
|
139 * @type: |
|
140 * FT_Incremental_GetGlyphDataFunc |
|
141 * |
|
142 * @description: |
|
143 * A function called by FreeType to access a given glyph's data bytes |
|
144 * during @FT_Load_Glyph or @FT_Load_Char if incremental loading is |
|
145 * enabled. |
|
146 * |
|
147 * Note that the format of the glyph's data bytes depends on the font |
|
148 * file format. For TrueType, it must correspond to the raw bytes within |
|
149 * the `glyf' table. For PostScript formats, it must correspond to the |
|
150 * *unencrypted* charstring bytes, without any `lenIV' header. It is |
|
151 * undefined for any other format. |
|
152 * |
|
153 * @input: |
|
154 * incremental :: |
|
155 * Handle to an opaque @FT_Incremental handle provided by the client |
|
156 * application. |
|
157 * |
|
158 * glyph_index :: |
|
159 * Index of relevant glyph. |
|
160 * |
|
161 * @output: |
|
162 * adata :: |
|
163 * A structure describing the returned glyph data bytes (which will be |
|
164 * accessed as a read-only byte block). |
|
165 * |
|
166 * @return: |
|
167 * FreeType error code. 0~means success. |
|
168 * |
|
169 * @note: |
|
170 * If this function returns successfully the method |
|
171 * @FT_Incremental_FreeGlyphDataFunc will be called later to release |
|
172 * the data bytes. |
|
173 * |
|
174 * Nested calls to @FT_Incremental_GetGlyphDataFunc can happen for |
|
175 * compound glyphs. |
|
176 * |
|
177 */ |
|
178 typedef FT_Error |
|
179 (*FT_Incremental_GetGlyphDataFunc)( FT_Incremental incremental, |
|
180 FT_UInt glyph_index, |
|
181 FT_Data* adata ); |
|
182 |
|
183 |
|
184 /*************************************************************************** |
|
185 * |
|
186 * @type: |
|
187 * FT_Incremental_FreeGlyphDataFunc |
|
188 * |
|
189 * @description: |
|
190 * A function used to release the glyph data bytes returned by a |
|
191 * successful call to @FT_Incremental_GetGlyphDataFunc. |
|
192 * |
|
193 * @input: |
|
194 * incremental :: |
|
195 * A handle to an opaque @FT_Incremental handle provided by the client |
|
196 * application. |
|
197 * |
|
198 * data :: |
|
199 * A structure describing the glyph data bytes (which will be accessed |
|
200 * as a read-only byte block). |
|
201 * |
|
202 */ |
|
203 typedef void |
|
204 (*FT_Incremental_FreeGlyphDataFunc)( FT_Incremental incremental, |
|
205 FT_Data* data ); |
|
206 |
|
207 |
|
208 /*************************************************************************** |
|
209 * |
|
210 * @type: |
|
211 * FT_Incremental_GetGlyphMetricsFunc |
|
212 * |
|
213 * @description: |
|
214 * A function used to retrieve the basic metrics of a given glyph index |
|
215 * before accessing its data. This is necessary because, in certain |
|
216 * formats like TrueType, the metrics are stored in a different place from |
|
217 * the glyph images proper. |
|
218 * |
|
219 * @input: |
|
220 * incremental :: |
|
221 * A handle to an opaque @FT_Incremental handle provided by the client |
|
222 * application. |
|
223 * |
|
224 * glyph_index :: |
|
225 * Index of relevant glyph. |
|
226 * |
|
227 * vertical :: |
|
228 * If true, return vertical metrics. |
|
229 * |
|
230 * ametrics :: |
|
231 * This parameter is used for both input and output. |
|
232 * The original glyph metrics, if any, in font units. If metrics are |
|
233 * not available all the values must be set to zero. |
|
234 * |
|
235 * @output: |
|
236 * ametrics :: |
|
237 * The replacement glyph metrics in font units. |
|
238 * |
|
239 */ |
|
240 typedef FT_Error |
|
241 (*FT_Incremental_GetGlyphMetricsFunc) |
|
242 ( FT_Incremental incremental, |
|
243 FT_UInt glyph_index, |
|
244 FT_Bool vertical, |
|
245 FT_Incremental_MetricsRec *ametrics ); |
|
246 |
|
247 |
|
248 /************************************************************************** |
|
249 * |
|
250 * @struct: |
|
251 * FT_Incremental_FuncsRec |
|
252 * |
|
253 * @description: |
|
254 * A table of functions for accessing fonts that load data |
|
255 * incrementally. Used in @FT_Incremental_InterfaceRec. |
|
256 * |
|
257 * @fields: |
|
258 * get_glyph_data :: |
|
259 * The function to get glyph data. Must not be null. |
|
260 * |
|
261 * free_glyph_data :: |
|
262 * The function to release glyph data. Must not be null. |
|
263 * |
|
264 * get_glyph_metrics :: |
|
265 * The function to get glyph metrics. May be null if the font does |
|
266 * not provide overriding glyph metrics. |
|
267 * |
|
268 */ |
|
269 typedef struct FT_Incremental_FuncsRec_ |
|
270 { |
|
271 FT_Incremental_GetGlyphDataFunc get_glyph_data; |
|
272 FT_Incremental_FreeGlyphDataFunc free_glyph_data; |
|
273 FT_Incremental_GetGlyphMetricsFunc get_glyph_metrics; |
|
274 |
|
275 } FT_Incremental_FuncsRec; |
|
276 |
|
277 |
|
278 /*************************************************************************** |
|
279 * |
|
280 * @struct: |
|
281 * FT_Incremental_InterfaceRec |
|
282 * |
|
283 * @description: |
|
284 * A structure to be used with @FT_Open_Face to indicate that the user |
|
285 * wants to support incremental glyph loading. You should use it with |
|
286 * @FT_PARAM_TAG_INCREMENTAL as in the following example: |
|
287 * |
|
288 * { |
|
289 * FT_Incremental_InterfaceRec inc_int; |
|
290 * FT_Parameter parameter; |
|
291 * FT_Open_Args open_args; |
|
292 * |
|
293 * |
|
294 * // set up incremental descriptor |
|
295 * inc_int.funcs = my_funcs; |
|
296 * inc_int.object = my_object; |
|
297 * |
|
298 * // set up optional parameter |
|
299 * parameter.tag = FT_PARAM_TAG_INCREMENTAL; |
|
300 * parameter.data = &inc_int; |
|
301 * |
|
302 * // set up FT_Open_Args structure |
|
303 * open_args.flags = FT_OPEN_PATHNAME | FT_OPEN_PARAMS; |
|
304 * open_args.pathname = my_font_pathname; |
|
305 * open_args.num_params = 1; |
|
306 * open_args.params = ¶meter; // we use one optional argument |
|
307 * |
|
308 * // open the font |
|
309 * error = FT_Open_Face( library, &open_args, index, &face ); |
|
310 * ... |
|
311 * } |
|
312 * |
|
313 */ |
|
314 typedef struct FT_Incremental_InterfaceRec_ |
|
315 { |
|
316 const FT_Incremental_FuncsRec* funcs; |
|
317 FT_Incremental object; |
|
318 |
|
319 } FT_Incremental_InterfaceRec; |
|
320 |
|
321 |
|
322 /*************************************************************************** |
|
323 * |
|
324 * @type: |
|
325 * FT_Incremental_Interface |
|
326 * |
|
327 * @description: |
|
328 * A pointer to an @FT_Incremental_InterfaceRec structure. |
|
329 * |
|
330 */ |
|
331 typedef FT_Incremental_InterfaceRec* FT_Incremental_Interface; |
|
332 |
|
333 |
|
334 /*************************************************************************** |
|
335 * |
|
336 * @constant: |
|
337 * FT_PARAM_TAG_INCREMENTAL |
|
338 * |
|
339 * @description: |
|
340 * A constant used as the tag of @FT_Parameter structures to indicate |
|
341 * an incremental loading object to be used by FreeType. |
|
342 * |
|
343 */ |
|
344 #define FT_PARAM_TAG_INCREMENTAL FT_MAKE_TAG( 'i', 'n', 'c', 'r' ) |
|
345 |
|
346 /* */ |
|
347 |
|
348 FT_END_HEADER |
|
349 |
|
350 #endif /* __FTINCREM_H__ */ |
|
351 |
|
352 |
|
353 /* END */ |