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 |
layer |
The current layer. Will be set by |
p |
An opaque pointer into ‘COLR’ table data. The caller must set this to |
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 |
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 |
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 ) );
}