rayzee 10.0.0 → 11.0.0

package/src/TSL/LightGenerateKernel.js

@@ -0,0 +1,293 @@
+/**
+ * LightGenerateKernel.js — starts the bidirectional light subpaths, one per pool slot, on a source picked from
+ * the source table: an emissive triangle, the physical sky's sun, the environment, or a lamp. Throughput is kept at a max channel
+ * of 1, for Russian roulette; its scale rides with the emission data.
+ */
+
+import {
+	Fn, float, vec3, vec4, int, uint, If, instanceIndex, atomicStore, normalize, cross, dot, max, select, Return,
+	sqrt, cos, sin, Loop, sampler, bool as tslBool,
+} from 'three/tsl';
+
+import { getRandomSample1D, getRandomSample2D, getDecorrelatedSeed, pcgHash } from './Random.js';
+import { sampleTriangle, fetchTriangleData, binarySearchCDF, TriangleData } from './EmissiveSampling.js';
+import { cosineWeightedSample } from './MaterialSampling.js';
+import { offsetRayOrigin, triangleRow } from './Common.js';
+import { triangleSide } from './BVHTraversal.js';
+import { sampleSunDisc, sunRadianceToward } from './Sun.js';
+import { sampleEnvironment, sampleEnvironmentExact } from './Environment.js';
+import {
+	DirectionalLight, AreaLight, PointLight, SpotLight, getDirectionalLight, getAreaLight, getPointLight, getSpotLight,
+	getSpotAttenuation, sampleSpotGoboMask, sampleIESProfile, sampleCone, LIGHT_TYPE_DIRECTIONAL, LIGHT_TYPE_AREA, LIGHT_TYPE_POINT,
+} from './LightsCore.js';
+import { areaLightRadiance, areaLightSpreadAttenuation } from './LightsSampling.js';
+import { spotConeSolidAngle, directionalConeSolidAngle } from './BidirectionalLamps.js';
+import {
+	lightPathPixel, mis, sunEmissionPdf, sourcePick, sourceLampType, sourceLampIndex, SOURCE, DIM_EMIT,
+} from './Bidirectional.js';
+import { sampleGuidedDisc, guidedDiscPdf } from './LightGuide.js';
+import { RAY_FLAG, COUNTER } from '../Processor/QueueManager.js';
+import {
+	writeRayOriginMeta, writeRayDirFlags, writeRayThroughputPdf, writeRayRadiance, writeMediumStack,
+	writeRngMis, writeLightOrigin,
+} from '../Processor/PackedRayBuffer.js';
+
+const WG_SIZE = 256;
+
+export function buildLightGenerateKernel( params ) {
+
+	const {
+		rayBufferRW, hitBufferRW, activeIndicesRW, counters,
+		lightBuffer, triangleBuffer, bvhBuffer,
+		emissiveTriangleCount, emissiveVec4Offset, emissiveTotalPower, emissiveBoost,
+		sunDirection, sunRadiance, sunParams, environmentIntensity,
+		envTexture, envCDFTexture, envMatrix, envResolution,
+		directionalLightsBuffer, areaLightsBuffer, pointLightsBuffer, spotLightsBuffer,
+		bidirectional, resolution, frame, transmissiveBounces,
+	} = params;
+	const { lightPaths } = bidirectional;
+
+	return Fn( () => {
+
+		const tid = instanceIndex;
+
+		If( tid.equal( uint( 0 ) ), () => {
+
+			atomicStore( counters.element( uint( COUNTER.ACTIVE_RAY_COUNT ) ), lightPaths );
+			atomicStore( counters.element( uint( COUNTER.ENTERING_COUNT ) ), lightPaths );
+
+		} );
+
+		If( tid.greaterThanEqual( lightPaths ), () => {
+
+			Return();
+
+		} );
+
+		activeIndicesRW.element( tid ).assign( tid );
+
+		const pixel = lightPathPixel( tid, resolution ).toVar();
+		const rng = pcgHash( { state: getDecorrelatedSeed( { pixelCoord: pixel, rayIndex: int( 3 ), frame } ) } ).toVar();
+
+		const origin = vec3( 0.0 ).toVar();
+		const direction = vec3( 0.0, 1.0, 0.0 ).toVar();
+		const throughput = vec3( 0.0 ).toVar();
+		const dVCM = float( 0.0 ).toVar();
+		const dVC = float( 0.0 ).toVar();
+		const triangle = int( - 1 ).toVar();
+		const instanceLeaf = int( 0 ).toVar();
+		const startCos = float( 1.0 ).toVar();
+		const valid = tslBool( false ).toVar();
+
+		const xiSource = getRandomSample1D( pixel, int( 0 ), int( DIM_EMIT + 4 ), rng, resolution, frame ).toVar();
+		const source = int( 0 ).toVar();
+		const hi = int( bidirectional.sourceCount - 1 ).toVar();
+		Loop( source.lessThan( hi ), () => {
+
+			const mid = source.add( hi ).div( 2 ).toVar();
+			If( bidirectional.sourceCdf.element( mid ).lessThanEqual( xiSource ), () => {
+
+				source.assign( mid.add( 1 ) );
+
+			} ).Else( () => {
+
+				hi.assign( mid );
+
+			} );
+
+		} );
+
+		// From the scene's bounding disc facing `toLight`, for a light at infinity, where the guide learned light gets in;
+		// returns the start and its area density.
+		const guide = bidirectional.guideTexture;
+		const discOrigin = ( toLight ) => {
+
+			const start = sampleGuidedDisc( bidirectional, guide, toLight,
+				getRandomSample1D( pixel, int( 0 ), int( DIM_EMIT + 7 ), rng, resolution, frame ),
+				getRandomSample2D( pixel, int( 0 ), int( DIM_EMIT + 6 ), rng, resolution, frame ) ).toVar();
+			return { start, pdf: guidedDiscPdf( bidirectional, guide, toLight, start ) };
+
+		};
+
+		If( source.equal( int( SOURCE.SUN ) ), () => {
+
+			const toSun = sampleSunDisc( sunDirection, sunParams, getRandomSample2D( pixel, int( 0 ), int( DIM_EMIT + 5 ), rng, resolution, frame ) ).toVar();
+			const radiance = sunRadianceToward( toSun, sunDirection, sunRadiance, sunParams ).mul( environmentIntensity ).toVar();
+			const disc = discOrigin( toSun );
+			const emissionPdf = sunEmissionPdf( bidirectional, sunParams, disc.pdf ).toVar();
+
+			If( radiance.x.add( radiance.y ).add( radiance.z ).greaterThan( 0.0 ).and( emissionPdf.greaterThan( 0.0 ) ), () => {
+
+				origin.assign( disc.start );
+				direction.assign( toSun.negate() );
+				throughput.assign( radiance.div( emissionPdf ) );
+				// NEE draws this direction at 1 / solid angle, from any point; the distance is undone at the first hit.
+				dVCM.assign( mis( float( 1.0 ).div( sunParams.y.mul( emissionPdf ) ) ) );
+				dVC.assign( mis( float( 1.0 ).div( emissionPdf ) ) );
+				valid.assign( true );
+
+			} );
+
+		} ).ElseIf( source.equal( int( SOURCE.EMITTERS ) ), () => {
+
+			const pick = binarySearchCDF( lightBuffer, emissiveVec4Offset, emissiveTriangleCount,
+				getRandomSample1D( pixel, int( 0 ), int( DIM_EMIT ), rng, resolution, frame ) ).toVar();
+			const base = emissiveVec4Offset.add( pick.mul( int( 2 ) ) );
+			const entry = lightBuffer.element( base ).toVar(); // triangle, power, cdf, instance leaf
+			const emission = lightBuffer.element( base.add( int( 1 ) ) ).toVar(); // rgb, area
+			triangle.assign( int( entry.x ) );
+			instanceLeaf.assign( int( entry.w ) );
+
+			const tri = TriangleData.wrap( fetchTriangleData( triangle, triangleBuffer, bvhBuffer, instanceLeaf ) ).toVar();
+			const point = sampleTriangle( tri.v0, tri.v1, tri.v2, getRandomSample2D( pixel, int( 0 ), int( DIM_EMIT + 1 ), rng, resolution, frame ) ).toVar();
+			const windingN = normalize( cross( tri.v1.sub( tri.v0 ), tri.v2.sub( tri.v0 ) ) ).toVar();
+
+			const side = triangleSide( triangleRow( triangleBuffer, triangle, 4 ).z ).toVar();
+			const back = side.equal( int( 1 ) ).or( side.equal( int( 2 ) )
+				.and( getRandomSample1D( pixel, int( 0 ), int( DIM_EMIT + 3 ), rng, resolution, frame ).lessThan( 0.5 ) ) ).toVar();
+			const n = select( back, windingN.negate(), windingN ).toVar();
+			direction.assign( cosineWeightedSample( n, getRandomSample2D( pixel, int( 0 ), int( DIM_EMIT + 2 ), rng, resolution, frame ) ) );
+			const cosLight = dot( direction, n ).toVar();
+
+			const areaPdf = max( entry.y, 0.0 ).div( max( emissiveTotalPower, 1e-10 ) ).div( max( emission.w, 1e-20 ) ).mul(
+				select( side.equal( int( 2 ) ), float( 0.5 ), float( 1.0 ) ) ).mul( bidirectional.emitterPick ).toVar();
+			const emissionPdf = areaPdf.mul( cosLight ).div( Math.PI ).toVar();
+
+			If( cosLight.greaterThan( 1e-6 ).and( emissionPdf.greaterThan( 0.0 ) ), () => {
+
+				origin.assign( offsetRayOrigin( point, n ) );
+				// Le·cos / (pdfA·pdfW) = Le·π / pdfA.
+				throughput.assign( emission.xyz.mul( emissiveBoost ).mul( Math.PI ).div( areaPdf ) );
+				// NEE's density for this point depends on the first hit; Shade multiplies it into dVCM there.
+				dVCM.assign( mis( float( 1.0 ).div( emissionPdf ) ) );
+				dVC.assign( mis( cosLight.div( emissionPdf ) ) );
+				startCos.assign( cosLight );
+				valid.assign( true );
+
+			} );
+
+		} ).ElseIf( source.equal( int( SOURCE.ENVIRONMENT ) ), () => {
+
+			const drawn = sampleEnvironmentExact( envCDFTexture, envMatrix, envResolution,
+				getRandomSample2D( pixel, int( 0 ), int( DIM_EMIT + 5 ), rng, resolution, frame ) );
+			const toEnvironment = drawn.direction.toVar();
+			const directionPdf = drawn.pdf.toVar();
+			const radiance = sampleEnvironment( {
+				tex: envTexture, samp: sampler( envTexture ), direction: toEnvironment, environmentMatrix: envMatrix, environmentIntensity, enableEnvironmentLight: float( 1.0 ),
+			} ).xyz.toVar();
+			const disc = discOrigin( toEnvironment );
+			const emissionPdf = bidirectional.envPick.mul( directionPdf ).mul( disc.pdf ).toVar();
+
+			If( radiance.x.add( radiance.y ).add( radiance.z ).greaterThan( 0.0 ).and( emissionPdf.greaterThan( 0.0 ) ), () => {
+
+				origin.assign( disc.start );
+				direction.assign( toEnvironment.negate() );
+				throughput.assign( radiance.div( emissionPdf ) );
+				// NEE draws the direction from the same table, from any point.
+				dVCM.assign( mis( directionPdf.div( emissionPdf ) ) );
+				dVC.assign( mis( float( 1.0 ).div( emissionPdf ) ) );
+				triangle.assign( int( - 1 - SOURCE.ENVIRONMENT ) );
+				valid.assign( true );
+
+			} );
+
+		} ).ElseIf( source.greaterThanEqual( int( SOURCE.LAMPS ) ), () => {
+
+			// NEE's density depends on where the light lands; Shade multiplies it into dVCM there.
+			const pick = sourcePick( bidirectional, source ).toVar();
+			const type = sourceLampType( bidirectional, source ).toVar();
+			const index = sourceLampIndex( bidirectional, source, type ).toVar();
+			triangle.assign( int( - 1 ).sub( source ) );
+			const emissionPdf = float( 0.0 ).toVar();
+			const radiance = vec3( 0.0 ).toVar();
+			const xi = getRandomSample2D( pixel, int( 0 ), int( DIM_EMIT + 2 ), rng, resolution, frame ).toVar();
+
+			If( type.equal( int( LIGHT_TYPE_DIRECTIONAL ) ), () => {
+
+				const light = DirectionalLight.wrap( getDirectionalLight( directionalLightsBuffer, index ) );
+				const toLight = normalize( light.direction ).toVar();
+				radiance.assign( light.color.mul( light.intensity ) );
+				emissionPdf.assign( pick );
+				If( light.angle.greaterThan( 0.0 ), () => {
+
+					const solidAngle = directionalConeSolidAngle( light ).toVar();
+					toLight.assign( sampleCone( toLight, light.angle.mul( 0.5 ), getRandomSample2D( pixel, int( 0 ), int( DIM_EMIT + 5 ), rng, resolution, frame ) ) );
+					radiance.divAssign( solidAngle );
+					emissionPdf.divAssign( solidAngle );
+
+				} );
+				const disc = discOrigin( toLight );
+				emissionPdf.mulAssign( disc.pdf );
+				origin.assign( disc.start );
+				direction.assign( toLight.negate() );
+
+			} ).ElseIf( type.equal( int( LIGHT_TYPE_AREA ) ), () => {
+
+				const light = AreaLight.wrap( getAreaLight( areaLightsBuffer, index ) );
+				const disk = light.shape.greaterThan( 0.5 );
+				const p = getRandomSample2D( pixel, int( 0 ), int( DIM_EMIT + 1 ), rng, resolution, frame ).toVar();
+				const r = sqrt( p.x );
+				const phi = p.y.mul( 2 * Math.PI );
+				origin.assign( light.position.add( light.u.mul( select( disk, r.mul( cos( phi ) ), p.x.mul( 2.0 ).sub( 1.0 ) ) ) )
+					.add( light.v.mul( select( disk, r.mul( sin( phi ) ), p.y.mul( 2.0 ).sub( 1.0 ) ) ) ) );
+				direction.assign( cosineWeightedSample( light.normal, xi ) );
+				const cosLight = dot( direction, light.normal ).toVar();
+				radiance.assign( select( light.area.greaterThan( 0.0 ).and( cosLight.greaterThan( 1e-6 ) ),
+					areaLightRadiance( light ).mul( areaLightSpreadAttenuation( cosLight, light.spread ) ).mul( cosLight ), vec3( 0.0 ) ) );
+				emissionPdf.assign( pick.div( max( light.area, 1e-20 ) ).mul( cosLight ).div( Math.PI ) );
+				dVC.assign( mis( cosLight.div( max( emissionPdf, 1e-30 ) ) ) );
+
+			} ).ElseIf( type.equal( int( LIGHT_TYPE_POINT ) ), () => {
+
+				const light = PointLight.wrap( getPointLight( pointLightsBuffer, index ) );
+				origin.assign( light.position );
+				direction.assign( sampleCone( vec3( 0.0, 1.0, 0.0 ), float( Math.PI ), xi ) );
+				radiance.assign( light.color.mul( light.intensity ) );
+				emissionPdf.assign( pick.div( 4 * Math.PI ) );
+
+			} ).Else( () => {
+
+				const light = SpotLight.wrap( getSpotLight( spotLightsBuffer, index ) );
+				origin.assign( light.position );
+				direction.assign( sampleCone( light.direction, light.angle, xi ) );
+				const toLight = direction.negate();
+				radiance.assign( light.color.mul( light.intensity )
+					.mul( getSpotAttenuation( { coneCosine: cos( light.angle ), blend: light.penumbra, angleCosine: dot( direction, light.direction ) } ) )
+					.mul( sampleSpotGoboMask( light, toLight ) ).mul( sampleIESProfile( light, toLight ) ) );
+				emissionPdf.assign( pick.div( spotConeSolidAngle( light ) ) );
+
+			} );
+
+			If( radiance.x.add( radiance.y ).add( radiance.z ).greaterThan( 0.0 ).and( emissionPdf.greaterThan( 0.0 ) ), () => {
+
+				throughput.assign( radiance.div( emissionPdf ) );
+				dVCM.assign( mis( float( 1.0 ).div( emissionPdf ) ) );
+				valid.assign( true );
+
+			} );
+
+		} );
+
+		If( valid.not(), () => {
+
+			writeRayDirFlags( rayBufferRW, tid, direction, uint( 0 ) );
+			Return();
+
+		} );
+
+		const scale = max( max( max( throughput.x, throughput.y ), throughput.z ), 1e-20 ).toVar();
+
+		writeRayOriginMeta( rayBufferRW, tid, origin, int( 0 ), int( 0 ) );
+		writeRayDirFlags( rayBufferRW, tid, direction,
+			uint( RAY_FLAG.ACTIVE | RAY_FLAG.REDIRECTED | RAY_FLAG.LIGHT_PATH | RAY_FLAG.LIGHT_EMITTED ) );
+		writeRayThroughputPdf( rayBufferRW, tid, throughput.div( scale ), float( 0.0 ) );
+		writeRayRadiance( rayBufferRW, tid, vec4( vec3( 0.0 ), float( 1.0 ) ) );
+		writeMediumStack( rayBufferRW, tid, uint( 0 ), uint( transmissiveBounces ), float( 1.0 ), float( 1.0 ), float( 1.0 ) );
+		writeRngMis( hitBufferRW, tid, rng, dVCM, dVC );
+		writeLightOrigin( hitBufferRW, tid, triangle, instanceLeaf, startCos, scale );
+
+	} );
+
+}
+
+export { WG_SIZE as LIGHT_GENERATE_WG_SIZE };

package/src/TSL/LightGuide.js

@@ -0,0 +1,198 @@
+/**
+ * Where light from infinity gets into the scene, learned from camera paths. A camera path escaping at p in
+ * direction ω is where a light path along −ω would have done some good — through a window, past a door — so each
+ * escape counts one at p's place on the scene's bounding disc facing ω, per coarse direction. Lights at infinity
+ * (the sky, the sun, directional lamps) start their light paths from those counts, a share still drawn uniformly
+ * over the disc; every weight reads the same table, so the estimate stays unbiased whatever was learned.
+ *
+ * The counts sit in the counter buffer past COUNTER.GUIDE (Shade has no binding to spare); a kernel folds them
+ * into running sums every so often, which PathTracer copies into the guide texture: GUIDE_BINS rows of
+ * GUIDE_CELLS running sums ending at 1, then the row's count of escapes (0 = nothing learned: uniform).
+ */
+
+import {
+	Fn, float, int, uint, vec2, vec3, ivec2, If, Loop, Return, instanceIndex, abs, floor, max, mix, select, normalize, cross,
+	dot, sqrt, cos, sin, atomicAdd, atomicLoad, atomicStore,
+} from 'three/tsl';
+
+import { COUNTER, GUIDE_COUNTER_WORDS } from '../Processor/QueueManager.js';
+
+export const GUIDE_BIN_SIDE = 4;
+export const GUIDE_BINS = GUIDE_BIN_SIDE * GUIDE_BIN_SIDE;
+export const GUIDE_CELL_SIDE = 64;
+export const GUIDE_CELLS = GUIDE_CELL_SIDE * GUIDE_CELL_SIDE;
+export const GUIDE_TEXTURE_WIDTH = GUIDE_CELLS + 1;
+if ( GUIDE_BINS * GUIDE_CELLS !== GUIDE_COUNTER_WORDS ) throw new Error( 'LightGuide: the counter buffer is sized for another guide' );
+/** Floats per row of the build buffer: the texture's row, padded to the 256 bytes a buffer→texture copy needs. */
+export const GUIDE_ROW_STRIDE = Math.ceil( GUIDE_TEXTURE_WIDTH * 4 / 256 ) * 64;
+/** Share of light paths still drawn uniformly over the disc, so no start is ever ruled out. */
+export const GUIDE_UNIFORM_SHARE = 0.2;
+
+// The disc facing `toLight`: its plane's axes, as the light path's start is built on them.
+const discFrame = ( toLight ) => {
+
+	const u = normalize( cross( select( abs( toLight.x ).greaterThan( 0.9 ), vec3( 0, 1, 0 ), vec3( 1, 0, 0 ) ), toLight ) ).toVar();
+	return { u, v: cross( toLight, u ).toVar() };
+
+};
+
+// Coarse direction: an octahedral GUIDE_BIN_SIDE² grid.
+const guideBin = ( dir ) => {
+
+	const d = dir.div( max( abs( dir.x ).add( abs( dir.y ) ).add( abs( dir.z ) ), 1e-20 ) ).toVar();
+	const p = vec2( d.x, d.z ).toVar();
+	If( d.y.lessThan( 0.0 ), () => {
+
+		p.assign( vec2(
+			float( 1.0 ).sub( abs( d.z ) ).mul( select( d.x.greaterThanEqual( 0.0 ), 1.0, - 1.0 ) ),
+			float( 1.0 ).sub( abs( d.x ) ).mul( select( d.z.greaterThanEqual( 0.0 ), 1.0, - 1.0 ) ),
+		) );
+
+	} );
+	const q = floor( p.mul( 0.5 ).add( 0.5 ).mul( GUIDE_BIN_SIDE ) ).clamp( 0.0, GUIDE_BIN_SIDE - 1 );
+	return int( q.y ).mul( GUIDE_BIN_SIDE ).add( int( q.x ) );
+
+};
+
+// p's place on the disc facing `toLight`, in units of its radius: where the light path through p along −toLight starts.
+const discCoords = ( bdpt, toLight, p ) => {
+
+	const { u, v } = discFrame( toLight );
+	const rel = p.sub( bdpt.sceneCenter );
+	return vec2( dot( rel, u ), dot( rel, v ) ).div( bdpt.sceneRadius );
+
+};
+
+// The guide's cell at disc coordinates `st`, or −1 outside the square it covers.
+const guideCell = ( st ) => {
+
+	const g = st.mul( 0.5 ).add( 0.5 ).mul( GUIDE_CELL_SIDE ).toVar();
+	const inside = g.x.greaterThanEqual( 0.0 ).and( g.y.greaterThanEqual( 0.0 ) ).and( g.x.lessThan( GUIDE_CELL_SIDE ) ).and( g.y.lessThan( GUIDE_CELL_SIDE ) );
+	return select( inside, int( g.y ).mul( GUIDE_CELL_SIDE ).add( int( g.x ) ), int( - 1 ) );
+
+};
+
+const learned = ( bdpt, guide, bin ) => bdpt.guide.greaterThan( uint( 0 ) ).and( guide.load( ivec2( int( GUIDE_CELLS ), bin ) ).x.greaterThan( 0.0 ) );
+
+/**
+ * Area density, over the disc facing `toLight`, of the light path whose start projects to `p` along −toLight —
+ * what `sceneDiscPdf` was before the guide.
+ */
+export const guidedDiscPdf = ( bdpt, guide, toLight, p ) => {
+
+	const st = discCoords( bdpt, toLight, p ).toVar();
+	const radius2 = bdpt.sceneRadius.mul( bdpt.sceneRadius ).toVar();
+	const uniformPdf = select( dot( st, st ).lessThanEqual( 1.0 ), float( 1.0 ).div( max( radius2.mul( Math.PI ), 1e-30 ) ), float( 0.0 ) ).toVar();
+	const bin = guideBin( toLight ).toVar();
+	const cell = guideCell( st ).toVar();
+	const at = ( c ) => guide.load( ivec2( max( c, int( 0 ) ), bin ) ).x;
+	const share = select( cell.greaterThanEqual( int( 0 ) ), at( cell ).sub( select( cell.greaterThan( int( 0 ) ), at( cell.sub( int( 1 ) ) ), float( 0.0 ) ) ), float( 0.0 ) );
+	// A cell is ( 2R / GUIDE_CELL_SIDE )².
+	const cellPdf = share.mul( GUIDE_CELLS / 4 ).div( max( radius2, 1e-30 ) );
+	return select( learned( bdpt, guide, bin ), mix( cellPdf, uniformPdf, GUIDE_UNIFORM_SHARE ), uniformPdf );
+
+};
+
+/**
+ * A light path's start on the disc facing `toLight`: from a learned cell with chance 1 − GUIDE_UNIFORM_SHARE
+ * (`choice` < that, rescaled into the cell pick), else uniformly over the disc. `xi` places it within either.
+ */
+export const sampleGuidedDisc = ( bdpt, guide, toLight, choice, xi ) => {
+
+	const { u, v } = discFrame( toLight );
+	const st = vec2( 0.0 ).toVar();
+	const bin = guideBin( toLight ).toVar();
+	If( learned( bdpt, guide, bin ).and( choice.lessThan( 1 - GUIDE_UNIFORM_SHARE ) ), () => {
+
+		const target = choice.div( 1 - GUIDE_UNIFORM_SHARE ).toVar();
+		const lo = int( 0 ).toVar();
+		const hi = int( GUIDE_CELLS - 1 ).toVar();
+		Loop( lo.lessThan( hi ), () => {
+
+			const mid = lo.add( hi ).div( 2 ).toVar();
+			If( guide.load( ivec2( mid, bin ) ).x.lessThanEqual( target ), () => {
+
+				lo.assign( mid.add( 1 ) );
+
+			} ).Else( () => {
+
+				hi.assign( mid );
+
+			} );
+
+		} );
+		const cell = vec2( float( lo.mod( int( GUIDE_CELL_SIDE ) ) ), float( lo.div( int( GUIDE_CELL_SIDE ) ) ) );
+		st.assign( cell.add( xi ).div( GUIDE_CELL_SIDE ).mul( 2.0 ).sub( 1.0 ) );
+
+	} ).Else( () => {
+
+		const r = sqrt( xi.x );
+		const phi = xi.y.mul( 2 * Math.PI );
+		st.assign( vec2( r.mul( cos( phi ) ), r.mul( sin( phi ) ) ) );
+
+	} );
+	return bdpt.sceneCenter.add( toLight.mul( bdpt.sceneRadius ) ).add( u.mul( st.x ).add( v.mul( st.y ) ).mul( bdpt.sceneRadius ) );
+
+};
+
+/** A camera path escaping at `p` toward `toLight`: one count for light paths that would have reached p. */
+export const recordEscape = ( counters, bdpt, toLight, p ) => {
+
+	const cell = guideCell( discCoords( bdpt, toLight, p ) ).toVar();
+	If( bdpt.guideLearning.greaterThan( uint( 0 ) ).and( cell.greaterThanEqual( int( 0 ) ) ), () => {
+
+		atomicAdd( counters.element( uint( COUNTER.GUIDE ).add( uint( guideBin( toLight ).mul( int( GUIDE_CELLS ) ).add( cell ) ) ) ), uint( 1 ) );
+
+	} );
+
+};
+
+/** Folds the counts into the build buffer's rows (GUIDE_ROW_STRIDE floats each), one thread a direction bin. */
+export function buildGuideKernel( { counters, out } ) {
+
+	return Fn( () => {
+
+		const bin = instanceIndex;
+		If( bin.greaterThanEqual( uint( GUIDE_BINS ) ), () => {
+
+			Return();
+
+		} );
+
+		const base = uint( COUNTER.GUIDE ).add( bin.mul( uint( GUIDE_CELLS ) ) ).toVar();
+		const total = float( 0.0 ).toVar();
+		Loop( { start: int( 0 ), end: int( GUIDE_CELLS ), type: 'int', condition: '<' }, ( { i } ) => {
+
+			total.addAssign( float( atomicLoad( counters.element( base.add( uint( i ) ) ) ) ) );
+
+		} );
+
+		const row = bin.mul( uint( GUIDE_ROW_STRIDE ) ).toVar();
+		const running = float( 0.0 ).toVar();
+		Loop( { start: int( 0 ), end: int( GUIDE_CELLS ), type: 'int', condition: '<' }, ( { i } ) => {
+
+			running.addAssign( float( atomicLoad( counters.element( base.add( uint( i ) ) ) ) ) );
+			out.element( row.add( uint( i ) ) ).assign( select( total.greaterThan( 0.0 ),
+				select( i.equal( int( GUIDE_CELLS - 1 ) ), float( 1.0 ), running.div( total ) ), float( 0.0 ) ) );
+
+		} );
+		out.element( row.add( uint( GUIDE_CELLS ) ) ).assign( total );
+
+	} )().compute( GUIDE_BINS, [ GUIDE_BINS ] );
+
+}
+
+/** Forgets every count: what camera paths saw before a reset says nothing about the scene after it. */
+export function buildGuideClearKernel( { counters } ) {
+
+	return Fn( () => {
+
+		If( instanceIndex.lessThan( uint( GUIDE_COUNTER_WORDS ) ), () => {
+
+			atomicStore( counters.element( uint( COUNTER.GUIDE ).add( instanceIndex ) ), uint( 0 ) );
+
+		} );
+
+	} )().compute( GUIDE_COUNTER_WORDS, [ 256 ] );
+
+}

package/src/TSL/LightSplatKernel.js

@@ -0,0 +1,165 @@
+/**
+ * LightSplatKernel.js — light tracing: every stored light vertex to the pinhole, into the pixel it
+ * projects to. Fixed-point u32 channels: WGSL has no float atomics, and integer sums are order-free.
+ */
+
+import {
+	Fn, float, vec3, vec4, int, uint, If, instanceIndex, atomicAdd, atomicLoad, atomicStore, Return,
+	dot, sqrt, max, min, floor, length, localId, workgroupId,
+} from 'three/tsl';
+
+import { evaluateMaterialResponse } from './MaterialEvaluation.js';
+import { calculateMaterialPDF } from './LightsSampling.js';
+import { traceShadowRayRefractiveOpaque } from './LightsDirect.js';
+import { traverseBVHShadowCameraCulled } from './BVHTraversal.js';
+import { offsetRayOrigin, SHADOW_END, sanitizeRGB } from './Common.js';
+import { pcgHash } from './Random.js';
+import { regularizePathContribution } from './PathTracerCore.js';
+import { resolveSurfaceMaterial, lightEndCosine, misPartial, misWeight, strategyWeight, STRATEGY, SPLAT_SCALE, SPLAT_MAX } from './Bidirectional.js';
+import {
+	cachedVertex, readVertexRecord, readLightPathLength, readRayRadiance, writeRayRadiance,
+} from '../Processor/PackedRayBuffer.js';
+
+const WG_SIZE = 256;
+const RESOLVE_WG_SIZE = 16;
+
+export function buildLightSplatKernel( params ) {
+
+	const {
+		hitBufferRO, splatBuffer,
+		bvhBuffer, triangleBuffer, materialBuffer,
+		lightPaths, slotsPerPath, lightTag, strategyView,
+		cameraPosition, cameraForward, cameraViewMatrix, cameraProjectionMatrix, pixelArea,
+		renderWidth, renderHeight,
+		globalIlluminationIntensity, fireflyThreshold, accumFrame, frame,
+		mergeVm = null,
+	} = params;
+
+	return Fn( () => {
+
+		const slot = instanceIndex.toVar();
+		If( slot.greaterThanEqual( lightPaths.mul( slotsPerPath ) ), () => {
+
+			Return();
+
+		} );
+
+		const c = slot.mod( slotsPerPath ).toVar();
+		const stored = readLightPathLength( hitBufferRO, cachedVertex( slot.sub( c ) ), lightTag );
+		If( c.greaterThanEqual( stored ), () => {
+
+			Return();
+
+		} );
+
+		const record = readVertexRecord( hitBufferRO, cachedVertex( slot ) );
+		const v = { ...record, vm: mergeVm?.( record.position ) ?? null };
+
+		const toCamera = cameraPosition.sub( v.position ).toVar();
+		const dist2 = max( dot( toCamera, toCamera ), 1e-12 ).toVar();
+		const dir = toCamera.div( sqrt( dist2 ) ).toVar();
+		const cosFacet = dot( dir, v.facetN ).toVar();
+		const cosCamera = dot( dir, cameraForward ).negate().toVar();
+		// The camera is this vertex's viewer: like a camera path, only the facet decides which side it is on.
+		If( cosFacet.lessThanEqual( 0.0 ).or( cosCamera.lessThanEqual( 1e-6 ) ).or( v.extra.notEqual( uint( 0 ) ) ), () => {
+
+			Return();
+
+		} );
+
+		const clip = cameraProjectionMatrix.mul( cameraViewMatrix.mul( vec4( v.position, 1.0 ) ) ).toVar();
+		If( clip.w.lessThanEqual( 0.0 ), () => {
+
+			Return();
+
+		} );
+
+		const px = floor( clip.x.div( clip.w ).mul( 0.5 ).add( 0.5 ).mul( float( renderWidth ) ) ).toVar();
+		const py = floor( float( 0.5 ).sub( clip.y.div( clip.w ).mul( 0.5 ) ).mul( float( renderHeight ) ) ).toVar();
+		If( px.lessThan( 0.0 ).or( py.lessThan( 0.0 ) ).or( px.greaterThanEqual( float( renderWidth ) ) ).or( py.greaterThanEqual( float( renderHeight ) ) ), () => {
+
+			Return();
+
+		} );
+
+		const material = resolveSurfaceMaterial( v.materialIndex, v.uv, v.N, materialBuffer );
+		const f = evaluateMaterialResponse( dir, v.V, v.N, material ).toVar();
+
+		// The pinhole's solid-angle density for a uniform point in a pixel: 1 / (A_pixel cos³θ).
+		const cameraPdfW = float( 1.0 ).div( pixelArea.mul( cosCamera ).mul( cosCamera ).mul( cosCamera ) );
+		const toSurface = cameraPdfW.div( dist2 ).toVar();
+
+		// Georgiev (46); the camera side has no sum of its own.
+		const wLight = misPartial( toSurface.mul( cosFacet ).div( float( lightPaths ) ), v, calculateMaterialPDF( dir, v.V, v.N, material ) );
+		const bounces = c.add( uint( 1 ) );
+		const gi = float( 1.0 ).toVar();
+		If( bounces.greaterThan( uint( 1 ) ), () => {
+
+			gi.assign( globalIlluminationIntensity );
+
+		} );
+
+		const contribution = regularizePathContribution(
+			v.throughput.mul( f ).mul( lightEndCosine( v.V, v.N, v.facetN, dir ) )
+				.mul( toSurface.div( float( lightPaths ) ).mul( strategyWeight( strategyView, STRATEGY.LIGHT_TRACE, misWeight( wLight, float( 0.0 ) ) ) ).mul( gi ) ),
+			float( c ), fireflyThreshold, int( accumFrame ),
+		).toVar();
+
+		const origin = offsetRayOrigin( v.position, v.facetN ).toVar();
+		const segment = cameraPosition.sub( origin ).toVar();
+		const segmentLength = length( segment ).toVar();
+		// This segment stands in for the primary ray, which sees through the faces it culls.
+		const visibility = traceShadowRayRefractiveOpaque(
+			origin, segment.div( segmentLength ), segmentLength.mul( SHADOW_END ),
+			traverseBVHShadowCameraCulled, bvhBuffer, triangleBuffer, materialBuffer,
+		);
+
+		If( visibility.greaterThan( 0.0 ), () => {
+
+			const value = min( sanitizeRGB( contribution.mul( visibility ) ), vec3( SPLAT_MAX ) ).mul( SPLAT_SCALE ).toVar();
+			const dither = float( pcgHash( { state: slot.bitXor( uint( frame ).mul( uint( 0x9E3779B9 ) ) ) } ).shiftRight( uint( 8 ) ) ).mul( 1.0 / 16777216.0 ).toVar();
+			const base = uint( py ).mul( uint( renderWidth ) ).add( uint( px ) ).mul( uint( 3 ) ).toVar();
+			atomicAdd( splatBuffer.element( base ), uint( floor( value.x.add( dither ) ) ) );
+			atomicAdd( splatBuffer.element( base.add( uint( 1 ) ) ), uint( floor( value.y.add( dither ) ) ) );
+			atomicAdd( splatBuffer.element( base.add( uint( 2 ) ) ), uint( floor( value.z.add( dither ) ) ) );
+
+		} );
+
+	} );
+
+}
+
+export function buildSplatResolveKernel( params ) {
+
+	const { rayBufferRW, splatBuffer, renderWidth, chunkRowBase, chunkRows } = params;
+
+	return Fn( () => {
+
+		const gx = int( workgroupId.x ).mul( RESOLVE_WG_SIZE ).add( int( localId.x ) );
+		const localGy = int( workgroupId.y ).mul( RESOLVE_WG_SIZE ).add( int( localId.y ) );
+
+		If( gx.lessThan( renderWidth ).and( localGy.lessThan( chunkRows ) ), () => {
+
+			const rayID = uint( localGy.mul( renderWidth ).add( gx ) );
+			const base = uint( localGy.add( chunkRowBase ).mul( renderWidth ).add( gx ) ).mul( uint( 3 ) ).toVar();
+			const r = atomicLoad( splatBuffer.element( base ) ).toVar();
+			const g = atomicLoad( splatBuffer.element( base.add( uint( 1 ) ) ) ).toVar();
+			const b = atomicLoad( splatBuffer.element( base.add( uint( 2 ) ) ) ).toVar();
+
+			If( r.bitOr( g ).bitOr( b ).notEqual( uint( 0 ) ), () => {
+
+				atomicStore( splatBuffer.element( base ), uint( 0 ) );
+				atomicStore( splatBuffer.element( base.add( uint( 1 ) ) ), uint( 0 ) );
+				atomicStore( splatBuffer.element( base.add( uint( 2 ) ) ), uint( 0 ) );
+				const radiance = readRayRadiance( rayBufferRW, rayID ).toVar();
+				writeRayRadiance( rayBufferRW, rayID, vec4( radiance.xyz.add( vec3( float( r ), float( g ), float( b ) ).div( SPLAT_SCALE ) ), radiance.w ) );
+
+			} );
+
+		} );
+
+	} );
+
+}
+
+export { WG_SIZE as LIGHT_SPLAT_WG_SIZE, RESOLVE_WG_SIZE as SPLAT_RESOLVE_WG_SIZE };