#include <InputManager.h>

Classes
struct	InputEventData
	The data that is broadcast when certain events occur. More...

Public Types
using	xiiEventInput = xiiEvent<const InputEventData&>

Static Public Member Functions
static void	Update (xiiTime timeDifference)
static void	SetInputSlotDisplayName (xiiStringView sInputSlot, xiiStringView sDefaultDisplayName)
	Changes the display name of an input slot.
static xiiStringView	GetInputSlotDisplayName (xiiStringView sInputSlot)
	Returns the display name that was assigned to the given input slot.
static xiiStringView	GetInputSlotDisplayName (xiiStringView sInputSet, xiiStringView sAction, xiiInt32 iTrigger=-1)
static void	SetInputSlotDeadZone (xiiStringView sInputSlot, float fDeadZone)
static float	GetInputSlotDeadZone (xiiStringView sInputSlot)
	Returns the dead zone value for the given input slot.
static xiiBitflags< xiiInputSlotFlags >	GetInputSlotFlags (xiiStringView sInputSlot)
	Returns the flags for the given input slot.
static xiiKeyState::Enum	GetInputSlotState (xiiStringView sInputSlot, float *pValue=nullptr)
static void	RetrieveAllKnownInputSlots (xiiDynamicArray< xiiStringView > &out_inputSlots)
	Returns an array that contains all the names of all currently known input slots.
static xiiUInt32	RetrieveLastCharacter (bool bResetCurrent=true)
static void	PollHardware ()
static void	ClearInputMapping (xiiStringView sInputSet, xiiStringView sInputSlot)
static void	SetInputActionConfig (xiiStringView sInputSet, xiiStringView sAction, const xiiInputActionConfig &config, bool bClearPreviousInputMappings)
static xiiInputActionConfig	GetInputActionConfig (xiiStringView sInputSet, xiiStringView sAction)
static void	RemoveInputAction (xiiStringView sInputSet, xiiStringView sAction)
static xiiKeyState::Enum	GetInputActionState (xiiStringView sInputSet, xiiStringView sAction, float pValue=nullptr, xiiInt8 pTriggeredSlot=nullptr)
static void	SetActionDisplayName (xiiStringView sAction, xiiStringView sDisplayName)
	Sets the display name for the given action.
static const xiiString	GetActionDisplayName (xiiStringView sAction)
	Returns the display name for the given action, or the action name itself, if no special display name was specified yet.
static void	GetAllInputSets (xiiDynamicArray< xiiString > &out_inputSetNames)
	Returns the names of all currently registered input sets.
static void	GetAllInputActions (xiiStringView sInputSetName, xiiDynamicArray< xiiString > &out_inputActions)
	Returns the names of all input actions in the given input set.
static void	SetExclusiveInputSet (xiiStringView sExclusiveSet)
static xiiStringView	GetExclusiveInputSet ()
	Returns whether any input set gets input exclusively.
static void	InjectInputSlotValue (xiiStringView sInputSlot, float fValue)
static xiiStringView	GetPressedInputSlot (xiiInputSlotFlags::Enum mustHaveFlags, xiiInputSlotFlags::Enum mustNotHaveFlags)
static xiiStringView	ConvertScanCodeToEngineName (xiiUInt8 uiScanCode, bool bIsExtendedKey)
	Mostly for internal use. Converts a scan-code value to the string that is used inside the engine for that key.
static xiiStringView	GetInputSlotTouchPoint (xiiUInt32 uiIndex)
	Helper for retrieving the input slot string for touch point with a given index.
static xiiStringView	GetInputSlotTouchPointPositionX (xiiUInt32 uiIndex)
	Helper for retrieving the input slot string for touch point x position with a given index.
static xiiStringView	GetInputSlotTouchPointPositionY (xiiUInt32 uiIndex)
	Helper for retrieving the input slot string for touch point y position with a given index.
static xiiEventSubscriptionID	AddEventHandler (xiiEventInput::Handler handler)
	Adds an event handler that is called for input events.
static void	RemoveEventHandler (xiiEventInput::Handler handler)
	Removes a previously added event handler.
static void	RemoveEventHandler (xiiEventSubscriptionID id)

Friends
class	xiiInputDevice

Detailed Description

The central class to set up and query the state of all input.

The xiiInputManager is the central hub through which you can configure which keys will trigger which actions. You can query in which state an action is (inactive (up), active (down), just recently activated (pressed) or just recently deactivated (released)). You can query their values (e.g. how much a thumb-stick or the mouse was moved). Additionally you can localize buttons and actions. The internal data will always use English names and the US keyboard layout, but what with which names those keys are presented to the user can be changed. Although the input manager allows to query the state of each key, button, axis, etc. directly, this is not advised. Instead the user should set up 'actions' and define which keys will trigger those actions. At runtime the user should only query the state of actions. In the best case, an application allows the player to change the mapping which keys are used to trigger which actions.

Member Function Documentation

◆ ClearInputMapping()

void xiiInputManager::ClearInputMapping	(	xiiStringView	sInputSet,
		xiiStringView	sInputSlot )

static

If szInputSlot is used in any action in szInputSet, it will be removed from all of them.

This should be used to reset the usage of an input slot before it is bound to another input action.

◆ ConvertScanCodeToEngineName()

xiiStringView xiiInputManager::ConvertScanCodeToEngineName	(	xiiUInt8	uiScanCode,
		bool	bIsExtendedKey )

static

Mostly for internal use. Converts a scan-code value to the string that is used inside the engine for that key.

◆ GetInputActionConfig()

xiiInputActionConfig xiiInputManager::GetInputActionConfig	(	xiiStringView	sInputSet,
		xiiStringView	sAction )

static

Returns the configuration for the given input action in the given input set. Returns a default configuration, if the action does not exist.

◆ GetInputActionState()

xiiKeyState::Enum xiiInputManager::GetInputActionState	(	xiiStringView	sInputSet,
		xiiStringView	sAction,
		float *	pValue = nullptr,
		xiiInt8 *	pTriggeredSlot = nullptr )

static

Returns the current state and value of the given input action.

This is the one function that is called repeatedly at runtime to figure out which actions are active and thus which game-play functions to execute. You can (and should) use the /a pValue to scale game play features (e.g. how fast to drive).

◆ GetInputSlotDisplayName()

xiiStringView xiiInputManager::GetInputSlotDisplayName	(	xiiStringView	sInputSet,
		xiiStringView	sAction,
		xiiInt32	iTrigger = -1 )

static

A shortcut to get the display name of the input slot bound to a given action

If iTrigger is set, the name of that trigger (0 .. xiiInputActionConfig::MaxInputSlotAlternatives) will be used. If iTrigger is less than 0, the first valid trigger is used. If iTrigger is outside the valid range or no valid trigger is bound, nullptr is returned.

Test: This is new

◆ GetInputSlotState()

xiiKeyState::Enum xiiInputManager::GetInputSlotState	(	xiiStringView	sInputSlot,
		float *	pValue = nullptr )

static

Returns the current key state of the given input slot and optionally also returns its full value.

Do not use this function, unless you really, really need the value of exactly this key. Prefer to map your key to an action and then use GetInputActionState(). That method is more robust and extensible.

◆ GetPressedInputSlot()

xiiStringView xiiInputManager::GetPressedInputSlot	(	xiiInputSlotFlags::Enum	mustHaveFlags,
		xiiInputSlotFlags::Enum	mustNotHaveFlags )

static

Checks whether any input slot has been triggered in this frame, which has all MustHaveFlags and has none of the MustNotHaveFlags.

This function can be used in a UI to wait for user input and then assign that input to a certain action.

◆ InjectInputSlotValue()

void xiiInputManager::InjectInputSlotValue	(	xiiStringView	sInputSlot,
		float	fValue )

static

This function allows to 'inject' input state for one frame.

This can be useful to emulate certain keys, e.g. for virtual devices. Note that it usually makes more sense to actually have another input device, however this can be used to get data into the system quickly for when a full blown input device might be overkill. The injected input state is cleared immediately after it has been processed, so to keep a virtual input slot active, the input needs to be injected every frame.

Note that when the input is injected after xiiInputManager::Update was called, its effect will be delayed by one frame.

◆ PollHardware()

void xiiInputManager::PollHardware ( )

static

Makes sure that hardware input is processed at this moment, which allows to do this more often than Update() is called.

When you have a game where you are doing relatively few game updates (including processing input), for example only 20 times per second, it is possible to 'miss' input. PollHardware() allows to introduce sampling the hardware state more often to prevent this. E.g. when your renderer renders at 60 Hz, you can poll input also at 60 Hz, even though you really only process it at 20 Hz. In typical usage scenarios this is not required to do and can be ignored. Note that you can call PollHardware() as often as you like and at irregular intervals, it will not have a negative effect on the input states.

◆ RemoveInputAction()

void xiiInputManager::RemoveInputAction	(	xiiStringView	sInputSet,
		xiiStringView	sAction )

static

Deletes all state associated with the given input action.

It is not necessary to call this function for cleanup.

◆ RetrieveLastCharacter()

xiiUInt32 xiiInputManager::RetrieveLastCharacter ( bool bResetCurrent = true )

static

Returns the last typed character as the OS has reported it. Thus supports Unicode etc.

If bResetCurrent is true, the internal last character will be reset to '\0'. If it is false, the internal state will not be changed. This should only be used, if the calling code does not do anything meaningful with the value.

◆ SetExclusiveInputSet()

void xiiInputManager::SetExclusiveInputSet ( xiiStringView sExclusiveSet )

inlinestatic

This can be used to pass input exclusively to this input set and no others.

Querying input from other input sets will always return 'key up'.

◆ SetInputActionConfig()

void xiiInputManager::SetInputActionConfig	(	xiiStringView	sInputSet,
		xiiStringView	sAction,
		const xiiInputActionConfig &	config,
		bool	bClearPreviousInputMappings )

static

This is the one function to set up which input actions are available and by which input slots (keys) they are triggered.

Parameters

szInputSet	'Input Sets' are sets of actions that are disjunct from each other. That means the same input slot (key, mouse button, etc.) can trigger multiple different actions from different input sets. For example In the input set 'Game' the left mouse button may trigger the action 'Shoot', but in the input set 'UI' the left mouse button may trigger the action 'Click'. All input sets are always evaluated and update their state simultaneously. The user only has to decide which actions to react to, ie. whether the game is currently running and thus the 'Game' input set is queried or whether a menu is shown and thus the 'UI' input set is queried.
szAction	The action that is supposed to be triggered. The same action name may be reused in multiple input sets, they will have nothing in common. The action name should describe WHAT is to be done, not which key the user pressed. For example an action could be 'player_forwards'. Which key is set to trigger that action should be irrelevant at run-time.
Config	This struct defines exactly which input slots (keys, buttons etc.) will trigger this action. The configuration allows to scale key values by the frame time, to get smooth movement when the frame-rate varies. It allows to only accept input from a slot if two other slots have certain values. This makes it possible to react to mouse or touch input only if that input is done inside a certain input area. The action can be triggered by multiple keys, if desired. In the most common cases, one will only set one or two input slots as triggers (Config.m_sInputSlotTrigger) and possibly decide whether frame time scaling is required. It makes sense to let the xiiInputManager do the frame time scaling, because it should not be applied to all input, e.g. mouse delta values should never be scaled by the frame time.
bClearPreviousInputMappings	If set to true it is ensured that all the input slots that are used by this action are not mapped to any other action. That means no other action can be triggered by this key within this input set. For most actions this should be set to true. However, if you have several actions that can be triggered by the same slot (for example touch input) but only in different areas of the screen, this should be set to false.

◆ SetInputSlotDeadZone()

void xiiInputManager::SetInputSlotDeadZone	(	xiiStringView	sInputSlot,
		float	fDeadZone )

static

Sets the dead zone for the given input slot. As long as the hardware reports values lower than this, the input slot will report a value of zero.

◆ Update()

void xiiInputManager::Update ( xiiTime timeDifference )

static

Updates the state of the input manager. This should be called exactly once each frame.

Parameters

tTimeDifference The time elapsed since the last update. This will affect the value scaling of actions that use frame time scaling and is necessary to update controller vibration tracks.

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

/home/runner/work/XII/XII/Source/Engine/Core/Input/InputManager.h
/home/runner/work/XII/XII/Source/Engine/Core/Input/Implementation/Action.cpp
/home/runner/work/XII/XII/Source/Engine/Core/Input/Implementation/InputManager.cpp
/home/runner/work/XII/XII/Source/Engine/Core/Input/Implementation/ScancodeTable.cpp

Classes

Public Types

Static Public Member Functions

Friends

Detailed Description

Member Function Documentation

◆ ClearInputMapping()

◆ ConvertScanCodeToEngineName()

◆ GetInputActionConfig()

◆ GetInputActionState()

◆ GetInputSlotDisplayName()

◆ GetInputSlotState()

◆ GetPressedInputSlot()

◆ InjectInputSlotValue()

◆ PollHardware()

◆ RemoveInputAction()

◆ RetrieveLastCharacter()

◆ SetExclusiveInputSet()

◆ SetInputActionConfig()

◆ SetInputSlotDeadZone()

◆ Update()