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.

OVR Metrics Tool

OVR Metrics Tool can be used to provide performance metrics for Oculus applications running on Android devices, including frame rate, heat, GPU and CPU throttling values, and the number of tears and stale frames per second. OVR Metrics Tool provides this data via an onscreen graph over a running app or a recorded report that can be retrieved from the device. OVR Metrics Tool also offers remote device management functionality.

OVR Metrics Tool is available on our OVR Metrics Tool download page.

Overview

OVR Metrics Tool is an Oculus mobile tool that can provide performance information about a running app. Much of this performance information is similar to that provided by VrApi logcat logs. OVR Metrics Tools provides access to that information from an on-device app rather than the command line. See the logcat topic for information on using logcat.

OVR Metrics Tool has two modes. In Report Mode, the tool records a performance report about a VR session that can be read after it has concluded. Report data can be easily exported as a CSV with PNG images. In Performance HUD Mode, the tool displays a HUD overlay over running apps that provide real-time performance graphs and information. The information displayed on the performance HUD can be customized to preference.

See the Statistics Defininition Guide for information on all of the statistics OVR Metrics Tool can track.

Collect Performance Data with OVR Metrics Tool

The following sections describe how to install OVR Metrics Tool and use it to capture performance information for an app in Report Mode and Performance HUD Mode.

Preparation

The Oculus mobile device being used with OVR Metrics Tool must be in Developer Mode. The Android SDK must be installed and configured on the computer installing OVR Metrics Tool in order to establish an ADB connection. If you have followed the instructions in Device Setup and Android Development Software Setup, you should be ready to use OVR Metrics Tool.

Installation

The package containing the OVR Metrics Tool APK is available on our Downloads page. Install OVRMetricsTool_v1.4.apk on a connected Oculus mobile headset in developer mode via ADB. See ADB to learn about how to install APKs via ADB.

OVR Metrics Tool Usage

The OVR Metrics Tool app can be launched from the Unknown Sources section of the VR device’s app Library. It can also be launched by connecting the device to a computer via ADB and issuing the following command:

adb shell am start omms://app

When OVR Metrics Tool launches on the headset, the main screen looks like this:

OVR Metrics Tool main screen

From the main screen you can enable and configure the features of the tool.

Report Mode

Report mode records performance data from a VR session. Data from the reports can be retrieved from the device or viewed while in the headset.

To enable report mode, enable the toggle labeled Record all captured metrics to csv files. You can also enable report mode by issuing the following ADB command:

adb shell setprop debug.oculus.omms.enableOverlay true

Once enabled, you must manually select the metrics to be collected on the Stats tab or by using one of the preset option buttons:

  • Basic includes the following metrics:
    • FPS
    • CPU level
    • GPU level
    • Stale frame count
    • CPU utilization
    • GPU utilization
    • Available memory
    • App GPU time
  • Advanced includes everything in Basic as well as the following metrics:
    • Extra latency mode
    • Foveation level
    • Prediction
    • Early frame count
    • Eye buffer width
    • Eye buffer height
    • Used memory
    • Asynchronous TimeWarp (ATW) GPU time

After choosing metrics, run an app and conduct a session to collect data. Note that data will be logged from every app run. After the session, open OVR Metrics Tool, click the drop-down menu in the upper-right corner, and select View Recorded Sessions. Select the entry that corresponds to your session to see a series of graphs describing performance. Recorded sessions can be retrieved from /OVRMonitorMetricsService/CapturedMetrics/ as a CSV file when the device is connected to a computer.

Performance HUD Mode

Performance HUD mode displays a real-time graph showing selected metrics over running apps. To enable performance HUD mode, from the main screen, enable the toggle labelled Enable Persistent Overlay (may require reboot). You can also enable the HUD by issuing the ADB command:

adb shell setprop debug.oculus.omms.enableOverlay true

After enabling the HUD, you may have to reboot your device for it to appear. The HUD will resemble the following depending on the chosen metrics:

Performance HUD over app

By default, no metrics will be displayed on the HUD, although the FPS graph will be present. You must manually select the displayed metrics on the Stats tab or by using the Basic and Advanced buttons described in the Report Mode section.

Below the buttons are more options for the overlay. Stats and metrics on the graph can be toggled (enabled by default). The Render Overlay on GPU option toggles hardware rendering of the overlay and is enabled by default.

Lock Overlay to Head is enabled by default. Disabling this unlocks the HUD from view and positions it in space, but this can be unpredictable and is not recommended. Below this toggle are options for the scale and position of the HUD.

Many of the above options can be controlled from the command line:

adb shell setprop debug.oculus.omms.enableGraph (true|false) // show or hide the graph
adb shell setprop debug.oculus.omms.enableStats (true|false) // show or hide the stats
adb shell setprop debug.oculus.omms.pitch (number) // set the pitch of the perf hud (degrees from center)
adb shell setprop debug.oculus.omms.yaw (number) // set the yaw of the perf hud (degrees from center)
adb shell setprop debug.oculus.omms.distance (number) // set the distance of the perf hud (meters)
adb shell setprop debug.oculus.omms.scale (number) // set the scale of the perf hud (1,2, or 3)
adb shell setprop debug.oculus.omms.headLocked (true|false) // whether to head lock the hud or position it in space

The Screenshot on Dropped Frames option is at the bottom of the main screen. Enabling this option takes a screenshot if the number of dropped frames exceeds the set limit for the specified time.

Remote Device Management

To enable remote device management, enable the Allow settings to be modified over Bluetooth toggle is enabled on both the device you wish to control, and the device from which you will be controlling. You can also enable remote management by using the following command:

adb shell setprop debug.oculus.omms.enableBT true

Next, select Connect to Device from the drop-down menu in the upper-right corner of the main screen. This will search for local Oculus devices over Bluetooth that have remote management enabled. Select a device to connect to it. Once connected, you can configure the HUD of the remote device and receive real-time stats to the local device.