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