Skip to content

Renderer

Generated from engine/render/renderer.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.

Browse the render module

Audience: game code.

#include "engine/render/renderer.h" · namespace labrador

The renderer seam: one header, several backends, one of them chosen at build time (T5).

THIS FILE STATES THE CONTRACT A CALLER IS HELD TO, and nothing else. Why the seam has the shape it does - why Renderer is concrete rather than an abstract base, how one header serves every backend, what a backend supplies and what it may never decide, and what holds the backends to one another - is engine/render/SEAM.md. Terms below cite it where the reason is longer than the rule.

using TextureHandle = Handle<Texture>;
using FontHandle = Handle<Font>;
enum class SpriteFlip
{
none,
horizontal,
vertical,
both,
};
enum class TextureFilter
{
point,
linear,
};

CONSTRAINT: sampler state lives inside the seam. The API never names a sampler object: the caller says what it wants the filtering to look like, and the backend owns the state that produces it, recreated with the device like everything else.

point is what a pixel-art client wants everywhere - linear filtering is what makes tile seams shimmer.

enum class RenderDeviceKind
{
hardware,
software,
null_device,
};

What kind of device the selected backend actually created.

null_device is not a software rasteriser. It means the null backend, which records draws and never produces pixels. The distinction is what lets a measurement refuse WARP or another CPU rasteriser without also refusing the deliberately headless configuration.

The device a Renderer selected, in backend-neutral terms.

A performance result without this record cannot say which hardware it measured: listing the machine's adapters is not enough when an API may select a different one or fall back to software. backend and api are stable engine-facing names; device_name is what the selected API reports for the device. Vendor and device IDs are zero where that API exposes no portable numeric answer (OpenGL and the null backend). Why this is a description rather than a device accessor is in engine/render/SEAM.md#3.

std::string backend;
std::string api;
std::string device_name;
std::uint32_t vendor_id = 0;
std::uint32_t device_id = 0;
RenderDeviceKind kind = RenderDeviceKind::null_device;
std::string present_mode;
std::optional<int> requested_swap_interval;
std::optional<int> reported_swap_interval;

The API's configured presentation policy, not measured scan-out. Intervals count video frames; absent means not applicable or, for reported_swap_interval, that the API supplies no state query. A reported value is driver state and cannot detect compositor overrides.

class DrawList

A recording target for one view.

CONSTRAINT: the unit of work is a view, not an object.

The render workers do NOT own disjoint slices of the object list - the parallelism axis is views, so every worker enters draw() on the SAME object at the same time. That is why draw() is const all the way down.

A DrawList is obtained from Renderer::view(i) and is valid until the next Renderer::submit(). It is a handle, not an owner: copying one is free and copies refer to the same recording.

DrawList() = default;
bool valid() const;

Whether this list can be drawn into. A default-constructed one cannot; every list from Renderer::view() can.

void set_viewport(const Viewport& viewport);

Restricts subsequent draws to this viewport, in back-buffer pixels.

const Viewport& viewport() const;

The pane the next draw lands in, in back-buffer pixels: the Viewport last given to set_viewport, as given rather than snapped to whole pixels, else the whole back buffer the list starts with, Viewport(0, 0, width, height). Valid only on a valid() list.

void set_camera(const Camera& camera);

World to view, for every draw recorded after it. Changing it mid-list is ordinary: a view draws the world through its camera and then the HUD over it in screen space.

The identity is Camera::default_camera, which is what a list starts with, so a caller that only ever wanted screen space never mentions a camera at all.

const Camera& camera() const;

The camera the next draw on this list is mapped through: the last set_camera on it this frame, else Camera::default_camera. Valid only on a valid() list. A draw() may read it to choose what it draws for this view, and must not store it: the list is gone at the next Renderer::submit(). SEAM.md#6 says why it is read here rather than passed to draw().

A DRAW THAT GROWS AS THE CAMERA ZOOMS OUT MUST SAY SO TO THE CULL. A minimum stroke, or detail chosen by zoom, can draw outside bounds(); such a drawable reports that growth through GameObject::cull_bounds(units_per_pixel), or the scene's cull may reject it at a pane edge.

void set_filter(TextureFilter filter);

Applies to every draw recorded after it. Changing it mid-list is legal and costs a flush, so group by filter if it matters.

IT CHOOSES BETWEEN TEXELS OF LEVEL ZERO AND NEVER BETWEEN LEVELS. A minified draw samples level zero however many levels the texture carries, under either filter. That is a term of this seam and not a backend's habit. Chains are read and uploaded - a .dds that has one is not rejected and its bytes reach the device - and nothing samples from them. SEAM.md#6 says why the other answer is not the engine's to give.

void draw_sprite(TextureHandle texture,
const RectangleI& source,
const RectangleF& destination,
const Colour& tint,
float rotation,
const Vector2F& origin,
SpriteFlip flip,
float layer_depth);

CONSTRAINT: call order decides what is on top, and layer_depth orders nothing.

Within one list a later draw covers an earlier one whatever depths the two were given, and submit() draws the lists in view order. No backend reads layer_depth: there is no depth buffer and no sort, which RenderPixelTests pins - "layer_depth does not order draws, call order does". A background is put behind a player by drawing it first. SEAM.md#6 says why it is still a parameter.

destination is in world space; the list's current camera maps it.

source selects a rectangle in texture texels. rotation is in radians, positive clockwise on screen, where y increases downward. origin is an offset from the source rectangle's top-left in unscaled source texels. The camera maps destination to view pixels and each edge truncates to a whole pixel. For nonzero source dimensions, origin scales by the resulting destination-to-source size ratio in each axis. That offset is subtracted from the quad's local corners before rotation about the mapped, truncated destination top-left. This point is the pivot position: zero origin anchors the source corner there, and half the source size anchors its centre. Flip mirrors the sampled texels without moving the quad or its pivot.

tint multiplies the sampled texel as given. Nothing premultiplies it for the caller, and the blend is premultiplied (SEAM.md#5), so a tint with zero alpha still adds its colour channels: the tint that draws nothing is Colour(0, 0, 0, 0).

void draw_text(FontHandle font,
const std::wstring& text,
const Vector2F& position,
const Colour& tint,
float scale,
float rotation,
const Vector2F& origin,
float layer_depth);

CONSTRAINT: the text entry point is wide, and there is no narrow overload (SEAM.md#6).

The position need not be a whole pixel, and under the point filter at a scale of one, text off a whole pixel draws as it would on the nearest one. EXACTLY HALF WAY IS THE EXCEPTION: every pixel centre is then a texel edge, and which texel it samples is decided by rounding inside the rasteriser, differently on different backends and even between the two triangles of one glyph. Centring by halving a measured width lands there whenever the width is odd, so take std::floor of a centred point-sampled position.

layer_depth orders nothing here either: text covers what was drawn before it in the list and is covered by what is drawn after it, as draw_sprite states. tint is taken as given, under the same premultiplied blend draw_sprite states.

Told when the device goes away and comes back.

Not a graphics type: a game object that has to rebuild something after a device loss implements this and knows nothing about what was lost.

AND NOT A QUESTION ABOUT WHICH BACKEND YOU BUILT. One game source is built against every backend (T5), so a shell handles device loss whether or not its own preset can lose a device. SEAM.md#8 says what the rebuild belongs to.

virtual void on_device_lost() = 0;
virtual void on_device_restored() = 0;
~DeviceNotify() = default;
class Renderer

The frame.

One per process. Owns the device, the swap chain, the per-view recording state, the sampler states, and the command-list lifetime.

~Renderer();
Renderer(Renderer&&) noexcept;
Renderer& operator=(Renderer&&) noexcept;
Renderer(const Renderer&) = delete;
Renderer& operator=(const Renderer&) = delete;
void create_device(void* native_window, int width, int height,
int view_capacity);

The shell hands the renderer its window, and says how many views the frame may ever fan out to - which sizes the recording state, because a backend that records into per-thread contexts has to make them before any frame starts. The window is the platform's handle as void*: the backend casts it back, and the null backend ignores it (SEAM.md#6).

Throws std::invalid_argument for a view capacity below one, before it touches a window. The GL backend on Windows requires WGL_EXT_swap_control and throws std::runtime_error if requesting its swap interval fails; in a browser there is no interval to request, and it throws std::invalid_argument for a null canvas handle and std::runtime_error if the canvas gives it no WebGL2 context.

const RenderDeviceInfo& device_info() const;

The actual device create_device selected. Throws std::logic_error before create_device, when there is no truthful answer. In particular, this is not an enumeration of what else the machine has: it names the adapter or implementation this Renderer is using.

bool window_size_changed(int width, int height);

Returns whether anything was rebuilt, which is the signal the shell wants for "re-run the layout".

CONSTRAINT: IT MAY ARRIVE IN THE MIDDLE OF A FRAME, AND A FRAME IN PROGRESS IS RESTARTED RATHER THAN REFUSED. A client that changes resolution from inside its own drawing reaches this with a frame open; SEAM.md#6 says why that cannot be the caller's rule to keep.

WHAT RESTARTED MEANS, EXACTLY, because a caller may be holding a DrawList when this lands and that list must not become a trap:

- Everything recorded into every view this frame is dropped. It was recorded against a buffer that no longer exists. - The views the frame declared are reopened against the new buffer, which is cleared as begin_frame would clear it. A DrawList the caller is holding stays valid and draws into the new frame. - view_count is unchanged, because the layout is the shell's to decide and this call is what tells it to decide again.

So the frame that was in progress contributes nothing, exactly as a frame begun and never submitted does (begin_frame below), and the caller sees one frame's drawing lost rather than an exception it has nowhere to catch.

AND BEFORE create_device IT REBUILDS NOTHING AND ANSWERS false, which is a statement about an ordering Win32 allows: a shell can be sent a WM_SIZE between making its window and making its device.

void set_device_notify(DeviceNotify* device_notify);

Borrowed; the shell owns it and outlives the renderer.

void set_resources(const RenderResources* resources);

The table the draw lists resolve handles against. Borrowed, like the notify above. Set after create_device, because the resource factory needs a device before it can load anything into a table (SEAM.md#6).

AND THE TEARDOWN ORDER IS FIXED THE OTHER WAY AGAIN. The table outlives the renderer, because on some backends it holds resources the GPU may still be reading - an ID3D12Resource on d3d12, a VkImage on vulkan - and the only wait for them is inside this class's destructor. render_resources.h states it beside release_device_resources, where the resources in question are.

void begin_frame();
void end_frame();

begin_frame clears the back buffer and resets every view's recording; end_frame presents.

A FRAME BEGUN AND NEVER SUBMITTED CONTRIBUTES NOTHING TO THE NEXT ONE, which is a statement about what "resets" means. A client reaches that by catching an exception out of its own draw walk and carrying on - and so does a device event, which surfaces as a throw from a worker mid-frame. What each backend resets to keep it is in SEAM.md#6.

A FRAME SUBMITTED AND NEVER PRESENTED IS LEGAL, and contributes nothing to the next one either: the next begin_frame starts over. It is the frame read_back_buffer below is for - drawn to be read rather than shown - and SEAM.md#6 is again where each backend's reset is.

void set_view_count(int count);
int view_count() const;
DrawList view(int index) const;

The scene declares how many views this frame has, then fills them. Throws std::out_of_range above the capacity create_device was given, and std::out_of_range for a view index outside the current count - asking for a view nobody set up must not quietly return a fullscreen pane and draw a whole extra pass (T6).

AND std::logic_error FOR A COUNT LOWERED PAST A VIEW SOMETHING HAS ALREADY DRAWN INTO, which is a different mistake and gets a different type: the recording is stranded rather than absent. Every backend throws it, which is what makes it a term of the seam rather than one backend's caution.

void submit();

CONSTRAINT: whatever a view recorded into, closing it is the seam's job and not a caller's.

Draws every view in view order, which is the only ordering guarantee made here, and leaves nothing of the frame behind. What that costs depends on the backend and is deliberately not described on this line; SEAM.md#6 has each backend's answer.

Called once per frame, between begin_frame and end_frame - AND A SECOND CALL ADDS NOTHING.

Vector2F back_buffer_size() const;

Back-buffer size in pixels.

THE SIZE OF THE BUFFER, NOT OF THE LAST THING ANYONE SAID. The two agree whenever the shell is keeping up, and the one state where they need not is a drag-resize, during which the shell discards every WM_SIZE and still asks for frames (engine/app/win32/window.cpp). A backend then answers whatever it is really drawing into, which SEAM.md#6 gives for each. read_back_buffer below is sized from this and a viewport is placed inside it, so both describe the buffer the backend actually drew into.

void read_back_buffer(std::vector<unsigned char>& pixels);

Copies the back buffer out: 8-bit RGBA, row-major, top row first, exactly width * height * 4 bytes. pixels is resized to fit.

RGBA REGARDLESS OF WHAT THE BACKEND STORES (SEAM.md#6).

A BACKEND MAY REFUSE, and one does. The null backend never rasterises, so it throws std::logic_error.

BETWEEN submit() AND end_frame(), because on the backends where a present discards what it presented there is nothing left to read afterwards. The interval is the narrow one every backend can keep, and tests/render/pixel_tests.cpp's "a frame may be read back and then presented" walks its far end.

Not const: reading the GPU's memory means staging a copy through the device, which is a write.

NOT A FRAME-PATH CALL and not meant to become one (T8). It stalls on the GPU by construction.

CAPTURING A FRAME FROM INSIDE A RUNNING Application IS DRAWING IT AGAIN. Application owns its frame and offers no point between its submit and its end_frame, so a game that wants the picture calls begin_frame, then the stack's draw - Application is a StateContext, so app.draw(*app.renderer()) - then submit and read_back_buffer, and does not call end_frame. That frame is submitted and never presented, which begin_frame above makes legal, and because every draw() is a pure read the second walk draws exactly the frame the stack would draw.

FROM AN update(), AFTER THE UPDATE WHOSE WORLD IT SHOULD SHOW HAS FINISHED, and never from a draw(). A capture issued halfway through the capturing state's own update draws a half-updated world, and one issued during one step of a catch-up tick shows that step's world rather than the one the tick ends on. What it promises is the frame the stack would draw, not what was displayed. A draw that reads a clock or a counter is outside the pure-read premise, and the capture is then only as exact as that draw.

void begin_marker(const wchar_t* name);
void end_marker();
void set_marker(const wchar_t* name);

Debug markers, AND THEY ARE ADVISORY: a backend may forward them to a tool and may do nothing at all, and a caller may not tell which from anything it can observe. The d3d11 backend forwards them, to ID3DUserDefinedAnnotation, which is what a PIX capture reads, and every other backend discards them, each arguing the discard in its own file. That is the whole contract (T6).

LEGAL BEFORE create_device AND OUTSIDE A FRAME, which is the half a caller could otherwise only discover by crashing. Nesting is the caller's business: begin/end are a pair, and a backend that forwards them forwards whatever nesting it is given.

Impl* impl() const;

Named in the public declarations above: Camera, Colour, Font, Handle, RectangleF, RectangleI, RenderResources, Vector2F, View, Viewport.

The files that include this header directly. A file can also reach it through another header.

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

All documentation versions