Usando várias versões da API GameInput em um aplicativo

• Adicione recursos da v4 a um aplicativo criado com base em uma versão de API anterior, como a v0, sem migrar o aplicativo inteiro de uma só vez.
• Chame SDKs, middleware ou plug-ins de mecanismo que foram compilados com uma versão anterior do GameInput, mesmo quando o restante do seu aplicativo usa a v4.

​

Versões de API compatíveis

​

Configurar seu projeto

​

Incluir o cabeçalho 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>
}

• Ele inclui primeiro o <GameInput.h> mais recente. Isso declara a API mais recente em seu próprio namespace e inclui os cabeçalhos do Windows e do COM dos quais o cabeçalho v0 depende, para que o cabeçalho v0 não os inclua novamente dentro do namespace.
• As declarações antecipadas fazem com que os typedefs do cabeçalho v0 declarem novas interfaces em GameInput::v0, em vez de se referirem a interfaces que o cabeçalho mais recente já declarou.
• Incluir <v0/GameInput.h> dentro do namespace move todos os tipos, enumerações e constantes da v0 para GameInput::v0, como GameInput::v0::IGameInput e GameInput::v0::GameInputKindGamepad.

​

Exemplo: adicionar recursos da v4 a um aplicativo v0

​

Código v0 existente

• Ele inclui GameInputV0.h em vez de <GameInput.h>.
• Ele cria o GameInput chamando GameInputInitialize com o IID da v0, porque a biblioteca mais recente não exporta a função GameInputCreate da v0.
• Ele chama o novo código v4 quando o botão A é pressionado.

// 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();
    }
}

​

Novo 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();
    }
}

​

Manter uma biblioteca anterior

​

Regras para alternar entre versões

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

• Não inclua outro cabeçalho do GameInput depois do cabeçalho v0. O cabeçalho v0 define seus códigos de erro, como GAMEINPUT_E_DEVICE_DISCONNECTED, como macros, e essas macros quebram as declarações de qualquer cabeçalho do GameInput incluído depois dele. GameInputV0.h segue essa regra incluindo primeiro o cabeçalho mais recente.
• Os objetos retornados usam a versão que você chamou. Por exemplo, GetDevice em uma leitura v4 retorna um dispositivo v4, e um retorno de chamada de dispositivo registrado com o IGameInput da v4 recebe dispositivos v4. Chame QueryInterface antes de passar esses objetos para um código que usa outra versão.
• Cada chamada para QueryInterface adiciona uma referência. Libere o ponteiro retornado quando não precisar mais dele, assim como qualquer outro ponteiro de interface COM.
• Verifique o resultado. Quando você solicita uma versão de API mais recente, uma falha significa que o runtime instalado não é compatível com essa versão.
• Os tipos v0 em GameInputV0.h são tipos C++ separados. GameInput::v0::IGameInput e o IGameInput global de <v0/GameInput.h> sozinho descrevem a mesma interface, mas o C++ os trata como tipos diferentes. Se um código existente ou outra biblioteca declarar funções com os tipos v0 globais, chame essas funções a partir de um arquivo de origem que inclua somente <v0/GameInput.h>.

​

Chamar SDKs que usam uma versão de API anterior

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

​

Confira também