rayzee 7.31.1 → 8.1.0

package/src/Processor/ChunkedRecords.js

@@ -0,0 +1,302 @@
+/**
+ * ChunkedRecords — a logically contiguous array of fixed-size records, stored as several
+ * TypedArrays so it can exceed the ~2 GB cap V8 puts on a single ArrayBuffer.
+ *
+ * A GPU buffer may be 4 GB here while one JS array tops out near 2,040 MB, so the triangle and
+ * BVH buffers hit a CPU-side wall long before the GPU one. Splitting the CPU side lifts that
+ * without changing a single shader binding: the chunks are written into one GPU buffer in order.
+ *
+ * Chunk boundaries always fall on a record boundary, so a record never straddles two arrays.
+ * Callers resolve the chunk once per record and then index its lanes directly, which keeps the
+ * hot loops as fast as a flat array — one extra shift and mask per record, nothing per lane.
+ *
+ * One chunk is the overwhelmingly common case and is the fast path throughout: `single` returns
+ * the whole array, and callers that only work on flat data can keep using it.
+ */
+
+/**
+ * Below this a scene stays single-chunk. Far under the 2,040 MB V8 cap on purpose: a big
+ * ArrayBuffer needs that much *contiguous* address space, so chunk size sets the usable total.
+ * Placed before the allocator gave up, fresh renderer: 256 MB chunks 5,120 MB · 64 MB 7,040 MB ·
+ * 32 MB 7,744 MB.
+ */
+export const DEFAULT_CHUNK_BYTES = 64 * 1024 * 1024;
+
+/** Whether a worker can be handed these arrays without copying them first. */
+export const SHARED_MEMORY_AVAILABLE = typeof SharedArrayBuffer !== 'undefined';
+
+/**
+ * Notified of every chunk allocated, so a build can attribute memory to the phase that spent it.
+ * At most one watcher, and it must not throw — this sits on the allocation path.
+ * @type {?function(number, boolean): void}
+ */
+let chunkObserver = null;
+
+/** Watch chunk allocations. Pass null to stop. @param {?function(number, boolean): void} fn */
+export function setChunkObserver( fn ) {
+
+	chunkObserver = fn;
+
+}
+
+/** One chunk's storage, shared with workers when the page is cross-origin isolated. */
+function allocChunk( LaneType, lanes, shared ) {
+
+	const chunk = shared
+		? new LaneType( new SharedArrayBuffer( lanes * LaneType.BYTES_PER_ELEMENT ) )
+		: new LaneType( lanes );
+
+	if ( chunkObserver && chunk.byteLength > 0 ) chunkObserver( chunk.byteLength, shared );
+	return chunk;
+
+}
+
+export class ChunkedRecords {
+
+	/**
+	 * @param {number} recordCount - total records
+	 * @param {number} lanesPerRecord - elements per record (20 for a triangle, 16 for a BVH node)
+	 * @param {Function} LaneType - typed array constructor for one lane
+	 * @param {number} [maxBytesPerChunk]
+	 * @param {boolean} [shared] - back the chunks with SharedArrayBuffer so a worker can read and
+	 *   write them in place. Without it a refit has to copy the whole store into shared memory,
+	 *   which is a second copy of the largest thing in the scene.
+	 */
+	constructor( recordCount, lanesPerRecord, LaneType, maxBytesPerChunk = DEFAULT_CHUNK_BYTES, shared = false ) {
+
+		const recordBytes = lanesPerRecord * LaneType.BYTES_PER_ELEMENT;
+		const perChunk = Math.max( 1, Math.floor( maxBytesPerChunk / recordBytes ) );
+
+		this.recordCount = recordCount;
+		this.lanesPerRecord = lanesPerRecord;
+		this.LaneType = LaneType;
+		this.recordsPerChunk = recordCount <= perChunk ? Math.max( recordCount, 1 ) : perChunk;
+		this.shared = shared;
+
+		this.chunks = [];
+		let remaining = recordCount;
+		while ( remaining > 0 ) {
+
+			const n = Math.min( remaining, this.recordsPerChunk );
+			this.chunks.push( allocChunk( LaneType, n * lanesPerRecord, shared ) );
+			remaining -= n;
+
+		}
+
+		if ( this.chunks.length === 0 ) this.chunks.push( allocChunk( LaneType, 0, shared ) );
+
+	}
+
+	/** Adopt already-built chunks (e.g. handed over by the extractor) without copying. */
+	static adopt( chunks, recordCount, lanesPerRecord, recordsPerChunk ) {
+
+		const c = Object.create( ChunkedRecords.prototype );
+		c.recordCount = recordCount;
+		c.lanesPerRecord = lanesPerRecord;
+		c.LaneType = chunks[ 0 ]?.constructor ?? null;
+		c.recordsPerChunk = recordsPerChunk;
+		c.chunks = chunks;
+		c.shared = typeof SharedArrayBuffer !== 'undefined' && chunks[ 0 ]?.buffer instanceof SharedArrayBuffer;
+		return c;
+
+	}
+
+	/**
+	 * Like the constructor, but a chunk is allocated the first time it is touched, so a fill that
+	 * releases each source as it writes it never holds the whole source and destination at once.
+	 */
+	static lazy( recordCount, lanesPerRecord, LaneType, maxBytesPerChunk = DEFAULT_CHUNK_BYTES, shared = false ) {
+
+		const perChunk = Math.max( 1, Math.floor( maxBytesPerChunk / ( lanesPerRecord * LaneType.BYTES_PER_ELEMENT ) ) );
+		const c = Object.create( ChunkedRecords.prototype );
+		c.recordCount = recordCount;
+		c.lanesPerRecord = lanesPerRecord;
+		c.LaneType = LaneType;
+		c.recordsPerChunk = recordCount <= perChunk ? Math.max( recordCount, 1 ) : perChunk;
+		c.shared = shared;
+		c.chunks = new Array( Math.max( 1, Math.ceil( recordCount / c.recordsPerChunk ) ) );
+		c._views = [];
+		return c;
+
+	}
+
+	/** Allocate chunk `k`, plus the matching chunk of every view taken over this storage. @private */
+	_materialize( k ) {
+
+		if ( this._owner ) {
+
+			this._owner._materialize( k );
+			return this.chunks[ k ];
+
+		}
+
+		const from = k * this.recordsPerChunk;
+		const lanes = Math.min( this.recordsPerChunk, this.recordCount - from ) * this.lanesPerRecord;
+		const chunk = this.chunks[ k ] = allocChunk( this.LaneType, lanes, this.shared );
+
+		for ( const v of this._views ) {
+
+			v.chunks[ k ] = new v.LaneType( chunk.buffer, chunk.byteOffset, chunk.byteLength / v.LaneType.BYTES_PER_ELEMENT );
+
+		}
+
+		return chunk;
+
+	}
+
+	/** Allocate whatever a lazy fill never touched, so the result behaves like an eager one. */
+	materializeAll() {
+
+		for ( let k = 0; k < this.chunks.length; k ++ ) if ( ! this.chunks[ k ] ) this._materialize( k );
+		return this;
+
+	}
+
+	get chunkCount() {
+
+		return this.chunks.length;
+
+	}
+
+	/** The whole thing as one array when it fits in one, else null. */
+	get single() {
+
+		return this.chunks.length === 1 ? this.chunks[ 0 ] : null;
+
+	}
+
+	get byteLength() {
+
+		let n = 0;
+		for ( const c of this.chunks ) if ( c ) n += c.byteLength;
+		return n;
+
+	}
+
+	/** The array holding `record`. */
+	chunkFor( record ) {
+
+		const k = ( record / this.recordsPerChunk ) | 0;
+		return this.chunks[ k ] ?? this._materialize( k );
+
+	}
+
+	/** Lane offset of `record` within its own chunk. */
+	baseOf( record ) {
+
+		return ( record % this.recordsPerChunk ) * this.lanesPerRecord;
+
+	}
+
+	/** True when records [start, start+count) sit inside one chunk. */
+	isContiguous( start, count ) {
+
+		if ( count <= 0 ) return true;
+		return ( ( start / this.recordsPerChunk ) | 0 ) === ( ( ( start + count - 1 ) / this.recordsPerChunk ) | 0 );
+
+	}
+
+	/**
+	 * A view over records [start, start+count) when they share a chunk, otherwise a copy.
+	 * Callers that only read may use it freely; callers that write must use {@link setRecords}.
+	 */
+	slice( start, count ) {
+
+		const base = this.baseOf( start );
+		const lanes = count * this.lanesPerRecord;
+
+		if ( this.isContiguous( start, count ) ) return this.chunkFor( start ).subarray( base, base + lanes );
+
+		const out = new this.LaneType( lanes );
+		this.readRecords( start, count, out );
+		return out;
+
+	}
+
+	/** Copy records [start, start+count) into `out`. */
+	readRecords( start, count, out ) {
+
+		let done = 0;
+		while ( done < count ) {
+
+			const rec = start + done;
+			const chunk = this.chunkFor( rec );
+			const base = this.baseOf( rec );
+			const room = this.recordsPerChunk - ( rec % this.recordsPerChunk );
+			const n = Math.min( room, count - done );
+			out.set( chunk.subarray( base, base + n * this.lanesPerRecord ), done * this.lanesPerRecord );
+			done += n;
+
+		}
+
+		return out;
+
+	}
+
+	/** Write `src` (whole records) starting at record `start`, spanning chunks as needed. */
+	setRecords( start, src ) {
+
+		const count = src.length / this.lanesPerRecord;
+		let done = 0;
+		while ( done < count ) {
+
+			const rec = start + done;
+			const chunk = this.chunkFor( rec );
+			const base = this.baseOf( rec );
+			const room = this.recordsPerChunk - ( rec % this.recordsPerChunk );
+			const n = Math.min( room, count - done );
+			chunk.set(
+				src.subarray( done * this.lanesPerRecord, ( done + n ) * this.lanesPerRecord ),
+				base
+			);
+			done += n;
+
+		}
+
+	}
+
+	/** A fresh copy of records [start, start+count). Always a copy, so it is safe to transfer. */
+	copyOf( start, count ) {
+
+		return this.readRecords( start, count, new this.LaneType( count * this.lanesPerRecord ) );
+
+	}
+
+	/**
+	 * The same storage narrowed to the first `recordCount` records: whole unused chunks are
+	 * dropped and the last one is trimmed, so the upload writes exactly what was filled.
+	 */
+	trimTo( recordCount ) {
+
+		const needed = Math.max( 1, Math.ceil( recordCount / this.recordsPerChunk ) );
+		const chunks = this.chunks.slice( 0, needed );
+		const lanes = ( recordCount - ( needed - 1 ) * this.recordsPerChunk ) * this.lanesPerRecord;
+		const last = chunks[ needed - 1 ];
+		if ( last.length > lanes ) chunks[ needed - 1 ] = last.subarray( 0, Math.max( 0, lanes ) );
+
+		return ChunkedRecords.adopt( chunks, recordCount, this.lanesPerRecord, this.recordsPerChunk );
+
+	}
+
+	/** A parallel set of views of another lane type over the same memory (u32 records read as f32). */
+	viewAs( LaneType ) {
+
+		const wrap = c => new LaneType( c.buffer, c.byteOffset, c.byteLength / LaneType.BYTES_PER_ELEMENT );
+		const v = ChunkedRecords.adopt(
+			this.chunks.map( c => ( c ? wrap( c ) : undefined ) ),
+			this.recordCount, this.lanesPerRecord, this.recordsPerChunk
+		);
+		v.LaneType = LaneType;
+
+		if ( this._views ) {
+
+			v._owner = this;
+			this._views.push( v );
+
+		}
+
+		return v;
+
+	}
+
+}

package/src/Processor/EmissiveTriangleBuilder.js

@@ -7,7 +7,7 @@
  */
 
 import { DataTexture, RGBAFormat, FloatType, NearestFilter } from 'three';
-import { TRIANGLE_DATA_LAYOUT } from '../EngineDefaults.js';
+import { TRIANGLE_DATA_LAYOUT, TRI_MATERIAL_MASK } from '../EngineDefaults.js';
 import { LightBVHBuilder } from './LightBVHBuilder.js';
 import { createLogger, fmt } from '../utils/Logger.js';
 
@@ -38,25 +38,37 @@ export class EmissiveTriangleBuilder {
 
 	/**
 	 * Extract emissive triangles from processed geometry
-	 * @param {Array} triangleData - Flat array of triangle data
+	 * @param {Uint32Array} triangleData - Packed triangle records
 	 * @param {Array} materials - Array of material objects
 	 * @param {number} triangleCount - Total number of triangles
+	 * @param {import('./InstanceTable.js').InstanceTable} [table] - per placement; triangles are
+	 *        stored in object space, so power, bounds and the emission cone all have to be
+	 *        measured after the instance transform. One record per triangle, so a template
+	 *        placed more than once is lit by its first placement — the extractor expands an
+	 *        emissive instanced mesh into per-instance triangles to avoid exactly that.
 	 */
-	extractEmissiveTriangles( triangleData, materials, triangleCount ) {
+	extractEmissiveTriangles( triangleData, materials, triangleCount, table = null ) {
 
 		this.emissiveTriangles = [];
 		this.totalEmissivePower = 0;
 		this._totalTriangleCount = triangleCount;
 
 		const FLOATS_PER_TRIANGLE = TRIANGLE_DATA_LAYOUT.FLOATS_PER_TRIANGLE;
-		const MATERIAL_INDEX_OFFSET = TRIANGLE_DATA_LAYOUT.UV_C_MAT_OFFSET + 2; // materialIndex within vec4
-		const MESH_INDEX_OFFSET = TRIANGLE_DATA_LAYOUT.UV_C_MAT_OFFSET + 3; // meshIndex within vec4
+		const MATERIAL_FLAGS_OFFSET = TRIANGLE_DATA_LAYOUT.MATERIAL_FLAGS_OFFSET;
+		const MESH_INDEX_OFFSET = TRIANGLE_DATA_LAYOUT.MESH_INDEX_OFFSET;
+		// Flat array or ChunkedRecords; the chunk is resolved once per triangle.
+		const chunked = triangleData && triangleData.chunks ? triangleData : null;
+		const chunkedF = chunked ? chunked.viewAs( Float32Array ) : null;
+		const flatU = chunked ? null : triangleData;
+		const flatF = chunked ? null : new Float32Array( triangleData.buffer, triangleData.byteOffset, triangleData.length );
 
 		for ( let i = 0; i < triangleCount; i ++ ) {
 
-			const baseOffset = i * FLOATS_PER_TRIANGLE;
-			const materialIndex = Math.floor( triangleData[ baseOffset + MATERIAL_INDEX_OFFSET ] );
-			const meshIndex = Math.floor( triangleData[ baseOffset + MESH_INDEX_OFFSET ] );
+			const triU = chunked ? chunked.chunkFor( i ) : flatU;
+			const triFloats = chunked ? chunkedF.chunkFor( i ) : flatF;
+			const baseOffset = chunked ? chunked.baseOf( i ) : i * FLOATS_PER_TRIANGLE;
+			const materialIndex = triU[ baseOffset + MATERIAL_FLAGS_OFFSET ] & TRI_MATERIAL_MASK;
+			const meshIndex = triU[ baseOffset + MESH_INDEX_OFFSET ];
 
 			// Get material
 			const material = materials[ materialIndex ];
@@ -73,16 +85,25 @@ export class EmissiveTriangleBuilder {
 			if ( isEmissive ) {
 
 				// Calculate triangle area for power weighting
-				// Positions are at offsets 0-11
-				const v0x = triangleData[ baseOffset + 0 ];
-				const v0y = triangleData[ baseOffset + 1 ];
-				const v0z = triangleData[ baseOffset + 2 ];
-				const v1x = triangleData[ baseOffset + 4 ];
-				const v1y = triangleData[ baseOffset + 5 ];
-				const v1z = triangleData[ baseOffset + 6 ];
-				const v2x = triangleData[ baseOffset + 8 ];
-				const v2y = triangleData[ baseOffset + 9 ];
-				const v2z = triangleData[ baseOffset + 10 ];
+				// Positions are at offsets 0-11, in the instance's own space
+				// `meshIndex` names the template the triangle belongs to, never a row of the
+				// per-placement table: indexing the table with it put one object's matrix on
+				// another object's light as soon as any instanced mesh came earlier.
+				const placement = table?.placementRunOf?.( meshIndex )?.start ?? - 1;
+				const hasInstance = placement >= 0 && table.isSet[ placement ];
+				const m = hasInstance ? table.world : null;
+				const mo = hasInstance ? placement * 16 : 0;
+				const px = ( x, y, z ) => ( m ? m[ mo ] * x + m[ mo + 4 ] * y + m[ mo + 8 ] * z + m[ mo + 12 ] : x );
+				const py = ( x, y, z ) => ( m ? m[ mo + 1 ] * x + m[ mo + 5 ] * y + m[ mo + 9 ] * z + m[ mo + 13 ] : y );
+				const pz = ( x, y, z ) => ( m ? m[ mo + 2 ] * x + m[ mo + 6 ] * y + m[ mo + 10 ] * z + m[ mo + 14 ] : z );
+
+				const o0x = triFloats[ baseOffset + 0 ], o0y = triFloats[ baseOffset + 1 ], o0z = triFloats[ baseOffset + 2 ];
+				const o1x = triFloats[ baseOffset + 4 ], o1y = triFloats[ baseOffset + 5 ], o1z = triFloats[ baseOffset + 6 ];
+				const o2x = triFloats[ baseOffset + 8 ], o2y = triFloats[ baseOffset + 9 ], o2z = triFloats[ baseOffset + 10 ];
+
+				const v0x = px( o0x, o0y, o0z ), v0y = py( o0x, o0y, o0z ), v0z = pz( o0x, o0y, o0z );
+				const v1x = px( o1x, o1y, o1z ), v1y = py( o1x, o1y, o1z ), v1z = pz( o1x, o1y, o1z );
+				const v2x = px( o2x, o2y, o2z ), v2y = py( o2x, o2y, o2z ), v2z = pz( o2x, o2y, o2z );
 
 				const area = this._calculateTriangleArea( v0x, v0y, v0z, v1x, v1y, v1z, v2x, v2y, v2z );
 
@@ -119,6 +140,7 @@ export class EmissiveTriangleBuilder {
 					triangleIndex: i,
 					materialIndex: materialIndex,
 					meshIndex: meshIndex,
+					instanceLeaf: hasInstance ? table.tlasLeafIndex[ placement ] : - 1,
 					power: power,
 					area: area,
 					emissive: { r: emissive.r, g: emissive.g, b: emissive.b },
@@ -369,7 +391,10 @@ export class EmissiveTriangleBuilder {
 			data[ offset + 0 ] = tri.triangleIndex;
 			data[ offset + 1 ] = tri.power;
 			data[ offset + 2 ] = this.cdfArray[ i ];
-			data[ offset + 3 ] = this.totalEmissivePower > 0 ? tri.power / this.totalEmissivePower : 0;
+			// Slot 3 used to repeat power/total, which the shader recomputes anyway. It now
+			// names the TLAS leaf that owns this emitter, so sampling can put the triangle
+			// back into world space.
+			data[ offset + 3 ] = tri.instanceLeaf;
 
 			// vec4[1]: pre-multiplied emission (emissive * intensity), area
 			data[ offset + 4 ] = tri.emissive.r * tri.emissiveIntensity;
@@ -600,11 +625,13 @@ export class EmissiveTriangleBuilder {
 			const tri = tris[ origIdx ];
 			const offset = i * 8;
 
-			// vec4[0]: triangleIndex, power, cdf, selectionPdf
+			// vec4[0]: triangleIndex, power, cdf, instance. This is the authoritative writer —
+			// buildLightBVH re-sorts the entries and replaces emissiveTriangleData, so the
+			// instance has to be carried here too, not only in createEmissiveRawData.
 			data[ offset + 0 ] = tri.triangleIndex;
 			data[ offset + 1 ] = tri.power;
 			data[ offset + 2 ] = this.cdfArray[ i ];
-			data[ offset + 3 ] = this.totalEmissivePower > 0 ? tri.power / this.totalEmissivePower : 0;
+			data[ offset + 3 ] = tri.instanceLeaf;
 
 			// vec4[1]: pre-multiplied emission (emissive * intensity), area
 			data[ offset + 4 ] = tri.emissive.r * tri.emissiveIntensity;