Touch
Generated from engine/input/touch.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.
Audience: game code.
#include "engine/input/touch.h" · namespace labrador
Fed, not read, as the keyboard is: a touch reaches a Win32 program as WM_POINTER messages in a window's queue and a page as pointer events on its canvas, so the flow is app -> input and nothing in this file knows a window exists.
SEVERAL POINTS AT ONCE, which is the one way this device is not the mouse. A mouse has one position and a fixed set of buttons, so a bit per button is its whole state. A touchscreen has as many positions as there are fingers on the glass, and none of them is a button: a point is held for exactly as long as it exists. So the state is a short list of points, and the question a game asks of it - held, pressed, released - is asked of one point by its id rather than of one button by its name.
struct TouchPoint
Section titled “struct TouchPoint”One finger on the glass, in one frame.
uint32_t id = 0;THE ENGINE'S ID, NOT THE PLATFORM'S. It is handed out when the point goes down, stays the same until it comes up, and is not given to another point afterwards - so a game that keeps a map from finger to whatever the finger is dragging can key it on this and never find a stale entry adopted by a new touch.
The platform's own ids do not promise that. Windows and browsers both reuse them, and a finger lifted and a new one put down between two frames can arrive with the same number: keyed on that, a release and a press would read as one point that never let go. Zero is never an id, so it can stand for none.
position
Section titled “position”CLIENT PIXELS, as MouseState::position is: origin at the top-left of the area the game draws into, +y down. It can be outside the client rectangle and negative, because a point that went down inside the window is followed when it slides off the edge, as a dragged mouse is.
struct TouchState
Section titled “struct TouchState”The touchscreen, one frame. A value, for the reason every other device state is one: two of them are a frame boundary, and a test writes both by hand.
capacity
Section titled “capacity”static constexpr int capacity = 10;THE MOST POINTS A FRAME HOLDS, and the overflow rule that goes with it: a point that goes down while this many are already down is not seen at all, for the whole of its contact - not when another finger lifts and makes room, because a point that appeared mid-gesture would be a press nobody made at that moment. Ten is two hands, which is every game this engine is for; a palm on the glass is the usual way to reach it.
focused
Section titled “focused”bool focused = false;False means the window is not taking touch this frame, and there are no points. It is focused for the same reason and with the same rule as KeyboardState::focused and MouseState::focused.
int count = 0;points
Section titled “points”The points down this frame, the first count of points, in the order they went down.
cancelled_count
Section titled “cancelled_count”int cancelled_count = 0;cancelled
Section titled “cancelled”uint32_t cancelled[capacity] = {};Points that were down last frame and are gone this one WITHOUT having been lifted: the platform cancelled them, or the window lost capture of them. A cancelled point produces no released edge, as Mouse::cancel_buttons produces none: a gesture the system took away is not a finger the player lifted, and a button that fired on it would fire on something nobody let go of.
The point with this id, or null.
is_down
Section titled “is_down”bool is_down(uint32_t id) const;Whether a point with this id is down. False for zero, which is never an id.
active
Section titled “active”The points as a range, for the loop every caller writes.
pressed · released
Section titled “pressed · released”bool released(const TouchState& now, const TouchState& before, uint32_t id);The edges between two frames, per point, and the rule they inherit.
AN EDGE REQUIRES THE DEVICE TO HAVE BEEN FOCUSED ON BOTH FRAMES, as keyboard.h states it and for its three reasons: the first frame of the process, focus returning with a finger already down, and focus going away with fingers down. A finger on the glass across an app switch is never pressed into the game and never released into it either; a client that wants to know asks for the focus change:
just_unfocused(now, before) && before.count > 0A released point is no longer in now, so the loop that finds one walks the frame before:
if (released(now, before, point.id)) ...motion
Section titled “motion” uint32_t id);How far one point moved between the two frames, in client pixels. Zero unless the point is down on both and the device was focused on both, so the frame a point appears on is never a jump from wherever the last one was.
just_focused · just_unfocused
Section titled “just_focused · just_unfocused”bool just_unfocused(const TouchState& now, const TouchState& before);class Touch
Section titled “class Touch”The touchscreen as it was this frame and last, and the edges between them.
A game reads the borrowed instance from Application::touch(). Construction, feeding and poll() belong to the shell; a game reads the snapshots rather than advancing them.
Application owns one, feeds it from the window's messages and polls it once per fixed update beside the other devices, before that update's states run.
on_down · on_move · on_up · on_cancel
Section titled “on_down · on_move · on_up · on_cancel”void on_move(uint32_t platform_id, const Vector2I& position);void on_up(uint32_t platform_id, const Vector2I& position);void on_cancel(uint32_t platform_id);THE FEEDING SIDE, public for the reasons Mouse's is: input may not name a class in app to friend it, and a test double or a replay source feeds it with no window. The ids these take are the PLATFORM'S - a Win32 pointer id or a DOM pointerId - and are mapped to the engine's ids here, which is where the reuse TouchPoint::id describes is absorbed.
A point down and up again between two polls IS SEEN, for one frame, pressed on that frame and released on the next. That is unlike a key, which can be lost between two polls, and it is deliberate: a tap is the commonest thing a finger does, and a quick one is over in less than a frame often enough to matter.
Ignored while unfocused, so nothing pressed while the window was away is waiting for it when it comes back. A down for a platform id that is already down ends the old point as cancelled and starts a new one: its up was lost somewhere, and inventing a release would be inventing input. A move, up or cancel for an id that is not down is dropped, which is also what happens to every message of a point that arrived past capacity.
cancel_points
Section titled “cancel_points”void cancel_points();Cancels every point, as on_cancel cancels one: gone at the next poll, with no released edge. Focus is unchanged.
set_focused
Section titled “set_focused”void set_focused(bool focused);The window gained or lost touch. Losing it removes every point, as losing the foreground puts every key up, because the ups for the fingers still on the glass will be delivered somewhere else. Each one ends cancelled, as cancel_points ends it, so no released edge reaches the game even when focus comes back before any frame saw it gone - a hidden page gets no frames - and just_unfocused never fires.
void poll();THE FRAME BOUNDARY, called by the shell. What was current becomes previous, and what the messages have built becomes current: every point still down, every point that went down and up again unseen, and the ids cancelled since the last call.
state · previous_state
Section titled “state · previous_state”const TouchState& previous_state() const;points
Section titled “points”This frame's points, in the order they went down.
held · pressed · released · motion
Section titled “held · pressed · released · motion”bool held(uint32_t id) const;bool pressed(uint32_t id) const;bool released(uint32_t id) const;focused · just_focused · just_unfocused
Section titled “focused · just_focused · just_unfocused”bool focused() const;bool just_focused() const;bool just_unfocused() const;Related types
Section titled “Related types”Named in the public declarations above: Vector2I.
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/components/gallery_binding_tests.cpp,gallery_pointer_tests.cpp,gallery_state.cpp,gallery_text_tests.cpp,pointer_capture.h,pointer_capture_tests.cppsamples/linesweeper/presentation/touch_controls.hsamples/linesweeper/states/pause_state.cpp,play_state.cppsamples/minimal/states/hello_state.cpp,hello_state.htests/input/touch_tests.cpptests/linesweeper/touch_controls_tests.cpp,touch_pause_tests.cpp
Explained in
Section titled “Explained in”Documentation for Labrador v0.4.0. Built from Labrador f525bc6 of 2026-11-17.