1 /**************************************************************************** 2 * 3 * ftmm.h 4 * 5 * FreeType Multiple Master font interface (specification). 6 * 7 * Copyright (C) 1996-2022 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 integers. 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 * [Since 2.8.1] To reset all axes to the default values, call the 402 * function with `num_coords` set to zero and `coords` set to `NULL`. 403 * [Since 2.9] 'Default values' means the currently selected named 404 * instance (or the base font if no named instance is selected). 405 * 406 * [Since 2.9] If `num_coords` is larger than zero, this function sets 407 * the @FT_FACE_FLAG_VARIATION bit in @FT_Face's `face_flags` field 408 * (i.e., @FT_IS_VARIATION will return true). If `num_coords` is zero, 409 * this bit flag gets unset. 410 */ 411 FT_EXPORT( FT_Error ) 412 FT_Set_Var_Design_Coordinates( FT_Face face, 413 FT_UInt num_coords, 414 FT_Fixed* coords ); 415 416 417 /************************************************************************** 418 * 419 * @function: 420 * FT_Get_Var_Design_Coordinates 421 * 422 * @description: 423 * Get the design coordinates of the currently selected interpolated 424 * font. 425 * 426 * This function works with all supported variation formats. 427 * 428 * @input: 429 * face :: 430 * A handle to the source face. 431 * 432 * num_coords :: 433 * The number of design coordinates to retrieve. If it is larger than 434 * the number of axes, set the excess values to~0. 435 * 436 * @output: 437 * coords :: 438 * The design coordinates array. 439 * 440 * @return: 441 * FreeType error code. 0~means success. 442 * 443 * @since: 444 * 2.7.1 445 */ 446 FT_EXPORT( FT_Error ) 447 FT_Get_Var_Design_Coordinates( FT_Face face, 448 FT_UInt num_coords, 449 FT_Fixed* coords ); 450 451 452 /************************************************************************** 453 * 454 * @function: 455 * FT_Set_MM_Blend_Coordinates 456 * 457 * @description: 458 * Choose an interpolated font design through normalized blend 459 * coordinates. 460 * 461 * This function works with all supported variation formats. 462 * 463 * @inout: 464 * face :: 465 * A handle to the source face. 466 * 467 * @input: 468 * num_coords :: 469 * The number of available design coordinates. If it is larger than 470 * the number of axes, ignore the excess values. If it is smaller than 471 * the number of axes, use default values for the remaining axes. 472 * 473 * coords :: 474 * The design coordinates array (each element must be between 0 and 1.0 475 * for Adobe MM fonts, and between -1.0 and 1.0 for TrueType GX and 476 * OpenType variation fonts). 477 * 478 * @return: 479 * FreeType error code. 0~means success. 480 * 481 * @note: 482 * [Since 2.8.1] To reset all axes to the default values, call the 483 * function with `num_coords` set to zero and `coords` set to `NULL`. 484 * [Since 2.9] 'Default values' means the currently selected named 485 * instance (or the base font if no named instance is selected). 486 * 487 * [Since 2.9] If `num_coords` is larger than zero, this function sets 488 * the @FT_FACE_FLAG_VARIATION bit in @FT_Face's `face_flags` field 489 * (i.e., @FT_IS_VARIATION will return true). If `num_coords` is zero, 490 * this bit flag gets unset. 491 */ 492 FT_EXPORT( FT_Error ) 493 FT_Set_MM_Blend_Coordinates( FT_Face face, 494 FT_UInt num_coords, 495 FT_Fixed* coords ); 496 497 498 /************************************************************************** 499 * 500 * @function: 501 * FT_Get_MM_Blend_Coordinates 502 * 503 * @description: 504 * Get the normalized blend coordinates of the currently selected 505 * interpolated font. 506 * 507 * This function works with all supported variation formats. 508 * 509 * @input: 510 * face :: 511 * A handle to the source face. 512 * 513 * num_coords :: 514 * The number of normalized blend coordinates to retrieve. If it is 515 * larger than the number of axes, set the excess values to~0.5 for 516 * Adobe MM fonts, and to~0 for TrueType GX and OpenType variation 517 * fonts. 518 * 519 * @output: 520 * coords :: 521 * The normalized blend coordinates array. 522 * 523 * @return: 524 * FreeType error code. 0~means success. 525 * 526 * @since: 527 * 2.7.1 528 */ 529 FT_EXPORT( FT_Error ) 530 FT_Get_MM_Blend_Coordinates( FT_Face face, 531 FT_UInt num_coords, 532 FT_Fixed* coords ); 533 534 535 /************************************************************************** 536 * 537 * @function: 538 * FT_Set_Var_Blend_Coordinates 539 * 540 * @description: 541 * This is another name of @FT_Set_MM_Blend_Coordinates. 542 */ 543 FT_EXPORT( FT_Error ) 544 FT_Set_Var_Blend_Coordinates( FT_Face face, 545 FT_UInt num_coords, 546 FT_Fixed* coords ); 547 548 549 /************************************************************************** 550 * 551 * @function: 552 * FT_Get_Var_Blend_Coordinates 553 * 554 * @description: 555 * This is another name of @FT_Get_MM_Blend_Coordinates. 556 * 557 * @since: 558 * 2.7.1 559 */ 560 FT_EXPORT( FT_Error ) 561 FT_Get_Var_Blend_Coordinates( FT_Face face, 562 FT_UInt num_coords, 563 FT_Fixed* coords ); 564 565 566 /************************************************************************** 567 * 568 * @function: 569 * FT_Set_MM_WeightVector 570 * 571 * @description: 572 * For Adobe MM fonts, choose an interpolated font design by directly 573 * setting the weight vector. 574 * 575 * This function can't be used with TrueType GX or OpenType variation 576 * fonts. 577 * 578 * @inout: 579 * face :: 580 * A handle to the source face. 581 * 582 * @input: 583 * len :: 584 * The length of the weight vector array. If it is larger than the 585 * number of designs, the extra values are ignored. If it is less than 586 * the number of designs, the remaining values are set to zero. 587 * 588 * weightvector :: 589 * An array representing the weight vector. 590 * 591 * @return: 592 * FreeType error code. 0~means success. 593 * 594 * @note: 595 * Adobe Multiple Master fonts limit the number of designs, and thus the 596 * length of the weight vector to~16. 597 * 598 * If `len` is zero and `weightvector` is `NULL`, the weight vector array 599 * is reset to the default values. 600 * 601 * The Adobe documentation also states that the values in the 602 * WeightVector array must total 1.0 +/-~0.001. In practice this does 603 * not seem to be enforced, so is not enforced here, either. 604 * 605 * @since: 606 * 2.10 607 */ 608 FT_EXPORT( FT_Error ) 609 FT_Set_MM_WeightVector( FT_Face face, 610 FT_UInt len, 611 FT_Fixed* weightvector ); 612 613 614 /************************************************************************** 615 * 616 * @function: 617 * FT_Get_MM_WeightVector 618 * 619 * @description: 620 * For Adobe MM fonts, retrieve the current weight vector of the font. 621 * 622 * This function can't be used with TrueType GX or OpenType variation 623 * fonts. 624 * 625 * @inout: 626 * face :: 627 * A handle to the source face. 628 * 629 * len :: 630 * A pointer to the size of the array to be filled. If the size of the 631 * array is less than the number of designs, `FT_Err_Invalid_Argument` 632 * is returned, and `len` is set to the required size (the number of 633 * designs). If the size of the array is greater than the number of 634 * designs, the remaining entries are set to~0. On successful 635 * completion, `len` is set to the number of designs (i.e., the number 636 * of values written to the array). 637 * 638 * @output: 639 * weightvector :: 640 * An array to be filled. 641 * 642 * @return: 643 * FreeType error code. 0~means success. 644 * 645 * @note: 646 * Adobe Multiple Master fonts limit the number of designs, and thus the 647 * length of the WeightVector to~16. 648 * 649 * @since: 650 * 2.10 651 */ 652 FT_EXPORT( FT_Error ) 653 FT_Get_MM_WeightVector( FT_Face face, 654 FT_UInt* len, 655 FT_Fixed* weightvector ); 656 657 658 /************************************************************************** 659 * 660 * @enum: 661 * FT_VAR_AXIS_FLAG_XXX 662 * 663 * @description: 664 * A list of bit flags used in the return value of 665 * @FT_Get_Var_Axis_Flags. 666 * 667 * @values: 668 * FT_VAR_AXIS_FLAG_HIDDEN :: 669 * The variation axis should not be exposed to user interfaces. 670 * 671 * @since: 672 * 2.8.1 673 */ 674 #define FT_VAR_AXIS_FLAG_HIDDEN 1 675 676 677 /************************************************************************** 678 * 679 * @function: 680 * FT_Get_Var_Axis_Flags 681 * 682 * @description: 683 * Get the 'flags' field of an OpenType Variation Axis Record. 684 * 685 * Not meaningful for Adobe MM fonts (`*flags` is always zero). 686 * 687 * @input: 688 * master :: 689 * The variation descriptor. 690 * 691 * axis_index :: 692 * The index of the requested variation axis. 693 * 694 * @output: 695 * flags :: 696 * The 'flags' field. See @FT_VAR_AXIS_FLAG_XXX for possible values. 697 * 698 * @return: 699 * FreeType error code. 0~means success. 700 * 701 * @since: 702 * 2.8.1 703 */ 704 FT_EXPORT( FT_Error ) 705 FT_Get_Var_Axis_Flags( FT_MM_Var* master, 706 FT_UInt axis_index, 707 FT_UInt* flags ); 708 709 710 /************************************************************************** 711 * 712 * @function: 713 * FT_Set_Named_Instance 714 * 715 * @description: 716 * Set or change the current named instance. 717 * 718 * @input: 719 * face :: 720 * A handle to the source face. 721 * 722 * instance_index :: 723 * The index of the requested instance, starting with value 1. If set 724 * to value 0, FreeType switches to font access without a named 725 * instance. 726 * 727 * @return: 728 * FreeType error code. 0~means success. 729 * 730 * @note: 731 * The function uses the value of `instance_index` to set bits 16-30 of 732 * the face's `face_index` field. It also resets any variation applied 733 * to the font, and the @FT_FACE_FLAG_VARIATION bit of the face's 734 * `face_flags` field gets reset to zero (i.e., @FT_IS_VARIATION will 735 * return false). 736 * 737 * For Adobe MM fonts (which don't have named instances) this function 738 * simply resets the current face to the default instance. 739 * 740 * @since: 741 * 2.9 742 */ 743 FT_EXPORT( FT_Error ) 744 FT_Set_Named_Instance( FT_Face face, 745 FT_UInt instance_index ); 746 747 /* */ 748 749 750 FT_END_HEADER 751 752 #endif /* FTMM_H_ */ 753 754 755 /* END */ 756
