IGameInputDevice::SetLightingColor

Stages a color for one or more lamps on the input device. The color is sent to the device the next time you call IGameInputDevice::ApplyLightingColors.

Syntax

void SetLightingColor(
    GameInputColor color,
    GameInputLightingGroups group,
    uint32_t groupOrderIndex = GAMEINPUT_LIGHTING_GROUP_ORDER_INDEX_ALL
);

Parameters

color
Type: GameInputColor The color to stage for the selected lamps. group
Type: GameInputLightingGroups The lighting group selection that contains the lamps to set. This can be one or more named group flags, GameInputLightingGroupAll to select every lamp on the device, or GameInputLightingGroupUnknown to select the lamps that don’t belong to any named group. groupOrderIndex _In_opt_
Type: uint32_t Selects an individual lamp within group. The default value, GAMEINPUT_LIGHTING_GROUP_ORDER_INDEX_ALL, selects every lamp in group. See Remarks for how other values are interpreted.

Return value

Type: void

Remarks

SetLightingColor doesn’t change the lamps immediately. It records (stages) the color for the selected lamps. Call IGameInputDevice::ApplyLightingColors to send all staged colors to the device in a single update. Because nothing is sent until you apply the colors, you can set several groups or individual lamps and have them change at the same time. Staged colors remain in effect after they’re applied, so to change one group later, you only need to stage the new color for that group and apply again. The groupOrderIndex parameter is interpreted as follows.

Value of groupOrderIndex	Lamps selected
`GAMEINPUT_LIGHTING_GROUP_ORDER_INDEX_ALL` (0xFFFFFFFF)	Every lamp in group.
A keyboard scan code, when group is `GameInputLightingGroupKeyboardKey`	The lamp for the key with that scan code. The scan code uses the Set 1 encoding: 0x01 through 0x7F, extended scan codes 0xE001 through 0xE07F, or 0xE11D for the Pause key.
Any other value	The lamp at that zero-based position within group. The value must be less than the value returned by IGameInputDevice::GetSupportedLightingGroupSize for group.

A selection that combines GameInputLightingGroupKeyboardKey with other named groups can’t select an individual lamp, because the index would be ambiguous. Use GAMEINPUT_LIGHTING_GROUP_ORDER_INDEX_ALL with such selections. GameInputLightingGroupAll can select an individual lamp by its zero-based position among all lamps on the device. If the selection isn’t valid for the device, the call is ignored and nothing is staged. A selection isn’t valid if it includes a named group that the device doesn’t have (see IGameInputDevice::GetSupportedLightingGroups), contains no lamps, or specifies a groupOrderIndex that’s out of range or isn’t a valid scan code. Calls on a disconnected device have no effect. To discard staged colors and return the lamps to their default behavior, call IGameInputDevice::ApplyLightingSystemDefault. The following example sets the face buttons of a controller to red and its center light to blue, and then applies both colors in a single update.

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();
}

The following example dims all keys on a keyboard with per-key lighting and highlights the A key, which has the Set 1 scan code 0x1E.

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();
}

Lighting support depends on the device and the platform. Currently, GameInput supports lighting on Windows Dynamic Lighting (LampArray) devices and on the lightbar of DualSense controllers.

Requirements

Header: GameInput.h Library: gameinput.lib Supported platforms: Windows, XBOX One family consoles and XBOX Series consoles

Version History

Version	Changes
v4	Introduced.

Chat API reference

Developer kit only API reference

Graphics API reference

Input API reference

Lighting API reference

Networking API reference

XBOX PC remote iteration API reference

System API reference

Tools API reference

Windows device portal REST API reference

XBOX services API reference

MicrosoftGame.config reference

Additional pages

Reference

Syntax

Parameters

Return value

Remarks

Requirements

See also

Version History

​Syntax

​Parameters

​Return value

​Remarks

​Requirements

​See also

​Version History

Syntax

Parameters

Return value

Remarks

Requirements

See also

Version History