Home | History | Annotate | Download | only in freetype
      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 */
    354