> ## 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 基本概念

本頁說明如何註冊 `LampArray` 回呼，以及如何與 `ILampArray` 和 `ILampInfo` 執行個體互動。

<Note>
  截至 2023 年 3 月復原版本，GDK 照明 API 在主機上僅支援下列裝置。未來的復原版本將會新增對其他裝置的支援。

  * Razer Turret for XBOX One (鍵盤和滑鼠)
  * Razer BlackWidow Tournament Edition Chroma V2
</Note>

## ILampArray 和 ILampInfo

連線至系統的每個相容照明裝置都以 [ILampArray](/zh-TW/reference/lighting/lamparray/interfaces/ilamparray/ilamparray) 執行個體表示。`ILampArray` 提供裝置的相關資訊，例如其尺寸、裝置類型、製造商和 Lamp 數目。它也會公開變更其 Lamp 亮度和色彩值的方法。

[ILampInfo](/zh-TW/reference/lighting/lamparray/interfaces/ilampinfo/ilampinfo) 物件封裝 `LampArray` 中個別 Lamp 的屬性，包括 Lamp 的相對位置、色彩支援和預期用途。可以使用 [ILampArray::GetLampInfo](/zh-TW/reference/lighting/lamparray/interfaces/ilamparray/methods/ilamparray_getlampinfo) 擷取 `ILampInfo` 執行個體。

與圖形、音訊和 GameInput API 一樣，`ILampArray` 和 `ILampInfo` 不是真正的 COM API，即使它們公開衍生自 `IUnknown` 的介面。這種 API 樣式有時稱為「COM lite」或「nano-COM」。雖然 `IUnknown` 用於參考計數和反映，但 `ILampArray` 和 `ILampInfo` 不會使用 COM 執行階段基礎結構。具體而言，這表示下列事項：

* 應用程式不會呼叫 `CoInitialize` 或 `CoCreateInstance` 來取得物件執行個體。
* 不支援彙總和呼叫端提供的介面實作等 COM 功能。
* 沒有跨處理序封送處理支援，也沒有 Apartment/執行緒模型。所有物件都是 Agile 物件。
* 可以直接比較介面指標以判斷物件身分識別，而不需透過 `IUnknown`。
* 方法不需要傳回 `HRESULT` 代碼，這通常會產生更簡單的函式簽章。

## LampArray 回呼

`LampArray` 回呼是取得 `ILampArray` 執行個體，以及在 `LampArrays` 連接至系統或從系統移除時收到通知的機制。

[RegisterLampArrayStatusCallback](/zh-TW/reference/lighting/lamparray/functions/registerlamparraystatuscallback)

<Note>
  針對 `LampArray` 回呼，請使用 `RegisterLampArrayStatusCallback` 函式，而非 `RegisterLampArrayCallback`。
</Note>

```cpp theme={null}
enum class LampArrayEnumerationKind : uint32_t
{
    Async       = 1,
    Blocking    = 2
};

enum class LampArrayStatus : uint32_t
{
    None            = 0x00000000,
    Connected       = 0x00000001,
    Available       = 0x00000002
};

DEFINE_ENUM_FLAG_OPERATORS(LampArrayStatus);

typedef interface ILampArray ILampArray;

typedef uint64_t LampArrayCallbackToken;

typedef void (CALLBACK * LampArrayStatusCallback)(
    _In_opt_ void * context,
    LampArrayStatus currentStatus,
    LampArrayStatus previousStatus,
    _In_ ILampArray * lampArray);

STDAPI RegisterLampArrayStatusCallback(
    _In_ LampArrayStatusCallback callbackFunc,
    LampArrayEnumerationKind enumerationKind,
    _In_opt_ void * context,
    _Out_ _Result_zeroonfailure_ LampArrayCallbackToken * callbackToken);

```

## 回呼執行緒

如果在以 `LampArrayEnumerationKind::Blocking` 註冊 `LampArrayStatusCallback` 時已連接任何 `LampArray` 裝置，`RegisterLampArrayStatusCallback` 函式將會封鎖，直到針對每個已連接的裝置叫用該回呼為止 (這表示回呼會在呼叫執行緒上叫用)。

註冊第一個回呼時，`LampArray` API 會啟動背景工作執行緒，以處理 `ILampArray` 裝置連接和移除通知。這些事件並不常發生，背景工作執行緒在其他時候會維持等候狀態。註冊呼叫傳回後，所有後續的 `LampArrayStatusCallbacks` 都會在此背景工作執行緒上依序叫用。在以 `LampArrayEnumerationKind::Async` 註冊 `LampArrayStatusCallback` 時已連線的裝置，也會在背景工作執行緒上處理。

可以使用 [TrySetLampArrayWorkerThreadAffinityMask](/zh-TW/reference/lighting/lamparray/functions/trysetlamparrayworkerthreadaffinitymask) 控制 `LampArray` 背景工作執行緒的處理器親和性。每個處理序最多只能呼叫此 API 一次。對此 API 的任何後續呼叫都不會生效。

```cpp theme={null}
HRESULT TrySetLampArrayWorkerThreadAffinityMask(
    uint64_t threadAffinityMask);
```

## 取消註冊回呼

成功註冊回呼之後，應用程式必須保證執行回呼所需的任何資源都保持有效。這包括回呼程式碼所使用的資源，以及回呼函式本身，例如，如果回呼函式裝載於應用程式視需要載入和卸載的 DLL 中。

若要安全地回收這些資源，應用程式必須先將從 [RegisterLampArrayStatusCallback](/zh-TW/reference/lighting/lamparray/functions/registerlamparraystatuscallback) 方法收到的權杖傳遞至 [UnregisterLampArrayCallback](/zh-TW/reference/lighting/lamparray/functions/unregisterlamparraycallback) 方法，以取消註冊回呼。不支援從已註冊的 `LampArray` 回呼內部取消註冊 `LampArray` 回呼，嘗試這麼做將會終止處理序。

```cpp theme={null}
bool UnregisterLampArrayCallback(
    LampArrayCallbackToken callbackToken,
    uint64_t timeoutInMicroseconds);
```

## 另請參閱

[照明 API 概觀](/zh-TW/build/core-features/common/lighting/gc-lighting-toc)
[ILampArray 參考](/zh-TW/reference/lighting/lamparray/interfaces/ilamparray/ilamparray)
[ILampInfo 參考](/zh-TW/reference/lighting/lamparray/interfaces/ilampinfo/ilampinfo)


## Related topics

- [TrySetLampArrayWorkerThreadAffinityMask 參考](/zh-TW/reference/lighting/lamparray/functions/trysetlamparrayworkerthreadaffinitymask.md)
- [XBOX 和 PC 上的照明 API 與 LampArray](/zh-TW/build/core-features/common/lighting/index.md)
- [照明 API 概觀](/zh-TW/build/core-features/common/lighting/gc-lighting-toc.md)
- [LampArray 周邊裝置的燈光 API 參考](/zh-TW/reference/lighting/gc-reference-lighting-toc.md)
- [ILampArray 介面參考](/zh-TW/reference/lighting/lamparray/interfaces/ilamparray/ilamparray.md)