VR Compositor Layers

OVROverlay is a script in OVR/Scripts that allows you to render Game Objects as VR Compositor Layers instead of drawing them to the eye buffer.

OVROverlay

Game Objects rendered as VR compositor layers render at the frame rate of the compositor instead of rendering at the application frame rate. They are less prone to judder, and they are raytraced through the lenses, improving the clarity of textures displayed on them. This is useful for displaying easily-readable text.

Quadrilateral, cubemap, and cyllinder compositor layers are currently supported by Rift and mobile. Offset cubemap compositor layers are currently available in mobile only.

Overlay sample: A sample illustrating the use of quad and cylinder VR Compositor Layers for a UI is included with the rendering samples of our Unity Sample Framework. See Unity Sample Framework for more information.

All layer types support both stereoscopic and monoscopic rendering, though stereoscopic rendering only makes sense for cubemaps in most cases. Stereoscopically-rendered overlays require two textures, specified by setting Size to 2 in the Textures field of OVROverlay in the Inspector.

Gaze cursors and UIs are good candidates for rendering as quadrilateral compositor layers. Cylinders may be useful for smooth-curve UI interfaces. Cubemaps may be used for startup scenes or skyboxes.

We recommend using a cubemap compositor layer for your loading scene, so it will always display at a steady minimum frame rate, even if the application performs no updates whatsoever.

Applications may add three compositor layers to a scene. You may use no more than one cylinder and one cubemap compositor layer per scene.

Note that if a compositor layer fails to render (e.g., you attempt to render more than three compositor layers), only quads will currently fall back and be rendered as scene geometry. Cubemaps and cylinders will not display at all, but similar results can be achieved with scene geometry such as Unity’s Skybox component or Cylinder MeshFilter.

You may use OVRRTOverlayConnector to render textures to a compositor layer. See OVRRTOverlayConnector below for more information.

Ordering and Transparency

The depth ordering of compositor layers is controlled by two factors:

  1. Whether objects are rendered in front of or behind the scene geometry rendered to the eye buffer, and
  2. The sequence in which the compositor layers are enabled in the scene.

By default, VR compositor layers are displayed as overlays in front of the eye buffer. To place them behind the eye buffer, set Current Overlay Type to Underlay in the Inspector. Note that underlay compositor layers are more bandwidth-intensive, as the compositor must “punch a hole” in the eye buffer with an alpha mask so that underlays are visible. Texture bandwidth is often a VR bottleneck, so use them with caution and be sure to assess their impact on your application.

Underlays depend on the alpha channel of the render target. If a scene object that should occlude an underlay is opaque, set its alpha to 1. If the occluder is transparent, you must use the OVRUnderlayTransparentOccluder shader provided in the Utilities in Assets/OVR/Shaders. Overlays do not require any special handling for transparency.

Compositor layers are depth ordered by the sequence in which they are enabled in the scene, but the order is reversed for overlays and underlays. Underlays should be enabled in the scene in the sequence in which you want them to appear, enabling the underlays in front first and the layers in the back last. Overlays should be enabled in the opposite order.

Basic usage

  1. Attach OVROverlay.cs to a Game Object.
  2. Specify the Current Overlay Shape:
    • Quad (Rift and Mobile)
    • Cubemap (Rift and Mobile)
    • Cylinder (Mobile only)
  3. Specify the OVROverlay Texture. If you leave it as None (default), it will use the Renderer material’s main texture, if available. See OVRRTOverlayConnector below for more information on rendering textures to an OVROverlay Game Object.
  4. Disable all compositor layers (both overlays and underlays),
  5. Enable them sequentially to set the order in which you wish them to appear, enabling overlays in front last and underlays in front first.

Example

In this example, most of the scene geometry is rendered to the eye buffer. The application adds a gaze cursor as a quadrilateral monoscopic overlay and a skybox as a monoscopic cubemap underlay behind the scene.

Note the dotted sections of the eye buffer, indicating where OVROverlay has “punched a hole” to make the skybox visible behind scene geometry.

In this scene, the quad would be set to Current Overlay Type: Overlay and the cubemap would be set to Current Overlay Type: Underlay. Both would be disabled, then the quad overlay enabled, then the skybox enabled.

Note that if the cubemap in our scene were transparent, we would need to use the OVRUnderlayTransparentOccluder, which is required for any underlay with alpha less than 1. If it were stereoscopic, we would need to specify two textures and set Size to 2.

Cylinder and Offset Cubemap Overlays (Mobile Only)

The center of a cylinder overlay Game Objects is used as the cylinder’s center. The dimensions of the cylinder are encoded in transform.scale as follows:

  • [scale.z] cylinder radius
  • [scale.y] cylinder height
  • [scale.x] length of the cylinder arc

To use a cylinder overlay, your camera must be placed inside the inscribed sphere of the cylinder. The overlay will fade out automatically when the camera approaches to the inscribed sphere's surface.

Only half of the cylinder may be displayed, so the arc angle must be smaller than 180 degrees.

Offset cubemap compositor layers are useful for increasing resolution for areas of interest/visible areas by offsetting the cubemap sampling coordinate.

They are similar to the same as standard cubemap compositor layers. Attach the OVROverlay script to an Empty Game Object, and specify the texture coordinate offset in the Position Transform. For more information, see OVROverlay in our Unity Scripting Reference.

OVRRTOverlayConnector

OVRRTOverlayConnector is a helper class in OVR/Scripts/Util used to link a Render Texture to an OVROverlay Game Object. Attach this script to your camera object, and specify your overlay owner object in Ovr Overlay Obj.

The overlay camera must use Render Texture, and must be rendered before the Main Camera (e.g., using camera depth), so the Render Texture will be available before being used.

OVRRTOverlayConnector triple-buffers the render results before sending them to the overlay, which is a requirement for time warping a render target. It also clears the render Texture's border to alpha = 0 to avoid artifacts on mobile.

For more information, see "OVRRTOverlayConnector" in our Unity Scripting Reference.