rayzee 10.0.0 → 11.0.0

package/src/Stages/PathTracer.js

@@ -7,23 +7,28 @@
 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';
 import { buildGenerateKernel, GENERATE_WG_SIZE } from '../TSL/GenerateKernel.js';
 import { buildExtendKernel, EXTEND_WG_SIZE } from '../TSL/ExtendKernel.js';
 import { buildShadeKernel, SHADE_WG_SIZE } from '../TSL/ShadeKernel.js';
+import { buildVisibilityFoldKernel, buildVisibilityClearKernel } from '../TSL/LightVisibility.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 { ENGINE_DEFAULTS } from '../EngineDefaults.js';
+import { MAX_STORAGE_TEXTURE_SIZE } from '../Processor/StorageTexturePool.js';
+import { ISSUE_CODES } from '../EngineIssues.js';
 import { createLogger, fmt } from '../utils/Logger.js';
 import { deviceMemoryGB } from '../Processor/HostMemory.js';
 import {
@@ -33,11 +38,14 @@ 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' ];
+const PICKED_SHADOW_RAYS = [ 'two', 'one' ];
+const SHADOW_RAY_MODES = [ 'all', ...PICKED_SHADOW_RAYS ];
+
+export const BOUNCE_KERNELS = [ 'extend', 'shade', 'connect', 'merge', 'globalHist', 'globalScatter', 'compact', 'compactCopyback', 'lightCopyback' ];
 
 export class PathTracer extends PathTracerStage {
 
@@ -58,6 +66,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
@@ -77,9 +88,10 @@ export class PathTracer extends PathTracerStage {
 		// CPU sizes per-bounce kernels from last frame's survivor curve; kernels bound on ENTERING_COUNT so over-sizing is safe. (indirect dispatch not viable — three.js doesn't sync compute-written indirect buffers across submissions)
 		this._useDynamicDispatch = true;
 
-		// Global material-coherence sort: set per-build from ENGINE_DEFAULTS + material count (>8).
+		// Global material-coherence sort: the wavefrontSortMaterials setting, applied per build above 8 materials.
 		// Reorders entering rays into material-pure workgroups before Shade; runs under dynamic dispatch
 		// (compact reads the unsorted active list, so the survivor set is unchanged). Measured −8% at 1024²/8b.
+		this.sortMaterials = options.sortMaterials ?? ENGINE_DEFAULTS.wavefrontSortMaterials;
 		this._sortMaterials = false;
 
 		// Flag-gated off: perf-neutral vs atomic-append and adds a 'subgroups' feature dependency.
@@ -118,6 +130,7 @@ export class PathTracer extends PathTracerStage {
 		// so when one lands cannot change the image. { due, read, apply } while one is in flight.
 		this._lockstep = false;
 		this._lockstepRead = null;
+		this._accumulationLockstep = false;
 
 		// 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.
@@ -141,6 +154,21 @@ 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;
+		this._shadowRays = 'all';
+		this._compiledPick = null;
+		this._learnsVisibility = false;
+
+		// 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 );
@@ -158,10 +186,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', () => {
 
@@ -235,14 +266,152 @@ 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();
+
+		}
+
+	}
+
+	/**
+	 * Shadow rays a hit for the lamps, sky, sun and emitters: 'all', one per kind; 'two', the strongest and one picked
+	 * from the rest; 'one', one picked, by unshadowed light and where each kind gets through. Rebuilds the kernels
+	 * before the next frame; bidirectional integrators ignore it.
+	 * @param {'all'|'two'|'one'} mode
+	 */
+	setShadowRays( mode ) {
+
+		if ( ! SHADOW_RAY_MODES.includes( mode ) ) {
+
+			log.warn( `shadowRays: unknown mode "${mode}", using 'all'` );
+			mode = 'all';
+
+		}
+
+		if ( this._shadowRays === mode ) return;
+		this._shadowRays = mode;
+		this._outputsChanged = true;
+
+	}
+
+	/**
+	 * The lightPick variant to compile, or null for a ray per light kind: also when the scene has no more kinds than the
+	 * variant traces rays, where it would only add its bookkeeping.
+	 */
+	_pickedShadowRays() {
+
+		if ( this._integrator || ! PICKED_SHADOW_RAYS.includes( this._shadowRays ) ) return null;
+		const environment = this.enableEnvironment.value > 0;
+		const lamps = this.numDirectionalLights.value + this.numAreaLights.value + this.numPointLights.value + this.numSpotLights.value;
+		const kinds = Number( lamps > 0 )
+			+ Number( environment && this.envTotalSum.value > 0 )
+			+ Number( environment && this.hasSun.value > 0 )
+			+ Number( this.enableEmissiveTriangleSampling.value > 0 && this.emissiveTriangleCount.value > 0 );
+		return kinds > ( this._shadowRays === 'two' ? 2 : 1 ) ? this._shadowRays : null;
+
+	}
+
+	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) —
-		// the compiled kernels still bind the old attribute, so rebuild before rendering.
-		if ( this._lightBufferRealloc ) {
+		// 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. 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 ( PICKED_SHADOW_RAYS.includes( this._shadowRays ) && this._pickedShadowRays() !== this._compiledPick ) this._outputsChanged = true;
+
+		if ( this._lightBufferRealloc || this._outputsChanged ) {
 
 			if ( this._kernelManager ) this._kernelManager.dispose();
 			this._wavefrontReady = false;
@@ -291,7 +460,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 );
@@ -320,6 +489,7 @@ export class PathTracer extends PathTracerStage {
 		this.frame.value = frameValue;
 		this.seedFrame.value = this._seedTick ++;
 		this.tracedFrames ++;
+		if ( ! this._lockstep ) this._accumulationLockstep = false;
 
 		this._setWfDispatch();
 
@@ -388,6 +558,15 @@ 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;
+		// A camera move keeps what was learned (it is kept per place in the scene); a repeatable render starts afresh.
+		if ( this._learnsVisibility && frameValue === 0 && ( this._pinSeedToFrame || this._lockstep || ! this.cameraChanged ) ) {
+
+			km.dispatch( 'visibilityClear' );
+
+		}
+
 		// 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 ++ ) {
@@ -490,7 +669,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 ) {
 
@@ -519,10 +700,12 @@ export class PathTracer extends PathTracerStage {
 
 			}
 
+			integrator?.resolve( km );
 			km.dispatch( 'finalWrite' );
 
 		}
 
+		if ( this._learnsVisibility ) km.dispatch( 'visibilityFold' );
 		this._maybeReadbackCounters();
 
 		// Skip the normalDepth/albedo copies when aux is off — the wavefront didn't write them and
@@ -661,6 +844,8 @@ export class PathTracer extends PathTracerStage {
 		this._convergedFraction = state.convergedFraction ?? 0;
 		this._convergedGeometryFraction = state.convergedGeometryFraction ?? 0;
 		this.isComplete = false;
+		// The survivor curve is not in a checkpoint, so a continuation is not the lockstep render.
+		this._accumulationLockstep = false;
 
 	}
 
@@ -711,18 +896,58 @@ export class PathTracer extends PathTracerStage {
 
 	}
 
+	/** Whether the current image was traced in lockstep from a reset made in it; with no sample yet, the setting. */
+	get accumulationLockstep() {
+
+		return this.frameCount > 0 ? this._accumulationLockstep : this._lockstep;
+
+	}
+
 	/**
-	 * 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.
@@ -787,11 +1012,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;
@@ -877,7 +1103,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;
 
 	}
 
@@ -931,12 +1158,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;
 
@@ -960,7 +1188,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 );
 
@@ -993,17 +1221,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 );
 
 			};
@@ -1019,11 +1248,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;
@@ -1137,19 +1368,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;
@@ -1208,6 +1443,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();
@@ -1215,6 +1466,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;
@@ -1231,13 +1484,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 );
 
 		}
 
@@ -1275,6 +1529,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();
@@ -1310,6 +1566,11 @@ export class PathTracer extends PathTracerStage {
 		const prevNormalDepth = this.shaderBuilder.prevNormalDepthTexNode;
 		const writeTex = this.storageTextures.getWriteTextures();
 
+		const picked = this._pickedShadowRays();
+		this._compiledPick = picked;
+		const learnsVisibility = picked !== null;
+		this._learnsVisibility = learnsVisibility;
+		qm.setVisibilityTable( learnsVisibility );
 		const counters = qm.getCounters();
 
 		// Copy ACTIVE_RAY_COUNT into bounceCounts[currentBounce] for the readback survivor curve.
@@ -1393,6 +1654,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',
@@ -1586,13 +1849,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 = {
@@ -1603,8 +1874,7 @@ export class PathTracer extends PathTracerStage {
 		};
 
 		// Material-coherence sort gate (experiment): only worthwhile above a few materials.
-		this._sortMaterials = ( ENGINE_DEFAULTS.wavefrontSortMaterials ?? false )
-			&& ( this.materialData?.materialCount ?? 0 ) > 8;
+		this._sortMaterials = this.sortMaterials && ( this.materialData?.materialCount ?? 0 ) > 8;
 
 		const extFn = buildExtendKernel( {
 			bvhBuffer: freshBvh,
@@ -1669,7 +1939,6 @@ export class PathTracer extends PathTracerStage {
 
 		const shadeFn = buildShadeKernel( {
 			gBufferRW,
-			envCompensationDelta: this.envCompensationDelta,
 			bvhBuffer: freshBvh,
 			triangleBuffer: freshTri,
 			materialBuffer: freshMat,
@@ -1721,7 +1990,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,
@@ -1729,17 +1997,29 @@ 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,
+			shadowRays: picked,
+			cameraWorldMatrix: this.cameraWorldMatrix,
 		} );
 		this._kernelManager.register( 'shade',
-			shadeFn().compute(
+			own( shadeFn() ).compute(
 				[ Math.ceil( maxRays / SHADE_WG_SIZE ), 1, 1 ],
 				[ SHADE_WG_SIZE, 1, 1 ]
 			)
 		);
+		if ( learnsVisibility ) {
+
+			this._kernelManager.register( 'visibilityClear', buildVisibilityClearKernel( { counters } ) );
+			this._kernelManager.register( 'visibilityFold', buildVisibilityFoldKernel( { counters } ) );
+
+		}
 
 		// Subgroup prefix-sum variant when supported.
 		const subgroupsOK = this._useSubgroupCompact
@@ -1801,6 +2081,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,
@@ -1823,6 +2108,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,
@@ -1882,14 +2168,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 );
 
@@ -1898,6 +2186,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,
 		] ) );
 
 	}
@@ -1930,6 +2219,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 );
 
@@ -1947,6 +2237,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;
@@ -1956,6 +2249,8 @@ export class PathTracer extends PathTracerStage {
 		this._frozenMaskAttr = null;
 		this._convDebugSource = null;
 		this._wavefrontReady = false;
+		this._kernelGeneration ++;
+		this._kernelsCompiling = null;
 
 	}