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

# Dispositivos do GameInput

> Dispositivos do GameInput

<a id="introductionSection" />

Cada dispositivo de entrada físico conectado ao sistema é representado pela interface [IGameInputDevice](/pt-BR/reference/input/gameinput/interfaces/igameinputdevice/igameinputdevice). Assim como as leituras, as instâncias de dispositivo são singletons com contagem de referências, o que significa que os ponteiros de interface podem ser comparados quanto à igualdade. A maior parte do código de entrada de um aplicativo típico usa instâncias de dispositivo apenas dessa forma, como uma espécie de identificador de dispositivo ao chamar outras APIs (por exemplo, como um filtro ao recuperar leituras).

Os métodos da interface [IGameInputDevice](/pt-BR/reference/input/gameinput/interfaces/igameinputdevice/igameinputdevice) normalmente só são chamados quando um aplicativo precisa interagir diretamente com um dispositivo específico de alguma forma. O motivo mais comum é enviar comandos hápticos ou de force feedback ao dispositivo. No entanto, essa interface também expõe propriedades do dispositivo e fornece acesso à E/S de baixo nível do dispositivo, o que pode ser necessário para códigos mais avançados.

<a id="propertiesSection" />

## Propriedades do dispositivo

Os aplicativos que precisam conhecer detalhes específicos sobre um dispositivo podem acessar a estrutura [GameInputDeviceInfo](/pt-BR/reference/input/gameinput/structs/gameinputdeviceinfo) do dispositivo. Essa estrutura contém uma grande quantidade de informações sobre o dispositivo, mas há algumas coisas a entender sobre como usá-la.

As informações do dispositivo podem ser grandes - às vezes 10 KB ou mais. Por motivos de eficiência, a API GameInput não faz uma cópia dos dados do dispositivo; em vez disso, concede temporariamente aos aplicativos acesso direto aos dados armazenados internamente no GameInput. Essa abordagem favorece códigos de alto desempenho, evitando alocações de buffer e grandes transferências de memória, pois os aplicativos geralmente estão interessados apenas em uma pequena parte dos dados. Isso também permite que a estrutura [GameInputDeviceInfo](/pt-BR/reference/input/gameinput/structs/gameinputdeviceinfo) contenha ponteiros aninhados para outras regiões do bloco de dados de informações do dispositivo, onde podem ser encontradas várias matrizes de informações de suporte, sem adicionar a complexidade de saídas de tamanho variável e cópias profundas.

<a id="deviceIdsSection" />

## IDs de dispositivo

Uma informação importante disponível nas informações do dispositivo é a *ID de dispositivo local do aplicativo*. Trata-se de um valor especial de 32 bytes que identifica exclusivamente o dispositivo, mesmo entre reinicializações do aplicativo ou do sistema. Essa ID também é estável entre desconexões e reconexões de dispositivos sem fio, e de dispositivos USB com fio, desde que sejam reconectados na mesma porta USB.

A ID de dispositivo local do aplicativo é mais comumente usada para identificar dispositivos específicos além do tempo de vida do aplicativo. Por exemplo, um jogo com uma interface de mapeamento de entrada pode usar a ID do dispositivo para garantir que a configuração de entrada do usuário seja aplicada aos mesmos dispositivos sempre que o aplicativo for iniciado. Isso é especialmente importante para aplicativos que oferecem suporte a mapeamentos complexos entre vários dispositivos que, de outra forma, poderiam parecer idênticos (por exemplo, um conjunto de dispositivos de painel de instrumentos homogêneos para um simulador de voo).

<a id="enumerationSection" />

## Enumeração de dispositivos

Embora a maioria dos aplicativos nunca precise disso, o GameInput oferece suporte à enumeração explícita de dispositivos conectados. Isso pode ser feito por meio do método [RegisterDeviceCallback](/pt-BR/reference/input/gameinput/interfaces/igameinput/methods/igameinput_registerdevicecallback) da interface [IGameInput](/pt-BR/reference/input/gameinput/interfaces/igameinput/igameinput).

```c++ theme={null}
HRESULT RegisterDeviceCallback(
    _In_opt_ IGameInputDevice * device,
    _In_ GameInputKind inputKind,
    _In_ GameInputDeviceStatus statusFilter,
    _In_ GameInputEnumerationKind enumerationKind,
    _In_opt_ void * context,
    _In_ GameInputDeviceCallback callbackFunc,
    _Out_opt_ _Result_zeroonfailure_ GameInputCallbackToken * callbackToken);
```

Esse método lida tanto com a enumeração de dispositivos quanto com as notificações de conexão/desconexão de dispositivos, disparando primeiro uma série inicial de retornos de chamada para cada dispositivo conectado e, em seguida, retornos de chamada subsequentes sempre que novos dispositivos forem conectados ou desconectados. Os aplicativos podem usar o parâmetro [GameInputEnumerationKind](/pt-BR/reference/input/gameinput/enums/gameinputenumerationkind) para controlar se a função fica bloqueada até que todos os retornos de chamada iniciais tenham sido despachados ou se retorna imediatamente e os retornos de chamada são despachados de forma assíncrona.

Vários filtros estão disponíveis para controlar quais tipos de dispositivos são incluídos na enumeração e quais alterações de status do dispositivo dispararão um retorno de chamada. Para obter mais informações, consulte [RegisterDeviceCallback](/pt-BR/reference/input/gameinput/interfaces/igameinput/methods/igameinput_registerdevicecallback). Para obter informações gerais sobre como os retornos de chamada funcionam, consulte [Retornos de chamada do GameInput](/pt-BR/build/core-features/common/input/advanced/input-callbacks).

\<!-- <a id="aggregateDevicesSection" />

## Dispositivos agregados

Quando vários teclados estão conectados ao mesmo tempo, a maioria das APIs de entrada apresenta a entrada aos aplicativos de forma combinada, como se toda a entrada viesse de um único *teclado do sistema* virtual. (O mesmo também se aplica aos mouses.) O GameInput, no entanto, normalmente expõe cada dispositivo e sua entrada individualmente. Isso abre muitas possibilidades - por exemplo, poder saber qual chatpad de usuário está gerando entrada em um jogo multijogador local -, mas também adiciona muita complexidade a aplicativos que não precisam dessa funcionalidade.

Para resolver isso, o GameInput oferece suporte ao conceito de dispositivos agregados. O método [CreateAggregateDevice](/pt-BR/reference/input/gameinput/interfaces/igameinput/methods/igameinput_createaggregatedevice) da interface [IGameInput](/pt-BR/reference/input/gameinput/interfaces/igameinput/igameinput) permite que os aplicativos criem uma instância virtual de [IGameInputDevice](/pt-BR/reference/input/gameinput/interfaces/igameinputdevice/igameinputdevice) que expõe a entrada combinada de todos os dispositivos para um único [GameInputKind](/pt-BR/reference/input/gameinput/enums/gameinputkind). Esse dispositivo agregado pode então ser usado como filtro para outras funções da API GameInput para interagir com o dispositivo agregado (por exemplo, recuperar leituras). Embora isso seja mais comumente usado para entrada de teclado e mouse, também pode ser usado com a maioria dos outros tipos de entrada.

<Note>
  Na versão atual, [`CreateAggregateDevice`](/pt-BR/reference/input/gameinput/interfaces/igameinput/methods/igameinput_createaggregatedevice) ainda não está implementado. -->
</Note>

<a id="seeAlsoSection" />

## Documentação de referência da API

* [GameInput (conteúdo da API)](/pt-BR/reference/input/gameinput/gameinput_members)
  * Estruturas
    * [GameInputDeviceInfo](/pt-BR/reference/input/gameinput/structs/gameinputdeviceinfo)

## Confira também

[Conceitos básicos do GameInput](/pt-BR/build/core-features/common/input/overviews/input-fundamentals)

[Tópicos avançados do GameInput](/pt-BR/build/core-features/common/input/advanced/input-advanced-topics)

[Referência da API GameInput](/pt-BR/reference/input/gc-reference-input-toc)


## Related topics

- [GameInput](/es/reference/input/gameinput/gameinput_members.md)
- [Portabilidad de XInput a GameInput](/es/build/core-features/common/input/porting/input-porting-xinput.md)
- [Sensores en GameInput](/es/build/core-features/common/input/hardware/input-hardware-sensors.md)
- [Portabilidad de Windows.XBOX.Input a GameInput](/es/build/core-features/common/input/porting/input-porting-wxi.md)
- [Hápticos en GameInput](/es/build/core-features/common/input/hardware/input-hardware-haptics.md)