Home | History | Annotate | Download | only in freetype
      1 /***************************************************************************/
      2 /*                                                                         */
      3 /*  ftmm.h                                                                 */
      4 /*                                                                         */
      5 /*    FreeType Multiple Master font interface (specification).             */
      6 /*                                                                         */
      7 /*  Copyright 1996-2001, 2003, 2004, 2006, 2009 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. This */
     99   /*                   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 which 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            :: A table of axis descriptors.                    */
    205   /*                       GX fonts contain slightly more data than MM.    */
    206   /*                                                                       */
    207   /*    namedstyles     :: A table of named styles.                        */
    208   /*                       Only meaningful with GX.                        */
    209   /*                                                                       */
    210   typedef struct  FT_MM_Var_
    211   {
    212     FT_UInt              num_axis;
    213     FT_UInt              num_designs;
    214     FT_UInt              num_namedstyles;
    215     FT_Var_Axis*         axis;
    216     FT_Var_Named_Style*  namedstyle;
    217 
    218   } FT_MM_Var;
    219 
    220 
    221   /* */
    222 
    223 
    224   /*************************************************************************/
    225   /*                                                                       */
    226   /* <Function>                                                            */
    227   /*    FT_Get_Multi_Master                                                */
    228   /*                                                                       */
    229   /* <Description>                                                         */
    230   /*    Retrieve the Multiple Master descriptor of a given font.           */
    231   /*                                                                       */
    232   /*    This function can't be used with GX fonts.                         */
    233   /*                                                                       */
    234   /* <Input>                                                               */
    235   /*    face    :: A handle to the source face.                            */
    236   /*                                                                       */
    237   /* <Output>                                                              */
    238   /*    amaster :: The Multiple Masters descriptor.                        */
    239   /*                                                                       */
    240   /* <Return>                                                              */
    241   /*    FreeType error code.  0~means success.                             */
    242   /*                                                                       */
    243   FT_EXPORT( FT_Error )
    244   FT_Get_Multi_Master( FT_Face           face,
    245                        FT_Multi_Master  *amaster );
    246 
    247 
    248   /*************************************************************************/
    249   /*                                                                       */
    250   /* <Function>                                                            */
    251   /*    FT_Get_MM_Var                                                      */
    252   /*                                                                       */
    253   /* <Description>                                                         */
    254   /*    Retrieve the Multiple Master/GX var descriptor of a given font.    */
    255   /*                                                                       */
    256   /* <Input>                                                               */
    257   /*    face    :: A handle to the source face.                            */
    258   /*                                                                       */
    259   /* <Output>                                                              */
    260   /*    amaster :: The Multiple Masters/GX var descriptor.                 */
    261   /*               Allocates a data structure, which the user must free    */
    262   /*               (a single call to FT_FREE will do it).                  */
    263   /*                                                                       */
    264   /* <Return>                                                              */
    265   /*    FreeType error code.  0~means success.                             */
    266   /*                                                                       */
    267   FT_EXPORT( FT_Error )
    268   FT_Get_MM_Var( FT_Face      face,
    269                  FT_MM_Var*  *amaster );
    270 
    271 
    272   /*************************************************************************/
    273   /*                                                                       */
    274   /* <Function>                                                            */
    275   /*    FT_Set_MM_Design_Coordinates                                       */
    276   /*                                                                       */
    277   /* <Description>                                                         */
    278   /*    For Multiple Masters fonts, choose an interpolated font design     */
    279   /*    through design coordinates.                                        */
    280   /*                                                                       */
    281   /*    This function can't be used with GX fonts.                         */
    282   /*                                                                       */
    283   /* <InOut>                                                               */
    284   /*    face       :: A handle to the source face.                         */
    285   /*                                                                       */
    286   /* <Input>                                                               */
    287   /*    num_coords :: The number of design coordinates (must be equal to   */
    288   /*                  the number of axes in the font).                     */
    289   /*                                                                       */
    290   /*    coords     :: An array of design coordinates.                      */
    291   /*                                                                       */
    292   /* <Return>                                                              */
    293   /*    FreeType error code.  0~means success.                             */
    294   /*                                                                       */
    295   FT_EXPORT( FT_Error )
    296   FT_Set_MM_Design_Coordinates( FT_Face   face,
    297                                 FT_UInt   num_coords,
    298                                 FT_Long*  coords );
    299 
    300 
    301   /*************************************************************************/
    302   /*                                                                       */
    303   /* <Function>                                                            */
    304   /*    FT_Set_Var_Design_Coordinates                                      */
    305   /*                                                                       */
    306   /* <Description>                                                         */
    307   /*    For Multiple Master or GX Var fonts, choose an interpolated font   */
    308   /*    design through design coordinates.                                 */
    309   /*                                                                       */
    310   /* <InOut>                                                               */
    311   /*    face       :: A handle to the source face.                         */
    312   /*                                                                       */
    313   /* <Input>                                                               */
    314   /*    num_coords :: The number of design coordinates (must be equal to   */
    315   /*                  the number of axes in the font).                     */
    316   /*                                                                       */
    317   /*    coords     :: An array of design coordinates.                      */
    318   /*                                                                       */
    319   /* <Return>                                                              */
    320   /*    FreeType error code.  0~means success.                             */
    321   /*                                                                       */
    322   FT_EXPORT( FT_Error )
    323   FT_Set_Var_Design_Coordinates( FT_Face    face,
    324                                  FT_UInt    num_coords,
    325                                  FT_Fixed*  coords );
    326 
    327 
    328   /*************************************************************************/
    329   /*                                                                       */
    330   /* <Function>                                                            */
    331   /*    FT_Set_MM_Blend_Coordinates                                        */
    332   /*                                                                       */
    333   /* <Description>                                                         */
    334   /*    For Multiple Masters and GX var fonts, choose an interpolated font */
    335   /*    design through normalized blend coordinates.                       */
    336   /*                                                                       */
    337   /* <InOut>                                                               */
    338   /*    face       :: A handle to the source face.                         */
    339   /*                                                                       */
    340   /* <Input>                                                               */
    341   /*    num_coords :: The number of design coordinates (must be equal to   */
    342   /*                  the number of axes in the font).                     */
    343   /*                                                                       */
    344   /*    coords     :: The design coordinates array (each element must be   */
    345   /*                  between 0 and 1.0).                                  */
    346   /*                                                                       */
    347   /* <Return>                                                              */
    348   /*    FreeType error code.  0~means success.                             */
    349   /*                                                                       */
    350   FT_EXPORT( FT_Error )
    351   FT_Set_MM_Blend_Coordinates( FT_Face    face,
    352                                FT_UInt    num_coords,
    353                                FT_Fixed*  coords );
    354 
    355 
    356   /*************************************************************************/
    357   /*                                                                       */
    358   /* <Function>                                                            */
    359   /*    FT_Set_Var_Blend_Coordinates                                       */
    360   /*                                                                       */
    361   /* <Description>                                                         */
    362   /*    This is another name of @FT_Set_MM_Blend_Coordinates.              */
    363   /*                                                                       */
    364   FT_EXPORT( FT_Error )
    365   FT_Set_Var_Blend_Coordinates( FT_Face    face,
    366                                 FT_UInt    num_coords,
    367                                 FT_Fixed*  coords );
    368 
    369 
    370   /* */
    371 
    372 
    373 FT_END_HEADER
    374 
    375 #endif /* __FTMM_H__ */
    376 
    377 
    378 /* END */
    379