Class representing a font for text rendering. More...

#include <font.h>

Public Member Functions
	Font ()
	Default constructor Creates an empty font instance.

	Font (const Font &font)
	Copy constructor. More...

void	AddGlyph (const Glyph &glyph)
	Adds a glyph to the font. More...

void	AddGlyph (Ui32 codepoint, Si32 xadvance, Sprite sprite)
	Adds a glyph to the font. More...

void	CreateEmpty (Si32 base_to_top, Si32 line_height)
	Creates an empty font with no glyphs. More...

void	Draw (const char *text, const Si32 x, const Si32 y, const TextOrigin origin, const TextAlignment alignment, const DrawBlendingMode blending_mode, const DrawFilterMode filter_mode, const std::vector< Rgba > &palete)
	Draws a UTF-8 string containing one or more lines of text to the backbuffer (directly to the screen) using a color palette. More...

void	Draw (const char *text, const Si32 x, const Si32 y, const TextOrigin origin=kTextOriginBottom, const TextAlignment alignment=kTextAlignmentLeft, const DrawBlendingMode blending_mode=kDrawBlendingModeAlphaBlend, const DrawFilterMode filter_mode=kFilterNearest, const Rgba color=Rgba(0xffffffff))
	Draws a UTF-8 string containing one or more lines of text to the backbuffer (directly to the screen) More...

void	Draw (Sprite to_sprite, const char *text, const Si32 x, const Si32 y, const TextOrigin origin, const TextAlignment alignment, const DrawBlendingMode blending_mode, const DrawFilterMode filter_mode, const std::vector< Rgba > &palete)
	Draws a UTF-8 string containing one or more lines of text to the destination sprite. More...

void	Draw (Sprite to_sprite, const char *text, const Si32 x, const Si32 y, const TextOrigin origin=kTextOriginBottom, const TextAlignment alignment=kTextAlignmentLeft, const DrawBlendingMode blending_mode=kDrawBlendingModeAlphaBlend, const DrawFilterMode filter_mode=kFilterNearest, const Rgba color=Rgba(0xffffffff))
	Draws a UTF-8 string containing one or more lines of text to the destination sprite. More...

Vec2Si32	EvaluateSize (const char *text, bool do_keep_xadvance)

const std::shared_ptr< FontInstance > &	FontInstance () const
	Gets the internal font instance. More...

Si32	GetOutlineSize ()
	Returns outline size in pixels. Outline*2 is counted towards size.

bool	IsEmpty () const
	Checks if the font is empty (has no codepoints) More...

void	Load (const char *file_name)
	Loads the font from file. More...

void	LoadAsciiSquare (const char *file_name, bool is_dense)
	Loads an ASCII square font from a file. More...

void	LoadBinaryFnt (const char *file_name)
	Loads a binary BMFont file. More...

void	LoadHorizontalStripe (Sprite sprite, const char *utf8_letters, Si32 base_to_top, Si32 line_height, Si32 space_width)
	Loads a font from a horizontal stripe of glyphs. More...

void	LoadLetterBits (Letter *in_letters, Si32 base_to_top, Si32 line_height)

void	LoadTable (Sprite sprite, const char *utf8_letters, Si32 cell_width, Si32 cell_height, Si32 base_to_top, Si32 line_height, Si32 space_width, Si32 left_offset)
	Loads a font from a table of glyphs. More...

void	LoadXml (const char *file_name)
	Loads a font from an XML file. More...

Detailed Description

Class representing a font for text rendering.

The Font class provides functionality for loading and rendering text in your game. It supports various text origins, alignments, blending modes, and colors.

Basic Usage

Create a Font instance:
Font gameFont;

arctic::Font
Class representing a font for text rendering.
Definition: font.h:462
Load a font file (BMFont format):
gameFont.Load("data/arctic_one_bmf.fnt");

arctic::Font::Load
void Load(const char *file_name)
Loads the font from file.
Definition: font.h:536
Draw text to the screen:
// Simple white text

gameFont.Draw("Hello World", 100, 100, kTextOriginTop, kTextAlignmentLeft);

// Colored text

gameFont.Draw("Score: 100", 20, 20, kTextOriginTop, kTextAlignmentLeft,

kDrawBlendingModeColorize, kFilterNearest, Rgba(255, 255, 0));

arctic::Font::Draw
void Draw(Sprite to_sprite, const char *text, const Si32 x, const Si32 y, const TextOrigin origin=kTextOriginBottom, const TextAlignment alignment=kTextAlignmentLeft, const DrawBlendingMode blending_mode=kDrawBlendingModeAlphaBlend, const DrawFilterMode filter_mode=kFilterNearest, const Rgba color=Rgba(0xffffffff))
Draws a UTF-8 string containing one or more lines of text to the destination sprite.
Definition: font.h:630

arctic::kFilterNearest
@ kFilterNearest
Nearest neighbor filter.
Definition: easy_sprite.h:56

arctic::kTextOriginTop
@ kTextOriginTop
The top of the first text line.
Definition: font.h:190

arctic::kDrawBlendingModeColorize
@ kDrawBlendingModeColorize
Colorize.
Definition: easy_sprite.h:48

arctic::Rgba
Represents a color in RGBA format.
Definition: rgba.h:39

Font Format Requirements

The Arctic Engine font system ONLY supports bitmap fonts in the following formats:

BMFont binary format (.fnt)
BMFont XML format (.xml)
ASCII square font format (16x16 grid)
Horizontal stripe font format
Table font format

TTF (TrueType Font) files are NOT supported. You must convert your TTF fonts to one of the supported bitmap formats using tools like BMFont (https://www.angelcode.com/products/bmfont/) before using them with the Arctic Engine.

Blending Modes

The Font class supports several blending modes for text rendering:

kDrawBlendingModeColorize: Applies the specified color to the text while preserving its shape and transparency. Works best with black and white fonts. This is the recommended mode for text output.
kDrawBlendingModeSolidColor: Replaces all colors of the font with the specified color. This may work with a pre-colored font file.

Text Origins

The origin determines the reference point for positioning text:

kTextOriginTop: The top of the text is at the specified y-coordinate
kTextOriginFirstBase: The baseline of the first line is at the specified y-coordinate
kTextOriginBottom: The bottom of the text is at the specified y-coordinate
kTextOriginCenter: The center of the text is at the specified y-coordinate

Text Alignment

The alignment determines how text is positioned horizontally:

kTextAlignmentLeft: Text is aligned to the left of the specified x-coordinate
kTextAlignmentCenter: Text is centered at the specified x-coordinate
kTextAlignmentRight: Text is aligned to the right of the specified x-coordinate

Constructor & Destructor Documentation

◆ Font()

arctic::Font::Font ( const Font & font )

inline

Copy constructor.

Parameters

font	The font to copy

Member Function Documentation

◆ AddGlyph() [1/2]

void arctic::Font::AddGlyph ( const Glyph & glyph )

inline

Adds a glyph to the font.

Parameters

[in] glyph Glyph to add.

◆ AddGlyph() [2/2]

void arctic::Font::AddGlyph	(	Ui32	codepoint,
		Si32	xadvance,
		Sprite	sprite
	)

inline

Adds a glyph to the font.

Parameters

[in]	codepoint	UTF32 codepoint the glyph represents.
[in]	xadvance	The increment of the 'cursor' x position used for font rendering. \|XXXXXXX \|XXXXXXX X X X X X X X X \|XXXXXXX \|XXXXXXX \| \| \|<------->\| xadvance
[in]	sprite	The Sprite containing the graphical representation of the glyph.

◆ CreateEmpty()

void arctic::Font::CreateEmpty	(	Si32	base_to_top,
		Si32	line_height
	)

inline

Creates an empty font with no glyphs.

Parameters

[in]	base_to_top	Glyph height from base to top.
[in]	line_height	Line height for the font.

◆ Draw() [1/4]

void arctic::Font::Draw	(	const char *	text,
		const Si32	x,
		const Si32	y,
		const TextOrigin	origin,
		const TextAlignment	alignment,
		const DrawBlendingMode	blending_mode,
		const DrawFilterMode	filter_mode,
		const std::vector< Rgba > &	palete
	)

Draws a UTF-8 string containing one or more lines of text to the backbuffer (directly to the screen) using a color palette.

Parameters

[in]	text	UTF-8 c-string with one or more lines of text (separated either with `/n`, `/r` or both)
[in]	x	X screen coordinate to draw text at.
[in]	y	Y screen coordinate to draw text at.
[in]	origin	The origin that will be located at the specified screen coordinates.
[in]	alignment	The alignment that will be used for the text.
[in]	blending_mode	The blending mode to use when drawing the text.
[in]	filter_mode	The filtering mode to use when drawing the text.
[in]	palete	The vector of Rgba colors used to colorize the text by some blending modes (for example, the kDrawBlendingModeColorize blending mode). Characters with codepoints <= 8 are considered the color-control characters and select the color from the palette for the following text.

Example:

// Create a color palette with 3 colors
std::vector<Rgba> palette;
palette.push_back(Rgba(255, 255, 255)); // White (index 0)
palette.push_back(Rgba(255, 0, 0));     // Red (index 1)
palette.push_back(Rgba(0, 255, 0));     // Green (index 2)
 
// Draw text with color control characters
// \1 switches to red, \2 switches to green
gameFont.Draw("Normal \1Red \2Green", 20, 100, kTextOriginTop, 
              kTextAlignmentLeft, kDrawBlendingModeColorize, kFilterNearest, 
              palette);

Here is the call graph for this function:

◆ Draw() [2/4]

void arctic::Font::Draw	(	const char *	text,
		const Si32	x,
		const Si32	y,
		const TextOrigin	origin = `kTextOriginBottom`,
		const TextAlignment	alignment = `kTextAlignmentLeft`,
		const DrawBlendingMode	blending_mode = `kDrawBlendingModeAlphaBlend`,
		const DrawFilterMode	filter_mode = `kFilterNearest`,
		const Rgba	color = `Rgba(0xffffffff)`
	)

Draws a UTF-8 string containing one or more lines of text to the backbuffer (directly to the screen)

Parameters

[in]	text	UTF-8 c-string with one or more lines of text (separated either with `/n`, `/r` or both)
[in]	x	X screen coordinate to draw text at.
[in]	y	Y screen coordinate to draw text at.
[in]	origin	The origin that will be located at the specified screen coordinates. kTextOriginTop: The top of the text is at the specified y-coordinate kTextOriginFirstBase: The baseline of the first line is at the specified y-coordinate kTextOriginBottom: The bottom of the text is at the specified y-coordinate kTextOriginCenter: The center of the text is at the specified y-coordinate
[in]	alignment	The alignment that will be used for the text. kTextAlignmentLeft: Text is aligned to the left of the specified x-coordinate kTextAlignmentCenter: Text is centered at the specified x-coordinate kTextAlignmentRight: Text is aligned to the right of the specified x-coordinate
[in]	blending_mode	The blending mode to use when drawing the text. kDrawBlendingModeColorize: Best for colored text (applies the color parameter) kDrawBlendingModeSolidColor: Replaces all colors of the font with the specified color. kDrawBlendingModeAlphaBlend: Standard alpha blending
[in]	filter_mode	The filtering mode to use when drawing the text. kFilterNearest: Pixel-perfect rendering (recommended for pixel art) kFilterBilinear: Smooth rendering (better for high-resolution text)
[in]	color	The color used by some blending modes (for example, the kDrawBlendingModeColorize blending mode).

Example:

// Draw score text at the top of the screen in white
gameFont.Draw("Score: 100", 20, screenHeight - 20, kTextOriginTop, 
              kTextAlignmentLeft, kDrawBlendingModeColorize, kFilterNearest, 
              Rgba(255, 255, 255));
 
// Draw centered game over text in yellow
gameFont.Draw("Game Over", screenWidth/2, screenHeight/2, kTextOriginCenter, 
              kTextAlignmentCenter, kDrawBlendingModeColorize, kFilterNearest, 
              Rgba(255, 255, 0));

Here is the call graph for this function:

◆ Draw() [3/4]

void arctic::Font::Draw	(	Sprite	to_sprite,
		const char *	text,
		const Si32	x,
		const Si32	y,
		const TextOrigin	origin,
		const TextAlignment	alignment,
		const DrawBlendingMode	blending_mode,
		const DrawFilterMode	filter_mode,
		const std::vector< Rgba > &	palete
	)

inline

Draws a UTF-8 string containing one or more lines of text to the destination sprite.

Parameters

[in]	to_sprite	Destination sprite.
[in]	text	UTF-8 c-string with one or more lines of text (separated either with `/n`, `/r` or both)
[in]	x	X destination sprite coordinate to draw text at.
[in]	y	Y destination sprite coordinate to draw text at.
[in]	origin	The origin that will be located at the specified coordinates.
[in]	alignment	The alignment that will be used for the text.
[in]	blending_mode	The blending mode to use when drawing the text.
[in]	filter_mode	The filtering mode to use when drawing the text.
[in]	palete	The vector of Rgba colors used to colorize the text by some blending modes (for example, the kDrawBlendingModeColorize blending mode). Characters with codepoints <= 8 are considered the color-control characters and select the color from the palette for the following text.

◆ Draw() [4/4]

void arctic::Font::Draw	(	Sprite	to_sprite,
		const char *	text,
		const Si32	x,
		const Si32	y,
		const TextOrigin	origin = `kTextOriginBottom`,
		const TextAlignment	alignment = `kTextAlignmentLeft`,
		const DrawBlendingMode	blending_mode = `kDrawBlendingModeAlphaBlend`,
		const DrawFilterMode	filter_mode = `kFilterNearest`,
		const Rgba	color = `Rgba(0xffffffff)`
	)

inline

Draws a UTF-8 string containing one or more lines of text to the destination sprite.

Parameters

[in]	to_sprite	Destination sprite.
[in]	text	UTF-8 c-string with one or more lines of text (separated either with `/n`, `/r` or both)
[in]	x	X destination sprite coordinate to draw text at.
[in]	y	Y destination sprite coordinate to draw text at.
[in]	origin	The origin that will be located at the specified coordinates.
[in]	alignment	The alignment that will be used for the text.
[in]	blending_mode	The blending mode to use when drawing the text. kDrawBlendingModeColorize: Best for colored text (applies the color parameter) kDrawBlendingModeSolidColor: Replaces all colors of the font with the specified color. kDrawBlendingModeAlphaBlend: Standard alpha blending
[in]	filter_mode	The filtering mode to use when drawing the text. kFilterNearest: Pixel-perfect rendering (recommended for pixel art) kFilterBilinear: Smooth rendering (better for high-resolution text)
[in]	color	The color used by some blending modes (for example, the kDrawBlendingModeColorize blending mode).

Example:

// Draw red text on a sprite
Sprite mySprite;
mySprite.Create(Vec2Si32(200, 100));
gameFont.Draw(mySprite, "Hello World", 10, 50, kTextOriginCenter, 
              kTextAlignmentLeft, kDrawBlendingModeColorize, kFilterNearest, 
              Rgba(255, 0, 0));

◆ FontInstance()

const std::shared_ptr< FontInstance > & arctic::Font::FontInstance ( ) const

inline

Gets the internal font instance.

Returns: Pointer to the internal font instance

Here is the caller graph for this function:

◆ IsEmpty()

bool arctic::Font::IsEmpty ( ) const

inline

Checks if the font is empty (has no codepoints)

Returns: True if the font has no codepoints, false otherwise

◆ Load()

void arctic::Font::Load ( const char * file_name )

inline

Loads the font from file.

Parameters

[in] file_name Path to the *.fnt or *.xml font file to load.

This method loads a font from a file. The file must be in one of the following formats:

BMFont binary format (.fnt) - Most common format, created by BMFont tool
BMFont XML format (.xml) - Alternative format for BMFont

The font file must be accompanied by its corresponding texture file(s) in the same directory. For example, if you have "font.fnt", you should also have "font_0.tga"

Note: TTF (TrueType Font) files are NOT supported. You must convert your TTF fonts to BMFont format using tools like BMFont (https://www.angelcode.com/products/bmfont/) before using them.

Exceptions

Fatal error if the file extension is not recognized or the file cannot be loaded

◆ LoadAsciiSquare()

void arctic::Font::LoadAsciiSquare	(	const char *	file_name,
		bool	is_dense
	)

inline

Loads an ASCII square font from a file.

Parameters

[in]	file_name	Path to the font file
[in]	is_dense	Whether the font is densely packed

◆ LoadBinaryFnt()

void arctic::Font::LoadBinaryFnt ( const char * file_name )

inline

Loads a binary BMFont file.

Parameters

[in] file_name Path to the binary BMFont file

◆ LoadHorizontalStripe()

void arctic::Font::LoadHorizontalStripe	(	Sprite	sprite,
		const char *	utf8_letters,
		Si32	base_to_top,
		Si32	line_height,
		Si32	space_width
	)

inline

Loads a font from a horizontal stripe of glyphs.

Parameters

[in]	sprite	Sprite containing the glyph stripe
[in]	utf8_letters	UTF-8 encoded string of letters in the sprite
[in]	base_to_top	Distance from baseline to top of the font
[in]	line_height	Height of a line of text
[in]	space_width	Width of the space character

◆ LoadTable()

void arctic::Font::LoadTable	(	Sprite	sprite,
		const char *	utf8_letters,
		Si32	cell_width,
		Si32	cell_height,
		Si32	base_to_top,
		Si32	line_height,
		Si32	space_width,
		Si32	left_offset
	)

inline

Loads a font from a table of glyphs.

Parameters

[in]	sprite	Sprite containing the glyph table
[in]	utf8_letters	UTF-8 encoded string of letters in the sprite
[in]	cell_width	Width of each cell in the table
[in]	cell_height	Height of each cell in the table
[in]	base_to_top	Distance from baseline to top of the font
[in]	line_height	Height of a line of text
[in]	space_width	Width of the space character
[in]	left_offset	Left offset of glyphs within cells

◆ LoadXml()

void arctic::Font::LoadXml ( const char * file_name )

inline

Loads a font from an XML file.

Parameters

[in] file_name Path to the XML font file

The documentation for this class was generated from the following files:

/builds/seaice/arctic/engine/font.h
/builds/seaice/arctic/engine/font.cpp

Public Member Functions

Detailed Description

Basic Usage

Font Format Requirements

Blending Modes

Text Origins

Text Alignment

Constructor & Destructor Documentation

◆ Font()

Member Function Documentation

◆ AddGlyph() [1/2]

◆ AddGlyph() [2/2]

◆ CreateEmpty()

◆ Draw() [1/4]

◆ Draw() [2/4]

◆ Draw() [3/4]

◆ Draw() [4/4]

◆ FontInstance()

◆ IsEmpty()

◆ Load()

◆ LoadAsciiSquare()

◆ LoadBinaryFnt()

◆ LoadHorizontalStripe()

◆ LoadTable()

◆ LoadXml()