rayzee 7.3.0 → 7.4.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "rayzee",
-  "version": "7.3.0",
+  "version": "7.4.1",
   "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/Passes/OIDNDenoiser.js

@@ -137,6 +137,8 @@ export class OIDNDenoiser extends EventDispatcher {
 
 		// Track in-flight tile staging buffers so they can be destroyed on abort
 		this._pendingStagingBuffers = new Set();
+		// Per-run tile-blit promises; done() awaits these so capture waits for every tile to paint.
+		this._pendingTileBlits = [];
 
 		this.currentTZAUrl = null;
 		this.unet = null;
@@ -629,6 +631,9 @@ export class OIDNDenoiser extends EventDispatcher {
 
 			let abortDenoise = null;
 
+			// Fresh per-run list of tile-blit promises (the progress callback appends to it).
+			this._pendingTileBlits = [];
+
 			const abortHandler = () => {
 
 				if ( abortDenoise ) {
@@ -653,7 +658,23 @@ export class OIDNDenoiser extends EventDispatcher {
 
 					try {
 
-						await this._displayGPUOutput( output );
+						if ( this._pendingTileBlits.length > 0 ) {
+
+							// Normal path: the progress callback already painted every tile progressively, with
+							// the same exposure/saturation/tonemap/sRGB math the full-frame readback uses (verified:
+							// tiles tile the image exactly, no overlap). Just wait for those blits — no redundant
+							// full-frame re-read + re-tonemap.
+							await Promise.allSettled( this._pendingTileBlits );
+
+						} else {
+
+							// Degenerate fallback (no per-tile progress was emitted): one authoritative full paint.
+							await this._displayGPUOutput( output );
+
+						}
+
+						// DENOISING_END (which gates screenshot/video capture) fires only after this resolves,
+						// so the captured canvas is always complete.
 						resolve();
 
 					} catch ( err ) {
@@ -703,8 +724,9 @@ export class OIDNDenoiser extends EventDispatcher {
 
 					device.queue.submit( [ enc.finish() ] );
 
-					// Map and blit asynchronously — GPU copy is already queued
-					staging.mapAsync( GPUMapMode.READ ).then( () => {
+					// Map and blit asynchronously — GPU copy is already queued. Track the whole chain so
+					// done() can await every tile paint before resolving (replaces the full-frame readback).
+					const tileBlit = staging.mapAsync( GPUMapMode.READ ).then( () => {
 
 						const f32 = new Float32Array( staging.getMappedRange() );
 						const tileImageData = new ImageData( clampedW, clampedH );
@@ -766,6 +788,8 @@ export class OIDNDenoiser extends EventDispatcher {
 
 					} );
 
+					this._pendingTileBlits.push( tileBlit );
+
 				}
 			} );
 

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

@@ -11,16 +11,15 @@ import { StorageInstancedBufferAttribute } from 'three/webgpu';
 
 export const RAY_STRIDE = 7;
 export const HIT_STRIDE = 2;
-// Per-pixel G-buffer (first-hit MRT staging): 2 uvec4/pixel (AoS, element p*GBUFFER_STRIDE + lane).
-//   lane 0 — half-packed normal/depth/albedo (pack2x16, no f32 bitcast); read by FinalWrite:
-//     .x=packSnorm2x16(normal.xy)  .y=packSnorm2x16(normal.z, depth)  .z=packUnorm2x16(albedo.rg)  .w=packUnorm2x16(albedo.b, 0)
-//   lane 1 — primary-hit surface ID for A-SVGF correlated-gradient re-projection (Tier 1); written at the
-//     bounce-0 hit, valid=0 on miss (Generate inits): .x=triIndex .y=meshIndex .z=packUnorm2x16(bary.u,bary.v) .w=valid
+// Per-pixel G-buffer (first-hit MRT staging): 1 uvec4/pixel — half-packed normal/depth/albedo
+// (pack2x16, no f32 bitcast); read by FinalWrite:
+//   .x=packSnorm2x16(normal.xy)  .y=packSnorm2x16(normal.z, depth)  .z=packUnorm2x16(albedo.rg)  .w=packUnorm2x16(albedo.b, 0)
 // Separate buffer from RAY (per-pixel, not per-ray×S) — written by Generate/Shade bounce-0.
-export const GBUFFER_STRIDE = 2;
+// (A second lane reserved for an A-SVGF Tier-1 surface ID was removed — write-only, never read.)
+export const GBUFFER_STRIDE = 1;
 
 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)
@@ -152,36 +151,17 @@ export const readRayRadiance = ( buf, id ) =>
 // ── Per-pixel G-buffer (first-hit MRT). 2 uvec4/pixel (AoS), pack2x16 lanes. ──
 // normal: raw unit vec3; depth: linear [0,1]; albedo: vec3 [0,1]. Packed values live in u32 lanes
 // verbatim (no f32 bitcast) so NaN-range bit patterns (snorm ±1 → 0x7FFF) survive store/load intact.
-// gbLane resolves the AoS slot for a pixel (lane 0 = MRT, lane 1 = surface ID).
-const gbLane = ( pixelIndex, lane ) => {
-
-	const base = uint( pixelIndex ).mul( GBUFFER_STRIDE );
-	return lane === 0 ? base : base.add( lane );
-
-};
+// One uvec4 per pixel (stride 1); AoS base = pixelIndex * GBUFFER_STRIDE.
+const gbLane = ( pixelIndex ) => uint( pixelIndex ).mul( GBUFFER_STRIDE );
 
 export const writeGBuffer = ( buf, pixelIndex, normal, depth, albedo ) =>
-	buf.element( gbLane( pixelIndex, 0 ) ).assign( uvec4(
+	buf.element( gbLane( pixelIndex ) ).assign( uvec4(
 		packSnorm2x16( vec2( normal.x, normal.y ) ),
 		packSnorm2x16( vec2( normal.z, depth ) ),
 		packUnorm2x16( vec2( albedo.x, albedo.y ) ),
 		packUnorm2x16( vec2( albedo.z, 0.0 ) ),
 	) );
-export const readGBuffer = ( buf, pixelIndex ) => buf.element( gbLane( pixelIndex, 0 ) );
-
-// Lane 1 — primary-hit surface ID for A-SVGF correlated gradient re-projection (Tier 1).
-// valid=0 marks a miss (no primary surface); bary packed unorm (both in [0,1]).
-export const writeGBufferSurfaceID = ( buf, pixelIndex, triIndex, meshIndex, baryU, baryV, valid ) =>
-	buf.element( gbLane( pixelIndex, 1 ) ).assign( uvec4(
-		uint( triIndex ), uint( meshIndex ), packUnorm2x16( vec2( baryU, baryV ) ), uint( valid ),
-	) );
-export const readGBufferSurfaceID = ( buf, pixelIndex ) => {
-
-	const p = buf.element( gbLane( pixelIndex, 1 ) );
-	const bary = unpackUnorm2x16( p.z );
-	return { triIndex: p.x, meshIndex: p.y, baryU: bary.x, baryV: bary.y, valid: p.w };
-
-};
+export const readGBuffer = ( buf, pixelIndex ) => buf.element( gbLane( pixelIndex ) );
 
 // Decode for FinalWrite. normalDepth.xyz matches the prior path (normal*0.5+0.5), .w = raw depth.
 export const gbDecodeNormalDepth = ( packed ) => {
@@ -195,8 +175,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 +253,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/Processor/StorageTexturePool.js

@@ -141,16 +141,24 @@ export class StorageTexturePool {
 	 * Copy StorageTextures → RenderTarget textures via GPU copy.
 	 * Must be called after each compute dispatch.
 	 * @param {WebGPURenderer} renderer
+	 * @param {boolean} [includeAux=true] Copy the normalDepth + albedo attachments too. When no
+	 *   denoiser/OIDN consumes the aux MRT (default interactive), the wavefront doesn't write those
+	 *   StorageTextures, so skipping their copies saves two full-res GPU copies/frame. Color is always copied.
 	 */
-	copyToReadTargets( renderer ) {
+	copyToReadTargets( renderer, includeAux = true ) {
 
 		// Source write StorageTextures are over-allocated at the max size; the Box2 region
 		// restricts the copy to the active render size so source and destination extents match.
 		this._srcRegion.max.set( this.renderWidth, this.renderHeight );
 
 		renderer.copyTextureToTexture( this.writeColor, this.readTarget.textures[ 0 ], this._srcRegion );
-		renderer.copyTextureToTexture( this.writeNormalDepth, this.readTarget.textures[ 1 ], this._srcRegion );
-		renderer.copyTextureToTexture( this.writeAlbedo, this.readTarget.textures[ 2 ], this._srcRegion );
+
+		if ( includeAux ) {
+
+			renderer.copyTextureToTexture( this.writeNormalDepth, this.readTarget.textures[ 1 ], this._srcRegion );
+			renderer.copyTextureToTexture( this.writeAlbedo, this.readTarget.textures[ 2 ], this._srcRegion );
+
+		}
 
 	}
 

package/src/Processor/VRAMTracker.js

@@ -1,11 +1,15 @@
 /**
  * VRAMTracker.js — current/peak GPU memory accounting.
  *
- * Measures ACTUAL live bytes (attribute.array.byteLength, texture dims × format/type)
- * rather than re-deriving allocation formulas, so it never drifts when strides,
- * capacity rounding, or layouts change. Providers are thunks that read current state,
- * so they survive reallocation (resize, scene/material/env reload). A per-pass WeakSet
- * dedupes by resource identity, so overlapping registrations never double-count.
+ * Measures live GPU bytes: buffer attributes by backing-array byteLength, textures by
+ * dims × format/type — but ONLY when the backend actually holds a GPUTexture. three.js
+ * allocates a texture's GPUTexture lazily on first use, so a constructed-but-never-dispatched
+ * StorageTexture (e.g. a disabled stage's render targets) costs 0 here even though its JS
+ * `image` dimensions are set. Residency probing needs a renderer (constructor arg or
+ * setRenderer); without one it falls back to counting by dimensions (legacy behavior).
+ * Providers are thunks that read current state, so they survive reallocation (resize,
+ * scene/material/env reload). A per-pass WeakSet dedupes by resource identity, so
+ * overlapping registrations never double-count.
  */
 
 import {
@@ -60,15 +64,23 @@ export function textureBytes( tex ) {
 
 export class VRAMTracker {
 
-	constructor() {
+	constructor( renderer = null ) {
 
 		this._providers = [];
+		this._renderer = renderer;
 		this.current = 0;
 		this.peak = 0;
 		this.byCategory = {};
 
 	}
 
+	/** Late-bind the renderer so texture accounting can probe actual GPU residency. */
+	setRenderer( renderer ) {
+
+		this._renderer = renderer;
+
+	}
+
 	/**
 	 * @param {string} category - grouping label in the report
 	 * @param {Function} fn - returns a resource or array of resources: buffer
@@ -138,12 +150,12 @@ export class VRAMTracker {
 
 		}
 
-		// texture / render target — dedupe by object identity
+		// texture / render target — dedupe by object identity; count only GPU-resident bytes
 		if ( r.isRenderTarget || r.isTexture ) {
 
 			if ( seen.has( r ) ) return 0;
 			seen.add( r );
-			return textureBytes( r );
+			return this._residentTextureBytes( r );
 
 		}
 
@@ -151,6 +163,36 @@ export class VRAMTracker {
 
 	}
 
+	// three.js allocates a texture's GPUTexture lazily on first dispatch; a never-used StorageTexture
+	// (disabled stage) has none. Count only when the backend holds a real GPUTexture so the report is
+	// resident VRAM, not JS-declared dimensions. No renderer bound → assume resident (legacy behavior).
+	_isResident( tex ) {
+
+		const backend = this._renderer?.backend;
+		if ( ! backend || typeof backend.get !== 'function' ) return true;
+		if ( typeof backend.has === 'function' && ! backend.has( tex ) ) return false;
+		const data = backend.get( tex );
+		return !! ( data && ( data.texture || data.gpuTexture ) );
+
+	}
+
+	// RenderTarget bytes are attributed to its underlying texture(s); count each only if resident.
+	_residentTextureBytes( tex ) {
+
+		if ( tex.isRenderTarget ) {
+
+			const list = tex.textures?.length ? tex.textures : [ tex.texture ];
+			const w = tex.width || 0, h = tex.height || 0, d = tex.depth || 1;
+			let sum = 0;
+			for ( const t of list ) if ( t && this._isResident( t ) ) sum += w * h * d * texelBytes( t );
+			return sum;
+
+		}
+
+		return this._isResident( tex ) ? textureBytes( tex ) : 0;
+
+	}
+
 	/** Drop the high-water mark to the current value (call when a new render begins). */
 	resetPeak() {
 

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/ASVGF.js

@@ -832,6 +832,33 @@ export class ASVGF extends RenderStage {
 
 	}
 
+	// Free the over-allocated 2048² StorageTextures' GPU memory when the stage is disabled, so toggling
+	// the denoiser off reclaims VRAM. The JS texture objects + compiled compute nodes are kept; three.js
+	// lazily re-creates each GPUTexture on the next dispatch after re-enable. History re-anchors via the
+	// warm reset (the RTs are render-res, not 2048² — left alone).
+	releaseGPUMemory() {
+
+		this._temporalTexA?.dispose();
+		this._temporalTexB?.dispose();
+		this._outputModulatedTex?.dispose();
+		this._gradientStorageTex?.dispose();
+		this._heatmapStorageTex?.dispose();
+		// Render-res RT textures (sized to render resolution → meaningful VRAM at high res). Dispose the
+		// .texture, not the RenderTarget (RT.dispose() doesn't free the backing GPUTexture here); these RTs
+		// are copyTextureToTexture targets, so three.js reallocates on the next dispatch after re-enable.
+		// Drop the published context outputs first so the Compositor fallback (reads asvgf:output) can't
+		// sample a freed texture; render() re-publishes on re-enable.
+		this.context?.removeTexture( 'asvgf:demodulated' );
+		this.context?.removeTexture( 'asvgf:output' );
+		this.context?.removeTexture( 'asvgf:gradient' );
+		this._demodulatedRT?.texture?.dispose();
+		this._outputRT?.texture?.dispose();
+		this._gradientRT?.texture?.dispose();
+		this.heatmapTarget?.texture?.dispose();
+		this.resetTemporalData();
+
+	}
+
 	dispose() {
 
 		this._gradientNode?.dispose();

package/src/Stages/BilateralFilter.js

@@ -367,6 +367,18 @@ export class BilateralFilter extends RenderStage {
 
 	}
 
+	// Free the 2048² StorageTextures when disabled; three.js re-creates them on the next dispatch
+	// after re-enable (no temporal state to re-anchor). See ASVGF.releaseGPUMemory.
+	releaseGPUMemory() {
+
+		this._storageTexA?.dispose();
+		this._storageTexB?.dispose();
+		// Render-res RT texture (dispose .texture, not the RT — RT.dispose() doesn't free it here).
+		this.context?.removeTexture( 'bilateralFiltering:output' );
+		this._outputTarget?.texture?.dispose();
+
+	}
+
 	reset() {
 
 		// No temporal state to reset

package/src/Stages/EdgeFilter.js

@@ -267,6 +267,18 @@ export class EdgeFilter extends RenderStage {
 
 	}
 
+	// Free the 2048² StorageTexture when disabled; three.js re-creates it on the next dispatch
+	// after re-enable, and reset() clears the iteration history. See ASVGF.releaseGPUMemory.
+	releaseGPUMemory() {
+
+		this._outputStorageTex?.dispose();
+		// Render-res RT texture (dispose .texture, not the RT — RT.dispose() doesn't free it here).
+		this.context?.removeTexture( 'edgeFiltering:output' );
+		this.outputTarget?.texture?.dispose();
+		this.reset();
+
+	}
+
 	reset() {
 
 		this._iterations = 0;

package/src/Stages/MotionVector.js

@@ -495,6 +495,16 @@ export class MotionVector extends RenderStage {
 	 * Reset — intentionally does NOT reset matricesInitialized.
 	 * Motion vectors must track camera motion across pipeline resets.
 	 */
+	// Free the 2048² StorageTextures when disabled (no consumer); three.js re-creates them on the next
+	// dispatch after re-enable. _syncGBufferStages additionally reseeds camera history on re-enable.
+	releaseGPUMemory() {
+
+		this._screenSpaceStorageTex?.dispose();
+		this._worldSpaceStorageTex?.dispose();
+		this.reset();
+
+	}
+
 	reset() {
 
 		if ( ! this.matricesInitialized ) {

package/src/Stages/NormalDepth.js

@@ -367,6 +367,16 @@ export class NormalDepth extends RenderStage {
 
 	}
 
+	// Free the 2048² StorageTextures when disabled (no consumer); three.js re-creates them on the next
+	// dispatch after re-enable, and reset() re-arms the dirty/history fast-path. See ASVGF.releaseGPUMemory.
+	releaseGPUMemory() {
+
+		this._outputStorageTex?.dispose();
+		this._shadingStorageTex?.dispose();
+		this.reset();
+
+	}
+
 	reset() {
 
 		this._dirty = true;