Erstellen eines Eingabesystemdatenanbieters – MRTK2
Das Mixed Reality-Toolkit-Eingabesystem ist ein erweiterbares System zum Aktivieren der Unterstützung von Eingabegeräten. Um Unterstützung für eine neue Hardwareplattform hinzuzufügen, ist möglicherweise ein benutzerdefinierter Eingabedatenanbieter erforderlich.
In diesem Artikel wird beschrieben, wie Sie benutzerdefinierte Datenanbieter erstellen, die auch als Geräte-Manager bezeichnet werden, für das Eingabesystem. Der hier gezeigte Beispielcode stammt aus dem WindowsMixedRealityDeviceManager.
Den vollständigen Code, der in diesem Beispiel verwendet wird, finden Sie im Ordner MRTK/Providers/WindowsMixedReality.
Namespace- und Ordnerstruktur
Datenanbieter können als Drittanbieter-Add-On oder als Teil des Microsoft Mixed Reality Toolkits verteilt werden. Das Genehmigungsverfahren für übermittlungen neuer Datenanbieter an MRTK variiert von Fall zu Fall und wird zum Zeitpunkt des ursprünglichen Vorschlags mitgeteilt.
Wichtig
Wenn ein Eingabesystemdatenanbieter an das Mixed Reality Toolkit-Repository übermittelt wird, muss der Namespace mit Microsoft.MixedReality.Toolkit (z. B. Microsoft.MixedReality.Toolkit.WindowsMixedReality) beginnen, und der Code sollte sich in einem Ordner unter MRTK/Providers (z. B. MRTK/Providers/WindowsMixedReality) befinden.
Namespace
Datenanbieter müssen über einen Namespace verfügen, um potenzielle Namenskonflikte zu minimieren. Es wird empfohlen, dass der Namespace die folgenden Komponenten enthält.
- Unternehmensname
- Featurebereich
Beispielsweise kann ein vom Unternehmen Contoso erstellter Eingabedatenanbieter "Contoso.MixedReality.Toolkit.Input" sein.
Empfohlene Ordnerstruktur
Es wird empfohlen, den Quellcode für Datenanbieter in einer Ordnerhierarchie zu erstellen, wie in der folgenden Abbildung dargestellt.
Enthält ContosoInput die Implementierung des Datenanbieters, enthält der Ordner Editor den Inspektor (und jeden anderen spezifischen Unity-Editor-Code), der Ordner Textures Bilder der unterstützten Controller und Profile ein oder mehrere vorgefertigte Profile.
Hinweis
Einige gängige Controllerimages finden Sie im Ordner MixedRealityToolkit\StandardAssets\Textures.
Implementieren des Datenanbieters
Angeben der Schnittstellen- und/oder Basisklassenvererbung
Alle Eingabesystemdatenanbieter müssen die IMixedRealityInputDeviceManager -Schnittstelle implementieren, die die für das Eingabesystem erforderliche Mindestfunktionalität angibt. Die MRTK-Basis enthält die BaseInputDeviceManager -Klasse, die eine Standardimplementierung dieser erforderlichen Funktionalität bereitstellt. Für Geräte, die auf der UInput-Klasse von Unity aufbauen, kann die UnityJoystickManager -Klasse als Basisklasse verwendet werden.
Hinweis
Die BaseInputDeviceManager Klassen und UnityJoystickManager stellen die erforderliche IMixedRealityInputDeviceManager Implementierung bereit.
public class WindowsMixedRealityDeviceManager :
BaseInputDeviceManager,
IMixedRealityCapabilityCheck
{ }
IMixedRealityCapabilityCheckwird von verwendet,WindowsMixedRealityDeviceManagerum anzugeben, dass es eine Reihe von Eingabefunktionen unterstützt, insbesondere für artikulierte Hände, Blickgesten-Sprach-Hände und Motion-Controller.
Anwenden des MixedRealityDataProvider-Attributs
Ein wichtiger Schritt beim Erstellen eines Eingabesystemdatenanbieters besteht darin, das MixedRealityDataProvider -Attribut auf die -Klasse anzuwenden. Dieser Schritt ermöglicht das Festlegen des Standardprofils und der Plattform(en) für den Anbieter, wenn sie im Eingabesystemprofil ausgewählt sind.
[MixedRealityDataProvider(
typeof(IMixedRealityInputSystem),
SupportedPlatforms.WindowsUniversal,
"Windows Mixed Reality Device Manager")]
public class WindowsMixedRealityDeviceManager :
BaseInputDeviceManager,
IMixedRealityCapabilityCheck
{ }
Implementieren der IMixedRealityDataProvider-Methoden
Nachdem die -Klasse definiert wurde, besteht der nächste Schritt darin, die Implementierung der IMixedRealityDataProvider -Schnittstelle bereitzustellen.
Hinweis
Die BaseInputDeviceManager -Klasse stellt über die BaseService -Klasse nur leere Implementierungen für IMixedRealityDataProvider Methoden bereit. Die Details dieser Methoden sind in der Regel datenanbieterspezifisch.
Folgende Methoden sollten vom Datenanbieter implementiert werden:
Destroy()Disable()Enable()Initialize()Reset()Update()
Implementieren der Datenanbieterlogik
Der nächste Schritt besteht darin, die Logik zum Verwalten der Eingabegeräte hinzuzufügen, einschließlich aller controller, die unterstützt werden sollen.
Implementieren der Controllerklassen
Im Beispiel von WindowsMixedRealityDeviceManager werden die folgenden Controllerklassen definiert und implementiert.
Der Quellcode für jede dieser Klassen befindet sich im Ordner MRTK/Providers/WindowsMixedReality.
- WindowsMixedRealityArticulatedHand.cs
- WindowsMixedRealityController.cs
- WindowsMixedRealityGGVHand.cs
Hinweis
Nicht alle Geräte-Manager unterstützen mehrere Controllertypen.
Anwenden des MixedRealityController-Attributs
Wenden Sie als Nächstes das MixedRealityController -Attribut auf die -Klasse an. Dieses Attribut gibt den Controllertyp (z. B. artikulierte Hand), die Händigkeit (z. B. links oder rechts) und ein optionales Controllerbild an.
[MixedRealityController(
SupportedControllerType.WindowsMixedReality,
new[] { Handedness.Left, Handedness.Right },
"StandardAssets/Textures/MotionController")]
{ }
Konfigurieren der Interaktionszuordnungen
Der nächste Schritt besteht darin, den Satz von Interaktionszuordnungen zu definieren, die vom Controller unterstützt werden. Für Geräte, die ihre Daten über die Input-Klasse von Unity empfangen, ist das Controllerzuordnungstool eine hilfreiche Ressource, um die richtigen Achsen- und Schaltflächenzuordnungen zu bestätigen, die Interaktionen zugewiesen werden sollen.
Das folgende Beispiel wird von der -Klasse abgekürzt, die GenericOpenVRController sich im Ordner MRTK/Providers/OpenVR befindet.
public override MixedRealityInteractionMapping[] DefaultLeftHandedInteractions => new[]
{
// Controller Pose
new MixedRealityInteractionMapping(0, "Spatial Pointer", AxisType.SixDof, DeviceInputType.SpatialPointer, MixedRealityInputAction.None),
// Left Trigger Squeeze
new MixedRealityInteractionMapping(1, "Trigger Position", AxisType.SingleAxis, DeviceInputType.Trigger, ControllerMappingLibrary.AXIS_9),
// Left Trigger Press (Select)
new MixedRealityInteractionMapping(2, "Trigger Press (Select)", AxisType.Digital, DeviceInputType.TriggerPress, KeyCode.JoystickButton14),
};
Hinweis
Die ControllerMappingLibrary -Klasse stellt symbolische Konstanten für die Unity-Eingabeachsen- und Schaltflächendefinitionen bereit.
Auslösen von Benachrichtigungsereignissen
Damit Anwendungen auf Eingaben des Benutzers reagieren können, löst der Datenanbieter Benachrichtigungsereignisse aus, die controllerzustandsänderungen entsprechen, wie in den IMixedRealityInputHandler Schnittstellen und IMixedRealityInputHandler<T> definiert.
Lösen Sie für steuerelemente vom Typ digitale (Schaltflächen) die Ereignisse OnInputDown und OnInputUp aus.
// inputAction is the input event that is to be raised.
if (interactionSourceState.touchpadPressed)
{
InputSystem?.RaiseOnInputDown(InputSource, ControllerHandedness, inputAction);
}
else
{
InputSystem?.RaiseOnInputUp(InputSource, ControllerHandedness, inputAction);
}
Bei analogen Steuerelementen (z. B. Touchpadposition) sollte das InputChanged-Ereignis ausgelöst werden.
InputSystem?.RaisePositionInputChanged(InputSource, ControllerHandedness, interactionMapping.MixedRealityInputAction, interactionSourceState.touchpadPosition);
Hinzufügen der Unity Profiler-Instrumentierung
Die Leistung ist in Mixed Reality-Anwendungen von entscheidender Bedeutung. Jede Komponente fügt einen gewissen Mehraufwand hinzu, den Anwendungen berücksichtigen müssen. Zu diesem Zweck ist es wichtig, dass alle Eingabedatenanbieter die Unity Profiler-Instrumentierung in einer inneren Schleife enthalten und häufig Codepfade verwendet werden.
Es wird empfohlen, das muster zu implementieren, das von MRTK beim Instrumentieren benutzerdefinierter Anbieter verwendet wird.
private static readonly ProfilerMarker GetOrAddControllerPerfMarker = new ProfilerMarker("[MRTK] WindowsMixedRealityDeviceManager.GetOrAddController");
private async void GetOrAddController(InteractionSourceState interactionSourceState)
{
using (GetOrAddControllerPerfMarker.Auto())
{
// Code to be measured.
}
}
Hinweis
Der Name, der zum Identifizieren des Profilermarkers verwendet wird, ist beliebig. MRTK verwendet das folgende Muster.
"[product] className.methodName – optionaler Hinweis"
Es wird empfohlen, dass benutzerdefinierte Datenanbieter einem ähnlichen Muster folgen, um die Identifizierung bestimmter Komponenten und Methoden bei der Analyse von Ablaufverfolgungen zu vereinfachen.
Erstellen des Profils und des Inspektors
In Mixed Reality Toolkit werden Datenanbieter mithilfe von Profilen konfiguriert.
Datenanbieter mit zusätzlichen Konfigurationsoptionen (z. B. InputSimulationService) sollten ein Profil und einen Inspektor erstellen, damit Kunden das Verhalten so ändern können, dass es den Anforderungen der Anwendung am besten entspricht.
Den vollständigen Code für das Beispiel in diesem Abschnitt finden Sie im MRTK. Ordner "Services/InputSimulation".
Definieren des Profils
Profilinhalte sollten die verfügbaren Eigenschaften des Beobachters Spiegel (z. B. Updateintervall). Alle vom Benutzer konfigurierbaren Eigenschaften, die in jeder Schnittstelle definiert sind, sollten im Profil enthalten sein.
[CreateAssetMenu(
menuName = "Mixed Reality Toolkit/Profiles/Mixed Reality Simulated Input Profile",
fileName = "MixedRealityInputSimulationProfile",
order = (int)CreateProfileMenuItemIndices.InputSimulation)]
public class MixedRealityInputSimulationProfile : BaseMixedRealityProfile
{ }
Das CreateAssetMenu Attribut kann auf die Profilklasse angewendet werden, damit Kunden mithilfe des Menüs "Ressourcen > Mixed Reality Toolkitprofile > erstellen" > ein Profil instance erstellen können.
Implementieren des Inspektors
Profilinspektoren sind die Benutzeroberfläche zum Konfigurieren und Anzeigen von Profilinhalten. Jeder Profilinspektor sollte die BaseMixedRealityToolkitConfigurationProfileInspector-Klasse erweitern.
[CustomEditor(typeof(MixedRealityInputSimulationProfile))]
public class MixedRealityInputSimulationProfileInspector : BaseMixedRealityToolkitConfigurationProfileInspector
{ }
Das CustomEditor Attribut informiert Unity über den Typ des Medienobjekts, auf das der Inspektor angewendet wird.
Erstellen von Assemblydefinitionen
Mixed Reality Toolkit verwendet Assemblydefinitionsdateien (.asmdef), um Abhängigkeiten zwischen Komponenten anzugeben und Unity bei der Reduzierung der Kompilierungszeit zu unterstützen.
Es wird empfohlen, Assemblydefinitionsdateien für alle Datenanbieter und deren Editorkomponenten zu erstellen.
Unter Verwendung der Ordnerstruktur im vorherigen Beispiel wären zwei ASMDEF-Dateien für den Datenanbieter ContosoInput vorhanden.
Die erste Assemblydefinition gilt für den Datenanbieter. In diesem Beispiel heißt es ContosoInput und befindet sich im Ordner ContosoInput des Beispiels. Diese Assemblydefinition muss eine Abhängigkeit von Microsoft.MixedReality.Toolkit und allen anderen Assemblys angeben, von denen sie abhängt.
Die ContosoInputEditor-Assemblydefinition gibt den Profilinspektor und jeden editorspezifischen Code an. Diese Datei muss sich im Stammordner des Editorcodes befinden. In diesem Beispiel befindet sich die Datei im Ordner ContosoInput\Editor. Diese Assemblydefinition enthält einen Verweis auf die ContosoInput-Assembly sowie folgendes:
- Microsoft.MixedReality.Toolkit
- Microsoft.MixedReality.Toolkit.Editor.Inspectors
- Microsoft.MixedReality.Toolkit.Editor.Utilities
Registrieren des Datenanbieters
Nach der Erstellung kann der Datenanbieter beim Eingabesystem registriert und in der Anwendung verwendet werden.
Verpackung und Vertrieb
Datenanbieter, die als Komponenten von Drittanbietern verteilt werden, haben die spezifischen Details der Verpackung und Verteilung dem Wunsch des Entwicklers überlassen. Wahrscheinlich ist die gängigste Lösung das Generieren eines UNITY-Pakets und die Verteilung über den Unity Asset Store.
Wenn ein Datenanbieter als Teil des Microsoft Mixed Reality Toolkit-Pakets übermittelt und akzeptiert wird, packt und verteilt das Microsoft MRTK-Team ihn als Teil der MRTK-Angebote.