rayzee 7.7.0 → 7.9.0

package/package.json

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

package/src/EngineDefaults.js

@@ -492,9 +492,53 @@ export const TEXTURE_CONSTANTS = {
 	// guaranteed minimum). The configurable maxTextureSize setting is clamped to this.
 	MAX_TEXTURE_SIZE: 8192,
 	// Default cap applied when no maxTextureSize is supplied (engine standalone use).
-	DEFAULT_MAX_TEXTURE_SIZE: 4096
+	DEFAULT_MAX_TEXTURE_SIZE: 4096,
+	// Max layers (textures) per bucket array. Also the packing stride for (bucket, layer).
+	MAX_TEXTURES_LIMIT: 128,
+	// Size buckets per colorSpace pool. Material maps are grouped into this many
+	// longest-edge size classes so a small map no longer pays a large neighbour's
+	// footprint. 4 → ~8 bound material arrays (4 sRGB + 4 linear).
+	MATERIAL_BUCKET_COUNT: 4,
+	// Packing stride: a map's stored index encodes bucketId * BUCKET_LAYER_STRIDE + layer.
+	// Also the per-bucket layer cap. Kept at the WebGPU portable maxTextureArrayLayers floor (256)
+	// so a consolidated bucket (which merges several map types of one size) stays portable.
+	BUCKET_LAYER_STRIDE: 256,
 };
 
+// Longest-edge size ladder for a given cap, ascending.
+// cap=4096, count=4 → [512, 1024, 2048, 4096].
+export function getTextureBucketSizes( maxTextureSize, count = TEXTURE_CONSTANTS.MATERIAL_BUCKET_COUNT ) {
+
+	const sizes = [];
+	for ( let i = count - 1; i >= 0; i -- ) {
+
+		sizes.push( Math.max( TEXTURE_CONSTANTS.MIN_TEXTURE_WIDTH, Math.round( maxTextureSize / Math.pow( 2, i ) ) ) );
+
+	}
+
+	return sizes;
+
+}
+
+// Bucket index for a texture, by its power-of-2 longest edge vs the cap's ladder.
+// Larger-than-cap maps land in the top bucket (downscaled to cap, as before).
+export function getTextureBucketId( width, height, maxTextureSize, count = TEXTURE_CONSTANTS.MATERIAL_BUCKET_COUNT ) {
+
+	const longest = Math.max( width || 1, height || 1 );
+	const pot = Math.pow( 2, Math.ceil( Math.log2( longest ) ) );
+	const sizes = getTextureBucketSizes( maxTextureSize, count );
+	for ( let i = 0; i < sizes.length; i ++ ) if ( pot <= sizes[ i ] ) return i;
+	return sizes.length - 1;
+
+}
+
+// Pack (bucketId, layer) into the single int slot a material map index occupies.
+export function packTextureIndex( bucketId, layer ) {
+
+	return bucketId * TEXTURE_CONSTANTS.BUCKET_LAYER_STRIDE + layer;
+
+}
+
 // Default texture matrix for materials
 export const DEFAULT_TEXTURE_MATRIX = [ 0, 0, 1, 1, 0, 0, 0, 1 ];
 

package/src/EngineEvents.js

@@ -54,4 +54,5 @@ export const EngineEvents = {
 
 	// Lifecycle
 	DISPOSE: 'engine:dispose',
+	DEVICE_LOST: 'engine:deviceLost',
 };

package/src/Passes/OIDNDenoiser.js

@@ -142,6 +142,9 @@ export class OIDNDenoiser extends EventDispatcher {
 
 		this.currentTZAUrl = null;
 		this.unet = null;
+		// A start() requested while the UNet is still loading is deferred here and fired
+		// once loading finishes, instead of being silently dropped.
+		this._pendingStart = false;
 
 		// Initialize asynchronously
 		this._initialize().catch( error => {
@@ -257,6 +260,15 @@ export class OIDNDenoiser extends EventDispatcher {
 
 			this.state.isLoading = false;
 
+			// Fire a start() that arrived mid-load. Guard on unet+enabled so a failed load
+			// or a disable during loading doesn't kick off a denoise.
+			if ( this._pendingStart && this.unet && this.enabled ) {
+
+				this._pendingStart = false;
+				this.start();
+
+			}
+
 		}
 
 	}
@@ -302,8 +314,17 @@ export class OIDNDenoiser extends EventDispatcher {
 
 	async start() {
 
-		if ( ! this.enabled || this.state.isDenoising || this.state.isLoading ) {
+		if ( ! this.enabled || this.state.isDenoising ) {
+
+			return false;
+
+		}
 
+		// UNet weights still loading — defer the start (fired from _setupUNetDenoiser's
+		// finally) rather than silently dropping this frame's denoise request.
+		if ( this.state.isLoading ) {
+
+			this._pendingStart = true;
 			return false;
 
 		}
@@ -870,6 +891,9 @@ export class OIDNDenoiser extends EventDispatcher {
 
 	abort() {
 
+		// Cancel any start deferred during loading so a reset supersedes it.
+		this._pendingStart = false;
+
 		if ( ! this.enabled || ! this.state.isDenoising ) return;
 
 		// Signal abort to current operation

package/src/PathTracerApp.js

@@ -157,6 +157,7 @@ export class PathTracerApp extends EventDispatcher {
 		// Tracked listeners for clean dispose()
 		this._trackedListeners = [];
 		this._disposed = false;
+		this._deviceLost = false;
 
 	}
 
@@ -230,6 +231,9 @@ export class PathTracerApp extends EventDispatcher {
 	 */
 	animate() {
 
+		// Device lost: stop the loop rather than rescheduling render() on a dead device.
+		if ( this._deviceLost ) return;
+
 		this.animationManagerId = requestAnimationFrame( () => this.animate() );
 
 		if ( this._loadingInProgress || this._sdf?.isProcessing ) {
@@ -368,9 +372,25 @@ export class PathTracerApp extends EventDispatcher {
 
 	}
 
+	/**
+	 * Handle GPU device loss: halt the render loop and notify hosts so they can surface a
+	 * "renderer lost — reload" prompt. Full auto-recovery would require rebuilding every GPU
+	 * resource, so this deliberately stops cleanly rather than attempting to re-init.
+	 */
+	_handleDeviceLost( info ) {
+
+		if ( this._deviceLost ) return;
+		this._deviceLost = true;
+		console.error( `WebGPU device lost (${info?.reason || 'unknown'}): ${info?.message || ''}` );
+		this.stopAnimation();
+		this.dispatchEvent( { type: EngineEvents.DEVICE_LOST, reason: info?.reason, message: info?.message } );
+
+	}
+
 	/** Wakes the animation loop if it was stopped due to idle. */
 	wake() {
 
+		if ( this._deviceLost ) return;
 		if ( ! this.animationManagerId && this.isInitialized && ! this._paused ) this.animate();
 
 	}
@@ -1385,6 +1405,22 @@ export class PathTracerApp extends EventDispatcher {
 
 		await this.renderer.init();
 
+		// Detect GPU device loss (dGPU/iGPU switch, driver reset, TDR watchdog on heavy
+		// compute). Without this the rAF loop keeps calling render() on a dead device,
+		// spewing errors forever. reason 'destroyed' during dispose() is intentional teardown.
+		const gpuDevice = this.renderer.backend?.device;
+		if ( gpuDevice?.lost ) {
+
+			gpuDevice.lost.then( ( info ) => {
+
+				if ( this._disposed ) return;
+				this._handleDeviceLost( info );
+
+			} );
+			gpuDevice.onuncapturederror = ( event ) => console.error( 'WebGPU uncaptured error:', event.error );
+
+		}
+
 		RectAreaLightNode.setLTC( RectAreaLightTexturesLib.init() );
 
 		this.renderer.outputColorSpace = SRGBColorSpace;

package/src/Processor/AssetLoader.js

@@ -292,6 +292,9 @@ export class AssetLoader extends EventDispatcher {
 
 			if ( ! this.loaderCache.texture ) this.loaderCache.texture = new TextureLoader();
 			texture = await this.loaderCache.texture.loadAsync( url );
+			// LDR env maps (jpg/png/webp) are authored in sRGB; tag them so the backend
+			// decodes to linear. HDR/EXR are already linear and keep the loader's setting.
+			texture.colorSpace = SRGBColorSpace;
 
 		}
 

package/src/Processor/GeometryExtractor.js

@@ -45,8 +45,12 @@ export class GeometryExtractor {
 
 		this.resetArrays();
 
-		// Single-pass: allocate with initial capacity, grow dynamically as needed
-		this._triangleCapacity = 1024;
+		// Pre-count the exact triangle total so the buffer is allocated once.
+		// Doubling-with-copy rounded up to the next power of two (wasting ~1GB on
+		// an 8.5M-tri scene) and held old+new during the copy (~3GB transient),
+		// which overflowed the browser's ArrayBuffer allocator. Exact avoids both.
+		const totalTriangles = this._countTriangles( object );
+		this._triangleCapacity = Math.max( 1024, totalTriangles );
 		this.triangleData = new Float32Array( this._triangleCapacity * TRIANGLE_DATA_LAYOUT.FLOATS_PER_TRIANGLE );
 		this.currentTriangleIndex = 0;
 
@@ -58,19 +62,41 @@ export class GeometryExtractor {
 
 	}
 
-	// Ensure triangleData has capacity for at least `needed` triangles
+	// Sum the exact triangle count over every mesh extract() will process
+	// (mirrors traverseObject/processMesh guards) so we can allocate once.
+	_countTriangles( object ) {
+
+		let count = 0;
+
+		if ( object.isMesh && object.geometry && object.material ) {
+
+			const indices = object.geometry.index;
+			const positions = object.geometry.attributes.position;
+			if ( indices ) count += Math.ceil( indices.count / 3 );
+			else if ( positions ) count += Math.ceil( positions.count / 3 );
+
+		}
+
+		if ( object.children ) {
+
+			for ( const child of object.children ) count += this._countTriangles( child );
+
+		}
+
+		return count;
+
+	}
+
+	// Safety net only: extract() pre-counts and allocates exactly, so this should
+	// not fire. Grow to exactly `needed` (never double) to avoid a memory spike.
 	_ensureCapacity( needed ) {
 
 		if ( needed <= this._triangleCapacity ) return;
 
-		// Double until sufficient
-		let newCapacity = this._triangleCapacity;
-		while ( newCapacity < needed ) newCapacity *= 2;
-
-		const newData = new Float32Array( newCapacity * TRIANGLE_DATA_LAYOUT.FLOATS_PER_TRIANGLE );
+		const newData = new Float32Array( needed * TRIANGLE_DATA_LAYOUT.FLOATS_PER_TRIANGLE );
 		newData.set( this.triangleData );
 		this.triangleData = newData;
-		this._triangleCapacity = newCapacity;
+		this._triangleCapacity = needed;
 
 	}
 

package/src/Processor/PackedRayBuffer.js

@@ -38,6 +38,16 @@ let _cap = 0;
 
 const soa = ( id, slot ) => ( slot === 0 ? id : id.add( slot * _cap ) );
 
+// Free a compute storage attribute's GPU buffer. Nulling the JS reference alone leaks it —
+// these attributes hang off no geometry, so nothing triggers the renderer's attribute cleanup.
+// Deleting from the renderer's attribute map calls backend.destroyAttribute(). Guarded no-op
+// when the attribute was never uploaded or no renderer was provided (e.g. unit tests).
+export function freeStorageAttribute( renderer, attr ) {
+
+	if ( attr ) renderer?._attributes?.delete?.( attr );
+
+}
+
 export class PackedRayBuffer {
 
 	// Capacity maxRays would allocate (mirrors allocate()/resize()). 1.25× headroom, NO pow2 rounding —
@@ -49,9 +59,10 @@ export class PackedRayBuffer {
 
 	}
 
-	constructor( maxRays = 0 ) {
+	constructor( maxRays = 0, renderer = null ) {
 
 		this.capacity = 0;
+		this._renderer = renderer;
 		this._attrs = {};
 
 		// Each: { rw: StorageBufferNode, ro: StorageBufferNode } over one shared GPU buffer.
@@ -118,6 +129,9 @@ export class PackedRayBuffer {
 
 	dispose() {
 
+		freeStorageAttribute( this._renderer, this._attrs.ray );
+		freeStorageAttribute( this._renderer, this._attrs.rng );
+		freeStorageAttribute( this._renderer, this._attrs.hit );
 		this._attrs = {};
 		this.rayBuffer = null;
 		this.rngBuffer = null;

package/src/Processor/QueueManager.js

@@ -4,6 +4,7 @@
 
 import { storage } from 'three/tsl';
 import { StorageInstancedBufferAttribute } from 'three/webgpu';
+import { freeStorageAttribute } from './PackedRayBuffer.js';
 
 /** Counter indices — must match ResetCounters kernel */
 export const COUNTER = {
@@ -33,8 +34,9 @@ export class QueueManager {
 	/**
 	 * @param {number} maxRays - Maximum number of rays (typically width * height)
 	 */
-	constructor( maxRays = 0 ) {
+	constructor( maxRays = 0, renderer = null ) {
 
+		this._renderer = renderer;
 		this.capacity = 0;
 		this.counters = null;
 		// A/B alternate: one read by current bounce, other written by compaction
@@ -197,6 +199,16 @@ export class QueueManager {
 
 	dispose() {
 
+		// Free the GPU buffers before dropping the node references (nulling alone leaks them).
+		freeStorageAttribute( this._renderer, this._countersAttr );
+		freeStorageAttribute( this._renderer, this._bounceCountsAttr );
+		freeStorageAttribute( this._renderer, this._attrA );
+		freeStorageAttribute( this._renderer, this._attrB );
+		freeStorageAttribute( this._renderer, this._sortAttr );
+		freeStorageAttribute( this._renderer, this._sortGlobalHistAttr );
+		this._countersAttr = this._bounceCountsAttr = null;
+		this._attrA = this._attrB = this._sortAttr = this._sortGlobalHistAttr = null;
+
 		this.counters = null;
 		this.activeIndices = null;
 		this.activeIndicesRO = null;