# FreeType-2.7.1 API Reference

# Multiple Masters

## Synopsis

FT_MM_Axis | FT_Set_MM_Design_Coordinates
FT_Multi_Master | FT_Set_Var_Design_Coordinates
FT_Var_Axis | FT_Get_Var_Design_Coordinates
FT_Var_Named_Style | FT_Set_MM_Blend_Coordinates
FT_MM_Var | FT_Get_MM_Blend_Coordinates
FT_Get_Multi_Master | FT_Set_Var_Blend_Coordinates
FT_Get_MM_Var | FT_Get_Var_Blend_Coordinates

The following types and functions are used to manage Multiple Master fonts, i.e., the selection of specific design instances by setting design axis coordinates.

George Williams has extended this interface to make it work with both Type 1 Multiple Masters fonts and GX distortable (var) fonts. Some of these routines only work with MM fonts, others will work with both types. They are similar enough that a consistent interface makes sense.

### FT_MM_Axis

Defined in FT_MULTIPLE_MASTERS_H (freetype/ftmm.h).

      typedef struct  FT_MM_Axis_
      {
        FT_String*  name;
        FT_Long     minimum;
        FT_Long     maximum;

      } FT_MM_Axis;

A simple structure used to model a given axis in design space for Multiple Masters fonts.

This structure can't be used for GX var fonts.

#### fields

name | The axis's name.
minimum | The axis's minimum design coordinate.
maximum | The axis's maximum design coordinate.

### FT_Multi_Master

Defined in FT_MULTIPLE_MASTERS_H (freetype/ftmm.h).

      typedef struct  FT_Multi_Master_
      {
        FT_UInt     num_axis;
        FT_UInt     num_designs;
        FT_MM_Axis  axis[T1_MAX_MM_AXIS];

      } FT_Multi_Master;

A structure used to model the axes and space of a Multiple Masters font.

This structure can't be used for GX var fonts.

#### fields

num_axis | Number of axes. Cannot exceed 4.
num_designs | Number of designs; should be normally 2^num_axis even though the Type 1 specification strangely allows for intermediate designs to be present. This number cannot exceed 16.
axis | A table of axis descriptors.

### FT_Var_Axis

Defined in FT_MULTIPLE_MASTERS_H (freetype/ftmm.h).

      typedef struct  FT_Var_Axis_
      {
        FT_String*  name;

        FT_Fixed    minimum;
        FT_Fixed    def;
        FT_Fixed    maximum;

        FT_ULong    tag;
        FT_UInt     strid;

      } FT_Var_Axis;

A simple structure used to model a given axis in design space for Multiple Masters and GX var fonts.

#### fields

name | The axis's name. Not always meaningful for GX.
minimum | The axis's minimum design coordinate.
def | The axis's default design coordinate. FreeType computes meaningful default values for MM; it is then an integer value, not in 16.16 format.
maximum | The axis's maximum design coordinate.
tag | The axis's tag (the GX equivalent to ‘name’). FreeType provides default values for MM if possible.
strid | The entry in ‘name’ table (another GX version of ‘name’). Not meaningful for MM.

### FT_Var_Named_Style

Defined in FT_MULTIPLE_MASTERS_H (freetype/ftmm.h).

      typedef struct  FT_Var_Named_Style_
      {
        FT_Fixed*  coords;
        FT_UInt    strid;
        FT_UInt    psid;   /* since 2.7.1 */

      } FT_Var_Named_Style;

A simple structure used to model a named style in a GX var font.

This structure can't be used for MM fonts.

#### fields

coords | The design coordinates for this style. This is an array with one entry for each axis.
strid | The entry in ‘name’ table identifying this style.

### FT_MM_Var

Defined in FT_MULTIPLE_MASTERS_H (freetype/ftmm.h).

      typedef struct  FT_MM_Var_
      {
        FT_UInt              num_axis;
        FT_UInt              num_designs;
        FT_UInt              num_namedstyles;
        FT_Var_Axis*         axis;
        FT_Var_Named_Style*  namedstyle;

      } FT_MM_Var;

A structure used to model the axes and space of a Multiple Masters or GX var distortable font.

Some fields are specific to one format and not to the other.

#### fields

num_axis | The number of axes. The maximum value is 4 for MM; no limit in GX.
num_designs | The number of designs; should be normally 2^num_axis for MM fonts. Not meaningful for GX (where every glyph could have a different number of designs).
num_namedstyles | The number of named styles; a ‘named style’ is a tuple of design coordinates that has a string ID (in the ‘name’ table) associated with it. The font can tell the user that, for example, [Weight=1.5,Width=1.1] is ‘Bold’. For Type 1 Multiple Masters fonts, this value is always zero because the format does not support named styles.
axis | An axis descriptor table. GX fonts contain slightly more data than MM. Memory management of this pointer is done internally by FreeType.
namedstyle | A named style table. Only meaningful with GX. Memory management of this pointer is done internally by FreeType.

### FT_Get_Multi_Master

Defined in FT_MULTIPLE_MASTERS_H (freetype/ftmm.h).

      FT_EXPORT( FT_Error )
      FT_Get_Multi_Master( FT_Face           face,
                           FT_Multi_Master  *amaster );

Retrieve the Multiple Master descriptor of a given font.

This function can't be used with GX fonts.

#### input

face | A handle to the source face.

#### output

amaster | The Multiple Masters descriptor.

#### return

FreeType error code. 0 means success.

### FT_Get_MM_Var

Defined in FT_MULTIPLE_MASTERS_H (freetype/ftmm.h).

      FT_EXPORT( FT_Error )
      FT_Get_MM_Var( FT_Face      face,
                     FT_MM_Var*  *amaster );

Retrieve the Multiple Master/GX var descriptor of a given font.

#### input

face | A handle to the source face.

#### output

amaster | The Multiple Masters/GX var descriptor. Allocates a data structure, which the user must deallocate with ‘free’ after use.

#### return

FreeType error code. 0 means success.

### FT_Set_MM_Design_Coordinates

Defined in FT_MULTIPLE_MASTERS_H (freetype/ftmm.h).

      FT_EXPORT( FT_Error )
      FT_Set_MM_Design_Coordinates( FT_Face   face,
                                    FT_UInt   num_coords,
                                    FT_Long*  coords );

For Multiple Masters fonts, choose an interpolated font design through design coordinates.

This function can't be used with GX fonts.

#### inout

face | A handle to the source face.

#### input

num_coords | The number of available design coordinates. If it is larger than the number of axes, ignore the excess values. If it is smaller than the number of axes, use default values for the remaining axes.
coords | An array of design coordinates.

#### return

FreeType error code. 0 means success.

### FT_Set_Var_Design_Coordinates

Defined in FT_MULTIPLE_MASTERS_H (freetype/ftmm.h).

      FT_EXPORT( FT_Error )
      FT_Set_Var_Design_Coordinates( FT_Face    face,
                                     FT_UInt    num_coords,
                                     FT_Fixed*  coords );

For Multiple Master or GX Var fonts, choose an interpolated font design through design coordinates.

#### inout

face | A handle to the source face.

#### input

num_coords | The number of available design coordinates. If it is larger than the number of axes, ignore the excess values. If it is smaller than the number of axes, use default values for the remaining axes.
coords | An array of design coordinates.

#### return

FreeType error code. 0 means success.

### FT_Get_Var_Design_Coordinates

Defined in FT_MULTIPLE_MASTERS_H (freetype/ftmm.h).

      FT_EXPORT( FT_Error )
      FT_Get_Var_Design_Coordinates( FT_Face    face,
                                     FT_UInt    num_coords,
                                     FT_Fixed*  coords );

For Multiple Master and GX Var fonts, get the design coordinates of the currently selected interpolated font.

#### input

face | A handle to the source face.
num_coords | The number of design coordinates to retrieve. If it is larger than the number of axes, set the excess values to 0.

#### output

coords | The design coordinates array.

#### return

FreeType error code. 0 means success.

### FT_Set_MM_Blend_Coordinates

Defined in FT_MULTIPLE_MASTERS_H (freetype/ftmm.h).

      FT_EXPORT( FT_Error )
      FT_Set_MM_Blend_Coordinates( FT_Face    face,
                                   FT_UInt    num_coords,
                                   FT_Fixed*  coords );

For Multiple Masters and GX var fonts, choose an interpolated font design through normalized blend coordinates.

#### inout

face | A handle to the source face.

#### input

num_coords | The number of available design coordinates. If it is larger than the number of axes, ignore the excess values. If it is smaller than the number of axes, use default values for the remaining axes.
coords | The design coordinates array (each element must be between 0 and 1.0 for MM fonts, and between -1.0 and 1.0 for GX var fonts).

#### return

FreeType error code. 0 means success.

### FT_Get_MM_Blend_Coordinates

Defined in FT_MULTIPLE_MASTERS_H (freetype/ftmm.h).

      FT_EXPORT( FT_Error )
      FT_Get_MM_Blend_Coordinates( FT_Face    face,
                                   FT_UInt    num_coords,
                                   FT_Fixed*  coords );

For Multiple Masters and GX var fonts, get the normalized blend coordinates of the currently selected interpolated font.

#### input

face | A handle to the source face.
num_coords | The number of normalized blend coordinates to retrieve. If it is larger than the number of axes, set the excess values to 0.5 for MM fonts, and to 0 for GX var fonts.

#### output

coords | The normalized blend coordinates array.

#### return

FreeType error code. 0 means success.

### FT_Set_Var_Blend_Coordinates

Defined in FT_MULTIPLE_MASTERS_H (freetype/ftmm.h).

      FT_EXPORT( FT_Error )
      FT_Set_Var_Blend_Coordinates( FT_Face    face,
                                    FT_UInt    num_coords,
                                    FT_Fixed*  coords );

This is another name of FT_Set_MM_Blend_Coordinates.

### FT_Get_Var_Blend_Coordinates

Defined in FT_MULTIPLE_MASTERS_H (freetype/ftmm.h).

      FT_EXPORT( FT_Error )
      FT_Get_Var_Blend_Coordinates( FT_Face    face,
                                    FT_UInt    num_coords,
                                    FT_Fixed*  coords );

This is another name of FT_Get_MM_Blend_Coordinates.