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.
The files
Section titled “The files”| 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.
Making textures and fonts
Section titled “Making textures and fonts”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.
texconv:texconv.exefrom the DirectXTex releases.MakeSpriteFont:MakeSpriteFont.exefrom the DirectX Tool Kit releases.
A texture from a PNG, run from a starter project’s folder, C:\dev\mygame:
texconv -f R8G8B8A8_UNORM -m 1 -pmalpha --ignore-srgb -y -o game\content\textures hero.pngThis 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:
MakeSpriteFont "JetBrains Mono" game\content\fonts\jetbrains_mono_bold_16.spritefont /FontSize:16 /FontStyle:BoldThe 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 font and its licence
Section titled “The template’s font and its licence”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:
L"Hello from the engine.", font_name, this->motion_.centre, resources,samples/minimal/states/hello_state.cpp, lines 86–88 at 0f4f503
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:
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);}samples/linesweeper/states/pause_state.cpp, lines 69–75 at 0f4f503
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.
From a string table to text
Section titled “From a string table to text”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> const char* path){ const std::string utf8 = document.root().string("title"); 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,}tests/assets/string_table_text_tests.cpp, lines 35–51 at 0f4f503
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.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.
Wrap text when it changes
Section titled “Wrap text when it changes”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); &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.
Which languages the text path can draw
Section titled “Which languages the text path can draw”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.
Sprites from a sheet
Section titled “Sprites from a sheet”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:
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);samples/components/gallery_state.cpp, lines 68–73 at 0f4f503
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
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_;}samples/components/animation_preview.cpp, lines 31–57 at 0f4f503
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:
{ sheet->draw(draw_list, strip.frame_rect(this->frame_index_), destination, colour);}samples/components/animation_preview.cpp, lines 70–76 at 0f4f503
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.
Solid rectangles
Section titled “Solid rectangles”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:
void CollisionState::init(){ 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();samples/collision/collision_state.cpp, lines 32–37 at 0f4f503
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, lines 100–105 at 0f4f503
draw_sprite takes a source rectangle in texels, here the one pixel, and a destination rectangle
in world space, here the whole screen.
Colours and blending
Section titled “Colours and blending”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:
float alpha){ return labrador::Colour(colour.r * alpha, colour.g * alpha, colour.b * alpha, alpha);}samples/linesweeper/presentation/palette.h, lines 191–196 at 0f4f503
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:
float brightness){ return labrador::Colour(colour.r * brightness, colour.g * brightness, colour.b * brightness, 0.0f);}samples/linesweeper/presentation/palette.h, lines 217–222 at 0f4f503
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.
Filtering
Section titled “Filtering”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:
{ draw_list.draw_sprite(this->texture_, 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.