> ## 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

> GameInputSensorsState 結構的參考：回報 GameInput 感應器的加速計、陀螺儀、羅盤方位和方向四元數。

# GameInputSensorsState

描述感應器的狀態。

## 語法

```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;
};
```

### 成員

*accelerationInGX*\

類型：float

相對於 x 軸的線性加速度 (以 g 力為單位)。若 `GameInputSensorsInfo` 回報 `GameInputSensorsKindAccelerometer`，則此值有效。

*accelerationInGY*\

類型：float

相對於 y 軸的線性加速度 (以 g 力為單位)。若 `GameInputSensorsInfo` 回報 `GameInputSensorsKindAccelerometer`，則此值有效。

*accelerationInGZ*\

類型：float

相對於 z 軸的線性加速度 (以 g 力為單位)。若 `GameInputSensorsInfo` 回報 `GameInputSensorsKindAccelerometer`，則此值有效。

*angularVelocityInRadPerSecX*\

類型：float

相對於 x 軸的角速度 (以每秒弧度為單位)。若 `GameInputSensorsInfo` 回報
`GameInputSensorsKindGyrometer`，則此值有效。

*angularVelocityInRadPerSecY*\

類型：float

相對於 y 軸的角速度 (以每秒弧度為單位)。若 `GameInputSensorsInfo` 回報
`GameInputSensorsKindGyrometer`，則此值有效。

*angularVelocityInRadPerSecZ*\

類型：float

相對於 z 軸的角速度 (以每秒弧度為單位)。若 `GameInputSensorsInfo` 回報
`GameInputSensorsKindGyrometer`，則此值有效。

*headingInDegreesFromMagneticNorth*\

類型：float

相對於磁北的方位 (以度為單位)。範圍：\[0, 360)。若 `GameInputSensorsInfo` 回報
`GameInputSensorsKindCompass`，則此值有效。

*headingAccuracy*\

類型：[GameInputSensorAccuracy](https://docs.xbox.com/zh-TW/reference/input/gameinput/enums/gameinputsensoraccuracy.md)

方位的精確度。若 `GameInputSensorsInfo` 回報 `GameInputSensorsKindCompass`，則此值有效。

*orientationW*\

類型：float

代表裝置方向之四元數的 w 分量。若 `GameInputSensorsInfo` 回報
`GameInputSensorsKindOrientation`，則此值有效。

*orientationX*\

類型：float

代表裝置方向之四元數的 x 分量。若 `GameInputSensorsInfo` 回報
`GameInputSensorsKindOrientation`，則此值有效。

*orientationY*\

類型：float

代表裝置方向之四元數的 y 分量。若 `GameInputSensorsInfo` 回報
`GameInputSensorsKindOrientation`，則此值有效。

*orientationZ*\

類型：float

代表裝置方向之四元數的 z 分量。若 `GameInputSensorsInfo` 回報
`GameInputSensorsKindOrientation`，則此值有效。

## 備註

此結構由 [IGameInputReading::GetSensorsState](https://docs.xbox.com/zh-TW/reference/input/gameinput/interfaces/igameinputreading/methods/igameinputreading_getsensorsstate.md) 方法使用。

如需詳細資訊，請參閱 [GameInput 讀數](https://docs.xbox.com/zh-TW/build/core-features/common/input/overviews/input-readings.md)。

是否存在有效資料，由 [GameInputDeviceInfo](https://docs.xbox.com/zh-TW/reference/input/gameinput/structs/gameinputdeviceinfo.md) 中的
[GameInputKindSensors](https://docs.xbox.com/zh-TW/reference/input/gameinput/enums/gameinputkind.md) 表示。未回報為存在的資料將會以
預設的靜止值填入。

### 座標系統

裝置應以 Y 軸朝上的右手座標系統回報裝置加速度。角速度遵循繞這些軸的右手
定則。

| 控制器座標系統 | 掌上型裝置座標系統 |
| - | - |
| ![顯示於控制器上的感應器座標系統](https://mintcdn.com/microsoft-4404708b/5IpvKlT-jmAaVkeY/images/input-sensors-coordinates-gamepad.png?fit=max\&auto=format\&n=5IpvKlT-jmAaVkeY\&q=85\&s=cd864c92015f0cc7389d8c43e42e71af) | ![顯示於掌上型裝置上的感應器座標系統](https://mintcdn.com/microsoft-4404708b/5IpvKlT-jmAaVkeY/images/input-sensors-coordinates-handheld.png?fit=max\&auto=format\&n=5IpvKlT-jmAaVkeY\&q=85\&s=4d9b1548f5b414ab28b2772c4d937c80) |

X 軸從裝置中心指向右側。Y 軸從裝置中心指向
使用者的臉部。Z 軸從裝置中心指向底部外側。

範例加速度輸出 (以 g 為單位)：

* 裝置平放在桌上：{0, 1, 0}
  * 靜止時的角速度 (以每秒弧度為單位) 為 {0, 0, 0}
* 接著將裝置向上舉起：增加為 {0, 2, 0}
* 接著讓裝置落下：減少為 {0, 0, 0}
* 旋轉裝置，使頂部邊緣懸空、底部邊緣接觸表面：{0, 0, -1}
  * 移動期間，角速度 X 變為正值：{2, 0, 0}
* 回到平放狀態。
* 旋轉裝置，使左側邊緣懸空、右側邊緣接觸表面：{-1, 0, 0}
  * 移動期間，角速度 Z 變為負值：{0, 0, -2}
* 回到平放狀態。
* 順時針旋轉裝置 (與右手定則相反)
  * 移動期間，角速度 Y 變為負值：{0, -2, 0}

## 需求

**標頭：** GameInput.h

**支援的平台：** Windows、XBOX One 系列主機和 XBOX Series 主機

## 概念文件

* [建立 GameInput 感應器](https://docs.xbox.com/zh-TW/build/core-features/common/input/hardware/input-hardware-sensors.md)

## 另請參閱

[GameInput 概觀](https://docs.xbox.com/zh-TW/build/core-features/common/input/overviews/input-overview.md)\

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

## 版本歷程記錄

| 版本 | 變更 |
| - | - |
| **v2** | v2 中引進的**新結構**，包含加速計、陀螺儀、羅盤和方向的感應器狀態欄位。 |
| **v1** | 不存在。 |
| **v0** | 不存在。 |


## Related topics

- [GetSensorsState](https://docs.xbox.com/zh-TW/reference/input/gameinput/interfaces/igameinputreading/methods/igameinputreading_getsensorsstate.md)
- [GameInputSensorsKind](https://docs.xbox.com/zh-TW/reference/input/gameinput/enums/gameinputsensorskind.md)
- [GameInput 感應器建立](https://docs.xbox.com/zh-TW/build/core-features/common/input/hardware/input-hardware-sensors.md)
- [GameInputSensorAccuracy](https://docs.xbox.com/zh-TW/reference/input/gameinput/enums/gameinputsensoraccuracy.md)
- [GameInput API 成員](https://docs.xbox.com/zh-TW/reference/input/gameinput/gameinput_members.md)