Game Input API Reference
IXAudio2EngineCallback
The Game Input API provides a comprehensive set of interfaces and structures for handling game controller input on Windows. It allows developers to access raw input from various gamepads, joysticks, and other gaming peripherals, abstracting away the underlying hardware complexities.
Key Concepts
The Game Input API revolves around several core concepts:
- Input Devices: Represents physical gaming peripherals connected to the system.
- Input States: Captures the current readings from input devices, including button presses, analog stick positions, and trigger values.
- Input Events: Notifications that are triggered when changes occur in the state of an input device, such as a button being pressed or an analog stick being moved.
- Input Readers: Objects that allow you to poll or receive notifications about input states.
Core Interfaces
IGameInputDeviceManager
This interface is the primary entry point for interacting with game input devices. It allows you to enumerate connected devices, register for device connection/disconnection notifications, and obtain handles to individual input devices.
HRESULT GetDevices(
[out] const IGameInputDevice** devices,
[out] UINT32* deviceCount
);
IGameInputDevice
Represents a single connected game input device. Through this interface, you can retrieve device information, such as its type and capabilities, and create input readers for it.
HRESULT GetDeviceInfo(
[out] GameInputDeviceInfo* deviceInfo
);
HRESULT CreateReader(
[out] IGameInputReader** reader
);
IGameInputReader
An interface used to read input states from a specific device. You can poll for the latest input state or register callbacks for state changes.
HRESULT ReadCurrentState(
[in] GameInputKind desiredState,
[out] GameInputState* currentState
);
HRESULT RegisterCallback(
[in] GameInputKind desiredState,
[in] GameInputCallbackFunction callback,
[in] void* context,
[out] GameInputHandle* handle
);
Structures
GameInputDeviceInfo
Contains information about a game input device.
typedef struct GameInputDeviceInfo {
GameInputDeviceKind deviceKind;
wchar_t deviceName[64];
USHORT vendorId;
USHORT productId;
// ... other device specific information
} GameInputDeviceInfo;GameInputState
Represents the current state of a game input device.
typedef struct GameInputState {
GameInputKind kind;
GameInputTimestamp timestamp;
GameInputControllerState controllerState;
// ... other state types like keyboard, mouse, etc.
} GameInputState;GameInputControllerState
Represents the state of a gamepad or controller, including buttons and analog sticks.
typedef struct GameInputControllerState {
UINT32 packetNumber;
UINT64 buttons;
FLOAT leftThumbstickX;
FLOAT leftThumbstickY;
FLOAT rightThumbstickX;
FLOAT rightThumbstickY;
FLOAT leftTrigger;
FLOAT rightTrigger;
// ... D-pad, hats, etc.
} GameInputControllerState;Example Usage
The following snippet demonstrates how to initialize the Game Input API, get a list of connected controllers, and read their current state.
#include <Windows.h>
#include <GameInput.h>
int main() {
IGameInputDeviceManager* pDeviceManager = nullptr;
HRESULT hr = GameInputCreateDeviceManager(&pDeviceManager);
if (SUCCEEDED(hr)) {
const IGameInputDevice** devices = nullptr;
UINT32 deviceCount = 0;
hr = pDeviceManager->GetDevices(devices, &deviceCount);
if (SUCCEEDED(hr) && deviceCount > 0) {
for (UINT32 i = 0; i < deviceCount; ++i) {
IGameInputDevice* pDevice = const_cast<IGameInputDevice*>(devices[i]); // Need to cast away const if not provided as non-const pointer
GameInputDeviceInfo deviceInfo;
hr = pDevice->GetDeviceInfo(&deviceInfo);
if (SUCCEEDED(hr) && deviceInfo.deviceKind == GameInputDeviceKind_Controller) {
IGameInputReader* pReader = nullptr;
hr = pDevice->CreateReader(&pReader);
if (SUCCEEDED(hr)) {
GameInputState state;
// Read only controller state
hr = pReader->ReadCurrentState(GameInputKind_Controller, &state);
if (SUCCEEDED(hr)) {
wprintf(L"Device: %s, Buttons: %llX\n", deviceInfo.deviceName, state.controllerState.buttons);
}
pReader->Release();
}
}
}
}
pDeviceManager->Release();
}
return 0;
}