Tworzenie dostawcy danych systemu wejściowego — MRTK2

  • Artykuł

System wejściowy zestawu narzędzi Mixed Reality Toolkit jest rozszerzalnym systemem umożliwiającym obsługę urządzeń wejściowych. Aby dodać obsługę nowej platformy sprzętowej, może być wymagany niestandardowy dostawca danych wejściowych.

W tym artykule opisano sposób tworzenia niestandardowych dostawców danych, nazywanych również menedżerami urządzeń, dla systemu wejściowego. Przykładowy kod pokazany tutaj pochodzi z elementu WindowsMixedRealityDeviceManager.

Kompletny kod używany w tym przykładzie można znaleźć w folderze MRTK/Providers/WindowsMixedReality.

Przestrzeń nazw i struktura folderów

Dostawcy danych mogą być dystrybuowani jako dodatek innej firmy lub w ramach zestawu narzędzi Microsoft Mixed Reality Toolkit. Proces zatwierdzania przesyłania nowych dostawców danych do zestawu narzędzi MRTK będzie się różnić w zależności od przypadku i zostanie przekazany w momencie pierwotnego wniosku.

Ważne

Jeśli dostawca danych systemu wejściowego jest przesyłany do repozytorium zestawu narzędzi Mixed Reality, przestrzeń nazw musi zaczynać się od zestawu Narzędzi Microsoft.MixedReality.Toolkit (np. Microsoft.MixedReality.Toolkit.WindowsMixedReality) i kod powinien znajdować się w folderze poniżej zestawu NARZĘDZI MRTK/Providers (np. MRTK/Providers/WindowsMixedReality).

Przestrzeń nazw

Dostawcy danych muszą mieć przestrzeń nazw, aby wyeliminować potencjalne kolizje nazw. Zaleca się, aby przestrzeń nazw zawierała następujące składniki.

  • Nazwa firmy
  • Obszar funkcji

Na przykład dostawcą danych wejściowych utworzonym przez firmę Contoso może być "Contoso.MixedReality.Toolkit.Input".

Zaleca się, aby kod źródłowy dostawców danych został ułożone w hierarchii folderów, jak pokazano na poniższej ilustracji.

Przykładowa struktura folderów

Gdzie ContosoInput zawiera implementację dostawcy danych, folder Editor zawiera inspektora (i dowolny inny kod specyficzny dla edytora Aparatu Unity), folder Textures zawiera obrazy obsługiwanych kontrolerów, a profile zawierają co najmniej jeden wstępnie utworzony profil.

Uwaga

Niektóre typowe obrazy kontrolera można znaleźć w folderze MixedRealityToolkit\StandardAssets\Textures.

Implementowanie dostawcy danych

Określanie dziedziczenia interfejsu i/lub klasy bazowej

Wszyscy dostawcy danych systemu wejściowego IMixedRealityInputDeviceManager muszą zaimplementować interfejs, który określa minimalną funkcjonalność wymaganą przez system wejściowy. Podstawy zestawu narzędzi MRTK obejmują klasę BaseInputDeviceManager , która zapewnia domyślną implementację tej wymaganej funkcjonalności. W przypadku urządzeń, które bazują na klasie UInput aparatu Unity, UnityJoystickManager klasa może być używana jako klasa bazowa.

Uwaga

Klasy BaseInputDeviceManager i UnityJoystickManager zapewniają wymaganą IMixedRealityInputDeviceManager implementację.

public class WindowsMixedRealityDeviceManager :
    BaseInputDeviceManager,
    IMixedRealityCapabilityCheck
{ }

IMixedRealityCapabilityCheck element jest używany przez element WindowsMixedRealityDeviceManager , aby wskazać, że zapewnia obsługę zestawu funkcji wejściowych, w szczególności; wyrażanych rąk, rąk i gestów głosowych oraz kontrolerów ruchu.

Stosowanie atrybutu MixedRealityDataProvider

Kluczowym krokiem tworzenia dostawcy danych systemu wejściowego jest zastosowanie atrybutu MixedRealityDataProvider do klasy. Ten krok umożliwia ustawienie domyślnych profilów i platform dostawcy po wybraniu w profilu systemu wejściowego.

[MixedRealityDataProvider(
    typeof(IMixedRealityInputSystem),
    SupportedPlatforms.WindowsUniversal,
    "Windows Mixed Reality Device Manager")]
public class WindowsMixedRealityDeviceManager :
    BaseInputDeviceManager,
    IMixedRealityCapabilityCheck
{ }

Implementowanie metod IMixedRealityDataProvider

Po zdefiniowaniu klasy następnym krokiem jest zapewnienie implementacji interfejsu IMixedRealityDataProvider .

Uwaga

Klasa BaseInputDeviceManager za pośrednictwem BaseService klasy udostępnia tylko puste implementacje metod IMixedRealityDataProvider . Szczegóły tych metod są zwykle specyficzne dla dostawcy danych.

Metody, które powinny być implementowane przez dostawcę danych, to:

  • Destroy()
  • Disable()
  • Enable()
  • Initialize()
  • Reset()
  • Update()

Implementowanie logiki dostawcy danych

Następnym krokiem jest dodanie logiki do zarządzania urządzeniami wejściowymi, w tym wszystkich kontrolerów, które mają być obsługiwane.

Implementowanie klas kontrolerów

Przykład definiuje WindowsMixedRealityDeviceManager i implementuje następujące klasy kontrolera.

Kod źródłowy dla każdej z tych klas można znaleźć w folderze MRTK/Providers/WindowsMixedReality.

  • WindowsMixedRealityArticulatedHand.cs
  • WindowsMixedRealityController.cs
  • WindowsMixedRealityGGVHand.cs

Uwaga

Nie wszystkie menedżery urządzeń będą obsługiwać wiele typów kontrolerów.

Stosowanie atrybutu MixedRealityController

Następnie zastosuj MixedRealityController atrybut do klasy . Ten atrybut określa typ kontrolera (np. wyartykułowany ręka), ręcznie (np. w lewo lub po prawej) i opcjonalny obraz kontrolera.

[MixedRealityController(
    SupportedControllerType.WindowsMixedReality,
    new[] { Handedness.Left, Handedness.Right },
    "StandardAssets/Textures/MotionController")]
{ }

Konfigurowanie mapowań interakcji

Następnym krokiem jest zdefiniowanie zestawu mapowań interakcji obsługiwanych przez kontroler. W przypadku urządzeń, które odbierają dane za pośrednictwem klasy Input aparatu Unity, narzędzie do mapowania kontrolera jest przydatnym zasobem umożliwiającym potwierdzenie prawidłowych mapowań osi i przycisków w celu przypisania do interakcji.

Poniższy przykład jest skrócony z GenericOpenVRController klasy znajdującej się w folderze 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),
};

Uwaga

Klasa ControllerMappingLibrary udostępnia stałe symboliczne dla definicji osi wejściowej i przycisku aparatu Unity.

Zgłaszanie zdarzeń powiadomień

Aby umożliwić aplikacjom reagowanie na dane wejściowe od użytkownika, dostawca danych zgłasza zdarzenia powiadomień odpowiadające zmianom stanu kontrolera zgodnie z definicją w IMixedRealityInputHandler interfejsach i IMixedRealityInputHandler<T> .

W przypadku kontrolek typu cyfrowego (przycisk) zgłaszaj zdarzenia OnInputDown i 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);
}

W przypadku kontrolek analogowych (np. pozycja touchpadu) należy podnieść zdarzenie InputChanged.

InputSystem?.RaisePositionInputChanged(InputSource, ControllerHandedness, interactionMapping.MixedRealityInputAction, interactionSourceState.touchpadPosition);

Dodawanie instrumentacji profilera aparatu Unity

Wydajność ma kluczowe znaczenie w aplikacjach rzeczywistości mieszanej. Każdy składnik dodaje pewną ilość narzutów, dla których aplikacje muszą być uwzględniane. W tym celu ważne jest, aby wszyscy dostawcy danych wejściowych zawierali instrumentację profilera aparatu Unity w pętli wewnętrznej i często używane ścieżki kodu.

Zaleca się zaimplementowanie wzorca używanego przez zestaw narzędzi MRTK podczas instrumentowania dostawców niestandardowych.

        private static readonly ProfilerMarker GetOrAddControllerPerfMarker = new ProfilerMarker("[MRTK] WindowsMixedRealityDeviceManager.GetOrAddController");

        private async void GetOrAddController(InteractionSourceState interactionSourceState)
        {
            using (GetOrAddControllerPerfMarker.Auto())
            {
                // Code to be measured.
            }
        }

Uwaga

Nazwa używana do identyfikowania znacznika profilera jest dowolna. Zestaw narzędzi MRTK używa następującego wzorca.

"[product] className.methodName — opcjonalna uwaga"

Zaleca się, aby niestandardowi dostawcy danych postępowali zgodnie z podobnym wzorcem, aby ułatwić identyfikację określonych składników i metod podczas analizowania śladów.

Tworzenie profilu i inspektora

W Mixed Reality Toolkit dostawcy danych są skonfigurowani przy użyciu profilów.

Dostawcy danych z dodatkowymi opcjami konfiguracji (np. InputSimulationService) powinni utworzyć profil i inspektor, aby umożliwić klientom modyfikowanie zachowania zgodnie z potrzebami aplikacji.

Kompletny kod przykładu w tej sekcji można znaleźć w zestawie narzędzi MRTK. Folder Services/InputSimulation.

Definiowanie profilu

Zawartość profilu powinna odzwierciedlać dostępne właściwości obserwatora (np. interwał aktualizacji). Wszystkie konfigurowalne właściwości użytkownika zdefiniowane w każdym interfejsie powinny być zawarte w profilu.

[CreateAssetMenu(
    menuName = "Mixed Reality Toolkit/Profiles/Mixed Reality Simulated Input Profile",
    fileName = "MixedRealityInputSimulationProfile",
    order = (int)CreateProfileMenuItemIndices.InputSimulation)]
public class MixedRealityInputSimulationProfile : BaseMixedRealityProfile
{ }

Atrybut CreateAssetMenu można zastosować do klasy profilu, aby umożliwić klientom tworzenie wystąpienia profilu przy użyciu menu Tworzenie > zasobów > Mixed Reality Profile zestawu narzędzi>.

Implementowanie inspektora

Inspektorzy profilów to interfejs użytkownika służący do konfigurowania i wyświetlania zawartości profilu. Każdy inspektor profilu powinien rozszerzyć klasę BaseMixedRealityToolkitConfigurationProfileInspector .

[CustomEditor(typeof(MixedRealityInputSimulationProfile))]
public class MixedRealityInputSimulationProfileInspector : BaseMixedRealityToolkitConfigurationProfileInspector
{ }

Atrybut CustomEditor informuje aparat Unity o typie zasobu, do którego ma zastosowanie inspektor.

Tworzenie definicji zestawów

Mixed Reality Toolkit używa plików definicji zestawu (asmdef) do określania zależności między składnikami, a także pomaga aparatu Unity w skróceniu czasu kompilacji.

Zaleca się utworzenie plików definicji zestawu dla wszystkich dostawców danych i ich składników edytora.

Korzystając ze struktury folderów we wcześniejszym przykładzie, istnieją dwa pliki asmdef dla dostawcy danych ContosoInput.

Pierwsza definicja zestawu dotyczy dostawcy danych. W tym przykładzie zostanie ona nazwana ContosoInput i będzie znajdować się w folderze ContosoInput przykładu. Ta definicja zestawu musi określać zależność od zestawu Microsoft.MixedReality.Toolkit i innych zestawów, od których zależy.

Definicja zestawu ContosoInputEditor określi inspektora profilu i dowolny kod specyficzny dla edytora. Ten plik musi znajdować się w folderze głównym kodu edytora. W tym przykładzie plik zostanie umieszczony w folderze ContosoInput\Editor. Ta definicja zestawu będzie zawierać odwołanie do zestawu ContosoInput, a także:

  • Microsoft.MixedReality.Toolkit
  • Microsoft.MixedReality.Toolkit.Editor.Inspectors
  • Microsoft.MixedReality.Toolkit.Editor.Utilities

Rejestrowanie dostawcy danych

Po utworzeniu dostawca danych można zarejestrować w systemie wejściowym i być używany w aplikacji.

Zarejestrowani dostawcy danych systemu wejściowego

Pakowanie i dystrybucja

Dostawcy danych, którzy są dystrybuowani jako składniki innych firm, mają szczegółowe informacje dotyczące pakowania i dystrybucji pozostawione preferencjom dewelopera. Prawdopodobnie najbardziej typowym rozwiązaniem będzie wygenerowanie pakietu unitypackage i dystrybuowanie go za pośrednictwem magazynu zasobów aparatu Unity.

Jeśli dostawca danych zostanie przesłany i zaakceptowany jako część pakietu Microsoft Mixed Reality Toolkit, zespół zestawu narzędzi MRTK firmy Microsoft będzie pakował i rozpowszechniał go w ramach ofert zestawu narzędzi MRTK.

Zobacz też