Skip to main content
Version: 0.23.2

Using Dual Render Fusion

When working with the Dual Render Fusion (Experimental) feature, there are some additional considerations that should be taken into account.

Glass Connection / Disconnection​

Dual Render Fusion allows developers to build applications where XR is an extension to the smartphone mobile experience. As such, it is necessary to check that the application performs as expected when XR glasses are not connected. The easiest way to do this is by subscribing to the events made available through the Fusion Lifecycle Events component.

Considerations​

Some additional questions to think about when developing an application include:

  • What does the application look like when starting it up with glasses disconnected? And connected?
  • If the glasses disconnect "now" how will the application behave?
    • When disconnecting the On OpenXR Stopping, On OpenXR Stopped and On OpenXR Unavailable events are fired.
    • When stopping, the application should immediately stop using any XR perception features. When stopped, calling those features will fail.
    • Let the user know they should reconnect glasses when XR content is unavailable.
  • How does the application behave if the user presses the power button on the glasses?
    • Typically, this will cause XR content to be paused. But note that the application is still running in the foreground on the smartphone. The same behaviour occurs if the glasses go to sleep by leaving them on a desk while still connected (proximity sensor timeout).
    • Listen to the On Idle and On Active events.
    • If the XR content is not visible it may be able to be deprioritized. Consider pausing updates to the content or running high-intensity sections less frequently.
  • How does the application behave if the user presses the home button on the smartphone?
    • This will typically be handled by Unity as a Pause. With Dual Render Fusion, unlike normal Snapdragon Spaces projects, this will mean that XR content is stopped along with backgrounding the smartphone application. See App Backgrounding for more information.
  • Is it possible that a user runs this application on a device which doesn't support Dual Render Fusion (MR/VR All-In-One headset)? What does that look like?

Troubleshooting​

The application still isn't behaving as expected? Here are some Tips and Tricks to get development back on track:

Scene Transitions​

Pay special attention to the notes on Scene Transitions for the Dynamic OpenXR Loader, Spaces Glass Status, Spaces Host View, and Fusion Lifecycle Events components.
The Dynamic OpenXR Loader, Spaces Glass Status, and Spaces Host View are all intended to survive scene transitions and will be automatically marked as DontDestroyOnLoad. This means these components need to be attached to root level game objects in the hierarchy.
The Fusion Lifecycle Events is not intended to survive scene transitions, and should not be marked as DontDestroyOnLoad. It should be configured for each scene to handle enabling and disabling of content for XR or the smartphone as required.

Functionality Loss Caused By Disconnect​

The Dynamic OpenXR Loader by default handles enabling and disabling AR Session and XR Origin game objects when XR content is not useable. Other game objects can be disabled as required per application through Fusion Lifecycle Events. But it is important to consider the implications of disabling certain components.

For example, it is recommended that the Input Action Manager and Event System components never be disabled when XR content is not active. The Project Validation window will warn about this.

Dual Render Fusion project validator warning

Clicking Edit will log to the console more detailed information about what problems this might cause, and how to solve them.

Example​
Dual Render Fusion project validator warning

In the above example, disabling the game object named Sample Object To Be Disabled causes the Input Action Manager or Event System components to be disabled on a child object XR Interaction Manager when glasses disconnect, and this will prevent the smartphone from responding to touch screen inputs.

  • If the Sample Object To Be Disabled really should be disabled, the child object with the problematic components should be reparented.
  • It's also worth considering renaming the XR Interaction Manager object as it doesn't only affect interactions for XR content.

When structuring the hierarchy for an application it is important to consider the implications of disabling each component as a result of XR lifecycle events.

It is very hard to produce a comprehensive list of all problematic components, but the list of components monitored in this validation step will increase when they are identified.

Runtime Diagnostic Logs​

The Dual Render Fusion feature can provide useful diagnostic logs if an attempt is made to access an XR feature at runtime, when that feature is not available. There may be repeated log entries at runtime which look something like this:

Dual Render Fusion diagnostic log

Full diagnostic logs can contain enough information that they can cause other useful error messages to be lost. For this reason, the full diagnostic log only appears the very first time something attempts to use a feature and fails for each OpenXR session. This means it will be rechecked if a glass disconnect occurs, and again once the glasses reconnect.

The output of a full diagnostic log can include multiple messages.

Below are examples of the sorts of messages that might be logged, and how to solve these issues:

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.
  • The Dual Render Fusion feature is not enabled. If OpenXR is not running it likely means Initialize XR on Startup is disabled in Project Settings > XR Plug-In Management > Initialize XR on Startup. When Dual Render Fusion feature is enabled this is the correct configuration, but without it the application will fail to launch XR content.
Dual Render Fusion feature is enabled but OpenXR is set to initialize at startup.
It is likely that this will not behave as expected unless glasses are connected at application start.
  • The opposite of the problem above - Initialize XR on Startup is enabled in Project Settings > XR Plug-In Management > Initialize XR on Startup - when it should be disabled. 
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 content cannot start when glasses are disconnected, but without a Spaces Glass Status component there is no way to receive the information about when this can succeed. The Dynamic OpenXR Loader component requires a Spaces Glass Status component to function, and it provides additional assistance in managing the lifecycle of XR content when disconnects happen. It is recommended to add a Dynamic OpenXR Loader component. It is also recommended to enable the Auto Start XR On Display Connected and Auto Manage XR Camera properties. If handling the lifecycle of the application manually, at a minimum a Spaces Glass Status component is required.
  • Errors like this after switching scenes (and disconnecting/reconnecting) may indicate that the Dynamic OpenXR Loader or Spaces Glass Status did not survive the scene transition. This can happen if the components are attached to a non-root game object in the scene when they were created. See Scene Transitions above.
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).
  • Something is attempting to use an XR feature when it is not safe to do so. This is usually the result of a game object being active in the scene, when it should be disabled until On OpenXR Started has been signalled.
Example​

Consider a full diagnostic log containing the following messages:

Dual Render Fusion diagnostic log

In this example a game object exists with a SpacesCompositionLayer component attached to it. This game object is created when the scene loads, but the glasses are not connected. It attempts to use the CompositionLayersFeature, but because no glasses are connected XR content cannot run, so accessing the feature fails.

The Fusion Lifecycle Events component should enable this game object after On OpenXR Started has been signalled. The game object could be deactivated in the scene when the scene is saved, but then someone could enable it again and the error would return.
The Fusion Lifecycle Events component should disable the game object if On OpenXR Unavailable is signalled at application startup.
It should also be disabled if On OpenXR Stopping or On OpenXR Stopped is called, otherwise it might attempt to access the feature when it is unsafe to do so.

When handling the lifecycle manually, also note that OpenXR can be stopped, while still being available. This is the case where glasses are still connected but an app may choose to disable the OpenXR features. Available only means that glasses are connected. Note that manual calls to DynamicOpenXrLoader.Instance.StopOpenXR() will not disconnect the glasses.

App Backgrounding​

One disadvantage of the architecture with Dual Render Fusion is that apps cannot run purely in the background with a different app running in the foreground, unlike the headworn architecture.

Build Issues Caused by Project Validator​

Disable the Validate Open Scene feature setting when running automated builds. See Configure Dual Render Fusion Settings for further details.

Permissions for the OpenXR Runtime​

When an application is built with the Snapdragon Spaces SDK, the OpenXR Runtime application must have certain permissions granted to it for the Unity application to function correctly:

  • Camera permissions must be granted to the OpenXR Runtime to use most Snapdragon Spaces perception features.
  • The advanced setting Display over other apps must be allowed on the OpenXR Runtime. This allows the Unity application to draw the Dual Render Fusion phone content on the phone's display correctly. Without this permission, the OpenXR content is displayed on both the glasses and the phone, and any Dual Render Fusion phone content will not be visible.

See Handling App Permissions with Dual Render Fusion for further information, including localisation of pop-up prompts.