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

# GameInput 中的触觉反馈

> GameInput 中的触觉反馈

GameInput 公开的触觉反馈能力与 Windows 音频系统集成，以确保向兼容设备高效、稳健地传输波形数据。启用触觉反馈的设备的音频要求与普通桌面扬声器或耳机非常相似。GameInput 使用约定与制造商指定的元数据相结合的方式，将输入设备与用于触觉播放的音频端点相关联。

<a id="requirementsSection" />

## 要求

1. 设备必须在 Windows 中被识别为音频源。连接介质（USB、Bluetooth® 等）不作要求。
2. 设备最多只能公开一个触觉端点。
3. 设备最多只能公开八个触觉位置。
4. 设备在连接后不得修改其触觉能力。
5. 设备不得存在多个格式相同（每样本位数与每秒采样数相同）的音频端点。
6. 设备的音频端点必须与设备其余部分呈现相同的[容器 ID](https://learn.microsoft.com/windows-hardware/drivers/install/container-ids)。
7. 设备必须在注册表中有条目以显式标识其触觉端点。格式如下：

   * 触觉设备在注册表 `HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\GameInput\Devices` 下枚举。
   * 特定的设备键由供应商 ID、产品 ID、用途页和用途 ID 组合形成，格式为十六进制字符串。
   * `HapticSamplesPerSecond` 是一个 DWORD 值，标识触觉端点格式的每秒采样数 (Hz)。
   * `HapticsBitsPerSample` 是一个 DWORD 值，标识触觉端点格式的每样本位数（采样尺寸）。
   * `HapticLocations` 是一个由触觉位置 GUID 组成的 BYTE 数组。该数组必须包含 1 到 8 个 GUID，对应触觉通道映射。

   为便于说明，请看以下示例设备：

   | 字段     | 值                                                                                 |
   | ------ | --------------------------------------------------------------------------------- |
   | 供应商 ID | 0x045e                                                                            |
   | 产品 ID  | 0x1234                                                                            |
   | 用途页    | 0x0001                                                                            |
   | 用途 ID  | 0x0005                                                                            |
   | 采样频率   | 0x0fa0                                                                            |
   | 采样尺寸   | 0x0010                                                                            |
   | 触觉位置   | GAMEINPUT\_HAPTIC\_LOCATION\_GRIP\_LEFT, GAMEINPUT\_HAPTIC\_LOCATION\_GRIP\_RIGHT |

   对应的触觉注册表项如下所示：

```
    Windows Registry Editor Version 5.00

    [HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\GameInput\Devices\045E123400010005]
    "HapticSamplesPerSecond"=dword:00000fa0
    "HapticBitsPerSample"=dword:00000010
    "HapticLocations"=hex:c2,07,c7,08,bb,66,6c,40,a8,4a,df,e0,85,12,0a,92,77,0b,5a,\
    15,b2,8b,db,40,86,90,b6,d4,11,26,df,c1
```

### 触觉位置

目前，以下触觉位置 GUID 已定义供通用使用：

```cpp theme={null}
// { 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00 }
DEFINE_GUID(GAMEINPUT_HAPTIC_LOCATION_NONE, 0x00000000, 0x0000, 0x0000, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00);

// { 0xc2, 0x07, 0xc7, 0x08, 0xbb, 0x66, 0x6c, 0x40, 0xa8, 0x4a, 0xdf, 0xe0, 0x85, 0x12, 0x0a, 0x92 }
DEFINE_GUID(GAMEINPUT_HAPTIC_LOCATION_GRIP_LEFT, 0x08c707c2, 0x66bb, 0x406c, 0xa8, 0x4a, 0xdf, 0xe0, 0x85, 0x12, 0x0a, 0x92);

// { 0x77, 0x0b, 0x5a, 0x15, 0xb2, 0x8b, 0xdb, 0x40, 0x86, 0x90, 0xb6, 0xd4, 0x11, 0x26, 0xdf, 0xc1 }
DEFINE_GUID(GAMEINPUT_HAPTIC_LOCATION_GRIP_RIGHT, 0x155a0b77, 0x8bb2, 0x40db, 0x86, 0x90, 0xb6, 0xd4, 0x11, 0x26, 0xdf, 0xc1);

// { 0x96, 0xd8, 0xe4, 0x8d, 0x59, 0x55, 0x81, 0x40, 0x86, 0xe5, 0x17, 0x24, 0xcc, 0x07, 0xc6, 0xbc }
DEFINE_GUID(GAMEINPUT_HAPTIC_LOCATION_TRIGGER_LEFT, 0x8de4d896, 0x5559, 0x4081, 0x86, 0xe5, 0x17, 0x24, 0xcc, 0x07, 0xc6, 0xbc);

// { 0x57, 0xb5, 0x0c, 0xff, 0xf5, 0x3a, 0x6b, 0x40, 0x8b, 0x0f, 0x55, 0x5a, 0x2d, 0x92, 0xa2, 0x20 }
DEFINE_GUID(GAMEINPUT_HAPTIC_LOCATION_TRIGGER_RIGHT, 0xff0cb557, 0x3af5, 0x406b, 0x8b, 0x0f, 0x55, 0x5a, 0x2d, 0x92, 0xa2, 0x20);
```

请注意，在上述示例中，GUID 使用其在内存中的小端表示序列化到注册表。

<a id="seealsoSection" />

## 参考 API 文档

* [GameInput（API 目录）](/reference/input/gameinput/gameinput_members)
  * 结构体
    * [GameInputHapticInfo](/reference/input/gameinput/structs/gameinputhapticinfo)

## 另请参阅

[GetHapticInfo](/reference/input/gameinput/interfaces/igameinputdevice/methods/igameinputdevice_gethapticinfo)

[GameInputHapticInfo](/reference/input/gameinput/structs/gameinputhapticinfo)

[GameInput 概述](/build/core-features/common/input/overviews/input-overview)

[Windows 音频](/build/console-features/audio/overviews/audio)


## Related topics

- [GameInput 硬件：力反馈、触觉与传感器](/zh-CN/build/core-features/common/input/hardware/index.md)
- [GameInput](/zh-CN/reference/input/gameinput/gameinput_members.md)
- [GameInputHapticWaveformInfo](/zh-CN/reference/input/gameinput/deprecated/structs/gameinputhapticwaveforminfo.md)
- [IGameInputDevice::SetHapticMotorState](/zh-CN/reference/input/gameinput/deprecated/interfaces/igameinputdevice/methods/igameinputdevice_sethapticmotorstate.md)
- [GameInputHapticFeedbackParams](/zh-CN/reference/input/gameinput/deprecated/structs/gameinputhapticfeedbackparams.md)