rayzee 7.28.1 → 7.28.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "rayzee",
-  "version": "7.28.1",
+  "version": "7.28.2",
   "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/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 ) );
 
 			} );