From 66725768cdf758cfb3f9abf03cbf5e5a77f42088 Mon Sep 17 00:00:00 2001 From: Werner Lemberg Date: Sun, 15 Jan 2017 16:17:26 +0100 Subject: [PATCH] ftmm.h: Revise documentation. This commit is viewed best with git diff --color-words='[^*/ ]+' --- include/freetype/ftmm.h | 131 ++++++++++++++++++++++++---------------- 1 file changed, 78 insertions(+), 53 deletions(-) diff --git a/include/freetype/ftmm.h b/include/freetype/ftmm.h index ae9e6019d..96dd62523 100644 --- a/include/freetype/ftmm.h +++ b/include/freetype/ftmm.h @@ -43,11 +43,10 @@ FT_BEGIN_HEADER /* 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. */ + /* 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. */ /* */ /*************************************************************************/ @@ -58,10 +57,11 @@ FT_BEGIN_HEADER /* FT_MM_Axis */ /* */ /* */ - /* A simple structure used to model a given axis in design space for */ - /* Multiple Masters fonts. */ + /* A structure to model a given axis in design space for Multiple */ + /* Masters fonts. */ /* */ - /* This structure can't be used for GX var fonts. */ + /* This structure can't be used for TrueType GX or OpenType variation */ + /* fonts. */ /* */ /* */ /* name :: The axis's name. */ @@ -85,10 +85,11 @@ FT_BEGIN_HEADER /* FT_Multi_Master */ /* */ /* */ - /* A structure used to model the axes and space of a Multiple Masters */ + /* A structure to model the axes and space of a Multiple Masters */ /* font. */ /* */ - /* This structure can't be used for GX var fonts. */ + /* This structure can't be used for TrueType GX or OpenType variation */ + /* fonts. */ /* */ /* */ /* num_axis :: Number of axes. Cannot exceed~4. */ @@ -115,27 +116,35 @@ FT_BEGIN_HEADER /* FT_Var_Axis */ /* */ /* */ - /* A simple structure used to model a given axis in design space for */ - /* Multiple Masters and GX var fonts. */ + /* A structure to model a given axis in design space for Multiple */ + /* Masters, TrueType GX, and OpenType variation fonts. */ /* */ /* */ /* name :: The axis's name. */ - /* Not always meaningful for GX. */ + /* 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 MM; it */ - /* is then an integer value, not in 16.16 format. */ + /* FreeType computes meaningful default values for Adobe */ + /* MM fonts. */ /* */ /* 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. */ + /* 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 entry in `name' table (another GX version of */ - /* `name'). */ - /* Not meaningful for MM. */ + /* 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. */ + /* */ + /* */ + /* 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. */ /* */ typedef struct FT_Var_Axis_ { @@ -157,9 +166,10 @@ FT_BEGIN_HEADER /* FT_Var_Named_Style */ /* */ /* */ - /* A simple structure used to model a named style in a GX var font. */ + /* A structure to model a named style in a TrueType GX or OpenType */ + /* variation font. */ /* */ - /* This structure can't be used for MM fonts. */ + /* This structure can't be used for Adobe MM fonts. */ /* */ /* */ /* coords :: The design coordinates for this style. */ @@ -185,17 +195,19 @@ FT_BEGIN_HEADER /* FT_MM_Var */ /* */ /* */ - /* A structure used to model the axes and space of a Multiple Masters */ - /* or GX var distortable font. */ + /* A structure to model the axes and space of a Adobe MM, TrueType */ + /* GX, or OpenType variation font. */ /* */ - /* Some fields are specific to one format and not to the other. */ + /* Some fields are specific to one format and not to the others. */ /* */ /* */ /* num_axis :: The number of axes. The maximum value is~4 for */ - /* MM; no limit in GX. */ + /* 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 MM fonts. Not meaningful for GX */ + /* 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). */ /* */ @@ -205,19 +217,20 @@ FT_BEGIN_HEADER /* 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. */ + /* For Adobe 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. */ + /* 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 table. */ - /* Only meaningful with GX. */ - /* Memory management of this pointer is done */ - /* internally by FreeType. */ + /* Only meaningful for TrueType GX and OpenType */ + /* variation fonts. Memory management of this */ + /* pointer is done internally by FreeType. */ /* */ typedef struct FT_MM_Var_ { @@ -236,9 +249,10 @@ FT_BEGIN_HEADER /* FT_Get_Multi_Master */ /* */ /* */ - /* Retrieve the Multiple Master descriptor of a given font. */ + /* Retrieve a variation descriptor of a given Adobe MM font. */ /* */ - /* This function can't be used with GX fonts. */ + /* This function can't be used with TrueType GX or OpenType variation */ + /* fonts. */ /* */ /* */ /* face :: A handle to the source face. */ @@ -260,13 +274,15 @@ FT_BEGIN_HEADER /* FT_Get_MM_Var */ /* */ /* */ - /* Retrieve the Multiple Master/GX var descriptor of a given font. */ + /* Retrieve a variation descriptor for a given font. */ + /* */ + /* This function works with all supported variation formats. */ /* */ /* */ /* face :: A handle to the source face. */ /* */ /* */ - /* amaster :: The Multiple Masters/GX var descriptor. */ + /* amaster :: The variation descriptor. */ /* Allocates a data structure, which the user must */ /* deallocate with `free' after use. */ /* */ @@ -284,10 +300,11 @@ FT_BEGIN_HEADER /* FT_Set_MM_Design_Coordinates */ /* */ /* */ - /* For Multiple Masters fonts, choose an interpolated font design */ - /* through design coordinates. */ + /* For Adobe MM fonts, choose an interpolated font design through */ + /* design coordinates. */ /* */ - /* This function can't be used with GX fonts. */ + /* This function can't be used with TrueType GX or OpenType variation */ + /* fonts. */ /* */ /* */ /* face :: A handle to the source face. */ @@ -315,8 +332,9 @@ FT_BEGIN_HEADER /* FT_Set_Var_Design_Coordinates */ /* */ /* */ - /* For Multiple Master or GX Var fonts, choose an interpolated font */ - /* design through design coordinates. */ + /* Choose an interpolated font design through design coordinates. */ + /* */ + /* This function works with all supported variation formats. */ /* */ /* */ /* face :: A handle to the source face. */ @@ -344,8 +362,10 @@ FT_BEGIN_HEADER /* FT_Get_Var_Design_Coordinates */ /* */ /* */ - /* For Multiple Master and GX Var fonts, get the design coordinates */ - /* of the currently selected interpolated font. */ + /* Get the design coordinates of the currently selected interpolated */ + /* font. */ + /* */ + /* This function works with all supported variation formats. */ /* */ /* */ /* face :: A handle to the source face. */ @@ -372,8 +392,10 @@ FT_BEGIN_HEADER /* FT_Set_MM_Blend_Coordinates */ /* */ /* */ - /* For Multiple Masters and GX var fonts, choose an interpolated font */ - /* design through normalized blend coordinates. */ + /* Choose an interpolated font design through normalized blend */ + /* coordinates. */ + /* */ + /* This function works with all supported variation formats. */ /* */ /* */ /* face :: A handle to the source face. */ @@ -385,8 +407,9 @@ FT_BEGIN_HEADER /* 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). */ + /* between 0 and 1.0 for Adobe MM fonts, and between */ + /* -1.0 and 1.0 for TrueType GX and OpenType variation */ + /* fonts). */ /* */ /* */ /* FreeType error code. 0~means success. */ @@ -403,16 +426,18 @@ FT_BEGIN_HEADER /* FT_Get_MM_Blend_Coordinates */ /* */ /* */ - /* For Multiple Masters and GX var fonts, get the normalized blend */ - /* coordinates of the currently selected interpolated font. */ + /* Get the normalized blend coordinates of the currently selected */ + /* interpolated font. */ + /* */ + /* This function works with all supported variation formats. */ /* */ /* */ /* 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. */ + /* set the excess values to~0.5 for Adobe MM fonts, and */ + /* to~0 for TrueType GX and OpenType variation fonts. */ /* */ /* */ /* coords :: The normalized blend coordinates array. */