[WebGPU-XR][Phase 3] Range-correct XR projection matrix for half-Z (WebGPU) engines

On a WebGPU engine (isNDCHalfZRange === true) the clip-space depth range is
[0, 1], while WebGL/OpenGL uses [-1, 1]. WebXRCamera copies the XR binding's
projection matrix verbatim and the rig cameras freeze their projection, so the
engine's range-aware projection builders are bypassed. If the binding returns a
[-1, 1]-convention matrix while the engine clips at [0, 1], every fragment with
NDC z in [-1, 0) is clipped and all world geometry disappears (clear color still
shows) - matching the in-headset "meshes flash a frame then vanish" symptom.

Fix (WebGPU-gated, WebGL2 byte-identical, zero net public API):
- Add @internal Matrix.convertProjectionToHalfZRangeInPlace(), reusing the
  engine's existing mtxConvertNDCToHalfZRange remap (the same conversion the
  perspective/orthographic builders apply when halfZRange is set).
- In WebXRCamera._updateFromXRSession, on a half-Z engine, empirically detect the
  convention the binding used (project the view-space near point through the raw
  matrix: NDC z ~= -1 => [-1, 1], ~= 0 => [0, 1]) and convert only a [-1, 1]
  matrix, so a spec-compliant [0, 1] binding is never double-converted. Guards
  minZ <= 0 (avoids divide-by-zero) and assumes non-reverse-Z. WebGL2
  (isNDCHalfZRange === false) never enters the block.

Adds 6 unit tests: [-1,1]->[0,1] conversion, [0,1] left unchanged, WebGL2
byte-identical, asymmetric off-center frusta, minZ<=0 guard, and converter
equivalence to the engine's half-Z builder.

Refs #18639

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>

Author: RaananW

packages/dev/core/src/Maths/math.vector.pure.ts

@@ -7315,6 +7315,20 @@ export class Matrix implements Tensor<Tuple<Tuple<number, 4>, 4>, Matrix>, IMatr
         return this;
     }
 
+    /**
+     * Converts this projection matrix's clip-space depth range from the OpenGL/WebGL convention (NDC z in [-1, 1]) to
+     * the WebGPU/D3D convention (NDC z in [0, 1]) in place, by post-multiplying with the standard half-Z conversion
+     * matrix. This is the same conversion the perspective/orthographic builders apply internally when their
+     * `halfZRange` flag is set; it is exposed here for callers (e.g. the WebXR path) that receive a projection matrix
+     * verbatim from an external source and must range-correct it for a `isNDCHalfZRange` engine.
+     * @internal
+     * @returns the current updated matrix
+     */
+    public convertProjectionToHalfZRangeInPlace(): this {
+        this.multiplyToRef(mtxConvertNDCToHalfZRange, this);
+        return this;
+    }
+
     // Statics
     /**
      * Creates a matrix from an array

packages/dev/core/src/XR/webXRCamera.ts

@@ -322,6 +322,33 @@ export class WebXRCamera extends FreeCamera {
             }
             Matrix.FromFloat32ArrayToRefScaled(view.projectionMatrix, 0, 1, currentRig._projectionMatrix);
 
+            // WebGPU uses a [0, 1] clip-space depth range (engine.isNDCHalfZRange === true) whereas WebGL/OpenGL uses
+            // [-1, 1]. The rig cameras freeze their projection (see _updateNumberOfRigCameras) and take the XR binding's
+            // projection matrix verbatim, bypassing the engine's range-aware projection builders. If the binding hands
+            // back a [-1, 1]-convention matrix while the engine clips at [0, 1], every fragment with NDC z in [-1, 0)
+            // is clipped and all geometry disappears. On a half-Z engine we therefore detect the convention the binding
+            // actually used and convert a [-1, 1] matrix to [0, 1]. Detection is empirical (coefficient inspection is
+            // provably ambiguous): project the view-space near-plane point through the raw matrix, before the hand
+            // toggle. WebXR view space is right-handed (-Z forward), so the near point is (0, 0, -near); a [-1, 1] matrix
+            // maps it to NDC z ~= -1, a [0, 1] matrix to ~= 0. Assumes a non-reverse-Z projection (near -> 0 or -1),
+            // which UA-provided XR matrices are. WebGL2 (isNDCHalfZRange === false) never enters this block, so its path
+            // is byte-identical.
+            if (this._scene.getEngine().isNDCHalfZRange) {
+                const near = this.minZ;
+                let needsHalfZConversion: boolean;
+                if (near > 0) {
+                    const ndc = Vector3.TransformCoordinatesFromFloatsToRef(0, 0, -near, currentRig._projectionMatrix, TmpVectors.Vector3[0]);
+                    needsHalfZConversion = ndc.z < -0.5;
+                } else {
+                    // depthNear must be > 0 per the WebXR spec; if it is not, the near-plane probe would divide by zero,
+                    // so default to converting (matches the [-1, 1] range current XRGPUBinding implementations return).
+                    needsHalfZConversion = true;
+                }
+                if (needsHalfZConversion) {
+                    currentRig._projectionMatrix.convertProjectionToHalfZRangeInPlace();
+                }
+            }
+
             if (!this._scene.useRightHandedSystem) {
                 currentRig._projectionMatrix.toggleProjectionMatrixHandInPlace();
             }

packages/dev/core/test/unit/XR/webXRCamera.test.ts

@@ -6,7 +6,7 @@ import { NullEngine } from "core/Engines";
 import { Scene } from "core/scene";
 import { WebXRCamera } from "core/XR/webXRCamera";
 import { WebXRSessionManager } from "core/XR/webXRSessionManager";
-import { Vector3, Quaternion } from "core/Maths/math.vector";
+import { Vector3, Quaternion, Matrix } from "core/Maths/math.vector";
 import { FreeCamera } from "core/Cameras/freeCamera";
 import { Camera } from "core/Cameras/camera";
 import { beforeEach, afterEach, describe, it, expect } from "vitest";
@@ -155,4 +155,134 @@ describe("WebXRCamera", () => {
             expect(xrCamera.rigCameras[1].outputRenderTarget).toBeNull();
         });
     });
+
+    describe("projection depth-range (WebGPU half-Z) handling", () => {
+        // Builds a synthetic right-handed XR projection matrix (as an XR binding would provide it) in the requested
+        // NDC depth convention. halfZRange === false => WebGL/OpenGL [-1, 1]; true => WebGPU/D3D [0, 1].
+        function buildXRProjection(halfZRange: boolean, near = 0.1, far = 1000): Float32Array {
+            const m = new Matrix();
+            Matrix.PerspectiveFovRHToRef(Math.PI / 2, 1, near, far, m, true, halfZRange);
+            return Float32Array.from(m.asArray());
+        }
+
+        // Drives one XR view update with the given raw binding projection matrix and returns the resulting frozen
+        // rig-camera projection matrix. Tests set scene.useRightHandedSystem to control whether the LH hand-toggle runs.
+        function driveViewUpdate(projectionMatrix: Float32Array): Matrix {
+            const pose = {
+                emulatedPosition: false,
+                transform: { position: { x: 0, y: 0, z: 0 }, orientation: { x: 0, y: 0, z: 0, w: 1 } },
+                views: [
+                    {
+                        eye: "left",
+                        transform: { position: { x: 0, y: 0, z: 0 }, orientation: { x: 0, y: 0, z: 0, w: 1 } },
+                        projectionMatrix,
+                    },
+                ],
+            };
+            sessionManager.currentFrame = { getViewerPose: () => pose } as any;
+            // There is no real XR session in unit tests, so seed the near/far cache to skip the updateRenderState path.
+            (xrCamera as any)._cache.minZ = xrCamera.minZ;
+            (xrCamera as any)._cache.maxZ = xrCamera.maxZ;
+            (xrCamera as any)._updateFromXRSession();
+            return (xrCamera.rigCameras[0] as any)._projectionMatrix as Matrix;
+        }
+
+        // NDC z of the right-handed view-space point (0, 0, z) after the perspective divide.
+        function ndcZ(matrix: Matrix, z: number): number {
+            return Vector3.TransformCoordinatesFromFloatsToRef(0, 0, z, matrix, new Vector3()).z;
+        }
+
+        it("converts a [-1, 1] XR projection to [0, 1] on a half-Z (WebGPU) engine", () => {
+            scene.useRightHandedSystem = true; // isolate the depth-range conversion from the LH hand-toggle
+            (engine as any).isNDCHalfZRange = true;
+
+            const result = driveViewUpdate(buildXRProjection(false, 0.1, 1000));
+
+            expect(ndcZ(result, -0.1)).toBeCloseTo(0, 4); // near plane -> 0
+            expect(ndcZ(result, -1000)).toBeCloseTo(1, 4); // far plane -> 1
+        });
+
+        it("leaves an already [0, 1] XR projection unchanged on a half-Z engine (no double conversion)", () => {
+            scene.useRightHandedSystem = true;
+            (engine as any).isNDCHalfZRange = true;
+
+            const raw = buildXRProjection(true, 0.1, 1000);
+            const result = driveViewUpdate(raw);
+
+            // Still maps near -> 0 / far -> 1 (would be ~0.25 / ~1 if double-converted).
+            expect(ndcZ(result, -0.1)).toBeCloseTo(0, 4);
+            expect(ndcZ(result, -1000)).toBeCloseTo(1, 4);
+            // And it is numerically the raw matrix (conversion skipped entirely).
+            const rawMatrix = Matrix.FromArray(raw);
+            for (let k = 0; k < 16; k++) {
+                expect(result.m[k]).toBeCloseTo(rawMatrix.m[k], 6);
+            }
+        });
+
+        it("never touches the projection on a non-half-Z (WebGL2) engine - byte identical", () => {
+            // NullEngine defaults isNDCHalfZRange to false; assert explicitly for clarity.
+            (engine as any).isNDCHalfZRange = false;
+
+            const raw = buildXRProjection(false, 0.1, 1000); // WebGL [-1, 1] convention
+            const result = driveViewUpdate(raw); // default LH scene => hand-toggle applies
+
+            // Expected = verbatim load + hand-toggle, with NO range conversion (the WebGPU block is skipped).
+            const expected = Matrix.FromArray(raw);
+            expected.toggleProjectionMatrixHandInPlace();
+            for (let k = 0; k < 16; k++) {
+                expect(result.m[k]).toBe(expected.m[k]); // exact / byte-identical
+            }
+        });
+
+        it("converts an asymmetric (off-center) [-1, 1] XR projection - real XR eye frusta", () => {
+            scene.useRightHandedSystem = true;
+            (engine as any).isNDCHalfZRange = true;
+
+            // Start from a symmetric [-1, 1] projection and introduce off-center x/y projection-plane offsets
+            // (m[8], m[9]) to mimic a real, asymmetric XR eye frustum. These do not affect the depth mapping.
+            const raw = buildXRProjection(false, 0.1, 1000);
+            raw[8] = 0.2;
+            raw[9] = -0.15;
+            const result = driveViewUpdate(raw);
+
+            // Depth still maps to [0, 1] despite the asymmetry...
+            expect(ndcZ(result, -0.1)).toBeCloseTo(0, 4);
+            expect(ndcZ(result, -1000)).toBeCloseTo(1, 4);
+            // ...and the asymmetry (x/y offset columns) is preserved by the conversion (it only remaps the z column).
+            expect(result.m[8]).toBeCloseTo(0.2, 6);
+            expect(result.m[9]).toBeCloseTo(-0.15, 6);
+        });
+
+        it("guards depthNear <= 0: defaults to converting without producing NaN", () => {
+            scene.useRightHandedSystem = true;
+            (engine as any).isNDCHalfZRange = true;
+            xrCamera.minZ = 0; // near-plane probe would divide by zero -> guard path
+
+            const raw = buildXRProjection(false, 0.1, 1000);
+            const result = driveViewUpdate(raw);
+
+            for (let k = 0; k < 16; k++) {
+                expect(Number.isNaN(result.m[k])).toBe(false);
+            }
+            // Guard forces conversion; result equals the raw matrix with the half-Z conversion applied.
+            const expected = Matrix.FromArray(raw).convertProjectionToHalfZRangeInPlace();
+            for (let k = 0; k < 16; k++) {
+                expect(result.m[k]).toBeCloseTo(expected.m[k], 6);
+            }
+        });
+
+        it("convertProjectionToHalfZRangeInPlace matches the engine's own half-Z builder", () => {
+            // The @internal converter must reproduce exactly what PerspectiveFovRHToRef bakes in when halfZRange is set.
+            const converted = new Matrix();
+            Matrix.PerspectiveFovRHToRef(1.2, 1.5, 0.2, 500, converted, true, false); // [-1, 1]
+            converted.convertProjectionToHalfZRangeInPlace();
+
+            const reference = new Matrix();
+            Matrix.PerspectiveFovRHToRef(1.2, 1.5, 0.2, 500, reference, true, true); // [0, 1]
+
+            for (let k = 0; k < 16; k++) {
+                expect(converted.m[k]).toBeCloseTo(reference.m[k], 6);
+            }
+        });
+    });
 });