LampArray의 색상 설정 - XBOX Game Development Documentation

ILampArray의 모든 색상 업데이트 함수는 RGBA 색상 값을 나타내기 위해 LampArrayColor 구조체를 사용합니다. 알파 값(LampArrayColor::a)은 색상의 상대적 투명도를 나타내며, 0은 완전히 투명하고 0xFF는 완전히 불투명한 상태입니다. 0xFF가 아닌 알파 값을 사용하면 색상은 검정색과의 추가 블렌딩 단계를 거치게 됩니다. 이 블렌딩 단계를 피하려면 색상을 설정할 때 0xFF 이외의 알파 값을 전달하지 마세요. ILampArray의 SetColor API는 최상의 성능과 Lamp 상태 일관성을 위해 단일 스레드에서 호출되도록 설계되었습니다.

모든 Lamp 업데이트

ILampArray::SetColor 메서드는 장치의 모든 Lamp를 원하는 색상으로 변경합니다. 다음 예제는 LampArray 콜백을 등록하고 연결된 각 장치의 색상을 설정합니다.

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는 LampArray의 하나 이상의 Lamp를 업데이트하는 데 사용됩니다. 이 API에 전달되는 Lamp 인덱스는 순서에 상관없이 입력할 수 있습니다. 다음 예제는 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의 개별 Lamp 또는 Lamp 그룹에 대한 색상을 업데이트하는 방법을 보여줍니다.

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

마지막 수정일 2026년 8월 7일

관련 항목

LampArrayColor XBOX 및 PC의 조명 API와 LampArray ILampArray::SetColor ILampArray::SetColorsForIndices ILampArray::SetColorsForScanCodes

⌘I