include/freetype/ftmm.h

   1 /***************************************************************************/
   2 /*                                                                         */
   3 /*  ftmm.h                                                                 */
   4 /*                                                                         */
   5 /*    FreeType Multiple Master font interface (specification).             */
   6 /*                                                                         */
   7 /*  Copyright 1996-2017 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.                                       */
 182   /*                                                                       */
 183   typedef struct  FT_Var_Named_Style_
 184   {
 185     FT_Fixed*  coords;
 186     FT_UInt    strid;
 187     FT_UInt    psid;   /* since 2.7.1 */
 188
 189   } FT_Var_Named_Style;
 190
 191
 192   /*************************************************************************/
 193   /*                                                                       */
 194   /* <Struct>                                                              */
 195   /*    FT_MM_Var                                                          */
 196   /*                                                                       */
 197   /* <Description>                                                         */
 198   /*    A structure to model the axes and space of a Adobe MM, TrueType    */
 199   /*    GX, or OpenType variation font.                                    */
 200   /*                                                                       */
 201   /*    Some fields are specific to one format and not to the others.      */
 202   /*                                                                       */
 203   /* <Fields>                                                              */
 204   /*    num_axis        :: The number of axes.  The maximum value is~4 for */
 205   /*                       Adobe MM fonts; no limit in TrueType GX or      */
 206   /*                       OpenType variation fonts.                       */
 207   /*                                                                       */
 208   /*    num_designs     :: The number of designs; should be normally       */
 209   /*                       2^num_axis for Adobe MM fonts.  Not meaningful  */
 210   /*                       for TrueType GX or OpenType variation fonts     */
 211   /*                       (where every glyph could have a different       */
 212   /*                       number of designs).                             */
 213   /*                                                                       */
 214   /*    num_namedstyles :: The number of named styles; a `named style' is  */
 215   /*                       a tuple of design coordinates that has a string */
 216   /*                       ID (in the `name' table) associated with it.    */
 217   /*                       The font can tell the user that, for example,   */
 218   /*                       [Weight=1.5,Width=1.1] is `Bold'.  Another name */
 219   /*                       for `named style' is `named instance'.          */
 220   /*                                                                       */
 221   /*                       For Adobe Multiple Masters fonts, this value is */
 222   /*                       always zero because the format does not support */
 223   /*                       named styles.                                   */
 224   /*                                                                       */
 225   /*    axis            :: An axis descriptor table.                       */
 226   /*                       TrueType GX and OpenType variation fonts        */
 227   /*                       contain slightly more data than Adobe MM fonts. */
 228   /*                       Memory management of this pointer is done       */
 229   /*                       internally by FreeType.                         */
 230   /*                                                                       */
 231   /*    namedstyle      :: A named style (instance) table.                 */
 232   /*                       Only meaningful for TrueType GX and OpenType    */
 233   /*                       variation fonts.  Memory management of this     */
 234   /*                       pointer is done internally by FreeType.         */
 235   /*                                                                       */
 236   typedef struct  FT_MM_Var_
 237   {
 238     FT_UInt              num_axis;
 239     FT_UInt              num_designs;
 240     FT_UInt              num_namedstyles;
 241     FT_Var_Axis*         axis;
 242     FT_Var_Named_Style*  namedstyle;
 243
 244   } FT_MM_Var;
 245
 246
 247   /*************************************************************************/
 248   /*                                                                       */
 249   /* <Function>                                                            */
 250   /*    FT_Get_Multi_Master                                                */
 251   /*                                                                       */
 252   /* <Description>                                                         */
 253   /*    Retrieve a variation descriptor of a given Adobe MM font.          */
 254   /*                                                                       */
 255   /*    This function can't be used with TrueType GX or OpenType variation */
 256   /*    fonts.                                                             */
 257   /*                                                                       */
 258   /* <Input>                                                               */
 259   /*    face    :: A handle to the source face.                            */
 260   /*                                                                       */
 261   /* <Output>                                                              */
 262   /*    amaster :: The Multiple Masters descriptor.                        */
 263   /*                                                                       */
 264   /* <Return>                                                              */
 265   /*    FreeType error code.  0~means success.                             */
 266   /*                                                                       */
 267   FT_EXPORT( FT_Error )
 268   FT_Get_Multi_Master( FT_Face           face,
 269                        FT_Multi_Master  *amaster );
 270
 271
 272   /*************************************************************************/
 273   /*                                                                       */
 274   /* <Function>                                                            */
 275   /*    FT_Get_MM_Var                                                      */
 276   /*                                                                       */
 277   /* <Description>                                                         */
 278   /*    Retrieve a variation descriptor for a given font.                  */
 279   /*                                                                       */
 280   /*    This function works with all supported variation formats.          */
 281   /*                                                                       */
 282   /* <Input>                                                               */
 283   /*    face    :: A handle to the source face.                            */
 284   /*                                                                       */
 285   /* <Output>                                                              */
 286   /*    amaster :: The variation descriptor.                               */
 287   /*               Allocates a data structure, which the user must         */
 288   /*               deallocate with `free' after use.                       */
 289   /*                                                                       */
 290   /* <Return>                                                              */
 291   /*    FreeType error code.  0~means success.                             */
 292   /*                                                                       */
 293   FT_EXPORT( FT_Error )
 294   FT_Get_MM_Var( FT_Face      face,
 295                  FT_MM_Var*  *amaster );
 296
 297
 298   /*************************************************************************/
 299   /*                                                                       */
 300   /* <Function>                                                            */
 301   /*    FT_Set_MM_Design_Coordinates                                       */
 302   /*                                                                       */
 303   /* <Description>                                                         */
 304   /*    For Adobe MM fonts, choose an interpolated font design through     */
 305   /*    design coordinates.                                                */
 306   /*                                                                       */
 307   /*    This function can't be used with TrueType GX or OpenType variation */
 308   /*    fonts.                                                             */
 309   /*                                                                       */
 310   /* <InOut>                                                               */
 311   /*    face       :: A handle to the source face.                         */
 312   /*                                                                       */
 313   /* <Input>                                                               */
 314   /*    num_coords :: The number of available design coordinates.  If it   */
 315   /*                  is larger than the number of axes, ignore the excess */
 316   /*                  values.  If it is smaller than the number of axes,   */
 317   /*                  use default values for the remaining axes.           */
 318   /*                                                                       */
 319   /*    coords     :: An array of design coordinates.                      */
 320   /*                                                                       */
 321   /* <Return>                                                              */
 322   /*    FreeType error code.  0~means success.                             */
 323   /*                                                                       */
 324   FT_EXPORT( FT_Error )
 325   FT_Set_MM_Design_Coordinates( FT_Face   face,
 326                                 FT_UInt   num_coords,
 327                                 FT_Long*  coords );
 328
 329
 330   /*************************************************************************/
 331   /*                                                                       */
 332   /* <Function>                                                            */
 333   /*    FT_Set_Var_Design_Coordinates                                      */
 334   /*                                                                       */
 335   /* <Description>                                                         */
 336   /*    Choose an interpolated font design through design coordinates.     */
 337   /*                                                                       */
 338   /*    This function works with all supported variation formats.          */
 339   /*                                                                       */
 340   /* <InOut>                                                               */
 341   /*    face       :: A handle to the source face.                         */
 342   /*                                                                       */
 343   /* <Input>                                                               */
 344   /*    num_coords :: The number of available design coordinates.  If it   */
 345   /*                  is larger than the number of axes, ignore the excess */
 346   /*                  values.  If it is smaller than the number of axes,   */
 347   /*                  use default values for the remaining axes.           */
 348   /*                                                                       */
 349   /*    coords     :: An array of design coordinates.                      */
 350   /*                                                                       */
 351   /* <Return>                                                              */
 352   /*    FreeType error code.  0~means success.                             */
 353   /*                                                                       */
 354   FT_EXPORT( FT_Error )
 355   FT_Set_Var_Design_Coordinates( FT_Face    face,
 356                                  FT_UInt    num_coords,
 357                                  FT_Fixed*  coords );
 358
 359
 360   /*************************************************************************/
 361   /*                                                                       */
 362   /* <Function>                                                            */
 363   /*    FT_Get_Var_Design_Coordinates                                      */
 364   /*                                                                       */
 365   /* <Description>                                                         */
 366   /*    Get the design coordinates of the currently selected interpolated  */
 367   /*    font.                                                              */
 368   /*                                                                       */
 369   /*    This function works with all supported variation formats.          */
 370   /*                                                                       */
 371   /* <Input>                                                               */
 372   /*    face       :: A handle to the source face.                         */
 373   /*                                                                       */
 374   /*    num_coords :: The number of design coordinates to retrieve.  If it */
 375   /*                  is larger than the number of axes, set the excess    */
 376   /*                  values to~0.                                         */
 377   /*                                                                       */
 378   /* <Output>                                                              */
 379   /*    coords     :: The design coordinates array.                        */
 380   /*                                                                       */
 381   /* <Return>                                                              */
 382   /*    FreeType error code.  0~means success.                             */
 383   /*                                                                       */
 384   FT_EXPORT( FT_Error )
 385   FT_Get_Var_Design_Coordinates( FT_Face    face,
 386                                  FT_UInt    num_coords,
 387                                  FT_Fixed*  coords );
 388
 389
 390   /*************************************************************************/
 391   /*                                                                       */
 392   /* <Function>                                                            */
 393   /*    FT_Set_MM_Blend_Coordinates                                        */
 394   /*                                                                       */
 395   /* <Description>                                                         */
 396   /*    Choose an interpolated font design through normalized blend        */
 397   /*    coordinates.                                                       */
 398   /*                                                                       */
 399   /*    This function works with all supported variation formats.          */
 400   /*                                                                       */
 401   /* <InOut>                                                               */
 402   /*    face       :: A handle to the source face.                         */
 403   /*                                                                       */
 404   /* <Input>                                                               */
 405   /*    num_coords :: The number of available design coordinates.  If it   */
 406   /*                  is larger than the number of axes, ignore the excess */
 407   /*                  values.  If it is smaller than the number of axes,   */
 408   /*                  use default values for the remaining axes.           */
 409   /*                                                                       */
 410   /*    coords     :: The design coordinates array (each element must be   */
 411   /*                  between 0 and 1.0 for Adobe MM fonts, and between    */
 412   /*                  -1.0 and 1.0 for TrueType GX and OpenType variation  */
 413   /*                  fonts).                                              */
 414   /*                                                                       */
 415   /* <Return>                                                              */
 416   /*    FreeType error code.  0~means success.                             */
 417   /*                                                                       */
 418   FT_EXPORT( FT_Error )
 419   FT_Set_MM_Blend_Coordinates( FT_Face    face,
 420                                FT_UInt    num_coords,
 421                                FT_Fixed*  coords );
 422
 423
 424   /*************************************************************************/
 425   /*                                                                       */
 426   /* <Function>                                                            */
 427   /*    FT_Get_MM_Blend_Coordinates                                        */
 428   /*                                                                       */
 429   /* <Description>                                                         */
 430   /*    Get the normalized blend coordinates of the currently selected     */
 431   /*    interpolated font.                                                 */
 432   /*                                                                       */
 433   /*    This function works with all supported variation formats.          */
 434   /*                                                                       */
 435   /* <Input>                                                               */
 436   /*    face       :: A handle to the source face.                         */
 437   /*                                                                       */
 438   /*    num_coords :: The number of normalized blend coordinates to        */
 439   /*                  retrieve.  If it is larger than the number of axes,  */
 440   /*                  set the excess values to~0.5 for Adobe MM fonts, and */
 441   /*                  to~0 for TrueType GX and OpenType variation fonts.   */
 442   /*                                                                       */
 443   /* <Output>                                                              */
 444   /*    coords     :: The normalized blend coordinates array.              */
 445   /*                                                                       */
 446   /* <Return>                                                              */
 447   /*    FreeType error code.  0~means success.                             */
 448   /*                                                                       */
 449   FT_EXPORT( FT_Error )
 450   FT_Get_MM_Blend_Coordinates( FT_Face    face,
 451                                FT_UInt    num_coords,
 452                                FT_Fixed*  coords );
 453
 454
 455   /*************************************************************************/
 456   /*                                                                       */
 457   /* <Function>                                                            */
 458   /*    FT_Set_Var_Blend_Coordinates                                       */
 459   /*                                                                       */
 460   /* <Description>                                                         */
 461   /*    This is another name of @FT_Set_MM_Blend_Coordinates.              */
 462   /*                                                                       */
 463   FT_EXPORT( FT_Error )
 464   FT_Set_Var_Blend_Coordinates( FT_Face    face,
 465                                 FT_UInt    num_coords,
 466                                 FT_Fixed*  coords );
 467
 468
 469   /*************************************************************************/
 470   /*                                                                       */
 471   /* <Function>                                                            */
 472   /*    FT_Get_Var_Blend_Coordinates                                       */
 473   /*                                                                       */
 474   /* <Description>                                                         */
 475   /*    This is another name of @FT_Get_MM_Blend_Coordinates.              */
 476   /*                                                                       */
 477   FT_EXPORT( FT_Error )
 478   FT_Get_Var_Blend_Coordinates( FT_Face    face,
 479                                 FT_UInt    num_coords,
 480                                 FT_Fixed*  coords );
 481
 482   /* */
 483
 484
 485 FT_END_HEADER
 486
 487 #endif /* FTMM_H_ */
 488
 489
 490 /* END */