Skip to main content

​
Overview

The text rendering system provides support for loading TrueType fonts, managing font atlases, and rendering text with proper kerning and positioning. Text objects can be added to scenes as UI elements.

​
Font

The Font structure manages font resources and glyph atlases.

​
Properties

​
name
string
The name of the font.
​
atlas
FontAtlas
The font atlas that contains the glyphs for this font (map of char to Character).
​
size
int
The size of the font in pixels.
​
resource
Resource
The resource associated with the font.
​
texture
shared_ptr<opal::Texture>
The texture atlas containing all glyphs.

​
Static Methods

​
Font::fromResource
static Font
Creates a font from a resource.Parameters:
  • fontName - The name to associate with the font
  • resource - The resource from which to create the font
  • fontSize - The size of the font in pixels
Returns: Font instance
​
Font::getFont
static Font&
Gets the font associated with the given name.Parameters:
  • fontName - The name of the font to retrieve
Returns: Reference to the requested font

​
Methods

​
changeSize
void
Changes the size of the font. This will regenerate the font atlas.Warning: This operation is expensive. Use it when performance is not a concern.Parameters:
  • newSize - The new size for the font in pixels

​
Character

Structure representing a single character glyph in the font atlas.
​
size
Size2d
The size of the glyph.
​
bearing
Position2d
The offset from the baseline to the top-left of the glyph.
​
advance
unsigned int
The advance width of the glyph (horizontal spacing to next character).
​
uvMin
Position2d
The top-left UV coordinate in the atlas texture.
​
uvMax
Position2d
The bottom-right UV coordinate in the atlas texture.

​
Text

The Text class represents a text object that can be rendered in the game world or UI.

​
Constructors

​
Text
constructor (default)
Creates an empty text object.
​
Text
constructor (parameterized)
Creates a text object with the given parameters.Parameters:
  • text - The text content to display
  • font - The font with which to render the text
  • position - The position of the text in 2D space (default: {0, 0})
  • color - The color of the text (default: Color::white())

​
Properties

​
content
string
The content of the text to render.
​
font
Font
The font used to render the text.
​
position
Position2d
The position of the text in 2D screen space.
​
color
Color
default:"Color::white()"
The color of the text.

​
Methods

​
initialize
void
Prepares vertex buffers, shader state, and fonts for runtime use. Called automatically when added to a scene.
​
render
void
Renders the text glyphs to the screen honoring kerning and font metrics.Parameters:
  • dt - Delta time since last frame
  • commandBuffer - Command buffer for rendering
  • updatePipeline - Whether to update the pipeline (default: false)

​
FontAtlas

​
FontAtlas
typedef
A map that associates characters with their corresponding glyph information.Type: std::map<char, Character>

​
Example Usage

// Load a font from a resource
Resource fontResource = Workspace::get().getResource("MyFontResource");
Font myFont = Font::fromResource("MyFont", fontResource, 48);

// Retrieve the font later by name
Font& retrievedFont = Font::getFont("MyFont");

// Change the size of the font
retrievedFont.changeSize(72);

// Create a text object
Text titleText("Atlas Engine", myFont, {100, 50}, Color::white());

// Modify text properties
titleText.content = "Welcome to Atlas!";
titleText.position = {150, 100};
titleText.color = Color(1.0f, 0.8f, 0.0f, 1.0f); // Golden color

// Add the text object to the scene
scene.addObject(&titleText);

// Create a score display
Font scoreFont = Font::fromResource("ScoreFont", 
    Workspace::get().getResource("ScoreFontResource"), 32);
Text scoreText("Score: 0", scoreFont, {10, 10}, Color::green());
scene.addObject(&scoreText);

// Update score text dynamically
int score = 1000;
scoreText.content = "Score: " + std::to_string(score);

// Create colored text labels
Text redLabel("Health", myFont, {20, 100}, Color::red());
Text blueLabel("Mana", myFont, {20, 150}, Color::blue());
Text greenLabel("Stamina", myFont, {20, 200}, Color::green());

scene.addObject(&redLabel);
scene.addObject(&blueLabel);
scene.addObject(&greenLabel);

// Create multi-line text by using multiple Text objects
Font bodyFont = Font::fromResource("BodyFont",
    Workspace::get().getResource("BodyFontResource"), 24);

Text line1("Line 1: Welcome", bodyFont, {50, 300}, Color::white());
Text line2("Line 2: to the game", bodyFont, {50, 330}, Color::white());
Text line3("Line 3: Have fun!", bodyFont, {50, 360}, Color::white());

scene.addObject(&line1);
scene.addObject(&line2);
scene.addObject(&line3);

// Create a centered title
Font titleFont = Font::fromResource("TitleFont",
    Workspace::get().getResource("TitleFontResource"), 64);

Text centeredTitle("ATLAS", titleFont);
centeredTitle.position = {window.getWidth() / 2 - 100, 50};
centeredTitle.color = Color(1.0f, 1.0f, 1.0f, 1.0f);
scene.addObject(&centeredTitle);

​
Notes

  • Text rendering uses a font atlas texture to efficiently render multiple characters
  • The Character structure stores glyph metrics including size, bearing, advance, and UV coordinates
  • Font sizes can be changed dynamically but this regenerates the atlas (expensive operation)
  • Text objects inherit from UIObject and are rendered as 2D screen-space elements
  • Position coordinates are in screen pixels (0,0 is typically top-left)
  • Colors support alpha transparency for fade effects
  • The font system automatically handles glyph spacing and kerning
  • Multiple font sizes require separate Font instances

Build docs developers (and LLMs) love

Get started for freeTalk to us