rayzee 11.7.0 → 11.8.0

package/src/RayzeeRenderer.js

@@ -123,6 +123,15 @@ function attachDeviceLostHandler( device, holder ) {
 
 }
 
+// three.js's GPUFeatureName, which it does not export: what its own device request enables.
+const THREE_DEVICE_FEATURES = [
+	'core-features-and-limits', 'depth-clip-control', 'depth32float-stencil8', 'texture-compression-bc',
+	'texture-compression-bc-sliced-3d', 'texture-compression-etc2', 'texture-compression-astc',
+	'texture-compression-astc-sliced-3d', 'timestamp-query', 'indirect-first-instance', 'shader-f16',
+	'rg11b10ufloat-renderable', 'bgra8unorm-storage', 'float32-filterable', 'float32-blendable', 'clip-distances',
+	'dual-source-blending', 'subgroups', 'texture-formats-tier1', 'texture-formats-tier2',
+];
+
 const SOFTWARE_ADAPTER = /swiftshader|llvmpipe|lavapipe|basic render|microsoft basic|warp/i;
 
 /**
@@ -822,9 +831,10 @@ export class RayzeeRenderer extends EventDispatcher {
 		// disposed graph stays reachable until another app claims the same canvas.
 		if ( this.canvas && _appsByCanvas.get( this.canvas ) === this ) _appsByCanvas.delete( this.canvas );
 
-		if ( this._gpuDevice ) {
+		const device = this._gpuDevice;
+		if ( device ) {
 
-			this._gpuDevice.onuncapturederror = null;
+			device.onuncapturederror = null;
 			this._gpuDevice = null;
 
 		}
@@ -836,7 +846,8 @@ export class RayzeeRenderer extends EventDispatcher {
 
 		}
 
-		disposeRenderer( this.renderer );
+		// three.js destroys only a device it requested itself.
+		Promise.resolve( disposeRenderer( this.renderer ) ).finally( () => device?.destroy() );
 		this.renderer = null;
 
 		this.stages = {};
@@ -2724,7 +2735,8 @@ export class RayzeeRenderer extends EventDispatcher {
 	 * @param {string} [options.colorSpace='srgb'] - `'srgb'` for display bytes through the active
 	 *   view transform, `'linear'` for the raw working-space accumulation, or the name of a colour
 	 *   space in the loaded OCIO config for a delivery buffer (float, e.g. `'ACES2065-1'`)
-	 * @param {boolean} [options.preserveAlpha=false] - srgb only
+	 * @param {boolean} [options.preserveAlpha=false] - srgb only: coverage as alpha while the background is
+	 *   transparent, else 255. Float readbacks carry coverage then and 1 otherwise, as the canvas shows it.
 	 * @param {'accumulation'|'display'} [options.source='accumulation'] - `'display'` reads what the
 	 *   viewport is showing — denoised when a denoiser has run — instead of the raw
 	 *   accumulation
@@ -2750,6 +2762,8 @@ export class RayzeeRenderer extends EventDispatcher {
 
 		// The pool over-allocates to the reserve, so the texture is larger than the frame.
 		const { width, height } = stage;
+		// The accumulation's alpha is always coverage; an opaque backdrop reads back opaque, as the Compositor draws it.
+		const transparent = !! this.settings.get( 'transparentBackground' );
 
 		if ( colorSpace === 'srgb' ) {
 
@@ -2758,15 +2772,16 @@ export class RayzeeRenderer extends EventDispatcher {
 				exposure: this.renderer.toneMappingExposure,
 				toneMapping: this.renderer.toneMapping,
 				saturation: this.settings.get( 'saturation' ) ?? 1,
-				preserveAlpha,
+				preserveAlpha: preserveAlpha && transparent,
 				gain: this._displayGain(),
 			};
 
 			const gpu = await this._toneMapOnGPU( shown?.texture ?? null, target, width, height, tone );
-			const fn = ! gpu && tone.gain ? await tone.gain.cpu() : null;
+			const fn = ! gpu && tone.gain?.cpu ? await tone.gain.cpu() : null;
+			const backdrop = tone.gain?.backdrop ?? 0;
 			const data = gpu ?? toneMapToRGBA8( shown
 				? await this._readTexture( shown.texture, width, height )
-				: await readPixels( this.renderer, target, width, height ), { ...tone, pixelGain: fn && { fn, width, height } } );
+				: await readPixels( this.renderer, target, width, height ), { ...tone, pixelGain: ( fn || backdrop ) ? { fn, width, height, backdrop } : null } );
 			return { data, width, height, colorSpace, source: shown?.source ?? 'accumulation', toneMappedOn: gpu ? 'gpu' : 'cpu' };
 
 		}
@@ -2774,6 +2789,12 @@ export class RayzeeRenderer extends EventDispatcher {
 		const { data: linear, source: read } = source === 'display'
 			? await this._readDisplaySource( target, width, height )
 			: { data: await readPixels( this.renderer, target, width, height ), source: 'accumulation' };
+		if ( ! transparent ) {
+
+			const one = linear instanceof Uint16Array ? 0x3C00 : 1; // a half-float target reads back as its bits
+			for ( let i = 3; i < linear.length; i += 4 ) linear[ i ] = one;
+
+		}
 
 		// `colorSpace` stays 'linear' — callers branch on it. `workingSpace` is the new, additive
 		// answer to "linear in what primaries", which only means something once a config is loaded.
@@ -3654,14 +3675,25 @@ export class RayzeeRenderer extends EventDispatcher {
 
 		if ( typeof navigator === 'undefined' || ! navigator.gpu ) {
 
-			throw new Error( 'WebGPU is not available — outside a browser, install one as navigator.gpu (for Node, the `webgpu` package)' );
+			this._issues.fail( ISSUE_CODES.WEBGPU_UNAVAILABLE, 'WebGPU is not available — outside a browser, install one as navigator.gpu (for Node, the `webgpu` package)' );
+
+		}
+
+		let adapter = null;
+		let adapterError;
+		try {
+
+			adapter = await navigator.gpu.requestAdapter( { powerPreference: 'high-performance' } );
+
+		} catch ( error ) {
+
+			adapterError = error;
 
 		}
 
-		const adapter = await navigator.gpu.requestAdapter( { powerPreference: 'high-performance' } );
 		if ( ! adapter ) {
 
-			throw new Error( 'Failed to get WebGPU adapter' );
+			this._issues.fail( ISSUE_CODES.ADAPTER_UNAVAILABLE, `no WebGPU adapter${adapterError ? ': ' + adapterError.message : ''}`, {}, adapterError );
 
 		}
 
@@ -3711,22 +3743,43 @@ export class RayzeeRenderer extends EventDispatcher {
 		// buys nothing, and 10 is already this adapter's ceiling.
 		requiredLimits.maxStorageBuffersPerShaderStage = Math.min( adapterLimits.maxStorageBuffersPerShaderStage, 10 );
 
-		this.renderer = new WebGPURenderer( {
-			canvas: this.canvas,
-			alpha: true,
-			powerPreference: 'high-performance',
-			requiredLimits,
-		} );
+		// Requested here rather than by three.js, so a failure is typed where it happens.
+		let device;
+		try {
+
+			device = await adapter.requestDevice( {
+				requiredFeatures: THREE_DEVICE_FEATURES.filter( ( name ) => adapter.features.has( name ) ),
+				requiredLimits,
+			} );
 
-		await initWithoutFrameLoop( this.renderer, this._headless );
+		} catch ( error ) {
+
+			this._issues.fail( ISSUE_CODES.DEVICE_UNAVAILABLE, `WebGPU device request failed: ${error.message}`, { adapter: { ...this.adapterInfo } }, error );
+
+		}
+
+		this.renderer = new WebGPURenderer( { canvas: this.canvas, alpha: true, device } );
+
+		try {
+
+			await initWithoutFrameLoop( this.renderer, this._headless );
+
+		} catch ( error ) {
+
+			device.destroy();
+			throw error;
+
+		}
 
 		// WebGPURenderer swaps in WebGL2 on failure with only a warn(). The wavefront path is
 		// compute-only, so every frame would fail against an empty canvas.
 		if ( ! this.renderer.backend?.isWebGPUBackend ) {
 
-			throw new Error(
-				'WebGPU backend unavailable — three.js fell back to WebGL2, which cannot run the ' +
-				'path tracer\'s compute kernels. Check GPU process flags and driver support.'
+			device.destroy();
+			this._issues.fail(
+				ISSUE_CODES.WEBGPU_UNAVAILABLE,
+				'three.js fell back to WebGL2, which cannot run the path tracer\'s compute kernels. ' +
+				'Check GPU process flags and driver support.'
 			);
 
 		}
@@ -3743,13 +3796,12 @@ export class RayzeeRenderer extends EventDispatcher {
 		// BVH and CPU-side texture data per create/dispose cycle. `lost` is a pending promise
 		// whose reaction cannot be unregistered, so it reads the app out of a holder that
 		// dispose() empties; `onuncapturederror` is cleared there directly.
-		const gpuDevice = this.renderer.backend?.device;
-		if ( gpuDevice?.lost ) {
+		this._gpuDevice = device;
+		if ( device.lost ) {
 
-			this._gpuDevice = gpuDevice;
 			this._deviceLostHolder = { app: this };
-			attachDeviceLostHandler( gpuDevice, this._deviceLostHolder );
-			gpuDevice.onuncapturederror = ( event ) => log.error( 'WebGPU uncaptured error:', event.error );
+			attachDeviceLostHandler( device, this._deviceLostHolder );
+			device.onuncapturederror = ( event ) => log.error( 'WebGPU uncaptured error:', event.error );
 
 		}
 
@@ -4072,7 +4124,10 @@ export class RayzeeRenderer extends EventDispatcher {
 
 	}
 
-	/** A per-pixel gain the shown picture carries before the view (the compositor's), for tone-mapped readbacks; or null. */
+	/**
+	 * A per-pixel gain the shown picture carries before the view (the compositor's), for tone-mapped readbacks; or null.
+	 * Its `backdrop`, when set, is the gain a solid backdrop is held at (`PackedToneMapper`'s `gain`).
+	 */
 	_displayGain() {
 
 		return null;

package/src/Stages/AutoExposure.js

@@ -26,7 +26,7 @@ const BINS = 256;
 const LOG2_MIN = - 16;
 const LOG2_MAX = 12;
 const BIN_STOPS = ( LOG2_MAX - LOG2_MIN ) / BINS;
-// A tile below this has no light to meter: a black or transparent background is not part of the exposure.
+// A tile below this has no light to meter (a black sky, say): it is not part of the exposure.
 const BLACK = 2 ** - 24;
 const WEIGHT_SCALE = 65536;
 const MAX_TILE_READS = 256;
@@ -42,6 +42,10 @@ const MOTION_HOLD = 0.3; // a metering of a new view counts as motion for this l
 const DAMP_UNTIL = 1.5; // stops from the manual exposure: the room level is damped up to here...
 const FOLLOW_FROM = 3; // ...and followed fully from here
 const REC709_Y = [ 0.2126, 0.7152, 0.0722 ];
+// A pixel this covered saw only the scene. One less carries the backdrop's own colour: an edge, a window onto it.
+const FULL_COVERAGE = 0.999;
+// How the backdrop counts: weighed out by coverage (transparent), in full (the environment), not at all (a solid colour).
+const BACKDROP_MODES = { transparent: 0, environment: 1, color: 2 };
 
 /**
  * One adaptation step in stops: constant speed while far, exponential near the target, never past it.
@@ -93,15 +97,19 @@ const meterInterval = samples => samples < 16 ? 1 : samples < 64 ? 4 : 16;
 /**
  * Auto exposure: meters the accumulated image on the GPU and adapts on the CPU.
  *
- * Tiles are averaged in linear light, weighted by alpha, so a one-sample image meters like the
- * converged one; the percentile-clipped mean of their log2 histogram is read back. It aims at a room
- * level learned while the view changes plus a damped share of each view (`blendExposureEV`), moves in
- * stops every loop frame (`update()`: eased while the image restarts every frame, landing in ~0.3 s once
- * it accumulates), in video time (`advance()`, eased), or with each metering (`instant`), and is applied
- * as 2^EV × the manual exposure.
+ * Tiles are averaged in linear light, so a one-sample image meters like the converged one; the
+ * percentile-clipped mean of their log2 histogram is read back. The sky, also seen through windows, is
+ * part of what is lit and is metered; a transparent backdrop is weighed out by the path tracer's coverage
+ * (alpha); under a solid colour only pixels that saw the scene alone count, so its colour moves nothing.
+ *
+ * It aims at a room level learned while the view changes plus a damped share of each view
+ * (`blendExposureEV`), moves in stops every loop frame (`update()`: eased while the image restarts
+ * every frame, landing in ~0.3 s once it accumulates), in video time (`advance()`, eased), or with each
+ * metering (`instant`), and is applied as 2^EV × the manual exposure.
  *
  * Events listened: pipeline:reset, pipeline:lightingChanged (lands on the next metering)
  * Textures read: pathtracer:color
+ * State read: pathtracer:samples, pathtracer:backdrop
  * State published: autoexposure:value, autoexposure:avgLuminance
  */
 export class AutoExposure extends RenderStage {
@@ -133,6 +141,7 @@ export class AutoExposure extends RenderStage {
 		this._falloffU = uniform( new Vector2() );
 		this._pointU = uniform( new Vector2( 0.5, 0.5 ) );
 		this._lumWeightsU = uniform( new Vector3().fromArray( REC709_Y ) );
+		this._backdropModeU = uniform( BACKDROP_MODES.transparent, 'int' );
 		this._widthU = uniform( 1, 'int' );
 		this._heightU = uniform( 1, 'int' );
 		this._strideU = uniform( 1, 'int' );
@@ -178,6 +187,7 @@ export class AutoExposure extends RenderStage {
 		const hist = this._histogram;
 		const width = this._widthU, height = this._heightU, stride = this._strideU, gridX = this._gridXU, gridY = this._gridYU;
 		const lumWeights = this._lumWeightsU, falloff = this._falloffU, point = this._pointU;
+		const backdropMode = this._backdropModeU;
 
 		return Fn( () => {
 
@@ -199,7 +209,9 @@ export class AutoExposure extends RenderStage {
 					const lum = dot( c.xyz, lumWeights ).toVar();
 					// NaN or Inf would poison the whole tile.
 					const finite = floatBitsToUint( lum ).bitAnd( uint( 0x7f800000 ) ).notEqual( uint( 0x7f800000 ) );
-					const alpha = c.w.clamp( 0.0, 1.0 );
+					const coverage = c.w.clamp( 0.0, 1.0 );
+					const alpha = select( backdropMode.equal( int( BACKDROP_MODES.environment ) ), float( 1 ),
+						select( backdropMode.equal( int( BACKDROP_MODES.color ) ), select( coverage.greaterThanEqual( FULL_COVERAGE ), float( 1 ), float( 0 ) ), coverage ) );
 					sum.addAssign( select( finite, lum.clamp( 0.0, 1e6 ), float( 0 ) ).mul( alpha ) );
 					cover.addAssign( alpha );
 
@@ -388,6 +400,7 @@ export class AutoExposure extends RenderStage {
 		this._strideU.value = Math.max( 1, Math.round( Math.sqrt( tileReads / MAX_TILE_READS ) ) );
 		this._widthU.value = width;
 		this._heightU.value = height;
+		this._backdropModeU.value = BACKDROP_MODES[ context.getState( 'pathtracer:backdrop' ) ] ?? BACKDROP_MODES.transparent;
 		this._updateMeteringPattern( width / height );
 		this._inputNode.value = input;
 

package/src/Stages/Compositor.js

@@ -3,6 +3,7 @@ import { MeshBasicNodeMaterial, QuadMesh, TextureNode } from 'three/webgpu';
 import { NoBlending, NoToneMapping } from 'three';
 import { RenderStage, StageExecutionMode } from '../Pipeline/RenderStage.js';
 import { REC709_LUMINANCE_COEFFICIENTS } from '../TSL/Common.js';
+import { backdropGain } from '../Processor/ToneMapCPU.js';
 
 
 /**
@@ -51,6 +52,11 @@ export class Compositor extends RenderStage {
 		this._sourceTexNode = new TextureNode();
 		this._displayGain = null;
 
+		// A solid backdrop held at this exposure, or null: see setBackdropExposure().
+		this._backdropExposure = null;
+		this._holdBackdrop = uniform( 0, 'int' );
+		this._backdropGain = uniform( 1.0 );
+
 		this.compositorMaterial = new MeshBasicNodeMaterial();
 		this.compositorMaterial.blending = NoBlending;
 		this._buildColorNode();
@@ -62,7 +68,17 @@ export class Compositor extends RenderStage {
 	_buildColorNode() {
 
 		const texSample = this._sourceTexNode.sample( uv() );
-		const color = this._displayGain ? texSample.xyz.mul( this._displayGain( texSample.xyz, screenUV ) ) : texSample.xyz;
+		let gain = this._displayGain ? this._displayGain( texSample.xyz, screenUV ) : null;
+		if ( this._backdropExposure !== null ) {
+
+			// Alpha is coverage: the backdrop takes its own gain, a partly covered pixel a blend (ToneMapCPU's heldGain).
+			const g = gain ?? float( 1 );
+			const held = g.add( this._backdropGain.sub( g ).mul( texSample.w.clamp( 0, 1 ).oneMinus() ) );
+			gain = select( this._holdBackdrop.greaterThan( int( 0 ) ), held, g );
+
+		}
+
+		const color = gain ? texSample.xyz.mul( gain ) : texSample.xyz;
 
 		const luma = dot( color, REC709_LUMINANCE_COEFFICIENTS );
 		const gradedColor = mix( vec3( luma ), color, this.saturation );
@@ -86,6 +102,20 @@ export class Compositor extends RenderStage {
 
 	}
 
+	/**
+	 * Holds a solid-colour backdrop at `exposure` (the manual one): whatever the renderer's exposure does — auto
+	 * exposure — and whatever display gain the scene takes, the backdrop is shown as at that exposure. Applies while
+	 * the path tracer reports a 'color' backdrop. Null removes it.
+	 * @param {number|null} exposure
+	 */
+	setBackdropExposure( exposure ) {
+
+		const changes = ( exposure === null ) !== ( this._backdropExposure === null );
+		this._backdropExposure = exposure;
+		if ( changes ) this._buildColorNode();
+
+	}
+
 	/**
 	 * The picture to show: the first published of the display sources, else `pathtracer:color` — the newest
 	 * scene-referred image the pipeline holds, denoised when a denoiser has run.
@@ -224,6 +254,14 @@ export class Compositor extends RenderStage {
 		const sourceTexture = this.resolveLightTexture( context );
 		if ( ! sourceTexture ) return;
 
+		if ( this._backdropExposure !== null ) {
+
+			const hold = context.getState( 'pathtracer:backdrop' ) === 'color';
+			this._holdBackdrop.value = hold ? 1 : 0;
+			if ( hold ) this._backdropGain.value = backdropGain( this._backdropExposure, this.renderer.toneMappingExposure, this.renderer.toneMapping );
+
+		}
+
 		this._sourceTexNode.value = sourceTexture;
 
 		this.renderer.setRenderTarget( null );

package/src/Stages/LocalExposure.js

@@ -26,6 +26,7 @@ const BLUR_TEXEL = 32;
 const BLUR_BLEND = 0.6;
 const BLUR_PERCENT = 50;
 const MIDDLE_GREY = Math.log2( 0.18 );
+const FULL_COVERAGE = 0.999; // under a solid backdrop, a pixel counts only when it saw the scene alone
 const DARKEST = 2 ** - 24;
 const MAX_CELLS = Math.ceil( MAX_RESERVABLE_RENDER_SIZE / CELL );
 const MAX_BLUR = Math.ceil( MAX_RESERVABLE_RENDER_SIZE / BLUR_TEXEL );
@@ -127,9 +128,12 @@ fn rayzee_gain( uv: vec2<f32>, linear: vec3<f32>, exposure: f32 ) -> f32 {
  * shadows apart, and the detail kept. It changes only what is shown: the compositor and every tone-mapped
  * readback apply the same per-pixel gain (`gainNode`, `toneGain`), so a saved picture matches the canvas.
  *
- * Built from `pathtracer:color` when the image restarts, less often as it converges.
+ * Built from `pathtracer:color` when the image restarts, less often as it converges. While the backdrop is a solid
+ * colour, both are built from the pixels that saw the scene alone (full coverage in alpha): the backdrop is not part of
+ * what is lit, and the compositor holds it at the manual exposure without this gain.
  * Events listened: pipeline:reset
  * Textures read: pathtracer:color
+ * State read: pathtracer:samples, pathtracer:backdrop
  */
 export class LocalExposure extends RenderStage {
 
@@ -146,7 +150,9 @@ export class LocalExposure extends RenderStage {
 
 		this._grid = attributeArray( MAX_CELLS * MAX_CELLS * BINS, 'vec2' );
 		this._blur = attributeArray( MAX_BLUR * MAX_BLUR, 'float' );
-		this._blurTmp = attributeArray( MAX_BLUR * MAX_BLUR, 'float' );
+		// The blur runs on ( log2 luminance × share, share ), divided out at the end: see the blur source kernel.
+		this._blurSource = attributeArray( MAX_BLUR * MAX_BLUR, 'vec2' );
+		this._blurTmp = attributeArray( MAX_BLUR * MAX_BLUR, 'vec2' );
 		this._inputNode = new TextureNode();
 		this._widthU = uniform( 1, 'int' );
 		this._heightU = uniform( 1, 'int' );
@@ -155,10 +161,11 @@ export class LocalExposure extends RenderStage {
 		this._blurHU = uniform( 1, 'int' );
 		this._radiusU = uniform( 1 );
 		this._logExposureU = uniform( 0 );
+		this._sceneOnlyU = uniform( 0, 'int' ); // 1: only pixels that saw the scene alone, a solid backdrop left out
 		this._p = [ new Vector4(), new Vector4(), new Vector4(), new Vector4() ].map( v => uniform( v ) );
 		this._params = new Float32Array( 16 );
 
-		this._kernels = [ this._buildGridKernel(), this._buildBlurSourceKernel(), this._buildBlurKernel( this._blur, this._blurTmp, true ), this._buildBlurKernel( this._blurTmp, this._blur, false ) ];
+		this._kernels = [ this._buildGridKernel(), this._buildBlurSourceKernel(), this._buildBlurKernel( this._blurSource, this._blurTmp, true ), this._buildBlurKernel( this._blurTmp, this._blur, false ) ];
 
 		this._built = false;
 		this._restarts = 0;
@@ -175,6 +182,7 @@ export class LocalExposure extends RenderStage {
 
 		const input = this._inputNode, grid = this._grid;
 		const width = this._widthU, height = this._heightU, cellsX = this._cellsXU, logExposure = this._logExposureU;
+		const sceneOnly = this._sceneOnlyU.greaterThan( int( 0 ) );
 		const yw = vec4( ...Y, 0 ).xyz;
 
 		return Fn( () => {
@@ -202,20 +210,24 @@ export class LocalExposure extends RenderStage {
 					If( x.lessThan( width ).and( y.lessThan( height ) ), () => {
 
 						const x1 = min( x.add( int( 1 ) ), width.sub( int( 1 ) ) ), y1 = min( y.add( int( 1 ) ), height.sub( int( 1 ) ) );
-						const lum = dot( textureLoad( input, ivec2( x, y ) ).xyz, yw )
-							.add( dot( textureLoad( input, ivec2( x1, y ) ).xyz, yw ) )
-							.add( dot( textureLoad( input, ivec2( x, y1 ) ).xyz, yw ) )
-							.add( dot( textureLoad( input, ivec2( x1, y1 ) ).xyz, yw ) ).mul( 0.25 ).toVar();
+						const t00 = textureLoad( input, ivec2( x, y ) ).toVar(), t10 = textureLoad( input, ivec2( x1, y ) ).toVar();
+						const t01 = textureLoad( input, ivec2( x, y1 ) ).toVar(), t11 = textureLoad( input, ivec2( x1, y1 ) ).toVar();
+						const coverage = ( t ) => select( sceneOnly.and( t.w.lessThan( FULL_COVERAGE ) ), float( 0 ), float( 1 ) );
+						const a00 = coverage( t00 ), a10 = coverage( t10 ), a01 = coverage( t01 ), a11 = coverage( t11 );
+						const covered = a00.add( a10 ).add( a01 ).add( a11 ).toVar();
+						const lum = dot( t00.xyz, yw ).mul( a00 ).add( dot( t10.xyz, yw ).mul( a10 ) )
+							.add( dot( t01.xyz, yw ).mul( a01 ) ).add( dot( t11.xyz, yw ).mul( a11 ) ).div( max( covered, 1e-6 ) ).toVar();
+						const share = covered.mul( 0.25 ).toVar();
 						// A NaN or infinite texel is left out, as the meter leaves it out: max() may keep a NaN on some
 						// GPUs, and an infinite one would read as 2^40 and darken its whole cell.
-						If( floatBitsToUint( lum ).bitAnd( uint( 0x7f800000 ) ).notEqual( uint( 0x7f800000 ) ), () => {
+						If( floatBitsToUint( lum ).bitAnd( uint( 0x7f800000 ) ).notEqual( uint( 0x7f800000 ) ).and( covered.greaterThan( 0.0 ) ), () => {
 
 							const logL = log2( max( lum, DARKEST ) ).clamp( LOG_FLOOR, LOG_CEIL ).toVar();
 							const f = logL.add( logExposure ).sub( BIN_MIN ).div( BIN_MAX - BIN_MIN ).clamp( 0.0, 1.0 ).mul( BINS - 1 ).toVar();
 							const b0 = uint( floor( f ) ).min( uint( BINS - 1 ) );
 							const b1 = b0.add( uint( 1 ) ).min( uint( BINS - 1 ) );
-							const w1 = f.sub( floor( f ) );
-							const w0 = float( 1 ).sub( w1 );
+							const w1 = f.sub( floor( f ) ).mul( share );
+							const w0 = float( 1 ).sub( f.sub( floor( f ) ) ).mul( share );
 							const level = logL.sub( LOG_FLOOR ).mul( FIXED );
 							atomicAdd( sums.element( b0 ), uint( level.mul( w0 ).add( 0.5 ) ) );
 							atomicAdd( weights.element( b0 ), uint( w0.mul( FIXED ).add( 0.5 ) ) );
@@ -246,10 +258,12 @@ export class LocalExposure extends RenderStage {
 	}
 
 	// The log of each 32×32 block's mean luminance: averaged in linear light, like the meter, so noise does not darken it.
+	// Stored as ( log × share, share ), share the fraction of its pixels counted: 1 unless a solid backdrop is left out.
 	_buildBlurSourceKernel() {
 
-		const input = this._inputNode, out = this._blur;
+		const input = this._inputNode, out = this._blurSource;
 		const width = this._widthU, height = this._heightU, blurW = this._blurWU;
+		const sceneOnly = this._sceneOnlyU.greaterThan( int( 0 ) );
 		const yw = vec4( ...Y, 0 ).xyz;
 
 		return Fn( () => {
@@ -257,6 +271,7 @@ export class LocalExposure extends RenderStage {
 			const lid = localId.y.mul( uint( 8 ) ).add( localId.x );
 			const ox = int( workgroupId.x ).mul( int( BLUR_TEXEL ) ), oy = int( workgroupId.y ).mul( int( BLUR_TEXEL ) );
 			const sum = float( 0 ).toVar();
+			const covered = float( 0 ).toVar();
 			const count = float( 0 ).toVar();
 
 			Loop( { start: int( localId.y ), end: int( BLUR_TEXEL ), type: 'int', condition: '<', update: 8, name: 'by' }, ( { by } ) => {
@@ -266,9 +281,12 @@ export class LocalExposure extends RenderStage {
 					const x = ox.add( bx ), y = oy.add( by );
 					If( x.lessThan( width ).and( y.lessThan( height ) ), () => {
 
-						const lum = dot( textureLoad( input, ivec2( x, y ) ).xyz, yw ).toVar();
+						const texel = textureLoad( input, ivec2( x, y ) ).toVar();
+						const lum = dot( texel.xyz, yw ).toVar();
 						const finite = floatBitsToUint( lum ).bitAnd( uint( 0x7f800000 ) ).notEqual( uint( 0x7f800000 ) );
-						sum.addAssign( select( finite, lum.max( 0.0 ), float( 0 ) ) );
+						const a = select( sceneOnly.and( texel.w.lessThan( FULL_COVERAGE ) ), float( 0 ), float( 1 ) );
+						sum.addAssign( select( finite, lum.max( 0.0 ).mul( a ), float( 0 ) ) );
+						covered.addAssign( select( finite, a, float( 0 ) ) );
 						count.addAssign( select( finite, float( 1 ), float( 0 ) ) );
 
 					} );
@@ -278,8 +296,10 @@ export class LocalExposure extends RenderStage {
 			} );
 
 			const sharedSum = workgroupArray( 'float', 64 );
+			const sharedCovered = workgroupArray( 'float', 64 );
 			const sharedCount = workgroupArray( 'float', 64 );
 			sharedSum.element( lid ).assign( sum );
+			sharedCovered.element( lid ).assign( covered );
 			sharedCount.element( lid ).assign( count );
 			workgroupBarrier();
 
@@ -288,6 +308,7 @@ export class LocalExposure extends RenderStage {
 				If( lid.lessThan( uint( s ) ), () => {
 
 					sharedSum.element( lid ).addAssign( sharedSum.element( lid.add( uint( s ) ) ) );
+					sharedCovered.element( lid ).addAssign( sharedCovered.element( lid.add( uint( s ) ) ) );
 					sharedCount.element( lid ).addAssign( sharedCount.element( lid.add( uint( s ) ) ) );
 
 				} );
@@ -297,8 +318,10 @@ export class LocalExposure extends RenderStage {
 
 			If( lid.equal( uint( 0 ) ), () => {
 
-				const mean = sharedSum.element( uint( 0 ) ).div( max( sharedCount.element( uint( 0 ) ), 1.0 ) );
-				out.element( uint( int( workgroupId.y ).mul( blurW ).add( int( workgroupId.x ) ) ) ).assign( log2( max( mean, DARKEST ) ).clamp( LOG_FLOOR, LOG_CEIL ) );
+				const mean = sharedSum.element( uint( 0 ) ).div( max( sharedCovered.element( uint( 0 ) ), 1.0 ) );
+				const level = log2( max( mean, DARKEST ) ).clamp( LOG_FLOOR, LOG_CEIL );
+				const share = select( sceneOnly, sharedCovered.element( uint( 0 ) ).div( max( sharedCount.element( uint( 0 ) ), 1.0 ) ), float( 1 ) ).toVar();
+				out.element( uint( int( workgroupId.y ).mul( blurW ).add( int( workgroupId.x ) ) ) ).assign( vec2( level.mul( share ), share ) );
 
 			} );
 
@@ -306,7 +329,8 @@ export class LocalExposure extends RenderStage {
 
 	}
 
-	// Unreal's Gaussian, exp( -16.7 ( x / r )² ), along one axis, mirrored at the edges.
+	// Unreal's Gaussian, exp( -16.7 ( x / r )² ), along one axis, mirrored at the edges. Runs on ( level × share,
+	// share ); the second pass divides it out, so backdrop the build left out takes no part.
 	_buildBlurKernel( src, dst, ax ) {
 
 		const blurW = this._blurWU, blurH = this._blurHU, radius = this._radiusU;
@@ -320,7 +344,7 @@ export class LocalExposure extends RenderStage {
 				const size = ax ? blurW : blurH;
 				const at = ax ? x : y;
 				const reach = int( radius.ceil() );
-				const sum = float( 0 ).toVar();
+				const sum = vec2( 0 ).toVar();
 				const total = float( 0 ).toVar();
 
 				Loop( { start: reach.negate(), end: reach.add( int( 1 ) ), type: 'int', condition: '<', name: 'o' }, ( { o } ) => {
@@ -342,7 +366,8 @@ export class LocalExposure extends RenderStage {
 
 				} );
 
-				dst.element( uint( y.mul( blurW ).add( x ) ) ).assign( sum.div( total ) );
+				const blurred = sum.div( total ).toVar();
+				dst.element( uint( y.mul( blurW ).add( x ) ) ).assign( ax ? blurred : blurred.x.div( max( blurred.y, 1e-30 ) ) );
 
 			} );
 
@@ -390,6 +415,7 @@ export class LocalExposure extends RenderStage {
 		this._blurHU.value = blurH;
 		this._radiusU.value = Math.max( 1, BLUR_PERCENT / 100 * blurW );
 		this._logExposureU.value = logExposure;
+		this._sceneOnlyU.value = context.getState( 'pathtracer:backdrop' ) === 'color' ? 1 : 0;
 		this._kernels[ 0 ].dispatchSize = [ cellsX, cellsY, 1 ];
 		this._kernels[ 1 ].dispatchSize = [ blurW, blurH, 1 ];
 		this._kernels[ 2 ].dispatchSize = this._kernels[ 3 ].dispatchSize = [ Math.ceil( blurW / 8 ), Math.ceil( blurH / 8 ), 1 ];

package/src/Stages/NormalDepth.js

@@ -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';
@@ -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 ),

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';
@@ -410,6 +431,7 @@ export class PathTracer extends PathTracerStage {
 		}
 
 		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 +1658,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 +1874,7 @@ export class PathTracer extends PathTracerStage {
 			iesProfiles: texNodes.iesProfilesTex,
 			alphaShadows: this.uniforms.get( 'enableAlphaShadows' ),
 			materialLayers: this._compiledLayers = this._layersToCompile(),
+			lightRadius: this._compiledLightRadius = this._lightRadiusNeeded(),
 		};
 		const own = ( call ) => withSceneResources( call, resources );
 		const freshEnvTex = _env.environmentTexture ? texture( _env.environmentTexture ) : texNodes.envTex;
@@ -2089,7 +2113,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 +2169,7 @@ export class PathTracer extends PathTracerStage {
 			anamorphicRatio: this.anamorphicRatio,
 			dofMode: this.dofMode,
 			dofBlur: this.dofBlur,
+			cameraClipStart: this.cameraClipStart,
 			bvhBuffer: freshBvh,
 			triangleBuffer: freshTri,
 			materialBuffer: freshMat,