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

# IGameInputDevice::SetLightingColor

> 为输入设备上的一个或多个灯暂存一种颜色。

为输入设备上的一个或多个灯暂存一种颜色。下次调用 [IGameInputDevice::ApplyLightingColors](https://docs.xbox.com/zh-CN/reference/input/gameinput/interfaces/igameinputdevice/methods/igameinputdevice_applylightingcolors.md) 时，该颜色会被发送到设备。

## 语法

```cpp theme={null}
void SetLightingColor(
    GameInputColor color,
    GameInputLightingGroups group,
    uint32_t groupOrderIndex = GAMEINPUT_LIGHTING_GROUP_ORDER_INDEX_ALL
);
```

### 参数

*color*\
类型：[GameInputColor](https://learn.microsoft.com/en-us/gaming/gdk/docs/reference/input/gameinput/structs/gameinputcolor)

要为所选灯暂存的颜色。

*group*\
类型：[GameInputLightingGroups](https://learn.microsoft.com/en-us/gaming/gdk/docs/reference/input/gameinput/enums/gameinputlightinggroups)

包含要设置的灯的灯光组选择。可以是一个或多个命名组标志、用于选择设备上每个灯的 `GameInputLightingGroupAll`，或用于选择不属于任何命名组的灯的 `GameInputLightingGroupUnknown`。

*groupOrderIndex*   \_In\_opt\_\
类型：uint32\_t

选择 *group* 中的单个灯。默认值 `GAMEINPUT_LIGHTING_GROUP_ORDER_INDEX_ALL` 选择 *group* 中的每个灯。有关其他值的解释方式，请参阅“备注”。

### 返回值

类型：void

## 备注

`SetLightingColor` 不会立即更改灯的状态。它会为所选灯记录（暂存）颜色。调用 [IGameInputDevice::ApplyLightingColors](https://docs.xbox.com/zh-CN/reference/input/gameinput/interfaces/igameinputdevice/methods/igameinputdevice_applylightingcolors.md) 可通过一次更新将所有暂存的颜色发送到设备。由于在应用颜色之前不会发送任何内容，因此你可以设置多个组或多个单独的灯，并让它们同时发生变化。暂存的颜色在应用后仍然有效，因此若要稍后更改某个组，只需为该组暂存新颜色并再次应用即可。

*groupOrderIndex* 参数按如下方式解释。

| *groupOrderIndex* 的值 | 所选的灯 |
| - | - |
| `GAMEINPUT_LIGHTING_GROUP_ORDER_INDEX_ALL` (0xFFFFFFFF) | *group* 中的每个灯。 |
| 当 *group* 为 `GameInputLightingGroupKeyboardKey` 时，为键盘扫描码 | 具有该扫描码的按键的灯。扫描码使用 Set 1 编码：0x01 到 0x7F、扩展扫描码 0xE001 到 0xE07F，或者 Pause 键的 0xE11D。 |
| 任何其他值 | *group* 中位于该从零开始位置的灯。该值必须小于针对 *group* 调用 [IGameInputDevice::GetSupportedLightingGroupSize](https://docs.xbox.com/zh-CN/reference/input/gameinput/interfaces/igameinputdevice/methods/igameinputdevice_getsupportedlightinggroupsize.md) 返回的值。 |

将 `GameInputLightingGroupKeyboardKey` 与其他命名组组合的选择无法选择单个灯，因为索引会产生歧义。对于此类选择，请使用 `GAMEINPUT_LIGHTING_GROUP_ORDER_INDEX_ALL`。`GameInputLightingGroupAll` 可以按单个灯在设备所有灯中的从零开始的位置来选择该灯。

如果所选范围对设备无效，则该调用会被忽略，并且不会暂存任何内容。如果所选范围包含设备不具有的命名组（请参阅 [IGameInputDevice::GetSupportedLightingGroups](https://docs.xbox.com/zh-CN/reference/input/gameinput/interfaces/igameinputdevice/methods/igameinputdevice_getsupportedlightinggroups.md)）、不包含任何灯，或者指定的 *groupOrderIndex* 超出范围或不是有效的扫描码，则该所选范围无效。对已断开连接的设备进行的调用不起作用。

若要丢弃暂存的颜色并让灯恢复默认行为，请调用 [IGameInputDevice::ApplyLightingSystemDefault](https://docs.xbox.com/zh-CN/reference/input/gameinput/interfaces/igameinputdevice/methods/igameinputdevice_applylightingsystemdefault.md)。

以下示例将控制器的正面按钮设置为红色、将中央灯设置为蓝色，然后通过一次更新应用这两种颜色。

```cpp theme={null}
void SetControllerLighting(IGameInputDevice* device) noexcept
{
    const GameInputLightingGroups groups = device->GetSupportedLightingGroups();

    if ((groups & GameInputLightingGroupFaceButtons) != 0)
    {
        device->SetLightingColor({ 255, 0, 0 }, GameInputLightingGroupFaceButtons);
    }

    if ((groups & GameInputLightingGroupCenterLight) != 0)
    {
        device->SetLightingColor({ 0, 0, 255 }, GameInputLightingGroupCenterLight);
    }

    device->ApplyLightingColors();
}
```

以下示例在具有逐键灯光的键盘上调暗所有按键，并突出显示 A 键（其 Set 1 扫描码为 0x1E）。

```cpp theme={null}
void HighlightKeyA(IGameInputDevice* device) noexcept
{
    if ((device->GetSupportedLightingGroups() & GameInputLightingGroupKeyboardKey) == 0)
    {
        return;
    }

    device->SetLightingColor({ 16, 16, 16 }, GameInputLightingGroupKeyboardKey);
    device->SetLightingColor({ 0, 255, 0 }, GameInputLightingGroupKeyboardKey, 0x1E);
    device->ApplyLightingColors();
}
```

> [!NOTE]
>
> 灯光支持取决于设备和平台。目前，GameInput 支持 Windows 动态光效 (LampArray) 设备以及 DualSense 控制器灯条的灯光。

## 要求

**头文件：** GameInput.h

**库：** gameinput.lib

**支持的平台：** Windows、XBOX One 系列主机和 XBOX Series 主机

## 另请参阅

[GameInput 概述](https://docs.xbox.com/zh-CN/build/core-features/common/input/overviews/input-overview.md)\
[IGameInputDevice](https://docs.xbox.com/zh-CN/reference/input/gameinput/interfaces/igameinputdevice/igameinputdevice.md)\
[GameInputColor](https://learn.microsoft.com/en-us/gaming/gdk/docs/reference/input/gameinput/structs/gameinputcolor)\
[GameInputLightingGroups](https://learn.microsoft.com/en-us/gaming/gdk/docs/reference/input/gameinput/enums/gameinputlightinggroups)\
[IGameInputDevice::ApplyLightingColors](https://docs.xbox.com/zh-CN/reference/input/gameinput/interfaces/igameinputdevice/methods/igameinputdevice_applylightingcolors.md)\
[IGameInputDevice::ApplyLightingSystemDefault](https://docs.xbox.com/zh-CN/reference/input/gameinput/interfaces/igameinputdevice/methods/igameinputdevice_applylightingsystemdefault.md)\
[IGameInputDevice::GetSupportedLightingGroups](https://docs.xbox.com/zh-CN/reference/input/gameinput/interfaces/igameinputdevice/methods/igameinputdevice_getsupportedlightinggroups.md)\
[IGameInputDevice::GetSupportedLightingGroupSize](https://docs.xbox.com/zh-CN/reference/input/gameinput/interfaces/igameinputdevice/methods/igameinputdevice_getsupportedlightinggroupsize.md)

## 版本历史

| 版本 | 变更 |
| - | - |
| **v4** | 引入。 |


## Related topics

- [IGameInputDevice::ApplyLightingColors](https://docs.xbox.com/zh-CN/reference/input/gameinput/interfaces/igameinputdevice/methods/igameinputdevice_applylightingcolors.md)
- [IGameInputDevice::ApplyLightingSystemDefault](https://docs.xbox.com/zh-CN/reference/input/gameinput/interfaces/igameinputdevice/methods/igameinputdevice_applylightingsystemdefault.md)
- [IGameInputDevice::GetSupportedLightingGroups](https://docs.xbox.com/zh-CN/reference/input/gameinput/interfaces/igameinputdevice/methods/igameinputdevice_getsupportedlightinggroups.md)
- [IGameInputDevice::GetSupportedLightingGroupSize](https://docs.xbox.com/zh-CN/reference/input/gameinput/interfaces/igameinputdevice/methods/igameinputdevice_getsupportedlightinggroupsize.md)
- [GameInput API 成员](https://docs.xbox.com/zh-CN/reference/input/gameinput/gameinput_members.md)