developers
Login

This website uses cookies to improve our services and deliver relevant ads.
By interacting with this site, you agree to this use. For more information, see our Cookies Policy

Testing and Performance Analysis in Unreal

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.

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.

Mobile

  • 60 FPS (required by Oculus Store)
  • 50-100 draw calls per frame
  • 50,000-100,000 triangles or vertices per frame

PC

  • 90 FPS (required by Oculus Store)
  • 500-1,000 draw calls per frame
  • 1-2 million triangles or vertices per frame

For more information, see:

Rift Performance HUD

The Oculus Performance Heads-Up Display (HUD) is an important, easy-to-use tool for viewing timings for render, latency, and performance headroom in real-time as you run an application in the Oculus Rift. The HUD is easily accessible through the Oculus Debug Tool provided with the PC SDK. You may activate it in the Viewport by pressing the ~ key.

For more details, see the Performance Heads-Up Display and Oculus Debug Tool sections of the Oculus Rift Developers Guide.

Rift Compositor Mirror

The compositor mirror is an experimental tool for viewing exactly what appears in the headset, with Asynchronous TimeWarp and distortion applied.

The compositor mirror is useful for development and troubleshooting without having to wear the headset. Everything that appears in the headset will appear, including Oculus Home, Guardian boundaries, in-game notifications, and transition fades. The compositor mirror is compatible with any game or experience, regardless of whether it was developed using the native PC SDK or a game engine.

For more details, see the Compositor Mirror section of the PC SDK Guide.

Debug Console (Mobile)

If your phone is set to Developer Mode, you may bring up a debug console for VR apps by pressing the screen with four fingers simultaneously while the application is running.

Enter stat unit in the console for information about your application frame rate and CPU performance.

Oculus Remote Monitor (Mobile)

The Oculus Remote Monitor client connects to VR applications running on remote mobile devices to capture, store, and display the streamed-in data. The VrCapture library is automatically included in Unreal projects, 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.

  • 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.

GDB Debugging (Mobile)

Oculus branches of Unreal add support for debugging mobile sessions using ndk-gdb, a small shell script wrapped around GNU GDB that is included with the Android NDK.

Using ndk-gdb from the command line adds convenient features to your debugging workflow by allowing, for example, adding breakpoints, stepping through code, and inspecting variables with a command line interface.

To use ndk-gdb for debugging:

  1. Enable remote port forwarding to link your target mobile port to a PC port: adb forward tcp:$port tcp:$port
  2. Set your device to Developer Mode (as described in our Mobile Developer Guide here).
  3. Launch the application you wish to debug.
  4. Start gdbserver on the mobile device with the following Unreal console command: gdbserver $port where $port is your port number. You application should freeze, and will now be ready for debugging.
  5. Launch the ndk-gdb client from the command line on your computer with the command gdb.exe. When it launches, type target remote :$port in the GDB command line to attach to your mobile device.

For more information on using GDB for debugging, see the GNU GDB documentation.

Additional Third-Party Tools

ETW + 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. Custom event manifests.

ETW profiles the whole system, not just the GPU. For a sample debug workflow using ETW to investigate queuing and system-level contention, see Example Workflow: PC below.

Windows 10 replaces ETW with Tracelogging.

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.

Mac OpenGL Monitor

An OpenGL debugging and optimizing tool for OS X. Available here: https://developer.apple.com/library/mac/technotes/tn2178/_index.html#//apple_ref/doc/uid/DTS40007990

APITrace

https://apitrace.github.io/

Other Resources

For detailed information about Oculus development, go to:

Contact

Visit our developer support forums at https://developer.oculus.com.

Our Support Center can be accessed at https://support.oculus.com.

Previous: Unreal Samples
Next: Release Notes