入力システムデータプロバイダーの作成 — MRTK2

[アーティクル]
07/12/2023

Mixed Reality Toolkit 入力システムは、入力デバイスサポートを有効にするための拡張可能なシステムです。新しいハードウェアプラットフォームのサポートを追加するには、カスタムの入力データプロバイダーが必要になることがあります。

この記事ではカスタムのデータプロバイダーを作成する方法と、入力システムのためにデバイスマネージャーを呼び出す方法について説明します。ここで示すコード例は、WindowsMixedRealityDeviceManager からのものです。

この例で使用するコードの全体は、MRTK/Providers/WindowsMixedReality フォルダーにあります。

名前空間とフォルダー構造

データプロバイダーは、サードパーティのアドオンとして、または Microsoft Mixed Reality Toolkit の一部として配布できます。 MRTK への新しいデータプロバイダーの提出の承認プロセスは、ケースバイケースで異なり、最初の提案の時点で伝達されます。

重要

システムデータプロバイダーを Mixed Reality ツールキットリポジトリに送信する場合、名前空間は、Microsoft.MixedReality.Toolkit で始まる必要があり (例: Microsoft.MixedReality.Toolkit.WindowsMixedReality)、コードは MRTK/Providers (例: MRTK/Providers/WindowsMixedReality) 下のフォルダーに配置される必要があります。

名前空間

名前が競合する可能性を低減するために、データプロバイダーでは名前空間を使用する必要があります。名前空間には次の構成要素を含めることをお勧めします。

会社名
Feature area (機能領域)

たとえば、Contoso 社によって作成された入力データプロバイダーの場合は、"Contoso.MixedReality.Toolkit.Input" にすることができます。

推奨のフォルダー構造

次の図に示すように、データプロバイダーのソースコードをフォルダー階層で整理することをお勧めします。

フォルダー構造の例

ContosoInput にデータプロバイダーの実装が含まれる場合、[Editor] フォルダーにはインスペクター (および他の Unity エディターに特有のコード) が含まれ、[Textures] フォルダーにはサポートされているコントローラーのイメージが含まれ、[Profiles] には 1 つ以上の事前作成されたプロファイルが含まれます。

Note

いくつかの共通のコントローラーのイメージは、MixedRealityToolkit\StandardAssets\Textures フォルダーにあります。

データプロバイダーを実装する

インターフェイスと基底クラス継承のどちらかまたは両方を指定する

すべての入力システムデータプロバイダーにおいて、入力システムが必要とする最小の機能を指定する、IMixedRealityInputDeviceManager インターフェイスを実装する必要があります。 MRTK Foundation には、この必須機能の既定の実装を提供する BaseInputDeviceManager クラスが含まれています。 Unity の UInput クラスをベースとして構築されるデバイスの場合は、基底クラスとして UnityJoystickManager クラスを使用することができます。

Note

BaseInputDeviceManager クラスと UnityJoystickManager クラスは、必要な IMixedRealityInputDeviceManager の実装を提供しています。

public class WindowsMixedRealityDeviceManager :
    BaseInputDeviceManager,
    IMixedRealityCapabilityCheck
{ }

WindowsMixedRealityDeviceManager は IMixedRealityCapabilityCheck を使用することにより、一連の入力機能のサポート (具体的には、多関節ハンド、Gaze-Gesture-Voice の手ぶり、モーションコントローラー) を提供することを示しています。

MixedRealityDataProvider 属性を適用する

入力システムデータプロバイダーを作成する重要なステップは、MixedRealityDataProvider 属性をクラスに適用することです。このステップでは、プロバイダーの既定のプロファイルとプラットフォームを、入力システムプロファイルで選択することによって設定することができます。

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

IMixedRealityDataProvider メソッドを実装する

クラスを定義したら、次の手順として、IMixedRealityDataProvider インターフェイスの実装を提供します。

Note

BaseInputDeviceManager クラスは、BaseService クラスを介して、IMixedRealityDataProvider メソッドの空の実装のみ提供します。これらのメソッドの詳細は、通常はデータプロバイダーごとに異なります。

データプロバイダーで実装する必要があるメソッドは、次のとおりです。

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

データプロバイダーのロジックを実装する

次の手順は、サポート対象のすべてのコントローラーを含む、入力デバイスの管理のためのロジックを追加することです。

コントローラーのクラスを実装する

WindowsMixedRealityDeviceManager の例では、次のコントローラーのクラスを定義して実装しています。

これらの各クラスのソースコードは、MRTK/Providers/WindowsMixedReality フォルダーにあります。

WindowsMixedRealityArticulatedHand.cs
WindowsMixedRealityController.cs
WindowsMixedRealityGGVHand.cs

Note

すべてのデバイスマネージャーで、複数のコントローラーの種類がサポートされるわけではありません。

MixedRealityController 属性を適用する

次に、MixedRealityController 属性をクラスに適用します。この属性は、コントローラーの種類 (例: 多関節ハンド)、利き手 (例: 左または右)、オプションのコントローラーイメージを指定します。

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

対話式操作マッピングを構成する

次の手順では、コントローラーでサポートされる一連の対話式操作マッピングを定義します。 Unity の Input クラスを介してデータを受信するデバイスの場合、対話式操作に割り当てる正確な軸とボタンのマッピングを確認するために、コントローラーマッピングツールが役立ちます。

次の例は MRTK/Providers/OpenVR フォルダーにある GenericOpenVRController クラスを省略したものです。

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),
};

Note

ControllerMappingLibrary クラスは、Unity 入力軸とボタンの定義のためのシンボル定数を指定します。

通知イベントの発生

アプリケーションがユーザーからの入力に応答できるようにするために、データプロバイダーは IMixedRealityInputHandler および IMixedRealityInputHandler<T> インターフェイスで定義されているコントローラーの状態の変化に対応する通知イベントを発生させます。

デジタルタイプのコントロール (ボタン) に対しては、OnInputDown および 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);
}

アナログコントロール (例: タッチパッドの位置) に対しては、InputChanged イベントを発生させる必要があります。

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

Unity Profiler インストルメンテーションを追加する

Mixed Reality アプリケーションでは、パフォーマンスが重要です。どのコンポーネントでも、ある程度のオーバーヘッドが追加されるため、アプリケーションではこれらのオーバーヘッドを考慮する必要があります。このため、すべての入力データプロバイダーに、内部ループと頻繁に使用されるコードパスで Unity Profiler インストルメンテーションを含めることが重要です。

カスタムプロバイダーをインストルメント化するときに MRTK によって使用されるパターンを実装することをお勧めします。

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

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

Note

プロファイラーマーカーを識別するために使用される名前は任意です。 MRTK では、次のパターンが使用されます。

"[製品] クラス名.メソッド名 - オプションのメモ"

トレースを分析するときに特定のコンポーネントとメソッドを簡単に識別できるようにするために、カスタムデータプロバイダーで同様のパターンに従うことをお勧めします。

プロファイルとインスペクターを作成する

Mixed Reality Toolkit では、データプロバイダーはプロファイルを使用して構成されます。

追加の構成オプション (例: InputSimulationService) を持つデータプロバイダーは、アプリケーションのニーズを満たすためにユーザーが挙動を変更することを可能にする、プロファイルとインスペクターを作成する必要があります。

このセクションのコード例全体は、MRTK.Services/InputSimulation フォルダーにあります。

プロファイルを定義する

プロファイルの内容には、オブザーバーのアクセス可能なプロパティ (例: 更新間隔など) を反映させる必要があります。各インターフェイスで定義するすべてのユーザー構成可能プロパティは、プロファイルに含める必要があります。

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

ユーザーが [Create](作成) > [Assets](アセット) > [Mixed Reality Toolkit](Mixed Reality ツールキット) > [Profiles](プロファイル) メニューを使用してプロファイルインスタンスを作成できるようにするために、CreateAssetMenu 属性をプロファイルクラスに適用できます。

インスペクターを実装する

プロファイルインスペクターは、プロファイルの内容を構成および表示するためのユーザーインターフェイスです。各プロファイルインスペクターは、`BaseMixedRealityToolkitConfigurationProfileInspector クラスを拡張する必要があります。

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

CustomEditor 属性により、インスペクターが適用されるアセットのタイプが Unity に通知されます。

アセンブリ定義を作成する

Mixed Reality Toolkit では、アセンブリ定義 (.asmdef) ファイルを使用してコンポーネント間の依存関係を指定し、Unity によるコンパイル時間の短縮を支援します。

すべてのデータプロバイダーとそのエディターコンポーネントに対してアセンブリ定義ファイルを作成することをお勧めします。

前の例の[folder structure](フォルダー構造)を使用して、ContosoInput データプロバイダーに対して 2 つの .asmdef ファイルを用意します。

最初のアセンブリ定義は、データプロバイダー用です。この例では ContosoInput と呼ばれ、例の ContosoInput フォルダーに配置されます。このアセンブリ定義では、Microsoft.MixedReality.Toolkit に対する依存関係と、これが依存する他のアセンブリを指定する必要があります。

ContosoInputEditor アセンブリ定義では、プロファイルインスペクターとエディター固有のコードを指定します。このファイルは、エディターコードのルートフォルダーに配置する必要があります。この例では、このファイルは ContosoInput\Editor フォルダーに配置されています。このアセンブリ定義には、ContosoInput アセンブリへの参照と次のものが含まれます。

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

データプロバイダーを登録する

データプロバイダーを作成したら、入力システムに登録してアプリケーションで使用することができます。

登録済み入力システムデータプロバイダー

パッケージ化と配布

サードパーティコンポーネントとして配布されるデータプロバイダーには、パッケージ化と配布に関する特定の詳細を含めますが、この詳細は開発者の裁量に任されます。最も一般的な解決策は、.unitypackage を生成し、Unity Asset Store を通じて配布する方法です。

データプロバイダーが Microsoft Mixed Reality Toolkit パッケージの一部として送信され、受理されると、Microsoft MRTK チームは、それを MRTK オファリングの一部としてパッケージ化し、配布します。

次の方法で共有

入力システムデータプロバイダーの作成 — MRTK2

名前空間とフォルダー構造

名前空間

推奨のフォルダー構造

データプロバイダーを実装する

インターフェイスと基底クラス継承のどちらかまたは両方を指定する

MixedRealityDataProvider 属性を適用する

IMixedRealityDataProvider メソッドを実装する

データプロバイダーのロジックを実装する

コントローラーのクラスを実装する

MixedRealityController 属性を適用する

対話式操作マッピングを構成する

通知イベントの発生

Unity Profiler インストルメンテーションを追加する

プロファイルとインスペクターを作成する

プロファイルを定義する

インスペクターを実装する

アセンブリ定義を作成する

データプロバイダーを登録する

パッケージ化と配布

関連項目

その他のリソース

次の方法で共有

入力システム データ プロバイダーの作成 — MRTK2

名前空間とフォルダー構造

名前空間

推奨のフォルダー構造

データ プロバイダーを実装する

インターフェイスと基底クラス継承のどちらかまたは両方を指定する

MixedRealityDataProvider 属性を適用する

IMixedRealityDataProvider メソッドを実装する

データ プロバイダーのロジックを実装する

コントローラーのクラスを実装する

MixedRealityController 属性を適用する

対話式操作マッピングを構成する

通知イベントの発生

Unity Profiler インストルメンテーションを追加する

プロファイルとインスペクターを作成する

プロファイルを定義する

インスペクターを実装する

アセンブリ定義を作成する

データ プロバイダーを登録する

パッケージ化と配布

関連項目

その他のリソース

入力システムデータプロバイダーの作成 — MRTK2

データプロバイダーを実装する

データプロバイダーのロジックを実装する

データプロバイダーを登録する