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

# Noções básicas do LampArray

> Noções básicas do LampArray

Esta página descreve como registrar retornos de chamada do `LampArray` e interagir com instâncias de `ILampArray` e `ILampInfo`.

<Note>
  A partir da recuperação de março de 2023, a API de iluminação do GDK oferece suporte apenas aos seguintes dispositivos no console. O suporte a dispositivos adicionais será incluído em versões de recuperação futuras.

  * Razer Turret for XBOX One (teclado e mouse)
  * Razer BlackWidow Tournament Edition Chroma V2
</Note>

## ILampArray e ILampInfo

Cada dispositivo de iluminação compatível conectado ao sistema é representado por uma instância de [ILampArray](/pt-BR/reference/lighting/lamparray/interfaces/ilamparray/ilamparray). `ILampArray` fornece informações sobre o dispositivo, como suas dimensões, tipo de dispositivo, fabricante e número de Lamps. Ela também expõe métodos para alterar os valores de brilho e cor de suas Lamps.

Um objeto [ILampInfo](/pt-BR/reference/lighting/lamparray/interfaces/ilampinfo/ilampinfo) encapsula as propriedades de uma Lamp individual no `LampArray`, incluindo a posição relativa da Lamp, o suporte a cores e as finalidades pretendidas. As instâncias de `ILampInfo` podem ser recuperadas usando [ILampArray::GetLampInfo](/pt-BR/reference/lighting/lamparray/interfaces/ilamparray/methods/ilamparray_getlampinfo).

Assim como as APIs de gráficos, áudio e GameInput, `ILampArray` e `ILampInfo` não são APIs COM verdadeiras, embora exponham interfaces derivadas de `IUnknown`. Esse estilo de API às vezes é chamado de "COM lite" ou "nano-COM". Embora `IUnknown` seja usado para contagem de referências e reflexão, a infraestrutura de runtime do COM não é usada por `ILampArray` nem por `ILampInfo`. Especificamente, isso significa o seguinte:

* Os aplicativos não chamam `CoInitialize` nem `CoCreateInstance` para obter instâncias de objetos.
* Recursos do COM, como agregação e implementações de interface fornecidas pelo chamador, não são suportados.
* Não há suporte a marshaling entre processos nem modelo de apartment/threading. Todos os objetos são ágeis.
* Os ponteiros de interface podem ser comparados diretamente para verificar a identidade do objeto, sem passar por `IUnknown`.
* Os métodos não precisam retornar códigos `HRESULT`, o que geralmente leva a assinaturas de função mais simples.

## Retornos de chamada do LampArray

Os retornos de chamada do `LampArray` são o mecanismo para obter instâncias de `ILampArray` e para ser notificado quando `LampArrays` são conectados ou removidos do sistema.

[RegisterLampArrayStatusCallback](/pt-BR/reference/lighting/lamparray/functions/registerlamparraystatuscallback)

<Note>
  Use a função `RegisterLampArrayStatusCallback` em vez de `RegisterLampArrayCallback` para retornos de chamada do `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 dos retornos de chamada

Se algum dispositivo `LampArray` estiver conectado no momento em que um `LampArrayStatusCallback` for registrado com `LampArrayEnumerationKind::Blocking`, a função `RegisterLampArrayStatusCallback` ficará bloqueada até que esse retorno de chamada seja invocado para cada dispositivo conectado (o que significa que o retorno de chamada será invocado no thread de chamada).

Quando o primeiro retorno de chamada é registrado, a API `LampArray` inicia um thread de trabalho para lidar com as notificações de conexão e remoção de dispositivos `ILampArray`. Esses eventos são pouco frequentes e, fora isso, o thread de trabalho permanece em estado de espera. Depois que a chamada de registro retorna, todos os `LampArrayStatusCallbacks` subsequentes serão invocados sequencialmente nesse thread de trabalho. Os dispositivos conectados no momento em que um `LampArrayStatusCallback` for registrado com `LampArrayEnumerationKind::Async` também serão tratados no thread de trabalho.

A afinidade de processador do thread de trabalho do `LampArray` pode ser controlada usando [TrySetLampArrayWorkerThreadAffinityMask](/pt-BR/reference/lighting/lamparray/functions/trysetlamparrayworkerthreadaffinitymask). Essa API pode ser chamada no máximo uma vez por processo. Quaisquer chamadas subsequentes à API não terão efeito.

```cpp theme={null}
HRESULT TrySetLampArrayWorkerThreadAffinityMask(
    uint64_t threadAffinityMask);
```

## Cancelamento do registro de retornos de chamada

Depois que um retorno de chamada é registrado com êxito, o aplicativo deve garantir que todos os recursos necessários para executar o retorno de chamada permaneçam válidos. Isso inclui tanto os recursos consumidos pelo código do retorno de chamada quanto a própria função de retorno de chamada, por exemplo, se a função de retorno de chamada estiver hospedada em uma DLL que o aplicativo carrega e descarrega sob demanda.

Para recuperar esses recursos com segurança, um aplicativo deve primeiro cancelar o registro do retorno de chamada passando o token recebido do método [RegisterLampArrayStatusCallback](/pt-BR/reference/lighting/lamparray/functions/registerlamparraystatuscallback) para o método [UnregisterLampArrayCallback](/pt-BR/reference/lighting/lamparray/functions/unregisterlamparraycallback). Não há suporte para cancelar o registro de um retorno de chamada do `LampArray` de dentro de um retorno de chamada do `LampArray` registrado, e tentar fazer isso encerrará o processo.

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

## Confira também

[Visão geral da API de iluminação](/pt-BR/build/core-features/common/lighting/gc-lighting-toc)
[Referência de ILampArray](/pt-BR/reference/lighting/lamparray/interfaces/ilamparray/ilamparray)
[Referência de ILampInfo](/pt-BR/reference/lighting/lamparray/interfaces/ilampinfo/ilampinfo)


## Related topics

- [API de iluminação e LampArray no XBOX e no PC](/pt-BR/build/core-features/common/lighting/index.md)
- [Visão geral da API de iluminação](/pt-BR/build/core-features/common/lighting/gc-lighting-toc.md)
- [Referência da API de iluminação para periféricos LampArray](/pt-BR/reference/lighting/gc-reference-lighting-toc.md)
- [Referência da função LampArrayCallback](/pt-BR/reference/lighting/lamparray/functions/lamparraycallback.md)
- [Referência da interface ILampArray](/pt-BR/reference/lighting/lamparray/interfaces/ilamparray/ilamparray.md)