The cmap table maps character codes to glyph IDs. It holds one or more
subtables, each for one character encoding, and a list saying which encoding each
subtable is for. A code with no glyph maps to glyph 0, which must be the
.notdef glyph shown for missing characters. For a new font, OpenType
recommends a format 4 subtable for Unicode characters up to U+FFFF or a format 12
subtable for the full range, plus format 14 for variation sequences if needed.
Header and encoding records
| Offset | Type | Name | Description |
|---|---|---|---|
0 | uint16 | version | 0, even in fonts that use the newer subtable formats. |
2 | uint16 | numTables | The number of encoding records. |
4 | record × numTables | encodingRecords | 8 bytes each: platformID (uint16), encodingID (uint16) and subtableOffset (Offset32, from the start of cmap). |
- Records are sorted by platform ID, then encoding ID, then the language field of the subtable. Each combination may appear only once.
- Several records may point to the same subtable.
- Software picks one subtable and ignores the rest, except that a format 14 subtable (platform 0, encoding 5) adds to whichever Unicode subtable is used.
- If a font has both a 16-bit Unicode subtable (format 4) and a 32-bit one (format 10 or 12), the 32-bit one should cover everything the 16-bit one does, and software should use it. A font should not have both format 4 and format 6 for Unicode, nor both format 10 and format 12; use 4 and 12.
Platform IDs
| ID | Platform | Encoding IDs |
|---|---|---|
| 0 | Unicode | Unicode encodings |
| 1 | Macintosh | Script Manager codes, listed on the name page. Required by older Mac OS; discouraged now. |
| 2 | ISO (deprecated) | 0 7-bit ASCII, 1 ISO 10646, 2 ISO 8859-1 |
| 3 | Windows | Windows encodings |
| 4 | Custom | 0 to 255: the Windows character set of the Type 1 font the font was converted from. Legacy; not for new fonts. |
| 240 to 255 | User-defined | Never assigned to a registered platform. |
Unicode platform (0)
| Encoding ID | Meaning | Used with |
|---|---|---|
| 0 | Unicode 1.0 semantics (deprecated) | – |
| 1 | Unicode 1.1 semantics (deprecated) | – |
| 2 | ISO/IEC 10646 semantics (deprecated) | – |
| 3 | Unicode 2.0 and later, Basic Multilingual Plane only | formats 4 and 6 |
| 4 | Unicode 2.0 and later, full repertoire | formats 10 and 12 |
| 5 | Unicode variation sequences | format 14 only, and format 14 only here |
| 6 | Unicode full repertoire, many-to-one | format 13 only, and format 13 only here |
Windows platform (3)
| Encoding ID | Meaning |
|---|---|
| 0 | Symbol: a format 4 subtable with up to 224 symbols, usually at codes from 0xF020 in the Private Use Area. Legacy software maps byte 0x20 to the font’s first character. |
| 1 | Unicode BMP: must use format 4, and only for characters up to U+FFFF. |
| 2 | Shift JIS (Japanese) |
| 3 | PRC (Simplified Chinese) |
| 4 | Big5 (Traditional Chinese) |
| 5 | Wansung (Korean) |
| 6 | Johab (Korean) |
| 7 to 9 | Reserved |
| 10 | Unicode full repertoire: must use format 12, for fonts with characters above U+FFFF. |
The language field
Every subtable has a language field. It must be 0 except under the
Macintosh platform, where it is the Macintosh
language ID plus 1 for a
language-specific subtable, or 0 otherwise. A Mac OS Turkish subtable has 18 (Turkish
is 17); a Mac OS Roman subtable has 0.
Subtable formats
Every subtable starts with its format number. Formats 0 to 6 have 16-bit
length and language fields; formats 8 to 13 have a reserved
uint16 and then 32-bit ones. Format 14 has no language field.
| Format | Name | Codes | Use today |
|---|---|---|---|
| 0 | Byte encoding table | 8-bit | Old Mac fonts |
| 2 | High byte mapping through table | mixed 8 and 16-bit | Old Chinese, Japanese and Korean fonts |
| 4 | Segment mapping to delta values | 16-bit | Standard for the BMP |
| 6 | Trimmed table mapping | 16-bit | Rare |
| 8 | Mixed 16-bit and 32-bit coverage | mixed 16 and 32-bit | Discouraged |
| 10 | Trimmed array | 32-bit | Rare; not supported on Windows |
| 12 | Segmented coverage | 32-bit | Standard for the full Unicode range |
| 13 | Many-to-one range mappings | 32-bit | Last-resort fonts |
| 14 | Unicode variation sequences | base character and selector | Alongside 4 or 12 |
Format 0: byte encoding table
| Type | Name | Description |
|---|---|---|
uint16 | format | 0 |
uint16 | length | The subtable’s length in bytes: 262. |
uint16 | language | See language. |
uint8 × 256 | glyphIdArray | The glyph for each code 0 to 255. Only glyphs 0 to 255 can be reached. |
Format 2: high byte mapping through table
For double-byte encodings such as Shift JIS, where some byte values start a two-byte character. The first byte selects a subheader; subheader 0 is for single-byte characters.
| Type | Name | Description |
|---|---|---|
uint16 | format | 2 |
uint16 | length | The subtable’s length in bytes. |
uint16 | language | See language. |
uint16 × 256 | subHeaderKeys | For each possible high byte, the index of its subheader times 8. A key of 0 means the byte is a single-byte character, looked up through subheader 0. |
SubHeader[ ] | subHeaders | 8-byte records, see below. |
uint16[ ] | glyphIdArray | The sub-arrays the subheaders point into. |
| Type | Name | Description |
|---|---|---|
uint16 | firstCode | The first valid low byte. |
uint16 | entryCount | How many low bytes are valid from firstCode; others map to glyph 0. |
int16 | idDelta | Added to a non-zero value from the sub-array, modulo 65,536, to give the glyph. |
uint16 | idRangeOffset | The number of bytes from this field to the glyphIdArray entry for firstCode. |
Format 4: segment mapping to delta values
The usual subtable for Unicode up to U+FFFF. Codes are grouped into segments of consecutive codes, held in four parallel arrays.
| Type | Name | Description |
|---|---|---|
uint16 | format | 4 |
uint16 | length | The subtable’s length in bytes. |
uint16 | language | See language. |
uint16 | segCountX2 | 2 × segCount, the number of segments. |
uint16 | searchRange | 2 × the largest power of 2 not above segCount. |
uint16 | entrySelector | floor(log2(segCount)). |
uint16 | rangeShift | 2 × segCount − searchRange. |
uint16 × segCount | endCode | The last code of each segment, in increasing order. The last is 0xFFFF. |
uint16 | reservedPad | 0. |
uint16 × segCount | startCode | The first code of each segment. The last segment must start and end at 0xFFFF, so a search always ends. |
int16 × segCount | idDelta | Added to the code (or to the value from glyphIdArray), modulo 65,536. |
uint16 × segCount | idRangeOffset | 0, or the offset into glyphIdArray, see below. |
uint16[ ] | glyphIdArray | Glyph IDs, as many as the segments need. |
To map a code c, find the first segment i whose
endCode is ≥ c. If its startCode is above
c, the code has no glyph (0). Otherwise:
- If
idRangeOffset[i]is 0, the glyph is (c +idDelta[i]) modulo 65,536. - If not, read the
uint16at the address ofidRangeOffset[i]+idRangeOffset[i]+ 2 × (c −startCode[i]), which lands inglyphIdArraybecause it follows theidRangeOffsetarray directly. In C,*(idRangeOffset[i]/2 + (c - startCode[i]) + &idRangeOffset[i]). If that value is 0 the code has no glyph; otherwise addidDelta[i], modulo 65,536.
The three search fields can be worked out from segCountX2, and readers
should not rely on them. With 39 segments they are 64, 5 and 14.
Format 6: trimmed table mapping
| Type | Name | Description |
|---|---|---|
uint16 | format | 6 |
uint16 | length | The subtable’s length in bytes. |
uint16 | language | See language. |
uint16 | firstCode | The first code in the range. |
uint16 | entryCount | The number of codes in the range. |
uint16 × entryCount | glyphIdArray | The glyph for each code from firstCode; codes outside the range map to 0. |
Format 8: mixed 16-bit and 32-bit coverage
Meant for UTF-16 text, where a 16-bit unit is either a whole character or the first half of a 32-bit one. It assumes no 32-bit code shares its first 16 bits with a 16-bit code. Rarely supported; discouraged.
| Type | Name | Description |
|---|---|---|
uint16 | format | 8 |
uint16 | reserved | 0 |
uint32 | length | The subtable’s length in bytes, header included. |
uint32 | language | See language. |
uint8 × 8192 | is32 | One bit per 16-bit value: set if it starts a 32-bit code. Value v is bit 1 << (7 − v % 8) of byte v / 8. |
uint32 | numGroups | The number of groups. |
SequentialMapGroup × numGroups | groups | As in format 12; a group of 16-bit codes has 0 in the top 16 bits of its codes. |
A font must not have both a glyph for U+0000 and glyphs for 32-bit codes whose high 16 bits are 0.
Format 10: trimmed array
| Type | Name | Description |
|---|---|---|
uint16 | format | 10 |
uint16 | reserved | 0 |
uint32 | length | The subtable’s length in bytes, header included. |
uint32 | language | See language. |
uint32 | startCharCode | The first code covered. |
uint32 | numChars | The number of codes covered. |
uint16[ ] | glyphIdArray | The glyph for each code. |
Format 12: segmented coverage
The usual subtable for Unicode characters above U+FFFF. A font with format 12 may also have format 4 for older software.
| Type | Name | Description |
|---|---|---|
uint16 | format | 12 |
uint16 | reserved | 0 |
uint32 | length | The subtable’s length in bytes, header included. |
uint32 | language | See language. |
uint32 | numGroups | The number of groups. |
SequentialMapGroup × numGroups | groups | 12 bytes each: startCharCode, endCharCode and startGlyphID, all uint32. Code c in the group maps to startGlyphID + (c − startCharCode). |
Groups are sorted by startCharCode, and each group ends before the
next one starts.
Format 13: many-to-one range mappings
The same layout as format 12, but every code in a group maps to the same glyph, its
glyphID. Made for last-resort fonts, which show one symbol for a whole
block of characters (see bit 14 of the head flags). Only under platform
0, encoding 6.
Format 14: Unicode variation sequences
A variation sequence is a base character followed by a variation selector, such as U+82A6 U+E0101, asking for a particular form of the character. A default sequence uses the glyph the main Unicode subtable gives the base character; a non-default one uses a glyph given here. Only under platform 0, encoding 5.
| Type | Name | Description |
|---|---|---|
uint16 | format | 14 |
uint32 | length | The subtable’s length in bytes. |
uint32 | numVarSelectorRecords | The number of variation selector records. |
record × numVarSelectorRecords | varSelector | 11 bytes each: varSelector (uint24, the selector), defaultUVSOffset and nonDefaultUVSOffset (Offset32, from the start of the subtable; 0 if absent). Sorted by selector, no repeats. |
A default UVS table is a uint32 count,
numUnicodeValueRanges, then 4-byte ranges: startUnicodeValue
(uint24) and additionalCount (uint8, how many
more values follow it, 0 for one value). U+4E4D to U+4E4F is
00 4E 4D 02. Ranges are sorted and do not overlap.
A non-default UVS table is a uint32 count,
numUVSMappings, then 5-byte mappings: unicodeValue
(uint24, the base character) and glyphID
(uint16). Sorted by base character, no repeats.
Example
The cmap of KaTeX’s Size2 Regular font, 196 bytes. Two encoding records,
Unicode BMP (0, 3) and Windows Unicode BMP (3, 1), both point to one format 4 subtable
at offset 20:
00000000 00 00 00 02 00 00 00 03 00 00 00 14 00 03 00 01
00000010 00 00 00 14 00 04 00 B0 00 00 00 28 00 20 00 04
00000020 00 08 00 20 00 29 00 2F ...The subtable has format 4, length 176, language 0, and segCountX2 40:
20 segments, so searchRange 32, entrySelector 4 and
rangeShift 8. Every idRangeOffset is 0, so each glyph is the
code plus the segment’s idDelta:
| Segment | startCode | endCode | idDelta | Mapping |
|---|---|---|---|---|
| 0 | 0020 | 0020 | −29 (FFE3) | space → glyph 3 |
| 1 | 0028 | 0029 | −36 | ( → 4, ) → 5 |
| 3 | 005B | 005D | −84 | [ → 7, \ → 8, ] → 9 |
| 10 | 220F | 2211 | −8,702 (DE02) | ∏ U+220F → 17, ∐ → 18, ∑ U+2211 → 19 |
| 19 | FFFF | FFFF | 1 | U+FFFF → (65,535 + 1) mod 65,536 = 0, the missing glyph |
A code such as U+0041 (A) falls in segment 3, whose endCode is the first
≥ 0x41, but whose startCode 0x5B is above it, so it maps to glyph 0: this
font has no letters.