> ## Documentation Index
> Fetch the complete documentation index at: https://devdocs.xbox.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Portage de XInput vers GameInput

> Portage de XInput vers GameInput

<a id="introductionSection" />

Le portage de XInput vers GameInput est le moins compliqué de toutes les anciennes API. En effet, GameInput a été fortement influencée par le modèle de programmation simple (et facile à utiliser) de XInput; par conséquent, de nombreuses API XInput correspondent directement (1:1) à des fonctions équivalentes dans GameInput.

<a id="keyDifferencesSection" />

## Différences clés

Les différences clés entre XInput et GameInput sont abordées dans les sections suivantes.

<a id="cVsCppSection" />

### C ou C++

L'API XInput est une collection de fonctions C plates. GameInput, en revanche, est en C++ et utilise des interfaces (tout comme les API graphiques et audio). En pratique, cela ne complique pas le code qui utilise l'API GameInput, n'a aucune incidence sur les performances et présente certains avantages qui deviennent évidents une fois que vous connaissez mieux le fonctionnement de GameInput.

Il est important de comprendre que, même si ces interfaces peuvent ressembler à COM, elles n'en sont pas. Seule une compréhension de base du décompte de références est nécessaire pour utiliser ces interfaces. Pour plus d'informations, consultez la [section Interfaces de la rubrique Notions fondamentales de GameInput](/fr-CA/build/core-features/common/input/overviews/input-fundamentals#interfacesSection).

<a id="gettingInputSection" />

### Obtention des entrées

Dans XInput, la plupart des jeux parcourent les index d'utilisateur jusqu'à en trouver un auquel un périphérique est connecté, puis l'état est lu à partir de ce périphérique. Les jeux mémorisent souvent l'index d'utilisateur pour ne pas avoir à refaire la boucle la fois suivante. Par exemple, le code suivant est typique d'un jeu qui invite l'utilisateur à « appuyer sur A » sur sa manette :

```c++ theme={null}
// This function looks for a gamepad that currently has the "A" button pressed.
void FindActiveGamepad()
{
    for (DWORD index = 0; index < XUSER_MAX_COUNT; index++)
    {
        XINPUT_STATE state;
        if (XInputGetState(index, &state) == ERROR_SUCCESS)
        {
            if (state.Gamepad.wButtons & XINPUT_GAMEPAD_A)
            {
                // Found the user's gamepad at this index.
            }
        }
    }
}
```

Dans GameInput, vous obtenez d'abord l'entrée sans préciser de périphérique, et vous pouvez demander de quel périphérique provient l'entrée si vous le souhaitez. Le code est semblable, mais l'élimination du besoin d'énumérer explicitement les périphériques peut mener à des algorithmes plus simples.

```c++ theme={null}
// This function looks for a gamepad that currently has the "A" button pressed.
void FindActiveGamepad(IGameInput * gameInput)
{
    // This checks for input from all gamepads simultaneously.
    IGameInputReading * reading;
    if (SUCCEEDED(gameInput->GetCurrentReading(GameInputKindGamepad, nullptr, &reading)))
    {
        GameInputGamepadState state;
        reading->GetGamepadState(&state);

        if (state.buttons & GameInputGamepadA)
        {
            // Found the user's gamepad.  At this point we can
            // get the device that generated this input, and then
            // pass that into future calls to the GetCurrentReading
            // method to receive input only from that gamepad.
        }

        reading->Release():
    }
}
```

Le code n'est pas tout à fait aussi simple qu'avec XInput, mais il est très semblable. À mesure que vous vous familiariserez avec l'API GameInput, vous verrez comment ce modèle offre de puissantes options de gestion des entrées qui n'existent pas dans XInput.

Il convient également de noter que XInput retourne les valeurs analogiques des gâchettes sous forme de type **BYTE** et les valeurs analogiques des sticks sous forme de type **SHORT**. Avec l'API GameInput, ces valeurs analogiques sont retournées sous forme de valeurs **float** de 0 à 1 (gâchettes) ou de -1 à 1 (sticks).

<a id="rumbleFeedbackSection" />

### Rétroaction par vibration

Dans XInput, les jeux appellent simplement`XInputSetState` pour envoyer des commandes de vibration à un périphérique. Dans GameInput, les jeux doivent obtenir l'instance [IGameInputDevice](/fr-CA/reference/input/gameinput/interfaces/igameinputdevice/igameinputdevice) du périphérique, puis appeler sa méthode [SetRumbleState](/fr-CA/reference/input/gameinput/interfaces/igameinputdevice/methods/igameinputdevice_setrumblestate). L'utilisation est semblable entre ces deux méthodes. Il s'agit d'un exemple de cas où vous appellerez des fonctions sur l'interface du périphérique, plutôt que de l'utiliser uniquement comme identificateur de périphérique.

<a id="appFocusSection" />

### Focus de l'application

Sur console, GameInput fournit des entrées à une application uniquement lorsqu'elle a le focus. Sinon, l'état retourné contient des valeurs neutres ou « au repos », comme si l'utilisateur ne touchait pas du tout le périphérique. Cela élimine le besoin de code d'entrée supplémentaire pour gérer les changements de focus (par exemple, l'appel à`XInputEnable`).

Sur PC, les entrées sont envoyées à tous les processus par défaut. À l'avenir, ce comportement pourra être modifié à l'aide de la méthode [SetFocusPolicy](/fr-CA/reference/input/gameinput/interfaces/igameinput/methods/igameinput_setfocuspolicy).

<a id="xinputWrapperSection" />

## Le wrapper XInputOnGameInput

Le Microsoft Game Development Kit (GDK) est fourni avec un fichier d'en-tête appelé`XInputOnGameInput.h` qui contient une implémentation de l'API XInput par-dessus GameInput. Nous recommandons de porter directement vers GameInput, surtout si vous voulez prendre en charge le clavier et la souris ou d'autres périphériques d'entrée. Cependant, le wrapper XInputOnGameInput peut servir à amorcer un premier effort de portage sans nécessiter de modifications du code XInput existant.

Pour utiliser le wrapper XInputOnGameInput, remplacez simplement ce code :

```c++ theme={null}
#include <XInput.h>
```

par ce code :

```c++ theme={null}
#include <XInputOnGameInput.h>
using namespace XInputOnGameInput;
```

puis recompilez votre code.

L'implémentation du code du wrapper XInput se trouve entièrement dans le fichier d'en-tête; elle peut donc aussi être examinée comme exemple d'utilisation de l'API GameInput, ou modifiée au besoin, ou les deux.

<a id="wrapperDifferencesSection" />

### Différences entre XInput et XInputOnGameInput

En général, le wrapper XInputOnGameInput remplace directement l'ancienne API XInput. Cependant, il existe quelques différences mineures :

* Par souci de simplicité, seule la prise en charge des manettes a été codée dans le wrapper. Si vous devez prendre en charge d'autres périphériques, comme les volants de course ou les sticks d'arcade, utilisez GameInput directement ou ajoutez la prise en charge de ces périphériques dans le code de XInputOnGameInput.

* Le wrapper ne retourne les entrées de manette que lorsque le jeu a le focus. Lorsque le jeu n'a pas le focus, tout état de manette retourné est défini sur des valeurs neutres ou « au repos », comme si l'utilisateur ne touchait pas la manette. C'est le cas indépendamment de tout appel à`XInputEnable` (ou de son absence).

* La valeur de`XUSER_MAX_COUNT` est passée de 4 à 8. Cela devrait généralement être transparent pour la plupart du code XInput existant. Cependant, assurez-vous d'examiner attentivement toute utilisation de la fonction`XInputGetKeystroke` dans votre code pour vous assurer que rien n'est codé en dur en supposant une valeur maximale de 4 retournée dans le membre`UserIndex` de la structure`XINPUT_KEYSTROKE`. Sinon, un dépassement de mémoire tampon pourrait se produire.

* Quelques nouvelles fonctions ont été ajoutées (voir ci-après); elles ne devraient vous intéresser que si vous avez l'intention de continuer à utiliser le wrapper XInput dans du code de production.

<a id="productionWrapperUseSection" />

### Utilisation de XInputOnGameInput dans du code de production

Le wrapper XInputOnGameInput est conçu pour être performant et sans verrou, héritant de toutes les optimisations de performances de l'API GameInput; il convient donc à une utilisation dans du code de production. Il hérite aussi de la prise en charge plus vaste des périphériques de GameInput (comme les manettes HID populaires) et ajoute les nouvelles fonctions suivantes à l'API :

* **`XInputSetStateEx`** est semblable à`XInputSetState`, mais ajoute la prise en charge des moteurs des gâchettes.

* **`XInputGetStateWithToken`** est semblable à`XInputGetState`, mais permet à l'appelant de fournir un jeton de pipeline d'images D3DX pour associer une lecture d'entrée précise à une image graphique en vue d'une analyse ultérieure dans PIX.

  > \[!NOTE]
  > Dans la version préliminaire de mai,`XInputGetStateWithToken` se comporte actuellement de façon identique à`XInputGetState`, car le code GameInput sous-jacent n'est pas entièrement implémenté.

* **`XInputGetDeviceId`** retourne le`APP_LOCAL_DEVICE_ID` du périphérique associé à un index d'utilisateur donné. Le passage de cet ID à la méthode [FindDeviceFromId](/fr-CA/reference/input/gameinput/interfaces/igameinput/methods/igameinput_finddevicefromid) de [IGameInput](/fr-CA/reference/input/gameinput/interfaces/igameinput/igameinput) retourne l'interface [IGameInputDevice](/fr-CA/reference/input/gameinput/interfaces/igameinputdevice/igameinputdevice) correspondant à cet index d'utilisateur. Celle-ci peut ensuite être utilisée pour accéder à des fonctionnalités supplémentaires de l'API GameInput qui ne sont pas exposées par le wrapper XInput.

<a id="optimizingSection" />

#### Optimisation du code du wrapper

Par défaut, le wrapper XInputOnGameInput est configuré pour être directement compatible avec l'ancienne API XInput. Les jeux qui n'ont pas besoin d'un comportement entièrement compatible peuvent ajuster le comportement et les performances du wrapper en définissant l'une ou l'autre des macros de préprocesseur suivantes :

##### XINPUT\_ON\_GAMEINPUT\_EXPLICIT\_INITIALIZATION

Par défaut, le wrapper XInput initialise automatiquement et de façon différée l'API GameInput sous-jacente la première fois que l'une des fonctions du wrapper est appelée. Cela garantit une compatibilité directe avec le code XInput existant, mais présente plusieurs inconvénients mineurs :

1. Le temps d'exécution du premier appel de fonction du wrapper XInput sera plus long que d'habitude.

2. Chaque fonction du wrapper XInput doit vérifier, à chaque appel, si l'initialisation différée a été effectuée. Il s'agit d'un simple test d'une variable globale; le prédicteur de branchement devrait donc atténuer le coût, mais il s'agit tout de même d'une surcharge supplémentaire.

3. Bien que cela ne devrait jamais échouer, il n'y a aucun moyen de savoir si l'initialisation différée de l'API GameInput sous-jacente a réussi.

4. L'instance [IGameInput](/fr-CA/reference/input/gameinput/interfaces/igameinput/igameinput) sous-jacente n'est pas libérée avant le nettoyage des variables globales du wrapper XInput (soit en raison du déchargement du module, soit en raison de l'arrêt du processus).

Les jeux peuvent prendre le contrôle manuel de l'initialisation et de l'arrêt du wrapper en définissant la macro`XINPUT_ON_GAMEINPUT_EXPLICIT_INITIALIZATION`. Cela ajoute deux nouvelles fonctions,`XInputOnGameInputInitialize` et`XInputOnGameInputUninitialize`, qui peuvent être appelées pour contrôler précisément le moment de l'initialisation et de l'arrêt.

##### XINPUT\_ON\_GAMEINPUT\_NO\_XINPUTENABLE

Le code requis pour implémenter la fonction`XInputEnable` ajoute une surcharge à chaque appel des fonctions`XInputGetState`,`XInputGetStateWithToken`,`XInputSetState`,`XInputSetStateEx` et`XInputGetKeystroke`. Si votre code n'appelle pas`XInputEnable`, ou si cet appel peut facilement être éliminé de votre code, la définition de la macro`XINPUT_ON_GAMEINPUT_NO_XINPUTENABLE` supprimera la prise en charge de`XInputEnable` et la surcharge associée. Le code GameInput sous-jacent exécute de toute façon automatiquement la fonctionnalité de`XInputEnable` lors des changements de focus; la plupart des jeux voudront donc définir cette macro s'ils le peuvent.

##### XINPUT\_ON\_GAMEINPUT\_NO\_XINPUTGETKEYSTROKE

Le code requis pour implémenter la fonction`XInputGetKeystroke` ajoute quelques fonctions et variables supplémentaires à l'implémentation du wrapper. Il n'ajoute aucune surcharge aux autres fonctions de l'API XInput, mais si votre code n'appelle pas`XInputGetKeystroke`, vous pouvez définir la macro`XINPUT_ON_GAMEINPUT_NO_XINPUTGETKEYSTROKE` pour réduire légèrement la taille du code et des données du wrapper XInput.

<a id="seeAlsoSection" />

## Documentation de référence de l'API

* [GameInput (contenu de l'API)](/fr-CA/reference/input/gameinput/gameinput_members)
* [XInputOnGameInput (contenu de l'API)](/fr-CA/reference/input/xinputongameinput/xinputongameinput_members)

## Voir aussi

[Vue d'ensemble de GameInput](/fr-CA/build/core-features/common/input/overviews/input-overview)

[Référence de l'API GameInput](/fr-CA/reference/input/gc-reference-input-toc)

[Microsoft Game Development Kit](/fr-CA/services/playfab/sdks/platforms/gdk)


## Related topics

- [Guides de portage vers le XBOX GDK](/fr-CA/home/build-first-title/porting-guides.md)
- [Guides de portage vers le GDK XBOX](/fr/home/build-first-title/porting-guides.md)
- [Portabilidad de XInput a GameInput](/es/build/core-features/common/input/porting/input-porting-xinput.md)
- [Porting from XInput to GameInput](/build/core-features/common/input/porting/input-porting-xinput.md)
- [Preguntas más frecuentes sobre GameInput](/es/build/core-features/common/input/overviews/input-faq.md)