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 */ | 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 */ |