Agon built-in system font
The built-in font is based on windows code page 1252, also known as "windows-1252". The font includes a number of modifications, including additional characters that were added to support the Teletext symbols. The characters in the range 0-31, and 127, and not directly displayable as they have meanining as control characters to the VDP. In order to access them, you need to use special codes outlined below. The symbols occupying the range 0-31 are only included from VDP 2.15 onwards, and aligned with the "graphics extended" version of the code page, again with some minor modifications. The card suits were added to use the available characters that were already available in the Teletext additions.
Displaying and reprogramming non-printable characters 0-31 and 127
Characters in the range 0-31, and 127, are considered control characters and when printed directly all have meaning to the VDP to perform particular actions as VDU Commands. In order to display a character in that range you will either need to "escape" it (from VDP 2.3 onwards) using the VDU 27 sequence, or from VDP 2.9 you can use the "print buffer" VDU 23, 0, &9B, bufferId; method which will raw display all symbols in the buffer, including treating all control characters as printable as defined in the current font.
Similarly, individually reprogramming characters in the range 0-31 cannot be done by the usual VDU 23, char_no, b1, b2, b3, b4, b5, b6, b7, b8 sequence, however, from VDP 2.3 they can be individually redefined using the VDU 23, 0, &90, n, b1, b2, b3, b4, b5, b6, b7, b8 sequence. These characters can also be reprogrammed by replacing the entire font as outlined in the Font management sequences below.
System font character set
The default system font is 8 pixels by 8 pixels, therefore all characters in the chart below fit within an 8x8 pixel grid.
VDU 23, 0, &95: Font management
From Console8 VDP 2.8.0 onwards, the VDP now has an API to allow for different fonts to be uploaded to the VDP and used on your Agon. At this time the VDP supports mono-spaced fonts only, each only at a single size. Future versions of this API may introduce support for variable width fonts, and displaying text at different sizes.
As with other APIs, the data for fonts is stored in buffers which are sent to the VDP using the Buffered Commands API.
Generally when selecting a font to use, you will need to upload the font data to a buffer on the VDP, and then indicate that buffer contains a font. Once this has been done the font can be selected and used to draw text on the screen. The system font will always be available, and can be used by selecting font -1 (65535).
You can define as many different fonts on the VDP as you have buffers available, and can switch between them as needed. Your font selection is tied to your currently selected cursor, so you can select different fonts for use with your graphics cursor and your text cursor.
The commands for the font API are as follows:
VDU 23, 0, &95, 0, bufferId; flags: Select font
Select a font to use for drawing text.
The bufferId here must refer to a buffer that has been uploaded to the VDP, and marked as a font using VDU 23, 0, &95, 1, <args>, as described below, or -1 (65535) for the system font.
The flags parameter is a bitfield which can be used to specify options for the font. The following flags are supported:
| Bit | Description |
|---|---|
| 0 | Adjust cursor position to ensure text baseline is aligned |
| 1-7 | Reserved for future use |
If you wish to change the font within a line of text, you should use a flags setting of 1. This will use data within the font to ensure that the cursor position is moved to keep the text baseline aligned.
When changing the font at the start of a new line, you should use a flags setting of 0, as otherwise the text may overlap the previous line.
VDU 23, 0, &95, 1, bufferId; width, height, ascent, flags: Create font from buffer
This command is used to mark a buffer as containing font data. The bufferId must refer to a buffer that has been uploaded to the VDP, and contains font data. The width and height parameters indicate the width and height of each character in the font in pixels, and ascent is the distance in pixels from the top of the character to the baseline.
The flags parameter is reserved for future use, and should be set to 0. In the future it will be used for indicating variable width fonts, and other font properties.
Font data is assumed to be a contiguous block of data, one character at a time, with a full 256 character definitions, from character 0 to 255. The buffer passed to this command should contain a single block of data of an appropriate size for the font. If the data has been uploaded in multiple parts, it should be concatenated into a single block before calling this command using the appropriate commands in the buffered commands API.
Fonts are monochrome, and the data is assumed to be one character at a time. Each character is stored in a byte-aligned format, where each row of a character is stored in a number of bytes equal to (width + 7) / 8, with their pixels organised most significant bit first, with as many rows as indicated by the height. "Most significant bit first" means that the leftmost pixel of the character is stored in the most significant bit of the first byte, so a font that is 6 pixels wide would be stored in bits 7-2, with bits 1 and 0 ignored when rendering the font.
VDU 23, 0, &95, 2, bufferId; field, value;: Set or adjust font property
Allows you to set or adjust properties of a font that has been created using VDU 23, 0, &95, 1, <args>. The bufferId must refer to a buffer that has been marked as containing font data.
The field parameter indicates the property to set, and the value parameter is the value to set it to. Whilst the value must be sent as a 16-bit value, most of the fields will only use the least significant 8-bits of the sent value. The following fields are supported:
| Field | Description |
|---|---|
| 0 | width |
| 1 | height |
| 2 | ascent |
| 3 | flags |
| 4 | buffer for character pointers (for variable width fonts) * |
| 5 | point size (defaults to 0) * |
| 6 | inleading (defaults to 0) * |
| 7 | exleading (defaults to 0) * |
| 8 | weight (defaults to 400) * |
| 9 | character set (defaults to 255) * |
| 10 | code page (defaults to 1252) * |
Fields 0-4 directly equate to the parameters passed to VDU 23, 0, &95, 1, <args>.
* Please note that as of VDP 2.8.0, whilst data can be set for these fields, setting them will not affect the rendering of the font. They are reserved for future use.
VDU 23, 0, &95, 3, bufferId; [<args>]: Reserved
This function is reserved for future use, and should not be used at this time.
(The intent is that this will be used to set the name of the font.)
VDU 23, 0, &95, 4, bufferId;: Clear/Delete font
Deletes a font that has been created using VDU 23, 0, &95, 1, <args>. The bufferId must refer to a buffer that has been marked as containing font data.
NB: This does not delete the buffer itself, only the font definition. The data remains intact in the buffer, and can be re-used to create a new font if desired.
VDU 23, 0, &95, 5, bufferId;: Copy system font to buffer
Copies the system font data into a buffer and makes a new font definition for it.
The buffer at the bufferId will be cleared first and then the system font data will be copied into it. The buffer will then be marked as containing font data, and can be used as a font in the same way as any other font.
This command will let you make multiple copies of the system font which can then be modified independently of each other using the buffered commands API.