Develop

Occlusion sample overview

Updated: May 11, 2026

Overview

This Blueprint-only sample demonstrates environment depth occlusion using the Depth API. It provides three occlusion modes (disabled, hard, and soft), hands removal toggling, and a depth visualization material. Soft occlusion and the Environment Depth material node require the Oculus fork of Unreal Engine.
View the sample source code on GitHub⁠.

What you will learn

  • Enable and disable environment depth occlusion at runtime using StartEnvironmentDepth() and StopEnvironmentDepth()
  • Cycle between three occlusion modes (disabled, hard, soft) using SetXROcclusionsMode()
  • Toggle hand removal with SetEnvironmentDepthHandRemoval()
  • Use the Environment Depth material node to visualize raw depth data (fork only)
  • Implement depth occlusion in a pure Blueprint project without C++

Requirements

  • Meta Quest 2, Quest 3, or Quest 3S
  • Unreal Engine 5.x with the OculusXR plugin
  • Oculus fork of Unreal Engine for soft occlusion and the Environment Depth material node (compile-time guard: WITH_OCULUS_BRANCH)
For build setup and configuration, see the sample README⁠.

Get started

Clone or download the sample from the GitHub repository. Open the project in Unreal Engine 5 with the OculusXR plugin enabled. For soft occlusion support, use the Oculus fork of Unreal Engine. Build and deploy to your Meta Quest device. Use the A/X buttons to cycle between occlusion modes at runtime.

Explore the sample

File / SceneWhat it demonstratesKey concepts
Main level (map)
Occlusion mode cycling with virtual objects
StartEnvironmentDepth(), StopEnvironmentDepth() lifecycle
Occlusion mode widget
UI for switching between disabled, hard, and soft
SetXROcclusionsMode() cycling
Hands removal toggle
Pinch gesture toggles hand removal
SetEnvironmentDepthHandRemoval()
M_EnvironmentDepth (material)
Warm-to-cool gradient depth visualization
Environment Depth material node (fork only)
Passthrough setup
Background passthrough environment
Mixed reality configuration

Runtime behavior

The sample starts with environment depth disabled. Pressing A/X cycles through three occlusion modes: disabled, hard occlusion, and soft occlusion. In hard occlusion mode, real-world surfaces occlude virtual objects with sharp edges. In soft occlusion mode, occlusion edges blend smoothly with the environment. A pinch gesture toggles hands removal so the user’s hands appear in front of virtual content.
The depth visualization material renders a warm-to-cool color gradient representing raw depth values from the Depth API. This material requires the Oculus fork of Unreal Engine, guarded by the WITH_OCULUS_BRANCH compile-time define.
Note: Hard occlusions are deprecated. Soft occlusions are the recommended mode for new projects.

Key concepts

Depth lifecycle management

The sample manages the Depth API lifecycle explicitly:
// Start depth sensing when entering the occlusion scene
StartEnvironmentDepth()

// Stop depth sensing when exiting or disabling occlusion
StopEnvironmentDepth()

Occlusion mode cycling

Three modes are available, cycled with the SetXROcclusionsMode() function:
  • Disabled: No occlusion, virtual objects render on top of everything
  • Hard: Sharp-edge occlusion where real surfaces clip virtual objects
  • Soft: Gradient-edge occlusion for more natural blending (requires the Oculus fork)

Fork-only features

Soft occlusion and the Environment Depth material node require the Oculus fork of Unreal Engine. The sample uses the WITH_OCULUS_BRANCH compile-time guard to conditionally enable these features:
#if WITH_OCULUS_BRANCH
// Soft occlusion and Environment Depth material node available
#endif

Extend the sample

  • Add additional occlusion visualization modes using custom post-process materials.
  • Combine depth occlusion with Scene API meshes for hybrid occlusion approaches.
  • Implement per-object occlusion control to selectively exclude objects from depth testing.
Nav Logo
Virtual reality / Meta Horizon
Virtual reality / Meta Horizon
Virtual reality / Meta Horizon
English (US)
© 2026 Meta