Utilisation de plusieurs versions de l'API GameInput dans une même application

• Ajouter des fonctionnalités v4 à une application basée sur une version antérieure de l’API, comme v0, sans migrer toute l’application en une seule fois.
• Appeler des SDK, des intergiciels ou des plug-ins de moteur générés avec une version antérieure de GameInput, même lorsque le reste de votre application utilise v4.

​

Versions de l’API prises en charge

​

Configurer votre projet

​

Inclure l’en-tête 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>
}

• Il inclut d’abord le dernier <GameInput.h>. Celui-ci déclare l’API la plus récente dans son propre espace de noms et inclut les en-têtes Windows et COM dont dépend l’en-tête v0, de sorte que l’en-tête v0 ne les inclut pas à nouveau dans l’espace de noms.
• Les déclarations anticipées font en sorte que les typedefs de l’en-tête v0 déclarent de nouvelles interfaces dans GameInput::v0, au lieu de faire référence aux interfaces déjà déclarées par l’en-tête le plus récent.
• L’inclusion de <v0/GameInput.h> dans l’espace de noms place chaque type, énumération et constante v0 dans GameInput::v0, par exemple GameInput::v0::IGameInput et GameInput::v0::GameInputKindGamepad.

​

Exemple : ajouter des fonctionnalités v4 à une application v0

​

Code v0 existant

• Il inclut GameInputV0.h au lieu de <GameInput.h>.
• Il crée GameInput en appelant GameInputInitialize avec l’IID v0, car la bibliothèque la plus récente n’exporte pas la fonction GameInputCreate v0.
• Il appelle le nouveau code v4 lorsque le bouton A est enfoncé.

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

​

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

​

Conserver une bibliothèque antérieure

​

Règles de passage d’une version à l’autre

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’incluez pas d’autre en-tête GameInput après l’en-tête v0. L’en-tête v0 définit ses codes d’erreur, comme GAMEINPUT_E_DEVICE_DISCONNECTED, sous forme de macros, et ces macros cassent les déclarations de tout en-tête GameInput inclus après lui. GameInputV0.h respecte cette règle en incluant d’abord l’en-tête le plus récent.
• Les objets renvoyés utilisent la version que vous avez appelée. Par exemple, GetDevice sur une lecture v4 renvoie un périphérique v4, et un rappel de périphérique inscrit auprès de l’IGameInput v4 reçoit des périphériques v4. Appelez QueryInterface avant de transmettre ces objets à du code qui utilise une autre version.
• Chaque appel à QueryInterface ajoute une référence. Libérez le pointeur renvoyé lorsque vous n’en avez plus besoin, comme pour tout autre pointeur d’interface COM.
• Vérifiez le résultat. Lorsque vous demandez une version plus récente de l’API, un échec signifie que le runtime installé ne prend pas en charge cette version.
• Les types v0 de GameInputV0.h sont des types C++ distincts. GameInput::v0::IGameInput et l’IGameInput global provenant de <v0/GameInput.h> seul décrivent la même interface, mais C++ les traite comme des types différents. Si du code existant ou une autre bibliothèque déclare des fonctions avec les types v0 globaux, appelez ces fonctions depuis un fichier source qui inclut uniquement <v0/GameInput.h>.

​

Appeler des SDK qui utilisent une version antérieure de l’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;
}

​

Voir aussi