Develop

Passthrough best practices

Updated: Apr 15, 2026

This topic describes several best practices for integrating the Passthrough API.

Enable and disable passthrough

The legacy UOculusXRPassthroughLayerComponent workflow for toggling passthrough is deprecated as of Unreal Engine 5.6. Use the persistent passthrough API on UOculusXRPassthroughSubsystem instead:

Call InitializePersistentPassthrough() to create passthrough.

Call SetVisible(false) on the returned UOculusXRPersistentPassthroughInstance to hide passthrough temporarily without incurring a full teardown.

Call DestroyPersistentPassthrough() on the subsystem to fully clean up resources when passthrough is not needed for an extended period, such as when changing scenes.

Use SetVisible(false) for brief pauses and DestroyPersistentPassthrough() when passthrough will remain inactive for a significant duration. Destroying and recreating passthrough has a higher cost than toggling visibility.

Use system recommendation to choose between MR and VR

If your app supports both MR and pure VR, query the system to decide which one to default to. See Enable Based on System Recommendation for details.

Keep passthrough cameras in sync with the display

To maximize the smoothness of passthrough, use a 72Hz refresh rate for your application. In flicker-free lighting conditions (environments without pulsing artificial light sources such as fluorescent or LED lights at certain frequencies), passthrough synchronizes the cameras with the display, ensuring stable latency and eliminating judder. Camera-display synchronization is only available on Meta Quest 3 and Meta Quest 3S devices.

To set the refresh rate programmatically, call UOculusXRFunctionLibrary::SetDisplayFrequency(). See Change display refresh rate for details.

Wait until passthrough is ready

The OnLayerResumed event fires when a passthrough layer has been rendered and presented on the HMD for the first time after initialization. Bind to this event before showing passthrough-dependent content to avoid black frames. The event is available through:

The OnLayerResumed delegate on UOculusXRPersistentPassthroughInstance (per-instance, BlueprintAssignable)

The OnAnyLayerResumed delegate on UOculusXRPassthroughSubsystem (global, passes LayerID)

A LayerResumed callback parameter on InitializePersistentPassthrough()

See Wait until Passthrough is ready in the getting started guide for a detailed walkthrough.

Use underlay mode

The overlay passthrough mode (PassthroughLayerOrder_Overlay) is deprecated. Use underlay mode (PassthroughLayerOrder_Underlay), which is the default. Underlay renders passthrough beneath virtual content. See Configure Unreal Project in the getting started guide for configuration details.

Configure passthrough for Meta Quest Link

Running passthrough over Meta Quest Link requires two additional project settings:

Enable Alpha Channel in Post Processing to pass alpha through the tonemapper.

Use the Android Vulkan Mobile Preview Platform for correct rendering behavior.

See Passthrough over Link for the full setup walkthrough.

Set anti-aliasing to MSAA

Passthrough requires MSAA as the anti-aliasing method. Set Anti-Aliasing Method to MSAA with a sample count of 4x in your project’s rendering settings. Post-processing anti-aliasing methods are not compatible with passthrough. All Meta passthrough sample projects use this configuration.

Troubleshooting

For common issues and solutions related to passthrough, including rendering artifacts and Meta Quest Link problems, see Passthrough troubleshooting.

Design guidelines

Design guidelines are Meta’s human interface standards and design frameworks that help you create safe, user-oriented, and retainable immersive and passthrough user experiences.