rayzee 5.3.8 → 5.4.1

package/src/TSL/PathTracerCore.js

@@ -41,7 +41,7 @@ import {
 	sampler,
 } from 'three/tsl';
 
-import { struct } from './structProxy.js';
+import { struct } from './patches.js';
 
 import {
 	PI_INV,
@@ -590,7 +590,7 @@ export const Trace = Fn( ( [
 	spotLightsBuffer, numSpotLights,
 	// Environment
 	envTexture, environmentIntensity, envMatrix,
-	envMarginalWeights, envConditionalWeights,
+	envCDFBuffer,
 	envTotalSum, envResolution,
 	enableEnvironmentLight, useEnvMapIS,
 	// Rendering parameters
@@ -598,7 +598,7 @@ export const Trace = Fn( ( [
 	backgroundIntensity, showBackground, transparentBackground,
 	fireflyThreshold, globalIlluminationIntensity,
 	totalTriangleCount, enableEmissiveTriangleSampling,
-	emissiveTriangleBuffer, emissiveTriangleCount, emissiveTotalPower, emissiveBoost,
+	emissiveTriangleBuffer, emissiveVec4Offset, emissiveTriangleCount, emissiveTotalPower, emissiveBoost,
 	lightBVHBuffer, lightBVHNodeCount,
 	// Per-pixel info
 	pixelCoord, resolution, frame,
@@ -1013,7 +1013,7 @@ export const Trace = Fn( ( [
 			triangleBuffer,
 			materialBuffer,
 			envTexture, environmentIntensity, envMatrix,
-			envMarginalWeights, envConditionalWeights,
+			envCDFBuffer,
 			envTotalSum, envResolution,
 			enableEnvironmentLight,
 		);
@@ -1040,6 +1040,7 @@ export const Trace = Fn( ( [
 					rngState,
 					lightBVHBuffer,
 					emissiveTriangleBuffer,
+					emissiveVec4Offset,
 					triangleBuffer,
 				) );
 
@@ -1091,7 +1092,7 @@ export const Trace = Fn( ( [
 					hitInfo.hitPoint, N, V, material,
 					totalTriangleCount, bounceIndex, rngState,
 					emissiveBoost,
-					emissiveTriangleBuffer, emissiveTriangleCount, emissiveTotalPower,
+					emissiveTriangleBuffer, emissiveVec4Offset, emissiveTriangleCount, emissiveTotalPower,
 					triangleBuffer,
 					traceShadowRayWrapped,
 					evaluateMaterialResponse,
@@ -1132,7 +1133,6 @@ export const Trace = Fn( ( [
 			rngState,
 			samplingInfo,
 			envTexture, environmentIntensity, envMatrix,
-			envMarginalWeights, envConditionalWeights,
 			envTotalSum, envResolution,
 			enableEnvironmentLight, useEnvMapIS,
 		) );

package/src/TSL/Struct.js

@@ -1,4 +1,4 @@
-import { struct } from './structProxy.js';
+import { struct } from './patches.js';
 
 export const Ray = struct( {
 	origin: 'vec3',

package/src/TSL/patches.js

@@ -0,0 +1,145 @@
+/**
+ * Rayzee patches for Three.js / TSL.
+ *
+ * Side-effect on import: installs `WebGPUBackend.createNodeBuilder` override
+ * (restores r183 function-scoped `var` emission for compute shaders — prevents
+ * a register-allocation regression in the path tracer's hot loop).
+ *
+ * Export: `struct()` — drop-in replacement for TSL's `struct()` returning
+ * a proxy factory that supports GLSL-style dot-notation field access.
+ */
+
+import { WebGPUBackend } from 'three/webgpu';
+import { struct as _struct } from 'three/tsl';
+
+// ---------------------------------------------------------------------------
+// 1. WGSL global-variable promotion patch (compute-only)
+// ---------------------------------------------------------------------------
+// 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 compute shaders with hundreds of `.toVar()` calls in loops (e.g. the 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.
+//
+// `allowGlobalVariables` is ONLY consumed by the compute template
+// (`_getWGSLComputeCode`). The vertex/fragment templates always emit
+// `shaderData.vars` at module scope and 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.
+//
+// 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.
+
+const _origCreateNodeBuilder = WebGPUBackend.prototype.createNodeBuilder;
+
+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;
+
+};
+
+// ---------------------------------------------------------------------------
+// 2. TSL struct proxy — enables GLSL-style dot-notation field access
+// ---------------------------------------------------------------------------
+// TSL structs require `.get('fieldName')` for member access, but GLSL-style
+// dot notation (`.fieldName`) is more natural and matches ported code.
+//
+// This wraps TSL's `struct()` so that:
+//  - Direct construction: `MyStruct({...}).toVar('x')` → `.fieldName` works
+//  - Fn return values:    `MyStruct.wrap(someFn(...))` → `.fieldName` works
+//
+// Property access for known struct member names is redirected to `.get('name')`.
+// Swizzle properties (x, y, z, w, etc.), Node methods (.add, .assign, etc.), and
+// other standard properties pass through to the underlying node unmodified.
+
+function createStructProxy( node, memberSet ) {
+
+	return new Proxy( node, {
+
+		get( target, prop, receiver ) {
+
+			// Intercept known struct member names
+			if ( typeof prop === 'string' && memberSet.has( prop ) ) {
+
+				return target.get( prop );
+
+			}
+
+			const val = Reflect.get( target, prop, receiver );
+
+			// Intercept .toVar() to proxy-wrap the result
+			if ( prop === 'toVar' && typeof val === 'function' ) {
+
+				return ( ...args ) => createStructProxy( val.apply( target, args ), memberSet );
+
+			}
+
+			return val;
+
+		}
+
+	} );
+
+}
+
+/**
+ * Drop-in replacement for TSL's `struct()` that returns a proxy-enhanced factory.
+ *
+ * The returned factory:
+ *  - Creates struct nodes where `.toVar()` results support dot-notation field access
+ *  - Has `.wrap(node)` method to proxy-wrap Fn return values for field access
+ *  - Has `.layout` and `.isStruct` matching the original TSL struct API
+ *
+ * @param {Object} members - Struct member layout (e.g., { didHit: 'bool', dst: 'float' })
+ * @param {string|null} name - Optional struct name
+ * @returns {Function} Enhanced struct factory
+ */
+export function struct( members, name = null ) {
+
+	const factory = _struct( members, name );
+	const memberSet = new Set( Object.keys( members ) );
+
+	const wrappedFactory = ( ...args ) => {
+
+		const node = factory( ...args );
+		return createStructProxy( node, memberSet );
+
+	};
+
+	wrappedFactory.layout = factory.layout;
+	wrappedFactory.isStruct = true;
+
+	/**
+	 * Wrap an existing node (e.g., Fn return value) with struct field access proxy.
+	 * Usage: `const hit = HitInfo.wrap(traverseBVH(...).toVar('hit'));`
+	 */
+	wrappedFactory.wrap = ( node ) => createStructProxy( node, memberSet );
+
+	return wrappedFactory;
+
+}

package/src/index.js

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

package/src/managers/EnvironmentManager.js

@@ -43,11 +43,11 @@ export class EnvironmentManager {
 		this.environmentTexture = this._envPlaceholder;
 		this.envTexSize = new Vector2();
 
-		// CDF storage buffers
-		this.envMarginalStorageAttr = null;
-		this.envMarginalStorageNode = null;
-		this.envConditionalStorageAttr = null;
-		this.envConditionalStorageNode = null;
+		// CDF storage buffer (marginal + conditional packed into one buffer).
+		// Layout: [ marginal (envResolution.y floats) | conditional (envResolution.x * envResolution.y floats) ]
+		// Conditional offset is the marginal length, which equals envResolution.y at runtime.
+		this.envCDFStorageAttr = null;
+		this.envCDFStorageNode = null;
 		this._initCDFStorageBuffers();
 
 		// Environment rotation
@@ -177,74 +177,52 @@ export class EnvironmentManager {
 
 	}
 
-	// ===== CDF STORAGE BUFFERS =====
+	// ===== CDF STORAGE BUFFER =====
 
 	/**
-	 * Initialize CDF storage buffers with placeholder data.
-	 * Must be called before shader compilation so the nodes exist in the graph.
+	 * Initialize the packed CDF storage buffer with placeholder data.
+	 * Must be called before shader compilation so the node exists in the graph.
+	 *
+	 * Layout: [ marginal (size = envResolution.y) | conditional (size = envResolution.x * envResolution.y) ]
+	 * Placeholder shape is a 1x2 env map: marginal=[0,1], conditional=[0,0,1,1].
 	 * @private
 	 */
 	_initCDFStorageBuffers() {
 
-		// Marginal: 1 float per entry, default placeholder
-		const marginalPlaceholder = new Float32Array( [ 0, 1 ] );
-		this.envMarginalStorageAttr = new StorageInstancedBufferAttribute( marginalPlaceholder, 1 );
-		this.envMarginalStorageNode = storage( this.envMarginalStorageAttr, 'float', 2 ).toReadOnly();
-
-		// Conditional: 1 float per entry, default placeholder
-		const conditionalPlaceholder = new Float32Array( [ 0, 0, 1, 1 ] );
-		this.envConditionalStorageAttr = new StorageInstancedBufferAttribute( conditionalPlaceholder, 1 );
-		this.envConditionalStorageNode = storage( this.envConditionalStorageAttr, 'float', 4 ).toReadOnly();
-
-	}
-
-	/**
-	 * Update marginal CDF storage buffer from Float32Array.
-	 */
-	setEnvMarginalData( floatData ) {
-
-		if ( ! floatData ) return;
-
-		this.envMarginalStorageAttr = new StorageInstancedBufferAttribute( floatData, 1 );
-		this.envMarginalStorageNode.value = this.envMarginalStorageAttr;
-		this.envMarginalStorageNode.bufferCount = floatData.length;
-
-	}
-
-	/**
-	 * Update conditional CDF storage buffer from Float32Array.
-	 */
-	setEnvConditionalData( floatData ) {
-
-		if ( ! floatData ) return;
-
-		this.envConditionalStorageAttr = new StorageInstancedBufferAttribute( floatData, 1 );
-		this.envConditionalStorageNode.value = this.envConditionalStorageAttr;
-		this.envConditionalStorageNode.bufferCount = floatData.length;
+		const placeholder = new Float32Array( [ 0, 1, 0, 0, 1, 1 ] );
+		this.envCDFStorageAttr = new StorageInstancedBufferAttribute( placeholder, 1 );
+		this.envCDFStorageNode = storage( this.envCDFStorageAttr, 'float', placeholder.length ).toReadOnly();
 
 	}
 
 	/**
-	 * Update both CDF storage buffers from equirectHdrInfo.
+	 * Update the packed CDF storage buffer from equirectHdrInfo.
+	 * Concatenates marginal + conditional into one buffer.
 	 * @private
 	 */
 	_updateCDFStorageBuffers() {
 
-		this.setEnvMarginalData( this.equirectHdrInfo.marginalData );
-		this.setEnvConditionalData( this.equirectHdrInfo.conditionalData );
+		const marginal = this.equirectHdrInfo.marginalData;
+		const conditional = this.equirectHdrInfo.conditionalData;
+		if ( ! marginal || ! conditional ) return;
+
+		const combined = new Float32Array( marginal.length + conditional.length );
+		combined.set( marginal, 0 );
+		combined.set( conditional, marginal.length );
+
+		this.envCDFStorageAttr = new StorageInstancedBufferAttribute( combined, 1 );
+		this.envCDFStorageNode.value = this.envCDFStorageAttr;
+		this.envCDFStorageNode.bufferCount = combined.length;
 
 	}
 
 	/**
-	 * Get CDF storage nodes for shader graph.
-	 * @returns {{ marginalNode: StorageNode, conditionalNode: StorageNode }}
+	 * Get the packed CDF storage node for shader graph.
+	 * @returns {{ cdfNode: StorageNode }}
 	 */
 	getCDFStorageNodes() {
 
-		return {
-			marginalNode: this.envMarginalStorageNode,
-			conditionalNode: this.envConditionalStorageNode,
-		};
+		return { cdfNode: this.envCDFStorageNode };
 
 	}
 
@@ -559,10 +537,8 @@ export class EnvironmentManager {
 
 		this.proceduralSkyRenderer = null;
 		this.simpleSkyRenderer = null;
-		this.envMarginalStorageAttr = null;
-		this.envMarginalStorageNode = null;
-		this.envConditionalStorageAttr = null;
-		this.envConditionalStorageNode = null;
+		this.envCDFStorageAttr = null;
+		this.envCDFStorageNode = null;
 		this._envPlaceholder?.dispose();
 		this._envPlaceholder = null;
 		this.environmentTexture = null;

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

@@ -237,6 +237,9 @@ export class UniformManager {
 		u( 'emissiveTriangleCount', 0, 'int' );
 		u( 'emissiveTotalPower', 0.0, 'float' );
 		u( 'lightBVHNodeCount', 0, 'int' );
+		// Offset (in vec4 elements) within the packed light buffer where emissive
+		// triangle data starts. Equals lightBVHNodeCount * LBVH_STRIDE; computed on upload.
+		u( 'emissiveVec4Offset', 0, 'int' );
 
 		// Render mode
 		u( 'renderMode', DEFAULT_STATE.renderMode, 'int' );
@@ -265,4 +268,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;
 
 	}
 

package/src/TSL/storageTexturePatch.js

@@ -1,31 +0,0 @@
-/**
- * Monkey-patch for Three.js StorageTexture.setSize() bind group staleness.
- *
- * Bug: StorageTexture.setSize() calls dispose() but never sets needsUpdate = true.
- * The Bindings system tracks texture.version (incremented by needsUpdate setter)
- * to detect when bind groups need recreation. Without the version bump, the bind
- * group keeps referencing the destroyed GPUTextureView → writes silently fail.
- *
- * Three.js issue: https://github.com/mrdoob/three.js/issues/32969
- * Targeted fix: r184+ (2026-03-25)
- *
- * Import this module once at app startup (side-effect only).
- */
-
-import { StorageTexture } from 'three/webgpu';
-
-const _origSetSize = StorageTexture.prototype.setSize;
-
-StorageTexture.prototype.setSize = function ( width, height ) {
-
-	const wasChanged = this.image.width !== width || this.image.height !== height;
-
-	_origSetSize.call( this, width, height );
-
-	if ( wasChanged ) {
-
-		this.needsUpdate = true;
-
-	}
-
-};

package/src/TSL/structProxy.js

@@ -1,87 +0,0 @@
-/**
- * Proxy-enhanced struct factory for TSL.
- *
- * TSL structs require `.get('fieldName')` for member access, but GLSL-style
- * dot notation (`.fieldName`) is more natural and matches the ported code.
- *
- * This utility wraps TSL's `struct()` so that:
- * - Direct construction: `MyStruct({...}).toVar('x')` → `.fieldName` works automatically
- * - Fn return values: `MyStruct.wrap(someFn(...))` → `.fieldName` works automatically
- *
- * Internally, property access for known struct member names is redirected to `.get('name')`.
- * Swizzle properties (x, y, z, w, etc.), Node methods (.add, .assign, etc.), and other
- * standard properties pass through to the underlying node unmodified.
- */
-
-import { struct as _struct } from 'three/tsl';
-
-/**
- * Creates a Proxy around a TSL node that redirects struct member access to `.get('name')`.
- * Also intercepts `.toVar()` to ensure the resulting VarNode is also proxy-wrapped.
- */
-function createStructProxy( node, memberSet ) {
-
-	return new Proxy( node, {
-
-		get( target, prop, receiver ) {
-
-			// Intercept known struct member names
-			if ( typeof prop === 'string' && memberSet.has( prop ) ) {
-
-				return target.get( prop );
-
-			}
-
-			const val = Reflect.get( target, prop, receiver );
-
-			// Intercept .toVar() to proxy-wrap the result
-			if ( prop === 'toVar' && typeof val === 'function' ) {
-
-				return ( ...args ) => createStructProxy( val.apply( target, args ), memberSet );
-
-			}
-
-			return val;
-
-		}
-
-	} );
-
-}
-
-/**
- * Drop-in replacement for TSL's `struct()` that returns a proxy-enhanced factory.
- *
- * The returned factory:
- * - Creates struct nodes where `.toVar()` results support dot-notation field access
- * - Has `.wrap(node)` method to proxy-wrap Fn return values for field access
- * - Has `.layout` and `.isStruct` matching the original TSL struct API
- *
- * @param {Object} members - Struct member layout (e.g., { didHit: 'bool', dst: 'float' })
- * @param {string|null} name - Optional struct name
- * @returns {Function} Enhanced struct factory
- */
-export function struct( members, name = null ) {
-
-	const factory = _struct( members, name );
-	const memberSet = new Set( Object.keys( members ) );
-
-	const wrappedFactory = ( ...args ) => {
-
-		const node = factory( ...args );
-		return createStructProxy( node, memberSet );
-
-	};
-
-	wrappedFactory.layout = factory.layout;
-	wrappedFactory.isStruct = true;
-
-	/**
-	 * Wrap an existing node (e.g., Fn return value) with struct field access proxy.
-	 * Usage: `const hit = HitInfo.wrap(traverseBVH(...).toVar('hit'));`
-	 */
-	wrappedFactory.wrap = ( node ) => createStructProxy( node, memberSet );
-
-	return wrappedFactory;
-
-}