Skip to content

FreeType » Docs » Miscellaneous » Incremental Loading

# Incremental Loading

## Synopsis

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.

## FT_Incremental

Defined in FT_INCREMENTAL_H (freetype/ftincrem.h).

      typedef struct FT_IncrementalRec_*  FT_Incremental;

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.

## FT_Incremental_MetricsRec

Defined in FT_INCREMENTAL_H (freetype/ftincrem.h).

      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;

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`.

## FT_Incremental_Metrics

Defined in FT_INCREMENTAL_H (freetype/ftincrem.h).

       typedef struct FT_Incremental_MetricsRec_*  FT_Incremental_Metrics;

A handle to an `FT_Incremental_MetricsRec` structure.

## FT_Incremental_GetGlyphDataFunc

Defined in FT_INCREMENTAL_H (freetype/ftincrem.h).

      typedef FT_Error
      (*FT_Incremental_GetGlyphDataFunc)( FT_Incremental  incremental,
                                          FT_UInt         glyph_index,
                                          FT_Data*        adata );

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.

## FT_Incremental_FreeGlyphDataFunc

Defined in FT_INCREMENTAL_H (freetype/ftincrem.h).

      typedef void
      (*FT_Incremental_FreeGlyphDataFunc)( FT_Incremental  incremental,
                                           FT_Data*        data );

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).

## FT_Incremental_GetGlyphMetricsFunc

Defined in FT_INCREMENTAL_H (freetype/ftincrem.h).

      typedef FT_Error
      (*FT_Incremental_GetGlyphMetricsFunc)
                          ( FT_Incremental              incremental,
                            FT_UInt                     glyph_index,
                            FT_Bool                     vertical,
                            FT_Incremental_MetricsRec  *ametrics );

A function used to retrieve the basic metrics of a given glyph index before accessing its data. This allows for handling font types such as PCL XL Format 1, Class 2 downloaded TrueType fonts, where the glyph metrics (`hmtx` and `vmtx` tables) are permitted to be omitted from the font, and the relevant metrics included in the header of the glyph outline data. Importantly, this is not intended to allow custom glyph metrics (for example, Postscript Metrics dictionaries), because that conflicts with the requirements of outline hinting. Such custom metrics must be handled separately, by the calling application.

#### 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 glyph metrics in font units.

## FT_Incremental_FuncsRec

Defined in FT_INCREMENTAL_H (freetype/ftincrem.h).

      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;

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 require it.

## FT_Incremental_InterfaceRec

Defined in FT_INCREMENTAL_H (freetype/ftincrem.h).

      typedef struct  FT_Incremental_InterfaceRec_
      {
        const FT_Incremental_FuncsRec*  funcs;
        FT_Incremental                  object;

      } FT_Incremental_InterfaceRec;

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 );
      ...

## FT_Incremental_Interface

Defined in FT_INCREMENTAL_H (freetype/ftincrem.h).

      typedef FT_Incremental_InterfaceRec*   FT_Incremental_Interface;

A pointer to an `FT_Incremental_InterfaceRec` structure.