A Virtual Thumb-stick is an input device that transforms certain types of input (mouse / touch) into input similar to a thumb-stick on a controller. More...

#include <VirtualThumbStick.h>

Inheritance diagram for xiiVirtualThumbStick:

[legend]

Classes
struct	CenterMode
	Defines whether the thumb-stick center position is locked or relative to where the user started touching it. More...

struct	Flags

struct	Input
	This enum allows to select either some default input mapping or to select 'Custom'. More...

struct	Output
	Specifies which type of output the thumb-stick shall generate. More...

Public Member Functions
	xiiVirtualThumbStick ()
	Constructor.

	~xiiVirtualThumbStick ()
	Destructor.

void	SetInputArea (const xiiVec2 &vLowerLeft, const xiiVec2 &vUpperRight, float fThumbstickRadius, float fPriority, CenterMode::Enum center=CenterMode::ActivationPoint)
	Defines the area on screen where the thumb-stick is located and accepts input.

void	SetFlags (xiiBitflags< Flags > flags)
	See the Flags struct for details.

xiiBitflags< Flags >	GetFlags () const
	See the Flags struct for details.

void	SetInputCoordinateAspectRatio (float fWidthDivHeight)
	Sets the aspect ratio of the screen on which the input happens.

float	GetInputCoordinateAspectRatio () const
	Returns the screen aspect ratio that was set. See SetInputCoordinateAspectRatio().

void	GetInputArea (xiiVec2 &out_vLowerLeft, xiiVec2 &out_vUpperRight) const
	Returns the input area of the virtual thumb-stick.

void	SetTriggerInputSlot (Input::Enum input, const xiiInputActionConfig *pCustomConfig=nullptr)
	Specifies from which input slots the thumb-stick is activated.

void	SetThumbstickOutput (Output::Enum output, xiiStringView sOutputLeft={}, xiiStringView sOutputRight={}, xiiStringView sOutputUp={}, xiiStringView sOutputDown={})
	Specifies which output the thumb-stick generates.

void	SetAreaFocusMode (xiiInputActionConfig::OnEnterArea onEnter, xiiInputActionConfig::OnLeaveArea onLeave)
	Specifies what happens when the input slots that trigger the thumb-stick are active while entering or leaving the input area.

void	SetEnabled (bool bEnabled)
	Allows to enable or disable the entire thumb-stick temporarily.

bool	IsEnabled () const
	Returns whether the thumb-stick is currently enabled.

bool	IsActive () const
	Returns whether the thumb-stick is currently active (ie. triggered) and generates output.

xiiVec2	GetCurrentCenter () const
	Returns the (normalized screen) coordinate where the current input center is. Depends on CenterMode.

float	GetThumbstickRadius () const
	See SetInputArea() for details.

xiiVec2	GetCurrentTouchPos () const
	Returns the (normalized screen) coordinate where the current touch point is.

float	GetInputStrength () const
	Returns the total strength of input.

xiiVec2	GetInputDirection () const
	Returns the normalized direction of the input.

Public Member Functions inherited from xiiInputDevice
	xiiInputDevice ()
	Default Constructor.

float	GetInputSlotState (xiiStringView sSlot) const
	Allows to query current input values for the given slot.

bool	HasDeviceBeenUsedLastFrame () const
	Returns true, if the device was 'used' during the last frame, ie. when it generated input due to some user interaction.

Public Member Functions inherited from xiiReflectedClass
virtual const xiiRTTI *	GetDynamicRTTI () const

bool	IsInstanceOf (const xiiRTTI *pType) const
	Returns whether the type of this instance is of the given type or derived from it.

template<typename T>
XII_ALWAYS_INLINE bool	IsInstanceOf () const
	Returns whether the type of this instance is of the given type or derived from it.

Protected Member Functions
void	UpdateActionMapping ()

Protected Member Functions inherited from xiiInputDevice
virtual void	ResetInputSlotValues ()
	Override this, if you need to reset certain input slot values to zero, after the xiiInputManager is finished with the current frame update.

virtual void	UpdateHardwareState (xiiTime tTimeDifference)
	This function is called once after xiiInputManager::Update with the same time delta value. It allows to update hardware state, such as the vibration of gamepad motors.

Protected Attributes
xiiVec2	m_vLowerLeft = xiiVec2::MakeZero()

xiiVec2	m_vUpperRight = xiiVec2::MakeZero()

float	m_fRadius = 0.0f

xiiInputActionConfig	m_ActionConfig

xiiStringView	m_sOutputLeft

xiiStringView	m_sOutputRight

xiiStringView	m_sOutputUp

xiiStringView	m_sOutputDown

xiiBitflags< Flags >	m_Flags

bool	m_bEnabled = false

bool	m_bConfigChanged = false

bool	m_bIsActive = false

xiiString	m_sName

xiiVec2	m_vCenter = xiiVec2::MakeZero()

xiiVec2	m_vTouchPos = xiiVec2::MakeZero()

xiiVec2	m_vInputDirection = xiiVec2::MakeZero()

float	m_fInputStrength = 0.0f

float	m_fAspectRatio = 1.0f

CenterMode::Enum	m_CenterMode

Protected Attributes inherited from xiiInputDevice
xiiMap< xiiString, float >	m_InputSlotValues
	Stores all the values for all input slots that this device handles.

xiiUInt32	m_uiLastCharacter
	If this input device type handles character input, it should write the last typed character into this variable. The xiiInputManager calls RetrieveLastCharacter() to query what the user typed last.

Protected Attributes inherited from xiiEnumerable< xiiInputDevice, xiiReflectedClass >
xiiEnumerable *	m_pNextInstance

Static Protected Attributes
static xiiInt32	s_iThumbsticks = 0

Private Member Functions
virtual void	InitializeDevice () override
	Override this if you need to do device specific initialization before the first use.

virtual void	UpdateInputSlotValues () override
	Override this, if you need to query the state of the hardware to update the input slots.

virtual void	RegisterInputSlots () override
	Override this to register all the input slots that this device exposes.

Additional Inherited Members
Static Public Member Functions inherited from xiiNoBase
static const xiiRTTI *	GetStaticRTTI ()

Static Protected Member Functions inherited from xiiInputDevice
static void	RegisterInputSlot (xiiStringView sName, xiiStringView sDefaultDisplayName, xiiBitflags< xiiInputSlotFlags > SlotFlags)
	Calls RegisterInputSlot() on the xiiInputManager and passes the parameters through.

Detailed Description

A Virtual Thumb-stick is an input device that transforms certain types of input (mouse / touch) into input similar to a thumb-stick on a controller.

A virtual thumb-stick can be used to provide an 'input device' on a touch screen, that acts like a controller thumb-stick and thus allows easier control over a game. The virtual thumb-stick takes input inside a certain screen area. It tracks the users finger movements inside this area and translates those into input from a controller thumb-stick, which it then feeds back into the input system. That makes it then possible to be mapped to input actions again. This way a game controller type of input is emulated.

Member Function Documentation

◆ InitializeDevice()

virtual void xiiVirtualThumbStick::InitializeDevice ( )

inlineoverrideprivatevirtual

Override this if you need to do device specific initialization before the first use.

Implements xiiInputDevice.

◆ RegisterInputSlots()

void xiiVirtualThumbStick::RegisterInputSlots ( )

overrideprivatevirtual

Override this to register all the input slots that this device exposes.

This is called once during initialization. It needs to call RegisterInputSlot() once for every input slot that this device exposes to the system.

Implements xiiInputDevice.

◆ SetInputArea()

void xiiVirtualThumbStick::SetInputArea	(	const xiiVec2 &	vLowerLeft,
		const xiiVec2 &	vUpperRight,
		float	fThumbstickRadius,
		float	fPriority,
		CenterMode::Enum	center = CenterMode::ActivationPoint )

Defines the area on screen where the thumb-stick is located and accepts input.

Parameters

vLowerLeft	The lower left corner of the input area. Coordinates are in [0; 1] range (normalized screen coordinates).
vUpperRight	The upper right corner of the input area. Coordinates are in [0; 1] range (normalized screen coordinates).
fThumbstickRadius	The distance to move the touch point to create a maximum input value (1.0). With a larger radius, users have to move the finger farther for full input strength. Note that the radius is also in [0; 1] range (normalized screen coordinates).
fPriority	The priority of the input area. Defines which thumb-stick or other input action gets priority, if they overlap.
center

See also: CenterMode.

◆ SetInputCoordinateAspectRatio()

void xiiVirtualThumbStick::SetInputCoordinateAspectRatio ( float fWidthDivHeight )

Sets the aspect ratio of the screen on which the input happens.

Mouse and touch input coordinates are in normalized [0; 1] coordinate space. To calculate correct input values, the aspect ratio of the screen is needed (width divided by height). Call this when the screen resolution is known. Without the correct aspect ratio, moving the finger left/right a given distance won't have the same influence as moving it up/down the same distance.

◆ SetThumbstickOutput()

void xiiVirtualThumbStick::SetThumbstickOutput	(	Output::Enum	output,
		xiiStringView	sOutputLeft = {},
		xiiStringView	sOutputRight = {},
		xiiStringView	sOutputUp = {},
		xiiStringView	sOutputDown = {} )

Specifies which output the thumb-stick generates.

If Output is 'Custom' the remaining parameters define which input slots the thumb-stick triggers for which direction. Otherwise the remaining parameters are ignored.

◆ SetTriggerInputSlot()

void xiiVirtualThumbStick::SetTriggerInputSlot	(	Input::Enum	input,
		const xiiInputActionConfig *	pCustomConfig = nullptr )

Specifies from which input slots the thumb-stick is activated.

If Input is 'Custom' the remaining parameters define the filter axes and up to three input slots that trigger the thumb-stick. Otherwise the remaining parameters are ignored.

◆ UpdateInputSlotValues()

void xiiVirtualThumbStick::UpdateInputSlotValues ( )

overrideprivatevirtual

Override this, if you need to query the state of the hardware to update the input slots.

Note: This function might be called multiple times before ResetInputSlotValues() is called. This will be the case when xiiInputManager::PollHardware is used to make more frequent hardware updates than input is actually processed. Just make sure to always accumulate delta values (such as mouse move values) and don't expect ResetInputSlotValues() to be called in tandem with this function and it will be fine.

Implements xiiInputDevice.

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

/home/runner/work/XII/XII/Source/Engine/Core/Input/VirtualThumbStick.h
/home/runner/work/XII/XII/Source/Engine/Core/Input/Implementation/VirtualThumbStick.cpp

Classes

Public Member Functions

Protected Member Functions

Protected Attributes

Static Protected Attributes

Private Member Functions

Additional Inherited Members

Detailed Description

Member Function Documentation

◆ InitializeDevice()

◆ RegisterInputSlots()

◆ SetInputArea()

◆ SetInputCoordinateAspectRatio()

◆ SetThumbstickOutput()

◆ SetTriggerInputSlot()

◆ UpdateInputSlotValues()