FreeType-2.1.10 API Reference
TrueType Tables
Synopsis
#TT_HeaderTT_Header #FT_Sfnt_TagFT_Sfnt_Tag #TT_HoriHeaderTT_HoriHeader #FT_Get_Sfnt_TableFT_Get_Sfnt_Table #TT_VertHeaderTT_VertHeader #FT_Load_Sfnt_TableFT_Load_Sfnt_Table #TT_OS2TT_OS2 #FT_Sfnt_Table_InfoFT_Sfnt_Table_Info #TT_PostscriptTT_Postscript #FT_Get_CMap_Language_IDFT_Get_CMap_Language_ID #TT_PCLTTT_PCLT #FT_PARAM_TAG_UNPATENTED_HINTINGFT_PARAM_TAG_UNPATENTED_HINTING #TT_MaxProfileTT_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_FixedFT_Fixed    Table_Version;
    
ft2-basic_types.html#FT_FixedFT_Fixed    Font_Revision;
    
ft2-basic_types.html#FT_LongFT_Long     CheckSum_Adjust;
    
ft2-basic_types.html#FT_LongFT_Long     Magic_Number;
    
ft2-basic_types.html#FT_UShortFT_UShort   Flags;
    
ft2-basic_types.html#FT_UShortFT_UShort   Units_Per_EM;
    
ft2-basic_types.html#FT_LongFT_Long     Created [2];
    
ft2-basic_types.html#FT_LongFT_Long     Modified[2];
    
ft2-basic_types.html#FT_ShortFT_Short    xMin;
    
ft2-basic_types.html#FT_ShortFT_Short    yMin;
    
ft2-basic_types.html#FT_ShortFT_Short    xMax;
    
ft2-basic_types.html#FT_ShortFT_Short    yMax;
    
ft2-basic_types.html#FT_UShortFT_UShort   Mac_Style;
    
ft2-basic_types.html#FT_UShortFT_UShort   Lowest_Rec_PPEM;
    
ft2-basic_types.html#FT_ShortFT_Short    Font_Direction;
    
ft2-basic_types.html#FT_ShortFT_Short    Index_To_Loc_Format;
    
ft2-basic_types.html#FT_ShortFT_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_FixedFT_Fixed    Version;
    
ft2-basic_types.html#FT_ShortFT_Short    Ascender;
    
ft2-basic_types.html#FT_ShortFT_Short    Descender;
    
ft2-basic_types.html#FT_ShortFT_Short    Line_Gap;
    
ft2-basic_types.html#FT_UShortFT_UShort   advance_Width_Max;      /* advance width maximum */
    
ft2-basic_types.html#FT_ShortFT_Short    min_Left_Side_Bearing;  /* minimum left-sb       */
    
ft2-basic_types.html#FT_ShortFT_Short    min_Right_Side_Bearing; /* minimum right-sb      */
    
ft2-basic_types.html#FT_ShortFT_Short    xMax_Extent;            /* xmax extents          */
    
ft2-basic_types.html#FT_ShortFT_Short    caret_Slope_Rise;
    
ft2-basic_types.html#FT_ShortFT_Short    caret_Slope_Run;
    
ft2-basic_types.html#FT_ShortFT_Short    caret_Offset;
    
ft2-basic_types.html#FT_ShortFT_Short    Reserved[4];
    
ft2-basic_types.html#FT_ShortFT_Short    metric_Data_Format;
    
ft2-basic_types.html#FT_UShortFT_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_FixedFT_Fixed    Version;
    
ft2-basic_types.html#FT_ShortFT_Short    Ascender;
    
ft2-basic_types.html#FT_ShortFT_Short    Descender;
    
ft2-basic_types.html#FT_ShortFT_Short    Line_Gap;
    
ft2-basic_types.html#FT_UShortFT_UShort   advance_Height_Max;      /* advance height maximum */
    
ft2-basic_types.html#FT_ShortFT_Short    min_Top_Side_Bearing;    /* minimum left-sb or top-sb       */
    
ft2-basic_types.html#FT_ShortFT_Short    min_Bottom_Side_Bearing; /* minimum right-sb or bottom-sb   */
    
ft2-basic_types.html#FT_ShortFT_Short    yMax_Extent;             /* xmax or ymax extents            */
    
ft2-basic_types.html#FT_ShortFT_Short    caret_Slope_Rise;
    
ft2-basic_types.html#FT_ShortFT_Short    caret_Slope_Run;
    
ft2-basic_types.html#FT_ShortFT_Short    caret_Offset;
    
ft2-basic_types.html#FT_ShortFT_Short    Reserved[4];
    
ft2-basic_types.html#FT_ShortFT_Short    metric_Data_Format;
    
ft2-basic_types.html#FT_UShortFT_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_UShortFT_UShort   version;                /* 0x0001 - more or 0xFFFF */
    
ft2-basic_types.html#FT_ShortFT_Short    xAvgCharWidth;
    
ft2-basic_types.html#FT_UShortFT_UShort   usWeightClass;
    
ft2-basic_types.html#FT_UShortFT_UShort   usWidthClass;
    
ft2-basic_types.html#FT_ShortFT_Short    fsType;
    
ft2-basic_types.html#FT_ShortFT_Short    ySubscriptXSize;
    
ft2-basic_types.html#FT_ShortFT_Short    ySubscriptYSize;
    
ft2-basic_types.html#FT_ShortFT_Short    ySubscriptXOffset;
    
ft2-basic_types.html#FT_ShortFT_Short    ySubscriptYOffset;
    
ft2-basic_types.html#FT_ShortFT_Short    ySuperscriptXSize;
    
ft2-basic_types.html#FT_ShortFT_Short    ySuperscriptYSize;
    
ft2-basic_types.html#FT_ShortFT_Short    ySuperscriptXOffset;
    
ft2-basic_types.html#FT_ShortFT_Short    ySuperscriptYOffset;
    
ft2-basic_types.html#FT_ShortFT_Short    yStrikeoutSize;
    
ft2-basic_types.html#FT_ShortFT_Short    yStrikeoutPosition;
    
ft2-basic_types.html#FT_ShortFT_Short    sFamilyClass;
    
ft2-basic_types.html#FT_ByteFT_Byte     panose[10];
    
ft2-basic_types.html#FT_ULongFT_ULong    ulUnicodeRange1;        /* Bits 0-31   */
    
ft2-basic_types.html#FT_ULongFT_ULong    ulUnicodeRange2;        /* Bits 32-63  */
    
ft2-basic_types.html#FT_ULongFT_ULong    ulUnicodeRange3;        /* Bits 64-95  */
    
ft2-basic_types.html#FT_ULongFT_ULong    ulUnicodeRange4;        /* Bits 96-127 */
    
ft2-basic_types.html#FT_CharFT_Char     achVendID[4];
    
ft2-basic_types.html#FT_UShortFT_UShort   fsSelection;
    
ft2-basic_types.html#FT_UShortFT_UShort   usFirstCharIndex;
    
ft2-basic_types.html#FT_UShortFT_UShort   usLastCharIndex;
    
ft2-basic_types.html#FT_ShortFT_Short    sTypoAscender;
    
ft2-basic_types.html#FT_ShortFT_Short    sTypoDescender;
    
ft2-basic_types.html#FT_ShortFT_Short    sTypoLineGap;
    
ft2-basic_types.html#FT_UShortFT_UShort   usWinAscent;
    
ft2-basic_types.html#FT_UShortFT_UShort   usWinDescent;
    /* only version 1 tables: */
    
ft2-basic_types.html#FT_ULongFT_ULong    ulCodePageRange1;       /* Bits 0-31   */
    
ft2-basic_types.html#FT_ULongFT_ULong    ulCodePageRange2;       /* Bits 32-63  */
    /* only version 2 tables: */
    
ft2-basic_types.html#FT_ShortFT_Short    sxHeight;
    
ft2-basic_types.html#FT_ShortFT_Short    sCapHeight;
    
ft2-basic_types.html#FT_UShortFT_UShort   usDefaultChar;
    
ft2-basic_types.html#FT_UShortFT_UShort   usBreakChar;
    
ft2-basic_types.html#FT_UShortFT_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_FixedFT_Fixed   FormatType;
    
ft2-basic_types.html#FT_FixedFT_Fixed   italicAngle;
    
ft2-basic_types.html#FT_ShortFT_Short   underlinePosition;
    
ft2-basic_types.html#FT_ShortFT_Short   underlineThickness;
    
ft2-basic_types.html#FT_ULongFT_ULong   isFixedPitch;
    
ft2-basic_types.html#FT_ULongFT_ULong   minMemType42;
    
ft2-basic_types.html#FT_ULongFT_ULong   maxMemType42;
    
ft2-basic_types.html#FT_ULongFT_ULong   minMemType1;
    
ft2-basic_types.html#FT_ULongFT_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_FixedFT_Fixed    Version;
    
ft2-basic_types.html#FT_ULongFT_ULong    FontNumber;
    
ft2-basic_types.html#FT_UShortFT_UShort   Pitch;
    
ft2-basic_types.html#FT_UShortFT_UShort   xHeight;
    
ft2-basic_types.html#FT_UShortFT_UShort   Style;
    
ft2-basic_types.html#FT_UShortFT_UShort   TypeFamily;
    
ft2-basic_types.html#FT_UShortFT_UShort   CapHeight;
    
ft2-basic_types.html#FT_UShortFT_UShort   SymbolSet;
    
ft2-basic_types.html#FT_CharFT_Char     TypeFace[16];
    
ft2-basic_types.html#FT_CharFT_Char     CharacterComplement[8];
    
ft2-basic_types.html#FT_CharFT_Char     FileName[6];
    
ft2-basic_types.html#FT_CharFT_Char     StrokeWeight;
    
ft2-basic_types.html#FT_CharFT_Char     WidthType;
    
ft2-basic_types.html#FT_ByteFT_Byte     SerifStyle;
    
ft2-basic_types.html#FT_ByteFT_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_FixedFT_Fixed    version;
    
ft2-basic_types.html#FT_UShortFT_UShort   numGlyphs;
    
ft2-basic_types.html#FT_UShortFT_UShort   maxPoints;
    
ft2-basic_types.html#FT_UShortFT_UShort   maxContours;
    
ft2-basic_types.html#FT_UShortFT_UShort   maxCompositePoints;
    
ft2-basic_types.html#FT_UShortFT_UShort   maxCompositeContours;
    
ft2-basic_types.html#FT_UShortFT_UShort   maxZones;
    
ft2-basic_types.html#FT_UShortFT_UShort   maxTwilightPoints;
    
ft2-basic_types.html#FT_UShortFT_UShort   maxStorage;
    
ft2-basic_types.html#FT_UShortFT_UShort   maxFunctionDefs;
    
ft2-basic_types.html#FT_UShortFT_UShort   maxInstructionDefs;
    
ft2-basic_types.html#FT_UShortFT_UShort   maxStackElements;
    
ft2-basic_types.html#FT_UShortFT_UShort   maxSizeOfInstructions;
    
ft2-basic_types.html#FT_UShortFT_UShort   maxComponentElements;
    
ft2-basic_types.html#FT_UShortFT_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_TableFT_Get_Sfnt_Table  API function.
FT_Get_Sfnt_Table 
  FT_EXPORT( 
void* )
  
FT_Get_Sfnt_Table( ft2-base_interface.html#FT_FaceFT_Face       face,
                     
ft2-truetype_tables.html#FT_Sfnt_TagFT_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_TagFT_Sfnt_Tag  for a list.
FT_Load_Sfnt_Table 
  FT_EXPORT( 
ft2-basic_types.html#FT_ErrorFT_Error  )
  
FT_Load_Sfnt_Table( ft2-base_interface.html#FT_FaceFT_Face     face,
                      
ft2-basic_types.html#FT_ULongFT_ULong    tag,
                      
ft2-basic_types.html#FT_LongFT_Long     offset,
                      
ft2-basic_types.html#FT_ByteFT_Byte *   buffer,
                      
ft2-basic_types.html#FT_ULongFT_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_HFT_TRUETYPE_TAGS_H  file, or forge a new one with ft2-basic_types.html#FT_MAKE_TAGFT_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_ErrorFT_Error  )
  
FT_Sfnt_Table_Info( ft2-base_interface.html#FT_FaceFT_Face     face,
                      
ft2-basic_types.html#FT_UIntFT_UInt     table_index,
                      
ft2-basic_types.html#FT_ULongFT_ULong   *tag,
                      
ft2-basic_types.html#FT_ULongFT_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_ULongFT_ULong  )
  
FT_Get_CMap_Language_ID( ft2-base_interface.html#FT_CharMapFT_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_TAGFT_MAKE_TAG ( 'u', 'n', 'p', 'a' )
A constant used as the tag of an ft2-base_interface.html#FT_ParameterFT_Parameter  structure to indicate that unpatented methods only should be used by the TrueType bytecode interpreter for a typeface opened by FT_Open_Face.
