• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
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 */
484