MRTK v2のドキュメントを少しずつ読み解く入力データプロバイダーの作成

本日は MRTKv2 の調査枠です。
MRTKv2 の Guides ドキュメントを少しずつ読み進めていきます。

MRTKv2のGuidesドキュメント

以下のドキュメントを読み進めていきます。
microsoft.github.io

以下のページでは有志による本ドキュメントの日本語翻訳が行われています。
投稿時点でこちらで未翻訳、または著者が興味のある部分について記事にしていきます。
hololabinc.github.io

本記事では以下のページを読み進めます。
microsoft.github.io
f:id:bluebirdofoz:20200221093700j:plain

入力データプロバイダーの作成

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

入力システム用に、デバイスマネージャーとも呼ばれるカスタムデータプロバイダーを作成する方法について説明します。

ここに示されているコード例は WindowsMixedRealityDeviceManager からのものです。
使用例の完全なコードは MixedRealityToolkit.Providers/WindowsMixedReality フォルダーにあります。
f:id:bluebirdofoz:20200221093709j:plain

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

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

重要

入力システムデータプロバイダーが Mixed Reality Toolkit リポジトリに追加される場合、名前空間は Microsoft.MixedReality.Toolkit(例：Microsoft.MixedReality.Toolkit.WindowsMixedReality) で始まる必要があります。
また、コードは MixedRealityToolkit.Providers の下のフォルダーに配置する必要があります(例：MixedRealityToolkit.Providers \ WindowsMixedReality)。

名前空間

データプロバイダーには名前の衝突を緩和するための名前空間が必要です。
名前空間には次のコンポーネントを含めることをお勧めします。

・アドオンを作成する会社名
・機能エリア

例えば、Contoso社が作成した入力データプロバイダーは「Contoso.MixedReality.Toolkit.Input」です。

フォルダー構造

次の図に示すように、データプロバイダーのソースコードを配置することをお勧めします。
f:id:bluebirdofoz:20200221093726j:plain

ContosoInput にはデータプロバイダーの実装が含まれ、Editor フォルダーにはインスペクターが含まれます。
(およびその他のUnityエディター固有のコード)
Textures フォルダーにはサポートされているコントローラーの画像が含まれます。
Profile フォルダーには、1つ以上の作成済みのプロファイルオブジェクトが含まれています。

注意

いくつかの一般的なコントローラーイメージは、MixedRealityToolkit/StandardAssets/Textures フォルダーにあります。

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

インターフェイスまたは基本クラスの継承を指定する

全ての入力データプロバイダーは、入力システムに必要な最小限の機能を指定する IMixedRealityInputDeviceManager インターフェイスを実装する必要があります。
MRTKには、この必要な機能のデフォルト実装を提供する BaseInputDeviceManager クラスが含まれています。
Unity の UInput クラスに基づいて構築されたデバイスの場合、その UnityJoystickManager クラスを基本クラスとして使用できます。

注意

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

public class WindowsMixedRealityDeviceManager :
    BaseInputDeviceManager,
    IMixedRealityCapabilityCheck
{ }

f:id:bluebirdofoz:20200221093739j:plain

IMixedRealityCapabilityCheck は WindowsMixedRealityDeviceManager によって使用されます。
これは一連の入力機能のサポートを提供します。
関節のある手、視線、ジェスチャー、音声、モーションコントローラーなど。

MixedRealityDataProvider属性を適用します

入力データプロバイダーを作成する上での重要な手順は MixedRealityDataProvider 属性をクラスに適用することです。
これにより、入力システムプロファイルで選択された場合、プロバイダーのデフォルトプロファイルとプラットフォームを設定できます。

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

IMixedRealityDataProviderメソッドを実装する

クラスが定義されたら、次のステップはIMixedRealityDataProvider インターフェースの実装を行うことです。

データプロバイダーによって実装されるメソッドは次のとおりです。
・Destroy()
・Disable()
・Enable()
・Initialize()
・Reset()
・Update()

注意

BaseInputDeviceManager クラスは BaseService クラスを介して IMixedRealityDataProvider メソッドの空の実装を提供します。
これらのメソッドの詳細は、一般にデータプロバイダー固有です。

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

次のステップはサポートされるコントローラーを含む入力デバイスを管理するためのロジックを追加することです。

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

WindowsMixedRealityDeviceManager の例では、次のコントローラークラスを定義および実装しています。
・WindowsMixedRealityArticulatedHand.cs
・WindowsMixedRealityController.cs
・WindowsMixedRealityGGVHand.cs
f:id:bluebirdofoz:20200221093755j:plain

注意

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

MixedRealityController属性を適用します

次に、MixedRealityController 属性をクラスに適用します。
この属性はコントローラーのタイプ(例：関節のある手)、利き手(例：左または右)、およびオプションのコントローラーイメージを指定します。

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

相互作用マッピングを構成する

次のステップは、コントローラーがサポートする相互作用マッピングのセットを定義することです。
Unity の入力クラスを介してデータを受信するデバイスの場合、Controller Mapping Toolはインタラクションに割り当てる正しい軸とボタンのマッピングを確認するのに役立つリソースです。
microsoft.github.io

次の例は MixedRealityToolkit.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),
};

f:id:bluebirdofoz:20200221093824j:plain

注意

このControllerMappingLibrary クラスは Unity の入力軸とボタンの定義にシンボリック定数を提供します。

通知イベントを発生させる

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

ボタン(Digital)タイプのコントロールの場合、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);

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

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

追加の構成オプション(例：InputSimulationService)を持つデータプロバイダーは、プロファイルとインスペクターを作成する必要があります。
これにより、ユーザがアプリケーションのニーズに最も合うように動作を変更できるようになります。

使用例の完全なコードは MixedRealityToolkit.Services/InputSimulation フォルダーにあります。
f:id:bluebirdofoz:20200221093840j:plain

プロファイルを定義する

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

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

f:id:bluebirdofoz:20200221093849j:plain

この CreateAssetMenu 属性をプロファイルクラスに適用すると、ユーザが Create -> Mixed Reality Toolkit -> Profiles メニューを使用してプロファイルインスタンスを作成できるようになります。
f:id:bluebirdofoz:20200221093858j:plain

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

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

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

f:id:bluebirdofoz:20200221093908j:plain

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

アセンブリ定義を作成します

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

全てのデータプロバイダーとそのエディターコンポーネント用にアセンブリ定義ファイルを作成することをお勧めします。
前例のフォルダー構造では InputSimulatio データプロバイダー用の2つの .asmdef ファイルが存在します。

最初のアセンブリ定義はデータプロバイダー用です。
この例では InputSimulatio と呼ばれ、InputSimulatio フォルダーに配置されます。
このアセンブリ定義では Microsoft.MixedReality.Toolkit および依存するその他のアセンブリへの依存関係を指定する必要があります。
f:id:bluebirdofoz:20200221093920j:plain

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

・Microsoft.MixedReality.Toolkit
・Microsoft.MixedReality.Toolkit.Editor.Inspectors
・Microsoft.MixedReality.Toolkit.Editor.Utilities
f:id:bluebirdofoz:20200221093929j:plain