> ## 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.

# Notions de base de LampArray

> Notions de base de LampArray

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

<Note>
  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
</Note>

## ILampArray et ILampInfo

Chaque périphérique d'éclairage compatible connecté au système est représenté par une instance [ILampArray](/fr-CA/reference/lighting/lamparray/interfaces/ilamparray/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](/fr-CA/reference/lighting/lamparray/interfaces/ilampinfo/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](/fr-CA/reference/lighting/lamparray/interfaces/ilamparray/methods/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](/fr-CA/reference/lighting/lamparray/functions/registerlamparraystatuscallback)

<Note>
  Utilisez la fonction `RegisterLampArrayStatusCallback` plutôt que `RegisterLampArrayCallback` pour les rappels `LampArray`.
</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);

```

## 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](/fr-CA/reference/lighting/lamparray/functions/trysetlamparrayworkerthreadaffinitymask). Cette API peut être appelée au plus une fois par processus. Tout appel subséquent à l'API n'aura aucun effet.

```cpp theme={null}
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](/fr-CA/reference/lighting/lamparray/functions/registerlamparraystatuscallback) à la méthode [UnregisterLampArrayCallback](/fr-CA/reference/lighting/lamparray/functions/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.

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

## Voir aussi

[Vue d'ensemble de l'API d'éclairage](/fr-CA/build/core-features/common/lighting/gc-lighting-toc)
[Référence d'ILampArray](/fr-CA/reference/lighting/lamparray/interfaces/ilamparray/ilamparray)
[Référence d'ILampInfo](/fr-CA/reference/lighting/lamparray/interfaces/ilampinfo/ilampinfo)


## Related topics

- [Referencia de la enumeración LampArrayKind](/es/reference/lighting/lamparray/enums/lamparraykind.md)
- [Efectos de LampArray](/es/build/core-features/common/lighting/lighting-effects.md)
- [Referencia de miembros de la API LampArray](/es/reference/lighting/lamparray/lamparray_members.md)
- [Establecimiento de colores en un LampArray](/es/build/core-features/common/lighting/lighting-colors.md)
- [API de iluminación y LampArray en XBOX y PC](/es/build/core-features/common/lighting/index.md)