Move 'COLR' API to `ftcolor.h`.

* include/freetype/freetype.h: Cut section layer managament
containing 'COLR' v0 and v1 API and move it to `ftcolor.h` as
requested by Werner on freetype-devel.
* include/freetype/ftcolor.h: Paste that section.

3 files changed, 1247 insertions, 1238 deletions

diff --git a/ChangeLog b/ChangeLog
index d9351d363..e230a0267 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,12 @@
+2021-07-22  Dominik Röttsches  <drott@chromium.org>
+
+	Move 'COLR' API to `ftcolor.h`.
+
+	* include/freetype/freetype.h: Cut section layer managament
+	containing 'COLR' v0 and v1 API and move it to `ftcolor.h` as
+	requested by Werner on freetype-devel.
+	* include/freetype/ftcolor.h: Paste that section.
+
 2021-06-19  Werner Lemberg  <david@freetype.org>
 
 	[truetype] Fix integer overflow.
diff --git a/include/freetype/freetype.h b/include/freetype/freetype.h
index 765685018..da93e814d 100644
--- a/include/freetype/freetype.h
+++ b/include/freetype/freetype.h
@@ -4125,1244 +4125,6 @@ FT_BEGIN_HEADER
   /**************************************************************************
    *
    * @section:
-   *   layer_management
-   *
-   * @title:
-   *   Glyph Layer Management
-   *
-   * @abstract:
-   *   Retrieving and manipulating OpenType's 'COLR' table data.
-   *
-   * @description:
-   *   The functions described here allow access of colored glyph layer data
-   *   in OpenType's 'COLR' tables.
-   */
-
-
-  /**************************************************************************
-   *
-   * @struct:
-   *   FT_LayerIterator
-   *
-   * @description:
-   *   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.
-   */
-  typedef struct  FT_LayerIterator_
-  {
-    FT_UInt   num_layers;
-    FT_UInt   layer;
-    FT_Byte*  p;
-
-  } FT_LayerIterator;
-
-
-  /**************************************************************************
-   *
-   * @function:
-   *   FT_Get_Color_Glyph_Layer
-   *
-   * @description:
-   *   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 ) );
-   *     }
-   *   ```
-   */
-  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 );
-
-
-  /**************************************************************************
-   *
-   * @enum:
-   *   FT_PaintFormat
-   *
-   * @description:
-   *   Enumeration describing the different paint format types of the v1
-   *   extensions to the 'COLR' table, see
-   *   'https://github.com/googlefonts/colr-gradients-spec'.
-   *
-   *   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 (interpolated) values are returned
-   *   for both variable and non-variable formats.
-   *
-   * @since:
-   *   2.11 -- **currently experimental only!**  There might be changes
-   *   without retaining backward-compatibility of both the API and ABI.
-   *
-   */
-  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_TRANSFORMED     = 12,
-    FT_COLR_PAINTFORMAT_TRANSLATE       = 14,
-    FT_COLR_PAINTFORMAT_ROTATE          = 16,
-    FT_COLR_PAINTFORMAT_SKEW            = 18,
-    FT_COLR_PAINTFORMAT_COMPOSITE       = 20,
-    FT_COLR_PAINT_FORMAT_MAX            = 21,
-    FT_COLR_PAINTFORMAT_UNSUPPORTED     = 255
-
-  } FT_PaintFormat;
-
-
-  /**************************************************************************
-   *
-   * @struct:
-   *   FT_ColorStopIterator
-   *
-   * @description:
-   *   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'.
-   *
-   * @fields:
-   *   num_color_stops ::
-   *     The number of color stops for the requested glyph index.  Set by
-   *     @FT_Get_Colorline_Stops.
-   *
-   *   current_color_stop ::
-   *     The current color stop.  Set by @FT_Get_Colorline_Stops.
-   *
-   *   p ::
-   *     An opaque pointer into 'COLR' table data.  The caller must set this
-   *     to `NULL` before the first call of @FT_Get_Colorline_Stops.
-   *
-   * @since:
-   *   2.11 -- **currently experimental only!**  There might be changes
-   *   without retaining backward-compatibility of both the API and ABI.
-   *
-   */
-  typedef struct  FT_ColorStopIterator_
-  {
-    FT_UInt  num_color_stops;
-    FT_UInt  current_color_stop;
-
-    FT_Byte*  p;
-
-  } FT_ColorStopIterator;
-
-
-  /**************************************************************************
-   *
-   * @struct:
-   *   FT_ColorIndex
-   *
-   * @description:
-   *   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.11 -- **currently experimental only!**  There might be changes
-   *   without retaining backward-compatibility of both the API and ABI.
-   *
-   */
-  typedef struct  FT_ColorIndex_
-  {
-    FT_UInt16   palette_index;
-    FT_F2Dot14  alpha;
-
-  } FT_ColorIndex;
-
-
-  /**************************************************************************
-   *
-   * @struct:
-   *   FT_ColorStop
-   *
-   * @description:
-   *   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 between 0 and 1 along the gradient.
-   *
-   *   color ::
-   *     The color information for this stop, see @FT_ColorIndex.
-   *
-   * @since:
-   *   2.11 -- **currently experimental only!**  There might be changes
-   *   without retaining backward-compatibility of both the API and ABI.
-   *
-   */
-  typedef struct  FT_ColorStop_
-  {
-    FT_F2Dot14     stop_offset;
-    FT_ColorIndex  color;
-
-  } FT_ColorStop;
-
-
-  /**************************************************************************
-   *
-   * @enum:
-   *   FT_PaintExtend
-   *
-   * @description:
-   *   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.11 -- **currently experimental only!**  There might be changes
-   *   without retaining backward-compatibility of both the API and ABI.
-   *
-   */
-  typedef enum  FT_PaintExtend_
-  {
-    FT_COLR_PAINT_EXTEND_PAD     = 0,
-    FT_COLR_PAINT_EXTEND_REPEAT  = 1,
-    FT_COLR_PAINT_EXTEND_REFLECT = 2
-
-  } FT_PaintExtend;
-
-
-  /**************************************************************************
-   *
-   * @struct:
-   *   FT_ColorLine
-   *
-   * @description:
-   *   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.11 -- **currently experimental only!**  There might be changes
-   *   without retaining backward-compatibility of both the API and ABI.
-   *
-   */
-  typedef struct  FT_ColorLine_
-  {
-    FT_PaintExtend        extend;
-    FT_ColorStopIterator  color_stop_iterator;
-
-  } FT_ColorLine;
-
-
-  /**************************************************************************
-   *
-   * @struct:
-   *   FT_Affine23
-   *
-   * @description:
-   *   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.11 -- **currently experimental only!**  There might be changes
-   *   without retaining backward-compatibility of both the API and ABI.
-   *
-   */
-  typedef struct  FT_Affine_23_
-  {
-    FT_Fixed  xx, xy, dx;
-    FT_Fixed  yx, yy, dy;
-
-  } FT_Affine23;
-
-
-  /**************************************************************************
-   *
-   * @enum:
-   *   FT_Composite_Mode
-   *
-   * @description:
-   *   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.11 -- **currently experimental only!**  There might be changes
-   *   without retaining backward-compatibility of both the API and ABI.
-   *
-   */
-  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_SCREEN         = 12,
-    FT_COLR_COMPOSITE_OVERLAY        = 13,
-    FT_COLR_COMPOSITE_DARKEN         = 14,
-    FT_COLR_COMPOSITE_LIGHTEN        = 15,
-    FT_COLR_COMPOSITE_COLOR_DODGE    = 16,
-    FT_COLR_COMPOSITE_COLOR_BURN     = 17,
-    FT_COLR_COMPOSITE_HARD_LIGHT     = 18,
-    FT_COLR_COMPOSITE_SOFT_LIGHT     = 19,
-    FT_COLR_COMPOSITE_DIFFERENCE     = 20,
-    FT_COLR_COMPOSITE_EXCLUSION      = 21,
-    FT_COLR_COMPOSITE_MULTIPLY       = 22,
-    FT_COLR_COMPOSITE_HSL_HUE        = 23,
-    FT_COLR_COMPOSITE_HSL_SATURATION = 24,
-    FT_COLR_COMPOSITE_HSL_COLOR      = 25,
-    FT_COLR_COMPOSITE_HSL_LUMINOSITY = 26,
-    FT_COLR_COMPOSITE_MAX            = 27
-
-  } FT_Composite_Mode;
-
-
-  /**************************************************************************
-   *
-   * @struct:
-   *   FT_OpaquePaint
-   *
-   * @description:
-   *   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_PaintTransformed
-   *   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.11 -- **currently experimental only!**  There might be changes
-   *   without retaining backward-compatibility of both the API and ABI.
-   *
-   */
-  typedef struct  FT_Opaque_Paint_
-  {
-    FT_Byte*  p;
-    FT_Bool   insert_root_transform;
-  } FT_OpaquePaint;
-
-
-  /**************************************************************************
-   *
-   * @struct:
-   *   FT_PaintColrLayers
-   *
-   * @description:
-   *   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.11 -- **currently experimental only!**  There might be changes
-   *   without retaining backward-compatibility of both the API and ABI.
-   *
-   */
-  typedef struct  FT_PaintColrLayers_
-  {
-    FT_LayerIterator  layer_iterator;
-
-  } FT_PaintColrLayers;
-
-
-  /**************************************************************************
-   *
-   * @struct:
-   *   FT_PaintSolid
-   *
-   * @description:
-   *   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.11 -- **currently experimental only!**  There might be changes
-   *   without retaining backward-compatibility of both the API and ABI.
-   *
-   */
-  typedef struct  FT_PaintSolid_
-  {
-    FT_ColorIndex  color;
-
-  } FT_PaintSolid;
-
-
-  /**************************************************************************
-   *
-   * @struct:
-   *   FT_PaintLinearGradient
-   *
-   * @description:
-   *   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).
-   *
-   *   p1 ::
-   *     The end point of the gradient definition (in font units).
-   *
-   *   p2 ::
-   *     Optional point~p2 to rotate the gradient (in font units).
-   *     Otherwise equal to~p0.
-   *
-   * @since:
-   *   2.11 -- **currently experimental only!**  There might be changes
-   *   without retaining backward-compatibility of both the API and ABI.
-   *
-   */
-  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;
-
-
-  /**************************************************************************
-   *
-   * @struct:
-   *   FT_PaintRadialGradient
-   *
-   * @description:
-   *   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 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).
-   *
-   *   r0 ::
-   *     The radius of the starting circle of the radial gradient (in font
-   *     units).
-   *
-   *   c1 ::
-   *     The center of the end point of the radial gradient (in font units).
-   *
-   *   r1 ::
-   *     The radius of the end circle of the radial gradient (in font
-   *     units).
-   *
-   * @since:
-   *   2.11 -- **currently experimental only!**  There might be changes
-   *   without retaining backward-compatibility of both the API and ABI.
-   *
-   */
-  typedef struct  FT_PaintRadialGradient_
-  {
-    FT_ColorLine  colorline;
-
-    FT_Vector  c0;
-    FT_UShort  r0;
-    FT_Vector  c1;
-    FT_UShort  r1;
-
-  } FT_PaintRadialGradient;
-
-
-  /**************************************************************************
-   *
-   * @struct:
-   *   FT_PaintSweepGradient
-   *
-   * @description:
-   *   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).
-   *
-   *   start_angle ::
-   *     The start angle of the sweep gradient, in 16.16 fixed point format
-   *     specifying degrees.  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.  Values are given counter-clockwise, starting
-   *     from the (positive) y~axis.
-   *
-   * @since:
-   *   2.11 -- **currently experimental only!**  There might be changes
-   *   without retaining backward-compatibility of both the API and ABI.
-   *
-   */
-  typedef struct  FT_PaintSweepGradient_
-  {
-    FT_ColorLine  colorline;
-
-    FT_Vector  center;
-    FT_Fixed   start_angle;
-    FT_Fixed   end_angle;
-
-  } FT_PaintSweepGradient;
-
-
-  /**************************************************************************
-   *
-   * @struct:
-   *   FT_PaintGlyph
-   *
-   * @description:
-   *   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.11 -- **currently experimental only!**  There might be changes
-   *   without retaining backward-compatibility of both the API and ABI.
-   *
-   */
-  typedef struct  FT_PaintGlyph_
-  {
-    FT_OpaquePaint  paint;
-    FT_UInt         glyphID;
-
-  } FT_PaintGlyph;
-
-
-  /**************************************************************************
-   *
-   * @struct:
-   *   FT_PaintColrGlyph
-   *
-   * @description:
-   *   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.11 -- **currently experimental only!**  There might be changes
-   *   without retaining backward-compatibility of both the API and ABI.
-   *
-   */
-  typedef struct  FT_PaintColrGlyph_
-  {
-    FT_UInt  glyphID;
-
-  } FT_PaintColrGlyph;
-
-
-  /**************************************************************************
-   *
-   * @struct:
-   *   FT_PaintTransformed
-   *
-   * @description:
-   *   A structure representing a 'COLR' v1 `PaintTransformed` paint table.
-   *
-   * @fields:
-   *   paint ::
-   *     An opaque paint that is subject to being transformed.
-   *
-   *   affine ::
-   *     A 2x3 transformation matrix in @FT_Affine23 format.
-   *
-   * @since:
-   *   2.11 -- **currently experimental only!**  There might be changes
-   *   without retaining backward-compatibility of both the API and ABI.
-   *
-   */
-  typedef struct  FT_PaintTransformed_
-  {
-    FT_OpaquePaint  paint;
-    FT_Affine23     affine;
-
-  } FT_PaintTransformed;
-
-
-  /**************************************************************************
-   *
-   * @struct:
-   *   FT_PaintTranslate
-   *
-   * @description:
-   *   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).
-   *
-   *   dy ::
-   *     Translation in y~direction (in font units).
-   *
-   * @since:
-   *   2.11 -- **currently experimental only!**  There might be changes
-   *   without retaining backward-compatibility of both the API and ABI.
-   *
-   */
-  typedef struct  FT_PaintTranslate_
-  {
-    FT_OpaquePaint  paint;
-
-    FT_Fixed  dx;
-    FT_Fixed  dy;
-
-  } FT_PaintTranslate;
-
-
-  /**************************************************************************
-   *
-   * @struct:
-   *   FT_PaintRotate
-   *
-   * @description:
-   *   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.
-   *
-   *   center_x ::
-   *     The x~coordinate of the pivot point of the rotation (in font
-   *     units).
-   *
-   *   center_y ::
-   *     The y~coordinate of the pivot point of the rotation (in font
-   *     units).
-   *
-   * @since:
-   *   2.11 -- **currently experimental only!**  There might be changes
-   *   without retaining backward-compatibility of both the API and ABI.
-   *
-   */
-
-  typedef struct  FT_PaintRotate_
-  {
-    FT_OpaquePaint  paint;
-
-    FT_Fixed  angle;
-
-    FT_Fixed  center_x;
-    FT_Fixed  center_y;
-
-  } FT_PaintRotate;
-
-
-  /**************************************************************************
-   *
-   * @struct:
-   *   FT_PaintSkew
-   *
-   * @description:
-   *   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.
-   *
-   *   y_skew_angle ::
-   *     The skewing angle in y~direction.
-   *
-   *   center_x ::
-   *     The x~coordinate of the pivot point of the skew (in font units).
-   *
-   *   center_y ::
-   *     The y~coordinate of the pivot point of the skew (in font units).
-   *
-   * @since:
-   *   2.11 -- **currently experimental only!**  There might be changes
-   *   without retaining backward-compatibility of both the API and ABI.
-   *
-   */
-  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;
-
-
-  /**************************************************************************
-   *
-   * @struct:
-   *   FT_PaintComposite
-   *
-   * @description:
-   *   A structure representing a 'COLR'v1 `PaintComposite` paint table.
-   *   Used for compositing two paints in a 'COLR' v1 directed acycling
-   *   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.11 -- **currently experimental only!**  There might be changes
-   *   without retaining backward-compatibility of both the API and ABI.
-   *
-   */
-  typedef struct  FT_PaintComposite_
-  {
-    FT_OpaquePaint     source_paint;
-    FT_Composite_Mode  composite_mode;
-    FT_OpaquePaint     backdrop_paint;
-
-  } FT_PaintComposite;
-
-
-  /**************************************************************************
-   *
-   * @union:
-   *   FT_COLR_Paint
-   *
-   * @description:
-   *   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_PaintTransformed
-   *       * @FT_PaintTranslate
-   *       * @FT_PaintRotate
-   *       * @FT_PaintSkew
-   *       * @FT_PaintComposite
-   *       * @FT_PaintColrGlyph
-   *
-   * @since:
-   *   2.11 -- **currently experimental only!**  There might be changes
-   *   without retaining backward-compatibility of both the API and ABI.
-   *
-   */
-  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_PaintTransformed     transformed;
-      FT_PaintTranslate       translate;
-      FT_PaintRotate          rotate;
-      FT_PaintSkew            skew;
-      FT_PaintComposite       composite;
-      FT_PaintColrGlyph       colr_glyph;
-
-    } u;
-
-  } FT_COLR_Paint;
-
-
-  /**************************************************************************
-   *
-   * @enum:
-   *   FT_Color_Root_Transform
-   *
-   * @description:
-   *   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.11 -- **currently experimental only!**  There might be changes
-   *   without retaining backward-compatibility of both the API and ABI.
-   *
-   */
-  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;
-
-
-  /**************************************************************************
-   *
-   * @function:
-   *   FT_Get_Color_Glyph_Paint
-   *
-   * @description:
-   *   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_PaintTransformed 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.11 -- **currently experimental only!**  There might be changes
-   *   without retaining backward-compatibility of both the API and ABI.
-   *
-   */
-  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 );
-
-
-  /**************************************************************************
-   *
-   * @function:
-   *   FT_Get_Paint_Layers
-   *
-   * @description:
-   *   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.11 -- **currently experimental only!**  There might be changes
-   *   without retaining backward-compatibility of both the API and ABI.
-   *
-   */
-  FT_EXPORT( FT_Bool )
-  FT_Get_Paint_Layers( FT_Face            face,
-                       FT_LayerIterator*  iterator,
-                       FT_OpaquePaint*    paint );
-
-
-  /**************************************************************************
-   *
-   * @function:
-   *   FT_Get_Colorline_Stops
-   *
-   * @description:
-   *   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.11 -- **currently experimental only!**  There might be changes
-   *   without retaining backward-compatibility of both the API and ABI.
-   *
-   */
-  FT_EXPORT( FT_Bool )
-  FT_Get_Colorline_Stops( FT_Face                face,
-                          FT_ColorStop*          color_stop,
-                          FT_ColorStopIterator*  iterator );
-
-
-  /**************************************************************************
-   *
-   * @function:
-   *  FT_Get_Paint
-   *
-   * @description:
-   *   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.11 -- **currently experimental only!**  There might be changes
-   *   without retaining backward-compatibility of both the API and ABI.
-   *
-   */
-  FT_EXPORT( FT_Bool )
-  FT_Get_Paint( FT_Face         face,
-                FT_OpaquePaint  opaque_paint,
-                FT_COLR_Paint*  paint );
-
-
-  /**************************************************************************
-   *
-   * @section:
    *   base_interface
    *
    */
diff --git a/include/freetype/ftcolor.h b/include/freetype/ftcolor.h
index 6bc5d9457..676d6ce38 100644
--- a/include/freetype/ftcolor.h
+++ b/include/freetype/ftcolor.h
@@ -302,6 +302,1244 @@ FT_BEGIN_HEADER
   FT_Palette_Set_Foreground_Color( FT_Face   face,
                                    FT_Color  foreground_color );
 
+
+  /**************************************************************************
+   *
+   * @section:
+   *   layer_management
+   *
+   * @title:
+   *   Glyph Layer Management
+   *
+   * @abstract:
+   *   Retrieving and manipulating OpenType's 'COLR' table data.
+   *
+   * @description:
+   *   The functions described here allow access of colored glyph layer data
+   *   in OpenType's 'COLR' tables.
+   */
+
+
+  /**************************************************************************
+   *
+   * @struct:
+   *   FT_LayerIterator
+   *
+   * @description:
+   *   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.
+   */
+  typedef struct  FT_LayerIterator_
+  {
+    FT_UInt   num_layers;
+    FT_UInt   layer;
+    FT_Byte*  p;
+
+  } FT_LayerIterator;
+
+
+  /**************************************************************************
+   *
+   * @function:
+   *   FT_Get_Color_Glyph_Layer
+   *
+   * @description:
+   *   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 ) );
+   *     }
+   *   ```
+   */
+  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 );
+
+
+  /**************************************************************************
+   *
+   * @enum:
+   *   FT_PaintFormat
+   *
+   * @description:
+   *   Enumeration describing the different paint format types of the v1
+   *   extensions to the 'COLR' table, see
+   *   'https://github.com/googlefonts/colr-gradients-spec'.
+   *
+   *   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 (interpolated) values are returned
+   *   for both variable and non-variable formats.
+   *
+   * @since:
+   *   2.11 -- **currently experimental only!**  There might be changes
+   *   without retaining backward-compatibility of both the API and ABI.
+   *
+   */
+  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_TRANSFORMED     = 12,
+    FT_COLR_PAINTFORMAT_TRANSLATE       = 14,
+    FT_COLR_PAINTFORMAT_ROTATE          = 16,
+    FT_COLR_PAINTFORMAT_SKEW            = 18,
+    FT_COLR_PAINTFORMAT_COMPOSITE       = 20,
+    FT_COLR_PAINT_FORMAT_MAX            = 21,
+    FT_COLR_PAINTFORMAT_UNSUPPORTED     = 255
+
+  } FT_PaintFormat;
+
+
+  /**************************************************************************
+   *
+   * @struct:
+   *   FT_ColorStopIterator
+   *
+   * @description:
+   *   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'.
+   *
+   * @fields:
+   *   num_color_stops ::
+   *     The number of color stops for the requested glyph index.  Set by
+   *     @FT_Get_Colorline_Stops.
+   *
+   *   current_color_stop ::
+   *     The current color stop.  Set by @FT_Get_Colorline_Stops.
+   *
+   *   p ::
+   *     An opaque pointer into 'COLR' table data.  The caller must set this
+   *     to `NULL` before the first call of @FT_Get_Colorline_Stops.
+   *
+   * @since:
+   *   2.11 -- **currently experimental only!**  There might be changes
+   *   without retaining backward-compatibility of both the API and ABI.
+   *
+   */
+  typedef struct  FT_ColorStopIterator_
+  {
+    FT_UInt  num_color_stops;
+    FT_UInt  current_color_stop;
+
+    FT_Byte*  p;
+
+  } FT_ColorStopIterator;
+
+
+  /**************************************************************************
+   *
+   * @struct:
+   *   FT_ColorIndex
+   *
+   * @description:
+   *   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.11 -- **currently experimental only!**  There might be changes
+   *   without retaining backward-compatibility of both the API and ABI.
+   *
+   */
+  typedef struct  FT_ColorIndex_
+  {
+    FT_UInt16   palette_index;
+    FT_F2Dot14  alpha;
+
+  } FT_ColorIndex;
+
+
+  /**************************************************************************
+   *
+   * @struct:
+   *   FT_ColorStop
+   *
+   * @description:
+   *   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 between 0 and 1 along the gradient.
+   *
+   *   color ::
+   *     The color information for this stop, see @FT_ColorIndex.
+   *
+   * @since:
+   *   2.11 -- **currently experimental only!**  There might be changes
+   *   without retaining backward-compatibility of both the API and ABI.
+   *
+   */
+  typedef struct  FT_ColorStop_
+  {
+    FT_F2Dot14     stop_offset;
+    FT_ColorIndex  color;
+
+  } FT_ColorStop;
+
+
+  /**************************************************************************
+   *
+   * @enum:
+   *   FT_PaintExtend
+   *
+   * @description:
+   *   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.11 -- **currently experimental only!**  There might be changes
+   *   without retaining backward-compatibility of both the API and ABI.
+   *
+   */
+  typedef enum  FT_PaintExtend_
+  {
+    FT_COLR_PAINT_EXTEND_PAD     = 0,
+    FT_COLR_PAINT_EXTEND_REPEAT  = 1,
+    FT_COLR_PAINT_EXTEND_REFLECT = 2
+
+  } FT_PaintExtend;
+
+
+  /**************************************************************************
+   *
+   * @struct:
+   *   FT_ColorLine
+   *
+   * @description:
+   *   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.11 -- **currently experimental only!**  There might be changes
+   *   without retaining backward-compatibility of both the API and ABI.
+   *
+   */
+  typedef struct  FT_ColorLine_
+  {
+    FT_PaintExtend        extend;
+    FT_ColorStopIterator  color_stop_iterator;
+
+  } FT_ColorLine;
+
+
+  /**************************************************************************
+   *
+   * @struct:
+   *   FT_Affine23
+   *
+   * @description:
+   *   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.11 -- **currently experimental only!**  There might be changes
+   *   without retaining backward-compatibility of both the API and ABI.
+   *
+   */
+  typedef struct  FT_Affine_23_
+  {
+    FT_Fixed  xx, xy, dx;
+    FT_Fixed  yx, yy, dy;
+
+  } FT_Affine23;
+
+
+  /**************************************************************************
+   *
+   * @enum:
+   *   FT_Composite_Mode
+   *
+   * @description:
+   *   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.11 -- **currently experimental only!**  There might be changes
+   *   without retaining backward-compatibility of both the API and ABI.
+   *
+   */
+  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_SCREEN         = 12,
+    FT_COLR_COMPOSITE_OVERLAY        = 13,
+    FT_COLR_COMPOSITE_DARKEN         = 14,
+    FT_COLR_COMPOSITE_LIGHTEN        = 15,
+    FT_COLR_COMPOSITE_COLOR_DODGE    = 16,
+    FT_COLR_COMPOSITE_COLOR_BURN     = 17,
+    FT_COLR_COMPOSITE_HARD_LIGHT     = 18,
+    FT_COLR_COMPOSITE_SOFT_LIGHT     = 19,
+    FT_COLR_COMPOSITE_DIFFERENCE     = 20,
+    FT_COLR_COMPOSITE_EXCLUSION      = 21,
+    FT_COLR_COMPOSITE_MULTIPLY       = 22,
+    FT_COLR_COMPOSITE_HSL_HUE        = 23,
+    FT_COLR_COMPOSITE_HSL_SATURATION = 24,
+    FT_COLR_COMPOSITE_HSL_COLOR      = 25,
+    FT_COLR_COMPOSITE_HSL_LUMINOSITY = 26,
+    FT_COLR_COMPOSITE_MAX            = 27
+
+  } FT_Composite_Mode;
+
+
+  /**************************************************************************
+   *
+   * @struct:
+   *   FT_OpaquePaint
+   *
+   * @description:
+   *   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_PaintTransformed
+   *   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.11 -- **currently experimental only!**  There might be changes
+   *   without retaining backward-compatibility of both the API and ABI.
+   *
+   */
+  typedef struct  FT_Opaque_Paint_
+  {
+    FT_Byte*  p;
+    FT_Bool   insert_root_transform;
+  } FT_OpaquePaint;
+
+
+  /**************************************************************************
+   *
+   * @struct:
+   *   FT_PaintColrLayers
+   *
+   * @description:
+   *   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.11 -- **currently experimental only!**  There might be changes
+   *   without retaining backward-compatibility of both the API and ABI.
+   *
+   */
+  typedef struct  FT_PaintColrLayers_
+  {
+    FT_LayerIterator  layer_iterator;
+
+  } FT_PaintColrLayers;
+
+
+  /**************************************************************************
+   *
+   * @struct:
+   *   FT_PaintSolid
+   *
+   * @description:
+   *   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.11 -- **currently experimental only!**  There might be changes
+   *   without retaining backward-compatibility of both the API and ABI.
+   *
+   */
+  typedef struct  FT_PaintSolid_
+  {
+    FT_ColorIndex  color;
+
+  } FT_PaintSolid;
+
+
+  /**************************************************************************
+   *
+   * @struct:
+   *   FT_PaintLinearGradient
+   *
+   * @description:
+   *   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).
+   *
+   *   p1 ::
+   *     The end point of the gradient definition (in font units).
+   *
+   *   p2 ::
+   *     Optional point~p2 to rotate the gradient (in font units).
+   *     Otherwise equal to~p0.
+   *
+   * @since:
+   *   2.11 -- **currently experimental only!**  There might be changes
+   *   without retaining backward-compatibility of both the API and ABI.
+   *
+   */
+  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;
+
+
+  /**************************************************************************
+   *
+   * @struct:
+   *   FT_PaintRadialGradient
+   *
+   * @description:
+   *   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 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).
+   *
+   *   r0 ::
+   *     The radius of the starting circle of the radial gradient (in font
+   *     units).
+   *
+   *   c1 ::
+   *     The center of the end point of the radial gradient (in font units).
+   *
+   *   r1 ::
+   *     The radius of the end circle of the radial gradient (in font
+   *     units).
+   *
+   * @since:
+   *   2.11 -- **currently experimental only!**  There might be changes
+   *   without retaining backward-compatibility of both the API and ABI.
+   *
+   */
+  typedef struct  FT_PaintRadialGradient_
+  {
+    FT_ColorLine  colorline;
+
+    FT_Vector  c0;
+    FT_UShort  r0;
+    FT_Vector  c1;
+    FT_UShort  r1;
+
+  } FT_PaintRadialGradient;
+
+
+  /**************************************************************************
+   *
+   * @struct:
+   *   FT_PaintSweepGradient
+   *
+   * @description:
+   *   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).
+   *
+   *   start_angle ::
+   *     The start angle of the sweep gradient, in 16.16 fixed point format
+   *     specifying degrees.  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.  Values are given counter-clockwise, starting
+   *     from the (positive) y~axis.
+   *
+   * @since:
+   *   2.11 -- **currently experimental only!**  There might be changes
+   *   without retaining backward-compatibility of both the API and ABI.
+   *
+   */
+  typedef struct  FT_PaintSweepGradient_
+  {
+    FT_ColorLine  colorline;
+
+    FT_Vector  center;
+    FT_Fixed   start_angle;
+    FT_Fixed   end_angle;
+
+  } FT_PaintSweepGradient;
+
+
+  /**************************************************************************
+   *
+   * @struct:
+   *   FT_PaintGlyph
+   *
+   * @description:
+   *   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.11 -- **currently experimental only!**  There might be changes
+   *   without retaining backward-compatibility of both the API and ABI.
+   *
+   */
+  typedef struct  FT_PaintGlyph_
+  {
+    FT_OpaquePaint  paint;
+    FT_UInt         glyphID;
+
+  } FT_PaintGlyph;
+
+
+  /**************************************************************************
+   *
+   * @struct:
+   *   FT_PaintColrGlyph
+   *
+   * @description:
+   *   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.11 -- **currently experimental only!**  There might be changes
+   *   without retaining backward-compatibility of both the API and ABI.
+   *
+   */
+  typedef struct  FT_PaintColrGlyph_
+  {
+    FT_UInt  glyphID;
+
+  } FT_PaintColrGlyph;
+
+
+  /**************************************************************************
+   *
+   * @struct:
+   *   FT_PaintTransformed
+   *
+   * @description:
+   *   A structure representing a 'COLR' v1 `PaintTransformed` paint table.
+   *
+   * @fields:
+   *   paint ::
+   *     An opaque paint that is subject to being transformed.
+   *
+   *   affine ::
+   *     A 2x3 transformation matrix in @FT_Affine23 format.
+   *
+   * @since:
+   *   2.11 -- **currently experimental only!**  There might be changes
+   *   without retaining backward-compatibility of both the API and ABI.
+   *
+   */
+  typedef struct  FT_PaintTransformed_
+  {
+    FT_OpaquePaint  paint;
+    FT_Affine23     affine;
+
+  } FT_PaintTransformed;
+
+
+  /**************************************************************************
+   *
+   * @struct:
+   *   FT_PaintTranslate
+   *
+   * @description:
+   *   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).
+   *
+   *   dy ::
+   *     Translation in y~direction (in font units).
+   *
+   * @since:
+   *   2.11 -- **currently experimental only!**  There might be changes
+   *   without retaining backward-compatibility of both the API and ABI.
+   *
+   */
+  typedef struct  FT_PaintTranslate_
+  {
+    FT_OpaquePaint  paint;
+
+    FT_Fixed  dx;
+    FT_Fixed  dy;
+
+  } FT_PaintTranslate;
+
+
+  /**************************************************************************
+   *
+   * @struct:
+   *   FT_PaintRotate
+   *
+   * @description:
+   *   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.
+   *
+   *   center_x ::
+   *     The x~coordinate of the pivot point of the rotation (in font
+   *     units).
+   *
+   *   center_y ::
+   *     The y~coordinate of the pivot point of the rotation (in font
+   *     units).
+   *
+   * @since:
+   *   2.11 -- **currently experimental only!**  There might be changes
+   *   without retaining backward-compatibility of both the API and ABI.
+   *
+   */
+
+  typedef struct  FT_PaintRotate_
+  {
+    FT_OpaquePaint  paint;
+
+    FT_Fixed  angle;
+
+    FT_Fixed  center_x;
+    FT_Fixed  center_y;
+
+  } FT_PaintRotate;
+
+
+  /**************************************************************************
+   *
+   * @struct:
+   *   FT_PaintSkew
+   *
+   * @description:
+   *   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.
+   *
+   *   y_skew_angle ::
+   *     The skewing angle in y~direction.
+   *
+   *   center_x ::
+   *     The x~coordinate of the pivot point of the skew (in font units).
+   *
+   *   center_y ::
+   *     The y~coordinate of the pivot point of the skew (in font units).
+   *
+   * @since:
+   *   2.11 -- **currently experimental only!**  There might be changes
+   *   without retaining backward-compatibility of both the API and ABI.
+   *
+   */
+  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;
+
+
+  /**************************************************************************
+   *
+   * @struct:
+   *   FT_PaintComposite
+   *
+   * @description:
+   *   A structure representing a 'COLR'v1 `PaintComposite` paint table.
+   *   Used for compositing two paints in a 'COLR' v1 directed acycling
+   *   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.11 -- **currently experimental only!**  There might be changes
+   *   without retaining backward-compatibility of both the API and ABI.
+   *
+   */
+  typedef struct  FT_PaintComposite_
+  {
+    FT_OpaquePaint     source_paint;
+    FT_Composite_Mode  composite_mode;
+    FT_OpaquePaint     backdrop_paint;
+
+  } FT_PaintComposite;
+
+
+  /**************************************************************************
+   *
+   * @union:
+   *   FT_COLR_Paint
+   *
+   * @description:
+   *   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_PaintTransformed
+   *       * @FT_PaintTranslate
+   *       * @FT_PaintRotate
+   *       * @FT_PaintSkew
+   *       * @FT_PaintComposite
+   *       * @FT_PaintColrGlyph
+   *
+   * @since:
+   *   2.11 -- **currently experimental only!**  There might be changes
+   *   without retaining backward-compatibility of both the API and ABI.
+   *
+   */
+  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_PaintTransformed     transformed;
+      FT_PaintTranslate       translate;
+      FT_PaintRotate          rotate;
+      FT_PaintSkew            skew;
+      FT_PaintComposite       composite;
+      FT_PaintColrGlyph       colr_glyph;
+
+    } u;
+
+  } FT_COLR_Paint;
+
+
+  /**************************************************************************
+   *
+   * @enum:
+   *   FT_Color_Root_Transform
+   *
+   * @description:
+   *   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.11 -- **currently experimental only!**  There might be changes
+   *   without retaining backward-compatibility of both the API and ABI.
+   *
+   */
+  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;
+
+
+  /**************************************************************************
+   *
+   * @function:
+   *   FT_Get_Color_Glyph_Paint
+   *
+   * @description:
+   *   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_PaintTransformed 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.11 -- **currently experimental only!**  There might be changes
+   *   without retaining backward-compatibility of both the API and ABI.
+   *
+   */
+  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 );
+
+
+  /**************************************************************************
+   *
+   * @function:
+   *   FT_Get_Paint_Layers
+   *
+   * @description:
+   *   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.11 -- **currently experimental only!**  There might be changes
+   *   without retaining backward-compatibility of both the API and ABI.
+   *
+   */
+  FT_EXPORT( FT_Bool )
+  FT_Get_Paint_Layers( FT_Face            face,
+                       FT_LayerIterator*  iterator,
+                       FT_OpaquePaint*    paint );
+
+
+  /**************************************************************************
+   *
+   * @function:
+   *   FT_Get_Colorline_Stops
+   *
+   * @description:
+   *   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.11 -- **currently experimental only!**  There might be changes
+   *   without retaining backward-compatibility of both the API and ABI.
+   *
+   */
+  FT_EXPORT( FT_Bool )
+  FT_Get_Colorline_Stops( FT_Face                face,
+                          FT_ColorStop*          color_stop,
+                          FT_ColorStopIterator*  iterator );
+
+
+  /**************************************************************************
+   *
+   * @function:
+   *  FT_Get_Paint
+   *
+   * @description:
+   *   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.11 -- **currently experimental only!**  There might be changes
+   *   without retaining backward-compatibility of both the API and ABI.
+   *
+   */
+  FT_EXPORT( FT_Bool )
+  FT_Get_Paint( FT_Face         face,
+                FT_OpaquePaint  opaque_paint,
+                FT_COLR_Paint*  paint );
+
   /* */