Notions de base sur LampArray

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

Depuis la mise à jour 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 d’autres périphériques 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 également 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 du LampArray, notamment sa position relative, sa prise en charge des couleurs et ses usages prévus. 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 comptage de références et la réflexion, l’infrastructure du runtime COM n’est pas utilisée par ILampArray ni par ILampInfo. Concrètement, cela signifie ce qui suit :

Les applications n’appellent ni CoInitialize ni CoCreateInstance pour obtenir des instances d’objets.
Les fonctionnalités COM telles que l’agrégation et les implémentations d’interfaces fournies par l’appelant ne sont pas prises en charge.
Il n’y a pas de prise en charge du marshaling interprocessus, 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 conduit 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 averti lorsque des LampArrays sont connectés au système ou en sont retirés. 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 reste bloquée jusqu’à ce que ce rappel soit appelé pour chaque périphérique connecté (ce qui signifie que le rappel est appelé sur le thread appelant). Lorsque le premier rappel est inscrit, l’API LampArray démarre un thread de travail chargé de 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 reste le reste du temps en état d’attente. Une fois l’appel d’inscription retourné, tous les LampArrayStatusCallbacks suivants sont appelés séquentiellement sur ce thread de travail. Les périphériques connectés au moment où un LampArrayStatusCallback est inscrit avec LampArrayEnumerationKind::Async sont également gérés sur le thread de travail. L’affinité processeur du thread de travail LampArray peut être contrôlée à l’aide de TrySetLampArrayWorkerThreadAffinityMask. Cette API ne peut être appelée qu’une seule fois par processus. Les appels ultérieurs à l’API n’ont aucun effet.

HRESULT TrySetLampArrayWorkerThreadAffinityMask(
    uint64_t threadAffinityMask);

Désinscription des rappels

Une fois qu’un rappel a été inscrit avec succès, l’application doit garantir que toutes les ressources nécessaires à l’exécution du rappel restent valides. Cela inclut à 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 transmettant le jeton reçu de la méthode RegisterLampArrayStatusCallback à la méthode UnregisterLampArrayCallback. La désinscription d’un rappel LampArray depuis un rappel LampArray inscrit n’est pas prise en charge, et toute tentative en ce sens met 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