Class Bindings
Defined in File input-bindings.h
Class Documentation
-
class Bindings
Owns physical-to-semantic mappings.
Device notifications update pending physical state on the polling thread; publish_actions() commits one immutable result for a platform poll. Configuration and on_* calls belong to that same owner thread. Published handles may be read on other threads.
Public Functions
-
Bindings() = default
Create an empty mapper with a retained initial snapshot, no mappings and lazy context-endpoint state.
Construction/allocation may fail.
-
~Bindings()
Close retained context endpoints and invalidate leases after mapper users quiesce.
Published immutable snapshots and retained context identities remain usable.
-
ContextSubmission action_contexts()
Declaration:
[[nodiscard]]Acquire on the polling/binding owner; retain the returned synchronized endpoint to attach definitions from other producers.
It does not retain this mapper or adapter.
-
void begin_poll()
Apply accepted context additions/removals at an explicit poll boundary, seeding held buttons/current absolute axes/device gates.
Mid-poll requests wait for the next boundary; prior relative deltas are not replayed. Legacy on_* or publication opens a boundary lazily. Evaluation/allocation failures may propagate.
-
BindingId bind_button(CE::Input::Control control, Id action)
Declaration:
[[nodiscard]]Bind one known physical control on the polling owner; equivalent to a one-control chord.
Return a nonzero registration token. Multiple button mappings to one action combine with OR; button/axis conflicts and pending relative activity reject.
-
BindingId bind_button(Chord chord, Id action)
Declaration:
[[nodiscard]]Own a nonempty AND chord; alternatives for the same action combine with OR.
Reject invalid controls, axis conflicts or pending relative activity before registration. Allocation can fail; binding IDs may skip. Device IDs are values, not borrowed device objects.
See also
-
BindingId bind_axis(CE::Input::Control axis, Id action, AxisOptions options = {})
Declaration:
[[nodiscard]]Bind an unconditional axis contribution; equivalent to an empty modifier chord.
Return its nonzero registration token. Scale/dead-zone/kind and action compatibility are validated.
-
BindingId bind_axis(Chord modifiers, CE::Input::Control axis, Id action, AxisOptions options = {})
Declaration:
[[nodiscard]]Own a modifier-gated additive axis contribution; empty modifiers are unconditional.
Reject unknown controls, nonfinite scale/dead-zone, dead-zone outside[0,1), invalid/mixed kinds or button conflicts. Pending relative activity must be published before changing to absolute/button behavior; allocation failures propagate.
-
bool unbind(BindingId binding)
Remove one mapping on the polling owner, returning false for unknown tokens.
Next publication reflects removal but preserves already mapped relative activity and old snapshots.
-
void unbind_action(Id action)
Remove all direct mappings to this semantic action, without modifying independent context namespaces or retained snapshots.
Already mapped relative activity survives until publication.
-
void clear()
Invalidate context leases and drop mappings/physical staging/device gates, then publish release/zero state from the old baseline.
Retained endpoints remain open for later attachment. Publication/allocation can throw after mutable state is cleared; this is not atomic rollback.
-
void set_device_enabled(CE::Input::DeviceId device, bool enabled)
Gate semantic contributions while retaining physical state, including active contexts.
Re-enabling can restore held controls/absolute values; other devices and alternative mappings remain independent. Use on the platform polling owner; staging failures need not roll back.
-
void on_axis(CE::Input::Control binding, float value)
Stage a finite absolute physical value without clamping[-1,1].
Updates pending semantic transitions as needed; opens a lazy poll boundary. Invalid values/allocation/scaled overflow can throw after partial staging.
-
void on_delta(CE::Input::Control binding, float delta)
Accumulate finite relative motion using mappings/device gates active when delivered.
Unbinding later does not erase admitted motion; successful publication resets it. Nonfinite/scaled/summed overflow and allocation failures throw without transactional staging guarantees.
-
void on_button(CE::Input::Control binding, bool held)
Stage physical held state and preserve semantic press/release transitions, including same-poll taps.
Repeated identical levels do not create an edge. Opens a lazy poll boundary; allocation failures may leave partial staging.
-
std::shared_ptr<const Snapshot> publish_actions(std::chrono::steady_clock::time_point observed_at = std::chrono::steady_clock::now())
Declaration:
[[nodiscard]]Complete and atomically publish one immutable direct/context snapshot on the polling owner.
Require nondecreasing observation time. Failure preserves the preceding published handle and pending transitions for retry; poll IDs can skip. Success clears transitions/relative activity and retains one release/zero sample for removed actions.
- Returns:
Owned retained state readable from other threads.
-
Bindings() = default