> ## 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 inspiré par le modèle de programmation simple (et facile à utiliser) de XInput ; de nombreuses API XInput ont donc un équivalent direct 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 et C++

L'API XInput est un ensemble de fonctions C simples. 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 pas d'incidence sur les performances et présente certains avantages qui deviennent évidents à mesure que vous vous familiarisez avec le fonctionnement de GameInput.

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

<a id="gettingInputSection" />

### Obtention des entrées

Avec XInput, la plupart des jeux parcourent les index d'utilisateur jusqu'à en trouver un auquel un périphérique est connecté, puis lisent l'état 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.
            }
        }
    }
}
```

Avec GameInput, vous obtenez d'abord l'entrée sans spécifier de périphérique, et vous pouvez ensuite déterminer de quel périphérique provient l'entrée si vous le souhaitez. Le code est similaire, mais l'absence d'énumération explicite des périphériques peut conduire à 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 similaire. À mesure que vous vous familiariserez avec l'API GameInput, vous verrez que ce modèle offre des options puissantes de gestion des entrées qui n'existent pas dans XInput.

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

<a id="rumbleFeedbackSection" />

### Retour par vibration

Avec XInput, les jeux appellent simplement`XInputSetState` pour envoyer des commandes de vibration à un périphérique. Avec GameInput, les jeux doivent obtenir l'instance [IGameInputDevice](/fr/reference/input/gameinput/interfaces/igameinputdevice/igameinputdevice) du périphérique, puis appeler sa méthode [SetRumbleState](/fr/reference/input/gameinput/interfaces/igameinputdevice/methods/igameinputdevice_setrumblestate). L'utilisation de ces deux méthodes est similaire. C'est un exemple de cas où vous appelez des fonctions de l'interface du périphérique, au lieu 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. Dans le cas contraire, l'état retourné contient des valeurs neutres ou « au repos », comme si l'utilisateur ne touchait pas du tout le périphérique. Cela évite d'avoir à écrire du code d'entrée supplémentaire pour gérer les changements de focus (par exemple, l'appel de`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/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 basée sur GameInput. Nous recommandons d'effectuer le portage directement vers GameInput, en particulier si vous souhaitez prendre en charge le clavier et la souris ou d'autres périphériques d'entrée. Toutefois, le wrapper XInputOnGameInput peut être utilisé pour 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 également être étudiée comme exemple d'utilisation de l'API GameInput et/ou modifiée selon vos besoins.

<a id="wrapperDifferencesSection" />

### Différences entre XInput et XInputOnGameInput

En règle générale, le wrapper XInputOnGameInput remplace directement l'ancienne API XInput. Il existe toutefois 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 des volants de course ou des sticks arcade, utilisez directement GameInput 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. Ce comportement s'applique indépendamment des appels à`XInputEnable` (ou de leur absence).

* La valeur de`XUSER_MAX_COUNT` est passée de 4 à 8. Cela devrait généralement être transparent pour la plupart des anciens codes XInput. Veillez toutefois à 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-dessous) ; elles ne présentent d'intérêt que si vous prévoyez 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 ; il hérite de toutes les optimisations de performances de l'API GameInput et convient donc à une utilisation dans du code de production. Il hérite également de la prise en charge étendue des périphériques de GameInput (comme les manettes HID populaires) et ajoute les nouvelles fonctions suivantes à l'API :

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

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

  > \[!NOTE]
  > Dans la version May Preview,`XInputGetStateWithToken` se comporte actuellement de la même manière que`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é. La transmission de cet ID à la méthode [FindDeviceFromId](/fr/reference/input/gameinput/interfaces/igameinput/methods/igameinput_finddevicefromid) de [IGameInput](/fr/reference/input/gameinput/interfaces/igameinput/igameinput) retourne le [IGameInputDevice](/fr/reference/input/gameinput/interfaces/igameinputdevice/igameinputdevice) correspondant à cet index d'utilisateur. Celui-ci peut ensuite être utilisé 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 100 % compatible peuvent affiner le comportement et les performances du wrapper en définissant l'une des macros de préprocesseur suivantes :

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

Par défaut, le wrapper XInput initialise automatiquement et de manière différée l'API GameInput sous-jacente lors du premier appel à l'une des fonctions du wrapper. 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 à une fonction du wrapper XInput est 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, ce qui permet au prédicteur de branchement d'en atténuer le coût, mais cela reste une surcharge supplémentaire.

3. Bien qu'elle ne doive jamais échouer, il n'existe aucun moyen de savoir si l'initialisation différée de l'API GameInput sous-jacente a réussi.

4. L'instance [IGameInput](/fr/reference/input/gameinput/interfaces/igameinput/igameinput) sous-jacente n'est pas libérée tant que les variables globales du wrapper XInput ne sont pas nettoyées (soit lors du déchargement du module, soit lors de l'arrêt du processus).

Les jeux peuvent contrôler manuellement l'initialisation et l'arrêt du wrapper en définissant la macro`XINPUT_ON_GAMEINPUT_EXPLICIT_INITIALIZATION`. Celle-ci ajoute deux nouvelles fonctions,`XInputOnGameInputInitialize` et`XInputOnGameInputUninitialize`, qui peuvent être appelées pour contrôler précisément le moment où l'initialisation et l'arrêt se produisent.

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

Le code nécessaire à l'implémentation de la fonction`XInputEnable` ajoute une surcharge supplémentaire à chaque appel des fonctions`XInputGetState`,`XInputGetStateWithToken`,`XInputSetState`,`XInputSetStateEx` et`XInputGetKeystroke`. Si votre code n'appelle pas`XInputEnable`, ou si cet appel peut facilement être supprimé de votre code, la définition de la macro`XINPUT_ON_GAMEINPUT_NO_XINPUTENABLE` supprime la prise en charge de`XInputEnable` et la surcharge associée. Le code GameInput sous-jacent assure 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 nécessaire à l'implémentation de la fonction`XInputGetKeystroke` ajoute quelques fonctions et variables supplémentaires à l'implémentation du wrapper. Il n'ajoute pas de 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/reference/input/gameinput/gameinput_members)
* [XInputOnGameInput (contenu de l'API)](/fr/reference/input/xinputongameinput/xinputongameinput_members)

## Voir aussi

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

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

[Microsoft Game Development Kit](/fr/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)