rayzee 7.15.2 → 7.17.0

package/package.json

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

package/src/EngineDefaults.js

@@ -184,11 +184,26 @@ export const ENGINE_DEFAULTS = {
 // only round-trip exactly when both sides agree.
 export const ALBEDO_EPS = 0.01;
 
-// Per-resolution compute StorageTextures are pre-allocated at this size and never
-// resized (works around three.js r184 StorageTexture-resize bugs — see TSL/patches
-// history). Render resolution must not exceed this on either axis; the engine warns
-// and ignores larger requests.
-export const MAX_STORAGE_TEXTURE_SIZE = 2048;
+// Hard ceiling the engine supports for the reserved (pre-allocated) render size. 4K (3840×2160)
+// fits within 4096². Raising the reserved size to this pins ~1.5 GB of MRT textures — opt-in only.
+export const MAX_RESERVABLE_RENDER_SIZE = 4096;
+
+// Reserved render size: every per-resolution compute StorageTexture + aux buffer is pre-allocated at
+// this SQUARE size and never resized at runtime (works around three.js StorageTexture-resize bugs —
+// see TSL/patches history). Render resolution must not exceed it; the engine warns + ignores larger.
+// It is a LIVE binding (mutable) so the host can raise it (e.g. for 4K) BEFORE the pipeline/stages are
+// constructed via setReservedRenderSize(); consumers read it inside their constructors. Default 2048
+// (zero VRAM regression). See docs/internal/specs/wavefront-chunked-pool.md.
+export let MAX_STORAGE_TEXTURE_SIZE = 2048;
+
+// Set the reserved render size. MUST be called before pipeline construction (stages pre-allocate at
+// this value and cannot resize). Clamped to [256, MAX_RESERVABLE_RENDER_SIZE]. Returns the applied value.
+export function setReservedRenderSize( px ) {
+
+	MAX_STORAGE_TEXTURE_SIZE = Math.max( 256, Math.min( MAX_RESERVABLE_RENDER_SIZE, Math.floor( px ) || 256 ) );
+	return MAX_STORAGE_TEXTURE_SIZE;
+
+}
 
 export const ASVGF_QUALITY_PRESETS = {
 	// phiColor / phiDepth are RELATIVE tolerances (fractions). Bigger = more

package/src/PathTracerApp.js

@@ -16,7 +16,7 @@ import { AutoExposure } from './Stages/AutoExposure.js';
 import { Compositor } from './Stages/Compositor.js';
 import { RenderPipeline } from './Pipeline/RenderPipeline.js';
 import { CompletionTracker } from './Pipeline/CompletionTracker.js';
-import { ENGINE_DEFAULTS as DEFAULT_STATE, PRODUCTION_RENDER_CONFIG, INTERACTIVE_RENDER_CONFIG, MAX_STORAGE_TEXTURE_SIZE } from './EngineDefaults.js';
+import { ENGINE_DEFAULTS as DEFAULT_STATE, PRODUCTION_RENDER_CONFIG, INTERACTIVE_RENDER_CONFIG, MAX_STORAGE_TEXTURE_SIZE, MAX_RESERVABLE_RENDER_SIZE, setReservedRenderSize } from './EngineDefaults.js';
 import { updateStats, updateLoading, resetLoading, setStatusCallback, getDisplaySamples, disposeObjectFromMemory } from './Processor/utils.js';
 import { BuildTimer } from './Processor/BuildTimer.js';
 import { InteractionManager } from './managers/InteractionManager.js';
@@ -775,11 +775,7 @@ export class PathTracerApp extends EventDispatcher {
 			this.reset();
 			this.cameraManager.currentCameraIndex = 0;
 			this.dispatchEvent( eventPayload );
-			this.dispatchEvent( {
-				type: 'CamerasUpdated',
-				cameras: this.cameraManager.cameras,
-				cameraNames: this.cameraManager.getCameraNames()
-			} );
+			this._dispatchCamerasUpdated();
 
 		} finally {
 
@@ -1093,6 +1089,57 @@ export class PathTracerApp extends EventDispatcher {
 
 	}
 
+	// ═══════════════════════════════════════════════════════════════
+	// Dynamic cameras (add / remove)
+	// ═══════════════════════════════════════════════════════════════
+
+	/** The index of the currently active camera (0 = built-in default). */
+	get currentCameraIndex() {
+
+		return this.cameraManager?.currentCameraIndex ?? 0;
+
+	}
+
+	/**
+	 * Snapshot the current view as a new named camera and switch to it.
+	 * @param {Object} [opts]
+	 * @param {string} [opts.name] - Display name (auto-generated otherwise).
+	 * @returns {number} The index of the newly added camera.
+	 */
+	addCamera( { name } = {} ) {
+
+		const index = this.cameraManager.addCameraFromView( name );
+		this.cameraManager.switchCamera( index );
+		this._dispatchCamerasUpdated();
+		return index;
+
+	}
+
+	/**
+	 * Remove a user-added camera by index. Built-in and model-embedded cameras
+	 * are protected. Falls back to the default camera if the active one is removed.
+	 * @param {number} index
+	 * @returns {boolean} true if a camera was removed.
+	 */
+	removeCamera( index ) {
+
+		const removed = this.cameraManager.removeCamera( index );
+		if ( removed ) this._dispatchCamerasUpdated();
+		return removed;
+
+	}
+
+	/** Notify consumers that the camera list changed (names / count). */
+	_dispatchCamerasUpdated() {
+
+		this.dispatchEvent( {
+			type: 'CamerasUpdated',
+			cameras: this.cameraManager.cameras,
+			cameraNames: this.cameraManager.getCameraNames(),
+		} );
+
+	}
+
 	// ═══════════════════════════════════════════════════════════════
 	// BVH Refit (Animation)
 	// ═══════════════════════════════════════════════════════════════
@@ -1155,6 +1202,56 @@ export class PathTracerApp extends EventDispatcher {
 	// Resize
 	// ═══════════════════════════════════════════════════════════════
 
+	/**
+	 * Raise (or lower) the reserved render size — the square dimension every compute StorageTexture + aux
+	 * buffer is pre-allocated at. Needed to enable resolutions above the 2048 default (e.g. 4K). The request
+	 * is device-capped: 4K reservation (~1.5 GB of MRT textures) is only granted on GPUs with ample VRAM +
+	 * a large storage-buffer binding limit; weaker devices clamp to 2048.
+	 *
+	 * MUST be called before the pipeline/stages are constructed (they pre-allocate at this value and cannot
+	 * resize). Calling it after init only takes effect on the next full pipeline (re)build.
+	 * @param {number} requestedPx desired reserved size (longest edge)
+	 * @returns {number} the applied reserved size
+	 */
+	setReservedRenderResolution( requestedPx ) {
+
+		const limits = this.renderer?.backend?.device?.limits;
+		const maxBinding = limits?.maxStorageBufferBindingSize || ( 128 * 1024 * 1024 );
+		const deviceMemGB = ( typeof navigator !== 'undefined' && navigator.deviceMemory ) || 4;
+		// 4K reserve pins the accum MRT (~1.5 GB) + aux; only grant it on clearly-capable GPUs.
+		const deviceSafeMax = ( deviceMemGB >= 8 && maxBinding >= 1024 * 1024 * 1024 )
+			? MAX_RESERVABLE_RENDER_SIZE : 2048;
+		const prev = MAX_STORAGE_TEXTURE_SIZE;
+		const applied = setReservedRenderSize( Math.min( requestedPx, deviceSafeMax ) );
+
+		// If the pipeline is already built and the reserved size changed, re-init the reserved GPU storage in
+		// place: each stage recreates its pre-allocated StorageTextures at the new size + rebuilds its compute
+		// pipelines. Stage OBJECTS, manager refs and event wiring are preserved (so no re-subscription needed);
+		// scene geometry buffers are resolution-independent and reused. Rendering is paused across the swap so
+		// no in-flight dispatch references a disposed texture.
+		if ( applied !== prev && this.stages?.pathTracer?._packedBuffers ) {
+
+			const wasPaused = this.pauseRendering;
+			this.pauseRendering = true;
+			try {
+
+				for ( const stage of Object.values( this.stages ) ) stage?.reallocateReservedStorage?.();
+
+			} finally {
+
+				this.pauseRendering = wasPaused;
+
+			}
+
+			this.reset();
+			this.dispatchEvent( { type: 'reserved_render_size_changed', size: applied } );
+
+		}
+
+		return applied;
+
+	}
+
 	/**
 	 * Guard against render resolutions the compute pipeline can't support.
 	 * Per-resolution StorageTextures are pre-allocated at MAX_STORAGE_TEXTURE_SIZE
@@ -1292,6 +1389,9 @@ export class PathTracerApp extends EventDispatcher {
 
 		if ( options.canvasWidth && options.canvasHeight ) {
 
+			// Raise the reserved storage first so a > 2048 final-render resolution (4K) fits (device-capped,
+			// in-place re-init). No-op when the size already fits.
+			this.setReservedRenderResolution( Math.max( options.canvasWidth, options.canvasHeight ) );
 			this.setCanvasSize( options.canvasWidth, options.canvasHeight );
 
 		}
@@ -1874,6 +1974,8 @@ export class PathTracerApp extends EventDispatcher {
 			onResize: () => this.onResize(),
 			onReset: () => this.reset(),
 			getSettings: ( k ) => this.settings.get( k ),
+			// Per-camera DOF restore — silent + reset:false so switchCamera's own onReset() is the single reset.
+			applySettings: ( updates ) => this.settings.setMany( updates, { silent: true, reset: false } ),
 		} );
 
 		// Auto-focus context — CameraManager stores it, reads it each frame

package/src/Processor/PackedRayBuffer.js

@@ -4,7 +4,7 @@
  */
 
 import {
-	storage, uintBitsToFloat, floatBitsToUint, vec2, vec3, vec4, uvec4, uint, int,
+	storage, uintBitsToFloat, floatBitsToUint, vec2, vec3, vec4, uvec4, uint, int, float, clamp,
 	packSnorm2x16, packUnorm2x16, unpackSnorm2x16, unpackUnorm2x16,
 } from 'three/tsl';
 import { StorageInstancedBufferAttribute } from 'three/webgpu';
@@ -24,7 +24,7 @@ export const RAY = {
 	THROUGHPUT_PDF: 2, // vec4(throughput.xyz, pdf)
 	RADIANCE_ALPHA: 3, // vec4(radiance.xyz, alpha)
 	MEDIUM_STACK: 4, // vec4(uintBitsToFloat(stackDepth|transTraversals<<8|wavelength<<16), ior1, ior2, ior3)
-	MEDIUM_SIGMA_A: 5, // vec4(sigmaA.xyz, _) — Beer-Lambert absorption coeff of the active medium (KHR_materials_volume + SSS)
+	MEDIUM_SIGMA_A: 5, // vec4(sigmaA.xyz, featTP.w) — Beer-Lambert absorption (KHR_materials_volume + SSS) + DDFA feature-throughput tint
 	SSS_SIGMA_S: 6, // vec4(sigmaS.xyz, g) — SSS scattering coeff + Henyey-Greenstein anisotropy (sigmaS==0 ⇒ glass)
 };
 
@@ -50,16 +50,11 @@ export function freeStorageAttribute( renderer, attr ) {
 
 export class PackedRayBuffer {
 
-	// Capacity maxRays would allocate (mirrors allocate()/resize()). 1.25× headroom, NO pow2 rounding —
-	// the pow2 jump nearly doubled VRAM (e.g. 2048²: 5.24M→8.39M) for no realloc benefit: the app's
-	// discrete resolution presets always exceed the 1.25× margin on a tier change, so they rebuild anyway.
-	static requiredCapacity( maxRays ) {
-
-		return Math.ceil( maxRays * 1.25 );
-
-	}
-
-	constructor( maxRays = 0, renderer = null ) {
+	// `capacity` is the exact paths-in-flight budget B (Blender-style path pool). It is DECOUPLED from
+	// image resolution and fixed for the device — the image is streamed through the pool in row bands
+	// (see docs/internal/specs/wavefront-chunked-pool.md), so the SoA stride _cap never changes with
+	// resolution and the wavefront kernels are built once (no resize-triggered WGSL regen).
+	constructor( capacity = 0, renderer = null ) {
 
 		this.capacity = 0;
 		this._renderer = renderer;
@@ -70,15 +65,14 @@ export class PackedRayBuffer {
 		this.rngBuffer = null;
 		this.hitBuffer = null;
 
-		if ( maxRays > 0 ) this.allocate( maxRays );
+		if ( capacity > 0 ) this.allocate( capacity );
 
 	}
 
-	allocate( maxRays ) {
+	allocate( capacity ) {
 
 		this.dispose();
 
-		const capacity = Math.ceil( maxRays * 1.25 );
 		this.capacity = capacity;
 		_cap = capacity;
 
@@ -117,12 +111,11 @@ export class PackedRayBuffer {
 
 	}
 
-	// Reallocates only if maxRays needs more capacity; returns true if it did.
-	resize( maxRays ) {
+	// Reallocates only if a larger budget capacity is requested; returns true if it did.
+	resize( capacity ) {
 
-		const needed = Math.ceil( maxRays * 1.25 );
-		if ( needed <= this.capacity && this.capacity > 0 ) return false;
-		this.allocate( maxRays );
+		if ( capacity <= this.capacity && this.capacity > 0 ) return false;
+		this.allocate( capacity );
 		return true;
 
 	}
@@ -258,11 +251,44 @@ export const writeMediumStack = ( buf, id, stackDepth, transTraversals, ior1, io
 			stackDepth.bitOr( transTraversals.shiftLeft( 8 ) ).bitOr( wavelength.shiftLeft( 16 ) )
 		), ior1, ior2, ior3 ) );
 
-// Region 7: Beer-Lambert sigmaA of the active medium; single-slot, absorption gated on stackDepth>0.
+// Region 7: Beer-Lambert sigmaA (.xyz) of the active medium + DDFA feature-throughput (.w).
+// .xyz absorption is gated on stackDepth>0; .w carries the OIDN/ASVGF see-through aux tint (see below).
+// Both writers RMW-preserve the other half so sigmaA (live in glass) and featTP never clobber each other.
 export const readMediumSigmaA = ( buf, id ) => buf.element( soa( id, RAY.MEDIUM_SIGMA_A ) ).xyz;
 
-export const writeMediumSigmaA = ( buf, id, sigmaA ) =>
-	buf.element( soa( id, RAY.MEDIUM_SIGMA_A ) ).assign( vec4( sigmaA, 0.0 ) );
+export const writeMediumSigmaA = ( buf, id, sigmaA ) => {
+
+	const keepW = buf.element( soa( id, RAY.MEDIUM_SIGMA_A ) ).w.toVar();
+	buf.element( soa( id, RAY.MEDIUM_SIGMA_A ) ).assign( vec4( sigmaA, keepW ) );
+
+};
+
+// DDFA (Deferred Denoising-Feature Aux) feature-throughput: a clean per-ray tint carried through smooth
+// glass/mirror, committed into the OIDN/ASVGF albedo guide at the first diffuse-enough surface. Rides the
+// otherwise-dead MEDIUM_SIGMA_A.w, packed 10/10/10 into 30 bits (top 2 bits zero ⇒ the float bit-pattern is
+// always finite — never NaN/Inf). LDR [0,1] per channel; final albedo re-quantizes to unorm16 anyway.
+const pack30 = ( tp ) => {
+
+	const c = clamp( tp, vec3( 0.0 ), vec3( 1.0 ) ).mul( 1023.0 ).add( 0.5 );
+	return uint( c.x ).bitOr( uint( c.y ).shiftLeft( 10 ) ).bitOr( uint( c.z ).shiftLeft( 20 ) );
+
+};
+
+const unpack30 = ( u ) => vec3(
+	float( u.bitAnd( uint( 1023 ) ) ),
+	float( u.shiftRight( 10 ).bitAnd( uint( 1023 ) ) ),
+	float( u.shiftRight( 20 ).bitAnd( uint( 1023 ) ) ),
+).div( 1023.0 );
+
+export const readFeatureThroughput = ( buf, id ) =>
+	unpack30( floatBitsToUint( buf.element( soa( id, RAY.MEDIUM_SIGMA_A ) ).w ) );
+
+export const writeFeatureThroughput = ( buf, id, tp ) => {
+
+	const keepXYZ = buf.element( soa( id, RAY.MEDIUM_SIGMA_A ) ).xyz.toVar();
+	buf.element( soa( id, RAY.MEDIUM_SIGMA_A ) ).assign( vec4( keepXYZ, uintBitsToFloat( pack30( tp ) ) ) );
+
+};
 
 // 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)

package/src/RenderSettings.js

@@ -252,8 +252,9 @@ export class RenderSettings extends EventDispatcher {
 	 * @param {Object} updates - Key/value pairs
 	 * @param {Object} [options]
 	 * @param {boolean} [options.silent] - Suppress settingChanged events
+	 * @param {boolean} [options.reset]  - Override the routes' default reset behavior
 	 */
-	setMany( updates, { silent } = {} ) {
+	setMany( updates, { silent, reset } = {} ) {
 
 		let needsReset = false;
 
@@ -279,7 +280,8 @@ export class RenderSettings extends EventDispatcher {
 
 		}
 
-		if ( needsReset ) this._resetCallback?.();
+		const shouldReset = reset !== undefined ? reset : needsReset;
+		if ( shouldReset ) this._resetCallback?.();
 
 	}
 

package/src/Stages/ASVGF.js

@@ -796,6 +796,44 @@ export class ASVGF extends RenderStage {
 
 	}
 
+	// Reserved-storage change (e.g. 4K toggle): recreate the MAX-preallocated StorageTextures at the new live
+	// reserved size + rebuild all compute nodes in place. Same stage object, so refs/wiring stay valid. Fresh
+	// build ⇒ the first-render warmup re-runs (no aliasing — the nodes are new, matching initial construction).
+	reallocateReservedStorage() {
+
+		this._gradientNode?.dispose();
+		this._temporalNodeA?.dispose();
+		this._temporalNodeB?.dispose();
+		this._heatmapComputeNode?.dispose();
+		this._temporalTexA?.dispose();
+		this._temporalTexB?.dispose();
+		this._outputModulatedTex?.dispose();
+		this._gradientStorageTex?.dispose();
+		this._heatmapStorageTex?.dispose();
+
+		const mk = ( type, filter ) => {
+
+			const t = new StorageTexture( MAX_STORAGE_TEXTURE_SIZE, MAX_STORAGE_TEXTURE_SIZE );
+			t.type = type; t.format = RGBAFormat; t.minFilter = filter; t.magFilter = filter;
+			return t;
+
+		};
+
+		this._temporalTexA = mk( FloatType, LinearFilter );
+		this._temporalTexB = mk( FloatType, LinearFilter );
+		this._outputModulatedTex = mk( FloatType, LinearFilter );
+		this._gradientStorageTex = mk( HalfFloatType, LinearFilter );
+		this._heatmapStorageTex = mk( FloatType, NearestFilter );
+
+		this._buildGradientCompute();
+		this._buildTemporalCompute();
+		this._buildHeatmapCompute();
+		this._compiled = false;
+		this.currentMoments = 0;
+		this._needsWarmReset = true;
+
+	}
+
 	setSize( width, height ) {
 
 		// StorageTextures stay at max alloc — see resize crash fix (three.js #33061).

package/src/Stages/BilateralFilter.js

@@ -385,6 +385,29 @@ export class BilateralFilter extends RenderStage {
 
 	}
 
+	// Reserved-storage change (e.g. 4K toggle): recreate the MAX-preallocated StorageTextures at the new live
+	// reserved size + rebuild the compute nodes in place. Same stage object, so refs/wiring stay valid.
+	reallocateReservedStorage() {
+
+		this._computeNodeA?.dispose();
+		this._computeNodeB?.dispose();
+		this._storageTexA?.dispose();
+		this._storageTexB?.dispose();
+		const mk = () => {
+
+			const t = new StorageTexture( MAX_STORAGE_TEXTURE_SIZE, MAX_STORAGE_TEXTURE_SIZE );
+			t.type = HalfFloatType; t.format = RGBAFormat; t.minFilter = LinearFilter; t.magFilter = LinearFilter;
+			return t;
+
+		};
+
+		this._storageTexA = mk();
+		this._storageTexB = mk();
+		this._buildCompute();
+		this._compiled = false;
+
+	}
+
 	dispose() {
 
 		this._computeNodeA?.dispose();

package/src/Stages/EdgeFilter.js

@@ -454,6 +454,24 @@ export class EdgeFilter extends RenderStage {
 
 	}
 
+	// Reserved-storage change (e.g. 4K toggle): recreate the MAX-preallocated StorageTextures at the new live
+	// reserved size + rebuild the compute nodes in place. Same stage object, so refs/wiring stay valid.
+	reallocateReservedStorage() {
+
+		this._computeDemod?.dispose();
+		this._computeAtrousA?.dispose();
+		this._computeAtrousB?.dispose();
+		this._demodTex?.dispose();
+		this._storageTexA?.dispose();
+		this._storageTexB?.dispose();
+		this._demodTex = this._makeStorageTex();
+		this._storageTexA = this._makeStorageTex();
+		this._storageTexB = this._makeStorageTex();
+		this._buildCompute();
+		this._compiled = false;
+
+	}
+
 	dispose() {
 
 		this._computeDemod?.dispose();

package/src/Stages/MotionVector.js

@@ -556,6 +556,29 @@ export class MotionVector extends RenderStage {
 
 	}
 
+	// Reserved-storage change (e.g. 4K toggle): recreate the MAX-preallocated StorageTextures at the new live
+	// reserved size + rebuild the compute nodes in place. Same stage object, so refs/wiring stay valid.
+	reallocateReservedStorage() {
+
+		this._screenSpaceComputeNode?.dispose();
+		this._worldSpaceComputeNode?.dispose();
+		this._screenSpaceStorageTex?.dispose();
+		this._worldSpaceStorageTex?.dispose();
+		const mk = () => {
+
+			const t = new StorageTexture( MAX_STORAGE_TEXTURE_SIZE, MAX_STORAGE_TEXTURE_SIZE );
+			t.type = HalfFloatType; t.format = RGBAFormat; t.minFilter = NearestFilter; t.magFilter = NearestFilter;
+			return t;
+
+		};
+
+		this._screenSpaceStorageTex = mk();
+		this._worldSpaceStorageTex = mk();
+		this._buildScreenSpaceCompute();
+		this._buildWorldSpaceCompute();
+
+	}
+
 	dispose() {
 
 		this._screenSpaceComputeNode?.dispose();

package/src/Stages/NormalDepth.js

@@ -405,6 +405,28 @@ export class NormalDepth extends RenderStage {
 
 	}
 
+	// Reserved-storage change (e.g. 4K toggle): recreate the MAX-preallocated StorageTextures at the new live
+	// reserved size. The compute node rebuilds lazily on the next execute (guarded by _computeBuilt).
+	reallocateReservedStorage() {
+
+		this._computeNode?.dispose();
+		this._computeNode = null;
+		this._outputStorageTex?.dispose();
+		this._shadingStorageTex?.dispose();
+		const mk = () => {
+
+			const t = new StorageTexture( MAX_STORAGE_TEXTURE_SIZE, MAX_STORAGE_TEXTURE_SIZE );
+			t.type = HalfFloatType; t.format = RGBAFormat; t.minFilter = NearestFilter; t.magFilter = NearestFilter;
+			return t;
+
+		};
+
+		this._outputStorageTex = mk();
+		this._shadingStorageTex = mk();
+		this._computeBuilt = false;
+
+	}
+
 	dispose() {
 
 		this._computeNode?.dispose();