three-gpu-pathtracer 0.0.27 → 0.0.28

package/src/webgpu/WebGPUPathTracer.js

@@ -1,4 +1,4 @@
-import { Box3, DataTexture, LinearFilter, Vector2, Scene, PerspectiveCamera, Color, NoToneMapping, FloatType, Timer, StorageTexture, MeshBasicNodeMaterial, Matrix4, WebGPUCoordinateSystem } from 'three/webgpu';
+import { Box3, DataTexture, EventDispatcher, LinearFilter, MathUtils, Vector2, Scene, PerspectiveCamera, Color, NoToneMapping, FloatType, Timer, StorageTexture, MeshBasicNodeMaterial, Matrix4, WebGPUCoordinateSystem } from 'three/webgpu';
 import { uv, uniform, varying } from 'three/tsl';
 import { SkinnedMeshBVH, MeshBVH, SAH } from 'three-mesh-bvh';
 import { ndcToCameraRay, rayStruct, wgslTagFn } from 'three-mesh-bvh/webgpu';
@@ -11,11 +11,11 @@ import { CubeToEquirectGenerator } from '../utils/CubeToEquirectGenerator.js';
 import { PathtracerBVHComputeData } from './nodes/PathtracerBVHComputeData.js';
 import { AtlasDebugMaterial } from './materials/debug/AtlasDebugMaterial.js';
 import { SampleDensityMaterial } from './materials/debug/SampleDensityMaterial.js';
+import { AuxDebugMaterial } from './materials/debug/AuxDebugMaterial.js';
 import { setCommonAttributes } from '../core/utils/GeometryPreparationUtils.js';
 import { getLights } from '../core/utils/sceneUpdateUtils.js';
 import { GltfCompliantMaterial } from './materials/GltfCompliantMaterial.js';
-import { TRANSMISSIVE_BACKGROUND_OVERLAY } from './constants.js';
-import * as RANDOM_BLUE_DITHER from './nodes/rand/bluedither.wgsl.js';
+import { TRANSMISSIVE_BACKGROUND_OVERLAY, RANDOM_SOBOL } from './constants.js';
 /** @import { Camera, Scene, Texture, WebGPURenderer } from 'three/webgpu' */
 /** @import { AtlasTexture } from './AtlasTexture.js' */
 /** @import { OIDNDenoiser } from './denoise/OIDNDenoiser.js' */
@@ -33,6 +33,71 @@ import * as RANDOM_BLUE_DITHER from './nodes/rand/bluedither.wgsl.js';
 const _resolution = new Vector2();
 const _color = new Color();
 
+// milliseconds between sample count readbacks while waiting for the render to complete
+const COMPLETE_CHECK_INTERVAL = 250;
+
+// How the adaptive frame budget follows the measured frame time. The budget is only reconsidered once
+// a window of measurements has been taken at it, and only changes when their average is off the target
+// by the threshold ratio, since a wavefront budget change reallocates the path buffers. It moves at most
+// the step ratio per window.
+// TODO: adapt more often, with a window of around 4, once the wavefront path buffers are grow-only so a budget
+// change only changes the active slot count rather than reallocating them
+const BUDGET_WINDOW = 16;
+const BUDGET_CHANGE_THRESHOLD = 1.15;
+const BUDGET_MAX_STEP = 2;
+const MIN_FRAME_BUDGET = 4096;
+
+// the options the mesh geometry bvhs are built with and how many workers build them at once
+const MESH_BVH_OPTIONS = { strategy: SAH, targetLeafSize: 5 };
+const MAX_BVH_WORKERS = 4;
+
+// the stages before a scene renders, in order
+const STAGE_BUILDING = 0;
+const STAGE_COMPILING = 1;
+const STAGE_RENDERING = 2;
+
+// Builds a geometry's BVH in a worker without giving up its buffers. The workers transfer the position and
+// index buffers, which neuters them for every other array viewing them, such as the attributes of other
+// meshes in a glTF. So the worker gets copies, the original arrays are restored, and the reordered index
+// is written back into the original. Shared array buffers aren't transferred, so they're sent as is.
+// TODO: this is imperfect, and depends on how the worker transfers. Remove once three-mesh-bvh's worker
+// has an option not to transfer
+async function generateBVHInWorker( worker, geometry, options ) {
+
+	const getCopy = array => {
+
+		const isShared = typeof SharedArrayBuffer !== 'undefined' && array.buffer instanceof SharedArrayBuffer;
+		return isShared ? array : array.slice();
+
+	};
+
+	const { position } = geometry.attributes;
+	const { index } = geometry;
+	const positionArray = position.array;
+	const indexArray = index ? index.array : null;
+
+	position.array = getCopy( positionArray );
+	if ( index ) {
+
+		index.array = getCopy( indexArray );
+
+	}
+
+	const bvh = await worker.generate( geometry, options );
+
+	position.array = positionArray;
+	if ( index ) {
+
+		indexArray.set( index.array );
+		index.array = indexArray;
+		index.needsUpdate = true;
+
+	}
+
+	return bvh;
+
+}
+
 class TextureCache {
 
 	constructor( renderer, key ) {
@@ -94,8 +159,18 @@ class TextureCache {
 
 		} else {
 
-			value = value.clone();
+			// hash the scene's texture rather than the clone, whose uuid is new on every call, so an
+			// unchanged texture isn't cloned and re-processed each time the environment is updated
 			hash = value.uuid + '_' + value.version;
+			if ( hash !== this.hash ) {
+
+				// a nearest filtered texture gets no sampler from TSL, which the equirect sampling
+				// needs, so the copy is always filtered
+				value = value.clone();
+				value.minFilter = LinearFilter;
+				value.magFilter = LinearFilter;
+
+			}
 
 		}
 
@@ -126,6 +201,21 @@ class TextureCache {
 
 }
 
+// WebGPUPathTracer Event Definitions
+
+/**
+ * Fired once every pixel has reached `maxSamples` and an attached denoiser has finished. Fires
+ * again after a reset, or after `maxSamples` is raised, once the render has caught up.
+ * @event WebGPUPathTracer#complete
+ */
+
+/**
+ * Fired as the render advances. `stage` is "building", "compiling", "rendering" or "denoising", and
+ * `progress` is the fraction of it done, or null when unknown. "rendering" also gives the sample
+ * counts as `samples`, reported a few times a second.
+ * @event WebGPUPathTracer#progress
+ */
+
 /**
  * Progressive path tracer running on WebGPU. Call {@link WebGPUPathTracer#setScene} once,
  * then {@link WebGPUPathTracer#renderSample} every frame to accumulate samples into the canvas.
@@ -134,7 +224,7 @@ class TextureCache {
  * the environment afterward require the matching `update*` function. Any change that invalidates
  * the accumulated image restarts it.
  */
-export class WebGPUPathTracer {
+export class WebGPUPathTracer extends EventDispatcher {
 
 	/**
 	 * Maximum number of times a ray can scatter before the path is terminated. Higher values
@@ -156,7 +246,7 @@ export class WebGPUPathTracer {
 	}
 
 	/**
-	 * Number of path slots dispatched per {@link WebGPUPathTracer#renderSample} call,
+	 * Number of path steps dispatched per {@link WebGPUPathTracer#renderSample} call,
 	 * independent of resolution. Raising it trades frame rate for convergence speed.
 	 * @type {number}
 	 * @default 250000
@@ -173,11 +263,23 @@ export class WebGPUPathTracer {
 
 	}
 
+	/**
+	 * GPU time in milliseconds of a recent {@link WebGPUPathTracer#renderSample} call. Only measured
+	 * when the renderer is created with `trackTimestamp: true`.
+	 * @type {number}
+	 * @readonly
+	 */
+	get frameTime() {
+
+		return this._pathTracer.timing.frameTime;
+
+	}
+
 	/**
 	 * Maximum number of alpha tested surfaces a ray can pass through. Counted separately from
 	 * {@link WebGPUPathTracer#maxBounces} so foliage and cutouts cannot exhaust the bounce budget.
 	 * @type {number}
-	 * @default 5
+	 * @default 15
 	 */
 	get maxTransparentBounces() {
 
@@ -192,6 +294,25 @@ export class WebGPUPathTracer {
 
 	}
 
+	/**
+	 * Maximum number of scatter events a path can take inside a subsurface scattering volume. Counted
+	 * separately from {@link WebGPUPathTracer#maxBounces}. Paths that reach it end, darkening dense volumes.
+	 * @type {number}
+	 * @default 256
+	 */
+	get maxSubsurfaceBounces() {
+
+		return this._pathTracer.maxSubsurfaceBounces;
+
+	}
+
+	set maxSubsurfaceBounces( v ) {
+
+		this._pathTracer.maxSubsurfaceBounces = v;
+		this.reset();
+
+	}
+
 	/**
 	 * Stops accumulating once every pixel reaches this many samples. A denoiser only runs once the
 	 * render has stopped, so it has no effect while this is `0`.
@@ -215,6 +336,21 @@ export class WebGPUPathTracer {
 
 	}
 
+	/**
+	 * Whether every pixel has reached {@link WebGPUPathTracer#maxSamples} and an attached denoiser
+	 * has finished, as of the last measurement. Always false while rendering indefinitely.
+	 * @type {boolean}
+	 */
+	get complete() {
+
+		const maxSamples = this.maxSamples;
+		const denoiser = this._denoiser;
+
+		// "min" so every pixel has stopped, not just the average
+		return maxSamples > 0 && this._lastSampleCounts.min >= maxSamples && ( ! denoiser || denoiser.complete );
+
+	}
+
 	/**
 	 * Measures the per pixel sample counts. Use `min` for convergence checks and `avg` to display.
 	 * @returns {Promise<SampleCounts>}
@@ -404,6 +540,19 @@ export class WebGPUPathTracer {
 
 	}
 
+	/**
+	 * Whether the kernels are compiling, such as after the scene or material changes. Nothing new
+	 * renders until they finish and the canvas keeps the last frame, so an app may draw its own
+	 * preview in the meantime.
+	 * @type {boolean}
+	 * @readonly
+	 */
+	get compiling() {
+
+		return this._pathTracer.compiling;
+
+	}
+
 	/**
 	 * The atlas every scene texture is packed into for the kernels to sample.
 	 * @type {AtlasTexture}
@@ -429,6 +578,7 @@ export class WebGPUPathTracer {
 		this._pathTracer.dispose();
 		this._pathTracer = value ? new MegaKernelPathTracer( this._renderer ) : new WaveFrontPathTracer( this._renderer );
 		this._pathTracer.maxSamples = maxSamples;
+		this._timingCount = 0;
 		this._pathTracer.setBVHData( this._bvhData );
 		this._pathTracer.setMaterial( this.material );
 		this._pathTracer.setRandom( this.random );
@@ -436,6 +586,7 @@ export class WebGPUPathTracer {
 		this._pathTracer.setTransmissiveBackground( this._transmissiveBackground );
 		this._pathTracer.setFilterGlossy( this._filterGlossyFactor );
 		this._pathTracer.setClamping( this._clampDirect, this._clampIndirect );
+		this._pathTracer.setAccumulateAux( Boolean( this._denoiser && this._denoiser.useAuxiliaryBuffers ) );
 		this.setCamera( this.camera );
 
 		// the new tracer has default environment and background maps so apply the cached scene textures
@@ -451,6 +602,8 @@ export class WebGPUPathTracer {
 	 */
 	constructor( renderer ) {
 
+		super();
+
 		// members
 		this._renderer = renderer;
 		this._timer = new Timer();
@@ -464,6 +617,16 @@ export class WebGPUPathTracer {
 		this._size = new Vector2();
 		this._blitQuad = new FullScreenQuad( new RenderToScreenNodeMaterial() );
 
+		// adaptive frame budget and preview state
+		this._timingCount = 0;
+		this._frameTimeTotal = 0;
+		this._frameTimeCount = 0;
+		this._warnedTimestamps = false;
+
+		// the budget from before the first pixels finished, restored on reset. The last few pixels render
+		// quickly and inflate the budget
+		this._fullFrameBudget = null;
+
 		// avoid mipmap gen on copy, not always supported with float type
 		this._lowResTarget = new StorageTexture( 1, 1 );
 		this._lowResTarget.type = FloatType;
@@ -475,10 +638,19 @@ export class WebGPUPathTracer {
 		this._denoiser = null;
 		this._upscaler = null;
 
+		// the attached denoiser's progress events are forwarded
+		this._onDenoiserProgress = e => this.dispatchEvent( { type: 'progress', stage: 'denoising', progress: e.progress } );
+
+		// the current stage. Only the latest "setSceneAsync" call sets its scene, and a geometry already building
+		// for an earlier call is awaited rather than built again
+		this._stage = STAGE_RENDERING;
+		this._sceneRequest = 0;
+		this._pendingBVHs = new WeakMap();
+
 		// options
 
 		/**
-		 * Samples every pixel must reach before the full resolution render is faded in.
+		 * Average samples per pixel the full resolution render must reach before it is faded in.
 		 * @type {number}
 		 * @default 1
 		 */
@@ -487,16 +659,16 @@ export class WebGPUPathTracer {
 		/**
 		 * Milliseconds to show the low resolution preview for after a reset.
 		 * @type {number}
-		 * @default 500
+		 * @default 16
 		 */
-		this.renderDelay = 500;
+		this.renderDelay = 16;
 
 		/**
 		 * Milliseconds taken to cross fade from the preview to the full render.
 		 * @type {number}
-		 * @default 500
+		 * @default 250
 		 */
-		this.fadeDuration = 500;
+		this.fadeDuration = 250;
 
 		/**
 		 * Whether to render a low resolution preview while the camera is moving.
@@ -506,12 +678,38 @@ export class WebGPUPathTracer {
 		this.dynamicLowRes = true;
 
 		/**
-		 * Resolution of the low resolution preview, as a fraction of the render size.
+		 * Resolution of the low resolution preview, as a fraction of the render size. Adjusted when
+		 * {@link WebGPUPathTracer#adaptiveDynamicRes} is set. The preview never has more pixels than a
+		 * frame of {@link WebGPUPathTracer#frameBudget} can render.
 		 * @type {number}
 		 * @default 0.1
 		 */
 		this.lowResScale = 0.1;
 
+		/**
+		 * Whether {@link WebGPUPathTracer#lowResScale} is adjusted to the pixels a frame of
+		 * {@link WebGPUPathTracer#frameBudget} can render.
+		 * @type {boolean}
+		 * @default true
+		 */
+		this.adaptiveDynamicRes = true;
+
+		/**
+		 * Whether {@link WebGPUPathTracer#frameBudget} is adjusted to keep each
+		 * {@link WebGPUPathTracer#renderSample} call near {@link WebGPUPathTracer#targetFrameTime} of
+		 * GPU time. Requires a renderer created with `trackTimestamp: true`.
+		 * @type {boolean}
+		 * @default true
+		 */
+		this.adaptiveFrameBudget = true;
+
+		/**
+		 * GPU time in milliseconds per frame targeted by {@link WebGPUPathTracer#adaptiveFrameBudget}.
+		 * @type {number}
+		 * @default 16
+		 */
+		this.targetFrameTime = 16;
+
 		/**
 		 * Resolution the path tracer renders at, as a fraction of the canvas size. Lowering it
 		 * converges faster at the cost of detail, and pairs with an upscaler.
@@ -528,6 +726,23 @@ export class WebGPUPathTracer {
 		 */
 		this.synchronizeRenderSize = true;
 
+		/**
+		 * Whether {@link WebGPUPathTracer#renderSample} draws the result to the current render
+		 * target, the canvas by default. Set to `false` to only accumulate, as when baking to a
+		 * texture read through {@link WebGPUPathTracer#target}.
+		 * @type {boolean}
+		 * @default true
+		 */
+		this.renderToCanvas = true;
+
+		/**
+		 * Whether to compile the kernels asynchronously so a compile doesn't stall the page. Nothing
+		 * new renders while {@link WebGPUPathTracer#compiling} is true.
+		 * @type {boolean}
+		 * @default false
+		 */
+		this.asyncCompile = false;
+
 		/**
 		 * Whether to generate the attributes in {@link WebGPUPathTracer#commonAttributes} on
 		 * geometry that is missing them when the scene is set.
@@ -569,7 +784,7 @@ export class WebGPUPathTracer {
 		 * @type {Object}
 		 * @private
 		 */
-		this.random = RANDOM_BLUE_DITHER;
+		this.random = RANDOM_SOBOL;
 
 		/**
 		 * Material model the kernels evaluate surfaces with.
@@ -583,6 +798,11 @@ export class WebGPUPathTracer {
 		// ( world * inverseProjection ), premultiplied on the CPU so no matrix multiply runs per ray.
 		this._invViewProjectionMatrix = uniform( new Matrix4() );
 		this._cameraRayFnHandle = null;
+		this._BVHWorker = null;
+
+		// the render time of the last check for the render having stopped
+		this._lastCompleteCheck = 0;
+		this._wasComplete = false;
 
 		// initialize the scene so it doesn't fail
 		this.setMaterial( this.material );
@@ -604,7 +824,8 @@ export class WebGPUPathTracer {
 
 	/**
 	 * Attaches a denoiser, run once the render settles and displayed in place of the raw image.
-	 * Settings live on the instance. Pass null to remove it.
+	 * Settings live on the instance. Pass null to remove it. The render restarts when the auxiliary
+	 * buffers it needs are added or dropped.
 	 *
 	 * @param {OIDNDenoiser|null} denoiser
 	 */
@@ -613,15 +834,19 @@ export class WebGPUPathTracer {
 		// a detached instance stops receiving resets, so clear it rather than let it hold a
 		// result from a camera position that has since moved
 		this._denoiser?.reset();
+		this._denoiser?.removeEventListener( 'progress', this._onDenoiserProgress );
 		this._denoiser = denoiser;
 
 		if ( denoiser ) {
 
 			denoiser.init( this._renderer );
-			denoiser.setScene( this.scene, this.camera );
+			denoiser.addEventListener( 'progress', this._onDenoiserProgress );
 
 		}
 
+		this._pathTracer.setAccumulateAux( Boolean( denoiser && denoiser.useAuxiliaryBuffers ) );
+		this.reset();
+
 	}
 
 	/**
@@ -688,7 +913,7 @@ export class WebGPUPathTracer {
 
 				if ( ! child.geometry.boundsTree ) {
 
-					child.geometry.boundsTree = new MeshBVH( child.geometry, { strategy: SAH, targetLeafSize: 5 } );
+					child.geometry.boundsTree = new MeshBVH( child.geometry, MESH_BVH_OPTIONS );
 
 				}
 
@@ -715,8 +940,150 @@ export class WebGPUPathTracer {
 		this.updateEnvironment();
 		this.updateLights();
 
-		// the denoiser rasterizes its own guide buffers, so it needs the scene too
-		this._denoiser?.setScene( scene, camera );
+	}
+
+	/**
+	 * Sets the worker class {@link WebGPUPathTracer#setSceneAsync} builds the mesh geometry BVHs
+	 * with, such as `GenerateMeshBVHWorker` from three-mesh-bvh. Several are created and disposed
+	 * per call so geometries build in parallel.
+	 *
+	 * @param {Function} WorkerConstructor
+	 */
+	setBVHWorker( WorkerConstructor ) {
+
+		this._BVHWorker = WorkerConstructor;
+
+	}
+
+	/**
+	 * Like {@link WebGPUPathTracer#setScene} but builds the mesh geometry BVHs in the workers set
+	 * with {@link WebGPUPathTracer#setBVHWorker} so the page is not blocked. Skinned meshes are
+	 * still built synchronously.
+	 *
+	 * @param {Scene} scene
+	 * @param {Camera} camera
+	 * @returns {Promise<void>}
+	 */
+	async setSceneAsync( scene, camera ) {
+
+		const WorkerConstructor = this._BVHWorker;
+		if ( ! WorkerConstructor ) {
+
+			throw new Error( 'WebGPUPathTracer: "setBVHWorker" must be called before "setSceneAsync" can be called.' );
+
+		}
+
+		this._sceneRequest ++;
+
+		const request = this._sceneRequest;
+		const pendingBVHs = this._pendingBVHs;
+
+		// the worker doesn't support interleaved attributes, so those geometries are built in "setScene" instead
+		const geometries = new Set();
+		const pending = new Set();
+		scene.traverse( child => {
+
+			if ( child.isMesh && ! child.isSkinnedMesh && ! child.geometry.boundsTree ) {
+
+				const { geometry } = child;
+				if ( geometry.attributes.position.isInterleavedBufferAttribute || geometry.index && geometry.index.isInterleavedBufferAttribute ) {
+
+					return;
+
+				}
+
+				if ( pendingBVHs.has( geometry ) ) {
+
+					pending.add( pendingBVHs.get( geometry ) );
+
+				} else {
+
+					geometries.add( geometry );
+
+				}
+
+			}
+
+		} );
+
+		// each worker runs one job at a time so they pull from a shared queue
+		const queue = Array.from( geometries );
+
+		// build progress, weighted by triangle count
+		const getTriangleCount = geometry => ( geometry.index ? geometry.index.count : geometry.attributes.position.count ) / 3;
+		const totalTriangles = queue.reduce( ( sum, geometry ) => sum + getTriangleCount( geometry ), 0 );
+		let builtTriangles = 0;
+
+		const workers = [];
+		for ( let i = 0, l = Math.min( MAX_BVH_WORKERS, queue.length ); i < l; i ++ ) {
+
+			workers.push( new WorkerConstructor() );
+
+		}
+
+		// stop rendering the previous scene while the next one builds, keeping the last frame. The denoiser runs
+		// its tiles on its own schedule, so it's reset separately
+		this._setStage( STAGE_BUILDING );
+		this._denoiser?.reset();
+
+		try {
+
+			await Promise.all( [ ...pending, ...workers.map( async worker => {
+
+				while ( queue.length > 0 ) {
+
+					const geometry = queue.shift();
+					const triangles = getTriangleCount( geometry );
+					let reported = 0;
+					const onProgress = progress => {
+
+						builtTriangles += ( progress - reported ) * triangles;
+						reported = progress;
+
+						// skip if a later call replaced this scene
+						if ( request === this._sceneRequest ) {
+
+							this.dispatchEvent( { type: 'progress', stage: 'building', progress: builtTriangles / totalTriangles } );
+
+						}
+
+					};
+
+					const promise = generateBVHInWorker( worker, geometry, { ...MESH_BVH_OPTIONS, onProgress } );
+					pendingBVHs.set( geometry, promise );
+
+					try {
+
+						geometry.boundsTree = await promise;
+						onProgress( 1 );
+
+					} finally {
+
+						pendingBVHs.delete( geometry );
+
+					}
+
+				}
+
+			} ) ] );
+
+		} finally {
+
+			workers.forEach( worker => worker.dispose() );
+			if ( request === this._sceneRequest ) {
+
+				this._setStage( STAGE_COMPILING );
+
+			}
+
+		}
+
+		// skip the scene if a later call replaced it while it built
+		if ( request === this._sceneRequest ) {
+
+			this.setScene( scene, camera );
+
+		}
 
 	}
 
@@ -942,6 +1309,8 @@ export class WebGPUPathTracer {
 
 		// a fresh object rather than a clear, so measurements still in flight detach
 		this._lastSampleCounts = { min: 0, max: 0, avg: 0, samplesPerSecond: 0 };
+		this._lastCompleteCheck = 0;
+		this._wasComplete = false;
 
 		if ( this.stableNoise ) {
 
@@ -949,6 +1318,130 @@ export class WebGPUPathTracer {
 
 		}
 
+		if ( this._fullFrameBudget !== null ) {
+
+			this.frameBudget = this._fullFrameBudget;
+			this._fullFrameBudget = null;
+
+		}
+
+	}
+
+	// Sets the stage, reporting when each one starts
+	_setStage( stage ) {
+
+		if ( this._stage === stage ) {
+
+			return;
+
+		}
+
+		this._stage = stage;
+		if ( stage === STAGE_BUILDING ) {
+
+			this.dispatchEvent( { type: 'progress', stage: 'building', progress: 0 } );
+
+		} else if ( stage === STAGE_COMPILING ) {
+
+			this.dispatchEvent( { type: 'progress', stage: 'compiling', progress: null } );
+
+		} else {
+
+			this._dispatchRenderProgress( { min: 0, max: 0, avg: 0, samplesPerSecond: 0 } );
+
+		}
+
+	}
+
+	// Measures the sample counts and reports them
+	_measureSamples() {
+
+		const counts = this._lastSampleCounts;
+		this.getSampleCountsAsync().then( samples => {
+
+			// skip if the render was reset or a new scene started building meanwhile
+			if ( counts === this._lastSampleCounts && this._stage === STAGE_RENDERING ) {
+
+				// save the budget once the first pixels finish
+				const { maxSamples } = this;
+				if ( this._fullFrameBudget === null && maxSamples > 0 && samples.max >= maxSamples ) {
+
+					this._fullFrameBudget = this.frameBudget;
+
+				}
+
+				this._dispatchRenderProgress( samples );
+
+			}
+
+		} );
+
+	}
+
+	_dispatchRenderProgress( samples ) {
+
+		const { maxSamples } = this;
+		const progress = maxSamples > 0 ? Math.min( samples.avg / maxSamples, 1 ) : null;
+		this.dispatchEvent( { type: 'progress', stage: 'rendering', progress, samples } );
+
+	}
+
+	// Adapts the frame budget to the tracer's latest gpu time measurement
+	_readTiming() {
+
+		const { timing } = this._pathTracer;
+		const { trackTimestamp } = this._renderer.backend;
+		if ( this.adaptiveFrameBudget && ! trackTimestamp && ! this._warnedTimestamps ) {
+
+			console.warn( 'WebGPUPathTracer: "adaptiveFrameBudget" needs timestamp queries. Create the renderer with "trackTimestamp: true" on a device that supports them.' );
+			this._warnedTimestamps = true;
+
+		}
+
+		if ( timing.count === this._timingCount ) {
+
+			return;
+
+		}
+
+		this._timingCount = timing.count;
+
+		// a measurement from before the budget changed doesn't describe the current one
+		const { frameBudget } = timing;
+		if ( ! this.adaptiveFrameBudget || frameBudget !== this.frameBudget ) {
+
+			this._frameTimeTotal = 0;
+			this._frameTimeCount = 0;
+			return;
+
+		}
+
+		this._frameTimeTotal += timing.frameTime;
+		this._frameTimeCount ++;
+		if ( this._frameTimeCount < BUDGET_WINDOW ) {
+
+			return;
+
+		}
+
+		const { targetFrameTime } = this;
+		const average = this._frameTimeTotal / this._frameTimeCount;
+		this._frameTimeTotal = 0;
+		this._frameTimeCount = 0;
+
+		// leave the budget alone while it's close enough to the target
+		const ratio = average / targetFrameTime;
+		if ( ratio < BUDGET_CHANGE_THRESHOLD && ratio > 1 / BUDGET_CHANGE_THRESHOLD ) {
+
+			return;
+
+		}
+
+		// scale the budget to land the average on the target
+		const next = frameBudget * targetFrameTime / average;
+		const stepped = MathUtils.clamp( next, frameBudget / BUDGET_MAX_STEP, frameBudget * BUDGET_MAX_STEP );
+		this.frameBudget = Math.max( Math.round( stepped ), MIN_FRAME_BUDGET );
+
 	}
 
 	/**
@@ -967,7 +1460,7 @@ export class WebGPUPathTracer {
 			dynamicLowRes,
 			synchronizeRenderSize,
 			renderScale,
-			lowResScale,
+			adaptiveDynamicRes,
 			minSamples,
 			maxSamples,
 		} = this;
@@ -1016,35 +1509,61 @@ export class WebGPUPathTracer {
 		const lowResMode = this._resetTime < renderDelay || ( firstFrame && dynamicLowRes && minSamples !== 0 );
 		if ( lowResMode ) {
 
-			width = Math.ceil( lowResScale * width );
-			height = Math.ceil( lowResScale * height );
+			// the most pixels a preview frame can render within the frame budget. Pixels past it are never
+			// reached by the wavefront in a preview
+			const budgetScale = Math.min( Math.sqrt( pathTracer.getPreviewPixelBudget() / ( width * height ) ), 1 );
+
+			if ( adaptiveDynamicRes ) {
+
+				this.lowResScale = budgetScale;
+
+			}
+
+			// checked every frame since the budget adapts separately
+			const scale = Math.min( this.lowResScale, budgetScale );
+			width = Math.max( 1, Math.floor( scale * width ) );
+			height = Math.max( 1, Math.floor( scale * height ) );
 
 		}
 
 		// set the size if necessary
 		pathTracer.getSize( _resolution );
 
-		const resized = _resolution.x !== width || _resolution.y !== height;
-		if ( resized ) {
+		// copy the low res content when transitioning to the full resolution view so we can fade from
+		// it, including when the preview was already full size and nothing is resized
+		if ( ! lowResMode && pathTracer.lowResMode && dynamicLowRes ) {
 
-			if ( ! lowResMode && dynamicLowRes ) {
+			lowResTarget.setSize( _resolution.x, _resolution.y );
+			renderer.copyTextureToTexture( pathTracer.outputTarget, lowResTarget );
 
-				// copy the low reset content if we're transitioning to the full
-				// resolution view so we can fade to it
-				lowResTarget.setSize( Math.ceil( lowResScale * width ), Math.ceil( lowResScale * height ) );
-				renderer.copyTextureToTexture( pathTracer.outputTarget, lowResTarget );
+		}
 
-			}
+		if ( _resolution.x !== width || _resolution.y !== height ) {
 
 			pathTracer.setSize( width, height );
 
 		}
 
-		// update the samples
-		if ( ! this.pause && ( ! lowResMode || ( lowResMode && dynamicLowRes ) ) ) {
+		// update the samples, stopping once every pixel has reached "maxSamples"
+		const samplesComplete = maxSamples > 0 && this._lastSampleCounts.min >= maxSamples;
+		if ( ! this.pause && ! samplesComplete && this._stage > STAGE_BUILDING && ( ! lowResMode || ( lowResMode && dynamicLowRes ) ) ) {
 
 			pathTracer.lowResMode = lowResMode;
+			pathTracer.asyncCompile = this.asyncCompile;
 			pathTracer.update();
+			this._readTiming();
+			this._setStage( pathTracer.compiling ? STAGE_COMPILING : STAGE_RENDERING );
+
+		}
+
+		// nothing renders while the next scene's BVHs build or the kernels compile, so restart the preview timer and
+		// keep the last frame
+		// TODO: decide what to display meanwhile - the last frame goes stale when the camera moves, and a
+		// rasterized preview compiles its own materials
+		if ( this._stage < STAGE_RENDERING ) {
+
+			this._resetTime = - 1;
+			return;
 
 		}
 
@@ -1056,17 +1575,25 @@ export class WebGPUPathTracer {
 		// counts every frame. A count of the camera rays dispatched would answer it in one value
 		const awaitingDenoise = Boolean( denoiser ) && ! denoiser.complete && ! denoiser.running && maxSamples > 0;
 
-		// Gate on the least converged pixel. Measuring is expensive so it stops once faded in, and
+		// Gate on the average pixel. Measuring is expensive so it stops once faded in, and
 		// the check reads the last measurement rather than waiting on this one.
 		if ( ! lowResMode ) {
 
-			if ( ( this._fadeState < 1 && minSamples > 0 ) || awaitingDenoise ) {
+			// the counts can't change once every pixel has finished, so measuring stops
+			if ( ! samplesComplete && this._fadeState < 1 && minSamples > 0 ) {
+
+				this._measureSamples();
 
-				this.getSampleCountsAsync();
+			} else if ( ! samplesComplete && this._resetTime - this._lastCompleteCheck >= COMPLETE_CHECK_INTERVAL ) {
+
+				// the readback stalls the gpu pipeline, so the render only measures a few times a second.
+				// The "progress" and "complete" events and the denoiser key off it
+				this._lastCompleteCheck = this._resetTime;
+				this._measureSamples();
 
 			}
 
-			if ( this._lastSampleCounts.min >= minSamples ) {
+			if ( this._lastSampleCounts.avg >= minSamples ) {
 
 				this._fadeState += delta / this.fadeDuration;
 				this._fadeState = Math.min( 1.0, this._fadeState ) || 1.0;
@@ -1086,7 +1613,7 @@ export class WebGPUPathTracer {
 			// "min" so every pixel has stopped, not just the average
 			if ( awaitingDenoise && this._lastSampleCounts.min >= maxSamples ) {
 
-				denoiser.update( pathTracer.outputTarget );
+				denoiser.update( pathTracer.outputTarget, pathTracer.auxTarget );
 
 			}
 
@@ -1094,26 +1621,41 @@ export class WebGPUPathTracer {
 
 		}
 
-		if ( upscaler && ! lowResMode ) {
+		// the upscale and the draw only serve the display
+		if ( this.renderToCanvas ) {
 
-			texture = upscaler.upscale( texture, this.camera );
+			if ( upscaler && ! lowResMode ) {
 
-			// the pass above binds its own targets
-			renderer.setRenderTarget( originalTarget );
+				texture = upscaler.upscale( texture, this.camera );
 
-		}
+				// the pass above binds its own targets
+				renderer.setRenderTarget( originalTarget );
+
+			}
+
+			renderer.autoClear = dynamicLowRes ? true : opacity === 1.0;
+			blitQuad.material.transition = dynamicLowRes ? opacity : 1.0;
+			blitQuad.material.opacity = dynamicLowRes ? 1.0 : opacity;
+			blitQuad.material.fromTexture = lowResTarget;
+			blitQuad.material.texture = texture;
+			blitQuad.render( renderer );
 
-		renderer.autoClear = dynamicLowRes ? true : opacity === 1.0;
-		blitQuad.material.transition = dynamicLowRes ? opacity : 1.0;
-		blitQuad.material.opacity = dynamicLowRes ? 1.0 : opacity;
-		blitQuad.material.fromTexture = lowResTarget;
-		blitQuad.material.texture = texture;
-		blitQuad.render( renderer );
+		}
 
 		// reset the renderer
 		renderer.autoClear = originalAutoClear;
 		renderer.setRenderTarget( originalTarget );
 
+		// fires once the render, and the denoiser if one is attached, has finished and the result is drawn
+		const complete = this.complete;
+		if ( complete && ! this._wasComplete ) {
+
+			this.dispatchEvent( { type: 'complete' } );
+
+		}
+
+		this._wasComplete = complete;
+
 	}
 
 	/**
@@ -1263,6 +1805,42 @@ export class WebGPUPathTracer {
 
 	}
 
+	/**
+	 * Draws the albedo or normal auxiliary buffer accumulated for the denoiser, for checking what
+	 * it is given. Nothing is drawn until a denoiser that uses them is attached.
+	 *
+	 * @param {'albedo'|'normal'} [buffer='albedo']
+	 */
+	renderAuxBuffer( buffer = 'albedo' ) {
+
+		const renderer = this._renderer;
+		const pathTracer = this._pathTracer;
+
+		if ( ! renderer._initialized || ! pathTracer.auxTarget ) {
+
+			return;
+
+		}
+
+		if ( ! this._auxDebugQuad ) {
+
+			this._auxDebugQuad = new FullScreenQuad( new AuxDebugMaterial() );
+
+		}
+
+		const originalToneMapping = renderer.toneMapping;
+		renderer.toneMapping = NoToneMapping;
+
+		const quad = this._auxDebugQuad;
+		quad.material.texture = pathTracer.auxTarget;
+		quad.material.showNormal = buffer === 'normal';
+		renderer.setRenderTarget( null );
+		quad.render( renderer );
+
+		renderer.toneMapping = originalToneMapping;
+
+	}
+
 	/**
 	 * Frees every GPU resource held by the tracer, including any attached denoiser and upscaler.
 	 */
@@ -1284,6 +1862,8 @@ export class WebGPUPathTracer {
 		this._atlasDebugQuad?.material.dispose();
 		this._sampleDensityQuad?.dispose();
 		this._sampleDensityQuad?.material.dispose();
+		this._auxDebugQuad?.dispose();
+		this._auxDebugQuad?.material.dispose();
 
 		if ( this._debugBoundsQuad !== undefined ) {