Tastatur-, Maus- und Controllereingaben in DirectXKeyboard, mouse, and controller input in DirectX

Hinweis

Dieser Artikel bezieht sich auf die älteren WinRT-APIs.This article relates to the legacy WinRT native APIs. Bei neuen nativen App-Projekten wird die Verwendung der openxr-API empfohlen.For new native app projects, we recommend using the OpenXR API.

Tastaturen, Mäuse und Spielcontroller können als nützliche Formen der Eingabe für Windows Mixed Reality-Geräte dienen.Keyboards, mice, and game controllers can all be useful forms of input for Windows Mixed Reality devices. Bluetooth-Tastaturen und-Mäuse werden sowohl in hololens unterstützt als auch beim Debuggen Ihrer APP oder als Alternative Form der Eingabe.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 unterstützt auch immersive Headsets, die an PCs angeschlossen sind, bei denen Mäuse, Tastaturen und Spielcontroller in der Vergangenheit die Norm waren.Windows Mixed Reality also supports immersive headsets attached to PCs - where mice, keyboards, and game controllers have historically been the norm.

Um Tastatureingaben in hololens zu verwenden, koppeln Sie eine Bluetooth-Tastatur mit Ihrem Gerät, oder verwenden Sie die virtuelle Eingabe über das Windows-Geräte Portal.To use keyboard input on HoloLens, pair a Bluetooth keyboard to your device or use virtual input via the Windows Device Portal. Wenn Sie Tastatureingaben beim Durchführen eines Windows Mixed Reality-immersiven Headsets verwenden möchten, weisen Sie der gemischten Realität den Eingabefokus zu, indem Sie das Gerät platzieren oder die Tastenkombination Windows-Taste + Y verwenden.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. Beachten Sie, dass apps, die für hololens vorgesehen sind, Funktionen ohne angehängte Geräte bereitstellen müssen.Keep in mind that apps intended for HoloLens must provide functionality without these devices attached.

Hinweis

Die Code Ausschnitte in diesem Artikel veranschaulichen derzeit die Verwendung von C++/CX anstelle von C + +17-kompatiblen C++/WinRT, wie Sie in der C++ Holographic-Projektvorlageverwendet werden.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. Die Konzepte sind äquivalent zu einem C++/WinRT-Projekt. Sie müssen jedoch den Code übersetzen.The concepts are equivalent for a C++/WinRT project, though you will need to translate the code.

Abonnieren von corewindow-Eingabe EreignissenSubscribe for CoreWindow input events

TastatureingabeKeyboard input

In der Windows Holographic-App-Vorlage fügen wir einen Ereignishandler für Tastatureingaben wie jede andere UWP-App ein.In the Windows Holographic app template, we include an event handler for keyboard input just like any other UWP app. Ihre APP beansprucht Tastatureingabe Daten in Windows Mixed Reality auf dieselbe Weise.Your app consumes keyboard input data the same way in Windows Mixed Reality.

Aus 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.
       //
   }

Virtuelle TastatureingabeVirtual keyboard input

Bei immersiven Desktop-Headsets können Sie durch die Implementierung von coretexteditcontext virtuelle Tastaturen, die von Windows gerendert werden, in ihrer immersiven Ansicht unterstützen.For immersive desktop headsets, you can support virtual keyboards rendered by Windows over your immersive view by implementing CoreTextEditContext. Dadurch kann Windows den Zustand ihrer eigenen, von der APP gerenderten Textfelder verstehen, sodass die virtuelle Tastatur ordnungsgemäß zum Text beitragen kann.This lets Windows understand the state of your own app-rendered text boxes, so the virtual keyboard can correctly contribute to the text there.

Weitere Informationen zum Implementieren der coretexteditcontext-Unterstützung finden Sie im coretexteditcontext-Beispiel.For more information on implementing CoreTextEditContext support, see the CoreTextEditContext sample.

MauseingabeMouse Input

Sie können auch über die Eingabe Ereignishandler von UWP corewindow auch Maus Eingaben verwenden.You can also use mouse input, again via the UWP CoreWindow input event handlers. Im folgenden wird erläutert, wie Sie die Windows Holographic-App-Vorlage ändern, um Mausklicks auf die gleiche Weise wie gedrückte Gesten zu unterstützen.Here's how to modify the Windows Holographic app template to support mouse clicks in the same way as pressed gestures. Nachdem Sie diese Änderung vorgenommen haben, wird der Cube durch einen Mausklick beim Ausführen eines immersiven Headset-Geräts neu positioniert.After making this modification, a mouse click while wearing an immersive headset device will reposition the cube.

Hinweis

UWP-Apps können auch unformatierte XY-Daten für die Maus mit der MouseDevice -API erhalten.UWP apps can also get raw XY data for the mouse by using the MouseDevice API.

Beginnen Sie mit dem Deklarieren eines neuen onpointerpressed-Handlers in 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);

Fügen Sie in appview. cpp den folgenden Code zu SetWindow hinzu:In AppView.cpp, add this code to SetWindow:

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

Fügen Sie dann diese Definition für "onpointerpressed" am Ende der Datei ein: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();
       }
   }

Der soeben hinzugefügte Ereignishandler ist eine Pass-Through-Funktion für die Hauptklasse der Vorlage.The event handler we just added is a pass-through to the template main class. Ändern wir nun die Hauptklasse, um diese Pass-Through-Unterstützung zu unterstützen.Let's modify the main class to support this pass-through. Fügen Sie diese Deklaration der öffentlichen Methode der Header Datei hinzu:Add this public method declaration to the header file:

// Handle mouse input.
       void OnPointerPressed();

Sie benötigen auch diese private Member-Variable:You'll need this private member variable, as well:

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

Zum Schluss aktualisieren wir die Hauptklasse mit neuer Logik zur Unterstützung von Mausklicks.Finally, we'll update the main class with new logic to support mouse clicks. Beginnen Sie mit dem Hinzufügen dieses Ereignis Handlers.Start by adding this event handler. Stellen Sie sicher, dass Sie den Klassennamen aktualisieren:Make sure to update the class name:

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

Ersetzen Sie nun in der Update-Methode die vorhandene Logik, um eine Zeiger Pose mit folgenden Informationen zu erhalten: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;

Neukompilieren und erneut bereitstellen.Recompile and redeploy. Beachten Sie, dass mit dem Maus Klick nun der Cube in Ihrem immersiven Headset oder hololens mit der Bluetooth-Maus angefügt wird.Notice that the mouse click will now reposition the cube in your immersive headset - or HoloLens with bluetooth mouse attached.

Spiele Controller UnterstützungGame controller support

Spiele Controller können eine angenehme und bequeme Möglichkeit bieten, dem Benutzer zu ermöglichen, eine immersive Windows Mixed Reality-Darstellung zu steuern.Game controllers can be a fun and convenient way of allowing the user to control an immersive Windows Mixed Reality experience.

Fügen Sie der Header Klasse für Ihre Hauptdatei die folgenden privaten Member-Deklarationen hinzu: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;

Initialisieren Sie Gamepad-Ereignisse und alle derzeit angefügten Gamepads im Konstruktor für Ihre Hauptklasse: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);
   }

Fügen Sie diese Ereignishandler ihrer Hauptklasse hinzu.Add these event handlers to your main class. Stellen Sie sicher, dass Sie den Klassennamen aktualisieren: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());
   }

Aktualisieren Sie schließlich die Eingabe Logik, um Änderungen im Controller Zustand zu erkennen.Finally, update the input logic to recognize changes in controller state. Hier verwenden wir die gleiche m_pointerPressed Variable, die im obigen Abschnitt zum Hinzufügen von Mausereignissen erläutert wurde.Here, we use the same m_pointerPressed variable discussed in the section above for adding mouse events. Fügen Sie diese der Update-Methode hinzu, kurz bevor Sie die Anwendung auf spatialpointerpose überprüft: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;

Vergessen Sie nicht, die Registrierung der Ereignisse beim Bereinigen der Hauptklasse aufzuheben: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;
   }

Neukompilieren und erneut bereitstellen.Recompile, and redeploy. Sie können jetzt einen Spielcontroller anfügen oder koppeln und ihn verwenden, um den drehenden Cube neu zu positionieren.You can now attach, or pair, a game controller and use it to reposition the spinning cube.

Wichtige Richtlinien für Tastatur-und Maus EingabenImportant guidelines for keyboard and mouse input

Es gibt einige wichtige Unterschiede bei der Verwendung dieses Codes für Microsoft hololens – bei dem es sich um ein Gerät handelt, das hauptsächlich auf natürlichen Benutzereingaben basiert – im Vergleich zu den Funktionen, die auf einem Windows Mixed Reality-fähigen PC verfügbar sind.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.

  • Sie können sich nicht darauf verlassen, dass Tastatur-oder Maus Eingaben vorhanden sind.You can’t rely on keyboard or mouse input to be present. Alle Funktionen Ihrer APP müssen mit Blick, Gesten und Spracheingaben funktionieren.All of your app's functionality must work with gaze, gesture, and speech input.
  • Wenn eine Bluetooth-Tastatur angefügt wird, kann es hilfreich sein, Tastatureingaben für jeden Text zu aktivieren, der von Ihrer APP angefordert werden kann.When a Bluetooth keyboard is attached, it can be helpful to enable keyboard input for any text that your app might ask for. Dies kann z. b. eine hervor artige Ergänzung zum Diktat darstellen.This can be a great supplement for dictation, for example.
  • Wenn Sie Ihre APP entwerfen möchten, verlassen Sie sich nicht auf (z. b.) WASD-und Mauszeiger-Steuerelemente für Ihr Spiel.When it comes to designing your app, don’t rely on (for example) WASD and mouse look controls for your game. Hololens ist dafür konzipiert, dass der Benutzer den Raum durchläuft.HoloLens is designed for the user to walk around the room. In diesem Fall steuert der Benutzer die Kamera direkt.In this case, the user controls the camera directly. Eine Schnittstelle zum Steuern der Kamera um den Raum mit Verschiebe-und Bild-Steuerelementen bietet nicht die gleiche Umgebung.An interface for driving the camera around the room with move/look controls won't provide the same experience.
  • Tastatureingaben sind eine hervorragende Möglichkeit, um das Debuggen Ihrer APP-oder Spiel-Engine zu steuern, insbesondere, da der Benutzer die Tastatur nicht verwenden muss.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. Die Verknüpfung ist identisch mit der Verwendung von corewindow-Ereignis-APIs.Wiring it up is the same as you're used to, with CoreWindow event APIs. In diesem Szenario können Sie eine Möglichkeit implementieren, um Ihre APP so zu konfigurieren, dass Tastatur Ereignisse während der Debugsitzungen an den Modus "nur debugeingabe" weitergeleitet werden.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.
  • Bluetooth-Controller sind ebenfalls funktionsfähig.Bluetooth controllers work as well.

Weitere InformationenSee also