[doc] Revise font variation API.
diff --git a/include/freetype/ftmm.h b/include/freetype/ftmm.h
index f97dfab..79ea8b5 100644
--- a/include/freetype/ftmm.h
+++ b/include/freetype/ftmm.h
@@ -37,24 +37,79 @@
* multiple_masters
*
* @title:
- * Multiple Masters
+ * OpenType Font Variations, TrueType GX, and Adobe MM Fonts
*
* @abstract:
- * How to manage Multiple Masters fonts.
+ * How to manage variable fonts with multiple design axes.
*
* @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.
+ * 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.
*
- * Besides Adobe MM fonts, the interface supports Apple's TrueType GX and
- * OpenType Font Variations. 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.
+ * For historical reasons there a 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.
*
* 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](https://learn.microsoft.com/en-us/typography/opentype/spec/otvaroverview)
+ * 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](https://adobe-type-tools.github.io/font-tech-notes/pdfs/5015.Type1_Supp.pdf)
+ * 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].
*/
@@ -90,7 +145,7 @@
* @description:
* A structure to model a given axis in design space for Adobe MM fonts.
*
- * This structure can't be used for TrueType GX or OpenType Font
+ * This structure can't be used with TrueType GX or OpenType Font
* Variations.
*
* @fields:
@@ -120,7 +175,7 @@
* @description:
* A structure to model the axes and space of an Adobe MM font.
*
- * This structure can't be used for TrueType GX or OpenType Font
+ * This structure can't be used with TrueType GX or OpenType Font
* Variations.
*
* @fields:
@@ -128,7 +183,7 @@
* Number of axes. Cannot exceed~4.
*
* num_designs ::
- * Number of designs; should be normally 2^num_axis even though the
+ * 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.
*
@@ -214,11 +269,11 @@
* entry for each axis.
*
* strid ::
- * The entry in 'name' table identifying this instance.
+ * An index into the 'name' table identifying this instance.
*
* psid ::
- * The entry in 'name' table identifying a PostScript name for this
- * instance. Value 0xFFFF indicates a missing entry.
+ * An index into the 'name' table identifying a PostScript name for
+ * this instance. Value 0xFFFF indicates a missing entry.
*/
typedef struct FT_Var_Named_Style_
{
@@ -235,8 +290,8 @@
* FT_MM_Var
*
* @description:
- * A structure to model the axes and space of an Adobe MM, TrueType GX,
- * or OpenType Font Variations.
+ * 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.
*
@@ -246,19 +301,13 @@
* limit in TrueType GX or OpenType Font Variations.
*
* num_designs ::
- * The number of designs; should be normally 2^num_axis for Adobe MM
+ * 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 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 MM fonts, this value is always zero because the format
- * does not support named styles.
+ * 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
@@ -266,7 +315,7 @@
* of this pointer is done internally by FreeType.
*
* namedstyle ::
- * A named style (instance) table. Only meaningful for TrueType GX and
+ * An array of named instances. Only meaningful for TrueType GX and
* OpenType Font Variations. Memory management of this pointer is done
* internally by FreeType.
*/
@@ -473,7 +522,7 @@
*
* @output:
* coords ::
- * The design coordinates array.
+ * The design coordinates array, which must be allocated by the user.
*
* @return:
* FreeType error code. 0~means success.
@@ -498,8 +547,7 @@
* FT_Set_MM_Blend_Coordinates
*
* @description:
- * Choose an interpolated font design through normalized blend
- * coordinates.
+ * Choose an interpolated font design through normalized coordinates.
*
* This function works with all supported variation formats.
*
@@ -514,9 +562,10 @@
* the number of axes, use default values for the remaining axes.
*
* coords ::
- * The design 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.
+ * 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.
@@ -550,8 +599,8 @@
* FT_Get_MM_Blend_Coordinates
*
* @description:
- * Get the normalized blend coordinates of the currently selected
- * interpolated font.
+ * Get the normalized coordinates of the currently selected interpolated
+ * font.
*
* This function works with all supported variation formats.
*
@@ -560,14 +609,14 @@
* 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
- * Adobe MM fonts, and to~0 for TrueType GX and OpenType Font
- * Variations.
+ * 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 blend coordinates array (as 16.16 fractional values).
+ * The normalized coordinates array (as 16.16 fractional values), which
+ * must be allocated by the user.
*
* @return:
* FreeType error code. 0~means success.
@@ -641,8 +690,8 @@
* 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.
+ * 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.,
@@ -650,7 +699,7 @@
* 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
+ * `WeightVector` array must total 1.0 +/-~0.001. In practice this does
* not seem to be enforced, so is not enforced here, either.
*
* @since:
@@ -688,14 +737,14 @@
*
* @output:
* weightvector ::
- * An array to be filled.
+ * 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 WeightVector to~16.
+ * Adobe MM fonts limit the number of designs, and thus the length of the
+ * weight vector, to~16 elements.
*
* @since:
* 2.10
@@ -771,8 +820,8 @@
* 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
+ * 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:
@@ -782,11 +831,11 @@
* 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 will
- * return false).
+ * `face_flags` field gets reset to zero (i.e., @FT_IS_VARIATION returns
+ * false).
*
- * For Adobe MM fonts (which don't have named instances) this function
- * simply resets the current face to the default instance.
+ * For Adobe MM fonts, this function resets the current face to the
+ * default instance.
*
* @since:
* 2.9
@@ -805,10 +854,6 @@
* Retrieve the index of the default named instance, to be used with
* @FT_Set_Named_Instance.
*
- * The default instance of a variation font is that instance for which
- * the nth axis coordinate is equal to `axis[n].def` (as specified in the
- * @FT_MM_Var structure), with~n covering all axes.
- *
* FreeType synthesizes a named instance for the default instance if the
* font does not contain such an entry.
*
@@ -824,8 +869,8 @@
* FreeType error code. 0~means success.
*
* @note:
- * For Adobe MM fonts (which don't have named instances) this function
- * always returns zero for `instance_index`.
+ * For Adobe MM fonts, this function always returns zero for
+ * `instance_index`.
*
* @since:
* 2.13.1
diff --git a/src/truetype/ttgxvar.c b/src/truetype/ttgxvar.c
index 071d6f8..b650a78 100644
--- a/src/truetype/ttgxvar.c
+++ b/src/truetype/ttgxvar.c
@@ -2810,7 +2810,7 @@
FT_UInt strid = ~0U;
- /* The default instance is missing in array the */
+ /* The default instance is missing in the array */
/* of named instances; try to synthesize an entry. */
/* If this fails, `default_named_instance` remains */
/* at value zero, which doesn't do any harm. */
