在 LampArray 上设置颜色

ILampArray 上的所有颜色更新函数都使用 LampArrayColor 结构来表示 RGBA 颜色值。

alpha 值 (LampArrayColor::a) 表示颜色的相对透明度，其中零是完全透明，0xFF 是完全不透明。 如果使用除 0xFF 以外的 Alpha 值，则颜色会针对黑色进行额外的混合步骤。 若要避免此混合步骤，请不要在设置颜色时传入除 0xFF 以外的任何 Alpha 值。

ILampArray SetColor API 旨在从单个线程调用，以获得最佳性能和 Lamp 状态一致性。

正在更新所有 Lamp

ILampArray::SetColor 方法更改设备上的所有灯以匹配所需颜色。

以下示例注册 LampArray 回调并设置每个附加设备的颜色。

const LampArrayColor greenColor = { 0x0 /* r */, 0xFF /* g */, 0x0 /* b */, 0xFF /* a */};
std::vector<Microsoft::WRL::ComPtr<ILampArray>> lampArrays;

void MyLampArrayCallback(
    _In_opt_ void* context,
    bool isAttached,
    _In_ ILampArray* lampArray)
{
    if (isAttached)
    {
        lampArray->SetColor(greenColor);
        lampArrays.push_back(lampArray);
    }
    else
    {
        for (auto iter = lampArrays.begin(); iter != lampArrays.end(); )
        {
            if (iter->Get() == lampArray)
            {
                lampArrays.erase(iter);
            }
            else
            {
                iter++;
            }
        }
    }
}

void MainLoop(
    _In_ volatile bool & cancelMonitoring) noexcept
{
    LampArrayCallbackToken token = LAMPARRAY_INVALID_CALLBACK_TOKEN_VALUE;
    if (SUCCEEDED(RegisterLampArrayCallback(
        MyLampArrayCallback,
        nullptr /* context */,
        &token)))
    {
        while (!cancelMonitoring)
        {
            Sleep(100);
        }

        UnregisterLampArrayCallback(token, 5000);
    }
}

以单个 Lamp 或 Lamp 组为目标

ILampArray::SetColorsForIndices 用于更新 LampArray 的一个或多个灯。 传入此 API 的灯索引可按任意顺序排列。

下面的示例演示如何在 LampArray 的所有 Lamp 上设置交替颜色。

void SetAlternatingColors(ILampArray* lampArray)
{
    const LampArrayColor blueColor = { 0x0 /* r */, 0x0 /* g */, 0xFF /* b */, 0xFF /* a */};
    const LampArrayColor redColor = { 0xFF /* r */, 0x0 /* g */, 0x0 /* b */, 0xFF /* a */};

    const uint32_t lampCount = lampArray->GetLampCount();

    // Set up our index and color buffers
    std::vector<uint32_t> indicesBuffer(lampCount);
    std::vector<LampArrayColor> colorsBuffer(lampCount);

    // Populate the buffers
    for (uint32_t i = 0; i < lampCount; i++)
    {
        // We will use all the Lamps for this update.
        indicesBuffer[i] = i;

        // Odd numbered indices will be red, even numbered indices will be blue
        if (i % 2 != 0)
        {
            colorsBuffer[i] = redColor;
        }
        else
        {
            colorsBuffer[i] = blueColor;
        }
    }

    // Apply the colors to the LampArray
    lampArray->SetColorsForIndices(lampCount, indicesBuffer.data(), colorsBuffer.data());
}

以下示例演示了如何更新 LampArray 上单盏灯或灯组的颜色。

void MyCustomColorUpdate(ILampArray* lampArray)
{
    const LampArrayColor greenColor = { 0x0 /* r */, 0xFF /* g */, 0x0 /* b */, 0xFF /* a */};
    const LampArrayColor yellowColor = { 0xFF /* r */, 0xFF /* g */, 0x0 /* b */, 0xFF /* a */};
    const LampArrayColor whiteColor = { 0xFF /* r */, 0xFF /* g */, 0xFF /* b */, 0xFF /* a */};

    const uint32_t lampCount = lampArray->GetLampCount();

    // Set custom colors for a single lamp at index 4
    const uint32_t index = 4;
    lampArray->SetColorsForIndices(1, &index, &greenColor);

    // Simultaneously make Lamp 1 yellow and Lamp 3 white
    std::vector<uint32_t> indicesBuffer = { 1, 3 };
    std::vector<LampArrayColor> colorsBuffer = { yellowColor, whiteColor };

    // Apply the colors to the LampArray
    lampArray->SetColorsForIndices(static_cast<uint32_t>(indicesBuffer.size()), indicesBuffer.data(), colorsBuffer.data());
}

使用键盘扫描代码定位 Lamp

ILampArray::SetColorsForScanCodes 提供了一种在 LampArray 键盘上设置特定键的 Lamp 颜色的简便方法。 这对于帮助用户在教程设置中按哪些键（例如，在键盘上显示与游戏状态相关的信息）很有用。

以下示例演示如何在 LampArray 键盘上更改 WASD 键的 Lamp 颜色：

#define SC_W    0x11
#define SC_A    0x1E
#define SC_S    0x1F
#define SC_D    0x20

void UpdateWASDKeys(ILampArray* lampArray)
{
    const LampArrayColor blueColor = { 0x0 /* r */, 0x0 /* g */, 0xFF /* b */, 0xFF /* a */};
    const LampArrayColor yellowColor = { 0xFF /* r */, 0xFF /* g */, 0x0 /* b */, 0xFF /* a */};

    // Set the color for all lamps. We will override the WASD keys below.
    lampArray->SetColor(blueColor);

    // Set up the buffer of scan codes for the Lamps we want to target
    std::vector<uint32_t> scanCodesBuffer = { SC_W, SC_A, SC_S, SC_D };

    // Create a matching buffer of LampArrayColors. In this example, we will set all of the WASD keys to yellow.
    std::vector<LampArrayColor> colorsBuffer;
    for (size_t i = 0; i < scanCodesBuffer.size(); i++)
    {
        colorsBuffer.push_back(yellowColor);
    }

    // Set the color for the WASD keys
    lampArray->SetColorsForScanCodes(static_cast<uint32_t>(scanCodesBuffer.size()), scanCodesBuffer.data(), colorsBuffer.data());
}

另请参阅

Lighting API 概述
ILampArray 参考
LampArrayColor
ILampArray::SetColor
ILampArray::SetColorsForIndices
ILampArray::SetColorsForScanCodes