Skip to content

FreeType » Docs » Core API » Glyph Layer Management

# Glyph Layer Management

## Synopsis

The functions described here allow access of colored glyph layer data in OpenType's ‘COLR’ tables.

## FT_LayerIterator

Defined in FT_FREETYPE_H (freetype/freetype.h).

      typedef struct  FT_LayerIterator_
      {
        FT_UInt   num_layers;
        FT_UInt   layer;
        FT_Byte*  p;

      } FT_LayerIterator;

This iterator object is needed for `FT_Get_Color_Glyph_Layer`.

#### fields

num_layers | The number of glyph layers for the requested glyph index. Will be set by `FT_Get_Color_Glyph_Layer`.
layer | The current layer. Will be set by `FT_Get_Color_Glyph_Layer`.
p | An opaque pointer into ‘COLR’ table data. The caller must set this to `NULL` before the first call of `FT_Get_Color_Glyph_Layer`.

## FT_Get_Color_Glyph_Layer

Defined in FT_FREETYPE_H (freetype/freetype.h).

      FT_EXPORT( FT_Bool )
      FT_Get_Color_Glyph_Layer( FT_Face            face,
                                FT_UInt            base_glyph,
                                FT_UInt           *aglyph_index,
                                FT_UInt           *acolor_index,
                                FT_LayerIterator*  iterator );

This is an interface to the ‘COLR’ table in OpenType fonts to iteratively retrieve the colored glyph layers associated with the current glyph slot.

https://docs.microsoft.com/en-us/typography/opentype/spec/colr

The glyph layer data for a given glyph index, if present, provides an alternative, multi-colour glyph representation: Instead of rendering the outline or bitmap with the given glyph index, glyphs with the indices and colors returned by this function are rendered layer by layer.

The returned elements are ordered in the z direction from bottom to top; the 'n'th element should be rendered with the associated palette color and blended on top of the already rendered layers (elements 0, 1, ..., n-1).

#### input

face | A handle to the parent face object.
base_glyph | The glyph index the colored glyph layers are associated with.

#### inout

iterator | An `FT_LayerIterator` object. For the first call you should set `iterator->p` to `NULL`. For all following calls, simply use the same object again.

#### output

aglyph_index | The glyph index of the current layer.
acolor_index | The color index into the font face's color palette of the current layer. The value 0xFFFF is special; it doesn't reference a palette entry but indicates that the text foreground color should be used instead (to be set up by the application outside of FreeType).

The color palette can be retrieved with `FT_Palette_Select`.

#### return

Value 1 if everything is OK. If there are no more layers (or if there are no layers at all), value 0 gets returned. In case of an error, value 0 is returned also.

#### note

This function is necessary if you want to handle glyph layers by yourself. In particular, functions that operate with `FT_GlyphRec` objects (like `FT_Get_Glyph` or `FT_Glyph_To_Bitmap`) don't have access to this information.

Note that `FT_Render_Glyph` is able to handle colored glyph layers automatically if the `FT_LOAD_COLOR` flag is passed to a previous call to `FT_Load_Glyph`. [This is an experimental feature.]

#### example

      FT_Color*         palette;
      FT_LayerIterator  iterator;

      FT_Bool  have_layers;
      FT_UInt  layer_glyph_index;
      FT_UInt  layer_color_index;

      error = FT_Palette_Select( face, palette_index, &palette );
      if ( error )
        palette = NULL;

      iterator.p  = NULL;
      have_layers = FT_Get_Color_Glyph_Layer( face,
                                              glyph_index,
                                              &layer_glyph_index,
                                              &layer_color_index,
                                              &iterator );

      if ( palette && have_layers )
      {
        do
        {
          FT_Color  layer_color;

          if ( layer_color_index == 0xFFFF )
            layer_color = text_foreground_color;
          else
            layer_color = palette[layer_color_index];

          // Load and render glyph `layer_glyph_index', then
          // blend resulting pixmap (using color `layer_color')
          // with previously created pixmaps.

        } while ( FT_Get_Color_Glyph_Layer( face,
                                            glyph_index,
                                            &layer_glyph_index,
                                            &layer_color_index,
                                            &iterator ) );
      }