rayzee 11.2.0 → 11.3.0

package/src/Storage/GeometrySpill.js

@@ -4,6 +4,16 @@ const PACK_BYTES = 32 * 1024 * 1024;
 const OWN_WRITE_BYTES = PACK_BYTES / 4;
 const READ_WINDOW = 64 * 1024 * 1024;
 const EMPTY = new Map();
+// Buffers a restore made: nothing else holds them, so once on disk again they are let go at once rather than at the
+// next major collection, which an idle page may not reach for minutes.
+const RESTORED = new WeakSet();
+
+function release( buffer ) {
+
+	RESTORED.delete( buffer );
+	buffer.transfer?.( 0 );
+
+}
 
 function empty( Type ) {
 
@@ -61,13 +71,25 @@ export class GeometrySpill {
 
 	}
 
-	/** Moves a geometry's arrays to disk, leaving empty arrays of the same type in their place. */
+	/** Moves a geometry's arrays to disk, leaving empty arrays of the same type in their place; its bounds stay. */
 	add( geometry ) {
 
-		const byArray = new Map();
+		if ( ! geometry.boundingBox ) geometry.computeBoundingBox();
+		if ( ! geometry.boundingSphere ) geometry.computeBoundingSphere();
+
 		const attributes = Object.values( geometry.attributes );
 		if ( geometry.index ) attributes.push( geometry.index );
+		this.addAttributes( attributes );
+
+		// What the bounds were with the arrays in place: anything computed from the empty ones must not outlive the restore.
+		this._geometries.push( { geometry, box: geometry.boundingBox.clone(), sphere: geometry.boundingSphere.clone() } );
+
+	}
 
+	/** Moves attributes' arrays to disk, each array once however many attributes share it. */
+	addAttributes( attributes ) {
+
+		const byArray = new Map();
 		for ( const attribute of attributes ) {
 
 			const array = attribute.array;
@@ -79,9 +101,6 @@ export class GeometrySpill {
 
 		}
 
-		// Bounds computed from an empty array would outlive the restore.
-		this._geometries.push( { geometry, box: geometry.boundingBox !== null, sphere: geometry.boundingSphere !== null } );
-
 	}
 
 	/** @private */
@@ -116,8 +135,9 @@ export class GeometrySpill {
 		record.at = this._packAt + this._packUsed;
 		record.pack = this._pack;
 		record.offset = this._packUsed;
-		this._packUsed += bytes.byteLength;
+		this._packUsed += record.byteLength;
 		this._packRecords.push( record );
+		if ( RESTORED.has( array.buffer ) ) release( array.buffer );
 		return record;
 
 	}
@@ -126,26 +146,35 @@ export class GeometrySpill {
 	_flushPack() {
 
 		if ( ! this._pack ) return;
-		this._queue( this._packAt, this._pack.subarray( 0, this._packUsed ), this._packRecords );
+		this._queue( this._packAt, this._pack.subarray( 0, this._packUsed ), this._packRecords, true );
 		this._pack = null;
 		this._packRecords = [];
 
 	}
 
-	/** @private */
-	_queue( at, bytes, records ) {
+	/** `own`: the buffer is this spill's (a pack), let go once written. @private */
+	_queue( at, bytes, records, own = false ) {
 
-		this._queued += bytes.byteLength;
+		const length = bytes.byteLength;
+		this._queued += length;
 		this._chain = this._chain
 			.then( async () => {
 
 				if ( this.error ) return;
 				await this._store.writeAt( at, bytes );
-				for ( const record of records ) record.array = record.pack = null;
+				for ( const record of records ) {
+
+					const buffer = record.array?.buffer;
+					record.array = record.pack = null;
+					if ( RESTORED.has( buffer ) ) release( buffer );
+
+				}
+
+				if ( own ) bytes.buffer.transfer?.( 0 );
 
 			} )
 			.catch( error => void ( this.error ??= error ) )
-			.finally( () => void ( this._queued -= bytes.byteLength ) );
+			.finally( () => void ( this._queued -= length ) );
 
 	}
 
@@ -176,6 +205,7 @@ export class GeometrySpill {
 
 				if ( ! window || record.at + record.byteLength > windowAt + window.byteLength ) {
 
+					if ( window ) release( window );
 					windowAt = record.at;
 					window = await this._store.readAt( record.at, READ_WINDOW );
 
@@ -186,14 +216,16 @@ export class GeometrySpill {
 			}
 
 			if ( array.byteLength !== record.byteLength ) throw new Error( 'geometry spill: an array came back short' );
+			if ( array !== record.array ) RESTORED.add( array.buffer );
 			for ( const attribute of record.attributes ) attribute.array = array;
 
 		}
 
+		if ( window ) release( window );
 		for ( const { geometry, box, sphere } of this._geometries ) {
 
-			if ( ! box ) geometry.boundingBox = null;
-			if ( ! sphere ) geometry.boundingSphere = null;
+			geometry.boundingBox = box;
+			geometry.boundingSphere = sphere;
 
 		}
 

package/src/Storage/SceneGraphCodec.js

@@ -192,6 +192,8 @@ export function encodeSceneGraph( root, { environment = null, animations = [], s
 
 	const sections = new SectionWriter();
 	const nodes = [];
+	// Instanced meshes sharing one matrix attribute are placed as one object; stored once, they come back shared.
+	const instanceSections = new Map();
 	const geometries = new Map();
 	const materials = new Map();
 	const textures = new Map();
@@ -228,7 +230,9 @@ export function encodeSceneGraph( root, { environment = null, animations = [], s
 		if ( object.isInstancedMesh ) {
 
 			node.count = object.count;
-			node.instanceMatrix = sections.add( object.instanceMatrix.array );
+			let matrices = instanceSections.get( object.instanceMatrix );
+			if ( ! matrices ) instanceSections.set( object.instanceMatrix, matrices = sections.add( object.instanceMatrix.array ) );
+			node.instanceMatrix = matrices;
 			node.instanceColor = object.instanceColor ? sections.add( object.instanceColor.array ) : null;
 
 		}
@@ -355,9 +359,16 @@ async function readSections( file, sections ) {
 function sectionsOf( manifest ) {
 
 	const all = [];
+	const seen = new Set();
 	for ( const node of manifest.nodes ) {
 
-		if ( node.instanceMatrix ) all.push( node.instanceMatrix );
+		if ( node.instanceMatrix && ! seen.has( node.instanceMatrix.offset ) ) {
+
+			seen.add( node.instanceMatrix.offset );
+			all.push( node.instanceMatrix );
+
+		}
+
 		if ( node.instanceColor ) all.push( node.instanceColor );
 
 	}
@@ -408,6 +419,7 @@ export async function decodeSceneGraph( manifest, data, { loadTexture } ) {
 
 	const arrays = await readSections( data, sectionsOf( manifest ) );
 	const section = ( record ) => arrays.get( record.offset );
+	const instanceMatrices = new Map();
 
 	const textures = {};
 	for ( const record of manifest.textures ) {
@@ -476,7 +488,9 @@ export async function decodeSceneGraph( manifest, data, { loadTexture } ) {
 
 				// Built for one instance, then given the stored matrices: no second full-size array.
 				object = new InstancedMesh( geometries[ node.geometry ], material, 1 );
-				object.instanceMatrix = new InstancedBufferAttribute( section( node.instanceMatrix ), 16 );
+				let matrices = instanceMatrices.get( node.instanceMatrix.offset );
+				if ( ! matrices ) instanceMatrices.set( node.instanceMatrix.offset, matrices = new InstancedBufferAttribute( section( node.instanceMatrix ), 16 ) );
+				object.instanceMatrix = matrices;
 				object.count = node.count;
 				if ( node.instanceColor ) object.instanceColor = new InstancedBufferAttribute( section( node.instanceColor ), 3 );
 				break;

package/src/Storage/SpillStore.js

@@ -99,6 +99,15 @@ export class SpillStore {
 
 	}
 
+	/** Reads chunk `k` into `target` (bytes) and lets the read buffer go at once, not at the next major collection. */
+	async readInto( k, target ) {
+
+		const buffer = await this.read( k, target.byteLength );
+		target.set( new Uint8Array( buffer ) );
+		buffer.transfer?.( 0 );
+
+	}
+
 	async dispose() {
 
 		if ( this._writer ) await this._writer.abort();

package/src/TSL/BVHTraversal.js

@@ -10,6 +10,7 @@ import {
 	If,
 	Loop,
 	Break,
+	Continue,
 	select,
 	abs,
 	sign,
@@ -27,7 +28,7 @@ import {
 
 import {
 	TRI_MATERIAL_MASK, TRI_SIDE_SHIFT, BVH_LEAF_MARKERS, BVH_MAX_INDEX, BVH_FOLDED_LEAF_MAX,
-	TLAS_LEAF_IDENTITY,
+	TLAS_LEAF_IDENTITY, COPY_ENTRY, CLUSTER_FIRST_MASK, CLUSTER_COUNT_SHIFT, CLUSTER_SIZE, CLUSTER_ROOT_MASK, CLUSTER_COPY_HIDDEN,
 } from '../Processor/BufferLayout.js';
 import { HitInfo } from './Struct.js';
 import {
@@ -83,6 +84,61 @@ const toObjectDir = ( rows, d ) => vec3(
 	rows[ 2 ].xyz.dot( d )
 );
 
+// Copy clusters (BufferLayout CLUSTER_LEAF): a leaf pushes a COPY_ENTRY for each copy whose byte box the ray reaches,
+// farthest first so the nearest is entered first, as an inner node orders its children; popping one moves the ray into
+// that copy and pushes its object's root.
+
+// Compare-swaps sorting up to four ascending.
+const SORT_NETWORKS = [[], [], [[ 0, 1 ]], [[ 0, 1 ], [ 1, 2 ], [ 0, 1 ]], [[ 0, 1 ], [ 2, 3 ], [ 0, 2 ], [ 1, 3 ], [ 1, 2 ]]];
+
+const pushHitCopies = ( bvhBuffer, nodeIndex, nodeData0, origin, invDir, stack, stackPtr, limit ) => {
+
+	const d1 = getDatafromStorageBuffer( bvhBuffer, nodeIndex, int( 1 ), int( BVH_STRIDE ) );
+	const d2 = getDatafromStorageBuffer( bvhBuffer, nodeIndex, int( 2 ), int( BVH_STRIDE ) );
+	const base = vec3( nodeData0.z, d1.x, d1.y ).toVar();
+	const exps = floatBitsToUint( nodeData0.y ).toVar();
+	const stepOf = ( a ) => uintBitsToFloat( exps.shiftRight( uint( a * 8 ) ).bitAnd( uint( 255 ) ).shiftLeft( uint( 23 ) ) );
+	const step = vec3( stepOf( 0 ), stepOf( 1 ), stepOf( 2 ) ).toVar();
+	const lo = [ floatBitsToUint( d1.z ).toVar(), floatBitsToUint( d1.w ).toVar(), floatBitsToUint( d2.x ).toVar() ];
+	const hi = [ floatBitsToUint( d2.y ).toVar(), floatBitsToUint( d2.z ).toVar(), floatBitsToUint( d2.w ).toVar() ];
+	const count = int( floatBitsToUint( nodeData0.x ).shiftRight( uint( CLUSTER_COUNT_SHIFT ) ).bitAnd( uint( 3 ) ) ).add( 1 ).toVar();
+	const byte = ( word, k ) => float( word.shiftRight( uint( k * 8 ) ).bitAnd( uint( 255 ) ) );
+
+	const dist = [], slot = [];
+	for ( let k = 0; k < CLUSTER_SIZE; k ++ ) {
+
+		const boxMin = base.add( vec3( byte( lo[ 0 ], k ), byte( lo[ 1 ], k ), byte( lo[ 2 ], k ) ).mul( step ) );
+		const boxMax = base.add( vec3( byte( hi[ 0 ], k ), byte( hi[ 1 ], k ), byte( hi[ 2 ], k ) ).mul( step ) );
+		const d = fastRayAABBDst( { rayOrigin: origin, invDir, boxMin, boxMax } );
+		dist.push( select( int( k ).lessThan( count ).and( d.lessThan( limit ) ), d, float( 1e30 ) ).toVar() );
+		slot.push( int( k ).toVar() );
+
+	}
+
+	for ( const [ a, b ] of SORT_NETWORKS[ CLUSTER_SIZE ] ) {
+
+		If( dist[ b ].lessThan( dist[ a ] ), () => {
+
+			const td = float( dist[ a ] ).toVar(), ts = int( slot[ a ] ).toVar();
+			dist[ a ].assign( dist[ b ] ); slot[ a ].assign( slot[ b ] );
+			dist[ b ].assign( td ); slot[ b ].assign( ts );
+
+		} );
+
+	}
+
+	for ( let k = CLUSTER_SIZE - 1; k >= 0; k -- ) {
+
+		If( dist[ k ].lessThan( limit ).and( stackPtr.lessThan( int( MAX_STACK_DEPTH ) ) ), () => {
+
+			stack.element( stackPtr ).assign( int( uint( COPY_ENTRY ).bitOr( uint( nodeIndex ).shiftLeft( uint( 2 ) ) ).bitOr( uint( slot[ k ] ) ) ) );
+			stackPtr.addAssign( 1 );
+
+		} );
+
+	}
+
+};
 
 // ================================================================================
 // RAY INTERSECTION HELPERS (inlined for BVH traversal performance)
@@ -301,6 +357,49 @@ const makeTraverseBVH = ( trackStats ) => Fn( ( [
 	const instExit = int( 0 ).toVar();
 	const hitInstLeaf = int( - 1 ).toVar();
 
+	// Built over copy clusters: the copies' transforms are records from vec4 `copyRecordBase` (BufferLayout).
+	const clustered = bvhBuffer.value?.copyRecordBase !== undefined;
+	const enterCopy = ( entry ) => {
+
+		const leaf = int( uint( entry ).bitAnd( uint( ~ COPY_ENTRY >>> 0 ) ).shiftRight( uint( 2 ) ) );
+		const k = uint( entry ).bitAnd( uint( 3 ) ).toVar();
+		const head = getDatafromStorageBuffer( bvhBuffer, leaf, int( 0 ), int( BVH_STRIDE ) );
+		const words = floatBitsToUint( getDatafromStorageBuffer( bvhBuffer, leaf, int( 3 ), int( BVH_STRIDE ) ) ).toVar();
+		const word = select( k.equal( uint( 0 ) ), words.x, select( k.equal( uint( 1 ) ), words.y, select( k.equal( uint( 2 ) ), words.z, words.w ) ) ).toVar();
+
+		If( word.bitAnd( uint( CLUSTER_COPY_HIDDEN ) ).equal( uint( 0 ) ), () => {
+
+			If( word.bitAnd( uint( TLAS_LEAF_IDENTITY ) ).equal( uint( 0 ) ), () => {
+
+				const record = int( floatBitsToUint( head.x ).bitAnd( uint( CLUSTER_FIRST_MASK ) ).add( k ) ).toVar();
+				const rows = instanceRows( bvhBuffer, record );
+				const localDir = toObjectDir( rows, worldDirection ).toVar();
+
+				rayOrigin.assign( toObjectPoint( rows, worldOrigin ) );
+				rayDirection.assign( localDir );
+				const localInv = buildInvDir( localDir ).toVar();
+				invDir.assign( localInv );
+				woopParams.assign( computeWoopFromInvDir( { rayDir: localDir, invDir: localInv } ) );
+				instLeaf.assign( record );
+				instExit.assign( stackPtr );
+
+			} ).Else( () => {
+
+				rayOrigin.assign( worldOrigin );
+				rayDirection.assign( worldDirection );
+				invDir.assign( worldInvDir );
+				woopParams.assign( worldWoop );
+				instLeaf.assign( int( - 1 ) );
+
+			} );
+
+			stack.element( stackPtr ).assign( int( word.bitAnd( uint( CLUSTER_ROOT_MASK ) ) ) );
+			stackPtr.addAssign( 1 );
+
+		} );
+
+	};
+
 	// Emitted once per leaf kind, in its own branch: hoisted below both, the range stayed live
 	// through the inner-node path and cost 9–13 % of traversal time.
 	const testLeaf = ( first, count ) => {
@@ -403,7 +502,11 @@ const makeTraverseBVH = ( trackStats ) => Fn( ( [
 
 					testLeaf( floatBitsToUint( nodeData0.x ), floatBitsToUint( nodeData0.y ) );
 
-				} ).Else( () => {
+				} ).Else( clustered ? () => {
+
+					pushHitCopies( bvhBuffer, nodeIndex, nodeData0, worldOrigin, worldInvDir, stack, stackPtr, closestHit.dst );
+
+				} : () => {
 
 					// BLAS-pointer leaf — enter the instance if the mesh is visible.
 					// nodeData0: [blasRootNodeIndex, meshIndex, visibility, -2]; slots 4..15 hold
@@ -487,9 +590,22 @@ const makeTraverseBVH = ( trackStats ) => Fn( ( [
 
 		};
 
+		// A copy continues the loop: the visit nested in an Else overflowed the JS stack building the island's kernels.
+		const dispatch = clustered ? () => {
+
+			If( entry.greaterThanEqual( int( COPY_ENTRY ) ), () => {
+
+				enterCopy( entry );
+				Continue();
+
+			} );
+			visitNode();
+
+		} : visitNode;
+
 		// Only a folded BVH has negative entries: a leaf folded into its parent, tested with no fetch.
-		if ( folded ) If( entry.lessThan( int( 0 ) ), () => testLeaf( foldedFirst( entry ), foldedCount( entry ) ) ).Else( visitNode );
-		else visitNode();
+		if ( folded ) If( entry.lessThan( int( 0 ) ), () => testLeaf( foldedFirst( entry ), foldedCount( entry ) ) ).Else( dispatch );
+		else dispatch();
 
 	} );
 
@@ -583,6 +699,49 @@ const makeTraverseBVHShadow = ( cameraCulled ) => Fn( ( [
 	const instExit = int( 0 ).toVar();
 	const blocked = tslBool( false ).toVar();
 
+	// Built over copy clusters: the copies' transforms are records from vec4 `copyRecordBase` (BufferLayout).
+	const clustered = bvhBuffer.value?.copyRecordBase !== undefined;
+	const enterCopy = ( entry ) => {
+
+		const leaf = int( uint( entry ).bitAnd( uint( ~ COPY_ENTRY >>> 0 ) ).shiftRight( uint( 2 ) ) );
+		const k = uint( entry ).bitAnd( uint( 3 ) ).toVar();
+		const head = getDatafromStorageBuffer( bvhBuffer, leaf, int( 0 ), int( BVH_STRIDE ) );
+		const words = floatBitsToUint( getDatafromStorageBuffer( bvhBuffer, leaf, int( 3 ), int( BVH_STRIDE ) ) ).toVar();
+		const word = select( k.equal( uint( 0 ) ), words.x, select( k.equal( uint( 1 ) ), words.y, select( k.equal( uint( 2 ) ), words.z, words.w ) ) ).toVar();
+
+		If( word.bitAnd( uint( CLUSTER_COPY_HIDDEN ) ).equal( uint( 0 ) ), () => {
+
+			If( word.bitAnd( uint( TLAS_LEAF_IDENTITY ) ).equal( uint( 0 ) ), () => {
+
+				const record = int( floatBitsToUint( head.x ).bitAnd( uint( CLUSTER_FIRST_MASK ) ).add( k ) ).toVar();
+				const rows = instanceRows( bvhBuffer, record );
+				const localDir = toObjectDir( rows, worldDirection ).toVar();
+
+				rayOrigin.assign( toObjectPoint( rows, worldOrigin ) );
+				rayDirection.assign( localDir );
+				const localInv = buildInvDir( localDir ).toVar();
+				invDir.assign( localInv );
+				woopParams.assign( computeWoopFromInvDir( { rayDir: localDir, invDir: localInv } ) );
+				instLeaf.assign( record );
+				instExit.assign( stackPtr );
+
+			} ).Else( () => {
+
+				rayOrigin.assign( worldOrigin );
+				rayDirection.assign( worldDirection );
+				invDir.assign( worldInvDir );
+				woopParams.assign( worldWoop );
+				instLeaf.assign( int( - 1 ) );
+
+			} );
+
+			stack.element( stackPtr ).assign( int( word.bitAnd( uint( CLUSTER_ROOT_MASK ) ) ) );
+			stackPtr.addAssign( 1 );
+
+		} );
+
+	};
+
 	const testLeaf = ( first, count ) => {
 
 		const triStart = int( first ).toVar();
@@ -672,7 +831,11 @@ const makeTraverseBVHShadow = ( cameraCulled ) => Fn( ( [
 
 					testLeaf( floatBitsToUint( nodeData0.x ), floatBitsToUint( nodeData0.y ) );
 
-				} ).Else( () => {
+				} ).Else( clustered ? () => {
+
+					pushHitCopies( bvhBuffer, nodeIndex, nodeData0, worldOrigin, worldInvDir, stack, stackPtr, closestHit.dst );
+
+				} : () => {
 
 					// BLAS-pointer leaf — enter the instance if the mesh is visible.
 					If( nodeData0.z.greaterThan( 0.5 ).and( stackPtr.lessThan( int( MAX_STACK_DEPTH ) ) ), () => {
@@ -755,9 +918,22 @@ const makeTraverseBVHShadow = ( cameraCulled ) => Fn( ( [
 
 		};
 
+		// A copy continues the loop: the visit nested in an Else overflowed the JS stack building the island's kernels.
+		const dispatch = clustered ? () => {
+
+			If( entry.greaterThanEqual( int( COPY_ENTRY ) ), () => {
+
+				enterCopy( entry );
+				Continue();
+
+			} );
+			visitNode();
+
+		} : visitNode;
+
 		// Only a folded BVH has negative entries: a leaf folded into its parent, tested with no fetch.
-		if ( folded ) If( entry.lessThan( int( 0 ) ), () => testLeaf( foldedFirst( entry ), foldedCount( entry ) ) ).Else( visitNode );
-		else visitNode();
+		if ( folded ) If( entry.lessThan( int( 0 ) ), () => testLeaf( foldedFirst( entry ), foldedCount( entry ) ) ).Else( dispatch );
+		else dispatch();
 
 	} );
 

package/src/TSL/Common.js

@@ -1,4 +1,4 @@
-import { Fn, wgslFn, float, vec2, vec3, vec4, int, uint, mat3, If, max, dot, clamp, select, bool as tslBool } from 'three/tsl';
+import { Fn, wgslFn, float, vec2, vec3, vec4, uvec2, uvec4, int, uint, mat3, If, max, dot, clamp, select, bool as tslBool } from 'three/tsl';
 
 import {
 	AnisoFrame,
@@ -322,12 +322,41 @@ export const classifyMaterial = Fn( ( [ metalness, roughness, transmission, clea
 
 // Storage buffer access — flat 1D indexing (WebGPU native)
 // No 2D coordinate math needed: directly indexes into the buffer
-export const getDatafromStorageBuffer = Fn( ( [ buffer, stride, sampleIndex, dataOffset ] ) => {
+/**
+ * One storage array split over several buffers, for a tree or triangle store past maxStorageBufferBindingSize: element
+ * e lives in part ⌊e / perPart⌋. A single node needs no split and is returned as it is, so a scene that fits one
+ * buffer compiles exactly the code it always did.
+ * @param {Array} parts - storage nodes, all but the last `perPart` vec4 elements long
+ * @param {number} perPart
+ * @param {'vec4'|'uvec4'} type
+ */
+export function splitStorage( parts, perPart, type ) {
 
-	const elementIndex = stride.mul( dataOffset ).add( sampleIndex );
-	return buffer.element( elementIndex );
+	return parts.length === 1 ? parts[ 0 ] : { isSplitStorage: true, parts, perPart, type, value: parts[ 0 ].value };
 
-} );
+}
+
+/** Element `index` of a storage node or of a {@link splitStorage}. */
+export function storageElement( buffer, index ) {
+
+	if ( ! buffer.isSplitStorage ) return buffer.element( index );
+
+	const { parts, perPart } = buffer;
+	const e = int( index ).toVar();
+	const out = ( { uvec4, uvec2 }[ buffer.type ] ?? vec4 )( 0 ).toVar();
+	const read = ( k ) => () => out.assign( parts[ k ].element( k === 0 ? e : e.sub( int( perPart * k ) ) ) );
+	let branch = If( e.lessThan( int( perPart ) ), read( 0 ) );
+	for ( let k = 1; k < parts.length - 1; k ++ ) branch = branch.ElseIf( e.lessThan( int( perPart * ( k + 1 ) ) ), read( k ) );
+	branch.Else( read( parts.length - 1 ) );
+	return out;
+
+}
+
+const asNode = ( v ) => ( v?.isNode ? v : int( v ) );
+
+// Element `index · stride + offset`.
+export const getDatafromStorageBuffer = ( buffer, index, offset, stride ) =>
+	storageElement( buffer, asNode( stride ).mul( asNode( index ) ).add( asNode( offset ) ) );
 
 /**
  * The five uvec4 rows of a triangle record (TRIANGLE_DATA_LAYOUT) live in two GPU buffers: rows
@@ -337,9 +366,17 @@ export const getDatafromStorageBuffer = Fn( ( [ buffer, stride, sampleIndex, dat
 export const TRI_GEO_ROWS = 3;
 export const TRI_SHADE_ROWS = 2;
 
-export const triangleRow = ( tris, triIndex, row ) => row < TRI_GEO_ROWS
-	? getDatafromStorageBuffer( tris.geo, triIndex, int( row ), int( TRI_GEO_ROWS ) )
-	: getDatafromStorageBuffer( tris.shade, triIndex, int( row - TRI_GEO_ROWS ), int( TRI_SHADE_ROWS ) );
+// Without texture coordinates (no material samples a texture) the shade buffer holds only flags and mesh index, one
+// uvec2 a triangle: rows 3–4 read as zero UVs around them, 24 B a triangle saved.
+export const triangleRow = ( tris, triIndex, row ) => {
+
+	if ( row < TRI_GEO_ROWS ) return getDatafromStorageBuffer( tris.geo, triIndex, int( row ), int( TRI_GEO_ROWS ) );
+	if ( ! tris.withoutUV ) return getDatafromStorageBuffer( tris.shade, triIndex, int( row - TRI_GEO_ROWS ), int( TRI_SHADE_ROWS ) );
+	if ( row === TRI_GEO_ROWS ) return uvec4( 0 );
+	const flagsMesh = storageElement( tris.shade, asNode( triIndex ) );
+	return uvec4( 0, 0, flagsMesh.x, flagsMesh.y );
+
+};
 
 // Unit normal to an octahedral snorm16 pair; GPU twin of packNormalOct in EngineDefaults.
 export const packNormalOct = /*@__PURE__*/ wgslFn( `
@@ -637,11 +674,18 @@ export const shadowFlagsSettle = ( flags, alphaShadows ) => {
 
 };
 
-export const instanceRows = ( bvhBuffer, leafIndex ) => [
-	getDatafromStorageBuffer( bvhBuffer, leafIndex, int( 1 ), int( 4 ) ),
-	getDatafromStorageBuffer( bvhBuffer, leafIndex, int( 2 ), int( 4 ) ),
-	getDatafromStorageBuffer( bvhBuffer, leafIndex, int( 3 ), int( 4 ) )
-];
+export const instanceRows = ( bvhBuffer, leafIndex ) => {
+
+	// Built over copy clusters, an instance is a copy record (3 vec4 from `copyRecordBase`), not a TLAS leaf.
+	const records = bvhBuffer.value?.copyRecordBase;
+	if ( records !== undefined ) return [ 0, 1, 2 ].map( ( row ) => getDatafromStorageBuffer( bvhBuffer, leafIndex, int( records + row ), int( 3 ) ) );
+	return [
+		getDatafromStorageBuffer( bvhBuffer, leafIndex, int( 1 ), int( 4 ) ),
+		getDatafromStorageBuffer( bvhBuffer, leafIndex, int( 2 ), int( 4 ) ),
+		getDatafromStorageBuffer( bvhBuffer, leafIndex, int( 3 ), int( 4 ) )
+	];
+
+};
 
 /** Object-space normal to world: transpose of the world-to-object basis. */
 export const instanceNormalToWorld = ( rows, n ) => vec3(

package/src/TSL/ShadeKernel.js

@@ -1,7 +1,8 @@
 /**
  * ShadeKernel.js — wavefront material eval + bounce generation. 256×1 workgroup, 1D dispatch.
- * 10 storage-buffer bindings: bvh, triGeo, triShade, mat, light, ray, hit (+ RNG state), gBuffer,
- * counters, activeIndices (at the device per-stage limit of 10; envCDF is a texture, not a storage buffer).
+ * 8 storage-buffer bindings: bvh, triGeo, triShade, scene data (materials, then lights), ray, hit (+ RNG state and the
+ * G-buffer), counters, activeIndices; envCDF is a texture. The device allows 10: the other two are for the BVH and
+ * triangle stores' parts past one buffer's limit (PathTracerStage._assertBindings).
  */
 
 import {

package/src/TSL/TextureSampling.js

@@ -363,11 +363,11 @@ export const processMetalnessRoughness = Fn( ( [ material, uvCache ], builder )
 
 } );
 
-// (t[1][1], t[0][1]) — the row of the inverse 2x2 linear part that maps dP/du onto dP/du',
-// up to the determinant, which drops out under the normalize that follows.
-const uvTransformJacobian = /*@__PURE__*/ wgslFn( `
-	fn uvTransformJacobian( t: mat3x3f ) -> vec2f {
-		return vec2f( t[1][1], t[0][1] );
+// The inverse of the transform's 2x2 linear part times |det|: .xy takes (dP/du, dP/dv) to dP/du', .zw to dP/dv'.
+// Times det instead, a mirrored transform turned both round.
+const uvTransformInverse = /*@__PURE__*/ wgslFn( `
+	fn uvTransformInverse( t: mat3x3f ) -> vec4f {
+		return vec4f( t[1][1], - t[0][1], - t[1][0], t[0][0] ) * sign( t[0][0] * t[1][1] - t[1][0] * t[0][1] );
 	}
 ` );
 
@@ -411,13 +411,16 @@ export const triangleUVTangent = Fn( ( [ triangleBuffer, triIndex, geometryNorma
 		const T = e1.mul( d2.y ).sub( e2.mul( d1.y ) ).mul( r ).toVar();
 		const B = e2.mul( d1.x ).sub( e1.mul( d2.x ) ).mul( r ).toVar();
 
-		// Re-express in the map's transformed UV space (inverse of the 2x2 linear part).
-		const uvJ = uvTransformJacobian( { t: transform } );
-		const Tt = T.mul( uvJ.x ).sub( B.mul( uvJ.y ) ).toVar();
+		// Re-express both in the map's transformed UV space: the handedness test below needs B there too, or a
+		// mirrored map, or one turned past 90°, gets its bitangent reversed.
+		const inv = uvTransformInverse( { t: transform } ).toVar();
+		const Tt = T.mul( inv.x ).add( B.mul( inv.y ) ).toVar();
+		const Bt = T.mul( inv.z ).add( B.mul( inv.w ) ).toVar();
 
 		If( length( Tt ).greaterThan( 1e-12 ), () => {
 
 			T.assign( Tt );
+			B.assign( Bt );
 
 		} );