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

• Ajouter des fonctionnalités v4 à une application créée avec une version antérieure de l’API, comme v0, sans migrer toute l’application d’un seul coup.
• Appeler des SDK, des intergiciels ou des plug-ins de moteur qui ont été 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 plus récent <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 de nouveau à l’intérieur de 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 que l’en-tête le plus récent a déjà déclarées.
• L’inclusion de <v0/GameInput.h> à l’intérieur de l’espace de noms déplace chaque type, énumération et constante v0 dans GameInput::v0, comme 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 plus récente bibliothèque 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 pour passer 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 brisent 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 retournés utilisent la version que vous avez appelée. Par exemple, GetDevice sur une lecture v4 retourne un appareil v4, et un rappel d’appareil inscrit auprès de l’interface IGameInput v4 reçoit des appareils 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 retourné 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’interface IGameInput globale 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 à partir d’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