Oculus Focus States and Dash Support

Important

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.

This guide describes how to handle the various focus states of a VR app.

The Oculus runtime provides information for the following:

  • Input focus handling
  • Depth buffer support
  • Declaring to the Oculus runtime that the application is input focus aware.

Input Focus Handling

When the Dash UI is active or use pauses the app, the running application loses input focus and the HasInputFocus flag will return false. The runtime renders tracked controllers in the scene to interact with the menu.

Your application should pause, mute, and hide any tracked controllers in the scene so there will not be a duplicate pair of hands in a UI. Depending on the application, additional action may also be warranted when input focus is lost (e.g., during a multiplayer combat game, you may wish to indicate that the player is unavailable and take any other appropriate action).

Note that HasInputFocus returns false under any other conditions in which the application loses input focus, such as when the HMD is removed from the head.

Input focus status may be queried using a Blueprint or in code. This query should be performed once during every frame render cycle.

Use OculusLibrary::HasInputFocus to query input status using Blueprints. For an illustration of a typical implementation of hiding tracked controllers when input focus is lost, see the VRCharacter Blueprint in our Touch sample (illustrated below).

To query input focus status in C++, use code similar to the following:

ovrpBool HasFocus = ovrpBool_False;
if (OVRP_SUCCESS(ovrp_GetAppHasInputFocus(&HasFocus)))
   {
   return HasFocus == ovrpBool_True;
   }
else
   {
   return false;
   }

Depth Buffer Support

By default, compatible Unreal versions automatically submit depth information for scene geometry to help avoid depth conflicts between the Dash UI rendered in the scene and objects in the scene. It also enables compositor layer depth testing.

You can disable depth buffer support. We do not recommend doing so, unless you have a good reason. There are two ways you can do this.

  • If you have the latest version of the Oculus Unreal integration (that you downloaded and compiled from the Oculus GitHub repo), you can simply uncheck Composites Depth under Edit / Project Settings / Plugins / OculusVR / PC.
  • If you are using the Epic release of Unreal 4.21 or earlier, you can do this by adding bCompositeDepth=False under Oculus.Settings in Engine.ini.

Declaring an Application is Input Focus Aware

If you have the latest version of the Oculus Unreal integration (that you downloaded and compiled from the Oculus GitHub repo), you can declare that your application is input focus aware by simply checking Supports Dash under Edit / Project Settings / Plugins / OculusVR / PC (as shown in the screenshot, above).

If you are using the Epic release of Unreal 4.21 or earlier, you can declare that your application is input focus aware by adding bSupportsDash=True under Oculus.Settings in Engine.ini (default is false).

When your application supports Dash, the Dash menu will be drawn over your paused application instead of in an empty room.

Alternatively, you can launch the application with the parameter -oculus-focus-aware. This will indicate that your application is Dash aware during that invocation of the application.

Do not specify that your application supports Dash unless it properly handles input focus loss.