Oculus Quest Development

All Oculus Quest developers MUST PASS the concept review prior to gaining publishing access to the Quest Store and additional resources. Submit a concept document for review as early in your Quest application development cycle as possible. For additional information and context, please see Submitting Your App to the Oculus Quest Store.

Frame Capturing with RenderDoc - Oculus Quest

RenderDoc is a graphics debugger tool that supports multiple graphics APIs and development platforms. It is used for frame capture and analysis during development. RenderDoc shows how a running application’s engine determined a scene should be rendered on Oculus Quest hardware for a single frame. This information can often be used to find optimization opportunities and potential sources or performance issues.

RenderDoc is available for Windows at the RenderDoc website.

RenderDoc

RenderDoc can be used to study an app’s rendering scheme to verify developer expectations and identify irregularities. In game engine development, the actual rendering code can be hidden, or complex with various built-in subsystems, making it difficult to isolate or understand problems. When RenderDoc analyzes a frame, it can provide enough information to begin addressing rendering issues affecting your app.

This topic describes how to use RenderDoc with Oculus Quest for frame capture and basic analysis during app development.

Overview

RenderDoc is used to capture API usage data from a single frame of an app, and to replay captured frames later for analysis. When a frame is captured, RenderDoc also captures all referenced input and output resources in memory for closer analysis, such as textures and meshes.

RenderDoc is useful for examining the operations of your app’s rendering scheme and verifying that the results are as expected. RenderDoc records all graphics API calls and referenced resources in the order they are issued so they can be replayed to study behavior and performance. It also times how long draw calls (and groups of draw calls) are taking to execute on the GPU relative to each other to help identify those that may require optimization. Textures in the capture can be examined at their current state for the selected event. Other information captured for analysis includes graphics pipeline data, meshes and mesh data, shader bytecode, and general statistics such as draw count and memory usage.

Using RenderDoc to Capture a Frame

The following sections describe how to set up RenderDoc, connect it to your Oculus Quest, and take a frame capture.

Preparation

The Oculus Quest being used with RenderDoc must be in Developer Mode. The Android SDK must be installed and configured on the computer running RenderDoc in order to establish an ADB connection with the Oculus Quest. If you have followed the instructions in Device Setup – Oculus Quest and Android Development Software Setup, you should be ready to use RenderDoc.

Download and Install RenderDoc

The RenderDoc installer for Windows can be downloaded from the RenderDoc website. Run the installer and when prompted, choose a Typical installation.

RenderDoc Main Interface

After it’s been installed, open RenderDoc and look at the main screen. The following image highlights notable elements of the interface that are referenced in this guide.
RenderDoc Main Interface

  • Timeline - When a capture is loaded, this displays a visual representation of how much time is spent during various stages of rendering (opaques, transparents, skybox, early-z, shadow pass, and so on). The Timeline also displays render target reads and writes during the selected API call or call group.
  • Event Browser - When a capture is loaded, this lists the API calls that went into rendering the frame, along with debug marker labels to separate logical call groups. Selecting a draw call or call group contextually updates the Timeline and populates other data fields within RenderDoc.
  • Replay Context - Indicates the device from which RenderDoc will take frame captures. To load a RenderDoc capture, the same type of device that captured the frame must be connected to the computer. Replay Context can be clicked to choose from available devices.
  • Tabs - The tabs control what is displayed in the main area of RenderDoc and serve a variety or purposes. Notable tabs related to this guide include the following:
    • Texture Viewer - Shows the input and output textures (RTs) for the selected draw. Individual textures can be examined to see their name, resolution, mip count, MSAA data (if applicable), format, and other information.
    • Pipeline Data - Displays a high-level diagram of the graphics pipeline states when the capture was taken. Each block represents a different part of the pipeline. Click on a block to view information on bound resources and other data.
    • Mesh Viewer - Shows mesh data for the selected draw as well as a visual representation of the mesh. Available data includes vertex count (useful for verifying LOD systems), vertex attributes, and the post-projected view of the mesh in screen space.
    • Launch Application - Used to select and launch a development application on a connected Oculus Quest. Also includes capture options for the app.
    • Resource Inspector - Displays a list of all resources bound on the GPU within the frame and shows when they were used via event ID (EID). You can quickly find render targets, temporary buffers, textures, shaders, and other resources.
    • Statistics - Provides basic information on the captured frame, including number of draw and API calls, texture information, and GPU memory usage.
    • When a development app has been successfully launched from the Launch Application tab, a new tab will appear named for the connected device and the Android package running on it. This tab is used to take and save frame captures.

Note: Some of these tabs may not be present when you first open RenderDoc. Missing tabs can be added from the Window drop-down menu on the menu bar.

Connect Oculus Quest to RenderDoc

A wired USB-C connection is required between the computer running RenderDoc and the target Oculus Quest on which the app being analyzed will run. To set up the connection between RenderDoc and Oculus Quest, follow these steps:

  1. Connect the Oculus Quest to the computer using a USB-C cable. Put on the headset and select Accept if the device requests permission to allow the computer to access its files.
  2. Open a command prompt and enter adb devices to confirm the Oculus Quest is properly connected to the PC. If the device is connected properly, its device ID will be listed as shown in this example:
    List of devices attached
     ce0551e7                device
    

    Note: If the Oculus Quest is not displaying the access prompt or is not showing up in the ADB device list, the most likely issue is that the correct USB driver is not installed (see Device Setup – Oculus Quest for more information). Another recommendation is to try a different USB cable or port on the computer. See ADB for more information on using ADB with Oculus Quest.

  3. In RenderDoc, go to the bottom-left corner, click Replay Context: Local, and select the attached device, which is likely listed as Oculus Quest (Offline).
    Replay Context

    Note: If you do not see the device listed, make sure you’ve followed the steps in Device Setup – Oculus Quest and Android Development Software Setup. The device is most likely not set up or not in Developer Mode.

  4. After the Replay Context has been changed, RenderDoc connects to the Oculus Quest and installs necessary remote server files. After a few seconds, Replay Context will change to Replay Context: Oculus Quest with the status reading Remote server ready. RenderDoc and the Oculus Quest are now connected and ready for an app to be launched for frame capturing.
    Replay Context: Oculus Quest

Launch an Application on Oculus Quest from RenderDoc

RenderDoc works by launching an app APK file on the Oculus Quest, and the remote server installed on the device during connection sends capture data back to RenderDoc. Development APKs can be installed on the Oculus Quest by building in either Unreal, Unity, or Android Studio, or by directly pushing a build using ADB.

To launch a development APK from RenderDoc, follow these steps:

  1. Connect the Oculus Quest to RenderDoc as described in the previous section and select the Launch Application tab.
  2. Click ... next to the Executable Path text box. A File Broswer window will open.
    Executable Path
  3. The File Browser shows all the development build APKs on the Oculus Quest. Select the APK you want to use and click OK. Store builds cannot be used with RenderDoc.
  4. On the Launch Application tab, click the Launch button to run the selected APK on the Oculus Quest.
    Launch
  5. When the app is launched, a new tab named after the device and the running Android package will appear. You are now ready to take frame captures from the Oculus Quest.
    Oculus Quest App Tab

Take a Frame Capture

Once the app is running on the connected Oculus Quest and RenderDoc is displaying its tab, follow these steps to take a frame capture:

  1. On the Oculus Quest, get to the part of your app that you want to test. Focus on areas where there are performance and rendering issues and other unexpected behaviors. You should also look at areas performing as expected for comparison.
  2. Select the tab for the app running on the Oculus Quest. To take a capture, click Capture Frame(s) Immediately. RenderDoc will intercept all calls, assets, and other data relevant to the graphics context and save them in an .rdc capture file on the Oculus Quest.
    • Available capture options in the tab include the ability to capture multiple sequential frames, a Capture After Delay setting that allows you to set a delay in seconds before captures will be taken, and a Capture Specific Frame(s) setting that allows the targeting of specific frames.
      Capturing a Frame in RenderDoc
  3. Captures will appear in the Captures collected: section of the Oculus Quest app’s tab. Since development apps may be prone to memory issues and crashes, it is recommended that you right-click and save your captures to your PC. Saving transfers the capture’s .rdc file from the Oculus Quest to the host computer and may take a few seconds.

    Note: When opening a capture taken from an Oculus Quest, the RenderDoc and the PC must still be connected to an Oculus Quest as described earlier in this guide. Other Oculus Android devices may be able to open Oculus Quest .rdc captures, but this is not supported and may result in unpredictable behavior.

  4. You can open the capture by double-clicking it in the Captures Collected: section or by selecting File > Open from the menu bar.

    Note: If the Oculus Quest app crashes when a capture is attempted, it typically means the device is out of system memory. To take a RenderDoc capture on the Oculus Quest, there must be enough memory available on the device to support the following:

    • Memory used by the app.
    • Memory used by the RenderDoc capture layer.
    • The .rdc files generated during the capture process.

Analyzing a RenderDoc Capture

A RenderDoc frame capture contains a lot of data, and it can be difficult to know where to start when analyzing a capture. This section contains recommendations for initial analysis on a new frame capture.

When opening a saved capture taken from an app on an Oculus Quest, the PC running RenderDoc must have an Oculus Quest connected to it as described in the “Connect Oculus Quest to RenderDoc” section of this topic.

Get an Overview of the Frame

After you have opened a capture, we recommend getting started by selecting the Statistics tab. Information on this tab applies to the entire frame, not just the currently selected call in the Event Browser. For initial analysis, look at the following information:

  • The draw call count can be used to give you an idea of render/main thread usage. On Oculus Quest, the guideline is to target 50-100 draw calls per frame.
  • Information on textures and GPU memory usage in the frame can also be found in this tab. This should be checked to confirm that it meets your expectations. While optimizing memory use is important to application performance, the draw call count provides a more useful point of data for optimization than the use of GPU memory in a single frame.

Statistics Tab

If the draw call count or GPU memory use are not in line with recommendations or expectations, reducing the number of calls and optimizing assets to minimize memory usage can be considered key optimization goals before you even begin looking at individual draw calls. In situations where both the call count and memory usage could use optimization, greater performance gains typically come from reducing the call count.

Visualize Draws and Examine Relative Call Timings

Once you have an overview of the frame, you can move on to examining individual draw calls. Select the Texture Viewer tab. From here, you can select individual draw calls in the Event Browser and examine the associated inputs and outputs.

Texture Viewing Tab Showing Outputs

To begin examining draw calls, you can follow these recommendations:

  1. After the frame capture has loaded, click the clock button at the top of the Event Browser to populate the Duration column. These values indicate the relative duration of each call or group of calls.
  2. In the Event Browser, select a draw call to investigate. When debugging, use the Duration column to identify calls that are taking longer than others in the frame. A range of values in the EID column indicates a group of calls.
  3. On the Texture Viewer tab, the main area will populate with data from that call. If you selected a group of calls, the data and resources for the last call in the group will be displayed.
  4. On the right side of the Texture Viewer, the Inputs and Outputs tabs can be used to see the input and output resources associated with the selected call. Click the Outputs tab to show thumbnails of the render target and depth/stencil buffer below it. Click the render target thumbnail to have it display in the main area of the Texture Viewer.
  5. Above the main area, select Highlight Drawcall from the Overlay drop-down menu. This option highlights the currently selected draw call in the render target while dimming the rest. This makes the objects drawn by the call stand out for faster analysis. When looking at a call that is taking too long or behaving unexpectedly, the highlighted portions of the target should be investigated for potential issues and optimization.

Following these steps, we recommend investigating draw calls that that have longer durations than others for optimization opportunities. Typical sources of long draw calls include complex shaders, issues with input resources or their properties, and rendering order issues.