1 /**************************************************************************** 2 * 3 * ftcolor.h 4 * 5 * FreeType's glyph color management (specification). 6 * 7 * Copyright (C) 2018-2021 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 FT_EXPORT( FT_Bool ) 461 FT_Get_Color_Glyph_Layer( FT_Face face, 462 FT_UInt base_glyph, 463 FT_UInt *aglyph_index, 464 FT_UInt *acolor_index, 465 FT_LayerIterator* iterator ); 466 467 468 /************************************************************************** 469 * 470 * @enum: 471 * FT_PaintFormat 472 * 473 * @description: 474 * Enumeration describing the different paint format types of the v1 475 * extensions to the 'COLR' table, see 476 * 'https://github.com/googlefonts/colr-gradients-spec'. 477 * 478 * The enumeration values losely correspond with the format numbers of 479 * the specification: FreeType always returns a fully specified 'Paint' 480 * structure for the 'Transform', 'Translate', 'Scale', 'Rotate', and 481 * 'Skew' table types even though the specification has different formats 482 * depending on whether or not a center is specified, whether the scale 483 * is uniform in x and y~direction or not, etc. Also, only non-variable 484 * format identifiers are listed in this enumeration; as soon as support 485 * for variable 'COLR' v1 fonts is implemented, interpolation is 486 * performed dependent on axis coordinates, which are configured on the 487 * @FT_Face through @FT_Set_Var_Design_Coordinates. This implies that 488 * always static, readily interpolated values are returned in the 'Paint' 489 * structures. 490 * 491 * @since: 492 * 2.11 -- **currently experimental only!** There might be changes 493 * without retaining backward compatibility of both the API and ABI. 494 * 495 */ 496 typedef enum FT_PaintFormat_ 497 { 498 FT_COLR_PAINTFORMAT_COLR_LAYERS = 1, 499 FT_COLR_PAINTFORMAT_SOLID = 2, 500 FT_COLR_PAINTFORMAT_LINEAR_GRADIENT = 4, 501 FT_COLR_PAINTFORMAT_RADIAL_GRADIENT = 6, 502 FT_COLR_PAINTFORMAT_SWEEP_GRADIENT = 8, 503 FT_COLR_PAINTFORMAT_GLYPH = 10, 504 FT_COLR_PAINTFORMAT_COLR_GLYPH = 11, 505 FT_COLR_PAINTFORMAT_TRANSFORM = 12, 506 FT_COLR_PAINTFORMAT_TRANSLATE = 14, 507 FT_COLR_PAINTFORMAT_SCALE = 16, 508 FT_COLR_PAINTFORMAT_ROTATE = 24, 509 FT_COLR_PAINTFORMAT_SKEW = 28, 510 FT_COLR_PAINTFORMAT_COMPOSITE = 32, 511 FT_COLR_PAINT_FORMAT_MAX = 33, 512 FT_COLR_PAINTFORMAT_UNSUPPORTED = 255 513 514 } FT_PaintFormat; 515 516 517 /************************************************************************** 518 * 519 * @struct: 520 * FT_ColorStopIterator 521 * 522 * @description: 523 * This iterator object is needed for @FT_Get_Colorline_Stops. It keeps 524 * state while iterating over the stops of an @FT_ColorLine, 525 * representing the `ColorLine` struct of the v1 extensions to 'COLR', 526 * see 'https://github.com/googlefonts/colr-gradients-spec'. 527 * 528 * @fields: 529 * num_color_stops :: 530 * The number of color stops for the requested glyph index. Set by 531 * @FT_Get_Colorline_Stops. 532 * 533 * current_color_stop :: 534 * The current color stop. Set by @FT_Get_Colorline_Stops. 535 * 536 * p :: 537 * An opaque pointer into 'COLR' table data. The caller must set this 538 * to `NULL` before the first call of @FT_Get_Colorline_Stops. 539 * 540 * @since: 541 * 2.11 -- **currently experimental only!** There might be changes 542 * without retaining backward compatibility of both the API and ABI. 543 * 544 */ 545 typedef struct FT_ColorStopIterator_ 546 { 547 FT_UInt num_color_stops; 548 FT_UInt current_color_stop; 549 550 FT_Byte* p; 551 552 } FT_ColorStopIterator; 553 554 555 /************************************************************************** 556 * 557 * @struct: 558 * FT_ColorIndex 559 * 560 * @description: 561 * A structure representing a `ColorIndex` value of the 'COLR' v1 562 * extensions, see 'https://github.com/googlefonts/colr-gradients-spec'. 563 * 564 * @fields: 565 * palette_index :: 566 * The palette index into a 'CPAL' palette. 567 * 568 * alpha :: 569 * Alpha transparency value multiplied with the value from 'CPAL'. 570 * 571 * @since: 572 * 2.11 -- **currently experimental only!** There might be changes 573 * without retaining backward compatibility of both the API and ABI. 574 * 575 */ 576 typedef struct FT_ColorIndex_ 577 { 578 FT_UInt16 palette_index; 579 FT_F2Dot14 alpha; 580 581 } FT_ColorIndex; 582 583 584 /************************************************************************** 585 * 586 * @struct: 587 * FT_ColorStop 588 * 589 * @description: 590 * A structure representing a `ColorStop` value of the 'COLR' v1 591 * extensions, see 'https://github.com/googlefonts/colr-gradients-spec'. 592 * 593 * @fields: 594 * stop_offset :: 595 * The stop offset between 0 and 1 along the gradient. 596 * 597 * color :: 598 * The color information for this stop, see @FT_ColorIndex. 599 * 600 * @since: 601 * 2.11 -- **currently experimental only!** There might be changes 602 * without retaining backward compatibility of both the API and ABI. 603 * 604 */ 605 typedef struct FT_ColorStop_ 606 { 607 FT_F2Dot14 stop_offset; 608 FT_ColorIndex color; 609 610 } FT_ColorStop; 611 612 613 /************************************************************************** 614 * 615 * @enum: 616 * FT_PaintExtend 617 * 618 * @description: 619 * An enumeration representing the 'Extend' mode of the 'COLR' v1 620 * extensions, see 'https://github.com/googlefonts/colr-gradients-spec'. 621 * It describes how the gradient fill continues at the other boundaries. 622 * 623 * @since: 624 * 2.11 -- **currently experimental only!** There might be changes 625 * without retaining backward compatibility of both the API and ABI. 626 * 627 */ 628 typedef enum FT_PaintExtend_ 629 { 630 FT_COLR_PAINT_EXTEND_PAD = 0, 631 FT_COLR_PAINT_EXTEND_REPEAT = 1, 632 FT_COLR_PAINT_EXTEND_REFLECT = 2 633 634 } FT_PaintExtend; 635 636 637 /************************************************************************** 638 * 639 * @struct: 640 * FT_ColorLine 641 * 642 * @description: 643 * A structure representing a `ColorLine` value of the 'COLR' v1 644 * extensions, see 'https://github.com/googlefonts/colr-gradients-spec'. 645 * It describes a list of color stops along the defined gradient. 646 * 647 * @fields: 648 * extend :: 649 * The extend mode at the outer boundaries, see @FT_PaintExtend. 650 * 651 * color_stop_iterator :: 652 * The @FT_ColorStopIterator used to enumerate and retrieve the 653 * actual @FT_ColorStop's. 654 * 655 * @since: 656 * 2.11 -- **currently experimental only!** There might be changes 657 * without retaining backward compatibility of both the API and ABI. 658 * 659 */ 660 typedef struct FT_ColorLine_ 661 { 662 FT_PaintExtend extend; 663 FT_ColorStopIterator color_stop_iterator; 664 665 } FT_ColorLine; 666 667 668 /************************************************************************** 669 * 670 * @struct: 671 * FT_Affine23 672 * 673 * @description: 674 * A structure used to store a 2x3 matrix. Coefficients are in 675 * 16.16 fixed-point format. The computation performed is 676 * 677 * ``` 678 * x' = x*xx + y*xy + dx 679 * y' = x*yx + y*yy + dy 680 * ``` 681 * 682 * @fields: 683 * xx :: 684 * Matrix coefficient. 685 * 686 * xy :: 687 * Matrix coefficient. 688 * 689 * dx :: 690 * x translation. 691 * 692 * yx :: 693 * Matrix coefficient. 694 * 695 * yy :: 696 * Matrix coefficient. 697 * 698 * dy :: 699 * y translation. 700 * 701 * @since: 702 * 2.11 -- **currently experimental only!** There might be changes 703 * without retaining backward compatibility of both the API and ABI. 704 * 705 */ 706 typedef struct FT_Affine_23_ 707 { 708 FT_Fixed xx, xy, dx; 709 FT_Fixed yx, yy, dy; 710 711 } FT_Affine23; 712 713 714 /************************************************************************** 715 * 716 * @enum: 717 * FT_Composite_Mode 718 * 719 * @description: 720 * An enumeration listing the 'COLR' v1 composite modes used in 721 * @FT_PaintComposite. For more details on each paint mode, see 722 * 'https://www.w3.org/TR/compositing-1/#porterduffcompositingoperators'. 723 * 724 * @since: 725 * 2.11 -- **currently experimental only!** There might be changes 726 * without retaining backward compatibility of both the API and ABI. 727 * 728 */ 729 typedef enum FT_Composite_Mode_ 730 { 731 FT_COLR_COMPOSITE_CLEAR = 0, 732 FT_COLR_COMPOSITE_SRC = 1, 733 FT_COLR_COMPOSITE_DEST = 2, 734 FT_COLR_COMPOSITE_SRC_OVER = 3, 735 FT_COLR_COMPOSITE_DEST_OVER = 4, 736 FT_COLR_COMPOSITE_SRC_IN = 5, 737 FT_COLR_COMPOSITE_DEST_IN = 6, 738 FT_COLR_COMPOSITE_SRC_OUT = 7, 739 FT_COLR_COMPOSITE_DEST_OUT = 8, 740 FT_COLR_COMPOSITE_SRC_ATOP = 9, 741 FT_COLR_COMPOSITE_DEST_ATOP = 10, 742 FT_COLR_COMPOSITE_XOR = 11, 743 FT_COLR_COMPOSITE_PLUS = 12, 744 FT_COLR_COMPOSITE_SCREEN = 13, 745 FT_COLR_COMPOSITE_OVERLAY = 14, 746 FT_COLR_COMPOSITE_DARKEN = 15, 747 FT_COLR_COMPOSITE_LIGHTEN = 16, 748 FT_COLR_COMPOSITE_COLOR_DODGE = 17, 749 FT_COLR_COMPOSITE_COLOR_BURN = 18, 750 FT_COLR_COMPOSITE_HARD_LIGHT = 19, 751 FT_COLR_COMPOSITE_SOFT_LIGHT = 20, 752 FT_COLR_COMPOSITE_DIFFERENCE = 21, 753 FT_COLR_COMPOSITE_EXCLUSION = 22, 754 FT_COLR_COMPOSITE_MULTIPLY = 23, 755 FT_COLR_COMPOSITE_HSL_HUE = 24, 756 FT_COLR_COMPOSITE_HSL_SATURATION = 25, 757 FT_COLR_COMPOSITE_HSL_COLOR = 26, 758 FT_COLR_COMPOSITE_HSL_LUMINOSITY = 27, 759 FT_COLR_COMPOSITE_MAX = 28 760 761 } FT_Composite_Mode; 762 763 764 /************************************************************************** 765 * 766 * @struct: 767 * FT_OpaquePaint 768 * 769 * @description: 770 * A structure representing an offset to a `Paint` value stored in any 771 * of the paint tables of a 'COLR' v1 font. Compare Offset<24> there. 772 * When 'COLR' v1 paint tables represented by FreeType objects such as 773 * @FT_PaintColrLayers, @FT_PaintComposite, or @FT_PaintTransform 774 * reference downstream nested paint tables, we do not immediately 775 * retrieve them but encapsulate their location in this type. Use 776 * @FT_Get_Paint to retrieve the actual @FT_COLR_Paint object that 777 * describes the details of the respective paint table. 778 * 779 * @fields: 780 * p :: 781 * An internal offset to a Paint table, needs to be set to NULL before 782 * passing this struct as an argument to @FT_Get_Paint. 783 * 784 * insert_root_transform :: 785 * An internal boolean to track whether an initial root transform is 786 * to be provided. Do not set this value. 787 * 788 * @since: 789 * 2.11 -- **currently experimental only!** There might be changes 790 * without retaining backward compatibility of both the API and ABI. 791 * 792 */ 793 typedef struct FT_Opaque_Paint_ 794 { 795 FT_Byte* p; 796 FT_Bool insert_root_transform; 797 } FT_OpaquePaint; 798 799 800 /************************************************************************** 801 * 802 * @struct: 803 * FT_PaintColrLayers 804 * 805 * @description: 806 * A structure representing a `PaintColrLayers` table of a 'COLR' v1 807 * font. This table describes a set of layers that are to be composited 808 * with composite mode `FT_COLR_COMPOSITE_SRC_OVER`. The return value 809 * of this function is an @FT_LayerIterator initialized so that it can 810 * be used with @FT_Get_Paint_Layers to retrieve the @FT_OpaquePaint 811 * objects as references to each layer. 812 * 813 * @fields: 814 * layer_iterator :: 815 * The layer iterator that describes the layers of this paint. 816 * 817 * @since: 818 * 2.11 -- **currently experimental only!** There might be changes 819 * without retaining backward compatibility of both the API and ABI. 820 * 821 */ 822 typedef struct FT_PaintColrLayers_ 823 { 824 FT_LayerIterator layer_iterator; 825 826 } FT_PaintColrLayers; 827 828 829 /************************************************************************** 830 * 831 * @struct: 832 * FT_PaintSolid 833 * 834 * @description: 835 * A structure representing a `PaintSolid` value of the 'COLR' v1 836 * extensions, see 'https://github.com/googlefonts/colr-gradients-spec'. 837 * Using a `PaintSolid` value means that the glyph layer filled with 838 * this paint is solid-colored and does not contain a gradient. 839 * 840 * @fields: 841 * color :: 842 * The color information for this solid paint, see @FT_ColorIndex. 843 * 844 * @since: 845 * 2.11 -- **currently experimental only!** There might be changes 846 * without retaining backward compatibility of both the API and ABI. 847 * 848 */ 849 typedef struct FT_PaintSolid_ 850 { 851 FT_ColorIndex color; 852 853 } FT_PaintSolid; 854 855 856 /************************************************************************** 857 * 858 * @struct: 859 * FT_PaintLinearGradient 860 * 861 * @description: 862 * A structure representing a `PaintLinearGradient` value of the 'COLR' 863 * v1 extensions, see 864 * 'https://github.com/googlefonts/colr-gradients-spec'. The glyph 865 * layer filled with this paint is drawn filled with a linear gradient. 866 * 867 * @fields: 868 * colorline :: 869 * The @FT_ColorLine information for this paint, i.e., the list of 870 * color stops along the gradient. 871 * 872 * p0 :: 873 * The starting point of the gradient definition in font units 874 * represented as a 16.16 fixed-point `FT_Vector`. 875 * 876 * p1 :: 877 * The end point of the gradient definition in font units 878 * represented as a 16.16 fixed-point `FT_Vector`. 879 * 880 * p2 :: 881 * Optional point~p2 to rotate the gradient in font units 882 * represented as a 16.16 fixed-point `FT_Vector`. 883 * Otherwise equal to~p0. 884 * 885 * @since: 886 * 2.11 -- **currently experimental only!** There might be changes 887 * without retaining backward compatibility of both the API and ABI. 888 * 889 */ 890 typedef struct FT_PaintLinearGradient_ 891 { 892 FT_ColorLine colorline; 893 894 /* TODO: Potentially expose those as x0, y0 etc. */ 895 FT_Vector p0; 896 FT_Vector p1; 897 FT_Vector p2; 898 899 } FT_PaintLinearGradient; 900 901 902 /************************************************************************** 903 * 904 * @struct: 905 * FT_PaintRadialGradient 906 * 907 * @description: 908 * A structure representing a `PaintRadialGradient` value of the 'COLR' 909 * v1 extensions, see 910 * 'https://github.com/googlefonts/colr-gradients-spec'. The glyph 911 * layer filled with this paint is drawn filled filled with a radial 912 * gradient. 913 * 914 * @fields: 915 * colorline :: 916 * The @FT_ColorLine information for this paint, i.e., the list of 917 * color stops along the gradient. 918 * 919 * c0 :: 920 * The center of the starting point of the radial gradient in font 921 * units represented as a 16.16 fixed-point `FT_Vector`. 922 * 923 * r0 :: 924 * The radius of the starting circle of the radial gradient in font 925 * units represented as a 16.16 fixed-point value. 926 * 927 * c1 :: 928 * The center of the end point of the radial gradient in font units 929 * represented as a 16.16 fixed-point `FT_Vector`. 930 * 931 * r1 :: 932 * The radius of the end circle of the radial gradient in font 933 * units represented as a 16.16 fixed-point value. 934 * 935 * @since: 936 * 2.11 -- **currently experimental only!** There might be changes 937 * without retaining backward compatibility of both the API and ABI. 938 * 939 */ 940 typedef struct FT_PaintRadialGradient_ 941 { 942 FT_ColorLine colorline; 943 944 FT_Vector c0; 945 FT_Pos r0; 946 FT_Vector c1; 947 FT_Pos r1; 948 949 } FT_PaintRadialGradient; 950 951 952 /************************************************************************** 953 * 954 * @struct: 955 * FT_PaintSweepGradient 956 * 957 * @description: 958 * A structure representing a `PaintSweepGradient` value of the 'COLR' 959 * v1 extensions, see 960 * 'https://github.com/googlefonts/colr-gradients-spec'. The glyph 961 * layer filled with this paint is drawn filled with a sweep gradient 962 * from `start_angle` to `end_angle`. 963 * 964 * @fields: 965 * colorline :: 966 * The @FT_ColorLine information for this paint, i.e., the list of 967 * color stops along the gradient. 968 * 969 * center :: 970 * The center of the sweep gradient in font units represented as a 971 * vector of 16.16 fixed-point values. 972 * 973 * start_angle :: 974 * The start angle of the sweep gradient in 16.16 fixed-point 975 * format specifying degrees divided by 180.0 (as in the 976 * spec). Multiply by 180.0f to receive degrees value. Values are 977 * given counter-clockwise, starting from the (positive) y~axis. 978 * 979 * end_angle :: 980 * The end angle of the sweep gradient in 16.16 fixed-point 981 * format specifying degrees divided by 180.0 (as in the 982 * spec). Multiply by 180.0f to receive degrees value. Values are 983 * given counter-clockwise, starting from the (positive) y~axis. 984 * 985 * @since: 986 * 2.11 -- **currently experimental only!** There might be changes 987 * without retaining backward compatibility of both the API and ABI. 988 * 989 */ 990 typedef struct FT_PaintSweepGradient_ 991 { 992 FT_ColorLine colorline; 993 994 FT_Vector center; 995 FT_Fixed start_angle; 996 FT_Fixed end_angle; 997 998 } FT_PaintSweepGradient; 999 1000 1001 /************************************************************************** 1002 * 1003 * @struct: 1004 * FT_PaintGlyph 1005 * 1006 * @description: 1007 * A structure representing a 'COLR' v1 `PaintGlyph` paint table. 1008 * 1009 * @fields: 1010 * paint :: 1011 * An opaque paint object pointing to a `Paint` table that serves as 1012 * the fill for the glyph ID. 1013 * 1014 * glyphID :: 1015 * The glyph ID from the 'glyf' table, which serves as the contour 1016 * information that is filled with paint. 1017 * 1018 * @since: 1019 * 2.11 -- **currently experimental only!** There might be changes 1020 * without retaining backward compatibility of both the API and ABI. 1021 * 1022 */ 1023 typedef struct FT_PaintGlyph_ 1024 { 1025 FT_OpaquePaint paint; 1026 FT_UInt glyphID; 1027 1028 } FT_PaintGlyph; 1029 1030 1031 /************************************************************************** 1032 * 1033 * @struct: 1034 * FT_PaintColrGlyph 1035 * 1036 * @description: 1037 * A structure representing a 'COLR' v1 `PaintColorGlyph` paint table. 1038 * 1039 * @fields: 1040 * glyphID :: 1041 * The glyph ID from the `BaseGlyphV1List` table that is drawn for 1042 * this paint. 1043 * 1044 * @since: 1045 * 2.11 -- **currently experimental only!** There might be changes 1046 * without retaining backward compatibility of both the API and ABI. 1047 * 1048 */ 1049 typedef struct FT_PaintColrGlyph_ 1050 { 1051 FT_UInt glyphID; 1052 1053 } FT_PaintColrGlyph; 1054 1055 1056 /************************************************************************** 1057 * 1058 * @struct: 1059 * FT_PaintTransform 1060 * 1061 * @description: 1062 * A structure representing a 'COLR' v1 `PaintTransform` paint table. 1063 * 1064 * @fields: 1065 * paint :: 1066 * An opaque paint that is subject to being transformed. 1067 * 1068 * affine :: 1069 * A 2x3 transformation matrix in @FT_Affine23 format containing 1070 * 16.16 fixed-point values. 1071 * 1072 * @since: 1073 * 2.11 -- **currently experimental only!** There might be changes 1074 * without retaining backward compatibility of both the API and ABI. 1075 * 1076 */ 1077 typedef struct FT_PaintTransform_ 1078 { 1079 FT_OpaquePaint paint; 1080 FT_Affine23 affine; 1081 1082 } FT_PaintTransform; 1083 1084 1085 /************************************************************************** 1086 * 1087 * @struct: 1088 * FT_PaintTranslate 1089 * 1090 * @description: 1091 * A structure representing a 'COLR' v1 `PaintTranslate` paint table. 1092 * Used for translating downstream paints by a given x and y~delta. 1093 * 1094 * @fields: 1095 * paint :: 1096 * An @FT_OpaquePaint object referencing the paint that is to be 1097 * rotated. 1098 * 1099 * dx :: 1100 * Translation in x~direction in font units represented as a 1101 * 16.16 fixed-point value. 1102 * 1103 * dy :: 1104 * Translation in y~direction in font units represented as a 1105 * 16.16 fixed-point value. 1106 * 1107 * @since: 1108 * 2.11 -- **currently experimental only!** There might be changes 1109 * without retaining backward compatibility of both the API and ABI. 1110 * 1111 */ 1112 typedef struct FT_PaintTranslate_ 1113 { 1114 FT_OpaquePaint paint; 1115 1116 FT_Fixed dx; 1117 FT_Fixed dy; 1118 1119 } FT_PaintTranslate; 1120 1121 1122 /************************************************************************** 1123 * 1124 * @struct: 1125 * FT_PaintScale 1126 * 1127 * @description: 1128 * A structure representing all of the 'COLR' v1 'PaintScale*' paint 1129 * tables. Used for scaling downstream paints by a given x and y~scale, 1130 * with a given center. This structure is used for all 'PaintScale*' 1131 * types that are part of specification; fields of this structure are 1132 * filled accordingly. If there is a center, the center values are set, 1133 * otherwise they are set to the zero coordinate. If the source font 1134 * file has 'PaintScaleUniform*' set, the scale values are set 1135 * accordingly to the same value. 1136 * 1137 * @fields: 1138 * paint :: 1139 * An @FT_OpaquePaint object referencing the paint that is to be 1140 * scaled. 1141 * 1142 * scale_x :: 1143 * Scale factor in x~direction represented as a 1144 * 16.16 fixed-point value. 1145 * 1146 * scale_y :: 1147 * Scale factor in y~direction represented as a 1148 * 16.16 fixed-point value. 1149 * 1150 * center_x :: 1151 * x~coordinate of center point to scale from represented as a 1152 * 16.16 fixed-point value. 1153 * 1154 * center_y :: 1155 * y~coordinate of center point to scale from represented as a 1156 * 16.16 fixed-point value. 1157 * 1158 * @since: 1159 * 2.11 -- **currently experimental only!** There might be changes 1160 * without retaining backward-compatibility of both the API and ABI. 1161 * 1162 */ 1163 typedef struct FT_PaintScale_ 1164 { 1165 FT_OpaquePaint paint; 1166 1167 FT_Fixed scale_x; 1168 FT_Fixed scale_y; 1169 1170 FT_Fixed center_x; 1171 FT_Fixed center_y; 1172 1173 } FT_PaintScale; 1174 1175 1176 /************************************************************************** 1177 * 1178 * @struct: 1179 * FT_PaintRotate 1180 * 1181 * @description: 1182 * A structure representing a 'COLR' v1 `PaintRotate` paint table. Used 1183 * for rotating downstream paints with a given center and angle. 1184 * 1185 * @fields: 1186 * paint :: 1187 * An @FT_OpaquePaint object referencing the paint that is to be 1188 * rotated. 1189 * 1190 * angle :: 1191 * The rotation angle that is to be applied in degrees divided by 1192 * 180.0 (as in the spec) represented as a 16.16 fixed-point 1193 * value. Multiply by 180.0f to receive degrees value. 1194 * 1195 * center_x :: 1196 * The x~coordinate of the pivot point of the rotation in font 1197 * units) represented as a 16.16 fixed-point value. 1198 * 1199 * center_y :: 1200 * The y~coordinate of the pivot point of the rotation in font 1201 * units represented as a 16.16 fixed-point value. 1202 * 1203 * @since: 1204 * 2.11 -- **currently experimental only!** There might be changes 1205 * without retaining backward compatibility of both the API and ABI. 1206 * 1207 */ 1208 1209 typedef struct FT_PaintRotate_ 1210 { 1211 FT_OpaquePaint paint; 1212 1213 FT_Fixed angle; 1214 1215 FT_Fixed center_x; 1216 FT_Fixed center_y; 1217 1218 } FT_PaintRotate; 1219 1220 1221 /************************************************************************** 1222 * 1223 * @struct: 1224 * FT_PaintSkew 1225 * 1226 * @description: 1227 * A structure representing a 'COLR' v1 `PaintSkew` paint table. Used 1228 * for skewing or shearing downstream paints by a given center and 1229 * angle. 1230 * 1231 * @fields: 1232 * paint :: 1233 * An @FT_OpaquePaint object referencing the paint that is to be 1234 * skewed. 1235 * 1236 * x_skew_angle :: 1237 * The skewing angle in x~direction in degrees divided by 180.0 1238 * (as in the spec) represented as a 16.16 fixed-point 1239 * value. Multiply by 180.0f to receive degrees. 1240 * 1241 * y_skew_angle :: 1242 * The skewing angle in y~direction in degrees divided by 180.0 1243 * (as in the spec) represented as a 16.16 fixed-point 1244 * value. Multiply by 180.0f to receive degrees. 1245 * 1246 * center_x :: 1247 * The x~coordinate of the pivot point of the skew in font units 1248 * represented as a 16.16 fixed-point value. 1249 * 1250 * center_y :: 1251 * The y~coordinate of the pivot point of the skew in font units 1252 * represented as a 16.16 fixed-point value. 1253 * 1254 * @since: 1255 * 2.11 -- **currently experimental only!** There might be changes 1256 * without retaining backward compatibility of both the API and ABI. 1257 * 1258 */ 1259 typedef struct FT_PaintSkew_ 1260 { 1261 FT_OpaquePaint paint; 1262 1263 FT_Fixed x_skew_angle; 1264 FT_Fixed y_skew_angle; 1265 1266 FT_Fixed center_x; 1267 FT_Fixed center_y; 1268 1269 } FT_PaintSkew; 1270 1271 1272 /************************************************************************** 1273 * 1274 * @struct: 1275 * FT_PaintComposite 1276 * 1277 * @description: 1278 * A structure representing a 'COLR'v1 `PaintComposite` paint table. 1279 * Used for compositing two paints in a 'COLR' v1 directed acycling 1280 * graph. 1281 * 1282 * @fields: 1283 * source_paint :: 1284 * An @FT_OpaquePaint object referencing the source that is to be 1285 * composited. 1286 * 1287 * composite_mode :: 1288 * An @FT_Composite_Mode enum value determining the composition 1289 * operation. 1290 * 1291 * backdrop_paint :: 1292 * An @FT_OpaquePaint object referencing the backdrop paint that 1293 * `source_paint` is composited onto. 1294 * 1295 * @since: 1296 * 2.11 -- **currently experimental only!** There might be changes 1297 * without retaining backward compatibility of both the API and ABI. 1298 * 1299 */ 1300 typedef struct FT_PaintComposite_ 1301 { 1302 FT_OpaquePaint source_paint; 1303 FT_Composite_Mode composite_mode; 1304 FT_OpaquePaint backdrop_paint; 1305 1306 } FT_PaintComposite; 1307 1308 1309 /************************************************************************** 1310 * 1311 * @union: 1312 * FT_COLR_Paint 1313 * 1314 * @description: 1315 * A union object representing format and details of a paint table of a 1316 * 'COLR' v1 font, see 1317 * 'https://github.com/googlefonts/colr-gradients-spec'. Use 1318 * @FT_Get_Paint to retrieve a @FT_COLR_Paint for an @FT_OpaquePaint 1319 * object. 1320 * 1321 * @fields: 1322 * format :: 1323 * The gradient format for this Paint structure. 1324 * 1325 * u :: 1326 * Union of all paint table types: 1327 * 1328 * * @FT_PaintColrLayers 1329 * * @FT_PaintGlyph 1330 * * @FT_PaintSolid 1331 * * @FT_PaintLinearGradient 1332 * * @FT_PaintRadialGradient 1333 * * @FT_PaintSweepGradient 1334 * * @FT_PaintTransform 1335 * * @FT_PaintTranslate 1336 * * @FT_PaintRotate 1337 * * @FT_PaintSkew 1338 * * @FT_PaintComposite 1339 * * @FT_PaintColrGlyph 1340 * 1341 * @since: 1342 * 2.11 -- **currently experimental only!** There might be changes 1343 * without retaining backward compatibility of both the API and ABI. 1344 * 1345 */ 1346 typedef struct FT_COLR_Paint_ 1347 { 1348 FT_PaintFormat format; 1349 1350 union 1351 { 1352 FT_PaintColrLayers colr_layers; 1353 FT_PaintGlyph glyph; 1354 FT_PaintSolid solid; 1355 FT_PaintLinearGradient linear_gradient; 1356 FT_PaintRadialGradient radial_gradient; 1357 FT_PaintSweepGradient sweep_gradient; 1358 FT_PaintTransform transform; 1359 FT_PaintTranslate translate; 1360 FT_PaintScale scale; 1361 FT_PaintRotate rotate; 1362 FT_PaintSkew skew; 1363 FT_PaintComposite composite; 1364 FT_PaintColrGlyph colr_glyph; 1365 1366 } u; 1367 1368 } FT_COLR_Paint; 1369 1370 1371 /************************************************************************** 1372 * 1373 * @enum: 1374 * FT_Color_Root_Transform 1375 * 1376 * @description: 1377 * An enumeration to specify whether @FT_Get_Color_Glyph_Paint is to 1378 * return a root transform to configure the client's graphics context 1379 * matrix. 1380 * 1381 * @values: 1382 * FT_COLOR_INCLUDE_ROOT_TRANSFORM :: 1383 * Do include the root transform as the initial @FT_COLR_Paint object. 1384 * 1385 * FT_COLOR_NO_ROOT_TRANSFORM :: 1386 * Do not output an initial root transform. 1387 * 1388 * @since: 1389 * 2.11 -- **currently experimental only!** There might be changes 1390 * without retaining backward compatibility of both the API and ABI. 1391 * 1392 */ 1393 typedef enum FT_Color_Root_Transform_ 1394 { 1395 FT_COLOR_INCLUDE_ROOT_TRANSFORM, 1396 FT_COLOR_NO_ROOT_TRANSFORM, 1397 1398 FT_COLOR_ROOT_TRANSFORM_MAX 1399 1400 } FT_Color_Root_Transform; 1401 1402 1403 /************************************************************************** 1404 * 1405 * @struct: 1406 * FT_ClipBox 1407 * 1408 * @description: 1409 * A structure representing a 'COLR' v1 'ClipBox' table. 'COLR' v1 1410 * glyphs may optionally define a clip box for aiding allocation or 1411 * defining a maximum drawable region. Use @FT_Get_Color_Glyph_ClipBox 1412 * to retrieve it. 1413 * 1414 * @fields: 1415 * bottom_left :: 1416 * The bottom left corner of the clip box as an @FT_Vector with 1417 * fixed-point coordinates in 26.6 format. 1418 * 1419 * top_left :: 1420 * The top left corner of the clip box as an @FT_Vector with 1421 * fixed-point coordinates in 26.6 format. 1422 * 1423 * top_right :: 1424 * The top right corner of the clip box as an @FT_Vector with 1425 * fixed-point coordinates in 26.6 format. 1426 * 1427 * bottom_right :: 1428 * The bottom right corner of the clip box as an @FT_Vector with 1429 * fixed-point coordinates in 26.6 format. 1430 * 1431 * @since: 1432 * 2.12 -- **currently experimental only!** There might be changes 1433 * without retaining backward compatibility of both the API and ABI. 1434 * 1435 */ 1436 typedef struct FT_ClipBox_ 1437 { 1438 FT_Vector bottom_left; 1439 FT_Vector top_left; 1440 FT_Vector top_right; 1441 FT_Vector bottom_right; 1442 1443 } FT_ClipBox; 1444 1445 1446 /************************************************************************** 1447 * 1448 * @function: 1449 * FT_Get_Color_Glyph_Paint 1450 * 1451 * @description: 1452 * This is the starting point and interface to color gradient 1453 * information in a 'COLR' v1 table in OpenType fonts to recursively 1454 * retrieve the paint tables for the directed acyclic graph of a colored 1455 * glyph, given a glyph ID. 1456 * 1457 * https://github.com/googlefonts/colr-gradients-spec 1458 * 1459 * In a 'COLR' v1 font, each color glyph defines a directed acyclic 1460 * graph of nested paint tables, such as `PaintGlyph`, `PaintSolid`, 1461 * `PaintLinearGradient`, `PaintRadialGradient`, and so on. Using this 1462 * function and specifying a glyph ID, one retrieves the root paint 1463 * table for this glyph ID. 1464 * 1465 * This function allows control whether an initial root transform is 1466 * returned to configure scaling, transform, and translation correctly 1467 * on the client's graphics context. The initial root transform is 1468 * computed and returned according to the values configured for @FT_Size 1469 * and @FT_Set_Transform on the @FT_Face object, see below for details 1470 * of the `root_transform` parameter. This has implications for a 1471 * client 'COLR' v1 implementation: When this function returns an 1472 * initially computed root transform, at the time of executing the 1473 * @FT_PaintGlyph operation, the contours should be retrieved using 1474 * @FT_Load_Glyph at unscaled, untransformed size. This is because the 1475 * root transform applied to the graphics context will take care of 1476 * correct scaling. 1477 * 1478 * Alternatively, to allow hinting of contours, at the time of executing 1479 * @FT_Load_Glyph, the current graphics context transformation matrix 1480 * can be decomposed into a scaling matrix and a remainder, and 1481 * @FT_Load_Glyph can be used to retrieve the contours at scaled size. 1482 * Care must then be taken to blit or clip to the graphics context with 1483 * taking this remainder transformation into account. 1484 * 1485 * @input: 1486 * face :: 1487 * A handle to the parent face object. 1488 * 1489 * base_glyph :: 1490 * The glyph index for which to retrieve the root paint table. 1491 * 1492 * root_transform :: 1493 * Specifies whether an initially computed root is returned by the 1494 * @FT_PaintTransform operation to account for the activated size 1495 * (see @FT_Activate_Size) and the configured transform and translate 1496 * (see @FT_Set_Transform). 1497 * 1498 * This root transform is returned before nodes of the glyph graph of 1499 * the font are returned. Subsequent @FT_COLR_Paint structures 1500 * contain unscaled and untransformed values. The inserted root 1501 * transform enables the client application to apply an initial 1502 * transform to its graphics context. When executing subsequent 1503 * FT_COLR_Paint operations, values from @FT_COLR_Paint operations 1504 * will ultimately be correctly scaled because of the root transform 1505 * applied to the graphics context. Use 1506 * @FT_COLOR_INCLUDE_ROOT_TRANSFORM to include the root transform, use 1507 * @FT_COLOR_NO_ROOT_TRANSFORM to not include it. The latter may be 1508 * useful when traversing the 'COLR' v1 glyph graph and reaching a 1509 * @FT_PaintColrGlyph. When recursing into @FT_PaintColrGlyph and 1510 * painting that inline, no additional root transform is needed as it 1511 * has already been applied to the graphics context at the beginning 1512 * of drawing this glyph. 1513 * 1514 * @output: 1515 * paint :: 1516 * The @FT_OpaquePaint object that references the actual paint table. 1517 * 1518 * The respective actual @FT_COLR_Paint object is retrieved via 1519 * @FT_Get_Paint. 1520 * 1521 * @return: 1522 * Value~1 if everything is OK. If no color glyph is found, or the root 1523 * paint could not be retrieved, value~0 gets returned. In case of an 1524 * error, value~0 is returned also. 1525 * 1526 * @since: 1527 * 2.11 -- **currently experimental only!** There might be changes 1528 * without retaining backward compatibility of both the API and ABI. 1529 * 1530 */ 1531 FT_EXPORT( FT_Bool ) 1532 FT_Get_Color_Glyph_Paint( FT_Face face, 1533 FT_UInt base_glyph, 1534 FT_Color_Root_Transform root_transform, 1535 FT_OpaquePaint* paint ); 1536 1537 1538 /************************************************************************** 1539 * 1540 * @function: 1541 * FT_Get_Color_Glyph_ClipBox 1542 * 1543 * @description: 1544 * Search for a 'COLR' v1 clip box for the specified `base_glyph` and 1545 * fill the `clip_box` parameter with the 'COLR' v1 'ClipBox' information 1546 * if one is found. 1547 * 1548 * @input: 1549 * face :: 1550 * A handle to the parent face object. 1551 * 1552 * base_glyph :: 1553 * The glyph index for which to retrieve the clip box. 1554 * 1555 * @output: 1556 * clip_box :: 1557 * The clip box for the requested `base_glyph` if one is found. The 1558 * clip box is computed taking scale and transformations configured on 1559 * the @FT_Face into account. @FT_ClipBox contains @FT_Vector values 1560 * in 26.6 format. 1561 * 1562 * @return: 1563 * Value~1 if a clip box is found. If no clip box is found or an error 1564 * occured, value~0 is returned. 1565 * 1566 * @note: 1567 * To retrieve the clip box in font units, reset scale to units-per-em 1568 * and remove transforms configured using @FT_Set_Transform. 1569 * 1570 * @since: 1571 * 2.12 -- **currently experimental only!** There might be changes 1572 * without retaining backward compatibility of both the API and ABI. 1573 * 1574 */ 1575 FT_EXPORT( FT_Bool ) 1576 FT_Get_Color_Glyph_ClipBox( FT_Face face, 1577 FT_UInt base_glyph, 1578 FT_ClipBox* clip_box ); 1579 1580 1581 /************************************************************************** 1582 * 1583 * @function: 1584 * FT_Get_Paint_Layers 1585 * 1586 * @description: 1587 * Access the layers of a `PaintColrLayers` table. 1588 * 1589 * If the root paint of a color glyph, or a nested paint of a 'COLR' 1590 * glyph is a `PaintColrLayers` table, this function retrieves the 1591 * layers of the `PaintColrLayers` table. 1592 * 1593 * The @FT_PaintColrLayers object contains an @FT_LayerIterator, which 1594 * is used here to iterate over the layers. Each layer is returned as 1595 * an @FT_OpaquePaint object, which then can be used with @FT_Get_Paint 1596 * to retrieve the actual paint object. 1597 * 1598 * @input: 1599 * face :: 1600 * A handle to the parent face object. 1601 * 1602 * @inout: 1603 * iterator :: 1604 * The @FT_LayerIterator from an @FT_PaintColrLayers object, for which 1605 * the layers are to be retrieved. The internal state of the iterator 1606 * is incremented after one call to this function for retrieving one 1607 * layer. 1608 * 1609 * @output: 1610 * paint :: 1611 * The @FT_OpaquePaint object that references the actual paint table. 1612 * The respective actual @FT_COLR_Paint object is retrieved via 1613 * @FT_Get_Paint. 1614 * 1615 * @return: 1616 * Value~1 if everything is OK. Value~0 gets returned when the paint 1617 * object can not be retrieved or any other error occurs. 1618 * 1619 * @since: 1620 * 2.11 -- **currently experimental only!** There might be changes 1621 * without retaining backward compatibility of both the API and ABI. 1622 * 1623 */ 1624 FT_EXPORT( FT_Bool ) 1625 FT_Get_Paint_Layers( FT_Face face, 1626 FT_LayerIterator* iterator, 1627 FT_OpaquePaint* paint ); 1628 1629 1630 /************************************************************************** 1631 * 1632 * @function: 1633 * FT_Get_Colorline_Stops 1634 * 1635 * @description: 1636 * This is an interface to color gradient information in a 'COLR' v1 1637 * table in OpenType fonts to iteratively retrieve the gradient and 1638 * solid fill information for colored glyph layers for a specified glyph 1639 * ID. 1640 * 1641 * https://github.com/googlefonts/colr-gradients-spec 1642 * 1643 * @input: 1644 * face :: 1645 * A handle to the parent face object. 1646 * 1647 * @inout: 1648 * iterator :: 1649 * The retrieved @FT_ColorStopIterator, configured on an @FT_ColorLine, 1650 * which in turn got retrieved via paint information in 1651 * @FT_PaintLinearGradient or @FT_PaintRadialGradient. 1652 * 1653 * @output: 1654 * color_stop :: 1655 * Color index and alpha value for the retrieved color stop. 1656 * 1657 * @return: 1658 * Value~1 if everything is OK. If there are no more color stops, 1659 * value~0 gets returned. In case of an error, value~0 is returned 1660 * also. 1661 * 1662 * @since: 1663 * 2.11 -- **currently experimental only!** There might be changes 1664 * without retaining backward compatibility of both the API and ABI. 1665 * 1666 */ 1667 FT_EXPORT( FT_Bool ) 1668 FT_Get_Colorline_Stops( FT_Face face, 1669 FT_ColorStop* color_stop, 1670 FT_ColorStopIterator* iterator ); 1671 1672 1673 /************************************************************************** 1674 * 1675 * @function: 1676 * FT_Get_Paint 1677 * 1678 * @description: 1679 * Access the details of a paint using an @FT_OpaquePaint opaque paint 1680 * object, which internally stores the offset to the respective `Paint` 1681 * object in the 'COLR' table. 1682 * 1683 * @input: 1684 * face :: 1685 * A handle to the parent face object. 1686 * 1687 * opaque_paint :: 1688 * The opaque paint object for which the underlying @FT_COLR_Paint 1689 * data is to be retrieved. 1690 * 1691 * @output: 1692 * paint :: 1693 * The specific @FT_COLR_Paint object containing information coming 1694 * from one of the font's `Paint*` tables. 1695 * 1696 * @return: 1697 * Value~1 if everything is OK. Value~0 if no details can be found for 1698 * this paint or any other error occured. 1699 * 1700 * @since: 1701 * 2.11 -- **currently experimental only!** There might be changes 1702 * without retaining backward compatibility of both the API and ABI. 1703 * 1704 */ 1705 FT_EXPORT( FT_Bool ) 1706 FT_Get_Paint( FT_Face face, 1707 FT_OpaquePaint opaque_paint, 1708 FT_COLR_Paint* paint ); 1709 1710 /* */ 1711 1712 1713 FT_END_HEADER 1714 1715 #endif /* FTCOLOR_H_ */ 1716 1717 1718 /* END */ 1719