rayzee 7.2.1 → 7.4.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "rayzee",
-  "version": "7.2.1",
+  "version": "7.4.0",
   "type": "module",
   "description": "Real-time WebGPU path tracing engine built on Three.js",
   "main": "dist/rayzee.umd.js",
@@ -34,7 +34,7 @@
     "prepublishOnly": "npm run build"
   },
   "peerDependencies": {
-    "three": ">=0.184.0"
+    "three": ">=0.185.0"
   },
   "optionalDependencies": {
     "oidn-web": ">=0.3.0",

package/src/EngineDefaults.js

@@ -19,10 +19,23 @@ export const ENGINE_DEFAULTS = {
 	useImportanceSampledEnvironment: true,
 	environmentIntensity: 1,
 	backgroundIntensity: 1,
+	// Solid backdrop color shown on camera-ray misses in 'color' background mode
+	// (showBackground=false, transparentBackground=false). Black = legacy hidden-backdrop look.
+	backgroundColor: '#000000',
+	// Backdrop blur (env background only). 0 = sharp/off (no cost). Cone-jitter blur of the
+	// primary-ray env lookup; lighting/reflections stay sharp. Samples = taps/frame (noise vs cost).
+	backgroundBlurriness: 0,
+	backgroundBlurSamples: 8,
 	environmentRotation: 270.0,
 	groundProjectionEnabled: false,
 	groundProjectionRadius: 100,
 	groundProjectionHeight: 15,
+	// World Y of the projected ground plane; auto-seeded to the scene floor (min-Y) on model
+	// load so models that aren't authored at y=0 sit ON the ground instead of sinking into it.
+	groundProjectionLevel: 0,
+	// Analytic ground-plane shadow catcher (primary-ray holdout; no geometry)
+	enableGroundCatcher: false,
+	groundCatcherHeight: 0,
 	globalIlluminationIntensity: 1,
 
 	// Environment Mode System
@@ -58,16 +71,11 @@ export const ENGINE_DEFAULTS = {
 	afScreenPoint: { x: 0.5, y: 0.5 },
 	afSmoothingFactor: 0.15,
 
-	// Multi-sample pool: S=samplesPerPixel rays/pixel/frame, FinalWrite averages them; interactive-only (renderMode 0, ≤ cap), else S=1.
-	// Pixel cap (768²) bounds pool memory; covers the 512² default, excludes ≥768².
-	wavefrontMultiSampleMaxPixels: 589824,
-
 	enablePathTracer: true,
 	enableAccumulation: true,
 	pauseRendering: false,
 	maxSamples: 60,
 	bounces: 3,
-	samplesPerPixel: 1,
 	transmissiveBounces: 5,
 	maxSubsurfaceSteps: 8, // interactive default: low cap (bounded random-walk SSS)
 	samplingTechnique: 3,
@@ -481,7 +489,7 @@ export const DEFAULT_TEXTURE_MATRIX = [ 0, 0, 1, 1, 0, 0, 0, 1 ];
 // 'interactive' — low-sample, bounded bounces, no offline denoising, controls enabled.
 // 'production'  — high-sample, deep bounces, OIDN enabled, controls disabled.
 export const PRODUCTION_RENDER_CONFIG = {
-	maxSamples: 30, bounces: 20, transmissiveBounces: 8, maxSubsurfaceSteps: 64, samplesPerPixel: 1,
+	maxSamples: 30, bounces: 20, transmissiveBounces: 8, maxSubsurfaceSteps: 64,
 	renderMode: 1, enableAlphaShadows: true,
 	enableOIDN: true, oidnQuality: 'balance',
 	interactionModeEnabled: false,
@@ -489,7 +497,7 @@ export const PRODUCTION_RENDER_CONFIG = {
 
 export const INTERACTIVE_RENDER_CONFIG = {
 	maxSamples: ENGINE_DEFAULTS.maxSamples, bounces: ENGINE_DEFAULTS.bounces,
-	samplesPerPixel: ENGINE_DEFAULTS.samplesPerPixel, renderMode: ENGINE_DEFAULTS.renderMode, enableAlphaShadows: ENGINE_DEFAULTS.enableAlphaShadows,
+	renderMode: ENGINE_DEFAULTS.renderMode, enableAlphaShadows: ENGINE_DEFAULTS.enableAlphaShadows,
 	transmissiveBounces: ENGINE_DEFAULTS.transmissiveBounces,
 	maxSubsurfaceSteps: ENGINE_DEFAULTS.maxSubsurfaceSteps,
 	enableOIDN: false, oidnQuality: 'fast',

package/src/PathTracerApp.js

@@ -1,7 +1,7 @@
 import { WebGPURenderer, RectAreaLightNode, SRGBColorSpace } from 'three/webgpu';
 import { texture as _tslTexture, cubeTexture as _tslCubeTexture } from 'three/tsl';
 import {
-	ACESFilmicToneMapping, Scene, EventDispatcher
+	ACESFilmicToneMapping, Scene, EventDispatcher, Box3
 } from 'three';
 import { RectAreaLightTexturesLib } from 'three/addons/lights/RectAreaLightTexturesLib.js';
 import { SceneHelpers } from './SceneHelpers.js';
@@ -777,6 +777,12 @@ export class PathTracerApp extends EventDispatcher {
 
 		}
 
+		// Seed the ground-projection plane AND the shadow-catcher plane to the scene floor so models
+		// that aren't authored at y=0 sit on the ground (not sunk) — auto-updates on every model change.
+		const sceneMinY = this.getSceneMinY();
+		this.settings.set( 'groundProjectionLevel', sceneMinY, { reset: false } );
+		this.settings.set( 'groundCatcherHeight', sceneMinY, { reset: false } );
+
 		// Apply all settings to stages in one shot
 		timer.start( 'Apply settings' );
 		this.settings.applyAll();
@@ -953,7 +959,6 @@ export class PathTracerApp extends EventDispatcher {
 		this.settings.setMany( {
 			maxSamples: config.maxSamples,
 			maxBounces: config.bounces,
-			samplesPerPixel: config.samplesPerPixel,
 			transmissiveBounces: config.transmissiveBounces,
 			maxSubsurfaceSteps: config.maxSubsurfaceSteps,
 		}, { silent: true } );
@@ -972,6 +977,10 @@ export class PathTracerApp extends EventDispatcher {
 
 		}
 
+		// OIDN toggled directly above (bypassing setOIDNEnabled) — re-sync so the wavefront produces the
+		// aux MRT when OIDN is on and skips it otherwise. Runs before the reset below so kernels rebuild once.
+		this.denoisingManager?._syncGBufferStages?.();
+
 		this.denoisingManager?.upscaler?.abort();
 
 		if ( options.canvasWidth && options.canvasHeight ) {
@@ -1178,6 +1187,19 @@ export class PathTracerApp extends EventDispatcher {
 	 * @param {string} property
 	 * @param {*} value
 	 */
+	/**
+	 * World-space minimum Y of the loaded scene (the floor). Used to seed the
+	 * analytic ground-plane shadow catcher height. Returns 0 if no scene is loaded.
+	 * @returns {number}
+	 */
+	getSceneMinY() {
+
+		if ( ! this.meshScene ) return 0;
+		const box = new Box3().setFromObject( this.meshScene );
+		return Number.isFinite( box.min.y ) ? box.min.y : 0;
+
+	}
+
 	setMaterialProperty( materialIndex, property, value ) {
 
 		this.stages.pathTracer?.materialData.updateMaterialProperty( materialIndex, property, value );

package/src/Processor/CameraOptimizer.js

@@ -24,7 +24,6 @@ export class CameraOptimizer {
 		// Enhanced interaction mode settings for reduced quality during interaction
 		this.interactionQualitySettings = {
 			maxBounceCount: 1,
-			numRaysPerPixel: 1,
 			useEnvMapIS: false,
 			// pixelRatio: 0.25,
 			enableAccumulation: false,
@@ -304,28 +303,24 @@ export class CameraOptimizer {
 		const presets = {
 			'ultra-low': {
 				maxBounceCount: 1,
-				numRaysPerPixel: 1,
 				useEnvMapIS: false,
 				pixelRatio: 0.125,
 				enableAccumulation: false
 			},
 			'low': {
 				maxBounceCount: 1,
-				numRaysPerPixel: 1,
 				useEnvMapIS: false,
 				pixelRatio: 0.25,
 				enableAccumulation: false
 			},
 			'medium': {
 				maxBounceCount: 2,
-				numRaysPerPixel: 1,
 				useEnvMapIS: true,
 				pixelRatio: 0.5,
 				enableAccumulation: false
 			},
 			'high': {
 				maxBounceCount: 3,
-				numRaysPerPixel: 1,
 				useEnvMapIS: true,
 				pixelRatio: 0.75,
 				enableAccumulation: true

package/src/Processor/EmissiveTriangleBuilder.js

@@ -443,8 +443,9 @@ export class EmissiveTriangleBuilder {
 		// If not emissive before and not now, nothing to do
 		if ( ! isNowEmissive ) return false;
 
-		// Fast path: just update power + CDF for affected entries
-		const avgEmissive = ( emissive.r + emissive.g + emissive.b ) / 3.0;
+		// Fast path: just update power + CDF for affected entries.
+		// Rec.709 luma — must match the build path + shader MIS weighting.
+		const luma = 0.2126 * emissive.r + 0.7152 * emissive.g + 0.0722 * emissive.b;
 
 		this.totalEmissivePower = 0;
 		for ( let i = 0; i < this.emissiveCount; i ++ ) {
@@ -452,7 +453,7 @@ export class EmissiveTriangleBuilder {
 			const tri = this.emissiveTriangles[ i ];
 			if ( tri.materialIndex === materialIndex ) {
 
-				tri.power = avgEmissive * emissiveIntensity * tri.area;
+				tri.power = luma * emissiveIntensity * tri.area;
 				tri.emissive = { r: emissive.r, g: emissive.g, b: emissive.b };
 				tri.emissiveIntensity = emissiveIntensity;
 				this.emissivePowerArray[ i ] = tri.power;

package/src/Processor/PackedRayBuffer.js

@@ -20,7 +20,7 @@ export const HIT_STRIDE = 2;
 export const GBUFFER_STRIDE = 2;
 
 export const RAY = {
-	ORIGIN_META: 0, // vec4(origin.xyz, uintBitsToFloat(perRayBounces | sssSteps<<8)); pixelIndex+sampleIndex derived from rayID
+	ORIGIN_META: 0, // vec4(origin.xyz, uintBitsToFloat(perRayBounces | sssSteps<<8)); pixelIndex == rayID
 	DIR_FLAGS: 1, // vec4(direction.xyz, uintBitsToFloat(bounceFlags))
 	THROUGHPUT_PDF: 2, // vec4(throughput.xyz, pdf)
 	RADIANCE_ALPHA: 3, // vec4(radiance.xyz, alpha)
@@ -195,8 +195,8 @@ export const gbDecodeNormalDepth = ( packed ) => {
 export const gbDecodeAlbedo = ( packed ) =>
 	vec3( unpackUnorm2x16( packed.z ), unpackUnorm2x16( packed.w ).x );
 
-// .w packs per-ray bounce state: perRayBounces (bits 0-7) | sssSteps (bits 8-15). pixelIndex +
-// sampleIndex are NOT stored — derived from rayID (= subSample*w*h + pixelIndex) in-kernel.
+// .w packs per-ray bounce state: perRayBounces (bits 0-7) | sssSteps (bits 8-15). pixelIndex is
+// NOT stored — it equals rayID (one ray per pixel).
 export const writeRayOriginMeta = ( buf, id, origin, bounces, sssSteps ) =>
 	buf.element( soa( id, RAY.ORIGIN_META ) )
 		.assign( vec4( origin, uintBitsToFloat(
@@ -273,7 +273,6 @@ export const writeMediumSigmaA = ( buf, id, sigmaA ) =>
 // Per-ray bounce state packed into ORIGIN_META.w (written by writeRayOriginMeta alongside the origin):
 //   perRayBounces = bits 0-7 (camera-bounce depth; the loop index can't track it once free bounces decouple it)
 //   sssSteps      = bits 8-15 (SSS random-walk step counter)
-// sampleIndex (the multi-sample sub-sample 0..S-1) is derived in-kernel from rayID, not stored.
 export const readPathBounces = ( buf, id ) =>
 	int( floatBitsToUint( buf.element( soa( id, RAY.ORIGIN_META ) ).w ).bitAnd( 0xFF ) );
 export const readSssSteps = ( buf, id ) =>

package/src/Processor/QueueManager.js

@@ -25,6 +25,7 @@ export const RAY_FLAG = {
 	// bits 16-31: spare per-ray state carried across bounces
 	HAS_HIT_OPAQUE: 1 << 16, // bit 16: ray chain has hit non-transmissive geometry (transparent-bg alpha; megakernel hasHitOpaqueSurface)
 	AUX_LOCKED: 1 << 17, // bit 17: OIDN aux (normal/albedo) locked onto first non-specular hit (megakernel auxLocked)
+	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.
 };
 
 export class QueueManager {

package/src/RenderSettings.js

@@ -1,4 +1,4 @@
-import { EventDispatcher } from 'three';
+import { EventDispatcher, Color } from 'three';
 import { ENGINE_DEFAULTS } from './EngineDefaults.js';
 import { EngineEvents } from './EngineEvents.js';
 
@@ -16,16 +16,20 @@ const SETTING_ROUTES = {
 	// ── Simple PathTracer uniforms ──────────────────────────
 
 	maxBounces: { uniform: 'maxBounces', reset: true },
-	samplesPerPixel: { uniform: 'samplesPerPixel', reset: true },
 	transmissiveBounces: { uniform: 'transmissiveBounces', reset: true },
 	maxSubsurfaceSteps: { uniform: 'maxSubsurfaceSteps', reset: true },
 	environmentIntensity: { uniform: 'environmentIntensity', reset: true },
 	backgroundIntensity: { uniform: 'backgroundIntensity', reset: true },
+	backgroundBlurriness: { uniform: 'backgroundBlurriness', reset: true },
+	backgroundBlurSamples: { uniform: 'backgroundBlurSamples', reset: true },
 	showBackground: { uniform: 'showBackground', reset: true },
 	enableEnvironment: { uniform: 'enableEnvironment', reset: true },
 	groundProjectionEnabled: { uniform: 'groundProjectionEnabled', reset: true },
 	groundProjectionRadius: { uniform: 'groundProjectionRadius', reset: true },
 	groundProjectionHeight: { uniform: 'groundProjectionHeight', reset: true },
+	groundProjectionLevel: { uniform: 'groundProjectionLevel', reset: true },
+	enableGroundCatcher: { uniform: 'enableGroundCatcher', reset: true },
+	groundCatcherHeight: { uniform: 'groundCatcherHeight', reset: true },
 	globalIlluminationIntensity: { uniform: 'globalIlluminationIntensity', reset: true },
 	enableDOF: { uniform: 'enableDOF', reset: true },
 	focusDistance: { uniform: 'focusDistance', reset: false },
@@ -46,6 +50,7 @@ const SETTING_ROUTES = {
 	interactionModeEnabled: { handler: 'handleInteractionModeEnabled', reset: false },
 	maxSamples: { handler: 'handleMaxSamples', reset: false },
 	transparentBackground: { handler: 'handleTransparentBackground' },
+	backgroundColor: { handler: 'handleBackgroundColor', reset: true },
 	exposure: { handler: 'handleExposure' },
 	saturation: { handler: 'handleSaturation' },
 	renderLimitMode: { handler: 'handleRenderLimitMode' },
@@ -133,6 +138,15 @@ export class RenderSettings extends EventDispatcher {
 
 			},
 
+			handleBackgroundColor: ( value ) => {
+
+				// Accept a hex string ('#rrggbb') or a Color; THREE.Color converts sRGB → linear working
+				// space, which is what the shader adds to radiance.
+				const c = value?.isColor ? value : new Color( value );
+				stages.pathTracer?.setUniform( 'backgroundColor', c );
+
+			},
+
 			handleExposure: ( value ) => {
 
 				// Three.js applies toneMappingExposure inside the tone-mapping branch,

package/src/Stages/PathTracer.js

@@ -17,7 +17,6 @@ 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 { ENGINE_DEFAULTS } from '../EngineDefaults.js';
 import {
 	Fn, uint, atomicStore, atomicLoad, instanceIndex, If, Return,
 } from 'three/tsl';
@@ -35,16 +34,18 @@ export class PathTracer extends PathTracerStage {
 		this._gBufferAttr = null; // per-pixel first-hit MRT (ND + albedo); see _buildWavefrontKernels
 		this._wavefrontReady = false;
 
+		// Aux MRT (normalDepth + albedo) feeds only the denoiser/OIDN. When no denoiser is active the
+		// wavefront skips those writes (Generate/Shade G-buffer + FinalWrite stores). Gated by a live
+		// uniform — NOT baked — so DenoisingManager can toggle it without a (UI-freezing) kernel rebuild.
+		this._auxGBufferEnabled = false;
+		this._auxGBufferUniform = uniform( 0, 'uint' );
+
 		// 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;
 
 		// Flag-gated off: perf-neutral vs atomic-append and adds a 'subgroups' feature dependency.
 		this._useSubgroupCompact = false;
 
-		// Multi-sample pool: S=samplesPerPixel primary rays/pixel/frame (interactive-only, ≤ the pixel cap; else S=1). FinalWrite averages the S slots. Baked into kernels; _ensureSamplesPerPass() rebuilds on change.
-		this._multiSampleMaxPixels = ENGINE_DEFAULTS.wavefrontMultiSampleMaxPixels ?? 589824; // 768²
-		this._samplesPerPass = 1;
-
 		this._lastBounceCounts = null;
 		// maxBounces the curve was measured at; the curve is ignored once this no longer matches (-1 = none).
 		this._lastBounceCountsBudget = - 1;
@@ -164,19 +165,15 @@ export class PathTracer extends PathTracerStage {
 		const renderMode = this.renderMode.value;
 
 		let originalMaxBounces = null;
-		let originalSamplesPerPixel = null;
 
 		if ( renderMode === 1 && frameValue === 0 ) {
 
 			originalMaxBounces = this.maxBounces.value;
-			originalSamplesPerPixel = this.samplesPerPixel.value;
 			this.maxBounces.value = 1;
-			this.samplesPerPixel.value = 1;
 
 		}
 
 		this._handleResize();
-		this._ensureSamplesPerPass();
 		this.manageASVGFForRenderMode( renderMode );
 
 		// Full-frame render is always a complete cycle (PER_CYCLE stages gate on this).
@@ -218,7 +215,6 @@ export class PathTracer extends PathTracerStage {
 			if ( ! this.cameraOptimizer?.isInInteractionMode() ) this.frameCount ++;
 
 			if ( originalMaxBounces !== null ) this.maxBounces.value = originalMaxBounces;
-			if ( originalSamplesPerPixel !== null ) this.samplesPerPixel.value = originalSamplesPerPixel;
 
 			this.performanceMonitor?.end();
 			return;
@@ -336,7 +332,6 @@ export class PathTracer extends PathTracerStage {
 		if ( ! this.cameraOptimizer?.isInInteractionMode() ) this.frameCount ++;
 
 		if ( originalMaxBounces !== null ) this.maxBounces.value = originalMaxBounces;
-		if ( originalSamplesPerPixel !== null ) this.samplesPerPixel.value = originalSamplesPerPixel;
 
 		this.performanceMonitor?.end();
 
@@ -354,27 +349,16 @@ export class PathTracer extends PathTracerStage {
 
 	}
 
-	// S=samplesPerPixel for interactive within the pixel cap; production/tiled and high-res get S=1.
-	_resolveSamplesPerPass( w, h ) {
+	// Aux MRT (normalDepth/albedo) is needed only by the denoiser/OIDN; DenoisingManager calls this to
+	// turn the wavefront's aux writes on/off. It's a live uniform, so toggling is just a value flip +
+	// accumulation reset — no kernel rebuild, no UI freeze.
+	setAuxGBufferEnabled( enabled ) {
 
-		const interactive = this.renderMode.value === 0;
-		const within = ( w * h ) <= this._multiSampleMaxPixels;
-		return ( interactive && within ) ? Math.max( 1, this.samplesPerPixel.value | 0 ) : 1;
-
-	}
-
-	// S is baked at build but samplesPerPixel/mode can change without a resize; rebuild when the implied S differs.
-	_ensureSamplesPerPass() {
-
-		if ( ! this._wavefrontReady ) return;
-		const w = this.storageTextures.renderWidth;
-		const h = this.storageTextures.renderHeight;
-		if ( this._resolveSamplesPerPass( w, h ) !== this._samplesPerPass ) {
-
-			this._wavefrontReady = false;
-			this._buildWavefrontKernels();
-
-		}
+		enabled = !! enabled;
+		if ( this._auxGBufferEnabled === enabled ) return;
+		this._auxGBufferEnabled = enabled;
+		this._auxGBufferUniform.value = enabled ? 1 : 0;
+		this.reset();
 
 	}
 
@@ -464,12 +448,10 @@ export class PathTracer extends PathTracerStage {
 		this._readbackFrameCounter = 0;
 		this._readbackGeneration ++;
 
-		// Recompile only when buffers reallocate (capacity grows) or S changes; otherwise resize uniforms in place.
-		const newS = this._resolveSamplesPerPass( newW, newH );
-		const neededCap = PackedRayBuffer.requiredCapacity( newW * newH * newS );
+		// Recompile only when buffers reallocate (capacity grows); otherwise resize uniforms in place.
+		const neededCap = PackedRayBuffer.requiredCapacity( newW * newH );
 		const mustRebuild = ! this._packedBuffers
-			|| neededCap > this._packedBuffers.capacity
-			|| newS !== this._samplesPerPass;
+			|| neededCap > this._packedBuffers.capacity;
 
 		if ( mustRebuild ) {
 
@@ -485,10 +467,10 @@ export class PathTracer extends PathTracerStage {
 
 	}
 
-	// Same-capacity, same-S resize: update render-size uniforms + early-exit threshold, no recompile.
+	// Same-capacity resize: update render-size uniforms + early-exit threshold, no recompile.
 	_resizeWavefrontInPlace( w, h ) {
 
-		const maxRays = w * h * this._samplesPerPass;
+		const maxRays = w * h;
 		this._wfRenderWidth.value = w;
 		this._wfRenderHeight.value = h;
 		this._wfMaxRayCount.value = maxRays;
@@ -509,11 +491,7 @@ export class PathTracer extends PathTracerStage {
 
 		const w = this.storageTextures.renderWidth;
 		const h = this.storageTextures.renderHeight;
-		// maxRays = pool capacity (pixels × S); all downstream sizing scales off it, so S propagates for free.
-		this._samplesPerPass = this._resolveSamplesPerPass( w, h );
-		const S = this._samplesPerPass | 0;
-		const maxRaysPerSample = w * h;
-		const maxRays = maxRaysPerSample * S;
+		const maxRays = w * h;
 
 		if ( this._bounceEarlyExitThreshold !== - 1 ) {
 
@@ -534,9 +512,9 @@ export class PathTracer extends PathTracerStage {
 		// Per-pixel G-buffer (first-hit MRT: ND + albedo), 1 uvec4/pixel — half-precision packed (pack2x16).
 		// uint (not f32) buffer: packed lanes can hit the NaN exponent range (e.g. snorm 1.0 → 0x7FFF), which a
 		// GPU may canonicalize through f32 storage; u32 stores the bits verbatim. Separate from RAY — it's
-		// per-pixel (not per-ray×S), written by Generate/Shade bounce-0 and read only by FinalWrite.
+		// per-pixel, written by Generate/Shade bounce-0 and read only by FinalWrite.
 		// 1.25× margin (same as the per-ray buffers) so it survives the in-place-resize range.
-		const gBufferVec4s = PackedRayBuffer.requiredCapacity( maxRaysPerSample ) * GBUFFER_STRIDE;
+		const gBufferVec4s = PackedRayBuffer.requiredCapacity( maxRays ) * GBUFFER_STRIDE;
 		this._gBufferAttr = new StorageInstancedBufferAttribute( new Uint32Array( gBufferVec4s * 4 ), 4 );
 		const gBufferRW = storage( this._gBufferAttr, 'uvec4' );
 		const gBufferRO = storage( this._gBufferAttr, 'uvec4' ).toReadOnly();
@@ -639,14 +617,13 @@ export class PathTracer extends PathTracerStage {
 			anamorphicRatio: this.anamorphicRatio,
 			renderWidth: this._wfRenderWidth,
 			renderHeight: this._wfRenderHeight,
-			samplesPerPass: S,
 			transmissiveBounces: this.transmissiveBounces,
 			transparentBackground: this.transparentBackground,
+			auxGBufferEnabled: this._auxGBufferUniform,
 		} );
 		this._kernelManager.register( 'generate',
 			genFn().compute(
-				// Multi-sample: dispatch covers h·S rows (each sub-sample is a row band).
-				[ Math.ceil( w / GENERATE_WG_SIZE ), Math.ceil( ( h * S ) / GENERATE_WG_SIZE ), 1 ],
+				[ Math.ceil( w / GENERATE_WG_SIZE ), Math.ceil( h / GENERATE_WG_SIZE ), 1 ],
 				[ GENERATE_WG_SIZE, GENERATE_WG_SIZE, 1 ]
 			)
 		);
@@ -726,6 +703,9 @@ export class PathTracer extends PathTracerStage {
 			groundProjectionEnabled: this.groundProjectionEnabled,
 			groundProjectionRadius: this.groundProjectionRadius,
 			groundProjectionHeight: this.groundProjectionHeight,
+			groundProjectionLevel: this.groundProjectionLevel,
+			enableGroundCatcher: this.enableGroundCatcher,
+			groundCatcherHeight: this.groundCatcherHeight,
 			envTotalSum: this.envTotalSum,
 			envResolution: this.envResolution,
 			directionalLightsBuffer: this.directionalLightsBufferNode,
@@ -740,6 +720,9 @@ export class PathTracer extends PathTracerStage {
 			maxSubsurfaceSteps: this.maxSubsurfaceSteps,
 			transparentBackground: this.transparentBackground,
 			backgroundIntensity: this.backgroundIntensity,
+			backgroundColor: this.backgroundColor,
+			backgroundBlurriness: this.backgroundBlurriness,
+			backgroundBlurSamples: this.backgroundBlurSamples,
 			showBackground: this.showBackground,
 			globalIlluminationIntensity: this.globalIlluminationIntensity,
 			cameraProjectionMatrix: this.cameraProjectionMatrix,
@@ -757,6 +740,7 @@ export class PathTracer extends PathTracerStage {
 			reverseMapVec4Offset: this.reverseMapVec4Offset,
 			currentBounce: this._wfCurrentBounce,
 			maxRayCount: this._wfMaxRayCount,
+			auxGBufferEnabled: this._auxGBufferUniform,
 		} );
 		this._kernelManager.register( 'shade',
 			shadeFn().compute(
@@ -830,8 +814,8 @@ export class PathTracer extends PathTracerStage {
 			prevAlbedoTexture: prevAlbedo,
 			renderWidth: this._wfRenderWidth,
 			renderHeight: this._wfRenderHeight,
-			samplesPerPass: S,
 			visMode: this.visMode,
+			auxGBufferEnabled: this._auxGBufferUniform,
 		} );
 		this._kernelManager.register( 'finalWrite',
 			// Per-pixel (w×h) — kernel averages the S sample-slots internally.
@@ -870,7 +854,6 @@ export class PathTracer extends PathTracerStage {
 			enableEnvironmentLight: this.enableEnvironment,
 			visMode: this.visMode,
 			debugVisScale: this.debugVisScale,
-			samplesPerPass: this._samplesPerPass,
 			albedoMaps: freshAlbedoMaps,
 			normalMaps: freshNormalMaps,
 			bumpMaps: freshBumpMaps,
@@ -895,11 +878,10 @@ export class PathTracer extends PathTracerStage {
 
 		const w = this._wfRenderWidth.value;
 		const h = this._wfRenderHeight.value;
-		const S = this._samplesPerPass | 0;
 
 		this._kernelManager.setDispatchCount( 'generate', [
 			Math.ceil( w / GENERATE_WG_SIZE ),
-			Math.ceil( ( h * S ) / GENERATE_WG_SIZE ), 1
+			Math.ceil( h / GENERATE_WG_SIZE ), 1
 		] );
 		this._kernelManager.setDispatchCount( 'finalWrite', [
 			Math.ceil( w / FINALWRITE_WG_SIZE ),

package/src/Stages/PathTracerStage.js

@@ -279,18 +279,6 @@ export class PathTracerStage extends RenderStage {
 
 					}
 				},
-				numRaysPerPixel: {
-					get value() {
-
-						return self.samplesPerPixel.value;
-
-					},
-					set value( v ) {
-
-						self.samplesPerPixel.value = v;
-
-					}
-				},
 				useEnvMapIS: {
 					get value() {
 
@@ -346,7 +334,6 @@ export class PathTracerStage extends RenderStage {
 			enabled: DEFAULT_STATE.interactionModeEnabled,
 			qualitySettings: {
 				maxBounceCount: 1,
-				numRaysPerPixel: 1,
 				useEnvMapIS: false,
 				enableAccumulation: false,
 				enableEmissiveTriangleSampling: false,

package/src/TSL/Common.js

@@ -400,6 +400,68 @@ export const getMaterial = Fn( ( [ materialIndex, materialBuffer ] ) => {
 
 } );
 
+// Synthetic diffuse-white material for the analytic ground-plane shadow catcher.
+// No geometry/material buffer is involved — the plane is shaded as a matte Lambertian
+// so the direct-lighting estimator yields an irradiance-weighted shadow ratio (the
+// diffuse BRDF is constant and cancels in shadowed/unoccluded). All fields are set to
+// inert defaults; only color/roughness/metalness/transmission affect the lighting path.
+export const diffuseGroundMaterial = Fn( () => {
+
+	const idn = mat3( 1, 0, 0, 0, 1, 0, 0, 0, 1 );
+	return RayTracingMaterial( {
+		color: vec4( 1.0, 1.0, 1.0, 1.0 ),
+		emissive: vec3( 0.0 ),
+		emissiveIntensity: float( 0.0 ),
+		roughness: float( 1.0 ),
+		metalness: float( 0.0 ),
+		ior: float( 1.5 ),
+		transmission: float( 0.0 ),
+		thickness: float( 0.0 ),
+		clearcoat: float( 0.0 ),
+		clearcoatRoughness: float( 0.0 ),
+		opacity: float( 1.0 ),
+		transparent: float( 0.0 ),
+		attenuationColor: vec3( 1.0 ),
+		attenuationDistance: float( 0.0 ),
+		dispersion: float( 0.0 ),
+		sheen: float( 0.0 ),
+		sheenRoughness: float( 1.0 ),
+		sheenColor: vec3( 0.0 ),
+		specularIntensity: float( 1.0 ),
+		specularColor: vec3( 1.0 ),
+		alphaTest: float( 0.0 ),
+		alphaMode: int( 0 ),
+		side: int( 0 ),
+		depthWrite: int( 1 ),
+		albedoMapIndex: int( - 1 ),
+		emissiveMapIndex: int( - 1 ),
+		normalMapIndex: int( - 1 ),
+		bumpMapIndex: int( - 1 ),
+		bumpScale: float( 1.0 ),
+		displacementScale: float( 0.0 ),
+		metalnessMapIndex: int( - 1 ),
+		roughnessMapIndex: int( - 1 ),
+		displacementMapIndex: int( - 1 ),
+		normalScale: vec2( 1.0, 1.0 ),
+		albedoTransform: idn,
+		emissiveTransform: idn,
+		normalTransform: idn,
+		bumpTransform: idn,
+		metalnessTransform: idn,
+		roughnessTransform: idn,
+		displacementTransform: idn,
+		iridescence: float( 0.0 ),
+		iridescenceIOR: float( 1.3 ),
+		iridescenceThicknessRange: vec2( 100.0, 400.0 ),
+		subsurface: float( 0.0 ),
+		subsurfaceColor: vec3( 1.0 ),
+		subsurfaceRadius: vec3( 1.0, 0.2, 0.1 ),
+		subsurfaceRadiusScale: float( 1.0 ),
+		subsurfaceAnisotropy: float( 0.0 ),
+	} );
+
+} );
+
 // ── Shadow material thin reader (7 slot reads instead of 27) ─────────────
 // Only fetches fields needed by traceShadowRay: alpha, transmission, attenuation, albedo transform.
 

package/src/TSL/DebugKernel.js

@@ -32,7 +32,6 @@ export function buildDebugKernel( params ) {
 		visMode, debugVisScale,
 		albedoMaps, normalMaps, bumpMaps, metalnessMaps, roughnessMaps, emissiveMaps,
 		frame,
-		samplesPerPass = 1,
 	} = params;
 
 	const computeFn = Fn( () => {
@@ -61,8 +60,8 @@ export function buildDebugKernel( params ) {
 			// Mode 9: visualize the stratified AA-jitter pattern (R,G = jitter).
 			If( visMode.equal( int( 9 ) ), () => {
 
-				// Use the real per-frame sample count so >1 SPP shows the stratified lattice (totalRays≤1 → plain random).
-				const jitter = getStratifiedSample( pixelCoord, int( 0 ), int( samplesPerPass ), seed, resolution, frame );
+				// One ray per pixel — plain per-frame jitter (totalRays = 1 → random, no stratified lattice).
+				const jitter = getStratifiedSample( pixelCoord, int( 0 ), int( 1 ), seed, resolution, frame );
 				color.assign( vec4( jitter, 1.0, 1.0 ) );
 
 			} ).Else( () => {

package/src/TSL/Environment.js

@@ -1,4 +1,4 @@
-import { Fn, wgslFn, vec2, vec4, ivec2, float, int, If, texture, dot, sin, sqrt, floor, fract, min, max, mix, clamp } from 'three/tsl';
+import { Fn, wgslFn, vec2, vec3, vec4, ivec2, float, int, If, texture, dot, sin, sqrt, floor, fract, min, max, mix, clamp } from 'three/tsl';
 
 import { REC709_LUMINANCE_COEFFICIENTS } from './Common.js';
 
@@ -211,3 +211,24 @@ export const getGroundProjectedDirection = Fn( ( [ rayOrigin, rayDirection, radi
 	return projected;
 
 } );
+
+// Primary-ray environment lookup direction: bends onto the ground-projection sphere/disk when
+// ground projection is enabled, else returns the ray direction unchanged. Shared by the background
+// miss branch AND the shadow catcher so they can never disagree on the projection (the source of a
+// past horizon-seam bug when only one path bent the direction).
+export const groundProjectedEnvDir = Fn( ( [ rayOrigin, rayDirection, enabled, radius, height, level ] ) => {
+
+	const dir = rayDirection.toVar();
+	If( enabled, () => {
+
+		// Relocate the projected ground plane from y=0 to world y=level (the scene floor) so a model
+		// authored off the origin still sits ON the ground instead of sinking. Shifting the projection
+		// origin down by `level` puts the disk at y=level and the sphere at y=level+height; the internal
+		// horizontal radius test stays correct because the shifted disk point lands at y'=0.
+		const shiftedOrigin = vec3( rayOrigin.x, rayOrigin.y.sub( level ), rayOrigin.z );
+		dir.assign( getGroundProjectedDirection( shiftedOrigin, rayDirection, radius, height ) );
+
+	} );
+	return dir;
+
+} );