GameInput API versioning

Note

If you're developing for XBOX, the GDK headers and library provide the v0 API. To use API v1 or later on XBOX, compile and link with the headers and library from the Microsoft.GameInput NuGet package, which requires the October 2025 GDK (2510) or later. The API versions that are available at runtime depend on the GDK release and on whether you sideload the GameInput runtime with your game. For more information, see GameInput on XBOX consoles. PC apps require the latest GameInput redistributable, which is included in the NuGet package, to be installed on the target machine, or a sideloaded runtime.

GameInput is a living API that continues to evolve over time as new features are added and unneeded or outdated ones are removed. You can find the most recent version of GameInput in the official NuGet package. This package also includes the latest, up-to-date Version History. The package always contains the latest GameInput header, binaries, and redistributable to include with your title.

Upgrading to a newer version of GameInput is quick and painless. Furthermore, regardless of the API described in the latest GameInput header, binary and functional compatibility is maintained for applications compiled against earlier versions of GameInput. In this model, shipped games can enjoy improvements in GameInput and can be transitioned to the latest version of GameInput, if necessary, to take advantage of new features.

Upgrading runtime and API version

Different versions of GameInput have similar-looking names and methods but are distinctly versioned with different UUIDs. Starting with GameInput API v.1, each version is defined in a unique namespace (for example, GameInput::v1 or GameInput::v4). The same underlying objects in GameInput implement these interfaces. You can QueryInterface to switch between versions, which means you can mix API usage in your game if you want. For examples, see Using multiple GameInput API versions in one application.

If you're upgrading from GameInput v.0 where the API was defined in the global namespace, you might find that adding a using namespace GameInput::v1 statement helps reduce the number of GameInput call sites that you need to update for adoption of the v.1 and subsequent revisions of the API.

In addition to the runtime version checks, you can use conditional compilation by checking for the GAMEINPUT_API_VERSION processor define. This define corresponds to the GameInput API version currently in use as well as the GameInput major version. The v.0 API didn't feature this definition, so if you want to conditionally test for this version, you can add the following snippet after your GameInput header include.

#ifndef GAMEINPUT_API_VERSION
#define GAMEINPUT_API_VERSION 0
#endif

Upgrading runtime only

GameInput allows you to get the latest bug fixes without forcing you to update your API usage. To get these bug fixes on PC, install the GameInput redistributable bundled in the latest Microsoft.GameInput NuGet package. On XBOX, update the GDK or sideload the GameInput runtime; for more information, see GameInput on XBOX consoles. Because GameInput remains binary compatible with older versions of the API, you can continue using your existing header with the new runtime. Remember to redistribute the latest GameInput binaries with your titles to ensure functionality in your testing environment is consistent with production.

GameInput v.1 changes

If you're using a previous version of GameInput, note that many unimplemented functions and corresponding enums and constants are removed from the v.1 API onwards. Additionally, the API is placed in the GameInput::v1 namespace to facilitate versioning. Due to these changes, you might experience compilation errors when building that code by using this (and future) versions. Notable changes include:

IGameInputDevice::GetDeviceInfo previously returned the resulting IGameInputDeviceInfo struct as the function's return value. This struct is now returned as an out parameter on the function, and the function's return value is now an HRESULT.
IGameInput::UnregisterCallback previously took a timeout value as its second parameter, but this parameter is removed.
IGameInputReading::GetSequenceNumber is removed. Use IGameInputReading::GetTimestamp instead.

GameInput v.4 changes

GameInput v.4 is defined in the GameInput::v4 namespace, and GAMEINPUT_API_VERSION is defined as 4. If you're upgrading from v.3, notable changes include:

The GameInputDeviceInfo structure and IGameInputDevice::GetDeviceInfo are removed. Device properties are now returned by individual IGameInputDevice getter methods, such as GetVendorId, GetDisplayName, GetSupportedInput, and GetGamepadInfo. Controller element information that was in GameInputControllerInfo is returned by methods such as GetControllerAxisLabels.
IGameInputDevice::GetDeviceStatus and the GameInputDeviceStatus enumeration are removed. Use IGameInputDevice::IsConnected to check whether a device is connected.
IGameInput::RegisterDeviceCallback no longer takes statusFilter and enumerationKind parameters, and the GameInputEnumerationKind enumeration is removed. Device enumeration is always asynchronous. The GameInputDeviceCallback function now receives a GameInputDeviceEvent value instead of the current and previous device status.
IGameInput::RegisterKeyboardLayoutCallback is removed. Keyboard layout changes are reported as a GameInputDeviceEventKeyboardLayoutUpdated device event.
IGameInput::RegisterSystemButtonCallback is removed. System buttons, such as the Guide and Share buttons, are reported in readings of kind GameInputKindSystemButton, and are read with IGameInputReading::GetSystemButtonState.
IGameInput::SetFocusPolicy and the GameInputFocusPolicy enumeration are removed. Use IGameInput::EnableBackgroundInput to receive input while your application isn't in focus.
IGameInput::StopCallback is removed. IGameInput::UnregisterCallback can now be called from within a callback function.
New features include device lighting (SetLightingColor and ApplyLightingColors), touch input (GetTouchSurfaceInfo and IGameInputReading::GetTouchSurfaceState), the XInput index of a device (GetXInputDeviceIndex), and HID feature reports (GetRawDeviceFeature and SetRawDeviceFeature). Several new labels were also added to GameInputLabel and the device info structures.
The GameInput runtime can be sideloaded with your game instead of installed. For more information, see GameInput sideloading.

For a complete list of changes, see the Version History section of each page in the GameInput API reference. Pages for APIs that were removed in v.4 are listed in Deprecated GameInput API members.

Versioning tips

The change in the usable API surface between v.0 and v.1 is minimal, with the removal of functionality that was never implemented, along with the function signature changes described earlier.
The original v.0 API from the original GameInput.h header is still supported, but that API remains static. In this case, you would continue to use the header as-is from the GDK, older NuGet package, or the Windows SDK.
No matter which version of the API you use on PC, you must install the latest redistributable from the NuGet package during development, and include that redistributable (or newer) as part of your game's installation process to end users. Starting with GameInput 4.0, you can instead deploy the runtime with your game; see GameInput sideloading. This redistributable is where the newer GameInput runtime implementation exists, and it enhances all versions of the API with things like expanded controller support, trackpad support, remote desktop support, and various other bug fixes. On XBOX, the runtime is included with the GDK; see GameInput on XBOX consoles.

Feedback

Was this page helpful?

Last updated on 2026-11-04