rayzee 11.7.0 → 11.9.0

package/src/Processor/PBRT/PBRTTextureBake.js

@@ -5,10 +5,15 @@
  * A layer is an image as pbrt evaluates it: linear values, top row first, `channels` 1 (a float texture reads
  * an image's alpha where it has one, else the mean of its colour) or 3, already scaled and inverted, and the uv
  * mapping pbrt applies before the lookup (st = scale · uv + delta, image row from the top = 1 − t).
+ *
+ * pbrt's position mappings (`planar`, `spherical`, `cylindrical`) read no uv: their (s, t) becomes a uv set generated per
+ * shape (`generateUV`), and a layer in one carries it as `uv` (`{ type, key, … }`; null for the mesh's own uv).
  */
 
 const MAX_BAKE_SIZE = 4096;
 
+export const uvKey = ( uv ) => uv?.key ?? '';
+
 export const srgbToLinear = ( v ) => ( v <= 0.04045 ? v / 12.92 : ( ( v + 0.055 ) / 1.055 ) ** 2.4 );
 export const linearToSRGB = ( v ) => ( v <= 0.0031308 ? v * 12.92 : 1.055 * v ** ( 1 / 2.4 ) - 0.055 );
 
@@ -20,7 +25,7 @@ export const linearToSRGB = ( v ) => ( v <= 0.0031308 ? v * 12.92 : 1.055 * v **
  * @param {(v: number) => number} [options.decode] - 8-bit value / 255 → linear; omitted for float data
  * @param {number} [options.scale=1]
  * @param {boolean} [options.invert=false]
- * @param {{ su: number, sv: number, du: number, dv: number }} [options.mapping]
+ * @param {{ su: number, sv: number, du: number, dv: number, uv?: object }} [options.mapping]
  */
 export function makeLayer( pixels, { channels, decode = null, scale = 1, invert = false, mapping = null } ) {
 
@@ -29,7 +34,9 @@ export function makeLayer( pixels, { channels, decode = null, scale = 1, invert
 	const data = new Float32Array( width * height * channels );
 	const topDown = pixels.topDown !== false;
 	// pbrt's encoding applies to every channel of an 8-bit image, alpha included.
-	const read = ( i ) => ( decode ? decode( pixels.data[ i ] / 255 ) : pixels.data[ i ] );
+	const bytes = decode && ( pixels.data instanceof Uint8Array || pixels.data instanceof Uint8ClampedArray );
+	const lut = bytes ? Float64Array.from( { length: 256 }, ( _, v ) => decode( v / 255 ) ) : null;
+	const read = lut ? ( i ) => lut[ pixels.data[ i ] ] : ( i ) => ( decode ? decode( pixels.data[ i ] / 255 ) : pixels.data[ i ] );
 	const fromAlpha = channels === 1 && stride === 4 && hasAlpha( pixels );
 	const mean = channels === 1 && stride >= 3 && ! fromAlpha;
 
@@ -53,7 +60,7 @@ export function makeLayer( pixels, { channels, decode = null, scale = 1, invert
 
 	}
 
-	return { width, height, channels, data, su: 1, sv: 1, du: 0, dv: 0, ...mapping };
+	return { width, height, channels, data, su: 1, sv: 1, du: 0, dv: 0, uv: null, ...mapping };
 
 }
 
@@ -76,6 +83,15 @@ export function layerMean( layer ) {
 
 }
 
+function layerMeanRGB( { data, channels } ) {
+
+	const sum = [ 0, 0, 0 ];
+	for ( let i = 0; i < data.length; i ++ ) sum[ i % channels ] += data[ i ];
+	const texels = data.length / channels || 1;
+	return [ 0, 1, 2 ].map( ( c ) => sum[ Math.min( c, channels - 1 ) ] / texels );
+
+}
+
 // Bilinear, repeating, at pbrt's (s, t).
 function sample( layer, s, t, out ) {
 
@@ -102,20 +118,36 @@ function sample( layer, s, t, out ) {
 /**
  * Each term is `{ rgb }` (a constant) or `{ layer, tint? }` (an image, times `tint`); `clamp` clamps it to [0, 1]
  * first, as pbrt clamps a colour texture read as an albedo, before anything mixes it. Evaluates
- * `combine( values )` over the texel grid of the largest image among the terms, in that image's uv mapping;
- * a term with another mapping is sampled through it. The result is sRGB bytes laid out for a DataTexture
+ * `combine( values )` over the texel grid of the largest image among the terms in the first image's uv set, in that
+ * image's uv mapping; a term with another mapping is sampled through it, and one in another uv set counts as its mean
+ * (`averaged` says how many). The result is sRGB bytes laid out for a DataTexture
  * (bottom row first), clamped to [0, 1] as pbrt clamps an albedo. Null when every term is a constant.
  * @param {Array<{ rgb?: number[], layer?: object, tint?: number[] }>} terms
  * @param {(values: number[][]) => number[]} combine - linear RGB from each term's linear RGB
  * @param {object} [options]
  * @param {(values: number[][]) => number} [options.alphaOf] - the alpha channel, linear; opaque without it
  * @param {boolean} [options.linear=false] - linear bytes, for a data map
- * @returns {{ data: Uint8Array, width: number, height: number, mapping: { su: number, sv: number, du: number, dv: number } } | null}
+ * @returns {{ data: Uint8Array, width: number, height: number, mapping: { su: number, sv: number, du: number, dv: number, uv: object|null }, averaged: number } | null}
  */
 export function bake( terms, combine, { alphaOf = null, linear = false } = {} ) {
 
-	let driver = null;
-	for ( const term of terms ) if ( term.layer && ( ! driver || term.layer.width * term.layer.height > driver.width * driver.height ) ) driver = term.layer;
+	const set = uvKey( terms.find( ( term ) => term.layer )?.layer.uv );
+	let driver = null, averaged = 0;
+	terms = terms.map( ( term ) => {
+
+		if ( ! term.layer ) return term;
+		if ( uvKey( term.layer.uv ) !== set ) {
+
+			averaged ++;
+			const mean = layerMeanRGB( term.layer );
+			return { rgb: mean.map( ( v, c ) => v * ( term.tint?.[ c ] ?? 1 ) ), clamp: term.clamp };
+
+		}
+
+		if ( ! driver || term.layer.width * term.layer.height > driver.width * driver.height ) driver = term.layer;
+		return term;
+
+	} );
 	if ( ! driver ) return null;
 
 	const width = Math.min( driver.width, MAX_BAKE_SIZE ), height = Math.min( driver.height, MAX_BAKE_SIZE );
@@ -166,7 +198,7 @@ export function bake( terms, combine, { alphaOf = null, linear = false } = {} )
 
 	}
 
-	return { data: out, width, height, mapping: { su: driver.su, sv: driver.sv, du: driver.du, dv: driver.dv } };
+	return { data: out, width, height, mapping: { su: driver.su, sv: driver.sv, du: driver.du, dv: driver.dv, uv: driver.uv ?? null }, averaged };
 
 }
 
@@ -177,3 +209,153 @@ export const mixOf = ( [ a, b, amount ] ) => {
 	return [ a[ 0 ] + ( b[ 0 ] - a[ 0 ] ) * t, a[ 1 ] + ( b[ 1 ] - a[ 1 ] ) * t, a[ 2 ] + ( b[ 2 ] - a[ 2 ] ) * t ];
 
 };
+
+// The coordinate that goes once around the axis: spherical φ is t, cylindrical φ is s.
+const WRAPPED = { spherical: 1, cylindrical: 0 };
+
+/** pbrt-v4's (s, t) of a point in texture space (textures.h: PlanarMapping, SphericalMapping, CylindricalMapping). */
+export function mapPoint( mapping, x, y, z, out ) {
+
+	if ( mapping.type === 'planar' ) {
+
+		const { vs, vt } = mapping;
+		out[ 0 ] = mapping.ds + x * vs[ 0 ] + y * vs[ 1 ] + z * vs[ 2 ];
+		out[ 1 ] = mapping.dt + x * vt[ 0 ] + y * vt[ 1 ] + z * vt[ 2 ];
+
+	} else if ( mapping.type === 'spherical' ) {
+
+		const length = Math.hypot( x, y, z ) || 1;
+		const phi = Math.atan2( y, x );
+		out[ 0 ] = Math.acos( Math.min( 1, Math.max( - 1, z / length ) ) ) / Math.PI;
+		out[ 1 ] = ( phi < 0 ? phi + 2 * Math.PI : phi ) / ( 2 * Math.PI );
+
+	} else {
+
+		out[ 0 ] = ( Math.PI + Math.atan2( y, x ) ) / ( 2 * Math.PI );
+		out[ 1 ] = z;
+
+	}
+
+	return out;
+
+}
+
+/**
+ * pbrt's (s, t) at each vertex as a uv set, `toTexture` (column-major) taking `positions` to texture space. A triangle
+ * across the seam gets copies of its vertices a turn on (`extra` names their sources, `index` the rewritten triangles,
+ * null when none); a vertex on the axis takes its triangle's mean angle.
+ * @param {Float32Array} positions
+ * @param {ArrayLike<number>|null} index
+ * @param {number[]} toTexture
+ * @param {{ type: string }} mapping
+ * @returns {{ uv: Float32Array, index: Uint32Array|null, extra: Uint32Array }}
+ */
+export function generateUV( positions, index, toTexture, mapping ) {
+
+	const count = positions.length / 3;
+	const m = toTexture;
+	const k = WRAPPED[ mapping.type ];
+	const st = new Float64Array( count * 2 );
+	const radius = k === undefined ? null : new Float64Array( count );
+	const out = [ 0, 0 ];
+	let maxRadius = 0;
+
+	for ( let i = 0; i < count; i ++ ) {
+
+		const px = positions[ i * 3 ], py = positions[ i * 3 + 1 ], pz = positions[ i * 3 + 2 ];
+		const x = m[ 0 ] * px + m[ 4 ] * py + m[ 8 ] * pz + m[ 12 ];
+		const y = m[ 1 ] * px + m[ 5 ] * py + m[ 9 ] * pz + m[ 13 ];
+		const z = m[ 2 ] * px + m[ 6 ] * py + m[ 10 ] * pz + m[ 14 ];
+		mapPoint( mapping, x, y, z, out );
+		st[ i * 2 ] = out[ 0 ];
+		st[ i * 2 + 1 ] = out[ 1 ];
+		if ( ! radius ) continue;
+		radius[ i ] = Math.hypot( x, y );
+		if ( radius[ i ] > maxRadius ) maxRadius = radius[ i ];
+
+	}
+
+	const extra = [];
+	let triangles = index;
+
+	if ( radius ) {
+
+		const onAxis = maxRadius * 1e-6;
+		const copies = new Map();
+		const corner = [ 0, 0, 0 ], value = [ 0, 0, 0 ];
+		const triangleCount = ( index ? index.length : count ) / 3;
+
+		for ( let t = 0; t < triangleCount; t ++ ) {
+
+			let lo = Infinity, hi = - Infinity, sum = 0, around = 0;
+			for ( let c = 0; c < 3; c ++ ) {
+
+				const v = corner[ c ] = index ? index[ t * 3 + c ] : t * 3 + c;
+				if ( radius[ v ] <= onAxis ) continue;
+				lo = Math.min( lo, st[ v * 2 + k ] );
+				hi = Math.max( hi, st[ v * 2 + k ] );
+
+			}
+
+			const across = hi - lo > 0.5;
+			for ( let c = 0; c < 3; c ++ ) {
+
+				const w = st[ corner[ c ] * 2 + k ];
+				if ( radius[ corner[ c ] ] <= onAxis ) value[ c ] = NaN;
+				else {
+
+					value[ c ] = across && w < 0.5 ? w + 1 : w;
+					sum += value[ c ];
+					around ++;
+
+				}
+
+			}
+
+			for ( let c = 0; c < 3; c ++ ) {
+
+				const v = corner[ c ];
+				const w = Number.isNaN( value[ c ] ) ? ( around > 0 ? sum / around : st[ v * 2 + k ] ) : value[ c ];
+				if ( w === st[ v * 2 + k ] ) continue;
+
+				if ( ! index ) {
+
+					st[ v * 2 + k ] = w;
+					continue;
+
+				}
+
+				const key = `${v}|${w}`;
+				let copy = copies.get( key );
+				if ( copy === undefined ) {
+
+					copies.set( key, copy = count + extra.length / 2 );
+					extra.push( v, w );
+
+				}
+
+				if ( triangles === index ) triangles = Uint32Array.from( index );
+				triangles[ t * 3 + c ] = copy;
+
+			}
+
+		}
+
+	}
+
+	const added = extra.length / 2;
+	const uv = new Float32Array( ( count + added ) * 2 );
+	for ( let i = 0; i < count * 2; i ++ ) uv[ i ] = st[ i ];
+	const sources = new Uint32Array( added );
+	for ( let i = 0; i < added; i ++ ) {
+
+		const v = sources[ i ] = extra[ i * 2 ];
+		uv[ ( count + i ) * 2 ] = st[ v * 2 ];
+		uv[ ( count + i ) * 2 + 1 ] = st[ v * 2 + 1 ];
+		uv[ ( count + i ) * 2 + k ] = extra[ i * 2 + 1 ];
+
+	}
+
+	return { uv, index: triangles === index ? null : triangles, extra: sources };
+
+}

package/src/Processor/PBRT/index.js

@@ -15,7 +15,7 @@
  */
 
 import { freeNow } from './buffers.js';
-import { PBRTParser } from './PBRTParser.js';
+import { PBRTParser, ParamUsage } from './PBRTParser.js';
 import { PBRTSceneBuilder } from './PBRTSceneBuilder.js';
 import { findFrameSequence, FrameSequenceMerger, motionFromShutter, SEQUENCE_FPS } from './PBRTAnimation.js';
 
@@ -380,7 +380,8 @@ export async function listEntryPathsFrom( vfs ) {
  * @param {boolean} [args.convertHandedness=true]
  * @param {boolean} [args.animation=true] - load a frame sequence (`frame25.pbrt`, `frame35.pbrt`, …)
  *   as one animated scene instead of its first frame alone. Ignored when `entryPath` names a file.
- * @returns {Promise<{group, camera, environment, animations, warnings, entryPath, frames}>}
+ * @returns {Promise<{group, camera, environment, animations, warnings, entryPath, frames, parameters}>} - `parameters`: what
+ *   ParamUsage.finish() reports, the parameters this load ignored or approximated
  */
 export async function loadPBRTScene( args ) {
 
@@ -401,6 +402,7 @@ export async function loadPBRTScene( args ) {
 	}
 
 	const entryPath = requested || candidates[ 0 ];
+	const usage = new ParamUsage();
 
 	// Parse (with Include resolution). Bytes go straight to the lexer — a scene file can
 	// be larger than the longest string JavaScript will build.
@@ -415,7 +417,8 @@ export async function loadPBRTScene( args ) {
 			// scene file at once — the difference between 5.7 GB resident and a few MB.
 			releaseInclude: ( include, currentDir, bytes ) => vfs.releasePath( include, currentDir, bytes ),
 			maxPlacements: args.maxPlacements,
-			instanceIncludes: args.instanceIncludes
+			instanceIncludes: args.instanceIncludes,
+			usage
 		} );
 
 		const ir = await parser.parse( bytes, path.includes( '/' ) ? path.slice( 0, path.lastIndexOf( '/' ) ) : '' );
@@ -490,6 +493,7 @@ export async function loadPBRTScene( args ) {
 		curveSteps: args.curveSteps,
 		curveSides: args.curveSides,
 		curveTolerance: args.curveTolerance,
+		usage,
 		resolvePLY: async ( filename ) => {
 
 			const rec = vfs.findRecord( filename );
@@ -515,9 +519,20 @@ export async function loadPBRTScene( args ) {
 	} );
 
 	const buildStart = performance.now();
-	const result = await builder.build( ir );
+	let result, parameters;
+	try {
+
+		result = await builder.build( ir );
+
+	} finally {
+
+		parameters = usage.finish();
+
+	}
+
 	return {
 		...result,
+		parameters,
 		entryPath: sequence ? sequence[ 0 ].path : entryPath,
 		frames: sequence ? sequence.map( f => f.path ) : null,
 		candidates,

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

@@ -63,6 +63,14 @@ const GEOMETRY_QUEUE_BYTES = 256 * 1024 * 1024;
 
 const log = createLogger( 'scene' );
 
+// The per-type texture lists an extraction hands over (GeometryExtractor.getExtractedData).
+const TEXTURE_LISTS = Object.freeze( [
+	'maps', 'normalMaps', 'bumpMaps', 'roughnessMaps', 'metalnessMaps', 'emissiveMaps', 'displacementMaps',
+	'anisotropyMaps', 'transmissionMaps', 'clearcoatMaps', 'clearcoatRoughnessMaps', 'sheenColorMaps',
+	'sheenRoughnessMaps', 'iridescenceMaps', 'iridescenceThicknessMaps', 'specularIntensityMaps', 'specularColorMaps',
+	'diffuseTransmissionMaps', 'diffuseTransmissionColorMaps',
+] );
+
 // A BLAS's nodes: one array, or a split mesh's parts in order — never one array that large.
 const nodeParts = nodes => ( Array.isArray( nodes ) ? nodes : [ nodes ] );
 const nodeBytes = nodes => nodeParts( nodes ).reduce( ( sum, part ) => sum + part.byteLength, 0 );
@@ -913,25 +921,7 @@ export class SceneProcessor {
 		this.materialTriangleCounts = extractedData.materialTriangleCounts; // Per-material tri count for sort-bin remap
 		this.meshes = extractedData.meshes;
 		this.meshTriangleRanges = extractedData.meshTriangleRanges; // Per-mesh { start, count } for TLAS/BLAS
-		this.maps = extractedData.maps;
-		this.normalMaps = extractedData.normalMaps;
-		this.bumpMaps = extractedData.bumpMaps;
-		this.roughnessMaps = extractedData.roughnessMaps;
-		this.metalnessMaps = extractedData.metalnessMaps;
-		this.emissiveMaps = extractedData.emissiveMaps;
-		this.displacementMaps = extractedData.displacementMaps;
-		this.anisotropyMaps = extractedData.anisotropyMaps;
-		this.transmissionMaps = extractedData.transmissionMaps;
-		this.clearcoatMaps = extractedData.clearcoatMaps;
-		this.clearcoatRoughnessMaps = extractedData.clearcoatRoughnessMaps;
-		this.sheenColorMaps = extractedData.sheenColorMaps;
-		this.sheenRoughnessMaps = extractedData.sheenRoughnessMaps;
-		this.iridescenceMaps = extractedData.iridescenceMaps;
-		this.iridescenceThicknessMaps = extractedData.iridescenceThicknessMaps;
-		this.specularIntensityMaps = extractedData.specularIntensityMaps;
-		this.specularColorMaps = extractedData.specularColorMaps;
-		this.diffuseTransmissionMaps = extractedData.diffuseTransmissionMaps ?? [];
-		this.diffuseTransmissionColorMaps = extractedData.diffuseTransmissionColorMaps ?? [];
+		this._adoptTextureLists( extractedData );
 		this.directionalLights = extractedData.directionalLights;
 		this.cameras = extractedData.cameras;
 
@@ -2453,13 +2443,7 @@ export class SceneProcessor {
 			// Update material arrays (but keep existing triangle data)
 			this.materials = extractedData.materials;
 			this.meshes = extractedData.meshes; // Update mesh data
-			this.maps = extractedData.maps;
-			this.normalMaps = extractedData.normalMaps;
-			this.bumpMaps = extractedData.bumpMaps;
-			this.roughnessMaps = extractedData.roughnessMaps;
-			this.metalnessMaps = extractedData.metalnessMaps;
-			this.emissiveMaps = extractedData.emissiveMaps;
-			this.displacementMaps = extractedData.displacementMaps;
+			this._adoptTextureLists( extractedData );
 
 			// Bucket textures, remap material indices, regenerate raw material data, and
 			// build the consolidated bucket arrays — same path as the initial build.
@@ -2487,6 +2471,13 @@ export class SceneProcessor {
 
 	}
 
+	/** @private The extraction's material indices point into these lists, so every one is taken from it. */
+	_adoptTextureLists( extractedData ) {
+
+		for ( const name of TEXTURE_LISTS ) this[ name ] = extractedData[ name ] ?? [];
+
+	}
+
 	/**
      * Dispose only material-related textures
      * @private
@@ -2726,6 +2717,7 @@ export class SceneProcessor {
 		const FPT = TRIANGLE_DATA_LAYOUT.FLOATS_PER_TRIANGLE;
 		const triRanges = [];
 		const blasRanges = [];
+		const refit = [];
 		let owners = 0;
 		for ( let i = 0; i < table.count; i ++ ) {
 
@@ -2736,6 +2728,7 @@ export class SceneProcessor {
 			if ( ! p ) continue;
 			this._updateMeshTrianglePositions( i, p );
 			blasRanges.push( table.blasOffsetOf( i ), table.blasNodeCountOf( i ) );
+			refit.push( i );
 
 			// Smooth normals overwrite the face normals just computed, so they follow per mesh.
 			if ( normalsFor ) {
@@ -2764,6 +2757,12 @@ export class SceneProcessor {
 				const msg = e.data;
 				if ( msg.type === 'refitComplete' ) {
 
+					// Later moves and main-thread refits box placements by these.
+					for ( const i of refit ) table.recomputeAABB( i, this.bvh, this.triangles );
+					table.computeGroupAABBs();
+					// The worker boxes a group copy by its shown members only.
+					const leaves = this._hiddenGroupLeaves();
+					if ( leaves.length ) this._refitTLAS( leaves );
 					resolve( { refitTimeMs: msg.refitTimeMs, triRanges, bvhRanges } );
 
 				} else if ( msg.type === 'error' ) {
@@ -2979,6 +2978,22 @@ export class SceneProcessor {
 
 	}
 
+	/** The TLAS leaves of every copy of a group with a hidden member. @private */
+	_hiddenGroupLeaves() {
+
+		const table = this.instanceTable;
+		const leaves = [];
+		for ( const g of table.groups ) {
+
+			if ( g.members.every( ( _, j ) => table.visible[ g.starts[ j ] ] ) ) continue;
+			for ( let c = 0; c < g.count; c ++ ) leaves.push( table.leafOfPlacement( g.starts[ 0 ] + c ) );
+
+		}
+
+		return leaves;
+
+	}
+
 	/**
 	 * A grouped mesh's parts are traced as one object, so a part moved alone takes its siblings with it: each sibling
 	 * is given the first moved member's world transform, and all of them are moved.
@@ -4276,6 +4291,7 @@ export class SceneProcessor {
 				// scene's 4), producing a tree of a different size that the swap below rejects —
 				// so every rebuild was thrown away.
 				maxLeafSize: this.bvhBuilder.maxLeafSize,
+				foldLeaves: this._foldLeaves === true,
 				numBins: this.bvhBuilder.numBins,
 				maxBins: this.bvhBuilder.maxBins,
 				minBins: this.bvhBuilder.minBins,

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