> ## Documentation Index
> Fetch the complete documentation index at: https://docs.xbox.com/llms.txt
> Use this file to discover all available pages before exploring further.

# GameInputSensorsState

> Reference for the GameInputSensorsState struct: reports accelerometer, gyrometer, compass heading, and orientation quaternion for GameInput sensors.

Describes the state of sensors.

## Syntax

```cpp theme={null}
struct GameInputSensorsState
{
    // GameInputSensorsAccelerometer
    float accelerationInGX;
    float accelerationInGY;
    float accelerationInGZ;

    // GameInputSensorsGyrometer
    float angularVelocityInRadPerSecX;
    float angularVelocityInRadPerSecY;
    float angularVelocityInRadPerSecZ;

    // GameInputSensorsCompass
    float headingInDegreesFromMagneticNorth;
    GameInputSensorAccuracy headingAccuracy;

    // GameInputSensorsOrientation
    float orientationW;
    float orientationX;
    float orientationY;
    float orientationZ;
};
```

### Members

*accelerationInGX*\

Type: float

Linear acceleration, in g-force, with respect to the x axis. Valid if `GameInputSensorsInfo` reports `GameInputSensorsKindAccelerometer`.

*accelerationInGY*\

Type: float

Linear acceleration, in g-force, with respect to the y axis. Valid if `GameInputSensorsInfo` reports `GameInputSensorsKindAccelerometer`.

*accelerationInGZ*\

Type: float

Linear acceleration, in g-force, with respect to the z axis. Valid if `GameInputSensorsInfo` reports `GameInputSensorsKindAccelerometer`.

*angularVelocityInRadPerSecX*\

Type: float

Angular velocity, in radians per second, with respect to the x axis. Valid if `GameInputSensorsInfo` reports
`GameInputSensorsKindGyrometer`.

*angularVelocityInRadPerSecY*\

Type: float

Angular velocity, in radians per second, with respect to the y axis. Valid if `GameInputSensorsInfo` reports
`GameInputSensorsKindGyrometer`.

*angularVelocityInRadPerSecZ*\

Type: float

Angular velocity, in radians per second, with respect to the z axis. Valid if `GameInputSensorsInfo` reports
`GameInputSensorsKindGyrometer`.

*headingInDegreesFromMagneticNorth*\

Type: float

Heading, in degrees, from magnetic north. Range: \[0, 360). Valid if `GameInputSensorsInfo` reports
`GameInputSensorsKindCompass`.

*headingAccuracy*\

Type: [GameInputSensorAccuracy](https://docs.xbox.com/reference/input/gameinput/enums/gameinputsensoraccuracy.md)

Accuracy of the heading. Valid if `GameInputSensorsInfo` reports `GameInputSensorsKindCompass`.

*orientationW*\

Type: float

The w-component of a quaternion representing the device's orientation. Valid if `GameInputSensorsInfo` reports
`GameInputSensorsKindOrientation`.

*orientationX*\

Type: float

The x-component of a quaternion representing the device's orientation. Valid if `GameInputSensorsInfo` reports
`GameInputSensorsKindOrientation`.

*orientationY*\

Type: float

The y-component of a quaternion representing the device's orientation. Valid if `GameInputSensorsInfo` reports
`GameInputSensorsKindOrientation`.

*orientationZ*\

Type: float

The z-component of a quaternion representing the device's orientation. Valid if `GameInputSensorsInfo` reports
`GameInputSensorsKindOrientation`.

## Remarks

This structure is used by the [IGameInputReading::GetSensorsState](https://docs.xbox.com/reference/input/gameinput/interfaces/igameinputreading/methods/igameinputreading_getsensorsstate.md) method.

For more information, see [GameInput readings](https://docs.xbox.com/build/core-features/common/input/overviews/input-readings.md).

The presence of valid data is indicated by [GameInputKindSensors](https://docs.xbox.com/reference/input/gameinput/enums/gameinputkind.md) in
[GameInputDeviceInfo](https://docs.xbox.com/reference/input/gameinput/structs/gameinputdeviceinfo.md). Data that is not reported as being present will be filled
with default at-rest values.

### Coordinate system

Devices are expected to report device acceleration as a Y-up right-handed system. Angular velocity follows the right-hand
rule about these axes.

| Gamepad coordinate system | Handheld coordinate system |
| - | - |
| ![Sensors coordinate system shown on a gamepad](https://mintcdn.com/microsoft-4404708b/5IpvKlT-jmAaVkeY/images/input-sensors-coordinates-gamepad.png?fit=max\&auto=format\&n=5IpvKlT-jmAaVkeY\&q=85\&s=cd864c92015f0cc7389d8c43e42e71af) | ![Sensors coordinate system shown on a handheld](https://mintcdn.com/microsoft-4404708b/5IpvKlT-jmAaVkeY/images/input-sensors-coordinates-handheld.png?fit=max\&auto=format\&n=5IpvKlT-jmAaVkeY\&q=85\&s=4d9b1548f5b414ab28b2772c4d937c80) |

The X axis goes from the center of the device towards the right. The Y axis goes from the center of the device towards
the user’s face. The Z axis goes from the center of the device out the bottom.

Sample acceleration output, in g:

* Device laying flat on table: {0, 1, 0}
  * Angular velocity at rest, in radians per second, is {0, 0, 0}
* From there, lift device upwards: increases {0, 2, 0}
* From there, drop device: decreases {0, 0, 0}
* Rotate device so top edge is in air and bottom edge is on surface: {0, 0, -1}
  * While in motion, angular velocity X becomes positive: {2, 0, 0}
* Go back to flat.
* Rotate device so left edge is in air and right edge is on surface: {-1, 0, 0}
  * While in motion, angular velocity Z becomes negative: {0, 0, -2}
* Go back to flat.
* Rotate device clockwise (opposite to right-hand rule)
  * While in motion, angular velocity Y becomes negative: {0, -2, 0}

## Requirements

**Header:** GameInput.h

**Supported platforms:** Windows, XBOX One family consoles and XBOX Series consoles

## Conceptual documentation

* [GameInput sensors creation](https://docs.xbox.com/build/core-features/common/input/hardware/input-hardware-sensors.md)

## See also

[Overview of GameInput](https://docs.xbox.com/build/core-features/common/input/overviews/input-overview.md)\

[GameInput](https://docs.xbox.com/reference/input/gameinput/gameinput_members.md)

## Version History

| Version | Changes |
| - | - |
| **v2** | **New struct** introduced in v2 with sensor state fields for accelerometer, gyrometer, compass, and orientation. |
| **v1** | Not present. |
| **v0** | Not present. |


## Related topics

- [GetSensorsState](https://docs.xbox.com/reference/input/gameinput/interfaces/igameinputreading/methods/igameinputreading_getsensorsstate.md)
- [GameInput sensors creation](https://docs.xbox.com/build/core-features/common/input/hardware/input-hardware-sensors.md)
- [GameInputSensorsKind](https://docs.xbox.com/reference/input/gameinput/enums/gameinputsensorskind.md)
- [GameInputSensorAccuracy](https://docs.xbox.com/reference/input/gameinput/enums/gameinputsensoraccuracy.md)
- [GameInput API members](https://docs.xbox.com/reference/input/gameinput/gameinput_members.md)