rayzee 7.22.6 → 7.22.7

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "rayzee",
-  "version": "7.22.6",
+  "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/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' );