ReactOS  0.4.14-dev-358-gbef841c
ftmodapi.h
Go to the documentation of this file.
1 /***************************************************************************/
2 /* */
3 /* ftmodapi.h */
4 /* */
5 /* FreeType modules public interface (specification). */
6 /* */
7 /* Copyright 1996-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 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 
34 
35 
36  /*************************************************************************/
37  /* */
38  /* <Section> */
39  /* module_management */
40  /* */
41  /* <Title> */
42  /* Module Management */
43  /* */
44  /* <Abstract> */
45  /* How to add, upgrade, remove, and control 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  /* Additionally, some module properties can be controlled also. */
51  /* */
52  /* Here is a list of possible values of the `module_name' field in */
53  /* the @FT_Module_Class structure. */
54  /* */
55  /* { */
56  /* autofitter */
57  /* bdf */
58  /* cff */
59  /* gxvalid */
60  /* otvalid */
61  /* pcf */
62  /* pfr */
63  /* psaux */
64  /* pshinter */
65  /* psnames */
66  /* raster1 */
67  /* sfnt */
68  /* smooth, smooth-lcd, smooth-lcdv */
69  /* truetype */
70  /* type1 */
71  /* type42 */
72  /* t1cid */
73  /* winfonts */
74  /* } */
75  /* */
76  /* Note that the FreeType Cache sub-system is not a FreeType module. */
77  /* */
78  /* <Order> */
79  /* FT_Module */
80  /* FT_Module_Constructor */
81  /* FT_Module_Destructor */
82  /* FT_Module_Requester */
83  /* FT_Module_Class */
84  /* */
85  /* FT_Add_Module */
86  /* FT_Get_Module */
87  /* FT_Remove_Module */
88  /* FT_Add_Default_Modules */
89  /* */
90  /* FT_Property_Set */
91  /* FT_Property_Get */
92  /* FT_Set_Default_Properties */
93  /* */
94  /* FT_New_Library */
95  /* FT_Done_Library */
96  /* FT_Reference_Library */
97  /* */
98  /* FT_Renderer */
99  /* FT_Renderer_Class */
100  /* */
101  /* FT_Get_Renderer */
102  /* FT_Set_Renderer */
103  /* */
104  /* FT_Set_Debug_Hook */
105  /* */
106  /*************************************************************************/
107 
108 
109  /* module bit flags */
110 #define FT_MODULE_FONT_DRIVER 1 /* this module is a font driver */
111 #define FT_MODULE_RENDERER 2 /* this module is a renderer */
112 #define FT_MODULE_HINTER 4 /* this module is a glyph hinter */
113 #define FT_MODULE_STYLER 8 /* this module is a styler */
114 
115 #define FT_MODULE_DRIVER_SCALABLE 0x100 /* the driver supports */
116  /* scalable fonts */
117 #define FT_MODULE_DRIVER_NO_OUTLINES 0x200 /* the driver does not */
118  /* support vector outlines */
119 #define FT_MODULE_DRIVER_HAS_HINTER 0x400 /* the driver provides its */
120  /* own hinter */
121 #define FT_MODULE_DRIVER_HINTS_LIGHTLY 0x800 /* the driver's hinter */
122  /* produces LIGHT hints */
123 
124 
125  /* deprecated values */
126 #define ft_module_font_driver FT_MODULE_FONT_DRIVER
127 #define ft_module_renderer FT_MODULE_RENDERER
128 #define ft_module_hinter FT_MODULE_HINTER
129 #define ft_module_styler FT_MODULE_STYLER
130 
131 #define ft_module_driver_scalable FT_MODULE_DRIVER_SCALABLE
132 #define ft_module_driver_no_outlines FT_MODULE_DRIVER_NO_OUTLINES
133 #define ft_module_driver_has_hinter FT_MODULE_DRIVER_HAS_HINTER
134 #define ft_module_driver_hints_lightly FT_MODULE_DRIVER_HINTS_LIGHTLY
135 
136 
138 
139 
140  /*************************************************************************/
141  /* */
142  /* <FuncType> */
143  /* FT_Module_Constructor */
144  /* */
145  /* <Description> */
146  /* A function used to initialize (not create) a new module object. */
147  /* */
148  /* <Input> */
149  /* module :: The module to initialize. */
150  /* */
151  typedef FT_Error
153 
154 
155  /*************************************************************************/
156  /* */
157  /* <FuncType> */
158  /* FT_Module_Destructor */
159  /* */
160  /* <Description> */
161  /* A function used to finalize (not destroy) a given module object. */
162  /* */
163  /* <Input> */
164  /* module :: The module to finalize. */
165  /* */
166  typedef void
168 
169 
170  /*************************************************************************/
171  /* */
172  /* <FuncType> */
173  /* FT_Module_Requester */
174  /* */
175  /* <Description> */
176  /* A function used to query a given module for a specific interface. */
177  /* */
178  /* <Input> */
179  /* module :: The module to be searched. */
180  /* */
181  /* name :: The name of the interface in the module. */
182  /* */
183  typedef FT_Module_Interface
185  const char* name );
186 
187 
188  /*************************************************************************/
189  /* */
190  /* <Struct> */
191  /* FT_Module_Class */
192  /* */
193  /* <Description> */
194  /* The module class descriptor. */
195  /* */
196  /* <Fields> */
197  /* module_flags :: Bit flags describing the module. */
198  /* */
199  /* module_size :: The size of one module object/instance in */
200  /* bytes. */
201  /* */
202  /* module_name :: The name of the module. */
203  /* */
204  /* module_version :: The version, as a 16.16 fixed number */
205  /* (major.minor). */
206  /* */
207  /* module_requires :: The version of FreeType this module requires, */
208  /* as a 16.16 fixed number (major.minor). Starts */
209  /* at version 2.0, i.e., 0x20000. */
210  /* */
211  /* module_init :: The initializing function. */
212  /* */
213  /* module_done :: The finalizing function. */
214  /* */
215  /* get_interface :: The interface requesting function. */
216  /* */
217  typedef struct FT_Module_Class_
218  {
224 
225  const void* module_interface;
226 
230 
231  } FT_Module_Class;
232 
233 
234  /*************************************************************************/
235  /* */
236  /* <Function> */
237  /* FT_Add_Module */
238  /* */
239  /* <Description> */
240  /* Add a new module to a given library instance. */
241  /* */
242  /* <InOut> */
243  /* library :: A handle to the library object. */
244  /* */
245  /* <Input> */
246  /* clazz :: A pointer to class descriptor for the module. */
247  /* */
248  /* <Return> */
249  /* FreeType error code. 0~means success. */
250  /* */
251  /* <Note> */
252  /* An error will be returned if a module already exists by that name, */
253  /* or if the module requires a version of FreeType that is too great. */
254  /* */
257  const FT_Module_Class* clazz );
258 
259 
260  /*************************************************************************/
261  /* */
262  /* <Function> */
263  /* FT_Get_Module */
264  /* */
265  /* <Description> */
266  /* Find a module by its name. */
267  /* */
268  /* <Input> */
269  /* library :: A handle to the library object. */
270  /* */
271  /* module_name :: The module's name (as an ASCII string). */
272  /* */
273  /* <Return> */
274  /* A module handle. 0~if none was found. */
275  /* */
276  /* <Note> */
277  /* FreeType's internal modules aren't documented very well, and you */
278  /* should look up the source code for details. */
279  /* */
282  const char* module_name );
283 
284 
285  /*************************************************************************/
286  /* */
287  /* <Function> */
288  /* FT_Remove_Module */
289  /* */
290  /* <Description> */
291  /* Remove a given module from a library instance. */
292  /* */
293  /* <InOut> */
294  /* library :: A handle to a library object. */
295  /* */
296  /* <Input> */
297  /* module :: A handle to a module object. */
298  /* */
299  /* <Return> */
300  /* FreeType error code. 0~means success. */
301  /* */
302  /* <Note> */
303  /* The module object is destroyed by the function in case of success. */
304  /* */
307  FT_Module module );
308 
309 
310  /**********************************************************************
311  *
312  * @function:
313  * FT_Property_Set
314  *
315  * @description:
316  * Set a property for a given module.
317  *
318  * @input:
319  * library ::
320  * A handle to the library the module is part of.
321  *
322  * module_name ::
323  * The module name.
324  *
325  * property_name ::
326  * The property name. Properties are described in section
327  * @properties.
328  *
329  * Note that only a few modules have properties.
330  *
331  * value ::
332  * A generic pointer to a variable or structure that gives the new
333  * value of the property. The exact definition of `value' is
334  * dependent on the property; see section @properties.
335  *
336  * @return:
337  * FreeType error code. 0~means success.
338  *
339  * @note:
340  * If `module_name' isn't a valid module name, or `property_name'
341  * doesn't specify a valid property, or if `value' doesn't represent a
342  * valid value for the given property, an error is returned.
343  *
344  * The following example sets property `bar' (a simple integer) in
345  * module `foo' to value~1.
346  *
347  * {
348  * FT_UInt bar;
349  *
350  *
351  * bar = 1;
352  * FT_Property_Set( library, "foo", "bar", &bar );
353  * }
354  *
355  * Note that the FreeType Cache sub-system doesn't recognize module
356  * property changes. To avoid glyph lookup confusion within the cache
357  * you should call @FTC_Manager_Reset to completely flush the cache if
358  * a module property gets changed after @FTC_Manager_New has been
359  * called.
360  *
361  * It is not possible to set properties of the FreeType Cache
362  * sub-system itself with FT_Property_Set; use @FTC_Property_Set
363  * instead.
364  *
365  * @since:
366  * 2.4.11
367  *
368  */
371  const FT_String* module_name,
372  const FT_String* property_name,
373  const void* value );
374 
375 
376  /**********************************************************************
377  *
378  * @function:
379  * FT_Property_Get
380  *
381  * @description:
382  * Get a module's property value.
383  *
384  * @input:
385  * library ::
386  * A handle to the library the module is part of.
387  *
388  * module_name ::
389  * The module name.
390  *
391  * property_name ::
392  * The property name. Properties are described in section
393  * @properties.
394  *
395  * @inout:
396  * value ::
397  * A generic pointer to a variable or structure that gives the
398  * value of the property. The exact definition of `value' is
399  * dependent on the property; see section @properties.
400  *
401  * @return:
402  * FreeType error code. 0~means success.
403  *
404  * @note:
405  * If `module_name' isn't a valid module name, or `property_name'
406  * doesn't specify a valid property, or if `value' doesn't represent a
407  * valid value for the given property, an error is returned.
408  *
409  * The following example gets property `baz' (a range) in module `foo'.
410  *
411  * {
412  * typedef range_
413  * {
414  * FT_Int32 min;
415  * FT_Int32 max;
416  *
417  * } range;
418  *
419  * range baz;
420  *
421  *
422  * FT_Property_Get( library, "foo", "baz", &baz );
423  * }
424  *
425  * It is not possible to retrieve properties of the FreeType Cache
426  * sub-system with FT_Property_Get; use @FTC_Property_Get instead.
427  *
428  * @since:
429  * 2.4.11
430  *
431  */
434  const FT_String* module_name,
435  const FT_String* property_name,
436  void* value );
437 
438 
439  /*************************************************************************/
440  /* */
441  /* <Function> */
442  /* FT_Set_Default_Properties */
443  /* */
444  /* <Description> */
445  /* If compilation option FT_CONFIG_OPTION_ENVIRONMENT_PROPERTIES is */
446  /* set, this function reads the `FREETYPE_PROPERTIES' environment */
447  /* variable to control driver properties. See section @properties */
448  /* for more. */
449  /* */
450  /* If the compilation option is not set, this function does nothing. */
451  /* */
452  /* `FREETYPE_PROPERTIES' has the following syntax form (broken here */
453  /* into multiple lines for better readability). */
454  /* */
455  /* { */
456  /* <optional whitespace> */
457  /* <module-name1> ':' */
458  /* <property-name1> '=' <property-value1> */
459  /* <whitespace> */
460  /* <module-name2> ':' */
461  /* <property-name2> '=' <property-value2> */
462  /* ... */
463  /* } */
464  /* */
465  /* Example: */
466  /* */
467  /* { */
468  /* FREETYPE_PROPERTIES=truetype:interpreter-version=35 \ */
469  /* cff:no-stem-darkening=1 \ */
470  /* autofitter:warping=1 */
471  /* } */
472  /* */
473  /* <InOut> */
474  /* library :: A handle to a new library object. */
475  /* */
476  /* <Since> */
477  /* 2.8 */
478  /* */
479  FT_EXPORT( void )
481 
482 
483  /*************************************************************************/
484  /* */
485  /* <Function> */
486  /* FT_Reference_Library */
487  /* */
488  /* <Description> */
489  /* A counter gets initialized to~1 at the time an @FT_Library */
490  /* structure is created. This function increments the counter. */
491  /* @FT_Done_Library then only destroys a library if the counter is~1, */
492  /* otherwise it simply decrements the counter. */
493  /* */
494  /* This function helps in managing life-cycles of structures that */
495  /* reference @FT_Library objects. */
496  /* */
497  /* <Input> */
498  /* library :: A handle to a target library object. */
499  /* */
500  /* <Return> */
501  /* FreeType error code. 0~means success. */
502  /* */
503  /* <Since> */
504  /* 2.4.2 */
505  /* */
508 
509 
510  /*************************************************************************/
511  /* */
512  /* <Function> */
513  /* FT_New_Library */
514  /* */
515  /* <Description> */
516  /* This function is used to create a new FreeType library instance */
517  /* from a given memory object. It is thus possible to use libraries */
518  /* with distinct memory allocators within the same program. Note, */
519  /* however, that the used @FT_Memory structure is expected to remain */
520  /* valid for the life of the @FT_Library object. */
521  /* */
522  /* Normally, you would call this function (followed by a call to */
523  /* @FT_Add_Default_Modules or a series of calls to @FT_Add_Module, */
524  /* and a call to @FT_Set_Default_Properties) instead of */
525  /* @FT_Init_FreeType to initialize the FreeType library. */
526  /* */
527  /* Don't use @FT_Done_FreeType but @FT_Done_Library to destroy a */
528  /* library instance. */
529  /* */
530  /* <Input> */
531  /* memory :: A handle to the original memory object. */
532  /* */
533  /* <Output> */
534  /* alibrary :: A pointer to handle of a new library object. */
535  /* */
536  /* <Return> */
537  /* FreeType error code. 0~means success. */
538  /* */
539  /* <Note> */
540  /* See the discussion of reference counters in the description of */
541  /* @FT_Reference_Library. */
542  /* */
545  FT_Library *alibrary );
546 
547 
548  /*************************************************************************/
549  /* */
550  /* <Function> */
551  /* FT_Done_Library */
552  /* */
553  /* <Description> */
554  /* Discard a given library object. This closes all drivers and */
555  /* discards all resource objects. */
556  /* */
557  /* <Input> */
558  /* library :: A handle to the target library. */
559  /* */
560  /* <Return> */
561  /* FreeType error code. 0~means success. */
562  /* */
563  /* <Note> */
564  /* See the discussion of reference counters in the description of */
565  /* @FT_Reference_Library. */
566  /* */
569 
570  /* */
571 
572  typedef void
573  (*FT_DebugHook_Func)( void* arg );
574 
575 
576  /*************************************************************************/
577  /* */
578  /* <Function> */
579  /* FT_Set_Debug_Hook */
580  /* */
581  /* <Description> */
582  /* Set a debug hook function for debugging the interpreter of a font */
583  /* format. */
584  /* */
585  /* <InOut> */
586  /* library :: A handle to the library object. */
587  /* */
588  /* <Input> */
589  /* hook_index :: The index of the debug hook. You should use the */
590  /* values defined in `ftobjs.h', e.g., */
591  /* `FT_DEBUG_HOOK_TRUETYPE'. */
592  /* */
593  /* debug_hook :: The function used to debug the interpreter. */
594  /* */
595  /* <Note> */
596  /* Currently, four debug hook slots are available, but only two (for */
597  /* the TrueType and the Type~1 interpreter) are defined. */
598  /* */
599  /* Since the internal headers of FreeType are no longer installed, */
600  /* the symbol `FT_DEBUG_HOOK_TRUETYPE' isn't available publicly. */
601  /* This is a bug and will be fixed in a forthcoming release. */
602  /* */
603  FT_EXPORT( void )
605  FT_UInt hook_index,
606  FT_DebugHook_Func debug_hook );
607 
608 
609  /*************************************************************************/
610  /* */
611  /* <Function> */
612  /* FT_Add_Default_Modules */
613  /* */
614  /* <Description> */
615  /* Add the set of default drivers to a given library object. */
616  /* This is only useful when you create a library object with */
617  /* @FT_New_Library (usually to plug a custom memory manager). */
618  /* */
619  /* <InOut> */
620  /* library :: A handle to a new library object. */
621  /* */
622  FT_EXPORT( void )
624 
625 
626 
627  /**************************************************************************
628  *
629  * @section:
630  * truetype_engine
631  *
632  * @title:
633  * The TrueType Engine
634  *
635  * @abstract:
636  * TrueType bytecode support.
637  *
638  * @description:
639  * This section contains a function used to query the level of TrueType
640  * bytecode support compiled in this version of the library.
641  *
642  */
643 
644 
645  /**************************************************************************
646  *
647  * @enum:
648  * FT_TrueTypeEngineType
649  *
650  * @description:
651  * A list of values describing which kind of TrueType bytecode
652  * engine is implemented in a given FT_Library instance. It is used
653  * by the @FT_Get_TrueType_Engine_Type function.
654  *
655  * @values:
656  * FT_TRUETYPE_ENGINE_TYPE_NONE ::
657  * The library doesn't implement any kind of bytecode interpreter.
658  *
659  * FT_TRUETYPE_ENGINE_TYPE_UNPATENTED ::
660  * Deprecated and removed.
661  *
662  * FT_TRUETYPE_ENGINE_TYPE_PATENTED ::
663  * The library implements a bytecode interpreter that covers
664  * the full instruction set of the TrueType virtual machine (this
665  * was governed by patents until May 2010, hence the name).
666  *
667  * @since:
668  * 2.2
669  *
670  */
672  {
676 
678 
679 
680  /**************************************************************************
681  *
682  * @func:
683  * FT_Get_TrueType_Engine_Type
684  *
685  * @description:
686  * Return an @FT_TrueTypeEngineType value to indicate which level of
687  * the TrueType virtual machine a given library instance supports.
688  *
689  * @input:
690  * library ::
691  * A library instance.
692  *
693  * @return:
694  * A value indicating which level is supported.
695  *
696  * @since:
697  * 2.2
698  *
699  */
702 
703  /* */
704 
705 
707 
708 #endif /* FTMODAPI_H_ */
709 
710 
711 /* END */
void(* FT_DebugHook_Func)(void *arg)
Definition: ftmodapi.h:573
int FT_Error
Definition: fttypes.h:300
FT_TrueTypeEngineType_
Definition: ftmodapi.h:671
signed long FT_Long
Definition: fttypes.h:242
FT_Error(* FT_Module_Constructor)(FT_Module module)
Definition: ftmodapi.h:152
HMODULE module
Definition: main.cpp:47
unsigned long FT_ULong
Definition: fttypes.h:253
struct png_info_def **typedef void(__cdecl typeof(png_destroy_read_struct))(struct png_struct_def **
Definition: typeof.h:49
#define FT_END_HEADER
Definition: ftheader.h:54
static LPCWSTR LPCWSTR module_name
Definition: db.cpp:168
FT_Done_Library(FT_Library library)
Definition: ftobjs.c:5220
void * arg
Definition: msvc.h:12
FT_Remove_Module(FT_Library library, FT_Module module)
Definition: ftobjs.c:4927
FT_Library library
Definition: cffdrivr.c:654
static char memory[1024 *256]
Definition: process.c:116
struct FT_Module_Class_ FT_Module_Class
FT_Module_Constructor module_init
Definition: ftmodapi.h:227
#define FT_BEGIN_HEADER
Definition: ftheader.h:36
FT_Module_Interface(* FT_Module_Requester)(FT_Module module, const char *name)
Definition: ftmodapi.h:184
FT_Add_Module(FT_Library library, const FT_Module_Class *clazz)
Definition: ftobjs.c:4724
FT_ULong module_flags
Definition: ftmodapi.h:219
FT_Fixed module_requires
Definition: ftmodapi.h:223
char FT_String
Definition: fttypes.h:187
FT_Pointer FT_Module_Interface
Definition: ftmodapi.h:137
FT_Property_Get(FT_Library library, const FT_String *module_name, const FT_String *property_name, void *value)
Definition: ftobjs.c:5072
const void * module_interface
Definition: ftmodapi.h:225
FT_Property_Set(FT_Library library, const FT_String *module_name, const FT_String *property_name, const void *value)
Definition: ftobjs.c:5055
FT_Long module_size
Definition: ftmodapi.h:220
FT_Get_TrueType_Engine_Type(FT_Library library)
Definition: ftobjs.c:5342
enum FT_TrueTypeEngineType_ FT_TrueTypeEngineType
typedefFT_BEGIN_HEADER struct FT_MemoryRec_ * FT_Memory
Definition: ftsystem.h:66
FT_Set_Default_Properties(FT_Library library)
Definition: ftinit.c:309
signed long FT_Fixed
Definition: fttypes.h:288
FT_New_Library(FT_Memory memory, FT_Library *alibrary)
Definition: ftobjs.c:5138
FT_Add_Default_Modules(FT_Library library)
Definition: ftinit.c:198
unsigned int FT_UInt
Definition: fttypes.h:231
FT_Reference_Library(FT_Library library)
Definition: ftobjs.c:5124
#define FT_EXPORT(x)
Definition: ftconfig.h:461
const FT_String * module_name
Definition: ftmodapi.h:221
void(* FT_Module_Destructor)(FT_Module module)
Definition: ftmodapi.h:167
FT_Module_Destructor module_done
Definition: ftmodapi.h:228
FT_Fixed module_version
Definition: ftmodapi.h:222
FT_Get_Module(FT_Library library, const char *module_name)
Definition: ftobjs.c:4837
FT_Set_Debug_Hook(FT_Library library, FT_UInt hook_index, FT_DebugHook_Func debug_hook)
Definition: ftobjs.c:5328
FT_Module_Requester get_interface
Definition: ftmodapi.h:229
GLuint const GLchar * name
Definition: glext.h:6031