Skip to content

Renderer

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

software means the API, or the engine's list of known CPU rasterisers, says the device is one. hardware means neither did, which is not proof of a GPU. Ordinary Direct3D Release selection refuses every known software adapter. The explicit LABRADOR_D3D_SOFTWARE_TEST build option forces WARP and still reports software; Debug otherwise retains its hardware-first/WARP-fallback behaviour.

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. The next draw validates its scale before transforming geometry and throws std::invalid_argument unless the scale is finite and positive.

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. Genuine startup device/context requirement refusal throws RenderDeviceUnavailable (device_unavailable.h), preserving the backend's reason and native details. It remains a std::runtime_error; content, shaders, unrelated API errors and runtime recovery are outside that category. No fallback backend is selected.

GL requires WGL_EXT_swap_control on Windows; an interval setter failure remains an ordinary runtime error. Browser GL rejects missing/noncanvas targets with std::invalid_argument. Only a missing WebGL2 API proves capability absence. Null results and creation-error events can both arise from incompatible existing canvas state and remain ordinary std::runtime_error; this category is not exhaustive in a browser.

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.

std::optional<std::uint32_t> texture_dimension_limit() const;

The selected API device's maximum 2D texture width or height, in texels. Empty before successful create_device, while a device is lost or being restored, and for the null backend, which has no device. Restoration refreshes it before on_device_restored. This dimension bound does not guarantee an allocation or a format; file readers may also impose their own, independent admission bound.

void set_vsync(bool vsync);
bool vsync() const;

Whether end_frame waits for the display. true, the default, presents at most once per refresh; false hands the frame over as soon as it is submitted, so the frame rate is no longer the display's. Whether the picture can then tear is the platform's and the compositor's to say.

Legal before and after create_device, and kept across a lost device. A change after create_device takes effect at the next present. vsync() answers what was last asked.

A BACKEND WITH NO WAY TO HONOUR false KEEPS PRESENTING AT THE DISPLAY'S RATE: a browser's animation frame, a Vulkan surface that offers only FIFO, and the null backend, which presents nothing. device_info() describes the policy actually configured (SEAM.md#6).

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 that closes the window.

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.

void set_post_effects(std::span<const PostEffect> effects);

The post chain (docs/effects.md): the materials submit() draws the processed views through, in order, before any overlay view. Outside a frame - from begin_frame to end_frame, so a capture that never presents keeps its frame open until the next begin_frame - and std::logic_error inside one. An empty span removes the chain and the frame draws straight into the back buffer again. Throws std::invalid_argument for more than one effect: a chain is one material until multi-pass chains exist.

MaterialHandle add_material(const MaterialSource& source);

Registers build output from labrador_add_material, copying its bytes and name. Requires create_device and a call outside a frame, otherwise std::logic_error. Throws std::invalid_argument for a mismatched kind, empty data, malformed format header or text terminator, or empty name; null uses empty data. Throws std::runtime_error if the backend cannot create its shader, including invalid compiled code. The handle and values survive device loss.

void set_post_material(MaterialHandle material);

Replaces the built-in chain with one registered material. Like set_post_effects, legal only outside a frame. Throws std::invalid_argument for an unresolved or foreign handle. Calling set_post_effects again replaces this selection; an empty span disables post processing. Registered materials live until this renderer dies.

void set_post_values(MaterialHandle material, const PostValues& values);

The selected material's eight float4s, from the next submit onward. Legal inside a frame on its owning thread; values survive deselection. Throws std::invalid_argument for an unresolved, foreign or unselected handle, or any non-finite value.

void set_post_values(PostEffect effect, const PostValues& values);

The values a chain's effect draws with, from the next submit() on; legal inside a frame, from the thread that owns it. Values belong to the effect, not the chain: they start all zero, and survive the effect leaving the chain and coming back. Throws std::invalid_argument for an effect not in the chain, or a value that is not finite.

void begin_overlay();

Inside a frame, once: declares one new view, the overlay. It and every view declared after it draw over the chain's output, unprocessed. With no chain it only declares the view. Throws std::logic_error on a second call in one frame or outside a frame, and std::out_of_range when the view capacity has no room for it.

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, MaterialHandle, MaterialSource, PostEffect, PostValues, RectangleF, RectangleI, RenderResources, Vector2F, View, Viewport.

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

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

All documentation versions