rayzee 7.11.1 → 7.12.0

package/src/TSL/FinalWriteKernel.js

@@ -4,13 +4,15 @@
 
 import {
 	Fn, wgslFn, float, vec2, vec4, int, uint, uvec2,
-	If, mix, select, texture, textureStore, length,
+	If, mix, select, texture, textureStore, length, atomicAdd,
 	localId, workgroupId,
 } from 'three/tsl';
 
 import {
 	readRayRadiance, readGBuffer, gbDecodeNormalDepth, gbDecodeAlbedo,
 } from '../Processor/PackedRayBuffer.js';
+import { luminance } from './Common.js';
+import { COUNTER } from '../Processor/QueueManager.js';
 
 const WG_SIZE = 16;
 
@@ -41,10 +43,18 @@ export function buildFinalWriteKernel( params ) {
 		// Clean-aux normal (1 = temporally accumulate + renormalize the aux normal). On only for clean-aux
 		// OIDN models (calb_cnrm/high, alb_nrm/balanced); off for fast/ASVGF which want the bump normal.
 		cleanAuxNormalEnabled,
+		// Tier-1 convergence early-stop: per-pixel Welford luminance second moment + converged-pixel counter.
+		counters, m2BufferRW, useAdaptiveSampling, noiseThreshold, darkNoiseFloor, adaptiveMinSamples,
+		// Tier-2 per-pixel freeze: streakBufferRW = per-pixel freeze-candidate streak (stamped here);
+		// frozenMaskRO = dilated frozen mask from buildActivePixels (pass-through gates on it, not streak).
+		usePixelFreeze, pixelFreezeThreshold, pixelFreezeStability, streakBufferRW, frozenMaskRO,
 	} = params;
 
 	const auxOn = auxGBufferEnabled.greaterThan( uint( 0 ) );
 	const cleanAuxNormalOn = cleanAuxNormalEnabled.greaterThan( uint( 0 ) );
+	// useAdaptiveSampling is registered via UniformManager.ub() → an int 0/1 uniform, so compare against int(0).
+	const convOn = useAdaptiveSampling.greaterThan( int( 0 ) );
+	const adaptiveOn = usePixelFreeze.greaterThan( int( 0 ) );
 
 	const computeFn = Fn( () => {
 
@@ -60,6 +70,11 @@ export function buildFinalWriteKernel( params ) {
 			const finalColor = sampleColor.xyz.toVar();
 			const outputAlpha = select( transparentBackground, sampleColor.w, float( 1.0 ) ).toVar();
 
+			// A pixel frozen in a prior frame was skipped by Generate, so its rayBuffer sample is stale — pass
+			// the accumulated colour through unchanged (below) instead of mixing it. Inert unless adaptiveOn.
+			const wasFrozen = adaptiveOn.and( frame.greaterThan( uint( 0 ) ) )
+				.and( frozenMaskRO.element( rayID ).equal( uint( 1 ) ) ).toVar();
+
 			// MRT comes from the per-pixel G-buffer (rayID == pixelIndex). Half-packed: decode.
 			// auxOn gates the decode + stores so a no-denoiser frame does no G-buffer read and no aux writes.
 			const finalNormalDepth = vec4( 0.0 ).toVar();
@@ -81,7 +96,8 @@ export function buildFinalWriteKernel( params ) {
 
 				const prevAccumSample = texture( prevAccumTexture, prevUV, 0 ).toVar();
 
-				finalColor.assign( mix( prevAccumSample.xyz, sampleColor.xyz, accumulationAlpha ) );
+				// Frozen pixels pass prev colour through unchanged (stale sample); active pixels accumulate.
+				finalColor.assign( select( wasFrozen, prevAccumSample.xyz, mix( prevAccumSample.xyz, sampleColor.xyz, accumulationAlpha ) ) );
 				If( auxOn, () => {
 
 					// Albedo averages cleanly (it's a colour).
@@ -109,7 +125,74 @@ export function buildFinalWriteKernel( params ) {
 
 				If( transparentBackground, () => {
 
-					outputAlpha.assign( mix( prevAccumSample.w, sampleColor.w, accumulationAlpha ) );
+					outputAlpha.assign( select( wasFrozen, prevAccumSample.w, mix( prevAccumSample.w, sampleColor.w, accumulationAlpha ) ) );
+
+				} );
+
+			} );
+
+			// Tier-1 convergence: per-pixel running second moment of LUMINANCE (Welford). luminance() is linear,
+			// so luminance(running-mean color) == running-mean luminance == E[L]; m2 tracks E[L²] under the SAME
+			// global 1/(frame+1) alpha (NO per-pixel alpha). sampleVar = E[L²]-E[L]²; varOfMean = sampleVar/(N);
+			// relErr = SE(mean)/mean. A pixel counts as converged once frame>=minSamples AND relErr<threshold.
+			// The m2 write runs every frame (incl. frame 0, where alpha==1 self-inits it → no explicit clear).
+			// Sits AFTER the accumulation mix (finalColor is the mean) and BEFORE the visMode-11 mutation.
+			If( convOn, () => {
+
+				const sampleLum = luminance( sampleColor.xyz );
+				const prevM2 = m2BufferRW.element( rayID ).toVar();
+				const m2 = mix( prevM2, sampleLum.mul( sampleLum ), accumulationAlpha ).toVar();
+				m2BufferRW.element( rayID ).assign( m2 );
+
+				const meanLum = luminance( finalColor ).toVar();
+				const sampleVar = m2.sub( meanLum.mul( meanLum ) ).max( float( 0 ) );
+				const varOfMean = sampleVar.div( float( frame ).add( 1.0 ) );
+				// absSE = absolute standard error of the mean luminance; relErr = its ratio to the mean.
+				// Combined criterion: bright pixels converge on relErr<threshold; dark/dim pixels (where relErr
+				// stays high forever) converge on absSE<absFloor, since their absolute noise is imperceptible.
+				const absSE = varOfMean.sqrt().toVar();
+				const relErr = absSE.div( meanLum.add( float( 1e-4 ) ) );
+
+				If( frame.greaterThanEqual( uint( adaptiveMinSamples ) ).and(
+					relErr.lessThan( noiseThreshold ).or( absSE.lessThan( darkNoiseFloor ) )
+				), () => {
+
+					atomicAdd( counters.element( uint( COUNTER.CONVERGED_COUNT ) ), uint( 1 ) );
+
+				} );
+
+				// Maintain the freeze streak on the relErr-only predicate (NO absFloor — it bakes dim regions dark
+				// when it permanently freezes a pixel). Monotonic: streak>=K freezes for the run, so global alpha stays exact.
+				If( adaptiveOn, () => {
+
+					If( frame.equal( uint( 0 ) ), () => {
+
+						// Frame 0 (post-reset/camera-move) clears the frozen state so each run re-freezes fresh.
+						streakBufferRW.element( rayID ).assign( uint( 0 ) );
+
+					} );
+
+					If( wasFrozen, () => {
+
+						// Already frozen (passed through above) — count it.
+						atomicAdd( counters.element( uint( COUNTER.FROZEN_COUNT ) ), uint( 1 ) );
+
+					} );
+
+					If( wasFrozen.not().and( frame.greaterThan( uint( 0 ) ) ), () => {
+
+						const freezeCandidate = frame.greaterThanEqual( uint( adaptiveMinSamples ) )
+							.and( relErr.lessThan( pixelFreezeThreshold ) );
+						const newStreak = select( freezeCandidate, streakBufferRW.element( rayID ).add( uint( 1 ) ), uint( 0 ) ).toVar();
+						streakBufferRW.element( rayID ).assign( newStreak );
+						// Just reached K → frozen next frame; count it now so the frozen population is current.
+						If( newStreak.greaterThanEqual( uint( pixelFreezeStability ) ), () => {
+
+							atomicAdd( counters.element( uint( COUNTER.FROZEN_COUNT ) ), uint( 1 ) );
+
+						} );
+
+					} );
 
 				} );
 

package/src/TSL/GenerateKernel.js

@@ -1,10 +1,12 @@
 /**
- * GenerateKernel.js — wavefront primary ray generation (16×16, 2D screen-space dispatch).
+ * GenerateKernel.js — wavefront primary ray generation.
+ * Two dispatch modes from one builder: 2D screen-space (default) and 1D list-driven over the active-pixel
+ * list (Tier-2 per-pixel freeze).
  */
 
 import {
 	Fn, float, vec2, vec3, vec4, int, uint,
-	If, select,
+	If, select, instanceIndex, atomicLoad,
 	localId, workgroupId,
 } from 'three/tsl';
 
@@ -16,7 +18,7 @@ import {
 
 import { generateRayFromCamera } from './BVHTraversal.js';
 import { Ray } from './Struct.js';
-import { RAY_FLAG } from '../Processor/QueueManager.js';
+import { RAY_FLAG, COUNTER } from '../Processor/QueueManager.js';
 import {
 	writeRayOriginMeta, writeRayDirFlags, writeRayThroughputPdf,
 	writeRayRadiance, writeGBuffer,
@@ -36,68 +38,94 @@ export function buildGenerateKernel( params ) {
 		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] = pixelID) instead of 2D.
+		listDriven = false, activeIndicesRO = null, counters = null,
 	} = params;
 
 	const auxOn = auxGBufferEnabled.greaterThan( uint( 0 ) );
 
-	const computeFn = Fn( () => {
+	// Shared ray-gen body for a pixel (gx, gy) — identical in both dispatch modes.
+	const emitRay = ( gx, gy ) => {
+
+		const pixelCoord = vec2( float( gx ).add( 0.5 ), float( gy ).add( 0.5 ) );
+		const pixelIndex = gy.mul( int( resolution.x ) ).add( gx );
+		// One ray per pixel: rayID is the pixel index.
+		const rayID = uint( pixelIndex );
+
+		const screenPosition = pixelCoord.div( resolution ).mul( 2.0 ).sub( 1.0 ).toVar();
+		screenPosition.y.assign( screenPosition.y.negate() );
+
+		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();
+
+		const jitterScale = vec2( 2.0 ).div( resolution );
+		const jitter = stratifiedJitter.sub( 0.5 ).mul( jitterScale );
+		const jitteredScreenPosition = screenPosition.add( jitter );
+
+		const ray = Ray.wrap( generateRayFromCamera(
+			jitteredScreenPosition, seed,
+			cameraWorldMatrix, cameraProjectionMatrixInverse,
+			enableDOF, focalLength, aperture, focusDistance, sceneScale, apertureScale, anamorphicRatio,
+		) );
+
+		writeRayOriginMeta( rayBufferRW, rayID, ray.origin, int( 0 ), int( 0 ) );
+		// A fresh camera ray is NOT redirected — REDIRECTED stays clear so it sees the direct backdrop;
+		// ShadeKernel sets REDIRECTED on the first direction-changing interaction (see RAY_FLAG.REDIRECTED).
+		writeRayDirFlags( rayBufferRW, rayID, ray.direction, uint( RAY_FLAG.ACTIVE ) );
+		// pdf inits to 0 = prevBouncePdf (megakernel parity PathTracerCore.js:556). The bounce>0 env/emissive
+		// MIS gate skips until an opaque scatter writes a real combinedPdf; free bounces preserve it.
+		writeRayThroughputPdf( rayBufferRW, rayID, vec4( 1.0, 1.0, 1.0, 0.0 ).xyz, float( 0.0 ) );
+		// Alpha inits to 1 in transparent-bg mode (megakernel parity: PathTracerCore.js:554). Shade zeroes
+		// it only on env-escape-without-opaque; a ray that dies inside geometry (e.g. SSS walk termination)
+		// keeps alpha 1 → solid. Non-transparent mode is inert (FinalWrite forces alpha 1).
+		writeRayRadiance( rayBufferRW, rayID, vec4( vec3( 0.0 ), select( transparentBackground, float( 1.0 ), float( 0.0 ) ) ) );
+
+		If( auxOn, () => {
+
+			// default: normal +Z, depth 1 (far), black albedo (background/miss)
+			writeGBuffer( gBufferRW, uint( pixelIndex ), vec3( 0.0, 0.0, 1.0 ), float( 1.0 ), vec3( 0.0 ) );
 
-		const gx = int( workgroupId.x ).mul( WG_SIZE ).add( int( localId.x ) );
-		const gy = int( workgroupId.y ).mul( WG_SIZE ).add( int( localId.y ) );
+		} );
 
-		If( gx.lessThan( renderWidth ).and( gy.lessThan( renderHeight ) ), () => {
+		writeMediumStack( rayBufferRW, rayID, uint( 0 ), uint( transmissiveBounces ), float( 1.0 ), float( 1.0 ), float( 1.0 ) );
 
-			const pixelCoord = vec2( float( gx ).add( 0.5 ), float( gy ).add( 0.5 ) );
-			const pixelIndex = gy.mul( int( resolution.x ) ).add( gx );
-			// One ray per pixel: rayID is the pixel index.
-			const rayID = uint( pixelIndex );
+		rngBufferRW.element( rayID ).assign( seed );
 
-			const screenPosition = pixelCoord.div( resolution ).mul( 2.0 ).sub( 1.0 ).toVar();
-			screenPosition.y.assign( screenPosition.y.negate() );
+	};
 
-			const baseSeed = getDecorrelatedSeed( { pixelCoord, rayIndex: int( 0 ), frame } ).toVar();
-			const seed = pcgHash( { state: baseSeed } ).toVar();
+	const computeFn = Fn( () => {
 
-			// 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();
+		if ( listDriven ) {
 
-			const jitterScale = vec2( 2.0 ).div( resolution );
-			const jitter = stratifiedJitter.sub( 0.5 ).mul( jitterScale );
-			const jitteredScreenPosition = screenPosition.add( jitter );
+			const tid = instanceIndex;
+			// Grid is over-sized from a stale readback; bound on the live ENTERING_COUNT so extra threads no-op.
+			If( tid.lessThan( atomicLoad( counters.element( uint( COUNTER.ENTERING_COUNT ) ) ) ), () => {
 
-			const ray = Ray.wrap( generateRayFromCamera(
-				jitteredScreenPosition, seed,
-				cameraWorldMatrix, cameraProjectionMatrixInverse,
-				enableDOF, focalLength, aperture, focusDistance, sceneScale, apertureScale, anamorphicRatio,
-			) );
+				const pixelIndex = int( activeIndicesRO.element( tid ) );
+				const gx = pixelIndex.mod( int( resolution.x ) );
+				const gy = pixelIndex.div( int( resolution.x ) );
+				emitRay( gx, gy );
 
-			writeRayOriginMeta( rayBufferRW, rayID, ray.origin, int( 0 ), int( 0 ) );
-			// A fresh camera ray is NOT redirected — REDIRECTED stays clear so it sees the direct backdrop;
-			// ShadeKernel sets REDIRECTED on the first direction-changing interaction (see RAY_FLAG.REDIRECTED).
-			writeRayDirFlags( rayBufferRW, rayID, ray.direction, uint( RAY_FLAG.ACTIVE ) );
-			// pdf inits to 0 = prevBouncePdf (megakernel parity PathTracerCore.js:556). The bounce>0 env/emissive
-			// MIS gate skips until an opaque scatter writes a real combinedPdf; free bounces preserve it.
-			writeRayThroughputPdf( rayBufferRW, rayID, vec4( 1.0, 1.0, 1.0, 0.0 ).xyz, float( 0.0 ) );
-			// Alpha inits to 1 in transparent-bg mode (megakernel parity: PathTracerCore.js:554). Shade zeroes
-			// it only on env-escape-without-opaque; a ray that dies inside geometry (e.g. SSS walk termination)
-			// keeps alpha 1 → solid. Non-transparent mode is inert (FinalWrite forces alpha 1).
-			writeRayRadiance( rayBufferRW, rayID, vec4( vec3( 0.0 ), select( transparentBackground, float( 1.0 ), float( 0.0 ) ) ) );
+			} );
 
-			If( auxOn, () => {
+		} else {
 
-				// default: normal +Z, depth 1 (far), black albedo (background/miss)
-				writeGBuffer( gBufferRW, uint( pixelIndex ), vec3( 0.0, 0.0, 1.0 ), float( 1.0 ), vec3( 0.0 ) );
+			const gx = int( workgroupId.x ).mul( WG_SIZE ).add( int( localId.x ) );
+			const gy = int( workgroupId.y ).mul( WG_SIZE ).add( int( localId.y ) );
 
-			} );
+			If( gx.lessThan( renderWidth ).and( gy.lessThan( renderHeight ) ), () => {
 
-			writeMediumStack( rayBufferRW, rayID, uint( 0 ), uint( transmissiveBounces ), float( 1.0 ), float( 1.0 ), float( 1.0 ) );
+				emitRay( gx, gy );
 
-			rngBufferRW.element( rayID ).assign( seed );
+			} );
 
-		} );
+		}
 
 	} );
 

package/src/TSL/ShadeKernel.js

@@ -10,7 +10,7 @@ import {
 	If, Loop, normalize, max, exp, log, clamp, dot, length, select,
 	instanceIndex,
 	sampler,
-	atomicAdd, atomicLoad, uintBitsToFloat,
+	atomicAdd, atomicLoad, atomicStore, uintBitsToFloat,
 	Return,
 } from 'three/tsl';
 
@@ -137,6 +137,19 @@ export function buildShadeKernel( params ) {
 
 		const threadIdx = instanceIndex;
 
+		// Folds the former resetActiveCounter 1-thread kernel: thread 0 zeroes the survivor counter
+		// before compact re-counts it. Kept ABOVE the ENTERING_COUNT guard so it fires even at bound 0.
+		// Safe: shade never touches ACTIVE_RAY_COUNT, and the shade→compact dispatch boundary publishes it.
+		if ( counters ) {
+
+			If( threadIdx.equal( uint( 0 ) ), () => {
+
+				atomicStore( counters.element( uint( COUNTER.ACTIVE_RAY_COUNT ) ), uint( 0 ) );
+
+			} );
+
+		}
+
 		// bound on ENTERING_COUNT so an over-sized margin dispatch is safe
 		const bound = counters ? atomicLoad( counters.element( uint( COUNTER.ENTERING_COUNT ) ) ) : maxRayCount;
 		If( threadIdx.greaterThanEqual( bound ), () => {

package/src/managers/UniformManager.js

@@ -167,6 +167,21 @@ export class UniformManager {
 		u( 'visMode', DEFAULT_STATE.debugMode, 'int' );
 		u( 'debugVisScale', DEFAULT_STATE.debugVisScale, 'float' );
 
+		// Tier-1 convergence early-stop (FinalWrite reads these; live-toggled, no shader rebuild)
+		ub( 'useAdaptiveSampling', DEFAULT_STATE.useAdaptiveSampling );
+		u( 'noiseThreshold', DEFAULT_STATE.noiseThreshold, 'float' );
+		u( 'darkNoiseFloor', DEFAULT_STATE.darkNoiseFloor, 'float' );
+		u( 'adaptiveMinSamples', DEFAULT_STATE.adaptiveMinSamples, 'int' );
+		// CPU-only (read in PathTracer._isConvergedComplete, not bound to any kernel); registered here for
+		// the settings/configureForMode plumbing + the _defineUniformGetters accessor.
+		u( 'adaptiveStopFraction', DEFAULT_STATE.adaptiveStopFraction, 'float' );
+
+		// Tier-2 per-pixel freeze. usePixelFreeze gates both FinalWrite (stamp + pass-through) and render()'s
+		// frozen-compaction dispatch path.
+		ub( 'usePixelFreeze', DEFAULT_STATE.usePixelFreeze );
+		u( 'pixelFreezeThreshold', DEFAULT_STATE.pixelFreezeThreshold, 'float' );
+		u( 'pixelFreezeStability', DEFAULT_STATE.pixelFreezeStability, 'int' );
+
 		// Accumulation
 		ub( 'enableAccumulation', true );
 		u( 'accumulationAlpha', 0.0, 'float' );