Archived Documentation

This version of the guide is out of date. Click here for the latest version.

Android System Properties and Local Preferences

Useful testing and debugging device configuration options may be controlled by Android System Properties or Local Preferences.

Local Preferences are a set of key-value pairs written to /sdcard/.oculusprefs that are useful for storing debug settings that are tied to a device, rather than a particular application or user.

The values controlled by Local Preferences are mapped as Android System Properties on phones running System Activities 1.0.3.0 or later.

We recommend controlling settings with System Properties rather than Android System Properties, as they do not require enabling Developer Mode or SD card read access.

Local Preferences and System Properties may both be set independently. If SD Card read access is provided by your application and Developer Mode is enabled on your mobile device, then any Local Preferences settings (including defaults) will override the corresponding Android System Properties settings.

System Properties

Note: System Properties reset when the device reboots. All commands are case sensitive.

Basic Usage

Set value:

adb shell setprop <name> <value>

Example:

adb shell setprop debug.oculus.frontbuffer 0

Result: Disables front buffer rendering.

Get current value:

adb shell getprop <name>

Example:

adb shell getprop debug.oculus.gpuLevelENTRY

Result: Returns currently-configured GPU Level, e.g., 1.

Get all current values:

adb shell getprop | fgrep "debug.oculus"

Result: Returns all System Preferences settings on the device.

System PropertyValuesFunction

debug.oculus.enableCapture

0, 1

Enables support for Oculus Remote Monitor to connect to the application.

debug.oculus.cpuLevel

0, 1, 2, 3

Changes the fixed CPU level.

debug.oculus.gpuLevel

0, 1, 2, 3

Changes the fixed GPU level.

debug.oculus.asyncTimewarp

0, 1

Set to 0 to disable Asynchronous TimeWarp/enable Synchronous TimeWarp. Default is 1 (ATW is enabled).

debug.oculus.frontbuffer0, 1Disable/enable front buffer.
debug.oculus.calibrationLines0, 1Disable/enable calibration lines.

debug.oculus.gpuTimings

0, 1, 2

Turns on GPU timings in logcat (off by default due to instability). A setting of 2 is necessary on phones using the Mali GPU.

debug.oculus.simulateUndock-1, 0, 1, …, 10Simulate an undocking event after the specified number of seconds.

debug.oculus.enableVideoCapture

0, 1

When enabled, each enterVrMode generates a new mp4 file in /sdcard/oculus/VideoShots/. Videos are full resolution, undistorted, single-eye, with full-compositing support. Defaults are 1024 resolution at 5 Mb/s.

debug.oculus.phoneSensors0, 1Set to 0 to disable limited orientation tracking provided by phone sensors while in Developer Mode (enabled by default).

Local Preferences

Note: Modifying Local Preferences requires that your application have READ_EXTERNAL_STORAGE permission. Modifying System Properties does not require read access, and we generally recommend using that method instead.

For security reasons, Local Preferences are not allowed unless Developer Mode is enabled for your device. To enable Developer Mode for your device, please refer to Developer Mode.

All commands are case sensitive.

The following Local Preferences are currently available via the Unity and Unreal integrations and VR app framework:

Local PreferenceValuesFunction

dev_enableCapture

0, 1

Enables support for Oculus Remote Monitor to connect to the application.

dev_cpuLevel

0, 1, 2, 3

Changes the fixed CPU level.

dev_gpuLevel

0, 1, 2, 3

Changes the fixed GPU level.

dev_gpuTimings

0, 1, 2

Turns on GPU timings in logcat (off by default due to instability). A setting of 2 is necessary on phones using the Mali GPU.

dev_asyncTimewarp

0, 1

Set to 0 to disable Asynchronous TimeWarp/enable Synchronous TimeWarp. Default is 1 (ATW is enabled).

dev_frontbuffer0, 1Disable/enable front buffer.

dev_videoCapture

0, 1

When enabled, each enterVrMode generates a new mp4 file in /sdcard/oculus/VideoShots/. Videos are full resolution, undistorted, single-eye, with full-compositing support. Defaults are 1024 resolution at 5 Mb/s.

dev_usePhoneSensors0, 1Set to 0 to disable limited orientation tracking provided by phone sensors while in Developer Mode (enabled by default).
Note: When measuring GPU rendering times, we recommend setting dev_asyncTimewarp to 0 to avoid inflating the eye buffer rendering times with the TimeWarp rendering times. Be sure to re-set dev_asyncTimewarp to 1 when testing is complete, as disabling ATW in normal operation is never advised and may cause judder.

To set a local preference value, you may do the following via command line:

adb shell "echo dev_gpuTimings 1 > /sdcard/.oculusprefs"

You may also set multiple values at once:

adb shell "echo dev_cpuLevel 1 dev_gpuLevel 2 > /sdcard/.oculusprefs"

To add values to append to an existing set of preferences:

adb shell "echo dev_asyncTimewarp 0 >> /sdcard/.oculusprefs"

To remove all local preference settings:

adb shell "rm /sdcard/.oculusprefs"

After setting the values, pause and then resume your app for the Local Preferences file to be updated.

Note: Remember to clear or remove your local prefs file when finished so there are no surprises.

For native applications, you may query your own Local Preferences debug option with the following:

const char * myDebugOptionStr = ovr_GetLocalPreferenceValueForKey( "myDebugOption", "0" );
    
    if ( atoi( myDebugOptionStr ) > 0 )
    {
    // perform debug code
    }