Sprite geometry
Generated from engine/render/sprite_geometry.h at f525bc6. 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).
vertices_per_sprite · indices_per_sprite
Section titled “vertices_per_sprite · indices_per_sprite”constexpr int vertices_per_sprite = 4;constexpr int indices_per_sprite = 6;A sprite's corners, and the indices of the two triangles over them.
quad_indices
Section titled “quad_indices”The 16-bit index list for sprites consecutive quads: for each, the triangles (0,1,2) and (1,3,2) counted from its first corner. A backend builds its index buffer from this once, for the most sprites one draw call takes. Throws std::invalid_argument for a negative count, or for one whose last corner has no 16-bit index (more than 16384 sprites).
struct PixelsToClip
Section titled “struct PixelsToClip”What a backend's vertex shader multiplies a vertex position by to take it from view pixels to clip space: a scale, then an offset, per axis. Sixteen bytes, in the order sprite.hlsl reads them.
x_scale
Section titled “x_scale”float x_scale = 0.0f;y_scale
Section titled “y_scale”float y_scale = 0.0f;x_offset
Section titled “x_offset”float x_offset = 0.0f;y_offset
Section titled “y_offset”float y_offset = 0.0f;pixels_to_clip
Section titled “pixels_to_clip”The transform for a pane width by height pixels: (2 / width, -2 / height, -1, 1), and a zero scale for a size that is not positive.
THIS IS WHERE Y RUNNING DOWN IS DECIDED. The seam's y increases down the screen and clip space's increases up, so the y scale is negative and its offset is +1 rather than -1. Every backend writes these four numbers. Where a pane sits in its buffer is the backend's own term: GL measures a viewport from the bottom, and Vulkan, whose clip space runs the other way, hands the rasteriser a negative viewport height. The pane's position is not in the transform, because the rasteriser maps clip space onto the viewport wherever it is.
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_world_bounds
Section titled “sprite_world_bounds” const RectangleF& destination,The axis-aligned box around the quad build_sprite_quad would build before truncation from the same destination, source, rotation and origin, measured in world units before the camera maps and truncates it.
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.
At zero units per pixel (layout) the box is tight around the untruncated corners. A cull passes the view's nonnegative world units per pixel, and the box grows by a bound on the quantization error: each truncated edge moves by less than one pixel and a size 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,page_crossing_frame.h,sprite_geometry_tests.cpp
Explained in
Section titled “Explained in”No guide or concept page links to this header yet.
Documentation for Labrador v0.4.0. Built from Labrador f525bc6 of 2026-11-17.