Oculus Remote Monitor and VrCapture

Integration

Integrate VrCapture into your applications for greater visibility into performance and to supplement the default data captured by VrApi’s built-in integration. It is also automatically supported in Unity 5.1 and later.

Linking/Including with ndk-build

If your application uses ndk-build-based makefiles, linking to VrCapture is easy.

1. Include the following at the bottom of your Android.mk:

   $(call import-module,VrCapture/Projects/Android/jni)

2. Add LOCAL_STATIC_LIBRARIES += vrcapture between include $(CLEAR_VARS) and include $(BUILD_SHARED_LIBRARY).

VrCapture will now be compiled and linked into your application, your header search paths will be set up properly, and VrCapture will be automatically compiled to your target architecture.

Linking/Including manually

If you have a custom build system, follow this procedure instead:

1. Build VrCapture library:

   cd VrCapture/Projects/Android
   ndk-build -j16

2. Add the header search path to your compiler line:

   -IVrCapture/Include

3. Add the library to your link line:

   -LVrCapture/Projects/Android/obj/local/$(TARGET_ARCH)
   -lvrcapture

Init and Shutdown

Note that VrCapture will do nothing until it is initialized (e.g., no sockets, threads, allocations).

1. Include the primary VrCapture header:

   #include <OVR_Capture.h>

2. Near the beginning of execution of your application, add:

   OVR::Capture::Init();

3. Near the end of execution of your application, add:

   OVR::Capture::Shutdown();

We recommend not shipping your application with capture turned on by default.

VrApi provides a mechanism for you to query if Capture is enabled in VrApi_LocalPrefs.h.

ovr_GetLocalPreferenceValueForKey(LOCAL_PREF_VRAPI_ENABLE_CAPTURE);

CPU Zones

The ability to handle a large number of performance zones is a core feature of Oculus Remote Monitor. We conservatively recommend keeping the number of events/frame to under 1000. A CPU zone begins with a simple, one-line declaration (see below) and ends when it goes out of scope. Zones may be used to measure the execution time of a block of code with extremely low overhead, e.g.:

void SomeFunction(void)
{
OVR_CAPTURE_CPU_ZONE(SomeFunction);
// Do Something Expensive Here
}

Parameters

Declare a float constant as a capture parameter to allow users to adjust its value in real-time from the Oculus Remote Monitor parameter screen. Potential use cases include lighting intensity or update frequencies. Note that parameters for CPU and GPU rates are already exposed.

To declare and use a capture variable in your code, use GetVariable() with an identifying label, a default value, and a min/max. When not connected to Oculus Remote Monitor, GetVariable() will immediately return the default value. Otherwise, it returns the latest value from Oculus Remote Monitor.

In this example, SpecularPower is declared with a default value of 16, but Oculus Remote Monitor can override it with user input (between 1 and 128):

OVR_CAPTURE_CREATE_LABEL(SpecularPower);
const float specularPower = OVR::Capture::GetVariable(OVR_CAPTURE_LABEL_NAME(SpecularPower), 16.0f, 1.0f, 128.0f);
glUniform1f(uSpecularPower, specularPower);

Local Capture

The SDK includes support for capturing straight to a local file rather than waiting for a remote connection. This facilitates automated performance testing, startup time benchmarking, and dealing with poor network performance. It currently requires a number of manual steps to enable, pull, and disable.

To enable local capture for VrApi:

1. Make sure your application has WRITE_EXTERNAL_STORAGE permissions.
2. Enable capture to file with the following:

   adb shell setprop debug.oculus.enableCapture /sdcard/mycapture.dat

3. Run your app and let it play until you have captured the data that you need, then exit.
4. To compress and download the capture file, run the following on a local terminal:

   adb shell gzip -9 /sdcard/mycapture.dat

   adb pull /sdcard/mycapture.dat.gz capture.dat

5. Disable capture when complete:

   adb shell setprop debug.oculus.enableCapture 0

6. Open capture.dat in Oculus Remote Monitor.