rayzee 11.4.0 → 11.5.0

package/dist/{sceneCachePolicy-AKOEu2lf.js → sceneCachePolicy--ta6moJu.js}

@@ -1594,7 +1594,7 @@ var vt = class {
 			samples: this.samples.slice()
 		};
 	}
-}, yt = "11.4.0", $ = 1e4, bt = 15e5;
+}, yt = "11.5.0", $ = 1e4, bt = 15e5;
 function xt(e, t, n = $) {
 	return e >= n && t / bt < e / 3;
 }

package/package.json

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

package/src/Passes/AIUpscaler.js

@@ -123,7 +123,7 @@ export class AIUpscaler extends EventDispatcher {
 		this._worker = null;
 		this._currentModelUrl = null;
 		this._tileId = 0;
-		this._pendingWorkerHandlers = new Set();
+		this._pendingWorkerHandlers = new Map();
 
 		// Alpha channel cache (bilinear-upscaled from source, applied per tile)
 		this._upscaledAlpha = null;
@@ -227,7 +227,8 @@ export class AIUpscaler extends EventDispatcher {
 
 	// ─── Public Lifecycle ─────────────────────────────────────────────────────
 
-	async start() {
+	/** @param {ImageData} [source] - what to enlarge instead of the render canvas */
+	async start( source = null ) {
 
 		if ( ! this.enabled || this.state.isUpscaling || this.state.isLoading ) {
 
@@ -238,7 +239,7 @@ export class AIUpscaler extends EventDispatcher {
 		this.dispatchEvent( { type: 'start' } );
 
 		const startTime = performance.now();
-		const success = await this.execute();
+		const success = await this.execute( source );
 
 		if ( success ) {
 
@@ -260,7 +261,7 @@ export class AIUpscaler extends EventDispatcher {
 
 	}
 
-	async execute() {
+	async execute( source = null ) {
 
 		if ( ! this.enabled ) return false;
 
@@ -270,7 +271,11 @@ export class AIUpscaler extends EventDispatcher {
 		// Capture source image SYNCHRONOUSLY before any async work.
 		// WebGPU canvas textures expire after each compositor frame,
 		// so we must grab the pixels before awaiting model load.
-		if ( this.hdr && this.getGPUTextures ) {
+		if ( source ) {
+
+			this._capturedSource = source;
+
+		} else if ( this.hdr && this.getGPUTextures ) {
 
 			// HDR path: float planes tone-mapped on the GPU, no 8-bit step before the network
 			this._capturedSource = await this._captureSourceHDR();
@@ -586,7 +591,7 @@ export class AIUpscaler extends EventDispatcher {
 
 			};
 
-			this._pendingWorkerHandlers.add( handler );
+			this._pendingWorkerHandlers.set( handler, reject );
 			this._worker.addEventListener( 'message', handler );
 			this._worker.postMessage(
 				{ type: 'infer', tileData, width, height, id },
@@ -814,15 +819,13 @@ export class AIUpscaler extends EventDispatcher {
 
 	// ─── Disposal ─────────────────────────────────────────────────────────────
 
+	// Rejected, not dropped: an aborted run has to end before the next one starts.
 	_cleanupPendingWorkerHandlers() {
 
-		if ( this._worker ) {
-
-			for ( const handler of this._pendingWorkerHandlers ) {
+		for ( const [ handler, reject ] of this._pendingWorkerHandlers ) {
 
-				this._worker.removeEventListener( 'message', handler );
-
-			}
+			this._worker?.removeEventListener( 'message', handler );
+			reject( new DOMException( 'Aborted', 'AbortError' ) );
 
 		}
 

package/src/Processor/ToneMapGPU.js

@@ -275,8 +275,9 @@ export class PackedToneMapper {
 	 * @param {number} [tone.saturation=1]
 	 * @param {boolean} [tone.flipY=false]
 	 * @param {boolean} [tone.preserveAlpha=false] - the source's alpha, rounded as the CPU rounds it; else 255
-	 * @param {{key: string, wgsl: string, entries: GPUBindGroupEntry[]}} [tone.gain] - a per-pixel gain before the
-	 *   curve: WGSL defining `rayzee_gain( uv, linear, exposure ) -> f32` over bind group 1
+	 * @param {{key: string, wgsl: string, entries: GPUBindGroupEntry[], device?: GPUDevice, copyTo?: Function}} [tone.gain] - a
+	 *   per-pixel gain before the curve: WGSL defining `rayzee_gain( uv, linear, exposure ) -> f32` over bind group 1.
+	 *   One on another device is copied to this one for the run (`copyTo`).
 	 * @returns {Promise<Uint8ClampedArray>} RGBA bytes, `width * height * 4`
 	 */
 	async toRGBA8( src, tone ) {
@@ -298,7 +299,25 @@ export class PackedToneMapper {
 
 	}
 
-	async _run( src, { exposure = 1, toneMapping = 0, saturation = 1, flipY = false, preserveAlpha = false, gain = null } = {} ) {
+	async _run( src, tone = {} ) {
+
+		const gain = tone.gain;
+		if ( ! gain?.device || gain.device === this.device ) return this._dispatch( src, tone );
+
+		const copy = await gain.copyTo( this.device );
+		try {
+
+			return await this._dispatch( src, { ...tone, gain: copy } );
+
+		} finally {
+
+			copy.destroy();
+
+		}
+
+	}
+
+	async _dispatch( src, { exposure = 1, toneMapping = 0, saturation = 1, flipY = false, preserveAlpha = false, gain = null } = {} ) {
 
 		if ( this.disposed ) throw new Error( 'PackedToneMapper: disposed' );
 		if ( ! this._storage ) throw new Error( 'PackedToneMapper: call ensureSize() first' );

package/src/Stages/LocalExposure.js

@@ -495,7 +495,8 @@ export class LocalExposure extends RenderStage {
 
 	/**
 	 * The gain for a tone-mapping pass outside three.js (`PackedToneMapper`'s `gain`), or null before the
-	 * first build. `cpu()` reads the grid back for the CPU tone map.
+	 * first build. `cpu()` reads the grid back for the CPU tone map; `copyTo( device )` copies it to another
+	 * GPU device (the neural models' own).
 	 */
 	toneGain() {
 
@@ -508,10 +509,12 @@ export class LocalExposure extends RenderStage {
 		this._paramsBuffer ??= backend.device.createBuffer( { label: 'local-exposure-params', size: 64, usage: GPUBufferUsage.UNIFORM | GPUBufferUsage.COPY_DST } );
 		backend.device.queue.writeBuffer( this._paramsBuffer, 0, this._params );
 		const params = this._params.slice();
+		const read = () => Promise.all( [ this.renderer.getArrayBufferAsync( this._grid.value ), this.renderer.getArrayBufferAsync( this._blur.value ) ] );
 
 		return {
 			key: 'local-exposure',
 			wgsl: LOCAL_EXPOSURE_WGSL,
+			device: backend.device,
 			entries: [
 				{ binding: 0, resource: { buffer: grid } },
 				{ binding: 1, resource: { buffer: blur } },
@@ -519,11 +522,31 @@ export class LocalExposure extends RenderStage {
 			],
 			cpu: async () => {
 
-				const [ g, b ] = await Promise.all( [ this.renderer.getArrayBufferAsync( this._grid.value ), this.renderer.getArrayBufferAsync( this._blur.value ) ] );
+				const [ g, b ] = await read();
 				const gridData = new Float32Array( g ), blurData = new Float32Array( b );
 				return ( u, v, lum, logExposure ) => localExposureGain( params, gridData, blurData, u, v, lum, logExposure );
 
 			},
+			copyTo: async device => {
+
+				const [ g, b ] = await read();
+				const buffers = [[ g, GPUBufferUsage.STORAGE ], [ b, GPUBufferUsage.STORAGE ], [ params, GPUBufferUsage.UNIFORM ]].map( ( [ data, usage ] ) => {
+
+					const buffer = device.createBuffer( { label: 'local-exposure-copy', size: data.byteLength, usage: usage | GPUBufferUsage.COPY_DST } );
+					device.queue.writeBuffer( buffer, 0, data );
+					return buffer;
+
+				} );
+
+				return {
+					key: 'local-exposure',
+					wgsl: LOCAL_EXPOSURE_WGSL,
+					device,
+					entries: buffers.map( ( buffer, binding ) => ( { binding, resource: { buffer } } ) ),
+					destroy: () => buffers.forEach( buffer => buffer.destroy() ),
+				};
+
+			},
 		};
 
 	}

package/src/managers/DenoisingManager.js

@@ -137,6 +137,11 @@ export class DenoisingManager extends EventDispatcher {
 		this._retouch = null;
 		this._superResModule = null;
 		this._neuralPostBusy = false;
+		// The finished render's post passes: its guard, the run in flight, a queued rerun, and a cancel.
+		this._postIsStillComplete = null;
+		this._postRun = null;
+		this._postRedo = null;
+		this._postCancelled = false;
 
 		// The tier the finished image uses. The loaded tier is not always this one: while the
 		// image is still accumulating we run a cheaper model (see previewQuality).
@@ -1148,6 +1153,7 @@ export class DenoisingManager extends EventDispatcher {
 	/** Turns the neural-rendering (detail) pass on or off, and sets its appearance controls. */
 	setNeuralRendering( enabled, settings = null ) {
 
+		const changed = this.neuralRendering !== !! enabled;
 		this.neuralRendering = !! enabled;
 		if ( settings ) this.neuralRenderingSettings = { ...this.neuralRenderingSettings, ...settings };
 		if ( ! this.neuralRendering ) {
@@ -1157,6 +1163,8 @@ export class DenoisingManager extends EventDispatcher {
 
 		}
 
+		if ( changed ) this._redoPostPasses();
+
 	}
 
 	_releaseNeuralRetouch() {
@@ -1167,14 +1175,8 @@ export class DenoisingManager extends EventDispatcher {
 	}
 
 	/**
-	 * The neural post-chain over the picture the closing denoise just produced: super resolution
-	 * first, then the detail pass, either or both.
-	 *
-	 * Order is forced by the models. Super resolution hands back light that can be fed onward; the
-	 * detail pass writes an `rgba8unorm` texture with no `COPY_SRC`, so nothing can read its result
-	 * and it has to be last — and it presents in its own display space rather than the engine's tone
-	 * curve. Which shape super resolution returns therefore depends on what follows it: packed
-	 * halves when the detail pass is next, display bytes when it is the end of the chain.
+	 * The post-chain over the picture the closing denoise just produced: the detail pass at render size,
+	 * then the chosen upscaler (neural super resolution or the ONNX one), either or both.
 	 *
 	 * Deliberately fire-and-forget: the render is already finished and a failure must not break it.
 	 */
@@ -1182,6 +1184,7 @@ export class DenoisingManager extends EventDispatcher {
 
 		const wantSR = this.upscaler?.enabled && this.upscalerBackend === 'neural';
 		const wantNR = this.neuralRendering;
+		const wantESRGAN = this.upscaler?.enabled && ! wantSR;
 		if ( ! wantSR && ! wantNR ) return;
 
 		// A second completion can land while the first pass is still in flight — the models are
@@ -1230,7 +1233,12 @@ export class DenoisingManager extends EventDispatcher {
 
 			}
 
-			if ( ! wantSR && ! runNR ) return;
+			if ( ! wantSR && ! runNR ) {
+
+				if ( wantESRGAN && ! this._postCancelled ) await this.upscaler.start();
+				return;
+
+			}
 
 			// Must be the effective value, not the settings one: AutoExposure overwrites
 			// `renderer.toneMappingExposure` every frame and never touches settings, so reading
@@ -1291,6 +1299,15 @@ export class DenoisingManager extends EventDispatcher {
 
 			}
 
+			if ( this._postRedo || this._postCancelled ) return;
+
+			if ( wantESRGAN ) {
+
+				await this.upscaler.start( new ImageData( image.rgba8, image.width, image.height ) );
+				return;
+
+			}
+
 			sr.presentRGBA8( this.upscalerCanvas, image.rgba8, image.width, image.height );
 
 			if ( ! isStillComplete() ) {
@@ -1360,10 +1377,61 @@ export class DenoisingManager extends EventDispatcher {
 
 	}
 
+	/** The neural chain or the ONNX upscaler over the finished render, as the switches ask. */
+	_runPostPasses( isStillComplete ) {
+
+		this._postIsStillComplete = isStillComplete;
+		this._postCancelled = false;
+
+		// The neural chain owns the overlay canvas when it runs, and hands its result to the ONNX upscaler.
+		if ( this.neuralRendering || ( this.upscaler?.enabled && this.upscalerBackend === 'neural' ) ) {
+
+			this._postRun = this._runNeuralPost( isStillComplete );
+
+		} else {
+
+			this._postRun = this.upscaler?.enabled ? this.upscaler.start() : null;
+
+		}
+
+	}
+
+	/** Runs the post passes again on a finished render whose switches changed, once the run in flight ends. */
+	_redoPostPasses() {
+
+		const isStillComplete = this._postIsStillComplete;
+		// No chain yet: the closing denoise is still running and the chain reads the switches when it starts.
+		if ( ! isStillComplete?.() || this._postRedo ) return;
+
+		this.upscaler?.abort();
+		this._postCancelled = false;
+		this._postRedo = Promise.resolve( this._postRun ).catch( () => {} ).then( () => {
+
+			this._postRedo = null;
+			if ( this._postCancelled || this._postIsStillComplete !== isStillComplete || ! isStillComplete() ) return;
+			this._restoreRenderDisplay();
+			this._runPostPasses( isStillComplete );
+
+		} );
+
+	}
+
+	/** Stops the post passes on the finished render, which stays on screen as rendered. The switches stay as they are. */
+	cancelPostPasses() {
+
+		this._postCancelled = true;
+		this.upscaler?.abort();
+		this._restoreRenderDisplay();
+		// A retouch in flight cannot be stopped, only discarded, and ends later.
+		this.dispatchEvent( { type: EngineEvents.UPSCALING_END } );
+
+	}
+
 	onRenderComplete( { isStillComplete } ) {
 
 		// Remove any stale completion-chain listener from a previous render cycle
 		this._cleanupCompletionListener();
+		this._postIsStillComplete = null;
 
 		// What closes the render, if anything. A full pass at the chosen tier when that switch is
 		// on; otherwise, if OIDN owns the live view, one last cheap refresh — the cadence's last
@@ -1383,16 +1451,7 @@ export class DenoisingManager extends EventDispatcher {
 			// denoise. Ordered after `_denoiserEndHandler`, which publishes the picture.
 			if ( closing ) this._onDisplayRefresh?.();
 
-			// One owner of the overlay canvas, so the neural chain and the ONNX upscaler are
-			// exclusive. The neural chain also runs on its own when only its detail pass is on.
-			if ( this.neuralRendering || ( this.upscaler?.enabled && this.upscalerBackend === 'neural' ) ) {
-
-				this._runNeuralPost( isStillComplete );
-				return;
-
-			}
-
-			if ( this.upscaler?.enabled ) this.upscaler.start();
+			this._runPostPasses( isStillComplete );
 
 		};
 
@@ -1467,6 +1526,7 @@ export class DenoisingManager extends EventDispatcher {
 
 		// Remove stale completion-chain listener before aborting
 		this._cleanupCompletionListener();
+		this._postIsStillComplete = null;
 
 		// The 2D canvas is the upscaler's alone: a reset means its enlarged result no longer
 		// describes anything, so the render canvas comes back.
@@ -1509,6 +1569,7 @@ export class DenoisingManager extends EventDispatcher {
 
 		// Remove pending completion-chain listener
 		this._cleanupCompletionListener();
+		this._postIsStillComplete = null;
 		// Owns a second GPUDevice plus 3 MB of weights, so it must not outlive the manager.
 		this._releaseNeuralUpscaler();
 		this._releaseNeuralRetouch();
@@ -1737,10 +1798,12 @@ export class DenoisingManager extends EventDispatcher {
 	/** Enables or disables the AI upscaler. */
 	setUpscalerEnabled( enabled ) {
 
+		const changed = !! this.upscaler && this.upscaler.enabled !== !! enabled;
 		if ( this.upscaler ) this.upscaler.enabled = enabled;
 		else if ( enabled ) this._recordNoOverlayCanvas( 'upscaler' );
 		// The enlarged picture describes a setting that is no longer on.
 		if ( ! enabled ) this._restoreRenderDisplay();
+		if ( changed ) this._redoPostPasses();
 
 	}