rayzee 9.4.1 → 9.5.0

package/src/Stages/PathTracer.js

@@ -7,7 +7,9 @@
 import { uniform, texture, storage } from 'three/tsl';
 import { gpuOnlyStorageAttribute } from '../TSL/patches.js';
 import { PathTracerStage } from './PathTracerStage.js';
-import { PackedRayBuffer, GBUFFER_STRIDE, RAY_STRIDE, HIT_STRIDE, freeStorageAttribute } from '../Processor/PackedRayBuffer.js';
+import {
+	PackedRayBuffer, GBUFFER_STRIDE, RAY_STRIDE, HIT_STRIDE, freeStorageAttribute,
+} from '../Processor/PackedRayBuffer.js';
 import { QueueManager, COUNTER, ENERGY_SCALE } from '../Processor/QueueManager.js';
 import { VRAMTracker } from '../Processor/VRAMTracker.js';
 import { KernelManager } from '../Processor/KernelManager.js';
@@ -17,13 +19,14 @@ import { buildShadeKernel, SHADE_WG_SIZE } from '../TSL/ShadeKernel.js';
 import { buildCompactKernel, buildCompactSubgroupKernel, COMPACT_WG_SIZE } from '../TSL/CompactKernel.js';
 import { buildFinalWriteKernel, FINALWRITE_WG_SIZE } from '../TSL/FinalWriteKernel.js';
 import { buildDebugKernel, DEBUG_WG_SIZE } from '../TSL/DebugKernel.js';
-import { setMaterialBucketTextures, buildBucketTextureNodes, refreshBucketTextureNodes } from '../TSL/TextureSampling.js';
-import { setShadowAlbedoMaps } from '../TSL/LightsDirect.js';
+import { buildBucketTextureNodes, refreshBucketTextureNodes } from '../TSL/TextureSampling.js';
+import { withSceneResources, MATERIAL_LAYERS } from '../TSL/SceneResources.js';
 import {
 	buildResetGlobalHistKernel, buildGlobalHistKernel, buildGlobalPrefixKernel, buildGlobalScatterKernel,
 	SORT_GLOBAL_WG_SIZE, SORT_GLOBAL_MAX_BINS,
 } from '../TSL/SortGlobalKernels.js';
 import { ENGINE_DEFAULTS, MAX_STORAGE_TEXTURE_SIZE } from '../EngineDefaults.js';
+import { ISSUE_CODES } from '../EngineIssues.js';
 import { createLogger, fmt } from '../utils/Logger.js';
 import { deviceMemoryGB } from '../Processor/HostMemory.js';
 import {
@@ -33,11 +36,11 @@ import {
 const log = createLogger( 'wavefront' );
 
 // Shared by the 1D index-list kernels built inline below.
-const LIST_WG_SIZE = 256;
+export const LIST_WG_SIZE = 256;
 
 // Resized per bounce iteration, each from its own registered workgroup size. Unregistered entries
 // (the sort passes when _sortMaterials is off) are skipped by setDispatchForCount.
-const BOUNCE_KERNELS = [ 'extend', 'shade', 'globalHist', 'globalScatter', 'compact', 'compactCopyback' ];
+export const BOUNCE_KERNELS = [ 'extend', 'shade', 'connect', 'merge', 'globalHist', 'globalScatter', 'compact', 'compactCopyback', 'lightCopyback' ];
 
 export class PathTracer extends PathTracerStage {
 
@@ -58,6 +61,9 @@ export class PathTracer extends PathTracerStage {
 		this._convDebugSource = null; // memoized handle set for the Compositor's convergence overlay
 		this._dilateFrozenUniform = uniform( 1, 'int' ); // 1 = dilate (default); 0 = plain per-pixel freeze
 		this._wavefrontReady = false;
+		// The background compile of the kernels last built (_compileKernels), and its build's number.
+		this._kernelsCompiling = null;
+		this._kernelGeneration = 0;
 
 		// Aux MRT (normalDepth + albedo) feeds only the denoiser/OIDN. When no denoiser is active the
 		// wavefront skips those writes (Generate/Shade G-buffer + FinalWrite stores). Gated by a live
@@ -142,6 +148,18 @@ export class PathTracer extends PathTracerStage {
 		this._chunkRows = 0; // rows per chunk = floor(B / renderWidth), clamped ≥1
 		this._numChunks = 1; // ceil(renderHeight / chunkRows)
 
+		// Outputs a later stage asked for (requestOutput), compiled into Shade only while asked.
+		this._outputs = new Map();
+		this._outputsChanged = false;
+		// The material layers the kernels were compiled with (_layersToCompile).
+		this._compiledLayers = null;
+
+		// Integrators other than the path tracer's own, by name (registerIntegrator); the chosen one's instance, or
+		// null for plain path tracing, which builds exactly the unidirectional kernels.
+		this._integratorFactories = new Map();
+		this._integratorInstances = new Map();
+		this._integrator = null;
+
 		// VRAM accounting — providers are thunks reading CURRENT live resources,
 		// so they survive buffer/texture reallocation (resize, scene/material reload).
 		this.vramTracker = new VRAMTracker( this.renderer );
@@ -159,10 +177,13 @@ export class PathTracer extends PathTracerStage {
 		t.register( 'rays', () => {
 
 			const a = this._packedBuffers?._attrs;
-			return a ? [ a.ray, a.rng, a.hit ] : null;
+			return a ? [ a.ray, a.hit ] : null;
 
 		} );
 
+		// An integrator's own buffers (a light vertex cache rides in the hit buffer, under 'rays')
+		t.register( 'integrator', () => this._integrator?.gpuResources() ?? null );
+
 		// Queue indices + atomic counters
 		t.register( 'queues', () => {
 
@@ -236,14 +257,112 @@ export class PathTracer extends PathTracerStage {
 
 	}
 
+	/**
+	 * Asks for an extra per-pixel output, compiled in only while someone asks for it; the kernels rebuild before the
+	 * next frame. `'gBuffer'`: the denoisers' normal/depth (`pathtracer:normalDepth`) and albedo (`pathtracer:albedo`),
+	 * written while setAuxGBufferEnabled( true ). `'hitDistance'`: the first bounce's segment plus any alpha-skip run,
+	 * at camera depth 1, as `encode( distance, viewZ )` returns it — a [0, 1] value, in `pathtracer:albedo.w`; it
+	 * brings the G-buffer with it.
+	 * @param {'gBuffer'|'hitDistance'} name
+	 * @param {{encode?: function(Node, Node): Node}} [options]
+	 * @returns {function(): void} withdraws the request
+	 */
+	requestOutput( name, options = {} ) {
+
+		this._outputs.set( name, options );
+		this._outputsChanged = true;
+
+		return () => {
+
+			if ( this._outputs.get( name ) !== options ) return;
+			this._outputs.delete( name );
+			this._outputsChanged = true;
+
+		};
+
+	}
+
+	/**
+	 * Makes an integrator choosable by name. `create( pathTracer )` makes its instance, once, which then takes the
+	 * integrator hooks this class calls (see BidirectionalIntegrator); one class may answer several names.
+	 * @param {string|string[]} names
+	 * @param {function(PathTracer): Object} create
+	 */
+	registerIntegrator( names, create ) {
+
+		for ( const name of [ names ].flat() ) this._integratorFactories.set( name, create );
+
+	}
+
+	/**
+	 * Switching rebuilds the kernels: only an integrator's own bind its buffers. 'path' is the path tracer's own;
+	 * the others must have been registered (rayzee/addons/bidirectional: 'bidirectional', 'vcm').
+	 * @param {string} name
+	 */
+	setIntegrator( name ) {
+
+		let next = null;
+		if ( name !== 'path' ) {
+
+			const create = this._integratorFactories.get( name );
+			if ( ! create ) {
+
+				this.issues?.record( ISSUE_CODES.CAPABILITY_MISSING, `integrator "${name}" is not installed: pathTracer.registerIntegrator(), or rayzee/addons/bidirectional`, { capability: name } );
+				return;
+
+			}
+
+			next = this._integratorInstances.get( create );
+			if ( ! next ) this._integratorInstances.set( create, next = create( this ) );
+
+		}
+
+		if ( next === this._integrator && ( ! next || next.name === name ) ) return;
+		if ( this._integrator && this._integrator !== next ) this._integrator.dispose();
+		next?.select( name );
+		this._integrator = next;
+		this._pathBudget = 0;
+
+		if ( this._packedBuffers && this.materialData?.materialCount > 0 ) {
+
+			if ( this._kernelManager ) this._kernelManager.dispose();
+			this._wavefrontReady = false;
+			this._buildWavefrontKernels();
+
+		}
+
+	}
+
+	get integrator() {
+
+		return this._integrator?.name ?? 'path';
+
+	}
+
+	/** The chosen integrator's instance — its controls, e.g. setStrategy() — or null for plain path tracing. */
+	get activeIntegrator() {
+
+		return this._integrator;
+
+	}
+
 	render( context ) {
 
 		// Kernels not built yet (first frame / mid-resize) — skip until ready.
 		if ( ! this.isReady || ! this._wavefrontReady ) return;
 
 		// The packed light buffer was grow-reallocated at runtime (emissive set grew) or a light list grew —
-		// the compiled kernels still bind the old one, so rebuild before rendering.
-		if ( this._lightBufferRealloc ) {
+		// the compiled kernels still bind the old one, so rebuild before rendering. Likewise a changed output request.
+		// A layer some material now uses is compiled in at once; one nothing uses any more waits for the next build.
+		if ( this._materialFeaturesChanged ) {
+
+			this._materialFeaturesChanged = false;
+			const needed = this._layersToCompile();
+			if ( MATERIAL_LAYERS.some( ( layer ) => needed[ layer ] && ! this._compiledLayers?.[ layer ] ) ) this._outputsChanged = true;
+
+		}
+
+		if ( this._lightBufferRealloc || this._outputsChanged ) {
 
 			if ( this._kernelManager ) this._kernelManager.dispose();
 			this._wavefrontReady = false;
@@ -292,7 +411,7 @@ export class PathTracer extends PathTracerStage {
 		}
 
 		this._handleResize();
-		this.manageASVGFForRenderMode( renderMode );
+		this.resetHistoryOnRenderModeChange( renderMode );
 
 		// Full-frame render is always a complete cycle (PER_CYCLE stages gate on this).
 		if ( context ) context.setState( 'tileRenderingComplete', true );
@@ -390,6 +509,9 @@ export class PathTracer extends PathTracerStage {
 				: Math.min( this._lastBounceCountsBudget, this._lastBounceCountsLoopBound ) )
 			: 0;
 
+		// An integrator's light subpaths first, through the same pool; every camera chunk then connects to them.
+		const integrator = this._integrator?.beginFrame( loopBound ) ? this._integrator : null;
+
 		// Blender-style row-band streaming: the fixed-budget path pool processes the image in bands of ≤ chunkRows
 		// rows (one chunk when the frame fits the budget → identical to the pre-chunking path). See spec.
 		for ( let chunkIndex = 0, rowBase = 0; rowBase < frameHeight; rowBase += chunkRows, chunkIndex ++ ) {
@@ -492,7 +614,9 @@ export class PathTracer extends PathTracerStage {
 
 				}
 
+				integrator?.beforeShade();
 				km.dispatch( 'shade' ); // shade thread 0 folds resetActiveCounter (zeroes ACTIVE_RAY_COUNT before compact)
+				integrator?.afterShade( km );
 				km.dispatch( 'compact' );
 				if ( useFunctionalCompaction ) {
 
@@ -521,6 +645,7 @@ export class PathTracer extends PathTracerStage {
 
 			}
 
+			integrator?.resolve( km );
 			km.dispatch( 'finalWrite' );
 
 		}
@@ -723,17 +848,50 @@ export class PathTracer extends PathTracerStage {
 	}
 
 	/**
-	 * While a lockstep readback is due and has not landed, render() traces nothing: await this
-	 * before the next frame. Null otherwise.
+	 * While the kernels compile in the background, or a lockstep readback is due and has not landed, render() traces
+	 * nothing: await this before the next frame. Null otherwise.
 	 * @returns {?Promise<void>}
 	 */
 	readbackWait() {
 
+		if ( this._kernelsCompiling ) return this._kernelsCompiling;
 		const pending = this._lockstepRead;
 		return pending && ! pending.apply && this.frameCount >= pending.due ? pending.read : null;
 
 	}
 
+	/**
+	 * Compiles the kernels just built without blocking the page. Until they are ready render() traces nothing and the
+	 * canvas keeps its last frame; every driver loop awaits readbackWait(), which returns this. A build started
+	 * meanwhile supersedes it. A failed background compile — and every compile in Node — leaves each kernel to compile
+	 * at its first dispatch.
+	 */
+	_compileKernels() {
+
+		const generation = ++ this._kernelGeneration;
+		if ( ! KernelManager.canCompileInBackground ) {
+
+			this._kernelsCompiling = null;
+			this._wavefrontReady = true;
+			return;
+
+		}
+
+		const kernels = this._kernelManager;
+		this.emit( 'pathtracer:compiling', { compiling: true } );
+		this._kernelsCompiling = kernels.compile()
+			.catch( ( error ) => log.warn( `background kernel compile failed — compiling at first dispatch: ${error?.message ?? error}` ) )
+			.then( () => {
+
+				if ( generation !== this._kernelGeneration ) return;
+				this._kernelsCompiling = null;
+				this._wavefrontReady = true;
+				this.emit( 'pathtracer:compiling', { compiling: false } );
+
+			} );
+
+	}
+
 	/**
 	 * Per-pixel convergence state for the Compositor's debug overlay: the buffers FinalWrite maintains
 	 * plus the uniforms needed to re-derive its predicate. Read-only — the overlay never writes back.
@@ -798,11 +956,12 @@ export class PathTracer extends PathTracerStage {
 	}
 
 	// Aux MRT (normalDepth/albedo) is needed only by the denoiser/OIDN; DenoisingManager calls this to
-	// turn the wavefront's aux writes on/off. It's a live uniform, so toggling is just a value flip —
-	// no kernel rebuild, no UI freeze.
+	// turn the wavefront's aux writes on/off. The first call that turns them on compiles them in (requestOutput,
+	// kept for good); after that it is a live uniform, so toggling is a value flip — no kernel rebuild, no UI freeze.
 	setAuxGBufferEnabled( enabled ) {
 
 		enabled = !! enabled;
+		if ( enabled && ! this._outputs.has( 'gBuffer' ) ) this.requestOutput( 'gBuffer' );
 		if ( this._auxGBufferEnabled === enabled ) return;
 		this._auxGBufferEnabled = enabled;
 		this._auxGBufferUniform.value = enabled ? 1 : 0;
@@ -888,7 +1047,8 @@ export class PathTracer extends PathTracerStage {
 
 	_bounceLoopBound() {
 
-		return this.maxBounces.value + this.transmissiveBounces.value + this.maxSubsurfaceSteps.value;
+		// Camera paths take one segment past their last bounce (ShadeKernel, EMISSION_ONLY).
+		return this.maxBounces.value + this.transmissiveBounces.value + this.maxSubsurfaceSteps.value + 1;
 
 	}
 
@@ -942,12 +1102,13 @@ export class PathTracer extends PathTracerStage {
 		const budget = this.maxBounces.value;
 		const measuredLoopBound = this._bounceLoopBound();
 		const n = this._queueManager.MAX_BOUNCE_SNAPSHOTS;
+		const lightKey = this._integrator?.curveKey ?? null;
 		this.renderer.getArrayBufferAsync( attr ).then( ( buf ) => {
 
 			// 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 ) this._applyBounceCounts( buf, budget, measuredLoopBound, n );
+			if ( gen === this._readbackGeneration ) this._applyBounceCounts( buf, budget, measuredLoopBound, n, lightKey );
 
 			this._readbackPending = false;
 
@@ -971,7 +1132,7 @@ export class PathTracer extends PathTracerStage {
 				// Full-FRAME pixel count (CONVERGED_COUNT sums across all chunks) — not _wfMaxRayCount, which
 				// after the chunk loop holds only the last band's pixel count.
 				const total = this._wfRenderWidth.value * this._wfRenderHeight.value;
-				this.renderer.getArrayBufferAsync( cAttr ).then( ( buf ) => {
+				this.renderer.getArrayBufferAsync( cAttr, null, 0, COUNTER.COUNT * 4 ).then( ( buf ) => {
 
 					if ( cgen === this._readbackGeneration && total > 0 ) this._applyCounters( buf, total );
 
@@ -1004,17 +1165,18 @@ export class PathTracer extends PathTracerStage {
 		const loopBound = this._bounceLoopBound();
 		const n = this._queueManager.MAX_BOUNCE_SNAPSHOTS;
 		const total = this._wfRenderWidth.value * this._wfRenderHeight.value;
+		const lightKey = this._integrator?.curveKey ?? null;
 
 		const entry = { due: this.frameCount + this._readbackEveryNFrames, read: null, apply: null };
 		entry.read = Promise.all( [
 			this.renderer.getArrayBufferAsync( bounceAttr ),
-			this.renderer.getArrayBufferAsync( counterAttr ),
+			this.renderer.getArrayBufferAsync( counterAttr, null, 0, COUNTER.COUNT * 4 ),
 		] ).then( ( [ bounceBuf, counterBuf ] ) => {
 
 			entry.apply = () => {
 
 				if ( gen !== this._readbackGeneration ) return;
-				this._applyBounceCounts( bounceBuf, budget, loopBound, n );
+				this._applyBounceCounts( bounceBuf, budget, loopBound, n, lightKey );
 				if ( total > 0 ) this._applyCounters( counterBuf, total );
 
 			};
@@ -1030,11 +1192,13 @@ export class PathTracer extends PathTracerStage {
 
 	}
 
-	_applyBounceCounts( buf, budget, loopBound, n ) {
+	_applyBounceCounts( buf, budget, loopBound, n, lightKey = null ) {
 
 		const all = new Uint32Array( buf.slice( 0 ) );
 		this._lastBounceCounts = all.subarray( 0, n );
 		this._lastBounceEnergy = all.subarray( n, 2 * n );
+		// An integrator's light pass keeps its own curve after the camera's.
+		this._integrator?.applyLightCurve( all.subarray( 2 * n, 3 * n ), all.subarray( 3 * n, 4 * n ), lightKey );
 		this._lastBounceCountsBudget = budget;
 		this._lastBounceCountsLoopBound = loopBound;
 		this._curveSizingValid = true;
@@ -1148,19 +1312,23 @@ export class PathTracer extends PathTracerStage {
 	// any resolution through this pool, so a small B just means more row-bands (works on weak / small-VRAM GPUs).
 	_computePathBudget() {
 
-		if ( this._pathBudgetOverride > 0 ) return this._pathBudgetOverride;
-
 		const RAY_BYTES = RAY_STRIDE * 16;
-		const bytesPerPath = RAY_STRIDE * 16 + HIT_STRIDE * 16 + 4 /* rng */ + GBUFFER_STRIDE * 16
+		const HIT_BYTES = ( this._integrator?.hitStride ?? HIT_STRIDE ) * 16;
+		const bytesPerPath = RAY_BYTES + HIT_BYTES + GBUFFER_STRIDE * 16
 			+ 4 + 4 /* activeIndices A/B */ + 4;
 
 		const limits = this.renderer?.backend?.device?.limits;
 		const maxBinding = limits?.maxStorageBufferBindingSize || ( 128 * 1024 * 1024 );
 		const maxBuffer = limits?.maxBufferSize || maxBinding;
-
-		const bByBinding = Math.floor( ( maxBinding * 0.9 ) / RAY_BYTES );
 		const deviceMemBytes = deviceMemoryGB( this.hostMemoryGB ).gb * 1024 * 1024 * 1024;
-		const poolVramBudget = Math.min( deviceMemBytes * 0.25, maxBuffer * 4 );
+
+		// An integrator's light vertex cache shares the hit buffer's binding with the paths.
+		const cacheBytes = this._integrator?.cacheBytes( maxBinding, deviceMemBytes ) ?? 0;
+
+		if ( this._pathBudgetOverride > 0 ) return this._pathBudgetOverride;
+
+		const bByBinding = Math.floor( Math.min( ( maxBinding * 0.9 ) / RAY_BYTES, ( maxBinding * 0.9 - cacheBytes ) / HIT_BYTES ) );
+		const poolVramBudget = Math.min( deviceMemBytes * 0.25, maxBuffer * 4 ) - cacheBytes;
 		const bByVram = Math.floor( poolVramBudget / bytesPerPath );
 
 		const MIN_B = 512 * 512;
@@ -1219,6 +1387,22 @@ export class PathTracer extends PathTracerStage {
 
 	}
 
+	/** The material layers the scene uses; bidirectional leaves diffuse transmission out (its paths do not cross surfaces). */
+	_layersToCompile() {
+
+		const layers = this.materialData.materialLayers();
+		if ( this._integrator ) layers.diffuseTransmission = false;
+		return layers;
+
+	}
+
+	/** Whether the kernels write the G-buffer: asked for directly, or for the hit distance that rides in it. */
+	get _gBufferCompiled() {
+
+		return this._outputs.has( 'gBuffer' ) || this._outputs.has( 'hitDistance' );
+
+	}
+
 	_buildWavefrontKernels() {
 
 		const texNodes = this.shaderBuilder.getSceneTextureNodes();
@@ -1226,6 +1410,8 @@ export class PathTracer extends PathTracerStage {
 
 		// A fresh build binds the current lightStorageAttr — any pending realloc is covered.
 		this._lightBufferRealloc = false;
+		this._outputsChanged = false;
+		this._integrator?.beforeKernelBuild();
 
 		const w = this.storageTextures.renderWidth;
 		const h = this.storageTextures.renderHeight;
@@ -1242,13 +1428,14 @@ export class PathTracer extends PathTracerStage {
 
 		// Per-path buffers (RAY/HIT/rng) sized to the budget B and indexed by LOCAL slot r ∈ [0,B). _cap = B is
 		// baked into the SoA stride but never changes with resolution, so this build happens once (model load).
+		const lightVertices = this._integrator?.lightVertices ?? 0;
 		if ( ! this._packedBuffers ) {
 
-			this._packedBuffers = new PackedRayBuffer( B, this.renderer );
+			this._packedBuffers = new PackedRayBuffer( B, this.renderer, lightVertices );
 
 		} else {
 
-			this._packedBuffers.resize( B );
+			this._packedBuffers.resize( B, lightVertices );
 
 		}
 
@@ -1286,6 +1473,8 @@ export class PathTracer extends PathTracerStage {
 
 		}
 
+		this._integrator?.allocate( maxPixels );
+
 		const m2RW = storage( this._m2Attr, 'float' );
 		const streakRW = storage( this._streakAttr, 'uint' );
 		const streakRO = storage( this._streakAttr, 'uint' ).toReadOnly();
@@ -1404,6 +1593,8 @@ export class PathTracer extends PathTracerStage {
 			transmissiveBounces: this.transmissiveBounces,
 			transparentBackground: this.transparentBackground,
 			auxGBufferEnabled: this._auxGBufferUniform,
+			gBuffer: this._gBufferCompiled,
+			bidirectional: this._integrator?.uniforms ?? null,
 		};
 		const genFn = buildGenerateKernel( genParams );
 		this._kernelManager.register( 'generate',
@@ -1597,13 +1788,21 @@ export class PathTracer extends PathTracerStage {
 		const _mat = this.materialData;
 		const _env = this.environment;
 		// Consolidated size-bucket nodes (K sRGB + K linear). Empty buckets get placeholders so
-		// every runtime branch references a valid node. Published to the sampling module before
-		// the Shade/Debug graphs are built so they bake in these (per-pipeline) nodes.
+		// every runtime branch references a valid node.
 		const freshSrgbBuckets = buildBucketTextureNodes( _mat.srgbBuckets );
 		const freshLinearBuckets = buildBucketTextureNodes( _mat.linearBuckets );
-		setMaterialBucketTextures( freshSrgbBuckets, freshLinearBuckets );
-		// Alpha-cutout shadow rays sample albedo (sRGB pool) — emitted into the shade graph now.
-		setShadowAlbedoMaps( freshSrgbBuckets );
+		// This renderer's resources, in the build context of each kernel that samples them (SceneResources.js).
+		// Alpha-cutout shadow rays sample albedo (sRGB pool).
+		const resources = {
+			srgbBuckets: freshSrgbBuckets,
+			linearBuckets: freshLinearBuckets,
+			shadowAlbedoMaps: freshSrgbBuckets,
+			goboMaps: texNodes.goboMapsTex,
+			iesProfiles: texNodes.iesProfilesTex,
+			alphaShadows: this.uniforms.get( 'enableAlphaShadows' ),
+			materialLayers: this._compiledLayers = this._layersToCompile(),
+		};
+		const own = ( call ) => withSceneResources( call, resources );
 		const freshEnvTex = _env.environmentTexture ? texture( _env.environmentTexture ) : texNodes.envTex;
 
 		this._wfTexNodes = {
@@ -1680,7 +1879,6 @@ export class PathTracer extends PathTracerStage {
 
 		const shadeFn = buildShadeKernel( {
 			gBufferRW,
-			envCompensationDelta: this.envCompensationDelta,
 			bvhBuffer: freshBvh,
 			triangleBuffer: freshTri,
 			materialBuffer: freshMat,
@@ -1732,7 +1930,6 @@ export class PathTracer extends PathTracerStage {
 			emissiveVec4Offset: this.emissiveVec4Offset,
 			emissiveTotalPower: this.emissiveTotalPower,
 			emissiveBoost: this.emissiveBoost,
-			totalTriangleCount: this.totalTriangleCount,
 			enableEmissiveTriangleSampling: this.enableEmissiveTriangleSampling,
 			lightBVHNodeCount: this.lightBVHNodeCount,
 			reverseMapVec4Offset: this.reverseMapVec4Offset,
@@ -1740,13 +1937,17 @@ export class PathTracer extends PathTracerStage {
 			maxRayCount: this._wfMaxRayCount,
 			chunkRowBase: this._wfChunkRowBase,
 			auxGBufferEnabled: this._auxGBufferUniform,
+			gBuffer: this._gBufferCompiled,
 			hasSun: this.hasSun,
 			sunDirection: this.sunDirection,
 			sunRadiance: this.sunRadiance,
 			sunParams: this.sunParams,
+			bidirectional: this._integrator?.uniforms ?? null,
+			hitDistanceEncode: this._outputs.get( 'hitDistance' )?.encode ?? null,
+			materialLayers: this._compiledLayers,
 		} );
 		this._kernelManager.register( 'shade',
-			shadeFn().compute(
+			own( shadeFn() ).compute(
 				[ Math.ceil( maxRays / SHADE_WG_SIZE ), 1, 1 ],
 				[ SHADE_WG_SIZE, 1, 1 ]
 			)
@@ -1812,6 +2013,11 @@ export class PathTracer extends PathTracerStage {
 			copyFn().compute( [ Math.ceil( maxRays / LIST_WG_SIZE ), 1, 1 ], [ LIST_WG_SIZE, 1, 1 ] )
 		);
 
+		this._integrator?.registerKernels( {
+			km: this._kernelManager, qm, pb, counters, bounceCountsBuf, wfCurrentBounce, copyReadB, copyWriteA, maxRays, w, own,
+			freshLight, freshTri, freshBvh, freshMat, freshEnvTex, freshEnvCDF,
+		} );
+
 		const fwFn = buildFinalWriteKernel( {
 			rayBufferRO: pb.rayBuffer.ro,
 			gBufferRO,
@@ -1834,6 +2040,7 @@ export class PathTracer extends PathTracerStage {
 			renderHeight: this._wfRenderHeight,
 			visMode: this.visMode,
 			auxGBufferEnabled: this._auxGBufferUniform,
+			gBuffer: this._gBufferCompiled,
 			cleanAuxNormalEnabled: this._cleanAuxNormalUniform,
 			m2BufferRW: m2RW,
 			useAdaptiveSampling: this.useAdaptiveSampling,
@@ -1893,14 +2100,16 @@ export class PathTracer extends PathTracerStage {
 			debugVisScale: this.debugVisScale,
 			frame: this.frame,
 		} );
+		// Only the debug views dispatch it, so it compiles when one is first chosen.
 		this._kernelManager.register( 'debug',
-			debugFn().compute(
+			own( debugFn() ).compute(
 				[ Math.ceil( w / DEBUG_WG_SIZE ), Math.ceil( h / DEBUG_WG_SIZE ), 1 ],
 				[ DEBUG_WG_SIZE, DEBUG_WG_SIZE, 1 ]
-			)
+			),
+			{ eager: false },
 		);
 
-		this._wavefrontReady = true;
+		this._compileKernels();
 
 		const bufferBytes = ( this._packedBuffers?.totalBytes ?? 0 ) + ( this._queueManager?.totalBytes ?? 0 );
 
@@ -1909,6 +2118,7 @@ export class PathTracer extends PathTracerStage {
 			`${fmt.mb( bufferBytes )} wavefront buffers`,
 			`budget ${fmt.n( B )} paths`,
 			this._numChunks > 1 ? `${this._numChunks} chunks of ≤${this._chunkRows} rows` : null,
+			this._integrator?.describe() ?? null,
 		] ) );
 
 	}
@@ -1941,6 +2151,7 @@ export class PathTracer extends PathTracerStage {
 		const km = this._kernelManager;
 		km.setDispatchForGrid( 'generate', w, rows );
 		km.setDispatchForGrid( 'finalWrite', w, rows );
+		km.setDispatchForGrid( 'splatResolve', w, rows );
 		km.setDispatchForCount( 'initActiveIndices', chunkPixels );
 		km.setDispatchForCount( 'buildActivePixels', chunkPixels );
 
@@ -1958,6 +2169,9 @@ export class PathTracer extends PathTracerStage {
 		this._m2Attr?.dispose?.();
 		this._streakAttr?.dispose?.();
 		this._frozenMaskAttr?.dispose?.();
+		for ( const integrator of this._integratorInstances.values() ) integrator.dispose();
+		this._integratorInstances.clear();
+		this._integrator = null;
 		this._packedBuffers = null;
 		this._queueManager = null;
 		this._kernelManager = null;
@@ -1967,6 +2181,8 @@ export class PathTracer extends PathTracerStage {
 		this._frozenMaskAttr = null;
 		this._convDebugSource = null;
 		this._wavefrontReady = false;
+		this._kernelGeneration ++;
+		this._kernelsCompiling = null;
 
 	}
 

package/src/Stages/PathTracerStage.js

@@ -53,8 +53,7 @@ const BVH_VEC4_PER_NODE = 4;
  * Events emitted:
  * - pathtracer:frameComplete - When a frame finishes rendering
  * - camera:moved - When camera position/orientation changes
- * - asvgf:reset - Request ASVGF to reset temporal data
- * - asvgf:updateParameters - Update ASVGF parameters
+ * - pipeline:historyReset - temporal history from before is not comparable (render mode change)
  *
  * Textures published to context:
  * - pathtracer:color - Main color output
@@ -113,6 +112,13 @@ export class PathTracerStage extends RenderStage {
 		// Initialize material data manager
 		this.materialData = new MaterialDataManager( this.sdfs );
 		this.materialData.callbacks.onReset = () => this.reset();
+		// A material edit can switch the diffuse transmission lobe on or off, which the shade kernel compiles in.
+		this.materialData.callbacks.onMaterialFeaturesChanged = () => {
+
+			this._materialFeaturesChanged = true;
+
+		};
+
 		// Material edits patch the per-triangle flags lane in the CPU records (`_triangleRecords`
 		// when chunked, `_triangleFlat` otherwise — not sdfs.triangleData, which the PathTracerApp
 		// build path never fills). The flags live in the shade rows, so only those go up again.
@@ -375,16 +381,6 @@ export class PathTracerStage extends RenderStage {
 
 		} );
 
-		this.on( 'pathtracer:setCompletionThreshold', ( data ) => {
-
-			if ( data && data.threshold !== undefined ) {
-
-				this.completionThreshold = data.threshold;
-
-			}
-
-		} );
-
 	}
 
 	// ===== PUBLIC API METHODS =====
@@ -542,7 +538,7 @@ export class PathTracerStage extends RenderStage {
 		this.performanceMonitor?.reset();
 
 		// lastRenderMode is deliberately NOT invalidated here — clearing it made
-		// manageASVGFForRenderMode see a phantom mode change 50 ms after every reset, wiping
+		// resetHistoryOnRenderModeChange see a phantom mode change 50 ms after every reset, wiping
 		// ASVGF's history. A real mode change is still caught by the renderMode comparison.
 		this.lastInteractionModeState = false;
 
@@ -1420,7 +1416,7 @@ export class PathTracerStage extends RenderStage {
 
 	// ===== ASVGF DENOISING MANAGEMENT =====
 
-	manageASVGFForRenderMode( renderMode ) {
+	resetHistoryOnRenderModeChange( renderMode ) {
 
 		if ( renderMode !== this.lastRenderMode ) {
 
@@ -1440,8 +1436,7 @@ export class PathTracerStage extends RenderStage {
 					// History from the previous mode is not comparable. temporalAlpha is NOT
 					// touched here — it is owned by ASVGF_QUALITY_PRESETS, and overwriting it
 					// with a hardcoded value meant `medium` and `high` never took effect.
-					this.emit( 'asvgf:reset' );
-					this.emit( 'denoiser:reset' );
+					this.emit( 'pipeline:historyReset' );
 
 				}
 

package/src/Storage/BLASCache.js

@@ -4,7 +4,7 @@
  * stored BLAS is only ever used for exactly the triangles it was built over.
  */
 
-import { ENGINE_AREAS } from './StorageManager.js';
+import { ENGINE_AREAS } from './areas.js';
 
 export const BLAS_CACHE_FORMAT = 2;