include/internal/ftdriver.h

   1 /***************************************************************************/
   2 /*                                                                         */
   3 /*  ftdriver.h                                                             */
   4 /*                                                                         */
   5 /*    FreeType font driver interface (specification).                      */
   6 /*                                                                         */
   7 /*  Copyright 1996-2003, 2006, 2008, 2011-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 __FTDRIVER_H__
  20 #define __FTDRIVER_H__
  21
  22
  23 #include <ft2build.h>
  24 #include FT_MODULE_H
  25
  26
  27 FT_BEGIN_HEADER
  28
  29
  30   typedef FT_Error
  31   (*FT_Face_InitFunc)( FT_Stream      stream,
  32                        FT_Face        face,
  33                        FT_Int         typeface_index,
  34                        FT_Int         num_params,
  35                        FT_Parameter*  parameters );
  36
  37   typedef void
  38   (*FT_Face_DoneFunc)( FT_Face  face );
  39
  40
  41   typedef FT_Error
  42   (*FT_Size_InitFunc)( FT_Size  size );
  43
  44   typedef void
  45   (*FT_Size_DoneFunc)( FT_Size  size );
  46
  47
  48   typedef FT_Error
  49   (*FT_Slot_InitFunc)( FT_GlyphSlot  slot );
  50
  51   typedef void
  52   (*FT_Slot_DoneFunc)( FT_GlyphSlot  slot );
  53
  54
  55   typedef FT_Error
  56   (*FT_Size_RequestFunc)( FT_Size          size,
  57                           FT_Size_Request  req );
  58
  59   typedef FT_Error
  60   (*FT_Size_SelectFunc)( FT_Size   size,
  61                          FT_ULong  size_index );
  62
  63   typedef FT_Error
  64   (*FT_Slot_LoadFunc)( FT_GlyphSlot  slot,
  65                        FT_Size       size,
  66                        FT_UInt       glyph_index,
  67                        FT_Int32      load_flags );
  68
  69
  70   typedef FT_UInt
  71   (*FT_CharMap_CharIndexFunc)( FT_CharMap  charmap,
  72                                FT_Long     charcode );
  73
  74   typedef FT_Long
  75   (*FT_CharMap_CharNextFunc)( FT_CharMap  charmap,
  76                               FT_Long     charcode );
  77
  78
  79   typedef FT_Error
  80   (*FT_Face_GetKerningFunc)( FT_Face     face,
  81                              FT_UInt     left_glyph,
  82                              FT_UInt     right_glyph,
  83                              FT_Vector*  kerning );
  84
  85
  86   typedef FT_Error
  87   (*FT_Face_AttachFunc)( FT_Face    face,
  88                          FT_Stream  stream );
  89
  90
  91   typedef FT_Error
  92   (*FT_Face_GetAdvancesFunc)( FT_Face    face,
  93                               FT_UInt    first,
  94                               FT_UInt    count,
  95                               FT_Int32   flags,
  96                               FT_Fixed*  advances );
  97
  98
  99   /*************************************************************************/
 100   /*                                                                       */
 101   /* <Struct>                                                              */
 102   /*    FT_Driver_ClassRec                                                 */
 103   /*                                                                       */
 104   /* <Description>                                                         */
 105   /*    The font driver class.  This structure mostly contains pointers to */
 106   /*    driver methods.                                                    */
 107   /*                                                                       */
 108   /* <Fields>                                                              */
 109   /*    root             :: The parent module.                             */
 110   /*                                                                       */
 111   /*    face_object_size :: The size of a face object in bytes.            */
 112   /*                                                                       */
 113   /*    size_object_size :: The size of a size object in bytes.            */
 114   /*                                                                       */
 115   /*    slot_object_size :: The size of a glyph object in bytes.           */
 116   /*                                                                       */
 117   /*    init_face        :: The format-specific face constructor.          */
 118   /*                                                                       */
 119   /*    done_face        :: The format-specific face destructor.           */
 120   /*                                                                       */
 121   /*    init_size        :: The format-specific size constructor.          */
 122   /*                                                                       */
 123   /*    done_size        :: The format-specific size destructor.           */
 124   /*                                                                       */
 125   /*    init_slot        :: The format-specific slot constructor.          */
 126   /*                                                                       */
 127   /*    done_slot        :: The format-specific slot destructor.           */
 128   /*                                                                       */
 129   /*                                                                       */
 130   /*    load_glyph       :: A function handle to load a glyph to a slot.   */
 131   /*                        This field is mandatory!                       */
 132   /*                                                                       */
 133   /*    get_kerning      :: A function handle to return the unscaled       */
 134   /*                        kerning for a given pair of glyphs.  Can be    */
 135   /*                        set to 0 if the format doesn't support         */
 136   /*                        kerning.                                       */
 137   /*                                                                       */
 138   /*    attach_file      :: This function handle is used to read           */
 139   /*                        additional data for a face from another        */
 140   /*                        file/stream.  For example, this can be used to */
 141   /*                        add data from AFM or PFM files on a Type 1     */
 142   /*                        face, or a CIDMap on a CID-keyed face.         */
 143   /*                                                                       */
 144   /*    get_advances     :: A function handle used to return advance       */
 145   /*                        widths of `count' glyphs (in font units),      */
 146   /*                        starting at `first'.  The `vertical' flag must */
 147   /*                        be set to get vertical advance heights.  The   */
 148   /*                        `advances' buffer is caller-allocated.         */
 149   /*                        The idea of this function is to be able to     */
 150   /*                        perform device-independent text layout without */
 151   /*                        loading a single glyph image.                  */
 152   /*                                                                       */
 153   /*    request_size     :: A handle to a function used to request the new */
 154   /*                        character size.  Can be set to 0 if the        */
 155   /*                        scaling done in the base layer suffices.       */
 156   /*                                                                       */
 157   /*    select_size      :: A handle to a function used to select a new    */
 158   /*                        fixed size.  It is used only if                */
 159   /*                        @FT_FACE_FLAG_FIXED_SIZES is set.  Can be set  */
 160   /*                        to 0 if the scaling done in the base layer     */
 161   /*                        suffices.                                      */
 162   /* <Note>                                                                */
 163   /*    Most function pointers, with the exception of `load_glyph', can be */
 164   /*    set to 0 to indicate a default behaviour.                          */
 165   /*                                                                       */
 166   typedef struct  FT_Driver_ClassRec_
 167   {
 168     FT_Module_Class          root;
 169
 170     FT_Long                  face_object_size;
 171     FT_Long                  size_object_size;
 172     FT_Long                  slot_object_size;
 173
 174     FT_Face_InitFunc         init_face;
 175     FT_Face_DoneFunc         done_face;
 176
 177     FT_Size_InitFunc         init_size;
 178     FT_Size_DoneFunc         done_size;
 179
 180     FT_Slot_InitFunc         init_slot;
 181     FT_Slot_DoneFunc         done_slot;
 182
 183     FT_Slot_LoadFunc         load_glyph;
 184
 185     FT_Face_GetKerningFunc   get_kerning;
 186     FT_Face_AttachFunc       attach_file;
 187     FT_Face_GetAdvancesFunc  get_advances;
 188
 189     /* since version 2.2 */
 190     FT_Size_RequestFunc      request_size;
 191     FT_Size_SelectFunc       select_size;
 192
 193   } FT_Driver_ClassRec, *FT_Driver_Class;
 194
 195
 196   /*************************************************************************/
 197   /*                                                                       */
 198   /* <Macro>                                                               */
 199   /*    FT_DECLARE_DRIVER                                                  */
 200   /*                                                                       */
 201   /* <Description>                                                         */
 202   /*    Used to create a forward declaration of an FT_Driver_ClassRec      */
 203   /*    struct instance.                                                   */
 204   /*                                                                       */
 205   /* <Macro>                                                               */
 206   /*    FT_DEFINE_DRIVER                                                   */
 207   /*                                                                       */
 208   /* <Description>                                                         */
 209   /*    Used to initialize an instance of FT_Driver_ClassRec struct.       */
 210   /*                                                                       */
 211   /*    When FT_CONFIG_OPTION_PIC is defined a `create' function has to be */
 212   /*    called with a pointer where the allocated structure is returned.   */
 213   /*    And when it is no longer needed a `destroy' function needs to be   */
 214   /*    called to release that allocation.                                 */
 215   /*                                                                       */
 216   /*    `fcinit.c' (ft_create_default_module_classes) already contains a   */
 217   /*    mechanism to call these functions for the default modules          */
 218   /*    described in `ftmodule.h'.                                         */
 219   /*                                                                       */
 220   /*    Notice that the created `create' and `destroy' functions call      */
 221   /*    `pic_init' and `pic_free' to allow you to manually allocate and    */
 222   /*    initialize any additional global data, like a module specific      */
 223   /*    interface, and put them in the global pic container defined in     */
 224   /*    `ftpic.h'.  If you don't need them just implement the functions as */
 225   /*    empty to resolve the link error.  Also the `pic_init' and          */
 226   /*    `pic_free' functions should be declared in `pic.h', to be referred */
 227   /*    by driver definition calling `FT_DEFINE_DRIVER' in following.      */
 228   /*                                                                       */
 229   /*    When FT_CONFIG_OPTION_PIC is not defined the struct will be        */
 230   /*    allocated in the global scope (or the scope where the macro is     */
 231   /*    used).                                                             */
 232   /*                                                                       */
 233 #ifndef FT_CONFIG_OPTION_PIC
 234
 235 #define FT_DECLARE_DRIVER( class_ )  \
 236   FT_CALLBACK_TABLE                  \
 237   const FT_Driver_ClassRec  class_;
 238
 239 #define FT_DEFINE_DRIVER(                    \
 240           class_,                            \
 241           flags_,                            \
 242           size_,                             \
 243           name_,                             \
 244           version_,                          \
 245           requires_,                         \
 246           interface_,                        \
 247           init_,                             \
 248           done_,                             \
 249           get_interface_,                    \
 250           face_object_size_,                 \
 251           size_object_size_,                 \
 252           slot_object_size_,                 \
 253           init_face_,                        \
 254           done_face_,                        \
 255           init_size_,                        \
 256           done_size_,                        \
 257           init_slot_,                        \
 258           done_slot_,                        \
 259           load_glyph_,                       \
 260           get_kerning_,                      \
 261           attach_file_,                      \
 262           get_advances_,                     \
 263           request_size_,                     \
 264           select_size_ )                     \
 265   FT_CALLBACK_TABLE_DEF                      \
 266   const FT_Driver_ClassRec  class_ =         \
 267   {                                          \
 268     FT_DEFINE_ROOT_MODULE( flags_,           \
 269                            size_,            \
 270                            name_,            \
 271                            version_,         \
 272                            requires_,        \
 273                            interface_,       \
 274                            init_,            \
 275                            done_,            \
 276                            get_interface_ )  \
 277                                              \
 278     face_object_size_,                       \
 279     size_object_size_,                       \
 280     slot_object_size_,                       \
 281                                              \
 282     init_face_,                              \
 283     done_face_,                              \
 284                                              \
 285     init_size_,                              \
 286     done_size_,                              \
 287                                              \
 288     init_slot_,                              \
 289     done_slot_,                              \
 290                                              \
 291     load_glyph_,                             \
 292                                              \
 293     get_kerning_,                            \
 294     attach_file_,                            \
 295     get_advances_,                           \
 296                                              \
 297     request_size_,                           \
 298     select_size_                             \
 299   };
 300
 301 #else /* FT_CONFIG_OPTION_PIC */
 302
 303 #define FT_DECLARE_DRIVER( class_ )  FT_DECLARE_MODULE( class_ )
 304
 305 #define FT_DEFINE_DRIVER(                                        \
 306           class_,                                                \
 307           flags_,                                                \
 308           size_,                                                 \
 309           name_,                                                 \
 310           version_,                                              \
 311           requires_,                                             \
 312           interface_,                                            \
 313           init_,                                                 \
 314           done_,                                                 \
 315           get_interface_,                                        \
 316           face_object_size_,                                     \
 317           size_object_size_,                                     \
 318           slot_object_size_,                                     \
 319           init_face_,                                            \
 320           done_face_,                                            \
 321           init_size_,                                            \
 322           done_size_,                                            \
 323           init_slot_,                                            \
 324           done_slot_,                                            \
 325           load_glyph_,                                           \
 326           get_kerning_,                                          \
 327           attach_file_,                                          \
 328           get_advances_,                                         \
 329           request_size_,                                         \
 330           select_size_ )                                         \
 331   void                                                           \
 332   FT_Destroy_Class_ ## class_( FT_Library        library,        \
 333                                FT_Module_Class*  clazz )         \
 334   {                                                              \
 335     FT_Memory        memory = library->memory;                   \
 336     FT_Driver_Class  dclazz = (FT_Driver_Class)clazz;            \
 337                                                                  \
 338                                                                  \
 339     class_ ## _pic_free( library );                              \
 340     if ( dclazz )                                                \
 341       FT_FREE( dclazz );                                         \
 342   }                                                              \
 343                                                                  \
 344                                                                  \
 345   FT_Error                                                       \
 346   FT_Create_Class_ ## class_( FT_Library         library,        \
 347                               FT_Module_Class**  output_class )  \
 348   {                                                              \
 349     FT_Driver_Class  clazz  = NULL;                              \
 350     FT_Error         error;                                      \
 351     FT_Memory        memory = library->memory;                   \
 352                                                                  \
 353                                                                  \
 354     if ( FT_ALLOC( clazz, sizeof ( *clazz ) ) )                  \
 355       return error;                                              \
 356                                                                  \
 357     error = class_ ## _pic_init( library );                      \
 358     if ( error )                                                 \
 359     {                                                            \
 360       FT_FREE( clazz );                                          \
 361       return error;                                              \
 362     }                                                            \
 363                                                                  \
 364     FT_DEFINE_ROOT_MODULE( flags_,                               \
 365                            size_,                                \
 366                            name_,                                \
 367                            version_,                             \
 368                            requires_,                            \
 369                            interface_,                           \
 370                            init_,                                \
 371                            done_,                                \
 372                            get_interface_ )                      \
 373                                                                  \
 374     clazz->face_object_size = face_object_size_;                 \
 375     clazz->size_object_size = size_object_size_;                 \
 376     clazz->slot_object_size = slot_object_size_;                 \
 377                                                                  \
 378     clazz->init_face        = init_face_;                        \
 379     clazz->done_face        = done_face_;                        \
 380                                                                  \
 381     clazz->init_size        = init_size_;                        \
 382     clazz->done_size        = done_size_;                        \
 383                                                                  \
 384     clazz->init_slot        = init_slot_;                        \
 385     clazz->done_slot        = done_slot_;                        \
 386                                                                  \
 387     clazz->load_glyph       = load_glyph_;                       \
 388                                                                  \
 389     clazz->get_kerning      = get_kerning_;                      \
 390     clazz->attach_file      = attach_file_;                      \
 391     clazz->get_advances     = get_advances_;                     \
 392                                                                  \
 393     clazz->request_size     = request_size_;                     \
 394     clazz->select_size      = select_size_;                      \
 395                                                                  \
 396     *output_class = (FT_Module_Class*)clazz;                     \
 397                                                                  \
 398     return FT_Err_Ok;                                            \
 399   }
 400
 401
 402 #endif /* FT_CONFIG_OPTION_PIC */
 403
 404 FT_END_HEADER
 405
 406 #endif /* __FTDRIVER_H__ */
 407
 408
 409 /* END */