lib/freetype/include/freetype/ftincrem.h

   1 /***************************************************************************/
   2 /*                                                                         */
   3 /*  ftincrem.h                                                             */
   4 /*                                                                         */
   5 /*    FreeType incremental loading (specification).                        */
   6 /*                                                                         */
   7 /*  Copyright 2002 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 __FTINCREM_H__
  20 #define __FTINCREM_H__
  21
  22 #include <ft2build.h>
  23 #include FT_FREETYPE_H
  24
  25
  26 FT_BEGIN_HEADER
  27
  28
  29  /***************************************************************************
  30   *
  31   * @type:
  32   *   FT_Incremental
  33   *
  34   * @description:
  35   *   An opaque type describing a user-provided object used to implement
  36   *   "incremental" glyph loading within FreeType.  This is used to support
  37   *   embedded fonts in certain environments (e.g. Postscript interpreters),
  38   *   where the glyph data isn't in the font file, or must be overridden by
  39   *   different values.
  40   *
  41   * @note:
  42   *   It is up to client applications to create and implement @FT_Incremental
  43   *   objects, as long as they provide implementations for the methods
  44   *   @FT_Incremental_GetGlyphDataFunc, @FT_Incremental_FreeGlyphDataFunc
  45   *   and @FT_Incremental_GetGlyphMetricsFunc.
  46   *
  47   *   See the description of @FT_Incremental_InterfaceRec to understand how
  48   *   to use incremental objects with FreeType.
  49   */
  50   typedef struct FT_IncrementalRec_*  FT_Incremental;
  51
  52
  53  /***************************************************************************
  54   *
  55   * @struct:
  56   *   FT_Incremental_Metrics
  57   *
  58   * @description:
  59   *   A small structure used to contain the basic glyph metrics returned
  60   *   by the @FT_Incremental_GetGlyphMetricsFunc method.
  61   *
  62   * @fields:
  63   *   bearing_x ::
  64   *     Left bearing, in font units.
  65   *
  66   *   bearing_y ::
  67   *     Top bearing, in font units.
  68   *
  69   *   advance ::
  70   *     Glyph advance, in font units.
  71   *
  72   * @note:
  73   *   These correspond to horizontal or vertical metrics depending on the
  74   *   value of the 'vertical' argument to the function
  75   *   @FT_Incremental_GetGlyphMetricsFunc.
  76   */
  77   typedef struct  FT_Incremental_MetricsRec_
  78   {
  79     FT_Long  bearing_x;
  80     FT_Long  bearing_y;
  81     FT_Long  advance;
  82
  83   } FT_Incremental_MetricsRec, *FT_Incremental_Metrics;
  84
  85
  86  /***************************************************************************
  87   *
  88   * @type:
  89   *   FT_Incremental_GetGlyphDataFunc
  90   *
  91   * @description:
  92   *   A function called by FreeType to access a given glyph's data bytes
  93   *   during @FT_Load_Glyph or @FT_Load_Char if incremental loading is
  94   *   enabled.
  95   *
  96   *   Note that the format of the glyph's data bytes depends on the font
  97   *   file format.  For TrueType, it must correspond to the raw bytes within
  98   *   the 'glyf' table.  For Postscript formats, it must correspond to the
  99   *   *unencrypted* charstring bytes, without any 'lenIV' header.  It is
 100   *   undefined for any other format.
 101   *
 102   * @input:
 103   *   incremental ::
 104   *     Handle to an opaque @FT_Incremental handle provided by the client
 105   *     application.
 106   *
 107   *   glyph_index ::
 108   *     Index of relevant glyph.
 109   *
 110   * @output:
 111   *   adata ::
 112   *     A structure describing the returned glyph data bytes (which will be
 113   *     accessed as a read-only byte block).
 114   *
 115   * @return:
 116   *   FreeType error code.  0 means success.
 117   *
 118   * @note:
 119   *   If this function returns succesfully the method
 120   *   @FT_Incremental_FreeGlyphDataFunc will be called later to release
 121   *   the data bytes.
 122   *
 123   *   Nested calls to @FT_Incremental_GetGlyphDataFunc can happen for
 124   *   compound glyphs.
 125   */
 126   typedef FT_Error
 127   (*FT_Incremental_GetGlyphDataFunc)( FT_Incremental  incremental,
 128                                       FT_UInt         glyph_index,
 129                                       FT_Data*        adata );
 130
 131
 132  /***************************************************************************
 133   *
 134   * @type:
 135   *   FT_Incremental_FreeGlyphDataFunc
 136   *
 137   * @description:
 138   *   A function used to release the glyph data bytes returned by a
 139   *   successful call to @FT_Incremental_GetGlyphDataFunc.
 140   *
 141   * @input:
 142   *   incremental ::
 143   *     A handle to an opaque @FT_Incremental handle provided by the client
 144   *     application.
 145   *
 146   *   data ::
 147   *     A structure describing the glyph data bytes (which will be accessed
 148   *     as a read-only byte block).
 149   */
 150   typedef void
 151   (*FT_Incremental_FreeGlyphDataFunc)( FT_Incremental  incremental,
 152                                        FT_Data*        data );
 153
 154
 155  /***************************************************************************
 156   *
 157   * @type:
 158   *   FT_Incremental_GetGlyphMetricsFunc
 159   *
 160   * @description:
 161   *   A function used to retrieve the basic metrics of a given glyph index
 162   *   before accessing its data.  This is necessary because, in certain
 163   *   formats like TrueType, the metrics are stored in a different place from
 164   *   the glyph images proper.
 165   *
 166   * @input:
 167   *   incremental ::
 168   *     A handle to an opaque @FT_Incremental handle provided by the client
 169   *     application.
 170   *
 171   *   glyph_index ::
 172   *     Index of relevant glyph.
 173   *
 174   *   vertical ::
 175   *     If true, return vertical metrics.
 176   *
 177   *   ametrics ::
 178   *     This parameter is used for both input and output.
 179   *     The original glyph metrics, if any, in font units.  If metrics are
 180   *     not available all the values must be set to zero.
 181   *
 182   * @output:
 183   *   ametrics ::
 184   *     The replacement glyph metrics in font units.
 185   *
 186   */
 187   typedef FT_Error
 188   (*FT_Incremental_GetGlyphMetricsFunc)
 189                       ( FT_Incremental                   incremental,
 190                         FT_UInt                          glyph_index,
 191                         FT_Bool                          vertical,
 192                         FT_Incremental_MetricsRec        *ametrics );
 193
 194
 195   /**************************************************************************
 196    *
 197    * @struct:
 198    *   FT_Incremental_FuncsRec
 199    *
 200    * @description:
 201    *   A table of functions for accessing fonts that load data
 202    *   incrementally.  Used in @FT_Incremental_Interface.
 203    *
 204    * @fields:
 205    *   get_glyph_data ::
 206    *     The function to get glyph data.  Must not be null.
 207    *
 208    *   free_glyph_data ::
 209    *     The function to release glyph data.  Must not be null.
 210    *
 211    *   get_glyph_metrics ::
 212    *     The function to get glyph metrics.  May be null if the font does
 213    *     not provide overriding glyph metrics.
 214    */
 215   typedef struct  FT_Incremental_FuncsRec_
 216   {
 217     FT_Incremental_GetGlyphDataFunc     get_glyph_data;
 218     FT_Incremental_FreeGlyphDataFunc    free_glyph_data;
 219     FT_Incremental_GetGlyphMetricsFunc  get_glyph_metrics;
 220
 221   } FT_Incremental_FuncsRec;
 222
 223
 224  /***************************************************************************
 225   *
 226   * @struct:
 227   *   FT_Incremental_InterfaceRec
 228   *
 229   * @description:
 230   *   A structure to be used with @FT_Open_Face to indicate that the user
 231   *   wants to support incremental glyph loading.  You should use it with
 232   *   @FT_PARAM_TAG_INCREMENTAL as in the following example:
 233   *
 234   *     {
 235   *       FT_Incremental_InterfaceRec  inc_int;
 236   *       FT_Parameter                 parameter;
 237   *       FT_Open_Args                 open_args;
 238   *
 239   *
 240   *       // set up incremental descriptor
 241   *       inc_int.funcs  = my_funcs;
 242   *       inc_int.object = my_object;
 243   *
 244   *       // set up optional parameter
 245   *       parameter.tag  = FT_PARAM_TAG_INCREMENTAL;
 246   *       parameter.data = &inc_int;
 247   *
 248   *       // set up FT_Open_Args structure
 249   *       open_args.flags      = (FT_Open_Flags)( FT_OPEN_PATHNAME |
 250   *                                               FT_OPEN_PARAMS   );
 251   *       open_args.pathname   = my_font_pathname;
 252   *       open_args.num_params = 1;
 253   *       open_args.params     = &parameter; // we use one optional argument
 254   *
 255   *       // open the font
 256   *       error = FT_Open_Face( library, &open_args, index, &face );
 257   *       ...
 258   *     }
 259   */
 260   typedef struct  FT_Incremental_InterfaceRec_
 261   {
 262     const FT_Incremental_FuncsRec*  funcs;
 263     FT_Incremental                  object;
 264
 265   } FT_Incremental_InterfaceRec;
 266
 267
 268  /***************************************************************************
 269   *
 270   * @constant:
 271   *   FT_PARAM_TAG_INCREMENTAL
 272   *
 273   * @description:
 274   *   A constant used as the tag of @FT_Parameter structures to indicate
 275   *   an incremental loading object to be used by FreeType.
 276   *
 277   */
 278 #define FT_PARAM_TAG_INCREMENTAL  FT_MAKE_TAG( 'i', 'n', 'c', 'r' )
 279
 280  /* */
 281
 282 FT_END_HEADER
 283
 284 #endif /* __FTINCREM_H__ */
 285
 286
 287 /* END */