Skip to main content
Version: 20 Mar 2024

Troubleshooting Remote Render

This guide provides tips for troubleshooting issues you may encounter when using Remote Rendering.

Local Network Suggestions​

By default, Remote Rendering operates over your local network. Ideally you will setup your network with the following:

  • A WiFi 6 router with a discrete 5GHz SSID
  • Your ML2 connected to the 5GHz SSID
  • Your PC connected to the router via ethernet

Many other configurations are possible, with the overall goal being to maximize bandwidth and minimize network latency to get the best experience possible. Remote Rendering includes a variety of mitigations to handle a constrained network and provide an acceptable experience when these requirements can not be met.

Remote Rendering consumes between 2-20 Mbps of bandwidth during normal operation, dynamically adjusting as available. At very low bandwidths, image quality may suffer.

Remote Rendering operates on ports 50051 and 50052, and can use both TCP and UDP traffic. Upon installation, the Windows Firewall automatically has appropriate inbound rules added.

Note About Android Device Bridge (adb)​

Several troubleshooting steps below either directly use the Android Device Bridge (adb) in the command line, or indirectly through scripts. Adding adb to your computer’s PATH variable simplifies troubleshooting. Android device bridge is available from multiple official sources, such as here.

Verify That Your Network Allows Local Traffic​

Remote Rendering requires that traffic between the Magic Leap 2 (ML2) device and your PC is allowed by your network administrator. A network where each client is isolated will not work by default.

One way to check if this might be an issue is to ping your PC’s IP from your ML2.

Some networks might be configured to block a ping, but be configured to allow the traffic Remote Rendering requires. This still functions as a basic test in many scenarios.

First, open a powershell window and identify your PC’s IP address:

PS C:\Users\ebridgewater> ipconfig

Windows IP Configuration
Ethernet adapter Ethernet:

   Connection-specific DNS Suffix  . :
   IPv6 Address. . . . . . . . . . . : 6417:afed:d04f:a914:26a6:9c9e:2537:928d
   Temporary IPv6 Address. . . . . . : 25b3:9f97:0c82:a704:ae75:d870:c2dc:0157
   Link-local IPv6 Address . . . . . : fe92:bcc2:7aca:a4f0:ee74:604b:7c19:6b54
   IPv4 Address. . . . . . . . . . . : 92.83.36.160
   Subnet Mask . . . . . . . . . . . : 255.255.255.0

When attempting to pair, Remote Rendering runs an equivalent command and collects all potential IP addresses for local pairing, before embedding them into the QR code for the ML2 to attempt a connection with.

Next, try to see if the ML2 can reach this IP address:

PS C:\Users\ebridgewater> adb shell ping 92.83.36.160
PING 92.83.36.160 (92.83.36.160) 56(84) bytes of data.
64 bytes from 92.83.36.160: icmp_seq=1 ttl=128 time=1.69 ms
64 bytes from 92.83.36.160: icmp_seq=2 ttl=128 time=17.1 ms
64 bytes from 92.83.36.160: icmp_seq=3 ttl=128 time=11.4 ms

As you can see, the ML2 is successfully pinging the PC’s IP address, meaning one common point of failure is not an issue for this configuration.

If you can not ping your PC from your ML2, check your network configuration, and ensure a route exists from your ML2 to your PC.

Issues with Application Blend Mode​

Remote Rendering supports two OpenXR blend modes:

  • XR_ENVIRONMENT_BLEND_MODE_ADDITIVE - For AR applications which only add transparent content via RGB.

  • XR_ENVIRONMENT_BLEND_MODE_ALPHA_BLEND - For AR applications which render opaque content, signaling opacity via the alpha channel of an RGBA image.

Applications should only try to use blend modes which they have been tested with, and when properly tested XR_ENVIRONMENT_BLEND_MODE_ALPHA_BLEND gives the best results on Magic Leap 2, as they make use of the segmented dimmer.

If an application naively opts to use the preferred XR_ENVIRONMENT_BLEND_MODE_ALPHA_BLEND mode without testing that the alpha channel is valid, bugs may occur unexpectedly when used with a Magic Leap 2. In particular, the following issues have been reported:

  1. Using ALPHA_BLEND without submitting any projection layer where XR_COMPOSITION_LAYER_BLEND_TEXTURE_SOURCE_ALPHA_BIT is set results in the segmented dimmer being active for the entire frame.
    • This is because per the OpenXR specification: "If a submitted swapchain's texture format does not include an alpha channel or if the XR_COMPOSITION_LAYER_BLEND_TEXTURE_SOURCE_ALPHA_BIT is unset, then the layer alpha is initialized to one."
    • Some early versions of Remote Rendering did not have this behavior properly implemented, resulting in behavior similar to XR_ENVIRONMENT_BLEND_MODE_ADDITIVE.
  2. If an application’s alpha layer is arbitrary, content may not render at all, or may enable the segmented dimmer seemingly at random.
    • If XR_COMPOSITION_LAYER_UNPREMULTIPLIED_ALPHA_BIT is set, an alpha of 0 is equivalent to "Do not render this pixel."
    • This has been noticed in particular with some Unity applications that use custom shaders. Unity by default will select XR_ENVIRONMENT_BLEND_MODE_ALPHA_BLEND, and if application shaders adjust the alpha, this may no longer be valid. Either correct the shaders to account for proper alpha, or force Unity to use ADDITIVE_BLEND, referring to the Unity documentation here.

The Built-in Verify-App​

Remote Rendering ships with a small OpenXR application to help validate basic behavior. You can access it via the hub as seen in the below screenshot:

Remote Rendering OpenXR Demo App

The application is located at C:\Program Files\Magic Leap Remote Rendering\verify-app\verify-app.exe.

note

This application exhibits the above mentioned issue of XR_COMPOSITION_LAYER_UNPREMULTIPLIED_ALPHA_BIT at the current time of writing, enabling the segmented dimmer across the screen. This is a known issue.

Collecting data for Magic Leap support​

Included with Remote Rendering are powershell scripts that can collect information helpful to our engineers when diagnosing an issue. These scripts are signed cryptographically to prevent tampering, and can be viewed in plain text.

Depending on your PC’s policy, you may not easily be able to run any powershell scripts by default. With your IT administrator’s permission, the following workaround might work to run them:

powershell.exe -ExecutionPolicy Bypass -File "FILENAME"

DebuggerScript​

The DebuggerScript attempts to collect various information about your system, and is particularly useful in diagnosing connection issues. If adb.exe is in your PATH (Or a path to it is passed via the AdbPath argument) and a device is connected, the script will also collect information about your device. The script is located at 'C:\Program Files\Magic Leap Remote Rendering\DebuggerScript.ps1'. The information is printed directly to the console, so that you may elect to censor it as needed before sending to us.

The script collects the current information at the time of writing:

  • Information about adb, if available
  • The current ipconfig status of your PC, to list IP adddresses
  • A similar query of available IP addresses.
  • The default OpenXR runtime
  • The properties of your Magic Leap Remote Rendering installation
  • The script execution policy of your PC
  • A list of OpenXR applications active on your PC that are correctly loading the Remote Rendering DLL
  • If the Remote Rendering service is active
  • The status of the Remote Viewer installed on your ML2
  • The IP address of the ML2
  • The results of pinging the ML2 from your PC
  • The results of pinging your PC from the ML2
  • The ML2 OS
  • The status of your Nvidia driver installation
  • A scripted attempt to force pairing of Remote Rendering
  • The status of the environment variable XR_RUNTIME_JSON
    • This environment variable should not be set, though some OpenXR runtimes have historically set this improperly, breaking OpenXR applications for afflicted PCs.

Metrics Collection​

The metrics collection script should be run immediately after a problematic Remote Rendering session. It contains frame-by-frame information about the session, including networking latency and application frame timings.

The metrics collection script is located at C:\Program Files\Magic Leap Remote Rendering\FetchLogs.ps1. It should be run from powershell with the following arguments like so:

& 'C:\Program Files\Magic Leap Remote Rendering\FetchLogs.ps1' -HostMetrics

A zip archive can be created at ~/MagicLeap/remote-rendering-logs.

Advanced Usage​

Bypassing the Magic Leap Hub​

The Magic Leap Hub is the primary interface by which Remote Rendering should be managed and run, and the below options may change over time. However, it is understood that managing Remote Rendering from the command line may be preferable to some customers.

The Remote Viewer APK is downloaded by the Hub automatically when installing Remote Rendering from the Package Manager. By default it will have a location of ~/MagicLeap/tools/remote_render/VERSION/ml_remote_viewer.apk, and can be installed via standard adb install commands.

You can install an older version of the Remote Viewer if need be. However, be aware that each version of Remote Rendering is tested with specific MLOS, and using a different version may cause you to encounter unexpected behavior.

If you still wish to install an older version of the Remote Viewer, you can first uninstall your current version via:

adb uninstall com.magicleap.remote_viewer_app

Pairing of the Remote Viewer is accomplished via Android Intents, and is managed with a utility located at C:\Program Files\Magic Leap Remote Rendering\bin\setup_viewer.exe. Running this utility with the --help argument will list all options, though this document will call out the following useful options:

  • --mode {adb,qr} - The adb option will pair your ML2 directly via adb, if available. The qr option will render a QR code directly in the terminal, similar to the Hub method of pairing. By default, this utility will attempt to pair over adb if no option is specified.

    • Note: All pairing methods generate a secure code that is valid for 5 minutes. The Hub automatically regenerates the QR code to prevent this from being an issue.

  • --ip allows overriding the auto-discovery of the host IP address, useful if you are not routing over a local network and our other automatic discover mechanisms fail.

  • --print_launch_args will print the intents used in pairing. This could be useful if you have multiple PCs in your setup, where the first is your remote rendering host (Where you run this command) and the second is connected to the ML2 via adb.

Various internal details of the current state of Remote Rendering can be queried with the tool C:\Program Files\Magic Leap Remote Rendering\bin\mlrrc.exe. The most likely relevent command is mlrrc.exe device, which gives feedback on if an ML2 is currently connected to the Remote Rendering service.

Using USB Networking with the ML2​

USB Ethernet Adapter​

Using some USB-C to Ethernet adapters with your ML2 is supported by Remote Rendering, in lieu of WiFi. A router is still recommended, and so in such a configuration both your PC and ML2 would be connected to the same router over Ethernet.

Remote Rendering has the strongest support for adapters which enumerate themselves on Android as eth0 adapters. This adapter is tested within Magic Leap on a regular basis.

Using a USB Cable Directly via RNDIS​

Alternatively, it is possible to connect a USB-C cable directly between your ML2 and PC and issue the following command to establish a virtual network over the cable.

adb shell svc usb setFunctions rndis

Once issued, a new network adapter should appear on your PC, with a new IP. If you have previously generated a QR code for pairing, you must regenerate that QR code so that this IP is included. This process of enabling rndis and generating new pairing information must be repeated each time the USB cable is disconnected.

Using Remote Rendering Over the Internet​

At a fundamental level, all that is needed for Remote Rendering to function is a performant UDP route from your ML2 to your PC, with a known IP address. If your PC is exposed to the internet (via port forwarding being configured or any other option) and the ML2 is paired with the externally addressable IP address, then Remote Rendering will function, with appropriate caveats about the limitations of network latency.

note

If you are attempting to use Remote Rendering over the internet, it is especially important that your OpenXR application submit a valid depth layer, as detailed here. This allows our latency-mitigating reprojection to work optimally.

If you are hosting your PC in the cloud, the Remote Rendering IP detecting may be able to detect your IP address automatically and include it- in such a case, you can pair using the Hub as normal, as the QR code will include the IP.

If the IP address can not be dynamically detected, you can either use the setup_viewer.exe with the --ip argument as detailed above, or set the following environment variable on your PC: MLRR_IP_OVERRIDE. When set, the IP address specified will be included in all invocations of pairing automatically.