| GBDK libraries documentation | ||
|---|---|---|
| Prev | Chapter 5. Libraries | |
void init_font(void)Initialise the font system by clearing all font handles and releasing all tiles.
Initialises the font system. This routine should be called at the start of the program before any calls to font_load.
None.
Nothing.
FONT_HANDLE load_font( void *font_structure )Attempt to load the font font, returning a FONT_HANDLE on success or NULL on failure.
font_load should be called once for each font that is required. Note that currently there is no way to unload a font except by calling font_init().
font: pointer to the base of a valid font structure
On success, returns a FONT_HANDLE. On failure, returns NULL (0)
void font_set( FONT_HANDLE font_handle )Set the current font to the previously loaded font font_handle
set_font changes current output font to the one specified by font_handle
font_handle: handle from a previous font_load call.
Nothing.
No check is made to see if font_handle is a valid font handle.
A FONT_HANDLE is a 16 bit value returned from font_load and used by font_set. Physically it is a pointer to an entry in the font_table.
A font_structure is a container for the data related to a font, including the encoding data and tile (bitmap) image data. Due to the variable length nature of the encoding table and the tile data no default C structure exists.
A font structure is made up of four fields - the font type, the number of tiles used, the encoding table and the tile data.
The Font type is a single bit that describes the encoding table and the format of the tile data. The encoding table length is specified by the lower two bits: 00: 256 byte encoding table. 01: 128 byte encoding table. 10: No encoding table - the font is 256 tiles long. 11 is reserved. The third bit (0x04) is used to determine if the tile data is compressed. Many tiles do not use shades of grey, and so can be represented in 8 bytes instead of 16. If bit 2 is set, then the tiles are assumed to be 8 bytes long and are expanded to 16 bytes at the load stage.
num_tiles gives the number of tiles present in the tile data and hence the number of tiles required by the font.
The encoding table is an array that maps an ASCII character to the appropriate tile in the tile data. For example, suppose that the letter 'A' was the tenth tile. Then the 65th (the ASCII code for 'A') entry in the encoding table would be 10. Any ASCII characters that don't have a corresponding tile should be mapped to a default tile. Space is recommended tile.
The final field is the actual tile data. Note that tile numbering starts from zero.
The original text routines were replaced by the font routines in GBDK 2.0.18. This section describes the differences and compatibility between the old and new text routines.
The old font routines stored a bitmap of the entire IBM-ASCII character set in the Gaemboy tiles, such that the ASCII value of the letter mapped to the appropriate tile - for example, the bitmap of an 'A' (ASCII 65) was stored in tile 65. The new system allows multiple fonts to fit into the same 256 tiles by removing unused characters - for example, if one font only needs the letters 'A-Z' and numbers '0-9' (36 tiles), then the remaining 220 tiles can be used for other fonts or game tiles.
If no fonts are loaded before the first call to putchar() then the original IBM-ASCII font is automatically loaded. This should make the font routines backwards compatible with older code and standard C. Note that the text input routines currently only work with the IBM-ASCII font.
One side effect is that the IBM-ASCII font is always linked in occuping 2.3k of ROM, even if it is not used. If the extra ROM is required, add the line:
UBYTE font_ibm_fixed[]; or _font_ibm_fixed::
into the project. Note that in 2.0.18, the graphics mode text routines only use the IBM-ASCII font.
Fonts can also be used to store game tiles. To make the tiles allocated more predictable, load the game tile font first, as the first tile in the font will be allocated to tile 01h (tile 00h is always clear). Game tile fonts should use 'no encoding' for their encoding table type to save memory. Two features allow the standard C routines to also be used for game tiles - namely M_NO_INTERP and M_NO_SCROLL. The first stops the routines from interpreting carridge returns (\n), the second stops the screen from scrolling. Use
mode(get_mode() | M_NO_INTERP | M_NO_SCROLL);to turn both on. See font_draw in Michael Hopes 'metro' package for an example.
| Prev | Home | |
| malloc, free and related functions - stdlib.h | Up |