rayzee 7.28.1 → 7.29.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "rayzee",
-  "version": "7.28.1",
+  "version": "7.29.0",
   "type": "module",
   "description": "Real-time WebGPU path tracing engine built on Three.js",
   "main": "dist/rayzee.umd.js",

package/src/PathTracerApp.js

@@ -728,6 +728,9 @@ export class PathTracerApp extends EventDispatcher {
 	 * by reference, and any ancestor transform is baked in. Later edits to `object3d` do not
 	 * reach the render — mutate {@link sceneModel}, then {@link refitBVH}/{@link refitBLASes}.
 	 *
+	 * Lights keep three.js units — `RectAreaLight.intensity` in nits, point/spot in candela — and are
+	 * converted to radiant power on the copy. `areaLightIntensityScale` does not apply here.
+	 *
 	 * @param {import('three').Object3D} object3d - The Object3D to render; left untouched.
 	 * @param {string} [name='object3d'] - Display name for the object
 	 */

package/src/Processor/AssetLoader.js

@@ -51,6 +51,19 @@ function standInForSplit( source ) {
 
 }
 
+// three.js nits → the engine's radiant power, inverting areaLightRadiance.
+function areaLightPowerFactor( node, width, height, userData ) {
+
+	if ( ! ( userData.normalize ?? true ) ) return Math.PI;
+
+	const shapeFactor = userData.shape === 'ellipse' || userData.shape === 'disk' ? Math.PI / 4 : 1;
+	const scale = node.getWorldScale( new Vector3() );
+	// abs: a mirrored ancestor decomposes negative; the serializer takes the area as |u × v|.
+	const factor = Math.PI * shapeFactor * Math.abs( width * scale.x * height * scale.y );
+	return Number.isFinite( factor ) ? factor : Math.PI;
+
+}
+
 /**
  * AssetLoader class - handles loading of 3D models, environment maps, and archives
  */
@@ -1726,7 +1739,6 @@ export class AssetLoader extends EventDispatcher {
 
 	processModelObjects( model ) {
 
-		let visitedAreaLights = [];
 		// Split after the walk: traverse() caches children.length, so splitting in place
 		// shifts later siblings down a slot and skips one.
 		const multiMaterialMeshes = [];
@@ -1734,9 +1746,11 @@ export class AssetLoader extends EventDispatcher {
 
 			const userData = object.userData;
 
-			if ( object.isRectAreaLight && ! visitedAreaLights.includes( object.uuid ) ) {
+			// An adopted light carries three.js units; convert as point/spot are below.
+			if ( object.isRectAreaLight && ! userData.__radianceConverted ) {
 
-				visitedAreaLights.push( object.uuid );
+				object.intensity *= areaLightPowerFactor( object, object.width, object.height, userData );
+				userData.__radianceConverted = true;
 
 			}
 
@@ -1759,14 +1773,9 @@ export class AssetLoader extends EventDispatcher {
 
 				if ( userData.type === 'RectAreaLight' ) {
 
-					// Authored intensity is three.js radiance (these files also carry power = intensity·w·h·π);
-					// convert to the engine's radiant power through the world area so Normalize reproduces it.
-					const worldScale = object.getWorldScale( new Vector3() );
 					const normalize = userData.normalize ?? true;
 					const shape = userData.shape ?? 'rectangle';
-					const shapeFactor = shape === 'ellipse' || shape === 'disk' ? Math.PI / 4 : 1;
-					const worldArea = shapeFactor * userData.width * worldScale.x * userData.height * worldScale.y;
-					const power = userData.intensity * Math.PI * ( normalize ? worldArea : 1 );
+					const power = userData.intensity * areaLightPowerFactor( object, userData.width, userData.height, userData );
 					const light = new RectAreaLight(
 						new Color( ...userData.color ),
 						power * this._profile.areaLightIntensityScale,
@@ -1776,9 +1785,9 @@ export class AssetLoader extends EventDispatcher {
 					light.userData.normalize = normalize;
 					light.userData.spread = Number.isFinite( userData.spread ) ? userData.spread : Math.PI;
 					light.userData.shape = shape;
+					light.userData.__radianceConverted = true; // already power, and traverse() reaches it
 					light.name = userData.name;
 					object.add( light );
-					visitedAreaLights.push( light.uuid );
 
 				}
 

package/src/Processor/QueueManager.js

@@ -27,9 +27,15 @@ export const COUNTER = {
 	// bits restricted to pixels that hit geometry, so the stop can require both fractions.
 	GEOMETRY_COUNT: 5,
 	CONVERGED_GEOMETRY_COUNT: 6,
-	COUNT: 7,
+	// 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,
+	COUNT: 8,
 };
 
+export const ENERGY_SCALE = 64;
+export const ENERGY_RAY_CLAMP = 65535;
+
 /** Ray flag bits packed into rayBounceFlags (uint) */
 export const RAY_FLAG = {
 	BOUNCE_MASK: 0xFF, // bits 0-7: bounce count (0-255)
@@ -81,10 +87,10 @@ export class QueueManager {
 		this._countersAttr = new StorageInstancedBufferAttribute( new Uint32Array( COUNTER.COUNT ), 1 );
 		this.counters = storage( this._countersAttr, 'uint' ).toAtomic();
 
-		// per-bounce ACTIVE_RAY_COUNT snapshots; read back async to size/skip late bounces next frame
+		// per-bounce snapshots for the async readback: [0, MAX) ACTIVE_RAY_COUNT, [MAX, 2·MAX) ACTIVE_ENERGY
 		this.MAX_BOUNCE_SNAPSHOTS = 32;
 		this._bounceCountsAttr = new StorageInstancedBufferAttribute(
-			new Uint32Array( this.MAX_BOUNCE_SNAPSHOTS ), 1,
+			new Uint32Array( 2 * this.MAX_BOUNCE_SNAPSHOTS ), 1,
 		);
 		this.bounceCounts = storage( this._bounceCountsAttr, 'uint' );
 

package/src/Processor/SceneProcessor.js

@@ -836,7 +836,7 @@ export class SceneProcessor {
 			// (the prior model-load path omitted this, leaving albedo un-decoded / too bright).
 			const buildBucket = ( list, srgb ) => list.length === 0
 				? Promise.resolve( null )
-				: this.textureCreator.createTexturesToDataTexture( list ).then( tex => {
+				: this.textureCreator.createTexturesToDataTexture( list, { srgbPool: srgb } ).then( tex => {
 
 					if ( tex && srgb ) tex.colorSpace = SRGBColorSpace;
 					return tex;

package/src/Processor/TextureCreator.js

@@ -1,7 +1,38 @@
-import { DataArrayTexture, RGBAFormat, LinearFilter, UnsignedByteType, SRGBColorSpace, RepeatWrapping } from "three";
+import { DataArrayTexture, RGBAFormat, LinearFilter, UnsignedByteType, SRGBColorSpace, LinearSRGBColorSpace, RepeatWrapping } from "three";
 import { TEXTURE_CONSTANTS, MEMORY_CONSTANTS, DEFAULT_TEXTURE_MATRIX, MATERIAL_DATA_LAYOUT, normalizeAttenuationDistance } from '../EngineDefaults.js';
 import TexturesWorker from './Workers/TexturesWorker.js?worker&inline';
 import { ISSUE_CODES } from '../EngineIssues.js';
+import { linearToSRGB } from './ToneMapCPU.js';
+import { createLogger } from '../utils/Logger.js';
+
+const log = createLogger( 'textures' );
+
+// A bucket array carries ONE colorSpace and the shader reads each slot from a fixed pool, so a
+// texture disagreeing with its pool cannot be re-routed — its pixels are re-encoded instead.
+const TRANSFER_LUT = { toSRGB: null, toLinear: null };
+
+function transferLUT( direction ) {
+
+	if ( ! TRANSFER_LUT[ direction ] ) {
+
+		const lut = new Uint8Array( 256 );
+		for ( let i = 0; i < 256; i ++ ) {
+
+			const c = i / 255;
+			const v = direction === 'toSRGB'
+				? linearToSRGB( c )
+				: ( c <= 0.04045 ? c / 12.92 : Math.pow( ( c + 0.055 ) / 1.055, 2.4 ) );
+			lut[ i ] = Math.max( 0, Math.min( 255, Math.round( v * 255 ) ) );
+
+		}
+
+		TRANSFER_LUT[ direction ] = lut;
+
+	}
+
+	return TRANSFER_LUT[ direction ];
+
+}
 
 // Canvas pooling for efficient reuse of canvas elements
 class CanvasPool {
@@ -541,13 +572,76 @@ export class TextureCreator {
 
 	}
 
+	/**
+	 * Re-encodes any layer whose declared colour space disagrees with its pool, so the GPU's
+	 * decode — or absence of one — lands on the values the author stored. An untagged texture
+	 * keeps its pool's convention, which is what every loader produces for glTF.
+	 *
+	 * @param {import('three').DataArrayTexture} arrayTex
+	 * @param {Array<import('three').Texture>} textures - pre-normalization list, in layer order
+	 * @param {boolean} srgbPool - true when the array is tagged SRGBColorSpace
+	 */
+	_harmonizeTransfer( arrayTex, textures, srgbPool ) {
+
+		const data = arrayTex?.image?.data;
+		if ( ! data ) return;
+
+		// Mirrors _normalizeTexturesForProcessing's skip rule, which is what sets layer order.
+		const kept = textures.filter( t => t?.image );
+		const want = srgbPool ? SRGBColorSpace : LinearSRGBColorSpace;
+		const layerSize = arrayTex.image.width * arrayTex.image.height * 4;
+		const converted = [];
+
+		for ( let layer = 0; layer < kept.length; layer ++ ) {
+
+			const declared = kept[ layer ].colorSpace;
+			// Only an explicit disagreement is acted on; NoColorSpace defers to the pool.
+			if ( declared !== SRGBColorSpace && declared !== LinearSRGBColorSpace ) continue;
+			if ( declared === want ) continue;
+
+			const lut = transferLUT( srgbPool ? 'toSRGB' : 'toLinear' );
+			const start = layer * layerSize;
+			const end = Math.min( start + layerSize, data.length );
+			// RGB only — alpha is never transfer-encoded.
+			for ( let i = start; i < end; i += 4 ) {
+
+				data[ i ] = lut[ data[ i ] ];
+				data[ i + 1 ] = lut[ data[ i + 1 ] ];
+				data[ i + 2 ] = lut[ data[ i + 2 ] ];
+
+			}
+
+			converted.push( kept[ layer ].name || kept[ layer ].source?.uuid?.slice( 0, 8 ) || `layer ${layer}` );
+
+		}
+
+		if ( converted.length === 0 ) return;
+
+		arrayTex.needsUpdate = true;
+		const names = converted.slice( 0, 4 ).join( ', ' ) + ( converted.length > 4 ? `, +${converted.length - 4} more` : '' );
+
+		if ( srgbPool ) {
+
+			log.info( `re-encoded ${converted.length}/${kept.length} linear-declared colour map(s) to sRGB so the GPU decode round-trips: ${names}` );
+
+		} else {
+
+			// Storing a decoded value in an 8-bit linear array is the lossy direction, and a
+			// transfer-encoded data map is almost always an authoring slip rather than intent.
+			log.warn( `decoded ${converted.length}/${kept.length} sRGB-declared data map(s) to linear — precision is lost in the darks, check the asset: ${names}` );
+
+		}
+
+	}
+
 	// Unified texture processing with strategy selection
-	async createTexturesToDataTexture( textures ) {
+	async createTexturesToDataTexture( textures, { srgbPool = false } = {} ) {
 
 		if ( ! textures || textures.length === 0 ) return null;
 
-		// Check cache first
-		const cacheKey = this.textureCache.generateHash( textures );
+		// Pool is part of the identity: the same list packed for the colour pool and the data pool
+		// gets different pixels (see _harmonizeTransfer), so one key must not serve both.
+		const cacheKey = `${srgbPool ? 's' : 'l'}:${this.textureCache.generateHash( textures )}`;
 		const cached = this.textureCache.get( cacheKey );
 		if ( cached ) return cached;
 
@@ -579,6 +673,7 @@ export class TextureCreator {
 			// Cache successful result
 			if ( result ) {
 
+				this._harmonizeTransfer( result, textures, srgbPool );
 				this.textureCache.set( cacheKey, result );
 
 			}
@@ -592,7 +687,9 @@ export class TextureCreator {
 				'worker texture processing failed — retrying on the main thread',
 				{ cause: String( error?.message ?? error ) }
 			);
-			return await this.processOnMainThreadSync( normalized );
+			const fallback = await this.processOnMainThreadSync( normalized );
+			this._harmonizeTransfer( fallback, textures, srgbPool );
+			return fallback;
 
 		} finally {
 

package/src/Stages/PathTracer.js

@@ -8,7 +8,7 @@ import { uniform, texture, storage } from 'three/tsl';
 import { StorageInstancedBufferAttribute } from 'three/webgpu';
 import { PathTracerStage } from './PathTracerStage.js';
 import { PackedRayBuffer, GBUFFER_STRIDE, RAY_STRIDE, HIT_STRIDE, freeStorageAttribute } from '../Processor/PackedRayBuffer.js';
-import { QueueManager, COUNTER } from '../Processor/QueueManager.js';
+import { QueueManager, COUNTER, ENERGY_SCALE } from '../Processor/QueueManager.js';
 import { VRAMTracker } from '../Processor/VRAMTracker.js';
 import { KernelManager } from '../Processor/KernelManager.js';
 import { buildGenerateKernel, GENERATE_WG_SIZE } from '../TSL/GenerateKernel.js';
@@ -85,6 +85,7 @@ export class PathTracer extends PathTracerStage {
 		this._useSubgroupCompact = false;
 
 		this._lastBounceCounts = null;
+		this._lastBounceEnergy = null;
 		// maxBounces the curve was measured at; the curve is ignored once this no longer matches (-1 = none).
 		this._lastBounceCountsBudget = - 1;
 		this._readbackPending = false;
@@ -95,10 +96,11 @@ export class PathTracer extends PathTracerStage {
 		// Whether the survivor curve may be trusted to SIZE the dispatch. False during/after camera motion
 		// (or resize) until a readback measured at the settled view re-validates it — full-size until then so
 		// a stale/mid-motion curve can't under-size the row-major list and drop the bottom rows. The curve is
-		// still used for the per-bounce early-exit regardless (a stale early-exit only trims empty deep bounces).
+		// still used for the per-bounce early-exit regardless (it only trims bounces holding negligible energy).
 		this._curveSizingValid = false;
-		// 0.1% of primary ray count, floored at 100; -1 to disable. Updated per-scene in _buildWavefrontKernels.
-		this._bounceEarlyExitThreshold = 100;
+		// Early exit once the survivors' summed throughput is below this fraction of a full frame's; -1
+		// disables. Never a ray count: after Russian roulette a handful of survivors carry real weight.
+		this._bounceEarlyExitThreshold = 1e-4;
 
 		// Tier-1 convergence early-stop: fraction of pixels converged in the last settled-view readback, and a
 		// single-flight guard for its async counter read. Zeroed on reset/camera-move/resize; never refreshed
@@ -400,6 +402,9 @@ export class PathTracer extends PathTracerStage {
 
 			}
 
+			const energyCurve = this._lastBounceEnergy;
+			const exitEnergy = this._bounceEarlyExitThreshold >= 0 ? this._bounceEarlyExitThreshold * maxRays * ENERGY_SCALE : - 1;
+
 			for ( let bounce = 0; bounce <= loopBound; bounce ++ ) {
 
 				this._wfCurrentBounce.value = bounce;
@@ -474,10 +479,11 @@ export class PathTracer extends PathTracerStage {
 
 				// Early-exit on last frame's per-bounce snapshot (single-chunk only; curveReliableUpto=0 disables it for multi-chunk).
 				if (
-					bounce < curveReliableUpto
+					exitEnergy >= 0
+					&& bounce < curveReliableUpto
 					&& bounce < loopBound
-					&& curve[ bounce ] !== undefined
-					&& curve[ bounce ] <= this._bounceEarlyExitThreshold
+					&& energyCurve?.[ bounce ] !== undefined
+					&& energyCurve[ bounce ] <= exitEnergy
 				) {
 
 					break;
@@ -732,6 +738,7 @@ export class PathTracer extends PathTracerStage {
 		this._readbackPending = true;
 		const gen = this._readbackGeneration;
 		const budget = this.maxBounces.value;
+		const n = this._queueManager.MAX_BOUNCE_SNAPSHOTS;
 		this.renderer.getArrayBufferAsync( attr ).then( ( buf ) => {
 
 			// Drop counts measured at a now-stale generation (a resize or camera move happened mid-flight).
@@ -739,7 +746,9 @@ export class PathTracer extends PathTracerStage {
 			// happened before it resolved, so its counts match the current view — safe to size from.
 			if ( gen === this._readbackGeneration ) {
 
-				this._lastBounceCounts = new Uint32Array( buf.slice( 0 ) );
+				const all = new Uint32Array( buf.slice( 0 ) );
+				this._lastBounceCounts = all.subarray( 0, n );
+				this._lastBounceEnergy = all.subarray( n, 2 * n );
 				this._lastBounceCountsBudget = budget;
 				this._curveSizingValid = true;
 
@@ -826,6 +835,7 @@ export class PathTracer extends PathTracerStage {
 		// until the readback re-measures at the new size; bump the generation so any readback already
 		// in flight (carrying the old-resolution counts) is discarded when it resolves.
 		this._lastBounceCounts = null;
+		this._lastBounceEnergy = null;
 		this._lastBounceCountsBudget = - 1;
 		this._curveSizingValid = false;
 		this._readbackFrameCounter = 0;
@@ -861,11 +871,6 @@ export class PathTracer extends PathTracerStage {
 		this._wfRenderWidth.value = w;
 		this._wfRenderHeight.value = h;
 		this._updateChunkLayout();
-		if ( this._bounceEarlyExitThreshold !== - 1 ) {
-
-			this._bounceEarlyExitThreshold = Math.max( 100, Math.floor( ( w * h ) / 1000 ) );
-
-		}
 
 	}
 
@@ -969,11 +974,6 @@ export class PathTracer extends PathTracerStage {
 		// every per-ray kernel's dispatch per chunk; this is just a valid starting grid (always ≤ B).
 		const maxRays = this._chunkRows * w;
 
-		if ( this._bounceEarlyExitThreshold !== - 1 ) {
-
-			this._bounceEarlyExitThreshold = Math.max( 100, Math.floor( ( w * h ) / 1000 ) );
-
-		}
 
 		// Per-path buffers (RAY/HIT/rng) sized to the budget B and indexed by LOCAL slot r ∈ [0,B). _cap = B is
 		// baked into the SoA stride but never changes with resolution, so this build happens once (model load).
@@ -1068,6 +1068,7 @@ export class PathTracer extends PathTracerStage {
 			const cnt = atomicLoad( counters.element( uint( COUNTER.ACTIVE_RAY_COUNT ) ) );
 			const slot = uint( wfCurrentBounce ).clamp( uint( 0 ), uint( qm.MAX_BOUNCE_SNAPSHOTS - 1 ) );
 			bounceCountsBuf.element( slot ).assign( cnt );
+			bounceCountsBuf.element( slot.add( uint( qm.MAX_BOUNCE_SNAPSHOTS ) ) ).assign( atomicLoad( counters.element( uint( COUNTER.ACTIVE_ENERGY ) ) ) );
 			// Also set ENTERING_COUNT for the next bounce; the full-dispatch path's enterFull overrides it.
 			atomicStore( counters.element( uint( COUNTER.ENTERING_COUNT ) ), cnt );
 
@@ -1522,6 +1523,7 @@ export class PathTracer extends PathTracerStage {
 
 				const slot = uint( wfCurrentBounce ).clamp( uint( 0 ), uint( qm.MAX_BOUNCE_SNAPSHOTS - 1 ) );
 				bounceCountsBuf.element( slot ).assign( active );
+				bounceCountsBuf.element( slot.add( uint( qm.MAX_BOUNCE_SNAPSHOTS ) ) ).assign( atomicLoad( counters.element( uint( COUNTER.ACTIVE_ENERGY ) ) ) );
 				atomicStore( counters.element( uint( COUNTER.ENTERING_COUNT ) ), active );
 
 			} );

package/src/TSL/CompactKernel.js

@@ -3,7 +3,7 @@
  */
 
 import {
-	Fn, uint, select,
+	Fn, uint, select, max, min,
 	If,
 	instanceIndex,
 	atomicAdd, atomicLoad,
@@ -11,11 +11,20 @@ import {
 	Return,
 } from 'three/tsl';
 
-import { readRayBounceFlags } from '../Processor/PackedRayBuffer.js';
-import { RAY_FLAG, COUNTER } from '../Processor/QueueManager.js';
+import { readRayBounceFlags, readRayThroughput } from '../Processor/PackedRayBuffer.js';
+import { RAY_FLAG, COUNTER, ENERGY_SCALE, ENERGY_RAY_CLAMP } from '../Processor/QueueManager.js';
 
 const WG_SIZE = 256;
 
+// Survivor's remaining throughput as fixed-point u32; clamped so a frame's sum cannot wrap.
+const rayEnergy = ( rayBufferRO, rayID ) => {
+
+	const t = readRayThroughput( rayBufferRO, rayID );
+	const m = max( max( t.x, t.y ), t.z ).max( 0.0 );
+	return min( uint( m.mul( ENERGY_SCALE ).add( 0.5 ) ), uint( ENERGY_RAY_CLAMP ) );
+
+};
+
 export function buildCompactKernel( params ) {
 
 	const {
@@ -46,6 +55,7 @@ export function buildCompactKernel( params ) {
 
 			const writeIdx = atomicAdd( counters.element( uint( COUNTER.ACTIVE_RAY_COUNT ) ), uint( 1 ) );
 			activeIndicesWriteRW.element( writeIdx ).assign( rayID );
+			atomicAdd( counters.element( uint( COUNTER.ACTIVE_ENERGY ) ), rayEnergy( rayBufferRO, rayID ) );
 
 		} );
 
@@ -80,10 +90,12 @@ export function buildCompactSubgroupKernel( params ) {
 		const flags = readRayBounceFlags( rayBufferRO, rayID );
 		const isActive = inRange.and( flags.bitAnd( uint( RAY_FLAG.ACTIVE ) ).notEqual( uint( 0 ) ) );
 		const activeU = select( isActive, uint( 1 ), uint( 0 ) );
+		const energyU = select( isActive, rayEnergy( rayBufferRO, rayID ), uint( 0 ) );
 
 		// .toVar() materializes the subgroup ops at uniform control flow; inlining into the divergent If(isActive) write is rejected by WGSL.
 		const localOffset = subgroupExclusiveAdd( activeU ).toVar();
 		const sgCount = subgroupAdd( activeU ).toVar();
+		const sgEnergy = subgroupAdd( energyU ).toVar();
 
 		// laneId via exclusiveAdd(1) since TSL lacks subgroup_invocation_id; lane 0 does the single per-subgroup atomicAdd.
 		const laneId = subgroupExclusiveAdd( uint( 1 ) ).toVar();
@@ -91,6 +103,7 @@ export function buildCompactSubgroupKernel( params ) {
 		If( laneId.equal( uint( 0 ) ), () => {
 
 			base.assign( atomicAdd( counters.element( uint( COUNTER.ACTIVE_RAY_COUNT ) ), sgCount ) );
+			atomicAdd( counters.element( uint( COUNTER.ACTIVE_ENERGY ) ), sgEnergy );
 
 		} );
 		const sgBase = subgroupBroadcast( base, uint( 0 ) ).toVar();

package/src/TSL/ShadeKernel.js

@@ -155,6 +155,7 @@ export function buildShadeKernel( params ) {
 			If( threadIdx.equal( uint( 0 ) ), () => {
 
 				atomicStore( counters.element( uint( COUNTER.ACTIVE_RAY_COUNT ) ), uint( 0 ) );
+				atomicStore( counters.element( uint( COUNTER.ACTIVE_ENERGY ) ), uint( 0 ) );
 
 			} );