rayzee 7.16.0 → 7.18.0

package/src/Stages/PathTracerStage.js

@@ -25,6 +25,9 @@ import { LightSerializer } from '../Processor/LightSerializer';
 // Constants
 import { ENGINE_DEFAULTS as DEFAULT_STATE } from '../EngineDefaults.js';
 import { getAssetConfig } from '../AssetConfig.js';
+import { createLogger, fmt } from '../utils/Logger.js';
+
+const log = createLogger( 'pathtracer' );
 
 /**
  * Data layout constants
@@ -377,7 +380,7 @@ export class PathTracerStage extends RenderStage {
 
 			this.stbnScalarTexture = configure( tex );
 			stbnScalarTextureNode.value = tex;
-			console.log( `PathTracer: STBN scalar atlas loaded ${tex.image.width}x${tex.image.height}` );
+			log.debug( `STBN scalar atlas ${fmt.px( tex.image.width, tex.image.height )}` );
 
 		} );
 
@@ -385,7 +388,7 @@ export class PathTracerStage extends RenderStage {
 
 			this.stbnVec2Texture = configure( tex );
 			stbnVec2TextureNode.value = tex;
-			console.log( `PathTracer: STBN vec2 atlas loaded ${tex.image.width}x${tex.image.height}` );
+			log.debug( `STBN vec2 atlas ${fmt.px( tex.image.width, tex.image.height )}` );
 
 		} );
 
@@ -548,7 +551,7 @@ export class PathTracerStage extends RenderStage {
 
 			this.directionalLightsData = mockMaterial.uniforms.directionalLights.value;
 
-			console.log( `Sun added as directional light (intensity: ${scaledSunIntensity.toFixed( 2 )})` );
+			log.debug( `sun added as directional light · intensity ${scaledSunIntensity.toFixed( 2 )}` );
 
 		}
 
@@ -716,7 +719,7 @@ export class PathTracerStage extends RenderStage {
 
 		this.triangleCount = triangleCount;
 
-		console.log( `PathTracer: ${this.triangleCount} triangles (storage buffer)` );
+		log.debug( `${fmt.n( this.triangleCount )} triangles (storage buffer)` );
 
 	}
 
@@ -744,7 +747,7 @@ export class PathTracerStage extends RenderStage {
 		}
 
 		this.bvhNodeCount = Math.floor( vec4Count / BVH_VEC4_PER_NODE );
-		console.log( `PathTracer: ${this.bvhNodeCount} BVH nodes (storage buffer)` );
+		log.debug( `${fmt.n( this.bvhNodeCount )} BVH nodes (storage buffer)` );
 
 	}
 
@@ -983,14 +986,14 @@ export class PathTracerStage extends RenderStage {
 
 		if ( ! this.triangleStorageNode ) {
 
-			console.error( 'PathTracer: Triangle data required' );
+			log.error( 'triangle data required' );
 			return;
 
 		}
 
 		if ( ! this.bvhStorageNode ) {
 
-			console.error( 'PathTracer: BVH data required' );
+			log.error( 'BVH data required' );
 			return;
 
 		}
@@ -1348,7 +1351,7 @@ export class PathTracerStage extends RenderStage {
 		this.emissiveTriangleCount.value = count;
 		this.emissiveTotalPower.value = totalPower;
 		this._rebuildLightBuffer();
-		console.log( `PathTracer: ${count} emissive triangles, totalPower=${totalPower.toFixed( 4 )} (storage buffer)` );
+		log.debug( `${fmt.n( count )} emissive triangles · totalPower ${totalPower.toFixed( 4 )} (storage buffer)` );
 
 	}
 
@@ -1359,7 +1362,7 @@ export class PathTracerStage extends RenderStage {
 		this._lbvhDataCache = nodeData;
 		this.lightBVHNodeCount.value = nodeCount;
 		this._rebuildLightBuffer();
-		console.log( `PathTracer: Light BVH ${nodeCount} nodes` );
+		log.debug( `light BVH ${fmt.n( nodeCount )} nodes` );
 
 	}
 
@@ -1402,7 +1405,7 @@ export class PathTracerStage extends RenderStage {
 
 		try {
 
-			console.log( 'PathTracer: Starting material rebuild...' );
+			log.debug( 'material rebuild started' );
 
 			await this.sdfs.rebuildMaterials( scene );
 			this.updateSceneUniforms();
@@ -1410,20 +1413,20 @@ export class PathTracerStage extends RenderStage {
 			this.updateLights();
 			this.reset();
 
-			console.log( 'PathTracer materials rebuilt successfully' );
+			log.debug( 'material rebuild complete' );
 
 		} catch ( error ) {
 
-			console.error( 'Error rebuilding PathTracer materials:', error );
+			log.error( 'material rebuild failed:', error );
 
 			try {
 
-				console.warn( 'Attempting recovery by resetting path tracer...' );
+				log.warn( 'attempting recovery by resetting the path tracer' );
 				this.reset();
 
 			} catch ( recoveryError ) {
 
-				console.error( 'Recovery failed:', recoveryError );
+				log.error( 'recovery failed:', recoveryError );
 
 			}
 

package/src/Stages/Variance.js

@@ -404,6 +404,29 @@ export class Variance extends RenderStage {
 
 	}
 
+	// Reserved-storage change (e.g. 4K toggle): recreate the MAX-preallocated StorageTextures at the new live
+	// reserved size + rebuild the compute nodes in place. Same stage object, so refs/wiring stay valid.
+	reallocateReservedStorage() {
+
+		this._computeNodeA?.dispose();
+		this._computeNodeB?.dispose();
+		this._storageTexA?.dispose();
+		this._storageTexB?.dispose();
+		const mk = () => {
+
+			const t = new StorageTexture( MAX_STORAGE_TEXTURE_SIZE, MAX_STORAGE_TEXTURE_SIZE );
+			t.type = FloatType; t.format = RGBAFormat; t.minFilter = LinearFilter; t.magFilter = LinearFilter;
+			return t;
+
+		};
+
+		this._storageTexA = mk();
+		this._storageTexB = mk();
+		this._buildCompute();
+		this._compiled = false;
+
+	}
+
 	dispose() {
 
 		this._computeNodeA?.dispose();

package/src/TSL/FinalWriteKernel.js

@@ -1,5 +1,10 @@
 /**
  * FinalWriteKernel.js — wavefront final output: temporal accumulation + MRT StorageTexture writes (16×16, 2D).
+ *
+ * Chunked path pool (docs/internal/specs/wavefront-chunked-pool.md): runs 2D over one row band
+ * (renderWidth × chunkRows). A thread's band-local row `localGy` maps to global row `gy = chunkRowBase + localGy`.
+ * Path state + the per-chunk G-buffer are read at the LOCAL slot `rayID = localGy·W + gx`; the persistent
+ * per-pixel buffers (m2/streak/frozenMask) and the output texture use the GLOBAL pixel `p = gy·W + gx`.
  */
 
 import {
@@ -35,7 +40,8 @@ export function buildFinalWriteKernel( params ) {
 		enableAccumulation, hasPreviousAccumulated, accumulationAlpha, cameraIsMoving,
 		transparentBackground,
 		prevAccumTexture, prevAlbedoTexture, prevNormalDepthTexture,
-		renderWidth, renderHeight,
+		renderWidth,
+		chunkRowBase, chunkRows, // row band offset (global first row) + row count for this chunk
 		visMode,
 		// Aux MRT (normalDepth + albedo) feeds only the denoiser/OIDN. Gated by a live uniform (1 = denoiser
 		// on): when off, skip the G-buffer decode, the prev-frame aux mix, and the two aux stores.
@@ -44,7 +50,8 @@ export function buildFinalWriteKernel( params ) {
 		// 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,
+		counters, m2BufferRW, useAdaptiveSampling, noiseThreshold, 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,
@@ -59,12 +66,13 @@ export function buildFinalWriteKernel( params ) {
 	const computeFn = Fn( () => {
 
 		const gx = int( workgroupId.x ).mul( WG_SIZE ).add( int( localId.x ) );
-		const gy = int( workgroupId.y ).mul( WG_SIZE ).add( int( localId.y ) );
+		const localGy = int( workgroupId.y ).mul( WG_SIZE ).add( int( localId.y ) );
 
-		If( gx.lessThan( renderWidth ).and( gy.lessThan( renderHeight ) ), () => {
+		If( gx.lessThan( renderWidth ).and( localGy.lessThan( chunkRows ) ), () => {
 
-			const pixelIndex = gy.mul( int( resolution.x ) ).add( gx );
-			const rayID = uint( pixelIndex );
+			const gy = localGy.add( chunkRowBase ); // GLOBAL row
+			const rayID = uint( localGy.mul( renderWidth ).add( gx ) ); // LOCAL path/gBuffer slot
+			const pixelId = uint( gy.mul( renderWidth ).add( gx ) ); // GLOBAL pixel (persistent buffers + texture)
 
 			const sampleColor = readRayRadiance( rayBufferRO, rayID );
 			const finalColor = sampleColor.xyz.toVar();
@@ -73,9 +81,9 @@ export function buildFinalWriteKernel( params ) {
 			// 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();
+				.and( frozenMaskRO.element( pixelId ).equal( uint( 1 ) ) ).toVar();
 
-			// MRT comes from the per-pixel G-buffer (rayID == pixelIndex). Half-packed: decode.
+			// MRT comes from the per-chunk G-buffer (LOCAL slot). 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();
 			const finalAlbedo = vec4( 0.0 ).xyz.toVar();
@@ -134,15 +142,15 @@ export function buildFinalWriteKernel( params ) {
 			// 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.
+			// absSE = SE(mean); a pixel converges once frame>=minSamples AND the √-normalized error < 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 prevM2 = m2BufferRW.element( pixelId ).toVar();
 				const m2 = mix( prevM2, sampleLum.mul( sampleLum ), accumulationAlpha ).toVar();
-				m2BufferRW.element( rayID ).assign( m2 );
+				m2BufferRW.element( pixelId ).assign( m2 );
 
 				const meanLum = luminance( finalColor ).toVar();
 				const sampleVar = m2.sub( meanLum.mul( meanLum ) ).max( float( 0 ) );
@@ -151,11 +159,15 @@ export function buildFinalWriteKernel( params ) {
 				// 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 ) ) );
+				const relErr = absSE.div( meanLum.add( float( 1e-4 ) ) ); // Tier-2 freeze predicate reads this
+
+				// Cycles-style convergence: normalize the standard error by √luminance for dim pixels (lum<1),
+				// by luminance for bright ones. The √ loosens the relative bar in shadows so dark pixels converge
+				// on their small absolute noise instead of stalling forever on a pure relative bar.
+				const convNorm = select( meanLum.lessThan( float( 1.0 ) ), meanLum.sqrt(), meanLum );
+				const converged = absSE.div( convNorm.add( float( 1e-4 ) ) ).lessThan( noiseThreshold );
 
-				If( frame.greaterThanEqual( uint( adaptiveMinSamples ) ).and(
-					relErr.lessThan( noiseThreshold ).or( absSE.lessThan( darkNoiseFloor ) )
-				), () => {
+				If( frame.greaterThanEqual( uint( adaptiveMinSamples ) ).and( converged ), () => {
 
 					atomicAdd( counters.element( uint( COUNTER.CONVERGED_COUNT ) ), uint( 1 ) );
 
@@ -168,7 +180,7 @@ export function buildFinalWriteKernel( params ) {
 					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 ) );
+						streakBufferRW.element( pixelId ).assign( uint( 0 ) );
 
 					} );
 
@@ -183,8 +195,8 @@ export function buildFinalWriteKernel( params ) {
 
 						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 );
+						const newStreak = select( freezeCandidate, streakBufferRW.element( pixelId ).add( uint( 1 ) ), uint( 0 ) ).toVar();
+						streakBufferRW.element( pixelId ).assign( newStreak );
 						// Just reached K → frozen next frame; count it now so the frozen population is current.
 						If( newStreak.greaterThanEqual( uint( pixelFreezeStability ) ), () => {
 

package/src/TSL/GenerateKernel.js

@@ -2,6 +2,12 @@
  * 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).
+ *
+ * Chunked path pool (docs/internal/specs/wavefront-chunked-pool.md): the image is streamed through a fixed
+ * device-budget pool in row bands. A kernel thread maps to a LOCAL path slot `rayID` (∈ [0,B)); the global
+ * pixel is `pixelBase + rayID` where `pixelBase = chunkRowBase · renderWidth`. Path state / gBuffer are
+ * written at the LOCAL slot; camera ray + RNG seed use the GLOBAL pixel coord (so a pixel's sample sequence
+ * is stable across chunks and frames).
  */
 
 import {
@@ -22,7 +28,7 @@ import { RAY_FLAG, COUNTER } from '../Processor/QueueManager.js';
 import {
 	writeRayOriginMeta, writeRayDirFlags, writeRayThroughputPdf,
 	writeRayRadiance, writeGBuffer,
-	writeMediumStack,
+	writeMediumStack, writeFeatureThroughput,
 } from '../Processor/PackedRayBuffer.js';
 
 const WG_SIZE = 16;
@@ -34,23 +40,21 @@ export function buildGenerateKernel( params ) {
 		resolution, frame,
 		cameraWorldMatrix, cameraProjectionMatrixInverse,
 		enableDOF, focalLength, aperture, focusDistance, sceneScale, apertureScale, anamorphicRatio,
-		renderWidth, renderHeight,
+		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] = pixelID) instead of 2D.
+		// listDriven: 1D dispatch over the active-pixel list (activeIndicesRO[tid] = LOCAL slot) instead of 2D.
 		listDriven = false, activeIndicesRO = null, counters = null,
 	} = params;
 
 	const auxOn = auxGBufferEnabled.greaterThan( uint( 0 ) );
 
-	// Shared ray-gen body for a pixel (gx, gy) — identical in both dispatch modes.
-	const emitRay = ( gx, gy ) => {
+	// Shared ray-gen body. (gx, gy) is the GLOBAL pixel; rayID is the LOCAL path-slot (both dispatch modes).
+	const emitRay = ( gx, gy, rayID ) => {
 
 		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() );
@@ -88,8 +92,10 @@ export function buildGenerateKernel( params ) {
 
 		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 ) );
+			// default: normal +Z, depth 1 (far), black albedo (background/miss). Per-CHUNK G-buffer → LOCAL slot.
+			writeGBuffer( gBufferRW, rayID, vec3( 0.0, 0.0, 1.0 ), float( 1.0 ), vec3( 0.0 ) );
+			// DDFA: seed the see-through aux tint to white (no tint yet). RMW preserves slot-5 xyz (sigmaA).
+			writeFeatureThroughput( rayBufferRW, rayID, vec3( 1.0 ) );
 
 		} );
 
@@ -107,21 +113,26 @@ export function buildGenerateKernel( params ) {
 			// 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 pixelIndex = int( activeIndicesRO.element( tid ) );
-				const gx = pixelIndex.mod( int( resolution.x ) );
-				const gy = pixelIndex.div( int( resolution.x ) );
-				emitRay( gx, gy );
+				// active list holds LOCAL slots; global pixel = pixelBase + local slot.
+				const localSlot = int( activeIndicesRO.element( tid ) );
+				const globalPixel = localSlot.add( chunkRowBase.mul( renderWidth ) );
+				const gx = globalPixel.mod( renderWidth );
+				const gy = globalPixel.div( renderWidth );
+				emitRay( gx, gy, uint( localSlot ) );
 
 			} );
 
 		} else {
 
+			// 2D grid over (renderWidth × chunkRows). local_gy is the band-local row; global gy adds chunkRowBase.
 			const gx = int( workgroupId.x ).mul( WG_SIZE ).add( int( localId.x ) );
-			const gy = int( workgroupId.y ).mul( WG_SIZE ).add( int( localId.y ) );
+			const localGy = int( workgroupId.y ).mul( WG_SIZE ).add( int( localId.y ) );
 
-			If( gx.lessThan( renderWidth ).and( gy.lessThan( renderHeight ) ), () => {
+			If( gx.lessThan( renderWidth ).and( localGy.lessThan( chunkRows ) ), () => {
 
-				emitRay( gx, gy );
+				const gy = localGy.add( chunkRowBase );
+				const localRayID = uint( localGy.mul( renderWidth ).add( gx ) );
+				emitRay( gx, gy, localRayID );
 
 			} );