Partager via


IGameInputReading

Encapsulates the data for a single input update. The methods for this interface allow you to interpret game input through the lens of several devices, as well as gain information about the devices sending the input. This interface will help you translate inputs into actionable information about a game controllers state at some moment in time.

Syntax

class IGameInputReading : public IUnknown  

Methods

Method Description
GetArcadeStickState IGameInputReading GetArcadeStickState API reference
GetControllerAxisCount Retrieves the number of axes on a game controller.
GetControllerAxisState IGameInputReading GetControllerAxisState API reference
GetControllerButtonCount Retrieves the number of buttons on a game controller.
GetControllerButtonState IGameInputReading GetControllerButtonState API reference
GetControllerSwitchCount Retrieves the number of switches on a game controller.
GetControllerSwitchState IGameInputReading GetControllerSwitchState API reference
GetDevice IGameInputReading::GetDevice API
GetFlightStickState IGameInputReading GetFlightStickState API reference
GetGamepadState IGameInputReading::GetGamepadState API
GetInputKind IGameInputReading::GetInputKind API
GetKeyCount Retrieves the number of keys active on a game controller.
GetKeyState Retrieves the state of active keys on a game controller input.
GetMotionState IGameInputReading GetMotionState API reference
GetMouseState IGameInputReading GetMouseState API reference
GetRacingWheelState IGameInputReading GetRacingWheelState API reference
GetRawReport Retrieves the raw data from the device input.
GetSequenceNumber IGameInputReading GetSequenceNumber API reference
GetTimestamp IGameInputReading::GetTimestamp API
GetTouchCount Retrieves the number of touch points on a game controller.
GetTouchState Retrieves the state from all touch digitizers.
GetUiNavigationState IGameInputReading GetUiNavigationState API reference

Remarks

Every input state change received from a device is captured in an IGameInputReading instance. Essentially, this is a snapshot of the device's input state, at a specific moment in time. The IGameInputReading interface provides access to both the raw input report data from the device, as well as various transformations of that data.

After capturing the raw input data in a new report, the GameInput API examines the data and attempts to transform it into additional (more useful) representations. With very few exceptions, the data is transformed into one or more rudimentary representations - an array of button and axis values, an array of key states, etc. 12 If possible, the data is also transformed into one or more abstract fixed-format representations, such as gamepad state.

As a result, a single IGameInputReading instance often contains multiple "views" of the same input data. This caters to a broad range of applications of varying sophistication, by giving them access to as little or as much low-level detail about the input data as they need. For each kind of input data defined in the GameInputKind enumeration, a corresponding IGameInputReading method exists to retrieve that kind of data.

It is important to note that only the raw report data captured in two consecutive IGameInputReading instances (from the same device) is guaranteed to be different. This is because changes in the raw data may not always result in changes to the higher-level transformations of that data. This fact is understood by the polling and event-based APIs on the IGameInput interface and is accounted for as appropriate. For example, an application that provides an input kind filter of GameInputKindGamepad (and nothing else) will only receive readings whose raw data resulted in a change to the previously computed gamepad state.

Every IGameInputReading retrieved from the input stream is a singleton; retrieving the same reading multiple times simply increments the reference count on the underlying object. As a result, IGameInputReading instances can be compared for reference equality. IGameInputReading instances always remain valid (and state can be retrieved from them) until all references to the reading instance have been released - even if the underlying device has been disconnected from the system, or if the reading is so old it is no longer in the input stream buffer. Because all of the methods on this interface are simply retrieving cached data stored in the reading, they all return extremely quickly and are safe to call from time sensitive contexts.

Requirements

Header: GameInput.h

Supported platforms: Windows, Xbox One family consoles and Xbox Series consoles

See also

Input API Overview
GameInput