Reading the C++ in minimal
Keep this page beside the minimal sample when a language feature or rendering term interrupts
your reading. The excerpts come from the sample at the revision in this page’s footer. In the
project copied by Get Started, the same state files live under game/states/ instead of
samples/minimal/states/.
This is the optional programmer companion: it assumes you can already write small C++
functions and classes. If you have very little programming experience,
Read your starter’s C++ follows the three files in order and
explains their punctuation and jobs without that assumption. You do not need either reading
page to change your game: Make a first change
and the step-by-step guides give every line to type. Come back here when a line
they have you change, such as an override or a std::make_unique, is one you want to understand. What a game is to the engine explains how these pieces fit together.
Inheritance and override
Section titled “Inheritance and override”{public:
void init() override; void update(float dt) override;samples/minimal/states/hello_state.h, lines 28–35 at f525bc6
HelloState is a class of your game. : public labrador::State says that it implements the
engine’s State interface, so the engine can call it through a State pointer without knowing
the game’s concrete type. public: makes the following constructor and functions accessible
to callers.
override asks the compiler to check that each function matches a virtual function in the base
class. A misspelt name or mismatched parameter type becomes a compiler error. The const after
draw is part of that match and prevents ordinary writes to this object’s members through that
call. It does not make objects reached through pointers automatically immutable: the engine’s
read-only drawing contract applies to them too. Changes belong in update.
The drawing model explains why several views must be able to read the
same object at once.
unique_ptr owns; a raw pointer can borrow
Section titled “unique_ptr owns; a raw pointer can borrow”The sample records both kinds of relationship:
// Built in init() rather than the constructor, because a Label resolves its// font name against RenderResources - and that only has the font once the// manifest has been walked.//// Borrowed, not owned: the scene owns everything added to it, and add()// hands back a pointer of the object's own type for exactly this - the// things the game still has something to say to.samples/minimal/states/hello_state.h, lines 54–63 at f525bc6
std::unique_ptr<Scene> owns its scene. When the pointer is destroyed, it destroys that scene;
copying the unique pointer is forbidden, and moving it transfers ownership. nullptr means
there is no object yet. std::make_unique<Scene>(...) constructs the owned scene in init().
Label* greeting_ borrows a label that the scene owns. Scene::add takes a unique pointer and
returns this ordinary pointer so the state can speak to the label later. It does not give the
state a second owner. Do not delete that pointer or keep using it after the label leaves the
scene or the scene is destroyed.
The confirmation state makes the same distinction with different owners:
std::wstring question_;
samples/minimal/states/confirm_state.h, lines 37–40 at f525bc6
ConfirmState owns its prompt and borrows the application. The application outlives the states
on its stack; the state releases its prompt when it is destroyed. pointer->member accesses
the pointed-to object, while object.member accesses an object directly.
Ownership is explicit gives the engine’s rules for
the application, scene and state stack.
A lambda capturing this
Section titled “A lambda capturing this”This is the callback passed to push<bool> when the greeting asks whether to quit:
[this](const bool& quit){ if (quit) { this->app_->quit(); }});samples/minimal/states/hello_state.cpp, lines 196–202 at f525bc6
A lambda is a function written at the place it is needed. [this] captures the pointer to this
HelloState, so the body can read this->app_. It does not copy the state or keep it alive.
const bool& quit is the result supplied by the question, borrowed for this callback invocation.
The state below the question remains on the stack while suspended. When the question pops, the stack destroys it, resumes the state below and then delivers the result. Clearing the stack does not deliver result callbacks. Those are the lifetime rules that make this particular capture useful; a captured pointer in arbitrary C++ still needs its object to outlive its use. States and the stack shows the whole push/pop exchange.
std::span is a borrowed range
Section titled “std::span is a borrowed range”A std::span<T> describes a contiguous range: where its elements begin and how many there are.
It owns none of those elements and copying the span does not copy them. The const inside
span<const TouchPoint> means this view cannot change the touch points. The first const
means this local span will not be reassigned.
points.size() is the number of active touch points, and points[i] selects one. The sample
checks i < points.size() before indexing. Use this view while reading the current update;
polling the touch device again changes the state it views. To keep a snapshot, copy the values
you need into storage your game owns. The touch input guide explains
point ids and coordinates.
The Windows entry point and SAL annotations
Section titled “The Windows entry point and SAL annotations”int WINAPI wWinMain(_In_ HINSTANCE, _In_opt_ HINSTANCE, _In_ LPWSTR command_line, _In_ int)samples/minimal/main.cpp, lines 104–105 at f525bc6
wWinMain is the Windows desktop entry point used by this executable. WINAPI is Windows’
calling-convention macro. The w form receives a wide-character command line: LPWSTR is a
pointer to wide characters, and the sample names that parameter command_line. The unnamed
instance-handle and show-command parameters are accepted but not used. The function returns
an integer exit status.
_In_ and _In_opt_ are SAL annotations supplied by the Windows headers. They describe inputs
to analysis tools; opt marks an optional input. They are not extra C++ parameter types and
do not add a runtime check. The browser entry point is the separate main_web.cpp; you do not
put the Windows signature into a browser build.
A using namespace directive in a .cpp
Section titled “A using namespace directive in a .cpp”using namespace labrador;samples/minimal/main.cpp, line 26 at f525bc6
This directive lets unqualified names in this source file find names from labrador, so
Application can mean labrador::Application. It does not move a declaration into another
namespace. The sample’s headers spell engine names in full: a directive at namespace scope in
a header would affect every source file that includes it. Keeping it in the .cpp limits
that effect to this translation unit, the source file together with its includes.
Optional: rendering terms
Section titled “Optional: rendering terms”These sections explain the graphics vocabulary in the source comments. You can skip them while learning how to change the greeting; the game does not manage these graphics objects.
A deferred context records graphics commands
Section titled “A deferred context records graphics commands”// Nothing below names a graphics type. There is no deferred context to// index, no sprite batch to Begin and End, and no command list to finish,// execute and Release - which would be five more lines here and three// caller obligations stated nowhere in the tree.samples/minimal/states/hello_state.cpp, lines 228–231 at f525bc6
In Direct3D 11, the default Windows renderer, a deferred context records drawing commands for
later execution. It lets workers record separate views before the renderer submits their
work. It is unrelated to the state stack deferring a push or pop until update returns.
The game receives the backend-neutral Renderer and DrawList interface. The renderer owns
the graphics contexts and command-list lifetime. Other backends supply their own recording
machinery behind that same interface; the game does not allocate a deferred context itself.
See the frame from the engine’s side.
A dynamic vertex buffer holds changing sprite geometry
Section titled “A dynamic vertex buffer holds changing sprite geometry”// and a dynamic vertex buffer created at startup and never used.// A game that fans out says so here; this one does not.options.view_capacity = 1;samples/minimal/main.cpp, lines 125–127 at f525bc6
A vertex is one corner’s drawing data, such as position, texture coordinate and tint. A vertex
buffer holds those vertices for the graphics device. Dynamic here is Direct3D 11 terminology
for a buffer the CPU updates with this frame’s sprite geometry, rather than immutable geometry
loaded once. The backend owns the upload and reuse rules.
The comment explains the cost of reserving more views than this sample uses. view_capacity
is the maximum view count the renderer prepares for; this game asks for one. It does not need
to size, map or synchronize a graphics buffer. The split-screen explanation
connects that capacity to a game’s actual views.
Fan-out divides the views, not the objects
Section titled “Fan-out divides the views, not the objects”// thread pool - a fan-out over a single pane is a fan-out over nothing.samples/minimal/states/hello_state.h, lines 53–54 at f525bc6
Fan-out means splitting one scene draw into work for its several views. Each view looks at
the same objects through its own camera and viewport. When workers are enabled, different
workers can call draw on the same object concurrently; one worker is not assigned ownership
of one game object. That is why changing object state belongs in update and draw is const.
The minimal sample has one view, so it gives the scene no worker pool or partitioner:
With that choice, its drawing runs on the calling thread. The local multiplayer guide shows why a game would need several views. Return to Make a first change to edit the sample, or continue with States and the stack.
Documentation for Labrador v0.4.0. Built from Labrador f525bc6 of 2026-11-17.