Skip to main content
A maioria das APIs de entrada legadas da Microsoft é centrada em dispositivos, o que significa que o código do aplicativo deve primeiro encontrar os dispositivos de entrada aos quais oferece suporte (normalmente por meio de algum tipo de padrão de enumeração) antes que qualquer entrada possa ser lida. Para a maioria dos jogos com necessidades de entrada relativamente simples, isso adiciona muito código extra e complexidade. A API GameInput, por outro lado, é uma API centrada na entrada. Os aplicativos primeiro encontram a entrada na qual estão interessados e, em seguida, podem opcionalmente consultar o dispositivo que gerou a entrada. Isso leva a algoritmos mais naturais, o que, por sua vez, leva a um código mais simples.

​
Arquitetura do fluxo de entrada

O GameInput é construído em torno do conceito de um fluxo de entrada: a entrada de todos os dispositivos conectados ao sistema é direcionada para um único fluxo contíguo de eventos de entrada, na ordem em que a entrada ocorreu. Quando vários dispositivos geram entrada simultaneamente, isso resulta em uma intercalação natural dos eventos de entrada. Veja a seguir um exemplo de fluxo de entrada de vários dispositivos de entrada. Exemplo de fluxo de entrada de vários dispositivos de entrada Neste exemplo, quatro dispositivos estão enviando entradas simultaneamente. O número de cada quadrado representa a ordem em que a entrada foi enviada, e a cor representa qual dispositivo enviou a entrada. Portanto, neste exemplo, o primeiro gamepad envia a primeira entrada, o teclado envia a segunda entrada, o mouse envia a terceira entrada e o segundo gamepad envia a quarta entrada. Cada elemento no fluxo de entrada é representado por uma “leitura”. Os aplicativos começam obtendo a leitura mais atual do fluxo de entrada. A partir daí, o aplicativo pode continuar obtendo periodicamente a leitura mais atual ou pode avançar e retroceder pelo fluxo de entrada, examinando leituras adjacentes. Em ambos os casos, o aplicativo normalmente compara as diferenças entre as leituras de interesse e, em seguida, executa a ação apropriada. Por exemplo, um jogo de tiro em primeira pessoa talvez só precise saber se um botão está pressionado no início de cada quadro para determinar se a arma do jogador deve disparar. Nesse caso, apenas a leitura mais atual importa (e quaisquer leituras intermediárias podem ser ignoradas). Por outro lado, um jogo de luta competitivo pode querer examinar cada alteração de estado de entrada que ocorreu entre o último quadro e o atual por qualquer um dos motivos a seguir.
  • Tocar duas vezes em um botão pode ser mapeado para um combo/movimento diferente de um único toque.
  • A ordem em que dois botões foram pressionados pode importar.
  • O tempo decorrido entre dois pressionamentos de botão pode importar.
Ao recuperar leituras do fluxo de entrada, os aplicativos podem aplicar filtros opcionais, que limitam os resultados a leituras de tipos de entrada específicos (como gamepads ou teclados) e/ou de um dispositivo específico. Para obter mais detalhes, confira Leituras do GameInput. Os aplicativos só podem solicitar leituras históricas do fluxo de entrada que ocorreram no último meio segundo. A leitura mais atual de cada dispositivo conectado está sempre acessível, independentemente de quão antiga ela seja.

​
Interfaces

A API GameInput é exposta por meio de uma coleção de interfaces relacionadas, de forma semelhante às APIs de gráficos e áudio, conforme mostrado no diagrama a seguir. Um diagrama da API GameInput exposta por meio de uma coleção de interfaces relacionadas Há três interfaces principais que compõem a maior parte da superfície da API GameInput.
  • IGameInput é a interface base obtida chamando a função de fábrica GameInputCreate. Ela contém métodos para recuperar leituras do fluxo de entrada, registrar retornos de chamada e acessar outras funcionalidades globais.
  • IGameInputReading representa um único elemento no fluxo de entrada. Ela contém métodos para recuperar os dados de estado de entrada armazenados na leitura e para acessar o dispositivo que gerou a leitura. As leituras também são usadas como pontos de referência dentro do fluxo de entrada, ao avançar e retroceder pelas outras leituras do fluxo.
  • IGameInputDevice representa um único dispositivo de entrada conectado ao sistema. Ela contém métodos para recuperar as propriedades e o estado atual do dispositivo, além de métodos para controlar a resposta háptica e de força no dispositivo. Também contém métodos para executar E/S bruta de baixo nível no dispositivo.
As interfaces restantes são usadas em contextos específicos, que são discutidos na seção Tópicos avançados do GameInput.
Assim como as APIs de gráficos e áudio, o GameInput não é uma API COM verdadeira, embora exponha 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 pelo GameInput. 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.

​
Foco do aplicativo

No console, o GameInput fornece entrada a um aplicativo somente quando ele está em foco. Caso contrário, o estado retornado contém valores neutros ou de “repouso”, como se o usuário não estivesse tocando no dispositivo. Isso elimina a necessidade de código de entrada extra para lidar com a mudança de foco. No PC, por padrão, a entrada (incluindo os botões do sistema) vai para os aplicativos em foco. Esse comportamento pode ser alterado usando o método SetFocusPolicy. Qualquer resposta háptica ou de força enviada a um dispositivo é desabilitada quando um aplicativo perde o foco. Ele ainda pode chamar as APIs do GameInput para definir um novo estado de resposta, mas o novo estado não será enviado ao dispositivo. Quando o aplicativo estiver em foco novamente, o estado de resposta mais recente solicitado pelo aplicativo será enviado automaticamente ao dispositivo. Como resultado, os aplicativos não precisam executar nenhuma ação especial relacionada à entrada ou à resposta háptica/de força quando ganham e perdem o foco. A API GameInput sempre faz a coisa certa em nome deles.

​
Documentação de referência da API

​
Confira também

Leituras do GameInput Dispositivos do GameInput Tópicos avançados do GameInput Referência da API GameInput
Last modified on October 6, 2026