Format:
font (ref_sint8_var);
Set a new font to be used by all text output functions on the externally attached display device.
The parameter points to a sint8 (“byte”) type array which contains the binary definitions for the font.
Every font in Rittle has the following standardised structure (all fields are byte):
startL, startH 16-bit number that specifies the character code of the first character in the font. It must be greater than 0 since code 0 is reserved for end of string indication and cannot be displayed.
In standard ASCII fonts, currently supported by Rittle, the character codes are always 8-bit, so the high byte in this field should be kept 0.
countL, countH 16-bit number that tells how many character definitions are included in this font. Rittle currently supports only 8-bit character codes, so although more characters can be defined in the font, the actually usable range is up to 255 characters and the high byte should be kept 0.
width Pixel width of a single character.
This parameter specifies the number of columns in the characters. In fonts where this field is 0, every character definition starts with an additional byte that defines how many columns are present in that character only.
In fonts with fixed width where the “width” parameter is greater than 0, the leading width-specifying byte in every definition is missing since the width is already know for all characters.
height Pixel height of a single character.
Although they could be different in width, the height of all characters in the font is the same.
The actual number of bytes for every character definition depend on the width and height of the font combined: for fonts with height 8 lines or less, every byte represents one column, for fonts with height 16 lines or less, every column takes two bytes, and so on. Then the width specifies how many columns are needed for the entire character.
Bit counting starts from bit 0 which represents the top pixel, bit 1 is the one below, and so on. For fonts with more than 8 lines the counting continues in the same fashion on the following byte. If the number of lines in the font are not divisible by 8, the remaining bits in the last byte of every column remain unused, not displayed, and should be kept 0.
blankL Number of blank columns to add on the left side of every character.
blankR Number of blank columns to add on the right side of every character.
blankU Number of blank rows to add on top of every character.
blankD Number of blank rows to add under every character.
name ... 0x00 Text name of the font. The text must finish with a byte 0. If there is no name, then this field contains only a single byte 0.
The actual character definitions start after this font header.
Every character is defined as a bit mask within one or more bytes. The characters have consecutive codes, starting from the code specified in the “start” field in the header, and going on for the number of “count” characters. There are no separators between two neighbouring definitions. Rittle works out the numbers from the values supplied in the font header.
Font definition examples:
1. The definition of character ‘A’ in a font with fixed width 5 (the “width” field in the font header has value 5 and that defines that all characters in the font will be within 5 columns) and height 7:
0x7C, 0x12, 0x11, 0x12, 0x7C
This sequence of bytes looks like this:
|
|
7c |
12 |
11 |
12 |
7c |
|
0 |
|
|
# |
|
|
|
1 |
|
# |
|
# |
|
|
2 |
# |
|
|
|
# |
|
3 |
# |
|
|
|
# |
|
4 |
# |
# |
# |
# |
# |
|
5 |
# |
|
|
|
# |
|
6 |
# |
|
|
|
# |
|
7 |
not used |
||||
In addition to the definition, in the font header there are fixed definitions for certain number of blank pixels to be added to all sides of every character in the font.
2. Definition of character ‘W’ in a font with variable width (the “width” field in the font header has value 0) and height 14 pixels.
Since the width is variable, every character in the font has its own width, and that is specified in one additional byte at the beginning of every character definition.
The particular character in this example has 12 columns, and every column is described by two bytes. Since by definition the font has maximum height of 14 pixels, the last two bits in the second byte will remain unused and they are not displayed on the screen.
The definition will look like this:
12, 0x01,0x00, 0xFE,0x01, 0x00,0x07, 0x00,0x20, 0x20,0x18, 0xE0,0x07, 0x20,0x1e, 0x00,0x20, 0x00,0x18, 0xFE,0x07, 0x01,0x00
|
|
01 |
fe |
00 |
00 |
00 |
20 |
e0 |
20 |
00 |
00 |
fe |
01 |
|
0 |
# |
|
|
|
|
|
|
|
|
|
|
# |
|
1 |
|
# |
|
|
|
|
|
|
|
|
# |
|
|
2 |
|
# |
|
|
|
|
|
|
|
|
# |
|
|
3 |
|
# |
|
|
|
|
|
|
|
|
# |
|
|
4 |
|
# |
|
|
|
|
|
|
|
|
# |
|
|
5 |
|
# |
|
|
|
# |
# |
# |
|
|
# |
|
|
6 |
|
# |
|
|
|
|
# |
|
|
|
# |
|
|
7 |
|
# |
|
|
|
|
# |
|
|
|
# |
|
|
|
||||||||||||
|
|
00 |
01 |
07 |
1e |
20 |
18 |
07 |
1e |
20 |
18 |
07 |
00 |
|
8 |
|
# |
# |
|
|
|
# |
|
|
|
# |
|
|
9 |
|
|
# |
# |
|
|
# |
# |
|
|
# |
|
|
10 |
|
|
# |
# |
|
|
# |
# |
|
|
# |
|
|
11 |
|
|
|
# |
|
# |
|
# |
|
# |
|
|
|
12 |
|
|
|
# |
|
# |
|
# |
|
# |
|
|
|
13 |
|
|
|
|
# |
|
|
|
# |
|
|
|
|
14 |
not used |
|||||||||||
|
15 |
||||||||||||
All character definitions start immediately after the font header, and follow up in sequential order, so in the example above, after the character ‘W’ will follow character 'X', then character ‘Y’, and so on.
Example of the font() function use:
data byte myfont =
32, 0, ‘ the font starts from code 32 (space character)
1, 0, ‘ there is only one character in the font
8, ‘ the width is fixed at 8 columns
8, ‘ the height will be 8 lines
0, 1, 0, 1, ‘ blank pixels on left/right/up/down
0, ‘ name of the font (no name)
0, 0, 0, 0, 0, 0, 0, 0; ‘ definition of the first character in the font
font ( @myfont[] ); ‘ now “myfont” becomes the active font