Lecturas de GameInput

Los paquetes de entrada sin procesar recibidos de cada dispositivo se encapsulan en objetos de “lectura”. Las lecturas contienen los datos originales del paquete sin procesar y (normalmente) una o varias transformaciones de los datos sin procesar en formatos de nivel superior. Además de su función como contenedores de datos, las lecturas también sirven como identificadores que hacen referencia a una posición específica dentro de la secuencia de entrada.

Adquisición de lecturas

La API de GameInput proporciona dos maneras de adquirir lecturas. La más común es acceder a ellas directamente desde la secuencia de entrada, mediante los métodos de la interfaz IGameInput.

HRESULT GetCurrentReading(
    _In_ GameInputKind inputKind,
    _In_opt_ IGameInputDevice * device,
    _COM_Outptr_ IGameInputReading ** reading);

Al llamar a GetCurrentReading se recupera la lectura más reciente de la secuencia de entrada. Se puede pasar un filtro GameInputKind opcional que limita las lecturas devueltas a tipos específicos de entrada, como gamepad o teclado. También se puede pasar un filtro IGameInputDevice opcional que limita las lecturas devueltas solo a las generadas por el dispositivo especificado. Estos filtros se pueden aplicar de forma individual o conjunta. Las instancias de IGameInputReading son singletons con recuento de referencias. Recuperar una lectura es una operación extremadamente rápida y ligera: no se realizan asignaciones ni copias de memoria, y la llamada a la API no usa bloqueos ni transiciones al modo kernel. Dado que las lecturas son singletons, una aplicación puede comparar los punteros de lectura por igualdad para saber si dos llamadas a GetCurrentReading han devuelto la misma lectura (lo que significa que no se generó ninguna entrada nueva). Los juegos con necesidades de entrada menos complejas podrían simplemente sondear la entrada nueva una vez por fotograma y comparar el estado almacenado en las dos lecturas en busca de diferencias (si no son la misma lectura). Sin embargo, los juegos con necesidades de entrada más complejas podrían necesitar recorrer la secuencia de entrada para obtener una imagen completa de todos los cambios de estado de entrada que se han producido desde el fotograma anterior. Esto es posible gracias a los métodos GetNextReading y GetPreviousReading, que admiten los mismos filtros que GetCurrentReading. La secuencia de entrada mantiene el último medio segundo de lecturas históricas en su búfer.

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, las aplicaciones pueden registrar una devolución de llamada que se invoca cada vez que se genera una entrada. Al igual que con los métodos sincrónicos anteriores, se pueden aplicar varios filtros para controlar qué tipos de lecturas se devuelven y de qué dispositivos. Para obtener más información, consulte Devoluciones de llamada de GameInput en la sección de temas avanzados de GameInput.

Obtención de datos de las lecturas

Aunque cada lectura contiene los datos del paquete de entrada sin procesar del dispositivo, las lecturas también suelen contener una o varias transformaciones de alto nivel de esos datos. Por ejemplo, la entrada recibida de un gamepad también se analiza en una estructura estándar de formato fijo con identificadores de botones y sticks conocidos. Las lecturas a menudo contienen varias representaciones diferentes de los mismos datos de entrada sin procesar, lo que permite a las aplicaciones elegir el formato que mejor se adapte a sus necesidades. Las aplicaciones pueden consultar qué tipos de datos contiene una lectura llamando a su método GetInputKind. Este devuelve uno o varios valores de marca de la enumeración GameInputKind.

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;

Los tipos de datos disponibles en una lectura dependen del dispositivo de entrada y de sus propiedades físicas. Por ejemplo, una lectura de un teclado estándar podría contener solo datos de teclado, mientras que una lectura de un teclado con trackball integrado podría contener tanto datos de teclado como de mouse. Casi todos los mandos de juego generan lecturas que contienen datos genéricos de “mando”, que son simplemente una colección de estados anónimos de ejes y botones. Esto permite una amplia compatibilidad con dispositivos para las aplicaciones con una interfaz de usuario de asignación de entrada. Sin embargo, muchos mandos de juego (como los gamepads) también exponen en sus lecturas el conocido estado de formato fijo, que es mucho más fácil de consumir para los juegos típicos.

typedef struct GameInputGamepadState
{
    GameInputGamepadButtons buttons;
    float leftTrigger;
    float rightTrigger;
    float leftThumbstickX;
    float leftThumbstickY;
    float rightThumbstickX;
    float rightThumbstickY;
} GameInputGamepadState;

La interfaz IGameInputReading contiene métodos para recuperar el estado en cualquiera de los formatos que admite la lectura. Todas las diferentes representaciones disponibles en las lecturas están precalculadas, por lo que estos métodos simplemente copian unos pocos bytes de datos y regresan.

Un bucle de entrada de gamepad sencillo

El siguiente código de ejemplo es un ejemplo de un bucle de entrada totalmente funcional para gamepads. Algo que hay que destacar de este ejemplo es que no hay una enumeración explícita de dispositivos. El único uso de IGameInputDevice es como identificador de dispositivo. Nunca se llama a ninguno de sus métodos. Esto ilustra la naturaleza centrada en la entrada de la API de GameInput y cómo puede simplificar el código para escenarios de entrada comunes.

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;
    }
}

Documentación de referencia de la API

GameInput (contenido de la API)

Consulte también

Aspectos básicos de GameInput Temas avanzados de GameInput Referencia de la API de GameInput

GDK and Game Engines Integration

Steam porting guide

Game Principles

Core Features

Console Features

Adquisición de lecturas

Obtención de datos de las lecturas

Un bucle de entrada de gamepad sencillo

Documentación de referencia de la API

Consulte también

​Adquisición de lecturas

​Obtención de datos de las lecturas

​Un bucle de entrada de gamepad sencillo

​Documentación de referencia de la API

​Consulte también

Adquisición de lecturas

Obtención de datos de las lecturas

Un bucle de entrada de gamepad sencillo

Documentación de referencia de la API

Consulte también