通过

LampArray 基础知识

本页介绍如何注册LampArray回调并与 和 ILampInfo 实例交互ILampArray。

注意

自 2023 年 3 月恢复起，GDK 照明 API 仅支持主机上的以下设备。 将来的恢复版本会添加对其他设备的支持。

  • 适用于 Xbox One 的 Razer Turret（键盘和鼠标）
  • Razer BlackWidow Tournament Edition Chroma V2

ILampArray 和 ILampInfo

连接到系统的每个兼容照明设备都由一个 ILampArray 实例表示。 ILampArray 提供有关设备的信息，例如其尺寸、设备类型、制造商和灯的数量。 它还公开了更改其 Lamp 的亮度和颜色值的方法。

ILampInfo 对象将单个 Lamp 的属性封装在 中LampArray，包括灯的相对位置、颜色支持和预期目的。 ILampInfo 可以使用 ILampArray：：GetLampInfo 检索实例。

与图形、音频和 GameInput API 类似， ILampArray 它们 ILampInfo 不是真正的 COM API，即使它们公开了派生自 IUnknown的接口。 这种 API 样式有时称为“COM lite”或“nano-COM”。虽然 IUnknown 用于引用计数和反射，但 COM 运行时基础结构不由 ILampArray 或 ILampInfo使用。 具体是指以下方面：

  • 应用程序既不调用 CoInitialize 也不调用 CoCreateInstance 来获取对象实例。
  • 不支持聚合之类的 COM 功能以及调用方提供的接口实现。
  • 没有跨进程封送支持，也没有单元/线程模型。 所有对象都是敏捷对象。
  • 可以直接比较对象标识的接口指针，而无需通过 IUnknown。
  • 不要求方法返回 HRESULT 代码，这常常会导致更简单的函数签名。

LampArray 回调

LampArray callbacks 是一种机制，用于获取 ILampArray 实例，并在系统附加或删除时 LampArrays 收到通知。

RegisterLampArrayStatusCallback

注意

RegisterLampArrayStatusCallback对回调使用 函数而不是 RegisterLampArrayCallbackLampArray 。

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函数将阻塞，直到为每个附加设备调用该回调 (这意味着将在调用线程) 调用回调。

注册第一个回调后，API 会 LampArray 启动一个工作线程来处理 ILampArray 设备附加和删除通知。 这些事件很少发生，否则工作线程将保持等待状态。 注册调用返回后，将在此工作线程上按顺序调用所有后续 LampArrayStatusCallbacks 调用。 在注册 LampArrayEnumerationKind::Async 时LampArrayStatusCallback连接的设备也将在工作线程上进行处理。

可以使用 TrySetLampArrayWorkerThreadAffinityMask 控制工作线程的LampArray处理器相关性。 每个进程最多可以调用一次此 API。 对 API 的任何后续调用都不会生效。

HRESULT TrySetLampArrayWorkerThreadAffinityMask(
    uint64_t threadAffinityMask);

注销回调

在成功注册某一回调后，应用程序必须确保执行该回调所需的任何资源仍然有效。 这包括回调代码占用的资源以及回调函数本身，例如，如果回调函数托管在应用程序按需加载和卸载的 DLL 中。

若要安全地回收这些资源，应用程序必须先取消注册回调，方法是将从 RegisterLampArrayStatusCallback 方法收到的令牌传递到 UnregisterLampArrayCallback 方法。 不支持从已注册LampArray回调内部取消注册LampArray回调，并且尝试这样做将终止进程。

bool UnregisterLampArrayCallback(
    LampArrayCallbackToken callbackToken,
    uint64_t timeoutInMicroseconds);

另请参阅

Lighting API 概述
ILampArray 参考
ILampInfo 参考

  • Last updated on