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