include/freetype/ftmm.h

   1 /***************************************************************************/
   2 /*                                                                         */
   3 /*  ftmm.h                                                                 */
   4 /*                                                                         */
   5 /*    FreeType Multiple Master font interface (specification).             */
   6 /*                                                                         */
   7 /*  Copyright 1996-2016 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   /*    George Williams has extended this interface to make it work with   */
  47   /*    both Type~1 Multiple Masters fonts and GX distortable (var)        */
  48   /*    fonts.  Some of these routines only work with MM fonts, others     */
  49   /*    will work with both types.  They are similar enough that a         */
  50   /*    consistent interface makes sense.                                  */
  51   /*                                                                       */
  52   /*************************************************************************/
  53
  54
  55   /*************************************************************************/
  56   /*                                                                       */
  57   /* <Struct>                                                              */
  58   /*    FT_MM_Axis                                                         */
  59   /*                                                                       */
  60   /* <Description>                                                         */
  61   /*    A simple structure used to model a given axis in design space for  */
  62   /*    Multiple Masters fonts.                                            */
  63   /*                                                                       */
  64   /*    This structure can't be used for GX var 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 used to model the axes and space of a Multiple Masters */
  89   /*    font.                                                              */
  90   /*                                                                       */
  91   /*    This structure can't be used for GX var fonts.                     */
  92   /*                                                                       */
  93   /* <Fields>                                                              */
  94   /*    num_axis    :: Number of axes.  Cannot exceed~4.                   */
  95   /*                                                                       */
  96   /*    num_designs :: Number of designs; should be normally 2^num_axis    */
  97   /*                   even though the Type~1 specification strangely      */
  98   /*                   allows for intermediate designs to be present.      */
  99   /*                   This number cannot exceed~16.                       */
 100   /*                                                                       */
 101   /*    axis        :: A table of axis descriptors.                        */
 102   /*                                                                       */
 103   typedef struct  FT_Multi_Master_
 104   {
 105     FT_UInt     num_axis;
 106     FT_UInt     num_designs;
 107     FT_MM_Axis  axis[T1_MAX_MM_AXIS];
 108
 109   } FT_Multi_Master;
 110
 111
 112   /*************************************************************************/
 113   /*                                                                       */
 114   /* <Struct>                                                              */
 115   /*    FT_Var_Axis                                                        */
 116   /*                                                                       */
 117   /* <Description>                                                         */
 118   /*    A simple structure used to model a given axis in design space for  */
 119   /*    Multiple Masters and GX var fonts.                                 */
 120   /*                                                                       */
 121   /* <Fields>                                                              */
 122   /*    name    :: The axis's name.                                        */
 123   /*               Not always meaningful for GX.                           */
 124   /*                                                                       */
 125   /*    minimum :: The axis's minimum design coordinate.                   */
 126   /*                                                                       */
 127   /*    def     :: The axis's default design coordinate.                   */
 128   /*               FreeType computes meaningful default values for MM; it  */
 129   /*               is then an integer value, not in 16.16 format.          */
 130   /*                                                                       */
 131   /*    maximum :: The axis's maximum design coordinate.                   */
 132   /*                                                                       */
 133   /*    tag     :: The axis's tag (the GX equivalent to `name').           */
 134   /*               FreeType provides default values for MM if possible.    */
 135   /*                                                                       */
 136   /*    strid   :: The entry in `name' table (another GX version of        */
 137   /*               `name').                                                */
 138   /*               Not meaningful for MM.                                  */
 139   /*                                                                       */
 140   typedef struct  FT_Var_Axis_
 141   {
 142     FT_String*  name;
 143
 144     FT_Fixed    minimum;
 145     FT_Fixed    def;
 146     FT_Fixed    maximum;
 147
 148     FT_ULong    tag;
 149     FT_UInt     strid;
 150
 151   } FT_Var_Axis;
 152
 153
 154   /*************************************************************************/
 155   /*                                                                       */
 156   /* <Struct>                                                              */
 157   /*    FT_Var_Named_Style                                                 */
 158   /*                                                                       */
 159   /* <Description>                                                         */
 160   /*    A simple structure used to model a named style in a GX var font.   */
 161   /*                                                                       */
 162   /*    This structure can't be used for MM fonts.                         */
 163   /*                                                                       */
 164   /* <Fields>                                                              */
 165   /*    coords :: The design coordinates for this style.                   */
 166   /*              This is an array with one entry for each axis.           */
 167   /*                                                                       */
 168   /*    strid  :: The entry in `name' table identifying this style.        */
 169   /*                                                                       */
 170   typedef struct  FT_Var_Named_Style_
 171   {
 172     FT_Fixed*  coords;
 173     FT_UInt    strid;
 174
 175   } FT_Var_Named_Style;
 176
 177
 178   /*************************************************************************/
 179   /*                                                                       */
 180   /* <Struct>                                                              */
 181   /*    FT_MM_Var                                                          */
 182   /*                                                                       */
 183   /* <Description>                                                         */
 184   /*    A structure used to model the axes and space of a Multiple Masters */
 185   /*    or GX var distortable font.                                        */
 186   /*                                                                       */
 187   /*    Some fields are specific to one format and not to the other.       */
 188   /*                                                                       */
 189   /* <Fields>                                                              */
 190   /*    num_axis        :: The number of axes.  The maximum value is~4 for */
 191   /*                       MM; no limit in GX.                             */
 192   /*                                                                       */
 193   /*    num_designs     :: The number of designs; should be normally       */
 194   /*                       2^num_axis for MM fonts.  Not meaningful for GX */
 195   /*                       (where every glyph could have a different       */
 196   /*                       number of designs).                             */
 197   /*                                                                       */
 198   /*    num_namedstyles :: The number of named styles; only meaningful for */
 199   /*                       GX that allows certain design coordinates to    */
 200   /*                       have a string ID (in the `name' table)          */
 201   /*                       associated with them.  The font can tell the    */
 202   /*                       user that, for example, Weight=1.5 is `Bold'.   */
 203   /*                                                                       */
 204   /*    axis            :: An axis descriptor table.                       */
 205   /*                       GX fonts contain slightly more data than MM.    */
 206   /*                       Memory management of this pointer is done       */
 207   /*                       internally by FreeType.                         */
 208   /*                                                                       */
 209   /*    namedstyle      :: A named style table.                            */
 210   /*                       Only meaningful with GX.                        */
 211   /*                       Memory management of this pointer is done       */
 212   /*                       internally by FreeType.                         */
 213   /*                                                                       */
 214   typedef struct  FT_MM_Var_
 215   {
 216     FT_UInt              num_axis;
 217     FT_UInt              num_designs;
 218     FT_UInt              num_namedstyles;
 219     FT_Var_Axis*         axis;
 220     FT_Var_Named_Style*  namedstyle;
 221
 222   } FT_MM_Var;
 223
 224
 225   /*************************************************************************/
 226   /*                                                                       */
 227   /* <Function>                                                            */
 228   /*    FT_Get_Multi_Master                                                */
 229   /*                                                                       */
 230   /* <Description>                                                         */
 231   /*    Retrieve the Multiple Master descriptor of a given font.           */
 232   /*                                                                       */
 233   /*    This function can't be used with GX fonts.                         */
 234   /*                                                                       */
 235   /* <Input>                                                               */
 236   /*    face    :: A handle to the source face.                            */
 237   /*                                                                       */
 238   /* <Output>                                                              */
 239   /*    amaster :: The Multiple Masters descriptor.                        */
 240   /*                                                                       */
 241   /* <Return>                                                              */
 242   /*    FreeType error code.  0~means success.                             */
 243   /*                                                                       */
 244   FT_EXPORT( FT_Error )
 245   FT_Get_Multi_Master( FT_Face           face,
 246                        FT_Multi_Master  *amaster );
 247
 248
 249   /*************************************************************************/
 250   /*                                                                       */
 251   /* <Function>                                                            */
 252   /*    FT_Get_MM_Var                                                      */
 253   /*                                                                       */
 254   /* <Description>                                                         */
 255   /*    Retrieve the Multiple Master/GX var descriptor of a given font.    */
 256   /*                                                                       */
 257   /* <Input>                                                               */
 258   /*    face    :: A handle to the source face.                            */
 259   /*                                                                       */
 260   /* <Output>                                                              */
 261   /*    amaster :: The Multiple Masters/GX var descriptor.                 */
 262   /*               Allocates a data structure, which the user must         */
 263   /*               deallocate with `free' after use.                       */
 264   /*                                                                       */
 265   /* <Return>                                                              */
 266   /*    FreeType error code.  0~means success.                             */
 267   /*                                                                       */
 268   FT_EXPORT( FT_Error )
 269   FT_Get_MM_Var( FT_Face      face,
 270                  FT_MM_Var*  *amaster );
 271
 272
 273   /*************************************************************************/
 274   /*                                                                       */
 275   /* <Function>                                                            */
 276   /*    FT_Set_MM_Design_Coordinates                                       */
 277   /*                                                                       */
 278   /* <Description>                                                         */
 279   /*    For Multiple Masters fonts, choose an interpolated font design     */
 280   /*    through design coordinates.                                        */
 281   /*                                                                       */
 282   /*    This function can't be used with GX fonts.                         */
 283   /*                                                                       */
 284   /* <InOut>                                                               */
 285   /*    face       :: A handle to the source face.                         */
 286   /*                                                                       */
 287   /* <Input>                                                               */
 288   /*    num_coords :: The number of available design coordinates.  If it   */
 289   /*                  is larger than the number of axes, ignore the excess */
 290   /*                  values.  If it is smaller than the number of axes,   */
 291   /*                  use default values for the remaining axes.           */
 292   /*                                                                       */
 293   /*    coords     :: An array of design coordinates.                      */
 294   /*                                                                       */
 295   /* <Return>                                                              */
 296   /*    FreeType error code.  0~means success.                             */
 297   /*                                                                       */
 298   FT_EXPORT( FT_Error )
 299   FT_Set_MM_Design_Coordinates( FT_Face   face,
 300                                 FT_UInt   num_coords,
 301                                 FT_Long*  coords );
 302
 303
 304   /*************************************************************************/
 305   /*                                                                       */
 306   /* <Function>                                                            */
 307   /*    FT_Set_Var_Design_Coordinates                                      */
 308   /*                                                                       */
 309   /* <Description>                                                         */
 310   /*    For Multiple Master or GX Var fonts, choose an interpolated font   */
 311   /*    design through design coordinates.                                 */
 312   /*                                                                       */
 313   /* <InOut>                                                               */
 314   /*    face       :: A handle to the source face.                         */
 315   /*                                                                       */
 316   /* <Input>                                                               */
 317   /*    num_coords :: The number of available design coordinates.  If it   */
 318   /*                  is larger than the number of axes, ignore the excess */
 319   /*                  values.  If it is smaller than the number of axes,   */
 320   /*                  use default values for the remaining axes.           */
 321   /*                                                                       */
 322   /*    coords     :: An array of design coordinates.                      */
 323   /*                                                                       */
 324   /* <Return>                                                              */
 325   /*    FreeType error code.  0~means success.                             */
 326   /*                                                                       */
 327   FT_EXPORT( FT_Error )
 328   FT_Set_Var_Design_Coordinates( FT_Face    face,
 329                                  FT_UInt    num_coords,
 330                                  FT_Fixed*  coords );
 331
 332
 333   /*************************************************************************/
 334   /*                                                                       */
 335   /* <Function>                                                            */
 336   /*    FT_Set_MM_Blend_Coordinates                                        */
 337   /*                                                                       */
 338   /* <Description>                                                         */
 339   /*    For Multiple Masters and GX var fonts, choose an interpolated font */
 340   /*    design through normalized blend coordinates.                       */
 341   /*                                                                       */
 342   /* <InOut>                                                               */
 343   /*    face       :: A handle to the source face.                         */
 344   /*                                                                       */
 345   /* <Input>                                                               */
 346   /*    num_coords :: The number of available design coordinates.  If it   */
 347   /*                  is larger than the number of axes, ignore the excess */
 348   /*                  values.  If it is smaller than the number of axes,   */
 349   /*                  use default values for the remaining axes.           */
 350   /*                                                                       */
 351   /*    coords     :: The design coordinates array (each element must be   */
 352   /*                  between 0 and 1.0).                                  */
 353   /*                                                                       */
 354   /* <Return>                                                              */
 355   /*    FreeType error code.  0~means success.                             */
 356   /*                                                                       */
 357   FT_EXPORT( FT_Error )
 358   FT_Set_MM_Blend_Coordinates( FT_Face    face,
 359                                FT_UInt    num_coords,
 360                                FT_Fixed*  coords );
 361
 362
 363   /*************************************************************************/
 364   /*                                                                       */
 365   /* <Function>                                                            */
 366   /*    FT_Set_Var_Blend_Coordinates                                       */
 367   /*                                                                       */
 368   /* <Description>                                                         */
 369   /*    This is another name of @FT_Set_MM_Blend_Coordinates.              */
 370   /*                                                                       */
 371   FT_EXPORT( FT_Error )
 372   FT_Set_Var_Blend_Coordinates( FT_Face    face,
 373                                 FT_UInt    num_coords,
 374                                 FT_Fixed*  coords );
 375
 376   /* */
 377
 378
 379 FT_END_HEADER
 380
 381 #endif /* FTMM_H_ */
 382
 383
 384 /* END */