Oculus Go Development

On 6/23/20 Oculus announced plans to sunset Oculus Go. Information about dates and alternatives can be found in the Oculus Go introduction.

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.

Monitor Performance with OVR Metrics Tool

OVR Metrics Tool can be used to provide various performance metrics for Oculus mobile 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.

OVR Metrics Tool 1.5 introduces a number of new statistics that require the profiling tool ovrgpuprofiler to be enabled from a connected shell. See the ovrgpuprofiler for information on enabling the tool. Version 1.5 also introduces the OVR Metrics Tool toolkit for Unity and native mobile developers.

See the OVR Metrics Tool and VrApi Stats 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.

Installation

The package containing the OVR Metrics Tool APK is available on our Downloads page. Use ADB to install OVRMetricsTool_v1.4.apk on a connected Oculus mobile headset in Developer Mode. See ADB to learn about how to install APKs with 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

OVR Metrics Tool 1.5 introduces a number of new statistics that are not enabled with either the Basic or Advanced button. These statistics must be selected manually from the Stats tab, and some require that the profiling tool ovrgpuprofiler is enabled from a connected shell before they can be selected. See the ovrgpuprofiler for information on enabling the tool. These statistics include the following:

  • Guardian GPU Time
  • CPU Utilization Core 0-7
  • Application VSS, RSS, and Dalvik PSS

ovrgpuprofiler metrics

  • Average Vertices Per Frame
  • Average Fill Percentage per Eye
  • Average Instructions per Fragment
  • Average Instructions per Vertex
  • Average Textures per Fragment
  • Percentage Time Shading Fragments
  • Percentage Time Shading Vertices
  • Vertex Fetch Stall Percentage
  • Texture Fetch Stall Percentage
  • L1 Texture Miss Percentage
  • L2 Texture Miss Percentage
  • Texture Sample Percentage Using Nearest Filtering
  • Texture Sample Percentage Using Linear Filtering
  • Texture Sample Percentage Using Anisotropic Filtering

After choosing metrics, run an app and conduct a session to collect data. Note that data will be logged for 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.

OVR Metrics Tool Toolkit for Unity and Native Mobile

The OVR Metrics Tool toolkit exposes two calls that can be integrated into your application. The toolkit is available for Unity and native Mobile development and included with the OVR Metrics Tool download.

Append CSV Debug String

AppendCSVDebugString is used to append custom developer data into the CSV that is produced when the Record To CSV option is selected. The debug data will be placed in the last column of the CSV, if data is entered at a higher frequency than 1 Hz, data will be placed on a new line in the CSV with empty metric columns. The suggested use for this is to mark scene transitions to aid in CSV analysis.

This method can be accessed using the Unity SDK by calling

OVRMetricsToolSDK.Instance.AppendCsvDebugString(debugString);

This method can be accessed using the native Mobile SDK by calling:

ovrMetricsTool_AppendCsvDebugString(format, {format params});

Set Overlay Debug String

SetOverlayDebugString is used to display custom information on the OVR Metrics Tool Overlay. To make this data visible, make sure Show Debug Data is enabled. The data will appear at the bottom of the overlay. The overlay debug string can be updated once per frame, and will not be persisted. By default the overlay debug string will be white, but the color can be customized by including <color=#{hex value}>...</color> tags in the string.

The following method sets the string in Unity:

OVRMetricsToolSDK.Instance.SetOverlayDebugString(debugString);

The following method sets the string in the native Mobile SDK

ovrMetricsTool_SetOverlayDebugString(format, {format params});

Native Mobile Setup and Teardown

When using the toolkit native Mobile SDK, it is important that setup and teardown are handled appropriately.

When vrapi_Initialize is called, the following should be called:

bool ovrMetricsTool_Initialize(JavaVM* jvm, JNIEnv* jni, jobject context);

When vrapi_EnterVrMode is called, call the following:

bool ovrMetricsTool_EnterVrMode();

When vrapi_LeaveVrMode is called, call the following:

void ovrMetricsTool_LeaveVrMode();

Finally, when vrapi_Shutdown is called, call:

void ovrMetricsTool_Shutdown();