rayzee 11.3.0 → 11.4.0

package/dist/{sceneCachePolicy-BAib5fCp.js → sceneCachePolicy-AKOEu2lf.js}

@@ -1594,7 +1594,7 @@ var vt = class {
 			samples: this.samples.slice()
 		};
 	}
-}, yt = "11.3.0", $ = 1e4, bt = 15e5;
+}, yt = "11.4.0", $ = 1e4, bt = 15e5;
 function xt(e, t, n = $) {
 	return e >= n && t / bt < e / 3;
 }

package/package.json

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

package/src/EngineDefaults.js

@@ -24,8 +24,8 @@ export const ENGINE_DEFAULTS = deepFreeze( {
 
 	// Sampling and convergence
 	maxSamples: 60,
-	renderLimitMode: 'frames',
-	renderTimeLimit: 30,
+	renderLimitMode: 'frames', // 'frames' | 'time' (ceiling or deadline, whichever first) | 'timeOnly' (deadline lifts the ceiling)
+	renderTimeLimit: 30, // seconds; read in 'time' and 'timeOnly'
 	renderMode: 0, // 0 preview, 1 production; configureForMode() sets it
 	useAdaptiveSampling: true,
 	noiseThreshold: 0.1, // a pixel under this √-luminance noise has converged; the interactive tier's value

package/src/Passes/AIUpscaler.js

@@ -100,6 +100,7 @@ export class AIUpscaler extends EventDispatcher {
 		this.getExposure = options.getExposure || ( () => 1.0 );
 		this.getToneMapping = options.getToneMapping || ( () => ACESFilmicToneMapping );
 		this.getSaturation = options.getSaturation || ( () => 1.0 );
+		this.getDisplayGain = options.getDisplayGain || ( () => null );
 
 		// Configuration
 		this.enabled = false;
@@ -497,6 +498,7 @@ export class AIUpscaler extends EventDispatcher {
 			exposure: this.getExposure(),
 			toneMapping: this.getToneMapping() ?? ACESFilmicToneMapping,
 			saturation: this.getSaturation(),
+			gain: this.getDisplayGain(),
 		} );
 		this._toneMapper.release();
 

package/src/PathTracerApp.js

@@ -8,6 +8,7 @@ import { Variance } from './Stages/Variance.js';
 import { BilateralFilter } from './Stages/BilateralFilter.js';
 import { EdgeFilter } from './Stages/EdgeFilter.js';
 import { AutoExposure, AUTO_EXPOSURE_DEFAULTS } from './Stages/AutoExposure.js';
+import { LocalExposure, LOCAL_EXPOSURE_DEFAULTS } from './Stages/LocalExposure.js';
 import { PRODUCTION_RENDER_CONFIG, INTERACTIVE_RENDER_CONFIG, modePresetSettings } from './EngineDefaults.js';
 import { createLogger } from './utils/Logger.js';
 import { EngineEvents } from './EngineEvents.js';
@@ -156,10 +157,11 @@ export class PathTracerApp extends RayzeeRenderer {
 		stages.bilateralFilter = new BilateralFilter( renderer, { enabled: false } );
 		stages.edgeFilter = new EdgeFilter( renderer, { enabled: false } );
 		stages.autoExposure = new AutoExposure( renderer, { enabled: AUTO_EXPOSURE_DEFAULTS.autoExposure } );
+		stages.localExposure = new LocalExposure( renderer, { enabled: LOCAL_EXPOSURE_DEFAULTS.localExposure } );
 
 		return [
 			stages.normalDepth, stages.motionVector, stages.nrd, stages.asvgf,
-			stages.variance, stages.bilateralFilter, stages.edgeFilter, stages.autoExposure,
+			stages.variance, stages.bilateralFilter, stages.edgeFilter, stages.autoExposure, stages.localExposure,
 		];
 
 	}
@@ -325,10 +327,11 @@ export class PathTracerApp extends RayzeeRenderer {
 		const core = super._settingsBindings();
 		return {
 			...core,
-			// auto exposure drives the exposure while it is on, and restores this value when turned off
+			// the manual exposure, and the compensation on top of auto exposure while that is on
 			applyExposure: ( value ) => {
 
-				if ( ! this.stages.autoExposure?.enabled ) core.applyExposure( value );
+				if ( this.stages.autoExposure ) this.stages.autoExposure.setCompensation( value );
+				else core.applyExposure( value );
 
 			},
 			onCameraProjection: ( value ) => {
@@ -351,6 +354,7 @@ export class PathTracerApp extends RayzeeRenderer {
 
 		this.timeline.update();
 		this.cameraManager.updateControls();
+		this._updateExposure();
 
 		this._applyPendingRenderScale();
 
@@ -406,6 +410,8 @@ export class PathTracerApp extends RayzeeRenderer {
 	// Render completion → denoise/upscale chain
 	_renderCompleted() {
 
+		// _finishImage() landed the exposure just before, with the loop already asleep: draw it.
+		if ( this.stages.autoExposure?.enabled ) this._refreshFinished();
 		this.denoisingManager.onRenderComplete( {
 			isStillComplete: () => this.completion.renderCompleteDispatched,
 			context: this.pipeline?.context,
@@ -413,6 +419,65 @@ export class PathTracerApp extends RayzeeRenderer {
 
 	}
 
+	_settling() {
+
+		return !! this.stages.autoExposure?.settling;
+
+	}
+
+	_displayGain() {
+
+		const le = this.stages.localExposure;
+		// A readback outside the loop (headless) can come before the loop would have built it from this image.
+		if ( le?.wantsBuild ) le.build( this.pipeline.context );
+		return le?.toneGain() ?? null;
+
+	}
+
+	/**
+	 * Local exposure (Unreal Engine 5's): scales the contrast of large bright and dark areas around middle grey
+	 * while keeping detail, on the canvas and every tone-mapped readback alike.
+	 * @param {boolean} enabled
+	 */
+	setLocalExposure( enabled ) {
+
+		const le = this.stages.localExposure;
+		if ( ! le ) return;
+		le.setEnabled( enabled );
+		this.stages.compositor.setDisplayGain( enabled ? ( rgb, uv ) => le.gainNode( rgb, uv ) : null );
+		this.refreshFrame();
+
+	}
+
+	/** @param {{highlightContrast?: number, shadowContrast?: number, detailStrength?: number}} params - 1 changes nothing */
+	setLocalExposureParams( params ) {
+
+		this.stages.localExposure?.updateParameters( params );
+
+	}
+
+	// A finished render is exposed for its own image: one reading of it, landed on.
+	_finishImage() {
+
+		const ae = this.stages.autoExposure;
+		if ( ! ae?.enabled ) return null;
+		return ae.meter( this.pipeline.context ).then( () => ae.advance( Infinity ) );
+
+	}
+
+	/** The core's, plus the display-only exposure an sRGB readback was shaped by, which no setting records. */
+	getProvenance() {
+
+		const provenance = super.getProvenance();
+		const ae = this.stages.autoExposure, le = this.stages.localExposure;
+		provenance.exposure = {
+			auto: ae?.enabled ? { exposure: ae.getExposure(), strength: ae.strength, metering: ae.metering, keyValue: ae.keyValue } : null,
+			local: le?.enabled ? { highlightContrast: le.highlightContrast, shadowContrast: le.shadowContrast, detailStrength: le.detailStrength } : null,
+		};
+		return provenance;
+
+	}
+
 	_renderHelperOverlay() {
 
 		super._renderHelperOverlay();
@@ -550,7 +615,7 @@ export class PathTracerApp extends RayzeeRenderer {
 		if ( enabled ) {
 
 			this.cameraManager?.setAutoFocusMode( 'manual' );
-			if ( this.stages.autoExposure ) this.stages.autoExposure.enabled = false;
+			this.stages.autoExposure?.setEnabled( false );
 			// Cadence denoising is wall-clock driven, so which frame it lands on is not reproducible.
 			this.denoisingManager?.setContinuousDenoise( false );
 			return;
@@ -558,11 +623,7 @@ export class PathTracerApp extends RayzeeRenderer {
 		}
 
 		if ( snapshot.autoFocusMode !== undefined ) this.cameraManager?.setAutoFocusMode( snapshot.autoFocusMode );
-		if ( this.stages.autoExposure && snapshot.autoExposure !== undefined ) {
-
-			this.stages.autoExposure.enabled = snapshot.autoExposure;
-
-		}
+		if ( snapshot.autoExposure !== undefined ) this.stages.autoExposure?.setEnabled( snapshot.autoExposure );
 
 		if ( snapshot.continuousDenoise !== undefined ) {
 
@@ -839,6 +900,9 @@ export class PathTracerApp extends RayzeeRenderer {
 
 		this.timeline.stop();
 		this.cameraManager.controls.enabled = ! isProduction;
+		// A final render keeps the exposure it starts with through its first, noisiest samples (20 bounces: a 0.4-stop
+		// dip and back within 0.2 s at 2–8 samples), then lands as any still image does.
+		if ( this.stages.autoExposure ) this.stages.autoExposure.holdSamples = isProduction ? 8 : 0;
 
 		// Anything with a SETTING_ROUTES entry must go through settings, not setUniform: set() early-returns on
 		// `prev === value`, so a uniform written behind the map leaves it stale and the next set() silently no-ops.
@@ -1053,6 +1117,7 @@ export class PathTracerApp extends RayzeeRenderer {
 			pipeline: this.pipeline,
 			getExposure: () => this.settings.get( 'exposure' ) ?? 1.0,
 			getSaturation: () => this.settings.get( 'saturation' ) ?? 1.0,
+			getDisplayGain: () => this._displayGain(),
 			issues: this._issues,
 		} );
 
@@ -1072,20 +1137,61 @@ export class PathTracerApp extends RayzeeRenderer {
 
 	_setupAutoExposureListener() {
 
-		if ( ! this.stages.autoExposure ) return;
+		const ae = this.stages.autoExposure;
+		if ( ! ae ) return;
 
-		this.stages.autoExposure.on( 'autoexposure:updated', ( data ) => {
+		ae.setCompensation( this.settings.get( 'exposure' ) ?? 1 );
+		if ( this.stages.localExposure ) this.stages.localExposure.onChange = () => this._refreshFinished();
+		ae.onChange = () => this._refreshFinished();
 
-			this.dispatchEvent( {
-				type: EngineEvents.AUTO_EXPOSURE_UPDATED,
-				exposure: data.exposure,
-				luminance: data.luminance
-			} );
+		// Another camera is a cut: meter it afresh.
+		this._addTrackedListener( this.cameraManager, EngineEvents.CAMERA_SWITCHED, () => ae.resetHistory() );
+
+		ae.on( 'autoexposure:updated', ( { exposure, autoExposure, targetExposure, luminance } ) => {
+
+			this.dispatchEvent( { type: EngineEvents.AUTO_EXPOSURE_UPDATED, exposure, autoExposure, targetExposure, luminance } );
 
 		} );
 
 	}
 
+	// Only a finished render's idle loop is woken: renderFrames() and a video export drive frames themselves.
+	_refreshFinished() {
+
+		if ( ! this.completion.renderCompleteDispatched ) return;
+		this._needsDisplayRefresh = true;
+		this.wake();
+
+	}
+
+	// Every loop frame, a finished render included: builds local exposure and meters a finished image when asked, adapts.
+	_updateExposure() {
+
+		const le = this.stages.localExposure;
+		if ( le?.wantsBuild && this.completion.renderCompleteDispatched ) le.build( this.pipeline.context );
+
+		const ae = this.stages.autoExposure;
+		if ( ! ae?.enabled ) return;
+
+		this._noteExposureView();
+		const af = this.cameraManager.afScreenPoint;
+		if ( ae.metering === 'spot' && ( ae.meteringPoint.x !== af.x || ae.meteringPoint.y !== af.y ) ) ae.updateParameters( { meteringPoint: af } );
+		if ( ae.wantsMetering && this.completion.renderCompleteDispatched ) ae.meter( this.pipeline.context );
+		if ( ae.update() ) this._needsDisplayRefresh = true;
+
+	}
+
+	// Whatever moved the camera (controls, walk, timeline, a video export), auto exposure learns of it here.
+	_noteExposureView() {
+
+		const { matrixWorld, projectionMatrix } = this.camera;
+		const last = this._exposureView;
+		if ( last?.view.equals( matrixWorld ) && last.projection.equals( projectionMatrix ) ) return;
+		this._exposureView = { view: matrixWorld.clone(), projection: projectionMatrix.clone() };
+		if ( last ) this.stages.autoExposure?.noteViewChanged();
+
+	}
+
 	async _setupOverlayManager() {
 
 		this.overlayManager = new OverlayManager( this.cameraManager.camera );

package/src/Pipeline/CompletionTracker.js

@@ -33,20 +33,24 @@ export class CompletionTracker {
 
 	/**
 	 * Checks whether the wall-clock render budget has expired. An additional stop condition,
-	 * never a replacement — the sample ceiling and convergence still bind when they come first.
+	 * never a replacement — convergence still binds when it comes first, and in 'time' mode the
+	 * sample ceiling too ('timeOnly' lifts it: PathTracerStage.updateCompletionThreshold).
 	 *
 	 * Floored at one sample: frameCount does not advance while the stage compiles kernels or
 	 * while the camera is in interaction mode, and retiring in that window denoises an empty
 	 * buffer and captures a blank canvas.
 	 *
 	 * @param {Object} pathTracer - The PathTracer stage
-	 * @param {string} renderLimitMode - 'time' or 'frames'
+	 * @param {string} renderLimitMode - 'frames', 'time' or 'timeOnly'
 	 * @param {number} renderTimeLimit - Time limit in seconds
 	 * @returns {boolean}
 	 */
 	isTimeLimitReached( pathTracer, renderLimitMode, renderTimeLimit ) {
 
-		if ( renderLimitMode !== 'time' || ! ( renderTimeLimit > 0 ) ) return false;
+		// Decided afresh on every check: a raised limit or a switch to 'frames' reopens a render the deadline retired.
+		this.budgetOverrun = false;
+
+		if ( ( renderLimitMode !== 'time' && renderLimitMode !== 'timeOnly' ) || ! ( renderTimeLimit > 0 ) ) return false;
 		if ( this.timeElapsed < renderTimeLimit ) return false;
 
 		if ( ! ( pathTracer?.frameCount > 0 ) ) {

package/src/Processor/ToneMapCPU.js

@@ -128,21 +128,33 @@ export function applySaturation( out, saturation ) {
  * @param {number} options.toneMapping - a registered view transform id
  * @param {number} [options.saturation=1]
  * @param {boolean} [options.preserveAlpha=false]
+ * @param {{fn: function(number, number, number, number): number, width: number, height: number}} [options.pixelGain] -
+ *   the twin of the GPU pass's `gain`: `fn( u, v, luminance, log2 exposure )` per pixel, before the curve
  * @returns {Uint8ClampedArray} RGBA bytes
  */
-export function toneMapToRGBA8( linear, { exposure, toneMapping, saturation = 1, preserveAlpha = false } ) {
+export function toneMapToRGBA8( linear, { exposure, toneMapping, saturation = 1, preserveAlpha = false, pixelGain = null } ) {
 
 	const curve = TONE_MAP_FNS.get( toneMapping ) ?? TONE_MAP_FNS.get( NoToneMapping );
 	const gain = effectiveExposure( exposure, toneMapping );
 	const encoded = isOutputEncoded( toneMapping );
 	const out = new Uint8ClampedArray( linear.length );
 	const scratch = [ 0, 0, 0 ];
+	const logExposure = Math.log2( exposure );
 
 	for ( let i = 0; i < linear.length; i += 4 ) {
 
-		scratch[ 0 ] = linear[ i ] * gain;
-		scratch[ 1 ] = linear[ i + 1 ] * gain;
-		scratch[ 2 ] = linear[ i + 2 ] * gain;
+		let g = gain;
+		if ( pixelGain ) {
+
+			const p = i >> 2, x = p % pixelGain.width, y = ( p - x ) / pixelGain.width;
+			const lum = linear[ i ] * 0.2126 + linear[ i + 1 ] * 0.7152 + linear[ i + 2 ] * 0.0722;
+			g *= pixelGain.fn( ( x + 0.5 ) / pixelGain.width, ( y + 0.5 ) / pixelGain.height, lum, logExposure );
+
+		}
+
+		scratch[ 0 ] = linear[ i ] * g;
+		scratch[ 1 ] = linear[ i + 1 ] * g;
+		scratch[ 2 ] = linear[ i + 2 ] * g;
 
 		applySaturation( scratch, saturation );
 		curve( scratch[ 0 ], scratch[ 1 ], scratch[ 2 ], 1.0, scratch );

package/src/Processor/ToneMapGPU.js

@@ -88,7 +88,7 @@ fn rayzee_store( i: u32, linear: vec4<f32>, mapped: vec3<f32> ) {
 
 const BYTES_PER_PIXEL = { rgba8: 4, planar: 16 };
 
-const toneMapPassWGSL = ( transformWGSL, input, output ) => /* wgsl */ `
+const toneMapPassWGSL = ( transformWGSL, input, output, gainWGSL ) => /* wgsl */ `
 struct Params {
 	width: u32,
 	height: u32,
@@ -104,6 +104,7 @@ ${SOURCES[ input ]}
 
 ${transformWGSL}
 ${OUTPUTS[ output ]}
+${gainWGSL ?? ''}
 
 @compute @workgroup_size(8, 8)
 fn main( @builtin(global_invocation_id) gid: vec3<u32> ) {
@@ -113,7 +114,9 @@ fn main( @builtin(global_invocation_id) gid: vec3<u32> ) {
 	if ( params.flipY == 1u ) { srcY = params.height - 1u - gid.y; }
 
 	let linear = rayzee_source( gid.x, srcY );
-	rayzee_store( gid.y * params.width + gid.x, linear, rayzee_tone_map( linear.rgb, params.mode, params.exposure, params.saturation ) );
+	let uv = vec2<f32>( ( f32( gid.x ) + 0.5 ) / f32( params.width ), ( f32( gid.y ) + 0.5 ) / f32( params.height ) );
+	let rgb = linear.rgb${gainWGSL ? ' * rayzee_gain( uv, linear.rgb, params.exposure )' : ''};
+	rayzee_store( gid.y * params.width + gid.x, linear, rayzee_tone_map( rgb, params.mode, params.exposure, params.saturation ) );
 }
 `;
 
@@ -136,7 +139,7 @@ export class PackedToneMapper {
 		this.output = output;
 		this.width = 0;
 		this.height = 0;
-		this._pipeline = null;
+		this._pipelines = new Map();
 		this._storage = null;
 		this._map = null;
 		this._params = null;
@@ -157,21 +160,31 @@ export class PackedToneMapper {
 	 * heard of. Without this the readback silently falls through to the clamp and a saved image
 	 * comes back untone-mapped.
 	 */
-	_ensurePipeline() {
+	_ensurePipeline( gain = null ) {
 
 		const { wgsl, bindings, version } = currentShader();
-		if ( this._pipeline && this._shaderVersion === version ) return;
+		if ( this._shaderVersion !== version ) {
 
-		this._bindings = bindings;
-		this._shaderVersion = version;
-		this._pipeline = this.device.createComputePipeline( {
+			this._pipelines.clear();
+			this._bindings = bindings;
+			this._shaderVersion = version;
+
+		}
+
+		const key = gain?.key ?? '';
+		let pipeline = this._pipelines.get( key );
+		if ( pipeline ) return pipeline;
+
+		pipeline = this.device.createComputePipeline( {
 			label: this.label,
 			layout: 'auto',
 			compute: {
-				module: this.device.createShaderModule( { label: this.label, code: toneMapPassWGSL( wgsl, this.input, this.output ) } ),
+				module: this.device.createShaderModule( { label: this.label, code: toneMapPassWGSL( wgsl, this.input, this.output, gain?.wgsl ) } ),
 				entryPoint: 'main',
 			},
 		} );
+		this._pipelines.set( key, pipeline );
+		return pipeline;
 
 	}
 
@@ -262,6 +275,8 @@ export class PackedToneMapper {
 	 * @param {number} [tone.saturation=1]
 	 * @param {boolean} [tone.flipY=false]
 	 * @param {boolean} [tone.preserveAlpha=false] - the source's alpha, rounded as the CPU rounds it; else 255
+	 * @param {{key: string, wgsl: string, entries: GPUBindGroupEntry[]}} [tone.gain] - a per-pixel gain before the
+	 *   curve: WGSL defining `rayzee_gain( uv, linear, exposure ) -> f32` over bind group 1
 	 * @returns {Promise<Uint8ClampedArray>} RGBA bytes, `width * height * 4`
 	 */
 	async toRGBA8( src, tone ) {
@@ -283,14 +298,14 @@ export class PackedToneMapper {
 
 	}
 
-	async _run( src, { exposure = 1, toneMapping = 0, saturation = 1, flipY = false, preserveAlpha = false } = {} ) {
+	async _run( src, { exposure = 1, toneMapping = 0, saturation = 1, flipY = false, preserveAlpha = false, gain = null } = {} ) {
 
 		if ( this.disposed ) throw new Error( 'PackedToneMapper: disposed' );
 		if ( ! this._storage ) throw new Error( 'PackedToneMapper: call ensureSize() first' );
 
 		// A config can be loaded between two readbacks, so the registry is re-checked here rather
 		// than only on resize.
-		this._ensurePipeline();
+		const pipeline = this._ensurePipeline( gain );
 		this._ensureTables();
 
 		const { width, height } = this;
@@ -309,7 +324,7 @@ export class PackedToneMapper {
 			.map( ( [ binding, held ] ) => ( { binding, resource: held.view } ) );
 
 		const group = this.device.createBindGroup( {
-			layout: this._pipeline.getBindGroupLayout( 0 ),
+			layout: pipeline.getBindGroupLayout( 0 ),
 			entries: [
 				...tableEntries,
 				{ binding: 0, resource: this.input === 'texture' ? src.createView() : { buffer: src, size: width * height * 8 } },
@@ -320,8 +335,9 @@ export class PackedToneMapper {
 
 		const encoder = this.device.createCommandEncoder( { label: this.label } );
 		const pass = encoder.beginComputePass();
-		pass.setPipeline( this._pipeline );
+		pass.setPipeline( pipeline );
 		pass.setBindGroup( 0, group );
+		if ( gain ) pass.setBindGroup( 1, this.device.createBindGroup( { layout: pipeline.getBindGroupLayout( 1 ), entries: gain.entries } ) );
 		pass.dispatchWorkgroups( Math.ceil( width / 8 ), Math.ceil( height / 8 ) );
 		pass.end();
 		encoder.copyBufferToBuffer( this._storage, 0, this._map, 0, bytes );
@@ -360,7 +376,7 @@ export class PackedToneMapper {
 		this._releaseBuffers();
 		for ( const held of this._tables.values() ) held.texture.destroy();
 		this._tables.clear();
-		this._pipeline = null;
+		this._pipelines.clear();
 
 	}
 

package/src/RayzeeRenderer.js

@@ -532,6 +532,13 @@ export class RayzeeRenderer extends EventDispatcher {
 
 				}
 
+				if ( this._settling() ) {
+
+					this.dispatchEvent( { type: EngineEvents.FRAME } );
+					return;
+
+				}
+
 				// Stop the loop to avoid constant CPU usage while idle
 				this.stopAnimation();
 				return;
@@ -558,12 +565,7 @@ export class RayzeeRenderer extends EventDispatcher {
 
 			this._traceFrame( { liveDenoise: true } );
 
-			if ( this.stages.pathTracer.isComplete && this.completion.markComplete() ) {
-
-				this._renderCompleted();
-				this.dispatchEvent( { type: EngineEvents.RENDER_COMPLETE, ...this._completionInfo() } );
-
-			}
+			if ( this.stages.pathTracer.isComplete && this.completion.markComplete() ) this._announceComplete();
 
 		}
 
@@ -572,6 +574,25 @@ export class RayzeeRenderer extends EventDispatcher {
 
 	}
 
+	// The closing passes and RENDER_COMPLETE wait for _finishImage(), so both see the finished image's exposure.
+	_announceComplete() {
+
+		const info = this._completionInfo();
+		const restarts = this.stages.pathTracer.resetCount;
+		const announce = () => {
+
+			if ( ! this.completion.renderCompleteDispatched || this.stages.pathTracer?.resetCount !== restarts ) return;
+			this._renderCompleted();
+			this.dispatchEvent( { type: EngineEvents.RENDER_COMPLETE, ...info } );
+
+		};
+
+		const finishing = this._finishImage();
+		if ( finishing ) finishing.then( announce, announce );
+		else announce();
+
+	}
+
 	// One frame of a render and its bookkeeping, shared by animate() and renderUntilComplete().
 	_traceFrame( { liveDenoise = false } = {} ) {
 
@@ -2499,6 +2520,7 @@ export class RayzeeRenderer extends EventDispatcher {
 
 		}
 
+		await this._finishImage();
 		return stage.frameCount;
 
 	}
@@ -2576,6 +2598,8 @@ export class RayzeeRenderer extends EventDispatcher {
 			}
 
 			const info = this._completionInfo();
+			// Before it is announced: a listener reading pixels sees the finished image's exposure.
+			await this._finishImage();
 			if ( this.completion.markComplete() ) this.dispatchEvent( { type: EngineEvents.RENDER_COMPLETE, ...info } );
 
 			const denoised = denoise ? await this._finalDenoise() : false;
@@ -2735,12 +2759,14 @@ export class RayzeeRenderer extends EventDispatcher {
 				toneMapping: this.renderer.toneMapping,
 				saturation: this.settings.get( 'saturation' ) ?? 1,
 				preserveAlpha,
+				gain: this._displayGain(),
 			};
 
 			const gpu = await this._toneMapOnGPU( shown?.texture ?? null, target, width, height, tone );
+			const fn = ! gpu && tone.gain ? await tone.gain.cpu() : null;
 			const data = gpu ?? toneMapToRGBA8( shown
 				? await this._readTexture( shown.texture, width, height )
-				: await this.renderer.readRenderTargetPixelsAsync( target, 0, 0, width, height, 0 ), tone );
+				: await this.renderer.readRenderTargetPixelsAsync( target, 0, 0, width, height, 0 ), { ...tone, pixelGain: fn && { fn, width, height } } );
 			return { data, width, height, colorSpace, source: shown?.source ?? 'accumulation', toneMappedOn: gpu ? 'gpu' : 'cpu' };
 
 		}
@@ -3982,6 +4008,20 @@ export class RayzeeRenderer extends EventDispatcher {
 	/** Once, on the loop frame the render completes. */
 	_renderCompleted() {}
 
+	/** True keeps the loop running over a finished render, to redraw what is still changing. */
+	_settling() {
+
+		return false;
+
+	}
+
+	/** A render has its samples, before any closing pass or announcement: a promise to wait for, or null. */
+	_finishImage() {
+
+		return null;
+
+	}
+
 	/** Draws what sits over the image. Here only brings the light scene's matrices up to date. */
 	_renderHelperOverlay() {
 
@@ -4032,6 +4072,13 @@ export class RayzeeRenderer extends EventDispatcher {
 
 	}
 
+	/** A per-pixel gain the shown picture carries before the view (the compositor's), for tone-mapped readbacks; or null. */
+	_displayGain() {
+
+		return null;
+
+	}
+
 	/** Whether a 'display' read should find a processed picture. */
 	_denoiserInUse() {
 

package/src/RenderSettings.js

@@ -258,7 +258,7 @@ export class RenderSettings extends EventDispatcher {
 
 			handleRenderLimitMode: ( value ) => {
 
-				stages.pathTracer?.setRenderLimitMode?.( value );
+				stages.pathTracer?.setRenderLimitMode?.( value, this.get( 'renderTimeLimit' ) );
 				reconcileCompletion?.();
 
 			},
@@ -271,8 +271,10 @@ export class RenderSettings extends EventDispatcher {
 
 			},
 
-			handleRenderTimeLimit: () => {
+			// Arming or disarming the deadline lifts or restores the ceiling in 'timeOnly'.
+			handleRenderTimeLimit: ( value ) => {
 
+				stages.pathTracer?.setRenderLimitMode?.( this.get( 'renderLimitMode' ), value );
 				reconcileCompletion?.();
 
 			},