rayzee 9.1.1 → 9.2.0

package/src/Stages/PathTracer.js

@@ -25,6 +25,7 @@ import {
 } from '../TSL/SortGlobalKernels.js';
 import { ENGINE_DEFAULTS, MAX_STORAGE_TEXTURE_SIZE } from '../EngineDefaults.js';
 import { createLogger, fmt } from '../utils/Logger.js';
+import { deviceMemoryGB } from '../Processor/HostMemory.js';
 import {
 	Fn, uint, int, atomicStore, atomicLoad, atomicAdd, instanceIndex, If, Return,
 } from 'three/tsl';
@@ -113,6 +114,11 @@ export class PathTracer extends PathTracerStage {
 		this._geometryPixelCount = 0;
 		this._convergedReadbackPending = false;
 
+		// Lockstep: readbacks issued on a fixed cadence and applied a fixed number of frames later,
+		// so when one lands cannot change the image. { due, read, apply } while one is in flight.
+		this._lockstep = false;
+		this._lockstepRead = null;
+
 		// Tier-2: last settled active-pixel count (maxRays − frozen), sizes next frame's bounce-0 grid.
 		// 0 until a settled readback lands (and on reset/camera-move/resize) → grid stays full-size until then.
 		this._lastActivePixelCount = 0;
@@ -131,6 +137,7 @@ export class PathTracer extends PathTracerStage {
 		this._wfIsFirstChunk = uniform( 1, 'uint' ); // 1 → zero frame-scoped counters (CONVERGED/FROZEN)
 		this._pathBudget = 0; // B, paths-in-flight; computed once from device limits in _buildWavefrontKernels
 		this._pathBudgetOverride = 0; // test hook: force B (0 = derive from device)
+		this.hostMemoryGB = options.hostMemoryGB;
 		this._chunkRows = 0; // rows per chunk = floor(B / renderWidth), clamped ≥1
 		this._numChunks = 1; // ceil(renderHeight / chunkRows)
 
@@ -244,6 +251,15 @@ export class PathTracer extends PathTracerStage {
 
 		}
 
+		const lockstepRead = this._lockstepRead;
+		if ( lockstepRead && this.frameCount >= lockstepRead.due ) {
+
+			if ( ! lockstepRead.apply ) return; // see readbackWait()
+			this._lockstepRead = null;
+			lockstepRead.apply();
+
+		}
+
 		if ( this.isComplete || this.frameCount >= this.completionThreshold || this._isConvergedComplete() ) {
 
 			// Denoiser switched on after the render finished — spend one more frame to fill the aux MRT.
@@ -299,7 +315,7 @@ export class PathTracer extends PathTracerStage {
 
 		}
 
-		this._updateAccumulationUniforms( frameValue, renderMode );
+		this._updateAccumulationUniforms( frameValue );
 		const auxMixes = this._updateAuxAccumulationUniforms( frameValue );
 		this.frame.value = frameValue;
 		this.seedFrame.value = this._seedTick ++;
@@ -657,6 +673,54 @@ export class PathTracer extends PathTracerStage {
 		this._auxSamples = 0;
 		this._auxSeedPending = false;
 
+		if ( this._lockstep ) {
+
+			// Nothing measured by the previous render may steer this one.
+			this._lockstepRead = null;
+			this._readbackGeneration ++;
+			this._lastBounceCounts = null;
+			this._lastBounceEnergy = null;
+			this._lastBounceCountsBudget = - 1;
+			this._lastBounceCountsLoopBound = - 1;
+			this._curveSizingValid = false;
+
+		}
+
+	}
+
+	/**
+	 * Lockstep readbacks: the survivor curve and the convergence counters are read every N frames
+	 * and applied exactly N frames later, waiting when they have not landed, and every reset starts
+	 * from nothing measured and from seed 0. The same input then renders the same image however fast
+	 * frames are submitted. Off by default: waiting costs a stall whenever the GPU falls N frames behind.
+	 * @param {boolean} enabled
+	 */
+	setLockstepReadbacks( enabled ) {
+
+		enabled = !! enabled;
+		if ( enabled === this._lockstep ) return;
+		this._lockstep = enabled;
+		this._lockstepRead = null;
+		this._readbackGeneration ++;
+
+	}
+
+	get lockstepReadbacks() {
+
+		return this._lockstep;
+
+	}
+
+	/**
+	 * While a lockstep readback is due and has not landed, render() traces nothing: await this
+	 * before the next frame. Null otherwise.
+	 * @returns {?Promise<void>}
+	 */
+	readbackWait() {
+
+		const pending = this._lockstepRead;
+		return pending && ! pending.apply && this.frameCount >= pending.due ? pending.read : null;
+
 	}
 
 	/**
@@ -805,6 +869,7 @@ export class PathTracer extends PathTracerStage {
 	_willReadCountersThisFrame() {
 
 		if ( this.cameraChanged || this.cameraOptimizer?.isInInteractionMode() ) return false;
+		if ( this._lockstep ) return ! this._lockstepRead && this.frameCount % this._readbackEveryNFrames === 0;
 		if ( this._readbackPending || this._convergedReadbackPending ) return false;
 		return this._readbackFrameCounter + 1 >= this._readbackEveryNFrames;
 
@@ -819,6 +884,13 @@ export class PathTracer extends PathTracerStage {
 	// Async readback of the per-bounce snapshot every N frames; never awaited, so the early-exit uses past-frame data.
 	_maybeReadbackCounters() {
 
+		if ( this._lockstep ) {
+
+			this._issueLockstepReadback();
+			return;
+
+		}
+
 		// Never sample the survivor curve mid-motion, nor while the CameraOptimizer is holding maxBounces
 		// down to its interaction value (1): mid-motion counts belong to a pose we're leaving, and a curve
 		// measured at the interaction budget stores _lastBounceCountsBudget=1 — when the real (high) budget
@@ -864,16 +936,7 @@ export class PathTracer extends PathTracerStage {
 			// Drop counts measured at a now-stale generation (a resize or camera move happened mid-flight).
 			// A surviving readback was initiated while settled (init is skipped mid-motion) and no motion
 			// happened before it resolved, so its counts match the current view — safe to size from.
-			if ( gen === this._readbackGeneration ) {
-
-				const all = new Uint32Array( buf.slice( 0 ) );
-				this._lastBounceCounts = all.subarray( 0, n );
-				this._lastBounceEnergy = all.subarray( n, 2 * n );
-				this._lastBounceCountsBudget = budget;
-				this._lastBounceCountsLoopBound = measuredLoopBound;
-				this._curveSizingValid = true;
-
-			}
+			if ( gen === this._readbackGeneration ) this._applyBounceCounts( buf, budget, measuredLoopBound, n );
 
 			this._readbackPending = false;
 
@@ -899,19 +962,7 @@ export class PathTracer extends PathTracerStage {
 				const total = this._wfRenderWidth.value * this._wfRenderHeight.value;
 				this.renderer.getArrayBufferAsync( cAttr ).then( ( buf ) => {
 
-					if ( cgen === this._readbackGeneration && total > 0 ) {
-
-						const c = new Uint32Array( buf );
-						this._convergedFraction = c[ COUNTER.CONVERGED_COUNT ] / total;
-						// No geometry at all (pure environment) leaves nothing to gate on — 1 lets the
-						// whole-frame fraction decide alone.
-						const geo = c[ COUNTER.GEOMETRY_COUNT ];
-						this._geometryPixelCount = geo;
-						this._convergedGeometryFraction = geo > 0 ? c[ COUNTER.CONVERGED_GEOMETRY_COUNT ] / geo : 1;
-						// Tier-2: bounce-0 active-pixel count measured this settled frame → sizes next frame's grid.
-						this._lastActivePixelCount = c[ COUNTER.ACTIVE_PIXEL_COUNT ];
-
-					}
+					if ( cgen === this._readbackGeneration && total > 0 ) this._applyCounters( buf, total );
 
 					this._convergedReadbackPending = false;
 
@@ -927,6 +978,72 @@ export class PathTracer extends PathTracerStage {
 
 	}
 
+	_issueLockstepReadback() {
+
+		// One in flight, and none mid-motion: frames there do not count, so frameCount stands still.
+		if ( this._lockstepRead || this.frameCount % this._readbackEveryNFrames !== 0 ) return;
+		if ( this.cameraChanged || this.cameraOptimizer?.isInInteractionMode() ) return;
+
+		const bounceAttr = this._queueManager?.getBounceCountsAttribute();
+		const counterAttr = this._queueManager?.getCountersAttribute();
+		if ( ! bounceAttr || ! counterAttr ) return;
+
+		const gen = this._readbackGeneration;
+		const budget = this.maxBounces.value;
+		const loopBound = this._bounceLoopBound();
+		const n = this._queueManager.MAX_BOUNCE_SNAPSHOTS;
+		const total = this._wfRenderWidth.value * this._wfRenderHeight.value;
+
+		const entry = { due: this.frameCount + this._readbackEveryNFrames, read: null, apply: null };
+		entry.read = Promise.all( [
+			this.renderer.getArrayBufferAsync( bounceAttr ),
+			this.renderer.getArrayBufferAsync( counterAttr ),
+		] ).then( ( [ bounceBuf, counterBuf ] ) => {
+
+			entry.apply = () => {
+
+				if ( gen !== this._readbackGeneration ) return;
+				this._applyBounceCounts( bounceBuf, budget, loopBound, n );
+				if ( total > 0 ) this._applyCounters( counterBuf, total );
+
+			};
+
+		}, ( e ) => {
+
+			log.warn( 'lockstep readback failed:', e );
+			entry.apply = () => {};
+
+		} );
+
+		this._lockstepRead = entry;
+
+	}
+
+	_applyBounceCounts( buf, budget, loopBound, n ) {
+
+		const all = new Uint32Array( buf.slice( 0 ) );
+		this._lastBounceCounts = all.subarray( 0, n );
+		this._lastBounceEnergy = all.subarray( n, 2 * n );
+		this._lastBounceCountsBudget = budget;
+		this._lastBounceCountsLoopBound = loopBound;
+		this._curveSizingValid = true;
+
+	}
+
+	_applyCounters( buf, total ) {
+
+		const c = new Uint32Array( buf );
+		this._convergedFraction = c[ COUNTER.CONVERGED_COUNT ] / total;
+		// No geometry at all (pure environment) leaves nothing to gate on — 1 lets the
+		// whole-frame fraction decide alone.
+		const geo = c[ COUNTER.GEOMETRY_COUNT ];
+		this._geometryPixelCount = geo;
+		this._convergedGeometryFraction = geo > 0 ? c[ COUNTER.CONVERGED_GEOMETRY_COUNT ] / geo : 1;
+		// Tier-2: bounce-0 active-pixel count measured this settled frame → sizes next frame's grid.
+		this._lastActivePixelCount = c[ COUNTER.ACTIVE_PIXEL_COUNT ];
+
+	}
+
 	// Sync wavefront's texture nodes with current env/material textures; only a changed ref triggers GPU rebind.
 	_refreshWfTextureNodes() {
 
@@ -1031,7 +1148,7 @@ export class PathTracer extends PathTracerStage {
 		const maxBuffer = limits?.maxBufferSize || maxBinding;
 
 		const bByBinding = Math.floor( ( maxBinding * 0.9 ) / RAY_BYTES );
-		const deviceMemBytes = ( ( typeof navigator !== 'undefined' && navigator.deviceMemory ) || 4 ) * 1024 * 1024 * 1024;
+		const deviceMemBytes = deviceMemoryGB( this.hostMemoryGB ).gb * 1024 * 1024 * 1024;
 		const poolVramBudget = Math.min( deviceMemBytes * 0.25, maxBuffer * 4 );
 		const bByVram = Math.floor( poolVramBudget / bytesPerPath );
 
@@ -1596,7 +1713,7 @@ export class PathTracer extends PathTracerStage {
 			cameraViewMatrix: this.cameraViewMatrix,
 			fireflyThreshold: this.fireflyThreshold,
 			shadowTerminatorOffset: this.shadowTerminatorOffset,
-			// RNG axis only (keys STBN via frame & 63).
+			// RNG axis only.
 			frame: this.seedFrame,
 			accumFrame: this.frame,
 			resolution: this.resolution,

package/src/Stages/PathTracerStage.js

@@ -1,11 +1,7 @@
 import { storage } from 'three/tsl';
 import { gpuOnlyStorageAttribute, uploadStorageChunkRange, uploadStorageChunks } from '../TSL/patches.js';
 import { StorageInstancedBufferAttribute } from 'three/webgpu';
-import {
-	NearestFilter, Vector2, Matrix4,
-	TextureLoader, RepeatWrapping
-} from 'three';
-import { stbnScalarTextureNode, stbnVec2TextureNode } from '../TSL/Random.js';
+import { Vector2, Matrix4 } from 'three';
 
 // Pipeline system
 import { RenderStage, StageExecutionMode } from '../Pipeline/RenderStage.js';
@@ -26,8 +22,6 @@ import { LightSerializer } from '../Processor/LightSerializer';
 // Constants
 import { ENGINE_DEFAULTS as DEFAULT_STATE, TRIANGLE_DATA_LAYOUT } from '../EngineDefaults.js';
 import { TRI_GEO_ROWS, TRI_SHADE_ROWS } from '../TSL/Common.js';
-import { getAssetConfig } from '../AssetConfig.js';
-import { cachedObjectURL, DOWNLOAD_POLICY } from '../Storage/DownloadCache.js';
 import { createLogger, fmt } from '../utils/Logger.js';
 
 // Triangles converted per staging pass: 256K is 12 + 8 MB of staging, kept for the stage's life.
@@ -144,9 +138,6 @@ export class PathTracerStage extends RenderStage {
 		// Initialize rendering state
 		this._initRenderingState();
 
-		// Setup blue noise
-		this.setupBlueNoise();
-
 		// Cache frequently used objects
 		this.tempVector2 = new Vector2();
 		this.lastCameraMatrix = new Matrix4();
@@ -216,14 +207,8 @@ export class PathTracerStage extends RenderStage {
 		// and refreshes the bound TextureNode in-place when it changes.
 		this.iesProfiles = null;
 
-		// STBN noise textures
-		this.stbnScalarTexture = null;
-		this.stbnVec2Texture = null;
-
 		/**
-		 * Resolves once both STBN atlases have loaded. Await before any render whose
-		 * output must be reproducible — see PathTracerApp.setDeterministicMode().
-		 * Replaced by the real promise in setupBlueNoise(), which runs after this.
+		 * @deprecated Always resolved: the engine no longer loads blue-noise textures.
 		 * @type {Promise<void>}
 		 */
 		this.blueNoiseReady = Promise.resolve();
@@ -369,74 +354,6 @@ export class PathTracerStage extends RenderStage {
 
 	}
 
-	/**
-	 * Load STBN (Spatiotemporal Blue Noise) atlas textures.
-	 * Each atlas is 1024×1024: 8×8 grid of 128×128 tiles, 64 temporal slices.
-	 */
-	setupBlueNoise() {
-
-		const loader = new TextureLoader();
-		loader.setCrossOrigin( 'anonymous' );
-
-		const configure = ( tex ) => {
-
-			tex.minFilter = NearestFilter;
-			tex.magFilter = NearestFilter;
-			tex.wrapS = RepeatWrapping;
-			tex.wrapT = RepeatWrapping;
-			tex.generateMipmaps = false;
-			return tex;
-
-		};
-
-		const { stbnScalarAtlas, stbnVec2Atlas } = getAssetConfig();
-
-		const load = async ( url ) => {
-
-			const source = await cachedObjectURL( url, { policy: DOWNLOAD_POLICY.REVALIDATE } );
-			try {
-
-				return await loader.loadAsync( source.url );
-
-			} finally {
-
-				source.release();
-
-			}
-
-		};
-
-		const scalarLoad = load( stbnScalarAtlas ).then( ( tex ) => {
-
-			this.stbnScalarTexture = configure( tex );
-			stbnScalarTextureNode.value = tex;
-			log.debug( `STBN scalar atlas ${fmt.px( tex.image.width, tex.image.height )}` );
-
-		} );
-
-		const vec2Load = load( stbnVec2Atlas ).then( ( tex ) => {
-
-			this.stbnVec2Texture = configure( tex );
-			stbnVec2TextureNode.value = tex;
-			log.debug( `STBN vec2 atlas ${fmt.px( tex.image.width, tex.image.height )}` );
-
-		} );
-
-		// Until the atlases land the STBN sampler reads a constant-0.5 placeholder and bakes
-		// that degenerate "noise" permanently into the accumulation buffer. The cut-over frame
-		// is disk/network dependent, so reproducible renders must await this. Never rejects.
-		this.blueNoiseReady = Promise.allSettled( [ scalarLoad, vec2Load ] ).then( ( results ) => {
-
-			for ( const result of results ) {
-
-				if ( result.status === 'rejected' ) log.warn( 'STBN atlas failed to load', result.reason );
-
-			}
-
-		} );
-
-	}
-
 	/**
 	 * Setup event listeners for pipeline events
 	 */
@@ -646,8 +563,8 @@ export class PathTracerStage extends RenderStage {
 		// ASVGF's history. A real mode change is still caught by the renderMode comparison.
 		this.lastInteractionModeState = false;
 
-		// Only deterministic mode rewinds the seed axis; see _pinSeedToFrame.
-		if ( this._pinSeedToFrame ) this._seedTick = 0;
+		// Only deterministic mode and lockstep readbacks rewind the seed axis; see _pinSeedToFrame.
+		if ( this._pinSeedToFrame || this._lockstep ) this._seedTick = 0;
 
 	}
 
@@ -1406,9 +1323,8 @@ export class PathTracerStage extends RenderStage {
 	/**
 	 * Update accumulation uniforms
 	 * @param {number} frameValue
-	 * @param {number} renderMode
 	 */
-	_updateAccumulationUniforms( frameValue, renderMode ) {
+	_updateAccumulationUniforms( frameValue ) {
 
 		const currentInteractionMode = this.cameraOptimizer?.isInInteractionMode() ?? false;
 		this.lastInteractionModeState = currentInteractionMode;
@@ -1545,13 +1461,8 @@ export class PathTracerStage extends RenderStage {
 
 	}
 
-	setBlueNoiseTexture( tex ) {
-
-		// Legacy API — sets the scalar STBN atlas texture
-		this.stbnScalarTexture = tex;
-		if ( tex ) stbnScalarTextureNode.value = tex;
-
-	}
+	/** @deprecated No shader reads a blue-noise texture any more; kept so existing callers do not break. */
+	setBlueNoiseTexture() {}
 
 	/**
 	 * Rebuild the packed light buffer from cached lightBVH + emissive data.
@@ -1745,8 +1656,6 @@ export class PathTracerStage extends RenderStage {
 		this.storageTextures?.dispose();
 
 		// Dispose textures
-		this.stbnScalarTexture?.dispose();
-		this.stbnVec2Texture?.dispose();
 		this.placeholderTexture?.dispose();
 
 		// Clear data references

package/src/TSL/DebugKernel.js

@@ -59,7 +59,7 @@ export function buildDebugKernel( params ) {
 			If( visMode.equal( int( 9 ) ), () => {
 
 				// One ray per pixel — plain per-frame jitter (totalRays = 1 → random, no stratified lattice).
-				const jitter = getStratifiedSample( pixelCoord, int( 0 ), int( 1 ), seed, resolution, frame );
+				const jitter = getStratifiedSample( pixelCoord, int( 0 ), seed, resolution, frame );
 				color.assign( vec4( jitter, 1.0, 1.0 ) );
 
 			} ).Else( () => {

package/src/TSL/EmissiveSampling.js

@@ -552,7 +552,7 @@ export const sampleEmissiveTriangle = Fn( ( [
 
 export const calculateEmissiveTriangleContributionDebug = Fn( ( [
 	hitPoint, normal, geomNormal, viewDir, material,
-	bounceIndex, rngState,
+	_bounceIndex, rngState,
 	pixelCoord, resolution, frame, dimBase,
 	emissiveBoost,
 	emissiveTriangleBuffer, emissiveVec4Offset, emissiveTriangleCount, emissiveTotalPower,

package/src/TSL/GenerateKernel.js

@@ -12,7 +12,7 @@
 
 import {
 	Fn, float, vec2, vec3, vec4, int, uint,
-	If, select, instanceIndex, atomicLoad,
+	If, instanceIndex, atomicLoad,
 	localId, workgroupId,
 } from 'three/tsl';
 
@@ -44,7 +44,6 @@ export function buildGenerateKernel( params ) {
 		renderWidth,
 		chunkRowBase, chunkRows, // row band offset (global first row) + row count for this chunk
 		transmissiveBounces, // per-ray refraction budget (megakernel parity: PathTracerCore.js:606)
-		transparentBackground, // alpha inits to 1 here (megakernel parity: PathTracerCore.js:554) — env-escape-without-opaque zeroes it in Shade
 		auxGBufferEnabled, // live uniform: 1 = init the per-pixel G-buffer (denoiser on), 0 = skip it
 		// listDriven: 1D dispatch over the active-pixel list (activeIndicesRO[tid] = LOCAL slot) instead of 2D.
 		listDriven = false, activeIndicesRO = null, counters = null,
@@ -60,11 +59,8 @@ export function buildGenerateKernel( params ) {
 		const baseSeed = getDecorrelatedSeed( { pixelCoord, rayIndex: int( 0 ), frame } ).toVar();
 		const seed = pcgHash( { state: baseSeed } ).toVar();
 
-		// Sample index 1 (not 0) so the AA sub-pixel jitter draws a DIFFERENT STBN cell
-		// than the first-bounce BSDF sample (ShadeKernel uses sampleIndex 0). Every bounce
-		// samples at index 0, so index 1 is collision-free — this decorrelates the sub-pixel
-		// position from the first scatter direction (they were reading the identical cell).
-		const stratifiedJitter = getStratifiedSample( pixelCoord, int( 1 ), int( 1 ), seed, resolution, frame ).toVar();
+		// Sample index 1, not the bounces' 0, so the sub-pixel position is independent of the first scatter.
+		const stratifiedJitter = getStratifiedSample( pixelCoord, int( 1 ), seed, resolution, frame ).toVar();
 
 		// Y is subtracted because uv.y grows downward while the NDC this used to build grew upward —
 		// keeps the sub-pixel sample sequence bit-identical to the pre-panorama ray gen.

package/src/TSL/Random.js

@@ -1,7 +1,6 @@
 // Three.js Transpiler r182
 
-import { uniform, texture, float, If, wgslFn, uint, TWO_PI, cos, sin, vec2, sqrt, fract, mod, ivec2, select, int, vec4, mix } from 'three/tsl';
-import { DataTexture, FloatType } from 'three';
+import { uniform, float, If, wgslFn, uint, TWO_PI, cos, sin, vec2, sqrt, select, int, vec4 } from 'three/tsl';
 
 // -----------------------------------------------------------------------------
 // Uniform declarations and constants
@@ -12,31 +11,6 @@ const samplingTechnique = samplingTechniqueUniform;
 
 // 0: PCG, 1: Halton, 2: Owen-scrambled Sobol (default; anything higher falls back to it)
 
-// 1x1 placeholder — real texture assigned later via .value = ...
-const _placeholderData = new Float32Array( [ 0.5, 0.5, 0.5, 1.0 ] );
-
-const _placeholderScalar = new DataTexture( _placeholderData, 1, 1 );
-_placeholderScalar.type = FloatType;
-_placeholderScalar.needsUpdate = true;
-
-const _placeholderVec2 = new DataTexture( new Float32Array( [ 0.5, 0.5, 0.0, 1.0 ] ), 1, 1 );
-_placeholderVec2.type = FloatType;
-_placeholderVec2.needsUpdate = true;
-
-// STBN (Spatiotemporal Blue Noise) atlas textures — Heitz 2019
-// Each atlas: 1024×1024, 8×8 grid of 128×128 tiles, 64 temporal slices
-// Scalar atlas: single-channel (R) — optimal for 1D decisions (RR, lobe selection)
-// Vec2 atlas: two-channel (R,G) — decorrelated 2D pairs (direction sampling Xi)
-export const stbnScalarTextureNode = texture( _placeholderScalar );
-stbnScalarTextureNode.setUpdateMatrix( false );
-
-export const stbnVec2TextureNode = texture( _placeholderVec2 );
-stbnVec2TextureNode.setUpdateMatrix( false );
-
-// R2 quasi-random sequence constants (Roberts 2018) — optimal 2D additive offsets
-const R2_A1 = float( 0.7548776662466927 );
-const R2_A2 = float( 0.5698402909980532 );
-
 // -----------------------------------------------------------------------------
 // Basic random number generation
 // -----------------------------------------------------------------------------
@@ -160,53 +134,6 @@ export const RandomPointInCircle = ( rngState ) => {
 export const SAMPLER_DIMS_PER_BOUNCE = 32;
 export const SAMPLER_DIM_AUX_BASE = 4096;
 
-// -----------------------------------------------------------------------------
-// STBN atlas sampling — spatiotemporal blue noise
-// -----------------------------------------------------------------------------
-// Atlas layout: 8×8 grid of 128×128 tiles = 1024×1024 texture.
-// Temporal axis: frame % 64 selects tile (true STBN temporal decorrelation).
-// Spatial decorrelation: R2 quasi-random offset keyed on dimension + sample index.
-
-const computeSTBNAtlasCoord = ( pixelCoords, sampleIndex, dimensionIndex, frame ) => {
-
-	// Temporal slice — true STBN temporal axis
-	const slice = uint( frame ).bitAnd( uint( 63 ) ); // frame % 64
-
-	// R2 quasi-random spatial offset for per-dimension/per-sample decorrelation
-	const n = float( dimensionIndex ).add( float( sampleIndex ).mul( 7.0 ) );
-	const offsetX = int( fract( n.mul( R2_A1 ).add( 0.5 ) ).mul( 128.0 ) );
-	const offsetY = int( fract( n.mul( R2_A2 ).add( 0.5 ) ).mul( 128.0 ) );
-
-	// Pixel within 128×128 tile (toroidal wrap via bitmask)
-	const px = int( pixelCoords.x ).add( offsetX ).bitAnd( int( 127 ) );
-	const py = int( pixelCoords.y ).add( offsetY ).bitAnd( int( 127 ) );
-
-	// Atlas tile position from slice index
-	const tileCol = int( slice ).bitAnd( int( 7 ) ); // slice % 8
-	const tileRow = int( slice ).shiftRight( int( 3 ) ); // slice / 8
-
-	return ivec2( tileCol.mul( int( 128 ) ).add( px ), tileRow.mul( int( 128 ) ).add( py ) );
-
-};
-
-// Sample decorrelated 2D STBN pair in [0,1]²
-export const sampleSTBN2D = ( pixelCoords, sampleIndex, dimensionPairIndex, frame ) => {
-
-	const coord = computeSTBNAtlasCoord( pixelCoords, sampleIndex, dimensionPairIndex, frame );
-	const raw = stbnVec2TextureNode.load( coord ).xy;
-
-	// The atlas has only 64 temporal slices, so frame N and N+64 read the same slice: the
-	// sample repeats and accumulation stops improving past 64 frames. Decorrelate across
-	// 64-frame cycles with a Cranley-Patterson rotation (toroidal shift) by an R2 offset
-	// keyed on the cycle index (frame >> 6). The offset is uniform per cycle, preserving
-	// spatial and within-window temporal blue noise; cycle 0's offset is 0, so frames
-	// 0-63 stay bit-identical. A toroidal shift of uniform samples stays uniform (unbiased).
-	const cycle = float( uint( frame ).shiftRight( uint( 6 ) ) );
-	const rotation = fract( vec2( R2_A1, R2_A2 ).mul( cycle ) );
-	return fract( raw.add( rotation ) );
-
-};
-
 // -----------------------------------------------------------------------------
 // Low-discrepancy sequence generators
 // -----------------------------------------------------------------------------
@@ -531,52 +458,8 @@ export const getRandomSample1D = ( pixelCoord, sampleIndex, dimensionIndex, rngS
 
 };
 
-// Stratified sample. Both call sites pass totalRays = 1, so only the first branch is live;
-// the strata path below is kept for the multi-ray-per-pixel mode that was removed.
-
-export const getStratifiedSample = ( pixelCoord, rayIndex, totalRays, rngState, resolution, frame ) => {
-
-	// result variable avoids early-return ReturnNode escaping into outer Fn scope
-	const result = vec2( 0.0 ).toVar();
-
-	If( totalRays.lessThanEqual( int( 1 ) ), () => {
-
-		result.assign( getRandomSample( pixelCoord, rayIndex, int( 0 ), rngState, int( - 1 ), resolution, frame ) );
-
-	} ).Else( () => {
-
-		// Calculate strata dimensions
-
-		const strataX = int( sqrt( float( totalRays ) ) );
-		const strataY = totalRays.add( strataX ).sub( 1 ).div( strataX );
-		const strataIdx = mod( rayIndex, strataX.mul( strataY ) );
-		const sx = mod( strataIdx, strataX );
-		const sy = strataIdx.div( strataX );
-
-		// Base stratified position
-
-		const strataPos = vec2( float( sx ), float( sy ) ).div( vec2( float( strataX ), float( strataY ) ) );
-
-		const j1 = RandomValueFast( rngState ).toVar();
-		const j2 = RandomValueFast( rngState ).toVar();
-		const jitter = vec2( j1, j2 ).toVar();
-
-		If( totalRays.greaterThan( int( 4 ) ), () => {
-
-			const stbnInfluence = sampleSTBN2D( pixelCoord, rayIndex, int( 0 ), frame ).mul( 0.1 );
-			jitter.assign( mix( jitter, stbnInfluence, 0.2 ) );
-
-		} );
-
-		jitter.divAssign( vec2( float( strataX ), float( strataY ) ) );
-
-		result.assign( strataPos.add( jitter ) );
-
-	} );
-
-	return result;
-
-};
+export const getStratifiedSample = ( pixelCoord, rayIndex, rngState, resolution, frame ) =>
+	getRandomSample( pixelCoord, rayIndex, int( 0 ), rngState, int( - 1 ), resolution, frame );
 
 // Get decorrelated seed with better mixing
 

package/src/TSL/ShadeKernel.js

@@ -10,11 +10,11 @@ import {
 	If, Loop, normalize, max, min, exp, log, clamp, dot, length, select, smoothstep, acos,
 	instanceIndex,
 	sampler,
-	atomicAdd, atomicLoad, atomicStore, uintBitsToFloat,
+	atomicLoad, atomicStore,
 	Return,
 } from 'three/tsl';
 
-import { sampleEnvironment, sampleEquirectProbability, sampleEquirect, groundProjectedEnvDir } from './Environment.js';
+import { sampleEnvironment, sampleEquirect, groundProjectedEnvDir } from './Environment.js';
 import { getMaterial, powerHeuristic, balanceHeuristic, classifyMaterial, REC709_LUMINANCE_COEFFICIENTS, PI_INV, EPSILON, diffuseGroundMaterial, offsetRayOrigin, SHADOW_END } from './Common.js';
 import { cosineWeightedSample } from './MaterialSampling.js';
 import { sampleAllMaterialTextures, processAnisotropyMap, applyExtensionMaps, getTransformedUV, triangleUVTangent } from './TextureSampling.js';
@@ -107,7 +107,7 @@ export function buildShadeKernel( params ) {
 		accumFrame,
 		chunkRowBase, // chunked path pool: global pixel = chunkRowBase·W + localSlot (rayID). See spec.
 		emissiveTriangleCount, emissiveVec4Offset, emissiveTotalPower,
-		emissiveBoost, totalTriangleCount, enableEmissiveTriangleSampling,
+		emissiveBoost, enableEmissiveTriangleSampling,
 		lightBVHNodeCount, reverseMapVec4Offset,
 		maxRayCount,
 		// Aux G-buffer (normal/depth/albedo + surface ID) feeds only the denoiser/OIDN MRT. Gated by a
@@ -201,9 +201,9 @@ export function buildShadeKernel( params ) {
 		const pixelIndex = rayID;
 		const rngState = readRngState( hitBufferRW, rayID ).toVar();
 
-		// STBN keyed on (GLOBAL pixel, dimension, frame). pixelIndex is the LOCAL path slot; the global pixel
-		// = chunkRowBase·W + localSlot, so the blue-noise pattern stays spatially aligned across row-band chunks
-		// (and matches Generate's per-pixel RNG seed). chunkRowBase is 0 in the single-chunk case.
+		// Samples key on the GLOBAL pixel. pixelIndex is the LOCAL path slot; the global pixel
+		// = chunkRowBase·W + localSlot, so sequences stay aligned across row-band chunks
+		// (and match Generate's per-pixel RNG seed). chunkRowBase is 0 in the single-chunk case.
 		// Hoisted here rather than at the BSDF draw because the ground catcher runs NEE far earlier.
 		const _resX = int( resolution.x ).toVar();
 		const _globalPixel = int( pixelIndex ).add( chunkRowBase.mul( _resX ) );

package/src/index.js

@@ -12,7 +12,7 @@ import './TSL/patches.js';
 export { PathTracerApp, describeAdapter } from './PathTracerApp.js';
 
 // Event types
-export { EngineEvents } from './EngineEvents.js';
+export { EngineEvents, LEGACY_EVENT_NAMES } from './EngineEvents.js';
 
 // Headless rendering — the supported entry point for a caller with no screen
 export { renderHeadless, openHeadless, captureHeadless } from './Headless.js';
@@ -25,6 +25,7 @@ export { SETTING_SOURCE } from './RenderSettings.js';
 
 // Asset URL / cache namespace overrides (call before constructing PathTracerApp)
 export { configureAssets, getAssetConfig } from './AssetConfig.js';
+export { configurePlatform, getPlatform } from './Platform.js';
 
 // On-disk storage (origin private file system): caches, and areas a host defines for its own data
 export {