rayzee 11.2.0 → 11.3.0

package/src/Processor/GeometryExtractor.js

@@ -148,6 +148,26 @@ export function geometryBytesOf( object ) {
 
 }
 
+/** Bytes of InstancedMesh matrix lists under `object`, each list once however many meshes share it. */
+export function instanceBytesOf( object ) {
+
+	let bytes = 0;
+	const counted = new Set();
+	object.traverse?.( node => {
+
+		const array = node.isInstancedMesh ? node.instanceMatrix?.array : null;
+		if ( array && ! counted.has( array ) ) {
+
+			counted.add( array );
+			bytes += array.byteLength;
+
+		}
+
+	} );
+	return bytes;
+
+}
+
 // Affine point and linear direction transforms straight off the matrix elements: no perspective
 // divide, no method dispatch, on the hottest per-vertex path of a baked mesh.
 function affinePoint( v, e ) {
@@ -187,6 +207,54 @@ function determinant3( e ) {
 
 }
 
+/**
+ * Whether any material under `object` holds a texture, so the GPU needs the triangles' texture coordinates. A scene
+ * with none (Moana's USD: its Ptex is baked into colours) is uploaded without them.
+ */
+export function usesTextureCoordinates( object ) {
+
+	let uses = false;
+	const seen = new Set();
+	object.traverse( node => {
+
+		if ( uses || ! node.isMesh || ! node.material ) return;
+		for ( const material of Array.isArray( node.material ) ? node.material : [ node.material ] ) {
+
+			if ( seen.has( material ) ) continue;
+			seen.add( material );
+			for ( const key in material ) if ( material[ key ]?.isTexture ) uses = true;
+
+		}
+
+	} );
+	return uses;
+
+}
+
+/**
+ * Stores a geometry's float attribute in [−1, 1] as normalized 16-bit integers, which three.js reads back as floats.
+ * Left as floats when out of that range (or NaN) rather than silently clamped, or when morph targets use it.
+ */
+export function packUnitAttribute( g, name ) {
+
+	const attr = g.getAttribute( name );
+	if ( ! attr || attr.normalized || ! ( attr.array instanceof Float32Array ) ) return;
+	if ( g.morphAttributes?.[ name ]?.length ) return;
+
+	const src = attr.array;
+	for ( let i = 0; i < src.length; i ++ ) {
+
+		const v = src[ i ];
+		if ( ! ( v >= - 1.0001 && v <= 1.0001 ) ) return;
+
+	}
+
+	const packed = new Int16Array( src.length );
+	for ( let i = 0; i < src.length; i ++ ) packed[ i ] = Math.round( Math.max( - 1, Math.min( 1, src[ i ] ) ) * 32767 );
+	g.setAttribute( name, new BufferAttribute( packed, attr.itemSize, true ) );
+
+}
+
 export class GeometryExtractor {
 
 	/** @param {{issues?: import('../EngineIssues.js').IssueLog}} [options] */
@@ -252,7 +320,6 @@ export class GeometryExtractor {
 
 		// Single traversal: extract geometry, materials, lights, and cameras
 		this.traverseObject( object );
-		this._shareInstanceMatrices();
 		this._compressAttributes( object );
 
 		this.logStats();
@@ -307,7 +374,6 @@ export class GeometryExtractor {
 
 		}
 
-		this._shareInstanceMatrices();
 		this._compressAttributes( object );
 		this.triangles.trimInPlace( this.currentTriangleIndex );
 		this._streamedStore = true;
@@ -448,6 +514,7 @@ export class GeometryExtractor {
 			placements: this._countPlacements( object ),
 			meshes,
 			geometryBytes: geometryBytesOf( object ),
+			instanceBytes: instanceBytesOf( object ),
 		};
 
 	}
@@ -502,9 +569,71 @@ export class GeometryExtractor {
 		this.instanceCount = 0;
 		this.instanceCapacity = count;
 		this.instanceSource = new Int32Array( count );
-		this.instanceMatrices = new Float32Array( count * 16 );
-		this._shareable = [];
+		// Placement transforms as runs of rows (InstanceTable): an InstancedMesh's own matrix list read where it is,
+		// or rows of the extractor's own. A copy of every list was 3 GB beside them on the Moana island.
+		this._runs = { first: [], arrays: [], arrayOf: [], base: [], owned: [] };
+		this._runArrayIndex = new Map();
+		this._singles = null;
+		this._singlesUsed = 0;
+		this._singlesRun = null;
 		this._compressed = new Set();
+		this._matrixLists = new Map();
+
+	}
+
+	/** Starts a run of rows at the next placement. @private */
+	_beginRun( array, base, owned ) {
+
+		const runs = this._runs;
+		let a = this._runArrayIndex.get( array );
+		if ( a === undefined ) this._runArrayIndex.set( array, a = runs.arrays.push( array ) - 1 );
+		runs.first.push( this.instanceCount );
+		runs.arrayOf.push( a );
+		runs.base.push( base );
+		runs.owned.push( owned );
+
+	}
+
+	/** The row for a placement of a mesh without instances, appended to the extractor's own array. @private */
+	_singleRow() {
+
+		const runs = this._runs;
+		if ( ! this._singles ) {
+
+			this._singles = new Float32Array( 1024 * 16 );
+			this._singlesIndex = runs.arrays.push( this._singles ) - 1;
+
+		}
+
+		if ( this._singlesUsed + 16 > this._singles.length ) {
+
+			const grown = new Float32Array( this._singles.length * 2 );
+			grown.set( this._singles );
+			this._singles = runs.arrays[ this._singlesIndex ] = grown;
+
+		}
+
+		if ( this._singlesRun !== runs.first.length - 1 ) {
+
+			runs.first.push( this.instanceCount );
+			runs.arrayOf.push( this._singlesIndex );
+			runs.base.push( this._singlesUsed );
+			runs.owned.push( 1 );
+			this._singlesRun = runs.first.length - 1;
+
+		}
+
+		const o = this._singlesUsed;
+		this._singlesUsed += 16;
+		return o;
+
+	}
+
+	/** The runs, closed at the placement count (InstanceTable.allocate). @private */
+	_matrixRuns() {
+
+		const runs = this._runs;
+		return { first: [ ...runs.first, this.instanceCount ], arrays: runs.arrays, arrayOf: runs.arrayOf, base: runs.base, owned: runs.owned };
 
 	}
 
@@ -543,59 +672,7 @@ export class GeometryExtractor {
 		if ( this._compressed.has( g.uuid ) ) return;
 		this._compressed.add( g.uuid );
 
-		for ( const name of [ 'normal', 'tangent', 'color' ] ) {
-
-			const attr = g.getAttribute( name );
-			if ( ! attr || attr.normalized || ! ( attr.array instanceof Float32Array ) ) continue;
-			if ( g.morphAttributes?.[ name ]?.length ) continue;
-
-			const src = attr.array;
-			let ok = true;
-			for ( let i = 0; i < src.length; i ++ ) {
-
-				const v = src[ i ];
-				if ( ! ( v >= - 1.0001 && v <= 1.0001 ) ) {
-
-					ok = false; break;
-
-				}
-
-			}
-
-			// Out of snorm range (or NaN) — leave it as floats rather than silently clamp.
-			if ( ! ok ) continue;
-
-			const packed = new Int16Array( src.length );
-			for ( let i = 0; i < src.length; i ++ ) {
-
-				packed[ i ] = Math.round( Math.max( - 1, Math.min( 1, src[ i ] ) ) * 32767 );
-
-			}
-
-			g.setAttribute( name, new BufferAttribute( packed, attr.itemSize, true ) );
-
-		}
-
-	}
-
-	/**
-	 * Point each InstancedMesh's matrix attribute at the placement pool that duplicates it.
-	 *
-	 * With the host at the origin the two hold identical bytes — 366 MB apart at 6M instances.
-	 * Runs after the traversal, since growth reallocates the pool.
-	 * @private
-	 */
-	_shareInstanceMatrices() {
-
-		for ( const { mesh, start, count } of this._shareable ) {
-
-			const attr = mesh.instanceMatrix;
-			if ( ! attr || attr.array.length !== count * 16 ) continue;
-			attr.array = this.instanceMatrices.subarray( start * 16, ( start + count ) * 16 );
-
-		}
-
-		this._shareable = [];
+		for ( const name of [ 'normal', 'tangent', 'color' ] ) packUnitAttribute( g, name );
 
 	}
 
@@ -755,7 +832,7 @@ export class GeometryExtractor {
 			};
 			this.expandedTriangleCount += shared.count;
 			this.meshTriangleRanges.push( range );
-			this._recordPlacements( mesh, meshIndex );
+			this._recordPlacements( mesh, meshIndex, false, false, shared.count > 0 );
 			return;
 
 		}
@@ -785,7 +862,7 @@ export class GeometryExtractor {
 		this.expandedTriangleCount += range.count;
 		this.meshTriangleRanges.push( range );
 		if ( range.count > 0 && ! bake && shareable ) this._geometryRanges.set( key, { ...range, meshIndex } );
-		this._recordPlacements( mesh, meshIndex, bake, expand );
+		this._recordPlacements( mesh, meshIndex, bake, expand, range.count > 0 && shareable );
 		if ( range.count > 0 ) this._onRange?.( meshIndex, range );
 
 	}
@@ -796,10 +873,9 @@ export class GeometryExtractor {
 	 * a matrix each rather than a million Object3Ds.
 	 * @private
 	 */
-	_recordPlacements( mesh, meshIndex, baked = false, expanded = false ) {
+	_recordPlacements( mesh, meshIndex, baked = false, expanded = false, groupable = false ) {
 
 		const world = mesh.matrixWorld.elements;
-		const dst = this.instanceMatrices;
 		const src = this.instanceSource;
 
 		// Expanded instances live in the triangles, so the mesh keeps a single placement. The
@@ -807,6 +883,8 @@ export class GeometryExtractor {
 		// every instance equally, which is exactly what composing against it produces.
 		if ( ! mesh.isInstancedMesh || ! mesh.instanceMatrix || expanded ) {
 
+			const d = this._singleRow();
+			const dst = this._singles;
 			const p = this._nextPlacement();
 			src[ p ] = meshIndex;
 
@@ -814,12 +892,12 @@ export class GeometryExtractor {
 
 				// The triangles already carry this pose, so the placement starts at identity. A
 				// later move composes against the inverse of what was baked in.
-				for ( let k = 0; k < 16; k ++ ) dst[ p * 16 + k ] = k % 5 === 0 ? 1 : 0;
+				for ( let k = 0; k < 16; k ++ ) dst[ d + k ] = k % 5 === 0 ? 1 : 0;
 				this.bakeInverse.set( meshIndex, Float32Array.from( this._matrixPool.mat4.copy( mesh.matrixWorld ).invert().elements ) );
 
 			} else {
 
-				for ( let k = 0; k < 16; k ++ ) dst[ p * 16 + k ] = world[ k ];
+				for ( let k = 0; k < 16; k ++ ) dst[ d + k ] = world[ k ];
 
 			}
 
@@ -829,27 +907,28 @@ export class GeometryExtractor {
 
 		const arr = mesh.instanceMatrix.array;
 		const count = mesh.count ?? ( arr.length / 16 );
-		// A pbrt archive bakes the CTM into every instance, so the host needs no multiply.
-		const identityHost = isIdentityElements( world );
-		if ( identityHost && arr.length === count * 16 ) {
+		if ( groupable && count > 0 ) {
 
-			this._shareable.push( { mesh, start: this.instanceCount, count } );
+			let list = this._matrixLists.get( mesh.instanceMatrix );
+			if ( ! list ) this._matrixLists.set( mesh.instanceMatrix, list = [] );
+			list.push( { meshIndex, start: this.instanceCount, count, world: Float32Array.from( world ) } );
 
 		}
 
+		if ( count <= 0 ) return;
+
+		// A pbrt archive bakes the CTM into every instance, so the host needs no multiply and the list is read in place.
+		const identityHost = isIdentityElements( world ) && arr.length >= count * 16;
+		const dst = identityHost ? arr : new Float32Array( count * 16 );
+		this._beginRun( identityHost ? mesh.instanceMatrix : dst, 0, identityHost ? 0 : 1 );
+
 		for ( let i = 0; i < count; i ++ ) {
 
 			const o = i * 16;
 			const p = this._nextPlacement();
-			const d = p * 16;
+			const d = i * 16;
 			src[ p ] = meshIndex;
-
-			if ( identityHost ) {
-
-				for ( let k = 0; k < 16; k ++ ) dst[ d + k ] = arr[ o + k ];
-				continue;
-
-			}
+			if ( identityHost ) continue;
 
 			// world = mesh.matrixWorld * instanceMatrix, both column-major.
 			for ( let c = 0; c < 4; c ++ ) {
@@ -869,6 +948,39 @@ export class GeometryExtractor {
 
 	}
 
+	/**
+	 * Instanced meshes sharing one matrix attribute under the same host transform: one object traced once a copy
+	 * (InstanceTable.setGroups). A scene builder shares the attribute between a template's shapes for this.
+	 * @returns {Array<{members: number[], starts: number[], count: number}>}
+	 * @private
+	 */
+	_instanceGroups() {
+
+		const groups = [];
+		for ( const list of this._matrixLists.values() ) {
+
+			const open = [];
+			for ( const member of list ) {
+
+				const group = open.find( g => g.count === member.count && g.world.every( ( v, k ) => v === member.world[ k ] ) );
+				if ( group ) {
+
+					group.members.push( member.meshIndex );
+					group.starts.push( member.start );
+
+				} else open.push( { world: member.world, count: member.count, members: [ member.meshIndex ], starts: [ member.start ] } );
+
+			}
+
+			for ( const g of open ) if ( g.members.length >= 2 ) groups.push( { members: g.members, starts: g.starts, count: g.count } );
+
+		}
+
+		this._matrixLists.clear();
+		return groups;
+
+	}
+
 	/** Next free placement slot, growing only if the pre-count was short. @private */
 	_nextPlacement() {
 
@@ -876,11 +988,8 @@ export class GeometryExtractor {
 
 			const grown = Math.max( 16, this.instanceCapacity * 2 );
 			const srcCol = new Int32Array( grown );
-			const matCol = new Float32Array( grown * 16 );
 			srcCol.set( this.instanceSource );
-			matCol.set( this.instanceMatrices );
 			this.instanceSource = srcCol;
-			this.instanceMatrices = matCol;
 			this.instanceCapacity = grown;
 
 		}
@@ -1566,8 +1675,9 @@ export class GeometryExtractor {
 			meshTriangleRanges: this.meshTriangleRanges, // Per-mesh { start, count } for TLAS/BLAS
 			expandedTriangleCount: this.expandedTriangleCount,
 			instanceSource: this.instanceSource.subarray( 0, this.instanceCount ),
-			instanceMatrices: this.instanceMatrices.subarray( 0, this.instanceCount * 16 ),
+			matrixRuns: this._matrixRuns(),
 			instanceCount: this.instanceCount,
+			instanceGroups: this._instanceGroups(),
 			// meshIndex -> inverse of the pose baked into its triangles; only baked meshes appear.
 			bakeInverse: this.bakeInverse,
 			maps: this.maps,

package/src/Processor/HostMemory.js

@@ -29,8 +29,17 @@ const BVH_NODE_BYTES = 64;
  */
 const NODES_PER_TRIANGLE = 0.9;
 
-/** Bytes per placement in the instance table: a mat4 of world transform. */
-const PLACEMENT_BYTES = 64;
+/**
+ * Bytes per placement in the instance table's own columns, measured on the Moana island (1,415 MB for 51.0M). Its
+ * transforms are read where the scene keeps them (an InstancedMesh's matrix list, `instanceBytes`), not copied.
+ */
+const PLACEMENT_BYTES = 28;
+
+/**
+ * Bytes per placement while a spilling build makes its TLAS: the tree, a quarter of it per copy once copies are
+ * clustered, plus the boxes it is built from. Measured on the island: ~2.3 GB at 51.0M.
+ */
+const TLAS_PHASE_BYTES = 45;
 
 /** Bytes per triangle of per-template reorder map, one Uint32 each. */
 const ORDER_MAP_BYTES = 4;
@@ -59,11 +68,14 @@ export const SAFE_SCENE_BYTES = 7040 * 1024 * 1024;
  */
 export const MAX_SCENE_BYTES = 9216 * 1024 * 1024;
 
-// Scene-archive budgets with the memory spill on: the triangles and BVH leave the heap as the build goes, so the host
-// passes these instead of the importer's own. The whole 15-part Moana subset (55.7M / 7.0M) loads cold under them, at
-// an 8.1 GB preflight estimate; the preflight, not the budget, refuses anything larger.
-export const SPILL_TRIANGLE_BUDGET = 60_000_000;
-export const SPILL_PLACEMENT_BUDGET = 8_000_000;
+// Scene-archive budgets with the memory spill on: the triangles, BVH and geometry leave the heap as the build goes, so
+// the host passes these instead of the importer's own. The whole USD island (111.6M triangles, 51.0M placements) loads
+// under them in Chrome on a 24 GB M-series: 304 s, tab peak ~13 GB, 13 GB of GPU buffers. The preflight, not the
+// budget, refuses anything larger.
+export const SPILL_TRIANGLE_BUDGET = 120_000_000;
+export const SPILL_PLACEMENT_BUDGET = 60_000_000;
+/** Widest environment kept with memory spill on; a wider one is box-filtered down (AssetLoader). */
+export const SPILL_ENVIRONMENT_WIDTH = 8192;
 
 /**
  * The host's memory in GB: the host's own figure when it gives one, else Chrome's
@@ -96,21 +108,39 @@ const PROBE_CEILING_BYTES = 12 * 1024 * 1024 * 1024;
  * @returns {{total: number, triangles: number, bvh: number, geometry: number,
  *   placements: number, orderMaps: number}} bytes
  */
-export function estimateSceneBytes( { triangles, placements, geometryBytes = 0 } ) {
+export function estimateSceneBytes( { triangles, placements, geometryBytes = 0, instanceBytes = 0 } ) {
 
 	const parts = {
 		triangles: triangles * TRIANGLE_BYTES,
 		bvh: Math.ceil( triangles * NODES_PER_TRIANGLE ) * BVH_NODE_BYTES,
 		geometry: geometryBytes,
+		instances: instanceBytes,
 		placements: placements * PLACEMENT_BYTES,
 		orderMaps: triangles * ORDER_MAP_BYTES,
 	};
 
-	parts.total = parts.triangles + parts.bvh + parts.geometry + parts.placements + parts.orderMaps;
+	parts.total = parts.triangles + parts.bvh + parts.geometry + parts.instances + parts.placements + parts.orderMaps;
 	return parts;
 
 }
 
+/**
+ * A spilling, streamed build's peak: the larger of its two phases, since neither the triangles, the BLASes nor the
+ * three.js geometry are resident once each has been read. Extraction holds the geometry, the matrix lists and
+ * `residentTriangleBytes` of records; the TLAS phase the lists, the table, the tree being built and the order maps.
+ * @param {ReturnType<typeof estimateSceneBytes>} parts
+ * @param {number} placements
+ * @param {number} residentTriangleBytes
+ * @returns {number} bytes
+ */
+export function spillingPeakBytes( parts, placements, residentTriangleBytes ) {
+
+	const extraction = parts.geometry + parts.instances + placements * 4 + residentTriangleBytes;
+	const tlas = parts.instances + parts.placements + placements * TLAS_PHASE_BYTES + parts.orderMaps;
+	return Math.max( extraction, tlas );
+
+}
+
 /**
  * How many bytes this process can still place in chunk-sized pieces, right now.
  *