Application
Generated from engine/app/application.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.
Audience: game code.
#include "engine/app/application.h" · namespace labrador
default_thread_count
Section titled “default_thread_count”How many logical processors the machine reports, and never fewer than one.
It sizes the thread pool and nothing else. The renderer's view capacity is a property of the layout (ApplicationOptions::view_capacity) and the partition count is a property of the work (Scene::draw).
struct ApplicationOptions
Section titled “struct ApplicationOptions”What a game hands the shell before it opens a window. Everything here is a decision only the game can make - its title, the resolution it read out of its own save file - which is exactly why none of it is compiled into the engine (T1).
window_class_name
Section titled “window_class_name”std::wstring window_class_name = L"LabradorWindowClass";window_title
Section titled “window_title”std::wstring window_title = L"Labrador";The window class name has to be unique per process, so a game that ever opens two windows needs two of these. In a browser the page owns its title and there is no class, so neither is read there.
resolution
Section titled “resolution”client_size
Section titled “client_size”fullscreen
Section titled “fullscreen”bool fullscreen = false;The window's client size: one of the four presets, or, when client_size is set, any size at all - 1366x768, 1600x900, a 16:10 shape. A set client_size is the size the window opens at, and resolution is then only the preset label ResolutionManager reports until the size matches one. Neither extent may be below the minimum window size further down; validate() refuses it by name.
visible
Section titled “visible”bool visible = true;Whether the native window is shown after its first completed frame. Initialization, content loading and the first draw remain hidden; failure before end_frame succeeds never reveals the window. A smoke test or a capture tool says false and gets the whole shell - window, device, services - with nothing on screen and no focus taken, set_fullscreen included. The engine never shows a window created hidden; a window shown by other means is outside this contract. A browser shows whatever the page shows, so it is not read there.
cursor_visible
Section titled “cursor_visible”bool cursor_visible = true;cursor_confined
Section titled “cursor_confined”bool cursor_confined = false;The pointer over the window from the first frame: whether it is drawn, and whether it is kept inside (Application::set_cursor_visible, set_cursor_confined).
target_fps
Section titled “target_fps”int target_fps = 60;The fixed step the simulation advances at. Rendering is not capped by it. Must convert to at least one StepTimer tick (at most 10,000,000 FPS).
A MINIMISED WINDOW STILL STEPS AT THIS RATE AND DRAWS NOTHING. On Windows the loop sleeps between the steps, so a wake that comes late runs the steps it owes together, and no frame is drawn or counted in frame_timings until the window is restored. A window that is only hidden - visible above - is not minimised, and draws.
bool vsync = true;Whether presenting waits for the display, from the first frame. Changed later through renderer()->set_vsync, which says what each backend can honour. It changes presentation only: the simulation still steps at target_fps.
min_threads
Section titled “min_threads”int min_threads = 1;max_threads
Section titled “max_threads”The render thread pool's floor and ceiling. The ceiling defaults to what the machine reports (APPLICATION.md#1).
view_capacity
Section titled “view_capacity”int view_capacity = 4;The widest a frame may ever fan out, which is what sizes the renderer's per-view recording state - a backend that records into per-thread contexts has to make them before any frame starts. Every view costs memory whether or not a frame uses it (APPLICATION.md#1).
Four is four-player split-screen. A game drawing one pane says 1 and pays for one.
min_window_width
Section titled “min_window_width”int min_window_width = 320;min_window_height
Section titled “min_window_height”int min_window_height = 200;Smallest the user may drag the window; below this the swap chain is not worth resizing.
scripted_gamepad_source
Section titled “scripted_gamepad_source”Optional fixture source, borrowed through Application destruction. Null selects the configured shipping backend. A scripted source must have no other reader while this application is initialized.
window_icon_resource
Section titled “window_icon_resource”std::optional<std::wstring> window_icon_resource = std::nullopt;Explicit optional icon in the process executable. Same lookup, ownership and failure contract as WindowOptions::window_icon_resource; a browser ignores it and leaves the host's favicon alone.
cursor_shape
Section titled “cursor_shape”No explicit choice keeps the native arrow or the page's canvas style.
validate
Section titled “validate”void validate() const;Throws std::invalid_argument naming the field, rather than letting a bad number reach the code that divides by it. Application calls this before it opens a window. max_threads and target_fps are divisors, and a game may read them from a save file it does not control.
window_options_for
Section titled “window_options_for”The window Application opens for options, at client_size: every WindowOptions field ApplicationOptions also has, carried across unchanged. The client size is the caller's, because Application decides it from resolution and client_size together.
struct FrameTimings
Section titled “struct FrameTimings”What the last completed frame cost on the CPU, as steady_clock saw it (Application::frame_timings).
DRAW AND SUBMIT TOGETHER ARE THE WORK, and how it splits between them is the backend's. begin_frame_time and end_frame_time may contain waits for the GPU or the display, so neither is the cost of a frame. None of this is GPU time or CPU busy time, and the fields need not sum to interval.
std::uint64_t frame = 0;Frames completed since run() began; 0 until the first.
updates
Section titled “updates”int updates = 0;The fixed steps the frame's tick ran: 0, 1, or several when the clock was catching up.
interval
Section titled “interval”std::chrono::nanoseconds interval{};This tick's start minus the previous frame's. Zero on the first frame and on the frame after a discontinuity - reset_elapsed_time, or coming back from being hidden - because the time across one was not the game's. One that arrives during a tick, as a reset after a load in an update() does, zeroes that tick's frame as well, so two frames in a row read zero.
update_time
Section titled “update_time”std::chrono::nanoseconds update_time{};The whole catch-up: the input polls, every stack update, and audio.
begin_frame_time
Section titled “begin_frame_time”std::chrono::nanoseconds begin_frame_time{};draw_time
Section titled “draw_time”std::chrono::nanoseconds draw_time{};StateContext::draw, and any fan-out it joins.
submit_time
Section titled “submit_time”std::chrono::nanoseconds submit_time{};submit, and the debug marker that closes the frame.
end_frame_time
Section titled “end_frame_time”std::chrono::nanoseconds end_frame_time{};first_completed_frame_utc
Section titled “first_completed_frame_utc”std::optional<std::chrono::system_clock::time_point> first_completed_frame_utc = std::nullopt;UTC observed immediately after the first successful end_frame in this Application's loop, retained only when that frame is published. Unknown until then; resets and suspension do not replace it. This system-clock endpoint can reflect wall-clock adjustments and is not a steady duration, GPU-completion time or display-latency measurement.
class Application
Section titled “class Application”The machinery every game needs and no game should write: a window, a device, the services, the main loop, and the state stack. The game constructs it and hands it a first state (PHILOSOPHY, Structural types) - there is no IGame to implement and nothing here to subclass.
It is used in three steps, because the game has something to say between each pair:
app.initialize(); // window, device, servicesapp.resource_loader()->register_kind(...); // the game's own asset kindsapp.load_manifest("./manifest.json");return app.run(std::make_unique<MyFirstState>(...));The first state is constructed last on purpose: states build drawables, and a drawable resolves handles against resources that do not exist until the manifest has been walked.
Application · ~Application
Section titled “Application · ~Application”~Application() override;Application · operator=
Section titled “Application · operator=”Application& operator=(const Application&) = delete;initialize
Section titled “initialize”void initialize();Creates the window, device and services. A native window stays hidden until run() completes its first frame; visible=false keeps it hidden. Throws std::runtime_error naming the step that failed (T6). Native construction throws std::invalid_argument for a NUL title or an empty/NUL explicit icon name, before registering the window.
load_manifest
Section titled “load_manifest”void load_manifest(const std::string& manifest_path);Loads everything the manifest names. Register any game-specific kinds before calling this, or the walk throws naming the kind it does not know.
A RELATIVE PATH IS RELATIVE TO THE EXECUTABLE, not to the working directory, and a relative directory inside the manifest is relative to the manifest (engine/app/content_root.h says why). "./manifest.json" therefore means the file beside the game, wherever the game was started from. An absolute path is taken as it is.
ONE MANIFEST. A second call loads what it names as well, and then replaces the first as what a device restore replays, so a restore rebuilds what the second manifest names and nothing that only the first did. A game with more than one manifest loads them as one (ResourceLoader::load_manifest).
Throws std::logic_error naming this call if initialize() has not run, because there is no loader to load into (T6).
Takes the first state and runs until the window closes. Returns the process exit code.
IN A BROWSER IT DOES NOT RETURN, AND THE APPLICATION MUST NOT BE A LOCAL IN main. The frame loop is the browser's, so this hands it the first frame and gives control back to the page by unwinding the stack, main's included and destructors and all, before that frame runs (Window::pump_until_quit). An Application declared in main is destroyed there, and its window says so on the way out; one that outlives main - a static - is the shape a web entry point has. Nothing after this call in main ever runs, and quit() ends the loop rather than returning here.
Throws std::logic_error naming this call if initialize() has not run, on either platform and before the first state is entered, so no init() meets a service that does not exist (T6).
void quit() const;Closes the window, which ends run(), without asking on_close_requested(). Native user close requests first ask the top state; a game asking to exit here has already made its decision. This is the final quit path: a game asking to exit does not need to know which platform it is on. In a browser the page is told, and decides what comes next; the states and services are released on a later task (APPLICATION.md#7). If called during update, the tick completes its remaining fixed steps but does not draw or publish another completed frame. Before initialize() there is no window, and it does nothing.
THE LAYOUT SIZE FOLLOWS THE WINDOW. However the window comes to change size - any call below, or a user dragging an edge, which no game asked for at all - ResolutionManager is re-pointed at the new CLIENT size before the renderer resizes its back buffer. All of them arrive as the window's size report - WM_SIZE on Windows - so on_window_size_changed is the single place that holds the invariant, and it cannot be got at from a game (APPLICATION.md#2).
Called before initialize(), each of the three below only records what was asked, as the cursor calls further down do, and the window initialize() opens is the one it would have been.
set_resolution
Section titled “set_resolution”Resizes the window so the game gets resolution pixels of CLIENT area, and re-points the resolution manager at what it actually got. The game decides which resolution and when - it is reading its own options menu - and the engine owns what that means to a window, frame included.
set_resolution
Section titled “set_resolution”The same for a size no preset names, in CLIENT pixels. A size past the monitor's comes back clamped, and the layout follows what the window got. resolution_manager()->resolution() keeps the preset last asked for unless this size is one of the four. Throws std::invalid_argument, changing nothing, when either extent is below ApplicationOptions::min_window_width or min_window_height.
set_fullscreen
Section titled “set_fullscreen”void set_fullscreen(bool fullscreen);Switches between a borderless full-screen window and an ordinary one. Going full screen adopts the monitor's size; coming back adopts the resolution last requested, not the monitor size just vacated.
fullscreen
Section titled “fullscreen”bool fullscreen() const;Whether the window is full screen: what set_fullscreen last asked, until the platform says otherwise. A browser does - a player leaves with Escape, and a page in a frame may refuse - and this follows what it decided, so an options menu reading it shows the truth.
set_window_title
Section titled “set_window_title”void set_window_title(const std::wstring& title);Updates the native caption through Window::set_title, on the application thread. Before initialize(), keeps the title for the window's startup. Native startup validates that deferred text when it creates the window. The requested option changes only after a live window accepts the call. Browser pages keep their own title; calling this does not change it.
set_cursor_visible · cursor_visible
Section titled “set_cursor_visible · cursor_visible”void set_cursor_visible(bool visible);bool cursor_visible() const;Whether the pointer is drawn over the window. A game played with a pad hides it; the mouse is still read, so a hidden pointer still moves and clicks. Over anything but the client area the pointer is the platform's (Window::set_cursor_visible).
set_cursor_shape · cursor_shape
Section titled “set_cursor_shape · cursor_shape”std::optional<CursorShape> cursor_shape() const;The requested client-area shape, independent of visibility and confinement (Window::set_cursor_shape). std::nullopt selects the native arrow or prior canvas style. Kept before initialize() as an initial option; invalid enumerators throw std::invalid_argument without changing it.
set_cursor_confined · cursor_confined
Section titled “set_cursor_confined · cursor_confined”void set_cursor_confined(bool confined);bool cursor_confined() const;Whether the pointer is kept inside the window while the window is active - on Windows; a browser cannot confine a pointer, and this does nothing there (Window::set_cursor_confined). The answer below is what was asked, on either platform.
reset_elapsed_time
Section titled “reset_elapsed_time”void reset_elapsed_time();Tells the clock that the time just spent was not gameplay.
The step is fixed, so a long blocking call - loading a level, reading a save - is not one enormous dt. It is a backlog, and the next tick pays it off by running update() as many times as it takes, at full speed, on a world that has not been drawn yet. A client that swallows the first frame after a load instead pays for one frame and fixes nothing beyond it.
frame_timings
Section titled “frame_timings”The CPU times of the last frame this loop completed (FrameTimings), which a game cannot take itself: begin_frame, submit, end_frame and the catch-up count all run inside the loop.
WRITTEN BETWEEN FRAMES, after a frame's end_frame returns, so an update or a draw reads the last frame completed before it. A copy, safe to read from a draw worker.
ONLY THE LOOP'S OWN FRAMES. A tick that renders nothing - before the first update, or while the window is minimised - publishes nothing, and neither does a frame that throws. A frame a game draws itself, such as a capture (Renderer::read_back_buffer), is not one of them, and the time it takes inside an update is part of update_time.
THE CLOCK'S RESOLUTION IS THE PLATFORM'S. In a browser steady_clock is performance.now(), which a page without cross-origin isolation may coarsen to about 100 microseconds, so a short phase there can read as zero. Which phase holds the waits is the backend's (SEAM.md#6).
step_position
Section titled “step_position”How far between two fixed steps the frame being drawn falls (StepPosition), for a draw that wants motion smoother than the step.
WRITTEN TWICE A TICK. Before each update() it is that update's own step with a fraction of 0, so an update - and a frame drawn inside one, such as a capture - sees the step being run. After the tick's last update and before its draw it is the last step run and how far past it the frame falls. A reference to one member that stays put, so a drawable may hold a pointer to it for the Application's life, and safe to read from a draw worker.
A STATE THAT WAS NOT UPDATED MUST NOT USE THE FRACTION. Only the top of the stack is updated, and a match drawn under a pause menu has stopped while the fraction goes on cycling: extrapolated, it shimmers back and forth by up to a step's motion. That is what step is for - a drawable that records it in update() and finds it unchanged in draw() was updated on the latest step, and one that finds it moved on was not, and draws where it is.
On a display at the step's own rate the fraction barely moves from frame to frame, and nothing drawn with it looks different.
renderer · render_resources · audio_resources · resource_loader · resolution_manager · viewport_manager · thread_pool · partitioner · gamepads
Section titled “renderer · render_resources · audio_resources · resource_loader · resolution_manager · viewport_manager · thread_pool · partitioner · gamepads”The services. Every one of these is null until initialize() has run - which is what ApplicationOptions is for: anything the game needs to say before there is a window to say it to belongs in the options, not in a call against a service that does not exist yet.
After that they are created once and never reseated, so an object may hold one for its whole life - device loss recreates GPU objects in place and leaves service identity alone (PHILOSOPHY, Services and lifetimes). In a browser, which never destroys the Application, the task after the window closes - by quit, or by an exception the window caught - clears the states and destroys every service, and each accessor here answers null from then on (APPLICATION.md#7). Nothing holds a service past the page's onQuit or onError.
Borrowed, every one: the Application owns them and outlives the states it runs.
~Application drains the state stack before any service is destroyed, so a state may release a service in its destructor, which is the teardown pattern state_context.h documents (APPLICATION.md#3).
keyboard · mouse · touch
Section titled “keyboard · mouse · touch”The other three devices. All are polled beside the pads, once per fixed update before that update's states run, so every edge in the engine is measured across the same poll boundary whichever device it came from. A rendered frame that runs no update polls nothing, and one that catches up polls once per update it runs.
They differ from Gamepads only in where their data comes from: these are fed from the window's messages (engine/input/keyboard.h).
Touch is live while the player is here - the window in the foreground and shown - whether or not the canvas has the keyboard, because a finger reaches the canvas only by touching it, and a phone may never give a canvas the keyboard at all.
window
Section titled “window”void* window() const;The native window, as Renderer::create_device takes it (Window::handle): an HWND on Windows, the canvas in a browser. Null before initialize(), like the services.
display_info
Section titled “display_info”The current native window's nominal display metadata, queried on the application/window thread (Window::display_info). Before initialize(), after closure and in a browser it is unknown.
Related types
Section titled “Related types”Named in the public declarations above: AudioResources, CursorShape, DeviceNotify, Gamepads, Keyboard, Mouse, Partitioner, RenderResources, Renderer, ResolutionManager, ResourceLoader, ScreenResolution, ScriptedGamepadSource, State, StateContext, StepPosition, ThreadPool, Touch, Vector2I, ViewportManager, WindowDisplayInfo, WindowNotify, WindowOptions.
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/audio/audio_state.h,main.cpp,main_web.cppsamples/collision/collision_state.h,main.cpp,main_web.cpp,outlines_state_tests.cppsamples/components/gallery_animation_tests.cpp,gallery_binding_tests.cpp,gallery_pointer_tests.cpp,gallery_state.h,gallery_text_tests.cpp,gallery_touch_tests.cpp,main.cpp,main_web.cpp,touch_demo_state.hsamples/linesweeper/main.cpp,main_web.cppsamples/linesweeper/states/pause_state.h,play_state.hsamples/linesweeper/web/pacing_observer.cpp,pacing_state.cppsamples/local_multiplayer/join_state.h,main.cpp,main_web.cpp,play_state.hsamples/minimal/main.cpp,main_web.cpp,native_process_report.hsamples/minimal/states/confirm_state.h,hello_state.htests/app/application_loop_tests.cpp,application_options_tests.cpp,application_order_tests.cpp,application_resize_tests.cpp,application_reveal_tests.cpp,application_scripted_pad_tests.cpp,frame_timer_tests.cpp,startup_child.cpp,window_title_icon_tests.cpptests/app/win32/application_display_info_tests.cpptests/linesweeper/focus_pause_tests.cpp,touch_pause_tests.cpptests/local_multiplayer/join_state_tests.cpptests/minimal/close_request_tests.cpp,state_tests.cpp
Explained in
Section titled “Explained in”- Drawing, views and cameras
- What a game is to the engine
- Read your starter's C++
- Reading the C++ in minimal
- States and the stack
- The tick
- Content and the manifest
- Audio
- Build for the browser
- Input
- Embed the LineSweeper bundle
- Local multiplayer
- Menus
- Update your code for a newer Labrador
- Settings and saves
- Test your game
- Copy the components into your game
- Add a second level
- Make a title menu
- Roll a die in your game
- Add a screen to your game
- Write a post-processing shader
- Colours, the window and the background
Development documentation (unreleased). Built from Labrador aceb130 of 2026-11-20.