メインコンテンツまでスキップ
バージョン: 1.0.4

DRFのコンポーネント

このページでは、Dual Render Fusionに含まれるすべての新しいコンポーネントの機能について紹介します。

Dual Render FusionのセットアップガイドのProject Validatorの修正を適用するステップは、シーンに以下のコンポーネントを追加します。
　　　

これらのゲームオブジェクトを手動で作成するために、便利な機能が用意されています。
これらは2通りのメニューから使用できます。

  • シーンのHierarchyで右クリックし、XR > Snapdragon Spaces > Dual Render Fusion
  • メニューバーのGameObject > XR > Snapdragon Spaces > Dual Render Fusion

alt text

Dynamic OpenXR Loaderコンポーネント​

Dynamic OpenXR Loaderコンポーネントは、ARグラスが接続された後にアプリがOpenXRをロードすることを可能にします。このコンポーネントは、Spaces Glass Statusコンポーネントと一緒に動作し、サポートされているARグラスの存在を検出し、設定されていればOpenXRを起動します。

OpenXRが接続を開始した時のUIの動作を制御するために、いくつかのコールバックが用意されています。これらのコールバックは、Spaces Lifecycle Eventsコンポーネントを通して開発者に公開されます。

シーンの切り替え

Dynamic OpenXR Loaderは、シーン遷移に耐えられるように設計されています。

これはルートレベルのGameObjectに存在する必要があり、実行時に自動的にDontDestroyOnLoadに設定されます。

Dynamic OpenXR Loaderは、アプリ起動時の初期に作成され、ARグラスの接続が検出された時にシーンに表示するXRコンテンツが無くても、アプリが終了するまで持続することを目的としています。

Initialize XR on Startupを無効にする

Dynamic OpenXR Loaderコンポーネントを使用するには、Project Settings > XR Plug-In Managementで、Initialize XR on Startupを無効にする必要があります。
これは通常、Fusionのプロジェクト設定の変更のメニュー項目を使った自動セットアップで設定されます。

Dynamic OpenXR Loaderのプロパティ​

alt text

  • Auto Start XR On Display Connected
    • 有効の場合、サポートされているARグラスが接続されると、アプリは自動的にOpenXRを起動します。
    • 無効の場合、開発者はXRが必要になる時に、Dynamic OpenXR LoaderコンポーネントのStartOpenXRメソッドを呼び出す必要があります。

開発者は、手動でOpenXRを開始および停止することができます。

DynamicOpenXRLoader.Instance.StartOpenXR();
...
DynamicOpenXRLoader.Instance.StopOpenXR();

StartOpenXRは、サポートされているARグラスが接続されている場合にのみ成功します。
詳細はSpaces Glass Statusコンポーネントを参照してください。

WARNING

OpenXRが起動を開始すると、メインスレッドは短時間ブロックされます。OpenXRが起動中であることを示すUIを表示し、読み込み完了時に完了したことを表示するのをお勧めします。

  • Auto Manage XR Camera
    • この機能を有効にすると、OpenXR の起動・停止時に、AR SessionとAR Session Originを含むゲームオブジェクトが必要に応じて有効/無効になります。
TIP

AR Foundation 5.0以降を使用している場合、Dynamic OpenXR Loaderコンポーネントは、代わりにXROriginコンポーネントを見つけて有効/無効を切り替えます。

  • Cannot Display Overlay Dialog Options Provider

    • このオプションのフィールドは、OpenXRランタイムのアプリケーションで「他のアプリに重ねて表示」の権限が許可されていない場合に、ユーザーに表示するテキストをカスタマイズするために使用します。
      この権限が許可されていない場合、Dual Render Fusionのコンテンツは描画できません。

  • Runtime Camera Permissions Dialog Options Provider

    • このオプションのフィールドは、OpenXRランタイムのアプリケーションでカメラ権限が許可されていない場合に、ユーザーに表示されるテキストをカスタマイズするために使用します。
      この権限が許可されていない場合、いくつかの機能は動作しません。機能ごとに必要な権限のリストはこちらです。

  • Application Too Old For Runtime Dialog Options Provider

    • このオプションのフィールドを使用して、アプリケーションがOpenXRランタイムに対して古すぎる場合にユーザーに表示するテキストをカスタマイズできます。

  • Runtime Too Old For Application Dialog Options Provider

    • このオプションのフィールドを使用して、OpenXRランタイムがアプリケーションに対して古すぎる場合にユーザーに表示されるテキストをカスタマイズできます。

  • Runtime Validation Failure Dialog Options Provider

    • このオプションのフィールドを使用して、Older Runtime Compatibility機能が失敗のエラーをスローしたときにユーザーに表示されるテキストをカスタマイズできます。
OLDER RUNTIME COMPATIBILITY

Older Runtime Compatibility についての詳細は、専用ページをご覧ください。

これらのフィールドはSimple Dialog Options Providerコンポーネントを受け入れます。このコンポーネントはアプリケーション開発者によって実装されるべきで、メソッドを実装しなければなりません。

public override SimpleDialogOptions GetDialogOptions()

SimpleDialogOptionsの戻り値は各テキスト入力をカスタマイズする文字列を含みます。

  • Title
  • Message
  • PositiveButtonText
  • NegativeButtonText

このテキストは、希望するローカライゼーションのツールチェーンで動作するDialog Options Providerを実装することによって、ローカライズすることができます。
例えば、Unity.Localizationパッケージを使用している場合、Providerの開発者の実装は、単に文字列テーブルでローカライズされたテキストを検索することができます。

public class LocalizedSimpledDialogOptionsProvider : SimpleDialogOptionsProvider
{
    public LocalizedString Title;
    public LocalizedString Message;
    public LocalizedString PositiveButton;
    public LocalizedString NegativeButton;

    public override SimpleDialogOptions GetDialogOptions()
    {
        return new SimpleDialogOptions()
        {
            Title = this.Title.GetLocalizedString(),
            Message = this.Message.GetLocalizedString(),
            PositiveButtonText = this.PositiveButton.GetLocalizedString(),
            NegativeButtonText = this.NegativeButton.GetLocalizedString()
        };
    }
}

実装されているSimple Dialog Options Providerコンポーネントを、シーン内のDynamic OpenXR Loaderコンポーネントに、直接アタッチすることをおすすめします。

alt text

Dialog Options Providerが指定されていない場合、Cannot Display Overlay Dialog Options Providerに以下のデフォルトの英語のテキストが使用されます。

  • Title
    • OpenXR Runtime permissions
  • Message
    • The 'Display over other apps' permission is required for the OpenXR runtime to render XR content. Select 'Configure' to grant this permission manually by selecting 'Snapdragon Spaces Services' from the list shown.
  • Positive Button
    • Configure
  • Negative Button
    • Not Now

Dialog Options Providerが指定されていない場合、Runtime Camera Permissions Dialog Options Providerには以下のデフォルトの英語のテキストが使用されます。

  • Title
    • OpenXR Runtime permissions
  • Message
    • Camera permissions for the OpenXR runtime are not granted. Some features might not work. Would you like to grant the camera permissions now? If you select yes, this application will close and you will need to re-start it.
  • Positive Button
    • Yes
  • Negative Button
    • Not Now

Spaces Glass Statusコンポーネント​

Spaces Glass Statusコンポーネントは、アプリが動作しているデバイスタイプの情報にアクセスし、ARグラスの接続状態に関連する情報を取得するために使用されます。

推奨

Spaces Glass Statusコンポーネントは単独でも使用できますが、XRコンテンツのライフサイクルをより簡単に管理するために、Dynamic OpenXR Loaderコンポーネントと一緒に使用することをお勧めします。

シーンの切り替え

Spaces Glass Statusは、シーンの遷移にも耐えられるように設計されています。

実行時に自動的にDontDestroyOnLoadに設定されるルートレベルのGameObjectに存在する必要があります。(これは、Dynamic OpenXR Loaderと同じオブジェクトである可能性が高いです。)

Spaces Glass Statusは、アプリ起動時の初期に作成され、ARグラスの接続が検出された時にシーンに表示するXRコンテンツが無くても、アプリが終了するまで持続することを意図しています。

このコンポーネントは、Spaces Lifecycle Eventsコンポーネントを通して開発者にコールバックを公開します。

開発者はさらに、以下のように実行時にコードを通して、このデータを照会することができます。

Spaces Glass Statusの利用可能なデータ​

グラスの接続状態(GlassConnectionState)​

var connectionState = SpacesGlassStatus.Instance.GlassConnectionState;
  • グラスの接続状態はDisconnectedまたはConnectedのいずれかです。

グラスのアクティブ状態(GlassActiveState)​

var activeState = SpacesGlassStatus.Instance.GlassActiveState;
  • グラスのアクティブ状態はActiveまたはIdleのいずれかです。
  • グラスが切断されている場合、グラスをActiveにすることはできません。
  • Idleは、グラスが装着されていないことを示します。これは、例えば近接センサーのタイムアウトによってトリガーされることがあります。これは、品質を下げることによってレンダリングの優先順位を下げたり、高負荷のコードセクションの作業負荷を減らすことによって電力を節約することができます。

デバイスの種類(DeviceType)​

var deviceType = SpacesGlassStatus.Instance.DeviceType;
  • デバイスの種類は大まかなカテゴリに分かれています。これらのカテゴリは、与えられたカテゴリにコンテンツを表示する最適な方法をアプリに通知するのに役立ちます。
  • デバイスの種類はNone、Aio、Wired、Wirelessのいずれかです。
    • None：グラスの接続状態(GlassConnectionState)が現在Disconnectedであることを示します。
    • Aio：All-In-Oneグラス（MRやVRヘッドセットビューアなど）です。
    • Wired：スマートフォンにケーブルで接続されたARグラスです。
    • Wireless：スマートフォンにワイヤレスで接続されるARグラスです。

Spaces Host Viewコンポーネント​

Spaces Host Viewコンポーネントは、Dual Render FusionをサポートしていないMR/VRデバイス上でアプリを実行する際に、スマートフォンの表示を動的に無効にします。

さらに、MR/VRデバイス用の代替UIを有効にするなど、必要に応じて追加機能を有効/無効にするために開発者が使用できるコールバックを提供します。これらのコールバックは、Spaces Lifecycle Eventsコンポーネントを通して開発者に公開されます。

このコンポーネントには、スマートフォンのディスプレイにレンダリングするカメラが含まれています。

シーンの切り替え

Spaces Host Viewは、シーンの切り替えに耐えられるように設計されています。

これはルートレベルのGameObjectに存在する必要があり、実行時に自動的にDontDestroyOnLoadに設定されます。

Spaces Host Viewは、アプリ起動時のできるだけ早い段階で作成され、アプリが終了するまで持続するように意図されています。Dual Render Fusionを使用するために作成されたアプリが、MR/VRヘッドセットなどの互換性のないデバイスで起動された場合、Spaces Host Viewは早期にイベントをブロードキャストします。このような場合、スマートフォン特有の表示を隠すなどの対処が必要です。

Spaces Lifecycle Eventsコンポーネント​

Spaces Lifecycle Eventsコンポーネントは、Dynamic OpenXR Loader、Spaces Glass Status、Spaces Host Viewコンポーネントに関連するすべてのイベントを収集します。

グラスとの切断について

MiRZAはスマートフォンと無線で接続するため、他のグラスに比べ切断が起きやすいです。
そのため、Spaces Lifecycle Eventsを使用してグラスが切断されてから復帰するまでの処理をアプリの機能に応じて行う必要があります。

シーンの切り替え

Spaces Lifecycle Eventsは、上記のクラスとは異なり、シーンの切り替えに耐えられるようには設計されていません。シーンごとにインスタンス化する必要があります。各シーンで、開発者は、公開された各イベントの動作を設定することができます。

TIP

開発者は、ARグラスが接続されたり切断されたりしたときの各シーンの動作をコントロールすることができます。

メニューシーンでは、追加のXRコンテンツは表示されないかもしれませんが、グラスが正常に検出されたことを示すUI要素があるかもしれません。 XRコンテンツが必要なシーンでは、グラスの切断によってメニューシーンに戻るか、スマートフォンにポップアップを表示して、グラスが再接続されない限りアプリを実行し続けることができないことを示す必要があるかもしれません。

Spaces Lifecycle Eventsのプロパティ​

Rebroadcast On Scene Loadを有効にすると、Spaces Lifecycle Eventsコンポーネントは、シーンの切り替え時に、On OpenXR Available、On OpenXR Unavailable、On OpenXR Started、On OpenXR Stoppedのイベントをリブロードキャストすることができます。これにより、シーンのロードが完了した時に、接続されているデバイスの機能に応じて、シーンを正しく設定することができます。

イベント​

On OpenXR Available​
  • このイベントは、Dynamic OpenXR Loaderコンポーネントが有効になっている際に、OpenXRを開始する前とOpenXRを停止した後にブロードキャストされます。
  • グラスが接続されて検出されると、On OpenXR Availableがブロードキャストされます。これは OpenXRが初期化可能であることを示しますが、OpenXRはまだアクティブに動作していません。
  • このイベントは、互換性のあるランタイムが利用可能なグラスの接続が検出されたときに発生しますが、アプリがOpenXRの機能にアクセスする前に、OpenXRは初期化される必要があることに注意してください。
  • グラス接続の状態は、SpacesGlassStatus.Instance.GlassConnectionStateを通じていつでも照会できます。
On OpenXR Unavailable​
  • このイベントは、Dynamic OpenXR Loaderコンポーネントが有効になっているとき、OpenXRを起動する前とOpenXRを停止した後にブロードキャストされます。
  • On OpenXR Unavailableは、グラスが切断されたときにブロードキャストされます。これは OpenXRが初期化できず、アクティブに動作していないことを示します。
  • OpenXRのパスは検出されず、グラスが接続されておらず、OpenXRの機能を有効にするには再接続する必要があることを示しています。
  • グラス接続の状態は、SpacesGlassStatus.Instance.GlassConnectionStateを通じていつでも照会できます。
On OpenXR Starting​
  • このイベントはOpenXRが初期化された後、OpenXRのサブシステムが起動する直前にブロードキャストされます。
  • この時点で、どのOpenXR機能が有効になっているか、正しく初期化されているかは明らかですが、サブシステムは動作していません。
On OpenXR Started​
  • このイベントはOpenXRのサブシステムが起動した後にブロードキャストされます。
  • これで全てのXRコンテンツが使えるようになります。
  • このイベントは、シーンでオプションのXRコンテンツを起動したいときに、開発者がサブスクライブすべきイベントです。
  • このイベントがブロードキャストされた後、Stoppingイベントがブロードキャストされるまで、OpenXRの機能を安全に使うことができます。
On OpenXR Stopping​
  • このイベントは、OpenXRのサブシステムが停止し、OpenXRローダーが初期化解除される前にブロードキャストされます。
  • 開発者は、OpenXRを必要とするコンテンツを安全なうちにシャットダウンするために、このイベントをサブスクライブする必要があります。
  • このイベントがコールされたら、開発者はOpenXR機能の使用を直ちに停止しなければなりません。
On OpenXR Stopped​
  • このイベントは、OpenXRのサブシステムが停止し、OpenXRローダーが初期化解除された後にブロードキャストされます。
  • このイベントを受信すると、OpenXRはロードされません。
  • フィーチャーを照会して、使用する予定があるが実際には使用できないかどうかを確認することができます。
  • OpenXRのサブシステムは動作していません。
  • このイベントの直後に、OpenXRを再起動できるかどうか（グラスが接続されているかどうか）を示す可用性がブロードキャストされます。
On Idle​
  • このイベントは、グラスがアイドル状態のときにブロードキャストされます。つまり、グラスがテーブルなどに置かれ装着されていないように見えます（例えば、近接センサーのタイムアウトによりトリガーされます）。
  • これはレンダリング品質を下げたり、XRのみのコンテンツへの更新の優先度を下げたりすることで、電力を節約するヒントとして使用できます。
  • グラスのActive / Idle状態は、SpacesGlassStatus.Instance.GlassActiveStateを通じていつでも照会できます。
On Active​
  • このイベントは、グラスがアクティブであるとき、つまりグラスが装着され、コンテンツが表示されているときにブロードキャストされます。
  • グラスが接続されていない場合、グラスはアクティブになりません。
  • グラスのActive / Idle状態は、SpacesGlassStatus.Instance.GlassActiveStateを通じていつでも照会できます。
On Host View Enabled​
  • On Host View Enabledイベントは、Dual Render Fusionをサポートするデバイスを使用している時に発生します。アプリは、必要に応じてエレメントの表示 / 非表示を選択できます。例：ARデバイスでDual Render Fusionのホストビューを有効にします。
  • これは、サポートされているARデバイスがホストデバイスに接続されているかどうかを示すものではありません。
On Host View Disabled​
  • On Host View Disabledイベントは、Dual Render Fusionをサポートしていないデバイスを使用している時に発生します。アプリは、必要に応じてエレメントの表示 / 非表示を選択できます。例えば、MR / VRデバイスで代替のユーザーインターフェイス要素を有効にする場合などです。
  • これは、有効なホストデバイス(スマートフォン)がなく、SpacesGlassStatus.Instance.DeviceTypeがAioである可能性が高いことを示します。

Spaces XR Simulatorコンポーネント​

Dual Render FusionのEditorシミュレーションを有効にするには、Spaces XR Simulatorコンポーネントをシーンに追加する必要があります。このコンポーネントは、Spaces Host Viewと共に、Display 1とDisplay 2のUnity EditorでDual Render Fusionアプリを正しく表示するためのカメラロジックを処理します。
詳しくはシーンの再生をご覧ください。

Spaces Screen Setupコンポーネント​

Spaces Screen Setupには、スマートフォンのディスプレイで画面の向きを縦または横に強制するロジックが含まれています。
alt text
これはオプションです。

Screen.orientation = ScreenOrientation.Portrait;などの呼び出しを通じて、実行時にUnityでスマートフォンの画面の向きを設定するための正しい呼び出し方法を示します。Screen.orientationを設定するコールは、Dual Render Fusion機能が有効になっていることを確認する必要があります。

Spaces Permission Helperコンポーネント​

Spaces Permission Helperコンポーネントは、OpenXRランタイムのアプリケーションがインストールされていること、Unityアプリケーションに必要なカメラ権限があることを確認するために使用できます。このトピックの詳細については、Dual Render Fusionのアプリ権限の取り扱いを参照してください。
alt text
このコンポーネントをシーン内のゲームオブジェクトに追加します。

  • OpenXRランタイムのアプリケーションがインストールされているか確認します。インストールされていない場合、On Runtime Not Installedイベントがトリガーされます。
  • カメラ権限が必要な機能が有効になっている場合、Unityアプリケーションにカメラ権限が付与されているか確認します。権限が付与されていない場合、On Application Camera Permissions Not Grantedイベントがトリガーされます。
  • Unityアプリケーションにカメラ権限が付与されているか確認します。カメラ許可が付与されると、On Application Camera Permissions Grantedイベントがトリガーされます。

開発者はこれらのイベントに反応して、アプリケーションの動作を決定できます。このコンポーネントには、RequestApplicationCameraPermissionsと呼ばれるアプリケーションのカメラ権限の要求をトリガーするpublic関数があります。

TIP

OpenXR Loading Testのサンプルシーンには、このコンポーネントの使用例が含まれています。

サンプルのコンポーネント​

一部のコンポーネントはサンプルにのみ含まれています。

Companion Controller​

開発者の中には、既存のSnapdragon SpacesプロジェクトをDual Render Fusionに移行し、ジャイロセンサーによる3DoFポインターのCompanion Controller機能を利用したいと考える人もいるでしょう。この機能をプロジェクトに追加するには、以下の手順に従ってください。

Companion ControllerをUnityで再現するには、いくつかのアセットとスクリプトが必要です。

  1. サンプルをインポートします。

  2. 必要に応じて、TextMeshProをインポートしてください。

  3. Assets/Samples/Snapdragon Spaces/0.23.0(バージョン番号)/Fusion Samples/Prefabs内の、CanvasControllerCompanionプレハブをHierarchyにドラッグします。

  4. XR Cameraはプレハブに含まれていないため、2つのゲームオブジェクトを接続する必要があります。設定されていない場合、XR OriginまたはAR Session Originは実行時に自動的に検出され、接続されているカメラを使用します。または、ControllerPositionHeadMirrorのAr Cameraフィールドで手動で設定することもできます。
    alt text

    • GyroRotationReceiverのAr Cameraフィールドの下にあります。
      alt text

  5. ジャイロセンサー制御を有効にするために、Active Input HandlingがBothに設定されていることを確認します。
    alt text
    これは、Dual Render Fusion Setup GuideのProject Validatorの修正を適用するステップで正しく処理されるはずです。

  6. Assets/Samples/Snapdragon Spaces/0.23.0(バージョン番号)/Fusion Samples/Controller/Input Actionsから、ControllerPrefabInputActionsを追加アクションアセットとしてInput Action Managerに追加します。
    alt text
    HierarchyにInput Action Managerがない場合は、まず空のゲームオブジェクトを作成し、コンポーネントを追加します。

  7. Menu Buttonの機能を利用するには、標準のUnity Input Systemを使用し、Menu Buttonを表すHierarchyのButtonオブジェクトにOn Click()イベントを追加するだけです。
    alt text

  8. 設定メニューのオプションを増やすには、一時的に設定オーバーレイのゲームオブジェクトをオンにし、スクロールボックスのリストにメニュー項目を追加します。
    「About」ボタンは機能を持たず、単なる例として存在しています。
    alt text