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
- 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 .
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.
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 |br| RenderDoc|
|4.0.0 or newer||From PC||✓*||✓*||Not required|
|Before 4.0.0||From PC||Unsupported|
|Wave SDK Version||Embedded |br| RenderDoc||Launch type||Android 7||Android 10|
|4.0.0 or newer||Yes||Launch|
|Yes||Attach||✓||✓ |br| (Requires Setup Config 0)|
|No||Attach||✓||✓ |br| (Requires Setup Config 1)|
|Before 4.0.0||No||Don’t care|
|Yes||Attach||✓||✓ |br| (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.
To debug Unreal VR Applications built with older Wave SDK version, refer to sections `Import RenderDoc Feature Pack`_ and `Building an XR Application with embeded RenderDoc library`_.
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¶
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:
Open your WaveVR Unreal project.
Go to Project Settings. Under Plugins > WaveVR, select Enable RenderDoc.
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
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.
Availableis used to check if RenderDoc library is loaded.
Capture Frameis used to capture frames. Enter the number of frames to capture in
Frame Count. If
Delay in Msis not set, capturing will start immediately.
Set Auto Captureis used to automatically capture frames. Enter the number of frames to capture in
Frame Countwhen capturing every
Period in Ms. To turn off auto capture, set
Period in Msto 0. You can delay capturing the first frame by setting
Delay in Ms.
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
A RenderDoc UI is also provided in WaveVR Content > Blueprints > UI.
Use the controller to select buttons and to enter values.
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.
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. Change org.renderdoc.renderdoccmd.arm64 to org.renderdoc.renderdoccmd.arm32 if your app is a 32-bit application. Also, replace <com.your.package.name> with the package name of your application.
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.
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.