@zephyr3d/scene 0.9.22 → 0.9.24

package/dist/shaders/ssr.js

@@ -1,6 +1,6 @@
 import { ShaderHelper } from '../material/shader/helper.js';
+import { REVERSE_Z } from '@zephyr3d/base';
 
-const MAX_FLOAT_VALUE = 3.402823466e38;
 /** @internal */ function SSR_calcJitter(scope, viewPos, roughness) {
     const pb = scope.$builder;
     pb.func('SSR_calcJitter', [
@@ -21,14 +21,14 @@ const MAX_FLOAT_VALUE = 3.402823466e38;
         pb.vec3('p'),
         pb.mat4('mat')
     ], function() {
-        this.$l.c = pb.sub(pb.mul(this.p, 2), pb.vec3(1));
+        this.$l.c = pb.vec3(pb.sub(pb.mul(this.p.xy, 2), pb.vec2(1)), ShaderHelper.deviceDepthToClipZ(this, this.p.z));
         this.$l.u = pb.mul(this.mat, pb.vec4(this.c, 1));
         this.u = pb.div(this.u, this.u.w);
         this.$return(this.u.xyz);
     });
     return scope.invProjectPosition(pos, mat);
 }
-/** @internal */ function validateHit(scope, hit2D, hit3D, surfaceZ, thickness, uv, traceRay, viewMatrix, invProjMatrix, textureSize, normalTexture) {
+/** @internal */ function validateHit(scope, hit2D, hit3D, surfaceZ, thickness, uv, traceRay, viewMatrix, invProjMatrix, textureSize, normalTexture, debugValidationOut) {
     const pb = scope.$builder;
     const funcName = hit3D ? 'SSR_validateHit_HiZ' : 'SSR_validateHit';
     pb.func(funcName, [
@@ -44,19 +44,34 @@ const MAX_FLOAT_VALUE = 3.402823466e38;
         pb.vec3('viewSpaceRayDirection'),
         pb.mat4('viewMatrix'),
         pb.mat4('invProjMatrix'),
-        pb.vec4('textureSize')
+        pb.vec4('textureSize'),
+        ...debugValidationOut ? [
+            pb.vec3('debugValidation').out()
+        ] : []
     ], function() {
+        if (debugValidationOut) {
+            this.debugValidation = pb.vec3(1, 1, 0);
+        }
         this.$if(pb.or(pb.any(pb.lessThan(this.hit2d, pb.vec2(0))), pb.any(pb.greaterThan(this.hit2d, pb.vec2(1)))), function() {
+            if (debugValidationOut) {
+                this.debugValidation = pb.vec3(0);
+            }
             this.$return(pb.float(0));
         });
         this.$l.manhattanDist = pb.abs(pb.sub(this.hit2d, this.uv));
         this.$if(pb.all(pb.lessThan(this.manhattanDist, pb.vec2(pb.div(pb.vec2(2), this.textureSize.xy)))), function() {
+            if (debugValidationOut) {
+                this.debugValidation.x = 0;
+            }
             this.$return(pb.float(0));
         });
         if (normalTexture) {
             this.$l.hitNormalWS = pb.sub(pb.mul(pb.textureSampleLevel(normalTexture, this.hit2d, 0).rgb, 2), pb.vec3(1));
             this.$l.hitNormalVS = pb.mul(this.viewMatrix, pb.vec4(this.hitNormalWS, 0)).xyz;
             this.$if(pb.greaterThan(pb.dot(this.hitNormalVS, this.viewSpaceRayDirection), 0), function() {
+                if (debugValidationOut) {
+                    this.debugValidation.y = 0;
+                }
                 this.$return(pb.float(0));
             });
         }
@@ -67,14 +82,38 @@ const MAX_FLOAT_VALUE = 3.402823466e38;
         if (this.hit3d) {
             this.$l.distance = pb.distance(this.viewSpaceSurface, this.hit3d);
             this.$l.confidence = pb.sub(1, pb.smoothStep(0, this.thickness, this.distance));
+            if (debugValidationOut) {
+                this.debugValidation.z = this.confidence;
+            }
             this.$return(pb.mul(this.vignette, this.confidence, this.confidence));
         } else {
             this.$return(this.vignette);
         }
     });
-    return hit3D ? scope[funcName](hit2D, hit3D, thickness, surfaceZ, uv, traceRay, viewMatrix, invProjMatrix, textureSize) : scope[funcName](hit2D, surfaceZ, uv, traceRay, viewMatrix, invProjMatrix, textureSize);
+    return hit3D ? debugValidationOut ? scope[funcName](hit2D, hit3D, thickness, surfaceZ, uv, traceRay, viewMatrix, invProjMatrix, textureSize, debugValidationOut) : scope[funcName](hit2D, hit3D, thickness, surfaceZ, uv, traceRay, viewMatrix, invProjMatrix, textureSize) : scope[funcName](hit2D, surfaceZ, uv, traceRay, viewMatrix, invProjMatrix, textureSize);
 }
-function screenSpaceRayTracing_Linear2D(scope, viewPos, traceRay, viewMatrix, projMatrix, invProjMatrix, cameraNearFar, maxDistance, maxIterations, thickness, stride, textureSize, linearDepthTex, normalTexture, useBackfaceDepth) {
+/**
+ * Optional `giTraceOut` (both tracers): `vec3(occluded, escaped, rawConfidence)`.
+ *
+ * Reflections only care whether a hit is usable, so the returned confidence folds
+ * together "was the ray blocked" and "can its radiance be trusted". Diffuse GI
+ * needs those apart: a hit whose colour is unusable still occludes the sky.
+ * - `occluded`: the march intersected geometry (not a sky texel).
+ * - `escaped`: the march missed and the ray was provably unoccluded where it
+ *   stopped. Neither flag set means the outcome is indeterminate (ran out of
+ *   screen or iterations behind geometry) and callers should exclude the sample
+ *   rather than treat it as unoccluded.
+ * - `certainty`: how certain the intersection is *geometrically* — the hit's
+ *   distance from the sampled surface relative to the thickness, so a thin-object
+ *   false positive does not occlude. Deliberately excludes the screen-border,
+ *   near-self and backface vetoes {@link validateHit} applies: those bound
+ *   reflection artifacts, whereas for diffuse GI a border, adjacent or
+ *   back-facing hit is real geometry whose screen colour is still the best
+ *   available estimate of its outgoing radiance. The march-length attenuation is
+ *   excluded too, as it would make occlusion depend on camera distance.
+ *
+ * Callers that omit the parameter generate exactly the same shader as before.
+ */ function screenSpaceRayTracing_Linear2D(scope, viewPos, traceRay, viewMatrix, projMatrix, invProjMatrix, cameraNearFar, maxDistance, maxIterations, thickness, stride, textureSize, linearDepthTex, normalTexture, useBackfaceDepth, giTraceOut) {
     const pb = scope.$builder;
     pb.func('distanceSquared', [
         pb.vec2('a'),
@@ -211,7 +250,7 @@ function screenSpaceRayTracing_Linear2D(scope, viewPos, traceRay, viewMatrix, pr
         this.hit3D = pb.div(this.Q0, this.pqk.w);
         this.$return(this.intersected);
     });
-    pb.func('SSR_Linear2D', [
+    pb.func(giTraceOut ? 'SSR_Linear2D_GI' : 'SSR_Linear2D', [
         pb.vec3('rayOrigin'),
         pb.vec3('rayDirection'),
         pb.mat4('viewMatrix'),
@@ -222,22 +261,50 @@ function screenSpaceRayTracing_Linear2D(scope, viewPos, traceRay, viewMatrix, pr
         pb.float('maxIterations'),
         pb.float('thickness'),
         pb.vec2('cameraNearFar'),
-        pb.vec4('textureSize')
+        pb.vec4('textureSize'),
+        ...giTraceOut ? [
+            pb.vec3('giTrace').out()
+        ] : []
     ], function() {
+        if (giTraceOut) {
+            this.giTrace = pb.vec3(0);
+        }
         this.$l.hit2D = pb.vec3();
         this.$l.hit3D = pb.vec3();
         this.$l.origin = pb.vec2();
         this.$l.numIterations = pb.float();
         this.$l.intersected = this.traceRayLinear2D(this.rayOrigin, this.rayDirection, this.stride, this.maxDistance, this.maxIterations, this.thickness, this.cameraNearFar, this.projMatrix, this.textureSize, this.hit2D, this.hit3D, this.origin, this.numIterations);
-        this.$if(pb.not(this.intersected), function() {
-            this.$return(pb.vec4(0));
-        });
-        this.$l.surfaceZ01 = ShaderHelper.sampleLinearDepth(this, linearDepthTex, this.hit2D.xy, 0);
+        if (giTraceOut) {
+            // Depth where the march stopped. A miss only counts as a free escape
+            // when the ray was still in front of the depth buffer there; a ray that
+            // left the screen from behind geometry is indeterminate, not unoccluded.
+            this.$l.exitSurfaceZ01 = ShaderHelper.sampleLinearDepth(this, linearDepthTex, this.hit2D.xy, 0);
+            this.$if(pb.not(this.intersected), function() {
+                this.$l.exitSceneZ = pb.neg(pb.mul(this.exitSurfaceZ01, this.cameraNearFar.y));
+                this.giTrace = pb.vec3(0, pb.float(pb.or(pb.greaterThanEqual(this.exitSurfaceZ01, 1), pb.greaterThan(this.hit2D.z, this.exitSceneZ))), 0);
+                this.$return(pb.vec4(0));
+            });
+        } else {
+            this.$if(pb.not(this.intersected), function() {
+                this.$return(pb.vec4(0));
+            });
+        }
+        this.$l.surfaceZ01 = giTraceOut ? this.exitSurfaceZ01 : ShaderHelper.sampleLinearDepth(this, linearDepthTex, this.hit2D.xy, 0);
         this.$if(pb.equal(this.surfaceZ01, 1), function() {
+            if (giTraceOut) {
+                // The intersection resolved onto a sky texel, so the ray escaped.
+                this.giTrace = pb.vec3(0, 1, 0);
+            }
             this.$return(pb.vec4(0));
         });
         this.$l.surfaceZ = ShaderHelper.linearDepthToNonLinear(this, pb.mul(this.surfaceZ01, this.cameraNearFar.y), this.cameraNearFar);
         this.$l.confidence = validateHit(this, this.hit2D.xy, null, this.surfaceZ, null, this.origin, this.rayDirection, this.viewMatrix, this.invProjMatrix, this.textureSize, normalTexture);
+        if (giTraceOut) {
+            // rayIntersectDepth already enforced the thickness window, so an
+            // intersection here is geometrically certain regardless of the vetoes
+            // validateHit applies for reflections.
+            this.giTrace = pb.vec3(1, 0, 1);
+        }
         this.$l.iterationAttenuation = pb.sub(1, pb.smoothStep(0, this.maxIterations, this.numIterations));
         //this.$l.iterationAttenuation = pb.smoothStep(this.maxIterations, 1, this.numIterations);
         this.confidence = pb.mul(this.confidence, this.iterationAttenuation);
@@ -246,15 +313,50 @@ function screenSpaceRayTracing_Linear2D(scope, viewPos, traceRay, viewMatrix, pr
         this.$l.hitDistance = pb.length(pb.sub(this.hitPixel, this.startPixel));
         this.$return(pb.vec4(this.hit2D.xy, this.hitDistance, this.confidence));
     });
-    return scope.SSR_Linear2D(viewPos, traceRay, viewMatrix, projMatrix, invProjMatrix, stride, maxDistance, maxIterations, thickness, cameraNearFar, textureSize);
+    return giTraceOut ? scope.SSR_Linear2D_GI(viewPos, traceRay, viewMatrix, projMatrix, invProjMatrix, stride, maxDistance, maxIterations, thickness, cameraNearFar, textureSize, giTraceOut) : scope.SSR_Linear2D(viewPos, traceRay, viewMatrix, projMatrix, invProjMatrix, stride, maxDistance, maxIterations, thickness, cameraNearFar, textureSize);
 }
-function screenSpaceRayTracing_HiZ(scope, viewPos, traceRay, viewMatrix, projMatrix, invProjMatrix, cameraNearFar, maxMipLevel, maxIterations, maxDistance, thickness, textureSize, HiZTexture, normalTexture) {
+/**
+ * UE5 Random.ush InterleavedGradientNoise. Used as the temporal jitter
+ * (StepOffset) for the fixed-step HZB march below.
+ */ function SSR_interleavedGradientNoise(scope, uv, frameId) {
     const pb = scope.$builder;
-    pb.func('getMipResolution', [
-        pb.int('mipLevel')
+    pb.func('SSR_IGN', [
+        pb.vec2('uv'),
+        pb.float('frameId')
     ], function() {
-        this.$return(pb.vec2(pb.textureDimensions(HiZTexture, this.mipLevel)));
+        this.$l.p = pb.add(this.uv, pb.mul(pb.vec2(47, 17), 0.695, this.frameId));
+        this.$return(pb.fract(pb.mul(52.9829189, pb.fract(pb.dot(this.p, pb.vec2(0.06711056, 0.00583715))))));
     });
+    return scope.SSR_IGN(uv, frameId);
+}
+/**
+ * Screen space ray intersection against the HZB, ported from UE5's
+ * SSRTRayCast.ush (InitScreenSpaceRayFromWorldSpace + CastScreenSpaceRay):
+ * a fixed-step linear march over the ray clipped/extended to the screen
+ * border, sampling the furthest-depth pyramid at a mip level that grows with
+ * roughness, with a slope-based CompareTolerance hit window and line-segment
+ * hit refinement.
+ *
+ * Convention differences vs UE5:
+ * - UE is reversed-Z (larger = closer); we use standard Z, so every depth
+ *   difference is mirrored (`Diff = SampleDepth - SampleZ`).
+ * - UE view space has +z forward; ours has -z forward.
+ * - UE's HZB is a half-res pow2 pyramid and starts marching at its mip 1;
+ *   ours is full-res at mip0. Under standard-Z the march starts at
+ *   START_MIP = 0, because the coarse furthest-depth blocks quantize into a
+ *   staircase that grazing rays periodically self-intersect, showing up as
+ *   regular stripes TAA cannot converge. Under reverse-Z depth precision is
+ *   nearly uniform, so the march starts at mip 1 like UE; rough reflections
+ *   still climb the pyramid via the roughness mip ramp in both cases.
+ *
+ * `maxIterations` is the number of linear samples along the ray (UE NumSteps,
+ * typically 8..64), no longer the traversal iteration cap of the previous
+ * FidelityFX-style implementation.
+ */ function screenSpaceRayTracing_HiZ(scope, viewPos, traceRay, viewMatrix, projMatrix, invProjMatrix, cameraNearFar, maxMipLevel, maxIterations, maxDistance, thickness, textureSize, HiZTexture, normalTexture, giTraceOut, roughness, stepOffset) {
+    const pb = scope.$builder;
+    // The r32f pyramid stores the furthest depth (max reduction; mip0 is the
+    // raw depth). Matches UE5 marching against the FurthestHZBTexture (UE is
+    // reversed-Z, so its furthest pyramid is the min reduction instead).
     pb.func('SSR_loadDepth', [
         pb.vec2('uv'),
         pb.float('level')
@@ -265,130 +367,172 @@ function screenSpaceRayTracing_HiZ(scope, viewPos, traceRay, viewMatrix, projMat
         pb.vec3('p'),
         pb.mat4('mat')
     ], function() {
-        this.$l.c = pb.sub(pb.mul(this.p, 2), pb.vec3(1));
+        this.$l.c = pb.vec3(pb.sub(pb.mul(this.p.xy, 2), pb.vec2(1)), ShaderHelper.deviceDepthToClipZ(this, this.p.z));
         this.$l.u = pb.mul(this.mat, pb.vec4(this.c, 1));
         this.u = pb.div(this.u, this.u.w);
         this.$return(this.u.xyz);
     });
-    pb.func('projectPosition', [
-        pb.vec3('p'),
-        pb.mat4('mat')
+    // Port of UE5 GetStepScreenFactorToClipAtScreenEdge. Returns the multiplier
+    // for rayStepNDC so the ray ends exactly at the screen border. A factor
+    // above 1 extends short rays to the border (UE bExtendRayToScreenBorder).
+    pb.func('SSR_clipRayToScreenEdge', [
+        pb.vec2('rayStartNDC'),
+        pb.vec2('rayStepNDC')
     ], function() {
-        this.$l.projected = pb.mul(this.mat, pb.vec4(this.p, 1));
-        this.projected = pb.div(this.projected, this.projected.w);
-        this.projected = pb.add(pb.mul(this.projected, 0.5), pb.vec4(0.5));
-        this.$return(this.projected.xyz);
+        this.$l.rayStepInvFactor = pb.mul(0.5, pb.length(this.rayStepNDC));
+        this.$l.absStep = pb.max(pb.abs(this.rayStepNDC), pb.vec2(1e-8));
+        this.$l.s = pb.sub(pb.vec2(1), pb.div(pb.max(pb.sub(pb.abs(pb.add(this.rayStepNDC, pb.mul(this.rayStartNDC, this.rayStepInvFactor))), pb.vec2(this.rayStepInvFactor)), pb.vec2(0)), this.absStep));
+        this.$return(pb.div(pb.min(this.s.x, this.s.y), pb.max(this.rayStepInvFactor, 1e-8)));
     });
-    pb.func('projectDirection', [
-        pb.vec3('p'),
-        pb.vec3('d'),
-        pb.vec3('screenSpacePos'),
-        pb.mat4('mat')
-    ], function() {
-        this.$return(pb.sub(this.projectPosition(pb.add(this.p, this.d), this.mat), this.screenSpacePos));
-    });
-    pb.func('SSR_initialAdvanceRay', [
-        pb.vec3('origin'),
-        pb.vec3('direction'),
-        pb.vec3('invDirection'),
-        pb.vec2('currentMipResolution'),
-        pb.vec2('invCurrentMipResolution'),
-        pb.vec2('floorOffset'),
-        pb.vec2('uvOffset'),
-        pb.vec3('position').out(),
-        pb.float('currentT').out()
+    // Port of UE5 InitScreenSpaceRayFromWorldSpace, in view space (-z forward).
+    // Outputs the ray in "texture space": uv in [0,1], z = device depth in
+    // [0,1], the same mapping the HZB stores.
+    pb.func('SSR_initScreenSpaceRay', [
+        pb.vec3('viewPos'),
+        pb.vec3('rayDirection'),
+        pb.float('maxDistance'),
+        pb.float('slopeCompareToleranceScale'),
+        pb.mat4('projMatrix'),
+        pb.vec3('rayStartTS').out(),
+        pb.vec3('rayStepTS').out(),
+        pb.float('compareTolerance').out()
     ], function() {
-        this.$l.currentMipPosition = pb.mul(this.currentMipResolution, this.origin.xy);
-        this.$l.xyPlane = pb.add(pb.floor(this.currentMipPosition), this.floorOffset);
-        this.xyPlane = pb.add(pb.mul(this.xyPlane, this.invCurrentMipResolution), this.uvOffset);
-        this.$l.t = pb.mul(pb.sub(this.xyPlane, this.origin.xy), this.invDirection.xy);
-        this.currentT = pb.min(this.t.x, this.t.y);
-        this.position = pb.add(this.origin, pb.mul(this.direction, this.currentT));
+        // Rays heading towards the camera stop before reaching 5% of the
+        // surface view depth (UE: min(-0.95 * SceneDepth / ViewDirZ, TMax)).
+        this.$l.rayLength = this.$choice(pb.greaterThan(this.rayDirection.z, 0), pb.min(this.maxDistance, pb.div(pb.mul(-0.95, this.viewPos.z), pb.max(this.rayDirection.z, 1e-6))), this.maxDistance);
+        this.$l.rayEnd = pb.add(this.viewPos, pb.mul(this.rayDirection, this.rayLength));
+        this.$l.startH = pb.mul(this.projMatrix, pb.vec4(this.viewPos, 1));
+        this.$l.endH = pb.mul(this.projMatrix, pb.vec4(this.rayEnd, 1));
+        this.$l.startNDC = pb.div(this.startH.xyz, this.startH.w);
+        this.$l.endNDC = pb.div(this.endH.xyz, this.endH.w);
+        this.$l.stepNDC = pb.sub(this.endNDC, this.startNDC);
+        // Always extend/clip the ray to the screen border so NumSteps samples
+        // cover the whole visible segment.
+        this.stepNDC = pb.mul(this.stepNDC, this.SSR_clipRayToScreenEdge(this.startNDC.xy, this.stepNDC.xy));
+        if (REVERSE_Z) {
+            // Reverse ZO canonical clip space: NDC z is already the device depth.
+            this.rayStartTS = pb.vec3(pb.add(pb.mul(this.startNDC.xy, 0.5), pb.vec2(0.5)), this.startNDC.z);
+            this.rayStepTS = pb.vec3(pb.mul(this.stepNDC.xy, 0.5), this.stepNDC.z);
+        } else {
+            this.rayStartTS = pb.add(pb.mul(this.startNDC, 0.5), pb.vec3(0.5));
+            this.rayStepTS = pb.mul(this.stepNDC, 0.5);
+        }
+        // Depth-only step (UE RayDepthScreen): project the point at rayLength
+        // straight along the view forward axis for the slope tolerance.
+        this.$l.depthH = pb.mul(this.projMatrix, pb.vec4(this.viewPos.xy, pb.sub(this.viewPos.z, this.rayLength), 1));
+        this.$l.depthTSz = REVERSE_Z ? pb.div(this.depthH.z, this.depthH.w) : pb.add(pb.mul(pb.div(this.depthH.z, this.depthH.w), 0.5), 0.5);
+        // Under standard Z depth grows away from the camera, mirroring UE's
+        // reversed-Z expression (RayStartScreen.z - RayDepthScreen.z); under
+        // reverse-Z the UE orientation applies directly.
+        this.compareTolerance = pb.max(pb.abs(this.rayStepTS.z), pb.mul(REVERSE_Z ? pb.sub(this.rayStartTS.z, this.depthTSz) : pb.sub(this.depthTSz, this.rayStartTS.z), this.slopeCompareToleranceScale));
     });
-    pb.func('SSR_advanceRay', [
-        pb.vec3('origin'),
-        pb.vec3('direction'),
-        pb.vec3('invDirection'),
-        pb.vec2('currentMipPosition'),
-        pb.vec2('invCurrentMipResolution'),
-        pb.vec2('floorOffset'),
-        pb.vec2('uvOffset'),
-        pb.float('surfaceZ'),
-        pb.float('surfaceZMax'),
-        pb.int('currentMip'),
-        pb.vec3('position').inout(),
-        pb.float('currentT').inout()
+    // Port of UE5 CastScreenSpaceRay: NumSteps uniform samples in batches of 4,
+    // mip level ramped by roughness, tolerance-window hit test, uncertainty
+    // tracking and line-segment hit refinement.
+    // Standard-Z keeps 0 instead of UE's StartMipLevel=1: coarse-mip depth
+    // staircases combined with the poor far-depth resolution near 1.0 cause
+    // grazing-angle stripe artifacts. Under reverse-Z depth precision is nearly
+    // uniform along the ray, so the march starts at mip 1 like UE for better
+    // texture cache behavior.
+    const START_MIP = REVERSE_Z ? 1 : 0;
+    pb.func('SSR_castScreenSpaceRay', [
+        pb.vec3('rayStartTS'),
+        pb.vec3('rayStepTS'),
+        pb.float('compareToleranceIn'),
+        pb.float('numSteps'),
+        pb.float('stepOffset'),
+        pb.float('roughness'),
+        pb.float('maxMipLevel'),
+        pb.vec3('hitUVz').out(),
+        pb.bool('foundHit').out(),
+        pb.bool('uncertain').out(),
+        pb.float('numIterations').out()
     ], function() {
-        this.$l.xyPlane = pb.add(pb.floor(this.currentMipPosition), this.floorOffset);
-        this.xyPlane = pb.add(pb.mul(this.xyPlane, this.invCurrentMipResolution), this.uvOffset);
-        this.$l.skippedTile = pb.bool();
-        this.$if(pb.greaterThan(this.direction.z, 0), function() {
-            // Preserve the proven min-depth traversal for rays moving away from the camera.
-            this.$l.boundaryPlanes = pb.vec3(this.xyPlane, this.surfaceZ);
-            this.$l.forwardT = pb.mul(pb.sub(this.boundaryPlanes, this.origin), this.invDirection);
-            this.$l.tMin = pb.min(pb.min(this.forwardT.x, this.forwardT.y), this.forwardT.z);
-            this.$l.aboveSurface = pb.greaterThan(this.surfaceZ, this.position.z);
-            this.skippedTile = pb.and(pb.notEqual(pb.floatBitsToUint(this.tMin), pb.floatBitsToUint(this.forwardT.z)), this.aboveSurface);
-            this.currentT = this.$choice(this.aboveSurface, this.tMin, this.currentT);
-            this.position = pb.add(this.origin, pb.mul(this.direction, this.currentT));
-        }).$else(function() {
-            this.$l.reverseT = pb.mul(pb.sub(this.xyPlane, this.origin.xy), this.invDirection.xy);
-            this.$l.tExit = pb.min(this.reverseT.x, this.reverseT.y);
-            this.$l.exitZ = pb.add(this.origin.z, pb.mul(this.direction.z, this.tExit));
-            this.$l.rayMinZ = pb.min(this.position.z, this.exitZ);
-            this.$l.rayMaxZ = pb.max(this.position.z, this.exitZ);
-            this.$l.overlapsDepth = pb.and(pb.greaterThanEqual(this.rayMaxZ, this.surfaceZ), pb.lessThanEqual(this.rayMinZ, this.surfaceZMax));
-            this.skippedTile = pb.not(this.overlapsDepth);
-            this.$if(this.skippedTile, function() {
-                this.currentT = this.tExit;
-                this.position = pb.add(this.origin, pb.mul(this.direction, this.currentT));
-            }).$elseif(pb.equal(this.currentMip, 0), function() {
-                this.$if(pb.greaterThan(pb.abs(this.direction.z), 1e-6), function() {
-                    this.currentT = pb.div(pb.sub(this.surfaceZMax, this.origin.z), this.direction.z);
-                    this.position = pb.add(this.origin, pb.mul(this.direction, this.currentT));
+        this.$l.step = pb.div(1, this.numSteps);
+        this.$l.compareTolerance = pb.mul(this.compareToleranceIn, this.step);
+        this.$l.rayStepUVz = pb.mul(this.rayStepTS, this.step);
+        this.$l.rayUVz = pb.add(this.rayStartTS, pb.mul(this.rayStepUVz, this.stepOffset));
+        this.$l.level = pb.float(START_MIP);
+        this.$l.mipInc = pb.mul(pb.div(8, this.numSteps), this.roughness);
+        this.$l.lastDiff = pb.float(0);
+        this.foundHit = false;
+        this.uncertain = false;
+        this.$l.marchBase = pb.float(0);
+        // Depth diffs / hit flags of the current 4-sample batch, kept for the
+        // post-loop hit refinement.
+        this.$l.diff0 = pb.float(0);
+        this.$l.diff1 = pb.float(0);
+        this.$l.diff2 = pb.float(0);
+        this.$l.diff3 = pb.float(0);
+        this.$l.hit0 = pb.bool(false);
+        this.$l.hit1 = pb.bool(false);
+        this.$l.hit2 = pb.bool(false);
+        this.$l.hit3 = pb.bool(false);
+        this.$l.numBatches = pb.ceil(pb.mul(this.numSteps, 0.25));
+        this.$for(pb.float('i'), 0, pb.getDevice().type === 'webgl' ? 64 : this.numBatches, function() {
+            if (pb.getDevice().type === 'webgl') {
+                this.$if(pb.greaterThanEqual(this.i, this.numBatches), function() {
+                    this.$break();
                 });
+            }
+            this.marchBase = pb.mul(this.i, 4);
+            // Two samples per mip step (UE: SamplesMip.xy = Level; Level += inc).
+            this.$l.mip01 = pb.min(this.level, this.maxMipLevel);
+            this.$l.mip23 = pb.min(pb.add(this.level, this.mipInc), this.maxMipLevel);
+            this.level = pb.add(this.level, pb.mul(this.mipInc, 2));
+            for(let j = 0; j < 4; j++){
+                this.$l[`sampleT${j}`] = pb.add(this.marchBase, j + 1);
+                this.$l[`sampleUV${j}`] = pb.add(this.rayUVz.xy, pb.mul(this.rayStepUVz.xy, this[`sampleT${j}`]));
+                this.$l[`sampleZ${j}`] = pb.add(this.rayUVz.z, pb.mul(this.rayStepUVz.z, this[`sampleT${j}`]));
+                // Negative when the ray is behind the surface, hit window (-2T, 0).
+                // Under reverse-Z this is UE's original `SamplesZ - SampleDepth`;
+                // under standard Z the difference is mirrored.
+                this[`diff${j}`] = REVERSE_Z ? pb.sub(this[`sampleZ${j}`], this.SSR_loadDepth(this[`sampleUV${j}`], j < 2 ? this.mip01 : this.mip23)) : pb.sub(this.SSR_loadDepth(this[`sampleUV${j}`], j < 2 ? this.mip01 : this.mip23), this[`sampleZ${j}`]);
+                this[`hit${j}`] = pb.lessThan(pb.abs(pb.add(this[`diff${j}`], this.compareTolerance)), this.compareTolerance);
+                this.foundHit = pb.or(this.foundHit, this[`hit${j}`]);
+                // The ray went far behind geometry before any hit: its outcome
+                // cannot be resolved from the depth buffer (UE bUncertain).
+                this.uncertain = pb.or(this.uncertain, pb.and(pb.lessThan(pb.add(this[`diff${j}`], this.compareTolerance), pb.neg(this.compareTolerance)), pb.not(this.foundHit)));
+            }
+            this.$if(this.foundHit, function() {
+                this.$break();
             });
+            this.lastDiff = this.diff3;
         });
-        this.$return(this.skippedTile);
-    });
-    pb.func('SSR_RaymarchHiZ', [
-        pb.vec3('screenSpacePos'),
-        pb.vec3('screenSpaceDirection'),
-        pb.vec2('cameraNearFar'),
-        pb.vec2('screenSize'),
-        pb.int('mostDetailMip'),
-        pb.int('maxMipLevel'),
-        pb.float('maxIterations'),
-        pb.float('maxT'),
-        pb.float('numIterations').out()
-    ], function() {
-        this.$l.invDirection = pb.vec3(this.$choice(pb.greaterThan(pb.abs(this.screenSpaceDirection.x), 1e-8), pb.div(1, this.screenSpaceDirection.x), MAX_FLOAT_VALUE), this.$choice(pb.greaterThan(pb.abs(this.screenSpaceDirection.y), 1e-8), pb.div(1, this.screenSpaceDirection.y), MAX_FLOAT_VALUE), this.$choice(pb.greaterThan(pb.abs(this.screenSpaceDirection.z), 1e-8), pb.div(1, this.screenSpaceDirection.z), MAX_FLOAT_VALUE));
-        this.$l.currentMip = this.mostDetailMip;
-        this.$l.currentMipResolution = this.getMipResolution(this.currentMip);
-        this.$l.invCurrentMipResolution = pb.div(pb.vec2(1), this.currentMipResolution);
-        this.$l.uvOffset = pb.div(pb.mul(0.005, pb.exp2(pb.float(this.mostDetailMip))), this.screenSize);
-        this.uvOffset = pb.vec2(this.$choice(pb.lessThan(this.screenSpaceDirection.x, 0), pb.neg(this.uvOffset.x), this.uvOffset.x), this.$choice(pb.lessThan(this.screenSpaceDirection.y, 0), pb.neg(this.uvOffset.y), this.uvOffset.y));
-        this.$l.floorOffset = pb.vec2(this.$choice(pb.lessThan(this.screenSpaceDirection.x, 0), pb.float(0), pb.float(1)), this.$choice(pb.lessThan(this.screenSpaceDirection.y, 0), pb.float(0), pb.float(1)));
-        this.$l.currentT = pb.float();
-        this.$l.position = pb.vec3();
-        this.SSR_initialAdvanceRay(this.screenSpacePos, this.screenSpaceDirection, this.invDirection, this.currentMipResolution, this.invCurrentMipResolution, this.floorOffset, this.uvOffset, this.position, this.currentT);
-        this.numIterations = pb.float(0);
-        this.$while(pb.and(pb.and(pb.lessThan(this.numIterations, this.maxIterations), pb.greaterThanEqual(this.currentMip, this.mostDetailMip)), pb.and(pb.lessThanEqual(this.currentT, this.maxT), pb.all(pb.greaterThanEqual(this.position.xy, pb.vec2(0))), pb.all(pb.lessThanEqual(this.position.xy, pb.vec2(1))))), function() {
-            this.$l.currentMipPosition = pb.mul(this.currentMipResolution, this.position.xy);
-            this.$l.depthRange = pb.textureLoad(HiZTexture, pb.ivec2(this.currentMipPosition), this.currentMip).rg;
-            this.$l.skippedTile = this.SSR_advanceRay(this.screenSpacePos, this.screenSpaceDirection, this.invDirection, this.currentMipPosition, this.invCurrentMipResolution, this.floorOffset, this.uvOffset, this.depthRange.x, this.depthRange.y, this.currentMip, this.position, this.currentT);
-            this.$l.nextMipIsOutOfRange = pb.and(this.skippedTile, pb.greaterThanEqual(this.currentMip, this.maxMipLevel));
-            this.$if(pb.not(this.nextMipIsOutOfRange), function() {
-                this.currentMip = pb.add(this.currentMip, this.$choice(this.skippedTile, pb.int(1), pb.int(-1)));
-                this.currentMipResolution = pb.mul(this.currentMipResolution, this.$choice(this.skippedTile, 0.5, 2));
-                this.invCurrentMipResolution = pb.mul(this.invCurrentMipResolution, this.$choice(this.skippedTile, 2, 0.5));
+        this.$if(this.foundHit, function() {
+            // Locate the first hit sample of the batch, then refine with a line
+            // segment intersection (UE: TimeLerp = saturate(D0 / (D0 - D1))).
+            this.$l.depthDiff0 = this.diff2;
+            this.$l.depthDiff1 = this.diff3;
+            this.$l.time0 = pb.float(3);
+            this.$if(this.hit2, function() {
+                this.depthDiff0 = this.diff1;
+                this.depthDiff1 = this.diff2;
+                this.time0 = 2;
             });
-            this.numIterations = pb.add(this.numIterations, 1);
+            this.$if(this.hit1, function() {
+                this.depthDiff0 = this.diff0;
+                this.depthDiff1 = this.diff1;
+                this.time0 = 1;
+            });
+            this.$if(this.hit0, function() {
+                this.depthDiff0 = this.lastDiff;
+                this.depthDiff1 = this.diff0;
+                this.time0 = 0;
+            });
+            this.time0 = pb.add(this.time0, this.marchBase);
+            this.$l.denom = pb.sub(this.depthDiff0, this.depthDiff1);
+            this.$l.timeLerp = this.$choice(pb.greaterThan(pb.abs(this.denom), 1e-20), pb.clamp(pb.div(this.depthDiff0, this.denom), 0, 1), pb.float(0.5));
+            this.$l.intersectTime = pb.add(this.time0, this.timeLerp);
+            this.hitUVz = pb.add(this.rayUVz, pb.mul(this.rayStepUVz, this.intersectTime));
+            this.numIterations = this.intersectTime;
+        }).$else(function() {
+            // No certain intersection - the march covered the whole clipped ray.
+            this.hitUVz = pb.add(this.rayUVz, pb.mul(this.rayStepUVz, this.numSteps));
+            this.numIterations = this.numSteps;
         });
-        this.$l.validHit = this.$choice(pb.and(pb.lessThan(this.currentMip, this.mostDetailMip), pb.and(pb.greaterThanEqual(this.currentT, 0), pb.lessThanEqual(this.currentT, this.maxT))), pb.float(1), pb.float(0));
-        this.$return(pb.vec4(this.position, this.validHit));
     });
-    pb.func('SSR_HiZ', [
+    pb.func(giTraceOut ? 'SSR_HiZ_GI' : 'SSR_HiZ', [
         pb.vec3('viewPos'),
         pb.vec3('traceRay'),
         pb.mat4('viewMatrix'),
@@ -399,44 +543,68 @@ function screenSpaceRayTracing_HiZ(scope, viewPos, traceRay, viewMatrix, projMat
         pb.float('thickness'),
         pb.vec4('textureSize'),
         pb.int('maxMipLevel'),
-        pb.float('maxIterations')
+        pb.float('maxIterations'),
+        pb.float('roughness'),
+        pb.float('stepOffset'),
+        ...giTraceOut ? [
+            pb.vec3('giTrace').out()
+        ] : []
     ], function() {
+        if (giTraceOut) {
+            this.giTrace = pb.vec3(0);
+        }
         this.$l.rayDirection = pb.normalize(this.traceRay);
-        this.$l.reverseRay = pb.greaterThan(this.rayDirection.z, 1e-6);
-        this.$l.rayLength = this.maxDistance;
-        this.$if(this.reverseRay, function() {
-            this.rayLength = pb.min(this.rayLength, pb.div(pb.sub(pb.neg(this.cameraNearFar.x), this.viewPos.z), this.rayDirection.z));
-        });
-        this.$if(pb.lessThanEqual(this.rayLength, 0), function() {
-            this.$return(pb.vec4(0));
-        });
-        this.$l.originH = pb.mul(this.projMatrix, pb.vec4(this.viewPos, 1));
-        this.$l.originCS = pb.div(this.originH.xyz, this.originH.w);
-        this.$l.originTS = pb.add(pb.mul(this.originCS, 0.5), pb.vec3(0.5));
-        this.$l.endTS = this.projectPosition(pb.add(this.viewPos, pb.mul(this.rayDirection, this.rayLength)), this.projMatrix);
-        this.$l.directionTS = this.$choice(this.reverseRay, pb.sub(this.endTS, this.originTS), this.projectDirection(this.viewPos, this.rayDirection, this.originTS, this.projMatrix));
-        this.$l.maxT = this.$choice(this.reverseRay, pb.float(1), pb.float(MAX_FLOAT_VALUE));
-        this.$l.mostDetailMip = pb.int(0);
+        this.$l.rayStartTS = pb.vec3();
+        this.$l.rayStepTS = pb.vec3();
+        this.$l.compareTolerance = pb.float();
+        // UE uses SlopeCompareToleranceScale 4 for SSR and 2 for SSGI.
+        this.SSR_initScreenSpaceRay(this.viewPos, this.rayDirection, this.maxDistance, pb.float(giTraceOut ? 2 : 4), this.projMatrix, this.rayStartTS, this.rayStepTS, this.compareTolerance);
+        this.$l.hitUVz = pb.vec3();
+        this.$l.foundHit = pb.bool();
+        this.$l.uncertain = pb.bool();
         this.$l.numIterations = pb.float();
-        this.$l.hit = this.SSR_RaymarchHiZ(this.originTS, this.directionTS, this.cameraNearFar, this.textureSize.zw, this.mostDetailMip, this.maxMipLevel, this.maxIterations, this.maxT, this.numIterations);
+        this.SSR_castScreenSpaceRay(this.rayStartTS, this.rayStepTS, this.compareTolerance, pb.max(this.maxIterations, 4), this.stepOffset, this.roughness, pb.float(this.maxMipLevel), this.hitUVz, this.foundHit, this.uncertain, this.numIterations);
         this.$l.confidence = pb.float(0);
-        this.$if(pb.notEqual(this.hit.w, 0), function() {
-            this.$l.surfaceZ = pb.textureSampleLevel(HiZTexture, this.hit.xy, 0).r;
-            this.$if(pb.equal(this.surfaceZ, 1), function() {
+        const hitBranch = this.$if(this.foundHit, function() {
+            this.$l.surfaceZ = this.SSR_loadDepth(this.hitUVz.xy, 0);
+            this.$if(ShaderHelper.isFarthestDepth(this, this.surfaceZ), function() {
+                if (giTraceOut) {
+                    // The intersection resolved onto a sky texel, so the ray escaped.
+                    this.giTrace = pb.vec3(0, 1, 0);
+                }
                 this.$return(pb.vec4(0));
             });
-            this.$l.hit3D = invProjectPosition(this, this.hit.xyz, this.invProjMatrix);
-            this.confidence = validateHit(this, this.hit.xy, this.hit3D, this.surfaceZ, this.thickness, this.originTS.xy, this.rayDirection, this.viewMatrix, this.invProjMatrix, this.textureSize, normalTexture);
+            this.$l.hit3D = invProjectPosition(this, this.hitUVz, this.invProjMatrix);
+            this.confidence = validateHit(this, this.hitUVz.xy, this.hit3D, this.surfaceZ, this.thickness, this.rayStartTS.xy, this.rayDirection, this.viewMatrix, this.invProjMatrix, this.textureSize, normalTexture);
+            if (giTraceOut) {
+                // Keep only the thickness term of validateHit: a hit far from the
+                // sampled surface may be a thin-object false positive, which is a
+                // genuine geometric doubt. The border, near-self and backface vetoes
+                // bound reflection artifacts and must not gate diffuse occlusion.
+                this.$l.giSurfaceVS = invProjectPosition(this, pb.vec3(this.hitUVz.xy, this.surfaceZ), this.invProjMatrix);
+                this.$l.giThicknessFade = pb.sub(1, pb.smoothStep(0, this.thickness, pb.distance(this.giSurfaceVS, this.hit3D)));
+                this.giTrace = pb.vec3(1, 0, pb.mul(this.giThicknessFade, this.giThicknessFade));
+            }
         });
+        if (giTraceOut) {
+            hitBranch.$else(function() {
+                // The ray is always extended to the screen border, so a march that
+                // finished without ever going behind geometry is a proven escape.
+                // An uncertain march (went far behind geometry before any hit) is
+                // indeterminate, not unoccluded (UE bUncertain semantics).
+                this.giTrace = pb.vec3(0, pb.float(pb.not(this.uncertain)), 0);
+            });
+        }
         this.$l.iterationAttenuation = pb.sub(1, pb.smoothStep(0, this.maxIterations, this.numIterations));
-        //this.$l.iterationAttenuation = pb.smoothStep(this.maxIterations, 1, this.numIterations);
         this.confidence = pb.mul(this.confidence, this.iterationAttenuation);
-        this.$l.hitPixel = pb.mul(this.hit.xy, this.textureSize.zw);
-        this.$l.startPixel = pb.mul(this.originTS.xy, this.textureSize.zw);
+        this.$l.hitPixel = pb.mul(this.hitUVz.xy, this.textureSize.zw);
+        this.$l.startPixel = pb.mul(this.rayStartTS.xy, this.textureSize.zw);
         this.$l.hitDistance = pb.length(pb.sub(this.hitPixel, this.startPixel));
-        this.$return(pb.vec4(this.hit.xy, this.hitDistance, this.confidence));
+        this.$return(pb.vec4(this.hitUVz.xy, this.hitDistance, this.confidence));
     });
-    return scope.SSR_HiZ(viewPos, traceRay, viewMatrix, projMatrix, invProjMatrix, cameraNearFar, maxDistance, thickness, textureSize, pb.sub(maxMipLevel, 1), maxIterations);
+    const roughnessArg = roughness ?? 0;
+    const stepOffsetArg = stepOffset ?? 0.5;
+    return giTraceOut ? scope.SSR_HiZ_GI(viewPos, traceRay, viewMatrix, projMatrix, invProjMatrix, cameraNearFar, maxDistance, thickness, textureSize, pb.sub(maxMipLevel, 1), maxIterations, roughnessArg, stepOffsetArg, giTraceOut) : scope.SSR_HiZ(viewPos, traceRay, viewMatrix, projMatrix, invProjMatrix, cameraNearFar, maxDistance, thickness, textureSize, pb.sub(maxMipLevel, 1), maxIterations, roughnessArg, stepOffsetArg);
 } /*
 float2 cell(float2 ray, float2 cell_count, uint camera) {
 	return floor(ray.xy * cell_count);
@@ -517,5 +685,5 @@ float3 hi_z_trace(float3 p, float3 v, in uint camera, out uint iterations) {
 }
 */
 
-export { SSR_calcJitter, screenSpaceRayTracing_HiZ, screenSpaceRayTracing_Linear2D };
+export { SSR_calcJitter, SSR_interleavedGradientNoise, screenSpaceRayTracing_HiZ, screenSpaceRayTracing_Linear2D };
 //# sourceMappingURL=ssr.js.map