Occlusions

Occlusion is the effect of real-world objects blocking, or appearing in front of, virtual objects. For example, a user’s hand reaching toward a virtual light switch should appear in front of the switch, not behind it. Without occlusion, virtual objects always render on top of the real world, breaking the illusion of mixed reality.

The Meta XR Plugin provides environment depth occlusion as the primary solution for this problem. The Depth API captures real-time depth information from the physical environment and uses it to determine, on a per-pixel basis, whether a real-world surface is closer to the viewer than a virtual object. Where a real surface is closer, the system hides the virtual object behind the real-world passthrough.

For a complete implementation walkthrough, see Get started with occlusions.

To enable environment depth occlusion, start depth capture at runtime using the StartEnvironmentDepth Blueprint node, then set the occlusion mode using the SetXROcclusionsMode Blueprint node with the value SoftOcclusions. Soft occlusions produce smooth, natural-looking edges where real and virtual content meet.

Environment depth occlusion supports both static surfaces (walls, furniture) and dynamic objects (hands, people moving through the scene), providing per-pixel accuracy.

For an overview of hard versus soft occlusion modes, see Occlusions overview.

The Scene Model provides geometry of the physical environment, including walls, floors, ceiling, and furniture. You can use this geometry as an occluder for static real-world surfaces. This approach is useful when you need occlusion from known room features without enabling the full Depth API.

The Scene Model supports static occlusion only. For dynamic occlusion (moving objects, hands), use environment depth occlusion instead.

If you have access to the geometry of specific real-world objects, you can use it to create occlusion manually. For example, you can render tracked hands or other known geometry with a material that writes only to the depth buffer, before other objects. Set a custom depth value on the material so that subsequent virtual objects fail the depth test in the area of the occluder and do not render there. This creates the illusion of the virtual content being behind the real-world object.

This manual approach works across the entire mesh, producing fully opaque occlusion without smooth edges. For per-pixel, soft-edged occlusion, use environment depth occlusion instead.