.WOFF2 File Format – Transformed glyf and loca

Header

The transformed table starts with a 36-byte header. All values are big-endian.

Streams

The streams follow the header in this order, each straight after the one before. Each is read from its start as the glyphs are decoded, glyph 0 first.

Decoding a glyph

For each glyph in turn, read its contour count from nContourStream.

Triplet codes

Bits 0 to 6 of a point’s flag, 0 to 127, choose how its x and y changes are packed in the glyph stream: how many bytes they take, how many bits each coordinate has, a fixed amount added to each, and the signs. Small moves along one axis take one byte, small moves on both axes take one byte split into two four-bit halves, and the largest take four bytes. The specification calls the flag and its coordinate bytes a triplet, and gives a table of all 128 codes; this is the same table with each group of codes on one row.

Bytes is the number of bytes read from the glyph stream (the specification’s byte count also counts the flag, which is in the flag stream). X and Y give each coordinate’s bits and the amount added to them. Signs is the order of signs within the group: within each group of two codes, the second is positive; within each group of four, the codes run (x −, y −), (x +, y −), (x −, y +), (x +, y +).

So a code’s x change is positive when the code is odd, and for codes 20 and up its y change is positive when bit 1 of the code is set; for codes 0 to 9 the y change is positive when the code is odd. Where four-bit or twelve-bit values share a byte, the x value comes first, in the high bits. As formulas, with c the code and b0, b1… the bytes read, before the sign is applied (this is how Google’s reference decoder writes them; they give exactly the table above):

For example, flag 0F followed by the byte 20 is an on-curve point (bit 7 clear) with code 15: x changes by +(512 + 32) = +544, y by 0. Flag A9 is an off-curve point with code 41 (x +, y −, both with 17 added); with the byte 3C it moves x by +(17 + 3) = +20 and y by −(17 + 12) = −29.

Overlap bitmap

TrueType’s simple glyph flags have a bit, OVERLAP_SIMPLE (bit 6 of the first flag of a glyph), that says the glyph’s contours overlap. The triplet flags do not carry it, so it has its own bitmap. An encoder includes the bitmap, and sets bit 0 of optionFlags, only when some simple glyph has the bit set; it then holds one bit per glyph. A decoder sets bit 6 of each simple glyph’s first flag from the bitmap, or leaves it clear everywhere when there is no bitmap. The bitmap is not in the first Recommendation of 2018: it came in as a correction to it, made normative in the 2024 edition.

Rebuilding loca

A transformed loca table has version 0 in the directory and a transformLength of 0: it takes no bytes in the stream. The decoder builds it while it writes the glyph records, one offset per glyph and one for the end of the last, in the format indexFormat gives. Its origLength must be (numGlyphs + 1) × 2 for short offsets or × 4 for long ones; any other value makes the font invalid. Short offsets store the offset divided by 2, so with indexFormat 0 every glyph record must start at an even offset.

If glyf is transformed, loca must be too, and the reverse.

When the font must be rejected

• A composite glyph has no explicit bounding box, or an empty glyph has one.
• The transformed loca has a transformLength other than 0, or an origLength that does not match numGlyphs and indexFormat.
• Only one of glyf and loca is transformed.
• A stream runs out before every glyph is decoded.

The rebuilt glyf table need not be the same size as its origLength, because the decoder chooses its own encoding of flags and coordinates; that is not an error.