BRender Technical Reference Manual:4 Data Structures (Alphabetical Reference):br_font
The Structure
Access & Maintenance
Referencing & Lifetime
Import & Export


The Structure

The font data structure, describing a BRender font. Up to 223 bit mapped characters are supported. The font does not necessarily need to accord with ASCII character codes, however the non-printing ASCII codes (0-31 & 127) of the 256 codes possible are reserved for such a purpose.

Three ASCII fonts (covering codes 32-126) are predefined by BRender:

3 pixels wide by 5 high, fixed pitch font

4 pixels wide by 6 high, pixel proportional font

7 pixels wide by 9 high, pixel proportional font

The typedef

(See brfont.h for precise declaration and ordering)

br_uint_32 flags Properties of the font

br_uint_16 glyph_x Pixel width of fixed pitch characters

br_uint_16 glyph_y Pixel height of characters

br_int_16 spacing_x Horizontal pixel spacing of characters

br_int_16 spacing_y Vertical pixel spacing of characters

br_int_8 * width Pixel widths of proportional characters

br_uint_16 * encoding Offsets to data for each character

br_uint_8 * glyphs Pointer to bit mapped character data

Related Functions

See BrPixelmapText()
277, BrPixelmapTextF()278, BrPixelmapTextWidth()279, BrPixelmapTextHeight()280.


br_uint_32 flags

The flags member contains various details about the properties of the font such as whether it is proportional or not.

The presence of the flag whose value is defined by the symbol BR_FONTF_PROPORTIONAL indicates that the spacing between characters is proportional to their widths (width is used), otherwise each character is regularly spaced (glyph_x is used).

br_uint_16 glyph_x

The width of characters in fixed pitch fonts. Note that there is an implicit single pixel gap between characters.

br_uint_16 glyph_y

The height of the font in pixels (the number of pixel rows making up the largest character).

br_int_16 spacing_x

The width in pixels between horizontally adjacent character co-ordinates. This is not currently implemented by BRender, but could be used to determine the spacing between columns of text when interpreting ASCII HTAB say.

br_int_16 spacing_y

The height in pixels between vertically adjacent character co-ordinates. This is not currently implemented by BRender, but could be used to determine the spacing of between rows of text when interpreting ASCII VTAB or CRLF say.

br_int_8 * width

Pointer to an array of 256 widths in pixels of each character (in proportional fonts). Values for ASCII control codes (0-31 & 127) have reserved meanings. Note that there is an implicit single pixel gap between characters.

br_uint_16 * encoding

Pointer to an array of 256 offsets to each character's bit map (values for ASCII control codes (0-31 & 127) have reserved meanings), with a set bit indicating character foreground colour, and a cleared bit indicating transparent.

Each character is formed of a number of rows of bytes. The number of rows in each character is equal to glyph_y. The number of bytes in each row is given by the integer formula below, where Width is the pixel width of the character (glyph_x in the case of fixed pitch fonts and width[char] in the case of proportional fonts).

Therefore, in proportional fonts, it is possible that some characters will have a different number of bytes per row.

The character's pixels are arranged in memory such that the character's top left hand corner occupies the most significant bit of the first byte. Naturally a character row may use fewer pixels than all of the bits of the bytes it occupies, in such a case the least significant bits of the last byte of each row will be unused. For example, say the ASCII letter `E' was stored in a font called my_font as a 10x18 character. It would be stored in 18 pairs of bytes (36 bytes) at an address pointed to by my_font.glyphs+my_font.encoding[`E']. The first byte would contain the pixels for the left hand 8 dots of the top row. The second byte's two most significant bits would contain the remaining two dots of the top row. Subsequent bytes would contain pixels for lower rows in a similar fashion.

br_uint_8 * glyphs

Pointer to raw font data containing bit maps for each character. In proportional fonts the first byte should not be used for character data so that an encoding offset of zero can be considered Null. For the same purpose, in fixed pitch fonts, there should be a dummy character definition at an encoding offset of zero. Note that the space character should not use this definition, but have its own (therefore at a non-zero offset*1).


May be freely copied. However, be careful of a structure assignment if the lifetime of the original font data is unknown.

Given that font data can be arranged in a convoluted manner, there is not necessarily a single most efficient way of copying it. One way to copy font data is to first determine the extent of the data by scanning the list of offsets and obtaining the maximum extent of each character's data (including the character's width). Another way is to copy font data character by character.

Access & Maintenance

The font and its data are not guaranteed to be writable, but otherwise members may be freely accessed (although this should be avoided during text operations). Do not modify the supplied fonts (though their data may be copied and subsequently modified if desired).

Referencing & Lifetime

The font should be maintained while references to it exist.


Initialise the entire structure to zero (using memset(,0,sizeof(br_font)), say) and ensure all the above members are set appropriately. The elements of width and encoding corresponding to ASCII control codes (0-31 & 127) should be set to zero. All of the remaining 223 elements must have valid values. Character data can be stored in any order, may overlap and need not be contiguous. In proportional fonts, codes for which no character is defined should have a width of zero and a zero encoding offset. In fixed pitch fonts, codes for which no character is defined should have a zero encoding offset (therefore a dummy character definition is required at an offset of zero).

Import & Export

There are no specific font load/save functions. See Filing System Support for details of BRender functions that could be used to assist font import and export.

Do not be beguiled by the apparent simplicity of storing fonts within monochrome pixel maps. There are a few points at which this idea has difficulties. For instance, a monochrome pixel map may require 4 byte alignment of pixel rows, whereas a font requires single byte alignment. Also, with proportional fonts, characters may not necessarily all have the same number of bytes per row, so it may not be possible to fit them all into a neat column.

Generated with
CERN WebMaker