rayzee 11.7.0 → 11.8.0

package/dist/{sceneCachePolicy-B9w3BnaP.js → sceneCachePolicy-D_uBSbQF.js}

@@ -1,7 +1,7 @@
 import { t as e } from "./EngineEvents-CLckhYbL.js";
 import { a as t, i as n, r } from "./Logger-dDDGj9Av.js";
 import { f as i, v as a, y as o } from "./BufferLayout-xPRH9jYD.js";
-import { n as s } from "./EngineIssues-CIZnXHsF.js";
+import { n as s } from "./EngineIssues-xljoXM0E.js";
 import { n as c, r as l } from "./shared-BGBcSxBQ.js";
 import { n as u } from "./AssetConfig-DSEntE65.js";
 import { BackSide as d, BufferAttribute as f, Color as p, DoubleSide as m, FrontSide as h, Matrix3 as g, Matrix4 as _, RGBAFormat as v, Vector2 as y, Vector3 as b } from "three";
@@ -1594,7 +1594,7 @@ var vt = class {
 			samples: this.samples.slice()
 		};
 	}
-}, yt = "11.7.0", $ = 1e4, bt = 15e5;
+}, yt = "11.8.0", $ = 1e4, bt = 15e5;
 function xt(e, t, n = $) {
 	return e >= n && t / bt < e / 3;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "rayzee",
-  "version": "11.7.0",
+  "version": "11.8.0",
   "type": "module",
   "description": "Real-time WebGPU path tracing engine built on Three.js",
   "main": "dist/rayzee.umd.js",

package/src/EngineIssues.js

@@ -6,6 +6,9 @@
  */
 export const ISSUE_CODES = Object.freeze( {
 	ADAPTER_SOFTWARE: 'adapter.software',
+	ADAPTER_UNAVAILABLE: 'adapter.unavailable',
+	DEVICE_UNAVAILABLE: 'device.unavailable',
+	WEBGPU_UNAVAILABLE: 'webgpu.unavailable',
 	ASSET_UNREACHABLE: 'asset.unreachable',
 	ASSET_AMBIGUOUS_ENTRY: 'asset.ambiguous_entry',
 	ASSET_ARCHIVE_TOO_LARGE: 'asset.archive_too_large',
@@ -42,9 +45,9 @@ export const ISSUE_SEVERITY = Object.freeze( { ERROR: 'error', WARNING: 'warning
 
 export class EngineIssueError extends Error {
 
-	constructor( issue ) {
+	constructor( issue, options ) {
 
-		super( `[${issue.code}] ${issue.message}` );
+		super( `[${issue.code}] ${issue.message}`, options );
 		this.name = 'EngineIssueError';
 		this.code = issue.code;
 		this.detail = issue.detail;
@@ -67,13 +70,24 @@ export class IssueLog {
 	/** @throws {EngineIssueError} when strict and severity is 'error' */
 	record( code, message, detail = {}, severity = ISSUE_SEVERITY.ERROR ) {
 
-		const issue = Object.freeze( { code, message, detail, severity, at: Date.now() } );
-		this._entries.push( issue );
+		const issue = this._add( code, message, detail, severity );
+		if ( this.strict && severity === ISSUE_SEVERITY.ERROR ) throw new EngineIssueError( issue );
+		return issue;
 
-		this._onIssue?.( issue );
+	}
 
-		if ( this.strict && severity === ISSUE_SEVERITY.ERROR ) throw new EngineIssueError( issue );
+	/** For what nothing can continue past: records an error and throws it, strict or not. */
+	fail( code, message, detail = {}, cause ) {
 
+		throw new EngineIssueError( this._add( code, message, detail, ISSUE_SEVERITY.ERROR ), cause === undefined ? undefined : { cause } );
+
+	}
+
+	_add( code, message, detail, severity ) {
+
+		const issue = Object.freeze( { code, message, detail, severity, at: Date.now() } );
+		this._entries.push( issue );
+		this._onIssue?.( issue );
 		return issue;
 
 	}

package/src/Passes/AIUpscaler.js

@@ -78,6 +78,7 @@ export class AIUpscaler extends EventDispatcher {
 	 * @param {Function} [options.getGPUTextures] - Returns { color: GPUTexture } for HDR path
 	 * @param {Function} [options.getExposure] - Returns current exposure multiplier
 	 * @param {Function} [options.getToneMapping] - Returns Three.js ToneMapping constant
+	 * @param {Function} [options.getTransparentBackground] - Whether the HDR path keeps the render's coverage as alpha
 	 * @param {number} [options.tileSize] - Override default tile size
 	 */
 	constructor( output, renderer, options = {} ) {
@@ -101,6 +102,7 @@ export class AIUpscaler extends EventDispatcher {
 		this.getToneMapping = options.getToneMapping || ( () => ACESFilmicToneMapping );
 		this.getSaturation = options.getSaturation || ( () => 1.0 );
 		this.getDisplayGain = options.getDisplayGain || ( () => null );
+		this.getTransparentBackground = options.getTransparentBackground || ( () => false );
 
 		// Configuration
 		this.enabled = false;
@@ -506,6 +508,8 @@ export class AIUpscaler extends EventDispatcher {
 			gain: this.getDisplayGain(),
 		} );
 		this._toneMapper.release();
+		// The render's alpha is coverage; the canvas shows an opaque backdrop opaque, and so does the upscale.
+		if ( ! this.getTransparentBackground() ) planes.fill( 1, 3 * width * height );
 
 		return { planes, width, height, isHDR: true };
 

package/src/Passes/OIDNDenoiser.js

@@ -443,10 +443,10 @@ export class OIDNDenoiser extends EventDispatcher {
 
 		} while ( this._reloadPending );
 
-		// Fire a start() that arrived mid-load. Guard on unet+enabled so a failed load
-		// or a disable during loading doesn't kick off a denoise. Outside the loop, so a
-		// no-op reload still releases it — it used to be stranded by the early return below.
-		if ( this._pendingStart && this.unet && this.enabled ) {
+		// Fire a start() that arrived mid-load, unless it was disabled meanwhile. After a failed
+		// load too: it denoises nothing but still sends 'end', which its caller waits for. Outside
+		// the loop, so a no-op reload still releases it — it used to be stranded by the early return below.
+		if ( this._pendingStart && this.enabled ) {
 
 			const continuous = this._pendingStartContinuous;
 			this._pendingStart = false;
@@ -617,8 +617,6 @@ export class OIDNDenoiser extends EventDispatcher {
 
 	async execute( continuous = false ) {
 
-		if ( ! this.enabled || ! this.unet ) return false;
-
 		// Create abort controller for this execution
 		const runId = ++ this._runId;
 		this.state.abortController = new AbortController();
@@ -626,6 +624,10 @@ export class OIDNDenoiser extends EventDispatcher {
 
 		try {
 
+			// Inside the try, so the finally ends what start() announced: with no weights (a failed
+			// load) the Denoising badge, the closing upscaler and a video export waited forever.
+			if ( ! this.enabled || ! this.unet ) return false;
+
 			// The GPU path bails out early — no textures yet, no device — by returning false, and
 			// a caller that read that as success published a picture nothing had written to.
 			return await this._executeUNetGPU( continuous ) !== false;

package/src/PathTracerApp.js

@@ -5,6 +5,7 @@ import { MotionVector } from './Stages/MotionVector.js';
 import { NRD } from './Stages/NRD.js';
 import { AutoExposure, AUTO_EXPOSURE_DEFAULTS } from './Stages/AutoExposure.js';
 import { LocalExposure, LOCAL_EXPOSURE_DEFAULTS } from './Stages/LocalExposure.js';
+import { backdropGain } from './Processor/ToneMapCPU.js';
 import { PRODUCTION_RENDER_CONFIG, INTERACTIVE_RENDER_CONFIG, modePresetSettings } from './EngineDefaults.js';
 import { createLogger } from './utils/Logger.js';
 import { EngineEvents } from './EngineEvents.js';
@@ -323,6 +324,7 @@ export class PathTracerApp extends RayzeeRenderer {
 
 				if ( this.stages.autoExposure ) this.stages.autoExposure.setCompensation( value );
 				else core.applyExposure( value );
+				this.stages.compositor?.setBackdropExposure( value );
 
 			},
 			onCameraProjection: ( value ) => {
@@ -423,7 +425,12 @@ export class PathTracerApp extends RayzeeRenderer {
 		const le = this.stages.localExposure;
 		// A readback outside the loop (headless) can come before the loop would have built it from this image.
 		if ( le?.wantsBuild ) le.build( this.pipeline.context );
-		return le?.toneGain() ?? null;
+		const local = le?.toneGain() ?? null;
+		if ( this.pipeline?.context.getState( 'pathtracer:backdrop' ) !== 'color' ) return local;
+
+		// As the compositor shows it: a solid backdrop at the manual exposure, untouched by auto and local exposure.
+		const { toneMappingExposure, toneMapping } = this.renderer;
+		return { ...local, backdrop: backdropGain( this.settings.get( 'exposure' ) ?? 1, toneMappingExposure, toneMapping ) };
 
 	}
 
@@ -1130,6 +1137,8 @@ export class PathTracerApp extends RayzeeRenderer {
 		if ( ! ae ) return;
 
 		ae.setCompensation( this.settings.get( 'exposure' ) ?? 1 );
+		// A solid backdrop stays at the manual exposure while auto exposure moves the picture.
+		this.stages.compositor.setBackdropExposure( this.settings.get( 'exposure' ) ?? 1 );
 		if ( this.stages.localExposure ) this.stages.localExposure.onChange = () => this._refreshFinished();
 		ae.onChange = () => this._refreshFinished();
 

package/src/Processor/ArchiveImporter.js

@@ -26,9 +26,10 @@ import { loadPBRTScene, pickEntryPath, VirtualFS, PBRT_BUILD_REVISION } from './
 import { loadUSDScene, listUSDRootLayers, listUSDParts, USDFiles, USDStage, USD_LAYER } from './USD/index.js';
 import { pfmTexture } from './PBRT/PFM.js';
 import { extractSceneMetadata } from './SceneMetadata.js';
-import { ISSUE_CODES, ISSUE_SEVERITY } from '../EngineIssues.js';
+import { ISSUE_CODES, ISSUE_SEVERITY, EngineIssueError } from '../EngineIssues.js';
 import { ARCHIVE_FORMATS } from './archiveFormats.js';
-import { withHostWorker } from '../Platform.js';
+import { withHostWorker, getPlatform } from '../Platform.js';
+import { platformImageFromBytes } from './PlatformImageLoader.js';
 
 const MTL_TEXTURE_TIMEOUT_MS = 30000;
 const MAIN_MODEL_FILES = [ 'scene.gltf', 'scene.glb', 'model.gltf', 'model.glb', 'main.gltf', 'main.glb', 'asset.gltf', 'asset.glb' ];
@@ -646,6 +647,7 @@ export class ArchiveImporter {
 
 		const stored = graphKey ? await this._loadStoredGraph( graphKey, source, { imageFromBytes, envFromBytes } ) : null;
 		const built = stored ?? await loadPBRTScene( { vfs: zip, source, entryPath, plyParser, imageFromBytes, envFromBytes, ...shape } );
+		this.loader._throwDeferred();
 
 		const { group, environment, animations, report, warnings, meshCount, entryPath: loadedEntry, candidates,
 			frames, parseMs, buildMs, triangleCount, placementCount, mergedShapes, skippedForBudget,
@@ -729,7 +731,20 @@ export class ArchiveImporter {
 	/** A texture map from an archive, tagged with its path so a stored scene can read it back. @private */
 	async _archiveImage( bytes, fname ) {
 
-		const texture = await this._pbrtTextureFromBytes( bytes, fname );
+		let texture;
+		try {
+
+			texture = await this._pbrtTextureFromBytes( bytes, fname );
+
+		} catch ( error ) {
+
+			// As a glTF's image: its surfaces render untextured, and a strict host hears of it at the end of the load.
+			if ( error instanceof EngineIssueError ) throw error;
+			this.loader._reportImageFailure( fname, error );
+			return null;
+
+		}
+
 		if ( texture ) texture.userData[ ARCHIVE_PATH ] = fname;
 		return texture;
 
@@ -803,6 +818,7 @@ export class ArchiveImporter {
 			maxTriangles: options.maxTriangles, maxPlacements: options.maxPlacements, mergeShapesAbove: options.mergeShapesAbove,
 			curveSteps: options.curveSteps, curveSides: options.curveSides, curveTolerance: options.curveTolerance,
 		} );
+		this.loader._throwDeferred();
 
 		const { group, environment, warnings, triangleCount, placementCount, skippedForBudget, meshCount, parseMs, buildMs, fitNote } = built;
 		this.lastUSDStats = { parseMs, buildMs, loaderMs: performance.now() - start, triangleCount, placementCount, skippedForBudget, meshCount, fitNote };
@@ -915,9 +931,10 @@ export class ArchiveImporter {
 
 		} else {
 
-			// png / jpg / webp / gif / bmp
-			const bitmap = await createImageBitmap( new Blob( [ bytes ] ) );
-			tex = new Texture( bitmap );
+			// png / jpg / webp / gif / bmp: the host's decoder where it has one (Node), else the browser's.
+			if ( getPlatform().decodeImage ) tex = await platformImageFromBytes( bytes, fname );
+			else if ( typeof createImageBitmap === 'function' ) tex = new Texture( await createImageBitmap( new Blob( [ bytes ] ) ) );
+			else throw new Error( 'no image decoder in this runtime: configurePlatform( nodePlatform( { decodeImage } ) ) — see "Running in Node"' );
 			tex.colorSpace = SRGBColorSpace;
 
 		}

package/src/Processor/AssetLoader.js

@@ -52,6 +52,20 @@ function standInForSplit( source ) {
 
 }
 
+// glTF's znear is a camera's near clipping plane (Blender writes its clip start there): the path tracer honours it.
+export const cameraClipPlugin = {
+	name: 'RAYZEE_camera_clip',
+	afterRoot( result ) {
+
+		for ( const scene of result.scenes ) scene.traverse( ( object ) => {
+
+			if ( object.isCamera && object.near > 0 ) object.userData.clipStart = object.near;
+
+		} );
+
+	},
+};
+
 // Luminous efficacy glTF, three.js and Blender's exporter all assume (PBR_WATTS_TO_LUMENS).
 const LUMENS_PER_WATT = 683;
 
@@ -768,6 +782,7 @@ export class AssetLoader extends EventDispatcher {
 		if ( getPlatform().decodeImage ) loader.register( ( parser ) => platformImagesPlugin( parser, onImageFailure ) );
 		else if ( ! hasImageDecoder() ) loader.register( ( parser ) => missingImageDecoderPlugin( parser, onImageFailure ) );
 		loader.register( ( parser ) => diffuseTransmissionPlugin( parser ) );
+		loader.register( () => cameraClipPlugin );
 
 		return loader;
 

package/src/Processor/LightSerializer.js

@@ -32,6 +32,9 @@ function effectiveEmission( light ) {
 
 }
 
+// A point or spot light's radius (Blender's Radius, USD's SphereLight radius): `userData.radius`, in scene units.
+const lightRadius = ( light ) => Math.max( 0, Number( light.userData?.radius ) || 0 );
+
 export class LightSerializer {
 
 	constructor() {
@@ -216,7 +219,8 @@ export class LightSerializer {
 				em.r, em.g, em.b, // color (3) — incl. temperature tint
 				em.intensity * INV_4PI, // radiant intensity W/sr = power(W)/4π, incl. exposure (1)
 				light.distance || 0.0, // cutoff distance (0 = infinite) (1)
-				light.decay !== undefined ? light.decay : 2.0 // decay exponent (1)
+				light.decay !== undefined ? light.decay : 2.0, // decay exponent (1)
+				lightRadius( light ), // radius: a disc this size facing the lit point, 0 = a point (1)
 			],
 			importance: importance,
 			light: light
@@ -266,7 +270,7 @@ export class LightSerializer {
 				goboIntensity, // signed gobo strength (1)
 				iesIndex, // IES profile index, -1 = none (1)
 				iesIntensity, // IES blend [0,1] (1)
-				0.0, // reserved (1)
+				lightRadius( light ), // radius, as a point light's (1)
 				0.0, // reserved (1) — keeps stride at 20 (vec4 aligned)
 			],
 			importance: importance,

package/src/Processor/PBRT/PBRTMaterials.js

@@ -393,7 +393,8 @@ export async function buildMaterial( def, ctx ) {
 		case 'metal': {
 
 			await applyConductorColor( mat, params, ctx, '', applyAlbedo, setColor );
-			await applyRoughness( mat, 'roughness', params, 0.1, ctx );
+			// pbrt's roughness defaults to 0, a mirror.
+			await applyRoughness( mat, 'roughness', params, 0, ctx );
 			break;
 
 		}

package/src/Processor/PBRT/PBRTSceneBuilder.js

@@ -108,7 +108,7 @@ const DEFAULT_CURVE_SIDES = { flat: 1, ribbon: 1, cylinder: 2 };
 const DEFAULT_CURVE_TOLERANCE = 0.05;
 
 /** Bumped whenever the same scene files build a different graph, so a stored graph is not reused. */
-export const PBRT_BUILD_REVISION = 10;
+export const PBRT_BUILD_REVISION = 11;
 
 function samePlacements( a, b ) {
 

package/src/Processor/PlatformImageLoader.js

@@ -97,6 +97,15 @@ export async function loadPlatformImage( url, mimeType = mimeTypeOf( { uri: url
 
 }
 
+/** An image file's bytes as a texture, decoded by the platform: {@link loadPlatformImage} without the fetch. */
+export async function platformImageFromBytes( bytes, filename ) {
+
+	const texture = pixelTexture( await decodeBytes( bytes, mimeTypeOf( { uri: filename } ) ), { shared: true } );
+	texture.flipY = true;
+	return texture;
+
+}
+
 /**
  * A GLTFLoader plugin for a runtime with no way to decode an image (Node without `decodeImage`): each image fails with
  * what to configure, where three.js's own path threw `self is not defined` and took the whole load down.

package/src/Processor/TextureCreator.js

@@ -1,4 +1,4 @@
-import { DataArrayTexture, RGBAFormat, LinearFilter, UnsignedByteType, SRGBColorSpace, LinearSRGBColorSpace, RepeatWrapping, FloatType, HalfFloatType } from "three";
+import { DataArrayTexture, RGBAFormat, RGFormat, RedFormat, LinearFilter, UnsignedByteType, UnsignedShortType, SRGBColorSpace, LinearSRGBColorSpace, RepeatWrapping, FloatType, HalfFloatType, DataUtils } from "three";
 import { MATERIAL_DATA_LAYOUT, BVH_LEAF_MARKERS, assertBVHIndexFits, bvhIndexView } from './BufferLayout.js';
 import { alignBucketWidth, TEXTURE_CONSTANTS } from './TextureBuckets.js';
 import { packMaterial } from './MaterialPacking.js';
@@ -1260,7 +1260,7 @@ export class TextureCreator {
 
 			const image = texture?.image;
 			const pixels = texture?.isCompressedTexture ? texture.mipmaps?.[ 0 ] : image;
-			const data = pixels?.data;
+			const data = texture?.isCompressedTexture ? pixels?.data : rgba8Pixels( texture );
 			if ( data && pixels.width > 0 && pixels.height > 0 && data.byteLength >= pixels.width * pixels.height * 4 ) {
 
 				return { data: new Uint8Array( data.buffer, data.byteOffset, pixels.width * pixels.height * 4 ), width: pixels.width, height: pixels.height, flipY: texture.flipY !== false };
@@ -1817,7 +1817,8 @@ export class TextureCreator {
 
 				const idx = normalized.length;
 				normalized.push( null );
-				bitmapJobs.push( { index: idx, flipY: tex.flipY, promise: _rawPixelsToBitmap( tex.image.data, tex.image.width, tex.image.height ) } );
+				const pixels = rgba8Pixels( tex );
+				bitmapJobs.push( { index: idx, flipY: tex.flipY, promise: pixels ? _rawPixelsToBitmap( pixels, tex.image.width, tex.image.height ) : Promise.reject( new Error( 'pixels in a layout the texture arrays cannot take' ) ) } );
 				continue;
 
 			}
@@ -1900,10 +1901,49 @@ export class TextureCreator {
 // ── Helpers ──────────────────────────────────────────────────────────
 
 /** Convert raw RGBA pixel data to an ImageBitmap (zero-copy Uint8ClampedArray view). */
-function _rawPixelsToBitmap( data, width, height ) {
+// Async, so a bad layer rejects into its placeholder instead of throwing through the whole bucket.
+async function _rawPixelsToBitmap( data, width, height ) {
 
 	const clamped = new Uint8ClampedArray( data.buffer, data.byteOffset, data.byteLength );
 	return createImageBitmap( new ImageData( clamped, width, height ) );
 
 }
 
+/**
+ * A data texture's pixels as RGBA8 (the arrays are 8-bit), or null. Float and half-float maps — an archive's EXR, HDR or
+ * PFM — clamp to [0, 1]; one channel fills grey. Read as bytes, a float buffer was noise in Node and failed the bucket in
+ * the browser.
+ */
+export function rgba8Pixels( texture ) {
+
+	const image = texture?.image;
+	const data = image?.data;
+	if ( ! data || ! ( image.width > 0 ) || ! ( image.height > 0 ) ) return null;
+	const count = image.width * image.height;
+	if ( data instanceof Uint8Array || data instanceof Uint8ClampedArray ) {
+
+		return data.byteLength >= count * 4 ? new Uint8Array( data.buffer, data.byteOffset, count * 4 ) : null;
+
+	}
+
+	const channels = { [ RGBAFormat ]: 4, [ RGFormat ]: 2, [ RedFormat ]: 1 }[ texture.format ] ?? Math.round( data.length / count );
+	if ( ! ( channels >= 1 && channels <= 4 ) || data.length < count * channels ) return null;
+	const half = texture.type === HalfFloatType;
+	const scale = texture.type === UnsignedShortType ? 1 / 65535 : 1;
+	const out = new Uint8Array( count * 4 );
+	for ( let i = 0; i < count; i ++ ) {
+
+		for ( let c = 0; c < 4; c ++ ) {
+
+			const raw = c < channels ? data[ i * channels + c ] : null;
+			const v = raw === null ? ( c === 3 ? 1 : out[ i * 4 ] / 255 ) : ( half ? DataUtils.fromHalfFloat( raw ) : raw * scale );
+			out[ i * 4 + c ] = Math.max( 0, Math.min( 255, Math.round( v * 255 ) ) );
+
+		}
+
+	}
+
+	return out;
+
+}
+

package/src/Processor/ToneMapCPU.js

@@ -98,6 +98,26 @@ export function effectiveExposure( exposure, toneMapping ) {
 
 }
 
+/**
+ * The gain that shows a pixel of a solid backdrop at `heldAt` while the picture is shown at `exposure`: auto
+ * exposure does not move the backdrop. 1 under a view that applies no exposure.
+ */
+export function backdropGain( heldAt, exposure, toneMapping ) {
+
+	return effectiveExposure( heldAt, toneMapping ) / effectiveExposure( exposure, toneMapping );
+
+}
+
+/**
+ * A pixel's gain once the backdrop is held: `backdrop` where the camera saw only the backdrop (coverage 0), the
+ * scene's own gain where it saw the scene, blended by coverage between. The GPU pass computes the same.
+ */
+export function heldGain( gain, backdrop, coverage ) {
+
+	return gain + ( backdrop - gain ) * ( 1 - Math.min( Math.max( coverage, 0 ), 1 ) );
+
+}
+
 /** Rec.709 luminance coefficients (same as Display / Common.js). */
 const LUM_R = 0.2126, LUM_G = 0.7152, LUM_B = 0.0722;
 
@@ -128,8 +148,9 @@ export function applySaturation( out, saturation ) {
  * @param {number} options.toneMapping - a registered view transform id
  * @param {number} [options.saturation=1]
  * @param {boolean} [options.preserveAlpha=false]
- * @param {{fn: function(number, number, number, number): number, width: number, height: number}} [options.pixelGain] -
- *   the twin of the GPU pass's `gain`: `fn( u, v, luminance, log2 exposure )` per pixel, before the curve
+ * @param {{fn?: function(number, number, number, number): number, width: number, height: number, backdrop?: number}} [options.pixelGain] -
+ *   the twin of the GPU pass's `gain`: `fn( u, v, luminance, log2 exposure )` per pixel, before the curve, and
+ *   `backdrop` the gain a solid backdrop is held at (`heldGain`)
  * @returns {Uint8ClampedArray} RGBA bytes
  */
 export function toneMapToRGBA8( linear, { exposure, toneMapping, saturation = 1, preserveAlpha = false, pixelGain = null } ) {
@@ -146,9 +167,17 @@ export function toneMapToRGBA8( linear, { exposure, toneMapping, saturation = 1,
 		let g = gain;
 		if ( pixelGain ) {
 
-			const p = i >> 2, x = p % pixelGain.width, y = ( p - x ) / pixelGain.width;
-			const lum = linear[ i ] * 0.2126 + linear[ i + 1 ] * 0.7152 + linear[ i + 2 ] * 0.0722;
-			g *= pixelGain.fn( ( x + 0.5 ) / pixelGain.width, ( y + 0.5 ) / pixelGain.height, lum, logExposure );
+			let pg = 1;
+			if ( pixelGain.fn ) {
+
+				const p = i >> 2, x = p % pixelGain.width, y = ( p - x ) / pixelGain.width;
+				const lum = linear[ i ] * 0.2126 + linear[ i + 1 ] * 0.7152 + linear[ i + 2 ] * 0.0722;
+				pg = pixelGain.fn( ( x + 0.5 ) / pixelGain.width, ( y + 0.5 ) / pixelGain.height, lum, logExposure );
+
+			}
+
+			if ( pixelGain.backdrop > 0 ) pg = heldGain( pg, pixelGain.backdrop, linear[ i + 3 ] );
+			g *= pg;
 
 		}
 

package/src/Processor/ToneMapGPU.js

@@ -97,6 +97,7 @@ struct Params {
 	exposure: f32,
 	saturation: f32,
 	alpha: u32,
+	backdrop: f32,
 };
 
 @group(0) @binding(2) var<uniform> params: Params;
@@ -115,12 +116,15 @@ fn main( @builtin(global_invocation_id) gid: vec3<u32> ) {
 
 	let linear = rayzee_source( gid.x, srcY );
 	let uv = vec2<f32>( ( f32( gid.x ) + 0.5 ) / f32( params.width ), ( f32( gid.y ) + 0.5 ) / f32( params.height ) );
-	let rgb = linear.rgb${gainWGSL ? ' * rayzee_gain( uv, linear.rgb, params.exposure )' : ''};
+	var g = ${gainWGSL ? 'rayzee_gain( uv, linear.rgb, params.exposure )' : '1.0'};
+	// A solid backdrop is held at its own gain, blended by the coverage in alpha (ToneMapCPU's heldGain).
+	if ( params.backdrop > 0.0 ) { g = g + ( params.backdrop - g ) * ( 1.0 - clamp( linear.a, 0.0, 1.0 ) ); }
+	let rgb = linear.rgb * g;
 	rayzee_store( gid.y * params.width + gid.x, linear, rayzee_tone_map( rgb, params.mode, params.exposure, params.saturation ) );
 }
 `;
 
-/** Uniform blocks round up to 16 bytes; the struct above is 28. */
+/** Uniform blocks round up to 16 bytes; the struct above is 32. */
 const PARAMS_BYTES = 32;
 
 /**
@@ -171,7 +175,7 @@ export class PackedToneMapper {
 
 		}
 
-		const key = gain?.key ?? '';
+		const key = gain?.wgsl ? gain.key : '';
 		let pipeline = this._pipelines.get( key );
 		if ( pipeline ) return pipeline;
 
@@ -275,9 +279,10 @@ export class PackedToneMapper {
 	 * @param {number} [tone.saturation=1]
 	 * @param {boolean} [tone.flipY=false]
 	 * @param {boolean} [tone.preserveAlpha=false] - the source's alpha, rounded as the CPU rounds it; else 255
-	 * @param {{key: string, wgsl: string, entries: GPUBindGroupEntry[], device?: GPUDevice, copyTo?: Function}} [tone.gain] - a
-	 *   per-pixel gain before the curve: WGSL defining `rayzee_gain( uv, linear, exposure ) -> f32` over bind group 1.
-	 *   One on another device is copied to this one for the run (`copyTo`).
+	 * @param {{key?: string, wgsl?: string, entries?: GPUBindGroupEntry[], device?: GPUDevice, copyTo?: Function, backdrop?: number}} [tone.gain] - a
+	 *   per-pixel gain before the curve: WGSL defining `rayzee_gain( uv, linear, exposure ) -> f32` over bind group 1,
+	 *   and/or `backdrop`, the gain a solid backdrop is held at (coverage in alpha). One on another device is copied
+	 *   to this one for the run (`copyTo`).
 	 * @returns {Promise<Uint8ClampedArray>} RGBA bytes, `width * height * 4`
 	 */
 	async toRGBA8( src, tone ) {
@@ -302,12 +307,12 @@ export class PackedToneMapper {
 	async _run( src, tone = {} ) {
 
 		const gain = tone.gain;
-		if ( ! gain?.device || gain.device === this.device ) return this._dispatch( src, tone );
+		if ( ! gain?.wgsl || ! gain.device || gain.device === this.device ) return this._dispatch( src, tone );
 
 		const copy = await gain.copyTo( this.device );
 		try {
 
-			return await this._dispatch( src, { ...tone, gain: copy } );
+			return await this._dispatch( src, { ...tone, gain: { ...copy, backdrop: gain.backdrop } } );
 
 		} finally {
 
@@ -337,6 +342,7 @@ export class PackedToneMapper {
 		this._paramF32[ 4 ] = exposure;
 		this._paramF32[ 5 ] = saturation;
 		this._paramU32[ 6 ] = preserveAlpha ? 1 : 0;
+		this._paramF32[ 7 ] = gain?.backdrop > 0 ? gain.backdrop : 0;
 		this.device.queue.writeBuffer( this._params, 0, this._paramData );
 
 		const tableEntries = [ ...this._tables.entries() ]
@@ -356,7 +362,7 @@ export class PackedToneMapper {
 		const pass = encoder.beginComputePass();
 		pass.setPipeline( pipeline );
 		pass.setBindGroup( 0, group );
-		if ( gain ) pass.setBindGroup( 1, this.device.createBindGroup( { layout: pipeline.getBindGroupLayout( 1 ), entries: gain.entries } ) );
+		if ( gain?.wgsl ) pass.setBindGroup( 1, this.device.createBindGroup( { layout: pipeline.getBindGroupLayout( 1 ), entries: gain.entries } ) );
 		pass.dispatchWorkgroups( Math.ceil( width / 8 ), Math.ceil( height / 8 ) );
 		pass.end();
 		encoder.copyBufferToBuffer( this._storage, 0, this._map, 0, bytes );