include/freetype/ftmodapi.h

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