Home | History | Annotate | Download | only in freetype
      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