rayzee 7.2.0 → 7.3.0

package/src/TSL/LightBVHSampling.js

@@ -14,6 +14,8 @@ import {
 	dot,
 	sqrt,
 	max,
+	clamp,
+	select,
 	normalize,
 	cross,
 	length,
@@ -29,6 +31,8 @@ import {
 	sampleSphericalTriangle,
 	barycentricFromPoint,
 	useSphericalSampling,
+	sphericalTriangleSolidAngle,
+	triangleArea,
 	SphericalTriangleSampleResult,
 } from './EmissiveSampling.js';
 
@@ -37,6 +41,58 @@ const LBVH_STRIDE = 4; // 4 vec4s per node
 const EMISSIVE_STRIDE = 2; // 2 vec4s per emissive entry (matches EmissiveSampling.js)
 const MAX_LBVH_DEPTH = 32;
 
+// ================================================================================
+// LIGHT-BVH NODE IMPORTANCE (Conty-Estevez & Kulla 2018 / PBRT-v4 BVHLightSampler)
+// ================================================================================
+// cos((thetaA - thetaB) clamped to >= 0). cosA > cosB ⇒ thetaA < thetaB ⇒ diff clamped to 0.
+const cosSubClamped = Fn( ( [ sinThetaA, cosThetaA, sinThetaB, cosThetaB ] ) => {
+
+	return select( cosThetaA.greaterThan( cosThetaB ), float( 1.0 ), cosThetaA.mul( cosThetaB ).add( sinThetaA.mul( sinThetaB ) ) );
+
+} );
+
+// sin((thetaA - thetaB) clamped to >= 0).
+const sinSubClamped = Fn( ( [ sinThetaA, cosThetaA, sinThetaB, cosThetaB ] ) => {
+
+	return select( cosThetaA.greaterThan( cosThetaB ), float( 0.0 ), sinThetaA.mul( cosThetaB ).sub( cosThetaA.mul( sinThetaB ) ) );
+
+} );
+
+// Importance of a Light-BVH node for a shading point (power × orientation × inverse-square),
+// θ_e = π/2 (diffuse emitters). cosThetaO = -1 ⇒ whole-sphere cone (never culled by orientation).
+// SHARED by both the stochastic descent and the MIS pdf re-walk — they MUST stay byte-identical.
+export const lbvhNodeImportance = Fn( ( [ nMin, power, nMax, coneAxis, cosThetaO, hitPoint ] ) => {
+
+	const center = nMin.add( nMax ).mul( 0.5 );
+	const diagLen = length( nMax.sub( nMin ) );
+	const toCenter = hitPoint.sub( center );
+	const d2c = max( dot( toCenter, toCenter ), float( 1e-12 ) );
+	// PBRT distance clamp (note: clamps to diagLen/2, a length not a square — matches PBRT)
+	const d2 = max( d2c, diagLen.mul( 0.5 ) );
+
+	const wi = toCenter.div( sqrt( d2c ) ); // direction from cluster center to shading point
+	const cosThetaW = dot( coneAxis, wi );
+	const sinThetaW = sqrt( max( float( 1.0 ).sub( cosThetaW.mul( cosThetaW ) ), float( 0.0 ) ) );
+
+	// Half-angle subtended by the cluster's bounding sphere from the shading point.
+	const r2 = diagLen.mul( diagLen ).mul( 0.25 );
+	const sin2ThetaB = clamp( r2.div( d2c ), float( 0.0 ), float( 1.0 ) );
+	const cosThetaB = select( d2c.lessThan( r2 ), float( - 1.0 ), sqrt( max( float( 1.0 ).sub( sin2ThetaB ), float( 0.0 ) ) ) );
+	const sinThetaB = sqrt( max( float( 1.0 ).sub( cosThetaB.mul( cosThetaB ) ), float( 0.0 ) ) );
+
+	const sinThetaO = sqrt( max( float( 1.0 ).sub( cosThetaO.mul( cosThetaO ) ), float( 0.0 ) ) );
+
+	// cosThetap = cos( (theta_w - theta_o - theta_b) clamped >= 0 )
+	const cosThetaX = cosSubClamped( sinThetaW, cosThetaW, sinThetaO, cosThetaO );
+	const sinThetaX = sinSubClamped( sinThetaW, cosThetaW, sinThetaO, cosThetaO );
+	const cosThetap = cosSubClamped( sinThetaX, cosThetaX, sinThetaB, cosThetaB );
+
+	// θ_e = π/2 ⇒ cosThetaE = 0; cluster cannot illuminate the point when cosThetap <= 0.
+	const imp = select( cosThetap.greaterThan( float( 0.0 ) ), power.mul( cosThetap ).div( d2 ), float( 0.0 ) );
+	return max( imp, float( 0.0 ) );
+
+} );
+
 /**
  * Sample one emissive triangle using the Light BVH for spatially-aware importance sampling.
  *
@@ -105,31 +161,12 @@ export const sampleLightBVHTriangle = Fn( ( [
 		const rd0 = lbvhBuffer.element( rBase ); // [minX, minY, minZ, totalPower]
 		const rd1 = lbvhBuffer.element( rBase.add( int( 1 ) ) ); // [maxX, maxY, maxZ, isLeaf]
 
-		// Compute center of each child's AABB
-		const lCenter = vec3(
-			ld0.x.add( ld1.x ).mul( 0.5 ),
-			ld0.y.add( ld1.y ).mul( 0.5 ),
-			ld0.z.add( ld1.z ).mul( 0.5 )
-		);
-		const rCenter = vec3(
-			rd0.x.add( rd1.x ).mul( 0.5 ),
-			rd0.y.add( rd1.y ).mul( 0.5 ),
-			rd0.z.add( rd1.z ).mul( 0.5 )
-		);
-
-		// Compute squared distance from hitPoint to each child center
-		const lDiff = lCenter.sub( hitPoint );
-		const rDiff = rCenter.sub( hitPoint );
-		const lDistSq = max( dot( lDiff, lDiff ), float( 0.01 ) );
-		const rDistSq = max( dot( rDiff, rDiff ), float( 0.01 ) );
-
-		// Child power
-		const lPower = max( ld0.w, float( 0.0 ) );
-		const rPower = max( rd0.w, float( 0.0 ) );
-
-		// Importance = power / dist²
-		const lImportance = lPower.div( lDistSq );
-		const rImportance = rPower.div( rDistSq );
+		// Conty-Kulla importance: power × orientation-cone × inverse-square (shared with the MIS re-walk).
+		// d3 = [coneAxis, cosThetaO]; cosThetaO = -1 ⇒ whole-sphere cone (never culled by orientation).
+		const ld3 = lbvhBuffer.element( lBase.add( int( 3 ) ) );
+		const rd3 = lbvhBuffer.element( rBase.add( int( 3 ) ) );
+		const lImportance = lbvhNodeImportance( ld0.xyz, ld0.w, ld1.xyz, ld3.xyz, ld3.w, hitPoint );
+		const rImportance = lbvhNodeImportance( rd0.xyz, rd0.w, rd1.xyz, rd3.xyz, rd3.w, hitPoint );
 		const totalImportance = lImportance.add( rImportance );
 
 		If( totalImportance.lessThanEqual( float( 0.0 ) ), () => {
@@ -307,3 +344,157 @@ export const sampleLightBVHTriangle = Fn( ( [
 	return result;
 
 } );
+
+// ================================================================================
+// LIGHT-BVH MIS PDF (re-walk)
+// ================================================================================
+// Computes the solid-angle pdf that sampleLightBVHTriangle WOULD assign to a given emissive
+// triangle hit by a BSDF bounce, by re-walking the exact stochastic descent along the triangle's
+// stored bit-trail. Required so the bounce-hit MIS weight uses the SAME light pdf the NEE sampler
+// used — without this the MIS partition-of-unity breaks (a real bias).
+//
+// lightBuffer packs [ LBVH nodes | emissive entries | bit-trail map ]. The bit-trail map holds one
+// float per absolute triangleIndex (4 packed per vec4): the root→leaf left(0)/right(1) choices.
+export const calculateLightBVHPdf = Fn( ( [
+	triangleIndex, hitDistance, rayDir, shadingPoint,
+	lightBuffer, emissiveVec4Offset, reverseMapVec4Offset, triangleBuffer,
+] ) => {
+
+	const result = float( 0.0 ).toVar();
+
+	const triIdx = int( triangleIndex ).toVar();
+
+	// Fetch this triangle's bit-trail (4 packed per vec4). -1 ⇒ not in the BVH (shouldn't happen on
+	// an emissive hit) → leave pdf 0 (MIS falls back to BSDF-only).
+	const packed = lightBuffer.element( reverseMapVec4Offset.add( triIdx.shiftRight( int( 2 ) ) ) );
+	const lane = triIdx.bitAnd( int( 3 ) );
+	const trailF = select( lane.equal( int( 0 ) ), packed.x,
+		select( lane.equal( int( 1 ) ), packed.y,
+			select( lane.equal( int( 2 ) ), packed.z, packed.w ) ) ).toVar();
+
+	If( trailF.greaterThanEqual( float( 0.0 ) ), () => {
+
+		const trail = int( trailF ).toVar();
+		const selectionPdf = float( 1.0 ).toVar();
+		const nodeIndex = int( 0 ).toVar();
+		const depth = int( 0 ).toVar();
+		const foundLeaf = tslBool( false ).toVar();
+
+		Loop( MAX_LBVH_DEPTH, () => {
+
+			const base = nodeIndex.mul( int( LBVH_STRIDE ) );
+			const d1 = lightBuffer.element( base.add( int( 1 ) ) ); // [max, isLeaf]
+
+			If( d1.w.greaterThan( 0.5 ), () => {
+
+				foundLeaf.assign( tslBool( true ) );
+				Break();
+
+			} );
+
+			const d2 = lightBuffer.element( base.add( int( 2 ) ) ); // [left, right]
+			const leftChildIdx = int( d2.x );
+			const rightChildIdx = int( d2.y );
+
+			const lBase = leftChildIdx.mul( int( LBVH_STRIDE ) );
+			const ld0 = lightBuffer.element( lBase );
+			const ld1 = lightBuffer.element( lBase.add( int( 1 ) ) );
+			const ld3 = lightBuffer.element( lBase.add( int( 3 ) ) );
+			const rBase = rightChildIdx.mul( int( LBVH_STRIDE ) );
+			const rd0 = lightBuffer.element( rBase );
+			const rd1 = lightBuffer.element( rBase.add( int( 1 ) ) );
+			const rd3 = lightBuffer.element( rBase.add( int( 3 ) ) );
+
+			const lImp = lbvhNodeImportance( ld0.xyz, ld0.w, ld1.xyz, ld3.xyz, ld3.w, shadingPoint );
+			const rImp = lbvhNodeImportance( rd0.xyz, rd0.w, rd1.xyz, rd3.xyz, rd3.w, shadingPoint );
+			const totalImp = lImp.add( rImp );
+
+			// Trail bit at this depth: 0 → left, 1 → right. Mirror the descent's choice logic EXACTLY.
+			const goRight = trail.shiftRight( depth ).bitAnd( int( 1 ) ).equal( int( 1 ) );
+
+			If( totalImp.lessThanEqual( float( 0.0 ) ), () => {
+
+				// Descent forces left with no pdf update; if the trail goes right it is unreachable.
+				If( goRight, () => {
+
+					selectionPdf.assign( float( 0.0 ) );
+					nodeIndex.assign( rightChildIdx );
+
+				} ).Else( () => {
+
+					nodeIndex.assign( leftChildIdx );
+
+				} );
+
+			} ).Else( () => {
+
+				const pLeft = lImp.div( totalImp );
+				If( goRight, () => {
+
+					selectionPdf.mulAssign( float( 1.0 ).sub( pLeft ) );
+					nodeIndex.assign( rightChildIdx );
+
+				} ).Else( () => {
+
+					selectionPdf.mulAssign( pLeft );
+					nodeIndex.assign( leftChildIdx );
+
+				} );
+
+			} );
+
+			depth.addAssign( int( 1 ) );
+
+		} );
+
+		If( foundLeaf.and( selectionPdf.greaterThan( float( 0.0 ) ) ), () => {
+
+			// Leaf: power-weighted within-leaf selection prob for the target triangle (matches the sampler).
+			const base = nodeIndex.mul( int( LBVH_STRIDE ) );
+			const d0 = lightBuffer.element( base );
+			const d2 = lightBuffer.element( base.add( int( 2 ) ) );
+			const emissiveStart = int( d2.x );
+			const emissiveCount = int( d2.y );
+			const leafTotalPower = max( d0.w, float( 1e-10 ) );
+
+			const targetPower = float( 0.0 ).toVar();
+			Loop( { start: int( 0 ), end: emissiveCount }, ( { i } ) => {
+
+				const entryIdx = emissiveStart.add( i );
+				const emData0 = lightBuffer.element( emissiveVec4Offset.add( entryIdx.mul( int( EMISSIVE_STRIDE ) ) ) );
+				If( int( emData0.r ).equal( triIdx ), () => {
+
+					targetPower.assign( max( emData0.g, float( 0.0 ) ) );
+					Break();
+
+				} );
+
+			} );
+
+			selectionPdf.mulAssign( targetPower.div( leafTotalPower ) );
+
+			// Convert selection pdf → solid-angle measure using the SAME heuristic as the sampler.
+			const triData = TriangleData.wrap( fetchTriangleData( triIdx, triangleBuffer ) );
+			If( useSphericalSampling( triData.v0, triData.v1, triData.v2, shadingPoint ), () => {
+
+				const solidAngle = sphericalTriangleSolidAngle( triData.v0, triData.v1, triData.v2, shadingPoint );
+				result.assign( selectionPdf.div( max( solidAngle, float( 1e-10 ) ) ) );
+
+			} ).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 area = triangleArea( triData.v0, triData.v1, triData.v2 );
+				const distSq = hitDistance.mul( hitDistance );
+				const pdfArea = selectionPdf.div( max( area, float( 1e-10 ) ) );
+				result.assign( pdfArea.mul( distSq ).div( cosLight ) );
+
+			} );
+
+		} );
+
+	} );
+
+	return max( result, MIN_PDF );
+
+} );

package/src/TSL/LightsSampling.js

@@ -58,7 +58,7 @@ import {
 	sampleIESProfile,
 } from './LightsCore.js';
 
-import { MISStrategy, DotProducts } from './Struct.js';
+import { MISStrategy, DotProducts, DirectLightingDual } from './Struct.js';
 import {
 	calculateDirectionalLightImportance,
 	estimateLightImportance,
@@ -707,9 +707,14 @@ export const calculateDirectLightingUnified = Fn( ( [
 	envCDFTexture,
 	envTotalSum, envCompensationDelta, envResolution,
 	enableEnvironmentLight,
+	// Shadow catcher: when true, also accumulate the unoccluded (visibility=1) reference
+	// at every light/env site so the caller can form a shadow ratio. Dead path otherwise.
+	wantUnoccluded,
 ] ) => {
 
 	const totalContribution = vec3( 0.0 ).toVar();
+	// Unoccluded reference (visibility forced to 1) — only filled when wantUnoccluded.
+	const unoccludedContribution = vec3( 0.0 ).toVar();
 	const rayOrigin = hitPoint.add( hitNormal.mul( 0.001 ) ).toVar();
 
 	// Binds BVH params so shadow-ray sites at varying call depths use a 3-arg call
@@ -819,7 +824,7 @@ export const calculateDirectLightingUnified = Fn( ( [
 					const shadowDistance = min( lightSample.distance.sub( 0.001 ), float( 1000.0 ) );
 					const visibility = shadow( rayOrigin, lightSample.direction, shadowDistance );
 
-					If( visibility.greaterThan( 0.0 ), () => {
+					If( visibility.greaterThan( 0.0 ).or( wantUnoccluded ), () => {
 
 						// Share H + dot products between BRDF eval and PDF — otherwise each
 						// would recompute normalize(V+L) + 5 dot products independently.
@@ -846,9 +851,15 @@ export const calculateDirectLightingUnified = Fn( ( [
 
 						} );
 
-						// Guard division
-						const lightContribution = lightSample.emission.mul( brdfValue ).mul( NoL ).mul( visibility ).mul( misW ).div( max( lightSample.pdf, 1e-10 ) );
-						totalContribution.addAssign( lightContribution.mul( totalSamplingWeight ).div( max( lightWeight, 1e-10 ) ) );
+						// Base contribution WITHOUT visibility; shadowed = base × visibility (identical to the
+						// pre-dual-sum math), unoccluded = base × 1 (shadow-catcher reference only).
+						const baseContribution = lightSample.emission.mul( brdfValue ).mul( NoL ).mul( misW ).div( max( lightSample.pdf, 1e-10 ) ).mul( totalSamplingWeight ).div( max( lightWeight, 1e-10 ) );
+						totalContribution.addAssign( baseContribution.mul( visibility ) );
+						If( wantUnoccluded, () => {
+
+							unoccludedContribution.addAssign( baseContribution );
+
+						} );
 
 					} );
 
@@ -918,7 +929,7 @@ export const calculateDirectLightingUnified = Fn( ( [
 								const shadowDistance = min( hitDistance.sub( 0.001 ), float( 1000.0 ) );
 								const visibility = shadow( rayOrigin, brdfSampleDirection, shadowDistance );
 
-								If( visibility.greaterThan( 0.0 ), () => {
+								If( visibility.greaterThan( 0.0 ).or( wantUnoccluded ), () => {
 
 									const lightFacing = max( float( 0.0 ), dot( brdfSampleDirection, light.normal ).negate() ).toVar();
 
@@ -934,9 +945,14 @@ export const calculateDirectLightingUnified = Fn( ( [
 										const misW = powerHeuristic( { pdf1: brdfPdfWeighted, pdf2: lightPdfWeighted } ).toVar();
 
 										const lightEmission = light.color.mul( light.intensity );
-										// Guard division
-										const brdfContribution = lightEmission.mul( brdfSampleValue ).mul( NoL ).mul( visibility ).mul( misW ).div( max( brdfSamplePdf, 1e-10 ) );
-										totalContribution.addAssign( brdfContribution.mul( totalSamplingWeight ).div( max( brdfWeight, 1e-10 ) ) );
+										// Base contribution WITHOUT visibility (see discrete-light site).
+										const baseContribution = lightEmission.mul( brdfSampleValue ).mul( NoL ).mul( misW ).div( max( brdfSamplePdf, 1e-10 ) ).mul( totalSamplingWeight ).div( max( brdfWeight, 1e-10 ) );
+										totalContribution.addAssign( baseContribution.mul( visibility ) );
+										If( wantUnoccluded, () => {
+
+											unoccludedContribution.addAssign( baseContribution );
+
+										} );
 
 									} );
 
@@ -984,7 +1000,7 @@ export const calculateDirectLightingUnified = Fn( ( [
 
 					const visibility = shadow( rayOrigin, envDirection, float( 1000.0 ) );
 
-					If( visibility.greaterThan( 0.0 ), () => {
+					If( visibility.greaterThan( 0.0 ).or( wantUnoccluded ), () => {
 
 						// Share H + dots between env BRDF/PDF — same redundancy fix as the
 						// discrete-light path above.
@@ -1000,9 +1016,14 @@ export const calculateDirectLightingUnified = Fn( ( [
 							float( 1.0 )
 						).toVar();
 
-						// Guard division — no stochastic scaling needed (deterministic estimator)
-						const envContribution = envColor.mul( brdfValue ).mul( NoL ).mul( visibility ).mul( misW ).div( max( envPdf, 1e-10 ) );
-						totalContribution.addAssign( envContribution );
+						// Base contribution WITHOUT visibility (deterministic estimator; no stochastic scaling).
+						const baseContribution = envColor.mul( brdfValue ).mul( NoL ).mul( misW ).div( max( envPdf, 1e-10 ) );
+						totalContribution.addAssign( baseContribution.mul( visibility ) );
+						If( wantUnoccluded, () => {
+
+							unoccludedContribution.addAssign( baseContribution );
+
+						} );
 
 					} );
 
@@ -1018,6 +1039,6 @@ export const calculateDirectLightingUnified = Fn( ( [
 	// NOTE: Emissive triangle sampling is handled separately in pathtracer_core.fs
 	// to bypass firefly suppression. Do not add it here to avoid double-counting.
 
-	return totalContribution;
+	return DirectLightingDual( { shadowed: totalContribution, unoccluded: unoccludedContribution } );
 
 } );

package/src/TSL/ShadeKernel.js

@@ -6,6 +6,7 @@
 
 import {
 	Fn, float, vec2, vec3, vec4, int, uint,
+	bool as tslBool,
 	If, normalize, max, exp, log, clamp, dot, length, select,
 	instanceIndex,
 	sampler,
@@ -13,8 +14,9 @@ import {
 	Return,
 } from 'three/tsl';
 
-import { sampleEnvironment, sampleEquirectProbability, sampleEquirect, getGroundProjectedDirection } from './Environment.js';
-import { getMaterial, powerHeuristic, balanceHeuristic, classifyMaterial } from './Common.js';
+import { sampleEnvironment, sampleEquirectProbability, sampleEquirect, groundProjectedEnvDir } from './Environment.js';
+import { getMaterial, powerHeuristic, balanceHeuristic, classifyMaterial, REC709_LUMINANCE_COEFFICIENTS, PI_INV, EPSILON, diffuseGroundMaterial } from './Common.js';
+import { cosineWeightedSample } from './MaterialSampling.js';
 import { sampleAllMaterialTextures } from './TextureSampling.js';
 import { evaluateMaterialResponse } from './MaterialEvaluation.js';
 import { calculateDirectLightingUnified, calculateMaterialPDF } from './LightsSampling.js';
@@ -29,7 +31,7 @@ import { getImportanceSamplingInfo } from './MaterialProperties.js';
 import { sampleClearcoat, ClearcoatResult } from './Clearcoat.js';
 import { refineDisplacedIntersection, DisplacementResult } from './Displacement.js';
 import { calculateEmissiveTriangleContribution, calculateEmissiveLightPdf, EmissiveSample } from './EmissiveSampling.js';
-import { sampleLightBVHTriangle } from './LightBVHSampling.js';
+import { sampleLightBVHTriangle, calculateLightBVHPdf } from './LightBVHSampling.js';
 import {
 	Ray,
 	HitInfo,
@@ -40,6 +42,7 @@ import {
 	MaterialClassification,
 	BRDFWeights,
 	MaterialCache,
+	DirectLightingDual,
 } from './Struct.js';
 import { RandomValue, getRandomSample } from './Random.js';
 import { RAY_FLAG, COUNTER } from '../Processor/QueueManager.js';
@@ -57,6 +60,14 @@ import {
 const WG_SIZE = 256;
 const MISS_DIST = 1e19;
 
+// Shadow-catcher thresholds (named so the two distinct 1e-4 uses don't read as one value)
+const CATCHER_T_MIN = 1e-4; // min ray-t for the analytic plane hit (skip behind/at the camera)
+const CATCHER_LUMA_FLOOR = 1e-4; // denominator floor for the shadow ratio
+const CATCHER_COVERAGE_MIN = 1e-3; // below this incident luma there is no shadow to catch
+// Reserved G-buffer surface ID for catcher pixels (no real triangle); stable across frames so the
+// denoiser treats the analytic plane as one coherent surface, not a background miss.
+const CATCHER_SURFACE_ID = 0xFFFFFFFE;
+
 export function buildShadeKernel( params ) {
 
 	const {
@@ -71,7 +82,8 @@ export function buildShadeKernel( params ) {
 		displacementMaps,
 		envTexture, environmentIntensity, envMatrix,
 		enableEnvironmentLight, useEnvMapIS,
-		groundProjectionEnabled, groundProjectionRadius, groundProjectionHeight,
+		groundProjectionEnabled, groundProjectionRadius, groundProjectionHeight, groundProjectionLevel,
+		enableGroundCatcher, groundCatcherHeight,
 		envTotalSum, envCompensationDelta, envResolution,
 		directionalLightsBuffer, numDirectionalLights,
 		areaLightsBuffer, numAreaLights,
@@ -85,7 +97,7 @@ export function buildShadeKernel( params ) {
 		fireflyThreshold, frame, resolution,
 		emissiveTriangleCount, emissiveVec4Offset, emissiveTotalPower,
 		emissiveBoost, totalTriangleCount, enableEmissiveTriangleSampling,
-		lightBVHNodeCount,
+		lightBVHNodeCount, reverseMapVec4Offset,
 		maxRayCount,
 	} = params;
 
@@ -136,6 +148,111 @@ export function buildShadeKernel( params ) {
 		const sssSteps = readSssSteps( rayBufferRW, rayID ).toVar();
 		const sampleIndex = int( rayID.div( maxRaysPerSample ) ).toVar();
 
+		// ── Analytic ground-plane shadow catcher (primary ray only, no geometry) ──
+		// A horizontal plane at y = groundCatcherHeight. For a bounce-0 ray that crosses it
+		// closer than any BVH hit (hitDist is MISS_DIST on sky rays, so the plane wins over the
+		// bare environment), shade it as a diffuse Lambertian holdout: output a monochrome shadow
+		// ratio in alpha (rgb = 0) so it composites as bg·ratio over a transparent background.
+		// Shadows are caught by the EXISTING NEE shadow ray into real geometry — the plane itself
+		// never enters the BVH. Secondary bounces ignore it entirely.
+		If( enableGroundCatcher.and( bounceIndex.equal( 0 ) ), () => {
+
+			const dirY = direction.y.toVar();
+			If( dirY.abs().greaterThan( float( EPSILON ) ), () => {
+
+				const tPlane = groundCatcherHeight.sub( origin.y ).div( dirY ).toVar();
+				If( tPlane.greaterThan( float( CATCHER_T_MIN ) ).and( tPlane.lessThan( hitDist ) ), () => {
+
+					const planePoint = origin.add( direction.mul( tPlane ) ).toVar();
+					const planeN = vec3( 0.0, 1.0, 0.0 );
+					const planeV = direction.negate().toVar();
+					const planeMat = RayTracingMaterial.wrap( diffuseGroundMaterial() ).toVar();
+
+					// Cosine-weighted hemisphere BRDF sample about the plane normal (0,1,0); the helper
+					// puts cosθ along N, so bDir.y == cosθ. Per-component .toVar() on the two randoms
+					// (vec2(RandomValue,RandomValue) would collapse to u==v — TSL pitfall).
+					const u1 = RandomValue( rngState ).toVar();
+					const u2 = RandomValue( rngState ).toVar();
+					const bDir = cosineWeightedSample( planeN, vec2( u1, u2 ) ).toVar();
+					const bPdf = bDir.y.mul( PI_INV ).toVar(); // cosθ / π
+					const bVal = vec3( PI_INV ); // albedo(1) / π
+
+					// Reuse the full NEE estimator; the diffuse BRDF is constant and cancels in the
+					// ratio, so this yields an irradiance-weighted shadow density across all lights + env.
+					const dual = DirectLightingDual.wrap( calculateDirectLightingUnified(
+						planePoint, planeN, planeMat, planeV,
+						bDir, bPdf, bVal,
+						bounceIndex, rngState,
+						directionalLightsBuffer, numDirectionalLights,
+						areaLightsBuffer, numAreaLights,
+						pointLightsBuffer, numPointLights,
+						spotLightsBuffer, numSpotLights,
+						bvhBuffer, triangleBuffer, materialBuffer,
+						envTexture, environmentIntensity, envMatrix,
+						envCDFTexture,
+						envTotalSum, envCompensationDelta, envResolution,
+						enableEnvironmentLight,
+						tslBool( true ), // wantUnoccluded
+					) ).toVar();
+
+					const lumShad = max( dot( dual.shadowed, REC709_LUMINANCE_COEFFICIENTS ), float( 0.0 ) );
+					const lumLit = max( dot( dual.unoccluded, REC709_LUMINANCE_COEFFICIENTS ), float( 0.0 ) ).toVar();
+					const ratio = clamp( lumShad.div( max( lumLit, float( CATCHER_LUMA_FLOOR ) ) ), 0.0, 1.0 ).toVar();
+					// Coverage gate: where no light reaches the plane there is no shadow to catch —
+					// force ratio=1 (no darkening) so unlit ground reads as plain background, not spurious black.
+					If( lumLit.lessThan( float( CATCHER_COVERAGE_MIN ) ), () => {
+
+						ratio.assign( 1.0 );
+
+					} );
+
+					// Adaptive output (matches Arnold's scene_background / Cycles shadow catcher): the catcher
+					// respects the current background mode instead of forcing transparency.
+					//  • Transparent background → emit a matte (rgb=0, alpha=1−ratio); the shadow rides alpha
+					//    and composites as backplate·ratio over an external plate.
+					//  • Visible background     → composite the shadow into RGB: show the environment this
+					//    camera ray would otherwise see, darkened by the shadow ratio (alpha=1). The HDRI stays
+					//    visible; at the horizon ratio→1 so the catcher meets the sky with no seam.
+					// Sample the background via the SAME shared helper the miss branch uses, so the
+					// catcher seamlessly continues the visible environment (with ground projection on it
+					// must bend identically, else a bright horizon seam / mismatched ground appears).
+					const catcherEnvDir = groundProjectedEnvDir(
+						origin, direction, groundProjectionEnabled, groundProjectionRadius, groundProjectionHeight, groundProjectionLevel,
+					).toVar();
+					const envBehind = sampleEnvironment( {
+						tex: envTexture,
+						samp: sampler( envTexture ),
+						direction: catcherEnvDir,
+						environmentMatrix: envMatrix,
+						environmentIntensity,
+						enableEnvironmentLight,
+					} ).xyz.toVar();
+					const bgColor = select( showBackground, envBehind.mul( backgroundIntensity ), vec3( 0.0 ) );
+					const outRgb = select( transparentBackground, vec3( 0.0 ), bgColor.mul( ratio ) );
+					const outAlpha = select( transparentBackground, float( 1.0 ).sub( ratio ), float( 1.0 ) );
+
+					// The catcher is a real ground surface for the denoiser — write the plane's normal/depth
+					// + a neutral albedo (black albedo would break OIDN demodulation) and mark the pixel a
+					// valid surface, so OIDN/ASVGF don't smear the caught shadow as a background miss.
+					If( sampleIndex.equal( int( 0 ) ), () => {
+
+						const planeDepth = computeNDCDepth( { worldPos: planePoint, cameraProjectionMatrix, cameraViewMatrix } );
+						writeGBuffer( gBufferRW, pixelIndex, planeN, planeDepth, vec3( 1.0 ) );
+						writeGBufferSurfaceID( gBufferRW, pixelIndex, uint( CATCHER_SURFACE_ID ), uint( CATCHER_SURFACE_ID ), 0.5, 0.5, uint( 1 ) );
+
+					} );
+
+					writeRayRadiance( rayBufferRW, rayID, vec4( outRgb, outAlpha ) );
+					writeRayDirFlags( rayBufferRW, rayID, direction, flags.bitAnd( uint( ~ RAY_FLAG.ACTIVE ) ) );
+					rngBufferRW.element( rayID ).assign( rngState );
+					Return();
+
+				} );
+
+			} );
+
+		} );
+
 		If( hitDist.greaterThan( MISS_DIST ), () => {
 
 			If( enableEnvironmentLight, () => {
@@ -143,11 +260,12 @@ export function buildShadeKernel( params ) {
 				// Ground projection bends the primary ray's background lookup onto a
 				// projected sphere+disk so the lower env hemisphere reads as a ground
 				// plane. Primary ray only; secondary bounces see the raw envmap as a light.
+				// Shared helper (also used by the shadow catcher) keeps the two in lockstep.
 				const envDir = direction.toVar();
-				If( bounceIndex.equal( 0 ).and( groundProjectionEnabled ), () => {
+				If( bounceIndex.equal( 0 ), () => {
 
-					envDir.assign( getGroundProjectedDirection(
-						origin, direction, groundProjectionRadius, groundProjectionHeight,
+					envDir.assign( groundProjectedEnvDir(
+						origin, direction, groundProjectionEnabled, groundProjectionRadius, groundProjectionHeight, groundProjectionLevel,
 					) );
 
 				} );
@@ -560,10 +678,25 @@ export function buildShadeKernel( params ) {
 					const prevBouncePdf = readRayPdf( rayBufferRW, rayID );
 					If( prevBouncePdf.greaterThan( 0.0 ), () => {
 
-						const lightPdf = calculateEmissiveLightPdf(
-							int( hitTriIdx ), hitDist, direction, origin,
-							triangleBuffer, materialBuffer, emissiveTotalPower,
-						);
+						// MIS partner pdf MUST match the actual NEE sampler: re-walk the Light BVH descent
+						// when it is active, else use the flat-CDF pdf. Mismatching them breaks MIS
+						// partition-of-unity → a real bias (see calculateLightBVHPdf).
+						const lightPdf = float( 0.0 ).toVar();
+						If( lightBVHNodeCount.greaterThan( int( 0 ) ), () => {
+
+							lightPdf.assign( calculateLightBVHPdf(
+								int( hitTriIdx ), hitDist, direction, origin,
+								lightBuffer, emissiveVec4Offset, reverseMapVec4Offset, triangleBuffer,
+							) );
+
+						} ).Else( () => {
+
+							lightPdf.assign( calculateEmissiveLightPdf(
+								int( hitTriIdx ), hitDist, direction, origin,
+								triangleBuffer, materialBuffer, emissiveTotalPower,
+							) );
+
+						} );
 						emissiveMISWeight.assign( powerHeuristic( { pdf1: prevBouncePdf, pdf2: lightPdf } ) );
 
 					} );
@@ -674,7 +807,7 @@ export function buildShadeKernel( params ) {
 
 		} );
 
-		const directLight = calculateDirectLightingUnified(
+		const directLight = DirectLightingDual.wrap( calculateDirectLightingUnified(
 			hitPoint, N, material, V,
 			brdfDir, brdfPdf, brdfValue,
 			bounceIndex, rngState,
@@ -687,7 +820,8 @@ export function buildShadeKernel( params ) {
 			envCDFTexture,
 			envTotalSum, envCompensationDelta, envResolution,
 			enableEnvironmentLight,
-		);
+			tslBool( false ), // wantUnoccluded: false on real surfaces — dead-codes the unoccluded sum
+		) ).shadowed.toVar();
 
 		const giScale = select( bounceIndex.greaterThan( 0 ), globalIlluminationIntensity, float( 1.0 ) );
 		// Per-term firefly suppression (megakernel parity: PathTracerCore.js:1164) — wrap the direct-light add

package/src/TSL/Struct.js

@@ -73,6 +73,14 @@ export const ShadowMaterial = struct( {
 	albedoTransform: 'mat3',
 } );
 
+// Dual direct-lighting result: shadowed (the normal NEE estimate) + unoccluded
+// (same estimator with visibility forced to 1). Used by the shadow catcher to
+// derive a shadow ratio = luma(shadowed) / luma(unoccluded).
+export const DirectLightingDual = struct( {
+	shadowed: 'vec3',
+	unoccluded: 'vec3',
+} );
+
 export const Sphere = struct( {
 	position: 'vec3',
 	radius: 'float',

package/src/managers/UniformManager.js

@@ -188,6 +188,9 @@ export class UniformManager {
 		ub( 'groundProjectionEnabled', DEFAULT_STATE.groundProjectionEnabled );
 		u( 'groundProjectionRadius', DEFAULT_STATE.groundProjectionRadius, 'float' );
 		u( 'groundProjectionHeight', DEFAULT_STATE.groundProjectionHeight, 'float' );
+		u( 'groundProjectionLevel', DEFAULT_STATE.groundProjectionLevel, 'float' );
+		ub( 'enableGroundCatcher', DEFAULT_STATE.enableGroundCatcher );
+		u( 'groundCatcherHeight', DEFAULT_STATE.groundCatcherHeight, 'float' );
 
 		// Sun parameters
 		u( 'sunDirection', new Vector3( 0, 1, 0 ), 'vec3' );
@@ -242,6 +245,10 @@ export class UniformManager {
 		// Offset (in vec4 elements) within the packed light buffer where emissive
 		// triangle data starts. Equals lightBVHNodeCount * LBVH_STRIDE; computed on upload.
 		u( 'emissiveVec4Offset', 0, 'int' );
+		// Offset (in vec4 elements) within the packed light buffer where the per-triangle
+		// bit-trail map starts (4 trails packed per vec4); computed on upload. Used by the
+		// bounce-hit MIS path to re-walk the Light BVH descent pdf.
+		u( 'reverseMapVec4Offset', 0, 'int' );
 
 		// Render mode
 		u( 'renderMode', DEFAULT_STATE.renderMode, 'int' );