RenderDoc for Oculus

RenderDoc is a graphics debugger that allows quick and easy single-frame capture and detailed introspection of any application. Check out our blog series “How to Optimize your Oculus Quest App w/ RenderDoc” to learn more about RenderDoc and Quest development.

We are excited to announce that Oculus now maintains its own fork of RenderDoc. This fork provides access to low-level GPU profiling data from the Quest's Snapdragon 835 chip, specifically information from its tile renderer, which due to its device-specific nature doesn’t make sense to upstream to mainline RenderDoc. This opens up new possibilities for getting actionable profiling information from your Quest, in a GUI directly embedded within what is arguably the most popular graphics debugging tool for the Quest platform. We are very grateful for Baldur Karlsson’s open source project (https://renderdoc.org/) and for his work on Renderdoc, which has become a very important tool in VR development.

Because this is a fork of RenderDoc, many of you should be familiar with its UI. If you are not familiar with RenderDoc, check out /documentation/tools/tools-renderdoc. On top of this familiar UI, RenderDoc for Oculus offers two profiling features unavailable in standard RenderDoc: Render Stage Tracing and Draw Call Tracing. With Render Stage Tracing, you get a detailed graphical view of how the GPU works in the form of the Tile Timeline. With Draw Call Tracing, you get 45 different low level metrics specific to the draw calls your app makes.

The new data comes in the form of a Tile Timeline view and can be opened through the Window->Tile Timeline menu. After completing a successful render stage trace on the device, you are presented with a timeline view of a single frame. The top row of the timeline shows each of the surfaces rendered to in succession during the frame. Each block on the surface row shows the surface, its dimension, its MSAA status, bit color and bit depth, and finally, the dimension of tiles on the surface along with a count of the total number of tiles.

The second row on the Tile Timeline lists out all the render stages for each tile on a given surface. This provides accurate timings (in microseconds) for each render stage, with a color key and label indicating the type of render stage:

The Tile Timeline presents a lot of information, so zooming functionality is provided through the mouse scrolling wheel to zoom in and out of particular areas of the timeline. You may remember render stages from our documentation on gpu systrace; the render stage information presented here is the same as what you’d get from systrace. RenderDoc’s UI makes render stage capture more convenient, but without the ability to see CPU-GPU concurrency. For a more detailed explanation on render stages, checkout our documentation at /documentation/tools/tools-renderdoc-for-oculus/.

Besides render stage trace, RenderDoc for Oculus now can perform a draw call trace for apps using the Vulkan API which collects up to 45 low level metrics pertaining to each individual draw call.

We have detailed explanations of each of these metrics in our Draw Call Metrics topic.

When choosing a replay context from RenderDoc, you will be presented with a new context alongside your usual Quest device connection; the new device is called "Oculus Quest Profiling Mode." This is the context you should use. If this is the first time you are installing RenderDoc on your device, you will get prompted inside the headset to give RenderDoc permission to write files.

After clicking on the profiling mode replay context, RenderDoc will install and run the server on your headset and establish connection. The profiling mode replay context puts the headset in detailed GPU profiling mode. This mode introduces a 5-10% GPU performance hit in exchange for getting accurate profiling timings. The mode also forces the headset GPU to its maximum clock to ensure you are getting accurate profiling data. If you choose the regular Oculus Quest device without the profiling mode suffix, profiling functionalities will be disabled. Note that when you switch to the non-profiling replay mode, or when you quit RenderDoc, your headset will be restored to its default, non-profiling state.

After selecting the profiling device, launch the app you would like to profile through the RenderDoc interface. From the Launch tab, configure the executable path to select the app APK to run on the headset and press the Launch button.

Once the target app has launched on the headset, the status panel in RenderDoc should display the detected API; then you may capture a frame by pressing the Capture Frame button.

Then, open the Event Browser tab (if it's not already opened), and click the render stage trace button (pictured as an Oculus icon). RenderDoc will then perform a render stage trace. Your headset proximity sensor will be disabled for a few seconds so RenderDoc can perform the trace without you having to wear the headset; in general, the only time you are required to wear the headset is when you are looking at the captured app to know when to press the Capture Frame button.

After a few seconds, you will be presented with the render stage data in the Tile Timeline window. Use your mouse wheel to zoom in and out.

Because RenderDoc inserts load and store operations during playback (for its graphics debugging features), you might notice some unexpected color/depth store in the Tile Timeline. To minimize the chance of unexpected render stages, try setting your Replay optimisation level to Fastest as described in https://renderdoc.org/docs/how/how_control_replay.html.

To perform a draw call trace, select Windows->Performance Counter Viewer

Click on Capture counters

Select the desired performance counters by clicking on the check box(es), then click on Sample counters

After replaying the scene on the HMD, you’ll be presented with a table of metrics in the Performance Counter Viewer. Each row represents a draw call, and you can double click on a row to select the corresponding draw call in the Event Browser.

Regardless of the new Profiling Mode, which introduces a new layer of internal communication with the GPU, we also made changes to the stock RenderDoc timing system. Although by default RenderDoc, upon clicking on the clock button, will replay your frame with performance queries added around drawcalls, this has drawbacks on tiled renderers such as the one running on Oculus Quest. On OpenGL which uses time_elapsed timer queries, drawcall timer queries will add overhead as the GPU now needs to stall in between drawcalls in each tile to calculate their total cost. On Vulkan which simply supports timestamps, putting two timestamps around a drawcall doesn’t have much meaning as drawcalls aren’t executed sequentially, so the results aren’t representative at all.

We have added a new Profiling tab under Settings, where you can choose instead to add timestamps around each renderpass only.

Given that renderpasses execute on the GPU as a single unit of work, measuring their time has no overhead at all, and is actually meaningful in Vulkan. When replaying, RenderDoc will now show you the per-renderpass time:

If the replay mode is set as Fast, this time should incur no overhead at all when compared to the actual application.

We will continue to maintain and improve our fork of RenderDoc. We believe RenderDoc is an excellent graphics debugging tool, and we will be working to make our fork a high quality application development tool. Stay tuned for Part 5 of our RenderDoc series, where Cristiano Ferreira will dive deeper into RenderDoc for Oculus.