入力イベント — MRTK2

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

次のリストは、カスタム MonoBehaviour コンポーネントによって実装される、使用可能なすべての入力イベントインターフェイスの概要を示しています。これらのインターフェイスは MRTK 入力システムによって呼び出され、ユーザーの入力対話式操作に基づいてカスタムアプリロジックを処理します。ポインター入力イベントの処理方法は、以下に示す標準的な入力イベントの種類とは若干異なります。

重要

既定では、スクリプトは、ポインターによるフォーカスがある GameObject またはフォーカスされている GameObject の親である場合にのみ、入力イベントを受信します。

Handler	events	説明
`IMixedRealitySourceStateHandler`	ソースの検出または喪失	入力ソースが検出されたか失われた場合 (多関節ハンドが検出された場合または追跡できなくなった場合など) に発生します。
`IMixedRealitySourcePoseHandler`	ソースの姿勢の変更	ソースの姿勢が変化したときに発生します。ソースの姿勢は、入力ソースの一般的な姿勢を表します。 6 DOF コントローラーのグリップまたはポインターの姿勢などの特定の姿勢は、`IMixedRealityInputHandler<MixedRealityPose>` を介して取得できます。
`IMixedRealityInputHandler`	[上] または [下] の入力	ボタンのようなバイナリ入力の変更時に発生します。
`IMixedRealityInputHandler<T>`	入力の変更された場合	指定された型の入力の変更時に発生します。 T には、次の値を指定できます。 - float (例: アナログトリガーを返す) - Vector2 (例: ゲームパッドのサムスティックの向きを返す) - Vector3 (例: 追跡対象デバイスの位置を返す) - Quaternion (例: 追跡対象デバイスの向きを返す) - MixedRealityPose (例: 完全に追跡されているデバイスを返す)
`IMixedRealitySpeechHandler`	音声キーワードの認識	"音声コマンドプロファイル" で構成されているキーワードのいずれかを認識したときに発生します。
`IMixedRealityDictationHandler`	ディクテーション仮説結果完了エラー	ディクテーションセッションの結果をレポートするために、ディクテーションシステムによって発生します。
`IMixedRealityGestureHandler`	以下のタイミングのジェスチャイベント: Started 更新済み完了 Canceled	ジェスチャの検出時に発生します。
`IMixedRealityGestureHandler<T>`	ジェスチャの更新時または完了時	指定した型の追加データを含むジェスチャが検出されたときに発生します。 T に指定できる値の詳細については、「ジェスチャイベント」を参照してください。
`IMixedRealityHandJointHandler`	手の関節の更新	手の関節が更新されたときに、多関節ハンドコントローラーによって発生します。
`IMixedRealityHandMeshHandler`	ハンドメッシュの更新	ハンドメッシュが更新されたときに、多関節ハンドコントローラーによって発生します。
`IMixedRealityInputActionHandler`	アクションの開始時または終了時	アクションにマップされた入力を表すアクションの開始と終了を示すために発生します。

入力イベントの動作

スクリプトレベルでは、上記の表に示したイベントハンドラーインターフェイスのいずれかを実装すると、入力イベントを使用できます。ユーザーの対話式操作によって入力イベントが発生すると、次の処理が行われます。

MRTK 入力システムでは、入力イベントが発生したことが認識されます。
MRTK 入力システムにより、すべての登録済みグローバル入力ハンドラーに対して、入力イベントに関連するインターフェイス関数が起動されます
入力システムに登録されているアクティブなポインターごとに、次の処理が行われます。
1. 入力システムで、現在のポインターのフォーカスがどの GameObject にあるのかが判断されます。
2. 入力システムは、Unity のイベントシステムを使用して、フォーカスがある GameObject 上の一致するコンポーネントのすべてに関連するインターフェイス関数を起動します。
3. いずれかの時点で入力イベントが使用済みとしてマークされている場合、プロセスは終了し、GameObject はそれ以降のコールバックを受信しません。
  - 例: インターフェイス IMixedRealitySpeechHandler を実装するコンポーネントは、音声コマンドが認識されたときに検索されます。
  - 注: 現在の GameObject で、目的のインターフェイスに一致するコンポーネントが見つからない場合、Unity イベントシステムはバブルアップして親 GameObject を検索します。
グローバル入力ハンドラーが登録されていない場合や、一致するコンポーネントまたはインターフェイスを備えた GameObject が見つからない場合、入力システムは入力ハンドラーに登録されている各フォールバックを呼び出します

Note

ポインター入力イベントは、上記の入力イベントインターフェイスとは若干異なる方法で処理されます。特に、ポインター入力イベントは、入力イベントを発生させたポインターでフォーカスされている GameObject および任意のグローバル入力ハンドラーによってのみ処理されます。通常の入力イベントは、すべてのアクティブなポインターでフォーカスされている GameObject によって処理されます。

入力イベントインターフェイスの例

次のコードは、IMixedRealitySpeechHandler インターフェイスの使用方法を示しています。この ShowHideSpeechHandler クラスを含む GameObject がフォーカスされているときに、ユーザーが "smaller" (小さく) または "bigger" (大きく) という言葉を言うと、その GameObject のサイズは半分または 2 倍になります。

public class ShowHideSpeechHandler : MonoBehaviour, IMixedRealitySpeechHandler
{
    ...

    void IMixedRealitySpeechHandler.OnSpeechKeywordRecognized(SpeechEventData eventData)
    {
        if (eventData.Command.Keyword == "smaller")
        {
            transform.localScale *= 0.5f;
        }
        else if (eventData.Command.Keyword == "bigger")
        {
            transform.localScale *= 2.0f;
        }
    }
}

Note

IMixedRealitySpeechHandler 入力イベントでは、目的のキーワードが MRTK 音声コマンドプロファイルに事前登録されている必要があります。

グローバル入力イベントに登録する

どの GameObject にフォーカスがあるかに関係なくグローバル入力イベントをリッスンするコンポーネントを作成するには、コンポーネント自体を入力システムに登録する必要があります。登録すると、この MonoBehaviour の任意のインスタンスは、現在フォーカスされている任意の GameObject および他のグローバル登録済みリスナーと共に入力イベントを受信します。

入力イベントが使用済みとしてマークされている場合でも、グローバル登録済みハンドラーはすべてのコールバックを受信します。ただし、フォーカスされている GameObject ではイベントは受信されません。

グローバル入力の登録の例

public class GlobalHandListenerExample : MonoBehaviour,
    IMixedRealitySourceStateHandler, // Handle source detected and lost
    IMixedRealityHandJointHandler // handle joint position updates for hands
{
    private void OnEnable()
    {
        // Instruct Input System that we would like to receive all input events of type
        // IMixedRealitySourceStateHandler and IMixedRealityHandJointHandler
        CoreServices.InputSystem?.RegisterHandler<IMixedRealitySourceStateHandler>(this);
        CoreServices.InputSystem?.RegisterHandler<IMixedRealityHandJointHandler>(this);
    }

    private void OnDisable()
    {
        // This component is being destroyed
        // Instruct the Input System to disregard us for input event handling
        CoreServices.InputSystem?.UnregisterHandler<IMixedRealitySourceStateHandler>(this);
        CoreServices.InputSystem?.UnregisterHandler<IMixedRealityHandJointHandler>(this);
    }

    // IMixedRealitySourceStateHandler interface
    public void OnSourceDetected(SourceStateEventData eventData)
    {
        var hand = eventData.Controller as IMixedRealityHand;

        // Only react to articulated hand input sources
        if (hand != null)
        {
            Debug.Log("Source detected: " + hand.ControllerHandedness);
        }
    }

    public void OnSourceLost(SourceStateEventData eventData)
    {
        var hand = eventData.Controller as IMixedRealityHand;

        // Only react to articulated hand input sources
        if (hand != null)
        {
            Debug.Log("Source lost: " + hand.ControllerHandedness);
        }
    }

    public void OnHandJointsUpdated(
                InputEventData<IDictionary<TrackedHandJoint, MixedRealityPose>> eventData)
    {
        MixedRealityPose palmPose;
        if (eventData.InputData.TryGetValue(TrackedHandJoint.Palm, out palmPose))
        {
            Debug.Log("Hand Joint Palm Updated: " + palmPose.Position);
        }
    }
}

フォールバック入力イベントに登録する

フォールバック入力ハンドラーは登録済みのグローバル入力ハンドラーに似ていますが、入力イベントを処理するための最後の手段として扱われます。グローバル入力ハンドラーが見つからず、GameObject がフォーカスされていない場合にのみ、フォールバック入力ハンドラーが利用されます。

フォールバック入力ハンドラーの例

public class GlobalHandListenerExample : MonoBehaviour,
    IMixedRealitySourceStateHandler // Handle source detected and lost
{
    private void OnEnable()
    {
        CoreServices.InputSystem?.PushFallbackInputHandler(this);
    }

    private void OnDisable()
    {
        CoreServices.InputSystem?.PopFallbackInputHandler();
    }

    // IMixedRealitySourceStateHandler interface
    public void OnSourceDetected(SourceStateEventData eventData)
    {
        ...
    }

    public void OnSourceLost(SourceStateEventData eventData)
    {
        ...
    }
}

入力イベントを停止する方法

すべての入力イベントインターフェイスは、インターフェイス上の各関数のパラメーターとして BaseInputEventData データオブジェクトを提供します。このイベントデータオブジェクトは、Unity 独自の AbstractEventData から拡張されます。

入力イベントが、概説されているようにその実行を介して伝播されるのを防ぐために、コンポーネントで AbstractEventData.Use() を呼び出してイベントを使用済みとしてマークすることができます。これにより、グローバル入力ハンドラーを除く、他のすべての GameObject で、現在の入力イベントの受信を止めることができます。

Note

あるコンポーネントが Use() メソッドを呼び出すと、他の GameObject によるそのメソッドの受信が停止します。ただし、現在の GameObject 上の他のコンポーネントは、引き続き入力イベントを受信したり、関連するインターフェイス関数を起動したりすることができます。

次の方法で共有

入力イベント — MRTK2

入力イベントの動作

入力イベントインターフェイスの例

グローバル入力イベントに登録する

グローバル入力の登録の例

フォールバック入力イベントに登録する

フォールバック入力ハンドラーの例

入力イベントを停止する方法

関連項目

その他のリソース

次の方法で共有

入力イベント — MRTK2

入力イベントの動作

入力イベント インターフェイスの例

グローバル入力イベントに登録する

グローバル入力の登録の例

フォールバック入力イベントに登録する

フォールバック入力ハンドラーの例

入力イベントを停止する方法

関連項目

その他のリソース

入力イベントインターフェイスの例