Skip to content

StateContext

Generated from engine/core/state_context.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.

Browse the core module

Audience: game code.

#include "engine/core/state_context.h" · namespace labrador

Owns a stack of states, their suspension and result delivery (docs/design/PHILOSOPHY.md, Structural types). A state's destructor releases what it set up; states beneath a pushed screen remain alive.

transition_to(), push() and pop() issued during this context's update, init, activation walk, close request or operation drain wait for the enclosing call to return. Nested callbacks retain that protection; the drain never reenters itself. Operations outside these calls take effect immediately.

A root State can own a separate StateContext to run code around every game update and draw. It forwards update, draw and activation to the owned context, including its parent's active() value during init(). It forwards on_close_requested() to notify_close_requested() too. Inner states use their own context(); Application::depth() then counts only the root. Frame capture belongs in the root's update after the owned update returns, never in draw() (engine/render/renderer.h, Renderer::read_back_buffer).

virtual ~StateContext();
StateContext();
StateContext(const StateContext&) = delete;
StateContext& operator=(const StateContext&) = delete;
void update(float dt);

Updates the top state only. Everything below it is suspended.

void draw(Renderer& renderer) const;

Draws from the topmost state that covers the screen, upward (State::covers_screen). The level draws, then the pause menu over it, in one pass with no state having to know what is under it.

void transition_to(std::unique_ptr<State> state);

Replaces the top state, or installs the first one on an empty stack. Rejects nullptr with std::invalid_argument. Safe inside the current state's update(): deferral keeps that state alive until its call returns. The new state's context is set and init() runs before update() or draw().

Consecutive queued transitions collapse to the last one; discarded states never run init(). Pushes and pops between transitions preserve their issue order, because they change which stack entry is being replaced.

void push(std::unique_ptr<State> state);

Puts a state above the current one and calls the covered state's on_suspend(). It stops updating and keeps drawing if the new top does not cover the screen. Rejects nullptr with std::invalid_argument; deferral and entry follow transition_to().

void push(std::unique_ptr<State> state, std::function<void()> on_closed);

Calls on_closed after this stack entry is popped, regardless of the result supplied to pop(). The ordering and shutdown rule match on_result below.

template <typename Result>
void push(std::unique_ptr<State> state,
std::function<void(const Result&)> on_result);

Calls on_result with the typed result when this stack entry is popped. The callback belongs to the entry and survives transition_to() replacing its state, so a multi-page screen answers the push that opened it.

The type is named at the push and checked at the pop:

this->context()->push<PauseChoice>(
std::make_unique<PauseState>(this->app_),
[this](const PauseChoice& choice) { ... });
// ...and, inside the pause screen, however many pages later:
this->context()->pop(PauseChoice::resume);

on_result runs after the popped state is destroyed and after the resumed state's on_resume(). Missing or mismatched results throw std::logic_error at delivery (T6). clear() never delivers results.

void pop();

Takes the top state off. Throws std::logic_error if there is nothing on the stack to take.

template <typename Result>
void pop(const Result& result);
int depth() const;

How many states are stacked: 1 at a title screen, and 3 with a pause menu over a match over a menu.

void notify_activation(bool active);

Reports a foreground change to every live state, top first. Repeating the current value does nothing. active() reflects the new value during callbacks; covered states are notified even though they do not update.

Stack operations issued by callbacks wait until the walk and any enclosing callback or active drain return. A nested notification cannot drain operations while an outer update() or init() is still running.

bool active() const;

Foreground state as last reported; initially true. A state constructed after a notification receives no retrospective callback and reads this in init() to learn whether it entered an inactive context.

bool notify_close_requested();

Asks the current top state's on_close_requested(), or allows closure when the stack is empty. Does not close a window itself. Stack changes wait until the callback returns, preserving its state and captures; the returned decision belongs to that request even if the top changes. Each later request asks the then-current top. A recursive request during this notification or its drain returns false without a callback.

void clear() noexcept;

Drops queued operations, then destroys live states top first without delivering result callbacks. It leaves active() unchanged. Also called by the destructor; repeated calls on an empty stack are harmless.

Immediate, never deferred: do not call it from a state's update(), init(), activation or close-request callback. The state whose code is running could be destroyed, along with frames an activation walk has yet to visit. Owners must clear states before destroying any services they borrow; Application clears its stack before its service members are destroyed. A throwing state destructor terminates here: teardown is noexcept (T6).

Named in the public declarations above: Renderer, State.

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

Documentation for Labrador v0.4.0. Built from Labrador f525bc6 of 2026-11-17.

All documentation versions