Named actions resolved from physical bindings, sampled once per frame. More...

#include <input_map.h>

Public Member Functions
void	define (std::string_view action, std::vector< InputBinding > bindings)
	Define (or replace) an action's bindings.
void	addBinding (std::string_view action, InputBinding binding)
	Add one binding to an action, defining it if new.
void	clearBindings (std::string_view action)
	Drop every binding for `action`, keeping the action defined.
const std::vector< InputBinding > &	bindings (std::string_view action) const
	Bindings currently feeding `action`.
std::vector< std::string >	actions () const
	Every defined action name, in name order.
void	update (InputHandle &input, const HostChrome &chrome)
	Sample every action from `input`, rolling the previous values.
void	setPointerOverUI (bool over)
	Say whether the pointer is over a blocking element of the game's UI.
void	discardPendingEdges ()
	Drop the edges latched since the last command.
void	reset ()
	Forget every action and every latched edge, then define the engine's own.
void	beginTick (uint32_t tick)
	Build the command for `tick` from everything since the last one.
void	setView (const glm::quat &view)
	Say where the player is looking, for the commands that follow.
int	indexOf (std::string_view action) const
	The command's slot for `action`, or -1 when it has none.
uint64_t	actionFingerprint () const
	A fingerprint of which action holds which command slot.
bool	held (std::string_view action) const
	Is the action active this frame?
bool	pressed (std::string_view action) const
	Did it become active this frame?
bool	released (std::string_view action) const
	Did it stop being active this frame?
float	axis (std::string_view action) const
	Summed, clamped value of the action's bindings, -1..1.
bool	held (const InputCommand &command, std::string_view action) const
	Is the action active in `command`? (the tick's answer)
bool	pressed (const InputCommand &command, std::string_view action) const
	Did it become active since the previous command?
bool	released (const InputCommand &command, std::string_view action) const
	Did it stop being active since the previous command?
float	axis (const InputCommand &command, std::string_view action) const
	The action's value in `command`, -1..1.
bool	pointerOverUI () const
	Whether the pointer was over a blocking element of the game's UI.
const glm::vec2 &	pointer () const
	Where the pointer is this frame, in window pixels.
const glm::vec2 &	pointerDelta () const
	How far the pointer moved since the previous frame, in window pixels.
float	wheel () const
	Wheel notches turned this frame for gameplay, positive away from the viewer.
float	uiWheel () const
	Wheel notches turned this frame, whatever is under the pointer.
std::u32string_view	text () const
	The characters typed this frame, in order, as UTF-32.
bool	typed (int key) const
	Whether `key` went down or auto-repeated this frame.
const InputCommand &	command () const
	The command the current fixed step is running under.
uint32_t	actionCount () const
	How many action slots are in use.

Detailed Description

Named actions resolved from physical bindings, sampled once per frame.

Sampled before any system runs, so every reader in the frame agrees. The frame queries serve frame-rate work only: a fixed update reads the per-tick InputCommand that beginTick() builds from the edges latched between ticks.

Member Function Documentation

◆ define()

void Vkm::Engine::InputMap::define	(	std::string_view	action,
		std::vector< InputBinding >	bindings )

Define (or replace) an action's bindings.

Parameters

action	Action name, e.g. "Move/Forward"; the stable identity a saved binding file refers to.
bindings	Physical controls feeding it.

◆ addBinding()

void Vkm::Engine::InputMap::addBinding	(	std::string_view	action,
		InputBinding	binding )

Add one binding to an action, defining it if new.

Parameters

action	Action name.
binding	Control added alongside the existing ones.

◆ clearBindings()

void Vkm::Engine::InputMap::clearBindings ( std::string_view action )

Drop every binding for action, keeping the action defined.

Parameters

action Action name; an undefined one is a no-op.

◆ bindings()

const std::vector< InputBinding > & Vkm::Engine::InputMap::bindings ( std::string_view action ) const

Bindings currently feeding action.

Parameters

action Action name.

Returns: Its bindings; empty if the action is undefined.

◆ actions()

std::vector< std::string > Vkm::Engine::InputMap::actions ( ) const

Every defined action name, in name order.

Returns: The names, sorted, so two runs produce the same file.

◆ update()

void Vkm::Engine::InputMap::update	(	InputHandle &	input,
		const HostChrome &	chrome )

Sample every action from input, rolling the previous values.

Called once per frame before the systems run; also latches edges for the next command. A binding struck since the last sample reads as down, so a sub-frame tap is held for one frame. A device the host's UI holds reads as untouched (the pointer position still travels). A press belongs to whoever held the device when it began, until let go; a press beginning over a blocking game UI element reads as down for UI_CLICK alone.

Parameters

input	Device state to sample; its strikes are cleared.
chrome	What the host's UI holds this frame.

◆ setPointerOverUI()

void Vkm::Engine::InputMap::setPointerOverUI ( bool over )

inline

Say whether the pointer is over a blocking element of the game's UI.

Read by the next update(): one frame of lag, as the host's chrome has.

Parameters

over	Whether a blocking element is under the pointer.

◆ discardPendingEdges()

void Vkm::Engine::InputMap::discardPendingEdges ( )

Drop the edges latched since the last command.

For a frame no tick follows (Clock::isSimulationStill); otherwise the next tick, such as the first of a Play session, would get every press made meanwhile.

◆ reset()

void Vkm::Engine::InputMap::reset ( )

Forget every action and every latched edge, then define the engine's own.

Frees the command slots, which kept would fill MAX_INPUT_ACTIONS across sessions. The command sequence keeps counting, since an ack names it; a press held across a reset stays with its holder until let go.

◆ beginTick()

void Vkm::Engine::InputMap::beginTick ( uint32_t tick )

Build the command for tick from everything since the last one.

Called once per fixed step before the systems run. Clears the latch, so one keypress does not read as pressed on every tick of a slow frame.

Parameters

tick	Simulation tick the command drives.

◆ setView()

void Vkm::Engine::InputMap::setView ( const glm::quat & view )

inline

Say where the player is looking, for the commands that follow.

Read back off InputCommand::view in a fixed update. A game steering relative to its camera calls this once per frame after moving it.

Parameters

view	Orientation the input from now on is aimed with.

◆ indexOf()

int Vkm::Engine::InputMap::indexOf ( std::string_view action ) const

The command's slot for action, or -1 when it has none.

Assigned in definition order, stable for the session. An action past MAX_INPUT_ACTIONS has no slot: absent from every command, still answered by the frame queries.

Parameters

action Action name.

Returns: Index into InputCommand::axis, or -1.

◆ actionFingerprint()

uint64_t Vkm::Engine::InputMap::actionFingerprint ( ) const

A fingerprint of which action holds which command slot.

Two ends defining the same actions in a different order agree on actionCount() but misread each other's commands; this tells them apart.

Returns: A hash of the slotted names in slot order, or zero when no action has a slot.

◆ held() [1/2]

bool Vkm::Engine::InputMap::held ( std::string_view action ) const

Is the action active this frame?

The summed value decides: W and S held together cancel.

Parameters

action Action name.

Returns: Whether its value is at or past the activation threshold; false if undefined.

◆ pressed() [1/2]

bool Vkm::Engine::InputMap::pressed ( std::string_view action ) const

Did it become active this frame?

Parameters

action Action name.

Returns: Whether it is active now and was not the previous frame.

◆ released() [1/2]

bool Vkm::Engine::InputMap::released ( std::string_view action ) const

Did it stop being active this frame?

Parameters

action Action name.

Returns: Whether it was active the previous frame and is not now.

◆ axis() [1/2]

float Vkm::Engine::InputMap::axis ( std::string_view action ) const

Summed, clamped value of the action's bindings, -1..1.

Parameters

action Action name.

Returns: Its value this frame; 0 if undefined.

◆ held() [2/2]

bool Vkm::Engine::InputMap::held	(	const InputCommand &	command,
		std::string_view	action ) const

Is the action active in command? (the tick's answer)

A fixed update must read these command queries: the frame queries drop a tap between ticks and repeat a press on every tick of a slow frame. Only the name-to-slot resolution comes from this map; an action with no slot reads as inactive.

Parameters

command	Command to read; the tick's, a peer's, or a replayed one.
action	Action name.

Returns: Whether the action reads as down in that command.

◆ pressed() [2/2]

bool Vkm::Engine::InputMap::pressed	(	const InputCommand &	command,
		std::string_view	action ) const

Did it become active since the previous command?

Parameters

command	Command to read.
action	Action name.

Returns: Whether the command carries a press edge for it.

◆ released() [2/2]

bool Vkm::Engine::InputMap::released	(	const InputCommand &	command,
		std::string_view	action ) const

Did it stop being active since the previous command?

Parameters

command	Command to read.
action	Action name.

Returns: Whether the command carries a release edge for it.

◆ axis() [2/2]

float Vkm::Engine::InputMap::axis	(	const InputCommand &	command,
		std::string_view	action ) const

The action's value in command, -1..1.

Parameters

command	Command to read.
action	Action name.

Returns: Its axis value, or 0 when the action has no command slot.

◆ pointerOverUI()

bool Vkm::Engine::InputMap::pointerOverUI ( ) const

inline

Whether the pointer was over a blocking element of the game's UI.

As of the last UI layout; e.g. for hiding a crosshair over a panel.

Returns: What UISystem last set through setPointerOverUI.

◆ pointer()

const glm::vec2 & Vkm::Engine::InputMap::pointer ( ) const

inline

Where the pointer is this frame, in window pixels.

Not framebuffer pixels: scale by WindowManager::framebufferScale for those.

Returns: Cursor position, origin at the window's top-left.

◆ pointerDelta()

const glm::vec2 & Vkm::Engine::InputMap::pointerDelta ( ) const

inline

How far the pointer moved since the previous frame, in window pixels.

Zero on the first frame and while no window exists.

Returns: The movement; zero while the host's UI holds the pointer.

◆ wheel()

float Vkm::Engine::InputMap::wheel ( ) const

inline

Wheel notches turned this frame for gameplay, positive away from the viewer.

Zero while the pointer is over a blocking game UI element or the host's UI holds it.

Returns: The notches gameplay may act on.

◆ uiWheel()

float Vkm::Engine::InputMap::uiWheel ( ) const

inline

Wheel notches turned this frame, whatever is under the pointer.

Zero only while the host's UI holds the pointer.

Returns: Every notch turned.

◆ text()

std::u32string_view Vkm::Engine::InputMap::text ( ) const

inline

The characters typed this frame, in order, as UTF-32.

Layout, Shift and dead keys applied, which no binding can say. Empty while the host's UI holds the keyboard.

Returns: This frame's characters, valid until the next update().

◆ typed()

bool Vkm::Engine::InputMap::typed ( int key ) const

inline

Whether key went down or auto-repeated this frame.

For editing keys (Backspace, arrows, Enter), which act again at the repeat rate as pressed() does not. False while the host's UI holds the keyboard.

Parameters

key	GLFW key code.

Returns: Whether it was typed this frame; false for out-of-range keys.

◆ command()

const InputCommand & Vkm::Engine::InputMap::command ( ) const

inline

The command the current fixed step is running under.

Zeroed before the first beginTick(), so an early reader sees no input, not stale input.

Returns: The current tick's command.

◆ actionCount()

uint32_t Vkm::Engine::InputMap::actionCount ( ) const

inline

How many action slots are in use.

The width of the part of a command that carries anything; both ends of a session must agree on it.

Returns: Slots assigned, at most MAX_INPUT_ACTIONS.

The documentation for this class was generated from the following file:

platform/input/input_map.h

Public Member Functions

Detailed Description

Member Function Documentation

◆ define()

◆ addBinding()

◆ clearBindings()

◆ bindings()

◆ actions()

◆ update()

◆ setPointerOverUI()

◆ discardPendingEdges()

◆ reset()

◆ beginTick()

◆ setView()

◆ indexOf()

◆ actionFingerprint()

◆ held() [1/2]

◆ pressed() [1/2]

◆ released() [1/2]

◆ axis() [1/2]

◆ held() [2/2]

◆ pressed() [2/2]

◆ released() [2/2]

◆ axis() [2/2]

◆ pointerOverUI()

◆ pointer()

◆ pointerDelta()

◆ wheel()

◆ uiWheel()

◆ text()

◆ typed()

◆ command()

◆ actionCount()