Font

Description

Font Manager and Font objects for bitmap-based text rendering [v26.04.0].

Overview

The Font module provides fast bitmap font handling optimized for game development. Instead of using a more sophisticated TTF font rendering system, the GDK uses a simple and blazing fast approach that is still quite powerful and allows using any kind of font design. The current font implementation is limited to the built-in printable ASCII character set and does not render arbitrary UTF-8 glyphs.

Key features

• High performance: Blazing fast bitmap-based text rendering.
• Design freedom: Use any font style, size or effects in your image editor.
• Printable ASCII character set: Space plus characters from '!' to '~'.
• Image access: Direct access to underlying Image object for advanced manipulation.
• CDC storage: Load and save fonts using CDC v1.x specification.
• Cloning support: Automatic child font creation for shared resources.
• Built-in fonts: Eight embedded Arial/Courier New black/white 10/12 fonts available through FontMgr::getBuiltin().

Text encoding note

Rendering and cursor helpers in this module operate on byte offsets within the supported ASCII bitmap character set. UTF-8 strings can be stored and edited by higher GUI layers, but glyph rendering and cursor metrics for non-ASCII text are not supported.

Character set

Font images must contain the following printable ASCII characters in this exact order:

! \" # $ % & ' ( ) * + , - . / 0 1 2 3 4 5 6 7 8 9 : ; < = > ? @ A B C D E F G H I J K L M N O P Q R S T U V W X Y Z [ \ ] ^ _ ` a b c d e f g h i j k l m n o p q r s t u v w x y z { | } ~

The first character is a space. Characters can represent any graphical representation, it is the responsibility of the creator to ensure the correct order.

Font creation process

Step 1	Create an image containing the printable ASCII character set using your favorite image design software with any font style and attributes.
Step 2	Ensure the image complies with spacing requirements (see Image requirements below).
Step 3	Save the image to PNG or BMP format.
Step 4	Load the image using the Image Manager (set colorkey now if used).
Step 5	Create a font with FontMgr::create().
Step 6	Call Font::assignImage() to scan and initialize the font.

Image requirements

Character separation	At least 1 transparent pixel between each character. Rendering adds letter spacing plus kerning between adjacent text characters.
Left/Right margins	At least 5 pixels on each side of the image.
Transparency	Use colorkey or alpha transparent pixels for separation and margins.
Supported formats	PNG or BMP.

Storage layer

Format	CDC v1.x specification.
FontMgr::load()	Load font from CDC archive.
Font::save()	Save font to CDC archive.

Built-in fonts

The engine embeds a small practical font set that can be requested through FontMgr::getBuiltin() using short names:

Arial	Arial10Black, Arial10White, Arial12Black, Arial12White
Courier New	CourierNew10Black, CourierNew10White, CourierNew12Black, CourierNew12White

Internally these built-ins are stored with the @c64/font/ prefix, but callers can use the short names above. This is the recommended way to obtain the default GUI and editor fonts.

Typical usage

Sint32 idFont = Main::Instance().IFontMgr().getBuiltin("Arial12Black");
Font* pFont = Main::Instance().IFontMgr().get(idFont);

Manager type

This is an advanced "cloning" manager: when loading a font from a CDC file that is already loaded or created (using the name as the key), it will create a new child font. Child fonts share base data with the parent while allowing independent state.

Naming security

Resource names are restricted to prevent collisions with system assets. The characters '#' and '@' are reserved for internal engine use. Any attempt to create or rename a resource starting with these characters will be rejected (returning a negative error code).

Best practices

• Use FontMgr::getBuiltin() for common UI/editor fonts instead of hardcoding resource buffers in higher-level modules.
• Use consistent character spacing in your font image for uniform text rendering.
• Set the colorkey on the Image before calling Font::assignImage() if using colorkey transparency.
• Double-check the character order in your font image: incorrect order will map characters incorrectly.
• Use PNG format with alpha transparency for high-quality anti-aliased fonts.
• Leverage cloning to efficiently share font resources across multiple UI elements.
• Access the underlying Image object via its ID when you need to modify font appearance (e.g., alpha modulation).
• Create multiple font sizes as separate images rather than scaling at runtime.
• Access the manager exclusively through Main::IFontMgr().

Note

The Font Manager is a singleton, automatically created once Main is instantiated. You can get a reference to this manager using Main::IFontMgr() method.
The Font Manager is automatically released when Main::Terminate() is called. At this time, any resource still loaded will be released, avoiding resource leaks.

Classes
class	CRM64Pro::Font
	Font Object class. More...
class	CRM64Pro::FontMgr
	Font Manager class. More...