rayzee 5.4.2 → 5.5.0

package/package.json

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

package/src/PathTracerApp.js

@@ -1,4 +1,5 @@
 import { WebGPURenderer, RectAreaLightNode } from 'three/webgpu';
+import { texture as _tslTexture, cubeTexture as _tslCubeTexture } from 'three/tsl';
 import {
 	ACESFilmicToneMapping, Scene, EventDispatcher, TimestampQuery
 } from 'three';
@@ -400,22 +401,100 @@ export class PathTracerApp extends EventDispatcher {
 
 		this.stopAnimation();
 		clearTimeout( this._resizeDebounceTimer );
+		this._resizeDebounceTimer = null;
 
-		// Remove all tracked listeners (app-owned subscriptions across managers/DOM)
 		this._removeTrackedListeners();
-
 		setStatusCallback( null );
 
+		this.interactionManager?.deselect?.();
+		this.transformManager?.detach?.();
+
 		this.animationManager?.dispose();
 		this.transformManager?.dispose();
 		this.overlayManager?.dispose();
-		this._sceneHelpers?.clear();
 		this.lightManager?.dispose();
 		this.denoisingManager?.dispose();
-		this.pipeline?.dispose();
 		this.interactionManager?.dispose();
 		this.cameraManager?.dispose();
+
+		this.pipeline?.dispose();
+
+		// _sdf + assetLoader own the heaviest GPU allocations (material texture arrays,
+		// BVH/triangle buffers, loaded GLTF resources, BVH refit worker, loader caches).
+		// They are not referenced by the pipeline, so pipeline.dispose() does not reach them.
+		this._sdf?.dispose();
+		this._sdf = null;
+
+		this.assetLoader?.dispose();
+		this.assetLoader = null;
+
+		if ( this.meshScene ) {
+
+			this.meshScene.environment?.dispose();
+			this.meshScene.environment = null;
+
+			for ( const child of [ ...this.meshScene.children ] ) {
+
+				disposeObjectFromMemory( child );
+
+			}
+
+			this.meshScene.clear();
+			this.meshScene = null;
+
+		}
+
+		this._sceneHelpers?.clear();
+		this._sceneHelpers = null;
+
+		this.scene?.clear();
+		this.scene = null;
+
+		// Three.js 0.184 leaks (confirmed via heap-snapshot retainer analysis):
+		//
+		//   1) Renderer.dispose() does not remove the 'resize' listener it installs on
+		//      _canvasTarget. The bound handler closes over the renderer, pinning the
+		//      entire WebGPU graph (Backend, Nodes, Bindings, Pipelines, GPUDevice,
+		//      every TSL node) alive indefinitely.
+		//      See three/src/renderers/common/Renderer.js:292 (attach) and
+		//      :2503 (dispose — missing removal).
+		//
+		//   2) Textures manager (one per renderer) registers a per-texture 'dispose'
+		//      listener that closes over `this = Textures` — which transitively
+		//      captures backend → renderer. These listeners are removed only when
+		//      the texture itself is destroyed. For module-level singletons like
+		//      EmptyTexture (new Texture in TextureNode.js) and its CubeTexture
+		//      counterpart, the texture is never destroyed, so every renderer ever
+		//      created leaks through the singleton's listener array.
+		//
+		// Both workarounds are safe when only a single PathTracerApp is active at a
+		// time. If you run multiple in parallel, reset listeners only on the renderer
+		// being disposed (not the shared singletons).
+		if ( this.renderer?._canvasTarget && this.renderer._onCanvasTargetResize ) {
+
+			this.renderer._canvasTarget.removeEventListener(
+				'resize',
+				this.renderer._onCanvasTargetResize
+			);
+
+		}
+
+		try {
+
+			const emptyTex = _tslTexture().value;
+			const emptyCube = _tslCubeTexture().value;
+			if ( emptyTex?._listeners?.dispose ) emptyTex._listeners.dispose.length = 0;
+			if ( emptyCube?._listeners?.dispose ) emptyCube._listeners.dispose.length = 0;
+
+		} catch ( err ) {
+
+			console.warn( 'PathTracerApp: failed to clear TSL texture singleton listeners', err );
+
+		}
+
 		this.renderer?.dispose();
+		if ( this.renderer ) this.renderer._canvasTarget = null;
+		this.renderer = null;
 
 		if ( this._stats ) {
 
@@ -424,6 +503,7 @@ export class PathTracerApp extends EventDispatcher {
 
 		}
 
+		this.stages = {};
 		this.isInitialized = false;
 
 	}
@@ -460,13 +540,9 @@ export class PathTracerApp extends EventDispatcher {
 		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;
-
-		}
+		// Release the loaded model. If loaded via loadObject3D(), the caller owns it —
+		// we only detach it from the scene. Otherwise dispose geometries/materials/textures.
+		this.assetLoader?.releaseTargetModel();
 
 		// Clear lights in the WebGPU light scene
 		this.lightManager?.clearLights?.();
@@ -1111,8 +1187,6 @@ export class PathTracerApp extends EventDispatcher {
 			}
 		} );
 
-		window.renderer = this.renderer; // For debugging
-
 		await this.renderer.init();
 
 		RectAreaLightNode.setLTC( RectAreaLightTexturesLib.init() );

package/src/Processor/AssetLoader.js

@@ -37,6 +37,7 @@ export class AssetLoader extends EventDispatcher {
 		this.camera = camera;
 		this.controls = controls;
 		this.targetModel = null;
+		this._externalModel = null;
 		this.floorPlane = null;
 		this.sceneScale = 1.0;
 		this.loaderCache = {};
@@ -46,6 +47,31 @@ export class AssetLoader extends EventDispatcher {
 
 	}
 
+	/**
+	 * Releases the current targetModel. If it was supplied by the caller via
+	 * loadObject3D(), we only detach it from its parent — the caller still owns
+	 * that Object3D and may reuse it. Otherwise we disposeObjectFromMemory() to
+	 * free geometry/material/texture GPU resources.
+	 */
+	releaseTargetModel() {
+
+		if ( ! this.targetModel ) return;
+
+		if ( this.targetModel === this._externalModel ) {
+
+			this.targetModel.parent?.remove( this.targetModel );
+
+		} else {
+
+			disposeObjectFromMemory( this.targetModel );
+
+		}
+
+		this.targetModel = null;
+		this._externalModel = null;
+
+	}
+
 	setRenderer( renderer ) {
 
 		this.renderer = renderer;
@@ -173,7 +199,11 @@ export class AssetLoader extends EventDispatcher {
 
 			} else {
 
-				const extension = envUrl.split( '.' ).pop().toLowerCase();
+				// Strip query string + fragment before extracting extension, otherwise
+				// URLs like ".../foo.hdr?v=2" get mis-detected and fall through to the
+				// regular TextureLoader, which can't parse HDR/EXR binary data.
+				const cleanPath = envUrl.split( /[?#]/ )[ 0 ];
+				const extension = cleanPath.split( '.' ).pop().toLowerCase();
 				texture = await this.loadEnvironmentByExtension( envUrl, extension );
 
 			}
@@ -479,7 +509,7 @@ export class AssetLoader extends EventDispatcher {
 					loader.parse( gltfContent, '',
 						gltf => {
 
-							if ( this.targetModel ) disposeObjectFromMemory( this.targetModel );
+							this.releaseTargetModel();
 							this.targetModel = gltf.scene;
 							this.onModelLoad( this.targetModel ).then( () => resolve( gltf ) );
 
@@ -522,7 +552,7 @@ export class AssetLoader extends EventDispatcher {
 		const object = objLoader.parse( objContent );
 		object.name = filePath;
 
-		if ( this.targetModel ) disposeObjectFromMemory( this.targetModel );
+		this.releaseTargetModel();
 		this.targetModel = object;
 		await this.onModelLoad( this.targetModel );
 		return object;
@@ -603,7 +633,7 @@ export class AssetLoader extends EventDispatcher {
 		const objContent = strFromU8( objFile.content );
 		const object = objLoader.parse( objContent );
 
-		if ( this.targetModel ) disposeObjectFromMemory( this.targetModel );
+		this.releaseTargetModel();
 		this.targetModel = object;
 		await this.onModelLoad( this.targetModel );
 
@@ -773,7 +803,7 @@ export class AssetLoader extends EventDispatcher {
 			const data = await loader.loadAsync( modelUrl );
 			updateLoading( { status: "Processing Data...", progress: 10 } );
 
-			if ( this.targetModel ) disposeObjectFromMemory( this.targetModel );
+			this.releaseTargetModel();
 
 			this.targetModel = data.scene;
 			this.animations = data.animations || [];
@@ -806,7 +836,7 @@ export class AssetLoader extends EventDispatcher {
 
 			const data = await loader.parseAsync( arrayBuffer, '' );
 
-			if ( this.targetModel ) disposeObjectFromMemory( this.targetModel );
+			this.releaseTargetModel();
 
 			this.targetModel = data.scene;
 			this.animations = data.animations || [];
@@ -845,7 +875,7 @@ export class AssetLoader extends EventDispatcher {
 			}
 
 			const object = this.loaderCache.fbx.parse( arrayBuffer );
-			if ( this.targetModel ) disposeObjectFromMemory( this.targetModel );
+			this.releaseTargetModel();
 			this.targetModel = object;
 
 			updateLoading( { isLoading: true, status: "Processing Data...", progress: 10 } );
@@ -882,7 +912,7 @@ export class AssetLoader extends EventDispatcher {
 			const object = this.loaderCache.obj.parse( contents );
 			object.name = filename;
 
-			if ( this.targetModel ) disposeObjectFromMemory( this.targetModel );
+			this.releaseTargetModel();
 			this.targetModel = object;
 
 			updateLoading( { isLoading: true, status: "Processing Data...", progress: 10 } );
@@ -920,7 +950,7 @@ export class AssetLoader extends EventDispatcher {
 			const mesh = new Mesh( geometry, material );
 			mesh.name = filename;
 
-			if ( this.targetModel ) disposeObjectFromMemory( this.targetModel );
+			this.releaseTargetModel();
 			this.targetModel = mesh;
 
 			updateLoading( { isLoading: true, status: "Processing Data...", progress: 10 } );
@@ -970,7 +1000,7 @@ export class AssetLoader extends EventDispatcher {
 			}
 
 			object.name = filename;
-			if ( this.targetModel ) disposeObjectFromMemory( this.targetModel );
+			this.releaseTargetModel();
 			this.targetModel = object;
 
 			updateLoading( { isLoading: true, status: "Processing Data...", progress: 10 } );
@@ -1007,7 +1037,7 @@ export class AssetLoader extends EventDispatcher {
 			const collada = this.loaderCache.collada.parse( contents );
 			collada.scene.name = filename;
 
-			if ( this.targetModel ) disposeObjectFromMemory( this.targetModel );
+			this.releaseTargetModel();
 			this.targetModel = collada.scene;
 
 			updateLoading( { isLoading: true, status: "Processing Data...", progress: 10 } );
@@ -1042,7 +1072,7 @@ export class AssetLoader extends EventDispatcher {
 
 			const object = this.loaderCache.threemf.parse( arrayBuffer );
 
-			if ( this.targetModel ) disposeObjectFromMemory( this.targetModel );
+			this.releaseTargetModel();
 			this.targetModel = object;
 
 			updateLoading( { isLoading: true, status: "Processing Data...", progress: 10 } );
@@ -1078,7 +1108,7 @@ export class AssetLoader extends EventDispatcher {
 			const object = this.loaderCache.usdz.parse( arrayBuffer );
 			object.name = filename;
 
-			if ( this.targetModel ) disposeObjectFromMemory( this.targetModel );
+			this.releaseTargetModel();
 			this.targetModel = object;
 
 			updateLoading( { isLoading: true, status: "Processing Data...", progress: 10 } );
@@ -1101,8 +1131,9 @@ export class AssetLoader extends EventDispatcher {
 
 		object3d.name = object3d.name || name;
 
-		if ( this.targetModel ) disposeObjectFromMemory( this.targetModel );
+		this.releaseTargetModel();
 		this.targetModel = object3d;
+		this._externalModel = object3d;
 
 		updateLoading( { isLoading: true, status: "Processing Data...", progress: 10 } );
 		await this.onModelLoad( this.targetModel );
@@ -1379,23 +1410,18 @@ export class AssetLoader extends EventDispatcher {
 		}
 
 		this.loaderCache = {};
-		super.dispose(); // Use EventDispatcher's dispose method
-
-		if ( this.targetModel ) {
 
-			disposeObjectFromMemory( this.targetModel );
-			this.targetModel = null;
-
-		}
+		// Three.js EventDispatcher exposes no dispose()/removeAllEventListeners().
+		// Clear the internal listener map directly so handlers don't retain references.
+		this._listeners = undefined;
 
-		console.log( 'AssetLoader resources disposed' );
+		this.releaseTargetModel();
 
 	}
 
 	removeAllEventListeners() {
 
-		// Use EventDispatcher's dispose method for backward compatibility
-		super.dispose();
+		this._listeners = undefined;
 
 	}
 

package/src/Processor/createRenderTargetHelper.js

@@ -206,32 +206,33 @@ export function createRenderTargetHelper( renderer, renderTargetOrTexture, optio
 
 	} );
 
-	window.addEventListener( 'pointermove', ( e ) => {
+	function onPointerMove( e ) {
 
 		if ( ! isDragging ) return;
 
 		const newLeft = e.clientX - dragOffsetX;
 		const newTop = e.clientY - dragOffsetY;
 
-		// Keep within window bounds
 		const maxX = window.innerWidth - container.offsetWidth;
 		const maxY = window.innerHeight - container.offsetHeight;
 
 		container.style.left = `${Math.max( 0, Math.min( newLeft, maxX ) )}px`;
 		container.style.top = `${Math.max( 0, Math.min( newTop, maxY ) )}px`;
 
-		// Reset position properties that would otherwise take precedence
 		container.style.bottom = 'auto';
 		container.style.right = 'auto';
 
-	} );
+	}
 
-	window.addEventListener( 'pointerup', () => {
+	function onPointerUp() {
 
 		isDragging = false;
 		document.body.style.userSelect = '';
 
-	} );
+	}
+
+	window.addEventListener( 'pointermove', onPointerMove );
+	window.addEventListener( 'pointerup', onPointerUp );
 
 	// Optimize resize handling
 	function handleResize() {
@@ -353,19 +354,20 @@ export function createRenderTargetHelper( renderer, renderTargetOrTexture, optio
 
 	};
 
-	// Handle resize events
-	container.addEventListener( 'mousedown', () => {
+	function onContainerMouseDown() {
 
 		window.addEventListener( 'mousemove', handleResize );
 
-	} );
+	}
 
-	window.addEventListener( 'mouseup', () => {
+	function onMouseUp() {
 
 		window.removeEventListener( 'mousemove', handleResize );
 
-	} );
+	}
 
+	container.addEventListener( 'mousedown', onContainerMouseDown );
+	window.addEventListener( 'mouseup', onMouseUp );
 	window.addEventListener( 'resize', handleResize );
 
 	// Auto-update animation frame
@@ -456,20 +458,45 @@ export function createRenderTargetHelper( renderer, renderTargetOrTexture, optio
      */
 	container.dispose = function dispose() {
 
-		if ( config.autoUpdate && animFrameId ) {
+		if ( animFrameId ) {
 
 			cancelAnimationFrame( animFrameId );
+			animFrameId = null;
 
 		}
 
-		// Remove from DOM if attached
+		// Remove window listeners — these close over renderer/renderTarget/container
+		// and pin the entire helper graph alive until the page unloads if not cleaned up.
+		window.removeEventListener( 'pointermove', onPointerMove );
+		window.removeEventListener( 'pointerup', onPointerUp );
+		window.removeEventListener( 'mouseup', onMouseUp );
+		window.removeEventListener( 'mousemove', handleResize );
+		window.removeEventListener( 'resize', handleResize );
+
 		if ( container.parentNode ) {
 
 			container.parentNode.removeChild( container );
 
 		}
 
-		// Clear references
+		// Drop closures attached to the container. These close over `renderer`,
+		// `renderTargetOrTexture`, and the canvas — keeping them around after the
+		// owning stage has been disposed retains the entire Three.js WebGPU graph.
+		container.startAutoUpdate = null;
+		container.stopAutoUpdate = null;
+		container.show = null;
+		container.hide = null;
+		container.toggle = null;
+		container.update = null;
+		container.dispose = null;
+
+		if ( domCanvas ) {
+
+			domCanvas.width = 0;
+			domCanvas.height = 0;
+
+		}
+
 		clampedPixels = null;
 
 	};

package/src/Stages/AdaptiveSampling.js

@@ -485,6 +485,13 @@ export class AdaptiveSampling extends RenderStage {
 		this.heatmapTarget?.dispose();
 		this.helper?.dispose();
 
+		this._computeNode = null;
+		this._heatmapComputeNode = null;
+		this._heatmapStorageTex = null;
+		this._outputStorageTex = null;
+		this.heatmapTarget = null;
+		this.helper = null;
+
 	}
 
 }

package/src/Stages/PathTracer.js

@@ -2,9 +2,9 @@ import { storage } from 'three/tsl';
 import { StorageInstancedBufferAttribute } from 'three/webgpu';
 import {
 	NearestFilter, Vector2, Matrix4,
-	TextureLoader, RepeatWrapping, FloatType
+	TextureLoader, RepeatWrapping
 } from 'three';
-import { blueNoiseTextureNode } from '../TSL/Random.js';
+import { stbnScalarTextureNode, stbnVec2TextureNode } from '../TSL/Random.js';
 
 // Pipeline system
 import { RenderStage, StageExecutionMode } from '../Pipeline/RenderStage.js';
@@ -26,8 +26,9 @@ import { LightSerializer } from '../Processor/LightSerializer';
 // Constants
 import { ENGINE_DEFAULTS as DEFAULT_STATE } from '../EngineDefaults.js';
 
-// Blue noise (loaded at runtime from CDN — not inlined to keep bundle small)
-const blueNoiseImage = 'https://assets.rayzee.atulmourya.com/noise/simple_bluenoise.png';
+// STBN atlases - original source: https://github.com/NVIDIA-RTX/STBN/blob/main/Assets/STBN.zip
+const stbnScalarAtlas = 'https://assets.rayzee.atulmourya.com/noise/stbn_scalar_atlas.png';
+const stbnVec2Atlas = 'https://assets.rayzee.atulmourya.com/noise/stbn_vec2_atlas.png';
 
 /**
  * Data layout constants
@@ -190,8 +191,9 @@ export class PathTracer extends RenderStage {
 		this.spotLightsData = null;
 		this.areaLightsData = null;
 
-		// Blue noise
-		this.blueNoiseTexture = null;
+		// STBN noise textures
+		this.stbnScalarTexture = null;
+		this.stbnVec2Texture = null;
 
 		// Packed light buffer — [lightBVH nodes (4 vec4s each) | emissive triangles (2 vec4s each)]
 		// emissiveVec4Offset uniform tracks the vec4-count offset where emissive data starts.
@@ -376,25 +378,38 @@ export class PathTracer extends RenderStage {
 	}
 
 	/**
-	 * Setup blue noise texture
+	 * Load STBN (Spatiotemporal Blue Noise) atlas textures.
+	 * Each atlas is 1024×1024: 8×8 grid of 128×128 tiles, 64 temporal slices.
 	 */
 	setupBlueNoise() {
 
 		const loader = new TextureLoader();
 		loader.setCrossOrigin( 'anonymous' );
-		loader.load( blueNoiseImage, ( texture ) => {
 
-			texture.minFilter = NearestFilter;
-			texture.magFilter = NearestFilter;
-			texture.wrapS = RepeatWrapping;
-			texture.wrapT = RepeatWrapping;
-			texture.type = FloatType;
-			texture.generateMipmaps = false;
+		const configure = ( tex ) => {
 
-			this.blueNoiseTexture = texture;
-			blueNoiseTextureNode.value = texture;
+			tex.minFilter = NearestFilter;
+			tex.magFilter = NearestFilter;
+			tex.wrapS = RepeatWrapping;
+			tex.wrapT = RepeatWrapping;
+			tex.generateMipmaps = false;
+			return tex;
 
-			console.log( `PathTracer: Blue noise loaded ${texture.image.width}x${texture.image.height}` );
+		};
+
+		loader.load( stbnScalarAtlas, ( tex ) => {
+
+			this.stbnScalarTexture = configure( tex );
+			stbnScalarTextureNode.value = tex;
+			console.log( `PathTracer: STBN scalar atlas loaded ${tex.image.width}x${tex.image.height}` );
+
+		} );
+
+		loader.load( stbnVec2Atlas, ( tex ) => {
+
+			this.stbnVec2Texture = configure( tex );
+			stbnVec2TextureNode.value = tex;
+			console.log( `PathTracer: STBN vec2 atlas loaded ${tex.image.width}x${tex.image.height}` );
 
 		} );
 
@@ -1521,9 +1536,9 @@ export class PathTracer extends RenderStage {
 
 	setBlueNoiseTexture( tex ) {
 
-		this.blueNoiseTexture = tex;
-		// Update the shared Random.js texture node so TSL shader graph uses the real texture
-		if ( tex ) blueNoiseTextureNode.value = tex;
+		// Legacy API — sets the scalar STBN atlas texture
+		this.stbnScalarTexture = tex;
+		if ( tex ) stbnScalarTextureNode.value = tex;
 
 	}
 
@@ -1676,7 +1691,8 @@ export class PathTracer extends RenderStage {
 		this.storageTextures?.dispose();
 
 		// Dispose textures
-		this.blueNoiseTexture?.dispose();
+		this.stbnScalarTexture?.dispose();
+		this.stbnVec2Texture?.dispose();
 		this.placeholderTexture?.dispose();
 
 		// Clear data references

package/src/TSL/LightsDirect.js

@@ -28,12 +28,11 @@ import {
 	texture,
 } from 'three/tsl';
 
-import { Ray, ShadowMaterial, HitInfo, DirectionSample, MaterialCache } from './Struct.js';
+import { Ray, ShadowMaterial, HitInfo } from './Struct.js';
 import { PI, TWO_PI, EPSILON, REC709_LUMINANCE_COEFFICIENTS, powerHeuristic, getShadowMaterial, getDatafromStorageBuffer } from './Common.js';
 import { fresnelSchlickFloat } from './Fresnel.js';
 import { iorToFresnel0 } from './Fresnel.js';
 import {
-	DirectionalLight, AreaLight, PointLight, SpotLight,
 	sampleCone, intersectAreaLight,
 } from './LightsCore.js';
 import { calculateBeerLawAbsorption, calculateShadowTransmittance } from './MaterialTransmission.js';