Skip to content

FreeType » Docs » Support API » Quick retrieval of advance values

# Quick retrieval of advance values

## Synopsis

This section contains functions to quickly extract advance values without handling glyph outlines, if possible.

## FT_Get_Advance

Defined in FT_ADVANCES_H (freetype/ftadvanc.h).

      FT_EXPORT( FT_Error )
      FT_Get_Advance( FT_Face    face,
                      FT_UInt    gindex,
                      FT_Int32   load_flags,
                      FT_Fixed  *padvance );

Retrieve the advance value of a given glyph outline in an `FT_Face`.

#### input

face | The source `FT_Face` handle.
gindex | The glyph index.
load_flags | A set of bit flags similar to those used when calling `FT_Load_Glyph`, used to determine what kind of advances you need.

#### output

padvance | The advance value. If scaling is performed (based on the value of `load_flags`), the advance value is in 16.16 format. Otherwise, it is in font units. If `FT_LOAD_VERTICAL_LAYOUT` is set, this is the vertical advance corresponding to a vertical layout. Otherwise, it is the horizontal advance in a horizontal layout.

#### return

FreeType error code. 0 means success.

#### note

This function may fail if you use `FT_ADVANCE_FLAG_FAST_ONLY` and if the corresponding font backend doesn't have a quick way to retrieve the advances.

A scaled advance is returned in 16.16 format but isn't transformed by the affine transformation specified by `FT_Set_Transform`.

## FT_Get_Advances

Defined in FT_ADVANCES_H (freetype/ftadvanc.h).

      FT_EXPORT( FT_Error )
      FT_Get_Advances( FT_Face    face,
                       FT_UInt    start,
                       FT_UInt    count,
                       FT_Int32   load_flags,
                       FT_Fixed  *padvances );

Retrieve the advance values of several glyph outlines in an `FT_Face`.

#### input

face | The source `FT_Face` handle.
start | The first glyph index.
count | The number of advance values you want to retrieve.
load_flags | A set of bit flags similar to those used when calling `FT_Load_Glyph`.

#### output

padvance

The advance values. This array, to be provided by the caller, must contain at least `count` elements.

If scaling is performed (based on the value of `load_flags`), the advance values are in 16.16 format. Otherwise, they are in font units.

If `FT_LOAD_VERTICAL_LAYOUT` is set, these are the vertical advances corresponding to a vertical layout. Otherwise, they are the horizontal advances in a horizontal layout.

#### return

FreeType error code. 0 means success.

#### note

This function may fail if you use `FT_ADVANCE_FLAG_FAST_ONLY` and if the corresponding font backend doesn't have a quick way to retrieve the advances.

Scaled advances are returned in 16.16 format but aren't transformed by the affine transformation specified by `FT_Set_Transform`.

## FT_ADVANCE_FLAG_FAST_ONLY

Defined in FT_ADVANCES_H (freetype/ftadvanc.h).

    #define FT_ADVANCE_FLAG_FAST_ONLY  0x20000000L

A bit-flag to be OR-ed with the `flags` parameter of the `FT_Get_Advance` and `FT_Get_Advances` functions.

If set, it indicates that you want these functions to fail if the corresponding hinting mode or font driver doesn't allow for very quick advance computation.

Typically, glyphs that are either unscaled, unhinted, bitmapped, or light-hinted can have their advance width computed very quickly.

Normal and bytecode hinted modes that require loading, scaling, and hinting of the glyph outline, are extremely slow by comparison.