rayzee 7.22.5 → 7.22.7

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "rayzee",
-  "version": "7.22.5",
+  "version": "7.22.7",
   "type": "module",
   "description": "Real-time WebGPU path tracing engine built on Three.js",
   "main": "dist/rayzee.umd.js",

package/src/PathTracerApp.js

@@ -442,16 +442,7 @@ export class PathTracerApp extends EventDispatcher {
 
 		}
 
-		// Abort post-processing and restore denoiser canvas resolution
-		this.denoisingManager?.abort( this.canvas );
-
-		if ( this.denoisingManager?.restoreBaseResolution() ) {
-
-			const w = this.denoisingManager._lastRenderWidth;
-			const h = this.denoisingManager._lastRenderHeight;
-			this.dispatchEvent( { type: 'resolution_changed', width: w, height: h } );
-
-		}
+		this._abortPostProcess();
 
 		this.completion.reset();
 		this.wake();
@@ -1524,6 +1515,37 @@ export class PathTracerApp extends EventDispatcher {
 
 	}
 
+	// Aborts any in-flight denoise/upscale and puts the denoiser canvas back at base resolution (the
+	// upscaler leaves it enlarged), so the live canvas is what's on screen again.
+	_abortPostProcess() {
+
+		this.denoisingManager?.abort( this.canvas );
+
+		if ( this.denoisingManager?.restoreBaseResolution() ) {
+
+			const w = this.denoisingManager._lastRenderWidth;
+			const h = this.denoisingManager._lastRenderHeight;
+			this.dispatchEvent( { type: 'resolution_changed', width: w, height: h } );
+
+		}
+
+	}
+
+	/**
+	 * Re-runs the post-process chain (OIDN → upscaler) against the accumulated image. The chain fires once,
+	 * on the frame the render completes, so a denoiser switched on afterwards would otherwise never run.
+	 */
+	requestPostProcessRefresh() {
+
+		if ( ! this.stages.pathTracer?.isReady || this._deviceLost ) return;
+
+		this._abortPostProcess();
+
+		this.completion.renderCompleteDispatched = false;
+		this.wake();
+
+	}
+
 	// ═══════════════════════════════════════════════════════════════
 	// Deterministic / headless control
 	// ═══════════════════════════════════════════════════════════════
@@ -2408,6 +2430,7 @@ export class PathTracerApp extends EventDispatcher {
 
 		this.denoisingManager.setOverlayManager( this.overlayManager );
 		this.denoisingManager.setResetCallback( () => this.reset() );
+		this.denoisingManager.setPostProcessRefreshCallback( () => this.requestPostProcessRefresh() );
 		this.denoisingManager.setSettings( this.settings );
 
 		// Expose environment manager (lives on pathTracer stage)

package/src/Stages/EdgeFilter.js

@@ -18,6 +18,9 @@ const MISS_THRESHOLD = 6e4;
 const sanitize1 = ( x ) => select( x.equal( x ), x, float( 0.0 ) ).clamp( 0.0, 1e7 );
 const sanitizeRGB = ( c ) => vec3( sanitize1( c.x ), sanitize1( c.y ), sanitize1( c.z ) );
 
+// Frames before the temporal EMA variance is trusted on its own (Schied 2017 §4.2).
+const VARIANCE_HISTORY_MIN = 4;
+
 // 5×5 à-trous kernel weights (B3-spline / Gaussian approx, Σ = 1.0).
 const ATROUS_KERNEL = [
 	1.0 / 256.0, 4.0 / 256.0, 6.0 / 256.0, 4.0 / 256.0, 1.0 / 256.0,
@@ -66,7 +69,9 @@ export class EdgeFilter extends RenderStage {
 		// phiNormal:    normal cone exponent (bigger = tighter, preserves more edges).
 		// phiDepth:     RELATIVE depth tolerance (fraction of ray distance, scale-invariant).
 		this.filterStrength = uniform( options.filterStrength ?? 1.0 );
-		this.phiLuminance = uniform( options.phiLuminance ?? 4.0 );
+		// 1.0, not the old 4.0, which was tuned against the non-converging variance seed below
+		// and now over-blurs enough to lose to no denoising at all from ~16spp up.
+		this.phiLuminance = uniform( options.phiLuminance ?? 1.0 );
 		this.phiNormal = uniform( options.phiNormal ?? 64.0 );
 		this.phiDepth = uniform( options.phiDepth ?? 0.1 );
 		this.iterations = options.atrousIterations ?? options.edgeAtrousIterations ?? 5;
@@ -75,6 +80,7 @@ export class EdgeFilter extends RenderStage {
 		this.isLastIterationU = uniform( 0, 'int' );
 		// 1 on pass 0 → seed variance from variance:output; later passes read the carried value.
 		this.isFirstIterationU = uniform( 1, 'int' );
+		this.varianceHistoryU = uniform( 0, 'int' );
 		this.resW = uniform( options.width || 1 );
 		this.resH = uniform( options.height || 1 );
 
@@ -205,6 +211,7 @@ export class EdgeFilter extends RenderStage {
 		const stepSize = this.stepSizeU;
 		const isLastIterationU = this.isLastIterationU;
 		const isFirstIterationU = this.isFirstIterationU;
+		const varianceHistoryU = this.varianceHistoryU;
 		const resW = this.resW;
 		const resH = this.resH;
 
@@ -233,19 +240,23 @@ export class EdgeFilter extends RenderStage {
 				const demodAlbedo = select( centerIsHitBool, max( centerAlbedo, vec3( ALBEDO_EPS ) ), vec3( 1.0 ) );
 				const centerAlbedoLum = max( luminance( demodAlbedo ), float( ALBEDO_EPS ) );
 
-				// Variance-guided luminance σ (SVGF). .z = temporal, .w = spatial variance;
-				// max() falls back to the spatial estimate as temporal collapses on a
-				// converging accumulation buffer. Dividing by albedoLum rescales the
-				// modulated-space variance into demodulated space (std ∝ 1/albedo).
+				// Variance-guided luminance σ (SVGF). .z = temporal, .w = spatial variance.
+				// Temporal only, once the EMA is warm: .w is the 3×3 contrast of the
+				// *accumulated* image, so it plateaus at scene detail instead of decaying with
+				// sample count. max()-ing it in pinned sigma_l wide forever, which left the
+				// geometric gates — binary reads off the jitter-free G-buffer — to snap every
+				// antialiased silhouette pixel to one side, destroying sub-pixel AA.
 				//
-				// Filtered alongside colour and carried between passes as √variance in the
-				// ping-pong's spare alpha, so sigma_l tightens as the signal smooths. Stored as
-				// the root because converged variance (~1e-6) is a half-float subnormal.
+				// Dividing by albedoLum rescales the modulated-space variance into demodulated
+				// space (std ∝ 1/albedo). Filtered alongside colour and carried between passes
+				// as √variance in the ping-pong's spare alpha, so sigma_l tightens as the signal
+				// smooths. Stored as the root because converged variance is a half-float subnormal.
 				const isFirst = isFirstIterationU.equal( int( 1 ) );
+				const historyShort = varianceHistoryU.lessThan( int( VARIANCE_HISTORY_MIN ) );
 				const seedVariance = ( at ) => {
 
 					const v = textureLoad( varTex, at );
-					return max( v.z, v.w );
+					return select( historyShort, max( v.z, v.w ), v.z );
 
 				};
 
@@ -383,6 +394,8 @@ export class EdgeFilter extends RenderStage {
 
 		}
 
+		this.varianceHistoryU.value = context.getState( 'accumulatedFrames' ) ?? 0;
+
 		this._colorTexNode.value = colorTex;
 		this._ndTexNode.value = ndTex;
 		this._snTexNode.value = snTex;

package/src/Stages/PathTracer.js

@@ -68,6 +68,10 @@ export class PathTracer extends PathTracerStage {
 		// of the point-sampled per-frame value that leaks noise. Off for fast/ASVGF (they want the bump normal).
 		this._cleanAuxNormalEnabled = false;
 		this._cleanAuxNormalUniform = uniform( 0, 'uint' );
+		// Aux MRT accumulates on an epoch of its own: enabling the denoiser at colour frame N must not leave
+		// the stale aux pinned by the colour's 1/(N+1) alpha.
+		this._auxSamples = 0;
+		this._auxSeedPending = false;
 
 		// CPU sizes per-bounce kernels from last frame's survivor curve; kernels bound on ENTERING_COUNT so over-sizing is safe. (indirect dispatch not viable — three.js doesn't sync compute-written indirect buffers across submissions)
 		this._useDynamicDispatch = true;
@@ -238,8 +242,17 @@ export class PathTracer extends PathTracerStage {
 
 		if ( this.isComplete || this.frameCount >= this.completionThreshold || this._isConvergedComplete() ) {
 
-			if ( ! this.isComplete ) this.isComplete = true;
-			return;
+			// Denoiser switched on after the render finished — spend one more frame to fill the aux MRT.
+			if ( this._auxSeedPending ) {
+
+				this.isComplete = false;
+
+			} else {
+
+				if ( ! this.isComplete ) this.isComplete = true;
+				return;
+
+			}
 
 		}
 
@@ -283,6 +296,7 @@ export class PathTracer extends PathTracerStage {
 		}
 
 		this._updateAccumulationUniforms( frameValue, renderMode );
+		const auxMixes = this._updateAuxAccumulationUniforms( frameValue );
 		this.frame.value = frameValue;
 		this.seedFrame.value = this._seedTick ++;
 
@@ -354,7 +368,8 @@ export class PathTracer extends PathTracerStage {
 
 			// Tier-2 bounce-0 grid size from the stale settled active-pixel count (single-chunk only; else full).
 			// Monotonic freeze ⇒ a stale count is a safe over-estimate; reset/camera-move → _curveSizingValid=false.
-			const adaptiveFreeze = this.usePixelFreeze.value > 0;
+			// An aux seed frame must trace every pixel: Generate/Shade skip the G-buffer for frozen ones.
+			const adaptiveFreeze = this.usePixelFreeze.value > 0 && ! this._auxSeedPending;
 			const activeBounce0 = ( singleChunk && adaptiveFreeze && this._curveSizingValid && this._lastActivePixelCount > 0 )
 				? this._lastActivePixelCount : maxRays;
 
@@ -488,6 +503,9 @@ export class PathTracer extends PathTracerStage {
 		// Don't count interaction-mode (1-SPP feedback) frames toward completion (megakernel parity Stages/PathTracer.js:1240) — else a continuous orbit "completes" on noise.
 		if ( ! this.cameraOptimizer?.isInInteractionMode() ) this.frameCount ++;
 
+		if ( this._auxGBufferEnabled ) this._auxSamples = auxMixes ? this._auxSamples + 1 : 1;
+		this._auxSeedPending = false;
+
 		if ( originalMaxBounces !== null ) this.maxBounces.value = originalMaxBounces;
 
 		this.performanceMonitor?.end();
@@ -518,6 +536,8 @@ export class PathTracer extends PathTracerStage {
 		this._convergedFraction = 0;
 		this._convergedGeometryFraction = 0;
 		this._lastActivePixelCount = 0;
+		this._auxSamples = 0;
+		this._auxSeedPending = false;
 
 	}
 
@@ -585,28 +605,62 @@ export class PathTracer extends PathTracerStage {
 	}
 
 	// Aux MRT (normalDepth/albedo) is needed only by the denoiser/OIDN; DenoisingManager calls this to
-	// turn the wavefront's aux writes on/off. It's a live uniform, so toggling is just a value flip +
-	// accumulation reset — no kernel rebuild, no UI freeze.
+	// turn the wavefront's aux writes on/off. It's a live uniform, so toggling is just a value flip —
+	// no kernel rebuild, no UI freeze.
 	setAuxGBufferEnabled( enabled ) {
 
 		enabled = !! enabled;
 		if ( this._auxGBufferEnabled === enabled ) return;
 		this._auxGBufferEnabled = enabled;
 		this._auxGBufferUniform.value = enabled ? 1 : 0;
-		this.reset();
+		this.restartAuxAccumulation();
 
 	}
 
 	// Clean-aux normal: when a clean-aux OIDN model is active (calb_cnrm/high, alb_nrm/balanced), FinalWrite
 	// temporally accumulates + renormalizes the aux normal so the model isn't fed per-frame point-sampled
-	// noise. DenoisingManager calls this on OIDN enable + quality change. Live uniform → value flip + reset.
+	// noise. DenoisingManager calls this on OIDN enable + quality change. The two modes write the normal in
+	// incompatible ways, so the aux buffer has to refill.
 	setCleanAuxNormal( enabled ) {
 
 		enabled = !! enabled;
 		if ( this._cleanAuxNormalEnabled === enabled ) return;
 		this._cleanAuxNormalEnabled = enabled;
 		this._cleanAuxNormalUniform.value = enabled ? 1 : 0;
-		this.reset();
+		this.restartAuxAccumulation();
+
+	}
+
+	/** Drops the aux MRT's history, leaving the colour's accumulation intact. */
+	restartAuxAccumulation() {
+
+		this._auxSamples = 0;
+		this._auxSeedPending = this._auxGBufferEnabled;
+
+	}
+
+	/**
+	 * @returns {boolean} whether FinalWrite will MIX the aux this frame rather than seed it.
+	 *
+	 * colorAccumulates mirrors FinalWrite's outer gate: when that gate is false the aux is written verbatim
+	 * regardless, which restarts the epoch. A mismatch costs aux quality only — the shader also reads
+	 * hasPreviousAux, so it can never mix against textures this epoch has not written.
+	 */
+	_updateAuxAccumulationUniforms( frameValue ) {
+
+		const colorAccumulates = this.accumulationEnabled
+			&& ! this.cameraIsMoving.value
+			&& frameValue > 0
+			&& this.hasPreviousAccumulated.value > 0
+			&& this.visMode.value !== 11;
+
+		const mixes = this._auxGBufferEnabled && colorAccumulates
+			&& ! this._auxSeedPending && this._auxSamples > 0;
+
+		this.hasPreviousAux.value = mixes ? 1 : 0;
+		this.auxAccumulationAlpha.value = mixes ? 1 / ( this._auxSamples + 1 ) : 1.0;
+
+		return mixes;
 
 	}
 
@@ -1483,6 +1537,8 @@ export class PathTracer extends PathTracerStage {
 			enableAccumulation: this.enableAccumulation,
 			hasPreviousAccumulated: this.hasPreviousAccumulated,
 			accumulationAlpha: this.accumulationAlpha,
+			hasPreviousAux: this.hasPreviousAux,
+			auxAccumulationAlpha: this.auxAccumulationAlpha,
 			cameraIsMoving: this.cameraIsMoving,
 			transparentBackground: this.transparentBackground,
 			prevAccumTexture: prevColor,

package/src/TSL/FinalWriteKernel.js

@@ -37,6 +37,8 @@ export function buildFinalWriteKernel( params ) {
 		writeColorTex, writeNDTex, writeAlbedoTex,
 		resolution, frame,
 		enableAccumulation, hasPreviousAccumulated, accumulationAlpha, cameraIsMoving,
+		// Aux MRT accumulates on its own epoch; hasPreviousAux=0 → write it verbatim instead of mixing.
+		hasPreviousAux, auxAccumulationAlpha,
 		transparentBackground,
 		prevAccumTexture, prevAlbedoTexture, prevNormalDepthTexture,
 		renderWidth,
@@ -113,10 +115,10 @@ export function buildFinalWriteKernel( params ) {
 
 				// 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, () => {
+				If( auxOn.and( hasPreviousAux ), () => {
 
 					// Albedo averages cleanly (it's a colour).
-					finalAlbedo.assign( mix( texture( prevAlbedoTexture, prevUV, 0 ).xyz, finalAlbedo, accumulationAlpha ) );
+					finalAlbedo.assign( mix( texture( prevAlbedoTexture, prevUV, 0 ).xyz, finalAlbedo, auxAccumulationAlpha ) );
 
 					// 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,
@@ -129,7 +131,7 @@ export function buildFinalWriteKernel( params ) {
 
 						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 mixedN = mix( prevN, curN, auxAccumulationAlpha ).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 ) );

package/src/managers/DenoisingManager.js

@@ -50,6 +50,9 @@ export class DenoisingManager extends EventDispatcher {
 		this.denoiser = null;
 		this.upscaler = null;
 
+		this._onReset = null;
+		this._onPostProcessRefresh = null;
+
 		// Resolution tracking — used for canvas restoration on reset
 		this._lastRenderWidth = 0;
 		this._lastRenderHeight = 0;
@@ -547,6 +550,13 @@ export class DenoisingManager extends EventDispatcher {
 
 	}
 
+	/** @param {Function} fn - () => void, re-runs the completion chain on the accumulated image */
+	setPostProcessRefreshCallback( fn ) {
+
+		this._onPostProcessRefresh = fn;
+
+	}
+
 	/** @param {import('../RenderSettings.js').RenderSettings} settings */
 	setSettings( settings ) {
 
@@ -620,6 +630,7 @@ export class DenoisingManager extends EventDispatcher {
 		if ( this.denoiser ) this.denoiser.enabled = enabled;
 		// OIDN reads the PathTracer aux MRT; re-sync so the wavefront produces it while OIDN is on.
 		this._syncGBufferStages();
+		this._onPostProcessRefresh?.();
 
 	}
 
@@ -629,6 +640,7 @@ export class DenoisingManager extends EventDispatcher {
 		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' );
+		this._onPostProcessRefresh?.();
 
 	}
 

package/src/managers/UniformManager.js

@@ -196,6 +196,10 @@ export class UniformManager {
 		ub( 'cameraIsMoving', false );
 		ub( 'hasPreviousAccumulated', false );
 
+		// Aux MRT epoch, separate from the colour's so the denoiser can be enabled mid-render.
+		u( 'auxAccumulationAlpha', 1.0, 'float' );
+		ub( 'hasPreviousAux', false );
+
 		// Environment
 		u( 'environmentIntensity', DEFAULT_STATE.environmentIntensity, 'float' );
 		u( 'backgroundIntensity', DEFAULT_STATE.backgroundIntensity, 'float' );