ref: 8013d89f7fe7da123e3cd5708e501caf88405226
parent: ba6f3e18d06dc38cac7b1357bf65cab4a49ed7bd
author: Werner Lemberg <[email protected]>
date: Tue Jan 17 07:39:53 EST 2017
ftsnames.h, ttnameid.h, tttables.h: Revise documentation. Show more macros in the reference: TT_MAC_LANGID_XXX, TT_MS_LANGID_XXX, TT_NAME_ID_XXX, TT_UCR_XXX. This commit is viewed best with git diff --color-words='[^*/ ]+'
--- a/include/freetype/freetype.h
+++ b/include/freetype/freetype.h
@@ -734,7 +734,7 @@
/* Russian). */
/* */
/* FT_ENCODING_NONE is set if `platform_id' is @TT_PLATFORM_MACINTOSH */
- /* and `encoding_id' is not @TT_MAC_ID_ROMAN (otherwise it is set to */
+ /* and `encoding_id' is not `TT_MAC_ID_ROMAN' (otherwise it is set to */
/* FT_ENCODING_APPLE_ROMAN). */
/* */
/* If `platform_id' is @TT_PLATFORM_MACINTOSH, use the function */
@@ -746,9 +746,9 @@
/* to get an idea how to do that. Basically, if the language ID */
/* is~0, don't use it, otherwise subtract 1 from the language ID. */
/* Then examine `encoding_id'. If, for example, `encoding_id' is */
- /* @TT_MAC_ID_ROMAN and the language ID (minus~1) is */
+ /* `TT_MAC_ID_ROMAN' and the language ID (minus~1) is */
/* `TT_MAC_LANGID_GREEK', it is the Greek encoding, not Roman. */
- /* @TT_MAC_ID_ARABIC with `TT_MAC_LANGID_FARSI' means the Farsi */
+ /* `TT_MAC_ID_ARABIC' with `TT_MAC_LANGID_FARSI' means the Farsi */
/* variant the Arabic encoding. */
/* */
typedef enum FT_Encoding_
--- a/include/freetype/ftsnames.h
+++ b/include/freetype/ftsnames.h
@@ -2,7 +2,7 @@
/* */
/* ftsnames.h */
/* */
-/* Simple interface to access SFNT name tables (which are used */
+/* Simple interface to access SFNT `name' tables (which are used */
/* to hold font names, copyright info, notices, etc.) (specification). */
/* */
/* This is _not_ used to retrieve glyph names! */
@@ -49,7 +49,7 @@
/* */
/* <Description> */
/* The TrueType and OpenType specifications allow the inclusion of */
- /* a special `names table' in font files. This table contains */
+ /* a special names table (`name') in font files. This table contains */
/* textual (and internationalized) information regarding the font, */
/* like family name, copyright, version, etc. */
/* */
@@ -70,31 +70,30 @@
/* */
/* <Fields> */
/* platform_id :: The platform ID for `string'. */
+ /* See @TT_PLATFORM_XXX for possible values. */
/* */
/* encoding_id :: The encoding ID for `string'. */
+ /* See @TT_APPLE_ID_XXX, @TT_MAC_ID_XXX, */
+ /* @TT_ISO_ID_XXX, @TT_MS_ID_XXX, and @TT_ADOBE_ID_XXX */
+ /* for possible values. */
/* */
/* language_id :: The language ID for `string'. */
+ /* See @TT_MAC_LANGID_XXX and @TT_MS_LANGID_XXX for */
+ /* possible values. */
/* */
/* name_id :: An identifier for `string'. */
+ /* See @TT_NAME_ID_XXX for possible values. */
/* */
/* string :: The `name' string. Note that its format differs */
/* depending on the (platform,encoding) pair. It can */
/* be a Pascal String, a UTF-16 one, etc. */
/* */
- /* Generally speaking, the string is not */
- /* zero-terminated. Please refer to the TrueType */
- /* specification for details. */
- /* */
/* string_len :: The length of `string' in bytes. */
/* */
/* <Note> */
- /* Possible values for `platform_id', `encoding_id', `language_id', */
- /* and `name_id' are given in the file `ttnameid.h'. For details */
- /* please refer to the TrueType or OpenType specification. */
+ /* Please refer to the TrueType or OpenType specification for more */
+ /* details. */
/* */
- /* See also @TT_PLATFORM_XXX, @TT_APPLE_ID_XXX, @TT_MAC_ID_XXX, */
- /* @TT_ISO_ID_XXX, and @TT_MS_ID_XXX. */
- /* */
typedef struct FT_SfntName_
{FT_UShort platform_id;
@@ -103,7 +102,7 @@
FT_UShort name_id;
FT_Byte* string; /* this string is *not* null-terminated! */
- FT_UInt string_len; /* in bytes */
+ FT_UInt string_len; /* in bytes */
} FT_SfntName;
--- a/include/freetype/ttnameid.h
+++ b/include/freetype/ttnameid.h
@@ -36,7 +36,7 @@
/*************************************************************************/
/* */
/* Possible values for the `platform' identifier code in the name */
- /* records of the TTF `name' table. */
+ /* records of an SFNT `name' table. */
/* */
/*************************************************************************/
@@ -142,42 +142,6 @@
* @description:
* A list of valid values for the `encoding_id' for
* @TT_PLATFORM_MACINTOSH charmaps and name entries.
- *
- * @values:
- * TT_MAC_ID_ROMAN ::
- * TT_MAC_ID_JAPANESE ::
- * TT_MAC_ID_TRADITIONAL_CHINESE ::
- * TT_MAC_ID_KOREAN ::
- * TT_MAC_ID_ARABIC ::
- * TT_MAC_ID_HEBREW ::
- * TT_MAC_ID_GREEK ::
- * TT_MAC_ID_RUSSIAN ::
- * TT_MAC_ID_RSYMBOL ::
- * TT_MAC_ID_DEVANAGARI ::
- * TT_MAC_ID_GURMUKHI ::
- * TT_MAC_ID_GUJARATI ::
- * TT_MAC_ID_ORIYA ::
- * TT_MAC_ID_BENGALI ::
- * TT_MAC_ID_TAMIL ::
- * TT_MAC_ID_TELUGU ::
- * TT_MAC_ID_KANNADA ::
- * TT_MAC_ID_MALAYALAM ::
- * TT_MAC_ID_SINHALESE ::
- * TT_MAC_ID_BURMESE ::
- * TT_MAC_ID_KHMER ::
- * TT_MAC_ID_THAI ::
- * TT_MAC_ID_LAOTIAN ::
- * TT_MAC_ID_GEORGIAN ::
- * TT_MAC_ID_ARMENIAN ::
- * TT_MAC_ID_MALDIVIAN ::
- * TT_MAC_ID_SIMPLIFIED_CHINESE ::
- * TT_MAC_ID_TIBETAN ::
- * TT_MAC_ID_MONGOLIAN ::
- * TT_MAC_ID_GEEZ ::
- * TT_MAC_ID_SLAVIC ::
- * TT_MAC_ID_VIETNAMESE ::
- * TT_MAC_ID_SINDHI ::
- * TT_MAC_ID_UNINTERP ::
*/
#define TT_MAC_ID_ROMAN 0
@@ -252,33 +216,32 @@
*
* @values:
* TT_MS_ID_SYMBOL_CS ::
- * Corresponds to Microsoft symbol encoding. See
- * @FT_ENCODING_MS_SYMBOL.
+ * Microsoft symbol encoding. See @FT_ENCODING_MS_SYMBOL.
*
* TT_MS_ID_UNICODE_CS ::
- * Corresponds to a Microsoft WGL4 charmap, matching Unicode. See
+ * Microsoft WGL4 charmap, matching Unicode. See
* @FT_ENCODING_UNICODE.
*
* TT_MS_ID_SJIS ::
- * Corresponds to SJIS Japanese encoding. See @FT_ENCODING_SJIS.
+ * Shift JIS Japanese encoding. See @FT_ENCODING_SJIS.
*
* TT_MS_ID_GB2312 ::
- * Corresponds to Simplified Chinese as used in Mainland China. See
+ * Simplified Chinese as used in Mainland China. See
* @FT_ENCODING_GB2312.
*
* TT_MS_ID_BIG_5 ::
- * Corresponds to Traditional Chinese as used in Taiwan and Hong Kong.
- * See @FT_ENCODING_BIG5.
+ * Traditional Chinese as used in Taiwan and Hong Kong. See
+ * @FT_ENCODING_BIG5.
*
* TT_MS_ID_WANSUNG ::
- * Corresponds to Korean Wansung encoding. See @FT_ENCODING_WANSUNG.
+ * Korean Extended Wansung encoding. See @FT_ENCODING_WANSUNG.
*
* TT_MS_ID_JOHAB ::
- * Corresponds to Johab encoding. See @FT_ENCODING_JOHAB.
+ * Korean Johab encoding. See @FT_ENCODING_JOHAB.
*
* TT_MS_ID_UCS_4 ::
- * Corresponds to UCS-4 or UTF-32 charmaps. This has been added to
- * the OpenType specification version 1.4 (mid-2001.)
+ * UCS-4 or UTF-32 charmaps. This has been added to the OpenType
+ * specification version 1.4 (mid-2001).
*/
#define TT_MS_ID_SYMBOL_CS 0
@@ -317,17 +280,22 @@
#define TT_ADOBE_ID_LATIN_1 3
- /*************************************************************************/
- /* */
- /* Possible values of the language identifier field in the name records */
- /* of the TTF `name' table if the `platform' identifier code is */
- /* TT_PLATFORM_MACINTOSH. These values are also used as return values */
- /* for function @FT_Get_CMap_Language_ID. */
- /* */
- /* The canonical source for the Apple assigned Language ID's is at */
- /* */
- /* https://developer.apple.com/fonts/TrueType-Reference-Manual/RM06/Chap6name.html */
- /* */
+ /***********************************************************************
+ *
+ * @enum:
+ * TT_MAC_LANGID_XXX
+ *
+ * @description:
+ * Possible values of the language identifier field in the name records
+ * of the SFNT `name' table if the `platform' identifier code is
+ * @TT_PLATFORM_MACINTOSH. These values are also used as return values
+ * for function @FT_Get_CMap_Language_ID.
+ *
+ * The canonical source for Apple's IDs is
+ *
+ * https://developer.apple.com/fonts/TrueType-Reference-Manual/RM06/Chap6name.html
+ */
+
#define TT_MAC_LANGID_ENGLISH 0
#define TT_MAC_LANGID_FRENCH 1
#define TT_MAC_LANGID_GERMAN 2
@@ -438,15 +406,6 @@
#define TT_MAC_LANGID_JAVANESE 138
#define TT_MAC_LANGID_SUNDANESE 139
-
-#if 0 /* these seem to be errors that have been dropped */
-
-#define TT_MAC_LANGID_SCOTTISH_GAELIC 140
-#define TT_MAC_LANGID_IRISH_GAELIC 141
-
-#endif
-
-
/* The following codes are new as of 2000-03-10 */
#define TT_MAC_LANGID_GALICIAN 140
#define TT_MAC_LANGID_AFRIKAANS 141
@@ -461,16 +420,29 @@
#define TT_MAC_LANGID_AZERBAIJANI_ROMAN_SCRIPT 150
- /*************************************************************************/
- /* */
- /* Possible values of the language identifier field in the name records */
- /* of the TTF `name' table if the `platform' identifier code is */
- /* TT_PLATFORM_MICROSOFT. */
- /* */
- /* The canonical source for the MS assigned LCIDs is */
- /* */
- /* http://www.microsoft.com/globaldev/reference/lcid-all.mspx */
- /* */
+ /***********************************************************************
+ *
+ * @enum:
+ * TT_MS_LANGID_XXX
+ *
+ * @description:
+ * Possible values of the language identifier field in the name records
+ * of the SFNT `name' table if the `platform' identifier code is
+ * @TT_PLATFORM_MICROSOFT. These values are also used as return values
+ * for function @FT_Get_CMap_Language_ID.
+ *
+ * The canonical source for Microsoft's IDs is
+ *
+ * http://www.microsoft.com/globaldev/reference/lcid-all.mspx ,
+ *
+ * however, we only provide macros for language identifiers present in
+ * the OpenType specification: Microsoft has abandoned the concept of
+ * LCIDs (language code identifiers), and format~1 of the `name' table
+ * provides a better mechanism for languages not covered here.
+ *
+ * More legacy values not listed in the reference can be found in the
+ * @FT_TRUETYPE_IDS_H header file.
+ */
#define TT_MS_LANGID_ARABIC_SAUDI_ARABIA 0x0401
#define TT_MS_LANGID_ARABIC_IRAQ 0x0801
@@ -804,11 +776,16 @@
TT_MS_LANGID_UIGHUR_PRC
- /*************************************************************************/
- /* */
- /* Possible values of the `name' identifier field in the name records of */
- /* the TTF `name' table. These values are platform independent. */
- /* */
+ /***********************************************************************
+ *
+ * @enum:
+ * TT_NAME_ID_XXX
+ *
+ * @description:
+ * Possible values of the `name' identifier field in the name records of
+ * an SFNT `name' table. These values are platform independent.
+ */
+
#define TT_NAME_ID_COPYRIGHT 0
#define TT_NAME_ID_FONT_FAMILY 1
#define TT_NAME_ID_FONT_SUBFAMILY 2
@@ -848,14 +825,22 @@
/* This is new in OpenType 1.8 */
#define TT_NAME_ID_VARIATIONS_PREFIX 25
+ /* */
- /*************************************************************************/
- /* */
- /* Bit mask values for the Unicode Ranges from the TTF `OS2 ' table. */
- /* */
- /* Updated 08-Nov-2008. */
- /* */
+ /***********************************************************************
+ *
+ * @enum:
+ * TT_UCR_XXX
+ *
+ * @description:
+ * Possible bit mask values for the `ulUnicodeRangeX' fields in an SFNT
+ * `OS/2' table.
+ */
+
+ /* ulUnicodeRange1 */
+ /* --------------- */
+
/* Bit 0 Basic Latin */
#define TT_UCR_BASIC_LATIN (1L << 0) /* U+0020-U+007E */
/* Bit 1 C1 Controls and Latin-1 Supplement */
@@ -944,6 +929,10 @@
/* Supplemental Punctuation */
#define TT_UCR_GENERAL_PUNCTUATION (1L << 31) /* U+2000-U+206F */
/* U+2E00-U+2E7F */
+
+ /* ulUnicodeRange2 */
+ /* --------------- */
+
/* Bit 32 Superscripts And Subscripts */
#define TT_UCR_SUPERSCRIPTS_SUBSCRIPTS (1L << 0) /* U+2070-U+209F */
/* Bit 33 Currency Symbols */
@@ -1016,13 +1005,13 @@
/* Bit 57 High Surrogates */
/* High Private Use Surrogates */
/* Low Surrogates */
- /* */
+
/* According to OpenType specs v.1.3+, */
/* setting bit 57 implies that there is */
/* at least one codepoint beyond the */
/* Basic Multilingual Plane that is */
/* supported by this font. So it really */
- /* means >= U+10000 */
+ /* means >= U+10000. */
#define TT_UCR_SURROGATES (1L << 25) /* U+D800-U+DB7F */
/* U+DB80-U+DBFF */
/* U+DC00-U+DFFF */
@@ -1055,6 +1044,10 @@
#define TT_UCR_ALPHABETIC_PRESENTATION_FORMS (1L << 30) /* U+FB00-U+FB4F */
/* Bit 63 Arabic Presentation Forms-A */
#define TT_UCR_ARABIC_PRESENTATION_FORMS_A (1L << 31) /* U+FB50-U+FDFF */
+
+ /* ulUnicodeRange3 */
+ /* --------------- */
+
/* Bit 64 Combining Half Marks */
#define TT_UCR_COMBINING_HALF_MARKS (1L << 0) /* U+FE20-U+FE2F */
/* Bit 65 Vertical forms */
@@ -1143,6 +1136,10 @@
#define TT_UCR_TAI_LE (1L << 30) /* U+1950-U+197F */
/* Bit 95 New Tai Lue */
#define TT_UCR_NEW_TAI_LUE (1L << 31) /* U+1980-U+19DF */
+
+ /* ulUnicodeRange4 */
+ /* --------------- */
+
/* Bit 96 Buginese */
#define TT_UCR_BUGINESE (1L << 0) /* U+1A00-U+1A1F */
/* Bit 97 Glagolitic */
@@ -1211,6 +1208,7 @@
/*U+1F000-U+1F02F*/
/* Bit 123-127 Reserved for process-internal usage */
+ /* */
/* for backwards compatibility with older FreeType versions */
#define TT_UCR_ARABIC_PRESENTATION_A \
--- a/include/freetype/tttables.h
+++ b/include/freetype/tttables.h
@@ -45,8 +45,9 @@
/* TrueType specific table types and functions. */
/* */
/* <Description> */
- /* This section contains the definition of TrueType-specific tables */
- /* as well as some routines used to access and process them. */
+ /* This section contains definitions of some basic tables specific to */
+ /* TrueType and OpenType as well as some routines used to access and */
+ /* process them. */
/* */
/* <Order> */
/* TT_Header */
@@ -76,8 +77,8 @@
/* TT_Header */
/* */
/* <Description> */
- /* A structure used to model a TrueType font header table. All */
- /* fields follow the TrueType specification. */
+ /* A structure to model a TrueType font header table. All fields */
+ /* follow the OpenType specification. */
/* */
typedef struct TT_Header_
{@@ -114,9 +115,9 @@
/* TT_HoriHeader */
/* */
/* <Description> */
- /* A structure used to model a TrueType horizontal header, the `hhea' */
+ /* A structure to model a TrueType horizontal header, the `hhea' */
/* table, as well as the corresponding horizontal metrics table, */
- /* i.e., the `hmtx' table. */
+ /* `hmtx'. */
/* */
/* <Fields> */
/* Version :: The table version. */
@@ -131,7 +132,7 @@
/* glyphs found in the font (maybe ASCII). */
/* */
/* You should use the `sTypoAscender' field */
- /* of the OS/2 table instead if you want */
+ /* of the `OS/2' table instead if you want */
/* the correct one. */
/* */
/* Descender :: The font's descender, i.e., the distance */
@@ -145,7 +146,7 @@
/* glyphs found in the font (maybe ASCII). */
/* */
/* You should use the `sTypoDescender' */
- /* field of the OS/2 table instead if you */
+ /* field of the `OS/2' table instead if you */
/* want the correct one. */
/* */
/* Line_Gap :: The font's line gap, i.e., the distance */
@@ -195,14 +196,6 @@
/* friends) if the font contains an `MVAR' table: `caret_Slope_Rise', */
/* `caret_Slope_Run', and `caret_Offset'. */
/* */
- /* IMPORTANT: The TT_HoriHeader and TT_VertHeader structures should */
- /* be identical except for the names of their fields, */
- /* which are different. */
- /* */
- /* This ensures that a single function in the `ttload' */
- /* module is able to read both the horizontal and vertical */
- /* headers. */
- /* */
typedef struct TT_HoriHeader_
{FT_Fixed Version;
@@ -224,7 +217,7 @@
FT_Short metric_Data_Format;
FT_UShort number_Of_HMetrics;
- /* The following fields are not defined by the TrueType specification */
+ /* The following fields are not defined by the OpenType specification */
/* but they are used to connect the metrics header to the relevant */
/* `hmtx' table. */
@@ -241,8 +234,8 @@
/* */
/* <Description> */
/* A structure used to model a TrueType vertical header, the `vhea' */
- /* table, as well as the corresponding vertical metrics table, i.e., */
- /* the `vmtx' table. */
+ /* table, as well as the corresponding vertical metrics table, */
+ /* `vmtx'. */
/* */
/* <Fields> */
/* Version :: The table version. */
@@ -258,8 +251,8 @@
/* ASCII). */
/* */
/* You should use the `sTypoAscender' */
- /* field of the OS/2 table instead if you */
- /* want the correct one. */
+ /* field of the `OS/2' table instead if */
+ /* you want the correct one. */
/* */
/* Descender :: The font's descender, i.e., the */
/* distance from the baseline to the */
@@ -273,8 +266,8 @@
/* ASCII). */
/* */
/* You should use the `sTypoDescender' */
- /* field of the OS/2 table instead if you */
- /* want the correct one. */
+ /* field of the `OS/2' table instead if */
+ /* you want the correct one. */
/* */
/* Line_Gap :: The font's line gap, i.e., the distance */
/* to add to the ascender and descender to */
@@ -309,7 +302,7 @@
/* */
/* metric_Data_Format :: Always~0. */
/* */
- /* number_Of_HMetrics :: Number of VMetrics entries in the */
+ /* number_Of_VMetrics :: Number of VMetrics entries in the */
/* `vmtx' table -- this value can be */
/* smaller than the total number of glyphs */
/* in the font. */
@@ -325,14 +318,6 @@
/* `Descender', `Line_Gap', `caret_Slope_Rise', `caret_Slope_Run', */
/* and `caret_Offset'. */
/* */
- /* IMPORTANT: The TT_HoriHeader and TT_VertHeader structures should */
- /* be identical except for the names of their fields, */
- /* which are different. */
- /* */
- /* This ensures that a single function in the `ttload' */
- /* module is able to read both the horizontal and vertical */
- /* headers. */
- /* */
typedef struct TT_VertHeader_
{FT_Fixed Version;
@@ -342,9 +327,9 @@
FT_UShort advance_Height_Max; /* advance height maximum */
- FT_Short min_Top_Side_Bearing; /* minimum left-sb or top-sb */
- FT_Short min_Bottom_Side_Bearing; /* minimum right-sb or bottom-sb */
- FT_Short yMax_Extent; /* xmax or ymax extents */
+ FT_Short min_Top_Side_Bearing; /* minimum top-sb */
+ FT_Short min_Bottom_Side_Bearing; /* minimum bottom-sb */
+ FT_Short yMax_Extent; /* ymax extents */
FT_Short caret_Slope_Rise;
FT_Short caret_Slope_Run;
FT_Short caret_Offset;
@@ -354,9 +339,9 @@
FT_Short metric_Data_Format;
FT_UShort number_Of_VMetrics;
- /* The following fields are not defined by the TrueType specification */
+ /* The following fields are not defined by the OpenType specification */
/* but they are used to connect the metrics header to the relevant */
- /* `hmtx' or `vmtx' table. */
+ /* `vmtx' table. */
void* long_metrics;
void* short_metrics;
@@ -370,12 +355,14 @@
/* TT_OS2 */
/* */
/* <Description> */
- /* A structure used to model a TrueType `OS/2' table. All fields */
- /* comply to the OpenType specification. */
+ /* A structure to model a TrueType `OS/2' table. All fields comply */
+ /* to the OpenType specification. */
/* */
- /* Note that we now support old Mac fonts that do not include an OS/2 */
- /* table. In this case, the `version' field is always set to 0xFFFF. */
+ /* Note that we now support old Mac fonts that do not include an */
+ /* `OS/2' table. In this case, the `version' field is always set to */
+ /* 0xFFFF. */
/* */
+ /* <Note> */
/* 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: `sCapHeight', */
@@ -385,6 +372,10 @@
/* `ySubscriptYOffset', `ySubscriptYSize', `ySuperscriptXOffset', */
/* `ySuperscriptXSize', `ySuperscriptYOffset', and */
/* `ySuperscriptYSize'. */
+ /* */
+ /* Possible values for bits in the `ulUnicodeRangeX' fields are given */
+ /* by the @TT_UCR_XXX macros. */
+ /* */
typedef struct TT_OS2_
{@@ -450,10 +441,10 @@
/* TT_Postscript */
/* */
/* <Description> */
- /* A structure used to model a TrueType `post' table. All fields */
- /* comply to the TrueType specification. This structure does not */
- /* reference the PostScript glyph names, which can be nevertheless */
- /* accessed with the `ttpost' module. */
+ /* A structure to model a TrueType `post' table. All fields comply */
+ /* to the OpenType specification. This structure does not reference */
+ /* a font's PostScript glyph names; use @FT_Get_Glyph_Name to */
+ /* retrieve them. */
/* */
/* <Note> */
/* For an OpenType variation font, the values of the following fields */
@@ -473,8 +464,8 @@
FT_ULong minMemType1;
FT_ULong maxMemType1;
- /* Glyph names follow in the file, but we don't */
- /* load them by default. See file `ttpost.c'. */
+ /* Glyph names follow in the `post' table, but we don't */
+ /* load them by default. */
} TT_Postscript;
@@ -485,8 +476,8 @@
/* TT_PCLT */
/* */
/* <Description> */
- /* A structure used to model a TrueType `PCLT' table. All fields */
- /* comply to the TrueType specification. */
+ /* A structure to model a TrueType `PCLT' table. All fields comply */
+ /* to the OpenType specification. */
/* */
typedef struct TT_PCLT_
{@@ -516,8 +507,8 @@
/* */
/* <Description> */
/* The maximum profile (`maxp') table contains many max values, which */
- /* can be used to pre-allocate arrays. This ensures that no memory */
- /* allocation occurs during a glyph load. */
+ /* can be used to pre-allocate arrays for speeding up glyph loading */
+ /* and hinting. */
/* */
/* <Fields> */
/* version :: The version number. */
@@ -527,21 +518,19 @@
/* */
/* maxPoints :: The maximum number of points in a */
/* non-composite TrueType glyph. See also */
- /* the structure element */
/* `maxCompositePoints'. */
/* */
/* maxContours :: The maximum number of contours in a */
/* non-composite TrueType glyph. See also */
- /* the structure element */
/* `maxCompositeContours'. */
/* */
/* maxCompositePoints :: The maximum number of points in a */
- /* composite TrueType glyph. See also the */
- /* structure element `maxPoints'. */
+ /* composite TrueType glyph. See also */
+ /* `maxPoints'. */
/* */
/* maxCompositeContours :: The maximum number of contours in a */
- /* composite TrueType glyph. See also the */
- /* structure element `maxContours'. */
+ /* composite TrueType glyph. See also */
+ /* `maxContours'. */
/* */
/* maxZones :: The maximum number of zones used for */
/* glyph hinting. */
@@ -602,8 +591,9 @@
/* FT_Sfnt_Tag */
/* */
/* <Description> */
- /* An enumeration used to specify the index of an SFNT table. */
- /* Used in the @FT_Get_Sfnt_Table API function. */
+ /* An enumeration to specify indices of SFNT tables loaded and parsed */
+ /* by FreeType during initialization of an SFNT font. Used in the */
+ /* @FT_Get_Sfnt_Table API function. */
/* */
/* <Values> */
/* FT_SFNT_HEAD :: To access the font's @TT_Header structure. */
@@ -651,7 +641,7 @@
/* FT_Get_Sfnt_Table */
/* */
/* <Description> */
- /* Return a pointer to a given SFNT table within a face. */
+ /* Return a pointer to a given SFNT table stored within a face. */
/* */
/* <Input> */
/* face :: A handle to the source. */
@@ -659,7 +649,7 @@
/* tag :: The index of the SFNT table. */
/* */
/* <Return> */
- /* A type-less pointer to the table. This will be~0 in case of */
+ /* A type-less pointer to the table. This will be NULL in case of */
/* error, or if the corresponding table was not found *OR* loaded */
/* from the file. */
/* */
@@ -688,70 +678,70 @@
FT_Sfnt_Tag tag );
- /**************************************************************************
- *
- * @function:
- * FT_Load_Sfnt_Table
- *
- * @description:
- * Load any font table into client memory.
- *
- * @input:
- * face ::
- * A handle to the source face.
- *
- * tag ::
- * The four-byte tag of the table to load. Use the value~0 if you want
- * to access the whole font file. Otherwise, you can use one of the
- * definitions found in the @FT_TRUETYPE_TAGS_H file, or forge a new
- * one with @FT_MAKE_TAG.
- *
- * offset ::
- * The starting offset in the table (or file if tag == 0).
- *
- * @output:
- * buffer ::
- * The target buffer address. The client must ensure that the memory
- * array is big enough to hold the data.
- *
- * @inout:
- * length ::
- * If the `length' parameter is NULL, then try to load the whole table.
- * Return an error code if it fails.
- *
- * Else, if `*length' is~0, exit immediately while returning the
- * table's (or file) full size in it.
- *
- * Else the number of bytes to read from the table or file, from the
- * starting offset.
- *
- * @return:
- * FreeType error code. 0~means success.
- *
- * @note:
- * If you need to determine the table's length you should first call this
- * function with `*length' set to~0, as in the following example:
- *
- * {- * FT_ULong length = 0;
- *
- *
- * error = FT_Load_Sfnt_Table( face, tag, 0, NULL, &length );
- * if ( error ) { ... table does not exist ... }- *
- * buffer = malloc( length );
- * if ( buffer == NULL ) { ... not enough memory ... }- *
- * error = FT_Load_Sfnt_Table( face, tag, 0, buffer, &length );
- * if ( error ) { ... could not load table ... }- * }
- *
- * Note that structures like @TT_Header or @TT_OS2 can't be used with
- * this function; they are limited to @FT_Get_Sfnt_Table. Reason is that
- * those structures depend on the processor architecture, with varying
- * size (e.g. 32bit vs. 64bit) or order (big endian vs. little endian).
- *
- */
+ /**************************************************************************
+ *
+ * @function:
+ * FT_Load_Sfnt_Table
+ *
+ * @description:
+ * Load any SFNT font table into client memory.
+ *
+ * @input:
+ * face ::
+ * A handle to the source face.
+ *
+ * tag ::
+ * The four-byte tag of the table to load. Use value~0 if you want
+ * to access the whole font file. Otherwise, you can use one of the
+ * definitions found in the @FT_TRUETYPE_TAGS_H file, or forge a new
+ * one with @FT_MAKE_TAG.
+ *
+ * offset ::
+ * The starting offset in the table (or file if tag~==~0).
+ *
+ * @output:
+ * buffer ::
+ * The target buffer address. The client must ensure that the memory
+ * array is big enough to hold the data.
+ *
+ * @inout:
+ * length ::
+ * If the `length' parameter is NULL, try to load the whole table.
+ * Return an error code if it fails.
+ *
+ * Else, if `*length' is~0, exit immediately while returning the
+ * table's (or file) full size in it.
+ *
+ * Else the number of bytes to read from the table or file, from the
+ * starting offset.
+ *
+ * @return:
+ * FreeType error code. 0~means success.
+ *
+ * @note:
+ * If you need to determine the table's length you should first call this
+ * function with `*length' set to~0, as in the following example:
+ *
+ * {+ * FT_ULong length = 0;
+ *
+ *
+ * error = FT_Load_Sfnt_Table( face, tag, 0, NULL, &length );
+ * if ( error ) { ... table does not exist ... }+ *
+ * buffer = malloc( length );
+ * if ( buffer == NULL ) { ... not enough memory ... }+ *
+ * error = FT_Load_Sfnt_Table( face, tag, 0, buffer, &length );
+ * if ( error ) { ... could not load table ... }+ * }
+ *
+ * Note that structures like @TT_Header or @TT_OS2 can't be used with
+ * this function; they are limited to @FT_Get_Sfnt_Table. Reason is that
+ * those structures depend on the processor architecture, with varying
+ * size (e.g. 32bit vs. 64bit) or order (big endian vs. little endian).
+ *
+ */
FT_EXPORT( FT_Error )
FT_Load_Sfnt_Table( FT_Face face,
FT_ULong tag,
@@ -760,41 +750,41 @@
FT_ULong* length );
- /**************************************************************************
- *
- * @function:
- * FT_Sfnt_Table_Info
- *
- * @description:
- * Return information on an SFNT table.
- *
- * @input:
- * face ::
- * A handle to the source face.
- *
- * table_index ::
- * The index of an SFNT table. The function returns
- * FT_Err_Table_Missing for an invalid value.
- *
- * @inout:
- * tag ::
- * The name tag of the SFNT table. If the value is NULL, `table_index'
- * is ignored, and `length' returns the number of SFNT tables in the
- * font.
- *
- * @output:
- * length ::
- * The length of the SFNT table (or the number of SFNT tables, depending
- * on `tag').
- *
- * @return:
- * FreeType error code. 0~means success.
- *
- * @note:
- * While parsing fonts, FreeType handles SFNT tables with length zero as
- * missing.
- *
- */
+ /**************************************************************************
+ *
+ * @function:
+ * FT_Sfnt_Table_Info
+ *
+ * @description:
+ * Return information on an SFNT table.
+ *
+ * @input:
+ * face ::
+ * A handle to the source face.
+ *
+ * table_index ::
+ * The index of an SFNT table. The function returns
+ * FT_Err_Table_Missing for an invalid value.
+ *
+ * @inout:
+ * tag ::
+ * The name tag of the SFNT table. If the value is NULL, `table_index'
+ * is ignored, and `length' returns the number of SFNT tables in the
+ * font.
+ *
+ * @output:
+ * length ::
+ * The length of the SFNT table (or the number of SFNT tables, depending
+ * on `tag').
+ *
+ * @return:
+ * FreeType error code. 0~means success.
+ *
+ * @note:
+ * While parsing fonts, FreeType handles SFNT tables with length zero as
+ * missing.
+ *
+ */
FT_EXPORT( FT_Error )
FT_Sfnt_Table_Info( FT_Face face,
FT_UInt table_index,
@@ -808,8 +798,8 @@
/* FT_Get_CMap_Language_ID */
/* */
/* <Description> */
- /* Return TrueType/sfnt specific cmap language ID. Definitions of */
- /* language ID values are in `ttnameid.h'. */
+ /* Return cmap language ID as specified in the OpenType standard. */
+ /* Definitions of language ID values are in file @FT_TRUETYPE_IDS_H. */
/* */
/* <Input> */
/* charmap :: */
@@ -816,8 +806,8 @@
/* The target charmap. */
/* */
/* <Return> */
- /* The language ID of `charmap'. If `charmap' doesn't belong to a */
- /* TrueType/sfnt face, just return~0 as the default value. */
+ /* The language ID of `charmap'. If `charmap' doesn't belong to an */
+ /* SFNT face, just return~0 as the default value. */
/* */
/* For a format~14 cmap (to access Unicode IVS), the return value is */
/* 0xFFFFFFFF. */
@@ -832,7 +822,7 @@
/* FT_Get_CMap_Format */
/* */
/* <Description> */
- /* Return TrueType/sfnt specific cmap format. */
+ /* Return the format of an SFNT `cmap' table. */
/* */
/* <Input> */
/* charmap :: */
@@ -839,8 +829,8 @@
/* The target charmap. */
/* */
/* <Return> */
- /* The format of `charmap'. If `charmap' doesn't belong to a */
- /* TrueType/sfnt face, return -1. */
+ /* The format of `charmap'. If `charmap' doesn't belong to an SFNT */
+ /* face, return -1. */
/* */
FT_EXPORT( FT_Long )
FT_Get_CMap_Format( FT_CharMap charmap );
--- a/src/sfnt/ttmtx.c
+++ b/src/sfnt/ttmtx.c
@@ -30,6 +30,14 @@
#include "sferrors.h"
+ /* IMPORTANT: The TT_HoriHeader and TT_VertHeader structures should */
+ /* be identical except for the names of their fields, */
+ /* which are different. */
+ /* */
+ /* This ensures that `tt_face_load_hmtx' is able to read */
+ /* both the horizontal and vertical headers. */
+
+
/*************************************************************************/
/* */
/* The macro FT_COMPONENT is used in trace mode. It is an implicit */