ReactOS 0.4.15-dev-7834-g00c4b3d
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 */
#define FT_END_HEADER
Definition: ftheader.h:54
#define FT_BEGIN_HEADER
Definition: ftheader.h:36
struct FT_Incremental_FuncsRec_ FT_Incremental_FuncsRec
typedefFT_BEGIN_HEADER struct FT_IncrementalRec_ * FT_Incremental
Definition: ftincrem.h:85
FT_Error(* FT_Incremental_GetGlyphMetricsFunc)(FT_Incremental incremental, FT_UInt glyph_index, FT_Bool vertical, FT_Incremental_MetricsRec *ametrics)
Definition: ftincrem.h:243
struct FT_Incremental_MetricsRec_ * FT_Incremental_Metrics
Definition: ftincrem.h:135
struct FT_Incremental_MetricsRec_ FT_Incremental_MetricsRec
struct FT_Incremental_InterfaceRec_ FT_Incremental_InterfaceRec
void(* FT_Incremental_FreeGlyphDataFunc)(FT_Incremental incremental, FT_Data *data)
Definition: ftincrem.h:205
FT_Incremental_InterfaceRec * FT_Incremental_Interface
Definition: ftincrem.h:332
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
int FT_Error
Definition: fttypes.h:300
signed long FT_Long
Definition: fttypes.h:242
unsigned int FT_UInt
Definition: fttypes.h:231
GLint GLenum GLsizei GLsizei GLsizei GLint GLsizei const GLvoid * data
Definition: gl.h:1950
FT_Incremental_FreeGlyphDataFunc free_glyph_data
Definition: ftincrem.h:273
FT_Incremental_GetGlyphDataFunc get_glyph_data
Definition: ftincrem.h:272
FT_Incremental_GetGlyphMetricsFunc get_glyph_metrics
Definition: ftincrem.h:274
const FT_Incremental_FuncsRec * funcs
Definition: ftincrem.h:317