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