/****************************************************************************

 *

 * ftmm.h

 *

 *   FreeType Multiple Master font interface (specification).

 *

 * Copyright (C) 1996-2019 by

 * David Turner, Robert Wilhelm, and Werner Lemberg.

 *

 * This file is part of the FreeType project, and may only be used,

 * modified, and distributed under the terms of the FreeType project

 * license, LICENSE.TXT.  By continuing to use, modify, or distribute

 * this file you indicate that you have read the license and

 * understand and accept it fully.

 *

 */

  /**************************************************************************

   *

   * @section:

   *   multiple_masters

   *

   * @title:

   *   Multiple Masters

   *

   * @abstract:

   *   How to manage Multiple Masters fonts.

   *

   * @description:

   *   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.

   *

   *   Besides Adobe MM fonts, the interface supports Apple's TrueType GX and

   *   OpenType variation fonts.  Some of the routines only work with Adobe

   *   MM fonts, others will work with all three types.  They are similar

   *   enough that a consistent interface makes sense.

   *

   */

  /**************************************************************************

   *

   * @struct:

   *   FT_MM_Axis

   *

   * @description:

   *   A structure to model a given axis in design space for Multiple Masters

   *   fonts.

   *

   *   This structure can't be used for TrueType GX or OpenType variation

   *   fonts.

   *

   * @fields:

   *   name ::

   *     The axis's name.

   *

   *   minimum ::

   *     The axis's minimum design coordinate.

   *

   *   maximum ::

   *     The axis's maximum design coordinate.

   */

  /**************************************************************************

   *

   * @struct:

   *   FT_Multi_Master

   *

   * @description:

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

   *

   *   This structure can't be used for TrueType GX or OpenType variation

   *   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.

   */

  /**************************************************************************

   *

   * @struct:

   *   FT_Var_Axis

   *

   * @description:

   *   A structure to model a given axis in design space for Multiple

   *   Masters, TrueType GX, and OpenType variation fonts.

   *

   * @fields:

   *   name ::

   *     The axis's name.  Not always meaningful for TrueType GX or OpenType

   *     variation fonts.

   *

   *   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 variation fonts).  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 variation fonts.  Not meaningful for Adobe MM fonts.

   *

   * @note:

   *   The fields `minimum`, `def`, and `maximum` are 16.16 fractional values

   *   for TrueType GX and OpenType variation fonts.  For Adobe MM fonts, the

   *   values are integers.

   */

  /**************************************************************************

   *

   * @struct:

   *   FT_Var_Named_Style

   *

   * @description:

   *   A structure to model a named instance in a TrueType GX or OpenType

   *   variation font.

   *

   *   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 ::

   *     The entry in 'name' table identifying this instance.

   *

   *   psid ::

   *     The entry in 'name' table identifying a PostScript name for this

   *     instance.  Value 0xFFFF indicates a missing entry.

   */

  /**************************************************************************

   *

   * @struct:

   *   FT_MM_Var

   *

   * @description:

   *   A structure to model the axes and space of an Adobe MM, TrueType GX,

   *   or OpenType variation font.

   *

   *   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 variation fonts.

   *

   *   num_designs ::

   *     The number of designs; should be normally 2^num_axis for Adobe MM

   *     fonts.  Not meaningful for TrueType GX or OpenType variation fonts

   *     (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'.  Another name for 'named style' is

   *     'named instance'.

   *

   *     For Adobe Multiple Masters fonts, this value is always zero because

   *     the format does not support named styles.

   *

   *   axis ::

   *     An axis descriptor table.  TrueType GX and OpenType variation fonts

   *     contain slightly more data than Adobe MM fonts.  Memory management

   *     of this pointer is done internally by FreeType.

   *

   *   namedstyle ::

   *     A named style (instance) table.  Only meaningful for TrueType GX and

   *     OpenType variation fonts.  Memory management of this pointer is done

   *     internally by FreeType.

   */

  /**************************************************************************

   *

   * @function:

   *   FT_Get_Multi_Master

   *

   * @description:

   *   Retrieve a variation descriptor of a given Adobe MM font.

   *

   *   This function can't be used with TrueType GX or OpenType variation

   *   fonts.

   *

   * @input:

   *   face ::

   *     A handle to the source face.

   *

   * @output:

   *   amaster ::

   *     The Multiple Masters descriptor.

   *

   * @return:

   *   FreeType error code.  0~means success.

   */

  /**************************************************************************

   *

   * @function:

   *   FT_Get_MM_Var

   *

   * @description:

   *   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.

   */

  /**************************************************************************

   *

   * @function:

   *   FT_Done_MM_Var

   *

   * @description:

   *   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.

   */

  /**************************************************************************

   *

   * @function:

   *   FT_Set_MM_Design_Coordinates

   *

   * @description:

   *   For Adobe MM fonts, choose an interpolated font design through design

   *   coordinates.

   *

   *   This function can't be used with TrueType GX or OpenType variation

   *   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.

   *

   * @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 will return true).  If `num_coords` is zero,

   *   this bit flag gets unset.

   */

  /**************************************************************************

   *

   * @function:

   *   FT_Set_Var_Design_Coordinates

   *

   * @description:

   *   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:

   *   [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 will return true).  If `num_coords` is zero,

   *   this bit flag gets unset.

   */

  /**************************************************************************

   *

   * @function:

   *   FT_Get_Var_Design_Coordinates

   *

   * @description:

   *   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.

   *

   * @return:

   *   FreeType error code.  0~means success.

   *

   * @since:

   *   2.7.1

   */

  /**************************************************************************

   *

   * @function:

   *   FT_Set_MM_Blend_Coordinates

   *

   * @description:

   *   Choose an interpolated font design through normalized blend

   *   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 design coordinates array (each element must be between 0 and 1.0

   *     for Adobe MM fonts, and between -1.0 and 1.0 for TrueType GX and

   *     OpenType variation fonts).

   *

   * @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 will return true).  If `num_coords` is zero,

   *   this bit flag gets unset.

   */

  /**************************************************************************

   *

   * @function:

   *   FT_Get_MM_Blend_Coordinates

   *

   * @description: