src/third_party/freetype2/src/include/freetype/ftincrem.h

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