This guide describes basic testing and performance analysis for Oculus development 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.
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.
For more information, see:
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.
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.
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.
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.
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 in 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.
Mali Graphics Debugger
If you have a Mali phone, such as a GALAXY S6, you can use the Mali Graphics Debugger built into Unreal by selecting it by opening Project Settings, selecting the Android option on the left, and setting Graphics Debugger to Mali Graphics Debugger.
Note that because there are no swap buffers in VR, Gear VR does not currently support frame delimiters. Consequently, application frames will be displayed as different render passes of the same frame.
Version 1.16 and later of the Oculus branch of Unreal provides RenderDoc support.
Gear VR support in RenderDoc is an experimental feature, so you must download a nightly build of RenderDoc to access it. To verify that you have the right version, confirm that your RenderDoc installation includes an android/ subfolder in its root path.
To use RenderDoc, open Project Settings in Unreal and select the Android option on the left. Set Graphics Debugger to RenderDoc.
The RenderDocCmd.apk application must be installed on the target device before debugging. Run the following command from the android/apk/32 directory of your RenderDoc installation:
adb install -r RenderDocCmd.apk
If your phone is not auto-recognized as a Remote server in the Tools > Manage Remote Server section, add it by typing adb:<device-id> in the Add section.
To attach to an application, run it and locate it in Tools > Manage Remote. To capture a frame, click on the Trigger Capture button. Save the capture locally and double-click it in RenderDoc to replay.
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:
For more information on using GDB for debugging, see the GNU GDB documentation.
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.
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 Unreal developer, but it contains a lot of applicable conceptual material that may be very useful.
Reports complete Android system utilization. Available here: http://developer.android.com/tools/help/systrace.html
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
For detailed information about Oculus development, go to: