> ## 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. # Leituras do GameInput > Leituras do GameInput Os pacotes de entrada brutos recebidos de cada dispositivo são encapsulados em objetos de "leitura". As leituras contêm os dados originais do pacote bruto e (geralmente) uma ou mais transformações dos dados brutos em formatos de nível mais alto. Além de sua função como contêineres de dados, as leituras também servem como identificadores que fazem referência a uma posição específica dentro do fluxo de entrada. ## Obtenção de leituras A API GameInput oferece duas maneiras de obter leituras. A maneira mais comum é acessá-las diretamente do fluxo de entrada, por meio de métodos da interface [IGameInput](/pt-BR/reference/input/gameinput/interfaces/igameinput/igameinput). ```c++ theme={null} HRESULT GetCurrentReading( _In_ GameInputKind inputKind, _In_opt_ IGameInputDevice * device, _COM_Outptr_ IGameInputReading ** reading); ``` Chamar [GetCurrentReading](/pt-BR/reference/input/gameinput/interfaces/igameinput/methods/igameinput_getcurrentreading) recupera a leitura mais recente do fluxo de entrada. Um filtro [GameInputKind](/pt-BR/reference/input/gameinput/enums/gameinputkind) opcional pode ser passado para limitar as leituras retornadas a tipos específicos de entrada, como gamepad ou teclado. Um filtro [IGameInputDevice](/pt-BR/reference/input/gameinput/interfaces/igameinputdevice/igameinputdevice) opcional também pode ser passado para limitar as leituras retornadas apenas àquelas geradas pelo dispositivo especificado. Esses filtros podem ser aplicados individualmente ou em conjunto. As instâncias de [IGameInputReading](/pt-BR/reference/input/gameinput/interfaces/igameinputreading/igameinputreading) são singletons com contagem de referências. Recuperar uma leitura é uma operação extremamente rápida e leve: nenhuma alocação ou cópia de memória é realizada, e a chamada de API é livre de bloqueio, sem transições para o modo kernel. Como as leituras são singletons, um aplicativo pode comparar os ponteiros de leitura quanto à igualdade para saber se duas chamadas a [GetCurrentReading](/pt-BR/reference/input/gameinput/interfaces/igameinput/methods/igameinput_getcurrentreading) retornaram a mesma leitura (o que significa que nenhuma nova entrada foi gerada). Jogos com necessidades de entrada menos complexas podem simplesmente sondar novas entradas uma vez por quadro e comparar o estado armazenado nas duas leituras em busca de diferenças (se não forem a mesma leitura). Jogos com necessidades de entrada mais complexas, no entanto, podem precisar percorrer o fluxo de entrada para obter uma visão completa de todas as alterações de estado de entrada que ocorreram desde o quadro anterior. Isso é possível com os métodos [GetNextReading](/pt-BR/reference/input/gameinput/interfaces/igameinput/methods/igameinput_getnextreading) e [GetPreviousReading](/pt-BR/reference/input/gameinput/interfaces/igameinput/methods/igameinput_getpreviousreading), que permitem os mesmos filtros que [GetCurrentReading](/pt-BR/reference/input/gameinput/interfaces/igameinput/methods/igameinput_getcurrentreading). O fluxo de entrada mantém o último meio segundo de leituras históricas em seu buffer. ```c++ theme={null} HRESULT GetNextReading( _In_ IGameInputReading * referenceReading, _In_ GameInputKind inputKind, _In_opt_ IGameInputDevice * device, _COM_Outptr_ IGameInputReading ** reading); HRESULT GetPreviousReading( _In_ IGameInputReading * referenceReading, _In_ GameInputKind inputKind, _In_opt_ IGameInputDevice * device, _COM_Outptr_ IGameInputReading ** reading); ``` Como alternativa, os aplicativos podem registrar um retorno de chamada que é invocado sempre que uma entrada é gerada. Assim como nos métodos síncronos anteriores, vários filtros podem ser aplicados para controlar quais tipos de leitura são retornados e de quais dispositivos. Para obter mais informações, confira [Retornos de chamada do GameInput](/pt-BR/build/core-features/common/input/advanced/input-callbacks) na seção Tópicos avançados do GameInput. ## Obtenção de dados das leituras Embora cada leitura contenha os dados do pacote de entrada bruto do dispositivo, as leituras normalmente também contêm uma ou mais transformações de alto nível desses dados. Por exemplo, a entrada recebida de um gamepad também é analisada em uma estrutura padrão de formato fixo com identificadores conhecidos de botões e direcionais analógicos. As leituras geralmente contêm várias representações diferentes dos mesmos dados de entrada brutos, permitindo que os aplicativos escolham o formato mais adequado às suas necessidades. Os aplicativos podem consultar quais tipos de dados uma leitura contém chamando o método [GetInputKind](/pt-BR/reference/input/gameinput/interfaces/igameinputreading/methods/igameinputreading_getinputkind) dela. Ele retorna um ou mais valores de sinalizador da enumeração [GameInputKind](/pt-BR/reference/input/gameinput/enums/gameinputkind). ```c++ theme={null} typedef enum GameInputKind { GameInputKindUnknown = 0x00000000, GameInputKindRawDeviceReport = 0x00000001, GameInputKindController = 0x00000002, GameInputKindKeyboard = 0x00000004, GameInputKindMouse = 0x00000008, GameInputKindTouch = 0x00000100, GameInputKindMotion = 0x00001000, GameInputKindArcadeStick = 0x00010000, GameInputKindFlightStick = 0x00020000, GameInputKindGamepad = 0x00040000, GameInputKindRacingWheel = 0x00080000, GameInputKindUiNavigation = 0x01000000 } GameInputKind; ``` Os tipos de dados disponíveis em uma leitura dependem do dispositivo de entrada e de suas propriedades físicas. Por exemplo, uma leitura de um teclado padrão pode conter apenas dados de teclado, enquanto uma leitura de um teclado com trackball integrado pode conter dados de teclado e de mouse. Quase todos os controles de jogo produzem leituras que contêm dados genéricos de "controle", que são simplesmente uma coleção de estados anônimos de eixos e botões. Isso permite um amplo suporte a dispositivos para aplicativos com uma interface de mapeamento de entrada. No entanto, muitos controles de jogo (como gamepads) também expõem em suas leituras um estado familiar de formato fixo, que é muito mais fácil de consumir para jogos típicos. ```c++ theme={null} typedef struct GameInputGamepadState { GameInputGamepadButtons buttons; float leftTrigger; float rightTrigger; float leftThumbstickX; float leftThumbstickY; float rightThumbstickX; float rightThumbstickY; } GameInputGamepadState; ``` A interface [IGameInputReading](/pt-BR/reference/input/gameinput/interfaces/igameinputreading/igameinputreading) contém métodos para recuperar o estado em qualquer um dos formatos aos quais a leitura dá suporte. Todas as diferentes representações disponíveis nas leituras são pré-calculadas, portanto, esses métodos simplesmente copiam alguns bytes de dados e retornam. ## Um loop simples de entrada de gamepad O código de exemplo a seguir é um exemplo de um loop de entrada totalmente funcional para gamepads. Algo a ser observado neste exemplo é que não há enumeração explícita de dispositivos. O único uso de [IGameInputDevice](/pt-BR/reference/input/gameinput/interfaces/igameinputdevice/igameinputdevice) é como identificador de dispositivo. Nenhum de seus métodos é chamado. Isso ilustra a natureza centrada na entrada da API GameInput e como ela pode simplificar o código para cenários de entrada comuns. ```c++ theme={null} IGameInput* g_gameInput = nullptr; IGameInputDevice* g_gamepad = nullptr; HRESULT InitializeInput() { return GameInputCreate(&g_gameInput); } void ShutdownInput() { if (g_gamepad) g_gamepad->Release(); if (g_gameInput) g_gameInput->Release(); } void PollGamepadInput() { // Ask for the latest reading from devices that provide fixed-format // gamepad state. If a device has been assigned to g_gamepad, filter // readings to just the ones coming from that device. Otherwise, if // g_gamepad is null, it will allow readings from any device. IGameInputReading * reading; if (SUCCEEDED(g_gameInput->GetCurrentReading(GameInputKindGamepad, g_gamepad, &reading))) { // If no device has been assigned to g_gamepad yet, set it // to the first device we receive input from. (This must be // the one the player is using because it's generating input.) if (!g_gamepad) reading->GetDevice(&g_gamepad); // Retrieve the fixed-format gamepad state from the reading. GameInputGamepadState state; reading->GetGamepadState(&state); reading->Release(); // Application-specific code to process the gamepad state goes here. } // If an error is returned from GetCurrentReading(), it means the // gamepad we were reading from has disconnected. Reset the // device pointer, and go back to looking for an active gamepad. else if (g_gamepad) { g_gamepad->Release(); g_gamepad = nullptr; } } ``` ## Documentação de referência da API * [GameInput (conteúdo da API)](/pt-BR/reference/input/gameinput/gameinput_members) ## Confira também [Fundamentos 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 - [Guias de portabilidade para o XBOX GDK](/pt-BR/home/build-first-title/porting-guides.md) - [GameInput API versioning](/build/core-features/common/input/overviews/input-versioning.md) - [GameInput frequently asked questions](/build/core-features/common/input/overviews/input-faq.md) - [Porting from XInput to GameInput](/build/core-features/common/input/porting/input-porting-xinput.md) - [GameInput](/reference/input/gameinput/gameinput_members.md)