]>
Commit | Line | Data |
---|---|---|
7407ac7f BB |
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 */ |