rayzee 7.31.1 → 8.0.0

package/src/TSL/patches.js

@@ -7,11 +7,12 @@
  * loop) and `initTimestampQuery` (enlarges the stats-gl timestamp query pool so
  * the wavefront tracer's high per-frame compute-pass count doesn't overflow it).
  *
- * Export: `struct()` — drop-in replacement for TSL's `struct()` returning
- * a proxy factory that supports GLSL-style dot-notation field access.
+ * Exports: `struct()` — drop-in replacement for TSL's `struct()` returning
+ * a proxy factory that supports GLSL-style dot-notation field access — and
+ * `gpuOnlyStorageAttribute()`, a storage attribute with no CPU backing array.
  */
 
-import { WebGPUBackend } from 'three/webgpu';
+import { StorageInstancedBufferAttribute, WebGPUBackend } from 'three/webgpu';
 import { struct as _struct } from 'three/tsl';
 
 // ---------------------------------------------------------------------------
@@ -69,6 +70,130 @@ WebGPUBackend.prototype.createNodeBuilder = function ( object, renderer ) {
 
 };
 
+// ---------------------------------------------------------------------------
+// 1b. GPU-only storage attributes
+// ---------------------------------------------------------------------------
+// `StorageBufferAttribute( count, ... )` always allocates a CPU TypedArray, even
+// for a buffer only compute shaders ever touch — three.js has no GPU-only path
+// (upstream request open). The wavefront ray/hit/rng state and the per-pixel
+// G-buffer are exactly that: every lane is written by a kernel before anything
+// reads it, nothing is ever read back, and WebGPU zero-initialises a new buffer,
+// so the CPU copy is pure overhead — 704 MB at a 4M path budget.
+//
+// `gpuOnlyStorageAttribute()` builds the attribute over a zero-length array and
+// records the size the GPU buffer needs; `createStorageAttribute` below allocates
+// that size unmapped, and `updateAttribute` becomes a no-op since there is
+// nothing to upload. Everything else (binding, dispose, readback plumbing) is
+// untouched — a storage binding takes the whole buffer with no size argument.
+
+export function gpuOnlyStorageAttribute( count, itemSize, typeClass = Float32Array ) {
+
+	const attr = new StorageInstancedBufferAttribute( new typeClass( 0 ), itemSize );
+	attr.count = count;
+	attr.gpuByteLength = count * itemSize * typeClass.BYTES_PER_ELEMENT;
+	attr.isGPUOnly = true;
+	return attr;
+
+}
+
+const _origCreateStorageAttribute = WebGPUBackend.prototype.createStorageAttribute;
+
+WebGPUBackend.prototype.createStorageAttribute = function ( attribute ) {
+
+	const bufferAttribute = this.attributeUtils._getBufferAttribute( attribute );
+	if ( ! bufferAttribute.isGPUOnly ) return _origCreateStorageAttribute.call( this, attribute );
+
+	const data = this.get( bufferAttribute );
+	if ( data.buffer !== undefined ) return;
+
+	data.buffer = this.device.createBuffer( {
+		label: bufferAttribute.name,
+		size: bufferAttribute.gpuByteLength,
+		usage: GPUBufferUsage.STORAGE | GPUBufferUsage.VERTEX | GPUBufferUsage.COPY_SRC | GPUBufferUsage.COPY_DST,
+	} );
+
+};
+
+/**
+ * Upload a storage attribute's contents from several CPU chunks.
+ *
+ * A GPU buffer may be up to `maxBufferSize` (4 GB here) while V8 caps a single ArrayBuffer at
+ * ~2 GB, so anything larger has to be staged in pieces. The attribute must be GPU-only: it owns
+ * no CPU array, and these writes are the only thing that fills it.
+ *
+ * @param {Object} renderer - WebGPURenderer
+ * @param {Object} attr - attribute from gpuOnlyStorageAttribute()
+ * @param {Array<TypedArray>} chunks - in order; total byte length must match the attribute
+ */
+export function uploadStorageChunks( renderer, attr, chunks ) {
+
+	const backend = renderer.backend;
+	backend.createStorageAttribute( attr );
+
+	const buffer = backend.get( attr ).buffer;
+	let byteOffset = 0;
+
+	for ( const chunk of chunks ) {
+
+		backend.device.queue.writeBuffer( buffer, byteOffset, chunk, 0, chunk.length );
+		byteOffset += chunk.byteLength;
+
+	}
+
+	if ( byteOffset !== attr.gpuByteLength ) {
+
+		throw new RangeError( `uploadStorageChunks wrote ${byteOffset} bytes into a ${attr.gpuByteLength}-byte buffer` );
+
+	}
+
+}
+
+/**
+ * Re-upload one lane range of a chunked storage attribute, spanning chunks as needed.
+ *
+ * The partial-update path three.js offers (`addUpdateRange` + a version bump) cannot work here:
+ * a GPU-only attribute owns no CPU array and its `updateAttribute` is a no-op, so a dirty range
+ * would silently never reach the GPU.
+ *
+ * @param {Object} renderer - WebGPURenderer
+ * @param {Object} attr - attribute from gpuOnlyStorageAttribute()
+ * @param {Object} records - the ChunkedRecords backing it
+ * @param {number} startLane - first lane to write
+ * @param {number} laneCount - how many lanes
+ */
+export function uploadStorageChunkRange( renderer, attr, records, startLane, laneCount ) {
+
+	const backend = renderer.backend;
+	backend.createStorageAttribute( attr );
+
+	const buffer = backend.get( attr ).buffer;
+	const lanesPerChunk = records.recordsPerChunk * records.lanesPerRecord;
+	const bytesPerLane = records.chunks[ 0 ].BYTES_PER_ELEMENT;
+	const end = startLane + laneCount;
+
+	let lane = startLane;
+	while ( lane < end ) {
+
+		const ci = Math.floor( lane / lanesPerChunk );
+		const chunk = records.chunks[ ci ];
+		const local = lane - ci * lanesPerChunk;
+		const n = Math.min( chunk.length - local, end - lane );
+		backend.device.queue.writeBuffer( buffer, lane * bytesPerLane, chunk, local, n );
+		lane += n;
+
+	}
+
+}
+
+const _origUpdateAttribute = WebGPUBackend.prototype.updateAttribute;
+
+WebGPUBackend.prototype.updateAttribute = function ( attribute ) {
+
+	if ( this.attributeUtils._getBufferAttribute( attribute ).isGPUOnly ) return;
+	return _origUpdateAttribute.call( this, attribute );
+
+};
+
 // ---------------------------------------------------------------------------
 // 2. Larger timestamp query pool (stats-gl GPU/compute timing)
 // ---------------------------------------------------------------------------

package/src/index.js

@@ -72,6 +72,9 @@ export { OverlayManager } from './managers/OverlayManager.js';
 
 // VRAM accounting
 export { VRAMTracker, bufferBytes, textureBytes } from './Processor/VRAMTracker.js';
+export {
+	MemoryLedger, estimateSceneBytes, probeAddressSpace, SAFE_SCENE_BYTES, MAX_SCENE_BYTES,
+} from './Processor/HostMemory.js';
 
 // Pipeline infrastructure (for advanced consumers building custom stages)
 export { RenderPipeline } from './Pipeline/RenderPipeline.js';

package/src/managers/AnimationManager.js

@@ -3,7 +3,7 @@
  *
  * Owns the Three.js AnimationMixer, advances clips each frame,
  * extracts deformed vertex positions via CPU skinning, and returns
- * them in the format expected by PathTracerApp.refitBVH().
+ * a per-mesh reader in the shape PathTracerApp.refitBVH() accepts.
  */
 
 import { AnimationMixer, EventDispatcher, Timer, Vector3, LoopRepeat, LoopOnce } from 'three';
@@ -24,7 +24,7 @@ export class AnimationManager extends EventDispatcher {
 		this._mixerRoot = null; // mixer target (GLTF model root for track resolution)
 		this._meshes = null;
 		this._meshTriRanges = null; // { start, count, uniqueVerts, indices }[]
-		this._posBuffer = null; // Float32Array(triCount * 9) — reused each frame
+		this._meshPositions = null; // per-mesh Float32Array(triCount * 9), allocated on first use
 		this._tempVec = new Vector3();
 		this._skinnedCache = null; // per-mesh Float32Array for skinned vertex positions
 		this._clipsCache = null;
@@ -111,14 +111,14 @@ export class AnimationManager extends EventDispatcher {
 			const uniqueVerts = positions.count;
 
 			this._meshTriRanges.push( { start: offset, count, uniqueVerts, indices } );
-			// Pre-allocate per-mesh skinned position cache (3 floats per unique vertex)
-			this._skinnedCache.push( new Float32Array( uniqueVerts * 3 ) );
 			offset += count;
 
 		}
 
-		// Allocate reusable output buffer
-		this._posBuffer = new Float32Array( offset * 9 );
+		// Scratch is per mesh and allocated on first use. One scene-wide output buffer would be
+		// 9 floats × every triangle — 1,030 MB at 30M, past what a renderer can allocate.
+		this._skinnedCache = [];
+		this._meshPositions = [];
 
 		const skinnedCount = meshes.filter( m => m.isSkinnedMesh ).length;
 		console.debug( `[AnimationManager] Init: ${animations.length} clips, ${meshes.length} meshes (${skinnedCount} skinned), ${offset} triangles` );
@@ -224,12 +224,12 @@ export class AnimationManager extends EventDispatcher {
 	}
 
 	/**
-	 * Seek to an absolute time and extract deformed vertex positions.
+	 * Seek to an absolute time and prepare deformed vertex positions.
 	 * Does not require playback — works from any state (stopped, paused, playing).
 	 *
 	 * @param {number} time - Absolute time in seconds
 	 * @param {number} [clipIndex=0] - Clip to evaluate, or -1 for all active
-	 * @returns {Float32Array|null} Position buffer (9 floats/tri) or null if no mixer
+	 * @returns {function(number): Float32Array|null} Per-mesh reader for refitBVH, or null if no mixer
 	 */
 	seekTo( time, clipIndex = 0 ) {
 
@@ -261,8 +261,7 @@ export class AnimationManager extends EventDispatcher {
 
 		}
 
-		this._computePositions();
-		return this._posBuffer;
+		return this._poseReader();
 
 	}
 
@@ -277,10 +276,10 @@ export class AnimationManager extends EventDispatcher {
 	}
 
 	/**
-	 * Advance animation and extract deformed positions.
+	 * Advance animation and prepare deformed positions.
 	 * Call once per frame from the animate loop.
 	 *
-	 * @returns {Float32Array|null} Position buffer (9 floats/tri, original mesh order) or null if not playing
+	 * @returns {function(number): Float32Array|null} Per-mesh reader for refitBVH, or null if not playing
 	 */
 	update() {
 
@@ -290,100 +289,111 @@ export class AnimationManager extends EventDispatcher {
 		const delta = this.timer.getDelta();
 		this.mixer.update( delta );
 
-		this._computePositions();
+		return this._poseReader();
+
+	}
+
+	/** A reusable per-mesh buffer, grown only when that mesh is first skinned. @private */
+	_scratch( cache, index, length ) {
 
-		return this._posBuffer;
+		const have = cache[ index ];
+		return have && have.length === length ? have : ( cache[ index ] = new Float32Array( length ) );
 
 	}
 
 	/**
-	 * Extract deformed vertex positions from all meshes.
-	 * Uses two-phase approach for indexed geometry:
-	 *   Phase 1: Skin all unique vertices per mesh
-	 *   Phase 2: Assemble triangles from index buffer
+	 * Settle the pose, then hand back a reader that skins one mesh at a time. The refit pulls each
+	 * mesh as it needs it, so only one mesh's worth of deformed positions exists at any moment.
 	 * @private
 	 */
-	_computePositions() {
+	_poseReader() {
 
-		const tempVec = this._tempVec;
-		const output = this._posBuffer;
-
-		// Update mixer root subtree — bones live outside mesh subtrees so
-		// per-mesh updateMatrixWorld() misses them. Using mixerRoot (not full
-		// scene) avoids recomputing matrices for unrelated static objects.
+		// Bones live outside mesh subtrees so per-mesh updateMatrixWorld() misses them. Doing it
+		// once here, on mixerRoot rather than the scene, keeps unrelated static objects out of it.
 		this._mixerRoot.updateMatrixWorld( true );
 
-		for ( let m = 0; m < this._meshes.length; m ++ ) {
+		return m => this._computeMeshPositions( m );
+
+	}
 
-			const mesh = this._meshes[ m ];
-			const { start, count, uniqueVerts, indices } = this._meshTriRanges[ m ];
-			const skinned = this._skinnedCache[ m ];
+	/**
+	 * Skin one mesh into its own buffer. Two phases for indexed geometry: skin the unique
+	 * vertices, then assemble triangles from the index buffer.
+	 * @private
+	 */
+	_computeMeshPositions( m ) {
 
-			const worldMatrix = mesh.matrixWorld;
+		const tempVec = this._tempVec;
+		const mesh = this._meshes[ m ];
+		const { count, uniqueVerts, indices } = this._meshTriRanges[ m ];
+		const skinned = this._scratch( this._skinnedCache, m, uniqueVerts * 3 );
+		const output = this._scratch( this._meshPositions, m, count * 9 );
 
-			// Phase 1: Compute world-space positions for all unique vertices
-			for ( let v = 0; v < uniqueVerts; v ++ ) {
+		const worldMatrix = mesh.matrixWorld;
 
-				// getVertexPosition handles morph targets + bone transforms (local space)
-				mesh.getVertexPosition( v, tempVec );
-				// Transform to world space (matches GeometryExtractor behavior)
-				tempVec.applyMatrix4( worldMatrix );
+		// Phase 1: Compute world-space positions for all unique vertices
+		for ( let v = 0; v < uniqueVerts; v ++ ) {
 
-				skinned[ v * 3 ] = tempVec.x;
-				skinned[ v * 3 + 1 ] = tempVec.y;
-				skinned[ v * 3 + 2 ] = tempVec.z;
+			// getVertexPosition handles morph targets + bone transforms (local space)
+			mesh.getVertexPosition( v, tempVec );
+			// Transform to world space (matches GeometryExtractor behavior)
+			tempVec.applyMatrix4( worldMatrix );
 
-			}
+			skinned[ v * 3 ] = tempVec.x;
+			skinned[ v * 3 + 1 ] = tempVec.y;
+			skinned[ v * 3 + 2 ] = tempVec.z;
 
-			// Phase 2: Assemble triangles
-			if ( indices ) {
+		}
 
-				for ( let t = 0; t < count; t ++ ) {
+		// Phase 2: Assemble triangles
+		if ( indices ) {
 
-					const t3 = t * 3;
-					const i0 = indices[ t3 ] * 3;
-					const i1 = indices[ t3 + 1 ] * 3;
-					const i2 = indices[ t3 + 2 ] * 3;
-					const o = ( start + t ) * 9;
+			for ( let t = 0; t < count; t ++ ) {
 
-					output[ o ] = skinned[ i0 ];
-					output[ o + 1 ] = skinned[ i0 + 1 ];
-					output[ o + 2 ] = skinned[ i0 + 2 ];
-					output[ o + 3 ] = skinned[ i1 ];
-					output[ o + 4 ] = skinned[ i1 + 1 ];
-					output[ o + 5 ] = skinned[ i1 + 2 ];
-					output[ o + 6 ] = skinned[ i2 ];
-					output[ o + 7 ] = skinned[ i2 + 1 ];
-					output[ o + 8 ] = skinned[ i2 + 2 ];
+				const t3 = t * 3;
+				const i0 = indices[ t3 ] * 3;
+				const i1 = indices[ t3 + 1 ] * 3;
+				const i2 = indices[ t3 + 2 ] * 3;
+				const o = t * 9;
 
-				}
+				output[ o ] = skinned[ i0 ];
+				output[ o + 1 ] = skinned[ i0 + 1 ];
+				output[ o + 2 ] = skinned[ i0 + 2 ];
+				output[ o + 3 ] = skinned[ i1 ];
+				output[ o + 4 ] = skinned[ i1 + 1 ];
+				output[ o + 5 ] = skinned[ i1 + 2 ];
+				output[ o + 6 ] = skinned[ i2 ];
+				output[ o + 7 ] = skinned[ i2 + 1 ];
+				output[ o + 8 ] = skinned[ i2 + 2 ];
 
-			} else {
+			}
 
-				// Non-indexed: vertices are sequential triplets
-				for ( let t = 0; t < count; t ++ ) {
+		} else {
 
-					const v0 = ( t * 3 ) * 3;
-					const v1 = ( t * 3 + 1 ) * 3;
-					const v2 = ( t * 3 + 2 ) * 3;
-					const o = ( start + t ) * 9;
+			// Non-indexed: vertices are sequential triplets
+			for ( let t = 0; t < count; t ++ ) {
 
-					output[ o ] = skinned[ v0 ];
-					output[ o + 1 ] = skinned[ v0 + 1 ];
-					output[ o + 2 ] = skinned[ v0 + 2 ];
-					output[ o + 3 ] = skinned[ v1 ];
-					output[ o + 4 ] = skinned[ v1 + 1 ];
-					output[ o + 5 ] = skinned[ v1 + 2 ];
-					output[ o + 6 ] = skinned[ v2 ];
-					output[ o + 7 ] = skinned[ v2 + 1 ];
-					output[ o + 8 ] = skinned[ v2 + 2 ];
+				const v0 = ( t * 3 ) * 3;
+				const v1 = ( t * 3 + 1 ) * 3;
+				const v2 = ( t * 3 + 2 ) * 3;
+				const o = t * 9;
 
-				}
+				output[ o ] = skinned[ v0 ];
+				output[ o + 1 ] = skinned[ v0 + 1 ];
+				output[ o + 2 ] = skinned[ v0 + 2 ];
+				output[ o + 3 ] = skinned[ v1 ];
+				output[ o + 4 ] = skinned[ v1 + 1 ];
+				output[ o + 5 ] = skinned[ v1 + 2 ];
+				output[ o + 6 ] = skinned[ v2 ];
+				output[ o + 7 ] = skinned[ v2 + 1 ];
+				output[ o + 8 ] = skinned[ v2 + 2 ];
 
 			}
 
 		}
 
+		return output;
+
 	}
 
 	/**
@@ -433,7 +443,7 @@ export class AnimationManager extends EventDispatcher {
 		this._mixerRoot = null;
 		this._meshes = null;
 		this._meshTriRanges = null;
-		this._posBuffer = null;
+		this._meshPositions = null;
 		this._skinnedCache = null;
 		this._clipsCache = null;
 

package/src/managers/MaterialDataManager.js

@@ -9,16 +9,17 @@
 
 import { StorageInstancedBufferAttribute } from 'three/webgpu';
 import { storage } from 'three/tsl';
-import { MATERIAL_DATA_LAYOUT as M, TRIANGLE_DATA_LAYOUT as T, normalizeAttenuationDistance } from '../EngineDefaults.js';
+import {
+	MATERIAL_DATA_LAYOUT as M, TRIANGLE_DATA_LAYOUT as T, normalizeAttenuationDistance,
+	TRI_MATERIAL_MASK, TRI_SIDE_SHIFT, TRI_BLOCKER_SHIFT, shadowBlockerBits
+} from '../EngineDefaults.js';
 import { createLogger, fmt } from '../utils/Logger.js';
 
 const log = createLogger( 'material' );
 
 const PIXELS_PER_MATERIAL = M.SLOTS_PER_MATERIAL;
-// Per-triangle float offsets used by _patchTriangleSideForMaterial / _patchTriangleBlockerForMaterial.
-const TRI_MAT_IDX_OFFSET = T.UV_C_MAT_OFFSET + 2; // uvData2.z in shader
-const TRI_SIDE_OFFSET = T.NORMAL_C_OFFSET + 3; // normalCData.w in shader
-const TRI_BLOCKER_OFFSET = T.NORMAL_A_OFFSET + 3; // nA.w in shader (opaque-blocker fast path)
+// Side and the opaque-blocker bit share the material lane, so a patch is a masked write.
+const TRI_FLAGS_OFFSET = T.MATERIAL_FLAGS_OFFSET;
 
 // Material properties that affect the shadow-ray opaque-blocker flag.
 const BLOCKER_PROPS = new Set( [ 'transmission', 'transparent', 'opacity', 'alphaMode' ] );
@@ -722,9 +723,8 @@ export class MaterialDataManager {
 	 * @private
 	 */
 	/**
-	 * Re-derive the shadow-ray opaque-blocker flag for a material from its
-	 * current buffer values and patch NORMAL_A.w on every matching triangle.
-	 * Kept in sync with the blocker definition in GeometryExtractor.
+	 * Re-derive the two shadow-blocker bits for a material from its current buffer
+	 * values and patch them on every matching triangle.
 	 * @private
 	 */
 	_recomputeOpaqueBlockerForMaterial( materialIndex ) {
@@ -733,36 +733,42 @@ export class MaterialDataManager {
 		if ( ! matBuf ) return;
 
 		const matStride = materialIndex * M.FLOATS_PER_MATERIAL;
-		const alphaMode = matBuf[ matStride + M.ALPHA_MODE ] | 0;
-		const transparent = matBuf[ matStride + M.TRANSPARENT ] | 0;
-		const transmission = matBuf[ matStride + M.TRANSMISSION ] || 0;
-		const opacity = matBuf[ matStride + M.OPACITY ] ?? 1;
-		const isOpaqueBlocker = ( alphaMode === 0 && transparent === 0 && transmission === 0 && opacity >= 1 ) ? 1.0 : 0.0;
+		const bits = shadowBlockerBits( {
+			alphaMode: matBuf[ matStride + M.ALPHA_MODE ],
+			transparent: matBuf[ matStride + M.TRANSPARENT ],
+			transmission: matBuf[ matStride + M.TRANSMISSION ],
+			opacity: matBuf[ matStride + M.OPACITY ],
+		} );
 
-		this._patchTriangleFlagForMaterial( materialIndex, TRI_BLOCKER_OFFSET, isOpaqueBlocker );
+		this._patchTriangleFlagForMaterial( materialIndex, TRI_BLOCKER_SHIFT, 2, bits );
 
 	}
 
 	/**
-	 * Generic helper: patch a single per-triangle float at `triOffset` for every
-	 * triangle whose materialIndex matches, then fire onTriangleDataChanged.
+	 * Generic helper: rewrite `width` bits at `shift` in the flags lane of every triangle
+	 * whose materialIndex matches, then fire onTriangleDataChanged.
 	 * @private
 	 */
-	_patchTriangleFlagForMaterial( materialIndex, triOffset, value ) {
+	_patchTriangleFlagForMaterial( materialIndex, shift, width, value ) {
 
 		const triInfo = this.callbacks.getTriangleData?.();
-		const triData = triInfo?.array;
+		// Chunked past the ~2 GB array cap; a flat array is the single-chunk case.
+		const records = triInfo?.records;
+		const flat = records ? null : triInfo?.array;
 		const triCount = triInfo?.count | 0;
-		if ( ! triData || triCount === 0 ) return;
+		if ( ( ! flat && ! records ) || triCount === 0 ) return;
 
 		const stride = T.FLOATS_PER_TRIANGLE;
+		const mask = ( ( ( 1 << width ) - 1 ) << shift ) >>> 0;
+		const bits = ( ( value << shift ) & mask ) >>> 0;
 		let patched = 0;
 		for ( let i = 0; i < triCount; i ++ ) {
 
-			const base = i * stride;
-			if ( triData[ base + TRI_MAT_IDX_OFFSET ] === materialIndex ) {
+			const triData = records ? records.chunkFor( i ) : flat;
+			const base = records ? records.baseOf( i ) : i * stride;
+			if ( ( triData[ base + TRI_FLAGS_OFFSET ] & TRI_MATERIAL_MASK ) === materialIndex ) {
 
-				triData[ base + triOffset ] = value;
+				triData[ base + TRI_FLAGS_OFFSET ] = ( ( triData[ base + TRI_FLAGS_OFFSET ] & ~ mask ) | bits ) >>> 0;
 				patched ++;
 
 			}
@@ -779,7 +785,7 @@ export class MaterialDataManager {
 
 	_patchTriangleSideForMaterial( materialIndex, sideValue ) {
 
-		this._patchTriangleFlagForMaterial( materialIndex, TRI_SIDE_OFFSET, sideValue );
+		this._patchTriangleFlagForMaterial( materialIndex, TRI_SIDE_SHIFT, 2, sideValue );
 
 	}