rayzee 11.2.1 → 11.4.0

package/src/Processor/USD/index.js

@@ -0,0 +1,138 @@
+/**
+ * USD scene loader for multi-file scenes in a folder or archive: layers are read only as composition reaches them, and
+ * the stage is built by the pbrt importer's builder, so instancing, budgets and curve tessellation are shared.
+ *
+ *   const files = new USDFiles( paths, read );
+ *   const { group, environment, cameras } = await loadUSDScene( { files, entryPath, resolveImage, resolveEnvironment } );
+ */
+
+import { PBRTSceneBuilder } from '../PBRT/PBRTSceneBuilder.js';
+import { USDStage } from './USDStage.js';
+import { USDSceneReader } from './USDScene.js';
+
+export { USDFiles, USDStage } from './USDStage.js';
+
+export const USD_LAYER = /\.(usd|usda|usdc)$/i;
+
+/** USD layers that could be a scene's root, best first: the shallowest, then the shortest name. */
+export function listUSDRootLayers( paths ) {
+
+	const layers = paths.filter( p => USD_LAYER.test( p ) && ! p.split( '/' ).pop().startsWith( '._' ) );
+	if ( layers.length === 0 ) return [];
+	const depth = p => p.split( '/' ).length;
+	const top = Math.min( ...layers.map( depth ) );
+	return layers.filter( p => depth( p ) === top ).sort( ( a, b ) => {
+
+		const na = a.split( '/' ).pop(), nb = b.split( '/' ).pop();
+		return na.length - nb.length || ( na < nb ? - 1 : na > nb ? 1 : 0 );
+
+	} );
+
+}
+
+/** The parts a large scene loads by: prims under the root's top prims that bring in sibling directories (Moana's elements/). */
+export async function listUSDParts( stage, listing ) {
+
+	const parts = new Map();
+	const root = stage.pseudoRoot;
+	const rootDir = stage.root.id.includes( '/' ) ? stage.root.id.slice( 0, stage.root.id.lastIndexOf( '/' ) ) : '';
+	for ( const top of root.childNames() ) {
+
+		for ( const [ , spec, layer ] of ( await stage.child( root, top ) )?.sites ?? [] ) {
+
+			for ( const [ name, child ] of spec.children ?? [] ) {
+
+				for ( const key of [ 'references', 'payload' ] ) {
+
+					const op = child.arcs?.[ key ];
+					for ( const ref of [ ...( op?.explicit ?? [] ), ...( op?.prepend ?? [] ), ...( op?.append ?? [] ), ...( op?.add ?? [] ) ] ) {
+
+						const file = stage.files.resolve( ref.asset, layer.path );
+						if ( ! file?.includes( '/' ) ) continue;
+						const prefix = file.slice( 0, file.lastIndexOf( '/' ) );
+						if ( prefix === rootDir || ! prefix.startsWith( rootDir ) ) continue;
+						if ( ! parts.has( prefix ) ) parts.set( prefix, { name, prefix, files: 0, bytes: 0, scenes: 1 } );
+
+					}
+
+				}
+
+			}
+
+		}
+
+	}
+
+	// A library referenced on its own beside the parts is not one.
+	const byParent = new Map();
+	for ( const part of parts.values() ) {
+
+		const parent = part.prefix.slice( 0, part.prefix.lastIndexOf( '/' ) );
+		if ( ! byParent.has( parent ) ) byParent.set( parent, [] );
+		byParent.get( parent ).push( part );
+
+	}
+
+	const siblings = [ ...byParent.values() ].sort( ( a, b ) => b.length - a.length )[ 0 ] ?? [];
+	for ( const part of siblings ) {
+
+		for ( const entry of listing ) {
+
+			if ( ! entry.path.startsWith( `${part.prefix}/` ) || ! USD_LAYER.test( entry.path ) ) continue;
+			part.files ++;
+			part.bytes += entry.size;
+
+		}
+
+	}
+
+	return siblings.sort( ( a, b ) => a.bytes - b.bytes );
+
+}
+
+export async function loadUSDScene( args ) {
+
+	const warnings = [];
+	const warn = message => warnings.push( message );
+	const builder = new PBRTSceneBuilder( {
+		maxTriangles: args.maxTriangles, maxPlacements: args.maxPlacements, mergeShapesAbove: args.mergeShapesAbove,
+		curveSteps: args.curveSteps, curveSides: args.curveSides, curveTolerance: args.curveTolerance,
+	} );
+
+	const parseStart = performance.now();
+	const stage = new USDStage( args.files, { warn } );
+	await stage.open( args.entryPath );
+	const reader = new USDSceneReader( stage, {
+		maxTriangles: builder.maxTriangles, maxPlacements: builder.maxPlacements, curveSteps: builder.curveSteps,
+		resolveImage: args.resolveImage, warn,
+	} );
+	const read = await reader.read();
+	if ( stage.omittedArcs > 0 ) warn( `${stage.omittedArcs} reference(s) into the parts left out of this load skipped` );
+	const parseMs = performance.now() - parseStart;
+
+	const buildStart = performance.now();
+	const built = await builder.build( read.ir );
+	for ( const object of [ ...read.cameras, ...read.lights ] ) built.group.add( object );
+
+	let environment = null;
+	if ( read.dome ) {
+
+		const texture = await args.resolveEnvironment( read.dome.file );
+		if ( texture ) environment = { texture, intensity: read.dome.intensity, rotation: read.dome.rotation };
+		else warn( `USD dome light texture "${read.dome.file}" could not be read` );
+
+	}
+
+	return {
+		...built,
+		environment,
+		cameras: read.cameras,
+		lights: read.lights,
+		cost: read.cost,
+		fitNote: reader.fitNote,
+		warnings: [ ...warnings, ...built.warnings ],
+		parseMs,
+		buildMs: performance.now() - buildStart,
+	};
+
+}

package/src/Processor/Workers/BVHRefitWorker.js

@@ -46,9 +46,9 @@ self.onmessage = function ( e ) {
 
 			const startTime = performance.now();
 
-			const { blasRanges, tlasNodeCount } = e.data;
-			if ( blasRanges ) refitter.refitPartial( bvhData, triData, blasRanges, tlasNodeCount );
-			else refitter.refit( bvhData, triData, nodeCount );
+			const { blasRanges, tlasNodeCount, groupRange, treeNodeCount, recordNodeStart = - 1 } = e.data;
+			if ( blasRanges ) refitter.refitPartial( bvhData, triData, blasRanges, tlasNodeCount, groupRange, recordNodeStart );
+			else refitter.refit( bvhData, triData, treeNodeCount ?? nodeCount, recordNodeStart );
 
 			self.postMessage( {
 				type: 'refitComplete',

package/src/RayzeeRenderer.js

@@ -11,6 +11,7 @@ import { RenderPipeline } from './Pipeline/RenderPipeline.js';
 import { CompletionTracker } from './Pipeline/CompletionTracker.js';
 import { ENGINE_DEFAULTS as DEFAULT_STATE } from './EngineDefaults.js';
 import { TRIANGLE_DATA_LAYOUT, BVH_LEAF_MARKERS } from './Processor/BufferLayout.js';
+import { usesTextureCoordinates } from './Processor/GeometryExtractor.js';
 import { MAX_STORAGE_TEXTURE_SIZE, MAX_RESERVABLE_RENDER_SIZE, setReservedRenderSize } from './Processor/StorageTexturePool.js';
 import { updateStats, updateLoading, resetLoading, setStatusCallback, getDisplaySamples, disposeObjectFromMemory, disposeRenderer } from './Processor/utils.js';
 import { BuildTimer } from './Processor/BuildTimer.js';
@@ -28,9 +29,9 @@ import { PackedToneMapper } from './Processor/ToneMapGPU.js';
 import { BasicColor } from './Color/BasicColor.js';
 import { setActiveColorManagement } from './Color/ActiveColor.js';
 import { getViewTransform, DEFAULT_VIEW } from './Color/ViewTransforms.js';
-import { AssetLoader } from './Processor/AssetLoader.js';
+import { AssetLoader, limitEnvironmentWidth } from './Processor/AssetLoader.js';
 import { SceneProcessor } from './Processor/SceneProcessor.js';
-import { deviceMemoryGB, SPILL_TRIANGLE_BUDGET, SPILL_PLACEMENT_BUDGET } from './Processor/HostMemory.js';
+import { deviceMemoryGB, SPILL_TRIANGLE_BUDGET, SPILL_PLACEMENT_BUDGET, SPILL_ENVIRONMENT_WIDTH } from './Processor/HostMemory.js';
 import { createHeadlessCanvas } from './HeadlessCanvas.js';
 
 // Managers
@@ -52,6 +53,8 @@ const partOf = ( { element, pbrtEntry } = {} ) => ( {
 // One app per canvas — auto-dispose a prior owner if the caller double-
 // instantiates (StrictMode, HMR, etc.) so its rAF loop can't burn CPU.
 const _appsByCanvas = new WeakMap();
+// Quiet time after an edit before memory spill puts back on disk what the edit read back.
+const RESPILL_AFTER_MS = 30_000;
 
 const KNOWN_EVENTS = new Set( [ ...Object.values( EngineEvents ), ...Object.values( LEGACY_EVENT_NAMES ) ] );
 const _warnedEvents = new Set();
@@ -165,9 +168,11 @@ export class RayzeeRenderer extends EventDispatcher {
 	 * @param {false|'auto'|Object} [options.storage] - on-disk storage; defaults to
 	 *   `configureAssets( { storage } )`, or off under `strict` unless that was set. 'auto' opens it through
 	 *   {@link setStorageOpener} (rayzee/addons/storage); a host-supplied StorageManager stays the host's to dispose.
-	 * @param {boolean} [options.memorySpill=false] - experimental: once a large static scene is
-	 *   on the GPU, move its triangle records and BLAS nodes to disk (see
-	 *   {@link ensureSceneResident}). Needs storage; skipped for animated scenes.
+	 * @param {'auto'|boolean} [options.memorySpill='auto'] - build a static scene through disk: its triangle records,
+	 *   BLAS nodes and three.js geometry leave memory as they are built (see {@link ensureSceneResident}), scene archives
+	 *   load past the default budgets, and an environment wider than SPILL_ENVIRONMENT_WIDTH is box-filtered down.
+	 *   'auto' does so only for a scene whose in-memory estimate passes SAFE_SCENE_BYTES; true for every scene, false
+	 *   never. Needs storage; skipped for animated scenes. See {@link setMemorySpill}.
 	 *
 	 * The engine dispatches `EngineEvents.FRAME` after each animate() iteration so hosts can
 	 * tick external instrumentation (e.g. a stats panel) without coupling the engine to it.
@@ -198,7 +203,8 @@ export class RayzeeRenderer extends EventDispatcher {
 		this._hostMemoryGB = options.hostMemoryGB;
 		this._storageOption = options.storage;
 		this._storageOpener = null;
-		this._memorySpill = options.memorySpill === true;
+		this._memorySpill = options.memorySpill === true || options.memorySpill === false ? options.memorySpill : 'auto';
+		this._spillPlan = null;
 		/** @type {?Object} on-disk storage (a StorageManager), null when off or unavailable */
 		this.storage = null;
 		this._storageRelease = null;
@@ -526,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;
@@ -552,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();
 
 		}
 
@@ -566,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 } = {} ) {
 
@@ -708,6 +735,8 @@ export class RayzeeRenderer extends EventDispatcher {
 		this.stopAnimation();
 		clearTimeout( this._resizeDebounceTimer );
 		this._resizeDebounceTimer = null;
+		clearTimeout( this._respillTimer );
+		this._respillTimer = null;
 
 		this._removeTrackedListeners();
 		setStatusCallback( null );
@@ -1175,6 +1204,8 @@ export class RayzeeRenderer extends EventDispatcher {
 		if ( this._loadingInProgress ) throw this._busyError( 'PathTracerApp' );
 
 		this._loadingInProgress = true;
+		// The previous scene's sky width must not narrow this one's while it loads.
+		if ( this.assetLoader ) this.assetLoader.maxEnvironmentWidth = this._memorySpill === true ? SPILL_ENVIRONMENT_WIDTH : 0;
 
 		try {
 
@@ -1189,6 +1220,8 @@ export class RayzeeRenderer extends EventDispatcher {
 			// (The old primary was already released by releaseTargetModel() in loadFn.)
 			this._clearAppendedModels();
 			this._modelReplaced();
+			// Before the scene's own environment starts loading: a spilling scene's is narrowed as it decodes.
+			this._planSpill();
 			await this.loadSceneData( { pendingEnvironment: this._beginSceneMetadataEnvironment() } );
 			this._maybeSpill();
 			this.pipeline?.eventBus.emit( 'pipeline:lightingChanged' );
@@ -1215,6 +1248,7 @@ export class RayzeeRenderer extends EventDispatcher {
 		} finally {
 
 			this._loadingInProgress = false;
+			this._spillPlan = null;
 
 		}
 
@@ -1445,11 +1479,22 @@ export class RayzeeRenderer extends EventDispatcher {
 		updateLoading( { status: "Transferring data to GPU...", progress: 86 } );
 		await new Promise( r => setTimeout( r, 0 ) );
 		timer.start( 'GPU data transfer' );
+		await this._sdf.uploadChunks( this._chunkUploader() );
 
 		// Re-read rather than reusing the snapshot above: a pendingEnvironment may have landed
 		// during the BVH build, and the snapshot is then a disposed texture.
 		if ( ! this._sdf.uploadToPathTracer( this.stages.pathTracer, this.lightManager, this.meshScene, hdri(), { keepUserLights } ) ) return false;
 
+		// A bucket at a time, each awaited (PathTracerStage#drainUploads): left to the first frame, three.js sends every
+		// layer at once, and Chrome keeps a pool that size (724 MB for 24155522.glb).
+		for ( const texture of [ ...( this._sdf.srgbBucketTextures ?? [] ), ...( this._sdf.linearBucketTextures ?? [] ) ] ) {
+
+			if ( ! texture ) continue;
+			this.renderer.initTexture( texture );
+			await this.stages.pathTracer.drainUploads();
+
+		}
+
 		// Patch per-mesh visibility into the TLAS leaves we just uploaded
 		this.stages.pathTracer._meshRefs = this.stages.pathTracer._collectMeshRefs( this.meshScene );
 		this.stages.pathTracer.setMeshVisibilityData( this.stages.pathTracer._meshRefs );
@@ -1724,43 +1769,124 @@ export class RayzeeRenderer extends EventDispatcher {
 	// Dynamic cameras (add / remove)
 	// ═══════════════════════════════════════════════════════════════
 
-	/** Triangle and placement budgets for a scene archive: raised when the build can spill. @private */
+	/** How scenes use the disk: 'auto', true or false (see the constructor's `memorySpill`). */
+	get memorySpill() {
+
+		return this._memorySpill;
+
+	}
+
+	/** Sets {@link memorySpill}; the next load or rebuild follows it. */
+	setMemorySpill( mode ) {
+
+		this._memorySpill = mode === true || mode === false ? mode : 'auto';
+
+	}
+
+	/** Whether the current scene was built through disk. */
+	get sceneSpilled() {
+
+		return !! this._sdf?.spilling;
+
+	}
+
+	/** Whether the model's three.js geometry is on disk, so picking skips it until {@link ensureSceneResident}. */
+	get geometryOnDisk() {
+
+		return this._sdf?.geometryOnDisk === true;
+
+	}
+
+	/**
+	 * Triangle and placement budgets for a scene archive: raised whenever a build could spill, since the preflight
+	 * refuses what cannot fit either way. @private
+	 */
 	_sceneBudgets( options ) {
 
-		if ( ! this._memorySpill || ! this.storage ) return options;
+		if ( this._memorySpill === false || ! this.storage ) return options;
 		return { maxTriangles: SPILL_TRIANGLE_BUDGET, maxPlacements: SPILL_PLACEMENT_BUDGET, ...options };
 
 	}
 
 	/**
-	 * Experimental memory spill, during the build: static scenes only, since a deforming clip
-	 * refits every frame. @private
+	 * Decides whether the scene about to be built spills: static scenes only, since a deforming clip refits every
+	 * frame. Held for the build that follows ({@link _progressiveSpill}). @private
 	 */
+	_planSpill() {
+
+		const offered = this._memorySpill !== false && !! this.storage && ( this.assetLoader?.animations?.length ?? 0 ) === 0;
+		const spill = offered && ( this._memorySpill === true || this._sdf.needsSpill( this.meshScene ) );
+		if ( this.assetLoader ) this.assetLoader.maxEnvironmentWidth = spill ? SPILL_ENVIRONMENT_WIDTH : 0;
+		// An importer installs its own sky at the end of its read, before this.
+		const sky = spill ? this.meshScene?.environment : null;
+		const image = sky?.image;
+		if ( image ) limitEnvironmentWidth( sky, SPILL_ENVIRONMENT_WIDTH );
+		if ( sky && sky.image !== image ) {
+
+			// three.js keeps an uploaded texture's size, so the old one goes.
+			sky.dispose();
+			sky.needsUpdate = true;
+
+		}
+
+		if ( spill && this._memorySpill === 'auto' ) log.info( 'scene is past the in-memory line: building it through disk' );
+		this._spillPlan = spill;
+		return spill;
+
+	}
+
+	/** @private */
 	_progressiveSpill() {
 
-		if ( ! this._memorySpill || ! this.storage || ( this.assetLoader?.animations?.length ?? 0 ) > 0 ) return null;
+		const spill = this._spillPlan ?? this._planSpill();
+		this._spillPlan = null;
+		return spill ? { storage: this.storage, uploader: this._chunkUploader() } : null;
+
+	}
+
+	/** @private */
+	_chunkUploader() {
+
 		const stage = this.stages.pathTracer;
-		return { storage: this.storage, uploader: ( records, kind ) => kind === 'triangles' ? stage.createTriangleChunkUploader( records ) : stage.createChunkUploader( records ) };
+		return ( records, kind, options ) => kind === 'triangles' ? stage.createTriangleChunkUploader( records, options ) : stage.createChunkUploader( records );
 
 	}
 
-	/** Experimental memory spill for a static scene, in the background. @private */
+	/** The rest of a spilling scene's spill, once it is on the GPU, in the background. @private */
 	_maybeSpill() {
 
-		if ( ! this._memorySpill || ! this.storage || ( this.assetLoader?.animations?.length ?? 0 ) > 0 ) return;
-		this._sdf?.spillToDisk( this.storage )
+		if ( ! this._sdf?.spilling || ! this.storage ) return;
+		this._sdf.spillAfterLoad().catch( error => this._issues.warn( ISSUE_CODES.STORAGE_WRITE_FAILED, `memory spill failed: ${error.message}` ) );
+		this._sdf.spillToDisk( this.storage )
 			.then( result => result && this.dispatchEvent( { type: EngineEvents.SCENE_SPILLED, ...result } ) )
 			.catch( error => this._issues.warn( ISSUE_CODES.STORAGE_WRITE_FAILED, `memory spill failed: ${error.message}` ) );
 
 	}
 
+	/** Once edits have been quiet for {@link RESPILL_AFTER_MS}, puts back on disk what they read back. @private */
+	_scheduleRespill() {
+
+		if ( ! this._sdf?.spilling ) return;
+		clearTimeout( this._respillTimer );
+		this._respillTimer = setTimeout( () => {
+
+			this._respillTimer = null;
+			this._sdf?.respill().catch( error => this._issues.warn( ISSUE_CODES.STORAGE_WRITE_FAILED, `memory spill failed: ${error.message}` ) );
+
+		}, RESPILL_AFTER_MS );
+		this._respillTimer.unref?.();
+
+	}
+
 	/**
-	 * Reads back what {@link options.memorySpill} moved to disk. The engine does this itself before
-	 * its own readers; a host calling {@link refitBLASes} on a spilled scene awaits it first.
+	 * Reads back what {@link options.memorySpill} moved to disk: triangle records, BLAS nodes and the three.js geometry
+	 * (whose arrays are empty until then). The engine does this itself before its own readers; a host calling
+	 * {@link refitBLASes}, or reading the model's geometry, on a spilled scene awaits it first.
 	 */
 	async ensureSceneResident() {
 
 		if ( this._sdf?.spilled ) await this._sdf.ensureResident();
+		await this._sdf?.ensureGeometryResident();
 
 	}
 
@@ -1885,15 +2011,26 @@ export class RayzeeRenderer extends EventDispatcher {
 	 * drags along any other object sharing the same geometry.
 	 *
 	 * @param {number[]} meshIndices - indices into {@link sceneMeshes}
-	 * @returns {{ refitTimeMs: number, placements: number }}
+	 * @returns {?{ refitTimeMs: number, placements: number }} null when the move waits for a spilled scene's data
 	 */
 	updateMeshTransforms( meshIndices ) {
 
+		// A spilled scene's matrix lists, TLAS or copy records are on disk: the move lands once they are back.
+		if ( this._sdf?.needsPageInForMove( meshIndices ) ) {
+
+			this._sdf.ensureMovable( meshIndices )
+				.then( () => this.updateMeshTransforms( meshIndices ) )
+				.catch( error => this._issues.warn( ISSUE_CODES.STORAGE_READ_FAILED, `reading instance matrices back failed: ${error.message}` ) );
+			return null;
+
+		}
+
 		this._notePlacementsMoving( meshIndices );
 		const result = this._sdf.updateMeshTransforms( meshIndices );
 
-		this.stages.pathTracer.updateBufferRanges( [], [ this._sdf.computeTLASDirtyRange() ] );
+		this.stages.pathTracer.updateBufferRanges( [], this._sdf.takeMoveRanges() );
 		this.reset( false, { motion: true } );
+		this._scheduleRespill();
 
 		return result;
 
@@ -2383,6 +2520,7 @@ export class RayzeeRenderer extends EventDispatcher {
 
 		}
 
+		await this._finishImage();
 		return stage.frameCount;
 
 	}
@@ -2460,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;
@@ -2619,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' };
 
 		}
@@ -3198,9 +3340,7 @@ export class RayzeeRenderer extends EventDispatcher {
 	 */
 	setMeshVisibility( meshIndex, visible ) {
 
-		this.stages.pathTracer?.updateMeshVisibility( meshIndex, visible );
-		this._refreshEmissiveForVisibility();
-		this.reset();
+		this._whenTLASEditable( () => this.stages.pathTracer?.updateMeshVisibility( meshIndex, visible ) );
 
 	}
 
@@ -3210,9 +3350,25 @@ export class RayzeeRenderer extends EventDispatcher {
 	 */
 	updateAllMeshVisibility() {
 
-		this.stages.pathTracer?.updateAllMeshVisibility();
-		this._refreshEmissiveForVisibility();
-		this.reset();
+		this._whenTLASEditable( () => this.stages.pathTracer?.updateAllMeshVisibility() );
+
+	}
+
+	/** Applies a visibility edit, then resets — once a spilled TLAS is back in memory. @private */
+	_whenTLASEditable( edit ) {
+
+		const apply = () => {
+
+			edit();
+			this._refreshEmissiveForVisibility();
+			this.reset();
+			this._scheduleRespill();
+
+		};
+
+		const ready = this._sdf?.whenTLASEditable();
+		if ( ! ready ) return apply();
+		ready.then( apply ).catch( error => this._issues.warn( ISSUE_CODES.STORAGE_READ_FAILED, `reading the TLAS back failed: ${error.message}` ) );
 
 	}
 
@@ -3472,7 +3628,18 @@ export class RayzeeRenderer extends EventDispatcher {
 	async rebuildMaterials( scene ) {
 
 		await this.ensureSceneResident();
-		await this.stages.pathTracer?.rebuildMaterials( scene || this.meshScene );
+		const stage = this.stages.pathTracer;
+		await stage?.rebuildMaterials( scene || this.meshScene );
+
+		// Loaded without texture coordinates, and a material has a texture now: they go up again from the records.
+		if ( stage?.triangleStorageNode?.withoutUV && this._sdf?.triangles && usesTextureCoordinates( scene || this.meshScene ) ) {
+
+			this._sdf.textureCoordinates = true;
+			stage.setTriangleData( this._sdf.triangles, this._sdf.triangleCount, { textureCoordinates: true } );
+			stage.setupMaterial();
+
+		}
+
 		this.reset();
 
 	}
@@ -3841,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() {
 
@@ -3891,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?.();
 
 			},