rayzee 7.22.2 → 7.22.4

package/package.json

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

package/src/EngineDefaults.js

@@ -93,24 +93,31 @@ export const ENGINE_DEFAULTS = {
 
 	// Adaptive sampling (Blender-style): stop the frame once enough pixels drop below the noise threshold.
 	useAdaptiveSampling: true,
-	noiseThreshold: 0.02, // √-luminance-normalized per-pixel noise below which a pixel is converged
+	// √-luminance-normalized per-pixel noise below which a pixel counts as converged. Base tracks the
+	// interactive tier — that is what a freshly booted engine renders before configureForMode runs.
+	noiseThreshold: 0.1,
 	adaptiveMinSamples: 8, // min samples before adaptive sampling can trigger
-	adaptiveStopFraction: 0.95, // retire the frame once this fraction of pixels has converged
+	// Fraction of pixels that must pass the 3×3-eroded convergence count before the frame retires; the
+	// geometry-only fraction has to clear the same bar (PathTracer._isConvergedComplete).
+	// ENGINE-INTERNAL: a calibration constant rather than a quality dial — it only means anything against
+	// those two counts. configureForMode supplies the per-tier value.
+	adaptiveStopFraction: 0.90,
 	// Per-pixel freeze: skip tracing pixels that individually converged (noise threshold only — no dark floor,
 	// which would bake dim regions too dark). Naturally engages only on static/idle views.
+	// Set together with useAdaptiveSampling by the single UI switch — two tiers of one feature.
 	usePixelFreeze: true,
-	pixelFreezeThreshold: 0.02, // per-pixel noise below which a pixel becomes a freeze candidate
-	pixelFreezeStability: 8, // consecutive candidate frames before a pixel freezes
+	// ENGINE-INTERNAL, and not the sibling of noiseThreshold it looks like: freeze bars on plain relErr where
+	// the frame test uses the √-normalized error, so the same number is 2-5× stricter here. Deriving it from
+	// noiseThreshold was measured and rejected — a pixel frozen before it satisfies the frame test can never
+	// satisfy it afterwards, so a looser bar delays the early stop rather than hastening it.
+	pixelFreezeThreshold: 0.02,
+	pixelFreezeStability: 8, // ENGINE-INTERNAL: consecutive candidate frames before a pixel freezes
+	convergenceOverlay: false, // display-only Compositor overlay; never alters the render
 
 	samplingTechnique: 2,
 	enableEmissiveTriangleSampling: false,
 	emissiveBoost: 1.0,
 
-	temporalVarianceWeight: 0.6,
-	enableEarlyTermination: true,
-	earlyTerminationThreshold: 0.002,
-	performanceModeAdaptive: 'medium',
-
 	fireflyThreshold: 3.0,
 	// Wavefront material-coherence sort: global counting-sort of entering rays by material before
 	// Shade (material-pure workgroups), under dynamic dispatch. Measured −8% at 1024²/8b. Gated on
@@ -199,9 +206,10 @@ 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.
+// It is a LIVE binding (mutable) so it can be raised (e.g. for 4K) via setReservedRenderSize(); consumers
+// read it inside their constructors, and stages already built at a lower value are re-initialised in place
+// by PathTracerApp.setReservedRenderResolution() — which is the device-gated API hosts should call, at any
+// point in the lifecycle. 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
@@ -598,11 +606,10 @@ export const PRODUCTION_RENDER_CONFIG = {
 	renderMode: 1, enableAlphaShadows: true,
 	enableOIDN: true, oidnQuality: 'balance',
 	interactionModeEnabled: false,
-	// √-norm convergence reaches a true ~all-converged gate, so stop at 0.98 — Cycles-faithful, leaving
-	// the unbiased residual for OIDN.
+	// 0.94 against the eroded count ≈ the old raw-count 0.98; erosion holds the fraction a few points lower.
 	useAdaptiveSampling: true,
-	noiseThreshold: 0.1,
-	adaptiveStopFraction: 0.98,
+	noiseThreshold: 0.02,
+	adaptiveStopFraction: 0.94,
 	usePixelFreeze: true,
 };
 
@@ -614,6 +621,7 @@ export const INTERACTIVE_RENDER_CONFIG = {
 	enableOIDN: false, oidnQuality: 'fast',
 	interactionModeEnabled: true,
 	useAdaptiveSampling: true, // idle refine stops early when converged; frozen during motion
+	noiseThreshold: 0.1, // loose: preview wants a fast settle, not a clean one
 	usePixelFreeze: true, // speeds up idle refinement on heavy/high-res views; inert while moving (freeze resets)
 };
 

package/src/PathTracerApp.js

@@ -114,6 +114,8 @@ export class PathTracerApp extends EventDispatcher {
 		// ── Pipeline & stages ──
 		this.pipeline = null;
 
+		this._pendingReservedRenderSize = null;
+
 		/**
 		 * Named access to all pipeline stages.
 		 * Advanced consumers can reach into stages for fine-grained control.
@@ -220,6 +222,7 @@ export class PathTracerApp extends EventDispatcher {
 	async init() {
 
 		await this._initRenderer();
+		this._applyPendingReservedRenderSize();
 		this._initCameraManager();
 		this._initScenes();
 		this._initAssetPipeline();
@@ -1233,34 +1236,53 @@ export class PathTracerApp extends EventDispatcher {
 	 * 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.
+	 * Callable at any point in the lifecycle:
+	 *  - before init(): recorded, then applied during init() before the stages are constructed, so they
+	 *    pre-allocate at the raised size directly. The device gate cannot run until the device exists, so
+	 *    the value returned here is the request, not the verdict — read getReservedRenderResolution() after
+	 *    init(), or listen for `reserved_render_size_changed`.
+	 *  - after init(): applied immediately, re-initialising the reserved GPU storage in place.
 	 * @param {number}  requestedPx desired reserved size (longest edge)
 	 * @param {Object}  [opts]
 	 * @param {boolean} [opts.allowLower=false] permit lowering, paying a rebuild, to reclaim VRAM
-	 * @returns {number} the applied reserved size
+	 * @returns {number} the applied reserved size (the pending request when called before init)
 	 */
 	setReservedRenderResolution( requestedPx, { allowLower = false } = {} ) {
 
-		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;
 
 		// Monotonic up: UI-driven callers request whatever the current view needs, so honouring decreases made
 		// the reserve oscillate on every preview↔render switch and paid a full kernel rebuild each time.
 		const target = allowLower ? requestedPx : Math.max( requestedPx, prev );
+
+		// No device yet: the gate below has nothing to interrogate and would clamp a 4K-capable GPU to 2048.
+		// init() replays the request once the device exists, still before the stages allocate.
+		if ( ! this.renderer ) {
+
+			this._pendingReservedRenderSize = { requestedPx, allowLower };
+			return Math.max( 256, Math.min( MAX_RESERVABLE_RENDER_SIZE, Math.floor( target ) || 256 ) );
+
+		}
+
+		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 applied = setReservedRenderSize( Math.min( target, 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 ) {
+		// Gate the realloc on the textures that EXIST, not on how the binding moved: a raise applied while
+		// nothing was allocated leaves `applied === prev` for every later call, so keying off that let the
+		// first ineffective call poison every effective one after it (issue #9). The path tracer's write MRT
+		// witnesses the reserve the stages were last built at.
+		const allocated = this.stages?.pathTracer?.storageTextures?.writeColor?.image?.width ?? applied;
+
+		// 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 ( allocated !== applied ) {
 
 			const wasPaused = this.pauseRendering;
 			this.pauseRendering = true;
@@ -1294,6 +1316,31 @@ export class PathTracerApp extends EventDispatcher {
 
 	}
 
+	/**
+	 * Replay a setReservedRenderResolution() call made before init(): after the device exists, so the gate is
+	 * evaluated against the real GPU, and before _initPipeline() constructs the stages, which read the reserve
+	 * in their constructors. The event carries the device's verdict — the only authoritative answer a pre-init
+	 * caller can get.
+	 */
+	_applyPendingReservedRenderSize() {
+
+		const pending = this._pendingReservedRenderSize;
+		if ( ! pending ) return;
+
+		this._pendingReservedRenderSize = null;
+
+		const applied = this.setReservedRenderResolution( pending.requestedPx, { allowLower: pending.allowLower } );
+
+		if ( applied < pending.requestedPx ) {
+
+			log.warn( `reserved render size ${fmt.n( pending.requestedPx )}px was capped to ${fmt.n( applied )}px by this device's limits — renders above ${fmt.n( applied )}px will be declined.` );
+
+		}
+
+		this.dispatchEvent( { type: 'reserved_render_size_changed', size: applied } );
+
+	}
+
 	/**
 	 * The current reserved (pre-allocated) square render size in px.
 	 * @returns {number}
@@ -1314,7 +1361,7 @@ export class PathTracerApp extends EventDispatcher {
 
 		if ( width > MAX_STORAGE_TEXTURE_SIZE || height > MAX_STORAGE_TEXTURE_SIZE ) {
 
-			log.warn( `render resolution ${width}×${height} exceeds the ${MAX_STORAGE_TEXTURE_SIZE}px limit (compute storage textures are pre-allocated at ${MAX_STORAGE_TEXTURE_SIZE}px). Ignoring resize — use a resolution ≤ ${MAX_STORAGE_TEXTURE_SIZE}.` );
+			log.warn( `render resolution ${width}×${height} exceeds the ${MAX_STORAGE_TEXTURE_SIZE}px reserve (compute storage textures are pre-allocated at ${MAX_STORAGE_TEXTURE_SIZE}px). Ignoring resize — raise the reserve with setReservedRenderResolution( ${Math.max( width, height )} ) first, or use a resolution ≤ ${MAX_STORAGE_TEXTURE_SIZE}.` );
 			return false;
 
 		}
@@ -1360,10 +1407,19 @@ export class PathTracerApp extends EventDispatcher {
 
 	}
 
+	/**
+	 * Set the render resolution in pixels, applied immediately (unlike the debounced onResize()).
+	 * @param {number} width
+	 * @param {number} height
+	 * @returns {{width: number, height: number}|null} the size now in effect, or null if the request was
+	 *   declined — zero, or above the reserved render size (raise it with setReservedRenderResolution).
+	 *   A declined request leaves the previous size in place, so ignoring this return renders at the
+	 *   wrong resolution with nothing but a warning to show for it.
+	 */
 	setCanvasSize( width, height ) {
 
-		if ( width === 0 || height === 0 ) return;
-		if ( ! this._isRenderSizeSupported( width, height ) ) return;
+		if ( width === 0 || height === 0 ) return null;
+		if ( ! this._isRenderSizeSupported( width, height ) ) return null;
 
 		this.renderer.setPixelRatio( 1.0 );
 		this.renderer.setSize( width, height, false );
@@ -1373,6 +1429,8 @@ export class PathTracerApp extends EventDispatcher {
 		clearTimeout( this._resizeDebounceTimer );
 		this._applyRenderResize( width, height );
 
+		return { width, height };
+
 	}
 
 	// ═══════════════════════════════════════════════════════════════
@@ -1926,6 +1984,18 @@ export class PathTracerApp extends EventDispatcher {
 
 	}
 
+	/**
+	 * Adaptive-sampling telemetry: `{ converged, activePixels, totalPixels, frame }`.
+	 * Counts come from an async readback taken on settled views only, so they lag a few frames
+	 * and read zero while the camera moves.
+	 * @returns {?Object}
+	 */
+	getConvergenceStats() {
+
+		return this.stages.pathTracer?.getConvergenceStats?.() ?? null;
+
+	}
+
 	/** The path tracer's VRAM tracker, or null before stages are built. */
 	get vram() {
 
@@ -2509,6 +2579,7 @@ export class PathTracerApp extends EventDispatcher {
 
 		this.stages.compositor = new Compositor( this.renderer, {
 			saturation: this.settings.get( 'saturation' ) ?? DEFAULT_STATE.saturation,
+			pathTracer: this.stages.pathTracer,
 		} );
 
 	}

package/src/Processor/QueueManager.js

@@ -22,7 +22,12 @@ export const COUNTER = {
 	RESERVED_3: 3,
 	// Tier-2 per-pixel freeze: bounce-0 active count (maxRays − frozen), read back to size next frame's grid.
 	ACTIVE_PIXEL_COUNT: 4,
-	COUNT: 5,
+	// Geometry-only convergence gate. CONVERGED_COUNT counts every pixel, so a mostly-sky frame inherits the
+	// sky's free convergence and can retire while the subject is still noisy. These count the same eroded
+	// bits restricted to pixels that hit geometry, so the stop can require both fractions.
+	GEOMETRY_COUNT: 5,
+	CONVERGED_GEOMETRY_COUNT: 6,
+	COUNT: 7,
 };
 
 /** Ray flag bits packed into rayBounceFlags (uint) */

package/src/RenderSettings.js

@@ -50,6 +50,7 @@ const SETTING_ROUTES = {
 	usePixelFreeze: { uniform: 'usePixelFreeze', reset: true },
 	pixelFreezeThreshold: { uniform: 'pixelFreezeThreshold', reset: true },
 	pixelFreezeStability: { uniform: 'pixelFreezeStability', reset: true },
+	convergenceOverlay: { handler: 'handleConvergenceOverlay', reset: false },
 	enableEmissiveTriangleSampling: { uniform: 'enableEmissiveTriangleSampling', reset: true },
 	emissiveBoost: { uniform: 'emissiveBoost', reset: true },
 	visMode: { uniform: 'visMode', reset: true },
@@ -142,7 +143,7 @@ export class RenderSettings extends EventDispatcher {
 	 * Builds handler functions for multi-stage settings that can't
 	 * be routed with a simple uniform forward.
 	 */
-	_buildHandlers( { stages, renderer, reconcileCompletion, denoisingManager, cameraManager } ) {
+	_buildHandlers( { stages, renderer, resetCallback, reconcileCompletion, denoisingManager, cameraManager } ) {
 
 		// UniformManager copies into the existing node, so one scratch vector serves every write.
 		const panoScratch = new Vector2();
@@ -209,6 +210,17 @@ export class RenderSettings extends EventDispatcher {
 
 			},
 
+			handleConvergenceOverlay: ( value ) => {
+
+				stages.pathTracer?.setUniform( 'convergenceOverlay', value );
+				stages.compositor?.setConvergenceOverlay( value );
+
+				// With adaptive sampling off nothing kept m2 current, so the estimate has no history to
+				// read — restart accumulation so it self-inits at frame 0 instead of painting stale error.
+				if ( value && ! this.get( 'useAdaptiveSampling' ) ) resetCallback?.();
+
+			},
+
 			handleRenderLimitMode: ( value ) => {
 
 				stages.pathTracer?.setRenderLimitMode?.( value );

package/src/Stages/Compositor.js

@@ -1,6 +1,6 @@
-import { vec4, vec3, uv, uniform, select, dot, mix } from 'three/tsl';
+import { vec4, vec3, uv, uniform, select, dot, mix, float, int, uint, storage, Fn, If } from 'three/tsl';
 import { MeshBasicNodeMaterial, QuadMesh, TextureNode } from 'three/webgpu';
-import { NoBlending } from 'three';
+import { NoBlending, NoToneMapping } from 'three';
 import { RenderStage, StageExecutionMode } from '../Pipeline/RenderStage.js';
 import { REC709_LUMINANCE_COEFFICIENTS } from '../TSL/Common.js';
 
@@ -31,6 +31,17 @@ export class Compositor extends RenderStage {
 
 		this._transparentBackground = uniform( 0, 'int' );
 
+		// Convergence debug overlay — reads the path tracer's per-pixel convergence buffers read-only.
+		// Material is compiled on first enable, so the normal display path carries none of its bindings.
+		this._pathTracer = options.pathTracer ?? null;
+		this._convergenceOverlay = false;
+		this._debugMaterial = null;
+		this._debugQuad = null;
+		this._debugTexNode = null;
+		this._debugM2Attr = null;
+		this._debugMaskAttr = null;
+		this._debugExposureComp = uniform( 1.0 );
+
 		// TextureNode reused across frames — only `.value` mutates, shader doesn't recompile.
 		this._sourceTexNode = new TextureNode();
 
@@ -63,10 +74,117 @@ export class Compositor extends RenderStage {
 
 	}
 
+	/**
+	 * Builds (or rebuilds) the convergence-overlay material.
+	 *
+	 * Re-derives FinalWrite's own convergence predicate from the accumulated colour (the running mean)
+	 * and the m2 buffer (its running second moment), so what is painted IS the decision the renderer
+	 * makes — nothing is recomputed differently or written back.
+	 *
+	 * @returns {boolean} True when a material is ready to render.
+	 */
+	_ensureDebugMaterial() {
+
+		const src = this._pathTracer?.getConvergenceDebugSource?.();
+		if ( ! src ) return false;
+
+		// The buffers are only reallocated when the render reserve grows; rebind when that happens.
+		if ( this._debugMaterial && this._debugM2Attr === src.m2 && this._debugMaskAttr === src.frozenMask ) return true;
+
+		this._debugMaterial?.dispose();
+		this._debugTexNode?.dispose();
+
+		this._debugM2Attr = src.m2;
+		this._debugMaskAttr = src.frozenMask;
+		this._debugTexNode = new TextureNode();
+
+		// Must stay one Fn body: as a raw node graph TSL emits a .toVar() inside the FIRST branch that demands
+		// it, and sibling branches then read an unassigned var<private>.
+		const overlayColor = Fn( () => {
+
+			const texel = this._debugTexNode.sample( uv() ).toVar();
+			const lum = dot( texel.xyz, REC709_LUMINANCE_COEFFICIENTS ).toVar();
+
+			// The overlay draws at canvas size, the buffers are indexed at render size — go through the pixel index.
+			const w = src.renderWidth;
+			const h = src.renderHeight;
+			const ix = int( uv().x.mul( float( w ) ) ).min( w.sub( int( 1 ) ) ).max( int( 0 ) );
+			const iy = int( uv().y.mul( float( h ) ) ).min( h.sub( int( 1 ) ) ).max( int( 0 ) );
+			const pixelId = uint( iy.mul( w ).add( ix ) ).toVar();
+
+			const m2 = storage( src.m2, 'float' ).toReadOnly().element( pixelId ).toVar();
+			const frozenFlag = storage( src.frozenMask, 'uint' ).toReadOnly().element( pixelId ).toVar();
+
+			const sampleVar = m2.sub( lum.mul( lum ) ).max( float( 0 ) );
+			const absSE = sampleVar.div( float( src.frame ).add( 1.0 ) ).sqrt().toVar();
+
+			// Freeze bars on the raw relative error; the whole-frame stop bars on the √-normalized one.
+			// Show whichever is actually steering the render.
+			const freezeOn = src.usePixelFreeze.greaterThan( int( 0 ) );
+			const convNorm = select( lum.lessThan( float( 1.0 ) ), lum.sqrt(), lum ).toVar();
+			const err = select( freezeOn, absSE.div( lum.add( float( 1e-4 ) ) ), absSE.div( convNorm.add( float( 1e-4 ) ) ) ).toVar();
+			const bar = select( freezeOn, src.pixelFreezeThreshold, src.noiseThreshold ).toVar();
+			const ratio = err.div( bar.max( float( 1e-6 ) ) ).toVar();
+
+			// Dim tone-mapped grayscale so scene structure stays readable under the overlay.
+			const base = vec3( lum.div( lum.add( float( 1.0 ) ) ).sqrt().mul( 0.55 ) ).toVar();
+			const out = base.toVar();
+
+			// Below minSamples the variance is untrustworthy — at frame 0 it is identically zero, which would
+			// paint a converged image over pure noise.
+			const eligible = float( src.frame ).greaterThanEqual( float( src.adaptiveMinSamples ) );
+
+			If( ratio.greaterThanEqual( float( 1.0 ) ).or( eligible.not() ), () => {
+
+				const heat = mix( vec3( 1.0, 0.8, 0.1 ), vec3( 1.0, 0.1, 0.05 ), ratio.sub( 1.0 ).div( 3.0 ).clamp( 0.0, 1.0 ) );
+				out.assign( mix( base, heat, 0.85 ) );
+
+			} );
+
+			// Frozen wins: these are the pixels the renderer actually skipped, dilation halo included.
+			If( frozenFlag.equal( uint( 1 ) ).and( freezeOn ), () => {
+
+				out.assign( mix( base, vec3( 0.1, 0.45, 1.0 ), 0.55 ) );
+
+			} );
+
+			return out;
+
+		} );
+
+		// Undo the output pass's exposure (tone-mapped configs only) and linear→sRGB so the palette reads the
+		// same at any exposure.
+		this._debugMaterial = new MeshBasicNodeMaterial();
+		this._debugMaterial.colorNode = vec4( overlayColor().pow( 2.2 ).mul( this._debugExposureComp ), 1.0 );
+		this._debugMaterial.blending = NoBlending;
+		this._debugQuad = new QuadMesh( this._debugMaterial );
+
+		return true;
+
+	}
+
 	render( context ) {
 
 		if ( ! this.enabled ) return;
 
+		if ( this._convergenceOverlay && this._ensureDebugMaterial() ) {
+
+			// The error estimate is paired with the raw accumulated colour, not a denoised derivative.
+			const ptColor = context.getTexture( 'pathtracer:color' );
+			if ( ptColor ) {
+
+				this._debugTexNode.value = ptColor;
+				const exposed = this.renderer.toneMapping !== NoToneMapping;
+				this._debugExposureComp.value = exposed ? 1 / Math.max( this.renderer.toneMappingExposure, 1e-4 ) : 1;
+
+				this.renderer.setRenderTarget( null );
+				this._debugQuad.render( this.renderer );
+				return;
+
+			}
+
+		}
+
 		const sourceTexture = this._resolveSourceTexture( context );
 		if ( ! sourceTexture ) return;
 
@@ -77,6 +195,12 @@ export class Compositor extends RenderStage {
 
 	}
 
+	setConvergenceOverlay( enabled ) {
+
+		this._convergenceOverlay = !! enabled;
+
+	}
+
 	setSaturation( value ) {
 
 		this.saturation.value = value;
@@ -93,8 +217,14 @@ export class Compositor extends RenderStage {
 
 		this._sourceTexNode?.dispose();
 		this.compositorMaterial?.dispose();
+		this._debugTexNode?.dispose();
+		this._debugMaterial?.dispose();
 		// QuadMesh extends Mesh — no dispose method; material already released above.
 		this.compositorQuad = null;
+		this._debugQuad = null;
+		this._debugMaterial = null;
+		this._debugTexNode = null;
+		this._pathTracer = null;
 
 	}