ReactOS  0.4.14-dev-342-gdc047f9
ftincrem.h
Go to the documentation of this file.
1 /***************************************************************************/
2 /* */
3 /* ftincrem.h */
4 /* */
5 /* FreeType incremental loading (specification). */
6 /* */
7 /* Copyright 2002-2018 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 #include FT_PARAMETER_TAGS_H
25 
26 #ifdef FREETYPE_H
27 #error "freetype.h of FreeType 1 has been loaded!"
28 #error "Please fix the directory search order for header files"
29 #error "so that freetype.h of FreeType 2 is found first."
30 #endif
31 
32 
34 
35  /***************************************************************************
36  *
37  * @section:
38  * incremental
39  *
40  * @title:
41  * Incremental Loading
42  *
43  * @abstract:
44  * Custom Glyph Loading.
45  *
46  * @description:
47  * This section contains various functions used to perform so-called
48  * `incremental' glyph loading. This is a mode where all glyphs loaded
49  * from a given @FT_Face are provided by the client application.
50  *
51  * Apart from that, all other tables are loaded normally from the font
52  * file. This mode is useful when FreeType is used within another
53  * engine, e.g., a PostScript Imaging Processor.
54  *
55  * To enable this mode, you must use @FT_Open_Face, passing an
56  * @FT_Parameter with the @FT_PARAM_TAG_INCREMENTAL tag and an
57  * @FT_Incremental_Interface value. See the comments for
58  * @FT_Incremental_InterfaceRec for an example.
59  *
60  */
61 
62 
63  /***************************************************************************
64  *
65  * @type:
66  * FT_Incremental
67  *
68  * @description:
69  * An opaque type describing a user-provided object used to implement
70  * `incremental' glyph loading within FreeType. This is used to support
71  * embedded fonts in certain environments (e.g., PostScript interpreters),
72  * where the glyph data isn't in the font file, or must be overridden by
73  * different values.
74  *
75  * @note:
76  * It is up to client applications to create and implement @FT_Incremental
77  * objects, as long as they provide implementations for the methods
78  * @FT_Incremental_GetGlyphDataFunc, @FT_Incremental_FreeGlyphDataFunc
79  * and @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
95  * by 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  */
117  {
121  FT_Long advance_v; /* since 2.3.12 */
122 
124 
125 
126  /***************************************************************************
127  *
128  * @struct:
129  * FT_Incremental_Metrics
130  *
131  * @description:
132  * A handle to an @FT_Incremental_MetricsRec structure.
133  *
134  */
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
173  * the data bytes.
174  *
175  * Nested calls to @FT_Incremental_GetGlyphDataFunc can happen for
176  * compound glyphs.
177  *
178  */
179  typedef FT_Error
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
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 is necessary because, in certain
217  * formats like TrueType, the metrics are stored in a different place from
218  * the glyph images proper.
219  *
220  * @input:
221  * incremental ::
222  * A handle to an opaque @FT_Incremental handle provided by the client
223  * application.
224  *
225  * glyph_index ::
226  * Index of relevant glyph.
227  *
228  * vertical ::
229  * If true, return vertical metrics.
230  *
231  * ametrics ::
232  * This parameter is used for both input and output.
233  * The original glyph metrics, if any, in font units. If metrics are
234  * not available all the values must be set to zero.
235  *
236  * @output:
237  * ametrics ::
238  * The replacement glyph metrics in font units.
239  *
240  */
241  typedef FT_Error
243  ( FT_Incremental incremental,
244  FT_UInt glyph_index,
245  FT_Bool vertical,
246  FT_Incremental_MetricsRec *ametrics );
247 
248 
249  /**************************************************************************
250  *
251  * @struct:
252  * FT_Incremental_FuncsRec
253  *
254  * @description:
255  * A table of functions for accessing fonts that load data
256  * incrementally. Used in @FT_Incremental_InterfaceRec.
257  *
258  * @fields:
259  * get_glyph_data ::
260  * The function to get glyph data. Must not be null.
261  *
262  * free_glyph_data ::
263  * The function to release glyph data. Must not be null.
264  *
265  * get_glyph_metrics ::
266  * The function to get glyph metrics. May be null if the font does
267  * not provide overriding glyph metrics.
268  *
269  */
271  {
275 
277 
278 
279  /***************************************************************************
280  *
281  * @struct:
282  * FT_Incremental_InterfaceRec
283  *
284  * @description:
285  * A structure to be used with @FT_Open_Face to indicate that the user
286  * wants to support incremental glyph loading. You should use it with
287  * @FT_PARAM_TAG_INCREMENTAL as in the following example:
288  *
289  * {
290  * FT_Incremental_InterfaceRec inc_int;
291  * FT_Parameter parameter;
292  * FT_Open_Args open_args;
293  *
294  *
295  * // set up incremental descriptor
296  * inc_int.funcs = my_funcs;
297  * inc_int.object = my_object;
298  *
299  * // set up optional parameter
300  * parameter.tag = FT_PARAM_TAG_INCREMENTAL;
301  * parameter.data = &inc_int;
302  *
303  * // set up FT_Open_Args structure
304  * open_args.flags = FT_OPEN_PATHNAME | FT_OPEN_PARAMS;
305  * open_args.pathname = my_font_pathname;
306  * open_args.num_params = 1;
307  * open_args.params = &parameter; // we use one optional argument
308  *
309  * // open the font
310  * error = FT_Open_Face( library, &open_args, index, &face );
311  * ...
312  * }
313  *
314  */
316  {
319 
321 
322 
323  /***************************************************************************
324  *
325  * @type:
326  * FT_Incremental_Interface
327  *
328  * @description:
329  * A pointer to an @FT_Incremental_InterfaceRec structure.
330  *
331  */
333 
334 
335  /* */
336 
337 
339 
340 #endif /* FTINCREM_H_ */
341 
342 
343 /* END */
int FT_Error
Definition: fttypes.h:300
signed long FT_Long
Definition: fttypes.h:242
struct png_info_def **typedef void(__cdecl typeof(png_destroy_read_struct))(struct png_struct_def **
Definition: typeof.h:49
FT_Error(* FT_Incremental_GetGlyphMetricsFunc)(FT_Incremental incremental, FT_UInt glyph_index, FT_Bool vertical, FT_Incremental_MetricsRec *ametrics)
Definition: ftincrem.h:243
#define FT_END_HEADER
Definition: ftheader.h:54
typedefFT_BEGIN_HEADER struct FT_IncrementalRec_ * FT_Incremental
Definition: ftincrem.h:85
FT_Incremental_GetGlyphDataFunc get_glyph_data
Definition: ftincrem.h:272
FT_Error(* FT_Incremental_GetGlyphDataFunc)(FT_Incremental incremental, FT_UInt glyph_index, FT_Data *adata)
Definition: ftincrem.h:180
FT_BEGIN_HEADER typedef unsigned char FT_Bool
Definition: fttypes.h:108
struct FT_Incremental_MetricsRec_ FT_Incremental_MetricsRec
#define FT_BEGIN_HEADER
Definition: ftheader.h:36
struct FT_Incremental_InterfaceRec_ FT_Incremental_InterfaceRec
FT_Incremental_InterfaceRec * FT_Incremental_Interface
Definition: ftincrem.h:332
GLint GLenum GLsizei GLsizei GLsizei GLint GLsizei const GLvoid * data
Definition: gl.h:1950
FT_Incremental_GetGlyphMetricsFunc get_glyph_metrics
Definition: ftincrem.h:274
struct FT_Incremental_FuncsRec_ FT_Incremental_FuncsRec
FT_Incremental_FreeGlyphDataFunc free_glyph_data
Definition: ftincrem.h:273
unsigned int FT_UInt
Definition: fttypes.h:231
void(* FT_Incremental_FreeGlyphDataFunc)(FT_Incremental incremental, FT_Data *data)
Definition: ftincrem.h:205
struct FT_Incremental_MetricsRec_ * FT_Incremental_Metrics
Definition: ftincrem.h:135
const FT_Incremental_FuncsRec * funcs
Definition: ftincrem.h:317