rayzee 5.3.7 → 5.4.0

package/src/Stages/AutoExposure.js

@@ -1,6 +1,7 @@
 import { Fn, wgslFn, vec4, float, int, uint, ivec2, uvec2, uniform, If, max,
-	textureLoad, textureStore, workgroupArray, workgroupBarrier, localId, workgroupId } from 'three/tsl';
-import { RenderTarget, TextureNode, StorageTexture } from 'three/webgpu';
+	textureLoad, textureStore, workgroupArray, workgroupBarrier, localId, workgroupId,
+	attributeArray } from 'three/tsl';
+import { RenderTarget, TextureNode, StorageTexture, ReadbackBuffer } from 'three/webgpu';
 import { FloatType, RGBAFormat, NearestFilter } from 'three';
 import { RenderStage, StageExecutionMode } from '../Pipeline/RenderStage.js';
 import { luminance } from '../TSL/Common.js';
@@ -54,8 +55,11 @@ const adaptExposure = /*@__PURE__*/ wgslFn( `
  *   2. Reduction (compute): parallel reduction 64×64 → 1×1 via shared memory
  *      Single workgroup of 256 threads, each loads 16 texels.
  *      Computes geometric mean: exp(Σlog(L) / N)
- *   3. Adaptation (compute): temporal smoothing with prev exposure
- *   4. Async readback (1×1): apply to renderer.toneMappingExposure
+ *   3. Adaptation (compute): temporal smoothing with prev exposure; writes
+ *      vec4(exposure, luminance, targetExposure, 1) into a 1-element storage buffer.
+ *   4. Async readback via `renderer.getArrayBufferAsync(attr, ReadbackBuffer)`:
+ *      the ReadbackBuffer pools its staging GPUBuffer across frames, avoiding
+ *      per-frame allocation churn. Apply to renderer.toneMappingExposure.
  *
  * WebGPU advantage: async readback (no GPU pipeline stall).
  * 1-frame delay is imperceptible for slowly-changing exposure.
@@ -156,15 +160,12 @@ export class AutoExposure extends RenderStage {
 		// from StorageTexture return zeros — must copy to RenderTarget first)
 		this._reductionReadTarget = new RenderTarget( 1, 1, rtOpts );
 
-		// Adaptation StorageTexture (1×1) — compute writes here
-		this._adaptationStorageTex = new StorageTexture( 1, 1 );
-		this._adaptationStorageTex.type = FloatType;
-		this._adaptationStorageTex.format = RGBAFormat;
-		this._adaptationStorageTex.minFilter = NearestFilter;
-		this._adaptationStorageTex.magFilter = NearestFilter;
-
-		// Adaptation target (1×1) — readable copy for async readback
-		this._adaptationTarget = new RenderTarget( 1, 1, rtOpts );
+		// Adaptation result — 1×vec4 storage buffer attribute. Compute writes
+		// vec4(exposure, luminance, targetExposure, 1) here; CPU reads via
+		// getArrayBufferAsync + a pooled ReadbackBuffer (16 bytes).
+		this._adaptationResult = attributeArray( 1, 'vec4' );
+		this._readbackBuffer = new ReadbackBuffer( 16 );
+		this._readbackBuffer.name = 'AutoExposureAdaptation';
 
 	}
 
@@ -351,16 +352,15 @@ export class AutoExposure extends RenderStage {
 	 * Adaptation (compute): temporal smoothing
 	 *
 	 * Single-thread compute dispatch [1, 1, 1], workgroup [1, 1, 1].
-	 * Reads geometric mean from reduction RenderTarget (copied from StorageTexture),
-	 * reads previous adaptation from adaptation RenderTarget,
-	 * applies asymmetric temporal smoothing, writes to adaptation StorageTexture.
-	 *
-	 * Output: R = exposure, G = luminance, B = targetExposure, A = 1
+	 * Reads geometric mean from reduction RenderTarget, applies asymmetric
+	 * temporal smoothing using the previous-exposure uniform, and writes
+	 * vec4(exposure, luminance, targetExposure, 1) into a 1-element storage
+	 * buffer which the CPU reads via getArrayBufferAsync + ReadbackBuffer.
 	 */
 	_buildAdaptationCompute() {
 
 		const reductionTex = this._reductionReadTexNode;
-		const outputTex = this._adaptationStorageTex;
+		const resultBuf = this._adaptationResult;
 		const keyValue = this.keyValueU;
 		const minExp = this.minExposureU;
 		const maxExp = this.maxExposureU;
@@ -381,11 +381,7 @@ export class AutoExposure extends RenderStage {
 				dt, isFirst
 			);
 
-			textureStore(
-				outputTex,
-				uvec2( uint( 0 ), uint( 0 ) ),
-				result
-			).toWriteOnly();
+			resultBuf.element( uint( 0 ) ).assign( result );
 
 		} );
 
@@ -463,22 +459,31 @@ export class AutoExposure extends RenderStage {
 
 		this._reductionReadTexNode.value = this._reductionReadTarget.texture;
 		this.renderer.compute( this._adaptationComputeNode );
-		this.renderer.copyTextureToTexture( this._adaptationStorageTex, this._adaptationTarget.texture );
 
-		// ── Async readback (WebGPU advantage) ────────────
+		// ── Async readback via pooled ReadbackBuffer ─────
+		// getArrayBufferAsync reuses the ReadbackBuffer's internal staging
+		// GPUBuffer across frames. ReadbackBuffer.release() must be called
+		// before it can be reused — the _pendingReadback flag gates reentry.
 
 		if ( ! this._pendingReadback ) {
 
 			this._pendingReadback = true;
 			const generation = this._readbackGeneration;
 
-			this.renderer.readRenderTargetPixelsAsync(
-				this._adaptationTarget, 0, 0, 1, 1
-			).then( ( data ) => {
+			this.renderer.getArrayBufferAsync(
+				this._adaptationResult.value, this._readbackBuffer
+			).then( ( readback ) => {
 
+				// Copy the 4 floats out of the mapped buffer before release(),
+				// because release() nulls readback.buffer and unmaps the GPU buffer.
+				const data = readback && readback.buffer
+					? new Float32Array( readback.buffer.slice( 0 ) )
+					: null;
+				this._readbackBuffer.release();
 				this._pendingReadback = false;
+
 				// Discard stale readback from before a reset
-				if ( generation === this._readbackGeneration ) {
+				if ( data && generation === this._readbackGeneration ) {
 
 					this._applyReadback( data );
 
@@ -486,6 +491,12 @@ export class AutoExposure extends RenderStage {
 
 			} ).catch( () => {
 
+				try {
+
+					this._readbackBuffer.release();
+
+				} catch { /* buffer may not be mapped on error */ }
+
 				this._pendingReadback = false;
 
 			} );
@@ -612,8 +623,7 @@ export class AutoExposure extends RenderStage {
 		this._downsampleStorageTex?.dispose();
 		this._reductionStorageTex?.dispose();
 		this._reductionReadTarget?.dispose();
-		this._adaptationStorageTex?.dispose();
-		this._adaptationTarget?.dispose();
+		this._readbackBuffer?.dispose();
 
 	}
 

package/src/Stages/BilateralFilter.js

@@ -304,8 +304,8 @@ export class BilateralFilter extends RenderStage {
 		// Update dispatch dimensions
 		this._dispatchX = Math.ceil( width / 8 );
 		this._dispatchY = Math.ceil( height / 8 );
-		this._computeNodeA.setCount( [ this._dispatchX, this._dispatchY, 1 ] );
-		this._computeNodeB.setCount( [ this._dispatchX, this._dispatchY, 1 ] );
+		this._computeNodeA.dispatchSize = [ this._dispatchX, this._dispatchY, 1 ];
+		this._computeNodeB.dispatchSize = [ this._dispatchX, this._dispatchY, 1 ];
 
 	}
 

package/src/Stages/Display.js

@@ -111,7 +111,8 @@ export class Display extends RenderStage {
 	dispose() {
 
 		this.displayMaterial?.dispose();
-		this.displayQuad?.dispose();
+		// QuadMesh extends Mesh — no dispose method; material already disposed.
+		this.displayQuad = null;
 
 	}
 

package/src/Stages/EdgeFilter.js

@@ -50,7 +50,9 @@ export class EdgeFilter extends RenderStage {
 
 		// Output StorageTexture (compute writes here)
 		// Pre-allocated at max size — NEVER resize/dispose after this.
-		// StorageTexture.setSize() breaks textureStore bind groups (Three.js bug #32969).
+		// Kept as a defensive pattern: bug #32969 (setSize bind-group staleness)
+		// was fixed in r184 (PR #33028), but #33061 (TSL compute pipeline
+		// re-compile returns zeros) is still open.
 		const MAX_STORAGE_SIZE = 2048;
 		const w = options.width || 1;
 		const h = options.height || 1;
@@ -254,7 +256,8 @@ export class EdgeFilter extends RenderStage {
 	setSize( width, height ) {
 
 		// Only resize the RenderTarget — StorageTexture stays at max allocation
-		// (StorageTexture.setSize() breaks textureStore bind groups, Three.js bug #32969)
+		// (see constructor note: pre-allocation is a defensive pattern, retained
+		// after r184 fixed #32969, because #33061 is still open.)
 		this.outputTarget.setSize( width, height );
 		this.outputTarget.texture.needsUpdate = true;
 		this.resW.value = width;
@@ -263,7 +266,7 @@ export class EdgeFilter 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._computeNode.dispatchSize = [ this._dispatchX, this._dispatchY, 1 ];
 
 	}
 

package/src/Stages/MotionVector.js

@@ -515,13 +515,13 @@ export class MotionVector extends RenderStage {
 		this._dispatchY = Math.ceil( height / 16 );
 		if ( this._screenSpaceComputeNode ) {
 
-			this._screenSpaceComputeNode.setCount( [ this._dispatchX, this._dispatchY, 1 ] );
+			this._screenSpaceComputeNode.dispatchSize = [ this._dispatchX, this._dispatchY, 1 ];
 
 		}
 
 		if ( this._worldSpaceComputeNode ) {
 
-			this._worldSpaceComputeNode.setCount( [ this._dispatchX, this._dispatchY, 1 ] );
+			this._worldSpaceComputeNode.dispatchSize = [ this._dispatchX, this._dispatchY, 1 ];
 
 		}
 

package/src/Stages/NormalDepth.js

@@ -352,7 +352,7 @@ export class NormalDepth extends RenderStage {
 		this._dispatchY = Math.ceil( height / 8 );
 		if ( this._computeNode ) {
 
-			this._computeNode.setCount( [ this._dispatchX, this._dispatchY, 1 ] );
+			this._computeNode.dispatchSize = [ this._dispatchX, this._dispatchY, 1 ];
 
 		}
 

package/src/Stages/PathTracer.js

@@ -1135,9 +1135,6 @@ export class PathTracer extends RenderStage {
 		// Update frame uniform
 		this.frame.value = frameValue;
 
-		// Force-compile compute nodes on first frame
-		this.shaderBuilder.forceCompile( this.renderer );
-
 		// Set dispatch region — tile-only dispatch for tiled mode, full-screen otherwise
 		if ( tileInfo.tileIndex >= 0 && tileInfo.tileBounds ) {
 
@@ -1616,6 +1613,7 @@ export class PathTracer extends RenderStage {
 		this.materialData?.dispose();
 		this.environment?.dispose();
 		this.shaderBuilder?.dispose();
+		this.uniforms?.dispose();
 
 		// Dispose storage textures
 		this.storageTextures?.dispose();

package/src/Stages/SSRC.js

@@ -175,10 +175,10 @@ export class SSRC extends RenderStage {
 		this._dispatchX = Math.ceil( width / 8 );
 		this._dispatchY = Math.ceil( height / 8 );
 
-		const count = [ this._dispatchX, this._dispatchY, 1 ];
-		if ( this._pass1NodeA ) this._pass1NodeA.setCount( count );
-		if ( this._pass1NodeB ) this._pass1NodeB.setCount( count );
-		if ( this._pass2Node ) this._pass2Node.setCount( count );
+		const dispatchSize = [ this._dispatchX, this._dispatchY, 1 ];
+		if ( this._pass1NodeA ) this._pass1NodeA.dispatchSize = dispatchSize;
+		if ( this._pass1NodeB ) this._pass1NodeB.dispatchSize = dispatchSize;
+		if ( this._pass2Node ) this._pass2Node.dispatchSize = dispatchSize;
 
 		this._resetCache();
 

package/src/Stages/Variance.js

@@ -360,8 +360,8 @@ export class Variance extends RenderStage {
 		// Update dispatch dimensions
 		this._dispatchX = Math.ceil( width / 8 );
 		this._dispatchY = Math.ceil( height / 8 );
-		this._computeNodeA.setCount( [ this._dispatchX, this._dispatchY, 1 ] );
-		this._computeNodeB.setCount( [ this._dispatchX, this._dispatchY, 1 ] );
+		this._computeNodeA.dispatchSize = [ this._dispatchX, this._dispatchY, 1 ];
+		this._computeNodeB.dispatchSize = [ this._dispatchX, this._dispatchY, 1 ];
 
 	}
 

package/src/TSL/wgslGlobalVarsPatch.js

@@ -0,0 +1,60 @@
+/**
+ * Monkey-patch to disable WGSL global-variable promotion for compute shaders.
+ *
+ * Three.js r184 introduced `WGSLNodeBuilder.allowGlobalVariables = true` which
+ * emits `.toVar()` declarations at WGSL module scope as `var<private> name : T`
+ * instead of function-local `var name : T` inside `fn main()` (as r183 did).
+ *
+ * For shaders with hundreds of `.toVar()` calls inside loops (e.g. our BVH
+ * traversal + BRDF path tracer), `var<private>` increases GPU register pressure
+ * because the Dawn/Chromium WGSL compiler cannot aggressively register-allocate
+ * variables with a stable per-invocation memory address. We measured a ~8% fps
+ * regression (120 → 110) on the path tracer after upgrading r183 → r184 that
+ * traced entirely to GPU execution, not CPU.
+ *
+ * This patch wraps `WebGPUBackend.createNodeBuilder` so every newly constructed
+ * node builder reports `allowGlobalVariables = false`, restoring r183's
+ * function-scoped `var` emission inside `fn main()`. No behavior change —
+ * WGSL spec guarantees `var<private>` and function-local `var` are semantically
+ * equivalent for per-invocation storage; only the compiler's register-allocation
+ * latitude differs.
+ *
+ * Relevant upstream lines:
+ *  - `node_modules/three/src/renderers/webgpu/nodes/WGSLNodeBuilder.js:247`
+ *    (`this.allowGlobalVariables = true`)
+ *  - `...WGSLNodeBuilder.js:2458` (module-scope vars block)
+ *  - `...WGSLNodeBuilder.js:2467` (function-body vars block)
+ *
+ * Revisit if upstream adds an official opt-out or fixes register pressure.
+ * Import this module once at app startup (side-effect only).
+ */
+
+import { WebGPUBackend } from 'three/webgpu';
+
+const _origCreateNodeBuilder = WebGPUBackend.prototype.createNodeBuilder;
+
+// WGSLNodeBuilder's `allowGlobalVariables` switch is ONLY consumed by the
+// compute-shader template (see `_getWGSLComputeCode`). The vertex/fragment
+// templates always emit `shaderData.vars` at module scope and therefore
+// REQUIRE `allowGlobalVariables=true` (emitting function-local `var` at
+// module scope is invalid WGSL and crashes pipeline creation with
+// "Invalid ShaderModule"). We install a per-instance accessor that returns
+// `false` only when the builder is for a compute node (material === null)
+// and `true` otherwise, so render pipelines keep r184 behavior untouched.
+WebGPUBackend.prototype.createNodeBuilder = function ( object, renderer ) {
+
+	const builder = _origCreateNodeBuilder.call( this, object, renderer );
+
+	Object.defineProperty( builder, 'allowGlobalVariables', {
+		get() {
+
+			return this.material !== null;
+
+		},
+		set() { /* ignore — the value is derived from material presence */ },
+		configurable: true,
+	} );
+
+	return builder;
+
+};

package/src/index.js

@@ -6,7 +6,7 @@
  */
 
 // Patches (side-effect imports — must run before any StorageTexture usage)
-import './TSL/storageTexturePatch.js';
+import './TSL/wgslGlobalVarsPatch.js';
 
 // Main application
 export { PathTracerApp } from './PathTracerApp.js';

package/src/managers/LightManager.js

@@ -255,6 +255,26 @@ export class LightManager extends EventDispatcher {
 
 	}
 
+	/**
+	 * Releases all scene lights, helper nodes, and callback refs.
+	 * Safe to call multiple times.
+	 */
+	dispose() {
+
+		if ( this._disposed ) return;
+		this._disposed = true;
+
+		this.sceneHelpers?.clear();
+		this._removeAllLights();
+
+		// Drop external refs so GC can collect scene/pathTracer
+		this._onReset = null;
+		this.pathTracer = null;
+		this.sceneHelpers = null;
+		this.scene = null;
+
+	}
+
 	// ── Private ───────────────────────────────────────────────────
 
 	/** Syncs helpers in sceneHelpers with current scene lights. */

package/src/managers/UniformManager.js

@@ -265,4 +265,23 @@ export class UniformManager {
 
 	}
 
+	/**
+	 * Releases uniform node references. Safe to call multiple times.
+	 *
+	 * Note: TSL uniform nodes are registered in the shader graph — once a
+	 * compiled pipeline references them they are kept alive by the renderer
+	 * until the pipeline is disposed. Clearing our maps here just drops the
+	 * JS-side strong refs so UniformManager itself can be collected.
+	 */
+	dispose() {
+
+		if ( this._disposed ) return;
+		this._disposed = true;
+
+		this._uniforms.clear();
+		this._booleans.clear();
+		this._lightBuffers = {};
+
+	}
+
 }

package/src/managers/helpers/OutlineHelper.js

@@ -121,7 +121,9 @@ export class OutlineHelper {
 		this.visible = false;
 		this._outlineNode?.dispose();
 		this._material?.dispose();
-		this._quad?.dispose();
+		// QuadMesh extends Mesh — no dispose method on the mesh itself;
+		// its material is already disposed above. Just drop the ref.
+		this._quad = null;
 
 	}