The input model: snapshots, keys, the mouse and logical coordinates

CNA snapshot 009d40f5  ·  Deep Dives › Input, audio, media & services  ·  source links pinned to 009d40f5

This page states the exact contract of CNA's keyboard and mouse input: what a GetState() call really returns and when it changes, how the 160 Keys values relate to physical keys and keyboard layouts, which mouse members are XNA and which are extensions, and how window pixels become the logical coordinates a game sees. It is for anyone porting input code, binding controls on non-US layouts, or debugging a mouse position that looks wrong under a virtual resolution. The user-level tour is the Input System guide; the event plumbing behind it is traced for maintainers on Input internals.

Where a GetState value comes from

FNA asks SDL for the current device state inside each GetState() call. CNA does not. Native events are drained once per frame by Game::PollEvents in Game.cpp, every event is first handed to PlatformInputBridge::ProcessEvent, and at the end of that batch the selected platform's keyboard and mouse services publish a snapshot. Keyboard::GetState() and Mouse::GetState() copy that snapshot; they never call a native API. The bridge itself feeds text input, touch, click notifications, device callbacks and a set of legacy accumulators that no public getter reads. Older descriptions in which the bridge's InputManager is the source of the public keyboard and mouse state describe an earlier design and are stale.

Three consequences are part of the contract rather than implementation detail:

• Repeatable reads. Two reads in the same frame return the same keyboard, absolute mouse and gamepad state; a read before the first pump sees the initial state, and several fixed-step Update calls inside one slow Tick all see the snapshot of the last completed pump.
• One consume-on-read exception. In relative mouse mode Mouse::GetState() drains the service's motion accumulator (IPlatformMouse::ConsumeRelativeDelta), so the second read in a frame returns zero motion. This is FNA's deliberate draining semantic, kept on purpose.
• One thread. The event pump and every state read belong on the game-loop thread. The input module contains no mutex or atomic, and TextInputEXT's own header states the same rule for its events.

Two ordinary keys carry a framework side effect: after the bridge has recorded a non-repeat press, Game::PollEvents calls the renderer's DebugSimulateContextLoss() on F9 and DebugRestoreContext() on F10. Both keys still reach Keyboard::GetState(), so a game can see them but cannot suppress the debug action; do not bind gameplay to them unless that loop code is changed. The frame order and the per-backend event mappers are on Input internals: actual order in one frame.

STRICT, EXT and CNAEXT members

CNA's input documentation (docs/input-public-api-frozen.md) sorts every public input member into tiers: STRICT members are XNA 4.0 API and must match XNA and FNA in name and signature; FNA-compatible members are STRICT members whose behaviour deliberately follows FNA where XNA left it to the platform; EXT members are FNA's own extensions beyond XNA (the EXT name suffix, for example Keyboard::GetKeyFromScancodeEXT or TextInputEXT); and CNAEXT members are CNA additions with no FNA counterpart. Non-enum extensions carry the CNAEXT marker macro whichever of the last two tiers they belong to, and a non-XNA enum value carries only the EXT suffix (Buttons::Misc1EXT). PublicApiInputSignatureFreezeTests.cpp takes the address of, or static_asserts, every frozen member, so a signature change fails to compile rather than slipping through.

Keys, KeyboardState and what a key value means

The Keys numbering

Keys has exactly 160 enumerators, numbered as the Windows virtual-key codes that XNA and FNA use, including the irregular ones: Pause = 19, Kana = 21, ImeConvert = 28, ChatPadGreen = 202, ProcessKey = 229. They are preserved exactly instead of being renumbered for tidiness, because games and saved input bindings persist keys by number. KeysValuesMatchXNANumericConstants in KeyboardInputTests.cpp pins every enumerator to a literal value (its comment records a name-for-name and value-for-value comparison with FNA's Keys.cs), and KeyCodeMatchesXnaKeysTests.cpp keeps the platform's own KeyCode numerically equal to Keys, which is what makes the plain cast between them safe.

KeyboardState

KeyboardState (KeyboardState.cpp) stores the pressed keys in a std::unordered_set<Keys> instead of FNA's eight 32-bit words, while keeping every observable query of the bitfield:

Keyboard is static-only. Keyboard::GetState(PlayerIndex) ignores its argument and returns the same state as GetState(): the keyboard is not split by player. With no keyboard service on the selected platform (Headless, or a terminal that is not a TTY) both return an empty state rather than throwing.

Physical keys, layouts and the scancode helpers

XNA's Keys is shaped like a US QWERTY keyboard, while modern platforms distinguish a scancode (a physical position) from a keycode (what the current layout prints on that key). Keyboard::GetState() reports layout keycodes: on the default SDL3 platform the snapshot resolves each held scancode to its unmodified layout key with SDL_GetKeyFromScancode. The extension helpers bridge the two views; they live in Keyboard.cpp and the name tables in SdlInputBridge.cpp (the file name is historical; it holds no SDL call).

The fallback tables are not symmetric. At this snapshot the bridge maps 122 platform scancodes to a Keys value but only 119 Keys values back to a scancode, because several positions share a key: the keypad Enter becomes Keys::Enter, the keypad period Keys::OemPeriod, and both the Application and Menu positions Keys::Apps. Forty non-None keys have no physical position at all and therefore cannot round-trip through the helpers: the IME keys (Kana, Kanji, ImeConvert, ProcessKey), the ChatPad keys, the browser and media keys, VolumeMute, and OemBackslash, the extra key of ISO keyboards whose platform scancode is deliberately left unmapped. Typed text must therefore go through TextInputEXT, never through the assumption that every character has a Keys value; several accented letters of European layouts have none and are simply absent from keyboard state.

The environment variable FNA_KEYBOARD_USE_SCANCODES=1 is read once per process. At this snapshot it changes only how the bridge interprets key events and makes GetKeyFromScancodeEXT return its argument unchanged; no platform keyboard service reads it, so it does not change what Keyboard::GetState() reports. Physical-position bindings therefore rest on the helper above, not on the variable.

Worked example: WASD on any layout

Binding movement to positions rather than letters keeps it usable on AZERTY, QWERTZ and Dvorak. Resolve the four positions once (and again if the layout can change), then poll the resolved keys:

#include "Microsoft/Xna/Framework/Input/Keyboard.hpp"
using namespace Microsoft::Xna::Framework::Input;

// The keys the current layout has where a US keyboard has W, A, S and D.
const Keys forwardKey = Keyboard::GetKeyFromScancodeEXT(Keys::W); // Z on AZERTY
const Keys leftKey    = Keyboard::GetKeyFromScancodeEXT(Keys::A); // Q on AZERTY
const Keys backKey    = Keyboard::GetKeyFromScancodeEXT(Keys::S);
const Keys rightKey   = Keyboard::GetKeyFromScancodeEXT(Keys::D);

const KeyboardState keyboard = Keyboard::GetState();
if (keyboard.IsKeyDown(forwardKey))
{
    // move forward
}

This fragment was syntax-checked against the TARGET headers with g++ -std=c++23 -fsyntax-only (not executed). With scancode mode switched on the helper returns its argument, which is also what the positions mean in that mode.

Mouse state and the mouse extensions

MouseState

MouseState (MouseState.cpp) is a plain value: X, Y, the five ButtonState values (LeftButton, RightButton, MiddleButton, XButton1, XButton2), the cumulative ScrollWheelValue in XNA's 120 units per notch, and the CNAEXT HorizontalScrollWheelValueEXT accumulated the same way. The constructor takes the buttons in XNA's order (left, middle, right, X1, X2). The horizontal value is deliberately excluded from Equals, GetHashCode and ToString, so those three stay identical to FNA's output even though the extra field exists; HorizontalScrollWheelEXTIsExcludedFromEqualityAndHash pins it. ToString prints [MouseState X=…, Y=…, Buttons=…, Wheel=…] with the pressed buttons in left, right, middle, X1, X2 order, and the hash is x ^ (y*31) ^ (wheel*17) computed in unsigned arithmetic so it cannot overflow a signed integer.

Mouse members at a glance

The desktop-coordinate calls depend on the platform's GlobalPointer capability. The native Wayland mouse service (clients are never given desktop coordinates) and the terminal mouse service both throw PlatformNotSupportedException from those operations, and Mouse::GetGlobalPositionEXT, WarpGlobalEXT and SetCaptureEXT do not catch it at this snapshot, so on those platforms the calls throw rather than answer (0, 0). The test that calls all three "on the real platform" runs on whatever platform the test build selected, not on Wayland. Relative mode, by contrast, is the supported pointer path on Wayland.

MouseCursor

MouseCursor (MouseCursor.cpp) holds a description, never a native handle; the platform service creates the native cursor when Mouse::SetCursor is called. There are twelve stock cursors (Arrow, Crosshair, Hand, IBeam, No, SizeAll, SizeNESW, SizeNS, SizeNWSE, SizeWE, Wait, WaitArrow), each a lazily constructed function-local static shared for the process lifetime. Dispose() on a stock instance is deliberately a no-op: MonoGame's PlatformDispose() frees a shared stock handle unconditionally, which can break every other user of that cursor, and DisposingAStockSingletonIsANoOpAndKeepsItUsable pins CNA's choice. FromTexture2D accepts only SurfaceFormat::Color or ColorSrgbEXT textures (std::invalid_argument otherwise) and throws std::runtime_error when the hot spot lies outside the texture.

Worked example: FPS-style camera look

// Once, when entering first-person control (inside a Game subclass):
setIsMouseVisibleProperty(false);
Mouse::setIsRelativeMouseModeEXTProperty(true);

// Each Update: relative mode reports motion since the previous read.
const MouseState mouse = Mouse::GetState();          // drains the accumulated delta
const float yaw   = static_cast<float>(mouse.getXProperty()) * mouseSensitivity;
const float pitch = static_cast<float>(mouse.getYProperty()) * mouseSensitivity;
cameraRotation = Quaternion::CreateFromYawPitchRoll(yaw, pitch, 0.0f) * cameraRotation;

Read the mouse once per update and pass the value around: a second GetState() in the same frame returns zero motion. The mouse part of this fragment was syntax-checked against the TARGET headers (not executed); in a browser build relative mode maps onto the Pointer Lock API, which the browser grants only after a user gesture.

Logical coordinates are a renderer contract

Under a virtual resolution or a letterboxed presentation, XNA code expects Mouse::GetState() to answer in game coordinates, not window pixels. CNA gets there through a registry keyed by the platform's WindowId: a renderer that knows its presentation geometry registers itself with IGraphicsRenderer::RegisterForWindow and implements TransformWindowToLogical and its inverse TransformLogicalToWindow (IGraphicsRenderer.hpp). By contract the renderer alone accounts for presentation scale, letterbox offsets and the difference between client units and drawable pixels on a high-density display.

The same lookup serves every direction. Mouse::GetState() converts the service's window-client position; the bridge converts the positions of motion and button events for its accumulators and for mouse-to-touch emulation; a touch event's normalized position is first multiplied by the event's client size and then goes through the same transform; and Mouse::SetPosition applies the inverse. A bad or missing transform therefore misplaces absolute reads, click positions and touch together, while relative motion is deliberately left as an unscaled delta. When no renderer is registered for the window, or the transform returns false, the coordinates pass through unchanged, which is also the correct 1:1 answer for a windowless or unscaled game.

Two consequences are worth knowing. On the renderers that answer false in a bar, a pointer over a letterbox bar reports its raw window coordinate, not an out-of-range logical one, because the input side keeps the untransformed value when the renderer declines; a game that hit-tests near the edges of the play area should reject positions outside its logical bounds itself. And the richer vocabulary of presentation modes is not the same thing as uniform implementation: the table is a reading of each renderer's source, and no test compares the mapping of every renderer in every mode on a high-density display.

The automated proof of the mechanism itself is CoordinateTransformPreservesLetterboxOffsetAndInverse in MouseInputTests.cpp: a fake renderer with a 50-pixel letterbox offset maps a window point (100, 50) to logical (50, 50), and SetPosition(25, 75) reaches the service as window (75, 75). The round trip reads back through a canned mouse service that records the warp, so it proves the conversion and the hand-off, not that an operating-system cursor landed on that pixel. Renderer-specific example programs such as presentation_mode_contract_test.cpp and opengl4_transformcoords_test.cpp exist and were not executed for this page. The FREEDIRECT example freedirect_logical_transform_test.cpp is not evidence for the public route either: it calls the renderer's TransformLogicalToWindow and TransformWindowToLogical directly, while Mouse never reaches them because FREEDIRECT does not register for its window. FNA needs none of this machinery: its Mouse.GetState() multiplies window coordinates by the independent back-buffer-to-window ratios and SetPosition applies their inverse, because it has no offset-bearing presentation modes.

Focus loss and held input

A desktop FocusLost window event sets Game::IsActive to false and raises Deactivated; FocusGained sets it back, raises Activated and invalidates the renderer surface. The input bridge synthesizes no key-up or button-up events on focus loss, matching FNA; WindowFocusLostDoesNotClearHeldKeysMatchingFna pins that for the bridge's legacy accumulator. What the public snapshot shows after focus loss is decided by the platform keyboard and mouse services: the SDL3 service reads SDL's own keyboard state, and the Win32 mapper emits a release for every key it had reported as held when WM_KILLFOCUS arrives. Either way the portable rule is the same: gate gameplay input on IsActive and do not rely on focus loss to release keys. FNA additionally restores an X11 fullscreen-desktop flag and toggles the screensaver on focus changes; CNA's Game::PollEvents reproduces neither side effect.

void MyGame::Update(GameTime& gameTime)
{
    Game::Update(gameTime);                 // keeps FrameworkDispatcher::Update running
    if (!getIsActiveProperty())
    {
        return;                             // unfocused: ignore retained keyboard and mouse state
    }
    const KeyboardState keyboard = Keyboard::GetState();
    if (keyboard.IsKeyDown(Keys::Space))
    {
        // process held input only while the window is active
    }
}

Platform boundaries outside CNA

• Wayland. Compositors do not give clients desktop pointer coordinates, and absolute warping is focus-gated. CNA's own manual verification log (an entry for an earlier revision, SDL3 on a Wayland session) records SDL_GetGlobalMouseState returning (0, 0) and names relative mode as the supported path; the native Wayland platform refuses the desktop-coordinate calls outright (see above).
• Controller identifiers on Windows. An XInput controller reports no USB vendor or product id, so GamePad::GetGUIDEXT returns "xinput" instead of a hexadecimal identifier; the full formatting rule is on Gamepads and haptics.
• Touch enumeration. Some platforms enumerate a touch device only after its first interaction, which is why the capability query combines live enumeration with an observed-touch fallback (Touch and gestures).
• Browsers. A gamepad stays invisible until the user presses a button on it, and pointer lock needs a preceding user gesture. These are browser privacy rules that no library can bypass; they were not re-tested for this page.
• Non-US layouts. Characters without a Keys value exist only as text; see the scancode section above.

Evidence and what it does not cover

The input module has 47 test sources with 523 statically counted GoogleTest-family definitions at this snapshot (the site's static count method), and the public signatures are frozen by compile-time tests. That is substantial automated evidence, but CNA's input plan (plans/plan_input.md) keeps fifteen manual-hardware checks formally blocked by design: physical keyboard, mouse, gamepad, touchscreen, IME and high-density display verification. They are absent observations, not passes. The renderer transform table above was read from source; nothing on this page was executed.