Apple Advanced Typography (AAT) is Apple’s way of shaping text, in tables that sit in
the same directory as the TrueType ones. They turn glyph sequences into other glyph
sequences (morx), kern and attach glyphs (kerx,
ankr), loosen or tighten a line (trak, just) and
describe glyphs (prop, lcar, opbd,
Zapf). macOS fonts carry many of them. The tables here follow Apple’s
TrueType Reference Manual, chapter 6, which also covers how Core Text uses them; all
numbers are big-endian.
Lookup tables
A lookup table maps a glyph to a value; what the value means is up to the table that
uses it. It starts with a uint16 format. Formats 2, 4 and 6
then have a binary search header: unitSize, nUnits,
searchRange, entrySelector and rangeShift (all
uint16). The last three only help a binary search and readers no longer
use them. A search ends at a unit whose glyph is 0xFFFF; that guard unit
may be counted in nUnits or follow it.
| Format | Contents |
|---|---|
| 0 | A simple array of values, one for each glyph of the font, from glyph 0. |
| 2 | Segments of glyphs that share one value. Units are lastGlyph, firstGlyph, value, sorted by lastGlyph; the unit size is 4 plus the size of a value. |
| 4 | Segments whose glyphs each have a value: lastGlyph, firstGlyph and a uint16 offset from the start of the lookup table to an array of one value for each glyph of the segment. |
| 6 | A sorted list of glyph, value pairs; the unit size is 2 plus the size of a value. |
| 8 | A trimmed array: firstGlyph and glyphCount (uint16), then a uint16 value for each glyph. |
| 10 | A trimmed array of values of 1, 2, 4 or 8 bytes: unitSize, firstGlyph, glyphCount, then the values. |
The viewer reads all six formats and shows each lookup as a tree and, for most tables, as a paged list of glyphs and values. It reports a format that is not one of these, a lookup that is cut off, a unit size too small for its format, an array that lies outside its table, and (as notes, since real fonts have them) segments that are out of order, overlap or have their two glyphs the wrong way round, and glyph numbers above the glyph count.
State tables
A state table is a finite state machine that runs over the glyph array. Each glyph has a class; the machine’s state and the class pick an entry, and the entry gives the new state, flags (the first two, at the top, say whether to move on to the next glyph) and, depending on the table, more words. Classes 0 to 3 are fixed: 0 end of text, 1 out of bounds (every glyph the class table does not cover), 2 deleted glyph and 3 end of line. Class 0 and 3 are fed to the machine after the last glyph; they, and 2, are not given by the class table. State 0 is the start of text and state 1 the start of a line.
The extended form (morx, kerx, just in newer
fonts) has an STXHeader of four uint32:
nClasses and the offsets of the class table, the state array and the
entry table, all from the start of the header. The class table is a lookup table of
uint16 classes. The state array is rows of nClasses
uint16 entry indices, and each entry is a uint16 new state
(an index), uint16 flags and the table’s own words. The original form
(mort, kern format 1, the justification category table) has a
StateHeader of four uint16: stateSize (the
classes, one byte each in a state), and offsets to a class table (firstGlyph,
nGlyphs and a class byte for each glyph), a state array of entry index bytes
and an entry table whose new state is a byte offset to a row.
Neither form says how many states or entries there are. The viewer finds them by
following the rows to the entries they use and the entries to the states they go to,
until nothing new turns up; a row or entry that lies outside the subtable is reported.
It also reports a class table that gives a class of nClasses or more,
fewer than 4 classes, an entry whose new state is not the offset of a row, and the
table-specific rules below; a class table that gives class 0, 2 or 3 is a note.
feat: feature names
The text features of the font and their settings, with name table
indices for the names a menu shows. morx and kerx turn
features on through their own feature tables, which use the same type and setting
numbers.
| Type | Name | Description |
|---|---|---|
Fixed | version | 0x00010000. |
uint16 | featureNameCount | The number of features. |
uint16, uint32 | reserved | 0. |
record × featureNameCount | names | 12 bytes each, sorted by feature type: feature (uint16), nSettings (uint16), settingTable (uint32, from the start of the table), featureFlags (uint16) and nameIndex (int16, above 255 and below 32768). |
featureFlags: 0x8000 the settings are exclusive (one at a
time); 0x4000 with it, the low byte is the index of the default setting, else
the first is the default; 0x3F00 unused. A setting array is
nSettings pairs of setting and nameIndex, sorted by
setting. A feature that is not exclusive has an even “on” setting followed by an odd
“off” one and lists only the on setting. Feature type 39 (language) is always exclusive,
and its selectors are one more than an index in the ltag
table.
morx: extended glyph metamorphosis
Substitutions, ligatures, reordering and insertions, run as state machines over the
glyph array. Header: uint16 version (2, or 3 with glyph
coverage arrays), uint16 0, uint32 nChains. A
chain has defaultFlags, chainLength (a multiple of
4), nFeatureEntries and nSubtables (all uint32),
then the feature table: 12-byte entries of featureType,
featureSetting, enableFlags and disableFlags. The
flags start from defaultFlags; for each requested feature setting, in
table order, they are ANDed with the disable flags and ORed with the enable flags. A
subtable runs when its subFeatureFlags share a bit with the result. The
last entry of the feature table turns off “all typographic features”.
A subtable has length, coverage and
subFeatureFlags (uint32 each). Coverage:
0x80000000 vertical text only, 0x40000000 process the glyphs
last to first, 0x20000000 horizontal and vertical, 0x10000000
logical order, the low byte the type.
| Type | Subtable | Entry words after the new state and the flags |
|---|---|---|
| 0 | Indic rearrangement. Flags: 0x8000 mark first, 0x4000 do not advance, 0x2000 mark last, the low 4 bits a verb that moves the glyphs from the marked first to the marked last, for example 3 is AxD ⇒ DxA, 15 is ABxCD ⇒ DCxBA. | none |
| 1 | Contextual substitution. A uint32 after the header gives the offset of an array of uint32 offsets, from the start of that array, to lookup tables (a value 0 means no change). Flags: 0x8000 set mark, 0x4000 do not advance. | markIndex, currentIndex: a substitution lookup for the marked and for the current glyph (0xFFFF none). |
| 2 | Ligature. Three uint32 offsets after the header: the ligature actions, the component table and the ligature list. Flags: 0x8000 push the glyph as a component, 0x4000 do not advance, 0x2000 perform the action. | ligActionIndex. An action: 0x80000000 last (and store), 0x40000000 store, the low 30 bits a signed offset added to the popped glyph to index the component table; the components are added to index the ligature list. |
| 4 | Noncontextual substitution: just a lookup table from a glyph to its replacement (0 for none). | none (no state table) |
| 5 | Insertion. A uint32 after the header gives the offset of the list of glyphs to insert. Flags: 0x8000 set mark, 0x4000 do not advance, 0x2000 and 0x1000 the current or marked insertion is kashida-like (else split-vowel-like), 0x0800 and 0x0400 insert before it (else after), 0x03E0 the number of glyphs to insert at the current glyph, 0x001F at the marked one. | currentInsertIndex, markedInsertIndex: where in the list (0xFFFF none). |
In version 3 the chain ends with a glyph coverage array: an offset (0 for none) for each subtable to a bit field of one bit for each glyph, padded to 4 bytes, which says which glyphs the subtable can change, so a run of text with none of them skips it.
The viewer shows each chain, feature entry (named from feat when it can),
subtable, class table, state array, entry (with its flags told in words), ligature
action, component and ligature, insertion glyph and substitution lookup, and lists them
in paged tables. It reports a version other than 2 or 3, a chain or subtable that
runs past its table or whose length is smaller than its header, a subtable of the
reserved type 3 or an undefined one, class tables, states and entries that lie outside
the subtable, a ligature action list that does not reach an action with its last bit
before the table ends, an insertion that names glyphs outside the subtable, and
substitution lookups that cannot be read. A subtable length that is not a multiple of 4
is not reported (the morx chapter does not ask for it and most fonts do it);
neither is a feature table that does not end with the “all features off” entry, which five
system fonts do not have; that is a note.
mort: glyph metamorphosis (legacy)
The earlier form of morx, still found in older fonts. Fixed
version 0x00010000, uint32 nChains; a chain
has uint32 defaultFlags and chainLength, then
uint16 nFeatureEntries and nSubtables; the feature
table is the same. A subtable has uint16 length and
coverage (0x8000 vertical, 0x4000 descending,
0x2000 both, the low 3 bits the type) and a uint32
subFeatureFlags; its lengths are multiples of 4. The state tables use the
original StateHeader. Contextual entries give word offsets to glyph arrays;
a ligature entry’s flags carry the offset of its action list; an insertion entry gives byte
offsets to the lists of glyphs. The viewer decodes the structure and the state machines and
labels the table as legacy; the glyph arrays and ligature lists of the original form are
shown as bytes. No font on this Mac has one, so that part is checked against the manual
only.
kerx: extended kerning
Header: uint16 version (2, 3 or 4), uint16 0,
uint32 nTables. Each subtable has length,
coverage and tupleCount (uint32); coverage
0x80000000 vertical, 0x40000000 cross-stream,
0x20000000 variation, 0x10000000 process last to first (only for
the state tables), the low byte the format. Adjustments of subtables add up. From
version 3 a glyph coverage array follows (offsets, 0xFFFFFFFF for none, for
the state-table formats); from version 4 a tupleCount above 0 makes the
values vectors for the global tuples of gvar in a variable font.
| Format | Subtable |
|---|---|
| 0 | Sorted pairs: four uint32 (nPairs and the search fields), then 6-byte left, right, value records ordered by left × 65536 + right; a final 0xFFFF, 0xFFFF pair may end it. |
| 1 | Contextual kerning of up to 8 glyphs. An STXHeader and a uint32 offset to the value array. Entry flags: 0x8000 push the glyph on the kerning stack, 0x4000 do not advance, 0x2000 reset the stack; the entry word is an index into the values; each value pops a glyph and kerns it; an odd value ends the list. |
| 2 | An offset-based class array: rowWidth, and offsets from the start of the subtable to a left-hand and a right-hand class lookup and to the array (all uint32). A left class is a row number times rowWidth, a right class a column number times 2; the value is the int16 at array + left + right. Row and column 0 are zeros. |
| 4 | Control point and anchor point positioning. An STXHeader and uint32 flags: the top two bits the action type, the low 24 the offset to the actions. Entry flags: 0x8000 mark, 0x4000 do not advance. An action gives, for the marked and the current glyph, a control point (type 0), an anchor point from ankr (type 1), or an x and y (type 2, int16 each); the glyph is moved so that the two meet. |
| 6 | An index-based class array: flags (bit 0: values are 4 bytes), rowCount and columnCount (uint16), then offsets to a row lookup (values premultiplied by columnCount), a column lookup, the array of values and, with tuples, the vectors. |
Formats 3, 5 and 7 and above are reserved. The viewer shows every format’s pairs, class tables, state machines, value lists, actions and arrays, and reports a version other than 2 to 4, a subtable that runs past the table, a reserved format, a pair count that does not fit, class values that do not lead to a row or column inside the array, and the state table problems above. A subtable that has the process-direction flag set but is not a state table is a note.
kern format 1: the state table
In Apple’s form of kern (Fixed version
0x00010000, uint32 subtable count, 8-byte subtable headers of
uint32 length, uint16 coverage and
uint16 tupleIndex) format 1 is contextual kerning with an
original-form StateHeader and a uint16 offset to the kerning values.
Entry flags: 0x8000 push, 0x4000 do not advance, the low 14 bits a
byte offset, from the start of the subtable, to a list of int16 values, each
popping a glyph from the kerning stack; the list ends at an odd value. Formats 0, 2 and 3
are as on the kern page. The
viewer decodes the state table and the lists, and reports a list that never ends.
just: justification
Fixed version 0x00010000, uint16
format 0, and horizOffset and vertOffset
(uint16, from the start of the table, 0 for none) to a
JustificationHeader: justClassTableOffset (a state table, with an
8-byte metamorphosis subtable header before its header, that gives a glyph a justification
category of 7 bits from its context; entry flags 0x8000 set mark,
0x4000 do not advance, 0x3F80 the marked glyph’s category,
0x007F the current one), wdcTableOffset and
pcTableOffset (from the start of the table, 0 for none), followed by a lookup
table from a glyph to a width delta cluster. A cluster’s offset, from the start of the
width delta clusters, is a multiple of 4. A cluster is a uint32 count and that
many 24-byte pairs: a uint32 category, four Fixed limits (before
grow, before shrink, after grow, after shrink, in ems of a one-point glyph) and two
uint16 flags, for growing and shrinking: 0x1000 the glyph takes
unlimited gap, the low 4 bits the priority (0 kashida, 1 whitespace, 2 inter-character, 3
null).
The postcompensation subtable is a lookup (a value 0 for no action) and, for each
action, a uint32 count of sub-records: category, type, length (uint16,
uint16, uint32) and the data: type 0 decompose a ligature (lower and
upper limit Fixed, order, count and glyphs), 1 add a glyph, 2 add a glyph and
substitute above a threshold, 3 stretch, 4 ductile (a variation axis and three
Fixed), 5 repeat a glyph. Some system fonts count the padding of a sub-record
outside its length; the viewer notes it.
trak: tracking
An adjustment of the space between glyphs for a size and a track number (−1 loose, 0
normal, +1 tight by convention). Fixed version
0x00010000, uint16 format 0, horizOffset
and vertOffset (uint16, 0 for none, a multiple of 4), a reserved
uint16. A TrackData has nTracks,
nSizes (uint16), sizeTableOffset (uint32
from the start of the table), the track records sorted by track (a Fixed track,
a uint16 nameIndex above 255 and below 32768, and a
uint16 offset of the track’s values), the Fixed point sizes and,
for each track, one int16 in font units for each size. The value, as a fraction of
the em, times the point size is added to every advance; sizes between and outside the
listed ones are interpolated and extrapolated.
ankr: anchor points
Points in a glyph’s space that kerx format 4 aligns. uint16
version 0, uint16 flags 0, uint32
lookupTableOffset (always 12) and glyphDataTableOffset. The lookup
table gives a glyph a uint16 offset from the glyph data table to its data: a
uint32 number of points and, for each, an int16 x and y. A glyph
without anchor points is not in the lookup.
opbd: optical bounds
How far to shift a glyph at the edge of a line so that its optical edge is flush.
Fixed version 0x00010000, uint16
format (0 distances in font units, 1 control point numbers), then a
lookup table whose values are uint16 offsets from the start of the table to four
int16: left, top, right and bottom. Negative distances move left or down; a control
point of −1 means the edge has none.
lcar: ligature carets
Where to put the text cursor inside a ligature. The header is that of
opbd; a lookup value is an offset from the start of the table to a
uint16 count and that many int16 division points (font units
along the baseline from x = 0, or control point numbers in format 1), one fewer than the
characters of the ligature.
prop: glyph properties
Fixed version (1.0, 2.0, which adds “attaches on right”, or 3.0, which
adds the Unicode 3.0 directions), uint16 format (0 no lookup, 1
lookup), uint16 default properties and a lookup table of uint16
properties. Bits: 0x8000 a floating mark (its advance must be zero),
0x4000 hangs off the left or top edge of a line, 0x2000 off the right
or bottom, 0x1000 a bracket whose partner is used when the text runs right to
left, 0x0F00 a signed offset from this glyph to the partner, 0x0080
attaches to the glyph on its right (version 2.0 on), 0x0060 zero,
0x001F the directionality: 0 left to right, 1 right to left, 2 Arabic letter, 3
European number, 4 European number separator, 5 European number terminator, 6 Arabic number,
7 common separator, 8 block separator, 9 segment separator, 10 whitespace, 11 other neutral;
12 to 31 are Unicode 3.0. The viewer reports the zero bits that are set, the 2.0 bit in a 1.0
table and a 3.0 direction in an older one, and notes a floating mark that has an advance.
bsln: baselines
Fixed version 0x00010000, uint16
format and uint16 defaultBaseline (0 to 31: 0 Roman, 1
ideographic centred, 2 ideographic low, 3 hanging, 4 math). Formats 0 and 1 then have 32
int16 distances in font units from the glyphs’ natural baseline; formats 2 and 3
have a standard glyph and 32 uint16 control point numbers (0xFFFF for
none) of that glyph. Formats 1 and 3 end with a lookup table of the baseline of each glyph (0
to 31); other glyphs use the default.
fdsc: font descriptors
Fixed version 0x00010000, uint32 count,
then 8-byte pairs of a tag and a Fixed value, so that a program can find a
similar font: wght weight (1.0 regular), wdth width (1.0 regular),
slnt slant in degrees, opsz the point size designed for,
nalf non-alphabetic, an integer (0 alphabetic, 1 dingbats, 2 pi characters, 3
fleurons, 4 decorative borders, 5 international symbols, 6 math symbols). Other tags may be
registered with Apple.
fmtx: font metrics
Fixed version 0x00020000, a uint32 glyph
index and eight uint8 point numbers of that glyph: horizontal before (ascent),
after (descent), caret head, caret base, and the same four for vertical text. They replace
the hhea and vhea values, and move with variation and hinting. A
horizontal caret base has y = 0, a vertical one x = 0.
gcid: glyph to CID
uint16 version 0, uint16 format 0,
uint32 size of the table, uint16 registry ID and a 64-byte
registry name, uint16 order ID and a 64-byte order name, a supplement version, a
count (not above the glyph count) and one uint16 CID for each glyph, 0xFFFF
for none: for example Adobe-CNS1-4 is registry 0 “Adobe”, order 2 “CNS1”, supplement 4. No
font on this Mac has one; the viewer is checked against the manual and a made-up font.
xref: cross-reference
Names that Apple’s tools keep for the classes, states, entries and actions of
just, kerx and morx; it should be removed from shipping
fonts. uint32 version 1, flags 0, numEntries and
stringOffset, then 16-byte entries: a tag, chainIndex,
subtableIndex, tableType (0 class, 1 state, 2 entry, 3 action, 4 column
class, 5 row class) and tableIndex (int16, −1 for any), a
uint16 string offset and length into the UTF-8 string data.
Zapf: glyph reference
Per-glyph information for tools: the text a glyph stands for, identifiers, the features that
give it and the groups it belongs to. Version 2: uint16 version,
uint16 0, uint32 extraInfo (an offset), then a lookup table of
uint32 offsets to GlyphInfo records (version 1 has an array of offsets
instead, and a 16-bit text length). A GlyphInfo is uint32
groupOffset and featOffset (from extraInfo,
0xFFFFFFFF for none), uint8 flags (0x80 the canonical glyph
for its text), uint8 count and the UTF-16 text, a uint16 count and
identifiers (a kind byte, then a Pascal string for kinds 0 to 63: PostScript, Adobe and
AFII names, a character name; or two bytes for 64 to 127: CIDs, name table indices of notes), padded
to 4 bytes. A group is a uint16 count (bit 15: each subgroup has a flag word; bit 14
set: an array of group offsets, the first for the alternate forms of the glyph) and subgroups of
a name index and glyph list; a FeatureInfo is a context bit field (line and word
initial, medial and final, fraction parts), type and selector pairs and, in version 2,
OpenType feature tags.
ltag: language tags
uint32 version 1, flags 0, numTags, then
uint16 offset and length (from the start of the table) of each IETF language tag,
in ASCII. The index of a tag is the language code that Unicode-platform name
strings use, and, plus one, the selector of feat type 39.
Sources
Apple, TrueType Reference
Manual: Apple Advanced Typography Font Tables (lookup and state tables) and the chapters of
feat, morx, mort, kerx, kern,
just, trak, ankr, opbd, lcar,
prop, bsln, fdsc, fmtx, gcid,
xref, Zapf and ltag. Where the fonts on a Mac, which the
viewer reads, differ from the manual, the page follows the fonts: the class values of
kerx format 2 count from the start of the array, a justification sub-record’s length may leave out
its padding, and a version 1 Zapf table’s FeatureInfo has no OpenType tags.