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