1 /**************************************************************************** 2 * 3 * ftmm.h 4 * 5 * FreeType Multiple Master font interface (specification). 6 * 7 * Copyright (C) 1996-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 FTMM_H_ 20 #define FTMM_H_ 21 22 23 #include <freetype/t1tables.h> 24 25 26 FT_BEGIN_HEADER 27 28 29 /************************************************************************** 30 * 31 * @section: 32 * multiple_masters 33 * 34 * @title: 35 * Multiple Masters 36 * 37 * @abstract: 38 * How to manage Multiple Masters fonts. 39 * 40 * @description: 41 * The following types and functions are used to manage Multiple Master 42 * fonts, i.e., the selection of specific design instances by setting 43 * design axis coordinates. 44 * 45 * Besides Adobe MM fonts, the interface supports Apple's TrueType GX and 46 * OpenType variation fonts. Some of the routines only work with Adobe 47 * MM fonts, others will work with all three types. They are similar 48 * enough that a consistent interface makes sense. 49 * 50 * For Adobe MM fonts, macro @FT_IS_SFNT returns false. For GX and 51 * OpenType variation fonts, it returns true. 52 * 53 */ 54 55 56 /************************************************************************** 57 * 58 * @struct: 59 * FT_MM_Axis 60 * 61 * @description: 62 * A structure to model a given axis in design space for Multiple Masters 63 * fonts. 64 * 65 * This structure can't be used for TrueType GX or OpenType variation 66 * fonts. 67 * 68 * @fields: 69 * name :: 70 * The axis's name. 71 * 72 * minimum :: 73 * The axis's minimum design coordinate. 74 * 75 * maximum :: 76 * The axis's maximum design coordinate. 77 */ 78 typedef struct FT_MM_Axis_ 79 { 80 FT_String* name; 81 FT_Long minimum; 82 FT_Long maximum; 83 84 } FT_MM_Axis; 85 86 87 /************************************************************************** 88 * 89 * @struct: 90 * FT_Multi_Master 91 * 92 * @description: 93 * A structure to model the axes and space of a Multiple Masters font. 94 * 95 * This structure can't be used for TrueType GX or OpenType variation 96 * fonts. 97 * 98 * @fields: 99 * num_axis :: 100 * Number of axes. Cannot exceed~4. 101 * 102 * num_designs :: 103 * Number of designs; should be normally 2^num_axis even though the 104 * Type~1 specification strangely allows for intermediate designs to be 105 * present. This number cannot exceed~16. 106 * 107 * axis :: 108 * A table of axis descriptors. 109 */ 110 typedef struct FT_Multi_Master_ 111 { 112 FT_UInt num_axis; 113 FT_UInt num_designs; 114 FT_MM_Axis axis[T1_MAX_MM_AXIS]; 115 116 } FT_Multi_Master; 117 118 119 /************************************************************************** 120 * 121 * @struct: 122 * FT_Var_Axis 123 * 124 * @description: 125 * A structure to model a given axis in design space for Multiple 126 * Masters, TrueType GX, and OpenType variation fonts. 127 * 128 * @fields: 129 * name :: 130 * The axis's name. Not always meaningful for TrueType GX or OpenType 131 * variation fonts. 132 * 133 * minimum :: 134 * The axis's minimum design coordinate. 135 * 136 * def :: 137 * The axis's default design coordinate. FreeType computes meaningful 138 * default values for Adobe MM fonts. 139 * 140 * maximum :: 141 * The axis's maximum design coordinate. 142 * 143 * tag :: 144 * The axis's tag (the equivalent to 'name' for TrueType GX and 145 * OpenType variation fonts). FreeType provides default values for 146 * Adobe MM fonts if possible. 147 * 148 * strid :: 149 * The axis name entry in the font's 'name' table. This is another 150 * (and often better) version of the 'name' field for TrueType GX or 151 * OpenType variation fonts. Not meaningful for Adobe MM fonts. 152 * 153 * @note: 154 * The fields `minimum`, `def`, and `maximum` are 16.16 fractional values 155 * for TrueType GX and OpenType variation fonts. For Adobe MM fonts, the 156 * values are whole numbers (i.e., the fractional part is zero). 157 */ 158 typedef struct FT_Var_Axis_ 159 { 160 FT_String* name; 161 162 FT_Fixed minimum; 163 FT_Fixed def; 164 FT_Fixed maximum; 165 166 FT_ULong tag; 167 FT_UInt strid; 168 169 } FT_Var_Axis; 170 171 172 /************************************************************************** 173 * 174 * @struct: 175 * FT_Var_Named_Style 176 * 177 * @description: 178 * A structure to model a named instance in a TrueType GX or OpenType 179 * variation font. 180 * 181 * This structure can't be used for Adobe MM fonts. 182 * 183 * @fields: 184 * coords :: 185 * The design coordinates for this instance. This is an array with one 186 * entry for each axis. 187 * 188 * strid :: 189 * The entry in 'name' table identifying this instance. 190 * 191 * psid :: 192 * The entry in 'name' table identifying a PostScript name for this 193 * instance. Value 0xFFFF indicates a missing entry. 194 */ 195 typedef struct FT_Var_Named_Style_ 196 { 197 FT_Fixed* coords; 198 FT_UInt strid; 199 FT_UInt psid; /* since 2.7.1 */ 200 201 } FT_Var_Named_Style; 202 203 204 /************************************************************************** 205 * 206 * @struct: 207 * FT_MM_Var 208 * 209 * @description: 210 * A structure to model the axes and space of an Adobe MM, TrueType GX, 211 * or OpenType variation font. 212 * 213 * Some fields are specific to one format and not to the others. 214 * 215 * @fields: 216 * num_axis :: 217 * The number of axes. The maximum value is~4 for Adobe MM fonts; no 218 * limit in TrueType GX or OpenType variation fonts. 219 * 220 * num_designs :: 221 * The number of designs; should be normally 2^num_axis for Adobe MM 222 * fonts. Not meaningful for TrueType GX or OpenType variation fonts 223 * (where every glyph could have a different number of designs). 224 * 225 * num_namedstyles :: 226 * The number of named styles; a 'named style' is a tuple of design 227 * coordinates that has a string ID (in the 'name' table) associated 228 * with it. The font can tell the user that, for example, 229 * [Weight=1.5,Width=1.1] is 'Bold'. Another name for 'named style' is 230 * 'named instance'. 231 * 232 * For Adobe Multiple Masters fonts, this value is always zero because 233 * the format does not support named styles. 234 * 235 * axis :: 236 * An axis descriptor table. TrueType GX and OpenType variation fonts 237 * contain slightly more data than Adobe MM fonts. Memory management 238 * of this pointer is done internally by FreeType. 239 * 240 * namedstyle :: 241 * A named style (instance) table. Only meaningful for TrueType GX and 242 * OpenType variation fonts. Memory management of this pointer is done 243 * internally by FreeType. 244 */ 245 typedef struct FT_MM_Var_ 246 { 247 FT_UInt num_axis; 248 FT_UInt num_designs; 249 FT_UInt num_namedstyles; 250 FT_Var_Axis* axis; 251 FT_Var_Named_Style* namedstyle; 252 253 } FT_MM_Var; 254 255 256 /************************************************************************** 257 * 258 * @function: 259 * FT_Get_Multi_Master 260 * 261 * @description: 262 * Retrieve a variation descriptor of a given Adobe MM font. 263 * 264 * This function can't be used with TrueType GX or OpenType variation 265 * fonts. 266 * 267 * @input: 268 * face :: 269 * A handle to the source face. 270 * 271 * @output: 272 * amaster :: 273 * The Multiple Masters descriptor. 274 * 275 * @return: 276 * FreeType error code. 0~means success. 277 */ 278 FT_EXPORT( FT_Error ) 279 FT_Get_Multi_Master( FT_Face face, 280 FT_Multi_Master *amaster ); 281 282 283 /************************************************************************** 284 * 285 * @function: 286 * FT_Get_MM_Var 287 * 288 * @description: 289 * Retrieve a variation descriptor for a given font. 290 * 291 * This function works with all supported variation formats. 292 * 293 * @input: 294 * face :: 295 * A handle to the source face. 296 * 297 * @output: 298 * amaster :: 299 * The variation descriptor. Allocates a data structure, which the 300 * user must deallocate with a call to @FT_Done_MM_Var after use. 301 * 302 * @return: 303 * FreeType error code. 0~means success. 304 */ 305 FT_EXPORT( FT_Error ) 306 FT_Get_MM_Var( FT_Face face, 307 FT_MM_Var* *amaster ); 308 309 310 /************************************************************************** 311 * 312 * @function: 313 * FT_Done_MM_Var 314 * 315 * @description: 316 * Free the memory allocated by @FT_Get_MM_Var. 317 * 318 * @input: 319 * library :: 320 * A handle of the face's parent library object that was used in the 321 * call to @FT_Get_MM_Var to create `amaster`. 322 * 323 * @return: 324 * FreeType error code. 0~means success. 325 */ 326 FT_EXPORT( FT_Error ) 327 FT_Done_MM_Var( FT_Library library, 328 FT_MM_Var *amaster ); 329 330 331 /************************************************************************** 332 * 333 * @function: 334 * FT_Set_MM_Design_Coordinates 335 * 336 * @description: 337 * For Adobe MM fonts, choose an interpolated font design through design 338 * coordinates. 339 * 340 * This function can't be used with TrueType GX or OpenType variation 341 * fonts. 342 * 343 * @inout: 344 * face :: 345 * A handle to the source face. 346 * 347 * @input: 348 * num_coords :: 349 * The number of available design coordinates. If it is larger than 350 * the number of axes, ignore the excess values. If it is smaller than 351 * the number of axes, use default values for the remaining axes. 352 * 353 * coords :: 354 * An array of design coordinates. 355 * 356 * @return: 357 * FreeType error code. 0~means success. 358 * 359 * @note: 360 * [Since 2.8.1] To reset all axes to the default values, call the 361 * function with `num_coords` set to zero and `coords` set to `NULL`. 362 * 363 * [Since 2.9] If `num_coords` is larger than zero, this function sets 364 * the @FT_FACE_FLAG_VARIATION bit in @FT_Face's `face_flags` field 365 * (i.e., @FT_IS_VARIATION will return true). If `num_coords` is zero, 366 * this bit flag gets unset. 367 */ 368 FT_EXPORT( FT_Error ) 369 FT_Set_MM_Design_Coordinates( FT_Face face, 370 FT_UInt num_coords, 371 FT_Long* coords ); 372 373 374 /************************************************************************** 375 * 376 * @function: 377 * FT_Set_Var_Design_Coordinates 378 * 379 * @description: 380 * Choose an interpolated font design through design coordinates. 381 * 382 * This function works with all supported variation formats. 383 * 384 * @inout: 385 * face :: 386 * A handle to the source face. 387 * 388 * @input: 389 * num_coords :: 390 * The number of available design coordinates. If it is larger than 391 * the number of axes, ignore the excess values. If it is smaller than 392 * the number of axes, use default values for the remaining axes. 393 * 394 * coords :: 395 * An array of design coordinates. 396 * 397 * @return: 398 * FreeType error code. 0~means success. 399 * 400 * @note: 401 * The design coordinates are 16.16 fractional values for TrueType GX and 402 * OpenType variation fonts. For Adobe MM fonts, the values are supposed 403 * to be whole numbers (i.e., the fractional part is zero). 404 * 405 * [Since 2.8.1] To reset all axes to the default values, call the 406 * function with `num_coords` set to zero and `coords` set to `NULL`. 407 * [Since 2.9] 'Default values' means the currently selected named 408 * instance (or the base font if no named instance is selected). 409 * 410 * [Since 2.9] If `num_coords` is larger than zero, this function sets 411 * the @FT_FACE_FLAG_VARIATION bit in @FT_Face's `face_flags` field 412 * (i.e., @FT_IS_VARIATION will return true). If `num_coords` is zero, 413 * this bit flag gets unset. 414 */ 415 FT_EXPORT( FT_Error ) 416 FT_Set_Var_Design_Coordinates( FT_Face face, 417 FT_UInt num_coords, 418 FT_Fixed* coords ); 419 420 421 /************************************************************************** 422 * 423 * @function: 424 * FT_Get_Var_Design_Coordinates 425 * 426 * @description: 427 * Get the design coordinates of the currently selected interpolated 428 * font. 429 * 430 * This function works with all supported variation formats. 431 * 432 * @input: 433 * face :: 434 * A handle to the source face. 435 * 436 * num_coords :: 437 * The number of design coordinates to retrieve. If it is larger than 438 * the number of axes, set the excess values to~0. 439 * 440 * @output: 441 * coords :: 442 * The design coordinates array. 443 * 444 * @return: 445 * FreeType error code. 0~means success. 446 * 447 * @note: 448 * The design coordinates are 16.16 fractional values for TrueType GX and 449 * OpenType variation fonts. For Adobe MM fonts, the values are whole 450 * numbers (i.e., the fractional part is zero). 451 * 452 * @since: 453 * 2.7.1 454 */ 455 FT_EXPORT( FT_Error ) 456 FT_Get_Var_Design_Coordinates( FT_Face face, 457 FT_UInt num_coords, 458 FT_Fixed* coords ); 459 460 461 /************************************************************************** 462 * 463 * @function: 464 * FT_Set_MM_Blend_Coordinates 465 * 466 * @description: 467 * Choose an interpolated font design through normalized blend 468 * coordinates. 469 * 470 * This function works with all supported variation formats. 471 * 472 * @inout: 473 * face :: 474 * A handle to the source face. 475 * 476 * @input: 477 * num_coords :: 478 * The number of available design coordinates. If it is larger than 479 * the number of axes, ignore the excess values. If it is smaller than 480 * the number of axes, use default values for the remaining axes. 481 * 482 * coords :: 483 * The design coordinates array. Each element is a 16.16 fractional 484 * value and must be between 0 and 1.0 for Adobe MM fonts, and between 485 * -1.0 and 1.0 for TrueType GX and OpenType variation fonts. 486 * 487 * @return: 488 * FreeType error code. 0~means success. 489 * 490 * @note: 491 * [Since 2.8.1] To reset all axes to the default values, call the 492 * function with `num_coords` set to zero and `coords` set to `NULL`. 493 * [Since 2.9] 'Default values' means the currently selected named 494 * instance (or the base font if no named instance is selected). 495 * 496 * [Since 2.9] If `num_coords` is larger than zero, this function sets 497 * the @FT_FACE_FLAG_VARIATION bit in @FT_Face's `face_flags` field 498 * (i.e., @FT_IS_VARIATION will return true). If `num_coords` is zero, 499 * this bit flag gets unset. 500 */ 501 FT_EXPORT( FT_Error ) 502 FT_Set_MM_Blend_Coordinates( FT_Face face, 503 FT_UInt num_coords, 504 FT_Fixed* coords ); 505 506 507 /************************************************************************** 508 * 509 * @function: 510 * FT_Get_MM_Blend_Coordinates 511 * 512 * @description: 513 * Get the normalized blend coordinates of the currently selected 514 * interpolated font. 515 * 516 * This function works with all supported variation formats. 517 * 518 * @input: 519 * face :: 520 * A handle to the source face. 521 * 522 * num_coords :: 523 * The number of normalized blend coordinates to retrieve. If it is 524 * larger than the number of axes, set the excess values to~0.5 for 525 * Adobe MM fonts, and to~0 for TrueType GX and OpenType variation 526 * fonts. 527 * 528 * @output: 529 * coords :: 530 * The normalized blend coordinates array (as 16.16 fractional values). 531 * 532 * @return: 533 * FreeType error code. 0~means success. 534 * 535 * @since: 536 * 2.7.1 537 */ 538 FT_EXPORT( FT_Error ) 539 FT_Get_MM_Blend_Coordinates( FT_Face face, 540 FT_UInt num_coords, 541 FT_Fixed* coords ); 542 543 544 /************************************************************************** 545 * 546 * @function: 547 * FT_Set_Var_Blend_Coordinates 548 * 549 * @description: 550 * This is another name of @FT_Set_MM_Blend_Coordinates. 551 */ 552 FT_EXPORT( FT_Error ) 553 FT_Set_Var_Blend_Coordinates( FT_Face face, 554 FT_UInt num_coords, 555 FT_Fixed* coords ); 556 557 558 /************************************************************************** 559 * 560 * @function: 561 * FT_Get_Var_Blend_Coordinates 562 * 563 * @description: 564 * This is another name of @FT_Get_MM_Blend_Coordinates. 565 * 566 * @since: 567 * 2.7.1 568 */ 569 FT_EXPORT( FT_Error ) 570 FT_Get_Var_Blend_Coordinates( FT_Face face, 571 FT_UInt num_coords, 572 FT_Fixed* coords ); 573 574 575 /************************************************************************** 576 * 577 * @function: 578 * FT_Set_MM_WeightVector 579 * 580 * @description: 581 * For Adobe MM fonts, choose an interpolated font design by directly 582 * setting the weight vector. 583 * 584 * This function can't be used with TrueType GX or OpenType variation 585 * fonts. 586 * 587 * @inout: 588 * face :: 589 * A handle to the source face. 590 * 591 * @input: 592 * len :: 593 * The length of the weight vector array. If it is larger than the 594 * number of designs, the extra values are ignored. If it is less than 595 * the number of designs, the remaining values are set to zero. 596 * 597 * weightvector :: 598 * An array representing the weight vector. 599 * 600 * @return: 601 * FreeType error code. 0~means success. 602 * 603 * @note: 604 * Adobe Multiple Master fonts limit the number of designs, and thus the 605 * length of the weight vector to 16~elements. 606 * 607 * If `len` is larger than zero, this function sets the 608 * @FT_FACE_FLAG_VARIATION bit in @FT_Face's `face_flags` field (i.e., 609 * @FT_IS_VARIATION will return true). If `len` is zero, this bit flag 610 * is unset and the weight vector array is reset to the default values. 611 * 612 * The Adobe documentation also states that the values in the 613 * WeightVector array must total 1.0 +/-~0.001. In practice this does 614 * not seem to be enforced, so is not enforced here, either. 615 * 616 * @since: 617 * 2.10 618 */ 619 FT_EXPORT( FT_Error ) 620 FT_Set_MM_WeightVector( FT_Face face, 621 FT_UInt len, 622 FT_Fixed* weightvector ); 623 624 625 /************************************************************************** 626 * 627 * @function: 628 * FT_Get_MM_WeightVector 629 * 630 * @description: 631 * For Adobe MM fonts, retrieve the current weight vector of the font. 632 * 633 * This function can't be used with TrueType GX or OpenType variation 634 * fonts. 635 * 636 * @inout: 637 * face :: 638 * A handle to the source face. 639 * 640 * len :: 641 * A pointer to the size of the array to be filled. If the size of the 642 * array is less than the number of designs, `FT_Err_Invalid_Argument` 643 * is returned, and `len` is set to the required size (the number of 644 * designs). If the size of the array is greater than the number of 645 * designs, the remaining entries are set to~0. On successful 646 * completion, `len` is set to the number of designs (i.e., the number 647 * of values written to the array). 648 * 649 * @output: 650 * weightvector :: 651 * An array to be filled. 652 * 653 * @return: 654 * FreeType error code. 0~means success. 655 * 656 * @note: 657 * Adobe Multiple Master fonts limit the number of designs, and thus the 658 * length of the WeightVector to~16. 659 * 660 * @since: 661 * 2.10 662 */ 663 FT_EXPORT( FT_Error ) 664 FT_Get_MM_WeightVector( FT_Face face, 665 FT_UInt* len, 666 FT_Fixed* weightvector ); 667 668 669 /************************************************************************** 670 * 671 * @enum: 672 * FT_VAR_AXIS_FLAG_XXX 673 * 674 * @description: 675 * A list of bit flags used in the return value of 676 * @FT_Get_Var_Axis_Flags. 677 * 678 * @values: 679 * FT_VAR_AXIS_FLAG_HIDDEN :: 680 * The variation axis should not be exposed to user interfaces. 681 * 682 * @since: 683 * 2.8.1 684 */ 685 #define FT_VAR_AXIS_FLAG_HIDDEN 1 686 687 688 /************************************************************************** 689 * 690 * @function: 691 * FT_Get_Var_Axis_Flags 692 * 693 * @description: 694 * Get the 'flags' field of an OpenType Variation Axis Record. 695 * 696 * Not meaningful for Adobe MM fonts (`*flags` is always zero). 697 * 698 * @input: 699 * master :: 700 * The variation descriptor. 701 * 702 * axis_index :: 703 * The index of the requested variation axis. 704 * 705 * @output: 706 * flags :: 707 * The 'flags' field. See @FT_VAR_AXIS_FLAG_XXX for possible values. 708 * 709 * @return: 710 * FreeType error code. 0~means success. 711 * 712 * @since: 713 * 2.8.1 714 */ 715 FT_EXPORT( FT_Error ) 716 FT_Get_Var_Axis_Flags( FT_MM_Var* master, 717 FT_UInt axis_index, 718 FT_UInt* flags ); 719 720 721 /************************************************************************** 722 * 723 * @function: 724 * FT_Set_Named_Instance 725 * 726 * @description: 727 * Set or change the current named instance. 728 * 729 * @input: 730 * face :: 731 * A handle to the source face. 732 * 733 * instance_index :: 734 * The index of the requested instance, starting with value 1. If set 735 * to value 0, FreeType switches to font access without a named 736 * instance. 737 * 738 * @return: 739 * FreeType error code. 0~means success. 740 * 741 * @note: 742 * The function uses the value of `instance_index` to set bits 16-30 of 743 * the face's `face_index` field. It also resets any variation applied 744 * to the font, and the @FT_FACE_FLAG_VARIATION bit of the face's 745 * `face_flags` field gets reset to zero (i.e., @FT_IS_VARIATION will 746 * return false). 747 * 748 * For Adobe MM fonts (which don't have named instances) this function 749 * simply resets the current face to the default instance. 750 * 751 * @since: 752 * 2.9 753 */ 754 FT_EXPORT( FT_Error ) 755 FT_Set_Named_Instance( FT_Face face, 756 FT_UInt instance_index ); 757 758 759 /************************************************************************** 760 * 761 * @function: 762 * FT_Get_Default_Named_Instance 763 * 764 * @description: 765 * Retrieve the index of the default named instance, to be used with 766 * @FT_Set_Named_Instance. 767 * 768 * The default instance of a variation font is that instance for which 769 * the nth axis coordinate is equal to `axis[n].def` (as specified in the 770 * @FT_MM_Var structure), with~n covering all axes. 771 * 772 * FreeType synthesizes a named instance for the default instance if the 773 * font does not contain such an entry. 774 * 775 * @input: 776 * face :: 777 * A handle to the source face. 778 * 779 * @output: 780 * instance_index :: 781 * The index of the default named instance. 782 * 783 * @return: 784 * FreeType error code. 0~means success. 785 * 786 * @note: 787 * For Adobe MM fonts (which don't have named instances) this function 788 * always returns zero for `instance_index`. 789 * 790 * @since: 791 * 2.13.1 792 */ 793 FT_EXPORT( FT_Error ) 794 FT_Get_Default_Named_Instance( FT_Face face, 795 FT_UInt *instance_index ); 796 797 /* */ 798 799 800 FT_END_HEADER 801 802 #endif /* FTMM_H_ */ 803 804 805 /* END */ 806