Notions de base de LampArray

Cette page décrit comment inscrire des rappels LampArray et interagir avec les instances ILampArray et ILampInfo.

Depuis la version de récupération de mars 2023, l’API d’éclairage du GDK ne prend en charge que les périphériques suivants sur console. La prise en charge de périphériques supplémentaires sera ajoutée dans de futures versions de récupération.

Razer Turret pour XBOX One (clavier et souris)
Razer BlackWidow Tournament Edition Chroma V2

ILampArray et ILampInfo

Chaque périphérique d’éclairage compatible connecté au système est représenté par une instance ILampArray. ILampArray fournit des informations sur le périphérique, comme ses dimensions, son type, son fabricant et son nombre de Lamps. Elle expose aussi des méthodes permettant de modifier les valeurs de luminosité et de couleur de ses Lamps. Un objet ILampInfo encapsule les propriétés d’une Lamp individuelle de la LampArray, notamment la position relative de la Lamp, sa prise en charge des couleurs et ses utilisations prévues. Les instances ILampInfo peuvent être récupérées à l’aide de ILampArray::GetLampInfo. Comme les API graphiques, audio et GameInput, ILampArray et ILampInfo ne sont pas de véritables API COM, même si elles exposent des interfaces dérivées de IUnknown. Ce style d’API est parfois appelé « COM lite » ou « nano-COM ». Bien que IUnknown soit utilisé pour le décompte de références et la réflexion, l’infrastructure du runtime COM n’est pas utilisée par ILampArray ni par ILampInfo. Plus précisément, cela signifie ce qui suit :

Les applications n’appellent ni CoInitialize ni CoCreateInstance pour obtenir des instances d’objets.
Les fonctionnalités COM comme l’agrégation et les implémentations d’interfaces fournies par l’appelant ne sont pas prises en charge.
Il n’y a aucune prise en charge du marshaling entre processus, ni de modèle d’apartment ou de threading. Tous les objets sont agiles.
Les pointeurs d’interface peuvent être comparés directement pour déterminer l’identité des objets, sans passer par IUnknown.
Les méthodes ne sont pas tenues de retourner des codes HRESULT, ce qui mène souvent à des signatures de fonctions plus simples.

Rappels LampArray

Les rappels LampArray constituent le mécanisme permettant d’obtenir des instances ILampArray et d’être avisé lorsque des LampArrays sont connectées au système ou retirées de celui-ci. RegisterLampArrayStatusCallback

Utilisez la fonction RegisterLampArrayStatusCallback plutôt que RegisterLampArrayCallback pour les rappels LampArray.

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);

Threading des rappels

Si des périphériques LampArray sont connectés au moment où un LampArrayStatusCallback est inscrit avec LampArrayEnumerationKind::Blocking, la fonction RegisterLampArrayStatusCallback bloquera jusqu’à ce que ce rappel soit invoqué pour chaque périphérique connecté (ce qui signifie que le rappel sera invoqué sur le thread appelant). Lorsque le premier rappel est inscrit, l’API LampArray démarre un thread de travail pour gérer les notifications de connexion et de retrait des périphériques ILampArray. Ces événements sont peu fréquents, et le thread de travail demeure autrement en état d’attente. Une fois l’appel d’inscription retourné, tous les LampArrayStatusCallbacks subséquents seront invoqués de façon séquentielle sur ce thread de travail. Les périphériques connectés au moment où un LampArrayStatusCallback est inscrit avec LampArrayEnumerationKind::Async seront aussi gérés sur le thread de travail. L’affinité de processeur du thread de travail LampArray peut être contrôlée à l’aide de TrySetLampArrayWorkerThreadAffinityMask. Cette API peut être appelée au plus une fois par processus. Tout appel subséquent à l’API n’aura aucun effet.

HRESULT TrySetLampArrayWorkerThreadAffinityMask(
    uint64_t threadAffinityMask);

Désinscription des rappels

Une fois qu’un rappel est inscrit avec succès, l’application doit garantir que toutes les ressources nécessaires à l’exécution du rappel demeurent valides. Cela comprend à la fois les ressources consommées par le code du rappel et la fonction de rappel elle-même, par exemple si la fonction de rappel est hébergée dans une DLL que l’application charge et décharge à la demande. Pour récupérer ces ressources en toute sécurité, une application doit d’abord désinscrire le rappel en passant le jeton reçu de la méthode RegisterLampArrayStatusCallback à la méthode UnregisterLampArrayCallback. La désinscription d’un rappel LampArray à partir d’un rappel LampArray inscrit n’est pas prise en charge, et toute tentative en ce sens mettra fin au processus.

bool UnregisterLampArrayCallback(
    LampArrayCallbackToken callbackToken,
    uint64_t timeoutInMicroseconds);

Voir aussi

Vue d’ensemble de l’API d’éclairage Référence d’ILampArray Référence d’ILampInfo

Introduction

Onboarding & Access

Setup & Install

Build Your First Title

ILampArray et ILampInfo

Rappels LampArray

Threading des rappels

Désinscription des rappels

Voir aussi

​ILampArray et ILampInfo

​Rappels LampArray

​Threading des rappels

​Désinscription des rappels

​Voir aussi

ILampArray et ILampInfo

Rappels LampArray

Threading des rappels

Désinscription des rappels

Voir aussi