WOFF File Format 2.0

1.1 Notational Conventions

The all-uppercase key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in RFC 2119 [RFC2119]. If these words occur in lower- or mixed case, they should be interpreted in accordance with their normal English meaning.

This document includes sections of text that are called out as "Notes" and set off from the main text of the specification. These notes are intended as informative explanations or clarifications, to serve as hints or guides to implementers and users, but are not part of the normative text.

This document also uses hexadecimal numerical notation "0x..." to define the constant binary values such as magic number or tag values, bitfields / flags format and mask values used in pseudo-code bitwise operators.

3.1. Data types

    Read255UShort( data )
    {
        UInt8 code;
        UInt16 value, value2;

        const oneMoreByteCode1    = 255;
        const oneMoreByteCode2    = 254;
        const wordCode            = 253;
        const lowestUCode         = 253;

        code = data.getNextUInt8();
        if ( code == wordCode ) {
            /* Read two more bytes and concatenate them to form UInt16 value*/
            value = data.getNextUInt8();
            value <<= 8;
            value &= 0xff00;
            value2 = data.getNextUInt8();
            value |= value2 & 0x00ff;
        }
        else if ( code == oneMoreByteCode1 ) {
            value = data.getNextUInt8();
            value = (value + lowestUCode);
        }
        else if ( code == oneMoreByteCode2 ) {
            value = data.getNextUInt8();
            value = (value + lowestUCode*2);
        }
        else {
            value = code;
        }
        return value;
    }
    

    bool ReadUIntBase128( data, *result )
    {
        UInt32 accum = 0;

        for (i = 0; i < 5; i++) {
            UInt8 data_byte = data.getNextUInt8();

            // No leading 0's
            if (i == 0 && data_byte == 0x80) return false;

            // If any of top 7 bits are set then << 7 would overflow
            if (accum & 0xFE000000) return false;

            *accum = (accum << 7) | (data_byte & 0x7F);

            // Spin until most significant bit of data byte is false
            if ((data_byte & 0x80) == 0) {
                *result = accum;
                return true;
            }
        }
        // UIntBase128 sequence exceeds 5 bytes
        return false;
    }
    

3.2. WOFF2 Header

The WOFF 2.0 header includes an identifying signature and provides the information about the compressed and uncompressed sizes of encapsulated font data. It also indicates the specific kind of font data included in the WOFF 2.0 file, font version number and provides offsets to additional data blocks included in the file.

The interpretation of the WOFF2 Header is the same as the WOFF Header in [WOFF1], with the addition of one new totalCompressedSize field. The signature field in the WOFF2 header MUST contain the value of 0x774F4632 ('wOF2'), which distinguishes it from WOFF 1.0 files. If the field does not contain this value, user agents MUST reject the file as invalid. A valid WOFF 2.0 file MUST have the reserved field set to 'zero', a decoder MUST NOT reject a downloaded font file if the reserved header value is not zero. User agents MUST NOT reject correctly decoded font file if the resulting font file size doesn't match the totalSfntSize value encoded as part of the WOFF2 header.

4.1. Table directory format

The table directory is an array of WOFF2 table directory entries, as defined below. The directory follows immediately after the WOFF2 file header; therefore, there is no explicit offset in the header pointing to this block. Its size is dependent on the exact content; thus, the best strategy for decoding is to process the file as a stream, rather than trying to access it randomly. Each table directory entry specifies the original size of a single font data table and, for those tables where an additional transform has been applied, the size of the transformed table. Transformed tables are identified by their 'flags' field that combines known table tags (bits 0-5, see "Known Table Tags") and transformation version number (bits 6 and 7, see the description below) defining the applied transform. The combination of the table tag and the transform version number defines the exact transform that was applied to a table, currently defined transforms are specified in details in clause 5 of this specification.

Contrary to the way how table directory entries are specified in the original input font file (where table directory entries are sorted in ascending alphabetical order), the WOFF2 table directory entries define the physical order of tables in which they have been processed and encoded as part of the compressed font data stream. It is a decoder responsibility to sort and reorder the reconstructed table directory when the font file is decompressed.

In order to simplify the font decoding process an encoder MUST reorder the transformed tables so that the associated 'glyf' and 'loca' tables are always present as a pair, with 'loca' table following the 'glyf' table. Please keep in mind that the entry for transformed 'loca' table is just a placeholder indicating the size required to reconstruct the table while consuming no bytes of the data stream. Therefore, the requirement for the 'loca' table entry to immediately follow the transformed 'glyf' table in the table directory makes it easier to implement the 'loca' table reconstruction step when the reverse transform (see subclause 5.1 for details) is being applied to the 'glyf' table. For more details on table order constraints see subclause 5.5.

The format of each individual table directory entry is as follows:

The interpretation of the flags field is as follows. Bits [0..5] contain an index to the "known tag" table, which represents tags likely to appear in fonts. If the tag is not present in this table, then the value of this bit field is 63. Bits 6 and 7 indicate the preprocessing transformation version number (0-3) that was applied to each table. For all tables in a font, except for 'glyf' and 'loca' tables, transformation version 0 indicates the null transform where the original table data is passed directly to the Brotli compressor for inclusion in the compressed data stream. For 'glyf' and 'loca' tables, transformation version 3 indicates the null transform where the original table data was passed directly to the Brotli compressor without applying any pre-processing defined in subclause 5.1 and subclause 5.3. The transformed table formats and their associated transformation version numbers are described in details in clause 5 of this specification.

Where more than one transformation version is defined for a given table tag, an encoder may use any of the defined transformations that is applicable to the input data; a decoder MUST be prepared to accept any of the defined transformations. If a decoder encounters a table entry that specifies an unknown transformation version number the entire font MUST be rejected as it cannot be correctly decoded.

Whether a font table is encoded with a known table tag or explicitly including the four-byte tag has no semantical significance; it is simply a choice of encoding intended to improve compression efficiency. Similarly, whether a particular four-byte tag is present or not in the "Known Table Tags" table is not a normative statement about whether such tags should be included in web fonts.The encoder MUST use known table flag when encoding an input font table with a tag that is listed in the "Known Table Tags" table.

There is a predefined extension mechanism for any custom table tag that is not included in the known tag list (or for any new standard tags that may be defined in the future). If bits [0..5] of the flags byte have the value 63 (0x3f), then following the flag byte is a 4-byte arbitrary tag value. Otherwise, the tag field is omitted in the TableDirectoryEntry structure, and is derived from bits [0..5] of the flag byte from the fixed Known Table Tags table, given below. The decoder MAY accept a table entry defined using a custom table tag even if the tag that follows is identified as one of the kown table tags.

Following the flags (and the optional tag field) are one or two length values, each in UIntBase128 unsigned integer encoding. The origLength field specifies the length of the table in an uncompressed version of the font. For tables that are subjected to additional transformations, the transformLength field that specifies the length of the transformed version of the table MUST be included.

The transformLength field is present in the table directory entry if, and only if, the table has been processed by a non-null transform prior to Brotli compression. For tables that are not transformed, no transformLength field is present in the directory entry.

4.2. Collection directory format

The collection directory is present only if the input font is a collection; i.e. if the value of the WOFF2 file header "flavor" field is set to 0x74746366 ('ttcf'). If present, the collection directory follows immediately after the table directory. The collection directory consists of a CollectionHeader and one or more CollectionFontEntry records.

If input font is a collection, the table directory contains a single entry for each unique table in the entire collection, regardless of whether a table is shared among different fonts in a collection or not. Thus, the table directory for a font collection compressed with WOFF2 comprises all tables from all fonts contained in the font collection file.

The Collection directory starts with the Collection Header followed by an array of Collection Font Entries.

Collection font entries specify each font in the collection (defined by CollectionHeader "numFonts" field). The format of each individual collection font entry is as follows:

A table whose offset is referred to by multiple Offset Tables in the original collection is considered "shared". An encoder MUST emit a single TableDirectoryEntry for each unique font table defined by its offset, regardless of whether that table is shared among multiple fonts in a collection or not. I.e., if a collection contains multiple fonts with their corresponding Table Records referencing shared font tables with the same offsets, the table data in the WOFF2 compressed data stream MUST NOT be duplicated.

If an input font file is a font collection that contains multiple unique glyf and loca tables, the transformations described for the glyf and loca tables MUST be applied to each pair of the tables.Sharing of glyf and loca tables is allowed and encouraged (this is one of the major benefits of a font collection); however, it is possible that font collections may have two or more pairs of the glyf / loca tables that may not be shared. When the tables are shared, an encoder MUST verify that both tables are shared and that both form an associated pair (if more than one pair of glyf / loca tables are present) and MUST reject a collection containing fonts that share only one of either glyf or loca table.

An encoder, when processing a font collection, MUST preserve the same order of the nested fonts as they are in the input font collection and MUST record the index of the matching TableDirectoryEntry into the CollectionFontEntry for each font.

A decoder MUST restore the collection with the same number of fonts and their corresponding Offset Tables. The Offset Tables for each font that comprises the output font collection file MUST have either the same numTables as the input collection, or one less if DSIG was present in the original input Offset Table. If the value of the version field for the TTC Header in the CollectionHeader is set to "2.0", a decoder MUST either set the TTC Header fields {ulDsigTag, ulDsigLength, ulDsigOffset} in the output collection to null or convert the TTC header format to version 1 (0x00010000).

A decoder, when processing a font collection, MUST recreate the same order of the nested fonts as they were in the input collection. The tables within each nested font can be reordered. When processing a font collection with multiple pairs of 'glyf'/'loca' tables present, a decoder MUST check CollectionFontEntry indices to make sure that referenced 'glyf' and 'loca' tables are paired with each other, and MUST reject a font collection if a mismatch in table pairing is found. For more details about table pairs see the table directory format description. A conforming user agent MUST be able to load and use properly formatted font collection file generated by a WOFF2 decoder.

5.1. Transformed glyf table format

The glyf table data can be presented in the WOFF2 file in one of two formats defined by the transformation version number (encoded in the table directory flag bits, see subclause 4.1 for details). The transformation version "3" defines a null transform where the content of the glyf table is presented in its original, unmodified format. The transformation version "0", specified below, is optional and can be applied to eliminate certain redundancies in the glyf table data.

The version "0" of the glyf table transformation (as defined by the table directory flag bits, see subclause 4.1 for details) specified in this subclause is intended to reduce redundant information and provide a more efficient encoding of the actual TrueType outlines of glyphs. The modified transformation is based on a similar transformation described in MicroType Express [MTX] specification. The reference to MTX is informative; the details of the modified transformation are stated below and this section is normative.

Regardless of the implementation details of the glyph record reconstruction process and the level of optimizations applied to reconstructed 'glyf' table data User Agents MUST NOT reject correctly decoded font file if the size of the reconstructed 'glyf' table doesn't match the origLength value encoded as part of the 'glyf' table entry in WOFF2 Table Directory.

For greater compression effectiveness, the glyf table is split into several substreams, to group like data together. The transformed table consists of a number of fields specifying the size of each of the substreams, followed by the substreams in sequence. During the decoding process the reverse transformation takes place, where data from various separate substreams are recombined to create a complete glyph record for each entry of the original glyf table.

The format is best characterized by describing the decoding process, especially indications of what are valid and invalid data. Note also that this format specifies the decoded result at the semantic level, not specific byte streams.

Included in the Transformed glyf Table is a bboxBitmap indicating for each glyph whether it contains an explicitly encoded bounding box, or whether the bounding box is to be inferred from the coordinate values. The relevant computations to determine the bounding box status must be performed by both an encoder and a decoder. For each simple glyph, an encoder MUST calculate the the xMin, yMin, xMax and yMax coordinate values using all outline points (both on- and off-curve points) and compare the calculated values with the encoded bounding box info for the glyph. If the glyph bounding box info matches the calculated values, an encoder MUST omit the bounding box info. Otherwise, if the calculated bounding box values do not equal the glyph values encoded in a font, an encoder MUST set the corresponding bboxBitmap flag and record the original bounding box values in the bboxStream. For glyphs records that contain zero contours, an encoder MUST check that the glyph bounding box values are all zeros and, if this condition is not met, MUST reject an input font as invalid. For either an empty glyph or a glyph with zero contours, an encoder MUST always clear the corresponding bboxBitmap flag. For a composite glyph, an encoder MUST always set the corresponding bboxBitmap flag and record the original bounding box values in the bboxStream.

A decoder MUST perform similar calculations if the bounding box is to be inferred. For a given glyph, when a corresponding bit in bboxBitmap is not set, the xMin, yMin, xMax and yMax values MUST be calculated at the time of decoding using all outline point coordinates. The total number of bytes in bboxBitmap is equal to 4 * floor((numGlyphs + 31) / 32). The bits are packed so that glyph number 0 corresponds to the most significant bit of the first byte, glyph number 7 corresponds to the least significant bit of the first byte, glyph number 8 corresponds to the most significant bit of the second byte, and so on. A bit=1 value indicates an explicitly set bounding box.

Upon reading the Transformed glyf Table, the decoding process iterates one glyph at a time. For each glyph, it reads zero or more bytes from each of the streams referenced in the Transformed glyf Table. Also, at the point of reconstructing a glyph, a decoder needs to store for each glyph the corresponding offset in the new reconstructed glyph table, and this data will collectively become the contents of the reconstructed loca table (see subclause 5.3 below for more information about the reconstruction of the loca table).

5.2. Decoding of variable-length X and Y coordinates

Simple glyph data structure defines all contours that comprise a glyph outline, which are presented by a sequence of on- and off-curve coordinate points. These point coordinates are encoded as delta values representing the incremental values between the previous and current corresponding X and Y coordinates of a point, the first point of each outline is relative to (0,0) point. To minimize the size of the dataset of point coordinate values, each point is presented as a (flag, xCoordinate, yCoordinate) triplet. The flag value is stored in a separate data stream and the coordinate values are stored as part of the glyph data stream using a variable-length encoding format consuming a total of 2-5 bytes per point.

The most significant bit of a flag indicates whether the point is on- or off-curve point (if the most significant bit is 0, then the point is on-curve), the remaining seven bits of the flag determine the format of X and Y coordinate values and specify 128 possible combinations of indices that have been assigned taking into consideration typical statistical distribution of data found in TrueType fonts. When X and Y coordinate values are recorded using nibbles (either 4 bits per coordinate or 12 bits per coordinate) the bits are packed in the byte stream with most significant bit of X coordinate first, followed by the value for Y coordinate (most significant bit first). As a result, the size of the glyph dataset is significantly reduced, and the grouping of the similar values (flags, coordinates) in separate and contiguous data streams allows more efficient application of the entropy coding applied as the second stage of encoding process.

Each of the 128 index values define the following properties and specified in details in the table below:

• Byte count (total number of bytes used for this set of coordinate values including one byte for 'flag' value).
• Number of bits used to represent X coordinate value (X bits).
• Number of bits used to represent Y coordinate value (Y bits).
• An additional incremental amount to be added to X bits value (delta X).
• An additional incremental amount to be added to Y bits value (delta Y).
• The sign of X coordinate value (X sign).
• The sign of Y coordinate value (Y sign).

Please note that “Byte Count” field reflects total size of the triplet (flag, xCoordinate, yCoordinate), including ‘flag’ value that is encoded in a separate stream.

For additional information and background on the triplet encoding please see section 5.11 of the MTX proposal [MTX].

5.3. Transformed loca table format

The loca table data can be presented in the WOFF2 file in one of two formats defined by the transformation version number (encoded in the table directory flag bits, see subclause 4.1 for details). The transformation version "3" defines a null transform where the content of the loca table is presented in its original, unmodified format. The transformation version "0", although optional, MUST be applied to the loca table data whenever glyf table data is transformed. In other words, both glyf and loca tables must either be present in their transformed format or with null transform applied to both tables.

The version "0" of the loca table transformation (as defined by the table directory flag bits, see subclause 4.1 for details) is specified below.

The transformLength of the transformed loca table MUST always be zero. The origLength MUST be the appropriate size (determined by numGlyphs+1, times the size per glyph, where that size per glyph is two bytes when indexFormat (defined in subclause 5.1. Transformed glyf table format) is zero, otherwise four bytes). If the transformLength of the transformed loca table is not equal to zero, or if the encoded origLength does not match the calculated size defined above the decoder MUST reject the WOFF2 file as invalid.

The loca table MUST be reconstructed when the glyf table is decoded. The process for reconstructing the loca table is specified in subclause 5.1 as part of the transformed glyf table decoding process. For reconstructed glyph records, a decoder MUST store the corresponding offsets for individual glyphs using a format that is indicated by the indexFormat field of the Transformed glyf Table.

5.4. Transformed hmtx table format

The hmtx table data can be presented in the WOFF2 file in one of two formats defined by the transformation version number (encoded in the table directory flag bits, see subclause 4.1 for details). The transformation version "0" defines a null transform where the content of the hmtx table is presented in its original, unmodified format. The transformation version "1", specified below, is optional and can be applied to eliminate certain redundancies in the hmtx table data.

The transformation version "1" exploits the built-in redundancy of the TrueType glyphs where the outlines of the glyphs designed according to the TrueType recommendations would likely have their left side bearing values equal to xMin value of the glyph bounding box. The hmtx table format is specified in subclause 5.2.4 of [OFF] and includes two arrays of left side bearing information for proportional and monospaced glyph runs. Each of these arrays can be eliminated from the original input font data and reconstructed from the glyph bounding box information if certain conditions are met.

If the hmtx table transform is both applicable and desired, the encoder MUST check that leftSideBearing values match the xMin values of the glyph bounding box for every glyph in a font (or check that leftSideBearing == 0 for an empty glyph) and, for font collections, this check MUST be performed on every corresponding pair of glyf and hmtx tables. If the conditions are met for each of the proportional or monospaced glyph runs the encoder MUST set hmtx transform version number to "1", MUST eliminate the corresponding array from the hmtx table and MUST set the appropriate Flags bits. In font collections that have shared hmtx table, the match between xMin values of glyph bounding boxes and the lsftSideBearing values MUST be checked for all combinations of shared hmtx and various glyf tables, and if there is a mismatch the hmtx table transform MUST NOT be applied.

When the table directory flags indicate that the hmtx transform is applied, the User Agent MUST check the Flags values and MUST reject the WOFF2 file if Flags are invalid. The decoder MUST reconstruct the lsb[] and/or leftSideBearing[] arrays from the xMin values provided by the glyph bounding box information from the glyf table.

5.5. Table order constraints

The following constraints on valid WOFF2 files are intended to facilitate a memory-efficient WOFF 2.0 file transfer and decoding process.

The loca table MUST follow the glyf table in the table directory. When WOFF2 file contains individually encoded font file, the table directory MAY contain other tables inserted between glyf and loca tables; however when WOFF2 contains a font collection file each loca table MUST immediately follow its corresponding glyf table. For example, the following order of tables: 'cmap', 'glyf', 'hhea', 'hmtx', 'loca', 'maxp' ... is acceptable for individually encoded font files; however, font collection files must have glyf / loca tables paired with each other, although they don't have to be ordered as a contiguous block of tables, e.g.: 'cmap', 'glyf', 'loca', 'hhea', 'hmtx', 'glyf', 'loca', 'maxp', 'post' ... would be acceptable. Additional constraints on the loca table are given in subclause 5.3.

D.1 Normative References

[WOFF1]

WOFF File Format 1.0 Jonathan Kew, Tal Leming, Erik van Blokland, Editors. World Wide Web Consortium, 13 December 2012. The latest version of the WOFF specification is available at http://www.w3.org/TR/WOFF/

[OFF]

Open Font Format specification (ISO/IEC 14496-22:2019). together with Amendment 1: Color font technology and other updates

[Brotli]

Brotli Compressed Data Format, RFC 7932 J. Alakuijala and Z. Szabadka, Editors. Internet Engineering Task Force, Informational, July 2016.

[RFC2119]

RFC 2119: Key words for use in RFCs to Indicate Requirement Levels. S. Bradner, Editor. Internet Engineering Task Force, Best Current practice, March 1997.

[RFC8081]

The font Top Level Type, RFC 8081 C. Lilley, (Editor). Internet Engineering Task Force, Proposed Standard, February 2017.

[CSS3-Fonts]

CSS Fonts Module Level 3, John Daggett, Myles C. Maxfield, Chris Lilley (Editors). World Wide Web Consortium Recommendation, 2018. The latest version of CSS3 Fonts is available at http://www.w3.org/TR/css-fonts-3/

D.2 Informative References

[WOFF2ER]

WOFF 2.0 Evaluation Report Chris Lilley, Editor. World Wide Web Consortium, 2015.

[OpenType]

Microsoft OpenType specification. OpenType is a registered trademark of Microsoft Corporation.

[TrueType]

Apple TrueType Reference manual. Apple, 2014. TrueType is a registered trademark of Apple, Inc.

[MTX]

MicroType® Express (MTX) Font Format Sarah Martin, Al Ristow, Steve Martin, Vladimir Levantovsky, and Christopher Chapman. W3C Member Submission, 5 March 2008.