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

# GameInputSensorsState

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

# GameInputSensorsState

描述感應器的狀態。

<a id="syntaxSection" />

## 語法

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

<a id="membersSection" />

### 成員

*accelerationInGX*<br />
類型：float

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

*accelerationInGY*<br />
類型：float

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

*accelerationInGZ*<br />
類型：float

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

*angularVelocityInRadPerSecX*<br />
類型：float

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

*angularVelocityInRadPerSecY*<br />
類型：float

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

*angularVelocityInRadPerSecZ*<br />
類型：float

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

*headingInDegreesFromMagneticNorth*<br />
類型：float

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

*headingAccuracy*<br />
類型：[GameInputSensorAccuracy](/zh-TW/reference/input/gameinput/enums/gameinputsensoraccuracy)

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

*orientationW*<br />
類型：float

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

*orientationX*<br />
類型：float

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

*orientationY*<br />
類型：float

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

*orientationZ*<br />
類型：float

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

<a id="remarksSection" />

## 備註

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

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

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

### 座標系統

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

| 控制器座標系統 | 掌上型裝置座標系統 |
| - | - |
| <img src="https://mintcdn.com/microsoft-4404708b/5IpvKlT-jmAaVkeY/images/input-sensors-coordinates-gamepad.png?fit=max&auto=format&n=5IpvKlT-jmAaVkeY&q=85&s=cd864c92015f0cc7389d8c43e42e71af" alt="顯示於控制器上的感應器座標系統" height="300" data-path="images/input-sensors-coordinates-gamepad.png" /> | <img src="https://mintcdn.com/microsoft-4404708b/5IpvKlT-jmAaVkeY/images/input-sensors-coordinates-handheld.png?fit=max&auto=format&n=5IpvKlT-jmAaVkeY&q=85&s=4d9b1548f5b414ab28b2772c4d937c80" alt="顯示於掌上型裝置上的感應器座標系統" height="300" data-path="images/input-sensors-coordinates-handheld.png" /> |

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}

<a id="requirementsSection" />

## 需求

**標頭：** GameInput.h

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

<a id="seealsoSection" />

## 概念文件

* [建立 GameInput 感應器](/zh-TW/build/core-features/common/input/hardware/input-hardware-sensors)

## 另請參閱

[GameInput 概觀](/zh-TW/build/core-features/common/input/overviews/input-overview)<br />
[GameInput](/zh-TW/reference/input/gameinput/gameinput_members)

## 版本歷程記錄

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


## Related topics

- [GameInputSensorsState](/reference/input/gameinput/structs/gameinputsensorsstate.md)
- [Sensors in GameInput](/build/core-features/common/input/hardware/input-hardware-sensors.md)
- [IGameInputReading::GetSensorsState](/reference/input/gameinput/interfaces/igameinputreading/methods/igameinputreading_getsensorsstate.md)
- [GameInputSensorsKind](/reference/input/gameinput/enums/gameinputsensorskind.md)
- [GameInputSensorAccuracy](/reference/input/gameinput/enums/gameinputsensoraccuracy.md)