Bitmap Fonts

The format

Version 1.1 Version 1.2

BMF version 1.1

offset	size	meaning
0	4	magic header (0xE1E6D51A)
4	1	version (0x11)
5	1	lineHeight – measure from lowest to highest reach (0…255) should be equal to or greater than sizeUnder – sizeOver
6	1	sizeOver (–128…127) measure from baseline to top of capital letters, in pixels; should be negative
7	1	sizeUnder (–128…127) measure from baseline to lowest extends (of letters like "y", "g"), in pixels; should be positive or zero
8	1	addSpace after each char (–128…127) how many pixels to add after plotting each character l2r
9	1	sizeInner (height of small letters) (–128…127) measure from baseline to top of small letters (e.g. "m"); should be negative
10	1	usedColors – count of used colors
11	1	highest used color attribute
12	4	reserved (0)
16	1	number of colors in palette, not counting color #0 (P)
17	P*3	font palette (array of RGB triplets, 6 bits/0…63 per component)
17+P*3	1	title length (T)
18+P*3	T	title or description of the font (string)
19+P*3+T	2	numChars – number of characters in font i.e. having non-zero size or shift (N)
21+P*3+T	?	bitmap definitions

N * (which character (its ASCII code 0…255), followed by its tablo entry)
E.g. "A", <tablo entry for "A">, "B", <tablo entry for "B">, "C", <tablo entry for "C">, …

Tablo entry has the following structure:

offset	size	meaning
0	1	character width (W)
1	1	character height (H)
2	1	relX – X offset from cursor position (–128…127)
3	1	relY – Y offset from cursor position (–128…127)
4	1	shift – horizontal cursor shift after drawing the character
5	W * H	character bitmap (uncompressed, row-major, 8 bits per pixel)

Each character with its width * height and shift equal to zero is considered empty (unused) and as such its entry is not stored. Characters with empty bitmaps but non-zero shift are valid, i.e. its tablo entry follows. Bitmap of 0×0 pixels = empty string. For example, space usually has no bitmap but its shift parameter is important to store within the font.

BMF version 1.2

Quick overview of changes from version 1.1:

• Unicode support
• alpha channel option
• multiple palettes
• kerning pairs

Basic backward compatibility maintained.

offset	size	meaning
0	4	magic header (0xE1E6D51A Little-Endian)
4	1	version (0x12)
5	1	lineHeight – measure from lowest to highest reach (0…255) should be equal to or greater than size-under – size-over
6	1	sizeOver (–128…127) measure from baseline to top of capital letters, in pixels; should be negative
7	1	sizeUnder (–128…127) measure from baseline to lowest extends (of letters like "y", "g"), in pixels; should be positive or zero
8	1	addSpace after each char (–128…127) how many pixels to add after plotting each character
9	1	sizeInner (height of small letters) (–128…127) measure from baseline to top of small letters (e.g. "m"); should be negative
10	1	usedColors – count of used colors
11	1	highest used color attribute
12	1	alphaBits – how many bits of each bitmap byte the alpha channel occupy? (0…8)
13	1	extraPalettes – how many additional palettes there are (all palettes must fit into the 255-entry field)
14	2	reserved (0)
16	1	number of colors in palette, not counting color #0 (P)
17	P*3	font palette (array of RGB triplets, 6 bits/0…63 per component)
17+P*3	1	title length (T)
18+P*3	T	title or description of the font (string)
19+P*3+T	2	asciiChars – number of characters in font of codes under 128 (N)
21+P*3+T	?	bitmap definitions

N * (which character (its ASCII code 0…127), followed by its tablo entry)
E.g. "A", <tablo entry for "A">, "B", <tablo entry for "B">, "C", <tablo entry for "C">, …

Tablo entry has the following structure:

offset	size	meaning
0	1	character width (W)
1	1	character height (H)
2	1	relX – X offset from cursor position (–128…127)
3	1	relY – Y offset from cursor position (–128…127)
4	1	shift – horizontal cursor shift after drawing the character
5	W * H	character bitmap (uncompressed, row-major, 8 bits per pixel)

after that follows

size	meaning
4	unicodeChars (32-bit unsigned int) – how many characters of Unicode code greater than 255 follow (U)

U * (which character (32-bit unsigned int), followed by its tablo entry (same format as above)

after that follows

size	meaning
4	kerningPairs (32-bit unsigned int) – how many kerning pairs are defined (K)

K * kerning pair definition

offset	size	meaning
0	4	first character (its Unicode code, 32-bit unsigned int)
4	4	second character
8	2	correction (16-bit signed int), positive=shift right, negative=shift left

Example #1: Inside BMF

Example #2: tablo attributes

For this example, let addSpace = 1, sizeOver = –8. The initial [x, y] of the layout is not the top-left corner of the first char's bitmap, it lies on the baseline. It should be the layout routine to add (usually negative) font's sizeOver to the y-coordinate. In the picture, the blue line is the base line, the blue cursor is the initial position to plot the text, the red cursor, being sizeOver pixels down from the base line, indicate cursor position before outputing each character of the text. Finally, to get to the actual top-left corners of each bitmap, we need to add the (relX, relY) vector from each character's tablo.

Working with the format

Pseudocode for loading a font

filename = "font.bmf";
file = fopen(filename, "rb");
buffer = fread(file, 17);
version = buffer[4];
if (substr(buffer, 0, 4) != "\xE1\xE6\xD5\x1A" || (version != 0x11 && version != 0x12)) {
  exit('Not a BMF, version 1.1 or 1.2');
}
lineHeight = buffer[5];
sizeOver = buffer[6];
sizeUnder = buffer[7];
addSpace = buffer[8];
sizeInner = buffer[9];
usedColors = buffer[10];
highestColor = buffer[11];
alphaBits = buffer[12];
extraPalettes = buffer[13];
reserved = buffer[14];
numColors = buffer[16];
palette = fread(file, numColors * 3);
for (i = 1; i <= numColors * 3; i++) {
  palette[i] *= 4; // stretch 0..63 values to 0..255
}
titleLength = fread(file, 1);
title = fread(file, titleLength);
asciiChars = fread(file, 2);
for (i = 0; i < asciiChars; i++) {
  whichChar = fread(file, 1);
  tablo[whichChar] = fread(file, 5);
  if (bitmapSize = tablo[whichChar][0] * tablo[whichChar][1]) {
    tablo[whichChar][5] = fread(file, bitmapSize);
  }
}
if (version >= 0x12) { // next goes for version 1.2+ only
  unicodeChars = fread(file, 4);
  for (i = 0; i < unicodeChars; i++) {
    whichChar = fread(file, 4);
    tablo[whichChar] = fread(file, 5);
    if (bitmapSize = tablo[whichChar][0] * tablo[whichChar][1]) {
      tablo[whichChar][5] = fread(file, bitmapSize);
    }
  }
  numKerningPairs = fread(file, 4);
  kerningPairs = [];
  for (i = 0; i < numKerningPairs; i++) {
    fread(file, kerningPair, 10);
    kerningPairs []= kerningPair;
  }
}
fclose(file);

Pseudocode for layout/output

text = "EXAMPLE ABC";
originalX = cursorX = 30;
cursorY = 20;
lineBreaksEnabled = true;
for (index = 0; index < strlen(text); index++) { // for each character..
  whichChar = ord(text[index]);
  if (lineBreaksEnabled && (whichChar == 13)) { // line break
    cursorY += font.lineHeight;
    cursorX = originalX;
    continue;
  }
  charWidth = font.tablo[whichChar][0];
  charHeight = font.tablo[whichChar][1];
  charRelX = font.tablo[whichChar][2];
  charRelY = font.tablo[whichChar][3];
  charShift = font.tablo[whichChar][4];
  charBitmap = font.tablo[whichChar][5];
  for (bitmapY = 0; bitmapY < charHeight; bitmapY++) { // for each bitmap row..
    for (bitmapX = 0; bitmapX < charWidth; bitmapX++) { // for each bitmap column..
      colorAttribute = charBitmap[bitmapY * charWidth + bitmapX];
      if (colorAttribute) { // leave color attribute 0 as transparent
        setPixel(
          cursorX + charRelX + bitmapX, // x
          cursorY + font.sizeOver + charRelY + bitmapY, // y
          font.palette[colorAttribute]
        );
      }
    }
  }
  cursorX += charShift + font.addSpace; // update cursor position
  if (version >= 0x12 && index < strlen(text) - 1) {
    cursorX += font.kerningPairs[whichChar, ord(text[index + 1])];
  }
}