rayzee 7.21.0 → 7.22.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "rayzee",
-  "version": "7.21.0",
+  "version": "7.22.1",
   "type": "module",
   "description": "Real-time WebGPU path tracing engine built on Three.js",
   "main": "dist/rayzee.umd.js",

package/src/EngineDefaults.js

@@ -62,6 +62,12 @@ export const ENGINE_DEFAULTS = {
 	skyMieAnisotropy: 0.76,
 	skyPreset: 'clearMorning',
 
+	// Camera projection — 'perspective' | 'equirectangular'. Panorama ranges are UI-facing degrees.
+	cameraProjection: 'perspective',
+	panoramaLonRange: [ - 180, 180 ],
+	panoramaLatRange: [ - 90, 90 ],
+	panoramaLevelHorizon: true,
+
 	enableDOF: false,
 	fov: 55,
 	focusDistance: 0.8,

package/src/PathTracerApp.js

@@ -1722,6 +1722,80 @@ export class PathTracerApp extends EventDispatcher {
 
 	}
 
+	/**
+	 * Per-kernel GPU milliseconds for the last resolved frame.
+	 *
+	 * {@link PathTracerApp#getGPUTimings} only reports the frame aggregate, which buries a change to
+	 * one kernel under everything else. The backend's timestamp query pool already retains one
+	 * duration per compute pass, keyed `c:<frameCalls>:<nodeId>:f<frame>` (three.js
+	 * `WebGPUTimestampQueryPool.resolveQueriesAsync` → `timestamps`); this attributes those back to
+	 * kernel names through `KernelManager`'s registry.
+	 *
+	 * Durations are SUMMED per kernel across the frame, so `extend` reports its whole per-frame cost
+	 * over every bounce iteration rather than one bounce. `unattributed` collects passes belonging to
+	 * no registered kernel (other stages, denoisers) so `sum(kernels) + unattributed` reconciles with
+	 * `total` — a gap there means a pass was missed, not that a kernel is free.
+	 *
+	 * The pool's map accumulates across frames and is never pruned, hence the newest-frame filter.
+	 *
+	 * Requires {@link PathTracerApp#enableGPUTiming}. Returns null when timestamps are unavailable.
+	 *
+	 * @returns {Promise<{kernels: Object<string, number>, total: number, unattributed: number, frame: number}|null>}
+	 */
+	async getKernelGPUTimings() {
+
+		const renderer = this.renderer;
+		if ( ! renderer?.backend?.trackTimestamp ) return null;
+
+		await renderer.resolveTimestampsAsync( 'compute' );
+
+		const timestamps = renderer.backend.timestampQueryPool?.compute?.timestamps;
+		if ( ! timestamps || timestamps.size === 0 ) return null;
+
+		const nameByNodeId = new Map();
+		const kernelMap = this.stages?.pathTracer?._kernelManager?.kernels;
+		if ( kernelMap ) {
+
+			for ( const [ name, node ] of kernelMap ) nameByNodeId.set( node.id, name );
+
+		}
+
+		const parsed = [];
+		let frame = - 1;
+
+		for ( const [ uid, ms ] of timestamps ) {
+
+			// 'c:<frameCalls>:<nodeId>:f<frame>'
+			const parts = uid.split( ':' );
+			if ( parts.length !== 4 ) continue;
+
+			const f = Number( parts[ 3 ].slice( 1 ) );
+			if ( ! Number.isFinite( f ) ) continue;
+
+			parsed.push( { nodeId: Number( parts[ 2 ] ), f, ms } );
+			if ( f > frame ) frame = f;
+
+		}
+
+		const kernels = {};
+		let total = 0;
+		let unattributed = 0;
+
+		for ( const entry of parsed ) {
+
+			if ( entry.f !== frame ) continue;
+
+			total += entry.ms;
+			const name = nameByNodeId.get( entry.nodeId );
+			if ( name === undefined ) unattributed += entry.ms;
+			else kernels[ name ] = ( kernels[ name ] ?? 0 ) + entry.ms;
+
+		}
+
+		return { kernels, total, unattributed, frame };
+
+	}
+
 	// ═══════════════════════════════════════════════════════════════
 	// Output (absorbed from OutputAPI)
 	// ═══════════════════════════════════════════════════════════════
@@ -2298,6 +2372,8 @@ export class PathTracerApp extends EventDispatcher {
 			renderer: this.renderer,
 			resetCallback: () => this.reset(),
 			reconcileCompletion: () => this._reconcileCompletion(),
+			denoisingManager: this.denoisingManager,
+			cameraManager: this.cameraManager,
 		} );
 
 		this.renderer.toneMappingExposure = this.settings.get( 'exposure' ) ?? 1.0;

package/src/Processor/BVHBuilder.js

@@ -96,13 +96,12 @@ export class BVHBuilder {
 			reinsertionIterations: 0
 		};
 
-		// Treelet optimization configuration
-		this.enableTreeletOptimization = true;
+		// Off: repairs LBVH trees, so on this binned-SAH build it buys 0.005% tree SAH for 72%
+		// of build time.
+		this.enableTreeletOptimization = false;
 		this.treeletSize = 5;
 		this.treeletOptimizationPasses = 1;
 		this.treeletMinImprovement = 0.02;
-		this.maxTreeletDepth = 3;
-		this.maxTreeletsPerScene = 20;
 		this.treeletComplexityThreshold = 50000;
 
 		// Reinsertion optimization configuration
@@ -191,6 +190,7 @@ export class BVHBuilder {
 		if ( config.size !== undefined ) this.treeletSize = Math.max( 3, Math.min( 12, config.size ) );
 		if ( config.passes !== undefined ) this.treeletOptimizationPasses = Math.max( 1, Math.min( 3, config.passes ) );
 		if ( config.minImprovement !== undefined ) this.treeletMinImprovement = Math.max( 0.001, config.minImprovement );
+		if ( config.complexityThreshold !== undefined ) this.treeletComplexityThreshold = config.complexityThreshold;
 
 	}
 
@@ -595,12 +595,10 @@ export class BVHBuilder {
 
 			const isLargeScene = this.totalTriangles > this.treeletComplexityThreshold;
 			const adaptiveTreeletSize = isLargeScene ? 3 : this.treeletSize;
-			const adaptiveMaxTreelets = isLargeScene ? 10 : this.maxTreeletsPerScene;
 
 			const optimizer = new TreeletOptimizer( this.traversalCost, this.intersectionCost );
 			optimizer.setTreeletSize( adaptiveTreeletSize );
 			optimizer.setMinImprovement( this.treeletMinImprovement );
-			optimizer.setMaxTreelets( adaptiveMaxTreelets );
 
 			const optimizationStartTime = performance.now();
 

package/src/Processor/KernelManager.js

@@ -4,25 +4,14 @@
  * Builds, caches, and dispatches individual compute nodes for the wavefront
  * path tracing pipeline. Each kernel is a separate `Fn().compute()` node.
  *
- * Manages workgroup sizes, dispatch dimensions, and provides a unified
- * dispatch interface that wraps `renderer.compute(node)`.
+ * Dispatch grids are derived from each node's own `workgroupSize`, so the divisor can never
+ * drift from the size the kernel was compiled with — see `setDispatchForCount`.
  */
 
 import { createLogger, fmt } from '../utils/Logger.js';
 
 const log = createLogger( 'wavefront' );
 
-/** Default workgroup sizes per kernel type */
-const WORKGROUP_SIZES = {
-	generate: [ 16, 16, 1 ], // 2D screen-space
-	extend: [ 256, 1, 1 ], // 1D ray-parallel
-	shade: [ 256, 1, 1 ], // 1D ray-parallel (material-sorted when sort enabled)
-	connect: [ 256, 1, 1 ], // 1D shadow-ray-parallel
-	accumulate: [ 256, 1, 1 ], // 1D shadow-ray-parallel
-	compact: [ 256, 1, 1 ], // 1D ray-parallel
-	finalWrite: [ 16, 16, 1 ], // 2D screen-space
-};
-
 export class KernelManager {
 
 	/**
@@ -41,12 +30,6 @@ export class KernelManager {
 		 */
 		this.kernels = new Map();
 
-		/**
-		 * Map of kernel name → workgroup size [x, y, z].
-		 * @type {Map<string, number[]>}
-		 */
-		this.workgroupSizes = new Map();
-
 		/**
 		 * Timing data for performance profiling.
 		 * @type {Map<string, {compiledOnce: boolean, lastDispatchMs: number}>}
@@ -74,13 +57,6 @@ export class KernelManager {
 		this._firstDispatches = [];
 		this._firstDispatchFlush = null;
 
-		// Initialize workgroup sizes from defaults
-		for ( const [ name, wgSize ] of Object.entries( WORKGROUP_SIZES ) ) {
-
-			this.workgroupSizes.set( name, wgSize );
-
-		}
-
 	}
 
 	/**
@@ -177,61 +153,32 @@ export class KernelManager {
 	}
 
 	/**
-	 * Update dispatch dimensions for a kernel.
+	 * Size a 1D kernel's grid to cover `count` items, deriving the divisor from the workgroup size the
+	 * kernel was actually registered with. Extend/Shade bound on ENTERING_COUNT rather than on the grid,
+	 * so an under-sized grid silently drops the tail of the active list — never hardcode the divisor.
 	 * @param {string} name - Kernel name
-	 * @param {number[]} count - Dispatch dimensions [x, y, z]
+	 * @param {number} count - Number of items to cover
 	 */
-	setDispatchCount( name, count ) {
+	setDispatchForCount( name, count ) {
 
 		const node = this.kernels.get( name );
 		if ( ! node ) return;
-		node.dispatchSize = count;
-
-	}
-
-	/**
-	 * Calculate 2D dispatch dimensions for a screen-space kernel.
-	 * @param {number} width - Render width in pixels
-	 * @param {number} height - Render height in pixels
-	 * @param {string} kernelName - Kernel name for WG size lookup
-	 * @returns {number[]} [dispatchX, dispatchY, 1]
-	 */
-	calcScreenDispatch( width, height, kernelName ) {
-
-		const wg = this.workgroupSizes.get( kernelName ) || [ 16, 16, 1 ];
-		return [
-			Math.ceil( width / wg[ 0 ] ),
-			Math.ceil( height / wg[ 1 ] ),
-			1
-		];
-
-	}
-
-	/**
-	 * Calculate 1D dispatch dimensions for a ray-parallel kernel.
-	 * @param {number} rayCount - Number of rays to process
-	 * @param {string} kernelName - Kernel name for WG size lookup
-	 * @returns {number[]} [dispatchX, 1, 1]
-	 */
-	calcRayDispatch( rayCount, kernelName ) {
-
-		const wg = this.workgroupSizes.get( kernelName ) || [ 256, 1, 1 ];
-		return [
-			Math.ceil( rayCount / wg[ 0 ] ),
-			1,
-			1
-		];
+		node.dispatchSize = [ Math.ceil( count / node.workgroupSize[ 0 ] ), 1, 1 ];
 
 	}
 
 	/**
-	 * Get the workgroup size for a kernel.
-	 * @param {string} name
-	 * @returns {number[]}
+	 * Size a 2D screen-space kernel's grid, deriving both divisors from the registered workgroup size.
+	 * @param {string} name - Kernel name
+	 * @param {number} width - Width in pixels
+	 * @param {number} height - Height in pixels
 	 */
-	getWorkgroupSize( name ) {
+	setDispatchForGrid( name, width, height ) {
 
-		return this.workgroupSizes.get( name ) || [ 256, 1, 1 ];
+		const node = this.kernels.get( name );
+		if ( ! node ) return;
+		const wg = node.workgroupSize;
+		node.dispatchSize = [ Math.ceil( width / wg[ 0 ] ), Math.ceil( height / wg[ 1 ] ), 1 ];
 
 	}
 

package/src/Processor/QueueManager.js

@@ -17,9 +17,10 @@ export const COUNTER = {
 	// per-frame count of pixels whose Tier-1 relative-error dropped below threshold; zeroed at frame start by
 	// initActiveIndices, incremented in FinalWrite, read back async to drive the whole-frame convergence early-stop.
 	CONVERGED_COUNT: 2,
-	// Tier-2 per-pixel freeze: FROZEN_COUNT = pixels skipped this frame; ACTIVE_PIXEL_COUNT = bounce-0 active
-	// count (maxRays − frozen), read back to size next frame's grid.
-	FROZEN_COUNT: 3,
+	// Reserved hole — was FROZEN_COUNT, a write-only counter no reader ever consumed. Kept as a hole so
+	// slot indices stay stable across the JS enum and every kernel that stores by index.
+	RESERVED_3: 3,
+	// Tier-2 per-pixel freeze: bounce-0 active count (maxRays − frozen), read back to size next frame's grid.
 	ACTIVE_PIXEL_COUNT: 4,
 	COUNT: 5,
 };

package/src/Processor/SceneProcessor.js

@@ -48,9 +48,13 @@ export class SceneProcessor {
 			enableTextureCache: true,
 			maxConcurrentTextureTasks: Math.min( navigator.hardwareConcurrency || 4, 6 ),
 			// Treelet optimization configuration
+			// Keep: `_buildBVH` sends `enabled: value !== false`, so undefined re-enables treelets.
+			enableTreeletOptimization: false,
 			treeletSize: 7, // 7 nodes gives 315 topologies for optimal enumeration
 			treeletOptimizationPasses: 1,
 			treeletMinImprovement: 0.01, // Minimum SAH improvement threshold
+			// Above this triangle count the builder drops treelets to size 3.
+			treeletComplexityThreshold: 50000,
 			...options
 		};
 
@@ -151,7 +155,8 @@ export class SceneProcessor {
 			enabled: this.config.enableTreeletOptimization,
 			size: this.config.treeletSize,
 			passes: this.config.treeletOptimizationPasses,
-			minImprovement: this.config.treeletMinImprovement
+			minImprovement: this.config.treeletMinImprovement,
+			complexityThreshold: this.config.treeletComplexityThreshold
 		} );
 
 		// Create and configure texture creator
@@ -436,7 +441,8 @@ export class SceneProcessor {
 					enabled: originalTreeletEnabled !== false,
 					size: this.config.treeletSize,
 					passes: this.config.treeletOptimizationPasses,
-					minImprovement: this.config.treeletMinImprovement
+					minImprovement: this.config.treeletMinImprovement,
+					complexityThreshold: this.config.treeletComplexityThreshold
 				},
 				reinsertionOptimization: {
 					enabled: this.bvhBuilder.enableReinsertionOptimization,
@@ -1267,7 +1273,8 @@ export class SceneProcessor {
 				enabled: this.config.enableTreeletOptimization,
 				size: this.config.treeletSize,
 				passes: this.config.treeletOptimizationPasses,
-				minImprovement: this.config.treeletMinImprovement
+				minImprovement: this.config.treeletMinImprovement,
+				complexityThreshold: this.config.treeletComplexityThreshold
 			} );
 
 		}
@@ -1953,7 +1960,8 @@ export class SceneProcessor {
 					enabled: treeletEnabled,
 					size: this.config.treeletSize,
 					passes: this.config.treeletOptimizationPasses,
-					minImprovement: this.config.treeletMinImprovement
+					minImprovement: this.config.treeletMinImprovement,
+					complexityThreshold: this.config.treeletComplexityThreshold
 				},
 				reinsertionOptimization: {
 					enabled: this.bvhBuilder.enableReinsertionOptimization,

package/src/Processor/TreeletOptimizer.js

@@ -545,13 +545,6 @@ export class TreeletOptimizer {
 
 	}
 
-	setMaxTreelets() {
-
-		// No-op — we process all valid treelets now.
-		// Kept for API compatibility with BVHBuilder.
-
-	}
-
 	getStatistics() {
 
 		return { ...this.stats };

package/src/RenderSettings.js

@@ -1,4 +1,4 @@
-import { EventDispatcher, Color } from 'three';
+import { EventDispatcher, Color, Vector2, MathUtils } from 'three';
 import { ENGINE_DEFAULTS } from './EngineDefaults.js';
 import { EngineEvents } from './EngineEvents.js';
 
@@ -32,6 +32,7 @@ const SETTING_ROUTES = {
 	enableGroundCatcher: { uniform: 'enableGroundCatcher', reset: true },
 	groundCatcherHeight: { uniform: 'groundCatcherHeight', reset: true },
 	globalIlluminationIntensity: { uniform: 'globalIlluminationIntensity', reset: true },
+	panoramaLevelHorizon: { uniform: 'panoLevelHorizon', reset: true },
 	enableDOF: { uniform: 'enableDOF', reset: true },
 	focusDistance: { uniform: 'focusDistance', reset: false },
 	focalLength: { uniform: 'focalLength', reset: true },
@@ -56,6 +57,9 @@ const SETTING_ROUTES = {
 
 	// ── Multi-stage / special handling ────────────────────────────
 
+	cameraProjection: { handler: 'handleCameraProjection', reset: true },
+	panoramaLonRange: { handler: 'handlePanoramaLonRange', reset: true },
+	panoramaLatRange: { handler: 'handlePanoramaLatRange', reset: true },
 	interactionModeEnabled: { handler: 'handleInteractionModeEnabled', reset: false },
 	maxSamples: { handler: 'handleMaxSamples', reset: false },
 	transparentBackground: { handler: 'handleTransparentBackground' },
@@ -122,13 +126,15 @@ export class RenderSettings extends EventDispatcher {
 	 * @param {Object} params.stages           - Pipeline stages { pathTracer, compositor, autoExposure, ... }
 	 * @param {Function} params.resetCallback   - Called to reset accumulation
 	 * @param {Function} [params.reconcileCompletion] - Called when completion limits change
+	 * @param {Object} [params.denoisingManager] - Needed to force ASVGF off under panorama
+	 * @param {Object} [params.cameraManager]    - Needed to force auto-focus manual under panorama
 	 */
-	bind( { stages, renderer, resetCallback, reconcileCompletion } ) {
+	bind( params ) {
 
-		this._pathTracer = stages.pathTracer;
-		this._resetCallback = resetCallback;
+		this._pathTracer = params.stages.pathTracer;
+		this._resetCallback = params.resetCallback;
 		this._delegates = {};
-		this._handlers = this._buildHandlers( stages, renderer, reconcileCompletion );
+		this._handlers = this._buildHandlers( params );
 
 	}
 
@@ -136,10 +142,39 @@ export class RenderSettings extends EventDispatcher {
 	 * Builds handler functions for multi-stage settings that can't
 	 * be routed with a simple uniform forward.
 	 */
-	_buildHandlers( stages, renderer, reconcileCompletion ) {
+	_buildHandlers( { stages, renderer, reconcileCompletion, denoisingManager, cameraManager } ) {
+
+		// UniformManager copies into the existing node, so one scratch vector serves every write.
+		const panoScratch = new Vector2();
+		const setPanoRange = ( uniform, value ) => {
+
+			panoScratch.set( value?.[ 0 ] ?? 0, value?.[ 1 ] ?? 0 ).multiplyScalar( MathUtils.DEG2RAD );
+			stages.pathTracer?.setUniform( uniform, panoScratch );
+
+		};
 
 		return {
 
+			handleCameraProjection: ( value ) => {
+
+				const isPanorama = value === 'equirectangular';
+				stages.pathTracer?.setUniform( 'cameraProjection', isPanorama ? 1 : 0 );
+
+				if ( ! isPanorama ) return;
+
+				// ASVGF is driven entirely by MotionVector, which unprojects through
+				// projectionMatrixInverse — meaningless once every pixel is its own direction.
+				// Fall back to the spatial-only denoiser rather than leaving no strategy.
+				if ( denoisingManager?.denoiserStrategy === 'asvgf' ) denoisingManager.setDenoiserStrategy( 'edgeaware' );
+				// Auto-focus raycasts via Raycaster.setFromCamera, which only knows the frustum.
+				cameraManager?.setAutoFocusMode( 'manual' );
+
+			},
+
+			handlePanoramaLonRange: ( value ) => setPanoRange( 'panoLonRange', value ),
+
+			handlePanoramaLatRange: ( value ) => setPanoRange( 'panoLatRange', value ),
+
 			handleTransparentBackground: ( value ) => {
 
 				stages.pathTracer?.setUniform( 'transparentBackground', value );

package/src/Stages/NormalDepth.js

@@ -1,4 +1,4 @@
-import { Fn, vec3, vec4, float, int, uint, uvec2, uniform, normalize, mat3, min, storage, If,
+import { Fn, vec2, vec3, vec4, float, int, uint, uvec2, uniform, min, storage, If,
 	textureStore, workgroupId, localId } from 'three/tsl';
 import { RenderTarget, StorageTexture } from 'three/webgpu';
 import { HalfFloatType, RGBAFormat, NearestFilter, Matrix4, Box2, Vector2 } from 'three';
@@ -6,6 +6,7 @@ import { RenderStage, StageExecutionMode } from '../Pipeline/RenderStage.js';
 import { MAX_STORAGE_TEXTURE_SIZE } from '../EngineDefaults.js';
 import { Ray, HitInfo, RayTracingMaterial, UVCache } from '../TSL/Struct.js';
 import { traverseBVH } from '../TSL/BVHTraversal.js';
+import { cameraRayDirection } from '../TSL/CameraRay.js';
 import { getMaterial } from '../TSL/Common.js';
 import { computeUVCache, processNormal, processBump, buildBucketTextureNodes, refreshBucketTextureNodes, setMaterialBucketTextures } from '../TSL/TextureSampling.js';
 
@@ -48,6 +49,12 @@ export class NormalDepth extends RenderStage {
 
 		this.cameraWorldMatrix = uniform( new Matrix4(), 'mat4' );
 		this.cameraProjectionMatrixInverse = uniform( new Matrix4(), 'mat4' );
+		// Mirrored from the path tracer each frame — these rays must use the same camera model
+		// as the colour buffer or the denoiser's normal/depth edge-stops fight the image.
+		this.cameraProjection = uniform( 0, 'int' );
+		this.panoLonRange = uniform( new Vector2(), 'vec2' );
+		this.panoLatRange = uniform( new Vector2(), 'vec2' );
+		this.panoLevelHorizon = uniform( 1, 'int' );
 		this.resolutionWidth = uniform( options.width || 1 );
 		this.resolutionHeight = uniform( options.height || 1 );
 
@@ -218,20 +225,12 @@ export class NormalDepth extends RenderStage {
 
 			If( gx.lessThan( int( resW ) ).and( gy.lessThan( int( resH ) ) ), () => {
 
-				// Pixel center → NDC, Y negated for Three.js WebGPU.
-				const ndcX = float( gx ).add( 0.5 ).div( resW ).mul( 2.0 ).sub( 1.0 );
-				const ndcY = float( gy ).add( 0.5 ).div( resH ).mul( 2.0 ).sub( 1.0 ).negate();
-				const ndcPos = vec3( ndcX, ndcY, 1.0 );
-
 				// No jitter — deterministic per-pixel ray so the temporal gate
 				// sees stable per-pixel normals across frames.
-				const rayDirCS = camProjInvMat.mul( vec4( ndcPos, 1.0 ) );
-				const rayDirWorld = normalize(
-					mat3(
-						camWorldMat[ 0 ].xyz,
-						camWorldMat[ 1 ].xyz,
-						camWorldMat[ 2 ].xyz
-					).mul( rayDirCS.xyz.div( rayDirCS.w ) )
+				const uv = vec2( float( gx ).add( 0.5 ).div( resW ), float( gy ).add( 0.5 ).div( resH ) );
+				const rayDirWorld = cameraRayDirection(
+					uv, camWorldMat, camProjInvMat,
+					this.cameraProjection, this.panoLonRange, this.panoLatRange, this.panoLevelHorizon
 				);
 				const rayOrigin = vec3( camWorldMat[ 3 ] );
 
@@ -307,6 +306,10 @@ export class NormalDepth extends RenderStage {
 
 			this.cameraWorldMatrix.value.copy( pt.uniforms.get( 'cameraWorldMatrix' ).value );
 			this.cameraProjectionMatrixInverse.value.copy( pt.uniforms.get( 'cameraProjectionMatrixInverse' ).value );
+			this.cameraProjection.value = pt.uniforms.get( 'cameraProjection' ).value;
+			this.panoLonRange.value.copy( pt.uniforms.get( 'panoLonRange' ).value );
+			this.panoLatRange.value.copy( pt.uniforms.get( 'panoLatRange' ).value );
+			this.panoLevelHorizon.value = pt.uniforms.get( 'panoLevelHorizon' ).value;
 
 		}