| CRM64Pro GDK v0.16.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.02.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.

### Key features

- High performance: Blazing fast bitmap-based text rendering.
- Design freedom: Use any font style, size or effects in your image editor.
- 96 character set: Full ASCII printable character support.
- 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.

### Character set

Font images must contain the following 96 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 96-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 (scans for 96 characters).

### Image requirements

Character separation | At least 2 pixels between each character.
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.

### 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 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...