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 ezVirtualThumbStick:

[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
	ezVirtualThumbStick ()
	Constructor.

	~ezVirtualThumbStick ()
	Destructor.

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

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

ezBitflags< 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. More...

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

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

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

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

void	SetAreaFocusMode (ezInputActionConfig::OnEnterArea onEnter, ezInputActionConfig::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.

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

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

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

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

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

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

float	GetInputSlotState (ezStringView 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. More...

Public Member Functions inherited from ezReflectedClass
virtual const ezRTTI *	GetDynamicRTTI () const

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

template<typename T >
EZ_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 ezInputDevice
virtual void	ResetInputSlotValues ()
	Override this, if you need to reset certain input slot values to zero, after the ezInputManager is finished with the current frame update.

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

Protected Attributes
ezVec2	m_vLowerLeft = ezVec2::MakeZero()

ezVec2	m_vUpperRight = ezVec2::MakeZero()

float	m_fRadius = 0.0f

ezInputActionConfig	m_ActionConfig

ezStringView	m_sOutputLeft

ezStringView	m_sOutputRight

ezStringView	m_sOutputUp

ezStringView	m_sOutputDown

ezBitflags< Flags >	m_Flags

bool	m_bEnabled = false

bool	m_bConfigChanged = false

bool	m_bIsActive = false

ezString	m_sName

ezVec2	m_vCenter = ezVec2::MakeZero()

ezVec2	m_vTouchPos = ezVec2::MakeZero()

ezVec2	m_vInputDirection = ezVec2::MakeZero()

float	m_fInputStrength = 0.0f

float	m_fAspectRatio = 1.0f

CenterMode::Enum	m_CenterMode

Protected Attributes inherited from ezInputDevice
ezMap< ezString, float >	m_InputSlotValues
	Stores all the values for all input slots that this device handles. More...

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

Protected Attributes inherited from ezEnumerable< ezInputDevice, ezReflectedClass >
ezEnumerable *	m_pNextInstance

Static Protected Attributes
static ezInt32	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. More...

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

Additional Inherited Members
Static Public Member Functions inherited from ezNoBase
static const ezRTTI *	GetStaticRTTI ()

Static Protected Member Functions inherited from ezInputDevice
static void	RegisterInputSlot (ezStringView sName, ezStringView sDefaultDisplayName, ezBitflags< ezInputSlotFlags > SlotFlags)
	Calls RegisterInputSlot() on the ezInputManager 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

◆ RegisterInputSlots()

void ezVirtualThumbStick::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 ezInputDevice.

◆ SetInputArea()

void ezVirtualThumbStick::SetInputArea	(	const ezVec2 &	vLowerLeft,
		const ezVec2 &	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 ezVirtualThumbStick::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 ezVirtualThumbStick::SetThumbstickOutput	(	Output::Enum	output,
		ezStringView	sOutputLeft = `{}`,
		ezStringView	sOutputRight = `{}`,
		ezStringView	sOutputUp = `{}`,
		ezStringView	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 ezVirtualThumbStick::SetTriggerInputSlot	(	Input::Enum	input,
		const ezInputActionConfig *	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 ezVirtualThumbStick::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 ezInputManager::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 ezInputDevice.

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

/home/runner/work/ezEngine/ezEngine/Code/Engine/Core/Input/VirtualThumbStick.h
/home/runner/work/ezEngine/ezEngine/Code/Engine/Core/Input/Implementation/VirtualThumbStick.cpp

Classes

Public Member Functions

Protected Member Functions

Protected Attributes

Static Protected Attributes

Private Member Functions

Additional Inherited Members