libraries/freetype-2.0.5/include/freetype/internal/ftextend.h

   1 /***************************************************************************/
   2 /*                                                                         */
   3 /*  ftextend.h                                                             */
   4 /*                                                                         */
   5 /*    FreeType extensions implementation (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 __FTEXTEND_H__
  20 #define __FTEXTEND_H__
  21
  22
  23 #include <ft2build.h>
  24 #include FT_INTERNAL_OBJECTS_H
  25
  26
  27 FT_BEGIN_HEADER
  28
  29
  30   /*************************************************************************/
  31   /*                                                                       */
  32   /* The extensions don't need to be integrated at compile time into the   */
  33   /* engine, only at link time.                                            */
  34   /*                                                                       */
  35   /*************************************************************************/
  36
  37
  38   /*************************************************************************/
  39   /*                                                                       */
  40   /* <FuncType>                                                            */
  41   /*    FT_Extension_Initializer                                           */
  42   /*                                                                       */
  43   /* <Description>                                                         */
  44   /*    Each new face object can have several extensions associated with   */
  45   /*    it at creation time.  This function is used to initialize given    */
  46   /*    extension data for a given face.                                   */
  47   /*                                                                       */
  48   /* <InOut>                                                               */
  49   /*    ext  :: A typeless pointer to the extension data.                  */
  50   /*                                                                       */
  51   /*    face :: A handle to the source face object the extension is        */
  52   /*            associated with.                                           */
  53   /*                                                                       */
  54   /* <Return>                                                              */
  55   /*    FreeType error code.  0 means success.                             */
  56   /*                                                                       */
  57   /* <Note>                                                                */
  58   /*    In case of error, the initializer should not destroy the extension */
  59   /*    data, as the finalizer will get called later by the function's     */
  60   /*    caller.                                                            */
  61   /*                                                                       */
  62   typedef FT_Error
  63   (*FT_Extension_Initializer)( void*    ext,
  64                                FT_Face  face );
  65
  66
  67   /*************************************************************************/
  68   /*                                                                       */
  69   /* <FuncType>                                                            */
  70   /*    FT_Extension_Finalizer                                             */
  71   /*                                                                       */
  72   /* <Description>                                                         */
  73   /*    Each new face object can have several extensions associated with   */
  74   /*    it at creation time.  This function is used to finalize given      */
  75   /*    extension data for a given face; it occurs before the face object  */
  76   /*    itself is finalized.                                               */
  77   /*                                                                       */
  78   /* <InOut>                                                               */
  79   /*    ext  :: A typeless pointer to the extension data.                  */
  80   /*                                                                       */
  81   /*    face :: A handle to the source face object the extension is        */
  82   /*            associated with.                                           */
  83   /*                                                                       */
  84   typedef void
  85   (*FT_Extension_Finalizer)( void*    ext,
  86                              FT_Face  face );
  87
  88
  89   /*************************************************************************/
  90   /*                                                                       */
  91   /* <Struct>                                                              */
  92   /*    FT_Extension_Class                                                 */
  93   /*                                                                       */
  94   /* <Description>                                                         */
  95   /*    A simple structure used to describe a given extension to the       */
  96   /*    FreeType base layer.  An FT_Extension_Class is used as a parameter */
  97   /*    for FT_Register_Extension().                                       */
  98   /*                                                                       */
  99   /* <Fields>                                                              */
 100   /*    id        :: The extension's ID.  This is a normal C string that   */
 101   /*                 is used to uniquely reference the extension's         */
 102   /*                 interface.                                            */
 103   /*                                                                       */
 104   /*    size      :: The size in bytes of the extension data that must be  */
 105   /*                 associated with each face object.                     */
 106   /*                                                                       */
 107   /*    init      :: A pointer to the extension data's initializer.        */
 108   /*                                                                       */
 109   /*    finalize  :: A pointer to the extension data's finalizer.          */
 110   /*                                                                       */
 111   /*    interface :: This pointer can be anything, but should usually      */
 112   /*                 point to a table of function pointers which implement */
 113   /*                 the extension's interface.                            */
 114   /*                                                                       */
 115   /*    offset    :: This field is set and used within the base layer and  */
 116   /*                 should be set to 0 when registering an extension      */
 117   /*                 through FT_Register_Extension().  It contains an      */
 118   /*                 offset within the face's extension block for the      */
 119   /*                 current extension's data.                             */
 120   /*                                                                       */
 121   typedef struct  FT_Extension_Class_
 122   {
 123     const char*               id;
 124     FT_ULong                  size;
 125     FT_Extension_Initializer  init;
 126     FT_Extension_Finalizer    finalize;
 127     void*                     interface;
 128
 129     FT_ULong                  offset;
 130
 131   } FT_Extension_Class;
 132
 133
 134   /*************************************************************************/
 135   /*                                                                       */
 136   /* <Function>                                                            */
 137   /*    FT_Register_Extension                                              */
 138   /*                                                                       */
 139   /* <Description>                                                         */
 140   /*    Registers a new extension.                                         */
 141   /*                                                                       */
 142   /* <InOut>                                                               */
 143   /*    driver :: A handle to the driver object.                           */
 144   /*                                                                       */
 145   /*    class  :: A pointer to a class describing the extension.           */
 146   /*                                                                       */
 147   /* <Return>                                                              */
 148   /*    FreeType error code.  0 means success.                             */
 149   /*                                                                       */
 150   FT_EXPORT( FT_Error )
 151   FT_Register_Extension( FT_Driver            driver,
 152                          FT_Extension_Class*  clazz );
 153
 154
 155 #ifdef FT_CONFIG_OPTION_EXTEND_ENGINE
 156
 157
 158   /* Initialize the extension component */
 159   FT_LOCAL FT_Error
 160   FT_Init_Extensions( FT_Library  library );
 161
 162   /* Finalize the extension component */
 163   FT_LOCAL FT_Error
 164   FT_Done_Extensions( FT_Library  library );
 165
 166   /* Create an extension within a face object.  Called by the */
 167   /* face object constructor.                                 */
 168   FT_LOCAL FT_Error
 169   FT_Create_Extensions( FT_Face  face );
 170
 171   /* Destroy all extensions within a face object.  Called by the */
 172   /* face object destructor.                                     */
 173   FT_LOCAL FT_Error
 174   FT_Destroy_Extensions( FT_Face  face );
 175
 176
 177 #endif
 178
 179
 180   /*************************************************************************/
 181   /*                                                                       */
 182   /* <Function>                                                            */
 183   /*    FT_Get_Extension                                                   */
 184   /*                                                                       */
 185   /* <Description>                                                         */
 186   /*    Queries an extension block by an extension ID string.              */
 187   /*                                                                       */
 188   /* <Input>                                                               */
 189   /*    face                :: A handle to the face object.                */
 190   /*    extension_id        :: An ID string identifying the extension.     */
 191   /*                                                                       */
 192   /* <Output>                                                              */
 193   /*    extension_interface :: A generic pointer, usually pointing to a    */
 194   /*                           table of functions implementing the         */
 195   /*                           extension interface.                        */
 196   /*                                                                       */
 197   /* <Return>                                                              */
 198   /*    A generic pointer to the extension block.                          */
 199   /*                                                                       */
 200   FT_EXPORT( void* )
 201   FT_Get_Extension( FT_Face      face,
 202                     const char*  extension_id,
 203                     void**       extension_interface );
 204
 205
 206 FT_END_HEADER
 207
 208 #endif /* __FTEXTEND_H__ */
 209
 210
 211 /* END */