simvx.graphics.platform._event_facts

The facts a platform can add to an input event beyond its identity.

A backend states the event’s identity and its payload; the router fills in what it left out. Two of the things it can fill in are better answered by the platform when the platform knows them, and this module holds the conversions that make those answers comparable across backends: the event’s own time, on the clock the rest of the engine measures with, and the label its key prints under the player’s layout.

Neither is invented here. A platform with nothing to say passes nothing, the router supplies its own answer, and Input.capabilities.event_timestamps reports which of the two happened.

Module Contents

Classes

EventClock

One platform’s event timestamps, mapped onto :func:time.monotonic.

Functions

key_label

The label for a key the platform says prints printed, or None.

Data

__all__

API

simvx.graphics.platform._event_facts.__all__

[‘EventClock’, ‘key_label’]

class simvx.graphics.platform._event_facts.EventClock

One platform’s event timestamps, mapped onto :func:time.monotonic.

SDL3 stamps an event in nanoseconds since it initialised and Qt in milliseconds on a clock whose zero the platform chooses. Neither epoch is monotonic()’s, so a single offset is captured from the first event seen: monotonic() at the moment of receipt, minus that event’s own stamp. Every stamp after it is shifted by that one offset.

The deltas between events are then exactly the platform’s deltas, which is the reason to read a platform time at all: a double click, a key repeat interval and a flick gesture are all differences. The absolute value sits on the clock the frame loop measures with, to within the delivery latency of the first event, which is baked into every stamp thereafter. That is a fraction of a frame once, against per-event error on every event of timing them at receipt.

A stamp of zero is no stamp. Some drivers send it and every synthetic event carries it, so it is reported as “the platform did not say” rather than as an event from the beginning of time.

Initialization

__slots__

(‘_offset’,)

convert(stamp: float) → float | None

stamp, in seconds on the platform’s own clock, as a monotonic time.

Returns None when the platform supplied no usable time, which leaves the event for the router to stamp at receipt.

simvx.graphics.platform._event_facts.key_label(printed: str | None) → str | None

The label for a key the platform says prints printed, or None.

A label is the single character a key produces under the player’s layout: it is what a prompt or a rebind screen shows for a binding that names a physical position, so an AZERTY player reading “a” presses the key that SimVX and the saved binding both call Key.Q.

Everything else a platform offers here is not a label and is refused, so that the router answers from the engine’s US table instead: an empty string, the control character Return and Escape carry, and a platform’s own name for a key that prints nothing (“Space”, “Left Shift”). Those names are that platform’s vocabulary, and taking them would have the same key read differently on each backend.

A letter is lowercased. The three desktop platforms disagree on its case, the engine’s table spells it lowercase, and the case of a letter says nothing about which key was pressed, so agreeing costs nothing. A prompt that wants capitals applies its own.