Création d’un fournisseur de données système d’entrée — MRTK2
Le système d’entrée Mixed Reality Toolkit est un système extensible permettant de prendre en charge les périphériques d’entrée. Pour ajouter la prise en charge d’une nouvelle plateforme matérielle, un fournisseur de données d’entrée personnalisé peut être nécessaire.
Cet article explique comment créer des fournisseurs de données personnalisés, également appelés gestionnaires d’appareils, pour le système d’entrée. L’exemple de code présenté ici provient de .WindowsMixedRealityDeviceManager
Le code complet utilisé dans cet exemple se trouve dans le dossier MRTK/Providers/WindowsMixedReality.
Structure de l’espace de noms et des dossiers
Les fournisseurs de données peuvent être distribués en tant que module complémentaire tiers ou dans le cadre de Microsoft Mixed Reality Toolkit. Le processus d’approbation des soumissions de nouveaux fournisseurs de données à MRTK variera au cas par cas et sera communiqué au moment de la proposition initiale.
Important
Si un fournisseur de données système d’entrée est soumis au référentiel Mixed Reality Toolkit, l’espace de noms doit commencer par Microsoft.MixedReality.Toolkit (par exemple, Microsoft.MixedReality.Toolkit.WindowsMixedReality) et le code doit se trouver dans un dossier sous MRTK/Providers (par exemple, MRTK/Providers/WindowsMixedReality).
Espace de noms
Les fournisseurs de données doivent disposer d’un espace de noms pour atténuer les collisions de noms potentielles. Il est recommandé que l’espace de noms inclue les composants suivants.
- Nom de la société
- Domaine de fonctionnalité
Par exemple, un fournisseur de données d’entrée créé par l’entreprise Contoso peut être « Contoso.MixedReality.Toolkit.Input ».
Structure de dossiers recommandée
Il est recommandé que le code source des fournisseurs de données soit retardé dans une hiérarchie de dossiers, comme illustré dans l’image suivante.
Là où ContosoInput contient l’implémentation du fournisseur de données, le dossier Editor contient l’inspecteur (et tout autre code spécifique à l’éditeur Unity), le dossier Textures contient des images des contrôleurs pris en charge et Profiles contient un ou plusieurs profils prédéfinits.
Notes
Certaines images de contrôleur courantes se trouvent dans le dossier MixedRealityToolkit\StandardAssets\Textures.
Implémenter le fournisseur de données
Spécifier l’héritage de l’interface et/ou de la classe de base
Tous les fournisseurs de données du système d’entrée doivent implémenter l’interface IMixedRealityInputDeviceManager , qui spécifie les fonctionnalités minimales requises par le système d’entrée. La base MRTK inclut la BaseInputDeviceManager classe qui fournit une implémentation par défaut de cette fonctionnalité requise. Pour les appareils qui s’appuient sur la classe UInput d’Unity, la UnityJoystickManager classe peut être utilisée comme classe de base.
Notes
Les BaseInputDeviceManager classes et UnityJoystickManager fournissent l’implémentation requise IMixedRealityInputDeviceManager .
public class WindowsMixedRealityDeviceManager :
BaseInputDeviceManager,
IMixedRealityCapabilityCheck
{ }
IMixedRealityCapabilityCheckest utilisé par leWindowsMixedRealityDeviceManagerpour indiquer qu’il fournit la prise en charge d’un ensemble de fonctionnalités d’entrée, en particulier les mains articulées, les mains de mouvement du regard et les contrôleurs de mouvement.
Appliquer l’attribut MixedRealityDataProvider
Une étape clé de la création d’un fournisseur de données système d’entrée consiste à appliquer l’attribut MixedRealityDataProvider à la classe . Cette étape permet de définir le profil et la ou les plateformes par défaut pour le fournisseur, lorsqu’elle est sélectionnée dans le profil système d’entrée.
[MixedRealityDataProvider(
typeof(IMixedRealityInputSystem),
SupportedPlatforms.WindowsUniversal,
"Windows Mixed Reality Device Manager")]
public class WindowsMixedRealityDeviceManager :
BaseInputDeviceManager,
IMixedRealityCapabilityCheck
{ }
Implémenter les méthodes IMixedRealityDataProvider
Une fois la classe définie, l’étape suivante consiste à fournir l’implémentation de l’interface IMixedRealityDataProvider .
Notes
La BaseInputDeviceManager classe, via la BaseService classe , fournit uniquement des implémentations vides pour IMixedRealityDataProvider les méthodes. Les détails de ces méthodes sont généralement spécifiques au fournisseur de données.
Les méthodes qui doivent être implémentées par le fournisseur de données sont les suivantes :
Destroy()Disable()Enable()Initialize()Reset()Update()
Implémenter la logique du fournisseur de données
L’étape suivante consiste à ajouter la logique de gestion des périphériques d’entrée, y compris les contrôleurs à prendre en charge.
Implémenter les classes de contrôleur
L’exemple de définit WindowsMixedRealityDeviceManager et implémente les classes de contrôleur suivantes.
Le code source de chacune de ces classes se trouve dans le dossier MRTK/Providers/WindowsMixedReality.
- WindowsMixedRealityArticulatedHand.cs
- WindowsMixedRealityController.cs
- WindowsMixedRealityGGVHand.cs
Notes
Tous les gestionnaires d’appareils ne prennent pas en charge plusieurs types de contrôleurs.
Appliquer l’attribut MixedRealityController
Ensuite, appliquez l’attribut MixedRealityController à la classe . Cet attribut spécifie le type de contrôleur (par exemple, main articulée), la main (par exemple, gauche ou droite) et une image de contrôleur facultative.
[MixedRealityController(
SupportedControllerType.WindowsMixedReality,
new[] { Handedness.Left, Handedness.Right },
"StandardAssets/Textures/MotionController")]
{ }
Configurer les mappages d’interaction
L’étape suivante consiste à définir l’ensemble des mappages d’interaction pris en charge par le contrôleur. Pour les appareils qui reçoivent leurs données via la classe Input d’Unity, l’outil de mappage de contrôleur est une ressource utile pour confirmer les mappages d’axes et de boutons corrects à affecter aux interactions.
L’exemple suivant est abrégé à partir de la GenericOpenVRController classe , située dans le dossier MRTK/Providers/OpenVR.
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),
};
Notes
La ControllerMappingLibrary classe fournit des constantes symboliques pour les définitions d’axe d’entrée et de bouton Unity.
Déclencher des événements de notification
Pour permettre aux applications de répondre aux entrées de l’utilisateur, le fournisseur de données déclenche des événements de notification correspondant aux changements d’état du contrôleur, comme défini dans les IMixedRealityInputHandler interfaces et IMixedRealityInputHandler<T> .
Pour les contrôles de type numérique (bouton), déclenchez les événements OnInputDown et OnInputUp.
// inputAction is the input event that is to be raised.
if (interactionSourceState.touchpadPressed)
{
InputSystem?.RaiseOnInputDown(InputSource, ControllerHandedness, inputAction);
}
else
{
InputSystem?.RaiseOnInputUp(InputSource, ControllerHandedness, inputAction);
}
Pour les contrôles analogiques (par exemple, position du pavé tactile), l’événement InputChanged doit être déclenché.
InputSystem?.RaisePositionInputChanged(InputSource, ControllerHandedness, interactionMapping.MixedRealityInputAction, interactionSourceState.touchpadPosition);
Ajouter l’instrumentation Unity Profiler
Les performances sont essentielles dans les applications de réalité mixte. Chaque composant ajoute une certaine surcharge pour laquelle les applications doivent prendre en compte. À cette fin, il est important que tous les fournisseurs de données d’entrée contiennent l’instrumentation Unity Profiler dans la boucle interne et les chemins de code fréquemment utilisés.
Il est recommandé d’implémenter le modèle utilisé par MRTK lors de l’instrumentation de fournisseurs personnalisés.
private static readonly ProfilerMarker GetOrAddControllerPerfMarker = new ProfilerMarker("[MRTK] WindowsMixedRealityDeviceManager.GetOrAddController");
private async void GetOrAddController(InteractionSourceState interactionSourceState)
{
using (GetOrAddControllerPerfMarker.Auto())
{
// Code to be measured.
}
}
Notes
Le nom utilisé pour identifier le marqueur du profileur est arbitraire. MRTK utilise le modèle suivant.
« [product] className.methodName - optional remarque »
Il est recommandé que les fournisseurs de données personnalisés suivent un modèle similaire pour simplifier l’identification de composants et de méthodes spécifiques lors de l’analyse des traces.
Créer le profil et l’inspecteur
Dans Mixed Reality Toolkit, les fournisseurs de données sont configurés à l’aide de profils.
Les fournisseurs de données avec des options de configuration supplémentaires (par exemple , InputSimulationService) doivent créer un profil et un inspecteur pour permettre aux clients de modifier le comportement en fonction des besoins de l’application.
Le code complet de l’exemple de cette section se trouve dans mrTK. Dossier Services/InputSimulation.
Définir le profil
Le contenu du profil doit miroir les propriétés accessibles de l’observateur (par exemple, intervalle de mise à jour). Toutes les propriétés configurables par l’utilisateur définies dans chaque interface doivent être contenues avec le profil.
[CreateAssetMenu(
menuName = "Mixed Reality Toolkit/Profiles/Mixed Reality Simulated Input Profile",
fileName = "MixedRealityInputSimulationProfile",
order = (int)CreateProfileMenuItemIndices.InputSimulation)]
public class MixedRealityInputSimulationProfile : BaseMixedRealityProfile
{ }
L’attribut CreateAssetMenu peut être appliqué à la classe de profil pour permettre aux clients de créer un profil instance à l’aide du menu Créer des > ressources > Mixed Reality Toolkit Profiles>.
Implémenter l’inspecteur
Les inspecteurs de profil sont l’interface utilisateur permettant de configurer et d’afficher le contenu du profil. Chaque inspecteur de profil doit étendre la classe BaseMixedRealityToolkitConfigurationProfileInspector .
[CustomEditor(typeof(MixedRealityInputSimulationProfile))]
public class MixedRealityInputSimulationProfileInspector : BaseMixedRealityToolkitConfigurationProfileInspector
{ }
L’attribut CustomEditor indique à Unity le type de ressource auquel l’inspecteur s’applique.
Créer une ou plusieurs définitions d’assembly
Mixed Reality Toolkit utilise des fichiers de définition d’assembly (.asmdef) pour spécifier des dépendances entre les composants et pour aider Unity à réduire le temps de compilation.
Il est recommandé de créer des fichiers de définition d’assembly pour tous les fournisseurs de données et leurs composants d’éditeur.
À l’aide de la structure de dossiers dans l’exemple précédent, il existe deux fichiers .asmdef pour le fournisseur de données ContosoInput.
La première définition d’assembly concerne le fournisseur de données. Pour cet exemple, il s’appelle ContosoInput et se trouve dans le dossier ContosoInput de l’exemple. Cette définition d’assembly doit spécifier une dépendance vis-à-vis de Microsoft.MixedReality.Toolkit et de tous les autres assemblys dont elle dépend.
La définition de l’assembly ContosoInputEditor spécifie l’inspecteur de profil et tout code spécifique à l’éditeur. Ce fichier doit se trouver dans le dossier racine du code de l’éditeur. Dans cet exemple, le fichier se trouve dans le dossier ContosoInput\Editor. Cette définition d’assembly contient une référence à l’assembly ContosoInput, ainsi que :
- Microsoft.MixedReality.Toolkit
- Microsoft.MixedReality.Toolkit.Editor.Inspectors
- Microsoft.MixedReality.Toolkit.Editor.Utilities
Inscrire le fournisseur de données
Une fois créé, le fournisseur de données peut être inscrit auprès du système d’entrée et être utilisé dans l’application.
Emballage et distribution
Les fournisseurs de données distribués en tant que composants tiers ont les détails spécifiques de l’empaquetage et de la distribution laissés à la préférence du développeur. La solution la plus courante consistera probablement à générer un fichier .unitypackage et à le distribuer via unity Asset Store.
Si un fournisseur de données est envoyé et accepté dans le cadre du package Microsoft Mixed Reality Toolkit, l’équipe Microsoft MRTK le packagera et le distribuera dans le cadre des offres MRTK.