FreeType » Docs » Extended 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_COLOR_H (freetype/ftcolor.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_COLOR_H (freetype/ftcolor.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-color 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 ) );
  }

since

2.10

FT_PaintFormat¶

Defined in FT_COLOR_H (freetype/ftcolor.h).

  typedef enum  FT_PaintFormat_
  {
    FT_COLR_PAINTFORMAT_COLR_LAYERS     = 1,
    FT_COLR_PAINTFORMAT_SOLID           = 2,
    FT_COLR_PAINTFORMAT_LINEAR_GRADIENT = 4,
    FT_COLR_PAINTFORMAT_RADIAL_GRADIENT = 6,
    FT_COLR_PAINTFORMAT_SWEEP_GRADIENT  = 8,
    FT_COLR_PAINTFORMAT_GLYPH           = 10,
    FT_COLR_PAINTFORMAT_COLR_GLYPH      = 11,
    FT_COLR_PAINTFORMAT_TRANSFORM       = 12,
    FT_COLR_PAINTFORMAT_TRANSLATE       = 14,
    FT_COLR_PAINTFORMAT_SCALE           = 16,
    FT_COLR_PAINTFORMAT_ROTATE          = 24,
    FT_COLR_PAINTFORMAT_SKEW            = 28,
    FT_COLR_PAINTFORMAT_COMPOSITE       = 32,
    FT_COLR_PAINT_FORMAT_MAX            = 33,
    FT_COLR_PAINTFORMAT_UNSUPPORTED     = 255

  } FT_PaintFormat;

Enumeration describing the different paint format types of the v1 extensions to the ‘COLR’ table, see ‘https://github.com/googlefonts/colr-gradients-spec’.

The enumeration values loosely correspond with the format numbers of the specification: FreeType always returns a fully specified ‘Paint’ structure for the ‘Transform’, ‘Translate’, ‘Scale’, ‘Rotate’, and ‘Skew’ table types even though the specification has different formats depending on whether or not a center is specified, whether the scale is uniform in x and y direction or not, etc. Also, only non-variable format identifiers are listed in this enumeration; as soon as support for variable ‘COLR’ v1 fonts is implemented, interpolation is performed dependent on axis coordinates, which are configured on the FT_Face through FT_Set_Var_Design_Coordinates. This implies that always static, readily interpolated values are returned in the ‘Paint’ structures.

since

2.13

FT_ColorStopIterator¶

Defined in FT_COLOR_H (freetype/ftcolor.h).

  typedef struct  FT_ColorStopIterator_
  {
    FT_UInt  num_color_stops;
    FT_UInt  current_color_stop;

    FT_Byte*  p;

    FT_Bool  read_variable;

  } FT_ColorStopIterator;

This iterator object is needed for FT_Get_Colorline_Stops. It keeps state while iterating over the stops of an FT_ColorLine, representing the ColorLine struct of the v1 extensions to ‘COLR’, see ‘https://github.com/googlefonts/colr-gradients-spec’. Do not manually modify fields of this iterator.

fields

num_color_stops	The number of color stops for the requested glyph index. Set by `FT_Get_Paint`.
current_color_stop	The current color stop. Set by `FT_Get_Colorline_Stops`.
p	An opaque pointer into ‘COLR’ table data. Set by `FT_Get_Paint`. Updated by `FT_Get_Colorline_Stops`.
read_variable	A boolean keeping track of whether variable color lines are to be read. Set by `FT_Get_Paint`.

since

2.13

FT_ColorIndex¶

Defined in FT_COLOR_H (freetype/ftcolor.h).

  typedef struct  FT_ColorIndex_
  {
    FT_UInt16   palette_index;
    FT_F2Dot14  alpha;

  } FT_ColorIndex;

A structure representing a ColorIndex value of the ‘COLR’ v1 extensions, see ‘https://github.com/googlefonts/colr-gradients-spec’.

fields

palette_index	The palette index into a ‘CPAL’ palette.
alpha	Alpha transparency value multiplied with the value from ‘CPAL’.

since

2.13

FT_ColorStop¶

Defined in FT_COLOR_H (freetype/ftcolor.h).

  typedef struct  FT_ColorStop_
  {
    FT_Fixed       stop_offset;
    FT_ColorIndex  color;

  } FT_ColorStop;

A structure representing a ColorStop value of the ‘COLR’ v1 extensions, see ‘https://github.com/googlefonts/colr-gradients-spec’.

fields

stop_offset	The stop offset along the gradient, expressed as a 16.16 fixed-point coordinate.
color	The color information for this stop, see `FT_ColorIndex`.

since

2.13

FT_PaintExtend¶

Defined in FT_COLOR_H (freetype/ftcolor.h).

  typedef enum  FT_PaintExtend_
  {
    FT_COLR_PAINT_EXTEND_PAD     = 0,
    FT_COLR_PAINT_EXTEND_REPEAT  = 1,
    FT_COLR_PAINT_EXTEND_REFLECT = 2

  } FT_PaintExtend;

An enumeration representing the ‘Extend’ mode of the ‘COLR’ v1 extensions, see ‘https://github.com/googlefonts/colr-gradients-spec’. It describes how the gradient fill continues at the other boundaries.

since

2.13

FT_ColorLine¶

Defined in FT_COLOR_H (freetype/ftcolor.h).

  typedef struct  FT_ColorLine_
  {
    FT_PaintExtend        extend;
    FT_ColorStopIterator  color_stop_iterator;

  } FT_ColorLine;

A structure representing a ColorLine value of the ‘COLR’ v1 extensions, see ‘https://github.com/googlefonts/colr-gradients-spec’. It describes a list of color stops along the defined gradient.

fields

extend	The extend mode at the outer boundaries, see `FT_PaintExtend`.
color_stop_iterator	The `FT_ColorStopIterator` used to enumerate and retrieve the actual `FT_ColorStop`'s.

since

2.13

FT_Affine23¶

Defined in FT_COLOR_H (freetype/ftcolor.h).

  typedef struct  FT_Affine_23_
  {
    FT_Fixed  xx, xy, dx;
    FT_Fixed  yx, yy, dy;

  } FT_Affine23;

A structure used to store a 2x3 matrix. Coefficients are in 16.16 fixed-point format. The computation performed is

  x' = x*xx + y*xy + dx
  y' = x*yx + y*yy + dy

fields

xx	Matrix coefficient.
xy	Matrix coefficient.
dx	x translation.
yx	Matrix coefficient.
yy	Matrix coefficient.
dy	y translation.

since

2.13

FT_Composite_Mode¶

Defined in FT_COLOR_H (freetype/ftcolor.h).

  typedef enum  FT_Composite_Mode_
  {
    FT_COLR_COMPOSITE_CLEAR          = 0,
    FT_COLR_COMPOSITE_SRC            = 1,
    FT_COLR_COMPOSITE_DEST           = 2,
    FT_COLR_COMPOSITE_SRC_OVER       = 3,
    FT_COLR_COMPOSITE_DEST_OVER      = 4,
    FT_COLR_COMPOSITE_SRC_IN         = 5,
    FT_COLR_COMPOSITE_DEST_IN        = 6,
    FT_COLR_COMPOSITE_SRC_OUT        = 7,
    FT_COLR_COMPOSITE_DEST_OUT       = 8,
    FT_COLR_COMPOSITE_SRC_ATOP       = 9,
    FT_COLR_COMPOSITE_DEST_ATOP      = 10,
    FT_COLR_COMPOSITE_XOR            = 11,
    FT_COLR_COMPOSITE_PLUS           = 12,
    FT_COLR_COMPOSITE_SCREEN         = 13,
    FT_COLR_COMPOSITE_OVERLAY        = 14,
    FT_COLR_COMPOSITE_DARKEN         = 15,
    FT_COLR_COMPOSITE_LIGHTEN        = 16,
    FT_COLR_COMPOSITE_COLOR_DODGE    = 17,
    FT_COLR_COMPOSITE_COLOR_BURN     = 18,
    FT_COLR_COMPOSITE_HARD_LIGHT     = 19,
    FT_COLR_COMPOSITE_SOFT_LIGHT     = 20,
    FT_COLR_COMPOSITE_DIFFERENCE     = 21,
    FT_COLR_COMPOSITE_EXCLUSION      = 22,
    FT_COLR_COMPOSITE_MULTIPLY       = 23,
    FT_COLR_COMPOSITE_HSL_HUE        = 24,
    FT_COLR_COMPOSITE_HSL_SATURATION = 25,
    FT_COLR_COMPOSITE_HSL_COLOR      = 26,
    FT_COLR_COMPOSITE_HSL_LUMINOSITY = 27,
    FT_COLR_COMPOSITE_MAX            = 28

  } FT_Composite_Mode;

An enumeration listing the ‘COLR’ v1 composite modes used in FT_PaintComposite. For more details on each paint mode, see ‘https://www.w3.org/TR/compositing-1/#porterduffcompositingoperators’.

since

2.13

FT_OpaquePaint¶

Defined in FT_COLOR_H (freetype/ftcolor.h).

  typedef struct  FT_Opaque_Paint_
  {
    FT_Byte*  p;
    FT_Bool   insert_root_transform;
  } FT_OpaquePaint;

A structure representing an offset to a Paint value stored in any of the paint tables of a ‘COLR’ v1 font. Compare Offset<24> there. When ‘COLR’ v1 paint tables represented by FreeType objects such as FT_PaintColrLayers, FT_PaintComposite, or FT_PaintTransform reference downstream nested paint tables, we do not immediately retrieve them but encapsulate their location in this type. Use FT_Get_Paint to retrieve the actual FT_COLR_Paint object that describes the details of the respective paint table.

fields

p	An internal offset to a Paint table, needs to be set to NULL before passing this struct as an argument to `FT_Get_Paint`.
insert_root_transform	An internal boolean to track whether an initial root transform is to be provided. Do not set this value.

since

2.13

FT_PaintColrLayers¶

Defined in FT_COLOR_H (freetype/ftcolor.h).

  typedef struct  FT_PaintColrLayers_
  {
    FT_LayerIterator  layer_iterator;

  } FT_PaintColrLayers;

A structure representing a PaintColrLayers table of a ‘COLR’ v1 font. This table describes a set of layers that are to be composited with composite mode FT_COLR_COMPOSITE_SRC_OVER. The return value of this function is an FT_LayerIterator initialized so that it can be used with FT_Get_Paint_Layers to retrieve the FT_OpaquePaint objects as references to each layer.

fields

layer_iterator

The layer iterator that describes the layers of this paint.

since

2.13

FT_PaintSolid¶

Defined in FT_COLOR_H (freetype/ftcolor.h).

  typedef struct  FT_PaintSolid_
  {
    FT_ColorIndex  color;

  } FT_PaintSolid;

A structure representing a PaintSolid value of the ‘COLR’ v1 extensions, see ‘https://github.com/googlefonts/colr-gradients-spec’. Using a PaintSolid value means that the glyph layer filled with this paint is solid-colored and does not contain a gradient.

fields

color

The color information for this solid paint, see FT_ColorIndex.

since

2.13

FT_PaintLinearGradient¶

Defined in FT_COLOR_H (freetype/ftcolor.h).

  typedef struct  FT_PaintLinearGradient_
  {
    FT_ColorLine  colorline;

    /* TODO: Potentially expose those as x0, y0 etc. */
    FT_Vector  p0;
    FT_Vector  p1;
    FT_Vector  p2;

  } FT_PaintLinearGradient;

A structure representing a PaintLinearGradient value of the ‘COLR’ v1 extensions, see ‘https://github.com/googlefonts/colr-gradients-spec’. The glyph layer filled with this paint is drawn filled with a linear gradient.

fields

colorline	The `FT_ColorLine` information for this paint, i.e., the list of color stops along the gradient.
p0	The starting point of the gradient definition in font units represented as a 16.16 fixed-point `FT_Vector`.
p1	The end point of the gradient definition in font units represented as a 16.16 fixed-point `FT_Vector`.
p2	Optional point p2 to rotate the gradient in font units represented as a 16.16 fixed-point `FT_Vector`. Otherwise equal to p0.

since

2.13

FT_PaintRadialGradient¶

Defined in FT_COLOR_H (freetype/ftcolor.h).

  typedef struct  FT_PaintRadialGradient_
  {
    FT_ColorLine  colorline;

    FT_Vector  c0;
    FT_Pos     r0;
    FT_Vector  c1;
    FT_Pos     r1;

  } FT_PaintRadialGradient;

A structure representing a PaintRadialGradient value of the ‘COLR’ v1 extensions, see ‘https://github.com/googlefonts/colr-gradients-spec’. The glyph layer filled with this paint is drawn filled with a radial gradient.

fields

colorline	The `FT_ColorLine` information for this paint, i.e., the list of color stops along the gradient.
c0	The center of the starting point of the radial gradient in font units represented as a 16.16 fixed-point `FT_Vector`.
r0	The radius of the starting circle of the radial gradient in font units represented as a 16.16 fixed-point value.
c1	The center of the end point of the radial gradient in font units represented as a 16.16 fixed-point `FT_Vector`.
r1	The radius of the end circle of the radial gradient in font units represented as a 16.16 fixed-point value.

since

2.13

FT_PaintSweepGradient¶

Defined in FT_COLOR_H (freetype/ftcolor.h).

  typedef struct  FT_PaintSweepGradient_
  {
    FT_ColorLine  colorline;

    FT_Vector  center;
    FT_Fixed   start_angle;
    FT_Fixed   end_angle;

  } FT_PaintSweepGradient;

A structure representing a PaintSweepGradient value of the ‘COLR’ v1 extensions, see ‘https://github.com/googlefonts/colr-gradients-spec’. The glyph layer filled with this paint is drawn filled with a sweep gradient from start_angle to end_angle.

fields

colorline	The `FT_ColorLine` information for this paint, i.e., the list of color stops along the gradient.
center	The center of the sweep gradient in font units represented as a vector of 16.16 fixed-point values.
start_angle	The start angle of the sweep gradient in 16.16 fixed-point format specifying degrees divided by 180.0 (as in the spec). Multiply by 180.0f to receive degrees value. Values are given counter-clockwise, starting from the (positive) y axis.
end_angle	The end angle of the sweep gradient in 16.16 fixed-point format specifying degrees divided by 180.0 (as in the spec). Multiply by 180.0f to receive degrees value. Values are given counter-clockwise, starting from the (positive) y axis.

since

2.13

FT_PaintGlyph¶

Defined in FT_COLOR_H (freetype/ftcolor.h).

  typedef struct  FT_PaintGlyph_
  {
    FT_OpaquePaint  paint;
    FT_UInt         glyphID;

  } FT_PaintGlyph;

A structure representing a ‘COLR’ v1 PaintGlyph paint table.

fields

paint	An opaque paint object pointing to a `Paint` table that serves as the fill for the glyph ID.
glyphID	The glyph ID from the ‘glyf’ table, which serves as the contour information that is filled with paint.

since

2.13

FT_PaintColrGlyph¶

Defined in FT_COLOR_H (freetype/ftcolor.h).

  typedef struct  FT_PaintColrGlyph_
  {
    FT_UInt  glyphID;

  } FT_PaintColrGlyph;

A structure representing a ‘COLR’ v1 PaintColorGlyph paint table.

fields

glyphID

The glyph ID from the BaseGlyphV1List table that is drawn for this paint.

since

2.13

FT_PaintTransform¶

Defined in FT_COLOR_H (freetype/ftcolor.h).

  typedef struct  FT_PaintTransform_
  {
    FT_OpaquePaint  paint;
    FT_Affine23     affine;

  } FT_PaintTransform;

A structure representing a ‘COLR’ v1 PaintTransform paint table.

fields

paint	An opaque paint that is subject to being transformed.
affine	A 2x3 transformation matrix in `FT_Affine23` format containing 16.16 fixed-point values.

since

2.13

FT_PaintTranslate¶

Defined in FT_COLOR_H (freetype/ftcolor.h).

  typedef struct  FT_PaintTranslate_
  {
    FT_OpaquePaint  paint;

    FT_Fixed  dx;
    FT_Fixed  dy;

  } FT_PaintTranslate;

A structure representing a ‘COLR’ v1 PaintTranslate paint table. Used for translating downstream paints by a given x and y delta.

fields

paint	An `FT_OpaquePaint` object referencing the paint that is to be rotated.
dx	Translation in x direction in font units represented as a 16.16 fixed-point value.
dy	Translation in y direction in font units represented as a 16.16 fixed-point value.

since

2.13

FT_PaintScale¶

Defined in FT_COLOR_H (freetype/ftcolor.h).

  typedef struct  FT_PaintScale_
  {
    FT_OpaquePaint  paint;

    FT_Fixed  scale_x;
    FT_Fixed  scale_y;

    FT_Fixed  center_x;
    FT_Fixed  center_y;

  } FT_PaintScale;

A structure representing all of the ‘COLR’ v1 ‘PaintScale*’ paint tables. Used for scaling downstream paints by a given x and y scale, with a given center. This structure is used for all ‘PaintScale*’ types that are part of specification; fields of this structure are filled accordingly. If there is a center, the center values are set, otherwise they are set to the zero coordinate. If the source font file has ‘PaintScaleUniform*’ set, the scale values are set accordingly to the same value.

fields

paint	An `FT_OpaquePaint` object referencing the paint that is to be scaled.
scale_x	Scale factor in x direction represented as a 16.16 fixed-point value.
scale_y	Scale factor in y direction represented as a 16.16 fixed-point value.
center_x	x coordinate of center point to scale from represented as a 16.16 fixed-point value.
center_y	y coordinate of center point to scale from represented as a 16.16 fixed-point value.

since

2.13

FT_PaintRotate¶

Defined in FT_COLOR_H (freetype/ftcolor.h).

  typedef struct  FT_PaintRotate_
  {
    FT_OpaquePaint  paint;

    FT_Fixed  angle;

    FT_Fixed  center_x;
    FT_Fixed  center_y;

  } FT_PaintRotate;

A structure representing a ‘COLR’ v1 PaintRotate paint table. Used for rotating downstream paints with a given center and angle.

fields

paint	An `FT_OpaquePaint` object referencing the paint that is to be rotated.
angle	The rotation angle that is to be applied in degrees divided by 180.0 (as in the spec) represented as a 16.16 fixed-point value. Multiply by 180.0f to receive degrees value.
center_x	The x coordinate of the pivot point of the rotation in font units represented as a 16.16 fixed-point value.
center_y	The y coordinate of the pivot point of the rotation in font units represented as a 16.16 fixed-point value.

since

2.13

FT_PaintSkew¶

Defined in FT_COLOR_H (freetype/ftcolor.h).

  typedef struct  FT_PaintSkew_
  {
    FT_OpaquePaint  paint;

    FT_Fixed  x_skew_angle;
    FT_Fixed  y_skew_angle;

    FT_Fixed  center_x;
    FT_Fixed  center_y;

  } FT_PaintSkew;

A structure representing a ‘COLR’ v1 PaintSkew paint table. Used for skewing or shearing downstream paints by a given center and angle.

fields

paint	An `FT_OpaquePaint` object referencing the paint that is to be skewed.
x_skew_angle	The skewing angle in x direction in degrees divided by 180.0 (as in the spec) represented as a 16.16 fixed-point value. Multiply by 180.0f to receive degrees.
y_skew_angle	The skewing angle in y direction in degrees divided by 180.0 (as in the spec) represented as a 16.16 fixed-point value. Multiply by 180.0f to receive degrees.
center_x	The x coordinate of the pivot point of the skew in font units represented as a 16.16 fixed-point value.
center_y	The y coordinate of the pivot point of the skew in font units represented as a 16.16 fixed-point value.

since

2.13

FT_PaintComposite¶

Defined in FT_COLOR_H (freetype/ftcolor.h).

  typedef struct  FT_PaintComposite_
  {
    FT_OpaquePaint     source_paint;
    FT_Composite_Mode  composite_mode;
    FT_OpaquePaint     backdrop_paint;

  } FT_PaintComposite;

A structure representing a ‘COLR’ v1 PaintComposite paint table. Used for compositing two paints in a ‘COLR’ v1 directed acyclic graph.

fields

source_paint	An `FT_OpaquePaint` object referencing the source that is to be composited.
composite_mode	An `FT_Composite_Mode` enum value determining the composition operation.
backdrop_paint	An `FT_OpaquePaint` object referencing the backdrop paint that `source_paint` is composited onto.

since

2.13

FT_COLR_Paint¶

Defined in FT_COLOR_H (freetype/ftcolor.h).

  typedef struct  FT_COLR_Paint_
  {
    FT_PaintFormat format;

    union
    {
      FT_PaintColrLayers      colr_layers;
      FT_PaintGlyph           glyph;
      FT_PaintSolid           solid;
      FT_PaintLinearGradient  linear_gradient;
      FT_PaintRadialGradient  radial_gradient;
      FT_PaintSweepGradient   sweep_gradient;
      FT_PaintTransform       transform;
      FT_PaintTranslate       translate;
      FT_PaintScale           scale;
      FT_PaintRotate          rotate;
      FT_PaintSkew            skew;
      FT_PaintComposite       composite;
      FT_PaintColrGlyph       colr_glyph;

    } u;

  } FT_COLR_Paint;

A union object representing format and details of a paint table of a ‘COLR’ v1 font, see ‘https://github.com/googlefonts/colr-gradients-spec’. Use FT_Get_Paint to retrieve a FT_COLR_Paint for an FT_OpaquePaint object.

fields

format

The gradient format for this Paint structure.

u

Union of all paint table types:

FT_PaintColrLayers FT_PaintGlyph FT_PaintSolid FT_PaintLinearGradient FT_PaintRadialGradient FT_PaintSweepGradient FT_PaintTransform FT_PaintTranslate FT_PaintRotate FT_PaintSkew FT_PaintComposite * FT_PaintColrGlyph

since

2.13

FT_Color_Root_Transform¶

Defined in FT_COLOR_H (freetype/ftcolor.h).

  typedef enum  FT_Color_Root_Transform_
  {
    FT_COLOR_INCLUDE_ROOT_TRANSFORM,
    FT_COLOR_NO_ROOT_TRANSFORM,

    FT_COLOR_ROOT_TRANSFORM_MAX

  } FT_Color_Root_Transform;

An enumeration to specify whether FT_Get_Color_Glyph_Paint is to return a root transform to configure the client's graphics context matrix.

values

FT_COLOR_INCLUDE_ROOT_TRANSFORM	Do include the root transform as the initial `FT_COLR_Paint` object.
FT_COLOR_NO_ROOT_TRANSFORM	Do not output an initial root transform.

since

2.13

FT_ClipBox¶

Defined in FT_COLOR_H (freetype/ftcolor.h).

  typedef struct  FT_ClipBox_
  {
    FT_Vector  bottom_left;
    FT_Vector  top_left;
    FT_Vector  top_right;
    FT_Vector  bottom_right;

  } FT_ClipBox;

A structure representing a ‘COLR’ v1 ‘ClipBox’ table. ‘COLR’ v1 glyphs may optionally define a clip box for aiding allocation or defining a maximum drawable region. Use FT_Get_Color_Glyph_ClipBox to retrieve it.

fields

bottom_left	The bottom left corner of the clip box as an `FT_Vector` with fixed-point coordinates in 26.6 format.
top_left	The top left corner of the clip box as an `FT_Vector` with fixed-point coordinates in 26.6 format.
top_right	The top right corner of the clip box as an `FT_Vector` with fixed-point coordinates in 26.6 format.
bottom_right	The bottom right corner of the clip box as an `FT_Vector` with fixed-point coordinates in 26.6 format.

since

2.13

FT_Get_Color_Glyph_Paint¶

Defined in FT_COLOR_H (freetype/ftcolor.h).

  FT_EXPORT( FT_Bool )
  FT_Get_Color_Glyph_Paint( FT_Face                  face,
                            FT_UInt                  base_glyph,
                            FT_Color_Root_Transform  root_transform,
                            FT_OpaquePaint*          paint );

This is the starting point and interface to color gradient information in a ‘COLR’ v1 table in OpenType fonts to recursively retrieve the paint tables for the directed acyclic graph of a colored glyph, given a glyph ID.

https://github.com/googlefonts/colr-gradients-spec

In a ‘COLR’ v1 font, each color glyph defines a directed acyclic graph of nested paint tables, such as PaintGlyph, PaintSolid, PaintLinearGradient, PaintRadialGradient, and so on. Using this function and specifying a glyph ID, one retrieves the root paint table for this glyph ID.

This function allows control whether an initial root transform is returned to configure scaling, transform, and translation correctly on the client's graphics context. The initial root transform is computed and returned according to the values configured for FT_Size and FT_Set_Transform on the FT_Face object, see below for details of the root_transform parameter. This has implications for a client ‘COLR’ v1 implementation: When this function returns an initially computed root transform, at the time of executing the FT_PaintGlyph operation, the contours should be retrieved using FT_Load_Glyph at unscaled, untransformed size. This is because the root transform applied to the graphics context will take care of correct scaling.

Alternatively, to allow hinting of contours, at the time of executing FT_Load_Glyph, the current graphics context transformation matrix can be decomposed into a scaling matrix and a remainder, and FT_Load_Glyph can be used to retrieve the contours at scaled size. Care must then be taken to blit or clip to the graphics context with taking this remainder transformation into account.

input

face

A handle to the parent face object.

base_glyph

The glyph index for which to retrieve the root paint table.

root_transform

Specifies whether an initially computed root is returned by the FT_PaintTransform operation to account for the activated size (see FT_Activate_Size) and the configured transform and translate (see FT_Set_Transform).

This root transform is returned before nodes of the glyph graph of the font are returned. Subsequent FT_COLR_Paint structures contain unscaled and untransformed values. The inserted root transform enables the client application to apply an initial transform to its graphics context. When executing subsequent FT_COLR_Paint operations, values from FT_COLR_Paint operations will ultimately be correctly scaled because of the root transform applied to the graphics context. Use FT_COLOR_INCLUDE_ROOT_TRANSFORM to include the root transform, use FT_COLOR_NO_ROOT_TRANSFORM to not include it. The latter may be useful when traversing the ‘COLR’ v1 glyph graph and reaching a FT_PaintColrGlyph. When recursing into FT_PaintColrGlyph and painting that inline, no additional root transform is needed as it has already been applied to the graphics context at the beginning of drawing this glyph.

output

paint

The FT_OpaquePaint object that references the actual paint table.

The respective actual FT_COLR_Paint object is retrieved via FT_Get_Paint.

return

Value 1 if everything is OK. If no color glyph is found, or the root paint could not be retrieved, value 0 gets returned. In case of an error, value 0 is returned also.

since

2.13

FT_Get_Color_Glyph_ClipBox¶

Defined in FT_COLOR_H (freetype/ftcolor.h).

  FT_EXPORT( FT_Bool )
  FT_Get_Color_Glyph_ClipBox( FT_Face      face,
                              FT_UInt      base_glyph,
                              FT_ClipBox*  clip_box );

Search for a ‘COLR’ v1 clip box for the specified base_glyph and fill the clip_box parameter with the ‘COLR’ v1 ‘ClipBox’ information if one is found.

input

face	A handle to the parent face object.
base_glyph	The glyph index for which to retrieve the clip box.

output

clip_box

The clip box for the requested base_glyph if one is found. The clip box is computed taking scale and transformations configured on the FT_Face into account. FT_ClipBox contains FT_Vector values in 26.6 format.

return

Value 1 if a clip box is found. If no clip box is found or an error occured, value 0 is returned.

note

To retrieve the clip box in font units, reset scale to units-per-em and remove transforms configured using FT_Set_Transform.

since

2.13

FT_Get_Paint_Layers¶

Defined in FT_COLOR_H (freetype/ftcolor.h).

  FT_EXPORT( FT_Bool )
  FT_Get_Paint_Layers( FT_Face            face,
                       FT_LayerIterator*  iterator,
                       FT_OpaquePaint*    paint );

Access the layers of a PaintColrLayers table.

If the root paint of a color glyph, or a nested paint of a ‘COLR’ glyph is a PaintColrLayers table, this function retrieves the layers of the PaintColrLayers table.

The FT_PaintColrLayers object contains an FT_LayerIterator, which is used here to iterate over the layers. Each layer is returned as an FT_OpaquePaint object, which then can be used with FT_Get_Paint to retrieve the actual paint object.

input

face	A handle to the parent face object.

inout

iterator

The FT_LayerIterator from an FT_PaintColrLayers object, for which the layers are to be retrieved. The internal state of the iterator is incremented after one call to this function for retrieving one layer.

output

paint

The FT_OpaquePaint object that references the actual paint table. The respective actual FT_COLR_Paint object is retrieved via FT_Get_Paint.

return

Value 1 if everything is OK. Value 0 gets returned when the paint object can not be retrieved or any other error occurs.

since

2.13

FT_Get_Colorline_Stops¶

Defined in FT_COLOR_H (freetype/ftcolor.h).

  FT_EXPORT( FT_Bool )
  FT_Get_Colorline_Stops( FT_Face                face,
                          FT_ColorStop*          color_stop,
                          FT_ColorStopIterator*  iterator );

This is an interface to color gradient information in a ‘COLR’ v1 table in OpenType fonts to iteratively retrieve the gradient and solid fill information for colored glyph layers for a specified glyph ID.

https://github.com/googlefonts/colr-gradients-spec

input

face	A handle to the parent face object.

inout

iterator

The retrieved FT_ColorStopIterator, configured on an FT_ColorLine, which in turn got retrieved via paint information in FT_PaintLinearGradient or FT_PaintRadialGradient.

output

color_stop

Color index and alpha value for the retrieved color stop.

return

Value 1 if everything is OK. If there are no more color stops, value 0 gets returned. In case of an error, value 0 is returned also.

since

2.13

FT_Get_Paint¶

Defined in FT_COLOR_H (freetype/ftcolor.h).

  FT_EXPORT( FT_Bool )
  FT_Get_Paint( FT_Face         face,
                FT_OpaquePaint  opaque_paint,
                FT_COLR_Paint*  paint );

Access the details of a paint using an FT_OpaquePaint opaque paint object, which internally stores the offset to the respective Paint object in the ‘COLR’ table.

input

face	A handle to the parent face object.
opaque_paint	The opaque paint object for which the underlying `FT_COLR_Paint` data is to be retrieved.

output

paint

The specific FT_COLR_Paint object containing information coming from one of the font's Paint* tables.

return

Value 1 if everything is OK. Value 0 if no details can be found for this paint or any other error occured.

since

2.13