rayzee 11.7.0 → 11.9.0

package/src/Stages/NRD.js

@@ -8,7 +8,7 @@ import { createStorageTexture } from '../Processor/StorageTexturePool.js';
 import { sanitizeRGB, sanitize1, FP16_MAX } from '../TSL/Common.js';
 import { cameraRayPoint, cameraRayUniforms, isOrthographic } from '../TSL/CameraRay.js';
 import {
-	NRD_DEFAULTS, NRD_HIT_DIST_A, NRD_HIT_DIST_B, ALBEDO_EPS, GBUFFER_MISS_THRESHOLD as MISS_THRESHOLD,
+	NRD_DEFAULTS, NRD_HIT_DIST_A, NRD_HIT_DIST_B, GBUFFER_MISS_THRESHOLD as MISS_THRESHOLD,
 } from './DenoiserSettings.js';
 
 const NRD_EPS = 1e-6;
@@ -25,6 +25,12 @@ const FIREFLY_RADIUS_SCALE = 0.1;
 const FIREFLY_FAST_RELATIVE_INTENSITY = 4.0;
 const ALMOST_ZERO_ANGLE_COS = Math.cos( 89.0 * Math.PI / 180.0 );
 const CATROM_SHARPNESS = 0.5;
+// The input fuses diffuse and specular, so it is demodulated by both lobes' albedo (NRD_MaterialFactors summed).
+const SPECULAR_F0 = 0.04;
+// A sample this dark reflects nothing diffusely: it carries emission, the environment or specular alone.
+const BLACK_ALBEDO = 0.1 * SPECULAR_F0;
+// Carried past the pre-pass in dataT.z, above the four occlusion bits.
+const BLACK_BIT = 16;
 const WG_SIZE = 16;
 
 const PASS = {
@@ -111,6 +117,12 @@ const clampNegativeToZero = ( v ) => vec4( linearToYCoCg( yCoCgToLinear( v.xyz )
 const stdDev = ( m1, m2 ) => sqrt( m2.sub( m1.mul( m1 ) ).abs() );
 // rotator = (cos, sin, -sin, cos)
 const rotate2 = ( rot, v ) => vec2( rot.x.mul( v.x ).add( rot.y.mul( v.y ) ), rot.z.mul( v.x ).add( rot.w.mul( v.y ) ) );
+const demodAlbedo = ( a ) => a.mul( 1.0 - SPECULAR_F0 ).add( SPECULAR_F0 );
+const isBlack = ( a ) => max( a.x, max( a.y, a.z ) ).lessThan( BLACK_ALBEDO );
+const isBlackData = ( data ) => data.z.greaterThan( BLACK_BIT - 0.5 );
+// NormalDepth negates an emitter's roughness, as NRD packs a material ID into its normal-roughness guide.
+const isEmitter = ( guideW ) => guideW.lessThan( 0.0 );
+const guideRoughness = ( guideW ) => guideW.abs().clamp( 0.05, 1.0 );
 const denanify = ( w, s ) => select( w.equal( 0.0 ), vec4( 0.0 ), s );
 
 function hash01( n ) {
@@ -256,7 +268,7 @@ export class NRD extends RenderStage {
 		this._geomPrev = tex();
 		this._stabA = tex(); // .x stabilized luma
 		this._stabB = tex();
-		this._dataT = tex(); // .x fast luma, .y accumSpeed, .z occlusion bits, .w catrom ok
+		this._dataT = tex(); // .x fast luma, .y accumSpeed, .z occlusion bits (+ BLACK_BIT), .w catrom ok
 
 	}
 
@@ -382,6 +394,13 @@ export class NRD extends RenderStage {
 
 	}
 
+	// Taps whose radiance is no estimate of the centre's lighting.
+	_excluded( zs, guideW, tapBlack, centerBlack ) {
+
+		return zs.greaterThanEqual( MISS_THRESHOLD ).or( isEmitter( guideW ) ).or( tapBlack.and( centerBlack.not() ) );
+
+	}
+
 	_bilinear( uv ) {
 
 		const t = uv.mul( vec2( this.resW, this.resH ) ).sub( 0.5 );
@@ -524,11 +543,9 @@ export class NRD extends RenderStage {
 		const inputFrames = this.inputFrames;
 
 		const readSignal = isPre
-			? ( c ) => {
+			? ( c, alb ) => {
 
-				const col = textureLoad( colorTex, c );
-				const alb = textureLoad( albedoTex, c );
-				const lighting = sanitizeRGB( col.xyz.div( max( alb.xyz, vec3( ALBEDO_EPS ) ) ) );
+				const lighting = sanitizeRGB( textureLoad( colorTex, c ).xyz.div( demodAlbedo( alb.xyz ) ) );
 				return vec4( linearToYCoCg( lighting ), sanitize1( alb.w, FP16_MAX ).min( 1.0 ) );
 
 			}
@@ -547,10 +564,12 @@ export class NRD extends RenderStage {
 				const isSky = dist.greaterThanEqual( MISS_THRESHOLD );
 				const sn = textureLoad( snTex, coord ).toVar();
 				const N = normalize( sn.xyz.mul( 2.0 ).sub( 1.0 ) ).toVar();
-				const roughness = sn.w.clamp( 0.05, 1.0 ).toVar();
+				const roughness = guideRoughness( sn.w ).toVar();
 				const viewZ = float( MISS_THRESHOLD ).toVar();
 
-				const result = readSignal( coord ).toVar();
+				const albedo = isPre ? textureLoad( albedoTex, coord ) : null;
+				const black = ( isPre ? isBlack( albedo ) : isBlackData( textureLoad( dataTex, coord ) ) ).toVar();
+				const result = readSignal( coord, albedo ).toVar();
 
 				If( isSky.not(), () => {
 
@@ -558,7 +577,7 @@ export class NRD extends RenderStage {
 					const X = this._worldPosAt( pixelUv, dist, cwm, cpi ).toVar();
 					viewZ.assign( camView.mul( vec4( X, 1.0 ) ).z.abs() );
 
-					If( maxRadiusU.greaterThan( 0.0 ), () => {
+					If( maxRadiusU.greaterThan( 0.0 ).and( isEmitter( sn.w ).not() ), () => {
 
 						const V = this._viewVector( X, camPos, this.viewVector );
 						const NoV = dot( N, V ).abs().toVar();
@@ -625,11 +644,13 @@ export class NRD extends RenderStage {
 
 							const angle = acosApproxPositive( dot( N, Ns ) );
 							w.mulAssign( weightSmooth( angle, normalParam, float( 0.0 ) ) );
-							w.mulAssign( weightSmooth( sns.w, roughParams.x, roughParams.y ) );
+							w.mulAssign( weightSmooth( guideRoughness( sns.w ), roughParams.x, roughParams.y ) );
 							w.mulAssign( weightSmooth( dot( N, Xs ), geomParams.x, geomParams.y ) );
-							w.assign( select( zs.greaterThanEqual( MISS_THRESHOLD ), float( 0.0 ), w ) );
+							const albS = isPre ? textureLoad( albedoTex, pos ) : null;
+							const blackS = isPre ? isBlack( albS ) : isBlackData( textureLoad( dataTex, pos ) );
+							w.assign( select( this._excluded( zs, sns.w, blackS, black ), float( 0.0 ), w ) );
 
-							const s = denanify( w, readSignal( pos ) );
+							const s = denanify( w, readSignal( pos, albS ) );
 							w.mulAssign( minHitDistWeight.add( weightExp( s.w, hdParams.x, hdParams.y ) ) );
 
 							sum.addAssign( w );
@@ -675,6 +696,7 @@ export class NRD extends RenderStage {
 		const geomTex = this._nGeom;
 		const outTex = this._tmpB;
 		const dataOut = this._dataT;
+		const albedoTex = this._albedoTexNode;
 		const camView = this.camView;
 		const prevCamView = this.prevCamView;
 		const camPos = this.camPos;
@@ -709,7 +731,7 @@ export class NRD extends RenderStage {
 
 				const sn = textureLoad( snTex, coord );
 				const N = normalize( sn.xyz.mul( 2.0 ).sub( 1.0 ) ).toVar();
-				const roughness = sn.w.clamp( 0.05, 1.0 ).toVar();
+				const roughness = guideRoughness( sn.w ).toVar();
 
 				const pixelUv = this._pixelUv( gx, gy );
 				const X = this._worldPosAt( pixelUv, dist, cwm, cpi ).toVar();
@@ -806,7 +828,8 @@ export class NRD extends RenderStage {
 				const fastClamped = min( fast, history.x.mul( maxRel ).mul( FIREFLY_FAST_RELATIVE_INTENSITY ) );
 				fast.assign( mix( fast, fastClamped, aff ) );
 
-				textureStore( dataOut, uvec, vec4( fast, accumSpeed, fbits, select( allowCatRom, float( 1.0 ), float( 0.0 ) ) ) ).toWriteOnly();
+				const blackBit = select( isBlack( textureLoad( albedoTex, coord ) ), float( BLACK_BIT ), float( 0.0 ) );
+				textureStore( dataOut, uvec, vec4( fast, accumSpeed, fbits.add( blackBit ), select( allowCatRom, float( 1.0 ), float( 0.0 ) ) ) ).toWriteOnly();
 
 			} );
 
@@ -862,7 +885,7 @@ export class NRD extends RenderStage {
 
 				const sn = textureLoad( snTex, coord );
 				const N = normalize( sn.xyz.mul( 2.0 ).sub( 1.0 ) ).toVar();
-				const roughness = sn.w.clamp( 0.05, 1.0 ).toVar();
+				const roughness = guideRoughness( sn.w ).toVar();
 				const pixelUv = this._pixelUv( gx, gy );
 				const X = this._worldPosAt( pixelUv, dist, cwm, cpi ).toVar();
 				const viewZ = camView.mul( vec4( X, 1.0 ) ).z.abs();
@@ -881,13 +904,16 @@ export class NRD extends RenderStage {
 					.mul( mix( float( 0.25 ).add( sqrt( hitDistFactor ).mul( 0.75 ) ), float( 1.0 ), nonLinear ) );
 				const strideR = round( stride ).toVar();
 
-				If( strideR.notEqual( 0.0 ), () => {
+				const emitter = isEmitter( sn.w ).toVar();
+
+				If( strideR.notEqual( 0.0 ).and( emitter.not() ), () => {
 
 					const normalParam = normalWeightParam( nonLinear, u.lobeAngleFraction, roughness, u.lobeVolumePercent ).toVar();
 					const geomParams = geometryWeightParams( u.planeDistSensitivity, frustumSize, X, N ).toVar();
 					const hdParams = hitDistWeightParams( centerH, nonLinear ).toVar();
 					const relaxedRough = relaxedRoughnessWeightParams( roughness.mul( roughness ), sqrt( u.roughnessFraction ), ROUGHNESS_SENSITIVITY ).toVar();
 
+					const black = isBlackData( data ).toVar();
 					const sumd = float( 1.0 ).add( frameNum ).toVar();
 					diff.mulAssign( sumd );
 
@@ -909,10 +935,12 @@ export class NRD extends RenderStage {
 							const angle = acosApproxPositive( dot( Ns, N ) );
 
 							const w = weightExp( angle, normalParam, float( 0.0 ) ).toVar();
-							w.mulAssign( weightExp( sns.w.mul( sns.w ), relaxedRough.x, relaxedRough.y ) );
-							w.mulAssign( float( 1.0 ).add( textureLoad( dataTex, pos ).y ) );
+							const rs = guideRoughness( sns.w );
+							w.mulAssign( weightExp( rs.mul( rs ), relaxedRough.x, relaxedRough.y ) );
+							const dataS = textureLoad( dataTex, pos );
+							w.mulAssign( float( 1.0 ).add( dataS.y ) );
 							w.mulAssign( weightSmooth( dot( N, Xs ), geomParams.x, geomParams.y ) );
-							w.assign( select( zs.greaterThanEqual( MISS_THRESHOLD ), float( 0.0 ), w ) );
+							w.assign( select( this._excluded( zs, sns.w, isBlackData( dataS ), black ), float( 0.0 ), w ) );
 
 							const s = denanify( w, textureLoad( inTex, pos ) );
 							w.mulAssign( weightExp( s.w, hdParams.x, hdParams.y ) );
@@ -1014,7 +1042,7 @@ export class NRD extends RenderStage {
 
 				}
 
-				textureStore( outTex, uvec, changeLuma( diff, diffLuma ) ).toWriteOnly();
+				textureStore( outTex, uvec, select( emitter, diff, changeLuma( diff, diffLuma ) ) ).toWriteOnly();
 
 			} );
 
@@ -1067,7 +1095,8 @@ export class NRD extends RenderStage {
 
 				} );
 
-				const roughness = textureLoad( snTex, coord ).w.clamp( 0.05, 1.0 );
+				const guideW = textureLoad( snTex, coord ).w;
+				const roughness = guideRoughness( guideW );
 				const pixelUv = this._pixelUv( gx, gy );
 				const mv = textureLoad( motionTex, coord );
 				const smbUv = pixelUv.sub( mv.xy ).toVar();
@@ -1107,7 +1136,7 @@ export class NRD extends RenderStage {
 				m2.divAssign( 9.0 );
 				const sigma = stdDev( m1, m2 ).toVar();
 
-				If( accumSpeed.lessThan( u.historyFixFrameNum ), () => {
+				If( accumSpeed.lessThan( u.historyFixFrameNum ).and( isEmitter( guideW ).not() ), () => {
 
 					diffLuma.assign( min( diffLuma, m1.mul( float( 1.2 ).add( float( 1.0 ).div( accumSpeed.add( 1.0 ) ) ) ) ) );
 
@@ -1145,7 +1174,7 @@ export class NRD extends RenderStage {
 
 				// Alpha stays the path tracer's coverage — Compositor reads it under transparentBackground.
 				const albedo = textureLoad( albedoTex, coord );
-				const lighting = yCoCgToLinear( diff.xyz ).mul( max( albedo.xyz, vec3( ALBEDO_EPS ) ) );
+				const lighting = yCoCgToLinear( diff.xyz ).mul( demodAlbedo( albedo.xyz ) );
 				const out = vec4( lighting, color.w ).toVar();
 
 				If( debugMode.equal( int( 1 ) ), () => {
@@ -1168,7 +1197,7 @@ export class NRD extends RenderStage {
 
 				} ).ElseIf( debugMode.equal( int( 5 ) ), () => {
 
-					out.assign( vec4( vec3( data.z.div( 15.0 ) ), 1.0 ) );
+					out.assign( vec4( vec3( float( bits.bitAnd( uint( 15 ) ) ).div( 15.0 ) ), 1.0 ) );
 
 				} );
 

package/src/Stages/NormalDepth.js

@@ -1,4 +1,4 @@
-import { Fn, vec2, vec4, float, int, uint, uvec2, uvec4, uniform, min, storage, If,
+import { Fn, vec2, vec4, float, int, uint, uvec2, uvec4, uniform, min, max, select, storage, If,
 	textureStore, workgroupId, localId } from 'three/tsl';
 import { RenderTarget, StorageTexture } from 'three/webgpu';
 import { HalfFloatType, RGBAFormat, RedIntegerFormat, UnsignedIntType, NearestFilter, Matrix4, Box2, Vector2 } from 'three';
@@ -7,7 +7,7 @@ import { MAX_STORAGE_TEXTURE_SIZE } from '../Processor/StorageTexturePool.js';
 import { GBUFFER_MISS_DEPTH } from './DenoiserSettings.js';
 import { Ray, HitInfo, RayTracingMaterial, UVCache } from '../TSL/Struct.js';
 import { traverseBVH } from '../TSL/BVHTraversal.js';
-import { cameraRayOf, cameraRayUniforms } from '../TSL/CameraRay.js';
+import { cameraRayOf, cameraRayUniforms, cameraClipDistance } from '../TSL/CameraRay.js';
 import { getMaterial } from '../TSL/Common.js';
 import { computeUVCache, processNormal, processBump, processMetalnessRoughness, triangleUVTangent, buildBucketTextureNodes, refreshBucketTextureNodes } from '../TSL/TextureSampling.js';
 import { withSceneResources } from '../TSL/SceneResources.js';
@@ -31,10 +31,10 @@ import { withSceneResources } from '../TSL/SceneResources.js';
  * map, recomputed from the SAME deterministic hit — no extra ray) so the
  * spatial denoiser's edge-stop can see normal-map detail the flat geometric
  * normal hides. Deterministic ⇒ jitter-free, so it's safe for the gates.
- * Its .w is the sampled material roughness (NRD's normal+roughness guide).
+ * Its .w is the sampled material roughness (NRD's normal+roughness guide), negated on an emitter.
  *
  * Publishes: pathtracer:normalDepth, pathtracer:prevNormalDepth,
- *            pathtracer:shadingNormal (rgb = shading normal·0.5+0.5, a = roughness),
+ *            pathtracer:shadingNormal (rgb = shading normal·0.5+0.5, a = roughness, negative on an emitter),
  *            pathtracer:instanceLeaf (r32uint: the hit's transformed TLAS leaf + 1, 0 = none)
  */
 export class NormalDepth extends RenderStage {
@@ -233,14 +233,18 @@ export class NormalDepth extends RenderStage {
 				// No jitter — deterministic per-pixel ray so the temporal gate
 				// sees stable per-pixel normals across frames.
 				const uv = vec2( float( gx ).add( 0.5 ).div( resW ), float( gy ).add( 0.5 ).div( resH ) );
-				const ray = Ray( cameraRayOf( uv, camWorldMat, camProjInvMat, this.cameraRay ) );
+				const primary = cameraRayOf( uv, camWorldMat, camProjInvMat, this.cameraRay );
+				const direction = primary.direction.toVar();
+				// From the camera's clip plane, as the path tracer's rays start; the depth stays measured from the camera.
+				const clipAlong = cameraClipDistance( direction, this.cameraRay.clipStart, camWorldMat, this.cameraRay.cameraProjection ).toVar();
+				const ray = Ray( { origin: primary.origin.add( direction.mul( clipAlong ) ), direction } );
 				const hit = HitInfo.wrap( traverseBVH( ray, bvhStorage, triStorage ) );
 
 				const encodedNormal = hit.normal.mul( 0.5 ).add( 0.5 );
 				// Clamp to the max finite HalfFloat: a hit farther than 65504 units would otherwise
 				// round to +Inf in the f16 texture (on backends that don't clamp), reintroducing the
 				// Inf-Inf=NaN in the denoiser depth weights that the finite miss-sentinel avoids.
-				const depth = min( hit.dst, float( 65504.0 ) );
+				const depth = min( hit.dst.add( clipAlong ), float( 65504.0 ) );
 
 				const result = hit.didHit.select(
 					vec4( encodedNormal, depth ),
@@ -289,6 +293,8 @@ export class NormalDepth extends RenderStage {
 					shadingNormal.assign( processBump( mapped, material, uvCache ) );
 					// Same floor the Shade kernel applies before shading.
 					roughness.assign( processMetalnessRoughness( material, uvCache ).y.clamp( 0.05, 1.0 ) );
+					const emits = max( material.emissive.x, max( material.emissive.y, material.emissive.z ) ).mul( material.emissiveIntensity ).greaterThan( 0.0 );
+					roughness.assign( select( emits, roughness.negate(), roughness ) );
 
 				} );
 

package/src/Stages/PathTracer.js

@@ -27,6 +27,7 @@ import {
 	SORT_GLOBAL_WG_SIZE, SORT_GLOBAL_MAX_BINS,
 } from '../TSL/SortGlobalKernels.js';
 import { ENGINE_DEFAULTS } from '../EngineDefaults.js';
+import { LIGHT_FLOATS } from '../managers/UniformManager.js';
 import { MAX_STORAGE_TEXTURE_SIZE } from '../Processor/StorageTexturePool.js';
 import { readPixels } from '../Processor/TextureReadback.js';
 import { ISSUE_CODES } from '../EngineIssues.js';
@@ -380,6 +381,26 @@ export class PathTracer extends PathTracerStage {
 
 	}
 
+	/**
+	 * Whether some point or spot light has a radius: only then is disc sampling compiled in, and never for an integrator
+	 * of its own (a bidirectional light path leaves a light's centre).
+	 */
+	_lightRadiusNeeded() {
+
+		if ( this._integrator ) return false;
+		const sized = ( type, count, slot ) => {
+
+			if ( ! count ) return false;
+			const data = this[ `${type}LightsBufferNode` ].array;
+			for ( let i = 0; i < count; i ++ ) if ( data[ i * LIGHT_FLOATS[ type ] + slot ] > 0 ) return true;
+			return false;
+
+		};
+
+		return sized( 'point', this.numPointLights.value, 9 ) || sized( 'spot', this.numSpotLights.value, 18 );
+
+	}
+
 	get integrator() {
 
 		return this._integrator?.name ?? 'path';
@@ -406,10 +427,12 @@ export class PathTracer extends PathTracerStage {
 			this._materialFeaturesChanged = false;
 			const needed = this._layersToCompile();
 			if ( MATERIAL_LAYERS.some( ( layer ) => needed[ layer ] && ! this._compiledLayers?.[ layer ] ) ) this._outputsChanged = true;
+			if ( ! this._compiledTransmissionMaps && this.materialData.hasTransmissionMaps() ) this._outputsChanged = true;
 
 		}
 
 		if ( PICKED_SHADOW_RAYS.includes( this._shadowRays ) && this._pickedShadowRays() !== this._compiledPick ) this._outputsChanged = true;
+		if ( this._lightRadiusNeeded() !== this._compiledLightRadius ) this._outputsChanged = true;
 
 		if ( this._lightBufferRealloc || this._outputsChanged ) {
 
@@ -1636,6 +1659,7 @@ export class PathTracer extends PathTracerStage {
 			anamorphicRatio: this.anamorphicRatio,
 			dofMode: this.dofMode,
 			dofBlur: this.dofBlur,
+			cameraClipStart: this.cameraClipStart,
 			renderWidth: this._wfRenderWidth,
 			renderHeight: this._wfRenderHeight,
 			chunkRowBase: this._wfChunkRowBase,
@@ -1851,6 +1875,8 @@ export class PathTracer extends PathTracerStage {
 			iesProfiles: texNodes.iesProfilesTex,
 			alphaShadows: this.uniforms.get( 'enableAlphaShadows' ),
 			materialLayers: this._compiledLayers = this._layersToCompile(),
+			lightRadius: this._compiledLightRadius = this._lightRadiusNeeded(),
+			transmissionMaps: this._compiledTransmissionMaps = this.materialData.hasTransmissionMaps(),
 		};
 		const own = ( call ) => withSceneResources( call, resources );
 		const freshEnvTex = _env.environmentTexture ? texture( _env.environmentTexture ) : texNodes.envTex;
@@ -2089,7 +2115,6 @@ export class PathTracer extends PathTracerStage {
 			hasPreviousAux: this.hasPreviousAux,
 			auxAccumulationAlpha: this.auxAccumulationAlpha,
 			cameraIsMoving: this.cameraIsMoving,
-			transparentBackground: this.transparentBackground,
 			prevAccumTexture: prevColor,
 			prevAlbedoTexture: prevAlbedo,
 			prevNormalDepthTexture: prevNormalDepth,
@@ -2146,6 +2171,7 @@ export class PathTracer extends PathTracerStage {
 			anamorphicRatio: this.anamorphicRatio,
 			dofMode: this.dofMode,
 			dofBlur: this.dofBlur,
+			cameraClipStart: this.cameraClipStart,
 			bvhBuffer: freshBvh,
 			triangleBuffer: freshTri,
 			materialBuffer: freshMat,

package/src/Stages/PathTracerStage.js

@@ -1018,7 +1018,11 @@ export class PathTracerStage extends RenderStage {
 
 		this._whenTLASResident( () => {
 
-			if ( ! this._patchTLASLeafVisibility( meshIndex, visible ) ) return;
+			// Leaves are per placement: an InstancedMesh holds a run of them, and shifts every index after it.
+			const run = this._instanceTable?.placementRunOf( meshIndex );
+			let patched = false;
+			for ( let p = run?.start; run && p < run.start + run.count; p ++ ) patched = this._patchTLASLeafVisibility( p, visible ) || patched;
+			if ( ! patched ) return;
 			this._patchGroupNodes();
 			this._flushBVHEdits();
 
@@ -1437,13 +1441,18 @@ export class PathTracerStage extends RenderStage {
 	 */
 	_updateCameraUniforms() {
 
+		// Only an imported camera's clip plane: `near` is the viewer's own for its default camera.
+		const clipStart = Math.max( this.camera.userData?.clipStart ?? 0, 0 );
+
 		if ( ! this._matricesApproxEqual( this.lastCameraMatrix, this.camera.matrixWorld ) ||
-			! this._matricesApproxEqual( this.lastProjectionMatrix, this.camera.projectionMatrixInverse ) ) {
+			! this._matricesApproxEqual( this.lastProjectionMatrix, this.camera.projectionMatrixInverse ) ||
+			clipStart !== this.cameraClipStart.value ) {
 
 			this.cameraWorldMatrix.value.copy( this.camera.matrixWorld );
 			this.cameraViewMatrix.value.copy( this.camera.matrixWorldInverse );
 			this.cameraProjectionMatrix.value.copy( this.camera.projectionMatrix );
 			this.cameraProjectionMatrixInverse.value.copy( this.camera.projectionMatrixInverse );
+			this.cameraClipStart.value = clipStart;
 
 			this.lastCameraMatrix.copy( this.camera.matrixWorld );
 			this.lastProjectionMatrix.copy( this.camera.projectionMatrixInverse );
@@ -1503,6 +1512,9 @@ export class PathTracerStage extends RenderStage {
 		// freezes when the frame retires or the camera moves, which is what a denoiser needs.
 		context.setState( 'pathtracer:samples', this.frameCount );
 		context.setState( 'renderMode', this.renderMode.value );
+		// What a camera ray that sees nothing shows; the colour texture's alpha is 0 there in every case.
+		context.setState( 'pathtracer:backdrop', this.uniforms.get( 'transparentBackground' ).value ? 'transparent'
+			: this.uniforms.get( 'showBackground' ).value ? 'environment' : 'color' );
 
 	}
 

package/src/Storage/SceneGraphCodec.js

@@ -284,10 +284,11 @@ export function encodeSceneGraph( root, { environment = null, animations = [], s
 
 /**
  * Writes an encoded graph into a storage entry: `graph.json` and `data.bin`.
- * @param {{release?: boolean}} [options] - drop each section's array once written, so a graph
- *   written during a build does not keep arrays the build has since replaced
+ * @param {{release?: boolean, signal?: AbortSignal}} [options] - `release` drops each section's array once
+ *   written, so a graph written during a build does not keep arrays the build has since replaced; `signal`
+ *   stops the write between pieces
  */
-export async function writeSceneGraph( writer, { manifest, sections }, { release = false } = {} ) {
+export async function writeSceneGraph( writer, { manifest, sections }, { release = false, signal = null } = {} ) {
 
 	for ( const section of sections ) {
 
@@ -295,6 +296,7 @@ export async function writeSceneGraph( writer, { manifest, sections }, { release
 		const bytes = new Uint8Array( array.buffer, array.byteOffset, array.byteLength );
 		for ( let at = 0; at < bytes.length; at += PIECE_BYTES ) {
 
+			signal?.throwIfAborted();
 			await writer.write( 'data.bin', bytes.subarray( at, Math.min( bytes.length, at + PIECE_BYTES ) ), { at: offset + at } );
 
 		}
@@ -304,6 +306,7 @@ export async function writeSceneGraph( writer, { manifest, sections }, { release
 	}
 
 	if ( sections.length === 0 ) await writer.write( 'data.bin', new Uint8Array( 0 ) );
+	signal?.throwIfAborted();
 	await writer.writeJSON( 'graph.json', manifest );
 
 }

package/src/TSL/BVHTraversal.js

@@ -32,7 +32,7 @@ import {
 } from '../Processor/BufferLayout.js';
 import { HitInfo } from './Struct.js';
 import {
-	getDatafromStorageBuffer, instanceRows, instanceNormalToWorld, unpackTriangleNormal, triangleRow, shadowFlagsSettle
+	getDatafromStorageBuffer, storageRows, instanceRows, instanceNormalToWorld, unpackTriangleNormal, triangleRow, shadowFlagsSettle
 } from './Common.js';
 
 const MAX_STACK_DEPTH = 32;
@@ -51,6 +51,15 @@ const HUGE_VAL = 1e8;
 
 const createStack = () => array( 'int', MAX_STACK_DEPTH ).toVar();
 
+// Row k of BVH node `nodeIndex`. One buffer reads each row where it is used; over parts, `rows` are read in one branch.
+const nodeRows = ( bvhBuffer, nodeIndex, rows = [ 0, 1, 2, 3 ] ) => {
+
+	if ( ! bvhBuffer.isSplitStorage ) return ( k ) => getDatafromStorageBuffer( bvhBuffer, nodeIndex, int( k ), int( BVH_STRIDE ) );
+	const read = storageRows( bvhBuffer, int( nodeIndex ).mul( BVH_STRIDE ), rows );
+	return ( k ) => read[ rows.indexOf( k ) ];
+
+};
+
 // A negative stack entry is a leaf folded into its parent, `~( first << 4 | count )` as the parent
 // stores it, so child slots are pushed as they are and a leaf needs no fetch.
 const foldedFirst = ( entry ) => int( uint( entry.bitNot() ).shiftRight( uint( 4 ) ) );
@@ -91,10 +100,10 @@ const toObjectDir = ( rows, d ) => vec3(
 // Compare-swaps sorting up to four ascending.
 const SORT_NETWORKS = [[], [], [[ 0, 1 ]], [[ 0, 1 ], [ 1, 2 ], [ 0, 1 ]], [[ 0, 1 ], [ 2, 3 ], [ 0, 2 ], [ 1, 3 ], [ 1, 2 ]]];
 
-const pushHitCopies = ( bvhBuffer, nodeIndex, nodeData0, origin, invDir, stack, stackPtr, limit ) => {
+const pushHitCopies = ( node, nodeIndex, nodeData0, origin, invDir, stack, stackPtr, limit ) => {
 
-	const d1 = getDatafromStorageBuffer( bvhBuffer, nodeIndex, int( 1 ), int( BVH_STRIDE ) );
-	const d2 = getDatafromStorageBuffer( bvhBuffer, nodeIndex, int( 2 ), int( BVH_STRIDE ) );
+	const d1 = node( 1 );
+	const d2 = node( 2 );
 	const base = vec3( nodeData0.z, d1.x, d1.y ).toVar();
 	const exps = floatBitsToUint( nodeData0.y ).toVar();
 	const stepOf = ( a ) => uintBitsToFloat( exps.shiftRight( uint( a * 8 ) ).bitAnd( uint( 255 ) ).shiftLeft( uint( 23 ) ) );
@@ -363,8 +372,9 @@ const makeTraverseBVH = ( trackStats ) => Fn( ( [
 
 		const leaf = int( uint( entry ).bitAnd( uint( ~ COPY_ENTRY >>> 0 ) ).shiftRight( uint( 2 ) ) );
 		const k = uint( entry ).bitAnd( uint( 3 ) ).toVar();
-		const head = getDatafromStorageBuffer( bvhBuffer, leaf, int( 0 ), int( BVH_STRIDE ) );
-		const words = floatBitsToUint( getDatafromStorageBuffer( bvhBuffer, leaf, int( 3 ), int( BVH_STRIDE ) ) ).toVar();
+		const node = nodeRows( bvhBuffer, leaf, [ 0, 3 ] );
+		const head = node( 0 );
+		const words = floatBitsToUint( node( 3 ) ).toVar();
 		const word = select( k.equal( uint( 0 ) ), words.x, select( k.equal( uint( 1 ) ), words.y, select( k.equal( uint( 2 ) ), words.z, words.w ) ) ).toVar();
 
 		If( word.bitAnd( uint( CLUSTER_COPY_HIDDEN ) ).equal( uint( 0 ) ), () => {
@@ -483,12 +493,13 @@ const makeTraverseBVH = ( trackStats ) => Fn( ( [
 		const visitNode = () => {
 
 			const nodeIndex = entry;
+			const node = nodeRows( bvhBuffer, nodeIndex );
 
 			// 4 vec4 per node
 			// Leaf: vec4(0) = [triOffset, triCount, 0, TRIANGLE_LEAF]
 			// Inner: vec4(0) = [leftMin.xyz, leftChild], vec4(1) = [leftMax.xyz, rightChild],
 			//        vec4(2) = [rightMin.xyz, 0], vec4(3) = [rightMax.xyz, 0]
-			const nodeData0 = getDatafromStorageBuffer( bvhBuffer, nodeIndex, int( 0 ), int( BVH_STRIDE ) );
+			const nodeData0 = node( 0 );
 			if ( trackStats ) closestHit.boxTests.addAssign( 1 );
 
 			// Slot [3] carries a u32 bit pattern: an inner node's left child, or a leaf tag. Stored as
@@ -504,7 +515,7 @@ const makeTraverseBVH = ( trackStats ) => Fn( ( [
 
 				} ).Else( clustered ? () => {
 
-					pushHitCopies( bvhBuffer, nodeIndex, nodeData0, worldOrigin, worldInvDir, stack, stackPtr, closestHit.dst );
+					pushHitCopies( node, nodeIndex, nodeData0, worldOrigin, worldInvDir, stack, stackPtr, closestHit.dst );
 
 				} : () => {
 
@@ -516,7 +527,7 @@ const makeTraverseBVH = ( trackStats ) => Fn( ( [
 						// A baked placement already sits in world space; only a transformed one moves the ray.
 						If( floatBitsToUint( nodeData0.y ).bitAnd( uint( TLAS_LEAF_IDENTITY ) ).equal( uint( 0 ) ), () => {
 
-							const rows = instanceRows( bvhBuffer, nodeIndex );
+							const rows = [ node( 1 ), node( 2 ), node( 3 ) ];
 							const localDir = toObjectDir( rows, worldDirection ).toVar();
 
 							rayOrigin.assign( toObjectPoint( rows, worldOrigin ) );
@@ -547,9 +558,9 @@ const makeTraverseBVH = ( trackStats ) => Fn( ( [
 			} ).Else( () => {
 
 				// Inner node — child AABBs stored in this node (4 reads total, no child fetches)
-				const nodeData1 = getDatafromStorageBuffer( bvhBuffer, nodeIndex, int( 1 ), int( BVH_STRIDE ) );
-				const nodeData2 = getDatafromStorageBuffer( bvhBuffer, nodeIndex, int( 2 ), int( BVH_STRIDE ) );
-				const nodeData3 = getDatafromStorageBuffer( bvhBuffer, nodeIndex, int( 3 ), int( BVH_STRIDE ) );
+				const nodeData1 = node( 1 );
+				const nodeData2 = node( 2 );
+				const nodeData3 = node( 3 );
 
 				const leftChild = int( nodeTag ).toVar();
 				const rightChild = int( floatBitsToUint( nodeData1.w ) ).toVar();
@@ -705,8 +716,9 @@ const makeTraverseBVHShadow = ( cameraCulled ) => Fn( ( [
 
 		const leaf = int( uint( entry ).bitAnd( uint( ~ COPY_ENTRY >>> 0 ) ).shiftRight( uint( 2 ) ) );
 		const k = uint( entry ).bitAnd( uint( 3 ) ).toVar();
-		const head = getDatafromStorageBuffer( bvhBuffer, leaf, int( 0 ), int( BVH_STRIDE ) );
-		const words = floatBitsToUint( getDatafromStorageBuffer( bvhBuffer, leaf, int( 3 ), int( BVH_STRIDE ) ) ).toVar();
+		const node = nodeRows( bvhBuffer, leaf, [ 0, 3 ] );
+		const head = node( 0 );
+		const words = floatBitsToUint( node( 3 ) ).toVar();
 		const word = select( k.equal( uint( 0 ) ), words.x, select( k.equal( uint( 1 ) ), words.y, select( k.equal( uint( 2 ) ), words.z, words.w ) ) ).toVar();
 
 		If( word.bitAnd( uint( CLUSTER_COPY_HIDDEN ) ).equal( uint( 0 ) ), () => {
@@ -818,7 +830,8 @@ const makeTraverseBVHShadow = ( cameraCulled ) => Fn( ( [
 		const visitNode = () => {
 
 			const nodeIndex = entry;
-			const nodeData0 = getDatafromStorageBuffer( bvhBuffer, nodeIndex, int( 0 ), int( BVH_STRIDE ) );
+			const node = nodeRows( bvhBuffer, nodeIndex );
+			const nodeData0 = node( 0 );
 
 			// Slot [3] carries a u32 bit pattern: an inner node's left child, or a leaf tag. Stored as
 			// float VALUES these rounded past 2^24 and sent the ray to a neighbouring node, which
@@ -833,7 +846,7 @@ const makeTraverseBVHShadow = ( cameraCulled ) => Fn( ( [
 
 				} ).Else( clustered ? () => {
 
-					pushHitCopies( bvhBuffer, nodeIndex, nodeData0, worldOrigin, worldInvDir, stack, stackPtr, closestHit.dst );
+					pushHitCopies( node, nodeIndex, nodeData0, worldOrigin, worldInvDir, stack, stackPtr, closestHit.dst );
 
 				} : () => {
 
@@ -843,7 +856,7 @@ const makeTraverseBVHShadow = ( cameraCulled ) => Fn( ( [
 						// A baked placement already sits in world space; only a transformed one moves the ray.
 						If( floatBitsToUint( nodeData0.y ).bitAnd( uint( TLAS_LEAF_IDENTITY ) ).equal( uint( 0 ) ), () => {
 
-							const rows = instanceRows( bvhBuffer, nodeIndex );
+							const rows = [ node( 1 ), node( 2 ), node( 3 ) ];
 							const localDir = toObjectDir( rows, worldDirection ).toVar();
 
 							rayOrigin.assign( toObjectPoint( rows, worldOrigin ) );
@@ -874,9 +887,9 @@ const makeTraverseBVHShadow = ( cameraCulled ) => Fn( ( [
 			} ).Else( () => {
 
 				// Inner node — child AABBs stored in this node
-				const nodeData1 = getDatafromStorageBuffer( bvhBuffer, nodeIndex, int( 1 ), int( BVH_STRIDE ) );
-				const nodeData2 = getDatafromStorageBuffer( bvhBuffer, nodeIndex, int( 2 ), int( BVH_STRIDE ) );
-				const nodeData3 = getDatafromStorageBuffer( bvhBuffer, nodeIndex, int( 3 ), int( BVH_STRIDE ) );
+				const nodeData1 = node( 1 );
+				const nodeData2 = node( 2 );
+				const nodeData3 = node( 3 );
 
 				const leftChild = int( nodeTag ).toVar();
 				const rightChild = int( floatBitsToUint( nodeData1.w ) ).toVar();

package/src/TSL/CameraRay.js

@@ -14,7 +14,7 @@
 
 import {
 	Fn, vec3, vec4, float, int, uniform,
-	If, normalize, mat3, mix, sin, cos, cross, dot, select,
+	If, normalize, mat3, mix, sin, cos, cross, dot, select, max,
 } from 'three/tsl';
 import { Vector2 } from 'three';
 
@@ -39,10 +39,12 @@ export function cameraRayUniforms() {
 		panoLonRange: uniform( new Vector2(), 'vec2' ),
 		panoLatRange: uniform( new Vector2(), 'vec2' ),
 		panoLevelHorizon: uniform( 1, 'int' ),
+		clipStart: uniform( 0, 'float' ),
 		/** @param {import('../managers/UniformManager.js').UniformManager} source */
 		sync( source ) {
 
 			u.cameraProjection.value = source.get( 'cameraProjection' ).value;
+			u.clipStart.value = source.get( 'cameraClipStart' ).value;
 			u.panoLonRange.value.copy( source.get( 'panoLonRange' ).value );
 			u.panoLatRange.value.copy( source.get( 'panoLatRange' ).value );
 			u.panoLevelHorizon.value = source.get( 'panoLevelHorizon' ).value;
@@ -70,6 +72,15 @@ export const cameraRayPoint = ( uv01, distance, cameraWorldMatrix, cameraProject
 
 };
 
+/**
+ * How far along a camera ray its clip plane lies: Cycles' clip start, a plane `clipStart` in front of the camera (a
+ * sphere for a panorama). Camera rays start there, so a camera can see through a wall behind it.
+ */
+export const cameraClipDistance = ( direction, clipStart, cameraWorldMatrix, cameraProjection ) => select(
+	cameraProjection.equal( PANORAMA ), clipStart,
+	clipStart.div( max( dot( direction, normalize( vec3( cameraWorldMatrix[ 2 ] ) ) ).negate(), 1e-4 ) )
+);
+
 /** World-space primary ray origin for pixel uv: the camera, or its image plane when orthographic. */
 export const cameraRayOrigin = Fn( ( [ uv01, cameraWorldMatrix, cameraProjectionMatrixInverse, cameraProjection ] ) => {