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 or .png A PNG from any paint program, as it is; or 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 or .png, and .json, with the same name A texture, plus a JSON file naming rectangles in it (below).

A PNG is read in whatever colour type it was saved, decoded to 32-bit colour and premultiplied as it loads. Its gamma and colour-profile chunks are not applied. It costs four bytes a pixel on the graphics card and a decode each time it loads, so a game with many or large pictures converts them to a block-compressed .dds instead. A name with both a .dds and a .png in its folder is refused, naming both.

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

The selected device’s texture dimensions

Section titled “The selected device’s texture dimensions”

Renderer::texture_dimension_limit() reports the selected API device’s maximum 2D texture width or height in texels. It returns an optional value: absence means the limit is unavailable, including before successful device creation, while a device is lost or being recreated, and with the null renderer, which has no graphics device. Restoration refreshes the new device’s limit before notifying the game. See the renderer contract for its lifetime.

This query is newer than the released v0.3.0 starter. Use the development engine or a release that contains it; update a starter or move a submodule pin before using it in an older project.

Each dimension must fit a known device bound. An oversized upload stops before allocation and names the texture, the requested width and height, and that bound. Fitting does not guarantee that the device supports the image’s format or has enough memory to allocate it. The PNG reader separately refuses dimensions above 16384 before decoding; a higher device limit does not raise that admission cap. A DDS carries its pixel bytes and has no PNG admission cap, but its data, format and device bounds are still checked.

RenderResources::texture_size(texture) answers a different question: the width and height of one loaded texture. Neither dimension query changes the number of texture names the Direct3D 12 backend can hold:

The Direct3D 12 backend holds at most 256 distinct texture names, because its textures sit in one fixed-size table on the graphics card. Every texture, every sprite sheet and every font’s atlas takes one name, and the engine’s own one-pixel white texture takes another, so a game has 255. Loading a 256th name of the game’s own throws at load with Texture '<name>' does not fit, giving the limit. Loading a name that is already there again reuses its place and takes no new one. The other backends have no such count.

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 unscaled layout size. Include engine/render/text_alignment.h and pass that size to aligned_text_position, with a point or rectangle to align against, a TextAlignment and an explicit TextSnapping choice. It returns the position for unrotated text drawn with zero origin. Pass the same scale as the draw, or use a size already scaled by your game with the helper’s default scale of one. Multiline text aligns as one measured block; its shorter lines keep their own left margin.

This helper is in the development engine after v0.3.0; that release’s starter does not have it. Use a source checkout containing the helper, or the release that carries it. Update a starter and Move your engine pin explain the two update routes.

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 aligned_text_position(size,
RectangleF(0.0f, y, landscape_width, 0.0f),
}

This call selects TextSnapping::floor, which rounds the final coordinates down to whole board-space units. At the sample’s identity camera those units are pixels. 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.

TextSnapping::none keeps fractional positions. The touch labels use that choice with their scaled measurements; the helper does not silently round every scale. A camera can still map a whole board-space coordinate to a fraction of a screen pixel. The engine has no layout system: the anchor, alignment, scale and snapping are numbers and choices your game supplies.

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 }
]
}

For an evenly spaced grid, the standard-library Python command grid_sheet.py writes this existing format from the image size, grid columns/rows and named cells. The animation guide’s generation command creates its lamp definition without calculating source rectangles. The tool is development authoring code, absent from the v0.3.0 starter, and needs no image decoder. The input and boundary contract includes empty strips, the count limit and deterministic ordering. Hand-authored definitions remain supported.

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.

The loader also checks the rectangles against the loaded atlas dimensions. For each axis, both endpoints (x and x + w, or y and y + h) must be between zero and the atlas dimension, including its outer edge. Negative widths and heights remain valid: a frame such as x: 32, w: -16 samples the texels between 16 and 32 in reverse order. Every expanded animation-strip frame must fit too. An out-of-atlas definition stops loading with the sheet path and offending frame or strip; move or resize that region, or supply the intended larger atlas. The loader does not clamp or wrap the definition.

Individual zero-area frames remain accepted when their endpoints fit. A nonempty animation strip still refuses zero width or height; a strip with frame_count: 0 remains empty and its unused first-frame rectangle is not checked against the atlas. Origins remain pivots and may lie outside a frame.

If you call the reader directly rather than loading a manifest, pass the atlas dimensions as its third argument:

const labrador::TextureHandle texture = resources.resolve_texture("hero");
"textures/hero.json", texture, resources.texture_size(texture));

The declaration is in engine/assets/sprite_sheet_loader.h. A tool that has decoded an atlas without a renderer can instead pass labrador::Vector2I(atlas.width, atlas.height) from its TextureData. Device restoration reloads texture storage while retaining sheet definitions; a replacement atlas must still contain every retained frame and strip. This path does not reparse or revalidate the definitions.

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");
const TextureHandle white = resources->resolve_texture(white_texture_name);
this->arena_ = std::make_unique<Arena>(white);
this->outlines_ = components::ShapeOutline(white);
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 .dds texture must arrive premultiplied, because the engine does no premultiplication when it loads one. A PNG is premultiplied as it loads, so a PNG that is premultiplied already comes out with darkened edges. 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.

A sheet frame drawn under linear can pick up its neighbour. Linear blends the texels around each point it samples, and a frame’s source rectangle is mapped edge to edge with no inset, so a point within half a texel of a frame’s edge blends in the first texel on the other side of it. That texel belongs to whatever is next to the frame in the sheet. It shows as a thin line of the neighbouring frame’s colour along an edge of the sprite, when the frame is drawn bigger or smaller than its rectangle, rotated, or placed off a whole pixel. Only the texture’s own outer edge is protected, because sampling stops there; that is why the whole-texture picture above is safe. Under point each pixel takes one texel from inside the rectangle, and at its own size on whole pixels linear does the same.

For a frame that will be drawn under linear, keep its neighbours one texel away, which is as far as the blend reaches:

  • Separate frames in a sheet: leave at least one fully transparent texel between their rectangles. Most sheet packers have a spacing or padding setting for this.
  • Frames of an animation strip touch, because a strip steps by the first frame’s width. Draw each frame with a transparent border one texel wide inside its rectangle, so that what lies across every edge is transparent.
  • Tiles that must meet with no gap cannot have a transparent border, which would show as a faint seam between them. Draw those under point.

Development documentation (unreleased). Built from Labrador aceb130 of 2026-11-20.

All documentation versions