.TTF File Format – Table directory

Data types

The names the OpenType specification uses, and that the pages for each table use too.

Table directory

The directory starts at byte 0 of a .ttf file. In a font collection each font has its own directory, wherever the collection header says.

The three search fields once sped up a binary search of the records. They can always be worked out from numTables, and the specification recommends that readers do so rather than trust them, since wrong values have been used to attack font parsers. Writers should still fill them in correctly.

Table record

• Records are sorted by tag in ascending order, comparing the bytes as unsigned numbers, so upper-case tags (OS/2) sort before lower-case ones (cmap).
• A font should have at most one table with any given tag; with two, what happens is up to the software.
• Every table starts on a four-byte boundary, and the gaps are filled with zeros. Only top-level tables are aligned this way, not the subtables inside them.
• Tables can be in any order in the file, and there is no fixed number of them.
• Apple reserves tags made only of lower-case letters for its own tables; anyone else defining a table should register its tag.

Checksums

A table’s checksum is the sum of its bytes taken as big-endian uint32 words, ignoring overflow. A table whose length is not a multiple of 4 is summed as if it were padded with zero bytes. In C, from the specification:

uint32 CalcTableChecksum(uint32 *Table, uint32 Length)
{
    uint32 Sum = 0L;
    uint32 *EndPtr = Table + ((Length + 3) & ~3) / sizeof(uint32);
    while (Table < EndPtr)
        Sum += *Table++;
    return Sum;
}

The head table holds a second check, checksumAdjustment, for the whole file. A font maker computes it last:

1. Set checksumAdjustment to 0.
2. Compute the checksum of every table, head included, and write each into its table record.
3. Compute the checksum of the whole file, as if it were one table.
4. Subtract that from 0xB1B0AFBA and store the result in checksumAdjustment.

Writing checksumAdjustment changes the head table, so to check head against its record a reader takes checksumAdjustment as 0. Once checksumAdjustment is in place, the checksum of the whole file is 0xB1B0AFBA. In a collection, checksumAdjustment is not used and may be 0.

For example, the 8-byte gasp table 00 01 00 01 FF FF 00 0F is two words, 0x00010001 + 0xFFFF000F = 0x100000010; dropping the overflow leaves the checksum 0x00000010.

Tables

OpenType groups the tables it defines as follows. A TrueType font must have the required tables and glyf and loca; the rest are optional. The tables a TrueType font cannot use, because they belong to CFF outlines, are CFF , CFF2 and VORG.

The tables that TrueType and OpenType fonts share beyond those on these TTF pages are documented on the OTF pages: vhea, vmtx and VORG; the bitmap tables (EBDT, EBLC, EBSC, CBDT, CBLC, sbix); COLR, CPAL and SVG ; the layout tables GDEF, GSUB, GPOS, BASE and JSTF and MATH, built on the layout common tables; the variation tables fvar, avar and STAT and gvar, cvar, HVAR, VVAR and MVAR; and DSIG and PCLT, meta and MERG.

Apple’s TrueType Reference Manual defines further tables that macOS and iOS use, not part of OpenType: acnt, ankr, bdat, bhed, bloc, bsln, fdsc, feat, fmtx, fond, gcid, hvgl, hvpm, just, kerx, lcar, ltag, mort, morx, opbd, prop, trak, xref and Zapf. Its avar, cvar, fvar, gvar, kern and meta tables share their tags with OpenType’s, but Apple’s versions of some of them differ in detail.

Example

The start of KaTeX’s Size2 Regular font, an 11,508-byte TrueType font with 14 tables: the 12-byte header and the first table record.

00000000  00 01 00 00 00 0E 00 80  00 03 00 60 4F 53 2F 32   ...........`OS/2
00000010  45 61 95 F5 00 00 17 6C  00 00 00 60               Ea.....l...`

sfntVersion is 0x00010000, TrueType; 14 tables; the largest power of 2 not above 14 is 8, so searchRange is 128, entrySelector 3 and rangeShift 224 − 128 = 96. All 14 records, in their sorted order:

The first table, glyf, starts at 236, straight after the 12 + 14 × 16 bytes of the directory. Its length, 5,390, is not a multiple of 4, so two zero bytes follow it and maxp starts at 5,628. The last table, gasp, ends at 11,508, the end of the file. The cvt  table is 14 zero bytes, hence its checksum of 0.