rayzee 9.4.2 → 9.5.0

package/src/Processor/PBRT/PBRTTextureBake.js

@@ -0,0 +1,154 @@
+/**
+ * pbrt textures the engine has no node for, baked on the CPU into an image it samples: the `mix` texture,
+ * an image texture's `scale` above 1 or `invert`, and a `mix` material whose amount is a texture.
+ *
+ * A layer is an image as pbrt evaluates it: linear values, top row first, `channels` 1 (a float texture reads
+ * the red channel) or 3, already scaled and inverted, and the uv mapping pbrt applies before the lookup
+ * (st = scale · uv + delta, image row from the top = 1 − t).
+ */
+
+const MAX_BAKE_SIZE = 4096;
+
+export const srgbToLinear = ( v ) => ( v <= 0.04045 ? v / 12.92 : ( ( v + 0.055 ) / 1.055 ) ** 2.4 );
+export const linearToSRGB = ( v ) => ( v <= 0.0031308 ? v * 12.92 : 1.055 * v ** ( 1 / 2.4 ) - 0.055 );
+
+/**
+ * @param {{ data: ArrayLike<number>, width: number, height: number, channels?: number, topDown?: boolean }} pixels -
+ *   8-bit (0–255) or float values, `channels` per texel (4 if unsaid)
+ * @param {object} options
+ * @param {number} options.channels - 1 for a float texture, 3 for a spectrum one
+ * @param {(v: number) => number} [options.decode] - 8-bit value / 255 → linear; omitted for float data
+ * @param {number} [options.scale=1]
+ * @param {boolean} [options.invert=false]
+ * @param {{ su: number, sv: number, du: number, dv: number }} [options.mapping]
+ */
+export function makeLayer( pixels, { channels, decode = null, scale = 1, invert = false, mapping = null } ) {
+
+	const { width, height } = pixels;
+	const stride = pixels.channels ?? 4;
+	const data = new Float32Array( width * height * channels );
+	const topDown = pixels.topDown !== false;
+
+	for ( let y = 0; y < height; y ++ ) {
+
+		const row = topDown ? y : height - 1 - y;
+		for ( let x = 0; x < width; x ++ ) {
+
+			const src = ( row * width + x ) * stride, dst = ( y * width + x ) * channels;
+			for ( let c = 0; c < channels; c ++ ) {
+
+				const raw = pixels.data[ src + Math.min( c, stride - 1 ) ];
+				const v = scale * ( decode ? decode( raw / 255 ) : raw );
+				data[ dst + c ] = invert ? Math.max( 0, 1 - v ) : v;
+
+			}
+
+		}
+
+	}
+
+	return { width, height, channels, data, su: 1, sv: 1, du: 0, dv: 0, ...mapping };
+
+}
+
+/** The layer's mean value (a float layer's only channel; a spectrum layer's average of three). */
+export function layerMean( layer ) {
+
+	let sum = 0;
+	for ( let i = 0; i < layer.data.length; i ++ ) sum += layer.data[ i ];
+	return layer.data.length ? sum / layer.data.length : 0;
+
+}
+
+// Bilinear, repeating, at pbrt's (s, t).
+function sample( layer, s, t, out ) {
+
+	const { width: w, height: h, channels: n, data } = layer;
+	const x = s * w - 0.5, y = ( 1 - t ) * h - 0.5;
+	const x0 = Math.floor( x ), y0 = Math.floor( y );
+	const fx = x - x0, fy = y - y0;
+	const wrap = ( i, size ) => ( ( i % size ) + size ) % size;
+	const xa = wrap( x0, w ), xb = wrap( x0 + 1, w ), ya = wrap( y0, h ), yb = wrap( y0 + 1, h );
+
+	for ( let c = 0; c < 3; c ++ ) {
+
+		const k = Math.min( c, n - 1 );
+		const top = data[ ( ya * w + xa ) * n + k ] * ( 1 - fx ) + data[ ( ya * w + xb ) * n + k ] * fx;
+		const bottom = data[ ( yb * w + xa ) * n + k ] * ( 1 - fx ) + data[ ( yb * w + xb ) * n + k ] * fx;
+		out[ c ] = top * ( 1 - fy ) + bottom * fy;
+
+	}
+
+	return out;
+
+}
+
+/**
+ * Each term is `{ rgb }` (a constant) or `{ layer, tint? }` (an image, times `tint`); `clamp` clamps it to [0, 1]
+ * first, as pbrt clamps a colour texture read as an albedo, before anything mixes it. Evaluates
+ * `combine( values )` over the texel grid of the largest image among the terms, in that image's uv mapping;
+ * a term with another mapping is sampled through it. The result is sRGB bytes laid out for a DataTexture
+ * (bottom row first), clamped to [0, 1] as pbrt clamps an albedo. Null when every term is a constant.
+ * @param {Array<{ rgb?: number[], layer?: object, tint?: number[] }>} terms
+ * @param {(values: number[][]) => number[]} combine - linear RGB from each term's linear RGB
+ * @returns {{ data: Uint8Array, width: number, height: number, mapping: { su: number, sv: number, du: number, dv: number } } | null}
+ */
+export function bake( terms, combine ) {
+
+	let driver = null;
+	for ( const term of terms ) if ( term.layer && ( ! driver || term.layer.width * term.layer.height > driver.width * driver.height ) ) driver = term.layer;
+	if ( ! driver ) return null;
+
+	const width = Math.min( driver.width, MAX_BAKE_SIZE ), height = Math.min( driver.height, MAX_BAKE_SIZE );
+	const out = new Uint8Array( width * height * 4 );
+	const values = terms.map( () => [ 0, 0, 0 ] );
+
+	for ( let j = 0; j < height; j ++ ) {
+
+		const t = ( j + 0.5 ) / height;
+		const v = ( t - driver.dv ) / driver.sv;
+
+		for ( let i = 0; i < width; i ++ ) {
+
+			const s = ( i + 0.5 ) / width;
+			const u = ( s - driver.du ) / driver.su;
+
+			for ( let k = 0; k < terms.length; k ++ ) {
+
+				const term = terms[ k ], value = values[ k ];
+				if ( term.layer ) {
+
+					const L = term.layer;
+					sample( L, L === driver ? s : L.su * u + L.du, L === driver ? t : L.sv * v + L.dv, value );
+					if ( term.tint ) for ( let c = 0; c < 3; c ++ ) value[ c ] *= term.tint[ c ];
+
+				} else {
+
+					value[ 0 ] = term.rgb[ 0 ]; value[ 1 ] = term.rgb[ 1 ]; value[ 2 ] = term.rgb[ 2 ];
+
+				}
+
+				if ( term.clamp ) for ( let c = 0; c < 3; c ++ ) value[ c ] = Math.min( 1, Math.max( 0, value[ c ] ) );
+
+			}
+
+			const rgb = combine( values );
+			const o = ( j * width + i ) * 4;
+			for ( let c = 0; c < 3; c ++ ) out[ o + c ] = Math.round( 255 * linearToSRGB( Math.min( 1, Math.max( 0, rgb[ c ] ) ) ) );
+			out[ o + 3 ] = 255;
+
+		}
+
+	}
+
+	return { data: out, width, height, mapping: { su: driver.su, sv: driver.sv, du: driver.du, dv: driver.dv } };
+
+}
+
+/** pbrt's mix: ( 1 − amount ) · a + amount · b, amount read from its first channel. */
+export const mixOf = ( [ a, b, amount ] ) => {
+
+	const t = amount[ 0 ];
+	return [ a[ 0 ] + ( b[ 0 ] - a[ 0 ] ) * t, a[ 1 ] + ( b[ 1 ] - a[ 1 ] ) * t, a[ 2 ] + ( b[ 2 ] - a[ 2 ] ) * t ];
+
+};

package/src/Processor/PBRT/PFM.js

@@ -0,0 +1,59 @@
+import { DataTexture, FloatType, LinearFilter, RGBAFormat } from 'three';
+
+/**
+ * Portable float map: "PF" (RGB) or "Pf" (grey), width and height, then a scale whose sign is the byte
+ * order, then rows bottom first — the order three's EXR and HDR loaders fill a DataTexture in.
+ * A scale other than ±1 multiplies the pixels, as pbrt reads it.
+ * @param {Uint8Array} bytes
+ * @returns {{ data: Float32Array, width: number, height: number }} RGBA, row 0 the bottom
+ */
+export function decodePFM( bytes ) {
+
+	let pos = 0;
+	const token = () => {
+
+		while ( pos < bytes.length && bytes[ pos ] <= 32 ) pos ++;
+		const start = pos;
+		while ( pos < bytes.length && bytes[ pos ] > 32 ) pos ++;
+		return String.fromCharCode( ...bytes.subarray( start, pos ) );
+
+	};
+
+	const magic = token();
+	if ( magic !== 'PF' && magic !== 'Pf' ) throw new Error( 'not a PFM image' );
+	const width = parseInt( token(), 10 );
+	const height = parseInt( token(), 10 );
+	const scale = parseFloat( token() );
+	pos ++;
+
+	const channels = magic === 'PF' ? 3 : 1;
+	const count = width * height;
+	if ( ! ( width > 0 && height > 0 ) || ! Number.isFinite( scale ) || scale === 0 ) throw new Error( 'bad PFM header' );
+	if ( bytes.length - pos < count * channels * 4 ) throw new Error( 'PFM image is truncated' );
+
+	const view = new DataView( bytes.buffer, bytes.byteOffset + pos, count * channels * 4 );
+	const little = scale < 0;
+	const gain = Math.abs( scale );
+	const data = new Float32Array( count * 4 );
+	for ( let i = 0; i < count; i ++ ) {
+
+		for ( let c = 0; c < 3; c ++ ) data[ i * 4 + c ] = view.getFloat32( ( i * channels + ( channels === 3 ? c : 0 ) ) * 4, little ) * gain;
+		data[ i * 4 + 3 ] = 1;
+
+	}
+
+	return { data, width, height };
+
+}
+
+/** @param {Uint8Array} bytes */
+export function pfmTexture( bytes ) {
+
+	const { data, width, height } = decodePFM( bytes );
+	const texture = new DataTexture( data, width, height, RGBAFormat, FloatType );
+	texture.minFilter = LinearFilter;
+	texture.magFilter = LinearFilter;
+	texture.needsUpdate = true;
+	return texture;
+
+}

package/src/Processor/PackedRayBuffer.js

@@ -44,11 +44,19 @@ export const HIT = {
 	NORMAL_MAT: 1, // uvec4(octNormal, matIndex, instanceLeaf + 1, 0)
 	// The path's RNG state, here rather than in a buffer of its own: Shade was at the device's
 	// 10 storage buffers, and the second triangle buffer needed the slot. Extend never writes it.
-	RNG: 2, // uvec4(rngState, 0, 0, 0)
+	// Bidirectional mode keeps the path's MIS partial sums in .y/.z.
+	RNG: 2, // uvec4(rngState, bits(dVCM), bits(dVC), 0)
+	// Bidirectional only: a camera vertex awaiting its connection, or a light path's emission.
+	VERTEX: 3, // 4 slots, a vertex record (see writeVertexRecord)
 };
 
+// Bidirectional: the light vertex cache follows the path regions — Shade has no binding left.
+export const HIT_STRIDE_BIDIRECTIONAL = HIT_STRIDE + 4;
+export const LIGHT_VERTEX_STRIDE = 4;
+
 // SoA region stride, baked into the shader graph at build time; single instance, rebuilt on resize.
 let _cap = 0;
+let _lightVertexBase = 0;
 
 const soa = ( id, slot ) => ( slot === 0 ? id : id.add( slot * _cap ) );
 
@@ -68,9 +76,10 @@ export class PackedRayBuffer {
 	// image resolution and fixed for the device — the image is streamed through the pool in row bands
 	// (see docs/internal/specs/wavefront-chunked-pool.md), so the SoA stride _cap never changes with
 	// resolution and the wavefront kernels are built once (no resize-triggered WGSL regen).
-	constructor( capacity = 0, renderer = null ) {
+	constructor( capacity = 0, renderer = null, lightVertices = 0 ) {
 
 		this.capacity = 0;
+		this.lightVertices = 0;
 		this._renderer = renderer;
 		this._attrs = {};
 
@@ -78,16 +87,23 @@ export class PackedRayBuffer {
 		this.rayBuffer = null;
 		this.hitBuffer = null;
 
-		if ( capacity > 0 ) this.allocate( capacity );
+		if ( capacity > 0 ) this.allocate( capacity, lightVertices );
 
 	}
 
-	allocate( capacity ) {
+	/**
+	 * @param {number} capacity - paths in flight
+	 * @param {number} [lightVertices] - light vertex cache slots; non-zero selects the bidirectional layout
+	 */
+	allocate( capacity, lightVertices = 0 ) {
 
 		this.dispose();
 
 		this.capacity = capacity;
+		this.lightVertices = lightVertices;
 		_cap = capacity;
+		const hitSlots = lightVertices > 0 ? HIT_STRIDE_BIDIRECTIONAL : HIT_STRIDE;
+		_lightVertexBase = capacity * hitSlots;
 
 		// count=0 so StorageBufferNode.getHash() shares the buffer → RW and RO nodes bind the same GPU data.
 		const rayCount = capacity * RAY_STRIDE;
@@ -98,7 +114,7 @@ export class PackedRayBuffer {
 			ro: storage( rayAttr, 'vec4' ).toReadOnly(),
 		};
 
-		const hitCount = capacity * HIT_STRIDE;
+		const hitCount = capacity * hitSlots + lightVertices * LIGHT_VERTEX_STRIDE;
 		const hitAttr = gpuOnlyStorageAttribute( hitCount, 4, Uint32Array );
 		this._attrs.hit = hitAttr;
 		this.hitBuffer = {
@@ -115,11 +131,11 @@ export class PackedRayBuffer {
 
 	}
 
-	// Reallocates only if a larger budget capacity is requested; returns true if it did.
-	resize( capacity ) {
+	// Reallocates if a larger budget or a different light vertex cache is requested; returns true if it did.
+	resize( capacity, lightVertices = 0 ) {
 
-		if ( capacity <= this.capacity && this.capacity > 0 ) return false;
-		this.allocate( capacity );
+		if ( capacity <= this.capacity && this.capacity > 0 && lightVertices === this.lightVertices ) return false;
+		this.allocate( capacity, lightVertices );
 		return true;
 
 	}
@@ -132,6 +148,7 @@ export class PackedRayBuffer {
 		this.rayBuffer = null;
 		this.hitBuffer = null;
 		this.capacity = 0;
+		this.lightVertices = 0;
 
 	}
 
@@ -282,6 +299,96 @@ export const readRngState = ( buf, id ) => buf.element( soa( id, HIT.RNG ) ).x;
 
 export const writeRngState = ( buf, id, state ) => buf.element( soa( id, HIT.RNG ) ).assign( uvec4( state, 0, 0, 0 ) );
 
+/** The subpath's MIS partial sums (Georgiev 2012, "Implementing Vertex Connection and Merging"). */
+export const readMisState = ( buf, id ) => {
+
+	const v = buf.element( soa( id, HIT.RNG ) );
+	return { dVCM: uintBitsToFloat( v.y ), dVC: uintBitsToFloat( v.z ) };
+
+};
+
+export const writeRngMis = ( buf, id, state, dVCM, dVC ) =>
+	buf.element( soa( id, HIT.RNG ) ).assign( uvec4( state, floatBitsToUint( dVCM ), floatBitsToUint( dVC ), uint( 0 ) ) );
+
+// A vertex record is four uvec4s:
+//   0  bits(position.xyz), tag
+//   1  bits(throughput.xyz), oct(V) — V points back along the subpath it was reached by
+//   2  oct(N), oct(facet normal), material index | extra << 24, bits(uv.x) — both normals on V's side
+//   3  bits(uv.y), bits(dVCM), bits(dVC), next — the merge grid's list (MergeKernel), in the cache only
+// `at( k )` addresses quad k, in a path's VERTEX slots or in the cache.
+export const pendingVertex = ( id ) => ( k ) => soa( id, HIT.VERTEX + k );
+export const cachedVertex = ( slot ) => ( k ) => uint( slot ).mul( LIGHT_VERTEX_STRIDE ).add( _lightVertexBase + k );
+
+export const writeVertexRecord = ( buf, at, v ) => {
+
+	buf.element( at( 0 ) ).assign( uvec4( floatBitsToUint( v.position ), v.tag ) );
+	buf.element( at( 1 ) ).assign( uvec4( floatBitsToUint( v.throughput ), packNormalOct( v.V ) ) );
+	buf.element( at( 2 ) ).assign( uvec4( packNormalOct( v.N ), packNormalOct( v.facetN ),
+		uint( v.materialIndex ).bitOr( uint( v.extra ).bitAnd( uint( 0xFF ) ).shiftLeft( uint( 24 ) ) ), floatBitsToUint( v.uv.x ) ) );
+	buf.element( at( 3 ) ).assign( uvec4( floatBitsToUint( v.uv.y ), floatBitsToUint( v.dVCM ), floatBitsToUint( v.dVC ), uint( 0 ) ) );
+
+};
+
+export const readVertexTag = ( buf, at ) => buf.element( at( 0 ) ).w;
+export const readVertexPosition = ( buf, at ) => uintBitsToFloat( buf.element( at( 0 ) ).xyz );
+export const readVertexNext = ( buf, at ) => buf.element( at( 3 ) ).w;
+export const writeVertexNext = ( buf, at, next ) => buf.element( at( 3 ) ).w.assign( next );
+
+export const readVertexRecord = ( buf, at ) => {
+
+	const q0 = buf.element( at( 0 ) ).toVar();
+	const q1 = buf.element( at( 1 ) ).toVar();
+	const q2 = buf.element( at( 2 ) ).toVar();
+	const q3 = buf.element( at( 3 ) ).toVar();
+	return {
+		position: uintBitsToFloat( q0.xyz ),
+		tag: q0.w,
+		throughput: uintBitsToFloat( q1.xyz ),
+		V: unpackTriangleNormal( q1.w ),
+		N: unpackTriangleNormal( q2.x ),
+		facetN: unpackTriangleNormal( q2.y ),
+		materialIndex: q2.z.bitAnd( uint( 0xFFFFFF ) ),
+		uv: vec2( uintBitsToFloat( q2.w ), uintBitsToFloat( q3.x ) ),
+		dVCM: uintBitsToFloat( q3.y ),
+		dVC: uintBitsToFloat( q3.z ),
+		extra: q2.z.shiftRight( uint( 24 ) ),
+	};
+
+};
+
+// A light path's vertex count, in its first slot's tag lane, stamped with the frame's tag.
+export const readLightPathLength = ( buf, at, frameTag ) => {
+
+	const word = buf.element( at( 0 ) ).w;
+	return select( word.shiftRight( uint( 8 ) ).equal( frameTag ), word.bitAnd( uint( 0xFF ) ), uint( 0 ) );
+
+};
+
+export const writeLightPathLength = ( buf, at, frameTag, length ) => {
+
+	const keep = buf.element( at( 0 ) ).xyz.toVar();
+	buf.element( at( 0 ) ).assign( uvec4( keep, frameTag.shiftLeft( uint( 8 ) ).bitOr( uint( length ) ) ) );
+
+};
+
+/** A light path's point of emission, held in its VERTEX slot until the first hit settles its MIS. */
+export const writeLightOrigin = ( buf, id, triangle, instanceLeaf, cosLight, scale ) =>
+	buf.element( soa( id, HIT.VERTEX ) ).assign( uvec4(
+		uint( triangle ), uint( int( instanceLeaf ).add( int( 1 ) ) ), floatBitsToUint( cosLight ), floatBitsToUint( scale ),
+	) );
+
+export const readLightOrigin = ( buf, id ) => {
+
+	const v = buf.element( soa( id, HIT.VERTEX ) ).toVar();
+	return {
+		triangle: int( v.x ),
+		instanceLeaf: int( v.y ).sub( int( 1 ) ),
+		cosLight: uintBitsToFloat( v.z ),
+		scale: uintBitsToFloat( v.w ),
+	};
+
+};
+
 export const writeHitPacked = ( buf, id, distance, triIndex, baryU, baryV, normal, matIndex, instanceLeaf, facet = uint( 0 ) ) => {
 
 	buf.element( soa( id, HIT.DIST_TRI_BARY ) )

package/src/Processor/ParallelBVHBuilder.js

@@ -31,7 +31,7 @@ const MAX_PARALLEL_WORKERS = 8;
  * @param {Uint32Array} triangles - Triangle records (20 lanes each)
  * @param {number} depth - Maximum BVH depth
  * @param {Function|null} progressCallback - Optional progress callback (0-100)
- * @param {Object} config - Builder config (maxLeafSize, numBins, treelet settings, etc.)
+ * @param {Object} config - Builder config (maxLeafSize, numBins, reinsertion settings, etc.)
  * @returns {Promise<{bvhData: Float32Array, bvhRoot: true, order?: Uint32Array, triangles?: Uint32Array, reorderedTriangles?: Uint32Array, splitStats: Object}>}
  *   the parallel build returns the input `triangles` and the BVH `order` of them (record i of the
  *   result is record order[i] of the input); its single-worker fallback returns `reorderedTriangles`.
@@ -192,7 +192,6 @@ export function buildBVHParallel( triangles, depth, progressCallback, config ) {
 				depth,
 				parallelDepth,
 				reportProgress: !! progressCallback,
-				treeletOptimization: config.treeletOptimization
 			} );
 
 		} )().catch( ( error ) => {
@@ -413,7 +412,6 @@ async function handlePhase2(
 			numBins: config.numBins,
 			maxBins: config.maxBins,
 			minBins: config.minBins,
-			treeletConfig: config.treeletOptimization,
 			reinsertionConfig: config.reinsertionOptimization,
 			reportProgress: !! progressCallback
 		} );
@@ -442,7 +440,7 @@ function buildSingleWorker( triangles, depth, progressCallback, config ) {
 
 			worker.onmessage = ( e ) => {
 
-				const { bvhData, triangles: transferredTriangles, originalToBvh, error, progress, treeletStats } = e.data;
+				const { bvhData, triangles: transferredTriangles, originalToBvh, error, progress, splitStats } = e.data;
 
 				if ( error ) {
 
@@ -464,7 +462,7 @@ function buildSingleWorker( triangles, depth, progressCallback, config ) {
 					? new Uint32Array( sharedReorderBuffer )
 					: transferredTriangles;
 
-				resolve( { bvhData, bvhRoot: true, reorderedTriangles, originalToBvh: originalToBvh || null, splitStats: treeletStats || {} } );
+				resolve( { bvhData, bvhRoot: true, reorderedTriangles, originalToBvh: originalToBvh || null, splitStats: splitStats || {} } );
 
 			};
 
@@ -484,7 +482,6 @@ function buildSingleWorker( triangles, depth, progressCallback, config ) {
 				depth,
 				reportProgress: !! progressCallback,
 				sharedReorderBuffer,
-				treeletOptimization: config.treeletOptimization,
 				reinsertionOptimization: config.reinsertionOptimization,
 				foldLeaves: config.foldLeaves
 			}, [ transferBuffer ] );

package/src/Processor/PhysicalSky.js

@@ -1,5 +1,5 @@
 import {
-	RGBAFormat, RedFormat, FloatType, LinearFilter, RepeatWrapping, ClampToEdgeWrapping,
+	RGBAFormat, FloatType, LinearFilter, RepeatWrapping, ClampToEdgeWrapping,
 	EquirectangularReflectionMapping, LinearSRGBColorSpace, DataTexture, Vector3, Vector4,
 } from 'three';
 import { StorageInstancedBufferAttribute } from 'three/webgpu';
@@ -50,7 +50,8 @@ export class PhysicalSky {
 		this._texture.wrapS = RepeatWrapping;
 		this._texture.wrapT = ClampToEdgeWrapping;
 		this._texture.generateMipmaps = false;
-		this._cdfTexture = gpuTexture( width + 1, height, RedFormat );
+		// packExactTable's layout (EnvironmentExactTable.js): running sums and guides, RGBA.
+		this._cdfTexture = gpuTexture( width + 1, height, RGBAFormat );
 		this._rec709Weights = spectrumToRec709( SKY_RADIANCE_SCALE );
 
 		this._attrs = null;
@@ -209,7 +210,7 @@ export class PhysicalSky {
 	 * @param {number} p.altitude - metres
 	 * @param {number} p.sunAngularDiameter - radians
 	 * @param {number} [p.sunStrength=1]
-	 * @returns {{ texture: DataTexture, cdfTexture: DataTexture, sun: Object, stats: Promise<{ totalSum: number, compensationDelta: number }> }}
+	 * @returns {{ texture: DataTexture, cdfTexture: DataTexture, sun: Object, stats: Promise<{ totalSum: number, radianceIntegral: number }> }}
 	 */
 	bake( renderer, p ) {
 
@@ -258,7 +259,7 @@ export class PhysicalSky {
 		const stats = renderer.getArrayBufferAsync( this._attrs.cdfStats ).then( buffer => {
 
 			const s = new Float32Array( buffer );
-			return { totalSum: s[ 4 ], compensationDelta: s[ 5 ] };
+			return { totalSum: s[ 4 ], radianceIntegral: 2 * Math.PI * Math.PI * s[ 0 ] / ( this.width * this.height ) };
 
 		} );
 

package/src/Processor/PlatformImageLoader.js

@@ -59,6 +59,32 @@ async function fetchBytes( url ) {
 
 }
 
+function imageBytes( parser, def ) {
+
+	return def.bufferView !== undefined
+		? parser.getDependency( 'bufferView', def.bufferView ).then( ( buffer ) => new Uint8Array( buffer ) )
+		: fetchBytes( parser.options.manager.resolveURL( LoaderUtils.resolveURL( def.uri, parser.options.path ) ) );
+
+}
+
+// GLTFLoader hands an image its extension decodes (KHR_texture_basisu → KTX2Loader) a loader of its own; three's way to
+// it is an object URL through `self.URL`, so here the loader parses the bytes.
+const ownsLoader = ( parser, loader ) => !! loader && loader !== parser.textureLoader && typeof loader.parse === 'function';
+
+function loadWithOwnLoader( parser, sourceIndex, loader ) {
+
+	if ( parser.sourceCache[ sourceIndex ] !== undefined ) return parser.sourceCache[ sourceIndex ].then( ( texture ) => texture.clone() );
+
+	const promise = imageBytes( parser, parser.json.images[ sourceIndex ] ).then( ( bytes ) => new Promise( ( resolve, reject ) => {
+
+		loader.parse( bytes.buffer.slice( bytes.byteOffset, bytes.byteOffset + bytes.byteLength ), resolve, reject );
+
+	} ) );
+	parser.sourceCache[ sourceIndex ] = promise;
+	return promise;
+
+}
+
 /**
  * An image file as a texture, decoded by the platform: the counterpart of TextureLoader for hosts
  * with no DOM. Rows stay top first with `flipY` on, exactly as TextureLoader leaves an image.
@@ -71,6 +97,27 @@ export async function loadPlatformImage( url, mimeType = mimeTypeOf( { uri: url
 
 }
 
+/**
+ * A GLTFLoader plugin for a runtime with no way to decode an image (Node without `decodeImage`): each image fails with
+ * what to configure, where three.js's own path threw `self is not defined` and took the whole load down.
+ */
+export function missingImageDecoderPlugin( parser, onFailure = null ) {
+
+	parser.loadImageSource = function ( sourceIndex, loader ) {
+
+		if ( ownsLoader( this, loader ) ) return loadWithOwnLoader( this, sourceIndex, loader );
+
+		const def = this.json.images[ sourceIndex ];
+		const error = new Error( 'no image decoder in this runtime: configurePlatform( nodePlatform( { decodeImage } ) ) — see "Running in Node"' );
+		onFailure?.( def.uri ?? `bufferView ${def.bufferView}`, error );
+		return Promise.reject( error );
+
+	};
+
+	return { name: 'RAYZEE_missing_image_decoder' };
+
+}
+
 /**
  * A GLTFLoader plugin for hosts with the platform's `decodeImage`: every image of the model, embedded
  * or not, is decoded by the host and becomes a DataTexture of its pixels, which the texture packer
@@ -82,19 +129,16 @@ export async function loadPlatformImage( url, mimeType = mimeTypeOf( { uri: url
  */
 export function platformImagesPlugin( parser, onFailure = null ) {
 
-	parser.loadImageSource = function ( sourceIndex ) {
+	parser.loadImageSource = function ( sourceIndex, loader ) {
 
+		if ( ownsLoader( this, loader ) ) return loadWithOwnLoader( this, sourceIndex, loader );
 		if ( this.sourceCache[ sourceIndex ] !== undefined ) return this.sourceCache[ sourceIndex ].then( ( texture ) => texture.clone() );
 
 		const def = this.json.images[ sourceIndex ];
 		const mimeType = mimeTypeOf( def );
 		const where = def.uri ?? `bufferView ${def.bufferView}`;
 
-		const bytes = def.bufferView !== undefined
-			? this.getDependency( 'bufferView', def.bufferView ).then( ( buffer ) => new Uint8Array( buffer ) )
-			: fetchBytes( this.options.manager.resolveURL( LoaderUtils.resolveURL( def.uri, this.options.path ) ) );
-
-		const promise = bytes.then( ( data ) => decodeBytes( data, mimeType ) ).then( ( pixels ) => {
+		const promise = imageBytes( this, def ).then( ( data ) => decodeBytes( data, mimeType ) ).then( ( pixels ) => {
 
 			const texture = pixelTexture( pixels, { shared: true } );
 			if ( def.extras && typeof def.extras === 'object' ) Object.assign( texture.userData, def.extras );

package/src/Processor/QueueManager.js

@@ -31,9 +31,14 @@ export const COUNTER = {
 	// Survivors' summed throughput (max channel, fixed-point ENERGY_SCALE). The early exit gates on this,
 	// not the count: past Russian roulette a few survivors carry the weight of many.
 	ACTIVE_ENERGY: 7,
+	// Words read back; the light guide's escape counts (TSL/LightGuide.js) follow, never read back.
 	COUNT: 8,
+	GUIDE: 8,
 };
 
+/** The light guide's counts: 16 direction bins × 64 × 64 disc cells (TSL/LightGuide.js). */
+export const GUIDE_COUNTER_WORDS = 16 * 64 * 64;
+
 export const ENERGY_SCALE = 64;
 export const ENERGY_RAY_CLAMP = 65535;
 
@@ -52,6 +57,9 @@ export const RAY_FLAG = {
 	REDIRECTED: 1 << 18, // bit 18: ray has been redirected (refraction/reflection/SSS/opaque scatter) since the camera, so env it reaches is transported light (sharp), NOT the direct backdrop. NOT set by pure alpha/transparent passthrough (direction unchanged) → env through cutout holes is still the backdrop (blur/intensity/show/color/ground-projection). Set via bitOr only (positive mask) so it never disturbs ACTIVE/bounce bits.
 	SUN_NEE: 1 << 19, // bit 19: the last opaque scatter's sun NEE could have drawn this direction (MIS partner for a sun hit on miss)
 	UNDER_SURFACE: 1 << 20, // bit 20: the last opaque scatter left below its own facet (shading normal allowed it), so the ray culls back faces to leave that shell
+	LIGHT_PATH: 1 << 21, // bit 21: bidirectional light subpath (traced from an emitter, gathers nothing)
+	LIGHT_EMITTED: 1 << 22, // bit 22: light subpath not yet past its first interaction (its MIS start is still open)
+	EMISSION_ONLY: 1 << 23, // bit 23: camera ray past its last bounce, traced only for the light it hits
 };
 
 export class QueueManager {
@@ -87,13 +95,14 @@ export class QueueManager {
 		this.capacity = capacity;
 
 		// explicit attribute (not attributeArray) so it can be referenced for async readback
-		this._countersAttr = new StorageInstancedBufferAttribute( new Uint32Array( COUNTER.COUNT ), 1 );
+		this._countersAttr = new StorageInstancedBufferAttribute( new Uint32Array( COUNTER.GUIDE + GUIDE_COUNTER_WORDS ), 1 );
 		this.counters = storage( this._countersAttr, 'uint' ).toAtomic();
 
-		// per-bounce snapshots for the async readback: [0, MAX) ACTIVE_RAY_COUNT, [MAX, 2·MAX) ACTIVE_ENERGY
+		// per-bounce snapshots for the async readback: [0, MAX) ACTIVE_RAY_COUNT, [MAX, 2·MAX) ACTIVE_ENERGY,
+		// then the same pair for the bidirectional light pass
 		this.MAX_BOUNCE_SNAPSHOTS = 32;
 		this._bounceCountsAttr = new StorageInstancedBufferAttribute(
-			new Uint32Array( 2 * this.MAX_BOUNCE_SNAPSHOTS ), 1,
+			new Uint32Array( 4 * this.MAX_BOUNCE_SNAPSHOTS ), 1,
 		);
 		this.bounceCounts = storage( this._bounceCountsAttr, 'uint' );
 

package/src/Processor/ReinsertionOptimizer.js

@@ -11,7 +11,7 @@
  *   3. Sort reinsertions by area improvement, apply non-conflicting ones greedily.
  *   4. Repeat for a configurable number of iterations.
  *
- * Typically yields 10-20% SAH cost reduction on top of treelet optimization.
+ * On this binned-SAH build it buys ~0.04 % tree SAH (3.5M triangles, 2026-08) for ~430 ms of worker time.
  */
 export class ReinsertionOptimizer {
 
@@ -52,7 +52,7 @@ export class ReinsertionOptimizer {
 
 	}
 
-	// --- Surface area (half SA, consistent with TreeletOptimizer) ---
+	// --- Surface area (half SA) ---
 
 	surfaceArea( node ) {