Parsing TrueType (TTF) Font Files — A Reference

A practical, implementation-agnostic guide to reading the TTF binary format. It is organized around the act of parsing: the spine of the document is 5. How to parse, which walks the file in order and links each step to that table’s byte layout in 6. Table reference. Read the parse flow top to bottom; click into a table’s layout only when you need the exact fields.

Contents

1. Introduction
2. Mental model
3. Conventions
4. File structure
5. How to parse
6. Table reference
   • 6.1 head
   • 6.2 maxp
   • 6.3 hhea
   • 6.4 hmtx
   • 6.5 loca
   • 6.6 glyf
   • 6.7 cmap
   • 6.8 name
   • 6.9 post
   • 6.10 OS/2
   • 6.11 kern
7. Sources

↑ Contents

1. Introduction

The goal is to take a .ttf file as a flat array of bytes and turn it into structured data — the font header, the glyph outlines, the metrics, the character map. This document covers how to do that: the file’s shape, the order to read things in, how to move the read cursor through the bytes, and the byte-level layout of every core table. Field layouts are given as plain Type | Name | Notes tables so they map directly to a struct in any language.

It does not contain program code — it is the format reference you build code from.

↑ Contents

2. Mental model

A TTF file is not a document you read front to back. It is a small archive (the format is called “sfnt” — scalable font). Its bytes are organized as:

1. A 12-byte offset table (the sfnt header): what kind of font this is and how many tables it holds.
2. A table directory: one fixed-size record per table, each saying “the table with this tag lives at this byte offset and is this long.”
3. The table data, located only by the offsets in the directory.

The crucial consequence: you never assume where anything is. You read a table’s offset and length from the directory, then jump there.

It helps to know what the tables are for before parsing them. This is how a character becomes a drawn glyph:

character code ──(cmap)──► glyph index ──(loca)──► glyf  (the outline)
                                        └─(hmtx)──► advance width (the spacing)

head and maxp are the configuration that makes loca interpretable. This chain is also why the parse order in section 5 is what it is.

↑ Contents

3. Conventions

Endianness

Everything is big-endian (most significant byte first). The two bytes 0x00 0x09 mean 9, not 2304. There are no little-endian fields anywhere.

Data types

The spec uses named types. These are the ones you need:

Signedness matters. Most binary helpers decode only unsigned integers. For signed fields (int16, int64, …), decode the unsigned value of the same width and reinterpret the bits as two’s complement. Get this wrong and a small negative (e.g. a descender of -200) becomes a huge positive — and bounding boxes routinely go negative, so it bites.

↑ Contents

4. File structure

The top of every TTF is a fixed header followed by the directory. These two are the only parts you read linearly; everything else is reached by offset.

4.1 Offset table (sfnt header) — 12 bytes, at byte 0

searchRange, entrySelector, and rangeShift are a legacy binary-search optimization. You can ignore their meaning, but for a byte-identical round-trip you must read and re-emit them verbatim (or recompute with the formulas above).

4.2 Table directory — numTables records of 16 bytes each, at byte 12

Record i begins at byte 12 + i × 16.

• In well-formed fonts the records are sorted ascending by tag, but the table data they point at can appear in any physical order.
• Each table’s data is padded with zero bytes to a 4-byte boundary. length is the real (unpadded) length; the next table’s offset accounts for padding.

↑ Contents

5. How to parse

This is the core of the document. The diagram above shows the full parse flow and table dependencies. Below is the exact sequence to follow and the strategy for decoding each table.

5.1 The parse sequence

Where a table sits (physical) is independent of when you decode it (logical). Decode order is forced by data dependencies:

Follow this sequence. Each step links to that table’s byte layout in section 7; the note is only what the step needs and yields, not the full definition.

1. Offset table — byte layout →. Read the first 12 bytes; capture numTables.
2. Table directory — byte layout →. Read numTables × 16 bytes into a tag → (offset, length) map. After this, switch from linear reading to seeking by offset.
3. head — byte layout →. Yields unitsPerEm, indexToLocFormat, the font bounding box.
4. maxp — byte layout →. Yields numGlyphs.
5. hhea — byte layout →. Yields numberOfHMetrics.
6. hmtx — byte layout →. Needs numberOfHMetrics (hhea) and numGlyphs (maxp).
7. loca — byte layout →. Needs indexToLocFormat (head) and numGlyphs (maxp).
8. glyf — byte layout →. Needs loca to bracket each glyph.
9. cmap — byte layout →. Independent; the character → glyph map.
10. name — layout →, post — layout →, OS/2 — layout →, kern — layout →. Independent / optional; parse as needed.

Validate as you go. sfntVersion is a known value; head.magicNumber == 0x5F0F3CF5; every offset + length stays within the file; the last loca entry equals the glyf table length. These checks turn corrupt input into clear errors instead of out-of-range reads.

5.2 Fixed- vs variable-layout tables — the decode strategy

How you decode a table depends on its shape:

• Fixed-layout tables have a fixed set of fixed-width fields in a fixed order, no embedded arrays or strings. Size is known in advance; you can decode one in a single positional pass — provided your struct’s field order matches the on-disk order exactly.
• Variable-layout tables contain a count, version, or offset that determines how much follows — arrays sized by another field, strings, sub-tables. Size is not known until you read; these need hand-written, conditional parsing.

* = fixed once you know the version; treat the version word as a branch.

↑ Contents

6. Table reference

The byte layouts the parse sequence in 5.1 links into. Skim only what you need.

↑ Contents

6.1 head — font header (54 bytes, fixed)

The global font header. It contains the design grid size (unitsPerEm), the bounding box that encloses every glyph in the font, creation and modification timestamps, and style flags. The most critical field for parsing is indexToLocFormat: it controls whether the loca table uses 2-byte or 4-byte offsets, so head must be decoded before loca can be read.

↑ Contents

6.2 maxp — maximum profile

Establishes the memory requirements for the font. It records the worst-case counts of points, contours, and interpreter stack depth across all glyphs so the rasterizer can pre-allocate exactly what it needs. The only field you strictly need for parsing is numGlyphs — it sizes the loca and hmtx arrays. Version 0.5 (CFF fonts) carries only that field; version 1.0 (TrueType) carries the full set.

Version 0.5 (0x00005000, CFF fonts — 6 bytes):

Version 1.0 adds (0x00010000, TrueType — 32 bytes total):

↑ Contents

6.3 hhea — horizontal header (36 bytes, fixed)

Contains the metrics needed to lay out glyphs on a horizontal baseline: the ascender, descender, and line gap that renderers use for line spacing, and the maximum advance width. All values are in font design units (FUnits). The key field for parsing is numberOfHMetrics, which tells the hmtx parser how many full (advance width + LSB) pairs the table contains.

↑ Contents

6.4 hmtx — horizontal metrics (variable)

Stores the advance width and left side bearing (LSB) for every glyph. The advance width is how far the cursor moves after drawing the glyph; the LSB is the distance from the glyph’s origin to the left edge of its bounding box. The table has no header — it is two back-to-back arrays whose sizes come from hhea.numberOfHMetrics and maxp.numGlyphs.

Two back-to-back arrays:

1. hMetrics: numberOfHMetrics entries (from hhea), each:

   Type	Name
   uint16	advanceWidth
   int16	lsb (left side bearing)

2. leftSideBearings: numGlyphs − numberOfHMetrics entries of int16.

The trailing array lets monospaced runs share one advance width: glyphs past numberOfHMetrics reuse the last advance width and store only their side bearing.

↑ Contents

6.5 loca — index to location (variable)

Maps each glyph index to the byte offset of its outline data inside the glyf table. Without loca you cannot find where any glyph starts. It stores numGlyphs + 1 offsets — the extra entry marks the end of the last glyph, so each glyph’s length is simply loca[i+1] − loca[i]. The entry width (2 or 4 bytes) is set by head.indexToLocFormat.

numGlyphs + 1 offsets into glyf. The + 1 exists so each glyph’s length is loca[i+1] − loca[i]; the final entry marks the end of the last glyph.

• Short (indexToLocFormat == 0): numGlyphs+1 × Offset16 (uint16). The stored value is the real offset ÷ 2 — multiply by 2 when reading. This works because glyph data is 2-byte aligned (every real offset is even) and it doubles a uint16’s reach to ~128 KB.
• Long (indexToLocFormat == 1): numGlyphs+1 × Offset32 (uint32), the real offset directly.

If loca[i] == loca[i+1], glyph i has no outline (e.g. the space). This is common — handle it.

↑ Contents

6.6 glyf — glyph data (variable, the hard one)

Contains the actual outline data for every glyph — the contours and control points that the rasterizer turns into pixels. It has no table header; it is just glyph blocks packed back to back, located entirely by loca. Each block starts with a common 10-byte header that tells you whether the glyph is simple (contours) or composite (references to other glyphs), followed by format-specific data. This is the most complex table to parse.

No table header. Just glyph blocks back to back, located by loca. Each block starts with a common header:

Simple glyph (numberOfContours ≥ 0)

Total point count = endPtsOfContours[last] + 1. You need it to know how many flags and coordinates to read.

Flag bits (one uint8 per point, logically):

The flag array is compressed: when REPEAT_FLAG (0x08) is set, the following byte gives how many extra points share that flag. Read flags in a loop until you have accumulated pointCount of them, expanding repeats as you go.

Coordinate decoding (x shown; y identical with 0x04/0x20). Coordinates are stored as deltas from the previous point (the first point’s delta is from 0), and all x deltas come first, then all y deltas:

• X_SHORT_VECTOR (0x02) set → x delta is 1 byte (uint8); its sign is given by 0x10: set ⇒ positive, clear ⇒ negative.
• X_SHORT_VECTOR clear:
  • 0x10 set ⇒ delta is 0 (this x equals the previous x).
  • 0x10 clear ⇒ x delta is a 2-byte int16.

Accumulate deltas to get absolute coordinates.

Composite glyph (numberOfContours < 0)

A loop of components, each referencing another glyph:

Component flag bits:

Loop while MORE_COMPONENTS is set.

↑ Contents

6.7 cmap — character-to-glyph mapping (variable)

Maps Unicode character codes (or other encodings) to glyph indices. It is the bridge between text and outlines — without it you cannot know which glyph to draw for a given character. The table contains multiple subtables for different platform/encoding combinations; you pick the best one for your use case (typically the Windows Unicode BMP subtable, format 4) and use only that.

Header:

Then numTables encoding records:

Common pairings: (3,1) Windows BMP Unicode → usually format 4; (3,10) Windows full Unicode → format 12; (0,*) Unicode; (1,0) Mac Roman → format 0. Pick the best subtable, then parse by its format word:

• Format 0 — byte encoding: format, length, language, then uint8 glyphIdArray[256].
• Format 4 — segment mapping (BMP, the workhorse): format, length, language, segCountX2, searchRange, entrySelector, rangeShift, then parallel arrays endCode[segCount], a reserved pad, startCode[segCount], idDelta[segCount], idRangeOffset[segCount], and a trailing glyphIdArray.
• Format 6 — trimmed table: a contiguous range of codes.
• Format 12 — segmented coverage (full Unicode): format(12), reserved, uint32 length, uint32 language, uint32 numGroups, then groups of { uint32 startCharCode; uint32 endCharCode; uint32 startGlyphID }.

↑ Contents

6.8 name — human-readable strings (variable)

Stores all the font’s human-readable text strings: family name, subfamily, full name, version string, copyright notice, trademark, and more. Each string is stored once in a raw byte pool at the end of the table, and a list of records points into that pool with platform, encoding, language, and name ID metadata. For most use cases you want name ID 1 (family), 2 (subfamily), and 4 (full name), platform 3 (Windows), decoded as UTF-16BE.

Then count name records:

(Version 1 adds a langTagCount + language-tag records before the storage.) Then the raw string bytes, encoded per platform — usually UTF-16BE for platform 3.

↑ Contents

6.9 post — PostScript data (variable, version-dependent)

Contains PostScript-specific metadata: the italic angle, whether the font is monospaced (isFixedPitch), and optionally a mapping from glyph index to PostScript glyph name. The 32-byte header is always present; the glyph name array only appears in version 2.0. For most transformation work you only need isFixedPitch and italicAngle.

Fixed 32-byte header:

• 1.0 (0x00010000): header only (standard Mac glyph names assumed).
• 2.0 (0x00020000): header + uint16 numGlyphs + uint16 glyphNameIndex[numGlyphs] + Pascal-string names for indices ≥ 258.
• 2.5: deprecated. 3.0 (0x00030000): header only, no names.

↑ Contents

6.10 OS/2 — OS/2 and Windows metrics (fixed per version)

The primary source of font classification metadata for Windows and cross-platform renderers. It holds the weight class (thin → black), width class (condensed → expanded), typographic ascender/descender/line gap, Windows-specific ascender/descender, Unicode and code-page coverage bitmaps, the PANOSE classification, and embedding permission flags. This is the table that bold and width transformations modify. The version word determines how many trailing fields exist. Zero-pad to the full struct size when reading older versions so missing fields default to 0.

Version 0 (78 bytes, all versions):

Version 1 adds (86 bytes total):

Version 2 / 3 / 4 add (96 bytes total):

Version 5 adds (100 bytes total):

↑ Contents

6.11 kern — kerning (optional, variable)

Stores spacing adjustments between specific pairs of glyphs. Where hmtx gives every glyph a single advance width, kern lets you say “when an ‘A’ is followed by a ‘V’, pull them 40 units closer together.” It is optional — many modern fonts omit it and use GPOS instead for more powerful contextual kerning. When present, it is a sequence of subtables each covering a set of pairs.

Optional and historically messy — Apple and Microsoft define incompatible headers. Many fonts omit kern entirely (modern kerning lives in GPOS). The Microsoft format (the one to target for OpenType-era fonts):

Table header:

Per subtable header:

Coverage flags (low byte): bit 0 = horizontal, bit 1 = minimum, bit 2 = cross-stream, bit 3 = override.

Format 0 (sorted kern pairs — the common case):

Then nPairs entries, each 6 bytes:

Pairs are sorted by (left << 16) | right for binary search. Loop over subtables while there are bytes remaining.

↑ Contents

7. Sources

• Microsoft OpenType specification — the definitive modern reference; it incorporates and supersedes the original TrueType spec: https://learn.microsoft.com/en-us/typography/opentype/spec/
• Apple TrueType Reference Manual — the original format, authoritative for TrueType outlines: https://developer.apple.com/fonts/TrueType-Reference-Manual/
• ISO/IEC 14496-22 “Open Font Format” — the ISO standardization, freely downloadable from ISO; equivalent to the Microsoft spec.

When the two disagree on edge cases, treat the Microsoft spec as canonical for OpenType-era fonts.

Per-table pages, all under https://learn.microsoft.com/en-us/typography/opentype/spec/: