RenderDoc

Contents

RenderDoc is a graphics debugger used for frame capture. It is similar to the Frame Debugger in Unity. RenderDoc can capture the following data from individual frames, which can be used for tracking rendering issues:

  • Graphics API Commands
  • Shader
  • Vertices
  • Input textures
  • Output textures

RenderDoc is a powerful and versatile debugging tool that is also easy to use, as the process of capturing frames from the attached XR Device can be initiated through the RenderDoc PC client without any complicated prerequisites.

This guide will only introduce basic RenderDoc usage and features provided by us. For fundamental information about RenderDoc, visit RenderDoc’s official site .

Caution

According to RenderDoc : For RenderDoc’s android support, your application must be installed and it must be debuggable. If your application is not debuggable, build a development build by enabling “Development Mode” in the Unity Build Settings.

Getting Started

Download and install the RenderDoc PC client from RenderDoc’s official site . We recommend you to use RenderDoc V1.9 as this is the version we have tested and verified.

Wave provide both normal RenderDoc capture and in-app capture types. A normal RenderDoc capture is a capture initiated from the PC client, while an in-app capture uses a blueprint or code embedded in the XR Application to trigger the capture.

There are two check tables to show the supported combinations of Wave SDK Version, capture type and launch type when your XR Application is running on a certain Android Version (Combinations marked with a “✓” are supported):

Wave SDK Version Capture type Android 7 Android 10 Embedded
RenderDoc
4.0.0 or newer From PC ✓* ✓* Not required
In-app ✓ ✓ Not required
Before 4.0.0 From PC Unsupported
In-app ✓ ✓ Required
Wave SDK Version Embedded
RenderDoc		 Launch type Android 7 Android 10
4.0.0 or newer Yes Launch    
No Launch ✓ ✓
Yes Attach ✓ ✓
(Requires Setup Config 0)
No Attach ✓ ✓
(Requires Setup Config 1)
Before 4.0.0 No Don’t care    
Yes Launch    
Yes Attach ✓ ✓
(Requires Setup Config 0)

To learn more about Launch types, refer to Using the RenderDoc PC client.

Combinations marked with a ‘*’ indicate the normal RenderDoc debug workflow. You can learn how to do a normal capture from the Document and Tutorials provided by RenderDoc, or refer to the Using the RenderDoc PC client section.

In-app capture type can be done wireless (i.e. no connection between your XR Device and the PC running the RenderDoc client is needed). You can unplug the USB cable, finish the frame capturing within your application and use Attach from the PC client to retrieve the captured data afterwards. To trigger a capture within the application, refer to the Adding an in-app capture trigger section.

Capture type USB Connection when Capturing Launch Type Rebuild Required Android 10
From PC Required Launch No Launch will help setup debug layer
In-app Not Required Launch or Attach Yes Manual setup or use Launch to setup once

Building an XR Application with embedded RenderDoc library

Note

This section is made for older Wave SDK versions or the tester-checker separation use case. Otherwise, you can skip this section.

The RenderDoc’s library will be embedded into your APK if you enable the setting by the following steps:

  1. Open your WaveVR Unreal project.

  2. Go to Project Settings. Under Plugins > WaveVR, select Enable RenderDoc.

    ../../_images/RenderDoc_ProjectSettings_Profile_Enable.PNG

By default, Enable RenderDoc is disabled. You should also disable it if your profiling tasks are done.

The application built with RenderDoc library will run the RenderDoc profiler when the application is launched, and the RenderDoc profiler cannot be stopped. The profiler will run in following situations:

  • Application is running on Android 7
  • Application is running on Android 10 and the gpu_debug_app settings are configured

As the RenderDoc profiler will negatively impact performance when it is running, you should disable the option if your profiling tasks are done.

Currently, the RenderDoc’s library is from RenderDoc V1.9. If you want to use another RenderDoc version, copy the library of that RenderDoc version to Plugins/WaveVR/Source/RenderDocAndroid/lib/android/.

Adding an in-app capture trigger

In-app capture can be triggered when using both Attach and Launch launch types.

WaveVR provides 3 blueprint functions to trigger a frame capture.

../../_images/RenderDoc_Blueprint_Search.PNG

  • Available is used to check if RenderDoc library is loaded.

    ../../_images/RenderDoc_Blueprint_Available.PNG

  • Capture Frame is used to capture frames. Enter the number of frames to capture in Frame Count. If Delay in Ms is not set, capturing will start immediately.

    ../../_images/RenderDoc_Blueprint_CaptureFrame.PNG

  • Set Auto Capture is used to automatically capture frames. Enter the number of frames to capture in Frame Count when capturing every Period in Ms. To turn off auto capture, set Frame Count and Period in Ms to 0. You can delay capturing the first frame by setting Delay in Ms.

    ../../_images/RenderDoc_Blueprint_SetAutoCapture.PNG

We recommend not capturing a large number of frames for Frame Count. When capturing, the screen will be blocked. The length of time the screen is blocked increases based on the number in Frame Count.

A RenderDoc UI is also provided in WaveVR Content > Blueprints > UI.

../../_images/RenderDoc_UI_1.PNG

Use the controller to select buttons and to enter values.

../../_images/RenderDoc_UI_2.PNG

RenderDoc Capture workflow charts

The flow charts here show many kinds of in-app capture’s workflow. According to your purpose, find a suitable workflow.

../../_images/RenderDoc_Slide51.PNG

Workflow 1

../../_images/RenderDoc_Slide61.PNG

Workflow 2

../../_images/RenderDoc_Slide71.PNG

Workflow 3

../../_images/RenderDoc_Slide81.PNG

Workflow 4

../../_images/RenderDoc_Slide91.PNG

Workflow 5

Tester-Checker separation use case

If your application is built with the embedded RenderDoc library, you can run the capture without having to install the RenderDoc PC Client in the tester’s environment.

Before the tester launches the application, Setup Config 0 should be setup. See the Graphic Debug Layer (Android 10) section for the configs.

After capturing, the captured files can be pulled by adb command and then sent to an engineer for further analysis. See the RenderDoc Captured Files section for more information.

Graphic Debug Layer (Android 10)

In Android 10, RenderDoc needs some Android Developer Settings to be enabled in order to debug. The following commands will be set by RenderDoc if you launch your application using RenderDoc or can also be set manually.

Use this shell script RenderDocDebugLayerConfig.sh to help you setup the required config or manually input following commands:

  • Setup Config 0
adb shell settings put global enable_gpu_debug_layers 1
adb shell settings put global gpu_debug_app <com.your.package.name>
adb shell settings delete global gpu_debug_layer_app
adb shell settings put global gpu_debug_layers VK_LAYER_RENDERDOC_Capture
adb shell settings put global gpu_debug_layers_gles libVkLayer_GLES_RenderDoc.so

Config 0 is for apps that have the RenderDoc library embedded during build time. Replace <com.your.package.name> with the package name of your application.

  • Setup Config 1
adb shell settings put global enable_gpu_debug_layers 1
adb shell settings put global gpu_debug_app <com.your.package.name>
adb shell settings put global gpu_debug_layer_app org.renderdoc.renderdoccmd.arm64
adb shell settings put global gpu_debug_layers VK_LAYER_RENDERDOC_Capture
adb shell settings put global gpu_debug_layers_gles libVkLayer_GLES_RenderDoc.so

Config 1 is for apps that do not have the RenderDoc library embedded during build time and the RenderDoc remote service is pre-installed. Replace <com.your.package.name> with the package name of your application.

Note

When RenderDoc’s remote server is launched or a captured file is opened by RenderDoc’s PC client, these above configs will be cleared and should be setup again before the application to be debugged is launched next time.

RenderDoc Captured Files

The captured files have the *.rdc extension. You can download the captured files to your PC with the following command:

adb pull //sdcard/Android/data/<com.your.package.name>/files/RenderDoc

Using the RenderDoc PC client

To learn how to profile using the RenderDoc PC client, go to Using the RenderDoc PC client in RenderDoc.

Leaving the RenderDoc service 2D screen

When RenderDoc service is launched, a 2D application will be shown. As some devices do not have the 2D VRDisplay feature, it is impossible to leave the app and return to the launcher by using VR controllers. Instead, adb commands can be used to do so:

First, find the package name of the launcher by using the following command that shows all of the names of the packages installed on your device.

adb shell cmd package list packages

Then use the following command to start the launcher activity to return to the launcher:

adb shell am start <com.launcher.package.name>/<com.launcher.activity.name>

Replace <com.launcher.package.name> with the package name of the launcher and <com.launcher.activity.name> with the activity name of the launcher, e.g. com.htc.vrs.launcher/com.htc.vr.unity.WVRUnityVRActivity.

RenderDoc Symptoms

As RenderDoc will hook into the graphic API commands for profiling, the XR application running with RenderDoc will have rendering defects, tearing, and low FPS. Also, when RenderDoc is capturing, the screen of the XR application will freeze intermittently. The tearing effect and screen freezing do not affect the captured file.