DRFを使用する際の注意事項

Dual Render Fusion機能（実験的）を使用する場合、考慮すべき追加事項がいくつかあります。

ARグラスの着脱

Dual Render Fusionにより、開発者はXRがスマートフォンのモバイル体験の延長となるアプリを構築することができます。そのため、ARグラスが接続されていない時に、アプリが期待通りに動作するかを確認する必要があります。

これを行う最も簡単な方法は、Spaces Lifecycle Eventsコンポーネントを通して提供されるイベントをサブスクライブすることです。

考察

アプリを開発する際に考えるべき追加的な質問には、以下のようなものがあります。

グラスとの接続が切断された状態、また接続された状態で起動すると、アプリはどのように動作しますか？

• On OpenXR StartedとOn OpenXR Stoppedイベントを利用してください。これらは、XR コンテンツが使えるか使えないかを知らせます。
  On OpenXR AvailableとOn OpenXR Unavailableイベントは、グラスが使用可能かどうか、XRコンテンツの開始の呼び出しが成功するかどうかを知らせます。
• XRコンテンツが使用できない場合は、無効にします。

アプリが動作中にグラスを切断したら、アプリはどのように動作しますか？

• 接続を切断すると、On OpenXR Stopping、On OpenXR Stopped、On OpenXR Unavailableイベントが発生します。
• 停止する場合、アプリは直ちに XRの知覚機能の使用を停止する必要があります。停止すると、それらの機能の呼び出しは失敗します。
• XRコンテンツが利用できなくなると、グラスを再接続する必要があることをユーザーに知らせます。

ユーザーがグラスの電源ボタンを押した場合、アプリはどのように動作しますか？

• 通常、XRコンテンツは一時停止されます。しかし、アプリはスマートフォンのフォアグラウンドで実行されていることに注意してください。グラスが接続されたまま机の上に放置されてスリープ状態になった場合（近接センサーのタイムアウト）にも、同じ動作が起こります。
• On IdleとOn Activeイベントを参照してください。
• XRコンテンツが表示されていない場合は、優先順位を下げることができます。コンテンツの更新を一時停止するか、高強度のセクションの実行頻度を下げることを検討してください。

ユーザーがスマートフォンのホームボタンを押した場合、アプリはどのように動作しますか？

• これは通常、Unityによって一時停止として処理されます。Dual Render Fusionでは、通常のSnapdragon Spacesプロジェクトとは異なり、スマートフォンアプリのバックグラウンド化とともにXRコンテンツが停止されます。詳細はアプリのバックグラウンド動作を参照してください。

Dual Render Fusion (MR / VR All-In-Oneヘッドセット)をサポートしていないデバイスでこのアプリを実行することは可能ですか？それはどのように動作しますか？

• On Host View EnabledとOn Host View Disabledは、Spaces Host Viewコンポーネントから情報を受け取るために使用できます。これらのイベントは、Dual Render Fusionコンテンツを表示できるスマートフォンが使用可能かどうかを通知します。
• スマートフォンのコンテンツが使用できない場合は、使用できないUIエレメントを無効にしてください。

トラブルシューティング

アプリが期待通りに動作しませんか？

開発を軌道に乗せるためのTipsとTricksをいくつか紹介します。

シーンの切り替え

Dynamic OpenXR Loader、Spaces Glass Status、Spaces Host View、Spaces Lifecycle Eventsコンポーネントのシーンの切り替えに関する注意事項に特に注意してください。
Dynamic OpenXR Loader、Spaces Glass Status、Spaces Host Viewは、シーンの切り替えに耐えられるように設計されており、自動的にDontDestroyOnLoadとしてマークされます。
つまり、これらのコンポーネントは、Hierarchyのルートレベルのゲームオブジェクトにアタッチする必要があります。
Spaces Lifecycle Eventsは、シーンの切り替えに対応するものではないので、DontDestroyOnLoadとしてマークされません。XRやスマートフォンのコンテンツの有効化、無効化は、シーンごとに設定する必要があります。

切断による機能喪失

Dynamic OpenXR Loaderは、XRコンテンツが使用できない場合に、AR SessionとAR Session Origin / XR Originゲームオブジェクトの有効化と無効化を行います。
その他のゲームオブジェクトは、Spaces Lifecycle Eventsを通して、アプリごとに必要に応じて無効にすることができます。しかし、特定のコンポーネントを無効にした場合の影響を考慮することが重要です。

例えば、Input Action ManagerやEvent Systemコンポーネントは、XRコンテンツがアクティブでない時は、決して無効にしないことをお勧めします。Project Validationウィンドウでは、この点について警告が表示されます。

Editをクリックすると、コンソールにログが記録され、どのような問題が発生し、どのように解決するかについての詳細な情報が表示されます。

例

上記の例では、Sample Object To Be Disabledというゲームオブジェクトを無効にすると、グラス接続が切断されたときに子オブジェクトのXR Interaction ManagerでInput Action ManagerやEvent Systemコンポーネントが無効になり、スマートフォンがタッチスクリーン入力に反応しなくなります。

• もし、Sample Object To Be Disabledが本当に無効化されるべきなら、問題のあるコンポーネントを持つ子オブジェクトは親を変更する必要があります。
• また、XR Interaction Managerオブジェクトは、XRコンテンツのインタラクションだけに影響するわけではないので、名前の変更も検討する価値があります。

アプリのHierarchyを構成する際には、XRライフサイクルのイベントの結果として各コンポーネントを無効にした場合の影響を考慮することが重要です。

ランタイムの診断ログ

Dual Render Fusion機能は、その機能が利用できない時に、実行時にXR機能にアクセスしようとした場合、有用な診断ログを提供することができます。実行時に以下のようなログが繰り返し記録されます。

完全な診断ログには十分な情報が含まれているため、他の有用なエラーメッセージが失われる可能性があります。このため、完全な診断ログは、OpenXRセッションごとに、最初に機能を使おうとして失敗したときにのみ表示されます。つまり、グラスの切断が発生すると再チェックされ、グラスが再接続されるとまた再チェックされます。

完全な診断ログの出力には、複数のメッセージが含まれるかもしれません。

以下に、ログに記録される可能性のあるメッセージの例と、これらの問題を解決する方法を示します。

Dual Render Fusion feature is not enabled, and yet OpenXR is not running!

The application is not configured to launch openXr at start and it is not safe to access features until it has started.
Please check Project Settings > XR Plugin Management > Initialize XR on Startup if this was unintended.
In the event that this value doesn't respond to attempts to change it, try opening Assets / XR / XRGeneralSettings -> AndroidSettings and checking the Init Manager On Start field.

• Dual Render Fusion 機能が有効になっていません。OpenXR が起動していない場合、Project Settings > XR Plug-In Management > Initialize XR on StartupでInitialize XR on Startupが無効になっている可能性があります。
  Dual Render Fusion機能が有効になっている場合、これは正しい設定ですが、有効になっていない場合、アプリはXRコンテンツの起動に失敗します。

Dual Render Fusion feature is enabled and configured to not start automatically, but there is no Spaces Glass Status component found in the scene or it is disabled.
Information about glasses connection and disconnection events will not be received.

• Project Settings > XR Plug-In Management > Initialize XR on Startupで、無効になっているはずのInitialize XR on Startupが有効になっています。

Dual Render Fusion feature is enabled and configured to not start automatically, but there is no Spaces Glass Status component found in the scene or it is disabled.
Information about glasses connection and disconnection events will not be received.

Dual Render Fusion feature is enabled and configured to not start automatically, and yet there is no Dynamic OpenXR Loader component found in the scene or it is disabled.
If not using the Dynamic OpenXR Loader component to control initialisation of OpenXR ensure that all objects which use OpenXR features are not actively using them until OpenXR starts!

The Dynamic OpenXR Loader was not configured to Auto Start XR On Display Connected.
When using the Dynamic OpenXR Loader to manually control startup, it is still helpful to configure your other objects using the events for tracking the OpenXR lifecycle.
Whatever is trying to access this feature might not be configured correctly.
It is likely that the object trying to get access should be enabled only when the Dynamic OpenXR Loader is finished launching OpenXR.
Try registering this object with the appropriate Dynamic OpenXR Loader events for tracking the OpenXR lifecycle (OnOpenXRAvailable, OnOpenXRUnavailable, OnOpenXRStarting, OnOpenXRStarted, OnOpenXRStopping, OnOpenXRStopped).

• XRコンテンツは、グラス接続が切断されると開始できませんが、Spaces Glass Statusコンポーネントがないと、いつ成功するかという情報を受け取ることができません。
  Dynamic OpenXR Loaderコンポーネントが機能するには、Spaces Glass Statusコンポーネントが必要です。 このコンポーネントは、切断が発生した時にXRコンテンツのライフサイクルを管理するためのさらなる助けとなります。 Dynamic OpenXR Loaderコンポーネントを追加することをお勧めします。
  また、Auto Start XR On Display ConnectedおよびAuto Manage XR Cameraプロパティを有効にすることをお勧めします。
  アプリのライフサイクルを手動で処理する場合は、最低でも Spaces Glass Statusコンポーネントが必要です。

• シーンを切り替えた後（および接続を切断／再接続した後）にこのようなエラーが発生するのは、Dynamic OpenXR LoaderやSpaces Glass Statusがシーンの切り替えに耐えられなかった可能性があります。これは、コンポーネントが作成されたときに、シーン内のルートでないゲームオブジェクトにアタッチされていた場合に起こる可能性があります。詳細は上記のシーンの切り替えを参照してください。

No glasses are connected and OpenXR is not running.
Whatever is trying to access this feature might not be configured correctly.
It is likely that the object trying to get access should be enabled only when the Dynamic OpenXR Loader is finished launching OpenXR.
Try registering this object with the appropriate Dynamic OpenXR Loader events for tracking the OpenXR lifecycle (OnOpenXRAvailable, OnOpenXRUnavailable, OnOpenXRStarting, OnOpenXRStarted, OnOpenXRStopping, OnOpenXRStopped).

• 安全ではないのに、XRの機能を使おうとしています。これは通常、ゲームオブジェクトがシーン内でアクティブになっていることが原因ですが、On OpenXR Startedが送られるまで、ゲームオブジェクトは無効になっているはずです。

例

以下のメッセージを含む完全な診断ログを考えてみましょう。 この例では、SpacesCompositionLayerコンポーネントがアタッチされたゲームオブジェクトが存在します。このゲームオブジェクトは、シーンのロード時に作成されますが、グラスは接続されていません。CompositionLayersFeatureを使用しようとしますが、グラスが接続されていないため、XRコンテンツが実行できず、機能へのアクセスに失敗します。

Spaces Lifecycle Eventsコンポーネントは、On OpenXR Startedが通知された後、このゲームオブジェクトを有効にする必要があります。このゲームオブジェクトは、シーンの保存時に非アクティブにするかもしれませんが、その後、再び有効にするとエラーが再発します。

Spaces Lifecycle Eventsコンポーネントは、アプリ起動時にOn OpenXR Unavailableが送られた場合、ゲームオブジェクトを無効にします。 また、On OpenXR StoppingやOn OpenXR Stoppedが呼び出された場合も、ゲームオブジェクトを無効にする必要があります。そうしないと、安全ではない時に機能にアクセスしようとする可能性があります。

ライフサイクルを手動で処理する場合、OpenXRはまだ利用可能であるにもかかわらず、停止する可能性があることにも注意してください。これはグラスがまだ接続されたまま、アプリがOpenXR機能を無効にすることを選択する場合です。Availableは、グラスが接続されていることだけを意味します。DynamicOpenXrLoader.Instance.StopOpenXR()を手動で呼び出しても、グラスは切断されないことに注意してください。

アプリのバックグラウンド動作

Dual Render Fusionの欠点は、ヘッドセットのアーキテクチャとは異なり、フォアグラウンドで別のアプリが動作している状態で、アプリを純粋にバックグラウンドで動作させることができないことです。

Project Validatorによるビルドの問題

自動ビルドを実行する際に、Validate Open Scene機能設定を無効にします。詳細は、Dual Render Fusionの設定を参照してください。

OpenXRランタイムの権限

Snapdragon Spaces SDKを使用してアプリケーションをビルドする場合、Unityアプリケーションを正しく機能させるために、OpenXRランタイムのアプリケーションに特定の権限が付与されている必要があります。

• ほとんどのSnapdragon Spacesの知覚機能を使用するには、OpenXRランタイムにカメラ権限を許可する必要があります。
• OpenXRランタイムで、高度な設定「他のアプリに重ねて表示」を許可する必要があります。これにより、UnityアプリケーションがDual Render Fusionコンテンツをスマートフォンのディスプレイに正しく描画できるようになります。この許可がないと、OpenXRコンテンツはARグラスとスマートフォンの両方に表示され、Dual Render Fusionのコンテンツは表示されません。

ポップアップのプロンプトのローカライズを含む詳細については、Dual Render Fusionのアプリ権限の取り扱いを参照してください。