Testing and Performance Analysis

Important

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.


We're no longer accepting submission of 32-bit Oculus Quest apps. Any new or updated Oculus Quest application needs to be 64-bit. Please contact Oculus if you are unable to comply with this policy. Oculus Go and Gear VR apps will not be affected by this change.

In this guide, we’ll review baseline targets, recommendations, tools, resources, and common workflows for performance analysis and bug squashing for Unity VR applications.

General Tips

VR application debugging is a matter of getting insight into how the application is structured and executed, gathering data to evaluate actual performance, evaluating it against expectation, then methodically isolating and eliminating problems.

When analyzing or debugging, it is crucial to proceed in a controlled way so that you know specifically what change results in a different outcome. Focus on bottlenecks first. Only compare apples to apples, and change one thing at a time (e.g., resolution, hardware, quality, configuration).

Always be sure to profile, as systems are full of surprises. We recommend starting with simple code, and optimizing as you go - don’t try to optimize too early.

We recommend creating a non-VR version of your camera rig so you can swap between VR and non-VR perspectives. This allows you to spot check your scenes, and it may be useful if you want to do profiling with third-party tools (e.g., Adreno Profiler).

It can be useful to disable Multithreaded Rendering in Player Settings during performance debugging. This will slow down the renderer, but also give you a clearer view of where your frame time is going. Be sure to turn it back on when you’re done!

Performance Targets

Before debugging performance problems, establish clear targets to use as a baseline for calibrating your performance.

These targets can give you a sense of where to aim, and what to look at if you’re not making frame rate or are having performance problems.

Below you will find some general guidelines for establishing your baselines, given as approximate ranges unless otherwise noted.

Android

  • 60 FPS for Oculus Go and 72 FPS for Oculus Quest (required by Oculus)
  • 50-100 draw calls per frame
  • 50,000-100,000 triangles or vertices per frame

Unity Profiling Tools

This section details tools provided by Unity to help you diagnose application problems and bottlenecks.

Unity Profiler (CPU/GPU Usage, and more)

Unity’s built-in profiler provides valuable information about how your app is using resources (see Unity’s Profiler manual). The Unity Profiler provides per-frame CPU and GPU performance metrics, which can be used to help identify bottlenecks. You should lock your CPU/GPU level before profiling to get consistent profiling results and measure improvements.

You may profile your application as it is running on your Android device using adb or Wi-Fi. For steps on using the Unity profiler, refer to the Unity documentation: GPU Profiler.

Note: The Unity GPU Profiler does not work with GearVR devices.

You should lock your CPU/GPU level before profiling to get consistent profiling results and measure improvements. See the Android Development guide for information on setting CPU/GPU levels.

Unity GPU Profiler

The Unity profiler displays performance metrics for your application. If your app isn’t performing as expected, you may need to gather information on what the entire system is doing.

The total draw call results from the GPU profiler may not be absolutely accurate due to profiling overhead. We recommend using this value as a comparison when profiling builds.

Show Rendering Statistics

Unity provides an option to display real-time rendering statistics, such as FPS, Draw Calls, Tri and Vert Counts, VRAM usage. While in the Game View, pressing the Stats button above the Game View will display an overlay showing realtime render statistics. Viewing stats in the Editor can help analyze and improve batching for your scene by indicating how many draw calls are being issued and how many are being saved by batching (the OverDraw render mode is helpful for this as well).

Show GPU Overdraw

Unity provides a specific render mode for viewing overdraw in a scene. From the Scene View Control Bar, select OverDraw in the drop-down Render Mode selection box.

In this mode, translucent colors will accumulate providing an overdraw “heat map” where more saturated colors represent areas with the most overdraw.

Unity Frame Debugger

Unity Frame Debugger lets you walk through the order of draw calls for any scene. Even if you’re not actively debugging, it can be very useful for understanding how Unity is putting your scene together. This can be very helpful in debugging pipeline problems.

For more information, see Frame Debugger in Unity 5.0.

Unity Built-in Profiler

Unity Built-in Profiler (not to be confused with Unity Profiler) provides frame rate statistics through logcat, including the number of draw calls, min/max frametime, number of tris and verts, et cetera.

To use this profiler, connect to your device over Wi-Fi using ADB over TCPIP as described in the Wireless usage section of Android’s adb documentation. Then run adb logcat while the device is docked in the headset.

See Unity’s Measuring Performance with the Built-in Profiler for more information. For more on using adb and logcat, see Android Debugging in the Mobile SDK documentation.

Use with Care

Applying recommendations may substantially affect the look and feel of your game. We strongly recommend that you only accept changes that you fully understand. For example, if you accept our recommendation to deactivate the Unity skybox, you will need to replace it with a cube mapped box or sphere and a shader that supports depth testing.

Auditing

To audit an Android project, select File > Build Settings…, and under Platform, select Android. If Switch Platform is not grayed out, click it.

Use

Once you have verified your Build Settings are configured properly, run the Performance Auditing Tool.

  1. Open the VR project you want to audit in the Unity editor.
  2. If you have not already imported the Utilities for Unity package, do so now (for further instructions, see Oculus Unity Getting Started Guide).
  3. In the Unity toolbar, select Tools > Oculus > Audit Project for VR Performance Issues.

For each issue the tool finds, you will be provided with the option of automatically updating your settings to bring them in line with our recommendations.

You may perform the same fix to multiple issues of the same type. Some issues allow multiple resolutions, such as “Optimize Light Baking” shown in the example below:

Click on any object with a reported issue to see the object highlighted in the scene in the Editor so you can quickly find and take a closer look at any affected object. For example, in the report above, clicking on “Couch Hot Rect 2 (Box Collider)” on the left will highlight that Game Object in the Editor.

Oculus Remote Monitor (Android)

The Oculus Remote Monitor client (available for Windows and Mac OS X) connects to VR applications running on remote Android devices to capture, store, and display the streamed-in data.

The VrCapture library is automatically included in projects built by Unity 5 or later, so setup and use of the Oculus Remote Monitor is easy.

Oculus Remote Monitor is available from our Downloads page. For more information about setup, features, and use, see Oculus Remote Monitor in our Mobile SDK guide.

Feature Highlights

  • The Frame Buffer Viewer provides a mechanism for inspecting the frame buffer as the data is received in real-time, which is particularly useful for monitoring play test sessions. When enabled, the Capture library will stream a downscaled pre-distortion eye buffer across the network.
  • The Performance Data Viewer provides real-time and offline inspection of the following on a single, contiguous timeline:
    • CPU/GPU events
    • Sensor readings
    • Console messages, warnings, and errors
    • Frame buffer captures
  • The Logging Viewer provides raw access to various messages and errors tracked by thread IDs.
  • Nearly any constant in your code may be turned into a knob that can be updated in real-time during a play test.

OVR Metrics Tool

OVR Metrics Tool is an application that provides performance metrics for Oculus Android applications.

OVR Metrics Tool reports application frame rate, heat, GPU and CPU throttling values, and the number of tears and stale frames per second. It is available for download from our Downloads page.

OVR Metrics Tool can be run two modes. In Report Mode, it displays performance report about a VR session after it is complete. Report data may be easily exported as a CSV and PNG graphs.

In Performance HUD Mode, OVR Metrics Tool renders performance graphs as a VR overlay over any running Oculus application.

For more information, see OVR Metrics Tool in our Mobile SDK Guide.

Additional Third-Party Tools

This section describes other tools that we have found useful for debugging and performance analysis.

ETW and GPUView

Event Tracing for Windows (ETW) is a trace utility provided by Windows for performance analysis. GPUView view provides a window into both GPU and CPU performance with DirectX applications. It is precise, has low overhead, and covers the whole Windows system.

Most Unity developers will find the Unity Profiler sufficient, but in some cases ETW and GPUView may be useful for debugging problems such as system-level contention with background processes. For a detailed description of how to use ETW with our native Rift SDK, see VR Performance Optimization in our PC SDK Developer Guide. Not all of the content will be relevant to the Unity developer, but it contains a lot of applicable conceptual material that may be very useful.

Systrace

Reports complete Android system utilization. Available here: http://developer.android.com/tools/help/systrace.html

NVIDIA NSight

NSight is a CPU/GPU debug tool for NVIDIA users, available in a Visual Studio version and an Eclipse version.

APITrace

https://apitrace.github.io/

Android Tips

This section describes basic techniques for performance analysis for Android development.

Use Oculus Remote Monitor (Android) for VRAPI, render times, and latency. Systrace shows CPU queueing.

It is a common problem to see Gfx.WaitForPresent appear frequently in Oculus Remote Monitor. This reports the amount of time the render pipeline is stalled, so begin troubleshooting by understanding your scene is assembled by Unity - the Unity Frame Debugger is a good starting place. See Unity Profiling Tools for more information.