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.

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

ILampArray e ILampInfo

Cada dispositivo de iluminação compatível conectado ao sistema é representado por uma instância de 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 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. 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

Use a função RegisterLampArrayStatusCallback em vez de RegisterLampArrayCallback para retornos de chamada do 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 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. Essa API pode ser chamada no máximo uma vez por processo. Quaisquer chamadas subsequentes à API não terão efeito.

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 para o método 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.

bool UnregisterLampArrayCallback(
    LampArrayCallbackToken callbackToken,
    uint64_t timeoutInMicroseconds);

Confira também

Visão geral da API de iluminação Referência de ILampArray Referência de ILampInfo

Porting

Build Paths

ILampArray e ILampInfo

Retornos de chamada do LampArray

Threading dos retornos de chamada

Cancelamento do registro de retornos de chamada

Confira também

​ILampArray e ILampInfo

​Retornos de chamada do LampArray

​Threading dos retornos de chamada

​Cancelamento do registro de retornos de chamada

​Confira também

ILampArray e ILampInfo

Retornos de chamada do LampArray

Threading dos retornos de chamada

Cancelamento do registro de retornos de chamada

Confira também