kc3-lang/freetype/include/ftincrem.h

• Show log

  Commit

• Hash : de43ace7
  Author :
  Date : 2014-12-02T23:06:04
  

  * include/*: Improve structure of documentation. . Add and update many `<Order>' tags. . Apply various documentation fixes. . Remove details to deprecated (or never implemented) data.

Download

• include/ftincrem.h

• /***************************************************************************/
  /*                                                                         */
  /*  ftincrem.h                                                             */
  /*                                                                         */
  /*    FreeType incremental loading (specification).                        */
  /*                                                                         */
  /*  Copyright 2002, 2003, 2006-2008, 2010, 2014 by                         */
  /*  David Turner, Robert Wilhelm, and Werner Lemberg.                      */
  /*                                                                         */
  /*  This file is part of the FreeType project, and may only be used,       */
  /*  modified, and distributed under the terms of the FreeType project      */
  /*  license, LICENSE.TXT.  By continuing to use, modify, or distribute     */
  /*  this file you indicate that you have read the license and              */
  /*  understand and accept it fully.                                        */
  /*                                                                         */
  /***************************************************************************/
  
  
  #ifndef __FTINCREM_H__
  #define __FTINCREM_H__
  
  #include <ft2build.h>
  #include FT_FREETYPE_H
  
  #ifdef FREETYPE_H
  #error "freetype.h of FreeType 1 has been loaded!"
  #error "Please fix the directory search order for header files"
  #error "so that freetype.h of FreeType 2 is found first."
  #endif
  
  
  FT_BEGIN_HEADER
  
    /***************************************************************************
     *
     * @section:
     *    incremental
     *
     * @title:
     *    Incremental Loading
     *
     * @abstract:
     *    Custom Glyph Loading.
     *
     * @description:
     *   This section contains various functions used to perform so-called
     *   `incremental' glyph loading.  This is a mode where all glyphs loaded
     *   from a given @FT_Face are provided by the client application.
     *
     *   Apart from that, all other tables are loaded normally from the font
     *   file.  This mode is useful when FreeType is used within another
     *   engine, e.g., a PostScript Imaging Processor.
     *
     *   To enable this mode, you must use @FT_Open_Face, passing an
     *   @FT_Parameter with the @FT_PARAM_TAG_INCREMENTAL tag and an
     *   @FT_Incremental_Interface value.  See the comments for
     *   @FT_Incremental_InterfaceRec for an example.
     *
     */
  
  
    /***************************************************************************
     *
     * @type:
     *   FT_Incremental
     *
     * @description:
     *   An opaque type describing a user-provided object used to implement
     *   `incremental' glyph loading within FreeType.  This is used to support
     *   embedded fonts in certain environments (e.g., PostScript interpreters),
     *   where the glyph data isn't in the font file, or must be overridden by
     *   different values.
     *
     * @note:
     *   It is up to client applications to create and implement @FT_Incremental
     *   objects, as long as they provide implementations for the methods
     *   @FT_Incremental_GetGlyphDataFunc, @FT_Incremental_FreeGlyphDataFunc
     *   and @FT_Incremental_GetGlyphMetricsFunc.
     *
     *   See the description of @FT_Incremental_InterfaceRec to understand how
     *   to use incremental objects with FreeType.
     *
     */
    typedef struct FT_IncrementalRec_*  FT_Incremental;
  
  
    /***************************************************************************
     *
     * @struct:
     *   FT_Incremental_MetricsRec
     *
     * @description:
     *   A small structure used to contain the basic glyph metrics returned
     *   by the @FT_Incremental_GetGlyphMetricsFunc method.
     *
     * @fields:
     *   bearing_x ::
     *     Left bearing, in font units.
     *
     *   bearing_y ::
     *     Top bearing, in font units.
     *
     *   advance ::
     *     Horizontal component of glyph advance, in font units.
     *
     *   advance_v ::
     *     Vertical component of glyph advance, in font units.
     *
     * @note:
     *   These correspond to horizontal or vertical metrics depending on the
     *   value of the `vertical' argument to the function
     *   @FT_Incremental_GetGlyphMetricsFunc.
     *
     */
    typedef struct  FT_Incremental_MetricsRec_
    {
      FT_Long  bearing_x;
      FT_Long  bearing_y;
      FT_Long  advance;
      FT_Long  advance_v;     /* since 2.3.12 */
  
    } FT_Incremental_MetricsRec;
  
  
    /***************************************************************************
     *
     * @struct:
     *   FT_Incremental_Metrics
     *
     * @description:
     *   A handle to an @FT_Incremental_MetricsRec structure.
     *
     */
     typedef struct FT_Incremental_MetricsRec_*  FT_Incremental_Metrics;
  
  
    /***************************************************************************
     *
     * @type:
     *   FT_Incremental_GetGlyphDataFunc
     *
     * @description:
     *   A function called by FreeType to access a given glyph's data bytes
     *   during @FT_Load_Glyph or @FT_Load_Char if incremental loading is
     *   enabled.
     *
     *   Note that the format of the glyph's data bytes depends on the font
     *   file format.  For TrueType, it must correspond to the raw bytes within
     *   the `glyf' table.  For PostScript formats, it must correspond to the
     *   *unencrypted* charstring bytes, without any `lenIV' header.  It is
     *   undefined for any other format.
     *
     * @input:
     *   incremental ::
     *     Handle to an opaque @FT_Incremental handle provided by the client
     *     application.
     *
     *   glyph_index ::
     *     Index of relevant glyph.
     *
     * @output:
     *   adata ::
     *     A structure describing the returned glyph data bytes (which will be
     *     accessed as a read-only byte block).
     *
     * @return:
     *   FreeType error code.  0~means success.
     *
     * @note:
     *   If this function returns successfully the method
     *   @FT_Incremental_FreeGlyphDataFunc will be called later to release
     *   the data bytes.
     *
     *   Nested calls to @FT_Incremental_GetGlyphDataFunc can happen for
     *   compound glyphs.
     *
     */
    typedef FT_Error
    (*FT_Incremental_GetGlyphDataFunc)( FT_Incremental  incremental,
                                        FT_UInt         glyph_index,
                                        FT_Data*        adata );
  
  
    /***************************************************************************
     *
     * @type:
     *   FT_Incremental_FreeGlyphDataFunc
     *
     * @description:
     *   A function used to release the glyph data bytes returned by a
     *   successful call to @FT_Incremental_GetGlyphDataFunc.
     *
     * @input:
     *   incremental ::
     *     A handle to an opaque @FT_Incremental handle provided by the client
     *     application.
     *
     *   data ::
     *     A structure describing the glyph data bytes (which will be accessed
     *     as a read-only byte block).
     *
     */
    typedef void
    (*FT_Incremental_FreeGlyphDataFunc)( FT_Incremental  incremental,
                                         FT_Data*        data );
  
  
    /***************************************************************************
     *
     * @type:
     *   FT_Incremental_GetGlyphMetricsFunc
     *
     * @description:
     *   A function used to retrieve the basic metrics of a given glyph index
     *   before accessing its data.  This is necessary because, in certain
     *   formats like TrueType, the metrics are stored in a different place from
     *   the glyph images proper.
     *
     * @input:
     *   incremental ::
     *     A handle to an opaque @FT_Incremental handle provided by the client
     *     application.
     *
     *   glyph_index ::
     *     Index of relevant glyph.
     *
     *   vertical ::
     *     If true, return vertical metrics.
     *
     *   ametrics ::
     *     This parameter is used for both input and output.
     *     The original glyph metrics, if any, in font units.  If metrics are
     *     not available all the values must be set to zero.
     *
     * @output:
     *   ametrics ::
     *     The replacement glyph metrics in font units.
     *
     */
    typedef FT_Error
    (*FT_Incremental_GetGlyphMetricsFunc)
                        ( FT_Incremental              incremental,
                          FT_UInt                     glyph_index,
                          FT_Bool                     vertical,
                          FT_Incremental_MetricsRec  *ametrics );
  
  
    /**************************************************************************
     *
     * @struct:
     *   FT_Incremental_FuncsRec
     *
     * @description:
     *   A table of functions for accessing fonts that load data
     *   incrementally.  Used in @FT_Incremental_InterfaceRec.
     *
     * @fields:
     *   get_glyph_data ::
     *     The function to get glyph data.  Must not be null.
     *
     *   free_glyph_data ::
     *     The function to release glyph data.  Must not be null.
     *
     *   get_glyph_metrics ::
     *     The function to get glyph metrics.  May be null if the font does
     *     not provide overriding glyph metrics.
     *
     */
    typedef struct  FT_Incremental_FuncsRec_
    {
      FT_Incremental_GetGlyphDataFunc     get_glyph_data;
      FT_Incremental_FreeGlyphDataFunc    free_glyph_data;
      FT_Incremental_GetGlyphMetricsFunc  get_glyph_metrics;
  
    } FT_Incremental_FuncsRec;
  
  
    /***************************************************************************
     *
     * @struct:
     *   FT_Incremental_InterfaceRec
     *
     * @description:
     *   A structure to be used with @FT_Open_Face to indicate that the user
     *   wants to support incremental glyph loading.  You should use it with
     *   @FT_PARAM_TAG_INCREMENTAL as in the following example:
     *
     *     {
     *       FT_Incremental_InterfaceRec  inc_int;
     *       FT_Parameter                 parameter;
     *       FT_Open_Args                 open_args;
     *
     *
     *       // set up incremental descriptor
     *       inc_int.funcs  = my_funcs;
     *       inc_int.object = my_object;
     *
     *       // set up optional parameter
     *       parameter.tag  = FT_PARAM_TAG_INCREMENTAL;
     *       parameter.data = &inc_int;
     *
     *       // set up FT_Open_Args structure
     *       open_args.flags      = FT_OPEN_PATHNAME | FT_OPEN_PARAMS;
     *       open_args.pathname   = my_font_pathname;
     *       open_args.num_params = 1;
     *       open_args.params     = &parameter; // we use one optional argument
     *
     *       // open the font
     *       error = FT_Open_Face( library, &open_args, index, &face );
     *       ...
     *     }
     *
     */
    typedef struct  FT_Incremental_InterfaceRec_
    {
      const FT_Incremental_FuncsRec*  funcs;
      FT_Incremental                  object;
  
    } FT_Incremental_InterfaceRec;
  
  
    /***************************************************************************
     *
     * @type:
     *   FT_Incremental_Interface
     *
     * @description:
     *   A pointer to an @FT_Incremental_InterfaceRec structure.
     *
     */
    typedef FT_Incremental_InterfaceRec*   FT_Incremental_Interface;
  
  
    /***************************************************************************
     *
     * @constant:
     *   FT_PARAM_TAG_INCREMENTAL
     *
     * @description:
     *   A constant used as the tag of @FT_Parameter structures to indicate
     *   an incremental loading object to be used by FreeType.
     *
     */
  #define FT_PARAM_TAG_INCREMENTAL  FT_MAKE_TAG( 'i', 'n', 'c', 'r' )
  
    /* */
  
  
  FT_END_HEADER
  
  #endif /* __FTINCREM_H__ */
  
  
  /* END */
  

Download