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.

FT_Render_Glyph, however, handles colored glyph layers automatically if the FT_LOAD_COLOR flag is passed to it.

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