Lectures GameInput

Les paquets d’entrée bruts reçus de chaque périphérique sont encapsulés dans des objets de « lecture ». Les lectures contiennent les données du paquet brut d’origine et (habituellement) une ou plusieurs transformations des données brutes en formats de plus haut niveau. En plus de leur rôle de conteneurs de données, les lectures servent aussi d’identificateurs qui référencent une position précise dans le flux d’entrée.

Acquisition des lectures

L’API GameInput offre deux façons d’acquérir des lectures. La façon la plus courante consiste à y accéder directement à partir du flux d’entrée, au moyen des méthodes de l’interface IGameInput.

HRESULT GetCurrentReading(
    _In_ GameInputKind inputKind,
    _In_opt_ IGameInputDevice * device,
    _COM_Outptr_ IGameInputReading ** reading);

L’appel à GetCurrentReading récupère la lecture la plus récente du flux d’entrée. Un filtre GameInputKind facultatif peut être passé pour limiter les lectures retournées à des types d’entrée précis, comme une manette ou un clavier. Un filtre IGameInputDevice facultatif peut aussi être passé pour limiter les lectures retournées à celles générées par le périphérique spécifié. Ces filtres peuvent être appliqués individuellement ou ensemble. Les instances de IGameInputReading sont des singletons avec décompte de références. La récupération d’une lecture est une opération extrêmement rapide et légère : aucune allocation de mémoire ni copie n’est effectuée, et l’appel d’API est sans verrou et sans transition vers le mode noyau. Comme les lectures sont des singletons, une application peut comparer l’égalité des pointeurs de lecture pour savoir si deux appels à GetCurrentReading ont retourné la même lecture (ce qui signifie qu’aucune nouvelle entrée n’a été générée). Les jeux ayant des besoins d’entrée moins complexes peuvent simplement interroger les nouvelles entrées une fois par image et comparer l’état stocké dans les deux lectures pour déceler des différences (si ce n’est pas la même lecture). Les jeux ayant des besoins d’entrée plus complexes, toutefois, peuvent devoir parcourir le flux d’entrée pour obtenir un portrait complet de tous les changements d’état d’entrée survenus depuis l’image précédente. Cela est rendu possible par les méthodes GetNextReading et GetPreviousReading, qui acceptent les mêmes filtres que GetCurrentReading. Le flux d’entrée conserve dans sa mémoire tampon la dernière demi-seconde de lectures historiques.

HRESULT GetNextReading(
    _In_ IGameInputReading * referenceReading,
    _In_ GameInputKind inputKind,
    _In_opt_ IGameInputDevice * device,
    _COM_Outptr_ IGameInputReading ** reading);

HRESULT GetPreviousReading(
    _In_ IGameInputReading * referenceReading,
    _In_ GameInputKind inputKind,
    _In_opt_ IGameInputDevice * device,
    _COM_Outptr_ IGameInputReading ** reading);

Les applications peuvent aussi inscrire un rappel qui est invoqué chaque fois qu’une entrée est générée. Comme pour les méthodes synchrones précédentes, plusieurs filtres peuvent être appliqués pour contrôler les types de lectures retournées et les périphériques dont elles proviennent. Pour plus d’informations, consultez Rappels GameInput dans la section Rubriques avancées sur GameInput.

Obtention des données des lectures

Bien que chaque lecture contienne les données du paquet d’entrée brut du périphérique, les lectures contiennent aussi généralement une ou plusieurs transformations de haut niveau de ces données. Par exemple, les entrées reçues d’une manette sont aussi analysées dans une structure standard à format fixe avec des identificateurs de boutons et de sticks bien connus. Les lectures contiennent souvent plusieurs représentations différentes des mêmes données d’entrée brutes, ce qui permet aux applications de choisir le format qui convient le mieux à leurs besoins. Les applications peuvent connaître les types de données qu’une lecture contient en appelant sa méthode GetInputKind. Celle-ci retourne une ou plusieurs valeurs d’indicateur de l’énumération GameInputKind.

typedef enum GameInputKind
{
    GameInputKindUnknown         = 0x00000000,
    GameInputKindRawDeviceReport = 0x00000001,
    GameInputKindController      = 0x00000002,
    GameInputKindKeyboard        = 0x00000004,
    GameInputKindMouse           = 0x00000008,
    GameInputKindTouch           = 0x00000100,
    GameInputKindMotion          = 0x00001000,
    GameInputKindArcadeStick     = 0x00010000,
    GameInputKindFlightStick     = 0x00020000,
    GameInputKindGamepad         = 0x00040000,
    GameInputKindRacingWheel     = 0x00080000,
    GameInputKindUiNavigation    = 0x01000000
} GameInputKind;

Les types de données disponibles dans une lecture dépendent du périphérique d’entrée et de ses propriétés physiques. Par exemple, une lecture provenant d’un clavier standard pourrait ne contenir que des données de clavier, tandis qu’une lecture provenant d’un clavier doté d’une boule de commande intégrée pourrait contenir à la fois des données de clavier et de souris. Presque tous les contrôleurs de jeu produisent des lectures qui contiennent des données génériques de « contrôleur », qui sont simplement une collection d’états anonymes d’axes et de boutons. Cela permet une vaste prise en charge des périphériques pour les applications dotées d’une interface utilisateur de mappage des entrées. Cependant, de nombreux contrôleurs de jeu (comme les manettes) exposent aussi dans leurs lectures un état familier à format fixe, beaucoup plus facile à utiliser pour les jeux typiques.

typedef struct GameInputGamepadState
{
    GameInputGamepadButtons buttons;
    float leftTrigger;
    float rightTrigger;
    float leftThumbstickX;
    float leftThumbstickY;
    float rightThumbstickX;
    float rightThumbstickY;
} GameInputGamepadState;

L’interface IGameInputReading contient des méthodes pour récupérer l’état dans n’importe lequel des formats que la lecture prend en charge. Toutes les différentes représentations disponibles à partir des lectures sont précalculées; ces méthodes se contentent donc de copier quelques octets de données et de retourner.

Une boucle d’entrée de manette simple

L’exemple de code suivant est un exemple de boucle d’entrée entièrement fonctionnelle pour les manettes. Il est à noter que cet exemple ne comporte aucune énumération explicite des périphériques. La seule utilisation de IGameInputDevice est comme identificateur de périphérique. Aucune de ses méthodes n’est jamais appelée. Cela illustre la nature centrée sur les entrées de l’API GameInput et la façon dont elle peut simplifier le code pour les scénarios d’entrée courants.

IGameInput* g_gameInput = nullptr;
IGameInputDevice* g_gamepad = nullptr;

HRESULT InitializeInput()
{
    return GameInputCreate(&g_gameInput);
}

void ShutdownInput()
{
    if (g_gamepad) g_gamepad->Release();
    if (g_gameInput) g_gameInput->Release();
}

void PollGamepadInput()
{
    // Ask for the latest reading from devices that provide fixed-format
    // gamepad state. If a device has been assigned to g_gamepad, filter
    // readings to just the ones coming from that device. Otherwise, if
    // g_gamepad is null, it will allow readings from any device.
    IGameInputReading * reading;
    if (SUCCEEDED(g_gameInput->GetCurrentReading(GameInputKindGamepad, g_gamepad, &reading)))
    {
        // If no device has been assigned to g_gamepad yet, set it
        // to the first device we receive input from. (This must be
        // the one the player is using because it's generating input.)
        if (!g_gamepad) reading->GetDevice(&g_gamepad);

        // Retrieve the fixed-format gamepad state from the reading.
        GameInputGamepadState state;
        reading->GetGamepadState(&state);
        reading->Release();

        // Application-specific code to process the gamepad state goes here.
    }

    // If an error is returned from GetCurrentReading(), it means the
    // gamepad we were reading from has disconnected. Reset the
    // device pointer, and go back to looking for an active gamepad.
    else if (g_gamepad)
    {
        g_gamepad->Release();
        g_gamepad = nullptr;
    }
}

Documentation de référence de l’API

GameInput (contenu de l’API)

Voir aussi

Notions fondamentales de GameInput Rubriques avancées sur GameInput Référence de l’API GameInput

Introduction

Onboarding & Access

Setup & Install

Build Your First Title

Acquisition des lectures

Obtention des données des lectures

Une boucle d’entrée de manette simple

Documentation de référence de l’API

Voir aussi

​Acquisition des lectures

​Obtention des données des lectures

​Une boucle d’entrée de manette simple

​Documentation de référence de l’API

​Voir aussi

Acquisition des lectures

Obtention des données des lectures

Une boucle d’entrée de manette simple

Documentation de référence de l’API

Voir aussi