Share via


glyf — Glyph Data (OpenType 1.8.4)

This table contains information that describes the glyphs in the font in the TrueType outline format. Information regarding the rasterizer (scaler) refers to the TrueType rasterizer. For details regarding scaling, grid-fitting and rasterization of TrueType outlines, see the TrueType Fundamentals chapter.

Table Organization

The 'glyf' table is comprised of a list of glyph data blocks, each of which provides the description for a single glyph. Glyphs are referenced by identifiers (glyph IDs), which are sequential integers beginning at zero. The total number of glyphs is specified by the numGlyphs field in the 'maxp' table. The 'glyf' table does not include any overall table header or records providing offsets to glyph data blocks. Rather, the 'loca' table provides an array of offsets, indexed by glyph IDs, which provide the location of each glyph data block within the 'glyf' table. Note that the 'glyf' table must always be used in conjunction with the 'loca' and 'maxp' tables. The size of each glyph data block is inferred from the difference between two consecutive offsets in the 'loca' table (with one extra offset provided to give the size of the last glyph data block). As a result of the 'loca' format, glyph data blocks within the 'glyf' table must be in glyph ID order.

Glyph Headers

Each glyph description begins with a header:

Glyph Header

Type Name Description
int16 numberOfContours If the number of contours is greater than or equal to zero, this is a simple glyph. If negative, this is a composite glyph — the value -1 should be used for composite glyphs.
int16 xMin Minimum x for coordinate data.
int16 yMin Minimum y for coordinate data.
int16 xMax Maximum x for coordinate data.
int16 yMax Maximum y for coordinate data.

Note that the bounding rectangle from each character is defined as the rectangle with a lower left corner of (xMin, yMin) and an upper right corner of (xMax, yMax). These values are obtained directly from the point coordinate data for the glyph, comparing all on-curve and off-curve points. Phantom points computed by the rasterizer are not relevant. Note that the bounding box defined by control points is guaranteed to contain the outline, but might not be tight to the outline.

Note: The scaler will perform better if the glyph coordinates have been created such that the xMin is equal to the lsb. For example, if the lsb is 123, then xMin for the glyph should be 123. If the lsb is -12 then the xMin should be -12. If the lsb is 0 then xMin is 0. If all glyphs are done like this, set bit 1 of flags field in the 'head' table.

Note: The glyph descriptions do not include side bearing information. Left side bearings are provided in the 'hmtx' table, and right side bearings are inferred from the advance width (also provided in the 'hmtx' table) and the bounding box coordinates provided in the 'glyf' table. For vertical layout, top side bearings are provided in the 'vmtx' table, and bottom side bearings are inferred. The rasterizer will generate a representation of side bearings in the form of “phantom” points, which are added as four additional points at the end of the glyph description and which can be referenced and manipulated by glyph instructions. See the chapter Instructing TrueType Glyphs for more background on phantom points.

Simple Glyph Description

This is the table information needed if numberOfContours is greater than or equal to zero, that is, a glyph is not a composite. Note that point numbers are base-zero indices that are numbered sequentially across all of the contours for a glyph; that is, the first point number of each contour (except the first) is one greater than the last point number of the preceding contour.

Simple Glyph Table

Type Name Description
uint16 endPtsOfContours[numberOfContours] Array of point indices for the last point of each contour, in increasing numeric order.
uint16 instructionLength Total number of bytes for instructions. If instructionLength is zero, no instructions are present for this glyph, and this field is followed directly by the flags field.
uint8 instructions[instructionLength] Array of instruction byte code for the glyph.
uint8 flags[variable] Array of flag elements. See below for details regarding the number of flag array elements.
uint8 or int16 xCoordinates[variable] Contour point x-coordinates. See below for details regarding the number of coordinate array elements. Coordinate for the first point is relative to (0,0); others are relative to previous point.
uint8 or int16 yCoordinates[variable] Contour point y-coordinates. See below for details regarding the number of coordinate array elements. Coordinate for the first point is relative to (0,0); others are relative to previous point.

Note: In the 'glyf' table, the position of a point is not stored in absolute terms but as a vector relative to the previous point. The delta-x and delta-y vectors represent these (often small) changes in position. Coordinate values are in font design units, as defined by the unitsPerEm field in the 'head' table. Note that smaller unitsPerEm values will make it more likely that delta-x and delta-y values can fit in a smaller representation (8-bit rather than 16-bit), though with a trade-off in the level or precision that can be used for describing an outline.

Each element in the flags array is a single byte, each of which has multiple flag bits with distinct meanings, as shown below.

In logical terms, there is one flag byte element, one x-coordinate, and one y-coordinate for each point. The number of points is determined by the last entry in the endPtsOfContours array. Note, however, that the flag byte elements and the coordinate arrays use packed representations. In particular, if a logical sequence of flag elements or sequence of x- or y-coordinates is repeated, then the actual flag byte element or coordinate value can be given in a single entry, with special flags used to indicate that this value is repeated for subsequent logical entries. The actual stored size of the flags or coordinate arrays must be determined by parsing the flags array entries. See the flag descriptions below for details.

Simple Glyph Flags

Mask Name Description
0x01 ON_CURVE_POINT Bit 0: If set, the point is on the curve; otherwise, it is off the curve.
0x02 X_SHORT_VECTOR Bit 1: If set, the corresponding x-coordinate is 1 byte long. If not set, it is two bytes long. For the sign of this value, see the description of the X_IS_SAME_OR_POSITIVE_X_SHORT_VECTOR flag.
0x04 Y_SHORT_VECTOR Bit 2: If set, the corresponding y-coordinate is 1 byte long. If not set, it is two bytes long. For the sign of this value, see the description of the Y_IS_SAME_OR_POSITIVE_Y_SHORT_VECTOR flag.
0x08 REPEAT_FLAG Bit 3: If set, the next byte (read as unsigned) specifies the number of additional times this flag byte is to be repeated in the logical flags array — that is, the number of additional logical flag entries inserted after this entry. (In the expanded logical array, this bit is ignored.) In this way, the number of flags listed can be smaller than the number of points in the glyph description.
0x10 X_IS_SAME_OR_POSITIVE_X_SHORT_VECTOR Bit 4: This flag has two meanings, depending on how the X_SHORT_VECTOR flag is set. If X_SHORT_VECTOR is set, this bit describes the sign of the value, with 1 equalling positive and 0 negative. If X_SHORT_VECTOR is not set and this bit is set, then the current x-coordinate is the same as the previous x-coordinate. If X_SHORT_VECTOR is not set and this bit is also not set, the current x-coordinate is a signed 16-bit delta vector.
0x20 Y_IS_SAME_OR_POSITIVE_Y_SHORT_VECTOR Bit 5: This flag has two meanings, depending on how the Y_SHORT_VECTOR flag is set. If Y_SHORT_VECTOR is set, this bit describes the sign of the value, with 1 equalling positive and 0 negative. If Y_SHORT_VECTOR is not set and this bit is set, then the current y-coordinate is the same as the previous y-coordinate. If Y_SHORT_VECTOR is not set and this bit is also not set, the current y-coordinate is a signed 16-bit delta vector.
0x40 OVERLAP_SIMPLE Bit 6: If set, contours in the glyph description may overlap. Use of this flag is not required in OpenType — that is, it is valid to have contours overlap without having this flag set. It may affect behaviors in some platforms, however. (See the discussion of “Overlapping contours” in Apple’s specification for details regarding behavior in Apple platforms.) When used, it must be set on the first flag byte for the glyph. See additional details below.
0x80 Reserved Bit 7 is reserved: set to zero.

A non-zero-fill algorithm is needed to avoid dropouts when contours overlap. The OVERLAP_SIMPLE flag is used by some rasterizer implementations to ensure that a non-zero-fill algorithm is used rather than an even-odd-fill algorithm. Implementations that always use a non-zero-fill algorithm will ignore this flag. Note that some implementations might check this flag specifically in non-variable fonts, but always use a non-zero-fill algorithm for variable fonts. This flag can be used in order to provide broad interoperability of fonts — particularly non-variable fonts — when glyphs have overlapping contours.

Note that variable fonts often make use of overlapping contours. This has implications for tools that generate static-font data for a specific instance of a variable font, if broad interoperability of the derived font is desired: if a glyph has overlapping contours in the given instance, then the tool should either set this flag in the derived glyph data, or else should merge contours to remove overlap of separate contours.

Note: The OVERLAP_COMPOUND flag, described below, has a similar purpose in relation to composite glyphs. The same considerations described for the OVERLAP_SIMPLE flag also apply to the OVERLAP_COMPOUND flag.

Composite Glyph Description

If numberOfContours is negative, a composite glyph description is used.

Note: A numberOfContours value of -1 is recommended to indicate a composite glyph.

A composite glyph starts with two uint16 values (“flags” and “glyphIndex,” i.e. the index of the first contour in this composite glyph); the data then varies according to “flags”).

Composite Glyph Table

Type Name Description
uint16 flags component flag
uint16 glyphIndex glyph index of component
uint8, int8, uint16 or int16 argument1 x-offset for component or point number; type depends on bits 0 and 1 in component flags
uint8, int8, uint16 or int16 argument2 y-offset for component or point number; type depends on bits 0 and 1 in component flags
Transformation Option

The C pseudo-code fragment below shows how the composite glyph information is stored and parsed; definitions for “flags” bits follow this fragment:

do {
    uint16 flags;
    uint16 glyphIndex;
    if ( flags & ARG_1_AND_2_ARE_WORDS) {
    (int16 or FWord) argument1;
    (int16 or FWord) argument2;
    } else {
        uint16 arg1and2; /* (arg1 << 8) | arg2 */
    }
    if ( flags & WE_HAVE_A_SCALE ) {
        F2Dot14  scale;    /* Format 2.14 */
    } else if ( flags & WE_HAVE_AN_X_AND_Y_SCALE ) {
        F2Dot14  xscale;    /* Format 2.14 */
        F2Dot14  yscale;    /* Format 2.14 */
    } else if ( flags & WE_HAVE_A_TWO_BY_TWO ) {
        F2Dot14  xscale;    /* Format 2.14 */
        F2Dot14  scale01;   /* Format 2.14 */
        F2Dot14  scale10;   /* Format 2.14 */
        F2Dot14  yscale;    /* Format 2.14 */
    }
} while ( flags & MORE_COMPONENTS )
if (flags & WE_HAVE_INSTR){
    uint16 numInstr
    uint8 instr[numInstr]

Argument1 and argument2 can be either x and y offsets to be added to the glyph (the ARGS_ARE_XY_VALUES flag is set), or two point numbers (the ARGS_ARE_XY_VALUES flag is not set). In the latter case, the first point number indicates the point that is to be matched to the new glyph. The second number indicates the new glyph’s “matched” point. Once a glyph is added, its point numbers begin directly after the last glyphs (endpoint of first glyph + 1).

When arguments 1 and 2 are an x and a y offset instead of points and the bit ROUND_XY_TO_GRID is set to 1, the values are rounded to those of the closest grid lines before they are added to the glyph. X and Y offsets are described in FUnits.

If the bit WE_HAVE_A_SCALE is set, the scale value is read in 2.14 format-the value can be between -2 to almost +2. The glyph will be scaled by this value before grid-fitting.

The bit WE_HAVE_A_TWO_BY_TWO allows for linear transformation of the X and Y coordinates by specifying a 2 × 2 matrix. This could be used for scaling and 90-degree rotations of the glyph components, for example.

The following composite glyph flags are defined:

Composite Glyph Flags

Mask Name Description
0x0001 ARG_1_AND_2_ARE_WORDS Bit 0: If this is set, the arguments are 16-bit (uint16 or int16); otherwise, they are bytes (uint8 or int8).
0x0002 ARGS_ARE_XY_VALUES Bit 1: If this is set, the arguments are signed xy values; otherwise, they are unsigned point numbers.
0x0004 ROUND_XY_TO_GRID Bit 2: For the xy values if the preceding is true.
0x0008 WE_HAVE_A_SCALE Bit 3: This indicates that there is a simple scale for the component. Otherwise, scale = 1.0.
0x0020 MORE_COMPONENTS Bit 5: Indicates at least one more glyph after this one.
0x0040 WE_HAVE_AN_X_AND_Y_SCALE Bit 6: The x direction will use a different scale from the y direction.
0x0080 WE_HAVE_A_TWO_BY_TWO Bit 7: There is a 2 by 2 transformation that will be used to scale the component.
0x0100 WE_HAVE_INSTRUCTIONS Bit 8: Following the last component are instructions for the composite character.
0x0200 USE_MY_METRICS Bit 9: If set, this forces the aw and lsb (and rsb) for the composite to be equal to those from this original glyph. This works for hinted and unhinted characters.
0x0400 OVERLAP_COMPOUND Bit 10: If set, the components of the compound glyph overlap. Use of this flag is not required in OpenType — that is, it is valid to have components overlap without having this flag set. It may affect behaviors in some platforms, however. (See Apple’s specification for details regarding behavior in Apple platforms.) When used, it must be set on the flag word for the first component. See additional remarks, above, for the similar OVERLAP_SIMPLE flag used in simple-glyph descriptions.
0x0800 SCALED_COMPONENT_OFFSET Bit 11: The composite is designed to have the component offset scaled.
0x1000 UNSCALED_COMPONENT_OFFSET Bit 12: The composite is designed not to have the component offset scaled.
0xE010 Reserved Bits 4, 13, 14 and 15 are reserved: set to 0.

The purpose of USE_MY_METRICS is to force the lsb and rsb to take on a desired value. For example, an i-circumflex (U+00EF) is often composed of the circumflex and a dotless-i. In order to force the composite to have the same metrics as the dotless-i, set USE_MY_METRICS for the dotless-i component of the composite. Without this bit, the rsb and lsb would be calculated from the 'hmtx' entry for the composite (or would need to be explicitly set with TrueType instructions).

Note that the behavior of the USE_MY_METRICS operation is undefined for rotated composite components.

The SCALED_COMPONENT_OFFSET and UNSCALED_COMPONENT_OFFSET flags are used to determine how x and y offset values are to be interpreted when the component glyph is scaled. If the SCALED_COMPONENT_OFFSET flag is set, then the x and y offset values are deemed to be in the component glyph’s coordinate system, and the scale transformation is applied to both values. If the UNSCALED_COMPONENT_OFFSET flag is set, then the x and y offset values are deemed to be in the current glyph’s coordinate system, and the scale transformation is not applied to either value. If neither flag is set, then the rasterizer will apply a default behavior. On Microsoft and Apple platforms, the default behavior is the same as when the UNSCALED_COMPONENT_OFFSET flag is set; this behavior is recommended for all rasterizer implementations. If a font has both flags set, this is invalid; the rasterizer should use its default behavior for this case.