GameInput
GameInput APIs are used to capture human input from a wide range of devices, such as game controllers, flight sticks, racing wheels, and touch input.This page documents the current (latest) GameInput API. Version history for each member is noted in the individual reference pages. Members that existed only in older API versions are listed in the Removed Members section below. Note newer runtimes for the API support all available versions of the API, so removed members can still be used with the headers for olders versions.
Interfaces
| Interface | Description |
|---|---|
| IGameInputDevice | Defines an input device. |
| IGameInputDispatcher | Provides manual control over scheduling the background tasks managed by the GameInput API. |
| IGameInputForceFeedbackEffect | Describes a force feedback effect on a compatible input device. |
| IGameInputMapper | Provides information on how GameInput maps a device. |
| IGameInputRawDeviceReport | Represents a raw byte buffer passed to or from an input device. |
| IGameInputReading | Contains the data for a single input update. |
| IGameInput | A per-process singleton that provides access to the device input stream. |
Functions
| Function | Description |
|---|---|
| GameInputCreate | Retrieves an instance of the IGameInput interface. |
| GameInputDeviceCallback | Defines a callback for device connection and disconnection events. |
| GameInputKeyboardLayoutCallback | Defines a callback for keyboard layout change events. |
| GameInputReadingCallback | Defines a callback for new reading arrival events. |
| GameInputSystemButtonCallback | Defines a callback for Guide or Share button press and release events. |
Structures
| Structure | Description |
|---|---|
| GameInputArcadeStickInfo | Details the characteristics of an arcade stick. |
| GameInputArcadeStickState | Provides the current status of an arcade stick. |
| GameInputAxisMapping | Describes how an axis maps to the controller. |
| GameInputButtonMapping | Describes how a button maps to the controller. |
| GameInputControllerInfo | Details the characteristics of a controller. |
| GameInputControllerSwitchInfo | Specifies a switch on an input device. |
| GameInputDeviceInfo | Contains comprehensive information about an input device. |
| GameInputFlightStickInfo | Details the characteristics of a flight stick. |
| GameInputFlightStickState | Provides the current status of a flight stick. |
| GameInputForceFeedbackConditionParams | Defines certain physical aspects of a force-feedback effect. |
| GameInputForceFeedbackConstantParams | Defines a constant physical aspect of a force-feedback effect. |
| GameInputForceFeedbackEnvelope | Defines an envelope that modifies a force-feedback effect. |
| GameInputForceFeedbackMagnitude | Defines the magnitude of the force exerted by a force-feedback effect. |
| GameInputForceFeedbackMotorInfo | Provides information about the force-feedback motor. |
| GameInputForceFeedbackParams | Defines the API-supported attributes of a force-feedback effect. |
| GameInputForceFeedbackPeriodicParams | Defines the parameters for a periodic force-feedback effect. |
| GameInputForceFeedbackRampParams | Defines the parameters for a ramp force-feedback effect. |
| GameInputGamepadInfo | Details the characteristics of a gamepad. |
| GameInputGamepadState | Provides the current status of a gamepad input device. |
| GameInputHapticInfo | Details the characteristics of a haptic feedback motor. |
| GameInputKeyState | Provides the current state of a key on a keyboard. |
| GameInputKeyboardInfo | Details the characteristics of a keyboard. |
| GameInputMouseInfo | Details the characteristics of a mouse. |
| GameInputMouseState | Provides the current status of a mouse. |
| GameInputRacingWheelInfo | Details the characteristics of a racing wheel. |
| GameInputRacingWheelState | Provides the current status of a racing wheel. |
| GameInputRawDeviceReportInfo | Describes a raw device report. |
| GameInputRumbleParams | Describes a rumble effect produced by a controller. |
| GameInputSensorsInfo | Details the characteristics of the available sensors. |
| GameInputSensorsState | Provides the current status of a device’s sensors. |
| GameInputUsage | Describes a specific HID usage. |
| GameInputVersion | Describes a four-part version number. |
Enumerations
| Enumeration | Description |
|---|---|
| GameInputArcadeStickButtons | Enumerates inputs from an arcade stick. |
| GameInputDeviceFamily | Enumerates families of input devices. |
| GameInputDeviceStatus | Enumerates the states that an input device can be in. |
| GameInputElementKind | Enumerates the element kind of a given input. |
| GameInputEnumerationKind | Enumerates types of behavior for enumerating input devices. |
| GameInputFeedbackAxes | Enumerates direction types of force feedback motors available on an input device. |
| GameInputFeedbackEffectState | Enumerates states of a force feedback effect. |
| GameInputFlightStickAxes | Enumerates flight stick axes. |
| GameInputFlightStickButtons | Enumerates flight stick buttons. |
| GameInputFocusPolicy | Enumerates focus policies for an input device. |
| GameInputForceFeedbackEffectKind | Enumerates types of magnitude over time effects that can be applied to a force feedback effect. |
| GameInputGamepadAxes | Enumerates gamepad axes. |
| GameInputGamepadButtons | Enumerates gamepad buttons, including the directional pad (D-pad). |
| GameInputKeyboardKind | Enumerates keyboard types by key layout. |
| GameInputKind | Enumerates valid GameInput device types. |
| GameInputLabel | Enumerates supported button labels. |
| GameInputMouseButtons | Enumerates mouse buttons. |
| GameInputMousePositions | Enumerates mouse positioning modes. |
| GameInputRacingWheelAxes | Enumerates axes on a racing wheel. |
| GameInputRacingWheelButtons | Enumerates buttons on a racing wheel. |
| GameInputRawDeviceReportKind | Enumerates kinds of raw device reports. |
| GameInputRumbleMotors | Enumerates the API supported rumble motors for an input device. |
| GameInputSensorAccuracy | Enumerates levels of accuracy for sensors. |
| GameInputSensorsKind | Enumerates valid GameInput sensor types. |
| GameInputSwitchKind | Enumerates types of switches supported by an input device. |
| GameInputSwitchPosition | Enumerates positions of a switch on an input device. |
| GameInputSystemButtons | Enumerates buttons used for controlling the system. |
Removed Members
The following members were present in older API versions but have been removed from the current API. For full documentation on each removed member, see Deprecated GameInput API members.Removed Interfaces
No interfaces have been permanently removed.IGameInputRawDeviceReport was absent in v1 and v2 but has been re-introduced in the current API.
Removed Functions
| Function | Last version | Description |
|---|---|---|
| GameInputGuideButtonCallback | v0 | Title-defined callback for Guide button events. Replaced by GameInputSystemButtonCallback. |
Removed Structures
| Structure | Last version | Description |
|---|---|---|
| GameInputBatteryState | v0 | Described the battery state of an input device. |
| GameInputControllerAxisInfo | v2 | Described an axis on an input device. Superseded by fields in GameInputControllerInfo. |
| GameInputControllerButtonInfo | v2 | Described a button on an input device. Superseded by fields in GameInputControllerInfo. |
| GameInputHapticFeedbackMotorInfo | v0 | Described a haptic feedback motor. Superseded by GameInputHapticInfo. |
| GameInputHapticFeedbackParams | v0 | Described a haptic feedback effect. |
| GameInputHapticWaveformInfo | v0 | Described characteristics of a haptic feedback effect. |
| GameInputMotionInfo | v0 | Described measurable properties for a motion-enabled input device. |
| GameInputMotionState | v0 | Described the state of motion input. |
| GameInputRawDeviceItemCollectionInfo | v0 | Described a collection of raw device items. |
| GameInputRawDeviceReportItemInfo | v0 | Described a raw device report item. |
| GameInputString | v0 | Described a string containing information about an input device. |
| GameInputTouchSensorInfo | v0 | Described a touch sensor for an input device. |
| GameInputTouchState | v0 | Described the state of a touch input device. |
| GameInputUiNavigationInfo | v2 | Specified the labels of navigation buttons in the UI. |
| GameInputUiNavigationState | v2 | Provided the current status of UI navigation input. |
Removed Enumerations
| Enumeration | Last version | Description |
|---|---|---|
| GameInputBatteryStatus | v0 | Enumerated battery states for an input device. |
| GameInputDeviceCapabilities | v0 | Enumerated certain capabilities of an input device. |
| GameInputLocation | v0 | Enumerated the parts of an input device. |
| GameInputMotionAccuracy | v0 | Enumerated levels of accuracy for motion sensors. |
| GameInputRawDeviceItemCollectionKind | v0 | Enumerated types of collections of raw device items. |
| GameInputRawDevicePhysicalUnitKind | v0 | Enumerated physical units associated with device input. |
| GameInputRawDeviceReportItemFlags | v0 | Enumerated types of raw device-report items. |
| GameInputTouchShape | v0 | Enumerated shapes of a touch sensor. |
| GameInputUiNavigationButtons | v2 | Enumerated UI navigation buttons. |
Version History
| Version | Changes |
|---|---|
| v3 | Added IGameInputMapper interface. Re-introduced IGameInputRawDeviceReport interface (was absent in v1/v2). Added GameInputAxisMapping, GameInputButtonMapping, GameInputControllerInfo, GameInputHapticInfo structs. Re-introduced GameInputRawDeviceReportInfo struct and GameInputRawDeviceReportKind enum (absent in v1/v2). Re-introduced GameInputVersion struct (absent in v1/v2). Added GameInputElementKind, GameInputFlightStickAxes, GameInputGamepadAxes, GameInputRacingWheelAxes enums. Removed GameInputControllerAxisInfo, GameInputControllerButtonInfo, GameInputUiNavigationInfo, GameInputUiNavigationState structs. Removed GameInputUiNavigationButtons enum. |
| v2 | Added GameInputSensorsInfo, GameInputSensorsState structs. Added GameInputSensorsKind, GameInputSensorAccuracy enums. Added IGameInputDevice::DirectInputEscape, IGameInputDevice::GetHapticInfo. Added IGameInputReading::GetSensorsState. Re-introduced GameInputVersion struct (was absent in v1). |
| v1 | Removed IGameInputRawDeviceReport interface, GameInputRawDeviceReportInfo struct, GameInputRawDeviceReportKind enum. Removed GameInputVersion struct. Added GameInputMousePositions enum. Removed v0-only unimplemented haptics, motion, and touch types (GameInputBatteryState, GameInputHapticFeedbackMotorInfo, GameInputHapticFeedbackParams, GameInputHapticWaveformInfo, GameInputMotionInfo, GameInputMotionState, GameInputTouchSensorInfo, GameInputTouchState, GameInputString, GameInputRawDeviceItemCollectionInfo, GameInputRawDeviceReportItemInfo). |
| v0 | Introduced. |