8f2e01794750c391efcdb111f3cff11e69206361
[reactos.git] / lib / 3rdparty / freetype / include / freetype / ftmodapi.h
1 /***************************************************************************/
2 /* */
3 /* ftmodapi.h */
4 /* */
5 /* FreeType modules public interface (specification). */
6 /* */
7 /* Copyright 1996-2001, 2002, 2003, 2006, 2008, 2009, 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 __FTMODAPI_H__
20 #define __FTMODAPI_H__
21
22
23 #include <ft2build.h>
24 #include FT_FREETYPE_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
33 FT_BEGIN_HEADER
34
35
36 /*************************************************************************/
37 /* */
38 /* <Section> */
39 /* module_management */
40 /* */
41 /* <Title> */
42 /* Module Management */
43 /* */
44 /* <Abstract> */
45 /* How to add, upgrade, and remove modules from FreeType. */
46 /* */
47 /* <Description> */
48 /* The definitions below are used to manage modules within FreeType. */
49 /* Modules can be added, upgraded, and removed at runtime. */
50 /* */
51 /*************************************************************************/
52
53
54 /* module bit flags */
55 #define FT_MODULE_FONT_DRIVER 1 /* this module is a font driver */
56 #define FT_MODULE_RENDERER 2 /* this module is a renderer */
57 #define FT_MODULE_HINTER 4 /* this module is a glyph hinter */
58 #define FT_MODULE_STYLER 8 /* this module is a styler */
59
60 #define FT_MODULE_DRIVER_SCALABLE 0x100 /* the driver supports */
61 /* scalable fonts */
62 #define FT_MODULE_DRIVER_NO_OUTLINES 0x200 /* the driver does not */
63 /* support vector outlines */
64 #define FT_MODULE_DRIVER_HAS_HINTER 0x400 /* the driver provides its */
65 /* own hinter */
66
67
68 /* deprecated values */
69 #define ft_module_font_driver FT_MODULE_FONT_DRIVER
70 #define ft_module_renderer FT_MODULE_RENDERER
71 #define ft_module_hinter FT_MODULE_HINTER
72 #define ft_module_styler FT_MODULE_STYLER
73
74 #define ft_module_driver_scalable FT_MODULE_DRIVER_SCALABLE
75 #define ft_module_driver_no_outlines FT_MODULE_DRIVER_NO_OUTLINES
76 #define ft_module_driver_has_hinter FT_MODULE_DRIVER_HAS_HINTER
77
78
79 typedef FT_Pointer FT_Module_Interface;
80
81
82 /*************************************************************************/
83 /* */
84 /* <FuncType> */
85 /* FT_Module_Constructor */
86 /* */
87 /* <Description> */
88 /* A function used to initialize (not create) a new module object. */
89 /* */
90 /* <Input> */
91 /* module :: The module to initialize. */
92 /* */
93 typedef FT_Error
94 (*FT_Module_Constructor)( FT_Module module );
95
96
97 /*************************************************************************/
98 /* */
99 /* <FuncType> */
100 /* FT_Module_Destructor */
101 /* */
102 /* <Description> */
103 /* A function used to finalize (not destroy) a given module object. */
104 /* */
105 /* <Input> */
106 /* module :: The module to finalize. */
107 /* */
108 typedef void
109 (*FT_Module_Destructor)( FT_Module module );
110
111
112 /*************************************************************************/
113 /* */
114 /* <FuncType> */
115 /* FT_Module_Requester */
116 /* */
117 /* <Description> */
118 /* A function used to query a given module for a specific interface. */
119 /* */
120 /* <Input> */
121 /* module :: The module to finalize. */
122 /* */
123 /* name :: The name of the interface in the module. */
124 /* */
125 typedef FT_Module_Interface
126 (*FT_Module_Requester)( FT_Module module,
127 const char* name );
128
129
130 /*************************************************************************/
131 /* */
132 /* <Struct> */
133 /* FT_Module_Class */
134 /* */
135 /* <Description> */
136 /* The module class descriptor. */
137 /* */
138 /* <Fields> */
139 /* module_flags :: Bit flags describing the module. */
140 /* */
141 /* module_size :: The size of one module object/instance in */
142 /* bytes. */
143 /* */
144 /* module_name :: The name of the module. */
145 /* */
146 /* module_version :: The version, as a 16.16 fixed number */
147 /* (major.minor). */
148 /* */
149 /* module_requires :: The version of FreeType this module requires, */
150 /* as a 16.16 fixed number (major.minor). Starts */
151 /* at version 2.0, i.e., 0x20000. */
152 /* */
153 /* module_init :: The initializing function. */
154 /* */
155 /* module_done :: The finalizing function. */
156 /* */
157 /* get_interface :: The interface requesting function. */
158 /* */
159 typedef struct FT_Module_Class_
160 {
161 FT_ULong module_flags;
162 FT_Long module_size;
163 const FT_String* module_name;
164 FT_Fixed module_version;
165 FT_Fixed module_requires;
166
167 const void* module_interface;
168
169 FT_Module_Constructor module_init;
170 FT_Module_Destructor module_done;
171 FT_Module_Requester get_interface;
172
173 } FT_Module_Class;
174
175
176 /*************************************************************************/
177 /* */
178 /* <Function> */
179 /* FT_Add_Module */
180 /* */
181 /* <Description> */
182 /* Add a new module to a given library instance. */
183 /* */
184 /* <InOut> */
185 /* library :: A handle to the library object. */
186 /* */
187 /* <Input> */
188 /* clazz :: A pointer to class descriptor for the module. */
189 /* */
190 /* <Return> */
191 /* FreeType error code. 0~means success. */
192 /* */
193 /* <Note> */
194 /* An error will be returned if a module already exists by that name, */
195 /* or if the module requires a version of FreeType that is too great. */
196 /* */
197 FT_EXPORT( FT_Error )
198 FT_Add_Module( FT_Library library,
199 const FT_Module_Class* clazz );
200
201
202 /*************************************************************************/
203 /* */
204 /* <Function> */
205 /* FT_Get_Module */
206 /* */
207 /* <Description> */
208 /* Find a module by its name. */
209 /* */
210 /* <Input> */
211 /* library :: A handle to the library object. */
212 /* */
213 /* module_name :: The module's name (as an ASCII string). */
214 /* */
215 /* <Return> */
216 /* A module handle. 0~if none was found. */
217 /* */
218 /* <Note> */
219 /* FreeType's internal modules aren't documented very well, and you */
220 /* should look up the source code for details. */
221 /* */
222 FT_EXPORT( FT_Module )
223 FT_Get_Module( FT_Library library,
224 const char* module_name );
225
226
227 /*************************************************************************/
228 /* */
229 /* <Function> */
230 /* FT_Remove_Module */
231 /* */
232 /* <Description> */
233 /* Remove a given module from a library instance. */
234 /* */
235 /* <InOut> */
236 /* library :: A handle to a library object. */
237 /* */
238 /* <Input> */
239 /* module :: A handle to a module object. */
240 /* */
241 /* <Return> */
242 /* FreeType error code. 0~means success. */
243 /* */
244 /* <Note> */
245 /* The module object is destroyed by the function in case of success. */
246 /* */
247 FT_EXPORT( FT_Error )
248 FT_Remove_Module( FT_Library library,
249 FT_Module module );
250
251
252 /*************************************************************************/
253 /* */
254 /* <Function> */
255 /* FT_Reference_Library */
256 /* */
257 /* <Description> */
258 /* A counter gets initialized to~1 at the time an @FT_Library */
259 /* structure is created. This function increments the counter. */
260 /* @FT_Done_Library then only destroys a library if the counter is~1, */
261 /* otherwise it simply decrements the counter. */
262 /* */
263 /* This function helps in managing life-cycles of structures which */
264 /* reference @FT_Library objects. */
265 /* */
266 /* <Input> */
267 /* library :: A handle to a target library object. */
268 /* */
269 /* <Return> */
270 /* FreeType error code. 0~means success. */
271 /* */
272 /* <Since> */
273 /* 2.4.2 */
274 /* */
275 FT_EXPORT( FT_Error )
276 FT_Reference_Library( FT_Library library );
277
278
279 /*************************************************************************/
280 /* */
281 /* <Function> */
282 /* FT_New_Library */
283 /* */
284 /* <Description> */
285 /* This function is used to create a new FreeType library instance */
286 /* from a given memory object. It is thus possible to use libraries */
287 /* with distinct memory allocators within the same program. */
288 /* */
289 /* Normally, you would call this function (followed by a call to */
290 /* @FT_Add_Default_Modules or a series of calls to @FT_Add_Module) */
291 /* instead of @FT_Init_FreeType to initialize the FreeType library. */
292 /* */
293 /* Don't use @FT_Done_FreeType but @FT_Done_Library to destroy a */
294 /* library instance. */
295 /* */
296 /* <Input> */
297 /* memory :: A handle to the original memory object. */
298 /* */
299 /* <Output> */
300 /* alibrary :: A pointer to handle of a new library object. */
301 /* */
302 /* <Return> */
303 /* FreeType error code. 0~means success. */
304 /* */
305 /* <Note> */
306 /* See the discussion of reference counters in the description of */
307 /* @FT_Reference_Library. */
308 /* */
309 FT_EXPORT( FT_Error )
310 FT_New_Library( FT_Memory memory,
311 FT_Library *alibrary );
312
313
314 /*************************************************************************/
315 /* */
316 /* <Function> */
317 /* FT_Done_Library */
318 /* */
319 /* <Description> */
320 /* Discard a given library object. This closes all drivers and */
321 /* discards all resource objects. */
322 /* */
323 /* <Input> */
324 /* library :: A handle to the target library. */
325 /* */
326 /* <Return> */
327 /* FreeType error code. 0~means success. */
328 /* */
329 /* <Note> */
330 /* See the discussion of reference counters in the description of */
331 /* @FT_Reference_Library. */
332 /* */
333 FT_EXPORT( FT_Error )
334 FT_Done_Library( FT_Library library );
335
336 /* */
337
338 typedef void
339 (*FT_DebugHook_Func)( void* arg );
340
341
342 /*************************************************************************/
343 /* */
344 /* <Function> */
345 /* FT_Set_Debug_Hook */
346 /* */
347 /* <Description> */
348 /* Set a debug hook function for debugging the interpreter of a font */
349 /* format. */
350 /* */
351 /* <InOut> */
352 /* library :: A handle to the library object. */
353 /* */
354 /* <Input> */
355 /* hook_index :: The index of the debug hook. You should use the */
356 /* values defined in `ftobjs.h', e.g., */
357 /* `FT_DEBUG_HOOK_TRUETYPE'. */
358 /* */
359 /* debug_hook :: The function used to debug the interpreter. */
360 /* */
361 /* <Note> */
362 /* Currently, four debug hook slots are available, but only two (for */
363 /* the TrueType and the Type~1 interpreter) are defined. */
364 /* */
365 /* Since the internal headers of FreeType are no longer installed, */
366 /* the symbol `FT_DEBUG_HOOK_TRUETYPE' isn't available publicly. */
367 /* This is a bug and will be fixed in a forthcoming release. */
368 /* */
369 FT_EXPORT( void )
370 FT_Set_Debug_Hook( FT_Library library,
371 FT_UInt hook_index,
372 FT_DebugHook_Func debug_hook );
373
374
375 /*************************************************************************/
376 /* */
377 /* <Function> */
378 /* FT_Add_Default_Modules */
379 /* */
380 /* <Description> */
381 /* Add the set of default drivers to a given library object. */
382 /* This is only useful when you create a library object with */
383 /* @FT_New_Library (usually to plug a custom memory manager). */
384 /* */
385 /* <InOut> */
386 /* library :: A handle to a new library object. */
387 /* */
388 FT_EXPORT( void )
389 FT_Add_Default_Modules( FT_Library library );
390
391
392
393 /**************************************************************************
394 *
395 * @section:
396 * truetype_engine
397 *
398 * @title:
399 * The TrueType Engine
400 *
401 * @abstract:
402 * TrueType bytecode support.
403 *
404 * @description:
405 * This section contains a function used to query the level of TrueType
406 * bytecode support compiled in this version of the library.
407 *
408 */
409
410
411 /**************************************************************************
412 *
413 * @enum:
414 * FT_TrueTypeEngineType
415 *
416 * @description:
417 * A list of values describing which kind of TrueType bytecode
418 * engine is implemented in a given FT_Library instance. It is used
419 * by the @FT_Get_TrueType_Engine_Type function.
420 *
421 * @values:
422 * FT_TRUETYPE_ENGINE_TYPE_NONE ::
423 * The library doesn't implement any kind of bytecode interpreter.
424 *
425 * FT_TRUETYPE_ENGINE_TYPE_UNPATENTED ::
426 * The library implements a bytecode interpreter that doesn't
427 * support the patented operations of the TrueType virtual machine.
428 *
429 * Its main use is to load certain Asian fonts which position and
430 * scale glyph components with bytecode instructions. It produces
431 * bad output for most other fonts.
432 *
433 * FT_TRUETYPE_ENGINE_TYPE_PATENTED ::
434 * The library implements a bytecode interpreter that covers
435 * the full instruction set of the TrueType virtual machine (this
436 * was governed by patents until May 2010, hence the name).
437 *
438 * @since:
439 * 2.2
440 *
441 */
442 typedef enum FT_TrueTypeEngineType_
443 {
444 FT_TRUETYPE_ENGINE_TYPE_NONE = 0,
445 FT_TRUETYPE_ENGINE_TYPE_UNPATENTED,
446 FT_TRUETYPE_ENGINE_TYPE_PATENTED
447
448 } FT_TrueTypeEngineType;
449
450
451 /**************************************************************************
452 *
453 * @func:
454 * FT_Get_TrueType_Engine_Type
455 *
456 * @description:
457 * Return an @FT_TrueTypeEngineType value to indicate which level of
458 * the TrueType virtual machine a given library instance supports.
459 *
460 * @input:
461 * library ::
462 * A library instance.
463 *
464 * @return:
465 * A value indicating which level is supported.
466 *
467 * @since:
468 * 2.2
469 *
470 */
471 FT_EXPORT( FT_TrueTypeEngineType )
472 FT_Get_TrueType_Engine_Type( FT_Library library );
473
474
475 /* */
476
477
478 FT_END_HEADER
479
480 #endif /* __FTMODAPI_H__ */
481
482
483 /* END */