Copyright (c) 2008-2011, Oliver Fromme <olli@fromme.com> <olli@secnetix.de>

Description of the font file format

This is a simple, yet generic and flexible font file format
that can be used to store monochrome fonts.  Proportional
as well as monospaced fonts are supported.  A font file can
contain up to 65535 characters, and every character can
have its own width and height.  The maximum character width
is 254 pixels, the maximum height is 255 pixels.

A font file consists of a font header, followed by one or
more character definitions.  Each character definition
consists of a character header and a bitmap.  The bitmap
is of variable size (even within the same font), depending
on width and height of the character.  There must be at
least one character in a font.

<font>  ::=
        <font header>
        <character list>

<font header>  ::=
        <flags>
        <planes>
        <bskip>
        <first>
        <count>

<character list>  ::=
        <character>
        [ <character list> ]

<character>  ::=
        <character header>
        <bitmap>

<character header>  ::=
        <height>
        <width>
        <voffset>
        <preskip>
        <postskip>

The values in the font header are all 16 bit unsigned
integer numbers, stored in little-endian byte order.
They have the following meaning:

<flags>:  Currently unused, must be 0.

<planes>:  Currently unused, must be 1.  Reserved for
           multiple bitplane support that might be
           implemented in the future.

<bskip>:  The so-called baseline skip.  This is the
          natural height of the font, i.e. the y offset
          should be incremented by this many pixels upon
          a linefeed.

<first>:  The ASCII code of the first character in the
          font.  Usually this is 32 (the space character),
          but it can be any number in the range from 0 to
          65535.

<count>:  The number of characters in this font file.
          For the full ASCII character set (i.e. codes
          from 32 to 126), the count would be 95.

In contrast, the values in the character header are all
single bytes (8 bit).  Note that some are unsigned and
some are signed, as explained below.

<height>:  The height of the character's bitmap in pixels.
           This is usually less than the <bskip> value,
           but it can be the same or even bigger.
           This is an unsigned value in the range 0 to 255,
           so the maximum character height is 255 pixels.

<width>:   The width of the character's bitmap in bytes
           (not pixels!).  This is unsigned, too.
           Therefore, in theory the maximum character width
           is 2040 pixels (255 * 8), but the usable width
           is limited by preskip+postskip (see below) to
           254 pixels.

<voffset>:  Vertical offset of this character, i.e. the
            bitmap is moved down this many pixels.  This
            is a signed value (range from -128 to +127),
            so you can move the bitmap up by specifying a
            negative value.

<preskip>:  How many pixels to skip to the right before
            drawing the bitmap, i.e. leaving this much
            space after the previous character.  This is
            a signed value, too, so you can also move to
            the left by specifying a negative value, thus
            possibly overwriting the previous character
            or part of it.

<postskip>:  How many pixels to skip to the right after
             the bitmap has been drawn, in order to reach
             the position where the next character should
             be drawn.  This is a signed value, too (range
             from -128 to +127).  The total width accounted
             for the character is preskip + postskip.

A character's <bitmap> must consist of <height> * <width>
bytes.  Note that it can be empty (for a space character).
In that case set both <height> and <width> to zero, and
set <preskip> to the width of the space in pixels.

Here's a typical character (an asterisk, ASCII code 42):

height:   5
width:    1
voffset:  5
preskip:  1
postskip: 8
bitmap:
.xx.xx..
..xxx...
xxxxxxx.
..xxx...
.xx.xx..

The height is 5 pixel rows, and the width is 1 byte per
row, so the bitmap consists of 5 bytes (printed in binary
above, a dot is "0" and an x is "1").  The voffset is 5,
meaning that the bitmap is drawn 5 pixels below the top
of the character line.  If this value was 0, the asterisk
would stick to the top and look like a superscript tag.
Preskip is 1 and postskip is 8 pixels, which means that
the asterisk is centered within a 9 pixels wide field
(note that the asterisk occupies the left 7 pixels within
the bitmap).

Typically, you create or edit a font with an ASCII editor
and "compile" it to binary format with the bincoder tool.
This is the bincoder format string for the font format:

(4 Wu) Wu=n (n Bu=h Bu*h=s (3 Bi) (s B))

So this is the command to compile the font:

$ bincoder '(4 Wu) Wu=n (n Bu=h Bu*h=s (3 Bi) (s B))' < source.txt > font

Starting a font from scratch is rather laborious.  It's
better to make a copy of the default font's source file
(stdfont.txt) and use it as a template.  It contains
some useful comments.  Note that comments are introduced
with a semicolon (';'), not with a hash sign.

So, basically you do this:

$ cp stdfont.txt myfont.txt
$ vi myfont.txt
$ bincoder '...' < myfont.txt > myfont

END