The Lost Frame Capture tool collects information about dropped frames while your VR application is running. You can then replay the dropped frames while viewing statistical data, in order to help track down performance problems within your application.

When you submit a VR application to the Rift Store, it is examined by Meta engineers to ensure that it adheres to the Rift Virtual Reality Checklist (VRC), which specifies a number of requirements that your application must satisfy, including performance targets. For information about the VRC, see: /distribute/publish-rift-app-submission/. If your application fails due to performance issues, it is generally because it failed to maintain the required frame rate of 90 frames per second at some point during its execution. (Large clusters of dropped frames are not allowed outside of scene transitions. Applications are allowed to drop frames while loading code into memory, or transitioning from scene to scene.)

If your application is rejected for performance reasons, you will need to address those issues, and re-submit the application. However, in the past it has been difficult for developers to pinpoint the exact problem areas within their application. Oculus will soon begin providing an Oculus Debug Archive (ODA file) to developers, whenever their application is rejected because of performance issues. You can use the Lost Frame Capture tool to load the ODA file, and then analyze the performance of your application. With this tool, you can see exactly where the performance problems occurred, and even view the lost frames that are causing performance issues.

You can also use the Lost Frame Capture tool to analyze your applications before you submit them to Meta. This helps you to discover and address any performance issues prior to submission.

The rest of this document describes how to use the Lost Frame Capture tool.

You can also analyze the Lost Frame Capture output that you captured during the currently running session, without necessarily saving that output to an ODA file.

Before you submit your application, it is a good idea to run it, and collect the Lost Frame Capture output. While running your application, you should go through all the scenarios that end users may encounter. Then, analyze the resulting output to determine if there were any large clusters of dropped frames outside of scene transitions. If you discover any performance problems, fix them before submitting your application.

To load and analyze an ODA file, follow these steps:

This window lists the frames that were lost during the time that the ODA content was being captured. The frame indexes are listed in the first column. You will notice that the lost frames are sometimes grouped into folder-like structures. This is intended to help you recognize when multiple frames are lost in close proximity to each other. Whenever a sequence of frames is lost, where there is never a gap of more than one second between any two lost frames, those lost frames are grouped together into a folder structure--called a lost frame cluster.

You can select a frame at the top level of the list, or a frame from within a lost frame cluster. The rendered left and right eye views for the frame are displayed on the right. A graph appears below, which indicates the frame rate for a set of lost frames, where 90 frames per second is the top-most value in the graph. When the graph dips down, it indicates that frames are being generated at a lower frame rate (which, if it is sustained, is not acceptable since it results in a poor user experience).

In the example above, the currently selected frame was generated at a rate of 56.3 frames per second, as indicated by the horizontal line. You can step through the lost frames using the arrow keys, and see how the line moves over time. The point at which the horizontal line intersects the vertical dashed line in the grid, and which also intersects the graph, indicates where the currently selected frame is in the timeline.

This graph view helps you to visualize how the frame rate for the currently selected frame compares with other nearby frames (if you are stepping through frames within a cluster). For example, you can compare the current level of the horizontal line to the overall graph. This can make it much easier to spot where a problem is beginning, and where it is at its worst. In many cases, you should be able to get an intuitive grasp of what the problem is by simply looking at the content of the frames. For example, an object may come into view when the frame rate drops. Perhaps the shader that is used by that object is too complex, or some other aspect of the rendering process for that object is using up too much of the CPU or GPU resources.

The columns displayed by the Lost Frame Capture tool are listed in the following table. You can click on any column header in order to sort the rows by that column. If you sort by a column other than Lost Frame Index, the clusters are sorted as a group at the top of the list, and the non-clustered individual frames are sorted as a group at the bottom of the list.

The columns include:

To capture any lost frames produced by your application, and then save that content as an ODA file:

To view a set of overall statistics for the currently open ODA file, or the current recording session, click the Summary button. The Performance Summary popup window is displayed: