rayzee 5.3.7 → 5.4.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "rayzee",
-  "version": "5.3.7",
+  "version": "5.4.0",
   "type": "module",
   "description": "Real-time WebGPU path tracing engine built on Three.js",
   "main": "dist/rayzee.umd.js",
@@ -34,7 +34,7 @@
     "prepublishOnly": "npm run build"
   },
   "peerDependencies": {
-    "three": ">=0.183.2"
+    "three": ">=0.184.0"
   },
   "dependencies": {
     "stats-gl": "^4.0.2"

package/src/Passes/AIUpscaler.js

@@ -114,6 +114,14 @@ export class AIUpscaler extends EventDispatcher {
 		this._baseWidth = output.width;
 		this._baseHeight = output.height;
 
+		// Pooled HDR readback staging buffer — reused across _captureSourceHDR calls.
+		// Rebuilt only when the source texture dimensions change (same spirit as
+		// r184's ReadbackBuffer; we can't use renderer.getArrayBufferAsync directly
+		// because our source is a raw GPUTexture, not a Three.js BufferAttribute).
+		this._hdrStagingBuffer = null;
+		this._hdrStagingWidth = 0;
+		this._hdrStagingHeight = 0;
+
 	}
 
 	// ─── Model Management ─────────────────────────────────────────────────────
@@ -477,14 +485,26 @@ export class AIUpscaler extends EventDispatcher {
 		const width = colorTexture.width;
 		const height = colorTexture.height;
 
-		// GPU texture → staging buffer → CPU readback
+		// GPU texture → pooled staging buffer → CPU readback.
+		// The staging buffer is kept alive between calls (unmap, don't destroy)
+		// and only re-created when texture dimensions change.
 		const bytesPerRow = Math.ceil( width * 16 / 256 ) * 256; // rgba32float=16 bytes, aligned to 256
 		const bufferSize = bytesPerRow * height;
 
-		const stagingBuffer = device.createBuffer( {
-			size: bufferSize,
-			usage: GPUBufferUsage.MAP_READ | GPUBufferUsage.COPY_DST
-		} );
+		if ( this._hdrStagingWidth !== width || this._hdrStagingHeight !== height ) {
+
+			this._hdrStagingBuffer?.destroy();
+			this._hdrStagingBuffer = device.createBuffer( {
+				label: 'aiupscaler-hdr-readback',
+				size: bufferSize,
+				usage: GPUBufferUsage.MAP_READ | GPUBufferUsage.COPY_DST
+			} );
+			this._hdrStagingWidth = width;
+			this._hdrStagingHeight = height;
+
+		}
+
+		const stagingBuffer = this._hdrStagingBuffer;
 
 		const encoder = device.createCommandEncoder();
 		encoder.copyTextureToBuffer(
@@ -511,7 +531,6 @@ export class AIUpscaler extends EventDispatcher {
 		}
 
 		stagingBuffer.unmap();
-		stagingBuffer.destroy();
 
 		// Mark as HDR so _extractTile and _tensorToImageData handle it correctly
 		return { data, width, height, isHDR: true };
@@ -856,6 +875,11 @@ export class AIUpscaler extends EventDispatcher {
 		this._upscaledAlpha = null;
 		this.state.abortController = null;
 
+		this._hdrStagingBuffer?.destroy();
+		this._hdrStagingBuffer = null;
+		this._hdrStagingWidth = 0;
+		this._hdrStagingHeight = 0;
+
 		console.log( 'AIUpscaler disposed' );
 
 	}

package/src/Passes/OIDNDenoiser.js

@@ -76,6 +76,17 @@ export class OIDNDenoiser extends EventDispatcher {
 		// Cached GPU storage buffers for texture→buffer copies (reused across denoise calls)
 		this._gpuInputBuffers = { color: null, albedo: null, normal: null };
 		this._gpuInputBufferSize = { width: 0, height: 0 };
+		// Shared pad-strip buffer for non-256-aligned widths. Reused across
+		// color/albedo/normal copies within the same encoder (WebGPU command
+		// order guarantees the overwrites are serialized).
+		this._gpuInputPadBuffer = null;
+		this._gpuInputPaddedRowBytes = 0;
+		// Pooled MAP_READ staging buffer for _cacheInputAlpha. Only allocated
+		// when transparent-background readback is used, destroyed on resolution
+		// change or dispose. Same spirit as r184's ReadbackBuffer — we can't use
+		// renderer.getArrayBufferAsync because the source is a raw GPUBuffer,
+		// not a Three.js BufferAttribute.
+		this._alphaReadbackBuffer = null;
 
 		// Cached alpha channel from the input color buffer (OIDN discards alpha)
 		this._cachedAlpha = null;
@@ -385,13 +396,15 @@ export class OIDNDenoiser extends EventDispatcher {
 
 		// Copy render target textures → tightly packed GPU storage buffers for oidn-web.
 		// copyTextureToBuffer requires bytesPerRow to be a multiple of 256. When the tight
-		// row size (width * 16) isn't aligned, copy via a padded staging buffer per texture
-		// then strip padding row-by-row.
+		// row size (width * 16) isn't aligned, copy via a shared pre-allocated padded buffer
+		// (see _ensureGPUInputBuffers) then strip padding row-by-row. The pad buffer is
+		// reused across color/albedo/normal — safe because WebGPU serializes commands
+		// within a single encoder.
 		const encoder = device.createCommandEncoder( { label: 'oidn-tex-to-buf' } );
 		const tightRowBytes = width * 16; // rgba32float
-		const paddedRowBytes = Math.ceil( tightRowBytes / 256 ) * 256;
-		const needsPadStrip = paddedRowBytes !== tightRowBytes;
-		const stagingBufs = [];
+		const paddedRowBytes = this._gpuInputPaddedRowBytes;
+		const needsPadStrip = paddedRowBytes > tightRowBytes;
+		const padBuf = this._gpuInputPadBuffer;
 
 		const copyTex = ( tex, tightBuf ) => {
 
@@ -405,9 +418,6 @@ export class OIDNDenoiser extends EventDispatcher {
 
 			} else {
 
-				const padBuf = device.createBuffer( { size: paddedRowBytes * height, usage: GPUBufferUsage.COPY_DST | GPUBufferUsage.COPY_SRC } );
-				stagingBufs.push( padBuf );
-
 				encoder.copyTextureToBuffer(
 					{ texture: tex, mipLevel: 0 },
 					{ buffer: padBuf, offset: 0, bytesPerRow: paddedRowBytes, rowsPerImage: height },
@@ -429,7 +439,6 @@ export class OIDNDenoiser extends EventDispatcher {
 		copyTex( textures.normal, this._gpuInputBuffers.normal );
 
 		device.queue.submit( [ encoder.finish() ] );
-		for ( const buf of stagingBufs ) buf.destroy();
 
 		// Cache alpha channel from input color buffer when transparent background is enabled.
 		// OIDN only processes RGB — the alpha channel is lost, so we read it before denoising.
@@ -478,6 +487,25 @@ export class OIDNDenoiser extends EventDispatcher {
 		this._gpuInputBuffers.normal = device.createBuffer( { label: 'oidn-in-normal', size: byteSize, usage } );
 		this._gpuInputBufferSize = { width, height };
 
+		// Pre-allocate the row-pad staging buffer when width * 16 isn't 256-aligned.
+		// Shared across the three texture copies; recreated only on resolution change.
+		const tightRowBytes = width * 16;
+		const paddedRowBytes = Math.ceil( tightRowBytes / 256 ) * 256;
+		if ( paddedRowBytes !== tightRowBytes ) {
+
+			this._gpuInputPadBuffer = device.createBuffer( {
+				label: 'oidn-in-pad',
+				size: paddedRowBytes * height,
+				usage: GPUBufferUsage.COPY_DST | GPUBufferUsage.COPY_SRC
+			} );
+			this._gpuInputPaddedRowBytes = paddedRowBytes;
+
+		} else {
+
+			this._gpuInputPaddedRowBytes = tightRowBytes;
+
+		}
+
 	}
 
 	_destroyGPUInputBuffers() {
@@ -485,7 +513,12 @@ export class OIDNDenoiser extends EventDispatcher {
 		this._gpuInputBuffers.color?.destroy();
 		this._gpuInputBuffers.albedo?.destroy();
 		this._gpuInputBuffers.normal?.destroy();
+		this._gpuInputPadBuffer?.destroy();
+		this._alphaReadbackBuffer?.destroy();
 		this._gpuInputBuffers = { color: null, albedo: null, normal: null };
+		this._gpuInputPadBuffer = null;
+		this._gpuInputPaddedRowBytes = 0;
+		this._alphaReadbackBuffer = null;
 		this._gpuInputBufferSize = { width: 0, height: 0 };
 
 	}
@@ -497,11 +530,21 @@ export class OIDNDenoiser extends EventDispatcher {
 	async _cacheInputAlpha( device, width, height ) {
 
 		const byteSize = width * height * 16; // rgba32float, tightly packed
-		const staging = device.createBuffer( {
-			label: 'oidn-alpha-staging',
-			size: byteSize,
-			usage: GPUBufferUsage.MAP_READ | GPUBufferUsage.COPY_DST
-		} );
+
+		// Lazy-allocate the pooled staging buffer on first call at this resolution.
+		// _destroyGPUInputBuffers clears it on resolution change or dispose, so if
+		// it is non-null here, it already matches the current resolution.
+		if ( this._alphaReadbackBuffer === null ) {
+
+			this._alphaReadbackBuffer = device.createBuffer( {
+				label: 'oidn-alpha-readback',
+				size: byteSize,
+				usage: GPUBufferUsage.MAP_READ | GPUBufferUsage.COPY_DST
+			} );
+
+		}
+
+		const staging = this._alphaReadbackBuffer;
 
 		const enc = device.createCommandEncoder();
 		enc.copyBufferToBuffer( this._gpuInputBuffers.color, 0, staging, 0, byteSize );
@@ -520,7 +563,6 @@ export class OIDNDenoiser extends EventDispatcher {
 		}
 
 		staging.unmap();
-		staging.destroy();
 
 		this._cachedAlpha = alpha;
 		this._cachedAlphaWidth = width;

package/src/PathTracerApp.js

@@ -19,7 +19,7 @@ import { Display } from './Stages/Display.js';
 import { RenderPipeline } from './Pipeline/RenderPipeline.js';
 import { CompletionTracker } from './Pipeline/CompletionTracker.js';
 import { ENGINE_DEFAULTS as DEFAULT_STATE, FINAL_RENDER_CONFIG, PREVIEW_RENDER_CONFIG } from './EngineDefaults.js';
-import { updateStats, updateLoading, resetLoading, setStatusCallback, getDisplaySamples } from './Processor/utils.js';
+import { updateStats, updateLoading, resetLoading, setStatusCallback, getDisplaySamples, disposeObjectFromMemory } from './Processor/utils.js';
 import { BuildTimer } from './Processor/BuildTimer.js';
 import { InteractionManager } from './managers/InteractionManager.js';
 import { EngineEvents } from './EngineEvents.js';
@@ -129,6 +129,45 @@ export class PathTracerApp extends EventDispatcher {
 		// Resolution state
 		this._resizeDebounceTimer = null;
 
+		// Tracked listeners for clean dispose()
+		this._trackedListeners = [];
+		this._disposed = false;
+
+	}
+
+	/**
+	 * Registers an event listener and tracks it for automatic cleanup on dispose().
+	 * @param {EventTarget|{addEventListener:Function, removeEventListener:Function}} target
+	 * @param {string} type
+	 * @param {Function} handler
+	 */
+	_addTrackedListener( target, type, handler ) {
+
+		if ( ! target ) return;
+		target.addEventListener( type, handler );
+		this._trackedListeners.push( { target, type, handler } );
+
+	}
+
+	/** Removes all listeners registered via _addTrackedListener. */
+	_removeTrackedListeners() {
+
+		for ( const { target, type, handler } of this._trackedListeners ) {
+
+			try {
+
+				target.removeEventListener( type, handler );
+
+			} catch ( err ) {
+
+				console.warn( 'PathTracerApp: failed to remove listener', type, err );
+
+			}
+
+		}
+
+		this._trackedListeners.length = 0;
+
 	}
 
 	// ═══════════════════════════════════════════════════════════════
@@ -356,19 +395,22 @@ export class PathTracerApp extends EventDispatcher {
 	 */
 	dispose() {
 
-		this.animationManager?.dispose();
-		this.stopAnimation();
-		setStatusCallback( null );
+		if ( this._disposed ) return;
+		this._disposed = true;
 
-		if ( this.assetLoader && this._onAssetLoaded ) {
+		this.stopAnimation();
+		clearTimeout( this._resizeDebounceTimer );
 
-			this.assetLoader.removeEventListener( 'load', this._onAssetLoaded );
+		// Remove all tracked listeners (app-owned subscriptions across managers/DOM)
+		this._removeTrackedListeners();
 
-		}
+		setStatusCallback( null );
 
+		this.animationManager?.dispose();
 		this.transformManager?.dispose();
 		this.overlayManager?.dispose();
 		this._sceneHelpers?.clear();
+		this.lightManager?.dispose();
 		this.denoisingManager?.dispose();
 		this.pipeline?.dispose();
 		this.interactionManager?.dispose();
@@ -382,9 +424,6 @@ export class PathTracerApp extends EventDispatcher {
 
 		}
 
-		clearTimeout( this._resizeDebounceTimer );
-		window.removeEventListener( 'resize', this.resizeHandler );
-
 		this.isInitialized = false;
 
 	}
@@ -393,6 +432,61 @@ export class PathTracerApp extends EventDispatcher {
 	// Asset Loading
 	// ═══════════════════════════════════════════════════════════════
 
+	/**
+	 * Tears down the current scene: stops animation, deselects, disposes
+	 * the loaded model + its GPU resources, clears lights, and seeds the
+	 * path tracer with an empty scene. Leaves the renderer, pipeline, and
+	 * managers intact so a subsequent loadModel() can reuse them.
+	 *
+	 * Safe to call at any point after init() (including while idle).
+	 * Throws if called concurrently with a load.
+	 */
+	unloadScene() {
+
+		if ( ! this.isInitialized ) return;
+		if ( this._loadingInProgress ) {
+
+			throw new Error( 'PathTracerApp.unloadScene: cannot unload while a load is in progress' );
+
+		}
+
+		if ( this._disposed ) return;
+
+		// Stop animation + refit
+		this.animationManager?.dispose();
+		this._animRefitInFlight = false;
+
+		// Drop selection + transform gizmo attachment
+		this.interactionManager?.deselect();
+		this.transformManager?.detach?.();
+
+		// Dispose the loaded model (geometries, materials, textures)
+		if ( this.assetLoader?.targetModel ) {
+
+			disposeObjectFromMemory( this.assetLoader.targetModel );
+			this.assetLoader.targetModel = null;
+
+		}
+
+		// Clear lights in the WebGPU light scene
+		this.lightManager?.clearLights?.();
+
+		// Seed path tracer with empty data (matches the init-time seed)
+		if ( this.stages.pathTracer ) {
+
+			this.stages.pathTracer.setTriangleData( new Float32Array( 32 ), 0 );
+			this.stages.pathTracer.setBVHData( new Float32Array( 16 ) );
+			this.stages.pathTracer.materialData.setMaterialData( new Float32Array( 16 ) );
+			this.stages.pathTracer.setEmissiveTriangleData?.( new Float32Array( 0 ), 0, 0 );
+			this.stages.pathTracer.setupMaterial();
+
+		}
+
+		this.reset();
+		this.dispatchEvent( { type: 'SceneUnloaded' } );
+
+	}
+
 	/**
 	 * Loads a model, builds BVH, and uploads scene data.
 	 * @param {string} url - Model URL
@@ -427,6 +521,12 @@ export class PathTracerApp extends EventDispatcher {
 	 */
 	async loadEnvironment( url ) {
 
+		if ( this._loadingInProgress ) {
+
+			throw new Error( 'PathTracerApp.loadEnvironment: another load is already in progress' );
+
+		}
+
 		this._loadingInProgress = true;
 
 		try {
@@ -469,6 +569,12 @@ export class PathTracerApp extends EventDispatcher {
 	/** Shared pipeline: load asset → sync controls → build BVH → reset → dispatch events */
 	async _loadWithSceneRebuild( loadFn, eventPayload ) {
 
+		if ( this._loadingInProgress ) {
+
+			throw new Error( 'PathTracerApp: another load is already in progress' );
+
+		}
+
 		this._loadingInProgress = true;
 
 		try {
@@ -547,6 +653,24 @@ export class PathTracerApp extends EventDispatcher {
 		this.stages.pathTracer.setupMaterial();
 		timer.end( 'Material setup (TSL compile)' );
 
+		// Front-load GPU pipeline creation so the first animate frame is snappy:
+		//  - compute: Three.js has no async compute compile — one dispatch at
+		//    build time moves the stall to this loading moment.
+		//  - raster fallback: compileAsync yields to main thread (r184+).
+		timer.start( 'Pipeline precompile' );
+		this.stages.pathTracer.shaderBuilder.forceCompile( this.renderer );
+		try {
+
+			await this.renderer.compileAsync( this.meshScene, this.cameraManager.camera );
+
+		} catch ( err ) {
+
+			console.warn( 'PathTracerApp: raster fallback precompile failed', err );
+
+		}
+
+		timer.end( 'Pipeline precompile' );
+
 		// Wait for CDF
 		if ( cdfPromise ) {
 
@@ -843,6 +967,16 @@ export class PathTracerApp extends EventDispatcher {
 
 	}
 
+	/**
+	 * Whether a model/environment load is currently in progress.
+	 * @returns {boolean}
+	 */
+	get isLoading() {
+
+		return this._loadingInProgress;
+
+	}
+
 	/**
 	 * Whether the path tracer has finished converging.
 	 * @returns {boolean}
@@ -1011,7 +1145,7 @@ export class PathTracerApp extends EventDispatcher {
 		this.assetLoader.setRenderer( this.renderer );
 		this.assetLoader.createFloorPlane();
 
-		this.cameraManager.controls.addEventListener( 'change', () => {
+		this._addTrackedListener( this.cameraManager.controls, 'change', () => {
 
 			this.needsReset = true;
 			this.wake();
@@ -1093,8 +1227,8 @@ export class PathTracerApp extends EventDispatcher {
 	_wireEvents() {
 
 		// Forward manager events → app events
-		this.cameraManager.addEventListener( 'CameraSwitched', ( e ) => this.dispatchEvent( e ) );
-		this.cameraManager.addEventListener( EngineEvents.AUTO_FOCUS_UPDATED, ( e ) => this.dispatchEvent( e ) );
+		this._addTrackedListener( this.cameraManager, 'CameraSwitched', ( e ) => this.dispatchEvent( e ) );
+		this._addTrackedListener( this.cameraManager, EngineEvents.AUTO_FOCUS_UPDATED, ( e ) => this.dispatchEvent( e ) );
 
 		this._forwardEvents( this.denoisingManager, [
 			EngineEvents.DENOISING_START, EngineEvents.DENOISING_END,
@@ -1111,12 +1245,12 @@ export class PathTracerApp extends EventDispatcher {
 			EngineEvents.ANIMATION_PAUSED,
 			EngineEvents.ANIMATION_STOPPED,
 		] );
-		this.animationManager.addEventListener( EngineEvents.ANIMATION_PAUSED, () => {
+		this._addTrackedListener( this.animationManager, EngineEvents.ANIMATION_PAUSED, () => {
 
 			this._animRefitInFlight = false;
 
 		} );
-		this.animationManager.addEventListener( EngineEvents.ANIMATION_STOPPED, () => {
+		this._addTrackedListener( this.animationManager, EngineEvents.ANIMATION_STOPPED, () => {
 
 			this._animRefitInFlight = false;
 
@@ -1152,7 +1286,7 @@ export class PathTracerApp extends EventDispatcher {
 		this.resizeHandler = () => this.onResize();
 		if ( this._autoResize ) {
 
-			window.addEventListener( 'resize', this.resizeHandler );
+			this._addTrackedListener( window, 'resize', this.resizeHandler );
 
 		}
 
@@ -1183,9 +1317,9 @@ export class PathTracerApp extends EventDispatcher {
 
 		};
 
-		this.assetLoader.addEventListener( 'load', this._onAssetLoaded );
+		this._addTrackedListener( this.assetLoader, 'load', this._onAssetLoaded );
 
-		this.assetLoader.addEventListener( 'modelProcessed', ( event ) => {
+		this._addTrackedListener( this.assetLoader, 'modelProcessed', ( event ) => {
 
 			const cameras = [ this.cameraManager.camera, ...( event.cameras || [] ) ];
 			this.cameraManager.setCameras( cameras );
@@ -1382,7 +1516,7 @@ export class PathTracerApp extends EventDispatcher {
 		if ( ! source ) return;
 		for ( const type of eventTypes ) {
 
-			source.addEventListener( type, ( e ) => this.dispatchEvent( e ) );
+			this._addTrackedListener( source, type, ( e ) => this.dispatchEvent( e ) );
 
 		}
 

package/src/Pipeline/RenderPipeline.js

@@ -449,7 +449,16 @@ export class RenderPipeline {
 
 		console.group( '[Pipeline] Performance Stats' );
 		console.log( `Frames: ${stats.frameCount}` );
-		console.log( `Total: ${stats.total.toFixed( 2 )}ms (min: ${stats.totalMin.toFixed( 2 )}ms, max: ${stats.totalMax.toFixed( 2 )}ms)` );
+
+		if ( stats.totalMin !== undefined ) {
+
+			console.log( `Total: ${stats.total.toFixed( 2 )}ms (min: ${stats.totalMin.toFixed( 2 )}ms, max: ${stats.totalMax.toFixed( 2 )}ms)` );
+
+		} else {
+
+			console.log( 'Total: no frames recorded yet (pipeline.render() has not run since stats were enabled — the path tracer may have converged and stopped its animation loop)' );
+
+		}
 
 		for ( const [ name, timing ] of Object.entries( stats.stages ) ) {
 

package/src/Processor/ShaderBuilder.js

@@ -50,9 +50,18 @@ export class ShaderBuilder {
 		this._dispatchX = 0;
 		this._dispatchY = 0;
 
+		// Reused per-frame dispatchSize array — avoids GC pressure from
+		// allocating [x,y,z] on every setFullScreenDispatch/setTileDispatch call.
+		// WebGPUBackend only reads indices 0..2 of this array during compute dispatch.
+		this._dispatchSize = [ 0, 0, 1 ];
+
 		// Scene texture nodes cache (for in-place updates on model change)
 		this._sceneTextureNodes = null;
 
+		// Whether the GPU compute pipeline has been compiled (via a real dispatch).
+		// Reset on setupCompute() rebuilds and on dispose().
+		this._compiled = false;
+
 	}
 
 	/**
@@ -89,6 +98,9 @@ export class ShaderBuilder {
 			writeTex.color, writeTex.normalDepth, writeTex.albedo
 		);
 
+		// New compute node → needs a fresh GPU pipeline compile
+		this._compiled = false;
+
 		timer.end( 'Build compute node (TSL)' );
 
 		timer.print();
@@ -131,7 +143,13 @@ export class ShaderBuilder {
 		this._dispatchX = Math.ceil( width / WG_SIZE );
 		this._dispatchY = Math.ceil( height / WG_SIZE );
 
-		if ( this.computeNode ) this.computeNode.setCount( [ this._dispatchX, this._dispatchY, 1 ] );
+		if ( this.computeNode ) {
+
+			this._dispatchSize[ 0 ] = this._dispatchX;
+			this._dispatchSize[ 1 ] = this._dispatchY;
+			this.computeNode.dispatchSize = this._dispatchSize;
+
+		}
 
 		this.renderWidth.value = width;
 		this.renderHeight.value = height;
@@ -158,7 +176,13 @@ export class ShaderBuilder {
 		const dispatchX = Math.ceil( tileWidth / WG_SIZE );
 		const dispatchY = Math.ceil( tileHeight / WG_SIZE );
 
-		if ( this.computeNode ) this.computeNode.setCount( [ dispatchX, dispatchY, 1 ] );
+		if ( this.computeNode ) {
+
+			this._dispatchSize[ 0 ] = dispatchX;
+			this._dispatchSize[ 1 ] = dispatchY;
+			this.computeNode.dispatchSize = this._dispatchSize;
+
+		}
 
 	}
 
@@ -170,13 +194,36 @@ export class ShaderBuilder {
 		this.tileOffsetX.value = 0;
 		this.tileOffsetY.value = 0;
 
-		if ( this.computeNode ) this.computeNode.setCount( [ this._dispatchX, this._dispatchY, 1 ] );
+		if ( this.computeNode ) {
+
+			this._dispatchSize[ 0 ] = this._dispatchX;
+			this._dispatchSize[ 1 ] = this._dispatchY;
+			this.computeNode.dispatchSize = this._dispatchSize;
+
+		}
 
 	}
 
-	forceCompile() {
+	/**
+	 * Front-load GPU compute pipeline creation via a single dispatch.
+	 *
+	 * Three.js WebGPU has no `createComputePipelineAsync` path — compute
+	 * pipelines always compile synchronously on first `renderer.compute(node)`.
+	 * Calling this at build time (while a "Compiling shaders…" status is
+	 * already visible) moves the stall off the first animate frame.
+	 *
+	 * The dispatch writes to ping-pong storage textures whose contents are
+	 * discarded by the subsequent `reset()` (frame counter back to 0 →
+	 * `hasPreviousAccumulated = 0` → prev textures are not read).
+	 *
+	 * @param {object} renderer - WebGPURenderer
+	 */
+	forceCompile( renderer ) {
+
+		if ( this._compiled || ! this.computeNode || ! renderer ) return;
 
-		// No-op — compilation happens on first renderer.compute() call.
+		this._compiled = true;
+		renderer.compute( this.computeNode );
 
 	}
 
@@ -379,6 +426,7 @@ export class ShaderBuilder {
 		this.prevAlbedoTexNode = null;
 		this.adaptiveSamplingTexNode = null;
 		this._sceneTextureNodes = null;
+		this._compiled = false;
 
 	}
 

package/src/Stages/ASVGF.js

@@ -803,10 +803,10 @@ export class ASVGF extends RenderStage {
 		// Update dispatch dimensions
 		this._dispatchX = Math.ceil( width / 8 );
 		this._dispatchY = Math.ceil( height / 8 );
-		this._gradientNode.setCount( [ this._dispatchX, this._dispatchY, 1 ] );
-		this._temporalNodeA.setCount( [ this._dispatchX, this._dispatchY, 1 ] );
-		this._temporalNodeB.setCount( [ this._dispatchX, this._dispatchY, 1 ] );
-		this._heatmapComputeNode.setCount( [ this._dispatchX, this._dispatchY, 1 ] );
+		this._gradientNode.dispatchSize = [ this._dispatchX, this._dispatchY, 1 ];
+		this._temporalNodeA.dispatchSize = [ this._dispatchX, this._dispatchY, 1 ];
+		this._temporalNodeB.dispatchSize = [ this._dispatchX, this._dispatchY, 1 ];
+		this._heatmapComputeNode.dispatchSize = [ this._dispatchX, this._dispatchY, 1 ];
 
 	}
 

package/src/Stages/AdaptiveSampling.js

@@ -422,8 +422,8 @@ export class AdaptiveSampling extends RenderStage {
 		// Update dispatch dimensions
 		this._dispatchX = Math.ceil( width / 16 );
 		this._dispatchY = Math.ceil( height / 16 );
-		this._computeNode.setCount( [ this._dispatchX, this._dispatchY, 1 ] );
-		this._heatmapComputeNode.setCount( [ this._dispatchX, this._dispatchY, 1 ] );
+		this._computeNode.dispatchSize = [ this._dispatchX, this._dispatchY, 1 ];
+		this._heatmapComputeNode.dispatchSize = [ this._dispatchX, this._dispatchY, 1 ];
 
 	}