rayzee 7.28.0 → 7.28.2

package/package.json

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

package/src/EngineDefaults.js

@@ -10,7 +10,7 @@
  */
 export const RENDER_PROFILES = Object.freeze( {
 	viewer: Object.freeze( {
-		areaLightIntensityScale: 0.1, // authored RectAreaLight watts from glTF placeholders
+		areaLightIntensityScale: 0.1, // scales glTF placeholder area-light power (viewer tuning)
 		environmentRotation: 270.0, // degrees
 		toneMapping: 4, // ACESFilmicToneMapping
 		saturation: 1.2, // compensates for ACES desaturation — see Compositor

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,23 +1773,21 @@ export class AssetLoader extends EventDispatcher {
 
 				if ( userData.type === 'RectAreaLight' ) {
 
-					// Intensity is authored in Watts (Blender-style); emitted radiance
-					// is computed at render time as power/(π·area). Blender emission
-					// defaults: power-normalized, full Lambertian spread (π), rectangle.
-					// Viewer tuning, not physics — see RENDER_PROFILES.
+					const normalize = userData.normalize ?? true;
+					const shape = userData.shape ?? 'rectangle';
+					const power = userData.intensity * areaLightPowerFactor( object, userData.width, userData.height, userData );
 					const light = new RectAreaLight(
 						new Color( ...userData.color ),
-						userData.intensity * this._profile.areaLightIntensityScale,
+						power * this._profile.areaLightIntensityScale,
 						userData.width,
 						userData.height
 					);
-					light.userData.normalize = userData.normalize ?? true;
+					light.userData.normalize = normalize;
 					light.userData.spread = Number.isFinite( userData.spread ) ? userData.spread : Math.PI;
-					light.userData.shape = userData.shape ?? 'rectangle';
-					light.position.z = - 2;
+					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/EmissiveSampling.js

@@ -527,7 +527,7 @@ export const sampleEmissiveTriangle = Fn( ( [
 // products with the PDF call below.
 
 export const calculateEmissiveTriangleContributionDebug = Fn( ( [
-	hitPoint, normal, viewDir, material,
+	hitPoint, normal, geomNormal, viewDir, material,
 	bounceIndex, rngState,
 	pixelCoord, resolution, frame, dimBase,
 	emissiveBoost,
@@ -565,10 +565,10 @@ export const calculateEmissiveTriangleContributionDebug = Fn( ( [
 		// Check geometric validity
 		const NoL = max( float( 0.0 ), dot( normal, emissiveSample.direction ) );
 
-		If( NoL.greaterThan( 0.0 ), () => {
+		If( NoL.greaterThan( 0.0 ).and( dot( emissiveSample.direction, geomNormal ).greaterThan( 0.0 ) ), () => {
 
 			// Calculate ray offset for shadow ray
-			const rayOffset = calculateRayOffsetFn( hitPoint, normal, material );
+			const rayOffset = calculateRayOffsetFn( hitPoint, geomNormal, material );
 			const rayOrigin = hitPoint.add( rayOffset );
 
 			// Trace shadow ray
@@ -609,7 +609,7 @@ export const calculateEmissiveTriangleContributionDebug = Fn( ( [
 
 // Wrapper that returns just the contribution vec3
 export const calculateEmissiveTriangleContribution = Fn( ( [
-	hitPoint, normal, viewDir, material,
+	hitPoint, normal, geomNormal, viewDir, material,
 	bounceIndex, rngState,
 	pixelCoord, resolution, frame, dimBase,
 	emissiveBoost,
@@ -620,7 +620,7 @@ export const calculateEmissiveTriangleContribution = Fn( ( [
 ] ) => {
 
 	const result = EmissiveContributionResult.wrap( calculateEmissiveTriangleContributionDebug(
-		hitPoint, normal, viewDir, material,
+		hitPoint, normal, geomNormal, viewDir, material,
 		bounceIndex, rngState,
 		pixelCoord, resolution, frame, dimBase,
 		emissiveBoost,

package/src/TSL/LightsDirect.js

@@ -341,8 +341,10 @@ export const estimateLightImportance = Fn( ( [ light, hitPoint, normal, material
 
 		If( lightFacing.greaterThan( 0.0 ), () => {
 
-			const solidAngle = light.area.div( max( distSq, 0.1 ) );
-			const power = light.intensity.mul( dot( light.color, REC709_LUMINANCE_COEFFICIENTS ) ).mul( light.area );
+			// Diffuse irradiance ∝ L·Ω·cosθ·cosθ′, Ω bounded by the hemisphere. Unit-free.
+			const solidAngle = min( light.area.div( max( distSq, 1e-12 ) ), float( 2.0 * Math.PI ) );
+			const invArea = select( light.normalize.greaterThan( 0.5 ), float( 1.0 ).div( max( light.area, 1e-10 ) ), float( 1.0 ) );
+			const radiance = light.intensity.mul( dot( light.color, REC709_LUMINANCE_COEFFICIENTS ) ).mul( invArea );
 
 			// Material-aware weighting
 			const materialFactor = float( 1.0 ).toVar();
@@ -358,20 +360,13 @@ export const estimateLightImportance = Fn( ( [ light, hitPoint, normal, material
 
 			} );
 
-			If( material.roughness.greaterThan( 0.6 ).and( material.metalness.lessThan( 0.3 ) ), () => {
-
-				const sizeBoost = min( light.area.mul( 2.0 ), float( 2.0 ) );
-				materialFactor.mulAssign( sizeBoost );
-
-			} );
-
 			If( material.transmission.greaterThan( 0.5 ), () => {
 
 				materialFactor.mulAssign( float( 1.0 ).add( material.transmission.mul( 0.3 ) ) );
 
 			} );
 
-			result.assign( power.mul( solidAngle ).mul( NoL ).mul( lightFacing ).mul( materialFactor ) );
+			result.assign( radiance.mul( solidAngle ).mul( NoL ).mul( lightFacing ).mul( materialFactor ) );
 
 		} );