rayzee 5.4.0 → 5.4.2

package/package.json

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

package/src/PathTracerApp.js

@@ -639,8 +639,7 @@ export class PathTracerApp extends EventDispatcher {
 
 		if ( ! this._sdf.uploadToPathTracer( this.stages.pathTracer, this.lightManager, this.meshScene, environmentTexture ) ) return false;
 
-		// Build per-mesh visibility buffer (must happen before setupMaterial so the
-		// shader graph captures the storage node during compilation)
+		// Patch per-mesh visibility into the TLAS leaves we just uploaded
 		this.stages.pathTracer._meshRefs = this.stages.pathTracer._collectMeshRefs( this.meshScene );
 		this.stages.pathTracer.setMeshVisibilityData( this.stages.pathTracer._meshRefs );
 

package/src/Processor/AssetLoader.js

@@ -472,20 +472,28 @@ export class AssetLoader extends EventDispatcher {
 			const loader = await this.createGLTFLoader();
 			loader.manager = manager;
 
-			return await new Promise( ( resolve, reject ) => {
+			try {
 
-				loader.parse( gltfContent, '',
-					gltf => {
+				return await new Promise( ( resolve, reject ) => {
 
-						if ( this.targetModel ) disposeObjectFromMemory( this.targetModel );
-						this.targetModel = gltf.scene;
-						this.onModelLoad( this.targetModel ).then( () => resolve( gltf ) );
+					loader.parse( gltfContent, '',
+						gltf => {
 
-					},
-					error => reject( error )
-				);
+							if ( this.targetModel ) disposeObjectFromMemory( this.targetModel );
+							this.targetModel = gltf.scene;
+							this.onModelLoad( this.targetModel ).then( () => resolve( gltf ) );
 
-			} );
+						},
+						error => reject( error )
+					);
+
+				} );
+
+			} finally {
+
+				this._disposeGLTFLoader( loader );
+
+			}
 
 		} else {
 
@@ -697,11 +705,10 @@ export class AssetLoader extends EventDispatcher {
 
 	}
 
-	// Model loading methods
+	// Returns a fresh loader each call — DRACOLoader/KTX2Loader hold persistent
+	// worker pools. Callers must invoke _disposeGLTFLoader() to terminate them.
 	async createGLTFLoader() {
 
-		if ( this.loaderCache.gltf ) return this.loaderCache.gltf;
-
 		const dracoLoader = new DRACOLoader();
 		dracoLoader.setDecoderConfig( { type: 'js' } );
 		dracoLoader.setDecoderPath( 'https://www.gstatic.com/draco/v1/decoders/' );
@@ -726,18 +733,23 @@ export class AssetLoader extends EventDispatcher {
 
 		}
 
-		this.loaderCache.ktx2 = ktx2Loader;
-
 		const loader = new GLTFLoader();
 		loader.setDRACOLoader( dracoLoader );
 		loader.setKTX2Loader( ktx2Loader );
 		loader.setMeshoptDecoder( MeshoptDecoder );
 
-		this.loaderCache.gltf = loader;
 		return loader;
 
 	}
 
+	_disposeGLTFLoader( loader ) {
+
+		if ( ! loader ) return;
+		loader.dracoLoader?.dispose();
+		loader.ktx2Loader?.dispose();
+
+	}
+
 	async loadExampleModels( index, modelFiles ) {
 
 		if ( ! modelFiles || ! modelFiles[ index ] ) {
@@ -753,9 +765,10 @@ export class AssetLoader extends EventDispatcher {
 
 	async loadModel( modelUrl ) {
 
+		const loader = await this.createGLTFLoader();
+
 		try {
 
-			const loader = await this.createGLTFLoader();
 			updateLoading( { status: "Loading Model...", progress: 2 } );
 			const data = await loader.loadAsync( modelUrl );
 			updateLoading( { status: "Processing Data...", progress: 10 } );
@@ -774,15 +787,20 @@ export class AssetLoader extends EventDispatcher {
 			this.dispatchEvent( { type: 'error', message: error.message, filename: modelUrl } );
 			throw error;
 
+		} finally {
+
+			this._disposeGLTFLoader( loader );
+
 		}
 
 	}
 
 	async loadGLBFromArrayBuffer( arrayBuffer, filename = 'model.glb' ) {
 
+		const loader = await this.createGLTFLoader();
+
 		try {
 
-			const loader = await this.createGLTFLoader();
 			updateLoading( { isLoading: true, status: "Processing GLB Data...", progress: 5 } );
 			await new Promise( r => setTimeout( r, 0 ) );
 
@@ -804,6 +822,10 @@ export class AssetLoader extends EventDispatcher {
 			this.dispatchEvent( { type: 'error', message: error.message, filename } );
 			throw error;
 
+		} finally {
+
+			this._disposeGLTFLoader( loader );
+
 		}
 
 	}

package/src/Processor/EquirectHDRInfo.js

@@ -220,53 +220,62 @@ export class EquirectHDRInfo {
 
 		const { floatData, width, height } = extractFloatData( hdr );
 
-		// Reuse worker across calls; create on first use
-		if ( ! this._worker ) {
+		// Fresh worker per call — terminated in finally to avoid ~30 MB residency.
+		try {
 
-			try {
+			this._worker = new Worker( CDF_WORKER_URL, { type: 'module' } );
 
-				this._worker = new Worker( CDF_WORKER_URL, { type: 'module' } );
+		} catch ( e ) {
 
-			} catch ( e ) {
+			if ( e.name !== 'SecurityError' ) throw e;
+			this._worker = await fetchAsWorker( CDF_WORKER_URL );
 
-				if ( e.name !== 'SecurityError' ) throw e;
-				this._worker = await fetchAsWorker( CDF_WORKER_URL );
+		}
 
-			}
+		try {
 
-		}
+			const result = await new Promise( ( resolve, reject ) => {
 
-		const result = await new Promise( ( resolve, reject ) => {
+				this._worker.onmessage = ( e ) => {
 
-			this._worker.onmessage = ( e ) => {
+					if ( e.data.error ) {
 
-				if ( e.data.error ) {
+						reject( new Error( e.data.error ) );
 
-					reject( new Error( e.data.error ) );
+					} else {
 
-				} else {
+						resolve( e.data );
 
-					resolve( e.data );
+					}
 
-				}
+				};
 
-			};
+				this._worker.onerror = reject;
 
-			this._worker.onerror = reject;
+				// Transfer floatData to worker (zero-copy)
+				this._worker.postMessage(
+					{ floatData, width, height },
+					[ floatData.buffer ]
+				);
 
-			// Transfer floatData to worker (zero-copy)
-			this._worker.postMessage(
-				{ floatData, width, height },
-				[ floatData.buffer ]
-			);
+			} );
 
-		} );
+			this.marginalData = result.marginalData;
+			this.conditionalData = result.conditionalData;
+			this.totalSum = result.totalSum;
+			this.width = result.width;
+			this.height = result.height;
 
-		this.marginalData = result.marginalData;
-		this.conditionalData = result.conditionalData;
-		this.totalSum = result.totalSum;
-		this.width = result.width;
-		this.height = result.height;
+		} finally {
+
+			if ( this._worker ) {
+
+				this._worker.terminate();
+				this._worker = null;
+
+			}
+
+		}
 
 	}
 

package/src/Processor/GeometryExtractor.js

@@ -618,7 +618,22 @@ export class GeometryExtractor {
 		this.triangleData[ offset + TRIANGLE_DATA_LAYOUT.NORMAL_A_OFFSET + 0 ] = normalA.x;
 		this.triangleData[ offset + TRIANGLE_DATA_LAYOUT.NORMAL_A_OFFSET + 1 ] = normalA.y;
 		this.triangleData[ offset + TRIANGLE_DATA_LAYOUT.NORMAL_A_OFFSET + 2 ] = normalA.z;
-		this.triangleData[ offset + TRIANGLE_DATA_LAYOUT.NORMAL_A_OFFSET + 3 ] = 0; // vec4 padding
+		// Repurposed padding: opaque-blocker fast-path flag for shadow rays.
+		// 1.0 = surface fully blocks light (no alpha, transmission, or transparency) →
+		//       traceShadowRay can skip the 7-slot getShadowMaterial fetch.
+		// 0.0 = requires full material evaluation.
+		{
+
+			const mat = this.materials[ materialIndex ];
+			const isOpaqueBlocker = mat
+				&& ( mat.alphaMode | 0 ) === 0
+				&& ( mat.transparent | 0 ) === 0
+				&& ( mat.transmission || 0 ) === 0
+				&& ( mat.opacity ?? 1 ) >= 1
+				? 1.0 : 0.0;
+			this.triangleData[ offset + TRIANGLE_DATA_LAYOUT.NORMAL_A_OFFSET + 3 ] = isOpaqueBlocker;
+
+		}
 
 		this.triangleData[ offset + TRIANGLE_DATA_LAYOUT.NORMAL_B_OFFSET + 0 ] = normalB.x;
 		this.triangleData[ offset + TRIANGLE_DATA_LAYOUT.NORMAL_B_OFFSET + 1 ] = normalB.y;
@@ -628,7 +643,9 @@ export class GeometryExtractor {
 		this.triangleData[ offset + TRIANGLE_DATA_LAYOUT.NORMAL_C_OFFSET + 0 ] = normalC.x;
 		this.triangleData[ offset + TRIANGLE_DATA_LAYOUT.NORMAL_C_OFFSET + 1 ] = normalC.y;
 		this.triangleData[ offset + TRIANGLE_DATA_LAYOUT.NORMAL_C_OFFSET + 2 ] = normalC.z;
-		this.triangleData[ offset + TRIANGLE_DATA_LAYOUT.NORMAL_C_OFFSET + 3 ] = 0; // vec4 padding
+		// Repurposed padding: per-triangle side flag (0=front, 1=back, 2=double).
+		// Lets BVH traversal do side culling without a material-buffer read per hit.
+		this.triangleData[ offset + TRIANGLE_DATA_LAYOUT.NORMAL_C_OFFSET + 3 ] = this.materials[ materialIndex ]?.side ?? 0;
 
 		// UVs and material index (2 vec4s = 8 floats)
 		// First vec4: uvA.x, uvA.y, uvB.x, uvB.y

package/src/Processor/InstanceTable.js

@@ -57,10 +57,26 @@ export class InstanceTable {
 			worldAABB: null, // Computed from triangle data
 			originalToBvhMap,
 			bvhData,
+			visible: true, // Per-mesh visibility (baked into TLAS leaf slot [2])
+			tlasLeafIndex: - 1, // Set by TLASBuilder.flatten() — enables in-place visibility patching
 		};
 
 	}
 
+	/**
+	 * Set per-mesh visibility flag. Does NOT update the GPU buffer —
+	 * caller must patch combinedBvhData[tlasLeafIndex*16 + 2] and mark bvh attr dirty.
+	 *
+	 * @param {number} meshIndex
+	 * @param {boolean} visible
+	 */
+	setVisibility( meshIndex, visible ) {
+
+		const entry = this.entries[ meshIndex ];
+		if ( entry ) entry.visible = visible;
+
+	}
+
 	/**
 	 * Compute world-space AABBs for all entries from their BLAS root node data.
 	 * O(1) per mesh for inner roots; falls back to triangle scan for leaf roots (rare).

package/src/Processor/SceneProcessor.js

@@ -476,48 +476,36 @@ export class SceneProcessor {
 
 			const validEntries = this.instanceTable.entries.filter( e => e !== null );
 
-			if ( validEntries.length === 1 ) {
-
-				// Single mesh — use BLAS directly as flat BVH (no TLAS wrapper).
-				// Avoids per-ray TLAS overhead and the extra branch in traversal.
-				const entry = validEntries[ 0 ];
-				this.bvhData = entry.bvhData;
-				this.instanceTable.assignOffsets( 0 ); // BLAS at offset 0
-				this._buildGlobalOriginalToBvhMap();
-				entry.originalToBvhMap = null;
-				entry.bvhData = null;
-
-			} else {
-
-				// Multi-mesh — build TLAS over mesh AABBs
-				this.instanceTable.computeAABBs( this.triangleData );
-				const { root: tlasRoot, nodeCount: tlasNodeCount } = this.tlasBuilder.build( validEntries );
+			// Always build a TLAS — even for a single mesh — so the BLAS-pointer leaf
+			// carries packed per-mesh visibility in its slot [2]. The 1-node TLAS
+			// overhead (one extra leaf fetch per ray) is negligible and eliminates
+			// a dedicated visibility storage buffer binding.
+			this.instanceTable.computeAABBs( this.triangleData );
+			const { root: tlasRoot, nodeCount: tlasNodeCount } = this.tlasBuilder.build( validEntries );
 
-				this.instanceTable.assignOffsets( tlasNodeCount );
-				const totalNodes = this.instanceTable.totalNodeCount;
+			this.instanceTable.assignOffsets( tlasNodeCount );
+			const totalNodes = this.instanceTable.totalNodeCount;
 
-				const tlasData = this.tlasBuilder.flatten( tlasRoot, validEntries );
+			const tlasData = this.tlasBuilder.flatten( tlasRoot, validEntries );
 
-				// Assemble combined buffer: [TLAS][BLAS_0][BLAS_1]...[BLAS_M]
-				this.bvhData = new Float32Array( totalNodes * 16 );
-				this.bvhData.set( tlasData );
+			// Assemble combined buffer: [TLAS][BLAS_0][BLAS_1]...[BLAS_M]
+			this.bvhData = new Float32Array( totalNodes * 16 );
+			this.bvhData.set( tlasData );
 
-				for ( const entry of validEntries ) {
+			for ( const entry of validEntries ) {
 
-					const destOffset = entry.blasOffset * 16;
-					this.bvhData.set( entry.bvhData, destOffset );
-					this._offsetBLASInPlace( destOffset, entry.bvhData.length / 16, entry.blasOffset, entry.triOffset );
+				const destOffset = entry.blasOffset * 16;
+				this.bvhData.set( entry.bvhData, destOffset );
+				this._offsetBLASInPlace( destOffset, entry.bvhData.length / 16, entry.blasOffset, entry.triOffset );
 
-				}
-
-				this._buildGlobalOriginalToBvhMap();
+			}
 
-				for ( const entry of validEntries ) {
+			this._buildGlobalOriginalToBvhMap();
 
-					entry.originalToBvhMap = null;
-					entry.bvhData = null;
+			for ( const entry of validEntries ) {
 
-				}
+				entry.originalToBvhMap = null;
+				entry.bvhData = null;
 
 			}
 
@@ -1384,6 +1372,7 @@ export class SceneProcessor {
 		}
 
 		pathTracer.setBVHData( this.bvhData );
+		pathTracer.setInstanceTable( this.instanceTable );
 
 		if ( this.materialData ) {
 

package/src/Processor/ShaderBuilder.js

@@ -16,7 +16,6 @@ import { Fn, texture, vec2, float, int, uniform, If,
 import { TextureNode } from 'three/webgpu';
 import { LinearFilter, DataArrayTexture } from 'three';
 import { pathTracerMain } from '../TSL/PathTracer.js';
-import { setMeshVisibilityBuffer } from '../TSL/BVHTraversal.js';
 import { setShadowAlbedoMaps, setAlphaShadowsUniform } from '../TSL/LightsDirect.js';
 import { BuildTimer } from './BuildTimer.js';
 
@@ -234,11 +233,9 @@ export class ShaderBuilder {
 		const triStorage = stage.triangleStorageNode;
 		const bvhStorage = stage.bvhStorageNode;
 		const matStorage = stage.materialData.materialStorageNode;
-		const emissiveTriStorage = stage.emissiveTriangleStorageNode;
-		const lightBVHStorage = stage.lightBVHStorageNode;
-
-		// Set per-mesh visibility buffer (module-level in BVHTraversal.js, read during graph construction)
-		setMeshVisibilityBuffer( stage.meshVisibilityStorageNode );
+		// Packed light buffer — [lightBVH | emissive triangles]. One node fed to both
+		// TSL params; emissive reads offset by stage.emissiveVec4Offset.
+		const lightBufferStorage = stage.lightStorageNode;
 
 		// Set alpha-shadow uniform (module-level in LightsDirect.js, read at runtime)
 		setAlphaShadowsUniform( stage.uniforms.get( 'enableAlphaShadows' ) );
@@ -249,9 +246,9 @@ export class ShaderBuilder {
 		const adaptiveSamplingTex = new TextureNode();
 		this.adaptiveSamplingTexNode = adaptiveSamplingTex;
 
-		// Environment importance sampling CDF (storage buffers)
-		const marginalCDFStorage = stage.environment.envMarginalStorageNode;
-		const conditionalCDFStorage = stage.environment.envConditionalStorageNode;
+		// Environment importance sampling CDF — packed storage buffer
+		// Layout: [marginal (envResolution.y floats) | conditional (envResolution.x * envResolution.y floats)]
+		const envCDFStorage = stage.environment.envCDFStorageNode;
 
 		// Previous-frame texture nodes — initialized from readTarget textures
 		const readTextures = storageTextures.getReadTextures();
@@ -285,8 +282,8 @@ export class ShaderBuilder {
 		setShadowAlbedoMaps( albedoMapsTex );
 
 		const result = {
-			triStorage, bvhStorage, matStorage, emissiveTriStorage, lightBVHStorage,
-			envTex, adaptiveSamplingTex, marginalCDFStorage, conditionalCDFStorage,
+			triStorage, bvhStorage, matStorage, lightBufferStorage,
+			envTex, adaptiveSamplingTex, envCDFStorage,
 			albedoMapsTex, normalMapsTex, bumpMapsTex,
 			metalnessMapsTex, roughnessMapsTex, emissiveMapsTex, displacementMapsTex,
 		};
@@ -304,8 +301,8 @@ export class ShaderBuilder {
 		writeColorTex, writeNDTex, writeAlbedoTex ) {
 
 		const {
-			triStorage, bvhStorage, matStorage, emissiveTriStorage, lightBVHStorage,
-			envTex, adaptiveSamplingTex, marginalCDFStorage, conditionalCDFStorage,
+			triStorage, bvhStorage, matStorage, lightBufferStorage,
+			envTex, adaptiveSamplingTex, envCDFStorage,
 			albedoMapsTex, normalMapsTex, bumpMapsTex,
 			metalnessMapsTex, roughnessMapsTex, emissiveMapsTex, displacementMapsTex,
 		} = textureNodes;
@@ -366,8 +363,7 @@ export class ShaderBuilder {
 					envTexture: envTex,
 					environmentIntensity: stage.environmentIntensity,
 					envMatrix: stage.environmentMatrix,
-					envMarginalWeights: marginalCDFStorage,
-					envConditionalWeights: conditionalCDFStorage,
+					envCDFBuffer: envCDFStorage,
 					envTotalSum: stage.envTotalSum,
 					envResolution: stage.envResolution,
 					enableEnvironmentLight: stage.enableEnvironment,
@@ -381,11 +377,12 @@ export class ShaderBuilder {
 					globalIlluminationIntensity: stage.globalIlluminationIntensity,
 					totalTriangleCount: stage.totalTriangleCount,
 					enableEmissiveTriangleSampling: stage.enableEmissiveTriangleSampling,
-					emissiveTriangleBuffer: emissiveTriStorage,
+					emissiveTriangleBuffer: lightBufferStorage,
 					emissiveTriangleCount: stage.emissiveTriangleCount,
 					emissiveTotalPower: stage.emissiveTotalPower,
 					emissiveBoost: stage.emissiveBoost,
-					lightBVHBuffer: lightBVHStorage,
+					emissiveVec4Offset: stage.emissiveVec4Offset,
+					lightBVHBuffer: lightBufferStorage,
 					lightBVHNodeCount: stage.lightBVHNodeCount,
 					debugVisScale: stage.debugVisScale,
 					enableAccumulation: stage.enableAccumulation,

package/src/Processor/TLASBuilder.js

@@ -199,10 +199,13 @@ export class TLASBuilder {
 	/**
 	 * Flatten TLAS tree into Float32Array.
 	 * Inner nodes: same format as BVH.
-	 * Leaf nodes: [blasRootNodeIndex, 0, 0, -2] (BLAS-pointer marker).
+	 * Leaf nodes: [blasRootNodeIndex, meshIndex, visibility, -2] (BLAS-pointer marker).
+	 *
+	 * Side effect: records each entry's flat leaf index on `entry.tlasLeafIndex` so that
+	 * visibility can later be patched in place (combinedBvhData[tlasLeafIndex*16 + 2]).
 	 *
 	 * @param {TLASNode} root
-	 * @param {Array<{blasOffset: number}>} entries - Instance table entries with assigned blasOffsets
+	 * @param {Array<{blasOffset: number, visible: boolean, tlasLeafIndex: number}>} entries
 	 * @returns {Float32Array}
 	 */
 	flatten( root, entries ) {
@@ -268,10 +271,12 @@ export class TLASBuilder {
 				// Leaf node — BLAS pointer
 				const entry = entries[ n.entryIndex ];
 				data[ o ] = entry.blasOffset; // Absolute node index of BLAS root in combined buffer
-				data[ o + 1 ] = n.entryIndex; // meshIndex for per-mesh visibility check
-				// data[o+2] = 0
+				data[ o + 1 ] = n.entryIndex; // meshIndex (kept for debug/ID — traversal uses slot [2])
+				data[ o + 2 ] = entry.visible === false ? 0.0 : 1.0; // Per-mesh visibility (packed — frees a binding)
 				data[ o + 3 ] = BVH_LEAF_MARKERS.BLAS_POINTER_LEAF; // -2 marker
 
+				entry.tlasLeafIndex = i;
+
 			}
 
 		}