Description

Font Manager and Font objects for bitmap-based text rendering [v25.12.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.

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

Functions
Sint32	CRM64Pro::Font::info (Sint32 iMode=0)
	Request Font object information.
Sint32	CRM64Pro::Font::getName (string &sName)
	Get the name.
Uint32	CRM64Pro::Font::getID ()
	Get the ID.
Sint32	CRM64Pro::Font::assignImage (Sint32 idImage, Sint32 iOwnership=0)
	Assign an Image to this font.
Sint32	CRM64Pro::Font::getImage ()
	Get the assigned Image of this font.
Sint32	CRM64Pro::Font::setCursor (Uint8 cCursor)
	Set cursor character.
Uint8	CRM64Pro::Font::getCursor ()
	Get cursor character.
Sint32	CRM64Pro::Font::getCursorPositionByPixel (const string &sText, Sint32 iPixelPos)
	Get the cursor position given a number of pixels.
Sint32	CRM64Pro::Font::setKerning (Sint32 iKer)
	Set the kerning value.
Sint32	CRM64Pro::Font::getKerning ()
	Get the kerning value.
Sint32	CRM64Pro::Font::getWidth (const string &sText, Sint32 iCurPos=-1)
	Get the width of the given string (in pixels).
Sint32	CRM64Pro::Font::getHeight ()
	Get the height of this font (in pixels).
Sint32	CRM64Pro::Font::setPosition (const Position &posX, const Position &posY)
	Set the font position.
Sint32	CRM64Pro::Font::getPosition (Position posX, Position posY)
	Get the font position (returns Position structs).
Sint32	CRM64Pro::Font::render (const string &sText, Sint32 iCurShow=0, Sint32 iCurPos=-1, Sint32 idRes=0)
	Render a text using this font.
Sint32	CRM64Pro::Font::renderEx (const string &sText, Sint32 iCurShow=0, Sint32 iCurPos=-1, const double dAngle=0.0, const SDL_FPoint *poCenter=nullptr, const SDL_FlipMode rf=SDL_FLIP_NONE, Sint32 idRes=0)
	Render a text using this font.
Sint32	CRM64Pro::Font::save (const string &sFileCDC)
	Save the font to a CDC file.
Sint32	CRM64Pro::Font::save (Sint32 idCDC)
	Save the font to a CDC file.
Sint32	CRM64Pro::FontMgr::info (Sint32 iMode=0)
	Request Font Manager information.
Sint32	CRM64Pro::FontMgr::create (const string &sName, Uint32 iVersion=10)
	Create a new font.
Sint32	CRM64Pro::FontMgr::close (Sint32 idFont)
	Close and destroy a font.
Sint32	CRM64Pro::FontMgr::getNum () const
	Get number of loaded objects.
Sint32	CRM64Pro::FontMgr::setName (Sint32 idFont, const string &sName)
	Change the object name.
Font *	CRM64Pro::FontMgr::get (Sint32 idFont)
	Get a pointer to the font using its handler.
Sint32	CRM64Pro::FontMgr::child (Sint32 idFont)
	Create a child font dependant on the provided one (the parent).
Sint32	CRM64Pro::FontMgr::load (const string &sFileCDC, const string &sName)
	Load a font stored in a CDC file.
Sint32	CRM64Pro::FontMgr::load (const Sint32 idCDC, const string &sName)
	Load a font stored in a CDC file.
Sint32	CRM64Pro::FontMgr::remove (const Sint32 idCDC, const string &sName)
	Remove a font stored in a CDC file.

Function Documentation

◆ info() [1/2]

Sint32 CRM64Pro::Font::info ( Sint32 iMode = 0 )

Request Font object information.

Writes information to the default log.

Parameters

iMode Unused for the time being.

Returns: 0 on success, or a negative error code on failure.

◆ getName()

Sint32 CRM64Pro::Font::getName ( string & sName )

Get the name.

Parameters

sName A string containing the font name.

Returns: 0 on success, or a negative error code on failure.

◆ getID()

Uint32 CRM64Pro::Font::getID ( )

Get the ID.

Returns: The object ID.

◆ assignImage()

Sint32 CRM64Pro::Font::assignImage	(	Sint32	idImage,
		Sint32	iOwnership = 0 )

Assign an Image to this font.

It is mainly used for associating an Image to the font when it is created via FontMgr::create().

Parameters

idImage	Image id with the whole characters set. They are identified using alpha channel so the image needs to have colorkey/alpha channel enabled.
iOwnership	0 for creating our own copy of the image or any other value for taking the ownership of the image; in this case, the image can not be already owned by another item. By default it is set to 0.

Returns: 0 on success, or a negative error code on failure.

Note: The image name associated to this font will be internally modified: starts with the reserved character '#' + an internal code + the font name. When re-assigning a new image, the old one will be closed.

◆ getImage()

Sint32 CRM64Pro::Font::getImage ( )

Get the assigned Image of this font.

Returns: Greater than 0 on success, or a negative error code on failure.

◆ setCursor()

Sint32 CRM64Pro::Font::setCursor ( Uint8 cCursor )

Set cursor character.

Parameters

cCursor A character on the range of (33, 129].

Returns: 0 on success, or a negative error code on failure.

◆ getCursor()

Uint8 CRM64Pro::Font::getCursor ( )

Get cursor character.

Returns: Greater than 33 and less than 130 on success, or a negative error code on failure.

◆ getCursorPositionByPixel()

Sint32 CRM64Pro::Font::getCursorPositionByPixel	(	const string &	sText,
		Sint32	iPixelPos )

Get the cursor position given a number of pixels.

Parameters

sText	String to get the cursor position.
iPixelPos	Pixel position to convert to cursor position.

Returns: 0 or greater on success (cursor position on the range of [0, text size in characters - 1]) or a negative error code on failure.

Note: If the pixel position is outside the text width, it will return -1.

◆ setKerning()

Sint32 CRM64Pro::Font::setKerning ( Sint32 iKer )

Set the kerning value.

Parameters

iKer	Signed integer with the kerning value in pixels.

Returns: 0 on success, or a negative error code on failure.

◆ getKerning()

Sint32 CRM64Pro::Font::getKerning ( )

Get the kerning value.

Returns: Signed integer with the kerning value in pixels.

◆ getWidth()

Sint32 CRM64Pro::Font::getWidth	(	const string &	sText,
		Sint32	iCurPos = -1 )

Get the width of the given string (in pixels).

Parameters

sText	String to get its width.
iCurPos	Up to this character position. By default, it is set to -1 for positioning the cursor at the end of the string.

Returns: Greater than 0 (string width on pixels) on success or a negative error code on failure.

◆ getHeight()

Sint32 CRM64Pro::Font::getHeight ( )

Get the height of this font (in pixels).

Returns: Greater than 0 (string height on pixels) on success or a negative error code on failure.

◆ setPosition()

Sint32 CRM64Pro::Font::setPosition	(	const Position &	posX,
		const Position &	posY )

Set the font position.

Parameters

posX	Position struct with X position. Can be absolute (float) or use position helpers from ::ePositionHelpers enum.
posY	Position struct with Y position. Can be absolute (float) or use position helpers from ::ePositionHelpers enum.

Returns: 0 on success, or a negative error code on failure.

Note: Supports implicit conversion from float: setPosition(100.0f, 200.0f) or explicit helpers: setPosition(Position(PH_CENTER, -10.0f), Position(PH_TOP))

◆ getPosition()

Sint32 CRM64Pro::Font::getPosition	(	Position *	posX,
		Position *	posY )

Get the font position (returns Position structs).

Parameters

posX	Position pointer filled in with X position struct. If nullptr is passed, the method ignores retrieving this value.
posY	Position pointer filled in with Y position struct. If nullptr is passed, the method ignores retrieving this value.

Returns: 0 on success, or a negative error code on failure.

◆ render()

Sint32 CRM64Pro::Font::render	(	const string &	sText,
		Sint32	iCurShow = 0,
		Sint32	iCurPos = -1,
		Sint32	idRes = 0 )

Render a text using this font.

Parameters

sText	String with the text to be rendered.
iCurShow	0 to hide the cursor or any other value to show it. By default it is hidden.
iCurPos	Position of the cursor on the given text. By default it is set to -1 which means at the end.
idRes	A valid screen or image handle. By default it tries to use the default screen.

Returns: 0 on success, or a negative error code on failure.

◆ renderEx()

Sint32 CRM64Pro::Font::renderEx	(	const string &	sText,
		Sint32	iCurShow = 0,
		Sint32	iCurPos = -1,
		const double	dAngle = 0.0,
		const SDL_FPoint *	poCenter = nullptr,
		const SDL_FlipMode	rf = SDL_FLIP_NONE,
		Sint32	idRes = 0 )

Render a text using this font.

Parameters

sText	String with the text to be rendered.
iCurShow	0 to hide the cursor or any other value to show it. By default it is hidden.
iCurPos	Position of the cursor on the given text. By default it is set to -1 which means at the end.
dAngle	An angle in degrees that indicates the rotation that will be applied.
poCenter	SDL_FPoint pointer indicating the point around which each character will be rotated. By default, it is set to nullptr and the rotation will be done around rDst.w/2 and rDst.h/2.
rf	SDL_FlipMode value stating which flipping actions should be performed.
idRes	A valid screen or image handle. By default it tries to use the default screen.

Returns: 0 on success, or a negative error code on failure.

◆ save() [1/2]

Sint32 CRM64Pro::Font::save ( const string & sFileCDC )

Save the font to a CDC file.

The associated image will also be saved in to the same CDC file.

Parameters

sFileCDC String containing the [directory]+filename+[extension]. Directory separators '\' and '/' are supported.

Returns: 0 or greater on success or a negative error code on failure.

Note: If the font already exists, it will be overwritten. If the font is a child, the parent font will be saved.

◆ save() [2/2]

Sint32 CRM64Pro::Font::save ( Sint32 idCDC )

Save the font to a CDC file.

The associated image will also be saved in to the same CDC file.

Parameters

idCDC CDC id.

Returns: 0 or greater on success or a negative error code on failure.

Note: If the font already exists, it will be overwritten. If the font is a child, it will call the save method of its parent.

◆ info() [2/2]

Sint32 CRM64Pro::FontMgr::info ( Sint32 iMode = 0 )

Request Font Manager information.

Writes information to the default log.

Parameters

iMode -1 for displaying only Manager information. 0 for displaying Manager and all Objects information. This is the default value. Greater than 0 (Font id) for displaying Manager and given Font information.

Returns: 0 on success, or a negative error code on failure.

◆ create()

Sint32 CRM64Pro::FontMgr::create	(	const string &	sName,
		Uint32	iVersion = 10 )

Create a new font.

This method will create an empty font (no image assigned), use Font::assignImage() method for assigning the image.

Parameters

sName	The name to give to the font e.g. 'myFont'. The object name must be unique and with a maximum size of 64 characters or will be truncated.
iVersion	Font version. 10 means 1.0 which is the only version supported (as of now). v1.0 is set by default.

Returns: Greater than 0 on success (the Font id) or a negative error code on failure.

Note: If the provided name already exists, it does nothing and return an error code.

◆ close()

Sint32 CRM64Pro::FontMgr::close ( Sint32 idFont )

Close and destroy a font.

Parameters

idFont 0 for closing all fonts or the Font id. Stand-alone and child fonts can be closed but parent ones, can not as they have at least one dependency (a child).

Returns: 0 on success, or a negative error code on failure.

Note: If you forget to close a Font, it will be automatically closed once the GDK is terminated.

◆ getNum()

Sint32 CRM64Pro::FontMgr::getNum ( ) const

Get number of loaded objects.

Returns: The number of fonts.

◆ setName()

Sint32 CRM64Pro::FontMgr::setName	(	Sint32	idFont,
		const string &	sName )

Change the object name.

Parameters

idFont	Font id.
sName	The name to give to the font e.g. 'myFont'. The object name must be unique and with a maximum size of 64 characters or will be truncated.

Returns: 0 on success, or a negative error code on failure.

Note: The image name associated to this font will be internally modified: starts with the reserved character '#' + an internal code + the font name.

◆ get()

Font * CRM64Pro::FontMgr::get ( Sint32 idFont )

Get a pointer to the font using its handler.

Parameters

idFont Font id.

Returns: nullptr The font was not found.; A pointer to the font object.

◆ child()

Sint32 CRM64Pro::FontMgr::child ( Sint32 idFont )

Create a child font dependant on the provided one (the parent).

A child font uses the attributes of the parent and creates also a parent child image for having different attributes.

Parameters

idFont Parent Font id. If the provided font is a child, internally it will redirect this request to the parent in order to create the new child.

Returns: Greater than 0 on success (the Font id) or a negative error code on failure.

Note: The child use the parent's name.

◆ load() [1/2]

Sint32 CRM64Pro::FontMgr::load	(	const string &	sFileCDC,
		const string &	sName )

Load a font stored in a CDC file.

Parameters

sFileCDC	String containing the [directory]+filename. Directory separators '\' and '/' are supported.
sName	String with the font name (maximum size of 64 characters). If the font is already created, this method will call child() for creating a child.

Returns: 0 or greater on success (the Font id) or a negative error code on failure.

◆ load() [2/2]

Sint32 CRM64Pro::FontMgr::load	(	const Sint32	idCDC,
		const string &	sName )

Load a font stored in a CDC file.

Parameters

idCDC	CDC id.
sName	String with the font name (maximum size of 64 characters). If the font is already created, this method will call child() for creating a child.

Returns: Greater than 0 on success (the Font id) or a negative error code on failure.

◆ remove()

Sint32 CRM64Pro::FontMgr::remove	(	const Sint32	idCDC,
		const string &	sName )

Remove a font stored in a CDC file.

Parameters

idCDC	CDC id.
sName	String with the font name (maximum size of 64 characters).

Returns: Greater than 0 on success, or a negative error code on failure.

Note: The font must be closed before trying to remove it from the CDC.

Description

Overview

Key features

Character set

Font creation process

Image requirements

Storage layer

Manager type

Best practices

Classes

Functions

Function Documentation

◆ info() [1/2]

◆ getName()

◆ getID()

◆ assignImage()

◆ getImage()

◆ setCursor()

◆ getCursor()

◆ getCursorPositionByPixel()

◆ setKerning()

◆ getKerning()

◆ getWidth()

◆ getHeight()

◆ setPosition()

◆ getPosition()

◆ render()

◆ renderEx()

◆ save() [1/2]

◆ save() [2/2]

◆ info() [2/2]

◆ create()

◆ close()

◆ getNum()

◆ setName()

◆ get()

◆ child()

◆ load() [1/2]

◆ load() [2/2]

◆ remove()