rayzee 11.6.0 → 11.8.0

package/dist/{sceneCachePolicy-W5PLbzuR.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.6.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.6.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

@@ -55,8 +55,8 @@ const MODEL_CONFIG = {
 	DEFAULT_OPTIONS: {
 		enableOIDN: true,
 		oidnQuality: 'fast',
-		// A cap on the frame, not a tile size: a frame that fits is one tile, with no overlap.
-		// It bounds the network's activation memory (~430 MB at 1024²).
+		// A cap on the frame, not a tile size: a frame no larger in area than this square is one
+		// tile, with no overlap. The area bounds the network's activation memory.
 		tileSize: 1024
 	}
 };
@@ -382,16 +382,14 @@ export class OIDNDenoiser extends EventDispatcher {
 	 */
 	_resolveTileSize() {
 
-		const longest = Math.max( this._renderWidth, this._renderHeight );
-		if ( ! longest ) return this.maxTileSize;
+		if ( ! this._renderWidth || ! this._renderHeight ) return this.maxTileSize;
 
-		// The cap is on the frame, so the border never splits a frame that fits one tile.
-		if ( longest <= this.maxTileSize ) {
-
-			const input = oidnInputSize( this._renderWidth, this._renderHeight );
-			return Math.max( input.width, input.height );
-
-		}
+		// One tile for any frame no larger in area than the square the cap allows: oidn-web's memory
+		// follows the tile's area, not its longest side, so a wide frame needs no split. The cap is on
+		// the frame, so the border never splits a frame that fits.
+		const input = oidnInputSize( this._renderWidth, this._renderHeight );
+		const largest = oidnInputSize( this.maxTileSize, this.maxTileSize );
+		if ( input.width * input.height <= largest.width * largest.height ) return Math.max( input.width, input.height );
 
 		return Math.max( OIDN_TILE_ALIGNMENT, Math.floor( this.maxTileSize / OIDN_TILE_ALIGNMENT ) * OIDN_TILE_ALIGNMENT );
 
@@ -445,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;
@@ -619,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();
@@ -628,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

@@ -2,13 +2,10 @@ import { Box3, Vector3 } from 'three';
 import { RayzeeRenderer, describeAdapter, RENDER_CHECKPOINT_VERSION } from './RayzeeRenderer.js';
 import { NormalDepth } from './Stages/NormalDepth.js';
 import { MotionVector } from './Stages/MotionVector.js';
-import { ASVGF } from './Stages/ASVGF.js';
 import { NRD } from './Stages/NRD.js';
-import { Variance } from './Stages/Variance.js';
-import { BilateralFilter } from './Stages/BilateralFilter.js';
-import { EdgeFilter } from './Stages/EdgeFilter.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';
@@ -151,17 +148,12 @@ export class PathTracerApp extends RayzeeRenderer {
 		const { renderer, stages } = this;
 		stages.normalDepth = new NormalDepth( renderer, { pathTracer: stages.pathTracer } );
 		stages.motionVector = new MotionVector( renderer, this.camera, { pathTracer: stages.pathTracer } );
-		stages.asvgf = new ASVGF( renderer, { enabled: false } );
 		stages.nrd = new NRD( renderer, { enabled: false, pathTracer: stages.pathTracer } );
-		stages.variance = new Variance( renderer, { enabled: false } );
-		stages.bilateralFilter = new BilateralFilter( renderer, { enabled: false } );
-		stages.edgeFilter = new EdgeFilter( renderer, { enabled: false } );
 		stages.autoExposure = new AutoExposure( renderer, { enabled: AUTO_EXPOSURE_DEFAULTS.autoExposure } );
 		stages.localExposure = new LocalExposure( renderer, { enabled: LOCAL_EXPOSURE_DEFAULTS.localExposure } );
 
 		return [
-			stages.normalDepth, stages.motionVector, stages.nrd, stages.asvgf,
-			stages.variance, stages.bilateralFilter, stages.edgeFilter, stages.autoExposure, stages.localExposure,
+			stages.normalDepth, stages.motionVector, stages.nrd, stages.autoExposure, stages.localExposure,
 		];
 
 	}
@@ -318,7 +310,7 @@ export class PathTracerApp extends RayzeeRenderer {
 
 	_displaySources() {
 
-		return [ 'oidn:output', 'edgeFiltering:output', 'bilateralFiltering:output', 'asvgf:output', 'nrd:output' ];
+		return [ 'oidn:output', 'nrd:output' ];
 
 	}
 
@@ -332,14 +324,17 @@ 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 ) => {
 
 				this.cameraManager.applyProjection( value );
 				// MotionVector unprojects through projectionMatrixInverse, which is meaningless once every pixel is its
-				// own direction: fall back to the spatial-only denoiser rather than leaving no strategy.
-				if ( value === 'equirectangular' && this.denoisingManager?.requiresMotionVectors ) this.denoisingManager.setDenoiserStrategy( 'edgeaware' );
+				// own direction: hand the view to OIDN, which needs none, rather than leaving no denoiser.
+				if ( value === 'equirectangular' && this.denoisingManager?.requiresMotionVectors ) this.denoisingManager.setDenoiserStrategy( 'oidn' );
+				// OIDN's motion history is off in a panorama and back on outside one.
+				else this.denoisingManager?._syncGBufferStages?.();
 
 			},
 		};
@@ -430,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 ) };
 
 	}
 
@@ -1106,11 +1106,7 @@ export class PathTracerApp extends RayzeeRenderer {
 				pathTracer: this.stages.pathTracer,
 				normalDepth: this.stages.normalDepth,
 				motionVector: this.stages.motionVector,
-				asvgf: this.stages.asvgf,
 				nrd: this.stages.nrd,
-				variance: this.stages.variance,
-				bilateralFilter: this.stages.bilateralFilter,
-				edgeFilter: this.stages.edgeFilter,
 				autoExposure: this.stages.autoExposure,
 				compositor: this.stages.compositor,
 			},
@@ -1141,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/Pipeline/BindingAudit.js

@@ -3,13 +3,12 @@
  *
  * Two TextureNodes still holding the default EmptyTexture when a stage's kernel is first
  * compiled can share one GPU binding, which then resolves to whichever is assigned last.
- * Nothing throws — the aliased node reads a real texture, just not its own. BilateralFilter
- * shipped this way, reading ASVGF's history counter as its variance.
+ * Nothing throws — the aliased node reads a real texture, just not its own.
  *
  * Rule enforced: every TextureNode a kernel reads must hold its real texture before that
  * kernel is first dispatched. StorageTexture-typed nodes are exempt — `textureLoad` codegen
  * only emits the required `level` parameter while the node still holds EmptyTexture, so those
- * are deliberately bound after compile (see ASVGF.render).
+ * are deliberately bound after compile.
  *
  * Off by default; the bench harness turns it on.
  */

package/src/Pipeline/PipelineContext.js

@@ -43,7 +43,6 @@ export class PipelineContext {
 
 			// Render modes
 			renderMode: 0, // 0 = interactive, 1 = production (full-frame in both)
-			interactionMode: false,
 			isComplete: false,
 
 			// Tile rendering

package/src/Pipeline/RenderPipeline.js

@@ -23,8 +23,7 @@ import { ISSUE_CODES } from '../EngineIssues.js';
  *
  * // Add stages in execution order
  * pipeline.addStage(new PathTracer(...));
- * pipeline.addStage(new ASVGF(...));
- * pipeline.addStage(new EdgeFilter(...));
+ * pipeline.addStage(new NRD(...));
  *
  * // Render all stages
  * pipeline.render(writeBuffer);

package/src/Pipeline/RenderStage.js

@@ -12,7 +12,7 @@ export const StageExecutionMode = {
 
 	/**
 	 * PER_CYCLE - Execute only when tile rendering cycle completes
-	 * Use for: Post-processing, denoisers, filters (ASVGF, EdgeAwareFiltering, OIDN)
+	 * Use for: Post-processing, denoisers, filters (NRD, OIDN)
 	 *
 	 * Complete cycle means:
 	 * - Progressive mode (renderMode=0): Every frame

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/PackedRayBuffer.js

@@ -424,7 +424,7 @@ export const writeMediumStack = ( buf, id, stackDepth, transTraversals, ior1, io
 		), ior1, ior2, ior3 ) );
 
 // Region 7: Beer-Lambert sigmaA (.xyz) of the active medium + DDFA feature-throughput (.w).
-// .xyz absorption is gated on stackDepth>0; .w carries the OIDN/ASVGF see-through aux tint (see below).
+// .xyz absorption is gated on stackDepth>0; .w carries the OIDN/NRD see-through aux tint (see below).
 // Both writers RMW-preserve the other half so sigmaA (live in glass) and featTP never clobber each other.
 export const readMediumSigmaA = ( buf, id ) => buf.element( soa( id, RAY.MEDIUM_SIGMA_A ) ).xyz;
 
@@ -436,7 +436,7 @@ export const writeMediumSigmaA = ( buf, id, sigmaA ) => {
 };
 
 // DDFA (Deferred Denoising-Feature Aux) feature-throughput: a clean per-ray tint carried through smooth
-// glass/mirror, committed into the OIDN/ASVGF albedo guide at the first diffuse-enough surface. Rides the
+// glass/mirror, committed into the OIDN/NRD albedo guide at the first diffuse-enough surface. Rides the
 // otherwise-dead MEDIUM_SIGMA_A.w, packed 10/10/10 into 30 bits (top 2 bits zero ⇒ the float bit-pattern is
 // always finite — never NaN/Inf). LDR [0,1] per channel; final albedo re-quantizes to unorm16 anyway.
 const pack30 = ( tp ) => {

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/StorageTexturePool.js

@@ -7,7 +7,7 @@
  *  - 1 MRT RenderTarget (3 attachments) used as the readable copy
  *  - After each compute dispatch, copyTextureToTexture() transfers data
  *    from StorageTextures → RenderTarget textures
- *  - Downstream stages (ASVGF, display, OIDN) read from the RenderTarget
+ *  - Downstream stages (NRD, display, OIDN) read from the RenderTarget
  *  - Previous-frame reads in the path tracer sample from RenderTarget textures
  *    via texture() (not storageTexture().toReadOnly())
  */

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;
 
 		}