Meta Developers

You need to set up your Unity development environment and configure your Quest headset.
Verify your headset is running the latest version. In the headset, go to Settings > System > Software Update and update it if necessary.
Complete the First Unity VR App Tutorial to make sure your basic Unity configuration is correct.
Perform the basic configuration settings to set up the Android platform and the XR Plugin management package. This makes sure that your Unity setup is ready for Quest development.

Configure Unity project

For a passthrough Unity project, you need to replace your Main Camera with a passthrough-enabled OVRCameraRig. With the camera in place, you just need to add one or more passthrough layers to use passthrough.

Create a new scene or open an existing one from your project.
If you have not already deleted the Main Camera, select it in the Hierarchy tab and delete it.
If you have not already added the OVRCamera Rig, on the Project tab, search for OVRCameraRig, and then drag the prefab into the scene.
On the Hierarchy tab, select OVRCameraRig.
On the Inspector tab, under OVRManager, do the following:
a. Under Quest Features > General tab, in the Passthrough Support list, select either Required or Supported to enable the build-time components for using passthrough.
b. Under Insight Passthrough, select Enable Passthrough to initialize passthrough during app startup. (To initialize passthrough at a later time through a C# script, you can leave the checkbox unchecked and set OVRManager.isInsightPassthroughEnabled in your script.)
c. Click Add Component, and then in Scripts, select OVR Passthrough Layer.
d. In the OVR Passthrough Layer (Script) section, select the Projection Surface dropdown list to configure whether the passthrough rendering uses an automatic environment depth reconstruction or a user-defined surface.

What you do next depends on the type of passthrough you want. To draw passthrough on top of your virtual content, set Placement to Overlay. To draw passthrough underneath your virtual content, set Placement to Underlay. When you have multiple layers, use the Composition Depth setting to define the ordering between the layers. Layers with smaller Composition Depth values have a higher priority and appear in front of layers with larger Composition Depth values.

To experiment more with passthrough, first do either the basic Passthrough Basic Tutorial or the Basic Passthrough Tutorial with Building Blocks. Then you can check out the Passthrough Samples in this documentation. For more advanced showcase projects, see the our GitHub repo. The Unity-Discover and Unity-TheWorldBeyord projects both make use of passthrough.

Customize passthrough

Customize passthrough through styling, color mapping, composite layering, or by implementing surface-projected passthrough.

Enable based on system recommendation

In your app, you may want to show either a VR or passthrough background based on user choice. Our system already provides users with this choice in the home environment, and your app can leverage the user’s home environment preference. More generally, our system provides a recommendation for apps to default to MR or VR based on user preferences. This recommendation is available using OVRManager.IsPassthroughRecommended(). Example usage:

// Add this to any MonoBehavior
void Start()
{
   if (OVRManager.IsPassthroughRecommended())
   {
      passthroughLayer.enabled = true;

      // Set camera background to transparent
      OVRCameraRig ovrCameraRig = GameObject.Find("OVRCameraRig").GetComponent<OVRCameraRig>();
      var centerCamera = ovrCameraRig.centerEyeAnchor.GetComponent<Camera>();
      centerCamera.clearFlags = CameraClearFlags.SolidColor;
      centerCamera.backgroundColor = Color.clear;

      // Ensure your VR background elements are disabled
   }
   else
   {
      passthroughLayer.enabled = false;

      // Ensure your VR background elements are enabled
   }
}

Wait until passthrough is ready

Enabling passthrough is asynchronous. System resources (like cameras) can take a few hundred milliseconds to activate, during which time passthrough is not yet rendered by the system. This can lead to black flickers if your app expects passthrough to be visible immediately upon enabling, and the passthrough system wasn’t previously active. You can avoid that by using the passthroughLayerResumed event, which is emitted once the layer is fully initialized, and passthrough is visible.

You don’t need to worry about this at app startup, though. If the transition leading into your app was already showing passthrough (see Loading Screens), you can rely on passthrough being rendered immediately upon enabling. Just make sure that your OVRPassthroughLayer is enabled right from the start. In other words, you only need to consider this event if you enable passthrough while the app is already running.

Example usage:

[SerializeField] private OVRPassthroughLayer oVRPassthroughLayer;

private void Awake()
{
  oVRPassthroughLayer.passthroughLayerResumed.AddListener(OnPassthroughLayerResumed);
  // 1) We enable the passthrough layer to kick off its initialization process
  oVRPassthroughLayer.enabled = true;
}

private void OnDestroy()
{
  oVRPassthroughLayer.passthroughLayerResumed.RemoveListener(OnPassthroughLayerResumed);
}

// 2) OnPassthroughLayerResumed is called once the layer is fully initialized and passthrough is visible
private void OnPassthroughLayerResumed(OVRPassthroughLayer passthroughLayer)
{
  // 3) Do something here after the passthrough layer has resumed
}

Rapid passthrough app development

You can speed up app development significantly by avoiding the need to rebuild and deploy for every iteration. Consider the following options:

Passthrough over Link allows you to run your app directly in the Unity editor with a headset connected over Link.
Meta XR Simulator allows you to run your app in a simulator without the need for a headset.

Did you find this page helpful?