feat(core): Add MinMaxSoftOcclusion mode with two-pass depth preprocessing

zjm-meta · meta-codesync[bot] · commit a3ccb48cb41e · 2026-03-02T12:19:08.000-08:00
Summary:
Add a new MinMaxSoftOcclusion occlusion mode to DepthOccludable that produces edge-aware smooth occlusion boundaries at depth discontinuities, ported from the Meta SDK's OcclusionVisualizationRenderer two-pass pipeline.

The implementation adds:
- MinMaxSoftOcclusion enum value in OcclusionShadersMode
- DepthPreprocessingPass: a fullscreen pass per eye at depth texture resolution (~256×192) that samples a 4×4 neighborhood using bimodal clustering to compute min/max/avg depth, output as RGBA = (minAvg, maxAvg, avg-minAvg, maxAvg-minAvg) in meters
- DepthPreprocessingShader: GPU-aware preprocessing shader supporting both CPU and GPU inverse-depth formats, with vectorized clustering using dot/mask operations for the second pass
- MinMax occlusion branch in the material shader that reads per-view preprocessed textures, computes per-cluster fade alphas with 4% metric distance range, and interpolates with smoothstep(0.2, 0.8 ) at depth edges

Key fixes applied during development:
- VIEW_ID uint comparison fix for multiview compatibility
- XR-safe preprocessing rendering (temporarily disables renderer.xr.enabled)
- Correct GPU depth texture dimensions instead of drawing buffer fallback
- Cached minMaxEntityCount to avoid per-frame entity scanning

Reviewed By: felixtrz

Differential Revision: D94752919

fbshipit-source-id: ccda8492e36f19ef31c9ed4d94c1a9465d78f5dc
diff --git a/examples/depth-occlusion/src/index.js b/examples/depth-occlusion/src/index.js
@@ -155,7 +155,10 @@ export class OcclusionDemoSystem extends createSystem({
       movementMode: MovementMode.MoveFromTarget,
     });
     entity.addComponent(XRAnchor);
-    entity.addComponent(DepthOccludable);
+    entity.addComponent(DepthOccludable, {
+      mode: OcclusionShadersMode.MinMaxSoftOcclusion,
+    });
+
 
     return entity;
   }
diff --git a/packages/core/src/depth/depth-occludable.ts b/packages/core/src/depth/depth-occludable.ts
@@ -13,6 +13,8 @@ export const OcclusionShadersMode = {
   SoftOcclusion: 'SoftOcclusion',
   /** Hard occlusion with a single depth sample per fragment. */
   HardOcclusion: 'HardOcclusion',
+  /** MinMax soft occlusion with depth preprocessing for edge-aware smooth edges. */
+  MinMaxSoftOcclusion: 'MinMaxSoftOcclusion',
 };
 
 /**
diff --git a/packages/core/src/depth/depth-sensing-system.ts b/packages/core/src/depth/depth-sensing-system.ts
@@ -6,10 +6,19 @@
  */
 
 import { createSystem, Entity, Types } from '../ecs/index.js';
-import { Mesh, Vector2 } from '../runtime/three.js';
+import { type IUniform, Mesh, Texture, Vector2 } from '../runtime/three.js';
 import { DepthOccludable, OcclusionShadersMode } from './depth-occludable.js';
 import { DepthTextures } from './depth-textures.js';
-import type { Shader, ShaderUniforms } from './types.js';
+import { DepthPreprocessingPass } from './occlusion/preprocessing-pass.js';
+
+type ShaderUniforms = { [uniform: string]: IUniform };
+
+interface Shader {
+  uniforms: ShaderUniforms;
+  defines?: { [key: string]: unknown };
+  vertexShader: string;
+  fragmentShader: string;
+}
 
 /**
  * DepthSensingSystem - Manages WebXR depth sensing and occlusion.
@@ -67,6 +76,8 @@ export class DepthSensingSystem extends createSystem(
   // Occlusion
   private entityShaderMap = new Map<Entity, Set<ShaderUniforms>>();
   private readonly viewportSize = new Vector2();
+  private preprocessingPass?: DepthPreprocessingPass;
+  private minMaxEntityCount = 0;
 
   /**
    * Get the raw value to meters conversion factor.
@@ -98,8 +109,20 @@ export class DepthSensingSystem extends createSystem(
 
     this.queries.occludables.subscribe('qualify', (entity: Entity) => {
       this.attachOcclusionToEntity(entity);
+      if (
+        DepthOccludable.data.mode[entity.index] ===
+        OcclusionShadersMode.MinMaxSoftOcclusion
+      ) {
+        this.minMaxEntityCount++;
+      }
     });
     this.queries.occludables.subscribe('disqualify', (entity: Entity) => {
+      if (
+        DepthOccludable.data.mode[entity.index] ===
+        OcclusionShadersMode.MinMaxSoftOcclusion
+      ) {
+        this.minMaxEntityCount--;
+      }
       this.detachOcclusionFromEntity(entity);
     });
   }
@@ -166,6 +189,9 @@ export class DepthSensingSystem extends createSystem(
     shader.uniforms.uViewportSize = { value: new Vector2() };
     shader.uniforms.uOcclusionBlurRadius = { value: 20.0 };
     shader.uniforms.uOcclusionHardMode = { value: false };
+    shader.uniforms.uOcclusionMinMaxMode = { value: false };
+    shader.uniforms.uMinMaxTexture0 = { value: null };
+    shader.uniforms.uMinMaxTexture1 = { value: null };
 
     shader.defines = {
       ...(shader.defines ?? {}),
@@ -200,6 +226,9 @@ export class DepthSensingSystem extends createSystem(
           'uniform vec2 uViewportSize;',
           'uniform float uOcclusionBlurRadius;',
           'uniform bool uOcclusionHardMode;',
+          'uniform bool uOcclusionMinMaxMode;',
+          'uniform sampler2D uMinMaxTexture0;',
+          'uniform sampler2D uMinMaxTexture1;',
           'varying float vOcclusionViewDepth;',
           '',
           'uniform sampler2DArray uXRDepthTextureArray;',
@@ -231,7 +260,29 @@ export class DepthSensingSystem extends createSystem(
           '  vec2 screenUV = gl_FragCoord.xy / uViewportSize;',
           '  vec2 depthUV = uIsGPUDepth ? screenUV : vec2(screenUV.x, 1.0 - screenUV.y);',
           '  float occlusion_value;',
-          '  if (uOcclusionHardMode) {',
+          '  if (uOcclusionMinMaxMode) {',
+          '    // MinMax soft occlusion — two-cluster edge-aware blending',
+          '    vec4 mmData;',
+          '    if (uint(VIEW_ID) == 0u) {',
+          '      mmData = texture2D(uMinMaxTexture0, depthUV);',
+          '    } else {',
+          '      mmData = texture2D(uMinMaxTexture1, depthUV);',
+          '    }',
+          '    float minAvgDepth = mmData.r;',
+          '    float maxAvgDepth = mmData.g;',
+          '    float midAvgDepth = mmData.r + mmData.b;',
+          '    float fadeRange = vOcclusionViewDepth * 0.04;',
+          '    float fadeRangeInv = 1.0 / max(fadeRange, 0.001);',
+          '    vec3 envDepths = vec3(minAvgDepth, maxAvgDepth, midAvgDepth);',
+          '    vec3 occAlphas = clamp((envDepths - vOcclusionViewDepth) * fadeRangeInv, 0.0, 1.0);',
+          '    occlusion_value = occAlphas.z;',
+          '    float alphaDiff = occAlphas.y - occAlphas.x;',
+          '    if (alphaDiff > 0.03) {',
+          '      float denom = mmData.a;',
+          '      float interp = denom > 0.001 ? mmData.b / denom : 0.5;',
+          '      occlusion_value = mix(occAlphas.x, occAlphas.y, smoothstep(0.2, 0.8, interp));',
+          '    }',
+          '  } else if (uOcclusionHardMode) {',
           '    occlusion_value = OcclusionGetSample(depthUV, vec2(0.0));',
           '  } else {',
           '   vec2 texelSize = uOcclusionBlurRadius / uViewportSize;',
@@ -267,6 +318,9 @@ export class DepthSensingSystem extends createSystem(
     this.depthFeatureEnabled = undefined;
     this.cpuDepthData = [];
     this.gpuDepthData = [];
+    this.preprocessingPass?.dispose();
+    this.preprocessingPass = undefined;
+    this.minMaxEntityCount = 0;
   }
 
   private updateEnabledFeatures(xrSession: XRSession | null): void {
@@ -295,10 +349,62 @@ export class DepthSensingSystem extends createSystem(
     }
 
     if (this.config.enableOcclusion.value) {
+      this.runMinMaxPreprocessing();
       this.updateOcclusionUniforms();
     }
   }
 
+  /**
+   * Runs the MinMax depth preprocessing pass if any entity uses MinMaxSoftOcclusion.
+   * Renders a fullscreen pass per eye that computes min/max/avg depth in a 4×4
+   * neighborhood, outputting to per-view 2D render targets.
+   */
+  private runMinMaxPreprocessing(): void {
+    if (this.minMaxEntityCount === 0) return;
+
+    const nativeTexture = this.depthTextures?.getNativeTexture();
+    const dataArrayTexture = this.depthTextures?.getDataArrayTexture();
+    const isGPUDepth = nativeTexture !== undefined;
+    const depthTextureArray = isGPUDepth
+      ? (nativeTexture as Texture)
+      : (dataArrayTexture as Texture);
+    if (!depthTextureArray) return;
+
+    const depthNear =
+      (this.gpuDepthData[0] as unknown as { depthNear: number } | undefined)
+        ?.depthNear ?? 0;
+
+    if (!this.preprocessingPass) {
+      this.preprocessingPass = new DepthPreprocessingPass();
+    }
+
+    this.preprocessingPass.setDepthTexture(
+      depthTextureArray,
+      this.rawValueToMeters,
+      isGPUDepth,
+      depthNear,
+    );
+
+    // Determine depth texture dimensions
+    let depthWidth: number;
+    let depthHeight: number;
+    if (this.cpuDepthData[0]) {
+      depthWidth = this.cpuDepthData[0].width;
+      depthHeight = this.cpuDepthData[0].height;
+    } else if (this.gpuDepthData[0]) {
+      // GPU depth textures have their own resolution (typically ~256×192),
+      // which is much smaller than the drawing buffer.
+      depthWidth = this.gpuDepthData[0].width;
+      depthHeight = this.gpuDepthData[0].height;
+    } else {
+      return; // No depth data available
+    }
+
+    // Render preprocessing for both eyes
+    this.preprocessingPass.render(this.renderer, depthWidth, depthHeight, 0);
+    this.preprocessingPass.render(this.renderer, depthWidth, depthHeight, 1);
+  }
+
   /**
    * Updates depth data from the XR frame.
    */
@@ -382,6 +488,9 @@ export class DepthSensingSystem extends createSystem(
       const isHardMode =
         DepthOccludable.data.mode[entity.index] ===
         OcclusionShadersMode.HardOcclusion;
+      const isMinMaxMode =
+        DepthOccludable.data.mode[entity.index] ===
+        OcclusionShadersMode.MinMaxSoftOcclusion;
 
       for (const uniforms of entityUniforms) {
         uniforms.uXRDepthTextureArray.value = depthTextureArray;
@@ -391,7 +500,13 @@ export class DepthSensingSystem extends createSystem(
         (uniforms.uViewportSize.value as Vector2).copy(this.viewportSize);
         uniforms.uOcclusionBlurRadius.value = this.config.blurRadius.value;
         uniforms.uOcclusionHardMode.value = isHardMode;
+        uniforms.uOcclusionMinMaxMode.value = isMinMaxMode;
         uniforms.occlusionEnabled.value = this.config.enableOcclusion.value;
+
+        if (isMinMaxMode && this.preprocessingPass) {
+          uniforms.uMinMaxTexture0.value = this.preprocessingPass.getTexture(0);
+          uniforms.uMinMaxTexture1.value = this.preprocessingPass.getTexture(1);
+        }
       }
     }
   }
diff --git a/packages/core/src/depth/depth-textures.ts b/packages/core/src/depth/depth-textures.ts
@@ -106,9 +106,7 @@ export class DepthTextures {
       this.nativeTexture.sourceTexture = depthData.texture;
     }
     // Update the texture properties for three.js
-    const textureProperties = renderer.properties.get(
-      this.nativeTexture,
-    ) as {
+    const textureProperties = renderer.properties.get(this.nativeTexture) as {
       __webglTexture: WebGLTexture;
       __version: number;
     };
diff --git a/packages/core/src/depth/index.ts b/packages/core/src/depth/index.ts
@@ -5,9 +5,6 @@
  * LICENSE file in the root directory of this source tree.
  */
 
-// Types and configuration
-export * from './types.js';
-
 // Components
 export * from './depth-occludable.js';
 
diff --git a/packages/core/src/depth/occlusion/preprocessing-pass.ts b/packages/core/src/depth/occlusion/preprocessing-pass.ts
@@ -0,0 +1,134 @@
+/**
+ * Copyright (c) Meta Platforms, Inc. and affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+
+import {
+  FloatType,
+  RGBAFormat,
+  ShaderMaterial,
+  Texture,
+  Vector2,
+  WebGLRenderer,
+  WebGLRenderTarget,
+} from '../../runtime/three.js';
+import { FullScreenQuad } from 'three/examples/jsm/postprocessing/Pass.js';
+import { DepthPreprocessingShader } from './preprocessing-shader.glsl.js';
+
+/**
+ * Depth preprocessing pass — ported from Meta SDK DepthPreprocessing.shader.
+ *
+ * Runs a single fullscreen pass on the raw XR depth texture at depth texture
+ * resolution (~256×192). For each output texel it samples a 4×4 neighborhood
+ * and computes min/max/avg depth, writing the result to an RGBA float target:
+ *
+ *   RGBA = (minAvg, maxAvg, avg - minAvg, maxAvg - minAvg)  in meters
+ *
+ * The material shader then samples this preprocessed texture to apply soft
+ * occlusion without requiring scene-override renders or Kawase blur.
+ */
+export class DepthPreprocessingPass {
+  private material: ShaderMaterial;
+  private renderTargets: [WebGLRenderTarget, WebGLRenderTarget];
+  private fsQuad: FullScreenQuad;
+
+  constructor() {
+    this.material = new ShaderMaterial({
+      name: 'DepthPreprocessing',
+      uniforms: {
+        uXRDepthTextureArray: { value: null },
+        uRawValueToMeters: { value: 0.001 },
+        uViewId: { value: 0 },
+        uDepthTextureSize: { value: new Vector2() },
+        uIsGPUDepth: { value: false },
+        uDepthNear: { value: 0 },
+      },
+      vertexShader: DepthPreprocessingShader.vertexShader,
+      fragmentShader: DepthPreprocessingShader.fragmentShader,
+    });
+
+    const rtOptions = { format: RGBAFormat, type: FloatType };
+    this.renderTargets = [
+      new WebGLRenderTarget(1, 1, rtOptions),
+      new WebGLRenderTarget(1, 1, rtOptions),
+    ];
+
+    this.fsQuad = new FullScreenQuad(this.material);
+  }
+
+  /**
+   * Set the depth texture source for preprocessing.
+   * @param depthTexture - The XR depth texture array (ExternalTexture or DataArrayTexture).
+   * @param rawValueToMeters - Conversion factor from raw depth values to meters.
+   * @param isGPUDepth - Whether the depth data is GPU-optimized (inverse depth).
+   * @param depthNear - The near plane distance for GPU depth conversion.
+   */
+  setDepthTexture(
+    depthTexture: Texture,
+    rawValueToMeters: number,
+    isGPUDepth: boolean,
+    depthNear: number,
+  ): void {
+    this.material.uniforms.uXRDepthTextureArray.value = depthTexture;
+    this.material.uniforms.uRawValueToMeters.value = rawValueToMeters;
+    this.material.uniforms.uIsGPUDepth.value = isGPUDepth;
+    this.material.uniforms.uDepthNear.value = depthNear;
+  }
+
+  /**
+   * Render the preprocessing pass.
+   * @param renderer - The three.js WebGL renderer.
+   * @param depthWidth - Width of the depth texture.
+   * @param depthHeight - Height of the depth texture.
+   * @param viewId - The view index to render (default 0).
+   */
+  render(
+    renderer: WebGLRenderer,
+    depthWidth: number,
+    depthHeight: number,
+    viewId = 0,
+  ): void {
+    const target = this.renderTargets[viewId];
+    // Only resize if dimensions actually changed
+    if (target.width !== depthWidth || target.height !== depthHeight) {
+      target.setSize(depthWidth, depthHeight);
+    }
+    this.material.uniforms.uViewId.value = viewId;
+    (this.material.uniforms.uDepthTextureSize.value as Vector2).set(
+      depthWidth,
+      depthHeight,
+    );
+
+    const originalRenderTarget = renderer.getRenderTarget();
+    // Temporarily disable XR so FullScreenQuad renders with its own
+    // identity camera instead of the XR stereo/multiview cameras.
+    const xrEnabled = renderer.xr.enabled;
+    renderer.xr.enabled = false;
+    renderer.setRenderTarget(target);
+    this.fsQuad.render(renderer);
+    renderer.setRenderTarget(originalRenderTarget);
+    renderer.xr.enabled = xrEnabled;
+  }
+
+  /**
+   * Get the preprocessed depth texture for a given view.
+   * RGBA = (minAvg, maxAvg, avg - minAvg, maxAvg - minAvg) in meters.
+   * @param viewId - The view index (0 for left eye, 1 for right eye).
+   */
+  getTexture(viewId = 0): Texture {
+    return this.renderTargets[viewId].texture;
+  }
+
+  /**
+   * Dispose of all resources.
+   */
+  dispose(): void {
+    for (const target of this.renderTargets) {
+      target.dispose();
+    }
+    this.material.dispose();
+    this.fsQuad.dispose();
+  }
+}
diff --git a/packages/core/src/depth/occlusion/preprocessing-shader.glsl.ts b/packages/core/src/depth/occlusion/preprocessing-shader.glsl.ts
diff --git a/packages/core/src/depth/types.ts b/packages/core/src/depth/types.ts
