rayzee 9.4.2 → 9.5.0

package/src/TSL/LightBVHSampling.js

@@ -18,11 +18,14 @@ import {
 	normalize,
 	cross,
 	length,
+	abs,
 } from 'three/tsl';
 import { MIN_PDF } from './Common.js';
+import { sideAccepts } from './BVHTraversal.js';
 import { getRandomSample1D, getRandomSample2D } from './Random.js';
 import {
 	EmissiveSample,
+	EmissiveSampleIndexed,
 	sampleTriangle,
 	interpolateNormal,
 	fetchTriangleData,
@@ -103,7 +106,7 @@ export const lbvhNodeImportance = Fn( ( [ nMin, power, nMax, coneAxis, cosThetaO
  *
  * Returns an EmissiveSample struct.
  */
-export const sampleLightBVHTriangle = Fn( ( [
+const makeSampleLightBVHTriangle = ( indexed ) => Fn( ( [
 	hitPoint, surfaceNormal,
 	rngState,
 	pixelCoord, resolution, frame, dimBase,
@@ -111,9 +114,11 @@ export const sampleLightBVHTriangle = Fn( ( [
 	emissiveTriangleBuffer,
 	emissiveVec4Offset,
 	triangleBuffer, bvhBuffer,
+	// The surface passes light through diffusely: a point behind it is as good as one in front.
+	throughSurface,
 ] ) => {
 
-	const result = EmissiveSample( {
+	const fields = {
 		position: vec3( 0.0 ),
 		normal: vec3( 0.0 ),
 		emission: vec3( 0.0 ),
@@ -123,7 +128,10 @@ export const sampleLightBVHTriangle = Fn( ( [
 		area: float( 0.0 ),
 		cosThetaLight: float( 0.0 ),
 		valid: false,
-	} ).toVar();
+	};
+	const result = ( indexed
+		? EmissiveSampleIndexed( { ...fields, triangleIndex: int( - 1 ), faceNormal: vec3( 0.0 ) } )
+		: EmissiveSample( fields ) ).toVar();
 
 	// Accumulated selection PDF (product of per-level choice probabilities)
 	const selectionPdf = float( 1.0 ).toVar();
@@ -279,9 +287,9 @@ export const sampleLightBVHTriangle = Fn( ( [
 				const samplePos = sphResult.position;
 
 				const surfaceFacing = dot( dir, surfaceNormal );
-				const emissiveFacing = dot( dir, geoNormal.negate() );
+				const emissiveFacing = abs( dot( dir, geoNormal ) );
 
-				If( surfaceFacing.greaterThan( float( 0.0 ) ).and( emissiveFacing.greaterThan( float( 0.0 ) ) ), () => {
+				If( surfaceFacing.greaterThan( float( 0.0 ) ).or( throughSurface ).and( sideAccepts( triData.side, dot( dir, geoNormal ) ) ), () => {
 
 					// Interpolate normal at sampled point via barycentric coords
 					const barycentricCoords = barycentricFromPoint( samplePos, triData.v0, triData.v1, triData.v2 );
@@ -305,6 +313,12 @@ export const sampleLightBVHTriangle = Fn( ( [
 					result.area.assign( area );
 					result.cosThetaLight.assign( emissiveFacing );
 					result.valid.assign( true );
+					if ( indexed ) {
+
+						result.triangleIndex.assign( triangleIndex );
+						result.faceNormal.assign( geoNormal );
+
+					}
 
 				} );
 
@@ -322,9 +336,11 @@ export const sampleLightBVHTriangle = Fn( ( [
 			const dir = toEmissive.div( dist );
 
 			const surfaceFacing = dot( dir, surfaceNormal );
-			const emissiveFacing = dot( dir, sampleNormal.negate() );
+			// The facet's cosine, not the shading normal's: it is what turns an area density into a solid-angle one.
+			const emissiveFacing = abs( dot( dir, geoNormal ) );
 
-			If( surfaceFacing.greaterThan( float( 0.0 ) ).and( emissiveFacing.greaterThan( float( 0.0 ) ) ), () => {
+			// Edge-on (a two-sided emitter passes its side test there) the density is infinite and the light zero.
+			If( surfaceFacing.greaterThan( float( 0.0 ) ).or( throughSurface ).and( sideAccepts( triData.side, dot( dir, geoNormal ) ) ).and( emissiveFacing.greaterThan( float( 0.0 ) ) ), () => {
 
 				// PDF: selectionPdf / area, converted to solid angle: pdfArea * distSq / cosLight
 				const pdfArea = selectionPdf.div( max( area, float( 1e-10 ) ) );
@@ -339,6 +355,12 @@ export const sampleLightBVHTriangle = Fn( ( [
 				result.area.assign( area );
 				result.cosThetaLight.assign( emissiveFacing );
 				result.valid.assign( true );
+				if ( indexed ) {
+
+					result.triangleIndex.assign( triangleIndex );
+					result.faceNormal.assign( geoNormal );
+
+				}
 
 			} );
 
@@ -350,6 +372,9 @@ export const sampleLightBVHTriangle = Fn( ( [
 
 } );
 
+export const sampleLightBVHTriangle = /*@__PURE__*/ makeSampleLightBVHTriangle( false );
+export const sampleLightBVHTriangleIndexed = /*@__PURE__*/ makeSampleLightBVHTriangle( true );
+
 // ================================================================================
 // LIGHT-BVH MIS PDF (re-walk)
 // ================================================================================
@@ -482,6 +507,12 @@ export const calculateLightBVHPdf = Fn( ( [
 
 			// Convert selection pdf → solid-angle measure using the SAME heuristic as the sampler.
 			const triData = TriangleData.wrap( fetchTriangleData( triIdx, triangleBuffer, bvhBuffer, targetInstance ) );
+			// The sampler draws only the sides the triangle emits from (a unit normal: sideAccepts has a threshold).
+			If( sideAccepts( triData.side, dot( rayDir, normalize( cross( triData.v1.sub( triData.v0 ), triData.v2.sub( triData.v0 ) ) ) ) ).not(), () => {
+
+				selectionPdf.assign( float( 0.0 ) );
+
+			} );
 			If( useSphericalSampling( triData.v0, triData.v1, triData.v2, shadingPoint ), () => {
 
 				const solidAngle = sphericalTriangleSolidAngle( triData.v0, triData.v1, triData.v2, shadingPoint );
@@ -490,7 +521,7 @@ export const calculateLightBVHPdf = Fn( ( [
 			} ).Else( () => {
 
 				const geoNormal = normalize( cross( triData.v1.sub( triData.v0 ), triData.v2.sub( triData.v0 ) ) );
-				const cosLight = max( dot( rayDir.negate(), geoNormal ), float( 0.001 ) );
+				const cosLight = max( abs( dot( rayDir, geoNormal ) ), float( 0.001 ) );
 				const area = triangleArea( triData.v0, triData.v1, triData.v2 );
 				const distSq = hitDistance.mul( hitDistance );
 				const pdfArea = selectionPdf.div( max( area, float( 1e-10 ) ) );
@@ -502,6 +533,6 @@ export const calculateLightBVHPdf = Fn( ( [
 
 	} );
 
-	return max( result, MIN_PDF );
+	return select( result.greaterThan( 0.0 ), max( result, MIN_PDF ), float( 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 ] );
+
+}