| CRM64Pro GDK v0.18.0 A free cross-platform game development kit built on top of SDL 3.0

Loading...
Searching...
No Matches
Font
Graphics modules

## 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().fontMgr().getBuiltin("Arial12Black");
Font* pFont = Main::instance().fontMgr().get(idFont);
CRM64Pro::FontMgr::getBuiltin
Sint32 getBuiltin(const string &sName)
Get a built-in embedded font id using its name.
Definition GraphicsFont.cpp:1326
CRM64Pro::FontMgr::get
Font * get(const string &sName)
Get a pointer to the font using its name.
Definition GraphicsFont.cpp:1123
CRM64Pro::Main::instance
static Main & instance()
Access the Main singleton.
Definition CoreMain.cpp:453
CRM64Pro::Main::fontMgr
FontMgr & fontMgr()
Get reference to Font Manager.
Definition CoreMain.cpp:986

### 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::fontMgr().

Note
  The Font Manager is a singleton, automatically created once Main is instantiated. You can get a reference to this manager using Main::fontMgr() 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...