The babylon-occlusion principle is:
Use the exact depth texture produced by Babylon Lite’s normal scene render, then perform asynchronous GPU depth queries for annotation anchor points. Do not render a second depth pass and do not perform synchronous GPU readback.
The flow is:
- Annotator projects each label or marker anchor into screen space.
- The occlusion provider receives the projected position and reverse-Z depth.
- A GPU compute/query pass samples Babylon Lite’s current live scene-depth texture at that screen position.
- The sampled depth is compared with the anchor depth using
occlusionBias.
- Results return asynchronously and are associated with a frame/request generation.
- Annotator applies only results that still correspond to the current camera, viewport, and annotation state.
- Until a valid result arrives, the previous stable result is retained to prevent flicker.
The essential comparison for reverse-Z is conceptually:
occluded = sampledSceneDepth > anchorDepth + occlusionBias;
In reverse-Z, larger depth values are nearer to the camera. Therefore, if the depth buffer contains a sufficiently larger value than the annotation anchor’s depth, another surface is in front of the anchor.
occlusionBias is measured in normalized reverse-Z depth, not world units. Its purpose is to reject self-occlusion and small depth-buffer noise near the annotated surface.
Presentation is separate from detection:
visibility: {
occlusion: "none" | "hide" | "fade",
occludedOpacity: 0.5,
occlusionBias: 0.0001
}
"hide" removes an occluded annotation from rendering and interaction."fade" keeps it rendered with an opacity multiplier."none" disables occlusion presentation.- The deprecated
hideWhenOccluded option maps to the newer modes.
A crucial implementation detail is that the provider uses the private live depth texture belonging to Babylon Lite’s default scene render task—the same depth buffer used to produce the visible frame. This avoids discrepancies caused by a duplicate depth render with different culling, animation state, render ordering, alpha behavior, or camera matrices.
Why asynchronous queries are important:
- WebGPU readback cannot be treated as immediate.
- Blocking for the current frame would stall the CPU/GPU pipeline.
- Query results naturally arrive one or more frames later.
- Generation checks prevent stale results from being applied after camera movement, viewport changes, disposal, or anchor updates.
- Hysteresis/stable-result reuse prevents transient query latency from causing visible flashing.
The provider owns the query resources, but not the scene, camera, depth texture, or annotation layer. Disposal cancels future application of pending results and releases its own GPU buffers.
The practical rule is:
Occlusion is a delayed visibility signal derived from the scene’s authoritative depth buffer, not a synchronous property calculated independently by each annotation.
That separation keeps rendering, depth ownership, asynchronous GPU work, and annotation presentation cleanly decoupled.
Later I’ll create a feature request for exposing the default scene render’s current depth texture through a supported public API. Currently babylon-occlusion reaches into Lite’s private render-task structure to obtain that texture.
More info here - lite-instancer/packages/annotator at main · eldinor/lite-instancer · GitHub
The latest update should improve depth occlusion - [LITE] Annotator - a Lightweight Annotation System for Babylon Lite - #7 by labris
