LampArray の基本
このページでは、LampArray コールバックを登録し、ILampArray および ILampInfo インスタンスとやり取りする方法について説明します。
ご注意ください: 2023 年 3 月の復旧時点では、GDK Lighting API はコンソールで次のデバイスのみをサポートしています。 今後のリカバリ リリースでは、追加のデバイスのサポートが追加される予定です。
- Xbox One 用 Razer Turret (キーボードとマウス)
- Razer BlackWidow Tournament Edition Chroma V2
ILampArray と ILampInfo
システムに接続された互換性のある各照明デバイスは、ILampArray インスタンスによって表されます。 ILampArray は、寸法、デバイスの種類、製造元、ランプの数など、デバイスに関する情報を提供します。 また、ランプの明るさと色の値を変更するメソッドも公開します。
ILampInfo オブジェクトは、LampArray 内の個々の Lamp のプロパティをカプセル化します。これには、Lamp の相対位置、色のサポート、使用目的が含まれます。 ILampInfo インスタンスは、ILampArray::GetLampInfo を使用して取得できます。
注: グラフィック、オーディオ、GameInput API と同様に、ILampArray と ILampInfo は、IUnknown から派生したインターフェイスを公開していますが、真の COM API ではありません。 このスタイルの API は "COM ライト" や "ナノ COM" と呼ばれることもあります。IUnknown は参照カウントとリフレクションに使用されていますが、COM ランタイム インフラストラクチャは ILampArray または ILampInfo には使用されていません。 具体的には、次のことを意味します。
- アプリケーションは、オブジェクトのインスタンスを取得するために
CoInitializeもCoCreateInstanceも呼び出すことはありません。- 集約や呼び出し元提供のインターフェイスの実装などの COM 機能はサポートされません。
- プロセスの境界を越えたマーシャリングはサポートされず、またアパートメント/スレッド モデルはありません。 すべてのオブジェクトはアジャイルです。
- IUnknown を介さずにインターフェイス ポインターのオブジェクト ID を直接比較できます。
- メソッドでは
HRESULTコードを返す必要はありません。多くの場合、これによって関数シグネチャが単純になります。
LampArray コールバック
LampArray コールバックは、ILampArray インスタンスを取得し、LampArray がシステムにアタッチまたはシステムから削除されたときに通知されるメカニズムです。
typedef interface ILampArray ILampArray;
typedef uint64_t LampArrayCallbackToken;
typedef void (CALLBACK * LampArrayCallback)(
_In_opt_ void * context,
bool isAttached,
_In_ ILampArray * lampArray);
HRESULT RegisterLampArrayCallback(
_In_ LampArrayCallback lampArrayCallback,
_In_opt_ void* context,
_Out_ _Result_zeroonfailure_ LampArrayCallbackToken* callbackToken);
コールバックのスレッド化
コールバックの登録時に LampArray デバイスがアタッチされている場合、RegisterLampArrayCallback 関数は、アタッチされたデバイスごとにコールバックが呼び出されるまでブロックされます (つまり、コールバックは呼び出し元のスレッドで呼び出されます)。
最初のコールバックが登録されると、LampArray API は、ILampArray デバイスのアタッチと削除の通知を処理するワーカー スレッドを開始します。 これらのイベントは頻度が低く、それ以外の場合、ワーカー スレッドは待機状態のままです。 登録呼び出しが返されると、後続のすべての LampArrayCallbacks がこのワーカー スレッドで順番に呼び出されます。
TrySetLampArrayWorkerThreadAffinityMask を使用して、LampArray ワーカー スレッドのプロセッサ アフィニティを制御できます。 この API は、プロセスごとに最大 1 回呼び出すことができます。 API への後続の呼び出しは有効になりません。
HRESULT TrySetLampArrayWorkerThreadAffinityMask(
uint64_t threadAffinityMask);
コールバックの登録解除
コールバックが正常に登録されたら、アプリケーションでは、コールバックの実行に必要なすべてのリソースが有効な状態を維持することを保証する必要があります。 これには、コールバックのコードによって使用されるリソースと、コールバック関数自体によって使用されるリソース (たとえば、アプリケーションがオンデマンドでロード/アンロードする DLL でコールバック関数がホストされている場合) の両方が含まれます。
これらのリソースを安全に再利用するには、アプリケーションはまず、RegisterLampArrayCallback メソッドから受け取ったトークンを UnregisterLampArrayCallback メソッドに渡すことによって、コールバックを登録解除する必要があります。 登録済みの LampArray コールバック内からの LampArray コールバックの登録解除はサポートされていません。そうしようとすると、プロセスが終了します。
bool UnregisterLampArrayCallback(
LampArrayCallbackToken callbackToken,
uint64_t timeoutInMicroseconds);