XINPUTSTATE

XINPUT_STATE is a data structure used by the Windows XInput API to report the current state of a connected gamepad. It is filled by the function XInputGetState and is commonly used by games and input libraries to poll the controller.

The XINPUT_STATE structure contains two members: dwPacketNumber and Gamepad. The dwPacketNumber is a monotonically increasing value that changes whenever the state of the controller changes, allowing applications to detect updates efficiently by comparing successive calls. The Gamepad member is itself a structure, XINPUT_GAMEPAD, which holds the detailed state of the physical controls.

XINPUT_GAMEPAD includes the following fields: wButtons, bLeftTrigger, bRightTrigger, sThumbLX, sThumbLY, sThumbRX, and sThumbRY. The wButtons field is a bitmask that represents the pressed state of the controller buttons, including the directional pad (D-Pad) and standard face and thumbstick buttons. The bLeftTrigger and bRightTrigger fields are 8-bit values (0-255) indicating how much each trigger is pressed. The thumbstick fields sThumbLX, sThumbLY, sThumbRX, and sThumbRY are 16-bit signed values (-32768 to 32767) that report the position of the left and right sticks along their X and Y axes, with centered sticks typically near zero.

Button mappings are defined as constants in the API (for example, XINPUT_GAMEPAD_A, XINPUT_GAMEPAD_B, XINPUT_GAMEPAD_X, XINPUT_GAMEPAD_Y, and corresponding D-Pad, Start, Back, and Thumbstick buttons). Applications typically read these bits to determine input and apply dead zones to thumbstick data as needed.

XInputGetState is called with a user index (0 to 3) to retrieve an XINPUT_STATE for up to four controllers. A successful call returns ERROR_SUCCESS and fills the structure; if the device is not connected, it returns ERROR_DEVICE_NOT_CONNECTED.