git.sesse.net Git - casparcg/blob - dependencies/SFML-1.6/extlibs/headers/freetype/ftincrem.h

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