Oculus Dash, Overlays and Input Focus

Starting with the v19 SDK release, if an app does not support focus awareness, Oculus will flag it with a warning at the time of submission to Oculus Store. We highly recommend that you enable the focus awareness feature early in your development process to test how your app handles the loss of input and let the system UI appear as an overlay.

This guide describes how to add focus awareness and overlay support to Unreal apps for Oculus Quest and Oculus Dash support to Unreal applications for Oculus Rift.

Overlays are a feature that enables Oculus system interface, such as Oculus Dash or the Universal Menu, to appear over an application without requiring the app to close. This enables users to access system features such as social menus, settings and more, which helps keep users engaged in the experience. For overlays to display correctly, your app must be focus aware.

Apps should query for status changes such as losing input focus or the presence of system overlays. Apps can then take appropriate action when an overlay appears. For example, when the universal menu appears on top of an app, an app can continue to run but pauses gameplay because it has lost input focus.

When users pause an application, one of two things will happen:

  • If the application is focus aware and has overlay support, the application will pause and the system UI will be drawn over the paused application.
  • If the application is not focus aware and does not have overlay support, the application will be paused by the runtime and the user will be presented with the system UI in an empty room.

Oculus Dash

Oculus Dash is a central hub containing Oculus system UI, and it runs on Rift devices as an overlay inside your current VR experience. This enables users to quickly switch from one application to the next, open their library and connect with friends without any extra steps. For general information about Dash, see the Dash announcement: Introducing Rift Core 2.0—Our Biggest Software Update Yet! Also see the Introducing Oculus Dash video to get a sense of how Dash works.

Input Focus Support

The Oculus Unreal integration provides the following support:

  • The ability to configure whether the application is input-focus aware
  • Input focus handling
  • Ability to configure the depth buffer support (Rift only)

Declare an Application is Input-Focus Aware

You can declare that your application is input-focus aware by doing the following:

Rift Apps - Dash Support

  • For Rift apps, enable Dash support in the Unreal Engine editor by navigating to Edit / Project Settings / Plugins / OculusVR / PC , and check Supports Dash.

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 losing input focus.

Quest Apps - Overlays/Focus Support

For Quest apps, make sure you have Oculus OVRPlugin v13 or later. For more information, see Version Compatibility Reference

  • Enable overlays in the Unreal Engine Editor by navigating to Edit > Project Settings > Plugins > Oculus VR > Mobile, and check Focus Aware. Once you make this selection the following entry is added to the app’s Android manifest under the <activity> tag, when you package the app for Android:

    <meta-data android:name="com.oculus.vr.focusaware" android:value="true"/>

    This entry is required for a focus-aware app to function properly.

Input Focus Handling

When an overlay appears (such as when the user presses the Oculus button), the running application loses input focus and the HasInputFocus flag will return false.

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.

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;
   return false;

Ensure that your app takes the appropriate action when input focus is lost. Examples may include:

  • Pausing gameplay. When you do this, it is important to remember that the system will display its own UI on top of any UI your app displays, and your app cannot accept input because it doesn’t have input focus.
  • Hide the user’s input affordance such as arms or hands
  • For online/multiplayer games, indicate the user isn’t focused on the app.

An application regains input focus when the overlay is dismissed. This means HasInputFocus flag will return true. In this case, you can resume gameplay or show the user’s input affordance.

Following is an illustration of a typical implementation of hiding tracked controllers when input focus is lost from the VRCharacter Blueprint in the Touch sample.

Depth Buffer Support

By default, Dash-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.

  • Uncheck Composites Depth under Edit / Project Settings / Plugins / OculusVR / PC.

Test Your App

To test your app’s behavior with Oculus Dash, while your app is running, press the Oculus button to display Oculus Dash.

For the store requirement related to Oculus Dash, see Rift VRC Input 4.

Enable the Universal Menu for Testing

You should test overlays and the Universal Menu to help ensure your app functions as expected when focus awareness is a default system behavior.

Use the following steps to enable the Universal Menu on your Quest device and test overlays.

  • Put on your Quest and from Oculus Home, go to Settings > Experiments, and then enable New Universal Menu.
  • Then, while your app is running, press the Oculus button to display the Universal Menu as an overlay.

If you don’t see the Universal Menu as an overlay, make sure you enabled Focus Aware for your app.

For the store requirement and testing steps related to focus-awareness, see Quest VRC Input 4.

Enable Keyboard Overlays

For information on how to enable keyboard overlays for text input, see Enable Keyboard Overlays for Text Input.