include/freetype/ftcolor.h

   1 /****************************************************************************
   2  *
   3  * ftcolor.h
   4  *
   5  *   FreeType's glyph color management (specification).
   6  *
   7  * Copyright (C) 2018-2023 by
   8  * David Turner, Robert Wilhelm, and Werner Lemberg.
   9  *
  10  * This file is part of the FreeType project, and may only be used,
  11  * modified, and distributed under the terms of the FreeType project
  12  * license, LICENSE.TXT.  By continuing to use, modify, or distribute
  13  * this file you indicate that you have read the license and
  14  * understand and accept it fully.
  15  *
  16  */
  17
  18
  19 #ifndef FTCOLOR_H_
  20 #define FTCOLOR_H_
  21
  22 #include <freetype/freetype.h>
  23
  24 #ifdef FREETYPE_H
  25 #error "freetype.h of FreeType 1 has been loaded!"
  26 #error "Please fix the directory search order for header files"
  27 #error "so that freetype.h of FreeType 2 is found first."
  28 #endif
  29
  30
  31 FT_BEGIN_HEADER
  32
  33
  34   /**************************************************************************
  35    *
  36    * @section:
  37    *   color_management
  38    *
  39    * @title:
  40    *   Glyph Color Management
  41    *
  42    * @abstract:
  43    *   Retrieving and manipulating OpenType's 'CPAL' table data.
  44    *
  45    * @description:
  46    *   The functions described here allow access and manipulation of color
  47    *   palette entries in OpenType's 'CPAL' tables.
  48    */
  49
  50
  51   /**************************************************************************
  52    *
  53    * @struct:
  54    *   FT_Color
  55    *
  56    * @description:
  57    *   This structure models a BGRA color value of a 'CPAL' palette entry.
  58    *
  59    *   The used color space is sRGB; the colors are not pre-multiplied, and
  60    *   alpha values must be explicitly set.
  61    *
  62    * @fields:
  63    *   blue ::
  64    *     Blue value.
  65    *
  66    *   green ::
  67    *     Green value.
  68    *
  69    *   red ::
  70    *     Red value.
  71    *
  72    *   alpha ::
  73    *     Alpha value, giving the red, green, and blue color's opacity.
  74    *
  75    * @since:
  76    *   2.10
  77    */
  78   typedef struct  FT_Color_
  79   {
  80     FT_Byte  blue;
  81     FT_Byte  green;
  82     FT_Byte  red;
  83     FT_Byte  alpha;
  84
  85   } FT_Color;
  86
  87
  88   /**************************************************************************
  89    *
  90    * @enum:
  91    *   FT_PALETTE_XXX
  92    *
  93    * @description:
  94    *   A list of bit field constants used in the `palette_flags` array of the
  95    *   @FT_Palette_Data structure to indicate for which background a palette
  96    *   with a given index is usable.
  97    *
  98    * @values:
  99    *   FT_PALETTE_FOR_LIGHT_BACKGROUND ::
 100    *     The palette is appropriate to use when displaying the font on a
 101    *     light background such as white.
 102    *
 103    *   FT_PALETTE_FOR_DARK_BACKGROUND ::
 104    *     The palette is appropriate to use when displaying the font on a dark
 105    *     background such as black.
 106    *
 107    * @since:
 108    *   2.10
 109    */
 110 #define FT_PALETTE_FOR_LIGHT_BACKGROUND  0x01
 111 #define FT_PALETTE_FOR_DARK_BACKGROUND   0x02
 112
 113
 114   /**************************************************************************
 115    *
 116    * @struct:
 117    *   FT_Palette_Data
 118    *
 119    * @description:
 120    *   This structure holds the data of the 'CPAL' table.
 121    *
 122    * @fields:
 123    *   num_palettes ::
 124    *     The number of palettes.
 125    *
 126    *   palette_name_ids ::
 127    *     An optional read-only array of palette name IDs with `num_palettes`
 128    *     elements, corresponding to entries like 'dark' or 'light' in the
 129    *     font's 'name' table.
 130    *
 131    *     An empty name ID in the 'CPAL' table gets represented as value
 132    *     0xFFFF.
 133    *
 134    *     `NULL` if the font's 'CPAL' table doesn't contain appropriate data.
 135    *
 136    *   palette_flags ::
 137    *     An optional read-only array of palette flags with `num_palettes`
 138    *     elements.  Possible values are an ORed combination of
 139    *     @FT_PALETTE_FOR_LIGHT_BACKGROUND and
 140    *     @FT_PALETTE_FOR_DARK_BACKGROUND.
 141    *
 142    *     `NULL` if the font's 'CPAL' table doesn't contain appropriate data.
 143    *
 144    *   num_palette_entries ::
 145    *     The number of entries in a single palette.  All palettes have the
 146    *     same size.
 147    *
 148    *   palette_entry_name_ids ::
 149    *     An optional read-only array of palette entry name IDs with
 150    *     `num_palette_entries`.  In each palette, entries with the same index
 151    *     have the same function.  For example, index~0 might correspond to
 152    *     string 'outline' in the font's 'name' table to indicate that this
 153    *     palette entry is used for outlines, index~1 might correspond to
 154    *     'fill' to indicate the filling color palette entry, etc.
 155    *
 156    *     An empty entry name ID in the 'CPAL' table gets represented as value
 157    *     0xFFFF.
 158    *
 159    *     `NULL` if the font's 'CPAL' table doesn't contain appropriate data.
 160    *
 161    * @note:
 162    *   Use function @FT_Get_Sfnt_Name to map name IDs and entry name IDs to
 163    *   name strings.
 164    *
 165    *   Use function @FT_Palette_Select to get the colors associated with a
 166    *   palette entry.
 167    *
 168    * @since:
 169    *   2.10
 170    */
 171   typedef struct  FT_Palette_Data_ {
 172     FT_UShort         num_palettes;
 173     const FT_UShort*  palette_name_ids;
 174     const FT_UShort*  palette_flags;
 175
 176     FT_UShort         num_palette_entries;
 177     const FT_UShort*  palette_entry_name_ids;
 178
 179   } FT_Palette_Data;
 180
 181
 182   /**************************************************************************
 183    *
 184    * @function:
 185    *   FT_Palette_Data_Get
 186    *
 187    * @description:
 188    *   Retrieve the face's color palette data.
 189    *
 190    * @input:
 191    *   face ::
 192    *     The source face handle.
 193    *
 194    * @output:
 195    *   apalette ::
 196    *     A pointer to an @FT_Palette_Data structure.
 197    *
 198    * @return:
 199    *   FreeType error code.  0~means success.
 200    *
 201    * @note:
 202    *   All arrays in the returned @FT_Palette_Data structure are read-only.
 203    *
 204    *   This function always returns an error if the config macro
 205    *   `TT_CONFIG_OPTION_COLOR_LAYERS` is not defined in `ftoption.h`.
 206    *
 207    * @since:
 208    *   2.10
 209    */
 210   FT_EXPORT( FT_Error )
 211   FT_Palette_Data_Get( FT_Face           face,
 212                        FT_Palette_Data  *apalette );
 213
 214
 215   /**************************************************************************
 216    *
 217    * @function:
 218    *   FT_Palette_Select
 219    *
 220    * @description:
 221    *   This function has two purposes.
 222    *
 223    *   (1) It activates a palette for rendering color glyphs, and
 224    *
 225    *   (2) it retrieves all (unmodified) color entries of this palette.  This
 226    *       function returns a read-write array, which means that a calling
 227    *       application can modify the palette entries on demand.
 228    *
 229    * A corollary of (2) is that calling the function, then modifying some
 230    * values, then calling the function again with the same arguments resets
 231    * all color entries to the original 'CPAL' values; all user modifications
 232    * are lost.
 233    *
 234    * @input:
 235    *   face ::
 236    *     The source face handle.
 237    *
 238    *   palette_index ::
 239    *     The palette index.
 240    *
 241    * @output:
 242    *   apalette ::
 243    *     An array of color entries for a palette with index `palette_index`,
 244    *     having `num_palette_entries` elements (as found in the
 245    *     `FT_Palette_Data` structure).  If `apalette` is set to `NULL`, no
 246    *     array gets returned (and no color entries can be modified).
 247    *
 248    *     In case the font doesn't support color palettes, `NULL` is returned.
 249    *
 250    * @return:
 251    *   FreeType error code.  0~means success.
 252    *
 253    * @note:
 254    *   The array pointed to by `apalette_entries` is owned and managed by
 255    *   FreeType.
 256    *
 257    *   This function always returns an error if the config macro
 258    *   `TT_CONFIG_OPTION_COLOR_LAYERS` is not defined in `ftoption.h`.
 259    *
 260    * @since:
 261    *   2.10
 262    */
 263   FT_EXPORT( FT_Error )
 264   FT_Palette_Select( FT_Face     face,
 265                      FT_UShort   palette_index,
 266                      FT_Color*  *apalette );
 267
 268
 269   /**************************************************************************
 270    *
 271    * @function:
 272    *   FT_Palette_Set_Foreground_Color
 273    *
 274    * @description:
 275    *   'COLR' uses palette index 0xFFFF to indicate a 'text foreground
 276    *   color'.  This function sets this value.
 277    *
 278    * @input:
 279    *   face ::
 280    *     The source face handle.
 281    *
 282    *   foreground_color ::
 283    *     An `FT_Color` structure to define the text foreground color.
 284    *
 285    * @return:
 286    *   FreeType error code.  0~means success.
 287    *
 288    * @note:
 289    *   If this function isn't called, the text foreground color is set to
 290    *   white opaque (BGRA value 0xFFFFFFFF) if
 291    *   @FT_PALETTE_FOR_DARK_BACKGROUND is present for the current palette,
 292    *   and black opaque (BGRA value 0x000000FF) otherwise, including the case
 293    *   that no palette types are available in the 'CPAL' table.
 294    *
 295    *   This function always returns an error if the config macro
 296    *   `TT_CONFIG_OPTION_COLOR_LAYERS` is not defined in `ftoption.h`.
 297    *
 298    * @since:
 299    *   2.10
 300    */
 301   FT_EXPORT( FT_Error )
 302   FT_Palette_Set_Foreground_Color( FT_Face   face,
 303                                    FT_Color  foreground_color );
 304
 305
 306   /**************************************************************************
 307    *
 308    * @section:
 309    *   layer_management
 310    *
 311    * @title:
 312    *   Glyph Layer Management
 313    *
 314    * @abstract:
 315    *   Retrieving and manipulating OpenType's 'COLR' table data.
 316    *
 317    * @description:
 318    *   The functions described here allow access of colored glyph layer data
 319    *   in OpenType's 'COLR' tables.
 320    */
 321
 322
 323   /**************************************************************************
 324    *
 325    * @struct:
 326    *   FT_LayerIterator
 327    *
 328    * @description:
 329    *   This iterator object is needed for @FT_Get_Color_Glyph_Layer.
 330    *
 331    * @fields:
 332    *   num_layers ::
 333    *     The number of glyph layers for the requested glyph index.  Will be
 334    *     set by @FT_Get_Color_Glyph_Layer.
 335    *
 336    *   layer ::
 337    *     The current layer.  Will be set by @FT_Get_Color_Glyph_Layer.
 338    *
 339    *   p ::
 340    *     An opaque pointer into 'COLR' table data.  The caller must set this
 341    *     to `NULL` before the first call of @FT_Get_Color_Glyph_Layer.
 342    */
 343   typedef struct  FT_LayerIterator_
 344   {
 345     FT_UInt   num_layers;
 346     FT_UInt   layer;
 347     FT_Byte*  p;
 348
 349   } FT_LayerIterator;
 350
 351
 352   /**************************************************************************
 353    *
 354    * @function:
 355    *   FT_Get_Color_Glyph_Layer
 356    *
 357    * @description:
 358    *   This is an interface to the 'COLR' table in OpenType fonts to
 359    *   iteratively retrieve the colored glyph layers associated with the
 360    *   current glyph slot.
 361    *
 362    *     https://docs.microsoft.com/en-us/typography/opentype/spec/colr
 363    *
 364    *   The glyph layer data for a given glyph index, if present, provides an
 365    *   alternative, multi-color glyph representation: Instead of rendering
 366    *   the outline or bitmap with the given glyph index, glyphs with the
 367    *   indices and colors returned by this function are rendered layer by
 368    *   layer.
 369    *
 370    *   The returned elements are ordered in the z~direction from bottom to
 371    *   top; the 'n'th element should be rendered with the associated palette
 372    *   color and blended on top of the already rendered layers (elements 0,
 373    *   1, ..., n-1).
 374    *
 375    * @input:
 376    *   face ::
 377    *     A handle to the parent face object.
 378    *
 379    *   base_glyph ::
 380    *     The glyph index the colored glyph layers are associated with.
 381    *
 382    * @inout:
 383    *   iterator ::
 384    *     An @FT_LayerIterator object.  For the first call you should set
 385    *     `iterator->p` to `NULL`.  For all following calls, simply use the
 386    *     same object again.
 387    *
 388    * @output:
 389    *   aglyph_index ::
 390    *     The glyph index of the current layer.
 391    *
 392    *   acolor_index ::
 393    *     The color index into the font face's color palette of the current
 394    *     layer.  The value 0xFFFF is special; it doesn't reference a palette
 395    *     entry but indicates that the text foreground color should be used
 396    *     instead (to be set up by the application outside of FreeType).
 397    *
 398    *     The color palette can be retrieved with @FT_Palette_Select.
 399    *
 400    * @return:
 401    *   Value~1 if everything is OK.  If there are no more layers (or if there
 402    *   are no layers at all), value~0 gets returned.  In case of an error,
 403    *   value~0 is returned also.
 404    *
 405    * @note:
 406    *   This function is necessary if you want to handle glyph layers by
 407    *   yourself.  In particular, functions that operate with @FT_GlyphRec
 408    *   objects (like @FT_Get_Glyph or @FT_Glyph_To_Bitmap) don't have access
 409    *   to this information.
 410    *
 411    *   Note that @FT_Render_Glyph is able to handle colored glyph layers
 412    *   automatically if the @FT_LOAD_COLOR flag is passed to a previous call
 413    *   to @FT_Load_Glyph.  [This is an experimental feature.]
 414    *
 415    * @example:
 416    *   ```
 417    *     FT_Color*         palette;
 418    *     FT_LayerIterator  iterator;
 419    *
 420    *     FT_Bool  have_layers;
 421    *     FT_UInt  layer_glyph_index;
 422    *     FT_UInt  layer_color_index;
 423    *
 424    *
 425    *     error = FT_Palette_Select( face, palette_index, &palette );
 426    *     if ( error )
 427    *       palette = NULL;
 428    *
 429    *     iterator.p  = NULL;
 430    *     have_layers = FT_Get_Color_Glyph_Layer( face,
 431    *                                             glyph_index,
 432    *                                             &layer_glyph_index,
 433    *                                             &layer_color_index,
 434    *                                             &iterator );
 435    *
 436    *     if ( palette && have_layers )
 437    *     {
 438    *       do
 439    *       {
 440    *         FT_Color  layer_color;
 441    *
 442    *
 443    *         if ( layer_color_index == 0xFFFF )
 444    *           layer_color = text_foreground_color;
 445    *         else
 446    *           layer_color = palette[layer_color_index];
 447    *
 448    *         // Load and render glyph `layer_glyph_index', then
 449    *         // blend resulting pixmap (using color `layer_color')
 450    *         // with previously created pixmaps.
 451    *
 452    *       } while ( FT_Get_Color_Glyph_Layer( face,
 453    *                                           glyph_index,
 454    *                                           &layer_glyph_index,
 455    *                                           &layer_color_index,
 456    *                                           &iterator ) );
 457    *     }
 458    *   ```
 459    *
 460    * @since:
 461    *   2.10
 462    */
 463   FT_EXPORT( FT_Bool )
 464   FT_Get_Color_Glyph_Layer( FT_Face            face,
 465                             FT_UInt            base_glyph,
 466                             FT_UInt           *aglyph_index,
 467                             FT_UInt           *acolor_index,
 468                             FT_LayerIterator*  iterator );
 469
 470
 471   /**************************************************************************
 472    *
 473    * @enum:
 474    *   FT_PaintFormat
 475    *
 476    * @description:
 477    *   Enumeration describing the different paint format types of the v1
 478    *   extensions to the 'COLR' table, see
 479    *   'https://github.com/googlefonts/colr-gradients-spec'.
 480    *
 481    *   The enumeration values loosely correspond with the format numbers of
 482    *   the specification: FreeType always returns a fully specified 'Paint'
 483    *   structure for the 'Transform', 'Translate', 'Scale', 'Rotate', and
 484    *   'Skew' table types even though the specification has different formats
 485    *   depending on whether or not a center is specified, whether the scale
 486    *   is uniform in x and y~direction or not, etc.  Also, only non-variable
 487    *   format identifiers are listed in this enumeration; as soon as support
 488    *   for variable 'COLR' v1 fonts is implemented, interpolation is
 489    *   performed dependent on axis coordinates, which are configured on the
 490    *   @FT_Face through @FT_Set_Var_Design_Coordinates.  This implies that
 491    *   always static, readily interpolated values are returned in the 'Paint'
 492    *   structures.
 493    *
 494    * @since:
 495    *   2.13
 496    */
 497   typedef enum  FT_PaintFormat_
 498   {
 499     FT_COLR_PAINTFORMAT_COLR_LAYERS     = 1,
 500     FT_COLR_PAINTFORMAT_SOLID           = 2,
 501     FT_COLR_PAINTFORMAT_LINEAR_GRADIENT = 4,
 502     FT_COLR_PAINTFORMAT_RADIAL_GRADIENT = 6,
 503     FT_COLR_PAINTFORMAT_SWEEP_GRADIENT  = 8,
 504     FT_COLR_PAINTFORMAT_GLYPH           = 10,
 505     FT_COLR_PAINTFORMAT_COLR_GLYPH      = 11,
 506     FT_COLR_PAINTFORMAT_TRANSFORM       = 12,
 507     FT_COLR_PAINTFORMAT_TRANSLATE       = 14,
 508     FT_COLR_PAINTFORMAT_SCALE           = 16,
 509     FT_COLR_PAINTFORMAT_ROTATE          = 24,
 510     FT_COLR_PAINTFORMAT_SKEW            = 28,
 511     FT_COLR_PAINTFORMAT_COMPOSITE       = 32,
 512     FT_COLR_PAINT_FORMAT_MAX            = 33,
 513     FT_COLR_PAINTFORMAT_UNSUPPORTED     = 255
 514
 515   } FT_PaintFormat;
 516
 517
 518   /**************************************************************************
 519    *
 520    * @struct:
 521    *   FT_ColorStopIterator
 522    *
 523    * @description:
 524    *   This iterator object is needed for @FT_Get_Colorline_Stops.  It keeps
 525    *   state while iterating over the stops of an @FT_ColorLine, representing
 526    *   the `ColorLine` struct of the v1 extensions to 'COLR', see
 527    *   'https://github.com/googlefonts/colr-gradients-spec'.  Do not manually
 528    *   modify fields of this iterator.
 529    *
 530    * @fields:
 531    *   num_color_stops ::
 532    *     The number of color stops for the requested glyph index.  Set by
 533    *     @FT_Get_Paint.
 534    *
 535    *   current_color_stop ::
 536    *     The current color stop.  Set by @FT_Get_Colorline_Stops.
 537    *
 538    *   p ::
 539    *     An opaque pointer into 'COLR' table data.  Set by @FT_Get_Paint.
 540    *     Updated by @FT_Get_Colorline_Stops.
 541    *
 542    *   read_variable ::
 543    *     A boolean keeping track of whether variable color lines are to be
 544    *     read.  Set by @FT_Get_Paint.
 545    *
 546    * @since:
 547    *   2.13
 548    */
 549   typedef struct  FT_ColorStopIterator_
 550   {
 551     FT_UInt  num_color_stops;
 552     FT_UInt  current_color_stop;
 553
 554     FT_Byte*  p;
 555
 556     FT_Bool  read_variable;
 557
 558   } FT_ColorStopIterator;
 559
 560
 561   /**************************************************************************
 562    *
 563    * @struct:
 564    *   FT_ColorIndex
 565    *
 566    * @description:
 567    *   A structure representing a `ColorIndex` value of the 'COLR' v1
 568    *   extensions, see 'https://github.com/googlefonts/colr-gradients-spec'.
 569    *
 570    * @fields:
 571    *   palette_index ::
 572    *     The palette index into a 'CPAL' palette.
 573    *
 574    *   alpha ::
 575    *     Alpha transparency value multiplied with the value from 'CPAL'.
 576    *
 577    * @since:
 578    *   2.13
 579    */
 580   typedef struct  FT_ColorIndex_
 581   {
 582     FT_UInt16   palette_index;
 583     FT_F2Dot14  alpha;
 584
 585   } FT_ColorIndex;
 586
 587
 588   /**************************************************************************
 589    *
 590    * @struct:
 591    *   FT_ColorStop
 592    *
 593    * @description:
 594    *   A structure representing a `ColorStop` value of the 'COLR' v1
 595    *   extensions, see 'https://github.com/googlefonts/colr-gradients-spec'.
 596    *
 597    * @fields:
 598    *   stop_offset ::
 599    *     The stop offset along the gradient, expressed as a 16.16 fixed-point
 600    *     coordinate.
 601    *
 602    *   color ::
 603    *     The color information for this stop, see @FT_ColorIndex.
 604    *
 605    * @since:
 606    *   2.13
 607    */
 608   typedef struct  FT_ColorStop_
 609   {
 610     FT_Fixed       stop_offset;
 611     FT_ColorIndex  color;
 612
 613   } FT_ColorStop;
 614
 615
 616   /**************************************************************************
 617    *
 618    * @enum:
 619    *   FT_PaintExtend
 620    *
 621    * @description:
 622    *   An enumeration representing the 'Extend' mode of the 'COLR' v1
 623    *   extensions, see 'https://github.com/googlefonts/colr-gradients-spec'.
 624    *   It describes how the gradient fill continues at the other boundaries.
 625    *
 626    * @since:
 627    *   2.13
 628    */
 629   typedef enum  FT_PaintExtend_
 630   {
 631     FT_COLR_PAINT_EXTEND_PAD     = 0,
 632     FT_COLR_PAINT_EXTEND_REPEAT  = 1,
 633     FT_COLR_PAINT_EXTEND_REFLECT = 2
 634
 635   } FT_PaintExtend;
 636
 637
 638   /**************************************************************************
 639    *
 640    * @struct:
 641    *   FT_ColorLine
 642    *
 643    * @description:
 644    *   A structure representing a `ColorLine` value of the 'COLR' v1
 645    *   extensions, see 'https://github.com/googlefonts/colr-gradients-spec'.
 646    *   It describes a list of color stops along the defined gradient.
 647    *
 648    * @fields:
 649    *   extend ::
 650    *     The extend mode at the outer boundaries, see @FT_PaintExtend.
 651    *
 652    *   color_stop_iterator ::
 653    *     The @FT_ColorStopIterator used to enumerate and retrieve the
 654    *     actual @FT_ColorStop's.
 655    *
 656    * @since:
 657    *   2.13
 658    */
 659   typedef struct  FT_ColorLine_
 660   {
 661     FT_PaintExtend        extend;
 662     FT_ColorStopIterator  color_stop_iterator;
 663
 664   } FT_ColorLine;
 665
 666
 667   /**************************************************************************
 668    *
 669    * @struct:
 670    *   FT_Affine23
 671    *
 672    * @description:
 673    *   A structure used to store a 2x3 matrix.  Coefficients are in
 674    *   16.16 fixed-point format.  The computation performed is
 675    *
 676    *   ```
 677    *     x' = x*xx + y*xy + dx
 678    *     y' = x*yx + y*yy + dy
 679    *   ```
 680    *
 681    * @fields:
 682    *   xx ::
 683    *     Matrix coefficient.
 684    *
 685    *   xy ::
 686    *     Matrix coefficient.
 687    *
 688    *   dx ::
 689    *     x translation.
 690    *
 691    *   yx ::
 692    *     Matrix coefficient.
 693    *
 694    *   yy ::
 695    *     Matrix coefficient.
 696    *
 697    *   dy ::
 698    *     y translation.
 699    *
 700    * @since:
 701    *   2.13
 702    */
 703   typedef struct  FT_Affine_23_
 704   {
 705     FT_Fixed  xx, xy, dx;
 706     FT_Fixed  yx, yy, dy;
 707
 708   } FT_Affine23;
 709
 710
 711   /**************************************************************************
 712    *
 713    * @enum:
 714    *   FT_Composite_Mode
 715    *
 716    * @description:
 717    *   An enumeration listing the 'COLR' v1 composite modes used in
 718    *   @FT_PaintComposite.  For more details on each paint mode, see
 719    *   'https://www.w3.org/TR/compositing-1/#porterduffcompositingoperators'.
 720    *
 721    * @since:
 722    *   2.13
 723    */
 724   typedef enum  FT_Composite_Mode_
 725   {
 726     FT_COLR_COMPOSITE_CLEAR          = 0,
 727     FT_COLR_COMPOSITE_SRC            = 1,
 728     FT_COLR_COMPOSITE_DEST           = 2,
 729     FT_COLR_COMPOSITE_SRC_OVER       = 3,
 730     FT_COLR_COMPOSITE_DEST_OVER      = 4,
 731     FT_COLR_COMPOSITE_SRC_IN         = 5,
 732     FT_COLR_COMPOSITE_DEST_IN        = 6,
 733     FT_COLR_COMPOSITE_SRC_OUT        = 7,
 734     FT_COLR_COMPOSITE_DEST_OUT       = 8,
 735     FT_COLR_COMPOSITE_SRC_ATOP       = 9,
 736     FT_COLR_COMPOSITE_DEST_ATOP      = 10,
 737     FT_COLR_COMPOSITE_XOR            = 11,
 738     FT_COLR_COMPOSITE_PLUS           = 12,
 739     FT_COLR_COMPOSITE_SCREEN         = 13,
 740     FT_COLR_COMPOSITE_OVERLAY        = 14,
 741     FT_COLR_COMPOSITE_DARKEN         = 15,
 742     FT_COLR_COMPOSITE_LIGHTEN        = 16,
 743     FT_COLR_COMPOSITE_COLOR_DODGE    = 17,
 744     FT_COLR_COMPOSITE_COLOR_BURN     = 18,
 745     FT_COLR_COMPOSITE_HARD_LIGHT     = 19,
 746     FT_COLR_COMPOSITE_SOFT_LIGHT     = 20,
 747     FT_COLR_COMPOSITE_DIFFERENCE     = 21,
 748     FT_COLR_COMPOSITE_EXCLUSION      = 22,
 749     FT_COLR_COMPOSITE_MULTIPLY       = 23,
 750     FT_COLR_COMPOSITE_HSL_HUE        = 24,
 751     FT_COLR_COMPOSITE_HSL_SATURATION = 25,
 752     FT_COLR_COMPOSITE_HSL_COLOR      = 26,
 753     FT_COLR_COMPOSITE_HSL_LUMINOSITY = 27,
 754     FT_COLR_COMPOSITE_MAX            = 28
 755
 756   } FT_Composite_Mode;
 757
 758
 759   /**************************************************************************
 760    *
 761    * @struct:
 762    *   FT_OpaquePaint
 763    *
 764    * @description:
 765    *   A structure representing an offset to a `Paint` value stored in any
 766    *   of the paint tables of a 'COLR' v1 font.  Compare Offset<24> there.
 767    *   When 'COLR' v1 paint tables represented by FreeType objects such as
 768    *   @FT_PaintColrLayers, @FT_PaintComposite, or @FT_PaintTransform
 769    *   reference downstream nested paint tables, we do not immediately
 770    *   retrieve them but encapsulate their location in this type.  Use
 771    *   @FT_Get_Paint to retrieve the actual @FT_COLR_Paint object that
 772    *   describes the details of the respective paint table.
 773    *
 774    * @fields:
 775    *   p ::
 776    *     An internal offset to a Paint table, needs to be set to NULL before
 777    *     passing this struct as an argument to @FT_Get_Paint.
 778    *
 779    *   insert_root_transform ::
 780    *     An internal boolean to track whether an initial root transform is
 781    *     to be provided.  Do not set this value.
 782    *
 783    * @since:
 784    *   2.13
 785    */
 786   typedef struct  FT_Opaque_Paint_
 787   {
 788     FT_Byte*  p;
 789     FT_Bool   insert_root_transform;
 790   } FT_OpaquePaint;
 791
 792
 793   /**************************************************************************
 794    *
 795    * @struct:
 796    *   FT_PaintColrLayers
 797    *
 798    * @description:
 799    *   A structure representing a `PaintColrLayers` table of a 'COLR' v1
 800    *   font.  This table describes a set of layers that are to be composited
 801    *   with composite mode `FT_COLR_COMPOSITE_SRC_OVER`.  The return value
 802    *   of this function is an @FT_LayerIterator initialized so that it can
 803    *   be used with @FT_Get_Paint_Layers to retrieve the @FT_OpaquePaint
 804    *   objects as references to each layer.
 805    *
 806    * @fields:
 807    *   layer_iterator ::
 808    *     The layer iterator that describes the layers of this paint.
 809    *
 810    * @since:
 811    *   2.13
 812    */
 813   typedef struct  FT_PaintColrLayers_
 814   {
 815     FT_LayerIterator  layer_iterator;
 816
 817   } FT_PaintColrLayers;
 818
 819
 820   /**************************************************************************
 821    *
 822    * @struct:
 823    *   FT_PaintSolid
 824    *
 825    * @description:
 826    *   A structure representing a `PaintSolid` value of the 'COLR' v1
 827    *   extensions, see 'https://github.com/googlefonts/colr-gradients-spec'.
 828    *   Using a `PaintSolid` value means that the glyph layer filled with
 829    *   this paint is solid-colored and does not contain a gradient.
 830    *
 831    * @fields:
 832    *   color ::
 833    *     The color information for this solid paint, see @FT_ColorIndex.
 834    *
 835    * @since:
 836    *   2.13
 837    */
 838   typedef struct  FT_PaintSolid_
 839   {
 840     FT_ColorIndex  color;
 841
 842   } FT_PaintSolid;
 843
 844
 845   /**************************************************************************
 846    *
 847    * @struct:
 848    *   FT_PaintLinearGradient
 849    *
 850    * @description:
 851    *   A structure representing a `PaintLinearGradient` value of the 'COLR'
 852    *   v1 extensions, see
 853    *   'https://github.com/googlefonts/colr-gradients-spec'.  The glyph
 854    *   layer filled with this paint is drawn filled with a linear gradient.
 855    *
 856    * @fields:
 857    *   colorline ::
 858    *     The @FT_ColorLine information for this paint, i.e., the list of
 859    *     color stops along the gradient.
 860    *
 861    *   p0 ::
 862    *     The starting point of the gradient definition in font units
 863    *     represented as a 16.16 fixed-point `FT_Vector`.
 864    *
 865    *   p1 ::
 866    *     The end point of the gradient definition in font units
 867    *     represented as a 16.16 fixed-point `FT_Vector`.
 868    *
 869    *   p2 ::
 870    *     Optional point~p2 to rotate the gradient in font units
 871    *     represented as a 16.16 fixed-point `FT_Vector`.
 872    *     Otherwise equal to~p0.
 873    *
 874    * @since:
 875    *   2.13
 876    */
 877   typedef struct  FT_PaintLinearGradient_
 878   {
 879     FT_ColorLine  colorline;
 880
 881     /* TODO: Potentially expose those as x0, y0 etc. */
 882     FT_Vector  p0;
 883     FT_Vector  p1;
 884     FT_Vector  p2;
 885
 886   } FT_PaintLinearGradient;
 887
 888
 889   /**************************************************************************
 890    *
 891    * @struct:
 892    *   FT_PaintRadialGradient
 893    *
 894    * @description:
 895    *   A structure representing a `PaintRadialGradient` value of the 'COLR'
 896    *   v1 extensions, see
 897    *   'https://github.com/googlefonts/colr-gradients-spec'.  The glyph
 898    *   layer filled with this paint is drawn filled with a radial gradient.
 899    *
 900    * @fields:
 901    *   colorline ::
 902    *     The @FT_ColorLine information for this paint, i.e., the list of
 903    *     color stops along the gradient.
 904    *
 905    *   c0 ::
 906    *     The center of the starting point of the radial gradient in font
 907    *     units represented as a 16.16 fixed-point `FT_Vector`.
 908    *
 909    *   r0 ::
 910    *     The radius of the starting circle of the radial gradient in font
 911    *     units represented as a 16.16 fixed-point value.
 912    *
 913    *   c1 ::
 914    *     The center of the end point of the radial gradient in font units
 915    *     represented as a 16.16 fixed-point `FT_Vector`.
 916    *
 917    *   r1 ::
 918    *     The radius of the end circle of the radial gradient in font
 919    *     units represented as a 16.16 fixed-point value.
 920    *
 921    * @since:
 922    *   2.13
 923    */
 924   typedef struct  FT_PaintRadialGradient_
 925   {
 926     FT_ColorLine  colorline;
 927
 928     FT_Vector  c0;
 929     FT_Pos     r0;
 930     FT_Vector  c1;
 931     FT_Pos     r1;
 932
 933   } FT_PaintRadialGradient;
 934
 935
 936   /**************************************************************************
 937    *
 938    * @struct:
 939    *   FT_PaintSweepGradient
 940    *
 941    * @description:
 942    *   A structure representing a `PaintSweepGradient` value of the 'COLR'
 943    *   v1 extensions, see
 944    *   'https://github.com/googlefonts/colr-gradients-spec'.  The glyph
 945    *   layer filled with this paint is drawn filled with a sweep gradient
 946    *   from `start_angle` to `end_angle`.
 947    *
 948    * @fields:
 949    *   colorline ::
 950    *     The @FT_ColorLine information for this paint, i.e., the list of
 951    *     color stops along the gradient.
 952    *
 953    *   center ::
 954    *     The center of the sweep gradient in font units represented as a
 955    *     vector of 16.16 fixed-point values.
 956    *
 957    *   start_angle ::
 958    *     The start angle of the sweep gradient in 16.16 fixed-point
 959    *     format specifying degrees divided by 180.0 (as in the
 960    *     spec).  Multiply by 180.0f to receive degrees value.  Values are
 961    *     given counter-clockwise, starting from the (positive) y~axis.
 962    *
 963    *   end_angle ::
 964    *     The end angle of the sweep gradient in 16.16 fixed-point
 965    *     format specifying degrees divided by 180.0 (as in the
 966    *     spec).  Multiply by 180.0f to receive degrees value.  Values are
 967    *     given counter-clockwise, starting from the (positive) y~axis.
 968    *
 969    * @since:
 970    *   2.13
 971    */
 972   typedef struct  FT_PaintSweepGradient_
 973   {
 974     FT_ColorLine  colorline;
 975
 976     FT_Vector  center;
 977     FT_Fixed   start_angle;
 978     FT_Fixed   end_angle;
 979
 980   } FT_PaintSweepGradient;
 981
 982
 983   /**************************************************************************
 984    *
 985    * @struct:
 986    *   FT_PaintGlyph
 987    *
 988    * @description:
 989    *   A structure representing a 'COLR' v1 `PaintGlyph` paint table.
 990    *
 991    * @fields:
 992    *   paint ::
 993    *     An opaque paint object pointing to a `Paint` table that serves as
 994    *     the fill for the glyph ID.
 995    *
 996    *   glyphID ::
 997    *     The glyph ID from the 'glyf' table, which serves as the contour
 998    *     information that is filled with paint.
 999    *
1000    * @since:
1001    *   2.13
1002    */
1003   typedef struct  FT_PaintGlyph_
1004   {
1005     FT_OpaquePaint  paint;
1006     FT_UInt         glyphID;
1007
1008   } FT_PaintGlyph;
1009
1010
1011   /**************************************************************************
1012    *
1013    * @struct:
1014    *   FT_PaintColrGlyph
1015    *
1016    * @description:
1017    *   A structure representing a 'COLR' v1 `PaintColorGlyph` paint table.
1018    *
1019    * @fields:
1020    *   glyphID ::
1021    *     The glyph ID from the `BaseGlyphV1List` table that is drawn for
1022    *     this paint.
1023    *
1024    * @since:
1025    *   2.13
1026    */
1027   typedef struct  FT_PaintColrGlyph_
1028   {
1029     FT_UInt  glyphID;
1030
1031   } FT_PaintColrGlyph;
1032
1033
1034   /**************************************************************************
1035    *
1036    * @struct:
1037    *   FT_PaintTransform
1038    *
1039    * @description:
1040    *   A structure representing a 'COLR' v1 `PaintTransform` paint table.
1041    *
1042    * @fields:
1043    *   paint ::
1044    *     An opaque paint that is subject to being transformed.
1045    *
1046    *   affine ::
1047    *     A 2x3 transformation matrix in @FT_Affine23 format containing
1048    *     16.16 fixed-point values.
1049    *
1050    * @since:
1051    *   2.13
1052    */
1053   typedef struct  FT_PaintTransform_
1054   {
1055     FT_OpaquePaint  paint;
1056     FT_Affine23     affine;
1057
1058   } FT_PaintTransform;
1059
1060
1061   /**************************************************************************
1062    *
1063    * @struct:
1064    *   FT_PaintTranslate
1065    *
1066    * @description:
1067    *   A structure representing a 'COLR' v1 `PaintTranslate` paint table.
1068    *   Used for translating downstream paints by a given x and y~delta.
1069    *
1070    * @fields:
1071    *   paint ::
1072    *     An @FT_OpaquePaint object referencing the paint that is to be
1073    *     rotated.
1074    *
1075    *   dx ::
1076    *     Translation in x~direction in font units represented as a
1077    *     16.16 fixed-point value.
1078    *
1079    *   dy ::
1080    *     Translation in y~direction in font units represented as a
1081    *     16.16 fixed-point value.
1082    *
1083    * @since:
1084    *   2.13
1085    */
1086   typedef struct  FT_PaintTranslate_
1087   {
1088     FT_OpaquePaint  paint;
1089
1090     FT_Fixed  dx;
1091     FT_Fixed  dy;
1092
1093   } FT_PaintTranslate;
1094
1095
1096   /**************************************************************************
1097    *
1098    * @struct:
1099    *   FT_PaintScale
1100    *
1101    * @description:
1102    *   A structure representing all of the 'COLR' v1 'PaintScale*' paint
1103    *   tables.  Used for scaling downstream paints by a given x and y~scale,
1104    *   with a given center.  This structure is used for all 'PaintScale*'
1105    *   types that are part of specification; fields of this structure are
1106    *   filled accordingly.  If there is a center, the center values are set,
1107    *   otherwise they are set to the zero coordinate.  If the source font
1108    *   file has 'PaintScaleUniform*' set, the scale values are set
1109    *   accordingly to the same value.
1110    *
1111    * @fields:
1112    *   paint ::
1113    *     An @FT_OpaquePaint object referencing the paint that is to be
1114    *     scaled.
1115    *
1116    *   scale_x ::
1117    *     Scale factor in x~direction represented as a
1118    *     16.16 fixed-point value.
1119    *
1120    *   scale_y ::
1121    *     Scale factor in y~direction represented as a
1122    *     16.16 fixed-point value.
1123    *
1124    *   center_x ::
1125    *     x~coordinate of center point to scale from represented as a
1126    *     16.16 fixed-point value.
1127    *
1128    *   center_y ::
1129    *     y~coordinate of center point to scale from represented as a
1130    *     16.16 fixed-point value.
1131    *
1132    * @since:
1133    *   2.13
1134    */
1135   typedef struct  FT_PaintScale_
1136   {
1137     FT_OpaquePaint  paint;
1138
1139     FT_Fixed  scale_x;
1140     FT_Fixed  scale_y;
1141
1142     FT_Fixed  center_x;
1143     FT_Fixed  center_y;
1144
1145   } FT_PaintScale;
1146
1147
1148   /**************************************************************************
1149    *
1150    * @struct:
1151    *   FT_PaintRotate
1152    *
1153    * @description:
1154    *   A structure representing a 'COLR' v1 `PaintRotate` paint table.  Used
1155    *   for rotating downstream paints with a given center and angle.
1156    *
1157    * @fields:
1158    *   paint ::
1159    *     An @FT_OpaquePaint object referencing the paint that is to be
1160    *     rotated.
1161    *
1162    *   angle ::
1163    *     The rotation angle that is to be applied in degrees divided by
1164    *     180.0 (as in the spec) represented as a 16.16 fixed-point
1165    *     value.  Multiply by 180.0f to receive degrees value.
1166    *
1167    *   center_x ::
1168    *     The x~coordinate of the pivot point of the rotation in font
1169    *     units represented as a 16.16 fixed-point value.
1170    *
1171    *   center_y ::
1172    *     The y~coordinate of the pivot point of the rotation in font
1173    *     units represented as a 16.16 fixed-point value.
1174    *
1175    * @since:
1176    *   2.13
1177    */
1178
1179   typedef struct  FT_PaintRotate_
1180   {
1181     FT_OpaquePaint  paint;
1182
1183     FT_Fixed  angle;
1184
1185     FT_Fixed  center_x;
1186     FT_Fixed  center_y;
1187
1188   } FT_PaintRotate;
1189
1190
1191   /**************************************************************************
1192    *
1193    * @struct:
1194    *   FT_PaintSkew
1195    *
1196    * @description:
1197    *   A structure representing a 'COLR' v1 `PaintSkew` paint table.  Used
1198    *   for skewing or shearing downstream paints by a given center and
1199    *   angle.
1200    *
1201    * @fields:
1202    *   paint ::
1203    *     An @FT_OpaquePaint object referencing the paint that is to be
1204    *     skewed.
1205    *
1206    *   x_skew_angle ::
1207    *     The skewing angle in x~direction in degrees divided by 180.0
1208    *     (as in the spec) represented as a 16.16 fixed-point
1209    *     value. Multiply by 180.0f to receive degrees.
1210    *
1211    *   y_skew_angle ::
1212    *     The skewing angle in y~direction in degrees divided by 180.0
1213    *     (as in the spec) represented as a 16.16 fixed-point
1214    *     value.  Multiply by 180.0f to receive degrees.
1215    *
1216    *   center_x ::
1217    *     The x~coordinate of the pivot point of the skew in font units
1218    *     represented as a 16.16 fixed-point value.
1219    *
1220    *   center_y ::
1221    *     The y~coordinate of the pivot point of the skew in font units
1222    *     represented as a 16.16 fixed-point value.
1223    *
1224    * @since:
1225    *   2.13
1226    */
1227   typedef struct  FT_PaintSkew_
1228   {
1229     FT_OpaquePaint  paint;
1230
1231     FT_Fixed  x_skew_angle;
1232     FT_Fixed  y_skew_angle;
1233
1234     FT_Fixed  center_x;
1235     FT_Fixed  center_y;
1236
1237   } FT_PaintSkew;
1238
1239
1240   /**************************************************************************
1241    *
1242    * @struct:
1243    *   FT_PaintComposite
1244    *
1245    * @description:
1246    *   A structure representing a 'COLR' v1 `PaintComposite` paint table.
1247    *   Used for compositing two paints in a 'COLR' v1 directed acyclic graph.
1248    *
1249    * @fields:
1250    *   source_paint ::
1251    *     An @FT_OpaquePaint object referencing the source that is to be
1252    *     composited.
1253    *
1254    *   composite_mode ::
1255    *     An @FT_Composite_Mode enum value determining the composition
1256    *     operation.
1257    *
1258    *   backdrop_paint ::
1259    *     An @FT_OpaquePaint object referencing the backdrop paint that
1260    *     `source_paint` is composited onto.
1261    *
1262    * @since:
1263    *   2.13
1264    */
1265   typedef struct  FT_PaintComposite_
1266   {
1267     FT_OpaquePaint     source_paint;
1268     FT_Composite_Mode  composite_mode;
1269     FT_OpaquePaint     backdrop_paint;
1270
1271   } FT_PaintComposite;
1272
1273
1274   /**************************************************************************
1275    *
1276    * @union:
1277    *   FT_COLR_Paint
1278    *
1279    * @description:
1280    *   A union object representing format and details of a paint table of a
1281    *   'COLR' v1 font, see
1282    *   'https://github.com/googlefonts/colr-gradients-spec'.  Use
1283    *   @FT_Get_Paint to retrieve a @FT_COLR_Paint for an @FT_OpaquePaint
1284    *   object.
1285    *
1286    * @fields:
1287    *   format ::
1288    *     The gradient format for this Paint structure.
1289    *
1290    *   u ::
1291    *     Union of all paint table types:
1292    *
1293    *       * @FT_PaintColrLayers
1294    *       * @FT_PaintGlyph
1295    *       * @FT_PaintSolid
1296    *       * @FT_PaintLinearGradient
1297    *       * @FT_PaintRadialGradient
1298    *       * @FT_PaintSweepGradient
1299    *       * @FT_PaintTransform
1300    *       * @FT_PaintTranslate
1301    *       * @FT_PaintRotate
1302    *       * @FT_PaintSkew
1303    *       * @FT_PaintComposite
1304    *       * @FT_PaintColrGlyph
1305    *
1306    * @since:
1307    *   2.13
1308    */
1309   typedef struct  FT_COLR_Paint_
1310   {
1311     FT_PaintFormat format;
1312
1313     union
1314     {
1315       FT_PaintColrLayers      colr_layers;
1316       FT_PaintGlyph           glyph;
1317       FT_PaintSolid           solid;
1318       FT_PaintLinearGradient  linear_gradient;
1319       FT_PaintRadialGradient  radial_gradient;
1320       FT_PaintSweepGradient   sweep_gradient;
1321       FT_PaintTransform       transform;
1322       FT_PaintTranslate       translate;
1323       FT_PaintScale           scale;
1324       FT_PaintRotate          rotate;
1325       FT_PaintSkew            skew;
1326       FT_PaintComposite       composite;
1327       FT_PaintColrGlyph       colr_glyph;
1328
1329     } u;
1330
1331   } FT_COLR_Paint;
1332
1333
1334   /**************************************************************************
1335    *
1336    * @enum:
1337    *   FT_Color_Root_Transform
1338    *
1339    * @description:
1340    *   An enumeration to specify whether @FT_Get_Color_Glyph_Paint is to
1341    *   return a root transform to configure the client's graphics context
1342    *   matrix.
1343    *
1344    * @values:
1345    *   FT_COLOR_INCLUDE_ROOT_TRANSFORM ::
1346    *     Do include the root transform as the initial @FT_COLR_Paint object.
1347    *
1348    *   FT_COLOR_NO_ROOT_TRANSFORM ::
1349    *     Do not output an initial root transform.
1350    *
1351    * @since:
1352    *   2.13
1353    */
1354   typedef enum  FT_Color_Root_Transform_
1355   {
1356     FT_COLOR_INCLUDE_ROOT_TRANSFORM,
1357     FT_COLOR_NO_ROOT_TRANSFORM,
1358
1359     FT_COLOR_ROOT_TRANSFORM_MAX
1360
1361   } FT_Color_Root_Transform;
1362
1363
1364   /**************************************************************************
1365    *
1366    * @struct:
1367    *   FT_ClipBox
1368    *
1369    * @description:
1370    *   A structure representing a 'COLR' v1 'ClipBox' table.  'COLR' v1
1371    *   glyphs may optionally define a clip box for aiding allocation or
1372    *   defining a maximum drawable region.  Use @FT_Get_Color_Glyph_ClipBox
1373    *   to retrieve it.
1374    *
1375    * @fields:
1376    *   bottom_left ::
1377    *     The bottom left corner of the clip box as an @FT_Vector with
1378    *     fixed-point coordinates in 26.6 format.
1379    *
1380    *   top_left ::
1381    *     The top left corner of the clip box as an @FT_Vector with
1382    *     fixed-point coordinates in 26.6 format.
1383    *
1384    *   top_right ::
1385    *     The top right corner of the clip box as an @FT_Vector with
1386    *     fixed-point coordinates in 26.6 format.
1387    *
1388    *   bottom_right ::
1389    *     The bottom right corner of the clip box as an @FT_Vector with
1390    *     fixed-point coordinates in 26.6 format.
1391    *
1392    * @since:
1393    *   2.13
1394    */
1395   typedef struct  FT_ClipBox_
1396   {
1397     FT_Vector  bottom_left;
1398     FT_Vector  top_left;
1399     FT_Vector  top_right;
1400     FT_Vector  bottom_right;
1401
1402   } FT_ClipBox;
1403
1404
1405   /**************************************************************************
1406    *
1407    * @function:
1408    *   FT_Get_Color_Glyph_Paint
1409    *
1410    * @description:
1411    *   This is the starting point and interface to color gradient
1412    *   information in a 'COLR' v1 table in OpenType fonts to recursively
1413    *   retrieve the paint tables for the directed acyclic graph of a colored
1414    *   glyph, given a glyph ID.
1415    *
1416    *     https://github.com/googlefonts/colr-gradients-spec
1417    *
1418    *   In a 'COLR' v1 font, each color glyph defines a directed acyclic
1419    *   graph of nested paint tables, such as `PaintGlyph`, `PaintSolid`,
1420    *   `PaintLinearGradient`, `PaintRadialGradient`, and so on.  Using this
1421    *   function and specifying a glyph ID, one retrieves the root paint
1422    *   table for this glyph ID.
1423    *
1424    *   This function allows control whether an initial root transform is
1425    *   returned to configure scaling, transform, and translation correctly
1426    *   on the client's graphics context.  The initial root transform is
1427    *   computed and returned according to the values configured for @FT_Size
1428    *   and @FT_Set_Transform on the @FT_Face object, see below for details
1429    *   of the `root_transform` parameter.  This has implications for a
1430    *   client 'COLR' v1 implementation: When this function returns an
1431    *   initially computed root transform, at the time of executing the
1432    *   @FT_PaintGlyph operation, the contours should be retrieved using
1433    *   @FT_Load_Glyph at unscaled, untransformed size.  This is because the
1434    *   root transform applied to the graphics context will take care of
1435    *   correct scaling.
1436    *
1437    *   Alternatively, to allow hinting of contours, at the time of executing
1438    *   @FT_Load_Glyph, the current graphics context transformation matrix
1439    *   can be decomposed into a scaling matrix and a remainder, and
1440    *   @FT_Load_Glyph can be used to retrieve the contours at scaled size.
1441    *   Care must then be taken to blit or clip to the graphics context with
1442    *   taking this remainder transformation into account.
1443    *
1444    * @input:
1445    *   face ::
1446    *     A handle to the parent face object.
1447    *
1448    *   base_glyph ::
1449    *     The glyph index for which to retrieve the root paint table.
1450    *
1451    *   root_transform ::
1452    *     Specifies whether an initially computed root is returned by the
1453    *     @FT_PaintTransform operation to account for the activated size
1454    *     (see @FT_Activate_Size) and the configured transform and translate
1455    *     (see @FT_Set_Transform).
1456    *
1457    *     This root transform is returned before nodes of the glyph graph of
1458    *     the font are returned.  Subsequent @FT_COLR_Paint structures
1459    *     contain unscaled and untransformed values.  The inserted root
1460    *     transform enables the client application to apply an initial
1461    *     transform to its graphics context.  When executing subsequent
1462    *     FT_COLR_Paint operations, values from @FT_COLR_Paint operations
1463    *     will ultimately be correctly scaled because of the root transform
1464    *     applied to the graphics context.  Use
1465    *     @FT_COLOR_INCLUDE_ROOT_TRANSFORM to include the root transform, use
1466    *     @FT_COLOR_NO_ROOT_TRANSFORM to not include it.  The latter may be
1467    *     useful when traversing the 'COLR' v1 glyph graph and reaching a
1468    *     @FT_PaintColrGlyph.  When recursing into @FT_PaintColrGlyph and
1469    *     painting that inline, no additional root transform is needed as it
1470    *     has already been applied to the graphics context at the beginning
1471    *     of drawing this glyph.
1472    *
1473    * @output:
1474    *   paint ::
1475    *     The @FT_OpaquePaint object that references the actual paint table.
1476    *
1477    *     The respective actual @FT_COLR_Paint object is retrieved via
1478    *     @FT_Get_Paint.
1479    *
1480    * @return:
1481    *   Value~1 if everything is OK.  If no color glyph is found, or the root
1482    *   paint could not be retrieved, value~0 gets returned.  In case of an
1483    *   error, value~0 is returned also.
1484    *
1485    * @since:
1486    *   2.13
1487    */
1488   FT_EXPORT( FT_Bool )
1489   FT_Get_Color_Glyph_Paint( FT_Face                  face,
1490                             FT_UInt                  base_glyph,
1491                             FT_Color_Root_Transform  root_transform,
1492                             FT_OpaquePaint*          paint );
1493
1494
1495   /**************************************************************************
1496    *
1497    * @function:
1498    *   FT_Get_Color_Glyph_ClipBox
1499    *
1500    * @description:
1501    *   Search for a 'COLR' v1 clip box for the specified `base_glyph` and
1502    *   fill the `clip_box` parameter with the 'COLR' v1 'ClipBox' information
1503    *   if one is found.
1504    *
1505    * @input:
1506    *   face ::
1507    *     A handle to the parent face object.
1508    *
1509    *   base_glyph ::
1510    *     The glyph index for which to retrieve the clip box.
1511    *
1512    * @output:
1513    *   clip_box ::
1514    *     The clip box for the requested `base_glyph` if one is found.  The
1515    *     clip box is computed taking scale and transformations configured on
1516    *     the @FT_Face into account.  @FT_ClipBox contains @FT_Vector values
1517    *     in 26.6 format.
1518    *
1519    * @return:
1520    *   Value~1 if a clip box is found.  If no clip box is found or an error
1521    *   occured, value~0 is returned.
1522    *
1523    * @note:
1524    *   To retrieve the clip box in font units, reset scale to units-per-em
1525    *   and remove transforms configured using @FT_Set_Transform.
1526    *
1527    * @since:
1528    *   2.13
1529    */
1530   FT_EXPORT( FT_Bool )
1531   FT_Get_Color_Glyph_ClipBox( FT_Face      face,
1532                               FT_UInt      base_glyph,
1533                               FT_ClipBox*  clip_box );
1534
1535
1536   /**************************************************************************
1537    *
1538    * @function:
1539    *   FT_Get_Paint_Layers
1540    *
1541    * @description:
1542    *   Access the layers of a `PaintColrLayers` table.
1543    *
1544    *   If the root paint of a color glyph, or a nested paint of a 'COLR'
1545    *   glyph is a `PaintColrLayers` table, this function retrieves the
1546    *   layers of the `PaintColrLayers` table.
1547    *
1548    *   The @FT_PaintColrLayers object contains an @FT_LayerIterator, which
1549    *   is used here to iterate over the layers.  Each layer is returned as
1550    *   an @FT_OpaquePaint object, which then can be used with @FT_Get_Paint
1551    *   to retrieve the actual paint object.
1552    *
1553    * @input:
1554    *   face ::
1555    *     A handle to the parent face object.
1556    *
1557    * @inout:
1558    *   iterator ::
1559    *     The @FT_LayerIterator from an @FT_PaintColrLayers object, for which
1560    *     the layers are to be retrieved.  The internal state of the iterator
1561    *     is incremented after one call to this function for retrieving one
1562    *     layer.
1563    *
1564    * @output:
1565    *   paint ::
1566    *     The @FT_OpaquePaint object that references the actual paint table.
1567    *     The respective actual @FT_COLR_Paint object is retrieved via
1568    *     @FT_Get_Paint.
1569    *
1570    * @return:
1571    *   Value~1 if everything is OK.  Value~0 gets returned when the paint
1572    *   object can not be retrieved or any other error occurs.
1573    *
1574    * @since:
1575    *   2.13
1576    */
1577   FT_EXPORT( FT_Bool )
1578   FT_Get_Paint_Layers( FT_Face            face,
1579                        FT_LayerIterator*  iterator,
1580                        FT_OpaquePaint*    paint );
1581
1582
1583   /**************************************************************************
1584    *
1585    * @function:
1586    *   FT_Get_Colorline_Stops
1587    *
1588    * @description:
1589    *   This is an interface to color gradient information in a 'COLR' v1
1590    *   table in OpenType fonts to iteratively retrieve the gradient and
1591    *   solid fill information for colored glyph layers for a specified glyph
1592    *   ID.
1593    *
1594    *     https://github.com/googlefonts/colr-gradients-spec
1595    *
1596    * @input:
1597    *   face ::
1598    *     A handle to the parent face object.
1599    *
1600    * @inout:
1601    *   iterator ::
1602    *     The retrieved @FT_ColorStopIterator, configured on an @FT_ColorLine,
1603    *     which in turn got retrieved via paint information in
1604    *     @FT_PaintLinearGradient or @FT_PaintRadialGradient.
1605    *
1606    * @output:
1607    *   color_stop ::
1608    *     Color index and alpha value for the retrieved color stop.
1609    *
1610    * @return:
1611    *   Value~1 if everything is OK.  If there are no more color stops,
1612    *   value~0 gets returned.  In case of an error, value~0 is returned
1613    *   also.
1614    *
1615    * @since:
1616    *   2.13
1617    */
1618   FT_EXPORT( FT_Bool )
1619   FT_Get_Colorline_Stops( FT_Face                face,
1620                           FT_ColorStop*          color_stop,
1621                           FT_ColorStopIterator*  iterator );
1622
1623
1624   /**************************************************************************
1625    *
1626    * @function:
1627    *  FT_Get_Paint
1628    *
1629    * @description:
1630    *   Access the details of a paint using an @FT_OpaquePaint opaque paint
1631    *   object, which internally stores the offset to the respective `Paint`
1632    *   object in the 'COLR' table.
1633    *
1634    * @input:
1635    *   face ::
1636    *     A handle to the parent face object.
1637    *
1638    *   opaque_paint ::
1639    *     The opaque paint object for which the underlying @FT_COLR_Paint
1640    *     data is to be retrieved.
1641    *
1642    * @output:
1643    *   paint ::
1644    *     The specific @FT_COLR_Paint object containing information coming
1645    *     from one of the font's `Paint*` tables.
1646    *
1647    * @return:
1648    *   Value~1 if everything is OK.  Value~0 if no details can be found for
1649    *   this paint or any other error occured.
1650    *
1651    * @since:
1652    *   2.13
1653    */
1654   FT_EXPORT( FT_Bool )
1655   FT_Get_Paint( FT_Face         face,
1656                 FT_OpaquePaint  opaque_paint,
1657                 FT_COLR_Paint*  paint );
1658
1659   /* */
1660
1661
1662 FT_END_HEADER
1663
1664 #endif /* FTCOLOR_H_ */
1665
1666
1667 /* END */