FreeType » Docs » Format-Specific API » OpenType Font Variations, TrueType GX, and Adobe MM Fonts

OpenType Font Variations, TrueType GX, and Adobe MM Fonts¶

Synopsis¶

The following types and functions manage OpenType Font Variations, Adobe Multiple Master (MM) fonts, and Apple TrueType GX fonts. These formats have in common that they allow the selection of specific design instances by setting design coordinates for one or more axes like font weight or width.

For historical reasons there are two interfaces. The first, older one can be used with Adobe MM fonts only, and the second, newer one is a unified interface that handles all three font formats. However, some differences remain and are documented accordingly; in particular, Adobe MM fonts don't have named instances (see below).

For Adobe MM fonts, macro FT_IS_SFNT returns false. For TrueType GX and OpenType Font Variations, it returns true.

We use mostly the terminology of the OpenType standard. Here are some important technical terms.

A ‘named instance’ is a tuple of design coordinates that has a string ID (i.e., an index into the font's ‘name’ table) associated with it. The font can tell the user that, for example, [Weight=700,Width=110] is ‘Bold’. Another name for ‘named instance’ is ‘named style’.

Adobe MM fonts don't have named instances.
The ‘default instance’ of a variation font is that instance for which the nth axis coordinate is equal to the nth default axis coordinate (i.e., axis[n].def as specified in the FT_MM_Var structure), with n covering all axes. In TrueType GX and OpenType Font Variations, the default instance is explicitly given. In Adobe MM fonts, the WeightVector entry as found in the font file is taken as the default instance.

For TrueType GX and OpenType Font Variations, FreeType synthesizes a named instance for the default instance if the font does not contain such an entry.
‘Design coordinates’ are the axis values found in a variation font file. Their meaning is specified by the font designer and the values are rather arbitrary.

For example, the ‘weight’ axis in design coordinates might vary between 100 (thin) and 900 (heavy) in font A, while font B contains values between 400 (normal) and 800 (extra bold).
‘Normalized coordinates’ are design coordinates mapped to a standard range; they are also called ‘blend coordinates’.

For TrueType GX and OpenType Font Variations, the range is [-1;1], with the minimum mapped to value -1, the default mapped to value 0, and the maximum mapped to value 1, and all other coordinates mapped to intervening points. Please look up the OpenType specification on how this mapping works in detail.

For Adobe MM fonts, this standard range is [0;1], with the minimum mapped to value 0 and the maximum mapped to value 1, and all other coordinates mapped to intervening points. Please look up Adobe TechNote #5015 on how this mapping works in detail.

Assuming that the two fonts in the previous example are OpenType Font Variations, both font A's [100;900] and font B's [400;800] coordinate ranges get mapped to [-1;1].

T1_MAX_MM_XXX¶

Defined in FT_MULTIPLE_MASTERS_H (freetype/ftmm.h).

#define T1_MAX_MM_AXIS         4
#define T1_MAX_MM_DESIGNS     16
#define T1_MAX_MM_MAP_POINTS  20

Adobe MM font limits as defined in their specifications.

values

T1_MAX_MM_AXIS	The maximum number of Adobe MM font axes.
T1_MAX_MM_DESIGNS	The maximum number of Adobe MM font designs.
T1_MAX_MM_MAP_POINTS	The maximum number of elements in a design map.

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 structure to model a given axis in design space for Adobe MM fonts.

This structure can't be used with TrueType GX or OpenType Font Variations.

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 to model the axes and space of an Adobe MM font.

This structure can't be used with TrueType GX or OpenType Font Variations.

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 structure to model a given axis in design space for Adobe MM fonts, TrueType GX, and OpenType Font Variations.

fields

name	The axis's name. Not always meaningful for TrueType GX or OpenType Font Variations.
minimum	The axis's minimum design coordinate.
def	The axis's default design coordinate. FreeType computes meaningful default values for Adobe MM fonts.
maximum	The axis's maximum design coordinate.
tag	The axis's tag (the equivalent to ‘name’ for TrueType GX and OpenType Font Variations). FreeType provides default values for Adobe MM fonts if possible.
strid	The axis name entry in the font's ‘name’ table. This is another (and often better) version of the ‘name’ field for TrueType GX or OpenType Font Variations. Not meaningful for Adobe MM fonts.

note

The fields minimum, def, and maximum are 16.16 fractional values for TrueType GX and OpenType Font Variations. For Adobe MM fonts, the values are whole numbers (i.e., the fractional part is zero).

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 structure to model a named instance in a TrueType GX or OpenType Font Variations.

This structure can't be used for Adobe MM fonts.

fields

coords	The design coordinates for this instance. This is an array with one entry for each axis.
strid	An index into the ‘name’ table identifying this instance.
psid	An index into the ‘name’ table identifying a PostScript name for this instance. Value 0xFFFF indicates a missing entry.

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 to model the axes and space of Adobe MM fonts, TrueType GX, or OpenType Font Variations.

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

fields

num_axis	The number of axes. The maximum value is 4 for Adobe MM fonts; no limit in TrueType GX or OpenType Font Variations.
num_designs	The number of designs; should be normally `2^num_axis` for Adobe MM fonts. Not meaningful for TrueType GX or OpenType Font Variations (where every glyph could have a different number of designs).
num_namedstyles	The number of named instances. For Adobe MM fonts, this value is always zero.
axis	An axis descriptor table. TrueType GX and OpenType Font Variations contain slightly more data than Adobe MM fonts. Memory management of this pointer is done internally by FreeType.
namedstyle	An array of named instances. Only meaningful for TrueType GX and OpenType Font Variations. 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 a variation descriptor of a given Adobe MM font.

This function can't be used with TrueType GX or OpenType Font Variations.

input

face	A handle to the source face.

output

amaster

The Adobe MM font's variation 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 a variation descriptor for a given font.

This function works with all supported variation formats.

input

face	A handle to the source face.

output

amaster

The variation descriptor. Allocates a data structure, which the user must deallocate with a call to FT_Done_MM_Var after use.

return

FreeType error code. 0 means success.

FT_Done_MM_Var¶

Defined in FT_MULTIPLE_MASTERS_H (freetype/ftmm.h).

  FT_EXPORT( FT_Error )
  FT_Done_MM_Var( FT_Library   library,
                  FT_MM_Var   *amaster );

Free the memory allocated by FT_Get_MM_Var.

input

library

A handle of the face's parent library object that was used in the call to FT_Get_MM_Var to create amaster.

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 Adobe MM fonts, choose an interpolated font design through design coordinates.

This function can't be used with TrueType GX or OpenType Font Variations.

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.

note

[Since 2.8.1] To reset all axes to the default values, call the function with num_coords set to zero and coords set to NULL.

[Since 2.9] If num_coords is larger than zero, this function sets the FT_FACE_FLAG_VARIATION bit in FT_Face's face_flags field (i.e., FT_IS_VARIATION returns true). If num_coords is zero, this bit flag gets unset.

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 );

Choose an interpolated font design through design coordinates.

This function works with all supported variation formats.

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.

note

The design coordinates are 16.16 fractional values for TrueType GX and OpenType Font Variations. For Adobe MM fonts, the values are supposed to be whole numbers (i.e., the fractional part is zero).

[Since 2.8.1] To reset all axes to the default values, call the function with num_coords set to zero and coords set to NULL. [Since 2.9] ‘Default values’ means the currently selected named instance (or the base font if no named instance is selected).

[Since 2.9] If num_coords is larger than zero, this function sets the FT_FACE_FLAG_VARIATION bit in FT_Face's face_flags field (i.e., FT_IS_VARIATION returns true). If num_coords is zero, this bit flag gets unset.

[Since 2.14] This function also sets the FT_FACE_FLAG_VARIATION bit in FT_Face's face_flags field (i.e., FT_IS_VARIATION returns true) if any of the provided coordinates is different from the face's default value for the corresponding axis, that is, the set up face is not at its default position.

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 );

Get the design coordinates of the currently selected interpolated font.

This function works with all supported variation formats.

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, which must be allocated by the user.

return

FreeType error code. 0 means success.

note

The design coordinates are 16.16 fractional values for TrueType GX and OpenType Font Variations. For Adobe MM fonts, the values are whole numbers (i.e., the fractional part is zero).

since

2.7.1

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 );

Choose an interpolated font design through normalized coordinates.

This function works with all supported variation formats.

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 normalized coordinates array. Each element is a 16.16 fractional value and must be between 0 and 1.0 for Adobe MM fonts, and between -1.0 and 1.0 for TrueType GX and OpenType Font Variations.

return

FreeType error code. 0 means success.

note

[Since 2.8.1] To reset all axes to the default values, call the function with num_coords set to zero and coords set to NULL. [Since 2.9] ‘Default values’ means the currently selected named instance (or the base font if no named instance is selected).

[Since 2.9] If num_coords is larger than zero, this function sets the FT_FACE_FLAG_VARIATION bit in FT_Face's face_flags field (i.e., FT_IS_VARIATION returns true). If num_coords is zero, this bit flag gets unset.

[Since 2.14] This function also sets the FT_FACE_FLAG_VARIATION bit in FT_Face's face_flags field (i.e., FT_IS_VARIATION returns true) if any of the provided coordinates is different from the face's default value for the corresponding axis, that is, the set up face is not at its default position.

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 );

Get the normalized coordinates of the currently selected interpolated font.

This function works with all supported variation formats.

input

face	A handle to the source face.
num_coords	The number of normalized coordinates to retrieve. If it is larger than the number of axes, set the excess values to 0.5 for Adobe MM fonts, and to 0 for TrueType GX and OpenType Font Variations.

output

coords

The normalized coordinates array (as 16.16 fractional values), which must be allocated by the user.

return

FreeType error code. 0 means success.

since

2.7.1

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.

since

2.7.1

FT_Set_MM_WeightVector¶

Defined in FT_MULTIPLE_MASTERS_H (freetype/ftmm.h).

  FT_EXPORT( FT_Error )
  FT_Set_MM_WeightVector( FT_Face    face,
                          FT_UInt    len,
                          FT_Fixed*  weightvector );

For Adobe MM fonts, choose an interpolated font design by directly setting the weight vector.

This function can't be used with TrueType GX or OpenType Font Variations.

inout

face	A handle to the source face.

input

len	The length of the weight vector array. If it is larger than the number of designs, the extra values are ignored. If it is less than the number of designs, the remaining values are set to zero.
weightvector	An array representing the weight vector.

return

FreeType error code. 0 means success.

note

Adobe MM fonts limit the number of designs, and thus the length of the weight vector, to 16 elements.

If len is larger than zero, this function sets the FT_FACE_FLAG_VARIATION bit in FT_Face's face_flags field (i.e., FT_IS_VARIATION returns true). If len is zero, this bit flag is unset and the weight vector array is reset to the default values.

The Adobe documentation also states that the values in the WeightVector array must total 1.0 ± 0.001. In practice this does not seem to be enforced, so is not enforced here, either.

since

2.10

FT_Get_MM_WeightVector¶

Defined in FT_MULTIPLE_MASTERS_H (freetype/ftmm.h).

  FT_EXPORT( FT_Error )
  FT_Get_MM_WeightVector( FT_Face    face,
                          FT_UInt*   len,
                          FT_Fixed*  weightvector );

For Adobe MM fonts, retrieve the current weight vector of the font.

This function can't be used with TrueType GX or OpenType Font Variations.

inout

face

A handle to the source face.

len

A pointer to the size of the array to be filled. If the size of the array is less than the number of designs, FT_Err_Invalid_Argument is returned, and len is set to the required size (the number of designs). If the size of the array is greater than the number of designs, the remaining entries are set to 0. On successful completion, len is set to the number of designs (i.e., the number of values written to the array).

output

weightvector

An array to be filled; it must be allocated by the user.

return

FreeType error code. 0 means success.

note

Adobe MM fonts limit the number of designs, and thus the length of the weight vector, to 16 elements.

since

2.10

FT_VAR_AXIS_FLAG_XXX¶

Defined in FT_MULTIPLE_MASTERS_H (freetype/ftmm.h).

#define FT_VAR_AXIS_FLAG_HIDDEN  1

A list of bit flags used in the return value of FT_Get_Var_Axis_Flags.

values

FT_VAR_AXIS_FLAG_HIDDEN

The variation axis should not be exposed to user interfaces.

since

2.8.1

FT_Get_Var_Axis_Flags¶

Defined in FT_MULTIPLE_MASTERS_H (freetype/ftmm.h).

  FT_EXPORT( FT_Error )
  FT_Get_Var_Axis_Flags( FT_MM_Var*  master,
                         FT_UInt     axis_index,
                         FT_UInt*    flags );

Get the ‘flags’ field of an OpenType Variation Axis Record.

Not meaningful for Adobe MM fonts (*flags is always zero).

input

master	The variation descriptor.
axis_index	The index of the requested variation axis.

output

flags

The ‘flags’ field. See FT_VAR_AXIS_FLAG_XXX for possible values.

return

FreeType error code. 0 means success.

since

2.8.1

FT_Set_Named_Instance¶

Defined in FT_MULTIPLE_MASTERS_H (freetype/ftmm.h).

  FT_EXPORT( FT_Error )
  FT_Set_Named_Instance( FT_Face  face,
                         FT_UInt  instance_index );

Set or change the current named instance.

input

face	A handle to the source face.
instance_index	The index of the requested instance, starting with value 1. If set to value 0, FreeType switches to font access without a named instance.

return

FreeType error code. 0 means success.

note

The function uses the value of instance_index to set bits 16-30 of the face's face_index field. It also resets any variation applied to the font, and the FT_FACE_FLAG_VARIATION bit of the face's face_flags field gets reset to zero (i.e., FT_IS_VARIATION returns false).

For Adobe MM fonts, this function resets the current face to the default instance.

since

2.9

FT_Get_Default_Named_Instance¶

Defined in FT_MULTIPLE_MASTERS_H (freetype/ftmm.h).

  FT_EXPORT( FT_Error )
  FT_Get_Default_Named_Instance( FT_Face   face,
                                 FT_UInt  *instance_index );

Retrieve the index of the default named instance, to be used with FT_Set_Named_Instance.

FreeType synthesizes a named instance for the default instance if the font does not contain such an entry.

input

face	A handle to the source face.

output

instance_index

The index of the default named instance.

return

FreeType error code. 0 means success.

note

For Adobe MM fonts, this function always returns zero for instance_index.

since

2.13.1