Open 3D Engine AzFramework API Reference 23.10.0
O3DE is an open-source, fully-featured, high-fidelity, modular 3D engine for building games and simulations, available to every industry.
AzFramework::InputDevice Class Referenceabstract

#include <InputDevice.h>

Inherits InputDeviceRequestBus::Handler, and ApplicationLifecycleEvents::Bus::Handler.

Inherited by AzFramework::InputContext, AzFramework::InputDeviceGamepad, AzFramework::InputDeviceKeyboard, AzFramework::InputDeviceMotion, AzFramework::InputDeviceMouse, AzFramework::InputDeviceTouch, and AzFramework::InputDeviceVirtualKeyboard.

Public Member Functions

 AZ_CLASS_ALLOCATOR (InputDevice, AZ::SystemAllocator)
 
 AZ_RTTI (InputDevice, "{29F9FB6B-15CB-4DB4-9F36-DE7396B82F3D}")
 
 InputDevice (const InputDeviceId &inputDeviceId)
 
 AZ_DISABLE_COPY_MOVE (InputDevice)
 
 ~InputDevice () override
 Destructor.
 
const InputDeviceGetInputDevice () const final
 AzFramework::InputDeviceRequests::GetInputDevice
 
const InputDeviceIdGetInputDeviceId () const
 
virtual LocalUserId GetAssignedLocalUserId () const
 
virtual void PromptLocalUserSignIn () const
 
virtual const InputChannelByIdMap & GetInputChannelsById () const =0
 
virtual bool IsSupported () const =0
 
virtual bool IsConnected () const =0
 

Static Public Member Functions

static void Reflect (AZ::ReflectContext *context)
 

Protected Member Functions

void BroadcastInputChannelEvent (const InputChannel &inputChannel) const
 
void BroadcastInputTextEvent (const AZStd::string &textUTF8) const
 
void BroadcastInputDeviceConnectedEvent () const
 Broadcast an event when the input device connects to the system.
 
void BroadcastInputDeviceDisconnectedEvent () const
 Broadcast an event when the input device disconnects from the system.
 
void ResetInputChannelStates ()
 Reset the state of all this input device's associated input channels.
 

Detailed Description

Base class for all input devices. Input devices are responsible for processing raw input and using it to update their associated input channels. Input devices can also be queried at any time to determine their current connected state, or retrieve their associated input channels.

While almost every concrete input device that inherits from this class will likely only send input events when running on a specific platform, we should always be able to access all the potentially available input devices and channels in order to display and set input bindings.

Derived classes are responsible for:

  • Creating and maintaining a collection of associated input channels
  • Overriding GetInputChannelsById to return all associated input channels
  • Overriding TickInputDevice to process raw input and update input channel states
  • Overriding IsSupported to return whether the input device is supported by the platform
  • Overriding IsConnected to return whether the input device is currently connected
  • Broadcasting events when the input device gets connected or diconnected

Ideally, an input device will use TickInputDevice (that gets called once every frame by the system) to process raw input, update all its input channels, and broadcast all input events. However, this may not always be possible, as the state of an input channel cannot always be queried at will, but will rather be sent by the system at a pre-determined time (eg. touch). In these cases, input devices must queue all raw input until TickInputDevice is called, when they can use it to update their input channels and broadcast events at the appropriate time.

Constructor & Destructor Documentation

◆ InputDevice()

AzFramework::InputDevice::InputDevice ( const InputDeviceId inputDeviceId)
explicit

Constructor

Parameters
[in]inputDeviceIdId of the input device

Member Function Documentation

◆ BroadcastInputChannelEvent()

void AzFramework::InputDevice::BroadcastInputChannelEvent ( const InputChannel inputChannel) const
protected

Broadcast an event when an associated input channel's state or value is updated

Parameters
[in]inputChannelThe input channel whose state or value was updated

◆ BroadcastInputTextEvent()

void AzFramework::InputDevice::BroadcastInputTextEvent ( const AZStd::string &  textUTF8) const
protected

Broadcast an event when unicode text input is generated by an input device

Parameters
[in]textUTF8The text emitted by the input device (encoded using UTF-8)

◆ GetAssignedLocalUserId()

virtual LocalUserId AzFramework::InputDevice::GetAssignedLocalUserId ( ) const
virtual

Access to the input device's currently assigned local user id. By default this returns the device index, but can be overridden to return a platform specific user id in order to support platforms where input comes from a specific user rather than just an index. Values are guaranteed to be unique for the local system, but they are otherwise system dependent and a user id may not necessarily persist for the same user between app runs.

Returns
Id of the local user currently assigned to the input device

Reimplemented in AzFramework::InputDeviceGamepad, AzFramework::InputDeviceKeyboard, and AzFramework::InputDeviceTouch.

◆ GetInputChannelsById()

virtual const InputChannelByIdMap & AzFramework::InputDevice::GetInputChannelsById ( ) const
pure virtual

Access to all input channels associated with this input device

Returns
Map of all input channels (keyed by their id) associated with this input device

Implemented in AzFramework::InputContext, AzFramework::InputDeviceGamepad, AzFramework::InputDeviceKeyboard, AzFramework::InputDeviceMotion, AzFramework::InputDeviceMouse, AzFramework::InputDeviceTouch, and AzFramework::InputDeviceVirtualKeyboard.

◆ GetInputDeviceId()

const InputDeviceId & AzFramework::InputDevice::GetInputDeviceId ( ) const

Access to the input device's id

Returns
Id of the input device

◆ IsConnected()

virtual bool AzFramework::InputDevice::IsConnected ( ) const
pure virtual

Query whether the device is currently connected to the system. A device can be supported but not currently connected, while a currently connected device will always be supported.

Returns
True if the input device is currently connected, false otherwise

Implemented in AzFramework::InputContext, AzFramework::InputDeviceGamepad, AzFramework::InputDeviceKeyboard, AzFramework::InputDeviceMotion, AzFramework::InputDeviceMouse, AzFramework::InputDeviceTouch, and AzFramework::InputDeviceVirtualKeyboard.

◆ IsSupported()

virtual bool AzFramework::InputDevice::IsSupported ( ) const
pure virtual

Query whether the device is supported by the current platform. A device can be supported but not currently connected, while a currently connected device will always be supported.

Returns
True if the input device is supported on the current platform, false otherwise

Implemented in AzFramework::InputContext, AzFramework::InputDeviceGamepad, AzFramework::InputDeviceKeyboard, AzFramework::InputDeviceMotion, AzFramework::InputDeviceMouse, AzFramework::InputDeviceTouch, and AzFramework::InputDeviceVirtualKeyboard.

◆ PromptLocalUserSignIn()

virtual void AzFramework::InputDevice::PromptLocalUserSignIn ( ) const
inlinevirtual

Prompt a platform-specific local user sign-in request from this device. Should be called at the appropriate times (eg. start screen, local multiplayer lobby / join screen) where input is detected from a specific input device that does not yet have a user id assigned.

Please note that on most platforms this will do nothing, and even on platforms where it does it cannot be assumed that the sign-in flow will actually be completed by the user.

Reimplemented in AzFramework::InputDeviceGamepad.


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