rayzee 7.3.0 → 7.4.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "rayzee",
-  "version": "7.3.0",
+  "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,6 +19,13 @@ 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,
@@ -64,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,
@@ -487,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,
@@ -495,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

@@ -959,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 } );
@@ -978,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 ) {

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,11 +16,12 @@ 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 },
@@ -49,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' },
@@ -136,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 ]
 			)
 		);
@@ -743,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,
@@ -760,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(
@@ -833,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.
@@ -873,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,
@@ -898,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/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/FinalWriteKernel.js

@@ -34,12 +34,13 @@ export function buildFinalWriteKernel( params ) {
 		transparentBackground,
 		prevAccumTexture, prevNormalDepthTexture, prevAlbedoTexture,
 		renderWidth, renderHeight,
-		// Multi-sample: average S sample-slots per pixel (slot = pixel + k*w*h, w*h from the resolution uniform).
-		samplesPerPass = 1,
 		visMode,
+		// Aux MRT (normalDepth + albedo) feeds only the denoiser/OIDN. Gated by a live uniform (1 = denoiser
+		// on): when off, skip the G-buffer decode, the prev-frame aux mix, and the two aux stores.
+		auxGBufferEnabled,
 	} = params;
 
-	const S = samplesPerPass | 0;
+	const auxOn = auxGBufferEnabled.greaterThan( uint( 0 ) );
 
 	const computeFn = Fn( () => {
 
@@ -51,31 +52,21 @@ export function buildFinalWriteKernel( params ) {
 			const pixelIndex = gy.mul( int( resolution.x ) ).add( gx );
 			const rayID = uint( pixelIndex );
 
-			// Average the S sub-samples; MRT (normal/depth/albedo) from sub-sample 0.
-			const sampleColor = ( () => {
-
-				if ( S <= 1 ) return readRayRadiance( rayBufferRO, rayID );
-				const acc = readRayRadiance( rayBufferRO, rayID ).toVar();
-				const mrps = uint( resolution.x ).mul( uint( resolution.y ) ).toVar(); // w*h from the resolution uniform, not baked
-				for ( let k = 1; k < S; k ++ ) {
-
-					acc.addAssign( readRayRadiance( rayBufferRO, rayID.add( uint( k ).mul( mrps ) ) ) );
-
-				}
+			const sampleColor = readRayRadiance( rayBufferRO, rayID );
+			const finalColor = sampleColor.xyz.toVar();
+			const outputAlpha = select( transparentBackground, sampleColor.w, float( 1.0 ) ).toVar();
 
-				acc.assign( acc.div( float( S ) ) );
-				return acc;
+			// MRT comes from the per-pixel G-buffer (rayID == pixelIndex). Half-packed: decode.
+			// auxOn gates the decode + stores so a no-denoiser frame does no G-buffer read and no aux writes.
+			const finalNormalDepth = vec4( 0.0 ).toVar();
+			const finalAlbedo = vec4( 0.0 ).xyz.toVar();
+			If( auxOn, () => {
 
-			} )();
-			// MRT comes from the per-pixel G-buffer (rayID == pixelIndex here, i.e. sub-sample 0). Half-packed: decode.
-			const gbuf = readGBuffer( gBufferRO, rayID );
-			const normalDepth = gbDecodeNormalDepth( gbuf );
-			const albedoID = vec4( gbDecodeAlbedo( gbuf ), 0.0 );
+				const gbuf = readGBuffer( gBufferRO, rayID );
+				finalNormalDepth.assign( gbDecodeNormalDepth( gbuf ) );
+				finalAlbedo.assign( vec4( gbDecodeAlbedo( gbuf ), 0.0 ).xyz );
 
-			const finalColor = sampleColor.xyz.toVar();
-			const finalNormalDepth = normalDepth.toVar();
-			const finalAlbedo = albedoID.xyz.toVar();
-			const outputAlpha = select( transparentBackground, sampleColor.w, float( 1.0 ) ).toVar();
+			} );
 
 			const pixelCoord = vec2( float( gx ).add( 0.5 ), float( gy ).add( 0.5 ) );
 			const prevUV = pixelCoord.div( resolution );
@@ -87,8 +78,12 @@ export function buildFinalWriteKernel( params ) {
 				const prevAccumSample = texture( prevAccumTexture, prevUV, 0 ).toVar();
 
 				finalColor.assign( mix( prevAccumSample.xyz, sampleColor.xyz, accumulationAlpha ) );
-				finalNormalDepth.assign( mix( texture( prevNormalDepthTexture, prevUV, 0 ), finalNormalDepth, accumulationAlpha ) );
-				finalAlbedo.assign( mix( texture( prevAlbedoTexture, prevUV, 0 ).xyz, finalAlbedo, accumulationAlpha ) );
+				If( auxOn, () => {
+
+					finalNormalDepth.assign( mix( texture( prevNormalDepthTexture, prevUV, 0 ), finalNormalDepth, accumulationAlpha ) );
+					finalAlbedo.assign( mix( texture( prevAlbedoTexture, prevUV, 0 ).xyz, finalAlbedo, accumulationAlpha ) );
+
+				} );
 
 				If( transparentBackground, () => {
 
@@ -107,8 +102,12 @@ export function buildFinalWriteKernel( params ) {
 
 			const uintCoord = uvec2( uint( gx ), uint( gy ) );
 			textureStore( writeColorTex, uintCoord, vec4( finalColor, outputAlpha ) ).toWriteOnly();
-			textureStore( writeNDTex, uintCoord, finalNormalDepth ).toWriteOnly();
-			textureStore( writeAlbedoTex, uintCoord, vec4( finalAlbedo, 1.0 ) ).toWriteOnly();
+			If( auxOn, () => {
+
+				textureStore( writeNDTex, uintCoord, finalNormalDepth ).toWriteOnly();
+				textureStore( writeAlbedoTex, uintCoord, vec4( finalAlbedo, 1.0 ) ).toWriteOnly();
+
+			} );
 
 		} );
 

package/src/TSL/GenerateKernel.js

@@ -33,39 +33,32 @@ export function buildGenerateKernel( params ) {
 		cameraWorldMatrix, cameraProjectionMatrixInverse,
 		enableDOF, focalLength, aperture, focusDistance, sceneScale, apertureScale, anamorphicRatio,
 		renderWidth, renderHeight,
-		// Multi-sample: S primary rays/pixel/frame; S>1 dispatch covers h*S rows, ray lands in slot subSample*(w*h) + pixelIndex.
-		samplesPerPass = 1,
 		transmissiveBounces, // per-ray refraction budget (megakernel parity: PathTracerCore.js:606)
 		transparentBackground, // alpha inits to 1 here (megakernel parity: PathTracerCore.js:554) — env-escape-without-opaque zeroes it in Shade
+		auxGBufferEnabled, // live uniform: 1 = init the per-pixel G-buffer (denoiser on), 0 = skip it
 	} = params;
 
-	const S = samplesPerPass | 0;
+	const auxOn = auxGBufferEnabled.greaterThan( uint( 0 ) );
 
 	const computeFn = Fn( () => {
 
 		const gx = int( workgroupId.x ).mul( WG_SIZE ).add( int( localId.x ) );
-		const gyRaw = int( workgroupId.y ).mul( WG_SIZE ).add( int( localId.y ) );
+		const gy = int( workgroupId.y ).mul( WG_SIZE ).add( int( localId.y ) );
 
-		const subSample = S > 1 ? gyRaw.div( renderHeight ).toVar() : int( 0 );
-		const gy = S > 1 ? gyRaw.sub( subSample.mul( renderHeight ) ).toVar() : gyRaw;
-		const yBound = S > 1 ? renderHeight.mul( int( S ) ) : renderHeight;
-
-		If( gx.lessThan( renderWidth ).and( gyRaw.lessThan( yBound ) ), () => {
+		If( gx.lessThan( renderWidth ).and( gy.lessThan( renderHeight ) ), () => {
 
 			const pixelCoord = vec2( float( gx ).add( 0.5 ), float( gy ).add( 0.5 ) );
 			const pixelIndex = gy.mul( int( resolution.x ) ).add( gx );
-			// maxRaysPerSample = w*h, derived from the resolution uniform (NOT baked) so resize never changes the WGSL.
-			const rayID = S > 1
-				? uint( pixelIndex ).add( uint( subSample ).mul( uint( resolution.x ).mul( uint( resolution.y ) ) ) )
-				: uint( pixelIndex );
+			// One ray per pixel: rayID is the pixel index.
+			const rayID = uint( pixelIndex );
 
 			const screenPosition = pixelCoord.div( resolution ).mul( 2.0 ).sub( 1.0 ).toVar();
 			screenPosition.y.assign( screenPosition.y.negate() );
 
-			const baseSeed = getDecorrelatedSeed( { pixelCoord, rayIndex: subSample, frame } ).toVar();
+			const baseSeed = getDecorrelatedSeed( { pixelCoord, rayIndex: int( 0 ), frame } ).toVar();
 			const seed = pcgHash( { state: baseSeed } ).toVar();
 
-			const stratifiedJitter = getStratifiedSample( pixelCoord, subSample, int( S ), seed, resolution, frame ).toVar();
+			const stratifiedJitter = getStratifiedSample( pixelCoord, int( 0 ), int( 1 ), seed, resolution, frame ).toVar();
 
 			const jitterScale = vec2( 2.0 ).div( resolution );
 			const jitter = stratifiedJitter.sub( 0.5 ).mul( jitterScale );
@@ -78,6 +71,8 @@ export function buildGenerateKernel( params ) {
 			) );
 
 			writeRayOriginMeta( rayBufferRW, rayID, ray.origin, int( 0 ), int( 0 ) );
+			// A fresh camera ray is NOT redirected — REDIRECTED stays clear so it sees the direct backdrop;
+			// ShadeKernel sets REDIRECTED on the first direction-changing interaction (see RAY_FLAG.REDIRECTED).
 			writeRayDirFlags( rayBufferRW, rayID, ray.direction, uint( RAY_FLAG.ACTIVE ) );
 			// pdf inits to 0 = prevBouncePdf (megakernel parity PathTracerCore.js:556). The bounce>0 env/emissive
 			// MIS gate skips until an opaque scatter writes a real combinedPdf; free bounces preserve it.
@@ -87,7 +82,7 @@ export function buildGenerateKernel( params ) {
 			// keeps alpha 1 → solid. Non-transparent mode is inert (FinalWrite forces alpha 1).
 			writeRayRadiance( rayBufferRW, rayID, vec4( vec3( 0.0 ), select( transparentBackground, float( 1.0 ), float( 0.0 ) ) ) );
 
-			If( subSample.equal( int( 0 ) ), () => {
+			If( auxOn, () => {
 
 				// default: normal +Z, depth 1 (far), black albedo (background/miss)
 				writeGBuffer( gBufferRW, uint( pixelIndex ), vec3( 0.0, 0.0, 1.0 ), float( 1.0 ), vec3( 0.0 ) );