Skip to content

Sprites and text

Everything Labrador draws is a textured rectangle: a sprite. Text is sprites cut from a font’s glyph atlas, and a solid rectangle is a sprite from a texture one pixel across. This guide covers the files, the classes that draw them, and the colours. To put a first picture, animation or font into the starter project step by step, follow Put a picture in your game, Animate a sprite sheet and Fonts and text in your game instead; this page is the reference behind them. If a build fails after you change your drawing code, Read a build error shows how to read the error.

Kind File Made with
Texture .dds Any tool that writes DDS, such as texconv from Microsoft’s DirectXTex (below).
Font .spritefont MakeSpriteFont from Microsoft’s DirectX Tool Kit, which renders an installed font into an atlas (below).
Sprite sheet .dds and .json with the same name A texture, plus a JSON file naming rectangles in it (below).

A texture can be uncompressed 32-bit colour (R8G8B8A8 or B8G8R8A8), 16-bit B4G4R4A4, or block-compressed BC1, BC2 or BC3. Anything else is refused at load, with the file named. Each file is listed in the manifest by name, without its extension.

Both tools are free Windows programs from Microsoft, each a single executable attached to its project’s releases. Neither is needed to build or run the samples, and neither is a dependency of the engine. Install the content tools downloads both to C:\dev\tools, and the commands below assume they can be found by their short names, as its Typing the programs’ names sets up. They were checked with the may2026 release of each.

A texture from a PNG, run from a starter project’s folder, C:\dev\mygame:

Terminal window
texconv -f R8G8B8A8_UNORM -m 1 -pmalpha --ignore-srgb -y -o game\content\textures hero.png

This writes game\content\textures\hero.dds, and the folder must already exist. The -f is required: without it texconv keeps the PNG’s sRGB format, which only the DX10 extended header can describe, and the engine refuses that header at load. --ignore-srgb keeps the PNG’s colour values as they are. Without it texconv reads a PNG as sRGB and converts it to linear values on the way to the UNORM format, which the engine then draws as stored, so every colour between full and none comes out darker: an orange of red 255, green 165 is stored and drawn as green 96. -m 1 writes one level rather than a mip chain. -pmalpha multiplies each colour by its alpha, which is what the engine’s blending expects (Colours and blending, below). -y overwrites an existing file.

A font from an installed font:

Terminal window
MakeSpriteFont "JetBrains Mono" game\content\fonts\jetbrains_mono_bold_16.spritefont /FontSize:16 /FontStyle:Bold

The first argument is the family name of a font installed on the machine, for the user or for all users; a path to a font file is not accepted, and neither is a face’s full name such as JetBrains Mono Bold. A name it cannot find stops it with Can't find font, writing nothing. With no /CharacterRegion the atlas holds the 95 printable ASCII characters, U+0020 to U+007E. The tool premultiplies the alpha itself and writes a BC2 atlas, which the engine reads as it is. The template’s own atlas was built at these settings from the Bold face of JetBrains Mono 2.304, and the minimal sample’s README records the font’s and the atlas’s checksums, so a rebuild can be compared byte for byte.

Then list the new file in game\content\manifest.json. On Windows a folder of content is copied beside the executable by a line in game\CMakeLists.txt, and a new folder such as textures needs a line of its own (Assets).

The template’s only font, content/fonts/jetbrains_mono_bold_16.spritefont, is an atlas rendered from JetBrains Mono Bold, which is licensed under the SIL Open Font License 1.1. The licence is content/fonts/OFL.txt, beside the atlas, and starts with the font’s copyright line. You may ship the atlas in your game, whether you sell the game or not, provided OFL.txt goes with every copy of the atlas and the font is not sold on its own. The atlas stays under the OFL rather than your game’s licence. NOTICE records it with the repository’s other third-party terms. Every sample draws its text from the same atlas.

To use a different font, install it and run the MakeSpriteFont command above with its name. Then change the atlas’s name in content/manifest.json, in the font_name constant at the top of states/hello_state.cpp and states/confirm_state.cpp, and in the .spritefont path the browser build lists in CMakeLists.txt. Delete the JetBrains Mono atlas and its OFL.txt, and put the new font’s licence beside its atlas if the licence asks to travel with it.

There are three text classes, for three places text appears:

Class Is a Use it for
Label GameObject Text in a scene: added once, culled and drawn with everything else.
Text a drawable you draw yourself Text a state draws directly, without a scene.
UiText a widget A row in a menu that can take focus (Menus).

All three take the same core arguments: the text as a wide string, the font’s name from the manifest, a position, and the render resources the font is resolved against. The minimal sample’s greeting is a Label:

samples/minimal/states/hello_state.cpp
this->greeting_ = this->scene_->add(std::make_unique<Label>(
L"Hello from the engine.", font_name, this->motion_.centre, resources,

The font name is resolved to a handle in the constructor, so a misspelt name throws there, and the text is measured once whenever it changes rather than on every frame. set_text, set_position, set_colour and set_scale change it afterwards, from update().

Text is wide (std::wstring, written L"...") all the way to the renderer, so drawing it never converts or allocates. A font can only draw the characters it was made with. Before showing text that came from outside the game, such as a player’s name, check it with RenderResources::can_render(font, text).

Save C++ source files as UTF-8. Linking labrador_settings selects UTF-8 for MSVC’s source and ordinary narrow-literal encoding, matching the browser build. The language limits and the glyphs in your atlas still determine which text can draw.

Centring text means measuring it. RenderResources::measure_text(font, text) returns its size. LineSweeper’s pause menu centres each row this way when the menu is built, and the COLOURS row again each time it names a different palette:

samples/linesweeper/states/pause_state.cpp
Vector2F centred(const RenderResources& resources, FontHandle font,
const std::wstring& text, float y)
{
const Vector2F size = resources.measure_text(font, text);
return Vector2F(std::floor((landscape_width - size.x) * 0.5f), y);
}

The position is rounded down to a whole pixel. Half of an odd width is half a pixel, and text there sits with every pixel centre on the edge between two texels of its font. Each graphics backend picks between them its own way, and can tear a glyph doing it. Any other fraction draws as it would on the nearest whole pixel, under the point filter.

The engine has no layout system: positions are numbers your game works out, as here.

Your game owns its string table and chooses its keys and language. For one menu title, put this in content/strings/fr.json, saved as UTF-8:

{ "title": "Caf\u00e9" }

The JSON escape is precomposed U+00E9; the decoded string is the same as a UTF-8 file spelling that character directly. The template atlas holds only U+0020-U+007E, so it does not include this title’s last character.

Make an atlas that includes printable ASCII and U+00E9, using MakeSpriteFont’s /CharacterRegion option to select the required code points. The font you choose must contain those glyphs. One .spritefont holds one fixed rasterized size; /FontSize is specified in points, and scaling the result resamples its pixels. Build another atlas when you need a different rasterized size rather than expecting new glyph detail from scaling.

Name that font menu_bold_16 in your manifest and load it before building the text. Copy the source folder content/strings/ to strings/ beside the native executable using the Assets guide. Include that folder in the Release install list beside content/fonts too. The JSON file is read directly by your game; it needs no new manifest kind. The template’s browser build embeds the whole content folder at link time. Add content/strings/fr.json and the new font file to its existing LINK_DEPENDS list beside the manifest, so editing either relinks and repackages it too.

Read and convert at initialization or when the language changes:

#include "engine/app/content_root.h"
#include "engine/assets/json.h"
#include "engine/math/vector2f.h"
#include "engine/render/render_resources.h"
#include "engine/render/text.h"
#include "engine/render/text_encoding.h"
#include <stdexcept>
#include <string>
tests/assets/string_table_text_tests.cpp
labrador::Text load_menu_title(labrador::RenderResources& resources,
const char* path)
{
const std::string utf8 = document.root().string("title");
const std::wstring title = labrador::widen(utf8);
const std::string font_name = "menu_bold_16";
const labrador::FontHandle font = resources.resolve_sprite_font(font_name);
if (!resources.can_render(font, title))
{
throw std::runtime_error(document.source_path() +
": title has no glyph at UTF-16 unit " +
std::to_string(resources.first_unrenderable(font, title)));
}
return labrador::Text(title, font_name,
labrador::Vector2F(32.0f, 32.0f), &resources);
}

JsonValue views borrow their document, while string("title") returns an owned UTF-8 copy. widen creates the wide string once, and Text keeps its own copy, so the JSON document can be destroyed on return. The render-resource table is borrowed and must outlive the text. Keep the returned Text as a state member instead of reading the file again each frame:

// In init(), after the manifest has loaded the font; title_ is a Text member.
const std::string strings_path = labrador::resolved_under(
labrador::executable_directory(), "strings/fr.json");
this->title_ = load_menu_title(*this->app_->render_resources(),
strings_path.c_str());
// In the existing draw code, with the current view's DrawList.
this->title_.draw(draw_list);

The draw list is a loan for the current view; do not store it. The same wide storage can be drawn by several views without converting it again. read_json_file uses the path it is given, so the initialization code resolves the table under the executable directory rather than the process’s working directory. In the browser, that directory is the packaged file system’s /.

can_render checks that each required glyph is in this atlas. A stand-in does not turn missing coverage into success: for an atlas containing only ASCII and U+00E9, can_render(font, L"\u03A9") must report false. It does not establish shaping or visual quality; the language limits still apply, and the chosen font must be checked on screen.

After checking glyph coverage, RenderResources::wrap_text(font, text, width) returns an owned wide string with selected ordinary spaces (U+0020) replaced by line feeds. Font::wrap(text, width) is the same query when you already have a font. Use the font’s unscaled units, as for measure_text, and a finite positive width. To wrap the helper’s title above, replace its final return with:

const std::wstring wrapped = resources.wrap_text(font, title, 240.0f);
return labrador::Text(wrapped, font_name, labrador::Vector2F(32, 32),
&resources);

Here title, font and resources are the helper’s existing locals and parameter; the returned Text owns the wrapped copy. Wrap when the title, font or available width changes, rather than inside draw(). At text scale one the width is in the same units as the panel; for a positive text scale, divide the panel’s available width by that scale before wrapping.

Exact fits stay together. Existing line feeds and carriage returns are preserved, as are all spaces not selected for replacement. Nothing is trimmed or collapsed: leading, trailing or repeated visible spaces can produce empty lines at a narrow width. Tabs, nonbreaking spaces and hyphens are not automatic break points. An unbroken word can remain wider than the limit. The result uses the existing glyph fallback and missing-glyph errors; wrapping does not replace the can_render coverage check.

Scripts without spaces are left unbroken because the glyph walk supplies no language-specific line-breaking rules. Those rules remain the game’s, along with whether to wrap, shrink or clip a string and where to place it. The language limits still apply.

Text is drawn one glyph per code unit, left to right, with each glyph’s own advance. There is no kerning, no shaping or ligatures, no right-to-left or bidirectional ordering, and no combining mark placed over the letter before it: a mark is a glyph of its own that moves the pen. The only line break is \n.

So a script in which every character is one precomposed glyph is in reach, given a font made with those characters:

In reach Out of reach
Latin with precomposed accents (é, not e plus a combining accent) Arabic and Hebrew, which are right-to-left and joined
Greek and Cyrillic Devanagari and the other Indic scripts, and Thai, which need shaping and placed marks
Chinese, Japanese kana and kanji, and Korean Hangul syllables Emoji and anything else outside the Basic Multilingual Plane

No font in this repository holds anything but printable ASCII, so none of these scripts has been drawn here; a large character set is also a large atlas, which is your game’s to size.

A character beyond the Basic Multilingual Plane (above U+FFFF) is not supported. A narrow string converted with widen() holds it as two UTF-16 code units, which draw as two stand-in glyphs on every platform. A wide literal in your source does not agree across platforms: wchar_t is 16 bits on Windows and 32 in the browser build, so the same L"..." is two units and two stand-ins on Windows but one unit and one stand-in in the browser. can_render reports either as text the font cannot draw.

A sprite sheet is one texture with named rectangles in it. Its JSON file lists frames, each a named rectangle, and animation strips, each a run of equal-sized frames laid out left to right from a first frame:

{
"sprite_frames": [
{ "name": "coin", "position": { "x": 0, "y": 0 }, "size": { "w": 16, "h": 16 } },
{ "name": "hero_idle", "position": { "x": 0, "y": 16 }, "size": { "w": 16, "h": 32 },
"origin": { "x": 8, "y": 32 } }
],
"animation_strips": [
{ "name": "hero_walk", "first_frame": { "x": 16, "y": 16, "w": 16, "h": 32 },
"frame_count": 6, "frame_time": 0.1, "looping": true }
]
}

origin is optional, in texels from the frame’s top-left; it is the point a sprite is placed and rotated by, such as the middle of a character’s feet. A sheet whose packer rotated frames to fit them is refused, because the engine draws frames as they are stored. rotated: false is accepted. Both top-level arrays are required and may be empty. Every field is checked when the sheet loads: missing, mistyped and unknown fields name the file, object/index and key. This includes position, size, origin and first-frame objects, so orgin is an error instead of silently choosing a zero origin. Correct misspellings and remove unsupported fields from these fixed definitions; your game’s own metadata can use its own JSON reader.

TextureObject draws one named frame from a sheet, and is designed to be inherited alongside GameObject, so your own class gets its drawing and keeps its own update. Its constructor takes the sheet name and the frame name. It has draw(draw_list, destination_rectangle) and draw(draw_list, position, scale), and a draw_with that takes the colour or flip as a parameter instead.

Because several views can draw the same TextureObject at once, a tint or flip that varies from draw to draw is passed through draw_with rather than set on the object first.

The engine has no animation player. The components gallery’s copyable AnimationPreview keeps elapsed time, looping, one-shot completion and restart in game code. The gallery resolves a named sheet and strip together, once at initialization:

samples/components/gallery_state.cpp
const RenderResources::SheetStrip loop_strip =
resources->resolve_sheet_strip("animation_preview", "pulse_loop");
const RenderResources::SheetStrip once_strip =
resources->resolve_sheet_strip("animation_preview", "pulse_once");
this->loop_preview_.emplace(*resources, loop_strip);
this->once_preview_.emplace(*resources, once_strip);

RenderResources::SheetStrip keeps the sheet and the strip handle paired; it belongs to the resource table that resolved it. That table must outlive the preview, and the sheet/strip definition must stay unchanged. A texture reload preserves the pair, so drawing looks up the sheet again instead of keeping a device texture pointer.

The original animation_preview DDS/JSON pair offers pulse_loop and pulse_once, each four 16x16 frames at 0.25 seconds per frame. The loop wraps after one second, while the one-shot holds its last frame after that frame’s full duration. The sample rejects negative or nonfinite time steps before mutation, treats zero as a no-op, and crosses several frames without a loop per frame. The gallery advances its clocks during update():

Show samples/components/animation_preview.cpp, 27 lines
samples/components/animation_preview.cpp
void AnimationPreview::update(float dt)
{
if (!std::isfinite(dt) || dt < 0.0f)
{
throw std::invalid_argument("AnimationPreview dt must be finite and nonnegative");
}
if (dt == 0.0f || this->finished_)
{
return;
}
// int count * finite float duration fits in double, as do two cycles.
// Reduce dt first: adding a huge dt directly would erase a small phase.
const double step = static_cast<double>(dt);
const double next_elapsed = this->looping_
? std::fmod(this->elapsed_ + std::fmod(step, this->duration_), this->duration_)
: std::min(this->elapsed_ + step, this->duration_);
const int last_frame = this->frame_count_ - 1;
const double position = next_elapsed / this->frame_time_;
// Clamp before conversion, including a rounded-up quotient at cycle end.
const int next_frame = position >= static_cast<double>(last_frame)
? last_frame : static_cast<int>(position);
this->elapsed_ = next_elapsed;
this->frame_index_ = next_frame;
this->finished_ = !this->looping_ && next_elapsed >= this->duration_;
}

Drawing uses the public AnimationStrip::frame_rect(index) accessor and passes that source rectangle to SpriteSheet::draw. It does not advance time, so several views can read the same preview:

samples/components/animation_preview.cpp
void AnimationPreview::draw(DrawList& draw_list,
const RectangleF& destination, const Colour& colour) const
{
const SpriteSheet* sheet = this->resources_->sprite_sheet(this->strip_.sheet());
const AnimationStrip& strip = sheet->animation_strip(this->strip_.strip());
sheet->draw(draw_list, strip.frame_rect(this->frame_index_), destination, colour);
}

R or gamepad X in the gallery restarts both previews. The sample README describes the controls, paired loader data and MIT artwork provenance. Its tests separate timing, real asset reads and null-render draw recordings from actual rendered-frame review.

There is no rectangle-drawing call, because a solid rectangle is a sprite from a texture one white pixel across, stretched and tinted. Colours, the window and the background uses one as the starter game’s background. The engine puts that texture in every game’s table, so no content file is needed: resolve it by white_texture_name, from engine/render/resource_factory.h, as the collision sample does:

samples/collision/collision_state.cpp
void CollisionState::init()
{
RenderResources* resources = this->app_->render_resources();
this->font_ = resources->resolve_sprite_font("jetbrains_mono_bold_16");
this->arena_ = std::make_unique<Arena>(resources->resolve_texture(white_texture_name));
this->refresh_view();

The application shell adds it when it sets up the table and again after a device restore. Code that builds its own Renderer and RenderResources, such as a test, calls add_white_texture(renderer, resources) itself. LineSweeper ships its own white texel instead, and every block, panel and line on its screen is that pixel stretched and tinted. This is the darkening layer its pause menu draws over the game:

samples/linesweeper/states/pause_state.cpp
void draw(DrawList& draw_list) const override
{
draw_list.draw_sprite(this->block_, RectangleI(0, 0, 1, 1),
*this->area_, faded(Colour(0.0f, 0.0f, 0.0f), scrim_alpha),
}

draw_sprite takes a source rectangle in texels, here the one pixel, and a destination rectangle in world space, here the whole screen.

Colour holds four floats from 0 to 1, and can be built from floats, from bytes (Colour(240, 152, 0)), or from a hex string. It has the usual named colours: Colour::white, Colour::goldenrod, Colour::dark_gray and so on.

Blending is premultiplied. A drawn pixel lands as source + destination × (1 − source alpha). For an ordinary translucent colour, multiply the colour by its alpha as well, which is what LineSweeper’s faded does:

samples/linesweeper/presentation/palette.h
constexpr labrador::Colour faded(const labrador::Colour& colour,
float alpha)
{
return labrador::Colour(colour.r * alpha, colour.g * alpha,
colour.b * alpha, alpha);
}

The same rule gives additive light for free. With alpha at zero the destination is untouched and the colour is simply added, so overlapping draws brighten towards white. That is LineSweeper’s glowing, and its whole particle effect:

samples/linesweeper/presentation/palette.h
constexpr labrador::Colour glowing(const labrador::Colour& colour,
float brightness)
{
return labrador::Colour(colour.r * brightness, colour.g * brightness,
colour.b * brightness, 0.0f);
}

A texture must arrive premultiplied, because the engine does no premultiplication at load. A .dds file’s texels are drawn as they are stored, so a soft-edged sprite is premultiplied when it is converted, which is what texconv’s -pmalpha does (Making textures and fonts, above). A texture converted without it keeps the full colour in its half-transparent edge texels and adds that colour to whatever is behind, which shows as a light fringe or halo round the sprite, and a fully transparent area whose colour is not black shows as a coloured box. Premultiplying a texture twice, by passing -pmalpha to a source that was already premultiplied, darkens its edges instead. MakeSpriteFont’s atlases are premultiplied by the tool.

DrawList::set_filter chooses between smooth (linear) and blocky (point) sampling when a texture is scaled, for every draw after it in that view. Pixel art usually wants point sampling. Changing the filter partway through a view is allowed and costs a little, so group draws by filter.

Point is the default. Every view starts each frame with TextureFilter::point, so pixel art drawn bigger than its texture is already blocky, and a starter project needs no line for it. For a picture that should be smoothed instead, such as a photograph drawn at twice its size, set linear in that object’s draw, just before its sprite, and set point back after it, so the objects drawn after it in the view stay blocky. In the Picture class from Put a picture in your game, draw becomes:

void draw(labrador::DrawList& draw_list) const override
{
draw_list.set_filter(labrador::TextureFilter::linear);
draw_list.draw_sprite(this->texture_,
labrador::RectangleI(0, 0, this->width_, this->height_),
this->bounds(), labrador::Colour::white, 0.0f,
draw_list.set_filter(labrador::TextureFilter::point);
}

At its own size a picture looks the same under either filter; the difference shows only when bounds() makes it bigger or smaller than the texture.

Documentation for Labrador v0.3.0. Built from Labrador 0f4f503 of 2026-11-03.

All documentation versions