rayzee 7.11.0 → 7.12.0

package/src/TSL/FinalWriteKernel.js

@@ -4,13 +4,15 @@
 
 import {
 	Fn, wgslFn, float, vec2, vec4, int, uint, uvec2,
-	If, mix, select, texture, textureStore,
+	If, mix, select, texture, textureStore, length, atomicAdd,
 	localId, workgroupId,
 } from 'three/tsl';
 
 import {
 	readRayRadiance, readGBuffer, gbDecodeNormalDepth, gbDecodeAlbedo,
 } from '../Processor/PackedRayBuffer.js';
+import { luminance } from './Common.js';
+import { COUNTER } from '../Processor/QueueManager.js';
 
 const WG_SIZE = 16;
 
@@ -32,15 +34,27 @@ export function buildFinalWriteKernel( params ) {
 		resolution, frame,
 		enableAccumulation, hasPreviousAccumulated, accumulationAlpha, cameraIsMoving,
 		transparentBackground,
-		prevAccumTexture, prevAlbedoTexture,
+		prevAccumTexture, prevAlbedoTexture, prevNormalDepthTexture,
 		renderWidth, renderHeight,
 		visMode,
 		// Aux MRT (normalDepth + albedo) feeds only the denoiser/OIDN. Gated by a live uniform (1 = denoiser
 		// on): when off, skip the G-buffer decode, the prev-frame aux mix, and the two aux stores.
 		auxGBufferEnabled,
+		// Clean-aux normal (1 = temporally accumulate + renormalize the aux normal). On only for clean-aux
+		// OIDN models (calb_cnrm/high, alb_nrm/balanced); off for fast/ASVGF which want the bump normal.
+		cleanAuxNormalEnabled,
+		// Tier-1 convergence early-stop: per-pixel Welford luminance second moment + converged-pixel counter.
+		counters, m2BufferRW, useAdaptiveSampling, noiseThreshold, darkNoiseFloor, adaptiveMinSamples,
+		// Tier-2 per-pixel freeze: streakBufferRW = per-pixel freeze-candidate streak (stamped here);
+		// frozenMaskRO = dilated frozen mask from buildActivePixels (pass-through gates on it, not streak).
+		usePixelFreeze, pixelFreezeThreshold, pixelFreezeStability, streakBufferRW, frozenMaskRO,
 	} = params;
 
 	const auxOn = auxGBufferEnabled.greaterThan( uint( 0 ) );
+	const cleanAuxNormalOn = cleanAuxNormalEnabled.greaterThan( uint( 0 ) );
+	// useAdaptiveSampling is registered via UniformManager.ub() → an int 0/1 uniform, so compare against int(0).
+	const convOn = useAdaptiveSampling.greaterThan( int( 0 ) );
+	const adaptiveOn = usePixelFreeze.greaterThan( int( 0 ) );
 
 	const computeFn = Fn( () => {
 
@@ -56,6 +70,11 @@ export function buildFinalWriteKernel( params ) {
 			const finalColor = sampleColor.xyz.toVar();
 			const outputAlpha = select( transparentBackground, sampleColor.w, float( 1.0 ) ).toVar();
 
+			// A pixel frozen in a prior frame was skipped by Generate, so its rayBuffer sample is stale — pass
+			// the accumulated colour through unchanged (below) instead of mixing it. Inert unless adaptiveOn.
+			const wasFrozen = adaptiveOn.and( frame.greaterThan( uint( 0 ) ) )
+				.and( frozenMaskRO.element( rayID ).equal( uint( 1 ) ) ).toVar();
+
 			// MRT comes from the per-pixel G-buffer (rayID == pixelIndex). Half-packed: decode.
 			// auxOn gates the decode + stores so a no-denoiser frame does no G-buffer read and no aux writes.
 			const finalNormalDepth = vec4( 0.0 ).toVar();
@@ -77,20 +96,103 @@ export function buildFinalWriteKernel( params ) {
 
 				const prevAccumSample = texture( prevAccumTexture, prevUV, 0 ).toVar();
 
-				finalColor.assign( mix( prevAccumSample.xyz, sampleColor.xyz, accumulationAlpha ) );
+				// Frozen pixels pass prev colour through unchanged (stale sample); active pixels accumulate.
+				finalColor.assign( select( wasFrozen, prevAccumSample.xyz, mix( prevAccumSample.xyz, sampleColor.xyz, accumulationAlpha ) ) );
 				If( auxOn, () => {
 
-					// Albedo averages cleanly (it's a colour). The NORMAL must NOT: averaging jittered
-					// unit normals collapses toward the flat geometric mean (worse at distance), which made
-					// OIDN smooth bump detail away. Keep this frame's point-sampled normal — it varies with
-					// the bump, which is exactly what OIDN's edge-stop needs to preserve it.
+					// Albedo averages cleanly (it's a colour).
 					finalAlbedo.assign( mix( texture( prevAlbedoTexture, prevUV, 0 ).xyz, finalAlbedo, accumulationAlpha ) );
 
+					// NORMAL: by default keep this frame's POINT-SAMPLED normal — it varies with the bump,
+					// which fast/ASVGF want to preserve edge detail. But a CLEAN-AUX OIDN model (calb_cnrm/high,
+					// alb_nrm/balanced) trusts the aux and is fed per-frame point-sampled NOISE → leaked noise
+					// (high) / over-smoothing (balanced). When cleanAuxNormalOn, temporally accumulate it like
+					// the colour. Average the RAW unit normals (decode 0.5+0.5 → [-1,1]) and RENORMALIZE — a
+					// plain encoded-space mix would bias toward the flat (0.5,0.5,1) mean and collapse detail.
+					// Depth (.w) stays this frame's value; guard the degenerate near-zero mean (opposing normals).
+					If( cleanAuxNormalOn, () => {
+
+						const prevN = texture( prevNormalDepthTexture, prevUV, 0 ).xyz.mul( 2.0 ).sub( 1.0 );
+						const curN = finalNormalDepth.xyz.mul( 2.0 ).sub( 1.0 ).toVar();
+						const mixedN = mix( prevN, curN, accumulationAlpha ).toVar();
+						const len = length( mixedN );
+						const avgN = select( len.greaterThan( 1e-4 ), mixedN.div( len ), curN );
+						finalNormalDepth.assign( vec4( avgN.mul( 0.5 ).add( 0.5 ), finalNormalDepth.w ) );
+
+					} );
+
 				} );
 
 				If( transparentBackground, () => {
 
-					outputAlpha.assign( mix( prevAccumSample.w, sampleColor.w, accumulationAlpha ) );
+					outputAlpha.assign( select( wasFrozen, prevAccumSample.w, mix( prevAccumSample.w, sampleColor.w, accumulationAlpha ) ) );
+
+				} );
+
+			} );
+
+			// Tier-1 convergence: per-pixel running second moment of LUMINANCE (Welford). luminance() is linear,
+			// so luminance(running-mean color) == running-mean luminance == E[L]; m2 tracks E[L²] under the SAME
+			// global 1/(frame+1) alpha (NO per-pixel alpha). sampleVar = E[L²]-E[L]²; varOfMean = sampleVar/(N);
+			// relErr = SE(mean)/mean. A pixel counts as converged once frame>=minSamples AND relErr<threshold.
+			// The m2 write runs every frame (incl. frame 0, where alpha==1 self-inits it → no explicit clear).
+			// Sits AFTER the accumulation mix (finalColor is the mean) and BEFORE the visMode-11 mutation.
+			If( convOn, () => {
+
+				const sampleLum = luminance( sampleColor.xyz );
+				const prevM2 = m2BufferRW.element( rayID ).toVar();
+				const m2 = mix( prevM2, sampleLum.mul( sampleLum ), accumulationAlpha ).toVar();
+				m2BufferRW.element( rayID ).assign( m2 );
+
+				const meanLum = luminance( finalColor ).toVar();
+				const sampleVar = m2.sub( meanLum.mul( meanLum ) ).max( float( 0 ) );
+				const varOfMean = sampleVar.div( float( frame ).add( 1.0 ) );
+				// absSE = absolute standard error of the mean luminance; relErr = its ratio to the mean.
+				// Combined criterion: bright pixels converge on relErr<threshold; dark/dim pixels (where relErr
+				// stays high forever) converge on absSE<absFloor, since their absolute noise is imperceptible.
+				const absSE = varOfMean.sqrt().toVar();
+				const relErr = absSE.div( meanLum.add( float( 1e-4 ) ) );
+
+				If( frame.greaterThanEqual( uint( adaptiveMinSamples ) ).and(
+					relErr.lessThan( noiseThreshold ).or( absSE.lessThan( darkNoiseFloor ) )
+				), () => {
+
+					atomicAdd( counters.element( uint( COUNTER.CONVERGED_COUNT ) ), uint( 1 ) );
+
+				} );
+
+				// Maintain the freeze streak on the relErr-only predicate (NO absFloor — it bakes dim regions dark
+				// when it permanently freezes a pixel). Monotonic: streak>=K freezes for the run, so global alpha stays exact.
+				If( adaptiveOn, () => {
+
+					If( frame.equal( uint( 0 ) ), () => {
+
+						// Frame 0 (post-reset/camera-move) clears the frozen state so each run re-freezes fresh.
+						streakBufferRW.element( rayID ).assign( uint( 0 ) );
+
+					} );
+
+					If( wasFrozen, () => {
+
+						// Already frozen (passed through above) — count it.
+						atomicAdd( counters.element( uint( COUNTER.FROZEN_COUNT ) ), uint( 1 ) );
+
+					} );
+
+					If( wasFrozen.not().and( frame.greaterThan( uint( 0 ) ) ), () => {
+
+						const freezeCandidate = frame.greaterThanEqual( uint( adaptiveMinSamples ) )
+							.and( relErr.lessThan( pixelFreezeThreshold ) );
+						const newStreak = select( freezeCandidate, streakBufferRW.element( rayID ).add( uint( 1 ) ), uint( 0 ) ).toVar();
+						streakBufferRW.element( rayID ).assign( newStreak );
+						// Just reached K → frozen next frame; count it now so the frozen population is current.
+						If( newStreak.greaterThanEqual( uint( pixelFreezeStability ) ), () => {
+
+							atomicAdd( counters.element( uint( COUNTER.FROZEN_COUNT ) ), uint( 1 ) );
+
+						} );
+
+					} );
 
 				} );
 

package/src/TSL/GenerateKernel.js

@@ -1,10 +1,12 @@
 /**
- * GenerateKernel.js — wavefront primary ray generation (16×16, 2D screen-space dispatch).
+ * GenerateKernel.js — wavefront primary ray generation.
+ * Two dispatch modes from one builder: 2D screen-space (default) and 1D list-driven over the active-pixel
+ * list (Tier-2 per-pixel freeze).
  */
 
 import {
 	Fn, float, vec2, vec3, vec4, int, uint,
-	If, select,
+	If, select, instanceIndex, atomicLoad,
 	localId, workgroupId,
 } from 'three/tsl';
 
@@ -16,7 +18,7 @@ import {
 
 import { generateRayFromCamera } from './BVHTraversal.js';
 import { Ray } from './Struct.js';
-import { RAY_FLAG } from '../Processor/QueueManager.js';
+import { RAY_FLAG, COUNTER } from '../Processor/QueueManager.js';
 import {
 	writeRayOriginMeta, writeRayDirFlags, writeRayThroughputPdf,
 	writeRayRadiance, writeGBuffer,
@@ -36,68 +38,94 @@ export function buildGenerateKernel( params ) {
 		transmissiveBounces, // per-ray refraction budget (megakernel parity: PathTracerCore.js:606)
 		transparentBackground, // alpha inits to 1 here (megakernel parity: PathTracerCore.js:554) — env-escape-without-opaque zeroes it in Shade
 		auxGBufferEnabled, // live uniform: 1 = init the per-pixel G-buffer (denoiser on), 0 = skip it
+		// listDriven: 1D dispatch over the active-pixel list (activeIndicesRO[tid] = pixelID) instead of 2D.
+		listDriven = false, activeIndicesRO = null, counters = null,
 	} = params;
 
 	const auxOn = auxGBufferEnabled.greaterThan( uint( 0 ) );
 
-	const computeFn = Fn( () => {
+	// Shared ray-gen body for a pixel (gx, gy) — identical in both dispatch modes.
+	const emitRay = ( gx, gy ) => {
+
+		const pixelCoord = vec2( float( gx ).add( 0.5 ), float( gy ).add( 0.5 ) );
+		const pixelIndex = gy.mul( int( resolution.x ) ).add( gx );
+		// One ray per pixel: rayID is the pixel index.
+		const rayID = uint( pixelIndex );
+
+		const screenPosition = pixelCoord.div( resolution ).mul( 2.0 ).sub( 1.0 ).toVar();
+		screenPosition.y.assign( screenPosition.y.negate() );
+
+		const baseSeed = getDecorrelatedSeed( { pixelCoord, rayIndex: int( 0 ), frame } ).toVar();
+		const seed = pcgHash( { state: baseSeed } ).toVar();
+
+		// Sample index 1 (not 0) so the AA sub-pixel jitter draws a DIFFERENT STBN cell
+		// than the first-bounce BSDF sample (ShadeKernel uses sampleIndex 0). Every bounce
+		// samples at index 0, so index 1 is collision-free — this decorrelates the sub-pixel
+		// position from the first scatter direction (they were reading the identical cell).
+		const stratifiedJitter = getStratifiedSample( pixelCoord, int( 1 ), int( 1 ), seed, resolution, frame ).toVar();
+
+		const jitterScale = vec2( 2.0 ).div( resolution );
+		const jitter = stratifiedJitter.sub( 0.5 ).mul( jitterScale );
+		const jitteredScreenPosition = screenPosition.add( jitter );
+
+		const ray = Ray.wrap( generateRayFromCamera(
+			jitteredScreenPosition, seed,
+			cameraWorldMatrix, cameraProjectionMatrixInverse,
+			enableDOF, focalLength, aperture, focusDistance, sceneScale, apertureScale, anamorphicRatio,
+		) );
+
+		writeRayOriginMeta( rayBufferRW, rayID, ray.origin, int( 0 ), int( 0 ) );
+		// A fresh camera ray is NOT redirected — REDIRECTED stays clear so it sees the direct backdrop;
+		// ShadeKernel sets REDIRECTED on the first direction-changing interaction (see RAY_FLAG.REDIRECTED).
+		writeRayDirFlags( rayBufferRW, rayID, ray.direction, uint( RAY_FLAG.ACTIVE ) );
+		// pdf inits to 0 = prevBouncePdf (megakernel parity PathTracerCore.js:556). The bounce>0 env/emissive
+		// MIS gate skips until an opaque scatter writes a real combinedPdf; free bounces preserve it.
+		writeRayThroughputPdf( rayBufferRW, rayID, vec4( 1.0, 1.0, 1.0, 0.0 ).xyz, float( 0.0 ) );
+		// Alpha inits to 1 in transparent-bg mode (megakernel parity: PathTracerCore.js:554). Shade zeroes
+		// it only on env-escape-without-opaque; a ray that dies inside geometry (e.g. SSS walk termination)
+		// keeps alpha 1 → solid. Non-transparent mode is inert (FinalWrite forces alpha 1).
+		writeRayRadiance( rayBufferRW, rayID, vec4( vec3( 0.0 ), select( transparentBackground, float( 1.0 ), float( 0.0 ) ) ) );
+
+		If( auxOn, () => {
+
+			// default: normal +Z, depth 1 (far), black albedo (background/miss)
+			writeGBuffer( gBufferRW, uint( pixelIndex ), vec3( 0.0, 0.0, 1.0 ), float( 1.0 ), vec3( 0.0 ) );
 
-		const gx = int( workgroupId.x ).mul( WG_SIZE ).add( int( localId.x ) );
-		const gy = int( workgroupId.y ).mul( WG_SIZE ).add( int( localId.y ) );
+		} );
 
-		If( gx.lessThan( renderWidth ).and( gy.lessThan( renderHeight ) ), () => {
+		writeMediumStack( rayBufferRW, rayID, uint( 0 ), uint( transmissiveBounces ), float( 1.0 ), float( 1.0 ), float( 1.0 ) );
 
-			const pixelCoord = vec2( float( gx ).add( 0.5 ), float( gy ).add( 0.5 ) );
-			const pixelIndex = gy.mul( int( resolution.x ) ).add( gx );
-			// One ray per pixel: rayID is the pixel index.
-			const rayID = uint( pixelIndex );
+		rngBufferRW.element( rayID ).assign( seed );
 
-			const screenPosition = pixelCoord.div( resolution ).mul( 2.0 ).sub( 1.0 ).toVar();
-			screenPosition.y.assign( screenPosition.y.negate() );
+	};
 
-			const baseSeed = getDecorrelatedSeed( { pixelCoord, rayIndex: int( 0 ), frame } ).toVar();
-			const seed = pcgHash( { state: baseSeed } ).toVar();
+	const computeFn = Fn( () => {
 
-			// Sample index 1 (not 0) so the AA sub-pixel jitter draws a DIFFERENT STBN cell
-			// than the first-bounce BSDF sample (ShadeKernel uses sampleIndex 0). Every bounce
-			// samples at index 0, so index 1 is collision-free — this decorrelates the sub-pixel
-			// position from the first scatter direction (they were reading the identical cell).
-			const stratifiedJitter = getStratifiedSample( pixelCoord, int( 1 ), int( 1 ), seed, resolution, frame ).toVar();
+		if ( listDriven ) {
 
-			const jitterScale = vec2( 2.0 ).div( resolution );
-			const jitter = stratifiedJitter.sub( 0.5 ).mul( jitterScale );
-			const jitteredScreenPosition = screenPosition.add( jitter );
+			const tid = instanceIndex;
+			// Grid is over-sized from a stale readback; bound on the live ENTERING_COUNT so extra threads no-op.
+			If( tid.lessThan( atomicLoad( counters.element( uint( COUNTER.ENTERING_COUNT ) ) ) ), () => {
 
-			const ray = Ray.wrap( generateRayFromCamera(
-				jitteredScreenPosition, seed,
-				cameraWorldMatrix, cameraProjectionMatrixInverse,
-				enableDOF, focalLength, aperture, focusDistance, sceneScale, apertureScale, anamorphicRatio,
-			) );
+				const pixelIndex = int( activeIndicesRO.element( tid ) );
+				const gx = pixelIndex.mod( int( resolution.x ) );
+				const gy = pixelIndex.div( int( resolution.x ) );
+				emitRay( gx, gy );
 
-			writeRayOriginMeta( rayBufferRW, rayID, ray.origin, int( 0 ), int( 0 ) );
-			// A fresh camera ray is NOT redirected — REDIRECTED stays clear so it sees the direct backdrop;
-			// ShadeKernel sets REDIRECTED on the first direction-changing interaction (see RAY_FLAG.REDIRECTED).
-			writeRayDirFlags( rayBufferRW, rayID, ray.direction, uint( RAY_FLAG.ACTIVE ) );
-			// pdf inits to 0 = prevBouncePdf (megakernel parity PathTracerCore.js:556). The bounce>0 env/emissive
-			// MIS gate skips until an opaque scatter writes a real combinedPdf; free bounces preserve it.
-			writeRayThroughputPdf( rayBufferRW, rayID, vec4( 1.0, 1.0, 1.0, 0.0 ).xyz, float( 0.0 ) );
-			// Alpha inits to 1 in transparent-bg mode (megakernel parity: PathTracerCore.js:554). Shade zeroes
-			// it only on env-escape-without-opaque; a ray that dies inside geometry (e.g. SSS walk termination)
-			// keeps alpha 1 → solid. Non-transparent mode is inert (FinalWrite forces alpha 1).
-			writeRayRadiance( rayBufferRW, rayID, vec4( vec3( 0.0 ), select( transparentBackground, float( 1.0 ), float( 0.0 ) ) ) );
+			} );
 
-			If( auxOn, () => {
+		} else {
 
-				// default: normal +Z, depth 1 (far), black albedo (background/miss)
-				writeGBuffer( gBufferRW, uint( pixelIndex ), vec3( 0.0, 0.0, 1.0 ), float( 1.0 ), vec3( 0.0 ) );
+			const gx = int( workgroupId.x ).mul( WG_SIZE ).add( int( localId.x ) );
+			const gy = int( workgroupId.y ).mul( WG_SIZE ).add( int( localId.y ) );
 
-			} );
+			If( gx.lessThan( renderWidth ).and( gy.lessThan( renderHeight ) ), () => {
 
-			writeMediumStack( rayBufferRW, rayID, uint( 0 ), uint( transmissiveBounces ), float( 1.0 ), float( 1.0 ), float( 1.0 ) );
+				emitRay( gx, gy );
 
-			rngBufferRW.element( rayID ).assign( seed );
+			} );
 
-		} );
+		}
 
 	} );
 

package/src/TSL/ShadeKernel.js

@@ -10,7 +10,7 @@ import {
 	If, Loop, normalize, max, exp, log, clamp, dot, length, select,
 	instanceIndex,
 	sampler,
-	atomicAdd, atomicLoad, uintBitsToFloat,
+	atomicAdd, atomicLoad, atomicStore, uintBitsToFloat,
 	Return,
 } from 'three/tsl';
 
@@ -54,7 +54,7 @@ import {
 	readHitDistance, readHitBarycentrics, readHitNormal,
 	readHitMaterialIndex, readHitTriangleIndex,
 	writeRayOriginMeta, writeRayDirFlags, writeRayThroughputPdf, writeRayRadiance,
-	writeGBuffer, readGBuffer, gbDecodeNormalDepth,
+	writeGBuffer, readGBuffer, gbDecodeNormalDepth, gbDecodeAlbedo,
 	readRayRadiance,
 } from '../Processor/PackedRayBuffer.js';
 
@@ -137,6 +137,19 @@ export function buildShadeKernel( params ) {
 
 		const threadIdx = instanceIndex;
 
+		// Folds the former resetActiveCounter 1-thread kernel: thread 0 zeroes the survivor counter
+		// before compact re-counts it. Kept ABOVE the ENTERING_COUNT guard so it fires even at bound 0.
+		// Safe: shade never touches ACTIVE_RAY_COUNT, and the shade→compact dispatch boundary publishes it.
+		if ( counters ) {
+
+			If( threadIdx.equal( uint( 0 ) ), () => {
+
+				atomicStore( counters.element( uint( COUNTER.ACTIVE_RAY_COUNT ) ), uint( 0 ) );
+
+			} );
+
+		}
+
 		// bound on ENTERING_COUNT so an over-sized margin dispatch is safe
 		const bound = counters ? atomicLoad( counters.element( uint( COUNTER.ENTERING_COUNT ) ) ) : maxRayCount;
 		If( threadIdx.greaterThanEqual( bound ), () => {
@@ -320,6 +333,11 @@ export function buildShadeKernel( params ) {
 			const wantBackdrop = isBackdropView.and( showBackground ); // draw env image as backdrop
 			const wantEnvLight = isBackdropView.not().and( enableEnvironmentLight ); // env as light on redirected bounces
 
+			// Fix ①: OIDN clean-aux for a redirected ray that escapes to the environment (e.g. smooth
+			// glass over sky). Holds the clamped env colour this ray sees; written into the aux G-buffer
+			// before the miss Return below, but only when the pixel still carries the black bounce-0 default.
+			const escapedAuxAlbedo = vec3( 0.0 ).toVar();
+
 			If( wantBackdrop.or( wantEnvLight ), () => {
 
 				// Ground projection bends the backdrop-view env lookup onto a projected sphere+disk so the lower
@@ -358,6 +376,10 @@ export function buildShadeKernel( params ) {
 
 				} );
 
+				// Fix ①: remember the (clamped) env colour this escaped ray sees, so a redirected ray
+				// that never captured a surface aux can feed OIDN a meaningful albedo below.
+				escapedAuxAlbedo.assign( clamp( envColor, vec3( 0.0 ), vec3( 1.0 ) ) );
+
 				// MIS weight for implicit env hit — prevents double-counting with NEE
 				const envMisWeight = float( 1.0 ).toVar();
 				If( isBackdropView.not().and( useEnvMapIS ), () => {
@@ -425,6 +447,25 @@ export function buildShadeKernel( params ) {
 
 			} );
 
+			// Fix ①: fill the black bounce-0 default aux for a redirected ray that reached the
+			// environment without ever locking a surface guide (smooth glass / specular transmission
+			// over sky). Only when the stored albedo is still the black default (dot < 1e-4), so a real
+			// specular-surface aux written upstream is never clobbered. Normal = the escaped ray
+			// direction (varies per pixel → OIDN sees structure that tracks the refracted view);
+			// albedo = the clamped env colour it sees; depth kept at the primary hit.
+			If( auxOn
+				.and( flags.bitAnd( uint( RAY_FLAG.AUX_LOCKED ) ).equal( uint( 0 ) ) )
+				.and( flags.bitAnd( uint( RAY_FLAG.REDIRECTED ) ).notEqual( uint( 0 ) ) ), () => {
+
+				const gPrev = readGBuffer( gBufferRW, pixelIndex );
+				If( dot( gbDecodeAlbedo( gPrev ), vec3( 1.0 ) ).lessThan( float( 1e-4 ) ), () => {
+
+					writeGBuffer( gBufferRW, pixelIndex, normalize( direction ), gbDecodeNormalDepth( gPrev ).w, escapedAuxAlbedo );
+
+				} );
+
+			} );
+
 			writeRayRadiance( rayBufferRW, rayID, currentRadiance );
 			writeRayDirFlags( rayBufferRW, rayID, direction, flags.bitAnd( uint( ~ RAY_FLAG.ACTIVE ) ) );
 			Return();
@@ -607,7 +648,23 @@ export function buildShadeKernel( params ) {
 			// (aux-extend) and may extend through specular surfaces (gap #9). Glass rays Return at the transparency
 			// block before that capture, so a glass-then-escape pixel keeps this default aux — megakernel parity
 			// (objectNormal/objectColor stay at their init for transmissive-then-miss).
-			writeGBuffer( gBufferRW, pixelIndex, vec3( 0.0, 0.0, 1.0 ), linearDepth, vec3( 0.0 ) );
+			//
+			// Fix ③: BLEND (semi-transparent) glass instead LOCKS its OWN normal + albedo here. Its per-frame
+			// stochastic alpha-skip-vs-opaque-shade outcome (MaterialTransmission.js:522-540) otherwise writes a
+			// DIFFERENT surface into the aux each frame (wall-behind on skip vs glass on opaque); with the normal
+			// not temporally averaged that becomes the speckle OIDN smears on — the visible artefact on
+			// alpha-transparent glass. A deterministic glass-surface guide every frame removes it. MASK / opaque
+			// materials keep the default + rely on the downstream aux-extend.
+			If( material.alphaMode.equal( int( 2 ) ), () => {
+
+				writeGBuffer( gBufferRW, pixelIndex, N, linearDepth, albedo.xyz );
+				flags.assign( flags.bitOr( uint( RAY_FLAG.AUX_LOCKED ) ) );
+
+			} ).Else( () => {
+
+				writeGBuffer( gBufferRW, pixelIndex, vec3( 0.0, 0.0, 1.0 ), linearDepth, vec3( 0.0 ) );
+
+			} );
 
 		} );
 
@@ -744,6 +801,26 @@ export function buildShadeKernel( params ) {
 
 			throughput.mulAssign( interaction.throughput );
 
+			// Fix ②: OIDN clean-aux for STOCHASTIC glass (rough / frosted / dispersive), whose refracted
+			// ray hits a different behind-surface every frame. Extending aux through it (the aux-extend on
+			// the opaque-hit path) captures that per-frame surface — albedo then temporally averaged, normal
+			// point-sampled — an inconsistent guide OIDN smears on. Instead lock the glass surface's OWN
+			// normal + tint here (deterministic, spatially coherent). Smooth non-dispersive glass is left
+			// alone: its refraction is a per-pixel delta, so the behind-surface aux captured downstream is
+			// already stable. Gated to a genuine dielectric event (not alpha-cutout passthrough or SSS).
+			If( auxOn
+				.and( flags.bitAnd( uint( RAY_FLAG.AUX_LOCKED ) ).equal( uint( 0 ) ) )
+				.and( interaction.isTransmissive )
+				.and( interaction.isAlphaSkip.not() )
+				.and( interaction.isSubsurface.not() )
+				.and( material.roughness.greaterThan( 0.05 ).or( material.dispersion.greaterThan( 0.0 ) ) ), () => {
+
+				const primaryDepth = gbDecodeNormalDepth( readGBuffer( gBufferRW, pixelIndex ) ).w;
+				writeGBuffer( gBufferRW, pixelIndex, N, primaryDepth, albedo.xyz );
+				flags.assign( flags.bitOr( uint( RAY_FLAG.AUX_LOCKED ) ) );
+
+			} );
+
 			// reflection stays on same side, transmission pushes through
 			const reflectOffsetDir = select( interaction.entering, N, N.negate() );
 			const offsetDir = select( interaction.didReflect, reflectOffsetDir, direction );

package/src/managers/DenoisingManager.js

@@ -368,6 +368,10 @@ export class DenoisingManager extends EventDispatcher {
 		// MRT read-targets directly). When none are active the wavefront skips those writes entirely.
 		s.pathTracer?.setAuxGBufferEnabled?.( normalNeeded || !! this.denoiser?.enabled );
 
+		// Clean-aux normal: temporally accumulate the aux normal only for OIDN clean-aux models
+		// (balanced/high). 'fast' and the real-time denoisers keep the point-sampled bump normal.
+		s.pathTracer?.setCleanAuxNormal?.( !! this.denoiser?.enabled && this.denoiser?.quality !== 'fast' );
+
 		// Reclaim VRAM: free the big 2048² StorageTextures of any denoiser/G-buffer stage that ended up
 		// disabled (lazily re-created on the next dispatch after re-enable). Every strategy/denoiser
 		// toggle funnels through here after the enabled flags above are settled, so this is the one
@@ -610,6 +614,8 @@ export class DenoisingManager extends EventDispatcher {
 	setOIDNQuality( quality ) {
 
 		this.denoiser?.updateQuality( quality );
+		// Clean-aux normal follows the model: balanced/high (clean-aux models) → accumulate; fast → keep bump.
+		this._stages.pathTracer?.setCleanAuxNormal?.( !! this.denoiser?.enabled && quality !== 'fast' );
 
 	}
 

package/src/managers/UniformManager.js

@@ -167,6 +167,21 @@ export class UniformManager {
 		u( 'visMode', DEFAULT_STATE.debugMode, 'int' );
 		u( 'debugVisScale', DEFAULT_STATE.debugVisScale, 'float' );
 
+		// Tier-1 convergence early-stop (FinalWrite reads these; live-toggled, no shader rebuild)
+		ub( 'useAdaptiveSampling', DEFAULT_STATE.useAdaptiveSampling );
+		u( 'noiseThreshold', DEFAULT_STATE.noiseThreshold, 'float' );
+		u( 'darkNoiseFloor', DEFAULT_STATE.darkNoiseFloor, 'float' );
+		u( 'adaptiveMinSamples', DEFAULT_STATE.adaptiveMinSamples, 'int' );
+		// CPU-only (read in PathTracer._isConvergedComplete, not bound to any kernel); registered here for
+		// the settings/configureForMode plumbing + the _defineUniformGetters accessor.
+		u( 'adaptiveStopFraction', DEFAULT_STATE.adaptiveStopFraction, 'float' );
+
+		// Tier-2 per-pixel freeze. usePixelFreeze gates both FinalWrite (stamp + pass-through) and render()'s
+		// frozen-compaction dispatch path.
+		ub( 'usePixelFreeze', DEFAULT_STATE.usePixelFreeze );
+		u( 'pixelFreezeThreshold', DEFAULT_STATE.pixelFreezeThreshold, 'float' );
+		u( 'pixelFreezeStability', DEFAULT_STATE.pixelFreezeStability, 'int' );
+
 		// Accumulation
 		ub( 'enableAccumulation', true );
 		u( 'accumulationAlpha', 0.0, 'float' );