rayzee 8.0.0 → 8.2.0

package/src/managers/DenoisingManager.js

@@ -27,6 +27,47 @@ const CADENCE_COST_BUDGET_MS = 120;
 // refreshes — 2x is the better trade while a person is watching the image resolve.
 const CADENCE_DENOISE_PERIODS = 2;
 
+// The first refresh of a fresh accumulation is the one replacing a held frame that is now stale, so
+// it waits one denoise rather than two. Measured over a 2 s reset storm (a slider being dragged):
+// 8.4 -> 12.5-15.3 refreshes/sec for 75.5 -> 70-73 fps.
+const CADENCE_FIRST_REFRESH_PERIODS = 1;
+
+// While the camera moves, the denoised frames ARE the picture — the raw render is never shown — so
+// the refresh rate is the frame rate a person sees, and back to back is the right cadence. Path
+// tracing costs little there (1 bounce, no accumulation), and `isDenoising` serialises the runs.
+const CADENCE_INTERACTION_PERIODS = 0;
+
+// A denoise slower than this cannot follow a camera: holding the last one would turn navigation
+// into a slideshow, so it goes back to the raw render instead. Measured on a 1.9M-triangle scene
+// at `fast`: 512² 59 ms (35 refreshes/sec while moving, 121 fps), 1024² 135 ms (7/sec, 47 fps),
+// 1536² 1.46 s. Set to keep 1024² on the clean side of the line and reject 1536².
+const INTERACTION_HOLD_BUDGET_MS = 300;
+
+// How many refresh timings the navigation decision is taken over. A single denoise is easily twice
+// its own typical cost — a GC pause, a texture upload, another tab — and deciding on one of those
+// left the next camera move entirely raw. The median of a few is stable and still cheap.
+//
+// Only refreshes taken WHILE MOVING count: that is a different regime, because the render loop
+// stops tracing frames nobody will see (skipsTrace) and hands the GPU to the denoise. Measured
+// inside a room at 1024², the same denoise is 596 ms with the loop tracing over it and ~95 ms
+// without, so a still-camera timing would rule out navigation that in fact works.
+//
+// Taken as the MINIMUM, not the median, and reset for each move. The first refresh of a move is
+// always slow — the GPU is still finishing the frame before it — and the estimate has to survive
+// that, because a demoted move stops refreshing and so stops measuring: one unlucky reading used
+// to pin navigation to the raw render for the rest of the session.
+const DENOISE_COST_SAMPLES = 5;
+
+// A refresh this far past the budget is not a warm-up reading, it is the wrong resolution for
+// denoised navigation. Remembered until the size changes, so only the first move pays for finding
+// out; anything short of it gets a second reading before navigation is given back to the raw render.
+const INTERACTION_HOPELESS_FACTOR = 3;
+
+// Consecutive refreshes that deliver nothing before the held frame is given up and the raw render
+// comes back. Counted in runs, not milliseconds: the loop stops while a finished render sits on
+// screen, so any clock would read a perfectly good frame as abandoned the moment it woke.
+const HELD_FRAME_MAX_FAILURES = 3;
+
 /**
  * Orchestrates all denoising, post-processing, and AI upscaling:
  *   - Real-time denoiser strategy switching (ASVGF / NRD / EdgeAware / None)
@@ -44,23 +85,18 @@ export class DenoisingManager extends EventDispatcher {
 	 * @param {Object} params
 	 * @param {import('three/webgpu').WebGPURenderer} params.renderer
 	 * @param {HTMLCanvasElement}                      params.mainCanvas  - The primary rendering canvas
-	 * @param {import('three').Scene}                  params.scene
-	 * @param {import('three').PerspectiveCamera}      params.camera
 	 * @param {Object}                                 params.stages     - Named references to pipeline stages
 	 * @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.getTransparentBg  - () => boolean
 	 */
-	constructor( { renderer, mainCanvas, scene, camera, stages, pipeline, getExposure, getSaturation, getTransparentBg } ) {
+	constructor( { renderer, mainCanvas, stages, pipeline, getExposure, getSaturation } ) {
 
 		super();
 
 		this.renderer = renderer;
 		this.mainCanvas = mainCanvas;
-		this.denoiserCanvas = this._createDenoiserCanvas( mainCanvas );
-		this.scene = scene;
-		this.camera = camera;
+		this.upscalerCanvas = this._createUpscalerCanvas( mainCanvas );
 		this.pipeline = pipeline;
 
 		// Stage references — only used internally for orchestration
@@ -68,7 +104,6 @@ export class DenoisingManager extends EventDispatcher {
 
 		this._getExposure = getExposure;
 		this._getSaturation = getSaturation;
-		this._getTransparentBg = getTransparentBg;
 
 		this.denoiser = null;
 		this.upscaler = null;
@@ -86,6 +121,16 @@ export class DenoisingManager extends EventDispatcher {
 		// denoise while performance.now() is still below the interval.
 		this._lastCadenceAt = - Infinity;
 		this._lastCadenceSamples = 0;
+		// Consecutive refreshes that delivered nothing, for the held-frame health check.
+		this._failedRefreshes = 0;
+		// A final render suspends the live-view refresh without forgetting that the host chose it.
+		this._cadenceSuspended = false;
+		// Refresh timings from the current camera move, and whether this resolution has already
+		// proved far too slow to navigate denoised.
+		this._movingDenoiseMs = [];
+		this._movingHopeless = false;
+		// Whether this camera move is being shown denoised. Decided once per move; null between.
+		this._holdWhileMoving = null;
 		this._onReset = null;
 		this._onPostProcessRefresh = null;
 
@@ -107,7 +152,12 @@ export class DenoisingManager extends EventDispatcher {
 
 	}
 
-	_createDenoiserCanvas( mainCanvas ) {
+	/**
+	 * The one canvas the engine keeps besides the renderer's own, for the AI upscaler: it works in
+	 * ordinary pixels and shows a picture larger than the render, neither of which the renderer's
+	 * canvas can do. Hidden until the upscaler has something to show.
+	 */
+	_createUpscalerCanvas( mainCanvas ) {
 
 		const parent = mainCanvas.parentNode;
 		if ( ! parent ) return null;
@@ -119,6 +169,7 @@ export class DenoisingManager extends EventDispatcher {
 		dc.style.inset = '0';
 		dc.style.width = '100%';
 		dc.style.height = '100%';
+		dc.style.display = 'none';
 
 		parent.insertBefore( dc, mainCanvas );
 		return dc;
@@ -139,27 +190,48 @@ export class DenoisingManager extends EventDispatcher {
 		// Cleared only when the tier or the resolution changes — a denoise costs 14 ms at 512²
 		// and 800 ms at 2048², so the affordability verdict does not survive a resize.
 		this._cadenceDowngraded = false;
+		this._holdWhileMoving = null;
+		this._movingDenoiseMs.length = 0;
+		this._movingHopeless = false;
+		// A run in flight was sized for the old resolution and setSize rebuilds the network under
+		// it. Resets no longer cancel a run while its frame is on screen, so this has to.
+		this.denoiser?.abort();
+		// The picture on screen is the old size, and the Compositor would stretch it over the new
+		// frame until a denoise lands. Back to the raw render until then.
+		this._unpublishOutput();
 		this.denoiser?.setSize( width, height );
+
+		// The 2D canvas exists for the upscaler alone, and sizing it here keeps that ownership in
+		// one place. Assigning width or height clears it, so only do it when it actually changed.
+		if ( this.upscalerCanvas && ( this.upscalerCanvas.width !== width || this.upscalerCanvas.height !== height ) ) {
+
+			this.upscalerCanvas.width = width;
+			this.upscalerCanvas.height = height;
+
+		}
+
 		this.upscaler?.setBaseSize( width, height );
 
 	}
 
 
 	/**
-	 * Restores the denoiser canvas to base render resolution after upscaling.
+	 * Puts the upscaler's canvas back to the render size — it leaves it two or four times larger.
 	 * @returns {boolean} true if the canvas was resized
 	 */
 	restoreBaseResolution() {
 
-		if ( ! this.denoiserCanvas || ! this._lastRenderWidth || ! this._lastRenderHeight ) return false;
+		if ( ! this.upscalerCanvas || ! this._lastRenderWidth || ! this._lastRenderHeight ) return false;
 
-		const wasResized = this.denoiserCanvas.width !== this._lastRenderWidth
-			|| this.denoiserCanvas.height !== this._lastRenderHeight;
+		const wasResized = this.upscalerCanvas.width !== this._lastRenderWidth
+			|| this.upscalerCanvas.height !== this._lastRenderHeight;
 
-		this.denoiserCanvas.width = this._lastRenderWidth;
-		this.denoiserCanvas.height = this._lastRenderHeight;
+		if ( ! wasResized ) return false;
 
-		return wasResized;
+		this.upscalerCanvas.width = this._lastRenderWidth;
+		this.upscalerCanvas.height = this._lastRenderHeight;
+
+		return true;
 
 	}
 
@@ -168,11 +240,14 @@ export class DenoisingManager extends EventDispatcher {
 	 */
 	setupDenoiser() {
 
-		if ( ! this.denoiserCanvas ) return;
+		if ( ! this.upscalerCanvas ) return;
 
 		const pt = this._stages.pathTracer;
 
-		this.denoiser = new OIDNDenoiser( this.denoiserCanvas, this.renderer, this.scene, this.camera, {
+		// No canvas: the denoiser hands its result to the pipeline as a picture, and the
+		// Compositor decides what the single canvas shows. The exposure, grade and tone curve
+		// come from the renderer's own output pass, so it is not told about them either.
+		this.denoiser = new OIDNDenoiser( this.renderer, {
 			...DEFAULT_STATE,
 
 			backendParams: () => ( {
@@ -180,13 +255,6 @@ export class DenoisingManager extends EventDispatcher {
 				adapterInfo: null
 			} ),
 
-			refreshInput: () => {
-
-				const ctx = this.pipeline?.context;
-				if ( this._stages.compositor && ctx ) this._stages.compositor.render( ctx );
-
-			},
-
 			getGPUTextures: () => {
 
 				if ( ! pt?.storageTextures?.readTarget ) return null;
@@ -199,11 +267,6 @@ export class DenoisingManager extends EventDispatcher {
 				};
 
 			},
-
-			getExposure: () => this._getEffectiveExposure(),
-			getToneMapping: () => this._getToneMapping(),
-			getSaturation: () => this._getSaturation(),
-			getTransparentBackground: () => this._getTransparentBg(),
 		} );
 
 		this._syncOIDNInUse();
@@ -211,8 +274,13 @@ export class DenoisingManager extends EventDispatcher {
 		// Forward lifecycle events (store refs for removal on re-setup / dispose)
 		this._denoiserStartHandler = e =>
 			this.dispatchEvent( { type: EngineEvents.DENOISING_START, continuous: !! e.continuous } );
-		this._denoiserEndHandler = e =>
+		this._denoiserEndHandler = e => {
+
+			if ( this.denoiser?.hasOutput ) this._publishOutput();
 			this.dispatchEvent( { type: EngineEvents.DENOISING_END, continuous: !! e.continuous } );
+
+		};
+
 		this.denoiser.addEventListener( 'start', this._denoiserStartHandler );
 		this.denoiser.addEventListener( 'end', this._denoiserEndHandler );
 
@@ -223,20 +291,19 @@ export class DenoisingManager extends EventDispatcher {
 	 */
 	setupUpscaler() {
 
-		if ( ! this.denoiserCanvas ) return;
+		if ( ! this.upscalerCanvas ) return;
 
 		const pt = this._stages.pathTracer;
 
-		this.upscaler = new AIUpscaler( this.denoiserCanvas, this.renderer, {
+		this.upscaler = new AIUpscaler( this.upscalerCanvas, this.renderer, {
 			scaleFactor: DEFAULT_STATE.upscalerScale || 2,
 			quality: DEFAULT_STATE.upscalerQuality || 'fast',
 
-			getSourceCanvas: () => {
-
-				if ( this.denoiser?.enabled ) return null;
-				return this.renderer.domElement;
-
-			},
+			// One source: the render canvas shows whatever the Compositor picked — the denoised
+			// picture when OIDN is on, the raw render otherwise — so the upscaler always enlarges
+			// what the viewer is actually looking at. It used to read its own canvas when the
+			// denoiser was on, which only worked while the denoiser painted there.
+			getSourceCanvas: () => this.renderer.domElement,
 
 			refreshInput: () => {
 
@@ -514,6 +581,85 @@ export class DenoisingManager extends EventDispatcher {
 
 	}
 
+	/**
+	 * Whether the view is moving and the denoiser is quick enough to be that view — in which case the
+	 * raw render is never shown and every reset keeps the last denoised frame up.
+	 *
+	 * Decided once per move rather than per frame, which would flip the viewport between clean and
+	 * noisy mid-drag. Nothing is known at the first move of a size, so it tries once and then knows.
+	 * Demotion is the exception: a move that turns out to be a slideshow gives the view back rather
+	 * than finishing at 1.5 refreshes a second.
+	 */
+	get holdsWhileMoving() {
+
+		if ( ! this._stages.pathTracer?.viewIsChanging ) return false;
+		if ( ! this.continuousDenoise || this._cadenceSuspended || ! this.denoiser?.enabled ) return false;
+		if ( this._movingHopeless ) return false;
+
+		const best = this.movingCostMs;
+		const seen = this._movingDenoiseMs.length;
+
+		if ( best > INTERACTION_HOLD_BUDGET_MS * INTERACTION_HOPELESS_FACTOR ) this._movingHopeless = true;
+
+		// One reading is a warm-up; two that are both over budget are the answer.
+		const affordable = ! this._movingHopeless && ( seen < 2 || best <= INTERACTION_HOLD_BUDGET_MS );
+		this._holdWhileMoving = this._holdWhileMoving === null ? affordable : this._holdWhileMoving && affordable;
+
+		return this._holdWhileMoving;
+
+	}
+
+	/**
+	 * Whether the render loop should leave this frame untraced. True only while the denoised frame
+	 * is the live view and a denoise is running — the one case where a traced frame reaches nobody:
+	 * accumulation is off while the camera moves, the canvas is hidden, and the next denoise reads
+	 * whatever the newest frame is. Measured inside a room at 512²: 19 -> 32 refreshes/sec.
+	 */
+	skipsTrace() {
+
+		return this.holdsWhileMoving && !! this.denoiser?.state.isDenoising;
+
+	}
+
+	// The best a refresh has managed during this camera move. Zero until one has been timed, which
+	// reads as free and buys a first attempt rather than a verdict from the wrong regime.
+	get movingCostMs() {
+
+		return this._movingDenoiseMs.length ? Math.min( ...this._movingDenoiseMs ) : 0;
+
+	}
+
+	/**
+	 * Hands the denoised picture to the pipeline. The Compositor prefers it over the raw render
+	 * from the next frame on, and keeps drawing it until it is taken away again — which is what
+	 * makes "hold the last clean frame" free rather than a rule.
+	 */
+	_publishOutput() {
+
+		const ctx = this.pipeline?.context;
+		const tex = this.denoiser?.outputTexture;
+		if ( ctx && tex ) ctx.setTexture( 'oidn:output', tex );
+
+	}
+
+	// Gives the viewport back to the raw render.
+	_unpublishOutput() {
+
+		this.pipeline?.context?.removeTexture( 'oidn:output' );
+		this.denoiser?.invalidateOutput();
+
+	}
+
+	// A picture the denoiser has stopped replacing describes a view that is long gone, so the raw
+	// render takes the viewport back until a refresh delivers again.
+	_checkHeldFrameHealthy() {
+
+		if ( ! this.denoiser?.hasOutput || this._failedRefreshes < HELD_FRAME_MAX_FAILURES ) return;
+
+		this._unpublishOutput();
+
+	}
+
 	/**
 	 * Denoises the accumulating mean on a cadence, so a preview shows a clean image while it
 	 * refines instead of only once it finishes. Driven from the render loop; call every frame.
@@ -524,20 +670,32 @@ export class DenoisingManager extends EventDispatcher {
 	tickContinuousDenoise( sampleCount ) {
 
 		const dn = this.denoiser;
-		if ( ! this.continuousDenoise || ! dn ) return false;
-		if ( dn.state.isDenoising || dn.state.isLoading ) return false;
+		if ( ! this.continuousDenoise || this._cadenceSuspended || ! dn ) return false;
+
+		this._checkHeldFrameHealthy();
+
+		// Moving with a denoise too slow to follow: the raw render owns the view, and a refresh
+		// would only paint a stale clean frame over a moving one.
+		const interacting = !! this._stages.pathTracer?.viewIsChanging;
+		if ( ! interacting ) {
 
-		// While the camera moves, reset() hides the output every frame and a denoise would paint
-		// a view that is already stale. Denoise once the motion stops.
-		if ( this._stages.pathTracer?.interactionMode ) return false;
+			this._holdWhileMoving = null;
+			this._movingDenoiseMs.length = 0;
+
+		} else if ( ! this.holdsWhileMoving ) return false;
+
+		if ( dn.state.isDenoising || dn.state.isLoading ) return false;
 
-		// Nothing new has landed since the last refresh, so it would repaint the same image.
-		if ( sampleCount <= this._lastCadenceSamples ) return false;
+		// frameCount is frozen while the camera moves — those frames are 1-SPP feedback and do not
+		// count toward completion — so this gate would refuse every tick. The clock governs there.
+		if ( ! interacting && sampleCount <= this._lastCadenceSamples ) return false;
 
 		const now = performance.now();
 		// `continuousDenoiseInterval` is only the floor's lower bound: on a cheap denoise it is
 		// what binds, and past ~1024² the denoise's own cost is.
-		const minGap = Math.max( this.continuousDenoiseInterval, dn.lastDenoiseMs * CADENCE_DENOISE_PERIODS );
+		const periods = interacting ? CADENCE_INTERACTION_PERIODS
+			: this._lastCadenceSamples === 0 ? CADENCE_FIRST_REFRESH_PERIODS : CADENCE_DENOISE_PERIODS;
+		const minGap = Math.max( this.continuousDenoiseInterval, dn.lastDenoiseMs * periods );
 		if ( now - this._lastCadenceAt < minGap ) return false;
 
 		this._lastCadenceAt = now;
@@ -552,7 +710,16 @@ export class DenoisingManager extends EventDispatcher {
 		const want = this._cadenceDowngraded ? this.previewQuality() : this._finalQuality;
 		if ( dn.quality !== want ) dn.updateQuality( want );
 
-		dn.start( { continuous: true } );
+		dn.start( { continuous: true } ).then( ok => {
+
+			this._failedRefreshes = ok ? 0 : this._failedRefreshes + 1;
+			if ( ! ok || ! interacting ) return;
+
+			this._movingDenoiseMs.push( dn.lastDenoiseMs );
+			if ( this._movingDenoiseMs.length > DENOISE_COST_SAMPLES ) this._movingDenoiseMs.shift();
+
+		} );
+
 		return true;
 
 	}
@@ -571,6 +738,27 @@ export class DenoisingManager extends EventDispatcher {
 
 	}
 
+	/**
+	 * Stops the live-view refresh for the duration of a final render, without changing what the
+	 * host picked in the denoiser list. A final render shows the accumulation and denoises once at
+	 * the end, so refreshing through it spends samples on frames nobody keeps — and a refresh
+	 * landing while the renderer resizes itself on the way in raced its output pass, which the
+	 * device reported as a write to a destroyed buffer.
+	 *
+	 * @param {boolean} suspended
+	 */
+	setCadenceSuspended( suspended ) {
+
+		this._cadenceSuspended = !! suspended;
+		if ( ! this._cadenceSuspended ) return;
+
+		// The accumulation is what a final render shows; a held preview frame would otherwise sit
+		// over it until the render finished.
+		this.denoiser?.abort();
+		this._unpublishOutput();
+
+	}
+
 	setContinuousDenoise( enabled ) {
 
 		this.continuousDenoise = !! enabled;
@@ -684,22 +872,36 @@ export class DenoisingManager extends EventDispatcher {
 
 	/**
 	 * Aborts any in-progress denoising/upscaling (called on reset).
-	 * @param {HTMLCanvasElement} canvas
+	 *
+	 * @param {HTMLCanvasElement} mainCanvas
+	 * @param {Object}  [options]
+	 * @param {boolean} [options.keepDisplay] - The viewpoint did not move, so the frame already on
+	 *   screen still describes this view. It stays up until the next denoise replaces it, instead
+	 *   of dropping back to the raw render for one denoise. Ignored unless OIDN owns the live view:
+	 *   nothing else would ever replace the held frame.
 	 */
-	abort( mainCanvas ) {
+	abort( mainCanvas, { keepDisplay = false } = {} ) {
 
 		// Remove stale completion-chain listener before aborting
 		this._cleanupCompletionListener();
 
+		// The 2D canvas is the upscaler's alone: a reset means its enlarged result no longer
+		// describes anything, so the render canvas comes back.
 		if ( mainCanvas ) mainCanvas.style.opacity = '1';
-
+		if ( this.upscalerCanvas ) this.upscalerCanvas.style.display = 'none';
 		if ( this.upscaler ) this.upscaler.abort();
 
-		if ( this.denoiser ) {
+		const moving = !! this._stages.pathTracer?.viewIsChanging;
+		const hold = keepDisplay && this.continuousDenoise && ! this._cadenceSuspended && !! this.denoiser?.hasOutput
+			&& ( ! moving || this.holdsWhileMoving );
+
+		if ( this.denoiser && ! hold ) {
 
+			// A held picture means the run in flight is the frame that replaces what is on screen.
+			// Cancelling it every time reset() runs — which is every frame of a camera drag — means
+			// none of them ever lands.
 			if ( this.denoiser.enabled ) this.denoiser.abort();
-			if ( this.denoiser.output ) this.denoiser.output.style.display = 'none';
-			this.denoiser.invalidateLatch();
+			this._unpublishOutput();
 
 		}
 
@@ -707,10 +909,26 @@ export class DenoisingManager extends EventDispatcher {
 
 	}
 
+	/**
+	 * Takes the denoised frame off screen and throws it away. For a change that makes the frame
+	 * wrong rather than stale — the scene it describes is gone — where holding it would leave the
+	 * previous model on screen over an empty or half-built one.
+	 */
+	dropDisplay() {
+
+		this._unpublishOutput();
+
+		if ( this.upscalerCanvas ) this.upscalerCanvas.style.display = 'none';
+		if ( this.mainCanvas ) this.mainCanvas.style.opacity = '1';
+
+	}
+
 	dispose() {
 
 		// Remove pending completion-chain listener
 		this._cleanupCompletionListener();
+		// Before the denoiser destroys the picture the Compositor would otherwise still sample.
+		this._unpublishOutput();
 
 		if ( this.denoiser ) {
 
@@ -739,10 +957,10 @@ export class DenoisingManager extends EventDispatcher {
 		this._upscalerProgressHandler = null;
 		this._upscalerEndHandler = null;
 
-		if ( this.denoiserCanvas?.parentNode ) {
+		if ( this.upscalerCanvas?.parentNode ) {
 
-			this.denoiserCanvas.parentNode.removeChild( this.denoiserCanvas );
-			this.denoiserCanvas = null;
+			this.upscalerCanvas.parentNode.removeChild( this.upscalerCanvas );
+			this.upscalerCanvas = null;
 
 		}
 
@@ -1014,7 +1232,7 @@ export class DenoisingManager extends EventDispatcher {
 		const keys = [
 			'asvgf:output', 'asvgf:demodulated', 'asvgf:gradient',
 			'variance:output', 'bilateralFiltering:output',
-			'edgeFiltering:output', 'nrd:output',
+			'edgeFiltering:output', 'nrd:output', 'oidn:output',
 		];
 		keys.forEach( k => ctx.removeTexture( k ) );
 

package/src/managers/VideoRenderManager.js

@@ -321,6 +321,10 @@ export class VideoRenderManager {
 
 		app.pauseRendering = state.pauseRendering ?? false;
 
+		// configureForMode( 'production' ) suspended the live-view refresh and nothing here switches
+		// back, so the viewport would stay un-denoised until the host changed tab.
+		app.denoisingManager?.setCadenceSuspended( false );
+
 		// Stop animation playback that seekTo may have started
 		app.animationManager?.stop();