FreeType-2.1.10 API Reference
TrueType Tables
Synopsis
#TT_Header
TT_Header
#FT_Sfnt_Tag
FT_Sfnt_Tag
#TT_HoriHeader
TT_HoriHeader
#FT_Get_Sfnt_Table
FT_Get_Sfnt_Table
#TT_VertHeader
TT_VertHeader
#FT_Load_Sfnt_Table
FT_Load_Sfnt_Table
#TT_OS2
TT_OS2
#FT_Sfnt_Table_Info
FT_Sfnt_Table_Info
#TT_Postscript
TT_Postscript
#FT_Get_CMap_Language_ID
FT_Get_CMap_Language_ID
#TT_PCLT
TT_PCLT
#FT_PARAM_TAG_UNPATENTED_HINTING
FT_PARAM_TAG_UNPATENTED_HINTING
#TT_MaxProfile
TT_MaxProfile
This section contains the definition of TrueType-specific tables as well as some routines used to access and process them.
TT_Header
typedef
struct
TT_Header_
{
ft2-basic_types.html#FT_Fixed
FT_Fixed
Table_Version;
ft2-basic_types.html#FT_Fixed
FT_Fixed
Font_Revision;
ft2-basic_types.html#FT_Long
FT_Long
CheckSum_Adjust;
ft2-basic_types.html#FT_Long
FT_Long
Magic_Number;
ft2-basic_types.html#FT_UShort
FT_UShort
Flags;
ft2-basic_types.html#FT_UShort
FT_UShort
Units_Per_EM;
ft2-basic_types.html#FT_Long
FT_Long
Created [2];
ft2-basic_types.html#FT_Long
FT_Long
Modified[2];
ft2-basic_types.html#FT_Short
FT_Short
xMin;
ft2-basic_types.html#FT_Short
FT_Short
yMin;
ft2-basic_types.html#FT_Short
FT_Short
xMax;
ft2-basic_types.html#FT_Short
FT_Short
yMax;
ft2-basic_types.html#FT_UShort
FT_UShort
Mac_Style;
ft2-basic_types.html#FT_UShort
FT_UShort
Lowest_Rec_PPEM;
ft2-basic_types.html#FT_Short
FT_Short
Font_Direction;
ft2-basic_types.html#FT_Short
FT_Short
Index_To_Loc_Format;
ft2-basic_types.html#FT_Short
FT_Short
Glyph_Data_Format;
}
TT_Header
;
A structure used to model a TrueType font header table. All fields follow the TrueType specification.
TT_HoriHeader
typedef
struct
TT_HoriHeader_
{
ft2-basic_types.html#FT_Fixed
FT_Fixed
Version;
ft2-basic_types.html#FT_Short
FT_Short
Ascender;
ft2-basic_types.html#FT_Short
FT_Short
Descender;
ft2-basic_types.html#FT_Short
FT_Short
Line_Gap;
ft2-basic_types.html#FT_UShort
FT_UShort
advance_Width_Max;      /* advance width maximum */
ft2-basic_types.html#FT_Short
FT_Short
min_Left_Side_Bearing;  /* minimum left-sb       */
ft2-basic_types.html#FT_Short
FT_Short
min_Right_Side_Bearing; /* minimum right-sb      */
ft2-basic_types.html#FT_Short
FT_Short
xMax_Extent;            /* xmax extents          */
ft2-basic_types.html#FT_Short
FT_Short
caret_Slope_Rise;
ft2-basic_types.html#FT_Short
FT_Short
caret_Slope_Run;
ft2-basic_types.html#FT_Short
FT_Short
caret_Offset;
ft2-basic_types.html#FT_Short
FT_Short
Reserved[4];
ft2-basic_types.html#FT_Short
FT_Short
metric_Data_Format;
ft2-basic_types.html#FT_UShort
FT_UShort
number_Of_HMetrics;
/* The following fields are not defined by the TrueType specification */
/* but they are used to connect the metrics header to the relevant    */
/* `HMTX' table.                                                      */
void
*
long_metrics
;
void
*
short_metrics
;
}
TT_HoriHeader
;
A structure used to model a TrueType horizontal header, the `hhea' table, as well as the corresponding horizontal metrics table, i.e., the `hmtx' table.
fields
Version
The table version.
Ascender
The font's ascender, i.e., the distance from the baseline to the top-most of all glyph points found in the font.
This value is invalid in many fonts, as it is usually set by the font designer, and often reflects only a portion of the glyphs found in the font (maybe ASCII).
You should use the `sTypoAscender' 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 bottom-most of all glyph points found in the font. It is negative.
This value is invalid in many fonts, as it is usually set by the font designer, and often reflects only a portion of the glyphs found in the font (maybe ASCII).
You should use the `sTypoDescender' 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 get the BTB, i.e., the baseline-to-baseline distance for the font.
advance_Width_Max
This field is the maximum of all advance widths found in the font. It can be used to compute the maximum width of an arbitrary string of text.
min_Left_Side_Bearing
The minimum left side bearing of all glyphs within the font.
min_Right_Side_Bearing
The minimum right side bearing of all glyphs within the font.
xMax_Extent
The maximum horizontal extent (i.e., the `width' of a glyph's bounding box) for all glyphs in the font.
caret_Slope_Rise
The rise coefficient of the cursor's slope of the cursor (slope=rise/run).
caret_Slope_Run
The run coefficient of the cursor's slope.
Reserved
10 reserved bytes.
metric_Data_Format
Always 0.
number_Of_HMetrics
Number of HMetrics entries in the `hmtx' table -- this value can be smaller than the total number of glyphs in the font.
long_metrics
A pointer into the `hmtx' table.
short_metrics
A pointer into the `hmtx' table.
note
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.
TT_VertHeader
typedef
struct
TT_VertHeader_
{
ft2-basic_types.html#FT_Fixed
FT_Fixed
Version;
ft2-basic_types.html#FT_Short
FT_Short
Ascender;
ft2-basic_types.html#FT_Short
FT_Short
Descender;
ft2-basic_types.html#FT_Short
FT_Short
Line_Gap;
ft2-basic_types.html#FT_UShort
FT_UShort
advance_Height_Max;      /* advance height maximum */
ft2-basic_types.html#FT_Short
FT_Short
min_Top_Side_Bearing;    /* minimum left-sb or top-sb       */
ft2-basic_types.html#FT_Short
FT_Short
min_Bottom_Side_Bearing; /* minimum right-sb or bottom-sb   */
ft2-basic_types.html#FT_Short
FT_Short
yMax_Extent;             /* xmax or ymax extents            */
ft2-basic_types.html#FT_Short
FT_Short
caret_Slope_Rise;
ft2-basic_types.html#FT_Short
FT_Short
caret_Slope_Run;
ft2-basic_types.html#FT_Short
FT_Short
caret_Offset;
ft2-basic_types.html#FT_Short
FT_Short
Reserved[4];
ft2-basic_types.html#FT_Short
FT_Short
metric_Data_Format;
ft2-basic_types.html#FT_UShort
FT_UShort
number_Of_VMetrics;
/* The following fields are not defined by the TrueType specification */
/* but they're used to connect the metrics header to the relevant     */
/* `HMTX' or `VMTX' table.                                            */
void
*
long_metrics
;
void
*
short_metrics
;
}
TT_VertHeader
;
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.
fields
Version
The table version.
Ascender
The font's ascender, i.e., the distance from the baseline to the top-most of all glyph points found in the font.
This value is invalid in many fonts, as it is usually set by the font designer, and often reflects only a portion of the glyphs found in the font (maybe ASCII).
You should use the `sTypoAscender' 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 bottom-most of all glyph points found in the font. It is negative.
This value is invalid in many fonts, as it is usually set by the font designer, and often reflects only a portion of the glyphs found in the font (maybe ASCII).
You should use the `sTypoDescender' 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 get the BTB, i.e., the baseline-to-baseline distance for the font.
advance_Height_Max
This field is the maximum of all advance heights found in the font. It can be used to compute the maximum height of an arbitrary string of text.
min_Top_Side_Bearing
The minimum top side bearing of all glyphs within the font.
min_Bottom_Side_Bearing
The minimum bottom side bearing of all glyphs within the font.
yMax_Extent
The maximum vertical extent (i.e., the `height' of a glyph's bounding box) for all glyphs in the font.
caret_Slope_Rise
The rise coefficient of the cursor's slope of the cursor (slope=rise/run).
caret_Slope_Run
The run coefficient of the cursor's slope.
caret_Offset
The cursor's offset for slanted fonts. This value is `reserved' in vmtx version 1.0.
Reserved
8 reserved bytes.
metric_Data_Format
Always 0.
number_Of_HMetrics
Number of VMetrics entries in the `vmtx' table -- this value can be smaller than the total number of glyphs in the font.
long_metrics
A pointer into the `vmtx' table.
short_metrics
A pointer into the `vmtx' table.
note
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.
TT_OS2
typedef
struct
TT_OS2_
{
ft2-basic_types.html#FT_UShort
FT_UShort
version;                /* 0x0001 - more or 0xFFFF */
ft2-basic_types.html#FT_Short
FT_Short
xAvgCharWidth;
ft2-basic_types.html#FT_UShort
FT_UShort
usWeightClass;
ft2-basic_types.html#FT_UShort
FT_UShort
usWidthClass;
ft2-basic_types.html#FT_Short
FT_Short
fsType;
ft2-basic_types.html#FT_Short
FT_Short
ySubscriptXSize;
ft2-basic_types.html#FT_Short
FT_Short
ySubscriptYSize;
ft2-basic_types.html#FT_Short
FT_Short
ySubscriptXOffset;
ft2-basic_types.html#FT_Short
FT_Short
ySubscriptYOffset;
ft2-basic_types.html#FT_Short
FT_Short
ySuperscriptXSize;
ft2-basic_types.html#FT_Short
FT_Short
ySuperscriptYSize;
ft2-basic_types.html#FT_Short
FT_Short
ySuperscriptXOffset;
ft2-basic_types.html#FT_Short
FT_Short
ySuperscriptYOffset;
ft2-basic_types.html#FT_Short
FT_Short
yStrikeoutSize;
ft2-basic_types.html#FT_Short
FT_Short
yStrikeoutPosition;
ft2-basic_types.html#FT_Short
FT_Short
sFamilyClass;
ft2-basic_types.html#FT_Byte
FT_Byte
panose[10];
ft2-basic_types.html#FT_ULong
FT_ULong
ulUnicodeRange1;        /* Bits 0-31   */
ft2-basic_types.html#FT_ULong
FT_ULong
ulUnicodeRange2;        /* Bits 32-63  */
ft2-basic_types.html#FT_ULong
FT_ULong
ulUnicodeRange3;        /* Bits 64-95  */
ft2-basic_types.html#FT_ULong
FT_ULong
ulUnicodeRange4;        /* Bits 96-127 */
ft2-basic_types.html#FT_Char
FT_Char
achVendID[4];
ft2-basic_types.html#FT_UShort
FT_UShort
fsSelection;
ft2-basic_types.html#FT_UShort
FT_UShort
usFirstCharIndex;
ft2-basic_types.html#FT_UShort
FT_UShort
usLastCharIndex;
ft2-basic_types.html#FT_Short
FT_Short
sTypoAscender;
ft2-basic_types.html#FT_Short
FT_Short
sTypoDescender;
ft2-basic_types.html#FT_Short
FT_Short
sTypoLineGap;
ft2-basic_types.html#FT_UShort
FT_UShort
usWinAscent;
ft2-basic_types.html#FT_UShort
FT_UShort
usWinDescent;
/* only version 1 tables: */
ft2-basic_types.html#FT_ULong
FT_ULong
ulCodePageRange1;       /* Bits 0-31   */
ft2-basic_types.html#FT_ULong
FT_ULong
ulCodePageRange2;       /* Bits 32-63  */
/* only version 2 tables: */
ft2-basic_types.html#FT_Short
FT_Short
sxHeight;
ft2-basic_types.html#FT_Short
FT_Short
sCapHeight;
ft2-basic_types.html#FT_UShort
FT_UShort
usDefaultChar;
ft2-basic_types.html#FT_UShort
FT_UShort
usBreakChar;
ft2-basic_types.html#FT_UShort
FT_UShort
usMaxContext;
}
TT_OS2
;
A structure used to model a TrueType OS/2 table. This is the long table version. All fields comply to the TrueType specification.
Note that we now support old Mac fonts which do not include an OS/2 table. In this case, the `version' field is always set to 0xFFFF.
TT_Postscript
typedef
struct
TT_Postscript_
{
ft2-basic_types.html#FT_Fixed
FT_Fixed
FormatType;
ft2-basic_types.html#FT_Fixed
FT_Fixed
italicAngle;
ft2-basic_types.html#FT_Short
FT_Short
underlinePosition;
ft2-basic_types.html#FT_Short
FT_Short
underlineThickness;
ft2-basic_types.html#FT_ULong
FT_ULong
isFixedPitch;
ft2-basic_types.html#FT_ULong
FT_ULong
minMemType42;
ft2-basic_types.html#FT_ULong
FT_ULong
maxMemType42;
ft2-basic_types.html#FT_ULong
FT_ULong
minMemType1;
ft2-basic_types.html#FT_ULong
FT_ULong
maxMemType1;
/* Glyph names follow in the file, but we don't   */
/* load them by default.  See the ttpost.c file.  */
}
TT_Postscript
;
A structure used to model a TrueType Postscript table. All fields comply to the TrueType table. This structure does not reference the Postscript glyph names, which can be nevertheless accessed with the `ttpost' module.
TT_PCLT
typedef
struct
TT_PCLT_
{
ft2-basic_types.html#FT_Fixed
FT_Fixed
Version;
ft2-basic_types.html#FT_ULong
FT_ULong
FontNumber;
ft2-basic_types.html#FT_UShort
FT_UShort
Pitch;
ft2-basic_types.html#FT_UShort
FT_UShort
xHeight;
ft2-basic_types.html#FT_UShort
FT_UShort
Style;
ft2-basic_types.html#FT_UShort
FT_UShort
TypeFamily;
ft2-basic_types.html#FT_UShort
FT_UShort
CapHeight;
ft2-basic_types.html#FT_UShort
FT_UShort
SymbolSet;
ft2-basic_types.html#FT_Char
FT_Char
TypeFace[16];
ft2-basic_types.html#FT_Char
FT_Char
CharacterComplement[8];
ft2-basic_types.html#FT_Char
FT_Char
FileName[6];
ft2-basic_types.html#FT_Char
FT_Char
StrokeWeight;
ft2-basic_types.html#FT_Char
FT_Char
WidthType;
ft2-basic_types.html#FT_Byte
FT_Byte
SerifStyle;
ft2-basic_types.html#FT_Byte
FT_Byte
Reserved;
}
TT_PCLT
;
A structure used to model a TrueType PCLT table. All fields comply to the TrueType table.
TT_MaxProfile
typedef
struct
TT_MaxProfile_
{
ft2-basic_types.html#FT_Fixed
FT_Fixed
version;
ft2-basic_types.html#FT_UShort
FT_UShort
numGlyphs;
ft2-basic_types.html#FT_UShort
FT_UShort
maxPoints;
ft2-basic_types.html#FT_UShort
FT_UShort
maxContours;
ft2-basic_types.html#FT_UShort
FT_UShort
maxCompositePoints;
ft2-basic_types.html#FT_UShort
FT_UShort
maxCompositeContours;
ft2-basic_types.html#FT_UShort
FT_UShort
maxZones;
ft2-basic_types.html#FT_UShort
FT_UShort
maxTwilightPoints;
ft2-basic_types.html#FT_UShort
FT_UShort
maxStorage;
ft2-basic_types.html#FT_UShort
FT_UShort
maxFunctionDefs;
ft2-basic_types.html#FT_UShort
FT_UShort
maxInstructionDefs;
ft2-basic_types.html#FT_UShort
FT_UShort
maxStackElements;
ft2-basic_types.html#FT_UShort
FT_UShort
maxSizeOfInstructions;
ft2-basic_types.html#FT_UShort
FT_UShort
maxComponentElements;
ft2-basic_types.html#FT_UShort
FT_UShort
maxComponentDepth;
}
TT_MaxProfile
;
The maximum profile is a table containing many max values which can be used to pre-allocate arrays. This ensures that no memory allocation occurs during a glyph load.
fields
version
The version number.
numGlyphs
The number of glyphs in this TrueType font.
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'.
maxCompositeContours
The maximum number of contours in a composite TrueType glyph. See also the structure element `maxContours'.
maxZones
The maximum number of zones used for glyph hinting.
maxTwilightPoints
The maximum number of points in the twilight zone used for glyph hinting.
maxStorage
The maximum number of elements in the storage area used for glyph hinting.
maxFunctionDefs
The maximum number of function definitions in the TrueType bytecode for this font.
maxInstructionDefs
The maximum number of instruction definitions in the TrueType bytecode for this font.
maxStackElements
The maximum number of stack elements used during bytecode interpretation.
maxSizeOfInstructions
The maximum number of TrueType opcodes used for glyph hinting.
maxComponentElements
The maximum number of simple (i.e., non- composite) glyphs in a composite glyph.
maxComponentDepth
The maximum nesting depth of composite glyphs.
note
This structure is only used during font loading.
FT_Sfnt_Tag
typedef
enum
{
ft_sfnt_head = 0,
ft_sfnt_maxp = 1,
ft_sfnt_os2  = 2,
ft_sfnt_hhea = 3,
ft_sfnt_vhea = 4,
ft_sfnt_post = 5,
ft_sfnt_pclt = 6,
sfnt_max   /*
internal
end mark */
}
FT_Sfnt_Tag
;
An enumeration used to specify the index of an SFNT table. Used in the
ft2-truetype_tables.html#FT_Get_Sfnt_Table
FT_Get_Sfnt_Table
API function.
FT_Get_Sfnt_Table
FT_EXPORT(
void
* )
FT_Get_Sfnt_Table
(
ft2-base_interface.html#FT_Face
FT_Face
face,
ft2-truetype_tables.html#FT_Sfnt_Tag
FT_Sfnt_Tag
tag );
Returns a pointer to a given SFNT table within a face.
input
face
A handle to the source.
tag
The index of the SFNT table.
return
A type-less pointer to the table. This will be 0 in case of error, or if the corresponding table was not found
OR
loaded from the file.
note
The table is owned by the face object and disappears with it.
This function is only useful to access SFNT tables that are loaded by the sfnt/truetype/opentype drivers. See
ft2-truetype_tables.html#FT_Sfnt_Tag
FT_Sfnt_Tag
for a list.
FT_Load_Sfnt_Table
FT_EXPORT(
ft2-basic_types.html#FT_Error
FT_Error
)
FT_Load_Sfnt_Table
(
ft2-base_interface.html#FT_Face
FT_Face
face,
ft2-basic_types.html#FT_ULong
FT_ULong
tag,
ft2-basic_types.html#FT_Long
FT_Long
offset,
ft2-basic_types.html#FT_Byte
FT_Byte
*   buffer,
ft2-basic_types.html#FT_ULong
FT_ULong
*  length );
Loads any font table into client memory.
input
face
A handle to the source face.
tag
The 4-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
ft2-header_file_macros.html#FT_TRUETYPE_TAGS_H
FT_TRUETYPE_TAGS_H
file, or forge a new one with
ft2-basic_types.html#FT_MAKE_TAG
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 ... }
FT_Sfnt_Table_Info
FT_EXPORT(
ft2-basic_types.html#FT_Error
FT_Error
)
FT_Sfnt_Table_Info
(
ft2-base_interface.html#FT_Face
FT_Face
face,
ft2-basic_types.html#FT_UInt
FT_UInt
table_index,
ft2-basic_types.html#FT_ULong
FT_ULong
*tag,
ft2-basic_types.html#FT_ULong
FT_ULong
*length );
Returns 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.
output
tag
The name tag of the SFNT table.
length
The length of the SFNT table.
return
FreeType error code. 0 means success.
note
SFNT tables with length zero are treated as missing by Windows.
FT_Get_CMap_Language_ID
FT_EXPORT(
ft2-basic_types.html#FT_ULong
FT_ULong
)
FT_Get_CMap_Language_ID
(
ft2-base_interface.html#FT_CharMap
FT_CharMap
charmap
);
Return TrueType/sfnt specific cmap language ID. Definitions of language ID values are in freetype/ttnameid.h.
input
charmap
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.
FT_PARAM_TAG_UNPATENTED_HINTING
#define
FT_PARAM_TAG_UNPATENTED_HINTING
ft2-basic_types.html#FT_MAKE_TAG
FT_MAKE_TAG
( 'u', 'n', 'p', 'a' )
A constant used as the tag of an
ft2-base_interface.html#FT_Parameter
FT_Parameter
structure to indicate that unpatented methods only should be used by the TrueType bytecode interpreter for a typeface opened by FT_Open_Face.
