Add the license back to ftmodule.h after the freetype 2.5.4 upgrade.
[pdfium.git] / third_party / freetype / include / ftmodapi.h
1 /***************************************************************************/
2 /*                                                                         */
3 /*  ftmodapi.h                                                             */
4 /*                                                                         */
5 /*    FreeType modules public interface (specification).                   */
6 /*                                                                         */
7 /*  Copyright 1996-2003, 2006, 2008-2010, 2012, 2013 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, 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, raster5                                                 */
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   /*                                                                       */
93   /*    FT_New_Library                                                     */
94   /*    FT_Done_Library                                                    */
95   /*    FT_Reference_Library                                               */
96   /*                                                                       */
97   /*    FT_Renderer                                                        */
98   /*    FT_Renderer_Class                                                  */
99   /*                                                                       */
100   /*    FT_Get_Renderer                                                    */
101   /*    FT_Set_Renderer                                                    */
102   /*                                                                       */
103   /*    FT_Set_Debug_Hook                                                  */
104   /*                                                                       */
105   /*************************************************************************/
106
107
108   /* module bit flags */
109 #define FT_MODULE_FONT_DRIVER         1  /* this module is a font driver  */
110 #define FT_MODULE_RENDERER            2  /* this module is a renderer     */
111 #define FT_MODULE_HINTER              4  /* this module is a glyph hinter */
112 #define FT_MODULE_STYLER              8  /* this module is a styler       */
113
114 #define FT_MODULE_DRIVER_SCALABLE     0x100   /* the driver supports      */
115                                               /* scalable fonts           */
116 #define FT_MODULE_DRIVER_NO_OUTLINES  0x200   /* the driver does not      */
117                                               /* support vector outlines  */
118 #define FT_MODULE_DRIVER_HAS_HINTER   0x400   /* the driver provides its  */
119                                               /* own hinter               */
120
121
122   /* deprecated values */
123 #define ft_module_font_driver         FT_MODULE_FONT_DRIVER
124 #define ft_module_renderer            FT_MODULE_RENDERER
125 #define ft_module_hinter              FT_MODULE_HINTER
126 #define ft_module_styler              FT_MODULE_STYLER
127
128 #define ft_module_driver_scalable     FT_MODULE_DRIVER_SCALABLE
129 #define ft_module_driver_no_outlines  FT_MODULE_DRIVER_NO_OUTLINES
130 #define ft_module_driver_has_hinter   FT_MODULE_DRIVER_HAS_HINTER
131
132
133   typedef FT_Pointer  FT_Module_Interface;
134
135
136   /*************************************************************************/
137   /*                                                                       */
138   /* <FuncType>                                                            */
139   /*    FT_Module_Constructor                                              */
140   /*                                                                       */
141   /* <Description>                                                         */
142   /*    A function used to initialize (not create) a new module object.    */
143   /*                                                                       */
144   /* <Input>                                                               */
145   /*    module :: The module to initialize.                                */
146   /*                                                                       */
147   typedef FT_Error
148   (*FT_Module_Constructor)( FT_Module  module );
149
150
151   /*************************************************************************/
152   /*                                                                       */
153   /* <FuncType>                                                            */
154   /*    FT_Module_Destructor                                               */
155   /*                                                                       */
156   /* <Description>                                                         */
157   /*    A function used to finalize (not destroy) a given module object.   */
158   /*                                                                       */
159   /* <Input>                                                               */
160   /*    module :: The module to finalize.                                  */
161   /*                                                                       */
162   typedef void
163   (*FT_Module_Destructor)( FT_Module  module );
164
165
166   /*************************************************************************/
167   /*                                                                       */
168   /* <FuncType>                                                            */
169   /*    FT_Module_Requester                                                */
170   /*                                                                       */
171   /* <Description>                                                         */
172   /*    A function used to query a given module for a specific interface.  */
173   /*                                                                       */
174   /* <Input>                                                               */
175   /*    module :: The module to be searched.                               */
176   /*                                                                       */
177   /*    name ::   The name of the interface in the module.                 */
178   /*                                                                       */
179   typedef FT_Module_Interface
180   (*FT_Module_Requester)( FT_Module    module,
181                           const char*  name );
182
183
184   /*************************************************************************/
185   /*                                                                       */
186   /* <Struct>                                                              */
187   /*    FT_Module_Class                                                    */
188   /*                                                                       */
189   /* <Description>                                                         */
190   /*    The module class descriptor.                                       */
191   /*                                                                       */
192   /* <Fields>                                                              */
193   /*    module_flags    :: Bit flags describing the module.                */
194   /*                                                                       */
195   /*    module_size     :: The size of one module object/instance in       */
196   /*                       bytes.                                          */
197   /*                                                                       */
198   /*    module_name     :: The name of the module.                         */
199   /*                                                                       */
200   /*    module_version  :: The version, as a 16.16 fixed number            */
201   /*                       (major.minor).                                  */
202   /*                                                                       */
203   /*    module_requires :: The version of FreeType this module requires,   */
204   /*                       as a 16.16 fixed number (major.minor).  Starts  */
205   /*                       at version 2.0, i.e., 0x20000.                  */
206   /*                                                                       */
207   /*    module_init     :: The initializing function.                      */
208   /*                                                                       */
209   /*    module_done     :: The finalizing function.                        */
210   /*                                                                       */
211   /*    get_interface   :: The interface requesting function.              */
212   /*                                                                       */
213   typedef struct  FT_Module_Class_
214   {
215     FT_ULong               module_flags;
216     FT_Long                module_size;
217     const FT_String*       module_name;
218     FT_Fixed               module_version;
219     FT_Fixed               module_requires;
220
221     const void*            module_interface;
222
223     FT_Module_Constructor  module_init;
224     FT_Module_Destructor   module_done;
225     FT_Module_Requester    get_interface;
226
227   } FT_Module_Class;
228
229
230   /*************************************************************************/
231   /*                                                                       */
232   /* <Function>                                                            */
233   /*    FT_Add_Module                                                      */
234   /*                                                                       */
235   /* <Description>                                                         */
236   /*    Add a new module to a given library instance.                      */
237   /*                                                                       */
238   /* <InOut>                                                               */
239   /*    library :: A handle to the library object.                         */
240   /*                                                                       */
241   /* <Input>                                                               */
242   /*    clazz   :: A pointer to class descriptor for the module.           */
243   /*                                                                       */
244   /* <Return>                                                              */
245   /*    FreeType error code.  0~means success.                             */
246   /*                                                                       */
247   /* <Note>                                                                */
248   /*    An error will be returned if a module already exists by that name, */
249   /*    or if the module requires a version of FreeType that is too great. */
250   /*                                                                       */
251   FT_EXPORT( FT_Error )
252   FT_Add_Module( FT_Library              library,
253                  const FT_Module_Class*  clazz );
254
255
256   /*************************************************************************/
257   /*                                                                       */
258   /* <Function>                                                            */
259   /*    FT_Get_Module                                                      */
260   /*                                                                       */
261   /* <Description>                                                         */
262   /*    Find a module by its name.                                         */
263   /*                                                                       */
264   /* <Input>                                                               */
265   /*    library     :: A handle to the library object.                     */
266   /*                                                                       */
267   /*    module_name :: The module's name (as an ASCII string).             */
268   /*                                                                       */
269   /* <Return>                                                              */
270   /*    A module handle.  0~if none was found.                             */
271   /*                                                                       */
272   /* <Note>                                                                */
273   /*    FreeType's internal modules aren't documented very well, and you   */
274   /*    should look up the source code for details.                        */
275   /*                                                                       */
276   FT_EXPORT( FT_Module )
277   FT_Get_Module( FT_Library   library,
278                  const char*  module_name );
279
280
281   /*************************************************************************/
282   /*                                                                       */
283   /* <Function>                                                            */
284   /*    FT_Remove_Module                                                   */
285   /*                                                                       */
286   /* <Description>                                                         */
287   /*    Remove a given module from a library instance.                     */
288   /*                                                                       */
289   /* <InOut>                                                               */
290   /*    library :: A handle to a library object.                           */
291   /*                                                                       */
292   /* <Input>                                                               */
293   /*    module  :: A handle to a module object.                            */
294   /*                                                                       */
295   /* <Return>                                                              */
296   /*    FreeType error code.  0~means success.                             */
297   /*                                                                       */
298   /* <Note>                                                                */
299   /*    The module object is destroyed by the function in case of success. */
300   /*                                                                       */
301   FT_EXPORT( FT_Error )
302   FT_Remove_Module( FT_Library  library,
303                     FT_Module   module );
304
305
306   /**********************************************************************
307    *
308    * @function:
309    *    FT_Property_Set
310    *
311    * @description:
312    *    Set a property for a given module.
313    *
314    * @input:
315    *    library ::
316    *       A handle to the library the module is part of.
317    *
318    *    module_name ::
319    *       The module name.
320    *
321    *    property_name ::
322    *       The property name.  Properties are described in the `Synopsis'
323    *       subsection of the module's documentation.
324    *
325    *       Note that only a few modules have properties.
326    *
327    *    value ::
328    *       A generic pointer to a variable or structure that gives the new
329    *       value of the property.  The exact definition of `value' is
330    *       dependent on the property; see the `Synopsis' subsection of the
331    *       module's documentation.
332    *
333    * @return:
334    *   FreeType error code.  0~means success.
335    *
336    * @note:
337    *    If `module_name' isn't a valid module name, or `property_name'
338    *    doesn't specify a valid property, or if `value' doesn't represent a
339    *    valid value for the given property, an error is returned.
340    *
341    *    The following example sets property `bar' (a simple integer) in
342    *    module `foo' to value~1.
343    *
344    *    {
345    *      FT_UInt  bar;
346    *
347    *
348    *      bar = 1;
349    *      FT_Property_Set( library, "foo", "bar", &bar );
350    *    }
351    *
352    *    Note that the FreeType Cache sub-system doesn't recognize module
353    *    property changes.  To avoid glyph lookup confusion within the cache
354    *    you should call @FTC_Manager_Reset to completely flush the cache if
355    *    a module property gets changed after @FTC_Manager_New has been
356    *    called.
357    *
358    *    It is not possible to set properties of the FreeType Cache
359    *    sub-system itself with FT_Property_Set; use @FTC_Property_Set
360    *    instead.
361    *
362    *  @since:
363    *    2.4.11
364    *
365    */
366   FT_EXPORT( FT_Error )
367   FT_Property_Set( FT_Library        library,
368                    const FT_String*  module_name,
369                    const FT_String*  property_name,
370                    const void*       value );
371
372
373   /**********************************************************************
374    *
375    * @function:
376    *    FT_Property_Get
377    *
378    * @description:
379    *    Get a module's property value.
380    *
381    * @input:
382    *    library ::
383    *       A handle to the library the module is part of.
384    *
385    *    module_name ::
386    *       The module name.
387    *
388    *    property_name ::
389    *       The property name.  Properties are described in the `Synopsis'
390    *       subsection of the module's documentation.
391    *
392    * @inout:
393    *    value ::
394    *       A generic pointer to a variable or structure that gives the
395    *       value of the property.  The exact definition of `value' is
396    *       dependent on the property; see the `Synopsis' subsection of the
397    *       module's documentation.
398    *
399    * @return:
400    *   FreeType error code.  0~means success.
401    *
402    * @note:
403    *    If `module_name' isn't a valid module name, or `property_name'
404    *    doesn't specify a valid property, or if `value' doesn't represent a
405    *    valid value for the given property, an error is returned.
406    *
407    *    The following example gets property `baz' (a range) in module `foo'.
408    *
409    *    {
410    *      typedef  range_
411    *      {
412    *        FT_Int32  min;
413    *        FT_Int32  max;
414    *
415    *      } range;
416    *
417    *      range  baz;
418    *
419    *
420    *      FT_Property_Get( library, "foo", "baz", &baz );
421    *    }
422    *
423    *    It is not possible to retrieve properties of the FreeType Cache
424    *    sub-system with FT_Property_Get; use @FTC_Property_Get instead.
425    *
426    *  @since:
427    *    2.4.11
428    *
429    */
430   FT_EXPORT( FT_Error )
431   FT_Property_Get( FT_Library        library,
432                    const FT_String*  module_name,
433                    const FT_String*  property_name,
434                    void*             value );
435
436
437   /*************************************************************************/
438   /*                                                                       */
439   /* <Function>                                                            */
440   /*    FT_Reference_Library                                               */
441   /*                                                                       */
442   /* <Description>                                                         */
443   /*    A counter gets initialized to~1 at the time an @FT_Library         */
444   /*    structure is created.  This function increments the counter.       */
445   /*    @FT_Done_Library then only destroys a library if the counter is~1, */
446   /*    otherwise it simply decrements the counter.                        */
447   /*                                                                       */
448   /*    This function helps in managing life-cycles of structures that     */
449   /*    reference @FT_Library objects.                                     */
450   /*                                                                       */
451   /* <Input>                                                               */
452   /*    library :: A handle to a target library object.                    */
453   /*                                                                       */
454   /* <Return>                                                              */
455   /*    FreeType error code.  0~means success.                             */
456   /*                                                                       */
457   /* <Since>                                                               */
458   /*    2.4.2                                                              */
459   /*                                                                       */
460   FT_EXPORT( FT_Error )
461   FT_Reference_Library( FT_Library  library );
462
463
464   /*************************************************************************/
465   /*                                                                       */
466   /* <Function>                                                            */
467   /*    FT_New_Library                                                     */
468   /*                                                                       */
469   /* <Description>                                                         */
470   /*    This function is used to create a new FreeType library instance    */
471   /*    from a given memory object.  It is thus possible to use libraries  */
472   /*    with distinct memory allocators within the same program.           */
473   /*                                                                       */
474   /*    Normally, you would call this function (followed by a call to      */
475   /*    @FT_Add_Default_Modules or a series of calls to @FT_Add_Module)    */
476   /*    instead of @FT_Init_FreeType to initialize the FreeType library.   */
477   /*                                                                       */
478   /*    Don't use @FT_Done_FreeType but @FT_Done_Library to destroy a      */
479   /*    library instance.                                                  */
480   /*                                                                       */
481   /* <Input>                                                               */
482   /*    memory   :: A handle to the original memory object.                */
483   /*                                                                       */
484   /* <Output>                                                              */
485   /*    alibrary :: A pointer to handle of a new library object.           */
486   /*                                                                       */
487   /* <Return>                                                              */
488   /*    FreeType error code.  0~means success.                             */
489   /*                                                                       */
490   /* <Note>                                                                */
491   /*    See the discussion of reference counters in the description of     */
492   /*    @FT_Reference_Library.                                             */
493   /*                                                                       */
494   FT_EXPORT( FT_Error )
495   FT_New_Library( FT_Memory    memory,
496                   FT_Library  *alibrary );
497
498
499   /*************************************************************************/
500   /*                                                                       */
501   /* <Function>                                                            */
502   /*    FT_Done_Library                                                    */
503   /*                                                                       */
504   /* <Description>                                                         */
505   /*    Discard a given library object.  This closes all drivers and       */
506   /*    discards all resource objects.                                     */
507   /*                                                                       */
508   /* <Input>                                                               */
509   /*    library :: A handle to the target library.                         */
510   /*                                                                       */
511   /* <Return>                                                              */
512   /*    FreeType error code.  0~means success.                             */
513   /*                                                                       */
514   /* <Note>                                                                */
515   /*    See the discussion of reference counters in the description of     */
516   /*    @FT_Reference_Library.                                             */
517   /*                                                                       */
518   FT_EXPORT( FT_Error )
519   FT_Done_Library( FT_Library  library );
520
521   /* */
522
523   typedef void
524   (*FT_DebugHook_Func)( void*  arg );
525
526
527   /*************************************************************************/
528   /*                                                                       */
529   /* <Function>                                                            */
530   /*    FT_Set_Debug_Hook                                                  */
531   /*                                                                       */
532   /* <Description>                                                         */
533   /*    Set a debug hook function for debugging the interpreter of a font  */
534   /*    format.                                                            */
535   /*                                                                       */
536   /* <InOut>                                                               */
537   /*    library    :: A handle to the library object.                      */
538   /*                                                                       */
539   /* <Input>                                                               */
540   /*    hook_index :: The index of the debug hook.  You should use the     */
541   /*                  values defined in `ftobjs.h', e.g.,                  */
542   /*                  `FT_DEBUG_HOOK_TRUETYPE'.                            */
543   /*                                                                       */
544   /*    debug_hook :: The function used to debug the interpreter.          */
545   /*                                                                       */
546   /* <Note>                                                                */
547   /*    Currently, four debug hook slots are available, but only two (for  */
548   /*    the TrueType and the Type~1 interpreter) are defined.              */
549   /*                                                                       */
550   /*    Since the internal headers of FreeType are no longer installed,    */
551   /*    the symbol `FT_DEBUG_HOOK_TRUETYPE' isn't available publicly.      */
552   /*    This is a bug and will be fixed in a forthcoming release.          */
553   /*                                                                       */
554   FT_EXPORT( void )
555   FT_Set_Debug_Hook( FT_Library         library,
556                      FT_UInt            hook_index,
557                      FT_DebugHook_Func  debug_hook );
558
559
560   /*************************************************************************/
561   /*                                                                       */
562   /* <Function>                                                            */
563   /*    FT_Add_Default_Modules                                             */
564   /*                                                                       */
565   /* <Description>                                                         */
566   /*    Add the set of default drivers to a given library object.          */
567   /*    This is only useful when you create a library object with          */
568   /*    @FT_New_Library (usually to plug a custom memory manager).         */
569   /*                                                                       */
570   /* <InOut>                                                               */
571   /*    library :: A handle to a new library object.                       */
572   /*                                                                       */
573   FT_EXPORT( void )
574   FT_Add_Default_Modules( FT_Library  library );
575
576
577
578   /**************************************************************************
579    *
580    * @section:
581    *   truetype_engine
582    *
583    * @title:
584    *   The TrueType Engine
585    *
586    * @abstract:
587    *   TrueType bytecode support.
588    *
589    * @description:
590    *   This section contains a function used to query the level of TrueType
591    *   bytecode support compiled in this version of the library.
592    *
593    */
594
595
596   /**************************************************************************
597    *
598    *  @enum:
599    *     FT_TrueTypeEngineType
600    *
601    *  @description:
602    *     A list of values describing which kind of TrueType bytecode
603    *     engine is implemented in a given FT_Library instance.  It is used
604    *     by the @FT_Get_TrueType_Engine_Type function.
605    *
606    *  @values:
607    *     FT_TRUETYPE_ENGINE_TYPE_NONE ::
608    *       The library doesn't implement any kind of bytecode interpreter.
609    *
610    *     FT_TRUETYPE_ENGINE_TYPE_UNPATENTED ::
611    *       The library implements a bytecode interpreter that doesn't
612    *       support the patented operations of the TrueType virtual machine.
613    *
614    *       Its main use is to load certain Asian fonts that position and
615    *       scale glyph components with bytecode instructions.  It produces
616    *       bad output for most other fonts.
617    *
618    *     FT_TRUETYPE_ENGINE_TYPE_PATENTED ::
619    *       The library implements a bytecode interpreter that covers
620    *       the full instruction set of the TrueType virtual machine (this
621    *       was governed by patents until May 2010, hence the name).
622    *
623    *  @since:
624    *     2.2
625    *
626    */
627   typedef enum  FT_TrueTypeEngineType_
628   {
629     FT_TRUETYPE_ENGINE_TYPE_NONE = 0,
630     FT_TRUETYPE_ENGINE_TYPE_UNPATENTED,
631     FT_TRUETYPE_ENGINE_TYPE_PATENTED
632
633   } FT_TrueTypeEngineType;
634
635
636   /**************************************************************************
637    *
638    *  @func:
639    *     FT_Get_TrueType_Engine_Type
640    *
641    *  @description:
642    *     Return an @FT_TrueTypeEngineType value to indicate which level of
643    *     the TrueType virtual machine a given library instance supports.
644    *
645    *  @input:
646    *     library ::
647    *       A library instance.
648    *
649    *  @return:
650    *     A value indicating which level is supported.
651    *
652    *  @since:
653    *     2.2
654    *
655    */
656   FT_EXPORT( FT_TrueTypeEngineType )
657   FT_Get_TrueType_Engine_Type( FT_Library  library );
658
659   /* */
660
661
662 FT_END_HEADER
663
664 #endif /* __FTMODAPI_H__ */
665
666
667 /* END */