libraries/freetype-2.0.5/include/freetype/ftmodule.h

   1 /***************************************************************************/
   2 /*                                                                         */
   3 /*  ftmodule.h                                                             */
   4 /*                                                                         */
   5 /*    FreeType modules public interface (specification).                   */
   6 /*                                                                         */
   7 /*  Copyright 1996-2001 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 __FTMODULE_H__
  20 #define __FTMODULE_H__
  21
  22
  23 #include <ft2build.h>
  24 #include FT_FREETYPE_H
  25
  26
  27 FT_BEGIN_HEADER
  28
  29
  30   /*************************************************************************/
  31   /*                                                                       */
  32   /* <Section>                                                             */
  33   /*    module_management                                                  */
  34   /*                                                                       */
  35   /* <Title>                                                               */
  36   /*    Module Management                                                  */
  37   /*                                                                       */
  38   /* <Abstract>                                                            */
  39   /*    How to add, upgrade, and remove modules from FreeType.             */
  40   /*                                                                       */
  41   /* <Description>                                                         */
  42   /*    The definitions below are used to manage modules within FreeType.  */
  43   /*    Modules can be added, upgraded, and removed at runtime.            */
  44   /*                                                                       */
  45   /*************************************************************************/
  46
  47
  48   /* module bit flags */
  49   typedef enum  FT_Module_Flags_
  50   {
  51     ft_module_font_driver         = 1,     /* this module is a font driver  */
  52     ft_module_renderer            = 2,     /* this module is a renderer     */
  53     ft_module_hinter              = 4,     /* this module is a glyph hinter */
  54     ft_module_styler              = 8,     /* this module is a styler       */
  55
  56     ft_module_driver_scalable     = 0x100, /* the driver supports scalable  */
  57                                            /* fonts                         */
  58     ft_module_driver_no_outlines  = 0x200, /* the driver does not support   */
  59                                            /* vector outlines               */
  60     ft_module_driver_has_hinter   = 0x400  /* the driver provides its own   */
  61                                            /* hinter                        */
  62
  63   } FT_Module_Flags;
  64
  65
  66   typedef void
  67   (*FT_Module_Interface)( void );
  68
  69   typedef FT_Error
  70   (*FT_Module_Constructor)( FT_Module  module );
  71
  72   typedef void
  73   (*FT_Module_Destructor)( FT_Module  module );
  74
  75   typedef FT_Module_Interface
  76   (*FT_Module_Requester)( FT_Module    module,
  77                           const char*  name );
  78
  79
  80   /*************************************************************************/
  81   /*                                                                       */
  82   /* <Struct>                                                              */
  83   /*    FT_Module_Class                                                    */
  84   /*                                                                       */
  85   /* <Description>                                                         */
  86   /*    The module class descriptor.                                       */
  87   /*                                                                       */
  88   /* <Fields>                                                              */
  89   /*    module_flags      :: Bit flags describing the module.              */
  90   /*                                                                       */
  91   /*    module_size       :: The size of one module object/instance in     */
  92   /*                         bytes.                                        */
  93   /*                                                                       */
  94   /*    module_name       :: The name of the module.                       */
  95   /*                                                                       */
  96   /*    module_version    :: The version, as a 16.16 fixed number          */
  97   /*                         (major.minor).                                */
  98   /*                                                                       */
  99   /*    module_requires   :: The version of FreeType this module requires  */
 100   /*                         (starts at version 2.0, i.e 0x20000)          */
 101   /*                                                                       */
 102   /*    module_init       :: A function used to initialize (not create) a  */
 103   /*                         new module object.                            */
 104   /*                                                                       */
 105   /*    module_done       :: A function used to finalize (not destroy) a   */
 106   /*                         given module object                           */
 107   /*                                                                       */
 108   /*    get_interface     :: Queries a given module for a specific         */
 109   /*                         interface by name.                            */
 110   /*                                                                       */
 111   typedef struct  FT_Module_Class_
 112   {
 113     FT_ULong               module_flags;
 114     FT_Int                 module_size;
 115     const FT_String*       module_name;
 116     FT_Fixed               module_version;
 117     FT_Fixed               module_requires;
 118
 119     const void*            module_interface;
 120
 121     FT_Module_Constructor  module_init;
 122     FT_Module_Destructor   module_done;
 123     FT_Module_Requester    get_interface;
 124
 125   } FT_Module_Class;
 126
 127
 128   /*************************************************************************/
 129   /*                                                                       */
 130   /* <Function>                                                            */
 131   /*    FT_Add_Module                                                      */
 132   /*                                                                       */
 133   /* <Description>                                                         */
 134   /*    Adds a new module to a given library instance.                     */
 135   /*                                                                       */
 136   /* <InOut>                                                               */
 137   /*    library :: A handle to the library object.                         */
 138   /*                                                                       */
 139   /* <Input>                                                               */
 140   /*    clazz   :: A pointer to class descriptor for the module.           */
 141   /*                                                                       */
 142   /* <Return>                                                              */
 143   /*    FreeType error code.  0 means success.                             */
 144   /*                                                                       */
 145   /* <Note>                                                                */
 146   /*    An error will be returned if a module already exists by that name, */
 147   /*    or if the module requires a version of FreeType that is too great. */
 148   /*                                                                       */
 149   FT_EXPORT( FT_Error )
 150   FT_Add_Module( FT_Library              library,
 151                  const FT_Module_Class*  clazz );
 152
 153
 154   /*************************************************************************/
 155   /*                                                                       */
 156   /* <Function>                                                            */
 157   /*    FT_Get_Module                                                      */
 158   /*                                                                       */
 159   /* <Description>                                                         */
 160   /*    Finds a module by its name.                                        */
 161   /*                                                                       */
 162   /* <Input>                                                               */
 163   /*    library     :: A handle to the library object.                     */
 164   /*                                                                       */
 165   /*    module_name :: The module's name (as an ASCII string).             */
 166   /*                                                                       */
 167   /* <Return>                                                              */
 168   /*    A module handle.  0 if none was found.                             */
 169   /*                                                                       */
 170   /* <Note>                                                                */
 171   /*    You should better be familiar with FreeType internals to know      */
 172   /*    which module to look for :-)                                       */
 173   /*                                                                       */
 174   FT_EXPORT( FT_Module )
 175   FT_Get_Module( FT_Library   library,
 176                  const char*  module_name );
 177
 178
 179   /*************************************************************************/
 180   /*                                                                       */
 181   /* <Function>                                                            */
 182   /*    FT_Remove_Module                                                   */
 183   /*                                                                       */
 184   /* <Description>                                                         */
 185   /*    Removes a given module from a library instance.                    */
 186   /*                                                                       */
 187   /* <InOut>                                                               */
 188   /*    library :: A handle to a library object.                           */
 189   /*                                                                       */
 190   /* <Input>                                                               */
 191   /*    module  :: A handle to a module object.                            */
 192   /*                                                                       */
 193   /* <Return>                                                              */
 194   /*    FreeType error code.  0 means success.                             */
 195   /*                                                                       */
 196   /* <Note>                                                                */
 197   /*    The module object is destroyed by the function in case of success. */
 198   /*                                                                       */
 199   FT_EXPORT( FT_Error )
 200   FT_Remove_Module( FT_Library  library,
 201                     FT_Module   module );
 202
 203
 204   /*************************************************************************/
 205   /*                                                                       */
 206   /* <Function>                                                            */
 207   /*    FT_New_Library                                                     */
 208   /*                                                                       */
 209   /* <Description>                                                         */
 210   /*    This function is used to create a new FreeType library instance    */
 211   /*    from a given memory object.  It is thus possible to use libraries  */
 212   /*    with distinct memory allocators within the same program.           */
 213   /*                                                                       */
 214   /* <Input>                                                               */
 215   /*    memory   :: A handle to the original memory object.                */
 216   /*                                                                       */
 217   /* <Output>                                                              */
 218   /*    alibrary :: A pointer to handle of a new library object.           */
 219   /*                                                                       */
 220   /* <Return>                                                              */
 221   /*    FreeType error code.  0 means success.                             */
 222   /*                                                                       */
 223   FT_EXPORT( FT_Error )
 224   FT_New_Library( FT_Memory    memory,
 225                   FT_Library  *alibrary );
 226
 227
 228   /*************************************************************************/
 229   /*                                                                       */
 230   /* <Function>                                                            */
 231   /*    FT_Done_Library                                                    */
 232   /*                                                                       */
 233   /* <Description>                                                         */
 234   /*    Discards a given library object.  This closes all drivers and      */
 235   /*    discards all resource objects.                                     */
 236   /*                                                                       */
 237   /* <Input>                                                               */
 238   /*    library :: A handle to the target library.                         */
 239   /*                                                                       */
 240   /* <Return>                                                              */
 241   /*    FreeType error code.  0 means success.                             */
 242   /*                                                                       */
 243   FT_EXPORT( FT_Error )
 244   FT_Done_Library( FT_Library  library );
 245
 246
 247
 248   typedef void
 249   (*FT_DebugHook_Func)( void*  arg );
 250
 251
 252   /*************************************************************************/
 253   /*                                                                       */
 254   /* <Function>                                                            */
 255   /*    FT_Set_Debug_Hook                                                  */
 256   /*                                                                       */
 257   /* <Description>                                                         */
 258   /*    Sets a debug hook function for debugging the interpreter of a font */
 259   /*    format.                                                            */
 260   /*                                                                       */
 261   /* <InOut>                                                               */
 262   /*    library    :: A handle to the library object.                      */
 263   /*                                                                       */
 264   /* <Input>                                                               */
 265   /*    hook_index :: The index of the debug hook.  You should use the     */
 266   /*                  values defined in ftobjs.h, e.g.                     */
 267   /*                  FT_DEBUG_HOOK_TRUETYPE.                              */
 268   /*                                                                       */
 269   /*    debug_hook :: The function used to debug the interpreter.          */
 270   /*                                                                       */
 271   /* <Note>                                                                */
 272   /*    Currently, four debug hook slots are available, but only two (for  */
 273   /*    the TrueType and the Type 1 interpreter) are defined.              */
 274   /*                                                                       */
 275   FT_EXPORT( void )
 276   FT_Set_Debug_Hook( FT_Library         library,
 277                      FT_UInt            hook_index,
 278                      FT_DebugHook_Func  debug_hook );
 279
 280
 281
 282   /*************************************************************************/
 283   /*                                                                       */
 284   /* <Function>                                                            */
 285   /*    FT_Add_Default_Modules                                             */
 286   /*                                                                       */
 287   /* <Description>                                                         */
 288   /*    Adds the set of default drivers to a given library object.         */
 289   /*    This is only useful when you create a library object with          */
 290   /*    FT_New_Library() (usually to plug a custom memory manager).        */
 291   /*                                                                       */
 292   /* <InOut>                                                               */
 293   /*    library :: A handle to a new library object.                       */
 294   /*                                                                       */
 295   FT_EXPORT( void )
 296   FT_Add_Default_Modules( FT_Library  library );
 297
 298
 299   /* */
 300
 301
 302 FT_END_HEADER
 303
 304 #endif /* __FTMODULE_H__ */
 305
 306
 307 /* END */