Skip to content

FreeType » Docs » Core API » Glyph Layer Management

Glyph Layer Management


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


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.



The number of glyph layers for the requested glyph index. Will be set by FT_Get_Color_Glyph_Layer.


The current layer. Will be set by FT_Get_Color_Glyph_Layer.


An opaque pointer into ‘COLR’ table data. The caller must set this to NULL before the first call of 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.

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



A handle to the parent face object.


The glyph index the colored glyph layers are associated with.



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.



The glyph index of the current layer.


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.


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.


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


  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,
                                          &iterator );

  if ( palette && have_layers )
      FT_Color  layer_color;

      if ( layer_color_index == 0xFFFF )
        layer_color = text_foreground_color;
        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,
                                        &iterator ) );