Uso de varias versiones de la API de GameInput en una aplicación

• Agregar características de v4 a una aplicación creada con una versión anterior de la API, como v0, sin migrar toda la aplicación a la vez.
• Llamar a SDK, middleware o complementos de motor que se compilaron con una versión anterior de GameInput, aunque el resto de su aplicación use v4.

​

Versiones de la API compatibles

​

Configuración del proyecto

​

Inclusión del encabezado v0

// GameInputV0.h: declares the v0 API in the GameInput::v0 namespace
#pragma once

#include <windows.h>
#include <GameInput.h>

// The v0 header isn't namespaced; its dependencies are already included above.
namespace GameInput::v0
{
    // Prevent the legacy typedefs from finding interfaces declared by the latest header.
    struct IGameInput;
    struct IGameInputReading;
    struct IGameInputDevice;
    struct IGameInputDispatcher;
    struct IGameInputForceFeedbackEffect;
    struct IGameInputRawDeviceReport;

    #include <v0/GameInput.h>
}

• Primero incluye el <GameInput.h> más reciente. Esto declara la API más reciente en su propio espacio de nombres e incluye los encabezados de Windows y COM de los que depende el encabezado v0, de modo que el encabezado v0 no vuelve a incluirlos dentro del espacio de nombres.
• Las declaraciones adelantadas hacen que los typedef del encabezado v0 declaren nuevas interfaces en GameInput::v0, en lugar de hacer referencia a interfaces que el encabezado más reciente ya declaró.
• Incluir <v0/GameInput.h> dentro del espacio de nombres traslada cada tipo, enumeración y constante de v0 a GameInput::v0, como GameInput::v0::IGameInput y GameInput::v0::GameInputKindGamepad.

​

Ejemplo: agregar características de v4 a una aplicación v0

​

Código v0 existente

• Incluye GameInputV0.h en lugar de <GameInput.h>.
• Crea GameInput llamando a GameInputInitialize con el IID de v0, ya que la biblioteca más reciente no exporta la función GameInputCreate de v0.
• Llama al nuevo código v4 cuando se presiona el botón A.

// LegacyInput.cpp: existing code that uses the v0 API
#include "GameInputV0.h"

using namespace GameInput::v0;

// Implemented in NewInputFeatures.cpp.
void SetControllerColor(IUnknown* device);

IGameInput* g_gameInput = nullptr;

HRESULT InitializeInput()
{
    return GameInput::v4::GameInputInitialize(__uuidof(IGameInput), reinterpret_cast<void**>(&g_gameInput));
}

void UpdateGamepad()
{
    IGameInputReading* reading = nullptr;
    if (SUCCEEDED(g_gameInput->GetCurrentReading(GameInputKindGamepad, nullptr, &reading)))
    {
        GameInputGamepadState state;
        reading->GetGamepadState(&state);

        if (state.buttons & GameInputGamepadA)
        {
            IGameInputDevice* device = nullptr;
            reading->GetDevice(&device);
            SetControllerColor(device);
            device->Release();
        }

        reading->Release();
    }
}

​

Nuevo código v4

// NewInputFeatures.cpp: new code that uses the v4 API
#include <windows.h>
#include <v4/GameInput.h>

using namespace GameInput::v4;

void SetControllerColor(IUnknown* legacyDevice)
{
    IGameInputDevice* device = nullptr;

    // Fails with E_NOINTERFACE if the installed runtime is older than 4.0.
    if (SUCCEEDED(legacyDevice->QueryInterface(IID_PPV_ARGS(&device))))
    {
        device->SetLightingColor({ 0, 255, 0 }, GameInputLightingGroupCenterLight);
        device->ApplyLightingColors();
        device->Release();
    }
}

​

Conservar una biblioteca anterior

​

Reglas para cambiar entre versiones

GameInput::v0::IGameInputDevice* legacyDevice = /* ... */;

// Wrong: compiles, but calls the wrong methods at run time.
auto badDevice = reinterpret_cast<GameInput::v4::IGameInputDevice*>(legacyDevice);

// Correct: asks the object for its v4 interface.
GameInput::v4::IGameInputDevice* device = nullptr;
HRESULT hr = legacyDevice->QueryInterface(IID_PPV_ARGS(&device));

• No incluya otro encabezado de GameInput después del encabezado v0. El encabezado v0 define sus códigos de error, como GAMEINPUT_E_DEVICE_DISCONNECTED, como macros, y esas macros rompen las declaraciones de cualquier encabezado de GameInput que se incluya después. GameInputV0.h sigue esta regla al incluir primero el encabezado más reciente.
• Los objetos devueltos usan la versión a la que llamó. Por ejemplo, GetDevice en una lectura v4 devuelve un dispositivo v4, y una devolución de llamada de dispositivo registrada con la interfaz IGameInput de v4 recibe dispositivos v4. Llame a QueryInterface antes de pasar estos objetos a código que use otra versión.
• Cada llamada a QueryInterface agrega una referencia. Libere el puntero devuelto cuando ya no lo necesite, igual que cualquier otro puntero de interfaz COM.
• Compruebe el resultado. Cuando solicita una versión más reciente de la API, un error significa que el entorno de ejecución instalado no admite esa versión.
• Los tipos v0 de GameInputV0.h son tipos de C++ independientes. GameInput::v0::IGameInput y la interfaz global IGameInput de <v0/GameInput.h> por sí solo describen la misma interfaz, pero C++ los trata como tipos diferentes. Si el código existente u otra biblioteca declara funciones con los tipos v0 globales, llame a esas funciones desde un archivo de código fuente que incluya solo <v0/GameInput.h>.

​

Llamar a SDK que usan una versión anterior de la API

// SdkBridge.cpp: calls an SDK that was built against the v2 API
#include <windows.h>
#include <v2/GameInput.h>
#include "ThirdPartySdk.h"

HRESULT InitializeThirdPartySdk(IUnknown* gameInputObject)
{
    GameInput::v2::IGameInput* gameInput = nullptr;
    HRESULT hr = gameInputObject->QueryInterface(IID_PPV_ARGS(&gameInput));
    if (SUCCEEDED(hr))
    {
        ThirdPartySdkInitialize(gameInput);
        gameInput->Release();
    }

    return hr;
}

​

Consulte también