Saisie à l’aide de la commande de jeu, du clavier et de la souris dans DirectXKeyboard, mouse, and controller input in DirectX

Notes

Cet article s’applique aux API natives WinRT héritées.This article relates to the legacy WinRT native APIs. Pour les nouveaux projets d’application native, nous vous recommandons d’utiliser l' API OpenXR.For new native app projects, we recommend using the OpenXR API.

Les claviers, les souris et les contrôleurs de jeu peuvent être des formes d’entrée utiles pour les appareils Windows Mixed Reality.Keyboards, mice, and game controllers can all be useful forms of input for Windows Mixed Reality devices. Les claviers et souris Bluetooth sont pris en charge sur HoloLens, pour être utilisés avec le débogage de votre application ou comme une autre forme d’entrée.Bluetooth keyboards and mice are both supported on HoloLens, for use with debugging your app or as an alternate form of input. Windows Mixed Reality prend également en charge les casques immersifs attachés à des PC, où les souris, les claviers et les contrôleurs de jeu étaient traditionnellement la norme.Windows Mixed Reality also supports immersive headsets attached to PCs - where mice, keyboards, and game controllers have historically been the norm.

Pour utiliser l’entrée au clavier sur HoloLens, couplez un clavier Bluetooth à votre appareil ou utilisez une entrée virtuelle via le portail de périphériques Windows.To use keyboard input on HoloLens, pair a Bluetooth keyboard to your device or use virtual input via the Windows Device Portal. Pour utiliser l’entrée au clavier tout en portant un casque immersif Windows Mixed Reality, affectez le focus d’entrée à la réalité mixte en plaçant sur l’appareil ou en utilisant la combinaison de touches Windows + Y.To use keyboard input while wearing a Windows Mixed Reality immersive headset, assign input focus to mixed reality by putting on the device or using the Windows Key + Y keyboard combination. Gardez à l’esprit que les applications destinées à HoloLens doivent fournir des fonctionnalités sans que ces appareils soient attachés.Keep in mind that apps intended for HoloLens must provide functionality without these devices attached.

Notes

Les extraits de code de cet article illustrent actuellement l’utilisation de C++/CX au lieu des/WinRT C++ conformes à C + +17, tels qu’ils sont utilisés dans le modèle de projet holographique c++.The code snippets in this article currently demonstrate use of C++/CX rather than C++17-compliant C++/WinRT as used in the C++ holographic project template. Les concepts sont équivalents pour un projet C++/WinRT, bien que vous deviez traduire le code.The concepts are equivalent for a C++/WinRT project, though you will need to translate the code.

S’abonner aux événements d’entrée CoreWindowSubscribe for CoreWindow input events

Saisie au clavierKeyboard input

Dans le modèle d’application holographique Windows, nous incluons un gestionnaire d’événements pour l’entrée au clavier comme n’importe quelle autre application UWP.In the Windows Holographic app template, we include an event handler for keyboard input just like any other UWP app. Votre application utilise les données d’entrée au clavier de la même façon dans Windows Mixed Reality.Your app consumes keyboard input data the same way in Windows Mixed Reality.

À partir de AppView. cpp :From AppView.cpp:

// Register for keypress notifications.
   window->KeyDown +=
       ref new TypedEventHandler<CoreWindow^, KeyEventArgs^>(this, &AppView::OnKeyPressed);

    …

   // Input event handlers

   void AppView::OnKeyPressed(CoreWindow^ sender, KeyEventArgs^ args)
   {
       //
       // TODO: Respond to keyboard input here.
       //
   }

Entrée au clavier virtuelVirtual keyboard input

Pour les casques de bureau immersifs, vous pouvez prendre en charge des claviers virtuels rendus par Windows sur votre vue immersif en implémentant CoreTextEditContext.For immersive desktop headsets, you can support virtual keyboards rendered by Windows over your immersive view by implementing CoreTextEditContext. Cela permet à Windows de comprendre l’état de vos propres zones de texte de rendu d’application, de sorte que le clavier virtuel puisse contribuer correctement au texte.This lets Windows understand the state of your own app-rendered text boxes, so the virtual keyboard can correctly contribute to the text there.

Pour plus d’informations sur l’implémentation de la prise en charge de CoreTextEditContext, consultez l' exemple CoreTextEditContext.For more information on implementing CoreTextEditContext support, see the CoreTextEditContext sample.

Entrée de la sourisMouse Input

Vous pouvez également utiliser l’entrée de la souris, à nouveau via les gestionnaires d’événements d’entrée UWP CoreWindow.You can also use mouse input, again via the UWP CoreWindow input event handlers. Voici comment modifier le modèle d’application holographique Windows pour prendre en charge les clics de souris de la même façon que les gestes appuyés.Here's how to modify the Windows Holographic app template to support mouse clicks in the same way as pressed gestures. Une fois cette modification effectuée, un clic de souris tout en faisant passer un périphérique de casque immersif repositionne le cube.After making this modification, a mouse click while wearing an immersive headset device will reposition the cube.

Notes

Les applications UWP peuvent également obtenir des données brutes XY pour la souris à l’aide de l’API MouseDevice .UWP apps can also get raw XY data for the mouse by using the MouseDevice API.

Commencez par déclarer un nouveau gestionnaire OnPointerPressed dans AppView. h :Start by declaring a new OnPointerPressed handler in AppView.h:

protected:
       void OnPointerPressed(Windows::UI::Core::CoreWindow^ sender, Windows::UI::Core::PointerEventArgs^ args);

Dans AppView. cpp, ajoutez ce code à SetWindow :In AppView.cpp, add this code to SetWindow:

// Register for pointer pressed notifications.
   window->PointerPressed +=
       ref new TypedEventHandler<CoreWindow^, PointerEventArgs^>(this, &AppView::OnPointerPressed);

Placez ensuite cette définition pour OnPointerPressed en bas du fichier :Then put this definition for OnPointerPressed at the bottom of the file:

void AppView::OnPointerPressed(CoreWindow^ sender, PointerEventArgs^ args)
   {
       // Allow the user to interact with the holographic world using the mouse.
       if (m_main != nullptr)
       {
           m_main->OnPointerPressed();
       }
   }

Le gestionnaire d’événements que nous venons d’ajouter est un transfert vers la classe principale du modèle.The event handler we just added is a pass-through to the template main class. Modifions la classe principale pour prendre en charge ce transfert.Let's modify the main class to support this pass-through. Ajoutez cette déclaration de méthode publique au fichier d’en-tête :Add this public method declaration to the header file:

// Handle mouse input.
       void OnPointerPressed();

Vous aurez également besoin de cette variable de membre privé :You'll need this private member variable, as well:

// Keep track of mouse input.
       bool m_pointerPressed = false;

Enfin, nous allons mettre à jour la classe principale avec la nouvelle logique pour prendre en charge les clics de souris.Finally, we'll update the main class with new logic to support mouse clicks. Commencez par ajouter ce gestionnaire d’événements.Start by adding this event handler. Veillez à mettre à jour le nom de la classe :Make sure to update the class name:

void MyHolographicAppMain::OnPointerPressed()
   {
       m_pointerPressed = true;
   }

Maintenant, dans la méthode de mise à jour, remplacez la logique existante pour obtenir un pointeur à l’aide de ce qui suit :Now, in the Update method, replace the existing logic for getting a pointer pose with this:

SpatialInteractionSourceState^ pointerState = m_spatialInputHandler->CheckForInput();
   SpatialPointerPose^ pose = nullptr;
   if (pointerState != nullptr)
   {
       pose = pointerState->TryGetPointerPose(currentCoordinateSystem);
   }
   else if (m_pointerPressed)
   {
       pose = SpatialPointerPose::TryGetAtTimestamp(currentCoordinateSystem, prediction->Timestamp);
   }
   m_pointerPressed = false;

Recompilez et redéployez.Recompile and redeploy. Notez que le clic de souris va à présent repositionner le cube dans votre casque immersif ou HoloLens avec la souris Bluetooth associée.Notice that the mouse click will now reposition the cube in your immersive headset - or HoloLens with bluetooth mouse attached.

Prise en charge des contrôleurs de jeuGame controller support

Les contrôleurs de jeu peuvent être un moyen amusant et pratique de permettre à l’utilisateur de contrôler une expérience Windows Mixed Reality.Game controllers can be a fun and convenient way of allowing the user to control an immersive Windows Mixed Reality experience.

Ajoutez les déclarations de membre privées suivantes à la classe d’en-tête de votre fichier principal :add the following private member declarations to the header class for your main file:

// Recognize gamepads that are plugged in after the app starts.
       void OnGamepadAdded(Platform::Object^, Windows::Gaming::Input::Gamepad^ args);
// Stop looking for gamepads that are unplugged.
       void OnGamepadRemoved(Platform::Object^, Windows::Gaming::Input::Gamepad^ args);
Windows::Foundation::EventRegistrationToken                     m_gamepadAddedEventToken;
       Windows::Foundation::EventRegistrationToken                     m_gamepadRemovedEventToken;
// Keeps track of a gamepad and the state of its A button.
       struct GamepadWithButtonState
       {
           Windows::Gaming::Input::Gamepad^ gamepad;
           bool buttonAWasPressedLastFrame = false;
       };
       std::vector<GamepadWithButtonState>                             m_gamepads;

Initialisez les événements de manette de main et tous les boîtiers de connexion actuellement attachés dans le constructeur de votre classe principale :Initialize gamepad events, and any gamepads that are currently attached, in the constructor for your main class:

// If connected, a game controller can also be used for input.
   m_gamepadAddedEventToken = Gamepad::GamepadAdded +=
       ref new EventHandler<Gamepad^>(
           bind(&$safeprojectname$Main::OnGamepadAdded, this, _1, _2)
           );
m_gamepadRemovedEventToken = Gamepad::GamepadRemoved +=
       ref new EventHandler<Gamepad^>(
           bind(&$safeprojectname$Main::OnGamepadRemoved, this, _1, _2)
           );
for (auto const& gamepad : Gamepad::Gamepads)
   {
       OnGamepadAdded(nullptr, gamepad);
   }

Ajoutez ces gestionnaires d’événements à votre classe principale.Add these event handlers to your main class. Veillez à mettre à jour le nom de la classe :Make sure to update the class name:

void MyHolographicAppMain::OnGamepadAdded(Object^, Gamepad^ args)
   {
       for (auto const& gamepadWithButtonState : m_gamepads)
       {
           if (args == gamepadWithButtonState.gamepad)
           {
               // This gamepad is already in the list.
               return;
           }
       }
       m_gamepads.push_back({ args, false });
   }
void MyHolographicAppMain::OnGamepadRemoved(Object^, Gamepad^ args)
   {
       m_gamepads.erase(
           std::remove_if(m_gamepads.begin(), m_gamepads.end(), [&](GamepadWithButtonState& gamepadWithState)
               {
                   return gamepadWithState.gamepad == args;
               }),
           m_gamepads.end());
   }

Enfin, mettez à jour la logique d’entrée pour reconnaître les modifications de l’état du contrôleur.Finally, update the input logic to recognize changes in controller state. Ici, nous utilisons la même m_pointerPressed variable traitée dans la section ci-dessus pour ajouter des événements de souris.Here, we use the same m_pointerPressed variable discussed in the section above for adding mouse events. Ajoutez-la à la méthode Update, juste avant l’emplacement où elle recherche le SpatialPointerPose :Add this to the Update method, just before where it checks for the SpatialPointerPose:

// Check for new input state since the last frame.
   for (auto& gamepadWithButtonState : m_gamepads)
   {
       bool buttonDownThisUpdate = ((gamepadWithButtonState.gamepad->GetCurrentReading().Buttons & GamepadButtons::A) == GamepadButtons::A);
       if (buttonDownThisUpdate && !gamepadWithButtonState.buttonAWasPressedLastFrame)
       {
           m_pointerPressed = true;
       }
       gamepadWithButtonState.buttonAWasPressedLastFrame = buttonDownThisUpdate;
   }
// For context.
   SpatialInteractionSourceState^ pointerState = m_spatialInputHandler->CheckForInput();
   SpatialPointerPose^ pose = nullptr;
   if (pointerState != nullptr)
   {
       pose = pointerState->TryGetPointerPose(currentCoordinateSystem);
   }
   else if (m_pointerPressed)
   {
       pose = SpatialPointerPose::TryGetAtTimestamp(currentCoordinateSystem, prediction->Timestamp);
   }
   m_pointerPressed = false;

N’oubliez pas d’annuler l’inscription des événements lors du nettoyage de la classe principale :Don't forget to unregister the events when cleaning up the main class:

if (m_gamepadAddedEventToken.Value != 0)
   {
       Gamepad::GamepadAdded -= m_gamepadAddedEventToken;
   }
   if (m_gamepadRemovedEventToken.Value != 0)
   {
       Gamepad::GamepadRemoved -= m_gamepadRemovedEventToken;
   }

Recompilez et redéployez.Recompile, and redeploy. Vous pouvez maintenant attacher un contrôleur de jeu, ou le coupler, et l’utiliser pour repositionner le cube en rotation.You can now attach, or pair, a game controller and use it to reposition the spinning cube.

Indications importantes pour l’entrée au clavier et à la sourisImportant guidelines for keyboard and mouse input

Il existe quelques différences clés dans la façon dont ce code peut être utilisé sur Microsoft HoloLens, qui est un appareil qui s’appuie principalement sur l’entrée d’utilisateur naturelle, par rapport à ce qui est disponible sur un PC Windows Mixed Reality.There are some key differences in how this code can be used on Microsoft HoloLens – which is a device that relies primarily on natural user input – versus what is available on a Windows Mixed Reality-enabled PC.

  • Vous ne pouvez pas vous appuyer sur l’entrée du clavier ou de la souris.You can’t rely on keyboard or mouse input to be present. Toutes les fonctionnalités de votre application doivent fonctionner avec le regard, le geste et l’entrée vocale.All of your app's functionality must work with gaze, gesture, and speech input.
  • Lorsqu’un clavier Bluetooth est attaché, il peut être utile d’activer l’entrée au clavier pour tout texte que votre application peut demander.When a Bluetooth keyboard is attached, it can be helpful to enable keyboard input for any text that your app might ask for. Il peut s’agir d’un excellent complément pour la dictée, par exemple.This can be a great supplement for dictation, for example.
  • Lorsqu’il s’agit de concevoir votre application, ne vous fiez pas (par exemple) aux contrôles WASD et Mouse pour votre jeu.When it comes to designing your app, don’t rely on (for example) WASD and mouse look controls for your game. HoloLens est conçu pour permettre à l’utilisateur de parcourir la salle.HoloLens is designed for the user to walk around the room. Dans ce cas, l’utilisateur contrôle directement l’appareil photo.In this case, the user controls the camera directly. Une interface pour la conduite de l’appareil photo autour de la salle avec des contrôles de déplacement/d’apparence n’offre pas la même expérience.An interface for driving the camera around the room with move/look controls won't provide the same experience.
  • L’entrée au clavier est un excellent moyen de contrôler le débogage de votre application ou du moteur de jeu, en particulier dans la mesure où l’utilisateur n’est pas obligé d’utiliser le clavier.Keyboard input is an excellent way to control your app or game engine debugging, especially since the user won't be required to use the keyboard. Son câblage est identique à celui que vous utilisez avec les API d’événement CoreWindow.Wiring it up is the same as you're used to, with CoreWindow event APIs. Dans ce scénario, vous pouvez choisir d’implémenter un moyen de configurer votre application pour acheminer les événements de clavier vers un mode « en entrée de débogage uniquement » pendant vos sessions de débogage.In this scenario, you might choose to implement a way to configure your app to route keyboard events to a "debug input only" mode during your debug sessions.
  • Les contrôleurs Bluetooth fonctionnent également.Bluetooth controllers work as well.

Voir aussiSee also