Optimizing Your Application. Oculus RIFT

Oculus Rift | Optimizing Your Application | 65

Optimizing Your Application

To provide the best user experience, your application must meet or exceed the minimum requirements to be considered for publication on the Oculus Store.

For more information about publishing requirements, see our

Publishing

documentation.

This section describes how to use tools we provide to optimize the performance of your application.

SDK Performance Statistics

The SDK performance statistics provide information about application and compositor performance on the system.

Stats are populated after each call to ovr_SubmitFrame. To get performance stats, use ovr_GetPerfStats().

To reset the stats, use ovr_ResetPerfStats.

Note: If your performance tool runs separately from your application, make sure to read the

VisibleProcessId in case your application loses focus.

The following table describes performance statistics:

Table 1: Statistics

Statistics

Description ovrPerfStatsPerCompositorFrame

AnyFrameStatsDropped

AdaptiveGpuPerformanceScale

The per-compositor frame statistics in the following tables.

If the app calls ovr_SubmitFrame at a rate less than 18 fps, then when calling ovr_GetPerfStats, expect AnyFrameStatsDropped to become ovrTrue while FrameStatsCount is equal to ovrMaxProvidedFrameStats.

An edge-filtered value that you can use to adjust the graphics quality of the application to keep the

GPU utilization in check. The value is calculated as:

(desired_GPU_utilization / current_GPU_utilization).

When this value is 1.0, the GPU is doing the right amount of work for the app. Lower values mean the application needs to reduce the GPU utilization.

Note: If the app directly drives render-target resolution using this value, make sure to take the square-root of the value before scaling the resolution with it.

Changing the render target resolution is only one of the many things your application can do increase or decrease the amount of GPU utilization. Since

66 | Optimizing Your Application | Oculus Rift

Statistics

Description

AswIsAvailable

AdaptiveGpuPerformanceScale is edge-filtered and does not change rapidly (i.e., it reports non-1.0 values once every couple of seconds), your application can make the necessary adjustments and continue watching the value to see if it has been satisfied.

Returns true if ASW is available for this system, based on the user's GPU, operating system, and debug override settings.

The following table describes statistics specific to your application's performance:

Table 2: Application Statistics

Statistic

Description

AppFrameIndex

AppDroppedFrameCount

AppMotionToPhotonLatency

AppQueueAheadTime

AppCpuElapsedTime

Index that increments with each ovr_SubmitFrame call.

Increments each time the application fails to submit a new set of layers using ovr_SubmitFrame() before the compositor is executed before each V-Sync (Vertical

Synchronization).

Latency from when the last predicted tracking information was queried by the application using ovr_GetTrackingState() to when the middle scanline of the target frame is illuminated on the HMD display.

This is the same information provided by the Latency

Timing HUD.

To improve CPU and GPU parallelism and increase the amount of time that the GPU has to process a frame, the SDK automatically applies queue ahead up to 1 frame. This value displays the amount of queue ahead time being applied (in milliseconds). For more information about adaptive queue ahead, see

Adaptive Queue Ahead

on page 30.

The time difference from when the application continued execution on CPU after ovr_SubmitFrame() returned the subsequent call to ovr_SubmitFrame().

This will show "N/A" if the latency tester is not functioning as expected (e.g., HMD display is sleeping due to prolonged inactivity). This includes the IPC call overhead to the compositor after ovr_SubmitFrame() is called by the client application.

AppGpuElapsedTime

The total GPU time spent on rendering by the client application. This includes the work done by the application after returning from ovr_SubmitFrame(), using the mirror texture if applicable.

It can also includes GPU command-buffer "bubbles" if the application's CPU thread doesn't push data to

Oculus Rift | Optimizing Your Application | 67

Statistic

Description the GPU fast enough to keep it occupied. Similarly, if the app pushes the GPU close to full-utilization, the work on next frame (N+1) might be preempted by the compositor's render work on the current frame

(N). Because of how the application GPU timing query operates, this can lead to artificially inflated application GPU times as they will start to include the compositor GPU usage times.

The compositor operates asynchronously and will increment for each vsync, regardless of whether the application calls ovr_SubmitFrame.

The following table describes compositor statistics:

Table 3: Compositor Statistics

Statistic

Description

CompositorFrameIndex

CompositorDroppedFrameCount

CompositorLatency

CompositorCpuElapsedTime

CompositorGpuElapsedTime

CompositorCpuStartToGpuEndElapsedTime

CompositorGpuEndToVsyncElapsedTime

Index that increments each time the SDK compositor completes a distortion/TimeWarp pass.

Increments each time the compositor fails to present a new rendered frame at V-Sync (Vertical

Synchronization).

Specifies the TimeWarp latency, which corrects app latency and dropped frames.

The amount of time in seconds spent on the GPU by the SDK compositor. Any time spent on the compositor takes available GPU time away from the application.

The amount of time the GPU spends executing the compositor renderer. This includes TimeWarp and distortion of all layers submitted by the application.

The amount of active layers, their resolutions, and the requested sampling quality can all affect the GPU times.

The amount of time from when the CPU kicks off the compositor to when the compositor completes distortion and TimeWarp on the GPU. If the time is not available, it returns -1.0f.

The amount of time between when the GPU completes the compositor rendering to the point in time when V-Sync is hit and that buffer starts scanning out on the HMD.

The Asynchronous SpaceWarp (ASW) HUD displays activity and tracking statistics for ASW, which runs as part of the Oculus Runtime Compositor. ASW automatically activates when an application fails to meet the required native frame rate for the connected HMD. Once active, ASW forces the application to run at half the normal frame rate while extrapolating every other frame. This gives the application more time to complete its work.

68 | Optimizing Your Application | Oculus Rift

The following table describes Asynchronous SpaceWarp (ASW) statistics:

Table 4: ASW Statistics

Statistic

Description

AswIsActive

AswActivatedToggleCount

AswPresentedFrameCount

AswFailedFrameCount

Shows the availability and current status of ASW.

"Not Available" can be due to the OS and/or GPU type used on the PC. "Available - Not Active" will mean the application is successfully maintaining the required native refresh rate, so ASW is not activated.

Tracks the number of times ASW has been activated for the lifetime of the HMD.

Tracks the number of frames extrapolated by ASW that were displayed. When ASW is active, since the app is forced to run at half-rate, expect this value to increase by 45 fps on a 90 Hz refresh rate HMD.

Tracks the number of extrapolated frames ASW needed to display, but failed to prepare in time.

This can occur for different reasons, but might be caused by contention for OS resources or when the capabilities of the system are exceeded.

Oculus Debug Tool

The Oculus Debug Tool enables you to view performance or debugging information within your game or experience.

To use the tool:

1. Make sure that you have admin privilege. This is required in order to run the Oculus Debug Tool.

2. Go to Program Files\Oculus\Support\oculus-diagnostics\OculusDebugTool.exe. Note that the Oculus

Debug Tool should always be run directly from this location, in order to ensure a version match with the Oculus distribution. If you copy the Oculus Debug Tool to another location, it might not work after subsequent Oculus updates.

3. Double-click

OculusDebugTool.exe. The Oculus Debug Tool opens.

4. Select the Visible HUD to view. Options include: None (no HUD is displayed), Performance HUD, Stereo

Debug HUD, or Layer HUD.

5. If you selected Performance HUD, select which Performance HUD you want to view. Options include:

Latency Timing, Render Timing, Performance Headroom, and Version Information. For more information, see

Performance Head-Up Display

on page 72.

The following is an example of the Performance HUD:

Oculus Rift | Optimizing Your Application | 69

6. If you selected Stereo Debug HUD, configure the mode, size, position, and color from the Stereo Debug

HUD options.

The following is an example of the Stereo Debug HUD:

70 | Optimizing Your Application | Oculus Rift

7. If you selected Layer HUD. select the layer for which to show information or select the Show All check box.

The following is an example of the Layer HUD:

Oculus Rift | Optimizing Your Application | 71

8. Select Launch App from the File menu and select the executable of the application.

9. Put on the headset and view the results.

Performance Profiler

The Oculus Performance Profiler displays a graph that shows statistics on the performance of your application.

You can view the statistics in real time or export them to a comma-separated value (CSV) file that you can import into a spreadsheet or database.

Note: For more information about the statistics collected, see

Performance Head-Up Display

on page

72.

To use the tool:

1. Go to Program Files\Oculus\Support\oculus-diagnostics\OculusDebugTool.exe.

2. Double-click

OculusDebugTool.exe. The Oculus Debug Tool opens.

3. Select Performance Profiler from the Mode list box.

4. Select Launch App from the File menu and select the application to profile.

5. Click Start.

6. Have someone put on the headset and start using with the application.

72 | Optimizing Your Application | Oculus Rift

7. View the results on screen.

Figure 13: Peformance Profiler

8. When you are finished, click Stop.

9. To export the results to CSV, click Export data to CSV and save the file.

Performance Head-Up Display

The Performance Head-Up Display (HUD) enables you or your users to view performance information for applications built with the SDK.

The Performance HUD screens are rendered by the compositor, which enables them to be displayed with a single SDK call to ovr_SubmitFrame. In the Oculus Debug Tool or OculusWorldDemo, you can toggle through the Performance HUD screens by pressing F11.

Performance Summary

The Performance Summary HUD displays the frame rate of the application and the unused hardware performance available. This HUD can be used by you or the user to tune an application's simulation and graphics fidelity. Because the user cannot disable V-Sync, it can be used to gauge performance instead of a frame rate counter. It is also useful for troubleshooting whether issues are related to the application or the hardware setup.

The following image shows the Performance Summary HUD:

Figure 14: Performance Summary HUD

Oculus Rift | Optimizing Your Application | 73

The following table describes each metric:

Metric Description

App Motion-to-Photon Latency Latency from when the last predicted tracking information was queried by the application using ovr_GetTrackingState() to when the middle scanline of the target frame is illuminated on the HMD display. This is the same information provided by the Latency Timing HUD.

Unused performance

Designed to help the user verify that the PC is powerful enough to avoid dropping frames, this displays the percentage of available PC performance not used by the application and compositor. This is calculated using the

CPU and GPU time tracked by the Application Render Timing HUD divided by the native frame time (inverse of refresh rate) of the HMD.

Note: As GPU utilization approaches 100%, adaptive queue ahead will choose an earlier render start point. If this start point overlaps with the compositor process in the previous frame, the performance will appear spiky. If you start to lower utilization, the graph will show an initial drop before becoming more linear.

Application Frames Dropped

Compositor Frames Dropped

Increments each time the application fails to submit a new set of layers using ovr_SubmitFrame() before the compositor is executed before each

V-Sync (Vertical Synchronization). This is identical to App Missed Submit

Count in the Application Render Timing HUD.

Increments each time the compositor fails to present a new rendered frame at V-Sync (Vertical Synchronization). This is identical to Compositor Missed

V-Sync Count in the Compositor Render Timing HUD.

74 | Optimizing Your Application | Oculus Rift

Latency Timing

The Latency Timing HUD displays the App to Mid - Photon, Timewarp to Photon - Start, and Timewarp to

Photon - Start graphs.

The following screenshot shows the Latency Timing HUD:

Figure 15: Latency Timing

The following table describes each metric:

Table 5: Latency Timing HUD

Metric

App Tracking to Mid-Photon

Timewarp to Mid-Photon

Flip to Photon - Start

Description

Latency from when the app called ovr_GetTrackingState() to when the target frame eventually was shown (i.e.illuminated) on the HMD display averaged mid - point illumination

Latency from when the last predictied tracking info is fed to the GPU for timewarp execution to the point when the middle scanline of the target frame is illuminated on the HMD display

Time difference from the point the back buffer is presented to the HMD to the point the target frame's first scanline is illuminated on the HMD display

Application Render Timing

The Application Render Timing HUD displays application-specific render timing information.

The following screenshot shows the Application Render Timing HUD:

Figure 16: Application Render Timing

Oculus Rift | Optimizing Your Application | 75

The following table describes each metric:

Table 6: Application Render Timing HUD

Metric Description

App Missed Submit Count

App Frame-rate

Increments each time the application fails to submit a new set of layers using ovr_SubmitFrame() before the compositor is executed and before each V-Sync

(Vertical Synchronization).

The rate at which application rendering calls ovr_SubmitFrame(). It will never exceed the native refresh rate of the HMD as the call to ovr_SubmitFrame() throttles the application's CPU execution as needed.

App Render GPU Time

The total GPU time spent on rendering by the client application. This includes the work done by the application after returning from ovr_SubmitFrame(), using the mirror texture if applicable.

It can also includes GPU command-buffer "bubbles" if the application's

CPU thread doesn't push data to the GPU fast enough to keep it occupied.

Similarly, if the app pushes the GPU close to full-utilization, the work on next frame (N+1) might be preempted by the compositor's render work on the current frame (N). Because of how the application GPU timing query operates, this can lead to artificially inflated application GPU times as they will start to include the compositor GPU usage times.

App Render CPU Time The time difference from when the application continued execution on CPU after ovr_SubmitFrame() returned the subsequent call to ovr_SubmitFrame().

This will show "N/A" if the latency tester is not functioning as expected (e.g.,

HMD display is sleeping due to prolonged inactivity). This includes the IPC

76 | Optimizing Your Application | Oculus Rift

Metric

App Queue Ahead Time

Description call overhead to the compositor after ovr_SubmitFrame() is called by the client application.

To improve CPU and GPU parallelism and increase the amount of time that the GPU has to process a frame, the SDK automatically applies queue ahead up to 1 frame. This value displays the amount of queue ahead time being applied (in milliseconds). For more information about adaptive queue ahead,

see

Adaptive Queue Ahead

on page 30.

Compositor Render Timing

The Compositor Render Timing HUD displays render timing information for the Oculus Runtime Compositor.

The Oculus Compositor applies distortion and TimeWarp to the layered eye textures provided by the VR application.

The following screenshot shows the Compositor Render Timing HUD:

Figure 17: Render Timing

The following table describes each metric:

Table 7: Compositor Render Timing HUD

Metric Description

Compositor Missed V-Sync Count Increments each time the compositor fails to present a new rendered frame at V-Sync (Vertical Synchronization).

Compositor Frame-rate The rate of the final composition; this is independent of the client application rendering rate. Because the compositor is always locked to

V-Sync, this value will never exceed the native HMD refresh rate. But, if

Oculus Rift | Optimizing Your Application | 77

Metric

Compositor GPU Time

Comp Gpu-End to V-Sync

Description the compositor fails to finish new frames on time, it can drop below the native refresh rate.

The amount of time the GPU spends executing the compositor renderer.

This includes TimeWarp and distortion of all layers submitted by the application. The amount of active layers, their resolutions, and the requested sampling quality can all affect the GPU times.

The amount of time between when the GPU completes the compositor rendering to the point in time when V-Sync is hit and that buffer starts scanning out on the HMD.

Asynchronous SpaceWarp Stats

The Asynchronous SpaceWarp (ASW) HUD displays activity and tracking statistics for ASW, which runs as part of the Oculus Runtime Compositor. ASW automatically activates when an application fails to meet the required native frame rate for the connected HMD. Once active, ASW forces the application to run at half the normal frame rate while extrapolating every other frame. This gives the application more time to complete its work.

The following screenshot shows the ASW HUD:

Figure 18: ASW Stats

The following table describes each metric:

Table 8: ASW Stats HUD

Metric

ASW Status

Description

Shows the availability and current status of ASW. "Not Available" can be due to the OS and/or GPU type used on the PC. "Available - Not Active" will

78 | Optimizing Your Application | Oculus Rift

Metric Description mean the application is successfully maintaining the required native refresh rate, so ASW is not activated.

ASW Active-Toggle Count

ASW Presented-Frame Count Tracks the number of frames extrapolated by ASW that were displayed. When

ASW is active, since the app is forced to run at half-rate, expect this value to increase by 45 fps on a 90 Hz refresh rate HMD.

ASW Failed-Frame Count

Tracks the number of times ASW has been activated for the lifetime of the

HMD.

Tracks the number of extrapolated frames ASW needed to display, but failed to prepare in time. This can occur for different reasons, but might be caused by contention for OS resources or when the capabilities of the system are exceeded.

Version Information

The Version Information HUD displays information about the HMD and the version of the SDK used to create the app.

The following screenshot shows the Version Information HUD:

Figure 19: Version Info HUD

The following table describes each piece of information:

Name

OVR SDK Runtime Ver

Description

Version of the currently installed runtime. Every VR application that uses the OVR SDK since 0.5.0 uses this runtime.

Oculus Rift | Optimizing Your Application | 79

Name

OVR SDK Client DLL Ver

HMD Type

HMD Serial

HMD Firmware

Sensor Serial

Sensor Firmware

Description

The SDK version that the client app was compiled against.

The type of HMD.

The serial number of the HMD.

The version of the installed HMD firmware.

The serial number of the positional sensor.

The version of the installed positional sensor firmware.

Performance Indicator

Asynchornous TimeWarp (ATW) can mask latency and judder issues that would normally be apparent. To help you identify when your application or experience isn't performing and to test your game or experience before submitting it, Oculus provides performance indicators.

When enabled, a letter code appears in the upper right of the headset whenever the application is experiencing a performance issue. The following figure shows an example of a performance indicator with L and F displayed:

Figure 20: Performance Indicator

To enable the performance indicator, set the following registry key:

HKLM\SOFTWARE\Oculus VR, LLC\LibOVR

FrameDropHUDEnabled (DWORD)

Enable = 1

Disable = 0

80 | Optimizing Your Application | Oculus Rift

The performance indicator can return the following codes:

• L—a latency issue is occurring; more than one frame of queue ahead is being applied.

• F—the application is not maintaining frame rate.

• C—the compositor is not maintaining frame rate. Possible causes include:

• Programs, such as anti-virus software, are overloading the CPU.

• The CPU cannot handle the number of threads.

• The CPU or GPU does not meet the recommended specification.

• Certain patterns of GPU usage, such as heavy usage of shaders and tessellation, are affecting frame rate.

• There is an issue with the GPU driver.

• There is an unknown hardware issue.

• U—an unknown error occurred.

Each warning lasts one frame. So, if L stays visible, the application is having continuous latency issues.

Compositor Mirror

The Compositor Mirror tool displays the content that appears within the Rift headset on your computer monitor. It has several display options that are useful for development, troubleshooting, and presentations.

Anything that appears in the Rift headset can be shown in the Compositor Mirror tool, including Oculus Home,

Guardian System boundaries, in-game notifications, and transition fades. It is compatible with all games and experiences regardless whether they are developed using the native PC SDK or a game engine.

Finding the Tool

The Compositor Mirror tool is located in C:\Program Files\Oculus\Support\oculus-diagnostics\OculusMirror.exe

Image Display Options

The Compositor Mirror tool provides several display options.

The default mode is recommended for live presentations and demos. If you double-click OculusMirror from

Windows Explorer or run from the command line without specifying any options, the tool displays a 1366x768

(pixel) window showing a rectilinear view of the right eye image, along with the Guardian System boundary layer and the Oculus notification layer.

The other display modes are as follows:

OculusMirror.exe

--

LeftEyeOnly

Display the left eye image in rectilinear view.

Oculus Rift | Optimizing Your Application | 81

82 | Optimizing Your Application | Oculus Rift

this example, the user's hands have protruded through the

Guardian

System boundary in two locations, as indicated by the circular holes in the boundary.

OculusMirror.exe

--

RectilinearBothEyes

-both eye images

Display both in rectilinear view.

rectilinear view along with the

Guardian

System boundary.

In

Oculus Rift | Optimizing Your Application | 83

84 | Optimizing Your Application | Oculus Rift

OculusMirror.exe

--

PostDistortion other options that appear within the headset.

For example, the following output is produced with

--

Display both eye images corrected for lens distortion and chromatic aberration.

This will also display any

PostDistortion, but also shows the

Guardian system boundary, since it is visible within the headset.

No additional options are allowed

Oculus Rift | Optimizing Your Application | 85

86 | Optimizing Your Application | Oculus Rift

in conjunction with

--

PostDistortion.

For example, you cannot explicitly exclude notifications or the

Guardian system boundary, if they are visible within the headset.

Oculus Rift | Optimizing Your Application | 87

88 | Optimizing Your Application | Oculus Rift

Changing the Window Size

You can change the size of the window by dragging the window borders on the desktop. You can also use the

--Size width height command to set the size of the window (in pixels) from the command line. If you exceed the resolution of your main display, the window size is reduced to fit. For example:

OculusMirror.exe --Size 2160 2160 --RightEyeOnly

Displaying Notifications

You can display the Oculus notifications layer by using

--IncludeNotifications. For example:

OculusMirror.exe --RectilinearBothEyes --IncludeNotifications

Flash on Frame Drops

It is possible that the CompositorMirror tool may drop frames that are displayed within the Rift headset. If you wish to clearly see when this happens, use the

--FlashFrameDrops command. This will cause the display in the CompositorMirror to flash whenever a frame is dropped. For example:

OculusMirror.exe --FlashFrameDrops --RectilinearBothEyes