rayzee 7.2.1 → 7.4.0

package/src/TSL/ShadeKernel.js

@@ -6,15 +6,17 @@
 
 import {
 	Fn, float, vec2, vec3, vec4, int, uint,
-	If, normalize, max, exp, log, clamp, dot, length, select,
+	bool as tslBool,
+	If, Loop, normalize, max, exp, log, clamp, dot, length, select,
 	instanceIndex,
 	sampler,
 	atomicAdd, atomicLoad, uintBitsToFloat,
 	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';
@@ -23,7 +25,7 @@ import { traverseBVHShadow } from './BVHTraversal.js';
 import { handleMaterialTransparency, MaterialInteractionResult } from './MaterialTransmission.js';
 import { sampleChromaticCollision, sampleHenyeyGreenstein, subsurfaceCoefficients, CollisionSample, MediumCoeffs } from './Subsurface.js';
 import { calculateIndirectLighting } from './LightsIndirect.js';
-import { IndirectLightingResult } from './LightsCore.js';
+import { IndirectLightingResult, sampleCone } from './LightsCore.js';
 import { regularizePathContribution, generateSampledDirection, computeNDCDepth, handleRussianRoulette } from './PathTracerCore.js';
 import { getImportanceSamplingInfo } from './MaterialProperties.js';
 import { sampleClearcoat, ClearcoatResult } from './Clearcoat.js';
@@ -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,
@@ -79,7 +91,7 @@ export function buildShadeKernel( params ) {
 		spotLightsBuffer, numSpotLights,
 		maxBounceCount, maxSubsurfaceSteps,
 		currentBounce, // loop iteration = path length (advances on free bounces); drives RR/firefly/giScale
-		transparentBackground, backgroundIntensity, showBackground,
+		transparentBackground, backgroundIntensity, backgroundColor, backgroundBlurriness, backgroundBlurSamples, showBackground,
 		globalIlluminationIntensity,
 		cameraProjectionMatrix, cameraViewMatrix,
 		fireflyThreshold, frame, resolution,
@@ -87,10 +99,45 @@ export function buildShadeKernel( params ) {
 		emissiveBoost, totalTriangleCount, enableEmissiveTriangleSampling,
 		lightBVHNodeCount, reverseMapVec4Offset,
 		maxRayCount,
+		// Aux G-buffer (normal/depth/albedo + surface ID) feeds only the denoiser/OIDN MRT. Gated by a
+		// live uniform (1 = denoiser on) so the wavefront skips these writes when nothing consumes them.
+		auxGBufferEnabled,
 	} = params;
 
+	const auxOn = auxGBufferEnabled.greaterThan( uint( 0 ) );
+
 	const useEmissiveNEE = lightBuffer !== undefined;
 
+	// Stochastic cone-jitter blur of an env backdrop lookup. Plain JS inliner (NOT a Fn — an rng Fn-param
+	// would freeze; see TSL pitfalls) so it mutates the caller's rngState .toVar() directly. Shared by the
+	// miss branch and the shadow catcher so their blur stays in lockstep (no horizon seam). normalize() the
+	// center direction — ground projection can return a non-unit vector, which would skew sampleCone's basis.
+	// Clamp the tap count to ≥1 so a 0 forced via the engine API can't produce a 0/0 NaN backdrop.
+	const sampleEnvBlurred = ( centerDir, halfAngle, samples, rng ) => {
+
+		const axis = normalize( centerDir ).toVar();
+		const n = max( samples, int( 1 ) ).toVar();
+		const acc = vec3( 0.0 ).toVar();
+		Loop( { start: int( 0 ), end: n, type: 'int', condition: '<' }, () => {
+
+			// per-component .toVar(): vec2(RandomValue, RandomValue) would collapse to u==v (TSL pitfall)
+			const u1 = RandomValue( rng ).toVar();
+			const u2 = RandomValue( rng ).toVar();
+			const jDir = sampleCone( axis, halfAngle, vec2( u1, u2 ) ).toVar();
+			acc.addAssign( sampleEnvironment( {
+				tex: envTexture,
+				samp: sampler( envTexture ),
+				direction: jDir,
+				environmentMatrix: envMatrix,
+				environmentIntensity,
+				enableEnvironmentLight: float( 1.0 ),
+			} ).xyz );
+
+		} );
+		return acc.div( float( n ) );
+
+	};
+
 	const computeFn = Fn( () => {
 
 		const threadIdx = instanceIndex;
@@ -113,13 +160,19 @@ export function buildShadeKernel( params ) {
 
 		} );
 
+		// Backdrop-view = the ray still travels the original camera direction (only alpha/transparent passthrough
+		// since the camera, REDIRECTED still clear). Captured at ARRIVAL (before the opaque/redirect bitOr below)
+		// so it stays valid for both the miss branch and the emissive-hit scale. This — not bounceIndex==0 — is
+		// the correct "is the env/emitter here a direct view" test, so env/emitters through alpha-cutout holes
+		// are treated like the open backdrop, not a GI bounce.
+		const isBackdropView = flags.bitAnd( uint( RAY_FLAG.REDIRECTED ) ).equal( uint( 0 ) ).toVar();
+
 		const origin = readRayOrigin( rayBufferRW, rayID ).toVar();
 		const direction = readRayDirection( rayBufferRW, rayID ).toVar();
 		const throughput = readRayThroughput( rayBufferRW, rayID ).toVar();
 		const currentRadiance = readRayRadiance( rayBufferRW, rayID ).toVar();
-		// pixelIndex + sampleIndex are derived from rayID (= subSample*maxRaysPerSample + pixelIndex; GenerateKernel.js:64), not stored.
-		const maxRaysPerSample = uint( resolution.x ).mul( uint( resolution.y ) ).toVar();
-		const pixelIndex = rayID.mod( maxRaysPerSample );
+		// One ray per pixel: rayID is the pixel index.
+		const pixelIndex = rayID;
 		const rngState = rngBufferRW.element( rayID ).toVar();
 
 		const hitDist = readHitDistance( hitBufferRO, rayID ).toVar();
@@ -134,43 +187,186 @@ export function buildShadeKernel( params ) {
 		// path length = loop iteration (advances every bounce incl. transmissive/SSS); drives RR/firefly/giScale/MIS. Megakernel: loop counter i.
 		const bounceIndex = int( currentBounce ).toVar();
 		const sssSteps = readSssSteps( rayBufferRW, rayID ).toVar();
-		const sampleIndex = int( rayID.div( maxRaysPerSample ) ).toVar();
 
-		If( hitDist.greaterThan( MISS_DIST ), () => {
+		// ── 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();
+					// force-enable the sampler (pass 1.0): the visible backdrop is decoupled from env-lighting,
+					// so the catcher continues the HDRI even when the environment isn't used as a light.
+					// Only sample the env where it's actually shown as the catcher backdrop (showBackground); in
+					// color/transparent mode the catcher composites over backgroundColor / alpha, so the (up to
+					// N-tap) env work would be discarded. Blur matches the miss branch via the shared helper.
+					const envBehind = vec3( 0.0 ).toVar();
+					If( showBackground, () => {
+
+						If( backgroundBlurriness.greaterThan( 0.0 ), () => {
+
+							envBehind.assign( sampleEnvBlurred( catcherEnvDir, backgroundBlurriness.mul( 1.3 ), backgroundBlurSamples, rngState ) );
+
+						} ).Else( () => {
+
+							envBehind.assign( sampleEnvironment( {
+								tex: envTexture,
+								samp: sampler( envTexture ),
+								direction: catcherEnvDir,
+								environmentMatrix: envMatrix,
+								environmentIntensity,
+								enableEnvironmentLight: float( 1.0 ),
+							} ).xyz );
+
+						} );
+
+					} );
+					// Background mode: env image (showBackground) or the solid backgroundColor (color mode).
+					const bgColor = select( showBackground, envBehind.mul( backgroundIntensity ), backgroundColor );
+					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( auxOn, () => {
+
+						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( enableEnvironmentLight, () => {
+		If( hitDist.greaterThan( MISS_DIST ), () => {
 
-				// 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.
+			// Background and environment-lighting are decoupled (independent axes):
+			//  • Visible backdrop: a PRIMARY ray draws the env image only when showBackground — regardless
+			//    of enableEnvironmentLight (so you can show the HDRI without it lighting the scene).
+			//  • Env as a light: SECONDARY bounces add the env (implicit MIS hit) only when enableEnvironmentLight.
+			// Backdrop-view = the ray still travels the original camera direction (only alpha/transparent
+			// passthrough since the camera). This — NOT bounceIndex==0 — is the correct test for "the env here
+			// is the direct backdrop", so env seen through alpha-cutout foliage holes is treated identically to
+			// the open sky (blur, intensity, show/hide, color-mode, ground projection all match).
+			// isBackdropView was captured at arrival (above) so it survives the REDIRECTED bitOr on opaque hits.
+			const wantBackdrop = isBackdropView.and( showBackground ); // draw env image as backdrop
+			const wantEnvLight = isBackdropView.not().and( enableEnvironmentLight ); // env as light on redirected bounces
+
+			If( wantBackdrop.or( wantEnvLight ), () => {
+
+				// Ground projection bends the backdrop-view env lookup onto a projected sphere+disk so the lower
+				// env hemisphere reads as a ground plane. Backdrop-view only (incl. through alpha-cutout holes,
+				// since they keep the camera direction); redirected bounces see the raw envmap as a light. The
+				// shared helper (also used by the shadow catcher) keeps the two in lockstep.
 				const envDir = direction.toVar();
-				If( bounceIndex.equal( 0 ).and( groundProjectionEnabled ), () => {
+				If( isBackdropView, () => {
 
-					envDir.assign( getGroundProjectedDirection(
-						origin, direction, groundProjectionRadius, groundProjectionHeight,
+					envDir.assign( groundProjectedEnvDir(
+						origin, direction, groundProjectionEnabled, groundProjectionRadius, groundProjectionHeight, groundProjectionLevel,
 					) );
 
 				} );
 
-				const envColor = sampleEnvironment( {
-					tex: envTexture,
-					samp: sampler( envTexture ),
-					direction: envDir,
-					environmentMatrix: envMatrix,
-					environmentIntensity,
-					enableEnvironmentLight,
-				} ).toVar();
+				// Backdrop-view rays blur the env (cone jitter, shared helper); redirected env-light bounces take
+				// the sharp Else. force-enable the sampler (pass 1.0): the wantBackdrop/wantEnvLight gate above
+				// already decided visibility, so the backdrop shows the HDRI even when env-lighting is off.
+				// Direction-space jitter keeps the blur free of equirect pole/seam artifacts; accumulation
+				// converges the noise. Opt-in — blurriness 0 takes the sharp Else (zero cost).
+				const envColor = vec3( 0.0 ).toVar();
+				If( isBackdropView.and( backgroundBlurriness.greaterThan( 0.0 ) ), () => {
+
+					envColor.assign( sampleEnvBlurred( envDir, backgroundBlurriness.mul( 1.3 ), backgroundBlurSamples, rngState ) );
 
-				// Hide the background for primary rays when showBackground is off; secondary bounces still see the envmap as a light.
-				If( bounceIndex.equal( 0 ).and( showBackground.not() ), () => {
+				} ).Else( () => {
 
-					envColor.assign( vec4( 0.0 ) );
+					envColor.assign( sampleEnvironment( {
+						tex: envTexture,
+						samp: sampler( envTexture ),
+						direction: envDir,
+						environmentMatrix: envMatrix,
+						environmentIntensity,
+						enableEnvironmentLight: float( 1.0 ),
+					} ).xyz );
 
 				} );
 
 				// MIS weight for implicit env hit — prevents double-counting with NEE
 				const envMisWeight = float( 1.0 ).toVar();
-				If( bounceIndex.greaterThan( 0 ).and( useEnvMapIS ), () => {
+				If( isBackdropView.not().and( useEnvMapIS ), () => {
 
 					const prevBouncePdf = readRayPdf( rayBufferRW, rayID );
 					If( prevBouncePdf.greaterThan( 0.0 ), () => {
@@ -189,18 +385,23 @@ export function buildShadeKernel( params ) {
 
 				} );
 
-				const envGiScale = select( bounceIndex.greaterThan( 0 ), globalIlluminationIntensity, float( 1.0 ) );
-				const envScale = select( bounceIndex.equal( 0 ), backgroundIntensity, envMisWeight.mul( envGiScale ) );
+				const envGiScale = select( isBackdropView.not(), globalIlluminationIntensity, float( 1.0 ) );
+				const envScale = select( isBackdropView, backgroundIntensity, envMisWeight.mul( envGiScale ) );
 
 				// Firefly-suppress the env contribution (megakernel parity: PathTracerCore.js:780). Without
 				// this, indirect bounces escaping to a bright environment are unsuppressed spikes that OIDN
 				// smears into white blobs. The miss branch Return()s before the hit-branch clamp (~line 712),
 				// so it must be applied here.
+				// Firefly path length: a backdrop view (incl. through alpha-cutout holes) is a DIRECT view of the
+				// sky → use 0 (loosest clamp, same as the open-sky bounce-0 backdrop) so a bright HDRI sun doesn't
+				// read dimmer behind foliage cutouts than beside them. Only redirected GI bounces get the tighter
+				// path-length threshold.
+				const fireflyPathLen = select( isBackdropView, float( 0.0 ), float( bounceIndex ) );
 				currentRadiance.assign( vec4(
 					currentRadiance.xyz.add(
 						regularizePathContribution(
-							throughput.mul( envColor.xyz ).mul( envScale ),
-							float( bounceIndex ), fireflyThreshold, int( frame ),
+							throughput.mul( envColor ).mul( envScale ),
+							fireflyPathLen, fireflyThreshold, int( frame ),
 						),
 					),
 					currentRadiance.w
@@ -208,6 +409,18 @@ export function buildShadeKernel( params ) {
 
 			} );
 
+			// Solid-color backdrop ('color' mode): a primary ray that doesn't show the env image and isn't
+			// transparent fills with backgroundColor (default black). Tinted by throughput so it reads
+			// correctly behind colored glass, matching the env-backdrop path.
+			If( isBackdropView.and( showBackground.not() ).and( transparentBackground.not() ), () => {
+
+				currentRadiance.assign( vec4(
+					currentRadiance.xyz.add( throughput.mul( backgroundColor ) ),
+					currentRadiance.w
+				) );
+
+			} );
+
 			// Transparent-bg alpha: see-through only if the ray escaped WITHOUT ever hitting opaque
 			// geometry (megakernel parity: PathTracerCore.js:784). A secondary bounce off an opaque
 			// surface that escapes to env keeps alpha 1 (HAS_HIT_OPAQUE set), so glass-in-front-of-an-
@@ -284,6 +497,8 @@ export function buildShadeKernel( params ) {
 					throughput.divAssign( rrP );
 
 					// free-bounce continuation: ray stays in the same medium, so medium stack + coeffs persist
+					// SSS scatter changes direction → no longer the direct backdrop view.
+					flags.assign( flags.bitOr( uint( RAY_FLAG.REDIRECTED ) ) );
 					writeRayOriginMeta( rayBufferRW, rayID, scatterPoint, cameraDepth, sssSteps );
 					writeRayDirFlags( rayBufferRW, rayID, newDir, flags );
 					// Free bounce: preserve prevBouncePdf (megakernel leaves it untouched across SSS scatter,
@@ -359,26 +574,22 @@ export function buildShadeKernel( params ) {
 		} );
 
 		// first-hit MRT data (bounce 0 only)
-		If( bounceIndex.equal( 0 ), () => {
+		If( bounceIndex.equal( 0 ).and( auxOn ), () => {
 
 			const linearDepth = computeNDCDepth( {
 				worldPos: hitPoint,
 				cameraProjectionMatrix,
 				cameraViewMatrix,
 			} );
-			// G-buffer is per-pixel — only sub-sample 0 writes it (FinalWrite reads sub-sample 0). writeGBuffer half-packs (normal/depth/albedo).
+			// G-buffer is per-pixel (rayID == pixelIndex). writeGBuffer half-packs (normal/depth/albedo).
 			// Write the primary DEPTH now with the miss-default aux; the real normal/albedo are captured below
 			// (aux-extend) and may extend through specular surfaces (gap #9). Glass rays Return at the transparency
 			// block before that capture, so a glass-then-escape pixel keeps this default aux — megakernel parity
 			// (objectNormal/objectColor stay at their init for transmissive-then-miss).
-			If( sampleIndex.equal( int( 0 ) ), () => {
-
-				writeGBuffer( gBufferRW, pixelIndex, vec3( 0.0, 0.0, 1.0 ), linearDepth, vec3( 0.0 ) );
-				// Persist the primary-hit surface ID (Tier-1 A-SVGF correlated re-projection). Hit-only
-				// branch (misses Return above), so this marks the pixel valid; bary from the bounce-0 hit.
-				writeGBufferSurfaceID( gBufferRW, pixelIndex, hitTriIdx, readHitMeshIndex( hitBufferRO, rayID ), hitUV.x, hitUV.y, uint( 1 ) );
-
-			} );
+			writeGBuffer( gBufferRW, pixelIndex, vec3( 0.0, 0.0, 1.0 ), linearDepth, vec3( 0.0 ) );
+			// Persist the primary-hit surface ID (Tier-1 A-SVGF correlated re-projection). Hit-only
+			// branch (misses Return above), so this marks the pixel valid; bary from the bounce-0 hit.
+			writeGBufferSurfaceID( gBufferRW, pixelIndex, hitTriIdx, readHitMeshIndex( hitBufferRO, rayID ), hitUV.x, hitUV.y, uint( 1 ) );
 
 		} );
 
@@ -522,6 +733,14 @@ export function buildShadeKernel( params ) {
 
 			// SSS = free bounce (depth unchanged); transmission advances camera-bounce depth.
 			// Transmissive / alpha-skip / SSS-boundary are all FREE bounces — they do NOT advance camera depth (megakernel parity, gap #4). cameraDepth advances only on opaque scatter (below).
+			// Backdrop-view survives a pure alpha/transparent passthrough (direction unchanged) but is cleared by
+			// any redirection (refraction/reflection/SSS boundary), so env through a leaf hole stays the blurred
+			// backdrop while env through glass becomes sharp redirected light.
+			If( interaction.isAlphaSkip.not(), () => {
+
+				flags.assign( flags.bitOr( uint( RAY_FLAG.REDIRECTED ) ) );
+
+			} );
 			writeRayOriginMeta( rayBufferRW, rayID, newOrigin, cameraDepth, sssSteps );
 			writeRayDirFlags( rayBufferRW, rayID, interaction.direction, flags );
 			// Free bounce: preserve prevBouncePdf (megakernel keeps the last opaque-scatter pdf across
@@ -539,12 +758,17 @@ export function buildShadeKernel( params ) {
 		// PathTracerCore.js:1042). Flag the chain so a later env-escape keeps alpha 1 (the gate in the
 		// miss branch). Alpha itself already defaults to 1 from Generate in transparent-bg mode, so there
 		// is nothing to set here — a ray dying inside geometry (SSS walk) stays solid without reaching this.
-		flags.assign( flags.bitOr( uint( RAY_FLAG.HAS_HIT_OPAQUE ) ) );
+		// Hit opaque geometry: set HAS_HIT_OPAQUE and mark REDIRECTED (this is a real surface scatter,
+		// so any later env-escape is redirected light, not the direct backdrop). Single positive bitOr.
+		flags.assign( flags.bitOr( uint( RAY_FLAG.HAS_HIT_OPAQUE | RAY_FLAG.REDIRECTED ) ) );
 
 		const emissive = matSamples.emissive.toVar();
 		If( length( emissive ).greaterThan( 0.0 ), () => {
 
-			const emissiveGiScale = select( bounceIndex.greaterThan( 0 ), globalIlluminationIntensity, float( 1.0 ) );
+			// Key on backdrop-view (not bounceIndex>0) so an emitter seen DIRECTLY through an alpha-cutout hole
+			// renders at full intensity (1.0) like a direct view, consistent with env-through-hole — instead of
+			// being GI-scaled as if it were an indirect bounce. (MIS below already self-guards via prevBouncePdf.)
+			const emissiveGiScale = select( isBackdropView.not(), globalIlluminationIntensity, float( 1.0 ) );
 
 			// MIS weight vs emissive-triangle NEE (megakernel parity: PathTracerCore.js:1117). On a secondary
 			// hit (bounceIndex>0) the prior bounce's NEE also sampled this emitter — power-heuristic balances the
@@ -616,7 +840,7 @@ export function buildShadeKernel( params ) {
 		// visible (the surface reflected in a mirror / seen behind glass), not the specular surface. Glass
 		// Returns at the transparency block above, so its aux is replaced by the surface behind it. Depth
 		// stays at the primary hit (read back + re-packed; the snorm depth re-pack is idempotent — no drift).
-		If( sampleIndex.equal( int( 0 ) ).and( flags.bitAnd( uint( RAY_FLAG.AUX_LOCKED ) ).equal( uint( 0 ) ) ), () => {
+		If( flags.bitAnd( uint( RAY_FLAG.AUX_LOCKED ) ).equal( uint( 0 ) ).and( auxOn ), () => {
 
 			const primaryDepth = gbDecodeNormalDepth( readGBuffer( gBufferRW, pixelIndex ) ).w;
 			writeGBuffer( gBufferRW, pixelIndex, N, primaryDepth, albedo.xyz );
@@ -636,13 +860,13 @@ export function buildShadeKernel( params ) {
 			material.clearcoat, material.emissive, material.subsurface,
 		) ).toVar();
 
-		// STBN keyed on (pixel, bounceIndex, frame); sampleIndex gives each sub-sample a distinct tap
+		// STBN keyed on (pixel, bounceIndex, frame).
 		const _resX = int( resolution.x ).toVar();
 		const _pixelCoord = vec2(
 			float( int( pixelIndex ).mod( _resX ) ).add( 0.5 ),
 			float( int( pixelIndex ).div( _resX ) ).add( 0.5 ),
 		);
-		const xi = getRandomSample( _pixelCoord, sampleIndex, bounceIndex, rngState, int( - 1 ), resolution, frame ).toVar();
+		const xi = getRandomSample( _pixelCoord, int( 0 ), bounceIndex, rngState, int( - 1 ), resolution, frame ).toVar();
 		const emptyWeights = BRDFWeights( {
 			specular: float( 0.0 ), diffuse: float( 0.0 ), sheen: float( 0.0 ),
 			clearcoat: float( 0.0 ), transmission: float( 0.0 ), iridescence: float( 0.0 ),
@@ -689,7 +913,7 @@ export function buildShadeKernel( params ) {
 
 		} );
 
-		const directLight = calculateDirectLightingUnified(
+		const directLight = DirectLightingDual.wrap( calculateDirectLightingUnified(
 			hitPoint, N, material, V,
 			brdfDir, brdfPdf, brdfValue,
 			bounceIndex, rngState,
@@ -702,7 +926,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/DenoisingManager.js

@@ -365,6 +365,11 @@ export class DenoisingManager extends EventDispatcher {
 
 		}
 
+		// PathTracer's aux MRT (normalDepth + albedo) is consumed by the real-time denoisers (ASVGF/
+		// BilateralFilter read albedo; ASVGF/SSRC/EdgeFilter read normalDepth) and by OIDN (reads the
+		// MRT read-targets directly). When none are active the wavefront skips those writes entirely.
+		s.pathTracer?.setAuxGBufferEnabled?.( normalNeeded || !! this.denoiser?.enabled );
+
 	}
 
 	// ── Render Completion Chain ───────────────────────────────────
@@ -595,6 +600,8 @@ export class DenoisingManager extends EventDispatcher {
 	setOIDNEnabled( enabled ) {
 
 		if ( this.denoiser ) this.denoiser.enabled = enabled;
+		// OIDN reads the PathTracer aux MRT; re-sync so the wavefront produces it while OIDN is on.
+		this._syncGBufferStages();
 
 	}
 

package/src/managers/UniformManager.js

@@ -6,7 +6,7 @@
  */
 
 import { uniform, uniformArray } from 'three/tsl';
-import { Vector2, Matrix4, Vector3 } from 'three';
+import { Vector2, Matrix4, Vector3, Color } from 'three';
 import { samplingTechniqueUniform } from '../TSL/Random.js';
 import { ENGINE_DEFAULTS as DEFAULT_STATE } from '../EngineDefaults.js';
 
@@ -161,7 +161,6 @@ export class UniformManager {
 		// Frame and sampling
 		u( 'frame', 0, 'uint' );
 		u( 'maxBounces', DEFAULT_STATE.bounces, 'int' );
-		u( 'samplesPerPixel', DEFAULT_STATE.samplesPerPixel, 'int' );
 		u( 'maxSamples', DEFAULT_STATE.maxSamples, 'int' );
 		u( 'transmissiveBounces', DEFAULT_STATE.transmissiveBounces, 'int' );
 		u( 'maxSubsurfaceSteps', DEFAULT_STATE.maxSubsurfaceSteps, 'int' );
@@ -177,6 +176,9 @@ export class UniformManager {
 		// Environment
 		u( 'environmentIntensity', DEFAULT_STATE.environmentIntensity, 'float' );
 		u( 'backgroundIntensity', DEFAULT_STATE.backgroundIntensity, 'float' );
+		u( 'backgroundColor', new Color( 0, 0, 0 ), 'color' ); // linear; solid backdrop in 'color' mode
+		u( 'backgroundBlurriness', DEFAULT_STATE.backgroundBlurriness, 'float' );
+		u( 'backgroundBlurSamples', DEFAULT_STATE.backgroundBlurSamples, 'int' );
 		ub( 'showBackground', DEFAULT_STATE.showBackground );
 		ub( 'transparentBackground', DEFAULT_STATE.transparentBackground );
 		ub( 'enableEnvironment', DEFAULT_STATE.enableEnvironment );
@@ -188,6 +190,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' );

package/src/managers/VideoRenderManager.js

@@ -277,7 +277,6 @@ export class VideoRenderManager {
 		return {
 			maxSamples: app.settings.get( 'maxSamples' ),
 			maxBounces: app.settings.get( 'maxBounces' ),
-			samplesPerPixel: app.settings.get( 'samplesPerPixel' ),
 			transmissiveBounces: app.settings.get( 'transmissiveBounces' ),
 			renderMode: app.stages.pathTracer?.renderMode?.value,
 			controlsEnabled: app.cameraManager.controls?.enabled,
@@ -300,7 +299,6 @@ export class VideoRenderManager {
 		app.settings.setMany( {
 			maxSamples: state.maxSamples,
 			maxBounces: state.maxBounces,
-			samplesPerPixel: state.samplesPerPixel,
 			transmissiveBounces: state.transmissiveBounces,
 		}, { silent: true } );