> ## 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 sur LampArray

> Notions de base sur LampArray

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

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

## ILampArray et ILampInfo

Chaque périphérique d'éclairage compatible connecté au système est représenté par une instance [ILampArray](/fr/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 également des méthodes permettant de modifier les valeurs de luminosité et de couleur de ses Lamps.

Un objet [ILampInfo](/fr/reference/lighting/lamparray/interfaces/ilampinfo/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](/fr/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 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](/fr/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` 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](/fr/reference/lighting/lamparray/functions/trysetlamparrayworkerthreadaffinitymask). Cette API ne peut être appelée qu'une seule fois par processus. Les appels ultérieurs à l'API n'ont aucun effet.

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

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

## Voir aussi

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


## Related topics

- [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)
- [Referencia de la API de iluminación para periféricos LampArray](/es/reference/lighting/gc-reference-lighting-toc.md)