Note
Access to this page requires authorization. You can try signing in or changing directories.
Access to this page requires authorization. You can try changing directories.
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.
Note
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 events, such as connection and disconnection. |
| GameInputInitialize | Retrieves an instance of the IGameInput interface for a specific API version. |
| GameInputReadingCallback | Defines a callback for new reading arrival 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. |
| GameInputColor | Describes an RGB color for device lighting. |
| GameInputControllerSwitchInfo | Specifies a switch on 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. |
| GameInputTouchContact | Describes a single contact on a touch surface. |
| GameInputTouchSurfaceInfo | Details the characteristics of a touch surface. |
| 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. |
| GameInputDeviceEvent | Enumerates the device events reported to a device callback. |
| GameInputElementKind | Enumerates the element kind of a given input. |
| 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. |
| 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. |
| GameInputLightingGroups | Enumerates groups of lamps on a device that supports lighting. |
| 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. |
| GameInputTouchSurfaceType | Enumerates kinds of touch surfaces. |
Constants
| Constant | Value | Description |
|---|---|---|
GAMEINPUT_LIGHTING_GROUP_ORDER_INDEX_ALL |
0xFFFFFFFF |
Selects every lamp in the lighting group passed to IGameInputDevice::SetLightingColor. |
Service interfaces
The GameInput service also exposes COM interfaces for trusted system components. These aren't part of the GameInput API. For more information, see GameInput service interfaces.
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. |
| GameInputKeyboardLayoutCallback | v3 | Title-defined callback for keyboard layout change events. Replaced by the GameInputDeviceEventKeyboardLayoutUpdated device event. |
| GameInputSystemButtonCallback | v3 | Title-defined callback for Guide or Share button events. Replaced by IGameInputReading::GetSystemButtonState. |
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. |
| GameInputControllerInfo | v3 | Described the axes, buttons, and switches of a controller. Replaced by IGameInputDevice getters such as GetControllerAxisLabels. |
| GameInputDeviceInfo | v3 | Contained comprehensive information about an input device. Replaced by individual IGameInputDevice getters. |
| 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. |
| GameInputDeviceStatus | v3 | Enumerated the states that an input device can be in. Replaced by GameInputDeviceEvent and IGameInputDevice::IsConnected. |
| GameInputEnumerationKind | v3 | Enumerated types of behavior for enumerating input devices. Device enumeration is always asynchronous in v4. |
| GameInputFocusPolicy | v3 | Enumerated focus policies. Replaced by IGameInput::EnableBackgroundInput. |
| 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 |
|---|---|
| v4 | Added GameInputColor, GameInputTouchContact, GameInputTouchSurfaceInfo structs. Added GameInputDeviceEvent, GameInputLightingGroups, GameInputTouchSurfaceType enums and the GAMEINPUT_LIGHTING_GROUP_ORDER_INDEX_ALL constant. Replaced GameInputDeviceInfo and IGameInputDevice::GetDeviceInfo with individual IGameInputDevice getters. Added device lighting, touch, and XInput index support. GameInputDeviceCallback now receives a GameInputDeviceEvent. Removed GameInputControllerInfo, GameInputDeviceInfo structs. Removed GameInputDeviceStatus, GameInputEnumerationKind, GameInputFocusPolicy enums. Removed GameInputKeyboardLayoutCallback, GameInputSystemButtonCallback callbacks. Re-introduced IGameInputDevice::GetRawDeviceFeature and IGameInputDevice::SetRawDeviceFeature (absent since v1). |
| 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. |