/***************************************************************************/

/*                                                                         */

/*  ftincrem.h                                                             */

/*                                                                         */

/*    FreeType incremental loading (specification).                        */

/*                                                                         */

/*  Copyright 2002, 2003, 2006, 2007, 2008, 2010 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 */