[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
[freetype2] master 8665e3f 2/2: freetype.h: Revise documentation.
|
From: |
Werner LEMBERG |
|
Subject: |
[freetype2] master 8665e3f 2/2: freetype.h: Revise documentation. |
|
Date: |
Sun, 15 Jan 2017 14:25:50 +0000 (UTC) |
branch: master
commit 8665e3f4af0676de37a0a721441e2a699da03e23
Author: Werner Lemberg <address@hidden>
Commit: Werner Lemberg <address@hidden>
freetype.h: Revise documentation.
This commit is viewed best with
git diff --color-words='[^*/ ]+'
---
include/freetype/freetype.h | 656 ++++++++++++++++++++++---------------------
1 file changed, 336 insertions(+), 320 deletions(-)
diff --git a/include/freetype/freetype.h b/include/freetype/freetype.h
index 1951ac7..b6c6032 100644
--- a/include/freetype/freetype.h
+++ b/include/freetype/freetype.h
@@ -265,8 +265,8 @@ FT_BEGIN_HEADER
/* FT_Glyph_Metrics */
/* */
/* <Description> */
- /* A structure used to model the metrics of a single glyph. The */
- /* values are expressed in 26.6 fractional pixel format; if the flag */
+ /* A structure to model the metrics of a single glyph. The values */
+ /* are expressed in 26.6 fractional pixel format; if the flag */
/* @FT_LOAD_NO_SCALE has been used while loading the glyph, values */
/* are expressed in font units instead. */
/* */
@@ -349,10 +349,10 @@ FT_BEGIN_HEADER
/* */
/* <Note> */
/* Windows FNT: */
- /* The nominal size given in a FNT font is not reliable. Thus when */
- /* the driver finds it incorrect, it sets `size' to some calculated */
- /* values and sets `x_ppem' and `y_ppem' to the pixel width and */
- /* height given in the font, respectively. */
+ /* The nominal size given in a FNT font is not reliable. If the */
+ /* driver finds it incorrect, it sets `size' to some calculated */
+ /* values, and `x_ppem' and `y_ppem' to the pixel width and height */
+ /* given in the font, respectively. */
/* */
/* TrueType embedded bitmaps: */
/* `size', `width', and `height' values are not contained in the */
@@ -421,9 +421,9 @@ FT_BEGIN_HEADER
/* FT_Module */
/* */
/* <Description> */
- /* A handle to a given FreeType module object. Each module can be a */
+ /* A handle to a given FreeType module object. A module can be a */
/* font driver, a renderer, or anything else that provides services */
- /* to the formers. */
+ /* to the former. */
/* */
typedef struct FT_ModuleRec_* FT_Module;
@@ -434,8 +434,8 @@ FT_BEGIN_HEADER
/* FT_Driver */
/* */
/* <Description> */
- /* A handle to a given FreeType font driver object. Each font driver */
- /* is a special module capable of creating faces from font files. */
+ /* A handle to a given FreeType font driver object. A font driver */
+ /* is a module capable of creating faces from font files. */
/* */
typedef struct FT_DriverRec_* FT_Driver;
@@ -446,10 +446,10 @@ FT_BEGIN_HEADER
/* FT_Renderer */
/* */
/* <Description> */
- /* A handle to a given FreeType renderer. A renderer is a special */
- /* module in charge of converting a glyph image to a bitmap, when */
- /* necessary. Each renderer supports a given glyph image format, and */
- /* one or more target surface depths. */
+ /* A handle to a given FreeType renderer. A renderer is a module in */
+ /* charge of converting a glyph's outline image to a bitmap. It */
+ /* supports a single glyph image format, and one or more target */
+ /* surface depths. */
/* */
typedef struct FT_RendererRec_* FT_Renderer;
@@ -467,15 +467,15 @@ FT_BEGIN_HEADER
/* FT_Face */
/* */
/* <Description> */
- /* A handle to a given typographic face object. A face object models */
- /* a given typeface, in a given style. */
+ /* A handle to a typographic face object. A face object models a */
+ /* given typeface, in a given style. */
/* */
/* <Note> */
- /* Each face object also owns a single @FT_GlyphSlot object, as well */
+ /* A face object also owns a single @FT_GlyphSlot object, as well */
/* as one or more @FT_Size objects. */
/* */
/* Use @FT_New_Face or @FT_Open_Face to create a new face object from */
- /* a given filepathname or a custom input stream. */
+ /* a given filepath or a custom input stream. */
/* */
/* Use @FT_Done_Face to destroy it (along with its slot and sizes). */
/* */
@@ -500,11 +500,11 @@ FT_BEGIN_HEADER
/* FT_Size */
/* */
/* <Description> */
- /* A handle to an object used to model a face scaled to a given */
+ /* A handle to an object that models a face scaled to a given */
/* character size. */
/* */
/* <Note> */
- /* Each @FT_Face has an _active_ @FT_Size object that is used by */
+ /* An @FT_Face has one _active_ @FT_Size object that is used by */
/* functions like @FT_Load_Glyph to determine the scaling */
/* transformation that in turn is used to load and hint glyphs and */
/* metrics. */
@@ -531,9 +531,8 @@ FT_BEGIN_HEADER
/* FT_GlyphSlot */
/* */
/* <Description> */
- /* A handle to a given `glyph slot'. A slot is a container where it */
- /* is possible to load any of the glyphs contained in its parent */
- /* face. */
+ /* A handle to a given `glyph slot'. A slot is a container that can */
+ /* hold any of the glyphs contained in its parent face. */
/* */
/* In other words, each time you call @FT_Load_Glyph or */
/* @FT_Load_Char, the slot's content is erased by the new glyph data, */
@@ -552,13 +551,14 @@ FT_BEGIN_HEADER
/* FT_CharMap */
/* */
/* <Description> */
- /* A handle to a given character map. A charmap is used to translate */
- /* character codes in a given encoding into glyph indexes for its */
- /* parent's face. Some font formats may provide several charmaps per */
- /* font. */
+ /* A handle to a character map (usually abbreviated to `charmap'). A */
+ /* charmap is used to translate character codes in a given encoding */
+ /* into glyph indexes for its parent's face. Some font formats may */
+ /* provide several charmaps per font. */
/* */
/* Each face object owns zero or more charmaps, but only one of them */
- /* can be `active' and used by @FT_Get_Char_Index or @FT_Load_Char. */
+ /* can be `active', providing the data used by @FT_Get_Char_Index or */
+ /* @FT_Load_Char. */
/* */
/* The list of available charmaps in a face is available through the */
/* `face->num_charmaps' and `face->charmaps' fields of @FT_FaceRec. */
@@ -615,8 +615,8 @@ FT_BEGIN_HEADER
/* FT_Encoding */
/* */
/* <Description> */
- /* An enumeration used to specify character sets supported by */
- /* charmaps. Used in the @FT_Select_Charmap API function. */
+ /* An enumeration to specify character sets supported by charmaps. */
+ /* Used in the @FT_Select_Charmap API function. */
/* */
/* <Note> */
/* Despite the name, this enumeration lists specific character */
@@ -630,18 +630,17 @@ FT_BEGIN_HEADER
/* The encoding value~0 is reserved. */
/* */
/* FT_ENCODING_UNICODE :: */
- /* Corresponds to the Unicode character set. This value covers */
- /* all versions of the Unicode repertoire, including ASCII and */
- /* Latin-1. Most fonts include a Unicode charmap, but not all */
- /* of them. */
+ /* The Unicode character set. This value covers all versions of */
+ /* the Unicode repertoire, including ASCII and Latin-1. Most fonts */
+ /* include a Unicode charmap, but not all of them. */
/* */
/* For example, if you want to access Unicode value U+1F028 (and */
/* the font contains it), use value 0x1F028 as the input value for */
/* @FT_Get_Char_Index. */
/* */
/* FT_ENCODING_MS_SYMBOL :: */
- /* Corresponds to the Microsoft Symbol encoding, used to encode */
- /* mathematical symbols and wingdings. For more information, see */
+ /* Microsoft Symbol encoding, used to encode mathematical symbols */
+ /* and wingdings. For more information, see */
/* `http://www.microsoft.com/typography/otspec/recom.htm', */
/* `http://www.kostis.net/charsets/symbol.htm', and */
/* `http://www.kostis.net/charsets/wingding.htm'. */
@@ -650,9 +649,9 @@ FT_BEGIN_HEADER
/* Area) in the range U+F020-U+F0FF. */
/* */
/* FT_ENCODING_SJIS :: */
- /* Corresponds to Japanese SJIS encoding. More info at */
- /* `http://en.wikipedia.org/wiki/Shift_JIS'. */
- /* See note on multi-byte encodings below. */
+ /* Shift JIS encoding for Japanese. More info at */
+ /* `http://en.wikipedia.org/wiki/Shift_JIS'. See note on */
+ /* multi-byte encodings below. */
/* */
/* FT_ENCODING_GB2312 :: */
/* Corresponds to an encoding system for Simplified Chinese as */
@@ -663,9 +662,10 @@ FT_BEGIN_HEADER
/* used in Taiwan and Hong Kong. */
/* */
/* FT_ENCODING_WANSUNG :: */
- /* Corresponds to the Korean encoding system known as Wansung. */
+ /* Corresponds to the Korean encoding system known as Extended */
+ /* Wansung (MS Windows code page 949). */
/* For more information see */
- /* `https://msdn.microsoft.com/en-US/goglobal/cc305154'. */
+ /*
`http://www.unicode.org/Public/MAPPINGS/VENDORS/MICSFT/WindowsBestFit/bestfit949.txt'.
*/
/* */
/* FT_ENCODING_JOHAB :: */
/* The Korean standard character set (KS~C 5601-1992), which */
@@ -677,26 +677,24 @@ FT_BEGIN_HEADER
/* PostScript font. It is limited to 256 character codes. */
/* */
/* FT_ENCODING_ADOBE_STANDARD :: */
- /* Corresponds to the Adobe Standard encoding, as found in Type~1, */
- /* CFF, and OpenType/CFF fonts. It is limited to 256 character */
- /* codes. */
+ /* Adobe Standard encoding, as found in Type~1, CFF, and */
+ /* OpenType/CFF fonts. It is limited to 256 character codes. */
/* */
/* FT_ENCODING_ADOBE_EXPERT :: */
- /* Corresponds to the Adobe Expert encoding, as found in Type~1, */
- /* CFF, and OpenType/CFF fonts. It is limited to 256 character */
- /* codes. */
+ /* Adobe Expert encoding, as found in Type~1, CFF, and OpenType/CFF */
+ /* fonts. It is limited to 256 character codes. */
/* */
/* FT_ENCODING_ADOBE_CUSTOM :: */
/* Corresponds to a custom encoding, as found in Type~1, CFF, and */
/* OpenType/CFF fonts. It is limited to 256 character codes. */
/* */
/* FT_ENCODING_APPLE_ROMAN :: */
- /* Corresponds to the 8-bit Apple roman encoding. Many TrueType */
- /* and OpenType fonts contain a charmap for this encoding, since */
- /* older versions of Mac OS are able to use it. */
+ /* Apple roman encoding. Many TrueType and OpenType fonts contain */
+ /* a charmap for this 8-bit encoding, since older versions of Mac */
+ /* OS are able to use it. */
/* */
/* FT_ENCODING_OLD_LATIN_2 :: */
- /* This value is deprecated and was never used nor reported by */
+ /* This value is deprecated and was neither used nor reported by */
/* FreeType. Don't use or test for it. */
/* */
/* FT_ENCODING_MS_SJIS :: */
@@ -716,7 +714,7 @@ FT_BEGIN_HEADER
/* */
/* <Note> */
/* By default, FreeType automatically synthesizes a Unicode charmap */
- /* for PostScript fonts, using their glyph names dictionaries. */
+ /* for PostScript fonts, using their glyph name dictionaries. */
/* However, it also reports the encodings defined explicitly in the */
/* font file, for the cases when they are needed, with the Adobe */
/* values as well. */
@@ -820,11 +818,11 @@ FT_BEGIN_HEADER
/* */
/* platform_id :: An ID number describing the platform for the */
/* following encoding ID. This comes directly from */
- /* the TrueType specification and should be emulated */
+ /* the TrueType specification gets emulated */
/* for other formats. */
/* */
/* encoding_id :: A platform specific encoding number. This also */
- /* comes from the TrueType specification and should be */
+ /* comes from the TrueType specification and gets */
/* emulated similarly. */
/* */
typedef struct FT_CharMapRec_
@@ -852,8 +850,8 @@ FT_BEGIN_HEADER
/* FT_Face_Internal */
/* */
/* <Description> */
- /* An opaque handle to an `FT_Face_InternalRec' structure, used to */
- /* model private data of a given @FT_Face object. */
+ /* An opaque handle to an `FT_Face_InternalRec' structure that models */
+ /* the private data of a given @FT_Face object. */
/* */
/* This structure might change between releases of FreeType~2 and is */
/* not generally available to client applications. */
@@ -873,7 +871,7 @@ FT_BEGIN_HEADER
/* <Fields> */
/* num_faces :: The number of faces in the font file. Some */
/* font formats can have multiple faces in */
- /* a font file. */
+ /* a single font file. */
/* */
/* face_index :: This field holds two different values. */
/* Bits 0-15 are the index of the face in the */
@@ -881,14 +879,15 @@ FT_BEGIN_HEADER
/* are set to~0 if there is only one face in */
/* the font file. */
/* */
- /* Bits 16-30 are relevant to GX variation */
- /* fonts only, holding the named instance */
- /* index for the current face index (starting */
- /* with value~1; value~0 indicates font access */
- /* without GX variation data). For non-GX */
- /* fonts, bits 16-30 are ignored. If we have */
- /* the third named instance of face~4, say, */
- /* `face_index' is set to 0x00030004. */
+ /* Bits 16-30 are relevant to GX and OpenType */
+ /* variation fonts only, holding the named */
+ /* instance index for the current face index */
+ /* (starting with value~1; value~0 indicates */
+ /* font access without variation data). For */
+ /* non-variation fonts, bits 16-30 are */
+ /* ignored. If we have the third named */
+ /* instance of face~4, say, `face_index' is */
+ /* set to 0x00030004. */
/* */
/* Bit 31 is always zero (this is, */
/* `face_index' is always a positive value). */
@@ -902,17 +901,18 @@ FT_BEGIN_HEADER
/* @FT_STYLE_FLAG_XXX for the details. Bits */
/* 16-30 hold the number of named instances */
/* available for the current face if we have a */
- /* GX variation (sub)font. Bit 31 is always */
- /* zero (this is, `style_flags' is always a */
- /* positive value). */
+ /* GX or OpenType variation (sub)font. Bit 31 */
+ /* is always zero (this is, `style_flags' is */
+ /* always a positive value). */
/* */
/* num_glyphs :: The number of glyphs in the face. If the */
/* face is scalable and has sbits (see */
/* `num_fixed_sizes'), it is set to the number */
/* of outline glyphs. */
/* */
- /* For CID-keyed fonts, this value gives the */
- /* highest CID used in the font. */
+ /* For CID-keyed fonts (not in an SFNT */
+ /* wrapper) this value gives the highest CID */
+ /* used in the font. */
/* */
/* family_name :: The face's family name. This is an ASCII */
/* string, usually in English, that describes */
@@ -990,8 +990,8 @@ FT_BEGIN_HEADER
/* expressed in font units. For font formats */
/* not having this information, it is set to */
/* `bbox.yMin'. Note that this field is */
- /* usually negative. Only relevant for */
- /* scalable formats. */
+ /* negative for values below the baseline. */
+ /* Only relevant for scalable formats. */
/* */
/* height :: This value is the vertical distance */
/* between two consecutive baselines, */
@@ -1034,6 +1034,12 @@ FT_BEGIN_HEADER
/* Fields may be changed after a call to @FT_Attach_File or */
/* @FT_Attach_Stream. */
/* */
+ /* For an OpenType variation font, the values of the following fields */
+ /* can change after a call to @FT_Set_Var_Design_Coordinates (and */
+ /* friends) if the font contains an `MVAR' table: `ascender', */
+ /* `descender', `height', `underline_position', and */
+ /* `underline_thickness'. */
+ /* */
typedef struct FT_FaceRec_
{
FT_Long num_faces;
@@ -1105,49 +1111,51 @@ FT_BEGIN_HEADER
/* */
/* <Values> */
/* FT_FACE_FLAG_SCALABLE :: */
- /* Indicates that the face contains outline glyphs. This doesn't */
- /* prevent bitmap strikes, i.e., a face can have both this and */
+ /* The face contains outline glyphs. Note that a face can contain */
+ /* bitmap strikes also, i.e., a face can have both this flag and */
/* @FT_FACE_FLAG_FIXED_SIZES set. */
/* */
/* FT_FACE_FLAG_FIXED_SIZES :: */
- /* Indicates that the face contains bitmap strikes. See also the */
+ /* The face contains bitmap strikes. See also the */
/* `num_fixed_sizes' and `available_sizes' fields of @FT_FaceRec. */
/* */
/* FT_FACE_FLAG_FIXED_WIDTH :: */
- /* Indicates that the face contains fixed-width characters (like */
- /* Courier, Lucido, MonoType, etc.). */
+ /* The face contains fixed-width characters (like Courier, Lucido, */
+ /* MonoType, etc.). */
/* */
/* FT_FACE_FLAG_SFNT :: */
- /* Indicates that the face uses the `sfnt' storage scheme. For */
- /* now, this means TrueType and OpenType. */
+ /* The face uses the SFNT storage scheme. For now, this means */
+ /* TrueType and OpenType. */
/* */
/* FT_FACE_FLAG_HORIZONTAL :: */
- /* Indicates that the face contains horizontal glyph metrics. This */
- /* should be set for all common formats. */
+ /* The face contains horizontal glyph metrics. This should be set */
+ /* for all common formats. */
/* */
/* FT_FACE_FLAG_VERTICAL :: */
- /* Indicates that the face contains vertical glyph metrics. This */
- /* is only available in some formats, not all of them. */
+ /* The face contains vertical glyph metrics. This is only */
+ /* available in some formats, not all of them. */
/* */
/* FT_FACE_FLAG_KERNING :: */
- /* Indicates that the face contains kerning information. If set, */
- /* the kerning distance can be retrieved through the function */
- /* @FT_Get_Kerning. Otherwise the function always return the */
- /* vector (0,0). Note that FreeType doesn't handle kerning data */
- /* from the `GPOS' table (as present in some OpenType fonts). */
+ /* The face contains kerning information. If set, the kerning */
+ /* distance can be retrieved using the function @FT_Get_Kerning. */
+ /* Otherwise the function always return the vector (0,0). Note */
+ /* that FreeType doesn't handle kerning data from the SFNT `GPOS' */
+ /* table (as present in many OpenType fonts). */
/* */
/* FT_FACE_FLAG_FAST_GLYPHS :: */
/* THIS FLAG IS DEPRECATED. DO NOT USE OR TEST IT. */
/* */
/* FT_FACE_FLAG_MULTIPLE_MASTERS :: */
- /* Indicates that the font contains multiple masters and is capable */
- /* of interpolating between them. See the multiple-masters */
- /* specific API for details. */
+ /* The face contains multiple masters and is capable of */
+ /* interpolating between them. Supported formats are Adobe MM, */
+ /* TrueType GX, and OpenType variation fonts. */
+ /* */
+ /* See the multiple-masters specific API for details. */
/* */
/* FT_FACE_FLAG_GLYPH_NAMES :: */
- /* Indicates that the font contains glyph names that can be */
- /* retrieved through @FT_Get_Glyph_Name. Note that some TrueType */
- /* fonts contain broken glyph name tables. Use the function */
+ /* The face contains glyph names, which can be retrieved using */
+ /* @FT_Get_Glyph_Name. Note that some TrueType fonts contain */
+ /* broken glyph name tables. Use the function */
/* @FT_Has_PS_Glyph_Names when needed. */
/* */
/* FT_FACE_FLAG_EXTERNAL_STREAM :: */
@@ -1156,31 +1164,31 @@ FT_BEGIN_HEADER
/* when @FT_Done_Face is called. Don't read or test this flag. */
/* */
/* FT_FACE_FLAG_HINTER :: */
- /* Set if the font driver has a hinting machine of its own. For */
- /* example, with TrueType fonts, it makes sense to use data from */
- /* the SFNT `gasp' table only if the native TrueType hinting engine */
- /* (with the bytecode interpreter) is available and active. */
+ /* The font driver has a hinting machine of its own. For example, */
+ /* with TrueType fonts, it makes sense to use data from the SFNT */
+ /* `gasp' table only if the native TrueType hinting engine (with */
+ /* the bytecode interpreter) is available and active. */
/* */
/* FT_FACE_FLAG_CID_KEYED :: */
- /* Set if the font is CID-keyed. In that case, the font is not */
- /* accessed by glyph indices but by CID values. For subsetted */
- /* CID-keyed fonts this has the consequence that not all index */
- /* values are a valid argument to FT_Load_Glyph. Only the CID */
- /* values for which corresponding glyphs in the subsetted font */
- /* exist make FT_Load_Glyph return successfully; in all other cases */
- /* you get an `FT_Err_Invalid_Argument' error. */
- /* */
- /* Note that CID-keyed fonts that are in an SFNT wrapper don't */
- /* have this flag set since the glyphs are accessed in the normal */
- /* way (using contiguous indices); the `CID-ness' isn't visible to */
- /* the application. */
+ /* The face is CID-keyed. In that case, the face is not accessed */
+ /* by glyph indices but by CID values. For subsetted CID-keyed */
+ /* fonts this has the consequence that not all index values are a */
+ /* valid argument to @FT_Load_Glyph. Only the CID values for which */
+ /* corresponding glyphs in the subsetted font exist make */
+ /* `FT_Load_Glyph' return successfully; in all other cases you get */
+ /* an `FT_Err_Invalid_Argument' error. */
+ /* */
+ /* Note that CID-keyed fonts that are in an SFNT wrapper (this is, */
+ /* all OpenType/CFF fonts) don't have this flag set since the */
+ /* glyphs are accessed in the normal way (using contiguous */
+ /* indices); the `CID-ness' isn't visible to the application. */
/* */
/* FT_FACE_FLAG_TRICKY :: */
- /* Set if the font is `tricky', this is, it always needs the */
- /* font format's native hinting engine to get a reasonable result. */
- /* A typical example is the Chinese font `mingli.ttf' that uses */
- /* TrueType bytecode instructions to move and scale all of its */
- /* subglyphs. */
+ /* The face is `tricky', this is, it always needs the font format's */
+ /* native hinting engine to get a reasonable result. A typical */
+ /* example is the old Chinese font `mingli.ttf' (but not */
+ /* `mingliu.ttc') that uses TrueType bytecode instructions to move */
+ /* and scale all of its subglyphs. */
/* */
/* It is not possible to auto-hint such fonts using */
/* @FT_LOAD_FORCE_AUTOHINT; it will also ignore */
@@ -1192,8 +1200,8 @@ FT_BEGIN_HEADER
/* tricky fonts; they are hard-coded in file `ttobjs.c'. */
/* */
/* FT_FACE_FLAG_COLOR :: */
- /* Set if the font has color glyph tables. To access color glyphs */
- /* use @FT_LOAD_COLOR. */
+ /* The face has color glyph tables. To access color glyphs use */
+ /* @FT_LOAD_COLOR. */
/* */
#define FT_FACE_FLAG_SCALABLE ( 1L << 0 )
#define FT_FACE_FLAG_FIXED_SIZES ( 1L << 1 )
@@ -1265,7 +1273,7 @@ FT_BEGIN_HEADER
* @description:
* A macro that returns true whenever a face object contains a scalable
* font face (true for TrueType, Type~1, Type~42, CID, OpenType/CFF,
- * and PFR font formats.
+ * and PFR font formats).
*
*/
#define FT_IS_SCALABLE( face ) \
@@ -1369,7 +1377,7 @@ FT_BEGIN_HEADER
*
* @description:
* A macro that returns true whenever a face object is a named instance
- * of a GX variation font.
+ * of a GX or OpenType variation font.
*
*/
#define FT_IS_NAMED_INSTANCE( face ) \
@@ -1428,15 +1436,15 @@ FT_BEGIN_HEADER
/* FT_STYLE_FLAG_XXX */
/* */
/* <Description> */
- /* A list of bit flags used to indicate the style of a given face. */
- /* These are used in the `style_flags' field of @FT_FaceRec. */
+ /* A list of bit flags to indicate the style of a given face. These */
+ /* are used in the `style_flags' field of @FT_FaceRec. */
/* */
/* <Values> */
/* FT_STYLE_FLAG_ITALIC :: */
- /* Indicates that a given face style is italic or oblique. */
+ /* The face style is italic or oblique. */
/* */
/* FT_STYLE_FLAG_BOLD :: */
- /* Indicates that a given face is bold. */
+ /* The face is bold. */
/* */
/* <Note> */
/* The style information as provided by FreeType is very basic. More */
@@ -1477,12 +1485,12 @@ FT_BEGIN_HEADER
/* hence the term `ppem' (pixels per EM). It is also */
/* referred to as `nominal height'. */
/* */
- /* x_scale :: A 16.16 fractional scaling value used to convert */
+ /* x_scale :: A 16.16 fractional scaling value to convert */
/* horizontal metrics from font units to 26.6 */
/* fractional pixels. Only relevant for scalable */
/* font formats. */
/* */
- /* y_scale :: A 16.16 fractional scaling value used to convert */
+ /* y_scale :: A 16.16 fractional scaling value to convert */
/* vertical metrics from font units to 26.6 */
/* fractional pixels. Only relevant for scalable */
/* font formats. */
@@ -1513,7 +1521,7 @@ FT_BEGIN_HEADER
/* glyphs. As this would be a definite performance hit, it is up to */
/* client applications to perform such computations. */
/* */
- /* The FT_Size_Metrics structure is valid for bitmap fonts also. */
+ /* The `FT_Size_Metrics' structure is valid for bitmap fonts also. */
/* */
typedef struct FT_Size_Metrics_
{
@@ -1653,8 +1661,8 @@ FT_BEGIN_HEADER
/* contained in the glyph slot. Typically */
/* @FT_GLYPH_FORMAT_BITMAP, */
/* @FT_GLYPH_FORMAT_OUTLINE, or */
- /* @FT_GLYPH_FORMAT_COMPOSITE, but others are */
- /* possible. */
+ /* @FT_GLYPH_FORMAT_COMPOSITE, but other values */
+ /* are possible. */
/* */
/* bitmap :: This field is used as a bitmap descriptor */
/* when the slot format is */
@@ -1669,10 +1677,9 @@ FT_BEGIN_HEADER
/* glyph slot contains a bitmap. */
/* */
/* bitmap_top :: The bitmap's top bearing expressed in integer */
- /* pixels. Remember that this is the distance */
- /* from the baseline to the top-most glyph */
- /* scanline, upwards y~coordinates being */
- /* *positive*. */
+ /* pixels. This is the distance from the */
+ /* baseline to the top-most glyph scanline, */
+ /* upwards y~coordinates being *positive*. */
/* */
/* outline :: The outline descriptor for the current glyph */
/* image if its format is */
@@ -1694,15 +1701,13 @@ FT_BEGIN_HEADER
/* control_data :: Certain font drivers can also return the */
/* control data for a given glyph image (e.g. */
/* TrueType bytecode, Type~1 charstrings, etc.). */
- /* This field is a pointer to such data. */
+ /* This field is a pointer to such data; it is */
+ /* currently internal to FreeType. */
/* */
/* control_len :: This is the length in bytes of the control */
- /* data. */
+ /* data. Currently internal to FreeType. */
/* */
- /* other :: Really wicked formats can use this pointer to */
- /* present their own glyph image to client */
- /* applications. Note that the application */
- /* needs to know about the image format. */
+ /* other :: Reserved. */
/* */
/* lsb_delta :: The difference between hinted and unhinted */
/* left side bearing while auto-hinting is */
@@ -1719,7 +1724,7 @@ FT_BEGIN_HEADER
/* formats). */
/* */
/* This image can later be converted into a bitmap by calling */
- /* @FT_Render_Glyph. This function finds the current renderer for */
+ /* @FT_Render_Glyph. This function searches the current renderer for */
/* the native image's format, then invokes it. */
/* */
/* The renderer is in charge of transforming the native image through */
@@ -1740,8 +1745,8 @@ FT_BEGIN_HEADER
/* */
/* */
/* for all glyphs do */
- /* <compute kern between current and previous glyph and add it to */
- /* `origin_x'> */
+ /* <compute kern between current and previous glyph */
+ /* and add it to `origin_x'> */
/* */
/* <load glyph with `FT_Load_Glyph'> */
/* */
@@ -1906,7 +1911,7 @@ FT_BEGIN_HEADER
/* FT_Parameter */
/* */
/* <Description> */
- /* A simple structure used to pass more or less generic parameters to */
+ /* A simple structure to pass more or less generic parameters to */
/* @FT_Open_Face. */
/* */
/* <Fields> */
@@ -1932,9 +1937,9 @@ FT_BEGIN_HEADER
/* FT_Open_Args */
/* */
/* <Description> */
- /* A structure used to indicate how to open a new font file or */
- /* stream. A pointer to such a structure can be used as a parameter */
- /* for the functions @FT_Open_Face and @FT_Attach_Stream. */
+ /* A structure to indicate how to open a new font file or stream. A */
+ /* pointer to such a structure can be used as a parameter for the */
+ /* functions @FT_Open_Face and @FT_Attach_Stream. */
/* */
/* <Fields> */
/* flags :: A set of bit flags indicating how to use the */
@@ -1949,9 +1954,10 @@ FT_BEGIN_HEADER
/* stream :: A handle to a source stream object. */
/* */
/* driver :: This field is exclusively used by @FT_Open_Face; */
- /* it simply specifies the font driver to use to open */
- /* the face. If set to~0, FreeType tries to load the */
- /* face with each one of the drivers in its list. */
+ /* it simply specifies the font driver to use for */
+ /* opening the face. If set to NULL, FreeType tries */
+ /* to load the face with each one of the drivers in */
+ /* its list. */
/* */
/* num_params :: The number of extra parameters. */
/* */
@@ -2004,7 +2010,7 @@ FT_BEGIN_HEADER
/* FT_New_Face */
/* */
/* <Description> */
- /* This function calls @FT_Open_Face to open a font by its pathname. */
+ /* Call @FT_Open_Face to open a font by its pathname. */
/* */
/* <InOut> */
/* library :: A handle to the library resource. */
@@ -2039,8 +2045,8 @@ FT_BEGIN_HEADER
/* FT_New_Memory_Face */
/* */
/* <Description> */
- /* This function calls @FT_Open_Face to open a font that has been */
- /* loaded into memory. */
+ /* Call @FT_Open_Face to open a font that has been loaded into */
+ /* memory. */
/* */
/* <InOut> */
/* library :: A handle to the library resource. */
@@ -2092,20 +2098,21 @@ FT_BEGIN_HEADER
/* with value~0). Set it to~0 if there is only one */
/* face in the font file. */
/* */
- /* Bits 16-30 are relevant to GX variation fonts only, */
- /* specifying the named instance index for the current */
- /* face index (starting with value~1; value~0 makes */
- /* FreeType ignore named instances). For non-GX fonts, */
- /* bits 16-30 are ignored. Assuming that you want to */
- /* access the third named instance in face~4, */
- /* `face_index' should be set to 0x00030004. If you */
- /* want to access face~4 without GX variation handling, */
- /* simply set `face_index' to value~4. */
- /* */
- /* FT_Open_Face and its siblings can be used to quickly */
- /* check whether the font format of a given font */
- /* resource is supported by FreeType. In general, if */
- /* the `face_index' argument is negative, the */
+ /* Bits 16-30 are relevant to GX and OpenType variation */
+ /* fonts only, specifying the named instance index for */
+ /* the current face index (starting with value~1; */
+ /* value~0 makes FreeType ignore named instances). For */
+ /* non-variation fonts, bits 16-30 are ignored. */
+ /* Assuming that you want to access the third named */
+ /* instance in face~4, `face_index' should be set to */
+ /* 0x00030004. If you want to access face~4 without */
+ /* variation handling, simply set `face_index' to */
+ /* value~4. */
+ /* */
+ /* `FT_Open_Face' and its siblings can be used to */
+ /* quickly check whether the font format of a given */
+ /* font resource is supported by FreeType. In general, */
+ /* if the `face_index' argument is negative, the */
/* function's return value is~0 if the font format is */
/* recognized, or non-zero otherwise. The function */
/* allocates a more or less empty face handle in */
@@ -2114,10 +2121,10 @@ FT_BEGIN_HEADER
/* `face->num_faces' and `face->style_flags'. For any */
/* negative value of `face_index', `face->num_faces' */
/* gives the number of faces within the font file. For */
- /* the negative value `-(N+1)' (with `N' a 16-bit */
- /* value), bits 16-30 in `face->style_flags' give the */
- /* number of named instances in face `N' if we have a */
- /* GX variation font (or zero otherwise). After */
+ /* the negative value `-(N+1)' (with `N' a non-negative */
+ /* 16-bit value), bits 16-30 in `face->style_flags' */
+ /* give the number of named instances in face `N' if we */
+ /* have a variation font (or zero otherwise). After */
/* examination, the returned @FT_Face structure should */
/* be deallocated with a call to @FT_Done_Face. */
/* */
@@ -2224,7 +2231,7 @@ FT_BEGIN_HEADER
/* FT_Attach_File */
/* */
/* <Description> */
- /* This function calls @FT_Attach_Stream to attach a file. */
+ /* Call @FT_Attach_Stream to attach a file. */
/* */
/* <InOut> */
/* face :: The target face object. */
@@ -2268,7 +2275,7 @@ FT_BEGIN_HEADER
/* */
/* Client applications are expected to know what they are doing */
/* when invoking this function. Most drivers simply do not implement */
- /* file attachments. */
+ /* file or stream attachments. */
/* */
FT_EXPORT( FT_Error )
FT_Attach_Stream( FT_Face face,
@@ -2352,11 +2359,11 @@ FT_BEGIN_HEADER
/* FreeType silently uses outlines if there is no bitmap for a given */
/* glyph index. */
/* */
- /* For GX variation fonts, a bitmap strike makes sense only if the */
- /* default instance is active (this is, no glyph variation takes */
- /* place); otherwise, FreeType simply ignores bitmap strikes. The */
- /* same is true for all named instances that are different from the */
- /* default instance. */
+ /* For GX and OpenType variation fonts, a bitmap strike makes sense */
+ /* only if the default instance is active (this is, no glyph */
+ /* variation takes place); otherwise, FreeType simply ignores bitmap */
+ /* strikes. The same is true for all named instances that are */
+ /* different from the default instance. */
/* */
/* Don't use this function if you are using the FreeType cache API. */
/* */
@@ -2389,7 +2396,7 @@ FT_BEGIN_HEADER
/* */
/* FT_SIZE_REQUEST_TYPE_REAL_DIM :: */
/* The real dimension. The sum of the `ascender' and (minus of) */
- /* the `descender' fields of @FT_FaceRec are used to determine both */
+ /* the `descender' fields of @FT_FaceRec is used to determine both */
/* scaling values. */
/* */
/* FT_SIZE_REQUEST_TYPE_BBOX :: */
@@ -2435,7 +2442,7 @@ FT_BEGIN_HEADER
/* FT_Size_RequestRec */
/* */
/* <Description> */
- /* A structure used to model a size request. */
+ /* A structure to model a size request. */
/* */
/* <Fields> */
/* type :: See @FT_Size_Request_Type. */
@@ -2448,14 +2455,16 @@ FT_BEGIN_HEADER
/* */
/* horiResolution :: The horizontal resolution (dpi, i.e., pixels per */
/* inch). If set to zero, `width' is treated as a */
- /* 26.6 fractional *pixel* value. */
+ /* 26.6 fractional *pixel* value, which gets */
+ /* internally rounded to an integer. */
/* */
/* vertResolution :: The vertical resolution (dpi, i.e., pixels per */
/* inch). If set to zero, `height' is treated as a */
- /* 26.6 fractional *pixel* value. */
+ /* 26.6 fractional *pixel* value, which gets */
+ /* internally rounded to an integer. */
/* */
/* <Note> */
- /* If `width' is zero, then the horizontal scaling value is set equal */
+ /* If `width' is zero, the horizontal scaling value is set equal */
/* to the vertical scaling value, and vice versa. */
/* */
/* If `type' is FT_SIZE_REQUEST_TYPE_SCALES, `width' and `height' are */
@@ -2512,7 +2521,7 @@ FT_BEGIN_HEADER
/* size is dependent entirely on how the size is defined in the */
/* source face. The font designer chooses the final size of each */
/* glyph relative to this size. For more information refer to */
- /* `http://www.freetype.org/freetype2/docs/glyphs/glyphs-2.html' */
+ /* `https://www.freetype.org/freetype2/docs/glyphs/glyphs-2.html'. */
/* */
/* Don't use this function if you are using the FreeType cache API. */
/* */
@@ -2527,8 +2536,7 @@ FT_BEGIN_HEADER
/* FT_Set_Char_Size */
/* */
/* <Description> */
- /* This function calls @FT_Request_Size to request the nominal size */
- /* (in points). */
+ /* Call @FT_Request_Size to request the nominal size (in points). */
/* */
/* <InOut> */
/* face :: A handle to a target face object. */
@@ -2546,6 +2554,10 @@ FT_BEGIN_HEADER
/* FreeType error code. 0~means success. */
/* */
/* <Note> */
+ /* While this function allows fractional points as input values, the */
+ /* resulting ppem value for the given resolution is always rounded to */
+ /* the nearest integer. */
+ /* */
/* If either the character width or height is zero, it is set equal */
/* to the other value. */
/* */
@@ -2571,8 +2583,7 @@ FT_BEGIN_HEADER
/* FT_Set_Pixel_Sizes */
/* */
/* <Description> */
- /* This function calls @FT_Request_Size to request the nominal size */
- /* (in pixels). */
+ /* Call @FT_Request_Size to request the nominal size (in pixels). */
/* */
/* <InOut> */
/* face :: A handle to the target face object. */
@@ -2586,8 +2597,8 @@ FT_BEGIN_HEADER
/* FreeType error code. 0~means success. */
/* */
/* <Note> */
- /* You should not rely on the resulting glyphs matching, or being */
- /* constrained, to this pixel size. Refer to @FT_Request_Size to */
+ /* You should not rely on the resulting glyphs matching or being */
+ /* constrained to this pixel size. Refer to @FT_Request_Size to */
/* understand how requested sizes relate to actual sizes. */
/* */
/* Don't use this function if you are using the FreeType cache API. */
@@ -2604,8 +2615,7 @@ FT_BEGIN_HEADER
/* FT_Load_Glyph */
/* */
/* <Description> */
- /* A function used to load a single glyph into the glyph slot of a */
- /* face object. */
+ /* Load a glyph into the glyph slot of a face object. */
/* */
/* <InOut> */
/* face :: A handle to the target face object where the glyph */
@@ -2650,8 +2660,8 @@ FT_BEGIN_HEADER
/* FT_Load_Char */
/* */
/* <Description> */
- /* A function used to load a single glyph into the glyph slot of a */
- /* face object, according to its character code. */
+ /* Load a glyph into the glyph slot of a face object, accessed by its */
+ /* character code. */
/* */
/* <InOut> */
/* face :: A handle to a target face object where the glyph */
@@ -2673,6 +2683,10 @@ FT_BEGIN_HEADER
/* <Note> */
/* This function simply calls @FT_Get_Char_Index and @FT_Load_Glyph. */
/* */
+ /* Many fonts contain glyphs that can't be loaded by this function */
+ /* since its glyph indices are not listed in any of the font's */
+ /* charmaps. */
+ /* */
FT_EXPORT( FT_Error )
FT_Load_Char( FT_Face face,
FT_ULong char_code,
@@ -2685,8 +2699,8 @@ FT_BEGIN_HEADER
* FT_LOAD_XXX
*
* @description:
- * A list of bit field constants used with @FT_Load_Glyph to indicate
- * what kind of operations to perform during glyph loading.
+ * A list of bit field constants for @FT_Load_Glyph to indicate what
+ * kind of operations to perform during glyph loading.
*
* @values:
* FT_LOAD_DEFAULT ::
@@ -2698,13 +2712,13 @@ FT_BEGIN_HEADER
* The bitmap data can be accessed from the glyph slot (see note
* below).
*
- * 2. If no embedded bitmap is searched or found, FreeType looks for a
- * scalable outline. If one is found, it is loaded from the font
- * file, scaled to device pixels, then `hinted' to the pixel grid
- * in order to optimize it. The outline data can be accessed from
- * the glyph slot (see note below).
+ * 2. If no embedded bitmap is searched for or found, FreeType looks
+ * for a scalable outline. If one is found, it is loaded from
+ * the font file, scaled to device pixels, then `hinted' to the
+ * pixel grid in order to optimize it. The outline data can be
+ * accessed from the glyph slot (see note below).
*
- * Note that by default, the glyph loader doesn't render outlines into
+ * Note that by default the glyph loader doesn't render outlines into
* bitmaps. The following flags are used to modify this default
* behaviour to more specific and useful cases.
*
@@ -2751,13 +2765,13 @@ FT_BEGIN_HEADER
* various font formats.
*
* FT_LOAD_FORCE_AUTOHINT ::
- * Indicates that the auto-hinter is preferred over the font's native
- * hinter. See also the note below.
+ * Prefer the auto-hinter over the font's native hinter. See also
+ * the note below.
*
* FT_LOAD_PEDANTIC ::
- * Indicates that the font driver should perform pedantic verifications
- * during glyph loading. This is mostly used to detect broken glyphs
- * in fonts. By default, FreeType tries to handle broken fonts also.
+ * Make the font driver perform pedantic verifications during glyph
+ * loading. This is mostly used to detect broken glyphs in fonts.
+ * By default, FreeType tries to handle broken fonts also.
*
* In particular, errors from the TrueType bytecode engine are not
* passed to the application if this flag is not set; this might
@@ -2765,17 +2779,16 @@ FT_BEGIN_HEADER
* bytecode is buggy.
*
* FT_LOAD_NO_RECURSE ::
- * Indicate that the font driver should not load composite glyphs
- * recursively. Instead, it should set the `num_subglyph' and
- * `subglyphs' values of the glyph slot accordingly, and set
- * `glyph->format' to @FT_GLYPH_FORMAT_COMPOSITE. The description of
- * subglyphs can then be accessed with @FT_Get_SubGlyph_Info.
+ * Don't load composite glyphs recursively. Instead, the font
+ * driver should set the `num_subglyph' and `subglyphs' values of
+ * the glyph slot accordingly, and set `glyph->format' to
+ * @FT_GLYPH_FORMAT_COMPOSITE. The description of subglyphs can
+ * then be accessed with @FT_Get_SubGlyph_Info.
*
* This flag implies @FT_LOAD_NO_SCALE and @FT_LOAD_IGNORE_TRANSFORM.
*
* FT_LOAD_IGNORE_TRANSFORM ::
- * Indicates that the transform matrix set by @FT_Set_Transform should
- * be ignored.
+ * Ignore the transform matrix set by @FT_Set_Transform.
*
* FT_LOAD_MONOCHROME ::
* This flag is used with @FT_LOAD_RENDER to indicate that you want to
@@ -2787,36 +2800,34 @@ FT_BEGIN_HEADER
* monochrome-optimized hinting algorithm is used.
*
* FT_LOAD_LINEAR_DESIGN ::
- * Indicates that the `linearHoriAdvance' and `linearVertAdvance'
- * fields of @FT_GlyphSlotRec should be kept in font units. See
- * @FT_GlyphSlotRec for details.
+ * Keep `linearHoriAdvance' and `linearVertAdvance' fields of
+ * @FT_GlyphSlotRec in font units. See @FT_GlyphSlotRec for
+ * details.
*
* FT_LOAD_NO_AUTOHINT ::
- * Disable auto-hinter. See also the note below.
+ * Disable the auto-hinter. See also the note below.
*
* FT_LOAD_COLOR ::
- * This flag is used to request loading of color embedded-bitmap
- * images. The resulting color bitmaps, if available, will have the
- * @FT_PIXEL_MODE_BGRA format. When the flag is not used and color
- * bitmaps are found, they will be converted to 256-level gray
- * bitmaps transparently. Those bitmaps will be in the
+ * Load embedded color bitmap images. The resulting color bitmaps,
+ * if available, will have the @FT_PIXEL_MODE_BGRA format. If the
+ * flag is not set and color bitmaps are found, they are converted
+ * to 256-level gray bitmaps transparently, using the
* @FT_PIXEL_MODE_GRAY format.
*
* FT_LOAD_COMPUTE_METRICS ::
- * This flag sets computing glyph metrics without the use of bundled
- * metrics tables (for example, the `hdmx' table in TrueType fonts).
- * Well-behaving fonts have optimized bundled metrics and these should
- * be used. This flag is mainly used by font validating or font
+ * Compute glyph metrics from the glyph data, without the use of
+ * bundled metrics tables (for example, the `hdmx' table in TrueType
+ * fonts). This flag is mainly used by font validating or font
* editing applications, which need to ignore, verify, or edit those
* tables.
*
* Currently, this flag is only implemented for TrueType fonts.
*
* FT_LOAD_BITMAP_METRICS_ONLY ::
- * This flag is used to request loading of the metrics and bitmap
- * image information of a (possibly embedded) bitmap glyph without
- * allocating or copying the bitmap image data itself. No effect if
- * the target glyph is not a bitmap image.
+ * Request loading of the metrics and bitmap image information of a
+ * (possibly embedded) bitmap glyph without allocating or copying
+ * the bitmap image data itself. No effect if the target glyph is
+ * not a bitmap image.
*
* This flag unsets @FT_LOAD_RENDER.
*
@@ -2863,14 +2874,14 @@ FT_BEGIN_HEADER
#define FT_LOAD_MONOCHROME ( 1L << 12 )
#define FT_LOAD_LINEAR_DESIGN ( 1L << 13 )
#define FT_LOAD_NO_AUTOHINT ( 1L << 15 )
- /* Bits 16..19 are used by `FT_LOAD_TARGET_' */
+ /* Bits 16-19 are used by `FT_LOAD_TARGET_' */
#define FT_LOAD_COLOR ( 1L << 20 )
#define FT_LOAD_COMPUTE_METRICS ( 1L << 21 )
#define FT_LOAD_BITMAP_METRICS_ONLY ( 1L << 22 )
/* */
- /* used internally only by certain font drivers! */
+ /* used internally only by certain font drivers */
#define FT_LOAD_ADVANCE_ONLY ( 1L << 8 )
#define FT_LOAD_SBITS_ONLY ( 1L << 14 )
@@ -2881,19 +2892,20 @@ FT_BEGIN_HEADER
* FT_LOAD_TARGET_XXX
*
* @description:
- * A list of values that are used to select a specific hinting algorithm
- * to use by the hinter. You should OR one of these values to your
- * `load_flags' when calling @FT_Load_Glyph.
+ * A list of values to select a specific hinting algorithm for the
+ * hinter. You should OR one of these values to your `load_flags'
+ * when calling @FT_Load_Glyph.
*
- * Note that font's native hinters may ignore the hinting algorithm you
- * have specified (e.g., the TrueType bytecode interpreter). You can set
- * @FT_LOAD_FORCE_AUTOHINT to ensure that the auto-hinter is used.
+ * Note that a font's native hinters may ignore the hinting algorithm
+ * you have specified (e.g., the TrueType bytecode interpreter). You
+ * can set @FT_LOAD_FORCE_AUTOHINT to ensure that the auto-hinter is
+ * used.
*
* @values:
* FT_LOAD_TARGET_NORMAL ::
- * This corresponds to the default hinting algorithm, optimized for
- * standard gray-level rendering. For monochrome output, use
- * @FT_LOAD_TARGET_MONO instead.
+ * The default hinting algorithm, optimized for standard gray-level
+ * rendering. For monochrome output, use @FT_LOAD_TARGET_MONO
+ * instead.
*
* FT_LOAD_TARGET_LIGHT ::
* A lighter hinting algorithm for gray-level modes. Many generated
@@ -2902,7 +2914,7 @@ FT_BEGIN_HEADER
* (Y-axis), as is done by Microsoft's ClearType and Adobe's
* proprietary font renderer. This preserves inter-glyph spacing in
* horizontal text. The snapping is done either by the native font
- * driver if the driver itself and the font support it or by the
+ * driver, if the driver itself and the font support it, or by the
* auto-hinter.
*
* FT_LOAD_TARGET_MONO ::
@@ -2968,18 +2980,17 @@ FT_BEGIN_HEADER
/* FT_Set_Transform */
/* */
/* <Description> */
- /* A function used to set the transformation that is applied to glyph */
- /* images when they are loaded into a glyph slot through */
- /* @FT_Load_Glyph. */
+ /* Set the transformation that is applied to glyph images when they */
+ /* are loaded into a glyph slot through @FT_Load_Glyph. */
/* */
/* <InOut> */
/* face :: A handle to the source face object. */
/* */
/* <Input> */
- /* matrix :: A pointer to the transformation's 2x2 matrix. Use~0 for */
- /* the identity matrix. */
- /* delta :: A pointer to the translation vector. Use~0 for the null */
- /* vector. */
+ /* matrix :: A pointer to the transformation's 2x2 matrix. Use NULL */
+ /* for the identity matrix. */
+ /* delta :: A pointer to the translation vector. Use NULL for the */
+ /* null vector. */
/* */
/* <Note> */
/* The transformation is only applied to scalable image formats after */
@@ -3002,9 +3013,8 @@ FT_BEGIN_HEADER
/* FT_Render_Mode */
/* */
/* <Description> */
- /* An enumeration type that lists the render modes supported by */
- /* FreeType~2. Each mode corresponds to a specific type of scanline */
- /* conversion performed on the outline. */
+ /* Render modes supported by FreeType~2. Each mode corresponds to a */
+ /* specific type of scanline conversion performed on the outline. */
/* */
/* For bitmap fonts and embedded bitmaps the `bitmap->pixel_mode' */
/* field in the @FT_GlyphSlotRec structure gives the format of the */
@@ -3017,8 +3027,8 @@ FT_BEGIN_HEADER
/* */
/* <Values> */
/* FT_RENDER_MODE_NORMAL :: */
- /* This is the default render mode; it corresponds to 8-bit */
- /* anti-aliased bitmaps. */
+ /* Default render mode; it corresponds to 8-bit anti-aliased */
+ /* bitmaps. */
/* */
/* FT_RENDER_MODE_LIGHT :: */
/* This is equivalent to @FT_RENDER_MODE_NORMAL. It is only */
@@ -3043,11 +3053,11 @@ FT_BEGIN_HEADER
/* glyph outline in pixels and use the @FT_PIXEL_MODE_LCD_V mode. */
/* */
/* <Note> */
- /* The LCD-optimized glyph bitmaps produced by FT_Render_Glyph can be */
- /* filtered to reduce color-fringes by using @FT_Library_SetLcdFilter */
- /* (not active in the default builds). It is up to the caller to */
- /* either call @FT_Library_SetLcdFilter (if available) or do the */
- /* filtering itself. */
+ /* The LCD-optimized glyph bitmaps produced by `FT_Render_Glyph' can */
+ /* be filtered to reduce color-fringes by using */
+ /* @FT_Library_SetLcdFilter (not active in the default builds). It */
+ /* is up to the caller to either call `FT_Library_SetLcdFilter' (if */
+ /* available) or do the filtering itself. */
/* */
/* The selected render mode only affects vector glyphs of a font. */
/* Embedded bitmaps often have a different pixel mode like */
@@ -3088,16 +3098,16 @@ FT_BEGIN_HEADER
/* convert. */
/* */
/* <Input> */
- /* render_mode :: This is the render mode used to render the glyph */
- /* image into a bitmap. See @FT_Render_Mode for a */
- /* list of possible values. */
+ /* render_mode :: The render mode used to render the glyph image into */
+ /* a bitmap. See @FT_Render_Mode for a list of */
+ /* possible values. */
/* */
/* <Return> */
/* FreeType error code. 0~means success. */
/* */
/* <Note> */
/* To get meaningful results, font scaling values must be set with */
- /* functions like @FT_Set_Char_Size before calling FT_Render_Glyph. */
+ /* functions like @FT_Set_Char_Size before calling `FT_Render_Glyph'. */
/* */
/* When FreeType outputs a bitmap of a glyph, it really outputs an */
/* alpha coverage map. If a pixel is completely covered by a */
@@ -3187,17 +3197,15 @@ FT_BEGIN_HEADER
/* FT_Kerning_Mode */
/* */
/* <Description> */
- /* An enumeration used to specify which kerning values to return in */
+ /* An enumeration to specify the format of kerning values returned by */
/* @FT_Get_Kerning. */
/* */
/* <Values> */
/* FT_KERNING_DEFAULT :: Return grid-fitted kerning distances in */
- /* pixels (value is~0). Whether they are */
- /* scaled depends on @FT_LOAD_NO_SCALE. */
+ /* 26.6 fractional pixels. */
/* */
/* FT_KERNING_UNFITTED :: Return un-grid-fitted kerning distances in */
- /* 26.6 fractional pixels. Whether they are */
- /* scaled depends on @FT_LOAD_NO_SCALE. */
+ /* 26.6 fractional pixels. */
/* */
/* FT_KERNING_UNSCALED :: Return the kerning vector in original font */
/* units. */
@@ -3207,9 +3215,13 @@ FT_BEGIN_HEADER
/* FreeType heuristically scale down kerning distances at small ppem */
/* values so that they don't become too big. */
/* */
+ /* Both FT_KERNING_DEFAULT and FT_KERNING_UNFITTED use the current */
+ /* horizontal scaling factor (as set e.g. with @FT_Set_Char_Size) to */
+ /* convert font units to pixels. */
+ /* */
typedef enum FT_Kerning_Mode_
{
- FT_KERNING_DEFAULT = 0,
+ FT_KERNING_DEFAULT = 0,
FT_KERNING_UNFITTED,
FT_KERNING_UNSCALED
@@ -3229,7 +3241,7 @@ FT_BEGIN_HEADER
/* FT_Get_Kerning */
/* */
/* <Description> */
- /* Return the kerning vector between two glyphs of a same face. */
+ /* Return the kerning vector between two glyphs of the same face. */
/* */
/* <Input> */
/* face :: A handle to a source face object. */
@@ -3257,6 +3269,10 @@ FT_BEGIN_HEADER
/* kernings, are out of the scope of this API function -- they can be */
/* implemented through format-specific interfaces. */
/* */
+ /* Kerning for OpenType fonts implemented in a `GPOS' table is not */
+ /* supported; use @FT_HAS_KERNING to find out whether a font has data */
+ /* that can be extracted with `FT_Get_Kerning'. */
+ /* */
FT_EXPORT( FT_Error )
FT_Get_Kerning( FT_Face face,
FT_UInt left_glyph,
@@ -3296,7 +3312,7 @@ FT_BEGIN_HEADER
/* @FT_Attach_Stream). */
/* */
/* Only very few AFM files come with track kerning data; please refer */
- /* to the Adobe's AFM specification for more details. */
+ /* to Adobe's AFM specification for more details. */
/* */
FT_EXPORT( FT_Error )
FT_Get_Track_Kerning( FT_Face face,
@@ -3358,7 +3374,7 @@ FT_BEGIN_HEADER
/* */
/* <Description> */
/* Retrieve the ASCII PostScript name of a given face, if available. */
- /* This only works with PostScript and TrueType fonts. */
+ /* This only works with PostScript, TrueType, and OpenType fonts. */
/* */
/* <Input> */
/* face :: A handle to the source face object. */
@@ -3429,7 +3445,8 @@ FT_BEGIN_HEADER
/* the face (i.e., if it is not listed in the `face->charmaps' */
/* table). */
/* */
- /* It also fails if a type~14 charmap is selected. */
+ /* It also fails if an OpenType type~14 charmap is selected (which */
+ /* doesn't map character codes to glyph indices at all). */
/* */
FT_EXPORT( FT_Error )
FT_Set_Charmap( FT_Face face,
@@ -3464,7 +3481,7 @@ FT_BEGIN_HEADER
/* */
/* <Description> */
/* Return the glyph index of a given character code. This function */
- /* uses a charmap object to do the mapping. */
+ /* uses the currently selected charmap to do the mapping. */
/* */
/* <Input> */
/* face :: A handle to the source face object. */
@@ -3498,9 +3515,8 @@ FT_BEGIN_HEADER
/* FT_Get_First_Char */
/* */
/* <Description> */
- /* This function is used to return the first character code in the */
- /* current charmap of a given face. It also returns the */
- /* corresponding glyph index. */
+ /* Return the first character code in the current charmap of a given */
+ /* face, together with its corresponding glyph index. */
/* */
/* <Input> */
/* face :: A handle to the source face object. */
@@ -3513,7 +3529,7 @@ FT_BEGIN_HEADER
/* The charmap's first character code. */
/* */
/* <Note> */
- /* You should use this function with @FT_Get_Next_Char to be able to */
+ /* You should use this function together with @FT_Get_Next_Char to */
/* parse all character codes available in a given charmap. The code */
/* should look like this: */
/* */
@@ -3553,12 +3569,13 @@ FT_BEGIN_HEADER
/* FT_Get_Next_Char */
/* */
/* <Description> */
- /* This function is used to return the next character code in the */
- /* current charmap of a given face following the value `char_code', */
- /* as well as the corresponding glyph index. */
+ /* Return the next character code in the current charmap of a given */
+ /* face following the value `char_code', as well as the corresponding */
+ /* glyph index. */
/* */
/* <Input> */
/* face :: A handle to the source face object. */
+ /* */
/* char_code :: The starting character code. */
/* */
/* <Output> */
@@ -3571,7 +3588,7 @@ FT_BEGIN_HEADER
/* <Note> */
/* You should use this function with @FT_Get_First_Char to walk */
/* over all character codes available in a given charmap. See the */
- /* note for this function for a simple code example. */
+ /* note for that function for a simple code example. */
/* */
/* Note that `*agindex' is set to~0 when there are no more codes in */
/* the charmap. */
@@ -3588,8 +3605,7 @@ FT_BEGIN_HEADER
/* FT_Get_Name_Index */
/* */
/* <Description> */
- /* Return the glyph index of a given glyph name. This function uses */
- /* driver specific objects to do the translation. */
+ /* Return the glyph index of a given glyph name. */
/* */
/* <Input> */
/* face :: A handle to the source face object. */
@@ -3610,8 +3626,10 @@ FT_BEGIN_HEADER
* FT_SUBGLYPH_FLAG_XXX
*
* @description:
- * A list of constants used to describe subglyphs. Please refer to the
- * TrueType specification for the meaning of the various flags.
+ * A list of constants describing subglyphs. Please refer to the
+ * `glyf' table description in the OpenType specification for the
+ * meaning of the various flags (which get synthesized for
+ * non-OpenType subglyphs).
*
* @values:
* FT_SUBGLYPH_FLAG_ARGS_ARE_WORDS ::
@@ -3672,7 +3690,7 @@ FT_BEGIN_HEADER
* @note:
* The values of `*p_arg1', `*p_arg2', and `*p_transform' must be
* interpreted depending on the flags returned in `*p_flags'. See the
- * TrueType specification for details.
+ * OpenType specification for details.
*
*/
FT_EXPORT( FT_Error )
@@ -3712,33 +3730,31 @@ FT_BEGIN_HEADER
/* the font software copyright owner. */
/* */
/* FT_FSTYPE_PREVIEW_AND_PRINT_EMBEDDING :: */
- /* If this bit is set, the font may be embedded and temporarily */
- /* loaded on the remote system. Documents containing Preview & */
- /* Print fonts must be opened `read-only'; no edits can be applied */
- /* to the document. */
+ /* The font may be embedded and temporarily loaded on the remote */
+ /* system. Documents containing Preview & Print fonts must be */
+ /* opened `read-only'; no edits can be applied to the document. */
/* */
/* FT_FSTYPE_EDITABLE_EMBEDDING :: */
- /* If this bit is set, the font may be embedded but must only be */
- /* installed temporarily on other systems. In contrast to Preview */
- /* & Print fonts, documents containing editable fonts may be opened */
- /* for reading, editing is permitted, and changes may be saved. */
+ /* The font may be embedded but must only be installed temporarily */
+ /* on other systems. In contrast to Preview & Print fonts, */
+ /* documents containing editable fonts may be opened for reading, */
+ /* editing is permitted, and changes may be saved. */
/* */
/* FT_FSTYPE_NO_SUBSETTING :: */
- /* If this bit is set, the font may not be subsetted prior to */
- /* embedding. */
+ /* The font may not be subsetted prior to embedding. */
/* */
/* FT_FSTYPE_BITMAP_EMBEDDING_ONLY :: */
- /* If this bit is set, only bitmaps contained in the font may be */
- /* embedded; no outline data may be embedded. If there are no */
- /* bitmaps available in the font, then the font is unembeddable. */
+ /* Only bitmaps contained in the font may be embedded; no outline */
+ /* data may be embedded. If there are no bitmaps available in the */
+ /* font, then the font is unembeddable. */
/* */
/* <Note> */
/* The flags are ORed together, thus more than a single value can be */
/* returned. */
/* */
- /* While the fsType flags can indicate that a font may be embedded, a */
- /* license with the font vendor may be separately required to use the */
- /* font in this way. */
+ /* While the `fsType' flags can indicate that a font may be embedded, */
+ /* a license with the font vendor may be separately required to use */
+ /* the font in this way. */
/* */
#define FT_FSTYPE_INSTALLABLE_EMBEDDING 0x0000
#define FT_FSTYPE_RESTRICTED_LICENSE_EMBEDDING 0x0002
@@ -3754,13 +3770,13 @@ FT_BEGIN_HEADER
/* FT_Get_FSType_Flags */
/* */
/* <Description> */
- /* Return the fsType flags for a font. */
+ /* Return the `fsType' flags for a font. */
/* */
/* <Input> */
/* face :: A handle to the source face object. */
/* */
/* <Return> */
- /* The fsType flags, @FT_FSTYPE_XXX. */
+ /* The `fsType' flags, see @FT_FSTYPE_XXX. */
/* */
/* <Note> */
/* Use this function rather than directly reading the `fs_type' field */
@@ -3800,8 +3816,9 @@ FT_BEGIN_HEADER
/* Database: */
/* */
/* http://www.unicode.org/reports/tr37/ */
+ /* http://www.unicode.org/ivd/ */
/* */
- /* To date (November 2014), the character with the most variants is */
+ /* To date (January 2017), the character with the most variants is */
/* U+9089, having 32 such IVS. */
/* */
/* Adobe and MS decided to support IVS with a new cmap subtable */
@@ -4030,16 +4047,17 @@ FT_BEGIN_HEADER
/* FT_MulDiv */
/* */
/* <Description> */
- /* A very simple function used to perform the computation `(a*b)/c' */
- /* with maximum accuracy (it uses a 64-bit intermediate integer */
- /* whenever necessary). */
+ /* Compute `(a*b)/c' with maximum accuracy, using a 64-bit */
+ /* intermediate integer whenever necessary. */
/* */
/* This function isn't necessarily as fast as some processor specific */
/* operations, but is at least completely portable. */
/* */
/* <Input> */
/* a :: The first multiplier. */
+ /* */
/* b :: The second multiplier. */
+ /* */
/* c :: The divisor. */
/* */
/* <Return> */
@@ -4059,12 +4077,12 @@ FT_BEGIN_HEADER
/* FT_MulFix */
/* */
/* <Description> */
- /* A very simple function used to perform the computation */
- /* `(a*b)/0x10000' with maximum accuracy. Most of the time this is */
- /* used to multiply a given value by a 16.16 fixed-point factor. */
+ /* Compute `(a*b)/0x10000' with maximum accuracy. Its main use is to */
+ /* multiply a given value by a 16.16 fixed-point factor. */
/* */
/* <Input> */
/* a :: The first multiplier. */
+ /* */
/* b :: The second multiplier. Use a 16.16 factor here whenever */
/* possible (see note below). */
/* */
@@ -4093,12 +4111,12 @@ FT_BEGIN_HEADER
/* FT_DivFix */
/* */
/* <Description> */
- /* A very simple function used to perform the computation */
- /* `(a*0x10000)/b' with maximum accuracy. Most of the time, this is */
- /* used to divide a given value by a 16.16 fixed-point factor. */
+ /* Compute `(a*0x10000)/b' with maximum accuracy. Its main use is to */
+ /* divide a given value by a 16.16 fixed-point factor. */
/* */
/* <Input> */
/* a :: The numerator. */
+ /* */
/* b :: The denominator. Use a 16.16 factor here. */
/* */
/* <Return> */
@@ -4115,13 +4133,13 @@ FT_BEGIN_HEADER
/* FT_RoundFix */
/* */
/* <Description> */
- /* A very simple function used to round a 16.16 fixed number. */
+ /* Round a 16.16 fixed number. */
/* */
/* <Input> */
/* a :: The number to be rounded. */
/* */
/* <Return> */
- /* `a' rounded to nearest 16.16 fixed integer, halfway cases away */
+ /* `a' rounded to the nearest 16.16 fixed integer, halfway cases away */
/* from zero. */
/* */
FT_EXPORT( FT_Fixed )
@@ -4134,8 +4152,7 @@ FT_BEGIN_HEADER
/* FT_CeilFix */
/* */
/* <Description> */
- /* A very simple function used to compute the ceiling function of a */
- /* 16.16 fixed number. */
+ /* Compute the smallest following integer of a 16.16 fixed number. */
/* */
/* <Input> */
/* a :: The number for which the ceiling function is to be computed. */
@@ -4153,8 +4170,7 @@ FT_BEGIN_HEADER
/* FT_FloorFix */
/* */
/* <Description> */
- /* A very simple function used to compute the floor function of a */
- /* 16.16 fixed number. */
+ /* Compute the largest previous integer of a 16.16 fixed number. */
/* */
/* <Input> */
/* a :: The number for which the floor function is to be computed. */
| [Prev in Thread] |
Current Thread |
[Next in Thread] |
- [freetype2] master 8665e3f 2/2: freetype.h: Revise documentation.,
Werner LEMBERG <=