rayzee 8.0.0 → 8.2.0

package/src/PathTracerApp.js

@@ -362,8 +362,12 @@ export class PathTracerApp extends EventDispatcher {
 
 		}
 
+		const cameraMoved = this.needsReset;
 		if ( this.needsReset ) {
 
+			// Before the reset, so the denoising manager's abort sees this frame as part of a move
+			// rather than deciding to hold on the first frame and dropping it on the second.
+			this.stages.pathTracer?.noteViewChanged();
 			this.reset( true );
 			this.needsReset = false;
 
@@ -404,6 +408,23 @@ export class PathTracerApp extends EventDispatcher {
 
 			}
 
+			// A frame traced while a denoise is in flight is never seen: only denoised frames reach
+			// the canvas during a camera move, and the next denoise reads the newest frame anyway.
+			// Tracing it only takes the GPU away from the denoise the viewport is waiting on —
+			// inside a room that turned a 10 ms denoise into 185 ms of wall clock.
+			if ( this.denoisingManager?.skipsTrace() ) {
+
+				// The camera is still being dragged; without this the interaction timeout can
+				// expire inside a long denoise and drop the view out of interaction mode.
+				if ( cameraMoved ) this.stages.pathTracer.enterInteractionMode();
+				// Gizmos and outlines are drawn against the live camera, not the traced frame, so
+				// they would visibly lag the view if they only redrew on the frames that traced.
+				this._renderHelperOverlay();
+				this.dispatchEvent( { type: EngineEvents.FRAME } );
+				return;
+
+			}
+
 			this.pipeline.render();
 
 			if ( ! this.stages.pathTracer.isComplete ) {
@@ -540,7 +561,9 @@ export class PathTracerApp extends EventDispatcher {
 
 		}
 
-		this._abortPostProcess();
+		// Whatever is on screen stays until its replacement is ready, including while the camera
+		// moves: the denoising manager decides, since only it knows something is coming.
+		this._abortPostProcess( { keepDisplay: true } );
 
 		this.completion.reset();
 		this.wake();
@@ -713,6 +736,7 @@ export class PathTracerApp extends EventDispatcher {
 
 		}
 
+		this.denoisingManager?.dropDisplay();
 		this.reset();
 		this.dispatchEvent( { type: 'SceneUnloaded' } );
 
@@ -962,6 +986,9 @@ export class PathTracerApp extends EventDispatcher {
 			this._syncControlsAfterLoad();
 			await this.loadSceneData( { pendingEnvironment: this._beginSceneMetadataEnvironment() } );
 			this.pipeline?.eventBus.emit( 'autoexposure:resetHistory' );
+			// Not held: the first denoise of a new scene lands ~1.1 s after the load (upload and
+			// shader compilation come first), and a second of the previous model reads as a bug.
+			this.denoisingManager?.dropDisplay();
 			this.reset();
 			this.cameraManager.currentCameraIndex = 0;
 			this.dispatchEvent( eventPayload );
@@ -994,6 +1021,7 @@ export class PathTracerApp extends EventDispatcher {
 
 			this._clearAppendedModels();
 			this.assetLoader?.releaseTargetModel();
+			this.denoisingManager?.dropDisplay();
 			this.reset();
 
 		} catch ( cleanupError ) {
@@ -1853,6 +1881,10 @@ export class PathTracerApp extends EventDispatcher {
 		const isProduction = mode === 'production';
 		const config = isProduction ? PRODUCTION_RENDER_CONFIG : INTERACTIVE_RENDER_CONFIG;
 
+		// First, before anything below can wake the loop or resize the renderer: a live-view
+		// refresh landing in the middle of that raced the renderer's own output pass.
+		this.denoisingManager?.setCadenceSuspended( isProduction );
+
 		this.cameraManager.controls.enabled = ! isProduction;
 
 		// Anything with a SETTING_ROUTES entry must go through settings, not setUniform: set() early-returns on
@@ -1935,9 +1967,9 @@ export class PathTracerApp extends EventDispatcher {
 
 	// Aborts any in-flight denoise/upscale and puts the denoiser canvas back at base resolution (the
 	// upscaler leaves it enlarged), so the live canvas is what's on screen again.
-	_abortPostProcess() {
+	_abortPostProcess( { keepDisplay = false } = {} ) {
 
-		this.denoisingManager?.abort( this.canvas );
+		this.denoisingManager?.abort( this.canvas, { keepDisplay } );
 
 		if ( this.denoisingManager?.restoreBaseResolution() ) {
 
@@ -2423,8 +2455,8 @@ export class PathTracerApp extends EventDispatcher {
 	// ═══════════════════════════════════════════════════════════════
 
 	/**
-	 * Returns the canvas element with the final rendered image.
-	 * Chooses the post-processing canvas when denoiser/upscaler are active.
+	 * Returns the canvas element holding the image on screen — denoised, graded and tone-mapped,
+	 * whatever is currently showing. The upscaler is the one thing that paints elsewhere.
 	 * @returns {HTMLCanvasElement|null}
 	 */
 	getCanvas() {
@@ -2432,13 +2464,13 @@ export class PathTracerApp extends EventDispatcher {
 		if ( ! this.renderer?.domElement ) return null;
 
 		const dm = this.denoisingManager;
-		const usePostProcess = ( dm?.denoiser?.enabled || dm?.upscaler?.enabled )
-			&& dm?.denoiserCanvas
-			&& this.stages.pathTracer?.isComplete;
+		const upscaled = dm?.upscaler?.enabled && dm?.upscalerCanvas
+			&& dm.upscalerCanvas.style.display !== 'none';
 
-		if ( usePostProcess ) return dm.denoiserCanvas;
+		if ( upscaled ) return dm.upscalerCanvas;
 
-		// Re-render compositor stage so the WebGPU canvas has valid content
+		// A presented WebGPU canvas only reads back what was drawn immediately before, so draw.
+		// This also puts the denoised picture on it: the Compositor prefers it over the raw render.
 		if ( this.stages.compositor && this.pipeline?.context ) {
 
 			this.stages.compositor.render( this.pipeline.context );
@@ -2881,16 +2913,41 @@ export class PathTracerApp extends EventDispatcher {
 
 		const adapterLimits = adapter.limits;
 
+		// A limit that is NOT requested is granted at WebGPU's portable default, never at the
+		// adapter's maximum — on Apple Metal-3 that is 16 sampled textures of 48, 4 storage
+		// textures of 8, 256 workgroup invocations of 1024 and 256 array layers of 2048.
+		// Requesting exactly what the adapter reports can never fail, so a weaker GPU simply
+		// gets less and every consumer has to stay adaptive.
+		const requiredLimits = { maxColorAttachmentBytesPerSample: 128 };
+
+		for ( const key of [
+			'maxBufferSize',
+			'maxStorageBufferBindingSize',
+			'maxSampledTexturesPerShaderStage',
+			'maxStorageTexturesPerShaderStage',
+			'maxTextureArrayLayers',
+			'maxTextureDimension2D',
+			'maxComputeInvocationsPerWorkgroup',
+			'maxComputeWorkgroupStorageSize',
+			'maxComputeWorkgroupSizeX',
+			'maxComputeWorkgroupSizeY',
+			'maxComputeWorkgroupSizeZ',
+		] ) {
+
+			const value = adapterLimits[ key ];
+			if ( value !== undefined ) requiredLimits[ key ] = value;
+
+		}
+
+		// Shade binds exactly 10 and the kernels are written to that budget; asking for more
+		// buys nothing, and 10 is already this adapter's ceiling.
+		requiredLimits.maxStorageBuffersPerShaderStage = Math.min( adapterLimits.maxStorageBuffersPerShaderStage, 10 );
+
 		this.renderer = new WebGPURenderer( {
 			canvas: this.canvas,
 			alpha: true,
 			powerPreference: 'high-performance',
-			requiredLimits: {
-				maxBufferSize: adapterLimits.maxBufferSize,
-				maxStorageBufferBindingSize: adapterLimits.maxStorageBufferBindingSize,
-				maxColorAttachmentBytesPerSample: 128,
-				maxStorageBuffersPerShaderStage: Math.min( adapterLimits.maxStorageBuffersPerShaderStage, 10 ),
-			}
+			requiredLimits,
 		} );
 
 		await this.renderer.init();
@@ -3236,8 +3293,6 @@ export class PathTracerApp extends EventDispatcher {
 		this.denoisingManager = new DenoisingManager( {
 			renderer: this.renderer,
 			mainCanvas: this.canvas,
-			scene: this.scene,
-			camera: this.cameraManager.camera,
 			stages: {
 				pathTracer: this.stages.pathTracer,
 				normalDepth: this.stages.normalDepth,
@@ -3253,7 +3308,6 @@ export class PathTracerApp extends EventDispatcher {
 			pipeline: this.pipeline,
 			getExposure: () => this.settings.get( 'exposure' ) ?? 1.0,
 			getSaturation: () => this.settings.get( 'saturation' ) ?? 1.0,
-			getTransparentBg: () => this.settings.get( 'transparentBackground' ) ?? false,
 		} );
 
 		this.denoisingManager.setupDenoiser();

package/src/Processor/GeometryExtractor.js

@@ -965,7 +965,9 @@ export class GeometryExtractor {
 	getTextureMatrix( texture ) {
 
 		if ( ! texture ) return new Matrix3().elements;
-		texture.updateMatrix();
+		// GLTFLoader writes `matrix` itself for a rotated KHR_texture_transform (glTF is
+		// T·R·S, three is T·S·R) and clears the flag; updateMatrix() ignores the flag.
+		if ( texture.matrixAutoUpdate ) texture.updateMatrix();
 		return texture.matrix.elements;
 
 	}

package/src/Processor/utils.js

@@ -1,10 +1,6 @@
 import { SphereGeometry, Mesh, MeshPhysicalMaterial, Group, Object3D, Color, Vector3, ShaderMaterial, Vector2, Matrix4, GLSL3 } from 'three';
-import { QuadMesh } from 'three/webgpu';
 import { EngineEvents } from '../EngineEvents.js';
 
-/** Every QuadMesh in the realm shares this one geometry (module-level in three). */
-const _sharedQuadGeometry = /*@__PURE__*/ new QuadMesh( null ).geometry;
-
 let _statusCallback = null;
 
 /**
@@ -103,17 +99,18 @@ export function distroyBuffers( { material, geometry, children } ) {
 /**
  * Disposes a renderer without leaking it.
  *
- * Three.js 0.184–0.185: `Renderer.dispose()` does not remove the 'resize' listener
+ * Three.js 0.184–0.186: `Renderer.dispose()` does not remove the 'resize' listener
  * it installs on `_canvasTarget`. The bound handler closes over the renderer,
  * pinning the entire WebGPU graph (Backend, Nodes, Bindings, Pipelines, GPUDevice,
  * every TSL node) alive indefinitely — confirmed via heap-snapshot retainer
- * analysis. See three/src/renderers/common/Renderer.js:292 (attach) and :2503
- * (dispose — missing removal).
+ * analysis. See `Renderer.js` (attach in the constructor, still absent from
+ * `dispose()` in r186). Re-check on every upgrade; drop this when upstream fixes it.
  *
  * Renderers constructed with an external `device` do not destroy it here; three
  * only destroys a device it created itself.
  *
  * @param {import('three/webgpu').WebGPURenderer} renderer
+ * @returns {?Promise<void>} Settles once the backend is torn down.
  */
 export function disposeRenderer( renderer ) {
 
@@ -125,20 +122,11 @@ export function disposeRenderer( renderer ) {
 
 	}
 
-	renderer.dispose();
+	// r186+ `dispose()` is async and settles once the backend is torn down; anything that
+	// measures memory straight afterwards has to await the returned promise.
+	const disposed = renderer.dispose();
 	renderer._canvasTarget = null;
-
-	// Three.js 0.185: `RenderObjects.dispose()` drops its chain maps without disposing the
-	// render objects, so each one leaves behind the 'dispose' listener it registered on its
-	// geometry. Full-screen passes render a QuadMesh, and every QuadMesh in the realm shares
-	// one module-level geometry — so that listener list grows by one entry per renderer and
-	// keeps RenderObject → RenderObjects → Bindings → Backend → GPUDevice reachable for the
-	// page's lifetime. The chain maps are WeakMaps, so this list is the only handle on them.
-	//
-	// Clearing it also drops entries belonging to live renderers, which is safe: the
-	// singleton geometry is never disposed, so none of these listeners can ever fire.
-	const quadDisposeListeners = _sharedQuadGeometry._listeners?.dispose;
-	if ( quadDisposeListeners ) quadDisposeListeners.length = 0;
+	return disposed;
 
 }
 

package/src/Stages/Compositor.js

@@ -67,6 +67,7 @@ export class Compositor extends RenderStage {
 	_resolveSourceTexture( context ) {
 
 		return context.getTexture( 'bloom:output' )
+			|| context.getTexture( 'oidn:output' )
 			|| context.getTexture( 'edgeFiltering:output' )
 			|| context.getTexture( 'bilateralFiltering:output' )
 			|| context.getTexture( 'asvgf:output' )

package/src/Stages/PathTracerStage.js

@@ -30,6 +30,10 @@ import { createLogger, fmt } from '../utils/Logger.js';
 
 const log = createLogger( 'pathtracer' );
 
+// How long after the last move the view still counts as moving. Matches CameraOptimizer's own
+// settle delay, so the answer does not change when interaction mode is switched off.
+const VIEW_SETTLE_MS = 100;
+
 /**
  * Data layout constants
  */
@@ -163,6 +167,8 @@ export class PathTracerStage extends RenderStage {
 
 		// Track changes for event emission
 		this.cameraChanged = false;
+		// When the view was last moved, for viewIsChanging.
+		this._lastViewChangeAt = - Infinity;
 
 		// Update completion threshold
 		this.updateCompletionThreshold();
@@ -704,6 +710,25 @@ export class PathTracerStage extends RenderStage {
 
 	}
 
+	/**
+	 * Whether the view is being moved right now — the camera or a gizmo — whether or not interaction
+	 * mode is on. Interaction mode answers a narrower question (may quality be reduced) and is a
+	 * switch a host can turn off; what a denoiser needs to know is only whether this frame is about
+	 * to be thrown away by the next move.
+	 */
+	get viewIsChanging() {
+
+		return this.interactionMode || performance.now() - this._lastViewChangeAt < VIEW_SETTLE_MS;
+
+	}
+
+	// Called by the host loop on a frame whose reset came from the view moving.
+	noteViewChanged() {
+
+		this._lastViewChangeAt = performance.now();
+
+	}
+
 	// ===== TEXTURE SETTERS =====
 
 	/**

package/src/TSL/SortGlobalKernels.js

@@ -21,11 +21,10 @@ import {
 	Fn, uint,
 	If, Loop,
 	instanceIndex, localId,
-	workgroupBarrier,
+	workgroupBarrier, workgroupArray,
 	atomicAdd, atomicLoad, atomicStore,
 } from 'three/tsl';
 
-import { workgroupAtomicArray } from './patches.js';
 import { readHitMaterialIndex } from '../Processor/PackedRayBuffer.js';
 import { COUNTER } from '../Processor/QueueManager.js';
 
@@ -54,7 +53,7 @@ export function buildGlobalHistKernel( { hitBufferRO, activeIndicesReadRO, sortG
 
 		const tid = instanceIndex;
 		const lid = localId.x;
-		const local = workgroupAtomicArray( 'uint', bins );
+		const local = workgroupArray( 'uint', bins ).toAtomic();
 
 		If( lid.lessThan( uint( bins ) ), () => {
 
@@ -127,7 +126,7 @@ export function buildGlobalScatterKernel( { hitBufferRO, activeIndicesReadRO, so
 
 		const tid = instanceIndex;
 		const lid = localId.x;
-		const local = workgroupAtomicArray( 'uint', bins );
+		const local = workgroupArray( 'uint', bins ).toAtomic();
 
 		If( lid.lessThan( uint( bins ) ), () => {
 

package/src/TSL/patches.js

@@ -7,12 +7,15 @@
  * loop) and `initTimestampQuery` (enlarges the stats-gl timestamp query pool so
  * the wavefront tracer's high per-frame compute-pass count doesn't overflow it).
  *
+ * Also overrides `ContextNode.prototype.setup` to undo an r186 codegen regression
+ * (§4) — that one is temporary and goes away at r187.
+ *
  * Exports: `struct()` — drop-in replacement for TSL's `struct()` returning
  * a proxy factory that supports GLSL-style dot-notation field access — and
  * `gpuOnlyStorageAttribute()`, a storage attribute with no CPU backing array.
  */
 
-import { StorageInstancedBufferAttribute, WebGPUBackend } from 'three/webgpu';
+import { ContextNode, StorageInstancedBufferAttribute, WebGPUBackend } from 'three/webgpu';
 import { struct as _struct } from 'three/tsl';
 
 // ---------------------------------------------------------------------------
@@ -62,10 +65,6 @@ WebGPUBackend.prototype.createNodeBuilder = function ( object, renderer ) {
 		configurable: true,
 	} );
 
-	// Install the workgroup-atomic-array codegen patch (section 4) lazily off the
-	// first builder, so we don't need to import WGSLNodeBuilder directly.
-	_installScopedArrayAtomicPatch( builder );
-
 	return builder;
 
 };
@@ -351,87 +350,28 @@ export function struct( members, name = null ) {
 }
 
 // ---------------------------------------------------------------------------
-// 4. Workgroup-scoped atomic arrays — var<workgroup> array<atomic<T>, N>
+// 4. r186 ContextNode.setup regression — DELETE WHEN THE three DEP REACHES r187
 // ---------------------------------------------------------------------------
-// TSL's `workgroupArray(type, count)` emits `var<workgroup> name: array<T, N>`
-// (`WGSLNodeBuilder.getScopedArrays`, r185 ~line 1773) with a NON-atomic element
-// type, so `atomicAdd(arr.element(i), v)` fails WGSL validation. AtomicFunctionNode
-// is itself address-space-agnostic — it emits `atomicAdd(&name[i], v)`, valid for
-// BOTH storage and workgroup pointers — so the ONLY missing piece is the
-// declaration. This patch adds `workgroupAtomicArray()` (a `workgroupArray` tagged
-// atomic) and overrides `getScopedArrays` to wrap the element type in `atomic<…>`
-// for tagged arrays, enabling true on-chip workgroup-shared atomics (e.g. fast
-// per-workgroup histograms) instead of the slow global-storage-atomic fallback.
-// Access tagged arrays ONLY via atomic ops (atomicAdd/atomicLoad/atomicStore).
-
-import { workgroupArray } from 'three/tsl';
-
-const _WorkgroupInfoNode = workgroupArray( 'uint', 1 ).constructor;
-
-// Tag the node so the patched getScopedArrays emits an atomic element type. The
-// array's WGSL name is only known after generate() runs, so we mark the builder's
-// scopedArrays entry there (idempotent across analyze/generate passes).
-const _origWorkgroupGenerate = _WorkgroupInfoNode.prototype.generate;
-
-_WorkgroupInfoNode.prototype.generate = function ( builder ) {
+// r186 (#34251) made `ContextNode.setup()` return the node it had just built.
+// Returning it stores the child's output node in the context node's own
+// properties, so `Node.build()` then re-builds it generically OUTSIDE the
+// context. `Loop()` wraps its body in a context (`fnCall.context({ nodeLoop })`),
+// so every loop-heavy kernel is evaluated against the wrong one — measured on our
+// corpus as 63x energy on furnace-clearcoat, 5.8x on furnace-sheen and NaN in the
+// SSS random walk, all while the WGSL compiled without a single error.
+//
+// Upstream reverted it in #34531 (merged 2026-09-11, on dev, ships in r187); this
+// body is that revert verbatim, and is also what r185 shipped, so it stays correct
+// if the dep is rolled back. Verified: with it, all 27 quality scenes pass and the
+// numbers are identical to r185. Drop this section and the `ContextNode` import
+// once the dep is r187+.
 
-	const name = _origWorkgroupGenerate.call( this, builder );
-	if ( this.isAtomicArray === true ) {
+ContextNode.prototype.setup = function ( builder ) {
 
-		const entry = builder.scopedArrays && builder.scopedArrays.get( name );
-		if ( entry ) entry.isAtomic = true;
+	const previousContext = builder.addContext( this.value );
 
-	}
+	this.node.build( builder );
 
-	return name;
+	builder.setContext( previousContext );
 
 };
-
-/**
- * Like `workgroupArray(type, count)` but declares the workgroup buffer with an
- * atomic element type: `var<workgroup> name: array<atomic<type>, count>`.
- * Elements MUST be accessed only via atomic ops (atomicAdd/atomicLoad/atomicStore).
- *
- * @param {string} type - Element type (e.g. 'uint').
- * @param {number} count - Number of elements.
- * @returns {WorkgroupInfoNode} The tagged workgroup array node.
- */
-export function workgroupAtomicArray( type, count ) {
-
-	const node = workgroupArray( type, count );
-	node.isAtomicArray = true;
-	return node;
-
-}
-
-let _scopedArraysPatched = false;
-
-// Override getScopedArrays on the builder's prototype (compute-stage WGSL
-// assembly) to emit `atomic<T>` element types for tagged workgroup arrays.
-// Installed once, lazily, off the first node builder created.
-function _installScopedArrayAtomicPatch( builder ) {
-
-	if ( _scopedArraysPatched ) return;
-	const proto = Object.getPrototypeOf( builder );
-	if ( ! proto || typeof proto.getScopedArrays !== 'function' ) return;
-
-	proto.getScopedArrays = function ( shaderStage ) {
-
-		if ( shaderStage !== 'compute' ) return;
-
-		const snippets = [];
-		for ( const { name, scope, bufferType, bufferCount, isAtomic } of this.scopedArrays.values() ) {
-
-			const type = this.getType( bufferType );
-			const elementType = ( isAtomic === true ) ? `atomic< ${ type } >` : type;
-			snippets.push( `var<${ scope }> ${ name }: array< ${ elementType }, ${ bufferCount } >;` );
-
-		}
-
-		return snippets.join( '\n' );
-
-	};
-
-	_scopedArraysPatched = true;
-
-}