Maps user buttons to device buttons. More...

#include <GainputInputMap.h>

Public Types
enum	UserButtonPolicy { UBP_FIRST_DOWN, UBP_MAX, UBP_MIN, UBP_AVERAGE }
	Policy for how multiple device buttons are summarized in one user button. More...

Public Member Functions
	InputMap (InputManager &manager, const char *name=0, Allocator &allocator=GetDefaultAllocator())
	Initializes the map. More...

	~InputMap ()
	Unitializes the map.

void	Clear ()
	Clears all mapped inputs.

const InputManager &	GetManager () const
	Returns the input manager this input map uses.

const char *	GetName () const
	Returns the map's name, if any. More...

unsigned	GetId () const
	Returns the map's auto-generated ID (that should not be used outside of the library).

bool	MapBool (UserButtonId userButton, DeviceId device, DeviceButtonId deviceButton)
	Maps a bool-type button. More...

bool	MapFloat (UserButtonId userButton, DeviceId device, DeviceButtonId deviceButton, float min=0.0f, float max=1.0f, FilterFunc_T filterFunc=0, void *filterUserData=0)
	Maps a float-type button, possibly to a custom range. More...

void	Unmap (UserButtonId userButton)
	Removes all mappings for the given user button.

bool	IsMapped (UserButtonId userButton) const
	Returns if the given user button has any mappings.

size_t	GetMappings (UserButtonId userButton, DeviceButtonSpec *outButtons, size_t maxButtonCount) const
	Gets all device buttons mapped to the given user button. More...

bool	SetUserButtonPolicy (UserButtonId userButton, UserButtonPolicy policy)
	Sets how a user button handles inputs from multiple device buttons. More...

bool	SetDeadZone (UserButtonId userButton, float deadZone)
	Sets a dead zone for a float-type button. More...

bool	GetBool (UserButtonId userButton) const
	Returns the bool state of a user button.

bool	GetBoolIsNew (UserButtonId userButton) const
	Returns if the user button is newly down.

bool	GetBoolPrevious (UserButtonId userButton) const
	Returns the bool state of a user button from the previous frame.

bool	GetBoolWasDown (UserButtonId userButton) const
	Returns if the user button has been released.

float	GetFloat (UserButtonId userButton) const
	Returns the float state of a user button.

float	GetFloatPrevious (UserButtonId userButton) const
	Returns the float state of a user button from the previous frame.

float	GetFloatDelta (UserButtonId userButton) const
	Returns the delta between the previous and the current frame of the float state of the given user button.

size_t	GetUserButtonName (UserButtonId userButton, char *buffer, size_t bufferLength) const
	Gets the name of the device button mapped to the given user button. More...

UserButtonId	GetUserButtonId (DeviceId device, DeviceButtonId deviceButton) const
	Returns the user button ID the given device button is mapped to. More...

ListenerId	AddListener (MappedInputListener *listener)
	Registers a listener to be notified when a button state changes. More...

void	RemoveListener (ListenerId listenerId)
	De-registers the given listener.

void	ReorderListeners ()
	Sorts the list of listeners which controls the order in which listeners are called. More...

Detailed Description

Maps user buttons to device buttons.

This is the interface that should be used to get input. You can have several maps that are used simultaneously or use different ones depending on game state. The user button IDs have to be unique per input map.

InputMap uses the provided InputManager to get devices inputs and process them into user-mapped inputs. After creating an InputMap, you should map some device buttons to user buttons (using MapBool() or MapFloat()). User buttons are identified by an ID provided by you. In order to ensure their uniqueness, it's a good idea to define an enum containing all your user buttons for any given InputMap. It's of course possible to map multiple different device button to one user button.

After a user button has been mapped, you can query its state by calling one of the several GetBool* and GetFloat* functions. The result will depend on the mapped device button(s) and the policy (set using SetUserButtonPolicy()).

Examples:: /samples/basic/basicsample_linux.cpp, /samples/basic/basicsample_win.cpp, /samples/dynamic/dynamicsample.cpp, /samples/gesture/gesturesample.cpp, /samples/listener/listenersample.cpp, /samples/recording/recordingsample.cpp, and /samples/sync/syncsample.cpp.

Member Enumeration Documentation

◆ UserButtonPolicy

enum gainput::InputMap::UserButtonPolicy

Policy for how multiple device buttons are summarized in one user button.

Enumerator
UBP_FIRST_DOWN	The first device buttons that is down (or not 0.0f) determines the result.
UBP_MAX	The maximum of all device button states is the result.
UBP_MIN	The minimum of all device button states is the result.
UBP_AVERAGE	The average of all device button states is the result.

Constructor & Destructor Documentation

◆ InputMap()

gainput::InputMap::InputMap	(	InputManager &	manager,
		const char *	name = `0`,
		Allocator &	allocator = `GetDefaultAllocator()`
	)

Initializes the map.

Parameters

manager	The input manager used to get device inputs.
name	The name for the input map (optional). If a name is provided, it is copied to an internal buffer.
allocator	The allocator to be used for all memory allocations.

Member Function Documentation

◆ AddListener()

ListenerId gainput::InputMap::AddListener ( MappedInputListener * listener )

Registers a listener to be notified when a button state changes.

If there are listeners registered, all input devices will have to record their state changes. This incurs extra runtime costs.

Examples:: /samples/listener/listenersample.cpp.

◆ GetMappings()

size_t gainput::InputMap::GetMappings	(	UserButtonId	userButton,
		DeviceButtonSpec *	outButtons,
		size_t	maxButtonCount
	)		const

Gets all device buttons mapped to the given user button.

Parameters

	userButton	The user button ID of the button to return all mappings for.
[out]	outButtons	An array with maxButtonCount fields to receive the device buttons that are mapped.
	maxButtonCount	The number of fields in outButtons.

Returns: The number of device buttons written to outButtons.

Examples:: /samples/dynamic/dynamicsample.cpp.

◆ GetName()

const char* gainput::InputMap::GetName ( ) const

inline

Returns the map's name, if any.

Returns: The map's name or 0 if no name was set.

Examples:: /samples/dynamic/dynamicsample.cpp.

◆ GetUserButtonId()

UserButtonId gainput::InputMap::GetUserButtonId	(	DeviceId	device,
		DeviceButtonId	deviceButton
	)		const

Returns the user button ID the given device button is mapped to.

This function iterates over all mapped buttons and therefore shouldn't be used in a performance critical situation.

Parameters

device	The device's ID of the device button to be checked.
deviceButton	The ID of the device button to be checked.

Returns: The user button ID the device button is mapped to or InvalidDeviceButtonId if the device button is not mapped.

Examples:: /samples/dynamic/dynamicsample.cpp.

◆ GetUserButtonName()

size_t gainput::InputMap::GetUserButtonName	(	UserButtonId	userButton,
		char *	buffer,
		size_t	bufferLength
	)		const

Gets the name of the device button mapped to the given user button.

Parameters

userButton	ID of the user button.
buffer	A char-buffer to receive the button name.
bufferLength	Length of the buffer receiving the button name in bytes.

Returns: The number of bytes written to buffer (includes the trailing \0).

◆ MapBool()

bool gainput::InputMap::MapBool	(	UserButtonId	userButton,
		DeviceId	device,
		DeviceButtonId	deviceButton
	)

Maps a bool-type button.

Parameters

userButton	The user ID for this mapping.
device	The device's ID of the device button to be mapped.
deviceButton	The ID of the device button to be mapped.

Returns: true if the mapping was created.

Examples:: /samples/dynamic/dynamicsample.cpp, /samples/gesture/gesturesample.cpp, /samples/listener/listenersample.cpp, /samples/recording/recordingsample.cpp, and /samples/sync/syncsample.cpp.

◆ MapFloat()

bool gainput::InputMap::MapFloat	(	UserButtonId	userButton,
		DeviceId	device,
		DeviceButtonId	deviceButton,
		float	min = `0.0f`,
		float	max = `1.0f`,
		FilterFunc_T	filterFunc = `0`,
		void *	filterUserData = `0`
	)

Maps a float-type button, possibly to a custom range.

Parameters

userButton	The user ID for this mapping.
device	The device's ID of the device button to be mapped.
deviceButton	The ID of the device button to be mapped.
min	Optional minimum value of the mapped button.
max	Optional maximum value of the mapped button.
filterFunc	Optional filter functions that modifies the device button value.
filterUserData	Optional user data pointer that is passed to filterFunc.

Returns: true if the mapping was created.

Examples:: /samples/dynamic/dynamicsample.cpp, /samples/gesture/gesturesample.cpp, /samples/listener/listenersample.cpp, and /samples/sync/syncsample.cpp.

◆ ReorderListeners()

void gainput::InputMap::ReorderListeners ( )

Sorts the list of listeners which controls the order in which listeners are called.

The order of listeners may be important as the functions being called to notify a listener of a state change can control if the state change will be passed to any consequent listeners. Call this function whenever listener priorites have changed. It is automatically called by AddListener() and RemoveListener().

◆ SetDeadZone()

bool gainput::InputMap::SetDeadZone	(	UserButtonId	userButton,
		float	deadZone
	)

Sets a dead zone for a float-type button.

If a dead zone is set for a button anything less or equal to the given value will be treated as 0.0f. The absolute input value is used in order to determine if the input value falls within the dead zone (i.e. with a dead zone of 0.2f, both -0.1f and 0.1f will result in 0.0f).

Parameters

userButton	The user button's ID.
deadZone	The dead zone to be set.

Returns: true if the dead zone was set, false otherwise (i.e. the user button doesn't exist).

◆ SetUserButtonPolicy()

bool gainput::InputMap::SetUserButtonPolicy	(	UserButtonId	userButton,
		UserButtonPolicy	policy
	)

Sets how a user button handles inputs from multiple device buttons.

Returns: true if the policy was set, false otherwise (i.e. the user button doesn't exist).

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

lib/include/gainput/GainputInputMap.h

Public Types

Public Member Functions

Detailed Description

Member Enumeration Documentation

◆ UserButtonPolicy

Constructor & Destructor Documentation

◆ InputMap()

Member Function Documentation

◆ AddListener()

◆ GetMappings()

◆ GetName()

◆ GetUserButtonId()

◆ GetUserButtonName()

◆ MapBool()

◆ MapFloat()

◆ ReorderListeners()

◆ SetDeadZone()

◆ SetUserButtonPolicy()