Chapter 44 The Input System

KeyboardState’s public surface is compact:

KeyboardState(std::initializer_list<Keys> keys)

the ordinary way application and test code constructs one, for example KeyboardState{Keys::W, Keys::LeftShift}.

getItem(Keys key) / operator[](Keys key)

both return a KeyState (Down or Up) for one key.

IsKeyDown(key) / IsKeyUp(key)

boolean key queries.

GetPressedKeys()

returns every currently-down key as an ascending-sorted std::vector<Keys>; the sort is part of the contract because the backing hash set has no stable iteration order.

Keyboard’s EXT methods bridge XNA’s US-QWERTY-shaped Keys enum and SDL3’s distinction between a physical scancode and a layout-dependent keycode. GetKeyFromScancodeEXT() maps a US-named physical position into the current layout, which supports position-based movement controls on non-US keyboards. The public API has no general keycode-to-physical-position inverse; the inverse helpers apply to textual names. GetModStateEXT() returns SDL’s modifier mask. GetScancodeNameEXT and GetKeyNameEXT, plus their name-to-key forms, provide current-layout labels for rebinding interfaces.

MouseState is a plain data carrier — X / Y, five ButtonState properties (LeftButton / RightButton / MiddleButton / XButton1 / XButton2), the cumulative ScrollWheelValue already named above, and (CNAEXT) a parallel HorizontalScrollWheelValueEXT for horizontal scroll, deliberately excluded from Equals / GetHashCode / ToString as already noted. Mouse itself, beyond GetState() and SetPosition, exposes relative (pointer-lock-style) mouse mode and window/capture-related EXT methods:

IsRelativeMouseModeEXT

(get/set) toggles SDL’s own relative mouse mode, where motion is reported as unbounded deltas rather than an absolute, screen-clamped position — the standard technique for an FPS-style camera look. Both accessors are safe to call with no window at all (no published window handle and no focused window): the getter simply reports false rather than querying SDL with a null window (whose behavior SDL leaves undefined), and the setter is a no-op. While relative mode is active, each SDL_EVENT_MOUSE_MOTION adds its relative delta to a separate accumulator; motion outside that mode is not accumulated, and toggling the mode flushes stale deltas. MouseState’s public X / Y read and immediately drain that accumulator in relative mode; otherwise they report the absolute position.

SetPosition(x, y)

is a documented no-op in relative mode because an absolute warp has no meaning while the mouse reports deltas.

SetCaptureEXT(enabled)

engages OS-level mouse capture (input keeps arriving even if the cursor leaves the window bounds), distinct from relative mode and combinable with it.

GetGlobalPositionEXT / WarpGlobalEXT

read or set the mouse position in desktop rather than window-relative coordinates.

ClickedEXT

a CNAEXT System::MulticastAction<int> event (Chapter 56 covers this sharp-runtime type) firing once per click with the button index, for code that wants a discrete click event rather than polling button state every frame.

The write direction is only half the story. Incoming SDL_EVENT_MOUSE_MOTION and mouse-button positions pass through SdlInputBridge::to_logical_position() before updating InputManager; touch starts from normalized window position and reaches the same helper. Thus a bad or missing transform affects absolute mouse reads, click coordinates, and touch together, while relative mouse motion deliberately remains an unscaled delta.

The SDL_RENDERER route has the strongest existing proof. A test creates a $100\times 100$ logical presentation inside a $200\times 200$ window, injects a physical motion event at $(100,100)$, and observes logical $(50,50)$ through Mouse::GetState(). Separate conversion tests cover the inverse and a horizontal letterbox offset. The latter tests cannot inspect the OS cursor under Wayland, however: SetPosition() writes the requested logical point into InputManager before attempting conversion and warp, so immediately reading that point back proves the cache assignment even if the physical cursor landed elsewhere. The former ASCII renderer’s integration test uses this same weak immediate set/get shape.

Other renderers in the inherited audit cohort are not interchangeable:

• •

  EasyGL and Canvas register an offset-free height scale. It matches their default fixed-height, dynamic-width mode, but not the other presentation modes they store.

• •

  WebGPU and SDL GPU implement all five viewport modes, but their transform uses physical pixel dimensions for SDL event and warp values expressed in window coordinates. A high-pixel-density display therefore introduces a density-factor error. Reads in a letterbox bar also return false, causing raw window coordinates to replace the outside logical point the method had already computed.

• •

  Vulkan has no override or registry entry. Its SpriteBatch projection stretches the virtual canvas across the physical swapchain, so absolute input becomes misaligned after a non-1:1 resize. Keeping its window-coordinate size equal to the requested virtual size is the only portable caller-side guard today.

• •

  BGFX and D3D9/11/12 also pass through, but those renderers in the inherited audit cohort ignore logical presentation and draw in physical coordinates; input matches that limitation rather than the requested mode.

• •

  FREEDIRECT’s correct direct helper methods are shadowed by the SDL renderer created inside free-direct. Public mapping is pass-through until the first Present() installs its hardcoded letterbox, then follows SDL’s mapping. Its four-property test invokes the helpers directly and does not exercise this public route.

The complete inherited fourteen-product matrix and its test evidence are in Chapter 19, §19.2.1. FNA has no corresponding renderer split: Mouse.GetState() multiplies window X/Y by the independent backbuffer/window ratios, and SetPosition() applies their inverses. CNA needs more machinery because its presentation modes include offsets and dynamic logical dimensions, but callers should not mistake that richer vocabulary for uniform implementation.

GamePadState composes four sub-structures, each a plain value carrier read directly from its header: GamePadThumbSticks (Left / Right, each a Vector2), GamePadTriggers (Left / Right, each a scalar float), GamePadButtons (eleven ButtonState properties — every face/shoulder/stick-click/back/start/big button — plus a ButtonStateFromFlag(Buttons) convenience for looking one up by the Buttons flag enum instead of by name), and GamePadDPad (Up / Down / Left / Right, each a ButtonState). GamePadState itself adds IsConnected, PacketNumber (incremented when the hardware state changes), and IsButtonDown / IsButtonUp convenience wrappers over the same Buttons flag enum.

The three GamePadDeadZone modes differ in shape as well as threshold. None filters nothing. The default IndependentAxes excludes and clamps each axis separately, which can distort direction near the boundary. Circular excludes by vector magnitude and clamps to the unit circle. None and IndependentAxes retain a square clamp, so changing modes can also change maximum diagonal magnitude.

Beyond the strict surface, GetGyroEXT / GetAccelerometerEXT expose a controller’s built-in motion sensors, distinct from host-device sensors. They require hardware that reports them, and GamePadCapabilities::getHasGyroEXTProperty() / getHasAccelerometerEXTProperty() exist specifically so calling code can check before relying on either. SetLightBarEXT and SetTriggerVibrationEXT (independent trigger motors rather than the two whole-controller motors) are modern-controller extensions, gated by their GamePadCapabilities flags.

TouchCollection is a per-frame snapshot of tracked touches. It provides Count / IsConnected (the sticky “a touch has been observed” flag described below), the by-index operator[], and the same general ordered-container surface Chapter 7’s own CurveKeyCollection coverage already described — Contains / IndexOf, a CNAEXT empty(), and CNAEXT iterator support for range-based for. Each TouchLocation inside it carries an Id stable across frames for one finger, a State (TouchLocationState: Pressed, Moved, Released, or Invalid for a stale/expired entry), a Position, and (CNAEXT) a PressureEXT reading on hardware that reports one. GestureSample (returned by TouchPanel::ReadGesture()) carries a GestureType, a Timestamp, and up to two positions/deltas (Position / Position2, Delta / Delta2); the second pair is used only by two-finger gestures like Pinch, left at their default for single-finger gestures.

The two connected flags do not use the same evidence. TouchPanel::GetCapabilities() enumerates SDL touch devices on every call, then falls back to the sticky observed-touch flag or a currently live touch. It can therefore report a device before the first interaction. TouchCollection::IsConnected, in contrast, reads only that sticky flag; it can remain false for an enumerated but untouched device until the first finger-down event. Use capabilities for device discovery and the collection’s count for whether a finger is currently tracked.

EnabledGestures is an active filter: ReadGesture() returns only enabled types. GestureType uses powers of two from Tap = 1 through PinchComplete = 512, so callers combine selections with |.

GestureSample::Timestamp deliberately differs from an FNA defect. FNA computes it as TimeSpan.FromTicks(Environment.TickCount) — but TickCount is a millisecond value, while FromTicks expects 100-nanosecond units. CNA converts milliseconds to ticks. Neither engine defines an absolute epoch for the field; the regression establishes non-negative, strictly increasing values across two gestures under an advanced test clock.

TextInput is a System::MulticastAction<charcs> that fires once per composed UTF-16 unit; a non-BMP code point arrives as a surrogate pair. TextEditing carries the uncommitted IME candidate, cursor start, and selection length. StartTextInput() and StopTextInput() enable or disable this event period, and IsTextInputActive() reports it. SetInputRectangle() positions a composition popup in logical window coordinates, while IsScreenKeyboardShown() reports a platform keyboard. The CNA-only StartTextInputWithTypeEXT() adds a plain-text, numeric, email, or similar mobile keyboard hint.

These five subsystems are small static CNAEXT classes with no XNA counterpart. Clipboard wraps SDL with GetTextEXT(), SetTextEXT(text), and HasTextEXT(). Joysticks exposes the raw, unmapped view of connected joystick hardware (GetJoysticksEXT() enumerates every connected device; GetCapabilitiesEXT(id) / GetStateEXT(id) read one device’s shape and current state directly by axis/button/hat index) — deliberately independent of GamePad’s own mapped, Xbox-360-shaped view of the same physical hardware, for the rarer case where an application needs a device’s true native layout rather than GamePad’s normalized abstraction. Sensors (GetSensorsEXT(), GetAccelerometerEXT / GetGyroscopeEXT) reads the host device’s own motion sensors — a laptop’s built-in accelerometer, a Steam Deck’s gyro — distinct from a gamepad controller’s own motion sensors already covered under GamePad’s EXT surface above. The current implementation never initializes SDL_INIT_SENSOR itself, however. Unless another subsystem has already initialized SDL sensors, enumeration is empty and both readers return false; fake-backend tests do not expose this latent production no-op. Power is a single method, GetInfoEXT(secondsLeft&, percent&), returning a PowerStateEXT plus two output parameters — the host device’s own battery state, not a gamepad’s (that is GamePad::GetPowerInfoEXT instead).

Haptics maintains device and effect lifetimes. GetHapticsEXT() enumerates force-feedback-capable devices, and OpenEXT(id) / OpenFromJoystickEXT(joystickId) / OpenFromMouseEXT() each return an owning HapticDevice handle. That handle’s own surface splits cleanly into two tiers: a simple InitRumbleEXT() / PlayRumbleEXT(strength, lengthMs) / StopRumbleEXT() trio for the common single-motor-strength case (the same conceptual level as GamePad::SetVibration, just reachable for non-gamepad haptic hardware too), and a full HapticEffectEXT lifecycle — CreateEffectEXT / UpdateEffectEXT / RunEffectEXT / StopEffectEXT / DestroyEffectEXT, plus GetEffectStatusEXT to poll whether an effect is running. Shaped feedback such as a directional kick or sustained curve is available only when IsEffectSupportedEXT accepts that effect type.

Like Sensors, this wrapper assumes its SDL subsystem already exists. No input-module path calls SDL_InitSubSystem(SDL_INIT_HAPTIC), and the focused haptic tests replace the backend rather than exercising subsystem startup. Unless the host or another module has initialized it, enumeration/open calls can fail before hardware capability is relevant. Treat subsystem ownership as an application integration requirement for both extension families.