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::InputDeviceRequests Class Referenceabstract

EBus interface used to query input devices for their associated input channels and state. More...

#include <InputDeviceRequestBus.h>

Inherits AZ::EBusTraits.

Public Types

using BusIdType = InputDeviceId
 EBus Trait: requests can be addressed to a specific InputDeviceId.
 
using BusIdOrderCompare = AZStd::less< BusIdType >
 EBus Trait: requests are handled by connected devices in the order of local player index.
 
using MutexType = AZStd::recursive_mutex
 
using InputDeviceIdSet = AZStd::unordered_set< InputDeviceId >
 
using InputChannelIdSet = AZStd::unordered_set< InputChannelId >
 
using InputDeviceByIdMap = AZStd::unordered_map< InputDeviceId, const InputDevice * >
 
using InputChannelByIdMap = AZStd::unordered_map< InputChannelId, const InputChannel * >
 

Public Member Functions

virtual const InputDeviceGetInputDevice () const =0
 
virtual void GetInputDeviceIds (InputDeviceIdSet &o_deviceIds) const =0
 
virtual void GetInputDevicesById (InputDeviceByIdMap &o_devicesById) const =0
 
virtual void GetInputDevicesByIdWithAssignedLocalUserId (InputDeviceByIdMap &o_devicesById, LocalUserId localUserId) const =0
 
virtual void GetInputChannelIds (InputChannelIdSet &o_channelIds) const =0
 
virtual void GetInputChannelsById (InputChannelByIdMap &o_channelsById) const =0
 
virtual void GetPhysicalKeyOrButtonText (const InputChannelId &, AZStd::string &) const
 
virtual void TickInputDevice ()=0
 
virtual ~InputDeviceRequests ()=default
 Default destructor.
 

Static Public Member Functions

static const InputDeviceFindInputDevice (const InputDeviceId &deviceId)
 
template<class CustomDataType >
static void GetInputChannelIdsWithCustomDataOfType (InputChannelIdSet &o_channelIds, const InputDeviceId *deviceId=nullptr)
 

Static Public Attributes

static const AZ::EBusAddressPolicy AddressPolicy = AZ::EBusAddressPolicy::ByIdAndOrdered
 
static const AZ::EBusHandlerPolicy HandlerPolicy = AZ::EBusHandlerPolicy::Single
 EBus Trait: requests should be handled by only one input device connected to each id.
 
static const bool LocklessDispatch = true
 

Detailed Description

EBus interface used to query input devices for their associated input channels and state.

Member Typedef Documentation

◆ InputDeviceIdSet

Alias for verbose container class

◆ MutexType

using AzFramework::InputDeviceRequests::MutexType = AZStd::recursive_mutex

EBus Trait: InputDeviceRequestBus can be accessed from multiple threads, but is safe to use with LocklessDispatch because connect/disconnect is handled only on engine startup/shutdown (InputSystemComponent).

Member Function Documentation

◆ FindInputDevice()

static const InputDevice * AzFramework::InputDeviceRequests::FindInputDevice ( const InputDeviceId deviceId)
static

Finds a specific input device (convenience function)

Parameters
[in]deviceIdId of the input device to find
Returns
Pointer to the input device if it was found, nullptr if it was not

◆ GetInputChannelIds()

virtual void AzFramework::InputDeviceRequests::GetInputChannelIds ( InputChannelIdSet &  o_channelIds) const
pure virtual

Request the ids of all input channels associated with an input device.

Can be called using either:

  • EBus<>::Broadcast (all input devices will add all their channel ids to o_channelIds)
  • EBus<>::Event(id) (the given device will add all of its channel ids to o_channelIds)
Parameters
[out]o_channelIdsThe set of input channel ids to return

◆ GetInputChannelIdsWithCustomDataOfType()

template<class CustomDataType >
void AzFramework::InputDeviceRequests::GetInputChannelIdsWithCustomDataOfType ( InputChannelIdSet &  o_channelIds,
const InputDeviceId deviceId = nullptr 
)
inlinestatic

Request the ids of all input channels (optionally those associated with an input device) that return custom data of a specific type (InputChannel::GetCustomData<CustomDataType>).

Parameters
[out]o_channelIdsThe set of input channel ids to return
[in]deviceId(optional) Id of a specific input device to query for input channels
Template Parameters
CustomDataTypeOnly consider input channels that return custom data of this type

◆ GetInputChannelsById()

virtual void AzFramework::InputDeviceRequests::GetInputChannelsById ( InputChannelByIdMap &  o_channelsById) const
pure virtual

Request all input channels associated with an input device.

Can be called using either:

  • EBus<>::Broadcast (all input devices will add all their channels to o_channelsById)
  • EBus<>::Event(id) (the given device will add all of its channels to o_channelsById)
Parameters
[out]o_channelsByIdThe map of input channels (keyed by their id) to return

◆ GetInputDevice()

virtual const InputDevice * AzFramework::InputDeviceRequests::GetInputDevice ( ) const
pure virtual

Gets the input device that is uniquely identified by the InputDeviceId used to address the call to this EBus function. Calls to this EBus method should never be broadcast to all connected input devices, otherwise the device returned will effectively be random.

Returns
Pointer to the input device if it exists, nullptr otherwise

◆ GetInputDeviceIds()

virtual void AzFramework::InputDeviceRequests::GetInputDeviceIds ( InputDeviceIdSet o_deviceIds) const
pure virtual

Request the ids of all currently enabled input devices. This does not imply they are all connected, or even available on the current platform, just that they are enabled for the application (meaning they will generate input when available / connected to the system).

Can be called using either:

  • EBus<>::Broadcast (all input devices will add their id to o_deviceIds)
  • EBus<>::Event(id) (the given device will add its id to o_deviceIds - not very useful!)
Parameters
[out]o_deviceIdsThe set of input device ids to return

◆ GetInputDevicesById()

virtual void AzFramework::InputDeviceRequests::GetInputDevicesById ( InputDeviceByIdMap &  o_devicesById) const
pure virtual

Request a map of all currently enabled input devices by id. This does not imply they are connected, or even available on the current platform, just that they are enabled for the application (meaning they will generate input when available / connected to the system).

Can be called using either:

  • EBus<>::Broadcast (all input devices will add themselves to o_devicesById)
  • EBus<>::Event(id) (the given input device will add itself to o_devicesById)
Parameters
[out]o_devicesByIdThe map of input devices (keyed by their id) to return

◆ GetInputDevicesByIdWithAssignedLocalUserId()

virtual void AzFramework::InputDeviceRequests::GetInputDevicesByIdWithAssignedLocalUserId ( InputDeviceByIdMap &  o_devicesById,
LocalUserId  localUserId 
) const
pure virtual

Request a map of all currently enabled input devices (keyed by their id) that have been assigned to the specified local user id.

Can be called using either:

  • EBus<>::Broadcast (all input devices assigned to localUserId added to o_devicesById)
  • EBus<>::Event(id) (add given input device to o_devicesById if assigned to localUserId)
Parameters
[out]o_devicesByIdThe map of input devices (keyed by their id) to return
[in]localUserIdThe local user id to check whether input devices are assigned to

◆ GetPhysicalKeyOrButtonText()

virtual void AzFramework::InputDeviceRequests::GetPhysicalKeyOrButtonText ( const InputChannelId ,
AZStd::string &   
) const
inlinevirtual

Request the text displayed on the physical key / button associated with an input channel. In the case of keyboard keys, this should take into account the current keyboard layout.

Can be called using either:

  • EBus<>::Broadcast (all input devices will search their channels for inputChannelId)
  • EBus<>::Event(id) (the given device will search its channel for inputChannelId)
Parameters
[in]inputChannelIdThe input channel id whose key or button text to search for
[out]o_keyOrButtonTextThe text displayed on the physical key or button if found

◆ TickInputDevice()

virtual void AzFramework::InputDeviceRequests::TickInputDevice ( )
pure virtual

Tick/update input devices.

Can be called using either:

  • EBus<>::Broadcast (all input devices are ticked/updated)
  • EBus<>::Event(id) (the given device is ticked/updated)

Member Data Documentation

◆ AddressPolicy

const AZ::EBusAddressPolicy AzFramework::InputDeviceRequests::AddressPolicy = AZ::EBusAddressPolicy::ByIdAndOrdered
static

EBus Trait: requests can be addressed to a specific InputDeviceId so that they are only handled by one input device that has connected to the bus using that unique id, or they can be broadcast to all input devices that have connected to the bus, regardless of id. Connected input devices are ordered by their local player index from lowest to highest.


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