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 */ 1668