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