rayzee 7.4.1 → 7.5.1

package/package.json

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

package/src/EngineDefaults.js

@@ -88,6 +88,10 @@ export const ENGINE_DEFAULTS = {
 	performanceModeAdaptive: 'medium',
 
 	fireflyThreshold: 3.0,
+	// Wavefront material-coherence sort: global counting-sort of entering rays by material before
+	// Shade (material-pure workgroups), under dynamic dispatch. Measured −8% at 1024²/8b. Gated on
+	// material count > 8; the histogram bin count is sized per-scene to the material count.
+	wavefrontSortMaterials: true,
 	renderLimitMode: 'frames',
 	renderTimeLimit: 30,
 	renderMode: 0,

package/src/Processor/AssetLoader.js

@@ -1446,12 +1446,18 @@ 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.
 					const light = new RectAreaLight(
 						new Color( ...userData.color ),
-						userData.intensity * 0.1 / Math.PI, // Adjust intensity for better visual results
+						userData.intensity * 0.1,
 						userData.width,
 						userData.height
 					);
+					light.userData.normalize = userData.normalize ?? true;
+					light.userData.spread = Number.isFinite( userData.spread ) ? userData.spread : Math.PI;
+					light.userData.shape = userData.shape ?? 'rectangle';
 					light.position.z = - 2;
 					light.name = userData.name;
 					object.add( light );

package/src/Processor/KernelManager.js

@@ -12,8 +12,7 @@
 const WORKGROUP_SIZES = {
 	generate: [ 16, 16, 1 ], // 2D screen-space
 	extend: [ 256, 1, 1 ], // 1D ray-parallel
-	sort: [ 256, 1, 1 ], // 1D ray-parallel
-	shade: [ 256, 1, 1 ], // 1D ray-parallel (sorted)
+	shade: [ 256, 1, 1 ], // 1D ray-parallel (material-sorted when sort enabled)
 	connect: [ 256, 1, 1 ], // 1D shadow-ray-parallel
 	accumulate: [ 256, 1, 1 ], // 1D shadow-ray-parallel
 	compact: [ 256, 1, 1 ], // 1D ray-parallel

package/src/Processor/LightSerializer.js

@@ -1,4 +1,31 @@
 import { Vector3, Quaternion } from 'three';
+import { blackbodyToLinearRGB } from './blackbody.js';
+
+// Point & spot lights specify Power in Watts; the shader uses radiant intensity
+// (W/sr) as `intensity / dist²`, so convert with I = P / 4π (isotropic emitter),
+// matching Blender. Area lights are already radiant power; the Sun is irradiance.
+const INV_4PI = 1 / ( 4 * Math.PI );
+
+// Effective emission colour + intensity after per-light Exposure (EV stops) and
+// optional blackbody Temperature tint (Blender-style). Both fold into the values
+// already sent to the GPU — no shader or struct change needed.
+function effectiveEmission( light ) {
+
+	const ud = light.userData || {};
+	const exposure = Number.isFinite( ud.exposure ) ? ud.exposure : 0;
+	const intensity = light.intensity * Math.pow( 2, exposure );
+
+	let r = light.color.r, g = light.color.g, b = light.color.b;
+	if ( ud.useTemperature ) {
+
+		const [ tr, tg, tb ] = blackbodyToLinearRGB( ud.temperature ?? 6500 );
+		r *= tr; g *= tg; b *= tb;
+
+	}
+
+	return { r, g, b, intensity };
+
+}
 
 export class LightSerializer {
 
@@ -90,6 +117,8 @@ export class LightSerializer {
 		// Get angle parameter from light (default to 0 for sharp shadows)
 		const angle = light.userData.angle || light.angle || 0.0; // In radians
 
+		const em = effectiveEmission( light );
+
 		// Optional projection mask. Sign of intensity carries the inverted flag.
 		const gobo = light.userData?.gobo;
 		const goboIndex = ( gobo && Number.isInteger( gobo.index ) ) ? gobo.index : - 1;
@@ -101,8 +130,8 @@ export class LightSerializer {
 		this.directionalLightCache.push( {
 			data: [
 				direction.x, direction.y, direction.z, // direction toward light (3)
-				light.color.r, light.color.g, light.color.b, // color (3)
-				light.intensity, // intensity (1)
+				em.r, em.g, em.b, // color (3) — incl. temperature tint
+				em.intensity, // intensity (1) — incl. exposure
 				angle, // angular diameter in radians (1)
 				goboIndex, // gobo layer index, -1 = none (1)
 				goboIntensity, // signed gobo strength (1)
@@ -133,14 +162,25 @@ export class LightSerializer {
 		// Calculate importance for sorting
 		const importance = this.calculateLightImportance( light, 'area' );
 
-		// Store in cache with importance
+		// Blender-style emission controls (stored on userData; sensible defaults).
+		// normalize ON → radiance ∝ 1/area (resizing keeps total power constant).
+		const normalize = ( light.userData?.normalize ?? true ) ? 1.0 : 0.0;
+		const spread = Number.isFinite( light.userData?.spread ) ? light.userData.spread : Math.PI;
+		const shape = ( light.userData?.shape === 'ellipse' || light.userData?.shape === 'disk' || light.userData?.shape === 1 ) ? 1.0 : 0.0;
+
+		const em = effectiveEmission( light );
+
+		// Store in cache with importance (16 floats, vec4-aligned)
 		this.areaLightCache.push( {
 			data: [
 				position.x, position.y, position.z, // position (3)
-				u.x, u.y, u.z, // u vector (3)
-				v.x, v.y, v.z, // v vector (3)
-				light.color.r, light.color.g, light.color.b, // color (3)
-				light.intensity // intensity (1)
+				u.x, u.y, u.z, // u half-vector (3)
+				v.x, v.y, v.z, // v half-vector (3)
+				em.r, em.g, em.b, // color (3) — incl. temperature tint
+				em.intensity, // radiant power in Watts (1) — incl. exposure
+				normalize, // power-normalize flag (1)
+				spread, // emission spread in radians (1)
+				shape, // 0 = rect, 1 = disk/ellipse (1)
 			],
 			importance: importance,
 			light: light
@@ -159,12 +199,14 @@ export class LightSerializer {
 		// Calculate importance for sorting
 		const importance = this.calculateLightImportance( light, 'point' );
 
+		const em = effectiveEmission( light );
+
 		// Store in cache with importance
 		this.pointLightCache.push( {
 			data: [
 				position.x, position.y, position.z, // position (3)
-				light.color.r, light.color.g, light.color.b, // color (3)
-				light.intensity, // intensity (1)
+				em.r, em.g, em.b, // color (3) — incl. temperature tint
+				em.intensity * INV_4PI, // radiant intensity W/sr = power(W)/4π, incl. exposure (1)
 				light.distance || 0.0, // cutoff distance (0 = infinite) (1)
 				light.decay !== undefined ? light.decay : 2.0 // decay exponent (1)
 			],
@@ -198,13 +240,15 @@ export class LightSerializer {
 		const iesIndex = ( ies && Number.isInteger( ies.index ) ) ? ies.index : - 1;
 		const iesIntensity = ( ies && typeof ies.intensity === 'number' ) ? ies.intensity : 1.0;
 
+		const em = effectiveEmission( light );
+
 		// Store in cache with importance
 		this.spotLightCache.push( {
 			data: [
 				position.x, position.y, position.z, // position (3)
 				direction.x, direction.y, direction.z, // direction (3)
-				light.color.r, light.color.g, light.color.b, // color (3)
-				light.intensity, // intensity (1)
+				em.r, em.g, em.b, // color (3) — incl. temperature tint
+				em.intensity * INV_4PI, // radiant intensity W/sr = power(W)/4π, incl. exposure (1)
 				light.angle || Math.PI / 4, // cone half-angle in radians (1)
 				light.penumbra || 0.0, // penumbra [0,1] (1)
 				light.distance || 0.0, // cutoff distance (0 = infinite) (1)
@@ -290,7 +334,7 @@ export class LightSerializer {
 
 		// Divide flat array lengths by per-light stride to get actual light counts
 		const directionalCount = Math.floor( this.lightData.directional.length / 12 );
-		const areaCount = Math.floor( this.lightData.rectArea.length / 13 );
+		const areaCount = Math.floor( this.lightData.rectArea.length / 16 );
 		const pointCount = Math.floor( this.lightData.point.length / 9 );
 		const spotCount = Math.floor( this.lightData.spot.length / 20 );
 

package/src/Processor/QueueManager.js

@@ -40,6 +40,9 @@ export class QueueManager {
 		// A/B alternate: one read by current bounce, other written by compaction
 		this.activeIndices = null;
 		this.activeIndicesRO = null;
+		this.sortedIndices = null;
+		this.sortedIndicesRO = null;
+		this.sortGlobalHistogram = null;
 		this.pingPong = 0; // 0 = read A / write B, 1 = read B / write A
 
 		if ( maxRays > 0 ) {
@@ -83,11 +86,23 @@ export class QueueManager {
 			b: storage( attrB, 'uint' ).toReadOnly(),
 		};
 
+		// Material-sort output: a material-reordered permutation of the active index
+		// list, written by the global material sort and read by Shade in place of activeIndices.
+		const sortAttr = new StorageInstancedBufferAttribute( new Uint32Array( capacity ), 1 );
+		this._sortAttr = sortAttr;
+		this.sortedIndices = storage( sortAttr, 'uint' );
+		this.sortedIndicesRO = storage( sortAttr, 'uint' ).toReadOnly();
+
+		// Global material-sort histogram, sized to the bin cap (SORT_GLOBAL_MAX_BINS=256); kernels use
+		// only the first `bins` entries (= per-scene material count). 256 × 4B = 1KB.
+		this._sortGlobalHistAttr = new StorageInstancedBufferAttribute( new Uint32Array( 256 ), 1 );
+		this.sortGlobalHistogram = storage( this._sortGlobalHistAttr, 'uint' ).toAtomic();
+
 		this.pingPong = 0;
 
 		const totalBytes = (
 			COUNTER.COUNT * 4 +
-			capacity * 4 * 2
+			capacity * 4 * 3
 		);
 
 		console.log(
@@ -131,6 +146,24 @@ export class QueueManager {
 
 	}
 
+	getSortedRW() {
+
+		return this.sortedIndices;
+
+	}
+
+	getSortedRO() {
+
+		return this.sortedIndicesRO;
+
+	}
+
+	getSortGlobalHistogram() {
+
+		return this.sortGlobalHistogram;
+
+	}
+
 	// raw attribute for `renderer.getArrayBufferAsync(...)` readback
 	getCountersAttribute() {
 
@@ -167,6 +200,9 @@ export class QueueManager {
 		this.counters = null;
 		this.activeIndices = null;
 		this.activeIndicesRO = null;
+		this.sortedIndices = null;
+		this.sortedIndicesRO = null;
+		this.sortGlobalHistogram = null;
 		this.capacity = 0;
 
 	}

package/src/Processor/blackbody.js

@@ -0,0 +1,74 @@
+// Blackbody temperature → linear Rec.709 (= linear sRGB) RGB.
+//
+// Ported verbatim from Blender/Cycles `svm_math_blackbody_color_rec709`
+// (Lukas Stockner's 7-segment rational/cubic fit; coefficients from
+// intern/cycles/kernel/tables.h). The fit is luminance-balanced — the Rec.709
+// luminance of the returned colour is ≈1.0 across the whole range — so it can be
+// multiplied straight into a light's colour without altering its power: the
+// temperature shifts hue only, brightness stays governed by intensity. This is
+// exactly how Cycles applies it (raw multiply into the light colour, no
+// renormalisation).
+
+const BB_R = [
+	[ 1.61919106e3, - 2.05010916e-3, 5.02995757e0 ],
+	[ 2.48845471e3, - 1.11330907e-3, 3.22621544e0 ],
+	[ 3.34143193e3, - 4.86551192e-4, 1.76486769e0 ],
+	[ 4.09461742e3, - 1.27446582e-4, 7.25731635e-1 ],
+	[ 4.67028036e3, 2.91258199e-5, 1.26703442e-1 ],
+	[ 4.59509185e3, 2.87495649e-5, 1.50345020e-1 ],
+	[ 3.78717450e3, 9.35907826e-6, 3.99075871e-1 ],
+];
+
+const BB_G = [
+	[ - 4.88999748e2, 6.04330754e-4, - 7.55807526e-2 ],
+	[ - 7.55994277e2, 3.16730098e-4, 4.78306139e-1 ],
+	[ - 1.02363977e3, 1.20223470e-4, 9.36662319e-1 ],
+	[ - 1.26571316e3, 4.87340896e-6, 1.27054498e0 ],
+	[ - 1.42529332e3, - 4.01150431e-5, 1.43972784e0 ],
+	[ - 1.17554822e3, - 2.16378048e-5, 1.30408023e0 ],
+	[ - 5.00799571e2, - 4.59832026e-6, 1.09098763e0 ],
+];
+
+const BB_B = [
+	[ 5.96945309e-11, - 4.85742887e-8, - 9.70622247e-5, - 4.07936148e-3 ],
+	[ 2.40430366e-11, 5.55021075e-8, - 1.98503712e-4, 2.89312858e-2 ],
+	[ - 1.40949732e-11, 1.89878968e-7, - 3.56632824e-4, 9.10767778e-2 ],
+	[ - 3.61460868e-11, 2.84822009e-7, - 4.93211319e-4, 1.56723440e-1 ],
+	[ - 1.97075738e-11, 1.75359352e-7, - 2.50542825e-4, - 2.22783266e-2 ],
+	[ - 1.61997957e-13, - 1.64216008e-8, 3.86216271e-4, - 7.38077418e-1 ],
+	[ 6.72650283e-13, - 2.73078809e-8, 4.24098264e-4, - 7.52335691e-1 ],
+];
+
+/**
+ * Convert a colour temperature in Kelvin to linear Rec.709 / linear-sRGB RGB.
+ * Negative out-of-gamut channels (very low temperatures) are clamped to 0.
+ * @param {number} kelvin
+ * @returns {[number, number, number]}
+ */
+export function blackbodyToLinearRGB( kelvin ) {
+
+	let r, g, b;
+
+	if ( kelvin >= 12000 ) {
+
+		r = 0.8262954810464208; g = 0.9945080501520986; b = 1.566307710274283;
+
+	} else if ( kelvin < 800 ) {
+
+		r = 5.413294490189271; g = - 0.20319390035873933; b = - 0.0822535242887164;
+
+	} else {
+
+		const i = kelvin >= 6365 ? 6 : kelvin >= 3315 ? 5 : kelvin >= 1902 ? 4
+			: kelvin >= 1449 ? 3 : kelvin >= 1167 ? 2 : kelvin >= 965 ? 1 : 0;
+		const cr = BB_R[ i ], cg = BB_G[ i ], cb = BB_B[ i ];
+		const tInv = 1 / kelvin;
+		r = cr[ 0 ] * tInv + cr[ 1 ] * kelvin + cr[ 2 ];
+		g = cg[ 0 ] * tInv + cg[ 1 ] * kelvin + cg[ 2 ];
+		b = ( ( cb[ 0 ] * kelvin + cb[ 1 ] ) * kelvin + cb[ 2 ] ) * kelvin + cb[ 3 ];
+
+	}
+
+	return [ Math.max( 0, r ), Math.max( 0, g ), Math.max( 0, b ) ];
+
+}

package/src/Stages/PathTracer.js

@@ -17,6 +17,11 @@ import { buildShadeKernel, SHADE_WG_SIZE } from '../TSL/ShadeKernel.js';
 import { buildCompactKernel, buildCompactSubgroupKernel, COMPACT_WG_SIZE } from '../TSL/CompactKernel.js';
 import { buildFinalWriteKernel, FINALWRITE_WG_SIZE } from '../TSL/FinalWriteKernel.js';
 import { buildDebugKernel, DEBUG_WG_SIZE } from '../TSL/DebugKernel.js';
+import {
+	buildResetGlobalHistKernel, buildGlobalHistKernel, buildGlobalPrefixKernel, buildGlobalScatterKernel,
+	SORT_GLOBAL_WG_SIZE, SORT_GLOBAL_MAX_BINS,
+} from '../TSL/SortGlobalKernels.js';
+import { ENGINE_DEFAULTS } from '../EngineDefaults.js';
 import {
 	Fn, uint, atomicStore, atomicLoad, instanceIndex, If, Return,
 } from 'three/tsl';
@@ -43,6 +48,11 @@ export class PathTracer extends PathTracerStage {
 		// CPU sizes per-bounce kernels from last frame's survivor curve; kernels bound on ENTERING_COUNT so over-sizing is safe. (indirect dispatch not viable — three.js doesn't sync compute-written indirect buffers across submissions)
 		this._useDynamicDispatch = true;
 
+		// Global material-coherence sort: set per-build from ENGINE_DEFAULTS + material count (>8).
+		// Reorders entering rays into material-pure workgroups before Shade; runs under dynamic dispatch
+		// (compact reads the unsorted active list, so the survivor set is unchanged). Measured −8% at 1024²/8b.
+		this._sortMaterials = false;
+
 		// Flag-gated off: perf-neutral vs atomic-append and adds a 'subgroups' feature dependency.
 		this._useSubgroupCompact = false;
 
@@ -90,7 +100,7 @@ export class PathTracer extends PathTracerStage {
 			if ( ! qm ) return null;
 			return [
 				qm._countersAttr, qm._bounceCountsAttr,
-				qm._attrA, qm._attrB,
+				qm._attrA, qm._attrB, qm._sortAttr,
 			];
 
 		} );
@@ -250,6 +260,7 @@ export class PathTracer extends PathTracerStage {
 			this._wfCurrentBounce.value = bounce;
 
 			// Functional-compaction path (dynamic dispatch): copyback keeps the read buffer dense, kernels sized to live survivors. Dynamic-off uses the full path (ENTERING=maxRays, identity buffer).
+			// Material sort is compatible: shade reads sortedIndices while compact still reads the UNSORTED active list (getActiveReadRO), so the survivor set is unchanged.
 			const useFunctionalCompaction = this._useDynamicDispatch;
 			if ( useFunctionalCompaction ) {
 
@@ -281,6 +292,8 @@ export class PathTracer extends PathTracerStage {
 				const wg = [ Math.ceil( sized / 256 ), 1, 1 ];
 				km.setDispatchCount( 'extend', wg );
 				km.setDispatchCount( 'shade', wg );
+				km.setDispatchCount( 'globalHist', wg );
+				km.setDispatchCount( 'globalScatter', wg );
 				km.setDispatchCount( 'compact', wg );
 				km.setDispatchCount( 'compactCopyback', wg );
 
@@ -291,11 +304,23 @@ export class PathTracer extends PathTracerStage {
 				km.setDispatchCount( 'extend', full );
 				km.setDispatchCount( 'shade', full );
 				km.setDispatchCount( 'compact', full );
+				km.setDispatchCount( 'globalHist', full );
+				km.setDispatchCount( 'globalScatter', full );
 
 			}
 
 			// Extend/Shade kept separate (not fused): a fused kernel's register pressure drops occupancy more than fusion saves.
 			km.dispatch( 'extend' );
+			if ( this._sortMaterials ) {
+
+				// Global material counting sort (material-pure workgroups): reset, histogram, prefix-sum, scatter.
+				km.dispatch( 'resetGlobalHist' );
+				km.dispatch( 'globalHist' );
+				km.dispatch( 'globalPrefix' );
+				km.dispatch( 'globalScatter' );
+
+			}
+
 			km.dispatch( 'shade' );
 
 			km.dispatch( 'resetActiveCounter' );
@@ -660,6 +685,10 @@ export class PathTracer extends PathTracerStage {
 			displacementMaps: freshDisplacementMaps,
 		};
 
+		// Material-coherence sort gate (experiment): only worthwhile above a few materials.
+		this._sortMaterials = ( ENGINE_DEFAULTS.wavefrontSortMaterials ?? false )
+			&& ( this.materialData?.materialCount ?? 0 ) > 8;
+
 		const extFn = buildExtendKernel( {
 			bvhBuffer: freshBvh,
 			triangleBuffer: freshTri,
@@ -677,6 +706,50 @@ export class PathTracer extends PathTracerStage {
 			)
 		);
 
+		// Material-coherence sort: reorder the entering-ray indices by material between
+		// Extend and Shade. Histogram is workgroup-shared (patches.js §4); Shade reads the output.
+		if ( this._sortMaterials ) {
+
+			const sgHist = qm.getSortGlobalHistogram();
+			const sortBins = Math.min( SORT_GLOBAL_MAX_BINS, this.materialData?.materialCount ?? SORT_GLOBAL_MAX_BINS );
+			this._kernelManager.register( 'resetGlobalHist',
+				buildResetGlobalHistKernel( { sortGlobalHistogram: sgHist, bins: sortBins } )().compute(
+					[ 1, 1, 1 ], [ SORT_GLOBAL_WG_SIZE, 1, 1 ]
+				)
+			);
+			this._kernelManager.register( 'globalHist',
+				buildGlobalHistKernel( {
+					hitBufferRO: pb.hitBuffer.ro,
+					activeIndicesReadRO: qm.getActiveReadRO(),
+					sortGlobalHistogram: sgHist,
+					counters,
+					bins: sortBins,
+				} )().compute(
+					[ Math.ceil( maxRays / SORT_GLOBAL_WG_SIZE ), 1, 1 ],
+					[ SORT_GLOBAL_WG_SIZE, 1, 1 ]
+				)
+			);
+			this._kernelManager.register( 'globalPrefix',
+				buildGlobalPrefixKernel( { sortGlobalHistogram: sgHist, bins: sortBins } )().compute(
+					[ 1, 1, 1 ], [ 1, 1, 1 ]
+				)
+			);
+			this._kernelManager.register( 'globalScatter',
+				buildGlobalScatterKernel( {
+					hitBufferRO: pb.hitBuffer.ro,
+					activeIndicesReadRO: qm.getActiveReadRO(),
+					sortedIndicesRW: qm.getSortedRW(),
+					sortGlobalHistogram: sgHist,
+					counters,
+					bins: sortBins,
+				} )().compute(
+					[ Math.ceil( maxRays / SORT_GLOBAL_WG_SIZE ), 1, 1 ],
+					[ SORT_GLOBAL_WG_SIZE, 1, 1 ]
+				)
+			);
+
+		}
+
 		const shadeFn = buildShadeKernel( {
 			gBufferRW,
 			envCompensationDelta: this.envCompensationDelta,
@@ -689,7 +762,7 @@ export class PathTracer extends PathTracerStage {
 			rngBufferRW: pb.rngBuffer.rw,
 			hitBufferRO: pb.hitBuffer.ro,
 			counters,
-			activeIndicesRO: qm.getActiveReadRO(),
+			activeIndicesRO: this._sortMaterials ? qm.getSortedRO() : qm.getActiveReadRO(),
 			albedoMaps: freshAlbedoMaps,
 			normalMaps: freshNormalMaps,
 			bumpMaps: freshBumpMaps,

package/src/Stages/PathTracerStage.js

@@ -571,11 +571,11 @@ export class PathTracerStage extends RenderStage {
 
 		}
 
-		// Area lights (13 floats per light)
+		// Area lights (16 floats per light — 13 base + normalize/spread/shape)
 		if ( this.areaLightsData && this.areaLightsData.length > 0 ) {
 
 			this.areaLightsBufferNode.array = Array.from( this.areaLightsData );
-			this.numAreaLights.value = Math.floor( this.areaLightsData.length / 13 );
+			this.numAreaLights.value = Math.floor( this.areaLightsData.length / 16 );
 
 		} else {
 

package/src/TSL/LightsCore.js

@@ -42,12 +42,15 @@ export const DirectionalLight = struct( {
 
 export const AreaLight = struct( {
 	position: 'vec3',
-	u: 'vec3', // First axis of the rectangular light
-	v: 'vec3', // Second axis of the rectangular light
+	u: 'vec3', // First axis half-vector of the rectangular light
+	v: 'vec3', // Second axis half-vector of the rectangular light
 	color: 'vec3',
-	intensity: 'float',
-	normal: 'vec3',
-	area: 'float',
+	intensity: 'float', // radiant power (Watts), Blender-style
+	normalize: 'float', // 1 = power normalized over area (radiance ∝ 1/area), 0 = constant radiance
+	spread: 'float', // emission cone half-fan in radians, π = full Lambertian hemisphere
+	shape: 'float', // 0 = rectangle, 1 = disk/ellipse
+	normal: 'vec3', // derived
+	area: 'float', // derived (true world area: rect = w·h, ellipse = π/4·w·h)
 } );
 
 export const PointLight = struct( {
@@ -125,7 +128,7 @@ export const getDirectionalLight = Fn( ( [ directionalLightsBuffer, index ] ) =>
 
 export const getAreaLight = Fn( ( [ areaLightsBuffer, index ] ) => {
 
-	const baseIndex = index.mul( 13 );
+	const baseIndex = index.mul( 16 );
 	const u = vec3(
 		areaLightsBuffer.element( baseIndex.add( 3 ) ),
 		areaLightsBuffer.element( baseIndex.add( 4 ) ),
@@ -138,6 +141,10 @@ export const getAreaLight = Fn( ( [ areaLightsBuffer, index ] ) => {
 	).toVar();
 
 	const crossUV = cross( u, v );
+	const shape = areaLightsBuffer.element( baseIndex.add( 15 ) );
+
+	// u,v are half-vectors → full rectangle area = 4·|u×v|; disk/ellipse = π/4 of that.
+	const rectArea = length( crossUV ).mul( 4.0 );
 
 	return AreaLight( {
 		position: vec3(
@@ -153,8 +160,11 @@ export const getAreaLight = Fn( ( [ areaLightsBuffer, index ] ) => {
 			areaLightsBuffer.element( baseIndex.add( 11 ) ),
 		),
 		intensity: areaLightsBuffer.element( baseIndex.add( 12 ) ),
+		normalize: areaLightsBuffer.element( baseIndex.add( 13 ) ),
+		spread: areaLightsBuffer.element( baseIndex.add( 14 ) ),
+		shape: shape,
 		normal: normalize( crossUV ),
-		area: length( crossUV ).mul( 4.0 ),
+		area: select( shape.greaterThan( 0.5 ), rectArea.mul( 0.7853981633974483 ), rectArea ),
 	} );
 
 } );
@@ -501,12 +511,18 @@ export const intersectAreaLight = Fn( ( [ light, rayOrigin, rayDirection ] ) =>
 			const u_dir = light.u.div( uLen );
 			const v_dir = light.v.div( vLen );
 
-			// Project onto axes
-			const u_proj = dot( localPoint, u_dir );
-			const v_proj = dot( localPoint, v_dir );
+			// Project onto axes, normalized to [-1,1] across the half-extents
+			const u_proj = dot( localPoint, u_dir ).div( uLen );
+			const v_proj = dot( localPoint, v_dir ).div( vLen );
 
-			// Check within rectangle bounds (half-lengths)
-			If( abs( u_proj ).lessThanEqual( uLen ).and( abs( v_proj ).lessThanEqual( vLen ) ), () => {
+			// Rectangle: |u|≤1 ∧ |v|≤1.  Disk/ellipse: u²+v²≤1.
+			const inside = select(
+				light.shape.greaterThan( 0.5 ),
+				u_proj.mul( u_proj ).add( v_proj.mul( v_proj ) ).lessThanEqual( 1.0 ),
+				abs( u_proj ).lessThanEqual( 1.0 ).and( abs( v_proj ).lessThanEqual( 1.0 ) ),
+			);
+
+			If( inside, () => {
 
 				result.assign( t );
 
@@ -520,3 +536,114 @@ export const intersectAreaLight = Fn( ( [ light, rayOrigin, rayDirection ] ) =>
 
 } );
 
+// ================================================================================
+// SPHERICAL RECTANGLE SAMPLING (Ureña et al. 2013, "An Area-Preserving
+// Parametrization for Spherical Rectangles"). Same scheme Cycles uses for rect
+// area lights — samples the light's solid angle directly, giving pdf = 1/S in
+// solid-angle measure (much lower variance than uniform-area sampling for
+// large/near lights). Inputs:
+//   o  = shading point (ray origin)
+//   s  = rectangle corner = center - u - v
+//   ex = full edge vector along u (= 2·u)
+//   ey = full edge vector along v (= 2·v)
+// ================================================================================
+
+// Solid angle S subtended by the rectangle from o (used for the BSDF-hit MIS pdf).
+export const sphQuadSolidAngle = /*@__PURE__*/ wgslFn( `
+	fn sphQuadSolidAngle( o: vec3f, s: vec3f, ex: vec3f, ey: vec3f ) -> f32 {
+		let PI = 3.141592653589793f;
+		let exl = length( ex );
+		let eyl = length( ey );
+		let x = ex / max( exl, 1e-12f );
+		let y = ey / max( eyl, 1e-12f );
+		var z = cross( x, y );
+		let d = s - o;
+		var z0 = dot( d, z );
+		if ( z0 > 0.0f ) { z = -z; z0 = -z0; }
+		let x0 = dot( d, x );
+		let y0 = dot( d, y );
+		let x1 = x0 + exl;
+		let y1 = y0 + eyl;
+		let v00 = vec3f( x0, y0, z0 );
+		let v01 = vec3f( x0, y1, z0 );
+		let v10 = vec3f( x1, y0, z0 );
+		let v11 = vec3f( x1, y1, z0 );
+		let n0 = normalize( cross( v00, v10 ) );
+		let n1 = normalize( cross( v10, v11 ) );
+		let n2 = normalize( cross( v11, v01 ) );
+		let n3 = normalize( cross( v01, v00 ) );
+		let g0 = acos( clamp( -dot( n0, n1 ), -1.0f, 1.0f ) );
+		let g1 = acos( clamp( -dot( n1, n2 ), -1.0f, 1.0f ) );
+		let g2 = acos( clamp( -dot( n2, n3 ), -1.0f, 1.0f ) );
+		let g3 = acos( clamp( -dot( n3, n0 ), -1.0f, 1.0f ) );
+		return g0 + g1 + g2 + g3 - 2.0f * PI;
+	}
+` );
+
+// Sample a direction toward the rectangle uniformly in solid angle.
+// Returns vec4( pointOnRect.xyz, pdf ); pdf = 1/S. pdf <= 0 signals the caller
+// to fall back to uniform-area sampling (degenerate / tiny solid angle).
+export const sampleSphQuad = /*@__PURE__*/ wgslFn( `
+	fn sampleSphQuad( o: vec3f, s: vec3f, ex: vec3f, ey: vec3f, uv: vec2f ) -> vec4f {
+		let PI = 3.141592653589793f;
+		let exl = length( ex );
+		let eyl = length( ey );
+		let x = ex / max( exl, 1e-12f );
+		let y = ey / max( eyl, 1e-12f );
+		var z = cross( x, y );
+		let d = s - o;
+		var z0 = dot( d, z );
+		if ( z0 > 0.0f ) { z = -z; z0 = -z0; }
+		let z0sq = z0 * z0;
+		let x0 = dot( d, x );
+		let y0 = dot( d, y );
+		let x1 = x0 + exl;
+		let y1 = y0 + eyl;
+		let y0sq = y0 * y0;
+		let y1sq = y1 * y1;
+		let v00 = vec3f( x0, y0, z0 );
+		let v01 = vec3f( x0, y1, z0 );
+		let v10 = vec3f( x1, y0, z0 );
+		let v11 = vec3f( x1, y1, z0 );
+		let n0 = normalize( cross( v00, v10 ) );
+		let n1 = normalize( cross( v10, v11 ) );
+		let n2 = normalize( cross( v11, v01 ) );
+		let n3 = normalize( cross( v01, v00 ) );
+		let g0 = acos( clamp( -dot( n0, n1 ), -1.0f, 1.0f ) );
+		let g1 = acos( clamp( -dot( n1, n2 ), -1.0f, 1.0f ) );
+		let g2 = acos( clamp( -dot( n2, n3 ), -1.0f, 1.0f ) );
+		let g3 = acos( clamp( -dot( n3, n0 ), -1.0f, 1.0f ) );
+		let b0 = n0.z;
+		let b1 = n2.z;
+		let b0sq = b0 * b0;
+		let k = 2.0f * PI - g2 - g3;
+		let S = g0 + g1 + g2 + g3 - 2.0f * PI;
+
+		if ( S <= 1e-5f ) {
+			return vec4f( 0.0f, 0.0f, 0.0f, -1.0f );
+		}
+
+		let au = uv.x * S + k;
+		let sinAu = sin( au );
+		let fu = ( cos( au ) * b0 - b1 ) / max( abs( sinAu ), 1e-7f ) * sign( sinAu );
+		var cu = select( -1.0f, 1.0f, fu >= 0.0f ) / sqrt( fu * fu + b0sq );
+		cu = clamp( cu, -1.0f, 1.0f );
+
+		var xu = -( cu * z0 ) / max( sqrt( 1.0f - cu * cu ), 1e-7f );
+		xu = clamp( xu, x0, x1 );
+
+		let dd = sqrt( xu * xu + z0sq );
+		let h0 = y0 / sqrt( dd * dd + y0sq );
+		let h1 = y1 / sqrt( dd * dd + y1sq );
+		let hv = h0 + uv.y * ( h1 - h0 );
+		let hv2 = hv * hv;
+		var yv = y1;
+		if ( hv2 < 1.0f - 1e-6f ) {
+			yv = ( hv * dd ) / sqrt( 1.0f - hv2 );
+		}
+
+		let p = o + xu * x + yv * y + z0 * z;
+		return vec4f( p, 1.0f / S );
+	}
+` );
+