HelenOS Typeface File Format (TPF)

HelenOS proportional fonts are stored in TPF format. TPF format can store an entire typeface (font family), i.e. a set of fonts of different sizes and attributes. At present the fonts are in the form of monochrome bitmaps, in future they could be extended to support e.g. ASCII art / ANSI art, outline or stroke fonts, as required. Other possible future extensions include the specification of fallback fonts. Reading and writing TPF files (as well as text rendering) is performed by libgfxfont. Font Editor is a HelenOS application that can be used to edit TPF typefaces.

The file format is considered evolving at this stage and not set in stone. It is based on Microsoft RIFF structure, which makes it easier to evolve the format, because incremental changes can be more easily made in a backward compatible manner (i.e. new version of software can still read older version of file format). The RIFF structure was also chosen because the library for reading/writing RIFF files has more uses in HelenOS (e.g. reading WAV files).

TPF fourcc codes overview

Here's an overview of fourcc codes used (at the risk of becoming out of sync with the code):

FourCC code	Comment
TPFC	Typeface (RIFF format ID)
font	Font (list type)
fprp	Font properties (CKID)
fmtr	Font metrics (CKID)
fbmp	Font bitmap (CKID)
glph	Glyph (list type)
gmtr	Glyph metrics (CKID)
gpat	Glyph patterns (CKID)
gror	Glyph rectangle/origin (CKID)

TPF file structure

   RIFF(TPFC)
       LIST(font)
           fprp
           fmtr
           fbmp
           LIST(glph)
               gmtr
               gpat
               gror
           LIST(glph)
               ...
           ...
       LIST(font)
           ...
       ...

A TPF file is a RIFF file with TPFC format ID. It consists of a number of LIST(font) chunks (one per font).

Each LIST(font) chunk contains three chunks, in order, fprp, fmtr and fbmp, followed by zero or more LIST(glph) chunks (one for each glyph). fprp contains the basic font properties (used to index the fonts), fmtr contains the font metrics and fbmp contains the bitmap of the entire font.

Each LIST(glph) chunk contains exactly three chunks, in order, gmtr, gpat, gror. gmtr contains the glyph metrics. gpat contains a list of string patterns that the glyph matches. gror contains the glyph rectangle/origin within the font bitmap (i.e. which rectangle inside bitmap contains the glyph and where its origin point is).

For backward compatibility, whenever the reader expects a particular chunk to appear, they will silently skip over any other chunk. That means new, optional, chunks can be introduced and the older file will still be readable by newer software.

fprp chunk

        uint16_t size;
        uint16_t flags;

size is the height (in pixels) of the font.

Flags:

Bit number	Description
0	Bold
1	Italic

fmtr chunk

        uint16_t ascent;
        uint16_t descent;
        uint16_t leading;

ascent is the number of pixels the capital characters extend above the baseline. descent is the number of pixels the descenders descend below the baseline. leading is the number of additional pixels of spacing added between two successive lines of text.

fbmp chunk

This chunk contains a header, immediately followed by the actual bitmap data. The format of the header is as follows:

        /** Width in pixels */
        uint32_t width;
        /** Height in pixels */
        uint32_t height;
        /** Format (0) */
        uint16_t fmt;
        /** Depth (bits/pixel) */
        uint16_t depth;

The font bitmap is stored as individual lines (each padded to an entire byte), top to bottom. Each line is packed into bytes, left to right. The first pixel is stored into the most significant bit.

gmtr chunk

        uint16_t advance;

advance is the number of pixels the pen advances to the right when this glyph is set.

gpat chunk

This chunk contains a series of null-terminated UTF-8 strings that the glyph should match. For example, the glyph "Č" could match either a single pre-composed character or the letter "C" follwed by a combining hook, so it would have two strings. In another example, there could be a ligature "iff" matching a single string consisting of three characters. In the simplest case there will be just one string containing a single Unicode code point.

gror chunk

        /** Rectangle p0.x */
        uint32_t p0x;
        /** Rectangle p0.y */
        uint32_t p0y;
        /** Rectangle p1.x */
        uint32_t p1x;
        /** Rectangle p1.y */
        uint32_t p1y;
        /** Origin X */
        uint32_t orig_x;
        /** Origin Y */
        uint32_t orig_y;

The rectangle [p0x, p1x) x [p0y, p1y) (i.e. excluding p1x,p1y) contains the glyph and its origin point is [orig_x, orig_y] (coordinates in the font bitmap). The origin point is placed at the current pen position when the glyph is set.