freetype1/lib/ttextend.h

   1 /*******************************************************************
   2  *
   3  *  ttextend.h                                                   2.0
   4  *
   5  *    Extensions Interface.
   6  *
   7  *  Copyright 1996-1999 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  *  This is an updated version of the extension component, now
  17  *  located in the main library's source directory.  It allows
  18  *  the dynamic registration/use of various face object extensions
  19  *  through a simple API.
  20  *
  21  ******************************************************************/
  22
  23 #ifndef TTEXTEND_H
  24 #define TTEXTEND_H
  25
  26 #include "ttconfig.h"
  27 #include "tttypes.h"
  28 #include "ttobjs.h"
  29
  30
  31 #ifdef __cplusplus
  32   extern "C" {
  33 #endif
  34
  35   /* The extensions don't need to be integrated at compile time into */
  36   /* the engine, only at link time.                                  */
  37
  38
  39   /* When a new face object is created, the face constructor calls */
  40   /* the extension constructor with the following arguments:       */
  41   /*                                                               */
  42   /*   ext  : typeless pointer to the face's extension block.      */
  43   /*          Its size is the one given at registration time       */
  44   /*          in the extension class's 'size' field.               */
  45   /*                                                               */
  46   /*   face : the parent face object.  Note that the extension     */
  47   /*          constructor is called when the face object is        */
  48   /*          built.                                               */
  49
  50   typedef TT_Error  TExt_Constructor( void*  ext, PFace  face );
  51
  52
  53   /* When a face object is destroyed, the face destructor calls    */
  54   /* the extension destructor with the following arguments.        */
  55   /*                                                               */
  56   /*   ext  : typeless pointer to the face's extension block.      */
  57   /*          Its size is the one given at registration time       */
  58   /*          in the extension class's 'size' field.               */
  59   /*                                                               */
  60   /*   face : the parent face object.  Note that the extension     */
  61   /*          destructor is called before the actual face object   */
  62   /*          is destroyed.                                        */
  63
  64   typedef TT_Error  TExt_Destructor ( void*  ext, PFace  face );
  65
  66   typedef TExt_Constructor*  PExt_Constructor;
  67   typedef TExt_Destructor*   PExt_Destructor;
  68
  69
  70   struct TExtension_Class_
  71   {
  72     Long              id;      /* extension id                      */
  73     Long              size;    /* size in bytes of extension record */
  74     PExt_Constructor  build;   /* the extension's class constructor */
  75     PExt_Destructor   destroy; /* the extension's class destructor  */
  76
  77     Long              offset;  /* offset of ext. record in face obj */
  78                                /* (set by the engine)               */
  79   };
  80
  81   typedef struct TExtension_Class_  TExtension_Class;
  82   typedef TExtension_Class*         PExtension_Class;
  83
  84
  85 #define Build_Extension_ID( a, b, c, d ) \
  86            ( ((ULong)(a) << 24) |        \
  87              ((ULong)(b) << 16) |        \
  88              ((ULong)(c) << 8 ) |        \
  89               (ULong)(d) )
  90
  91   /*  A note regarding extensions and the single-object compilation    */
  92   /*  mode :                                                           */
  93   /*                                                                   */
  94   /*  When the engine is compiled as a single object file, extensions  */
  95   /*  must remain linkable *after* compile time. In order to do this,  */
  96   /*  we need to export the functions that an extension may need.      */
  97   /*  Fortunately, we can limit ourselves to :                         */
  98   /*                                                                   */
  99   /*  o TT_Register_Extension (previously called Extension_Register)   */
 100   /*        which is to be called by each extension on within          */
 101   /*        it TT_Init_XXXX_Extension initializer.                     */
 102   /*                                                                   */
 103   /*  o File and frame access functions. Fortunately, these already    */
 104   /*    have their names prefixed by "TT_", so no change was needed    */
 105   /*    except replacing the LOCAL_DEF keyword with EXPORT_DEF         */
 106   /*                                                                   */
 107   /*  o Memory access functions, i.e. TT_Alloc and TT_Free. Again,     */
 108   /*    the change is minimal                                          */
 109   /*                                                                   */
 110   /*  o the table-lookup function : TT_LookUp_Table, formerly known    */
 111   /*    as Load_TrueType_Table in ttload.c.                            */
 112   /*                                                                   */
 113   /*                                                                   */
 114   /*  Other than that, an extension should be able to #include all     */
 115   /*  relevant header files to get access to internal types, but       */
 116   /*  should not call engine internal functions..                      */
 117   /*                                                                   */
 118   /*  If there is a need for a specific internal function call, let    */
 119   /*  me known to see if we need to export it by default..             */
 120   /*                                                         - DavidT  */
 121   /*                                                                   */
 122
 123   /* Register a new extension.  Called by extension */
 124   /* service initializers.                          */
 125   EXPORT_DEF
 126   TT_Error  TT_Register_Extension( PEngine_Instance  engine,
 127                                    Long              id,
 128                                    Long              size,
 129                                    PExt_Constructor  create,
 130                                    PExt_Destructor   destroy );
 131
 132
 133 #ifdef TT_CONFIG_OPTION_EXTEND_ENGINE
 134   /* Initialize the extension component */
 135   LOCAL_DEF
 136   TT_Error  TTExtend_Init( PEngine_Instance  engine );
 137
 138   /* Finalize the extension component */
 139   LOCAL_DEF
 140   TT_Error  TTExtend_Done( PEngine_Instance  engine );
 141
 142   /* Create an extension within a face object.  Called by the */
 143   /* face object constructor.                                 */
 144   LOCAL_DEF
 145   TT_Error  Extension_Create( PFace  face );
 146
 147   /* Destroy all extensions within a face object.  Called by the */
 148   /* face object destructor.                                     */
 149   LOCAL_DEF
 150   TT_Error  Extension_Destroy( PFace  face );
 151 #endif
 152
 153   /* Query an extension block by extension_ID.  Called by extension */
 154   /* service routines.                                              */
 155   EXPORT_DEF
 156   TT_Error  TT_Extension_Get( PFace   face,
 157                               Long    extension_id,
 158                               void**  extension_block );
 159
 160 #ifdef __cplusplus
 161   }
 162 #endif
 163
 164
 165 #endif /* TTEXTEND_H */
 166
 167
 168 /* END */