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

# 在 LampArray 上設定色彩

> 在 LampArray 上設定色彩

ILampArray 上的所有色彩更新函式都使用 [LampArrayColor](/zh-TW/reference/lighting/lamparray/structs/lamparraycolor) 結構來表示 RGBA 色彩值。

Alpha 值 (LampArrayColor::a) 代表色彩的相對透明度，其中零為完全透明，0xFF 為完全不透明。如果使用 0xFF 以外的 Alpha 值，色彩會額外經過一個與黑色混合的步驟。若要避免此混合步驟，設定色彩時請勿傳遞 0xFF 以外的 Alpha 值。

ILampArray SetColor API 的設計是從單一執行緒呼叫，以獲得最佳效能及 Lamp 狀態一致性。

## 更新所有 Lamp

[ILampArray::SetColor](/zh-TW/reference/lighting/lamparray/interfaces/ilamparray/methods/ilamparray_setcolor) 方法會將裝置上的所有 Lamp 變更為所需的色彩。

下列範例會註冊 LampArray 回呼，並設定每個已連接裝置的色彩。

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

void MyLampArrayStatusCallback(
    _In_opt_ void* context,
    LampArrayStatus currentStatus,
    LampArrayStatus previousStatus,
    _In_ ILampArray* lampArray)
{
    const bool wasAttached = (previousStatus & LampArrayStatus::Connected) == LampArrayStatus::Connected;
    const bool isAttached = (currentStatus & LampArrayStatus::Connected) == LampArrayStatus::Connected;
    if (wasAttached != isAttached)
    {
        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(RegisterLampArrayStatusCallback(
        MyLampArrayStatusCallback,
        LampArrayEnumerationKind::Async,
        nullptr /* context */,
        &token)))
    {
        while (!cancelMonitoring)
        {
            Sleep(100);
        }

        UnregisterLampArrayCallback(token, 5000);
    }
}
```

## 以個別 Lamp 或 Lamp 群組為目標

[ILampArray::SetColorsForIndices](/zh-TW/reference/lighting/lamparray/interfaces/ilamparray/methods/ilamparray_setcolorsforindices) 用來更新 LampArray 的一或多個 Lamp。傳入此 API 的 Lamp 索引可以是任何順序。

下列範例說明如何在 LampArray 的所有 Lamp 上設定交替的色彩。

```cpp theme={null}
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 上個別 Lamp 或 Lamp 群組的色彩。

```cpp theme={null}
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](/zh-TW/reference/lighting/lamparray/interfaces/ilamparray/methods/ilamparray_setcolorsforscancodes) 提供簡單的方式，來設定 LampArray 鍵盤上特定按鍵的 Lamp 色彩。例如，這在教學課程情境中協助教導使用者要按哪些按鍵，或在鍵盤上顯示遊戲狀態相關資訊時很有用。

下列範例說明如何變更 LampArray 鍵盤上 WASD 鍵的 Lamp 色彩：

```cpp theme={null}
#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());
}
```

## 另請參閱

[照明 API 概觀](/zh-TW/build/core-features/common/lighting/gc-lighting-toc)
[ILampArray 參考](/zh-TW/reference/lighting/lamparray/interfaces/ilamparray/ilamparray)
[LampArrayColor](/zh-TW/reference/lighting/lamparray/structs/lamparraycolor)
[ILampArray::SetColor](/zh-TW/reference/lighting/lamparray/interfaces/ilamparray/methods/ilamparray_setcolor)
[ILampArray::SetColorsForIndices](/zh-TW/reference/lighting/lamparray/interfaces/ilamparray/methods/ilamparray_setcolorsforindices)
[ILampArray::SetColorsForScanCodes](/zh-TW/reference/lighting/lamparray/interfaces/ilamparray/methods/ilamparray_setcolorsforscancodes)


## Related topics

- [LampArrayColor 結構參考](/zh-TW/reference/lighting/lamparray/structs/lamparraycolor.md)
- [ILampArray::SetColor 方法](/zh-TW/reference/lighting/lamparray/interfaces/ilamparray/methods/ilamparray_setcolor.md)
- [ILampArray::SetColorsForIndices 方法](/zh-TW/reference/lighting/lamparray/interfaces/ilamparray/methods/ilamparray_setcolorsforindices.md)
- [ILampArray::SetColorsForScanCodes 方法](/zh-TW/reference/lighting/lamparray/interfaces/ilamparray/methods/ilamparray_setcolorsforscancodes.md)
- [XBOX 和 PC 上的照明 API 與 LampArray](/zh-TW/build/core-features/common/lighting/index.md)