Sprite geometry
Generated from engine/render/sprite_geometry.h at 0f4f503. The text under each declaration is the header's own comment, word for word. About the reference says how these pages are made.
Audience: renderer writer.
#include "engine/render/sprite_geometry.h" · namespace labrador
Where a sprite's four corners go, and what they sample.
THIS FILE IS THE PIXEL CONTRACT. Every term RenderPixelTests pins is decided here and nowhere else: that the destination is in pixels with y running down, that texel (0,0) lands at the destination's top left, that a flip mirrors the texture and not the rectangle, that the source rectangle is in texels, that the tint multiplies, that a fractional destination truncates with an exclusive right edge, and that the origin is measured in unscaled source texels.
A BACKEND DOES NOT DO THIS ARITHMETIC, WHICH IS THE WHOLE POINT. What a backend receives is four SpriteVertex in view pixels; what it owes is a buffer, a shader that multiplies each vertex by one four-float constant and the sampled texel by the vertex's own colour, and the state that makes the blend premultiplied. No two backends can disagree about where a sprite went, because none of them decides - the null backend included, which runs this file too, and that is what makes its recording worth asserting on.
THE ONE TERM A BACKEND STILL OWNS is where the pane itself sits in the thing being drawn into, because that is the one question whose answer is not the same shape on every API behind this seam. Direct3D measures a viewport down from the render target's top left and needs no height at all. GL measures up from the bottom and so has to subtract from one, which it reads from the window rather than from a cached copy, because a cached copy is wrong for the whole of every drag-resize (engine/render/gl/backend.h, Impl::drawable_size). Vulkan hands the rasteriser a viewport whose origin is the pane's BOTTOM edge and whose height is negative, which inverts y for the whole pipeline and makes the flip pane-local rather than buffer-relative - so the buffer's height never enters it (engine/render/vulkan/renderer.cpp). Each keeps the sentence above true rather than nearly true.
THE CORNER ORDER IS PART OF THE CONTRACT: 0 is the destination's top left, 1 its top right, 2 its bottom left, 3 its bottom right. A backend's index buffer is built from that and from nothing else, so the two triangles are (0,1,2) and (1,3,2).
build_sprite_quad
Section titled “build_sprite_quad” float rotation, const Vector2F& origin,Fills corners[4] for a sprite drawn into destination.
destination is in view pixels and source in texels of a texture texture_size texels across. origin is in UNSCALED SOURCE TEXELS - so an 8x8 destination over a 2x2 source scales an origin of two texels into a shift of eight pixels, which is the term the seam states and the one most often assumed to be destination pixels instead.
THE DESTINATION TRUNCATES. Each of its four edges is taken to a whole pixel by dropping the fraction, and the size is the difference of the truncated edges rather than the truncation of the size - which is not the same number, and is why this takes a rectangle rather than a position and a size. A right edge of 18.9 becomes 18 and is exclusive.
build_scaled_quad
Section titled “build_scaled_quad” float scale, const Vector2F& texture_size, float rotation, const Vector2F& origin,The same, for a sprite placed by a position and a uniform scale over its source rather than by a rectangle.
NOTHING TRUNCATES HERE, and that is the difference that matters. Text is laid out by this: a pen advance is fractional in most fonts, and rounding each glyph to a whole pixel would make a line of text drift against its own measurement. There is no flip because no caller flips text, and flipped text is named in RenderPixelTests as something nothing pins.
SO THIS IS WHERE THE CONTRACT STOPS DECIDING A PIXEL. A position half a pixel off a whole one puts every pixel centre on a texel edge, and the texel the point filter picks there is the rasteriser's rounding of an interpolated coordinate rather than anything written here. The caller avoids it, as renderer.h's draw_text says; a nudge applied here would move every fractional position to fix one of them.
build_glyph_quad
Section titled “build_glyph_quad” float scale, const Vector2F& pen, const Vector2F& texture_size, float rotation, const Vector2F& origin,One glyph of a line of text, at the pen the walk (font.h) reported.
position, scale, tint and rotation are the whole string's, and origin is the caller's origin for the string - all four the same for every glyph in it. What varies per glyph is glyph and pen.
THIS IS THE TERM THE WALK DELIBERATELY DOES NOT CARRY. for_each_glyph reports pen.y as the TOP OF THE LINE and leaves the glyph's own y_offset out, because measurement wants the line and drawing wants the bearing; this is where drawing adds it back.
The pen subtracts because it moves the glyph and an origin moves the string: shifting the origin left by the pen puts the glyph right of the string's position by exactly the pen. Both are in unscaled source texels, which is what build_scaled_quad already means by an origin, so the two compose without a conversion.
sprite_quad_bounds
Section titled “sprite_quad_bounds” const RectangleF& destination, float rotation,THE AXIS-ALIGNED BOX AROUND THE QUAD build_sprite_quad WOULD BUILD from the same four arguments: the same truncated edges, the same origin shift, the same turn about the destination's top left. Tight, not merely conservative - it is the bounding box of the four corners.
This is a view-space measurement, not a world-space cull bound. sprite_world_bounds accounts for the camera-dependent quantization. It lives here because it has to agree with build_sprite_quad to the term. The destination rectangle is where a sprite lands only when its origin is zero and its rotation is zero. An authored frame origin shifts the sprite by that many texels' worth of destination, and a rotation turns it about its top left, so a sprite at x=100 with an origin of its own width draws across x=80..100 - and a cull against x=100..120 would drop it from any view that ends at x=90 while it is plainly inside, on every backend at once, because none of them decides this.
origin is the WHOLE origin - the frame's authored one plus the caller's, summed the way SpriteSheet::draw sums them - in unscaled source texels, exactly as build_sprite_quad takes it.
sprite_world_bounds
Section titled “sprite_world_bounds” const RectangleF& destination,World geometry before view-space quantization, expanded by a bound on its error at nonnegative world units per pixel (zero for layout). Each truncated edge moves by less than one pixel; a size moves by less than two. Rotation mixes those errors and the source-relative pivot scales them, including origins outside the source rectangle.
text_quad_bounds
Section titled “text_quad_bounds” float scale, const Vector2F& measured_size, float rotation, const Vector2F& origin);The same, for a string laid out by build_glyph_quad: measured_size is the unscaled size of its enclosing local rectangle, and the box is that size, scaled, sitting origin scaled texels up and left of position, turned about position. Font::measure reports a layout extent; callers enclosing drawn glyph cells as well must include overhanging bearings and subtract the local rectangle's position from the text's original origin. The transform then keeps that origin fixed.
struct ResolvedTexture
Section titled “struct ResolvedTexture”A texture handle a backend has resolved: whatever its view's draw() records, and the size in texels that the quad arithmetic needs. Texture is a pointer, a reference or a handle, as the backend's draw() takes it.
texture
Section titled “texture”Texture texture;record_sprite
Section titled “record_sprite” float rotation,DrawList::draw_sprite once the backend has resolved the handle. The view's camera maps destination, build_sprite_quad builds the corners, and the view records them. View is the backend's DrawList::View; it has a camera and a draw(texture, corners). A template rather than a virtual call, because it runs once per sprite (T8).
record_text
Section titled “record_text” const std::wstring& text, float scale, float rotation, const Vector2F& origin);DrawList::draw_text once the backend has resolved the font's atlas. A glyph is a sprite: the font walks the text, build_glyph_quad places each glyph, and the view records it as record_sprite's view does.
struct RunRecorder
Section titled “struct RunRecorder”One view's recording for a backend that draws the frame from memory at submit: the corners of every sprite, and the runs that say what to draw them with. A draw touches no driver, which is what lets several workers record at once into an API that is single-threaded, or whose command pools are. The GL and Vulkan backends' DrawList::View is one of these; the Direct3D backends record into a deferred context and a command list instead. TextureKey is what a run compares to decide whether the next sprite joins it: a GL texture name, or a pointer to a Vulkan texture.
{ TextureKey texture{}; int first_sprite = 0; int sprites = 0;};A run of sprites that share everything a draw call fixes. Closed and pushed when any of the three changes, or at the end of the view.
Declared as RunRecorder::Run.
max_run_sprites
Section titled “max_run_sprites”static constexpr int max_run_sprites = 2048;How many sprites one run may hold. The backend builds its index buffer once for this many and draws each run from its first vertex, so a longer run is split rather than growing anything. 16-bit indices would allow 16384; 2048 is 256KB of vertices.
vertices
Section titled “vertices”open_valid
Section titled “open_valid”bool open_valid = false;The run being built. Not in runs until something closes it.
camera
Section titled “camera”filter
Section titled “filter”viewport
Section titled “viewport”Reset at the top of every frame, not carried across one.
touched
Section titled “touched”bool touched = false;Whether anything has been recorded into this view this frame. It is what makes a dropped view detectable - see Renderer::set_view_count.
record
Section titled “record”Appends one sprite's four corners, joining the open run when the texture, filter and viewport all match it and it has room.
The viewport term never answers false today: DrawList::set_viewport closes the run before it writes the new pane, and the other writes follow a reset(). It is kept so that the join is the whole predicate, not one that relies on its callers.
close_run
Section titled “close_run”void close_run();Pushes the open run if it holds anything.
void reset();Forgets the frame: every sprite and run, the camera and the filter.
Related types
Section titled “Related types”Named in the public declarations above: Camera, Colour, Font, Glyph, RectangleF, RectangleI, Run, SpriteFlip, SpriteVertex, TextureFilter, Vector2F, View, Viewport.
In the samples and tests
Section titled “In the samples and tests”The files that include this header directly. A file can also reach it through another header.
samples/linesweeper/presentation/top_out_banner.cpptests/render/label_tests.cpp,sprite_geometry_tests.cpp
Explained in
Section titled “Explained in”No guide or concept page links to this header yet.
Documentation for Labrador v0.3.0. Built from Labrador 0f4f503 of 2026-11-03.