rayzee 11.3.0 → 11.5.0

package/src/index.js

@@ -68,6 +68,7 @@ export {
 } from './Stages/DenoiserSettings.js';
 export { SKY_DEFAULTS, DEFAULT_SUN_PATH } from './managers/EnvironmentManager.js';
 export { AUTO_EXPOSURE_DEFAULTS } from './Stages/AutoExposure.js';
+export { LOCAL_EXPOSURE_DEFAULTS } from './Stages/LocalExposure.js';
 export { AUTO_FOCUS_DEFAULTS } from './managers/CameraManager.js';
 export { TRIANGLE_DATA_LAYOUT, BVH_LEAF_MARKERS } from './Processor/BufferLayout.js';
 export { sunPosition, timeForSunElevation, dayOfYearForMonth } from './Processor/SunPosition.js';

package/src/managers/DenoisingManager.js

@@ -104,9 +104,10 @@ export class DenoisingManager extends EventDispatcher {
 	 * @param {import('../Pipeline/RenderPipeline.js').RenderPipeline} params.pipeline
 	 * @param {Function}                               params.getExposure       - () => current exposure value
 	 * @param {Function}                               params.getSaturation     - () => current saturation value
+	 * @param {Function}                               [params.getDisplayGain]  - () => the shown picture's per-pixel gain (PackedToneMapper `gain`)
 	 * @param {import('../EngineIssues.js').IssueLog}  [params.issues]
 	 */
-	constructor( { renderer, mainCanvas, stages, pipeline, getExposure, getSaturation, issues = null } ) {
+	constructor( { renderer, mainCanvas, stages, pipeline, getExposure, getSaturation, getDisplayGain = null, issues = null } ) {
 
 		super();
 
@@ -121,6 +122,7 @@ export class DenoisingManager extends EventDispatcher {
 
 		this._getExposure = getExposure;
 		this._getSaturation = getSaturation;
+		this._getDisplayGain = getDisplayGain;
 
 		this.denoiser = null;
 		this.upscaler = null;
@@ -135,6 +137,11 @@ export class DenoisingManager extends EventDispatcher {
 		this._retouch = null;
 		this._superResModule = null;
 		this._neuralPostBusy = false;
+		// The finished render's post passes: its guard, the run in flight, a queued rerun, and a cancel.
+		this._postIsStillComplete = null;
+		this._postRun = null;
+		this._postRedo = null;
+		this._postCancelled = false;
 
 		// The tier the finished image uses. The loaded tier is not always this one: while the
 		// image is still accumulating we run a cheaper model (see previewQuality).
@@ -409,6 +416,7 @@ export class DenoisingManager extends EventDispatcher {
 			getExposure: () => this._getEffectiveExposure(),
 			getToneMapping: () => this._getToneMapping(),
 			getSaturation: () => this._getSaturation(),
+			getDisplayGain: () => this._getDisplayGain?.() ?? null,
 		} );
 
 		this.upscaler.enabled = DENOISER_DEFAULTS.enableUpscaler || false;
@@ -546,21 +554,11 @@ export class DenoisingManager extends EventDispatcher {
 
 	/**
 	 * @param {boolean} enabled
-	 * @param {number}  manualExposure - Restored to renderer.toneMappingExposure when disabling.
+	 * @param {number}  manualExposure - the compensation while on, the exposure again once off
 	 */
 	setAutoExposureEnabled( enabled, manualExposure ) {
 
-		const s = this._stages;
-		if ( ! s.autoExposure ) return;
-
-		s.autoExposure.enabled = enabled;
-
-		// AutoExposure overwrites renderer.toneMappingExposure each frame; restore manual on disable.
-		if ( ! enabled && this.renderer ) {
-
-			this.renderer.toneMappingExposure = manualExposure;
-
-		}
+		this._stages.autoExposure?.setEnabled( enabled, manualExposure );
 
 	}
 
@@ -1155,6 +1153,7 @@ export class DenoisingManager extends EventDispatcher {
 	/** Turns the neural-rendering (detail) pass on or off, and sets its appearance controls. */
 	setNeuralRendering( enabled, settings = null ) {
 
+		const changed = this.neuralRendering !== !! enabled;
 		this.neuralRendering = !! enabled;
 		if ( settings ) this.neuralRenderingSettings = { ...this.neuralRenderingSettings, ...settings };
 		if ( ! this.neuralRendering ) {
@@ -1164,6 +1163,8 @@ export class DenoisingManager extends EventDispatcher {
 
 		}
 
+		if ( changed ) this._redoPostPasses();
+
 	}
 
 	_releaseNeuralRetouch() {
@@ -1174,14 +1175,8 @@ export class DenoisingManager extends EventDispatcher {
 	}
 
 	/**
-	 * The neural post-chain over the picture the closing denoise just produced: super resolution
-	 * first, then the detail pass, either or both.
-	 *
-	 * Order is forced by the models. Super resolution hands back light that can be fed onward; the
-	 * detail pass writes an `rgba8unorm` texture with no `COPY_SRC`, so nothing can read its result
-	 * and it has to be last — and it presents in its own display space rather than the engine's tone
-	 * curve. Which shape super resolution returns therefore depends on what follows it: packed
-	 * halves when the detail pass is next, display bytes when it is the end of the chain.
+	 * The post-chain over the picture the closing denoise just produced: the detail pass at render size,
+	 * then the chosen upscaler (neural super resolution or the ONNX one), either or both.
 	 *
 	 * Deliberately fire-and-forget: the render is already finished and a failure must not break it.
 	 */
@@ -1189,6 +1184,7 @@ export class DenoisingManager extends EventDispatcher {
 
 		const wantSR = this.upscaler?.enabled && this.upscalerBackend === 'neural';
 		const wantNR = this.neuralRendering;
+		const wantESRGAN = this.upscaler?.enabled && ! wantSR;
 		if ( ! wantSR && ! wantNR ) return;
 
 		// A second completion can land while the first pass is still in flight — the models are
@@ -1237,7 +1233,12 @@ export class DenoisingManager extends EventDispatcher {
 
 			}
 
-			if ( ! wantSR && ! runNR ) return;
+			if ( ! wantSR && ! runNR ) {
+
+				if ( wantESRGAN && ! this._postCancelled ) await this.upscaler.start();
+				return;
+
+			}
 
 			// Must be the effective value, not the settings one: AutoExposure overwrites
 			// `renderer.toneMappingExposure` every frame and never touches settings, so reading
@@ -1246,6 +1247,7 @@ export class DenoisingManager extends EventDispatcher {
 				exposure: this._getEffectiveExposure(),
 				toneMapping: this._getToneMapping(),
 				saturation: this._getSaturation?.() ?? 1,
+				gain: this._getDisplayGain?.() ?? null,
 			};
 
 			// Scene-referred throughout. Exposure reaches the detail pass through its own `paper_white`
@@ -1297,6 +1299,15 @@ export class DenoisingManager extends EventDispatcher {
 
 			}
 
+			if ( this._postRedo || this._postCancelled ) return;
+
+			if ( wantESRGAN ) {
+
+				await this.upscaler.start( new ImageData( image.rgba8, image.width, image.height ) );
+				return;
+
+			}
+
 			sr.presentRGBA8( this.upscalerCanvas, image.rgba8, image.width, image.height );
 
 			if ( ! isStillComplete() ) {
@@ -1366,10 +1377,61 @@ export class DenoisingManager extends EventDispatcher {
 
 	}
 
+	/** The neural chain or the ONNX upscaler over the finished render, as the switches ask. */
+	_runPostPasses( isStillComplete ) {
+
+		this._postIsStillComplete = isStillComplete;
+		this._postCancelled = false;
+
+		// The neural chain owns the overlay canvas when it runs, and hands its result to the ONNX upscaler.
+		if ( this.neuralRendering || ( this.upscaler?.enabled && this.upscalerBackend === 'neural' ) ) {
+
+			this._postRun = this._runNeuralPost( isStillComplete );
+
+		} else {
+
+			this._postRun = this.upscaler?.enabled ? this.upscaler.start() : null;
+
+		}
+
+	}
+
+	/** Runs the post passes again on a finished render whose switches changed, once the run in flight ends. */
+	_redoPostPasses() {
+
+		const isStillComplete = this._postIsStillComplete;
+		// No chain yet: the closing denoise is still running and the chain reads the switches when it starts.
+		if ( ! isStillComplete?.() || this._postRedo ) return;
+
+		this.upscaler?.abort();
+		this._postCancelled = false;
+		this._postRedo = Promise.resolve( this._postRun ).catch( () => {} ).then( () => {
+
+			this._postRedo = null;
+			if ( this._postCancelled || this._postIsStillComplete !== isStillComplete || ! isStillComplete() ) return;
+			this._restoreRenderDisplay();
+			this._runPostPasses( isStillComplete );
+
+		} );
+
+	}
+
+	/** Stops the post passes on the finished render, which stays on screen as rendered. The switches stay as they are. */
+	cancelPostPasses() {
+
+		this._postCancelled = true;
+		this.upscaler?.abort();
+		this._restoreRenderDisplay();
+		// A retouch in flight cannot be stopped, only discarded, and ends later.
+		this.dispatchEvent( { type: EngineEvents.UPSCALING_END } );
+
+	}
+
 	onRenderComplete( { isStillComplete } ) {
 
 		// Remove any stale completion-chain listener from a previous render cycle
 		this._cleanupCompletionListener();
+		this._postIsStillComplete = null;
 
 		// What closes the render, if anything. A full pass at the chosen tier when that switch is
 		// on; otherwise, if OIDN owns the live view, one last cheap refresh — the cadence's last
@@ -1389,16 +1451,7 @@ export class DenoisingManager extends EventDispatcher {
 			// denoise. Ordered after `_denoiserEndHandler`, which publishes the picture.
 			if ( closing ) this._onDisplayRefresh?.();
 
-			// One owner of the overlay canvas, so the neural chain and the ONNX upscaler are
-			// exclusive. The neural chain also runs on its own when only its detail pass is on.
-			if ( this.neuralRendering || ( this.upscaler?.enabled && this.upscalerBackend === 'neural' ) ) {
-
-				this._runNeuralPost( isStillComplete );
-				return;
-
-			}
-
-			if ( this.upscaler?.enabled ) this.upscaler.start();
+			this._runPostPasses( isStillComplete );
 
 		};
 
@@ -1473,6 +1526,7 @@ export class DenoisingManager extends EventDispatcher {
 
 		// Remove stale completion-chain listener before aborting
 		this._cleanupCompletionListener();
+		this._postIsStillComplete = null;
 
 		// The 2D canvas is the upscaler's alone: a reset means its enlarged result no longer
 		// describes anything, so the render canvas comes back.
@@ -1515,6 +1569,7 @@ export class DenoisingManager extends EventDispatcher {
 
 		// Remove pending completion-chain listener
 		this._cleanupCompletionListener();
+		this._postIsStillComplete = null;
 		// Owns a second GPUDevice plus 3 MB of weights, so it must not outlive the manager.
 		this._releaseNeuralUpscaler();
 		this._releaseNeuralRetouch();
@@ -1561,6 +1616,9 @@ export class DenoisingManager extends EventDispatcher {
 		this._onReset = null;
 		this._onPostProcessRefresh = null;
 		this._onDisplayRefresh = null;
+		this._getExposure = null;
+		this._getSaturation = null;
+		this._getDisplayGain = null;
 		this._issues = null;
 
 		if ( this.upscalerCanvas?.parentNode ) {
@@ -1740,10 +1798,12 @@ export class DenoisingManager extends EventDispatcher {
 	/** Enables or disables the AI upscaler. */
 	setUpscalerEnabled( enabled ) {
 
+		const changed = !! this.upscaler && this.upscaler.enabled !== !! enabled;
 		if ( this.upscaler ) this.upscaler.enabled = enabled;
 		else if ( enabled ) this._recordNoOverlayCanvas( 'upscaler' );
 		// The enlarged picture describes a setting that is no longer on.
 		if ( ! enabled ) this._restoreRenderDisplay();
+		if ( changed ) this._redoPostPasses();
 
 	}
 
@@ -1764,13 +1824,12 @@ export class DenoisingManager extends EventDispatcher {
 	// ── Convenience (match DenoisingAPI names with reset) ────────
 
 	/**
-	 * Enables or disables auto-exposure (convenience wrapper).
+	 * Enables or disables auto-exposure. A finished render is metered as it stands, not restarted.
 	 * @param {boolean} enabled
 	 */
 	setAutoExposure( enabled ) {
 
 		this.setAutoExposureEnabled( enabled, this._getExposure() );
-		this._onReset?.();
 
 	}
 

package/src/managers/VideoRenderManager.js

@@ -87,8 +87,13 @@ export class VideoRenderManager {
 		// Configure for high-quality offline rendering
 		app.configureForMode( 'production' );
 
-		// Override samples per frame
-		app.settings.setMany( { maxSamples: samplesPerFrame }, { silent: true } );
+		// Auto exposure adapts in video time, once a frame, not to each pass's wall clock.
+		const autoExposure = app.stages.autoExposure?.enabled ? app.stages.autoExposure : null;
+		if ( autoExposure ) autoExposure.instant = false;
+
+		// Override samples per frame. 'frames': this loop never checks the deadline, so a 'timeOnly'
+		// ceiling of Infinity would never finish a frame.
+		app.settings.setMany( { maxSamples: samplesPerFrame, renderLimitMode: 'frames' }, { silent: true, reset: false } );
 		app.stages.pathTracer?.updateCompletionThreshold?.();
 
 		// Disable camera controls during render
@@ -131,11 +136,23 @@ export class VideoRenderManager {
 				// kill it immediately so it doesn't race with our manual render loop
 				app.stopAnimation();
 
+				// Before accumulating: the stage meters as it goes, and a reading of this frame's view filed under the last
+				// one read as a scene change, moving the room the whole way each frame.
+				if ( autoExposure ) app._noteExposureView();
+
 				// 3. Accumulate samples until convergence
 				await this._accumulateFrame( app );
 
 				if ( this._cancelled ) break;
 
+				if ( autoExposure ) {
+
+					await autoExposure.meter( app.pipeline.context );
+					autoExposure.advance( i === Math.max( 0, startFrame ) ? Infinity : frameDuration );
+					app._presentDisplay();
+
+				}
+
 				// 4. Denoise if enabled
 				if ( enableOIDN && app.denoisingManager?.finalDenoise ) {
 
@@ -298,17 +315,19 @@ export class VideoRenderManager {
 
 		const app = this._app;
 		const effective = app.settings.getEffective();
-		const keys = Object.keys( modePresetSettings( PRODUCTION_RENDER_CONFIG ) );
+		const keys = [ ...Object.keys( modePresetSettings( PRODUCTION_RENDER_CONFIG ) ), 'renderLimitMode' ];
 		if ( view ) keys.push( 'focusDistance' );
 
 		return {
 			view: view ? app.cameraManager.captureView() : null,
-			// Everything configureForMode( 'production' ) overwrites, with who set it.
+			// Everything configureForMode( 'production' ) and the export overwrite, with who set it.
 			settings: keys.map( key => [ key, effective[ key ] ] ),
 			renderMode: app.stages.pathTracer?.renderMode?.value,
 			controlsEnabled: app.cameraManager.controls?.enabled,
 			oidnEnabled: app.denoisingManager?.finalDenoise,
 			oidnQuality: app.denoisingManager?.oidnQuality,
+			instantExposure: app.stages.autoExposure?.instant,
+			holdExposureSamples: app.stages.autoExposure?.holdSamples,
 			wasPlaying: app.animationManager?.isPlaying,
 			pauseRendering: app.pauseRendering,
 		};
@@ -347,6 +366,13 @@ export class VideoRenderManager {
 		}
 
 		app.pauseRendering = state.pauseRendering ?? false;
+		if ( app.stages.autoExposure ) {
+
+			app.stages.autoExposure.instant = state.instantExposure ?? false;
+			// configureForMode( 'production' ) set it, and nothing switches the mode back: left on, it froze the exposure while orbiting.
+			app.stages.autoExposure.holdSamples = state.holdExposureSamples ?? 0;
+
+		}
 
 		if ( state.view ) app.cameraManager.applyPose( state.view );
 

package/src/neural/NeuralRetouch.js

@@ -389,6 +389,7 @@ export class NeuralRetouch {
 			exposure: tone.exposure ?? 1,
 			toneMapping: tone.toneMapping ?? 0,
 			saturation: tone.saturation ?? 1,
+			gain: tone.gain,
 		} );
 
 		return { rgba8, width: w, height: h };

package/src/neural/NeuralSuperRes.js

@@ -373,6 +373,7 @@ export class NeuralSuperRes {
 			exposure: tone.exposure ?? 1,
 			toneMapping: tone.toneMapping ?? 0,
 			saturation: tone.saturation ?? 1,
+			gain: tone.gain,
 			// The network emits its picture vertically flipped.
 			flipY: true,
 		} );
@@ -482,6 +483,7 @@ export async function renderUpscaled( app, {
 		width: pathTracer?.width,
 		height: pathTracer?.height,
 		maxSamples: app.settings?.get?.( 'maxSamples' ),
+		renderLimitMode: app.settings?.get?.( 'renderLimitMode' ),
 		finalDenoise: app.denoisingManager?.finalDenoise,
 		paused: app.pauseRendering,
 	};
@@ -512,7 +514,8 @@ export async function renderUpscaled( app, {
 		await new Promise( r => setTimeout( r, 300 ) );
 
 		app.denoisingManager.applyOIDNEnabled( true );
-		app.settings.set( 'maxSamples', samples );
+		// 'frames': under 'timeOnly' the deadline, not `samples`, would end the render.
+		app.settings.setMany( { maxSamples: samples, renderLimitMode: 'frames' }, { reset: false } );
 		const done = waitForDenoise( app, samples, timeoutMs );
 		app.reset();
 		await done;
@@ -529,6 +532,7 @@ export async function renderUpscaled( app, {
 			exposure: app.renderer.toneMappingExposure,
 			toneMapping: app.renderer.toneMapping,
 			saturation: app.settings.get( 'saturation' ) ?? 1,
+			gain: app._displayGain?.() ?? null,
 		};
 
 		const { rgba8, width, height, ms, toneMs } = await sr.upscaleToRGBA8( source, tone );
@@ -550,6 +554,7 @@ export async function renderUpscaled( app, {
 
 		if ( restore.width && restore.height ) app.setCanvasSize( restore.width, restore.height );
 		if ( restore.maxSamples !== undefined ) app.settings?.set?.( 'maxSamples', restore.maxSamples );
+		if ( restore.renderLimitMode !== undefined ) app.settings?.set?.( 'renderLimitMode', restore.renderLimitMode, { reset: false } );
 		if ( restore.finalDenoise !== undefined ) app.denoisingManager?.applyOIDNEnabled( restore.finalDenoise );
 		app.pauseRendering = restore.paused;