rayzee 9.1.2 → 9.2.1

package/src/Processor/TextureCreator.js

@@ -2,13 +2,37 @@ import { DataArrayTexture, RGBAFormat, LinearFilter, UnsignedByteType, SRGBColor
 import { alignBucketWidth, TEXTURE_CONSTANTS, MEMORY_CONSTANTS, MATERIAL_DATA_LAYOUT, BVH_LEAF_MARKERS, assertBVHIndexFits, bvhIndexView } from '../EngineDefaults.js';
 import { packMaterial } from './MaterialPacking.js';
 import TexturesWorker from './Workers/TexturesWorker.js?worker&inline';
-import { ISSUE_CODES } from '../EngineIssues.js';
+import PackWorker from './Workers/PackWorker.js?worker&inline';
+import { resampleRGBA8 } from './ResampleRGBA8.js';
+import { ISSUE_CODES, EngineIssueError } from '../EngineIssues.js';
 import { linearToSRGB } from './ToneMapCPU.js';
 import { getActiveColorManagement } from '../Color/ColorManagement.js';
 import { createLogger } from '../utils/Logger.js';
+import { createWorker, hardwareThreads, hasWorkers } from '../Platform.js';
 
 const log = createLogger( 'textures' );
 
+// Below this a pack is cheaper than starting a worker for it.
+const WORKER_PACK_BYTES = 8 * 2 ** 20;
+
+// Buckets pack concurrently; this keeps their workers within the cores, beside the BVH pool's.
+const packSlots = { busy: 0, waiting: [] };
+
+async function acquirePackSlot() {
+
+	if ( packSlots.busy < Math.max( 1, hardwareThreads() - 1 ) ) packSlots.busy ++;
+	else await new Promise( ( resolve ) => packSlots.waiting.push( resolve ) );
+
+	return () => {
+
+		const next = packSlots.waiting.shift();
+		if ( next ) next();
+		else packSlots.busy --;
+
+	};
+
+}
+
 // A bucket array carries ONE colorSpace and the shader reads each slot from a fixed pool, so a
 // texture disagreeing with its pool cannot be re-routed — its pixels are re-encoded instead.
 const TRANSFER_LUT = { toSRGB: null, toLinear: null };
@@ -529,6 +553,7 @@ export class TextureCreator {
 	/** A failed map array leaves those surfaces untextured — complete-looking and wrong. @private */
 	_reportTextureFailure( map, error ) {
 
+		if ( error instanceof EngineIssueError ) throw error;
 		this._issues?.record(
 			ISSUE_CODES.TEXTURE_BUILD_FAILED,
 			`${map} texture array failed to build — those surfaces render untextured`,
@@ -537,6 +562,17 @@ export class TextureCreator {
 
 	}
 
+	// Layers are addressed by position, so a texture that cannot be read keeps its slot.
+	_reportTextureLayer( layer, cause ) {
+
+		this._issues?.record(
+			ISSUE_CODES.TEXTURE_BUILD_FAILED,
+			`texture ${layer} could not be read — its surfaces show a white placeholder`,
+			{ layer, cause: String( cause?.message ?? cause ) }
+		);
+
+	}
+
 	_clampTextureSize( size ) {
 
 		const n = Math.floor( Number( size ) || TEXTURE_CONSTANTS.DEFAULT_MAX_TEXTURE_SIZE );
@@ -562,7 +598,7 @@ export class TextureCreator {
 			offscreenCanvas: typeof OffscreenCanvas !== 'undefined',
 			imageBitmap: typeof createImageBitmap !== 'undefined',
 			workers: typeof Worker !== 'undefined',
-			hardwareConcurrency: navigator.hardwareConcurrency || 4
+			hardwareConcurrency: hardwareThreads()
 		};
 
 	}
@@ -775,6 +811,16 @@ export class TextureCreator {
 		const cached = this.textureCache.get( cacheKey );
 		if ( cached ) return cached;
 
+		if ( typeof createImageBitmap === 'undefined' ) {
+
+			const packed = await this.processOnCPU( textures );
+			const reencoded = this._harmonizeTransfer( packed, textures, srgbPool );
+			this._applyColorManagement( packed, textures, srgbPool, reencoded );
+			this.textureCache.set( cacheKey, packed );
+			return packed;
+
+		}
+
 		// Normalize non-drawable images (KTX2 CompressedTexture RGBA, DataTexture)
 		const { normalized, bitmapsToClose } = await this._normalizeTexturesForProcessing( textures );
 
@@ -813,6 +859,7 @@ export class TextureCreator {
 
 		} catch ( error ) {
 
+			if ( error instanceof EngineIssueError ) throw error;
 			this._issues?.warn(
 				ISSUE_CODES.TEXTURE_PROCESSING_FALLBACK,
 				'worker texture processing failed — retrying on the main thread',
@@ -885,9 +932,9 @@ export class TextureCreator {
 
 		this.activeWorkers ++;
 
-		try {
+		const worker = new TexturesWorker();
 
-			const worker = new TexturesWorker();
+		try {
 
 			// Prepare textures for worker with direct transfer
 			const texturesData = await this.prepareTexturesForWorkerDirect( textures );
@@ -934,11 +981,11 @@ export class TextureCreator {
 
 			} );
 
-			worker.terminate();
 			return this.createDataArrayTextureFromResult( result );
 
 		} finally {
 
+			worker.terminate();
 			this.activeWorkers --;
 
 		}
@@ -949,10 +996,18 @@ export class TextureCreator {
 	async prepareTexturesForWorkerDirect( textures ) {
 
 		const texturesData = [];
+		const placeholder = () => ( { data: new Uint8ClampedArray( [ 255, 255, 255, 255 ] ).buffer, width: 1, height: 1, isImageData: true } );
 
-		for ( const texture of textures ) {
+		for ( let layer = 0; layer < textures.length; layer ++ ) {
 
-			if ( ! texture?.image ) continue;
+			const texture = textures[ layer ];
+			if ( ! texture?.image ) {
+
+				this._reportTextureLayer( layer, 'no image' );
+				texturesData.push( placeholder() );
+				continue;
+
+			}
 
 			const flipY = texture.flipY !== false;
 
@@ -964,7 +1019,7 @@ export class TextureCreator {
 				// getImageData off the main thread (Option 2 blocks it per texture).
 				const img = texture.image;
 				const canDirect = typeof createImageBitmap !== 'undefined' && (
-					img instanceof HTMLImageElement
+					( typeof HTMLImageElement !== 'undefined' && img instanceof HTMLImageElement )
 					|| ( typeof ImageBitmap !== 'undefined' && img instanceof ImageBitmap )
 					|| ( typeof HTMLCanvasElement !== 'undefined' && img instanceof HTMLCanvasElement )
 					|| ( typeof OffscreenCanvas !== 'undefined' && img instanceof OffscreenCanvas )
@@ -1008,7 +1063,8 @@ export class TextureCreator {
 
 			} catch ( error ) {
 
-				console.warn( 'Failed to prepare texture for worker:', error );
+				this._reportTextureLayer( layer, error );
+				texturesData.push( placeholder() );
 
 			}
 
@@ -1018,6 +1074,93 @@ export class TextureCreator {
 
 	}
 
+	/**
+	 * Packing without a browser (no createImageBitmap, no 2D canvas): each layer must already be
+	 * pixels — a DataTexture, or an image the platform's decodeImage decoded. A layer that matches its
+	 * bucket is copied exactly; one that does not is resampled bilinearly, where a browser's canvas
+	 * would use its own filter, so those texels can differ slightly from a browser render. A large
+	 * bucket packs in a worker: on the main thread it starved the BVH workers of their next task.
+	 */
+	async processOnCPU( textures ) {
+
+		const layers = textures.map( ( texture, layer ) => {
+
+			const image = texture?.image;
+			const pixels = texture?.isCompressedTexture ? texture.mipmaps?.[ 0 ] : image;
+			const data = pixels?.data;
+			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 };
+
+			}
+
+			this._reportTextureLayer( layer, image ? 'not decoded to pixels, and there is no browser to decode it' : 'no image' );
+			return { data: new Uint8Array( [ 255, 255, 255, 255 ] ), width: 1, height: 1, flipY: false };
+
+		} );
+
+		const { maxWidth, maxHeight } = this.calculateOptimalDimensions( layers.map( ( image ) => ( { image } ) ) );
+		const layerBytes = maxWidth * maxHeight * 4;
+
+		const packed = hasWorkers() && layerBytes * layers.length >= WORKER_PACK_BYTES
+			? await this._packInWorker( layers, maxWidth, maxHeight )
+			: null;
+		if ( packed ) return this.createDataArrayTextureFromBuffer( packed, maxWidth, maxHeight, layers.length );
+
+		const data = this.bufferPool.getBuffer( layerBytes * layers.length, Uint8Array );
+		layers.forEach( ( layer, i ) => resampleRGBA8( layer, data, i * layerBytes, maxWidth, maxHeight ) );
+
+		return this.createDataArrayTextureFromBuffer( data, maxWidth, maxHeight, layers.length );
+
+	}
+
+	/** The packed pixels, or null to pack on the main thread instead. */
+	async _packInWorker( layers, width, height ) {
+
+		const release = await acquirePackSlot();
+		let worker = null;
+
+		try {
+
+			// A SharedArrayBuffer view crosses as itself; anything else as a copy of just its bytes,
+			// made only once this bucket has its slot so waiting buckets hold no copies.
+			const transfer = [];
+			const sent = layers.map( ( layer ) => {
+
+				if ( typeof SharedArrayBuffer !== 'undefined' && layer.data.buffer instanceof SharedArrayBuffer ) return layer;
+				const data = layer.data.slice();
+				transfer.push( data.buffer );
+				return { ...layer, data };
+
+			} );
+
+			worker = createWorker( PackWorker );
+			return await new Promise( ( resolve, reject ) => {
+
+				worker.onmessage = ( e ) => ( e.data.error ? reject( new Error( e.data.error ) ) : resolve( e.data.data ) );
+				worker.onerror = ( e ) => reject( e.error ?? new Error( e.message ?? 'texture pack worker failed' ) );
+				worker.postMessage( { layers: sent, width, height }, transfer );
+
+			} );
+
+		} catch ( error ) {
+
+			this._issues?.warn(
+				ISSUE_CODES.TEXTURE_PROCESSING_FALLBACK,
+				'worker texture packing failed — packing on the main thread',
+				{ cause: String( error?.message ?? error ) }
+			);
+			return null;
+
+		} finally {
+
+			worker?.terminate();
+			release();
+
+		}
+
+	}
+
 	async processOnMainThreadBatch( textures, batchSize ) {
 
 		const validTextures = textures.filter( tex => tex?.image );
@@ -1465,7 +1608,13 @@ export class TextureCreator {
 
 		for ( const tex of textures ) {
 
-			if ( ! tex?.image ) continue;
+			if ( ! tex?.image ) {
+
+				this._reportTextureLayer( normalized.length, 'no image' );
+				normalized.push( null );
+				continue;
+
+			}
 
 			// RGBA CompressedTexture (KTX2 Basis transcode wraps output as CompressedTexture)
 			if ( tex.isCompressedTexture && tex.format === RGBAFormat && tex.mipmaps?.[ 0 ]?.data ) {
@@ -1489,8 +1638,8 @@ export class TextureCreator {
 			}
 
 			// DataTexture with raw pixel array
-			if ( tex.image.data && ! ( tex.image instanceof HTMLImageElement ) &&
-				! ( tex.image instanceof HTMLCanvasElement ) &&
+			if ( tex.image.data && ! ( typeof HTMLImageElement !== 'undefined' && tex.image instanceof HTMLImageElement ) &&
+				! ( typeof HTMLCanvasElement !== 'undefined' && tex.image instanceof HTMLCanvasElement ) &&
 				! ( typeof ImageBitmap !== 'undefined' && tex.image instanceof ImageBitmap ) ) {
 
 				const idx = normalized.length;
@@ -1522,7 +1671,7 @@ export class TextureCreator {
 
 				} else {
 
-					console.warn( '[TextureCreator] Failed to create ImageBitmap:', result.reason );
+					this._reportTextureLayer( index, result.reason );
 
 				}
 

package/src/Processor/TextureReadback.js

@@ -46,6 +46,25 @@ export class TextureReadback {
 	 */
 	async read( source, width, height ) {
 
+		try {
+
+			return await this.renderer.readRenderTargetPixelsAsync( this.draw( source, width, height ), 0, 0, width, height );
+
+		} finally {
+
+			this.release();
+
+		}
+
+	}
+
+	/**
+	 * Draws `source` into this pass's float target, for a caller that reads it on the GPU. Pair with
+	 * `release()`.
+	 * @returns {import('three').RenderTarget}
+	 */
+	draw( source, width, height ) {
+
 		this._ensureTarget( width, height );
 
 		if ( this._source !== source ) {
@@ -63,19 +82,16 @@ export class TextureReadback {
 		this.renderer.setRenderTarget( this.target );
 		this.quad.render( this.renderer );
 		this.renderer.setRenderTarget( previous );
+		return this.target;
 
-		try {
-
-			return await this.renderer.readRenderTargetPixelsAsync( this.target, 0, 0, width, height );
-
-		} finally {
+	}
 
-			// A float target the size of the frame — 132 MB at 4K — for something done once per
-			// saved file. Not worth keeping between saves.
-			this.target.dispose();
-			this.target = null;
+	// A float target the size of the frame — 132 MB at 4K — for something done once per saved file.
+	// Not worth keeping between saves.
+	release() {
 
-		}
+		this.target?.dispose();
+		this.target = null;
 
 	}
 

package/src/Processor/ToneMapGPU.js

@@ -39,7 +39,24 @@ function currentShader() {
  */
 export const TONE_MAP_WGSL = currentShader().wgsl;
 
-const packedWGSL = transformWGSL => /* wgsl */ `
+// Where the linear colour comes from: a packed rgba16float buffer, or a float texture read by pixel.
+const SOURCES = {
+	packed: /* wgsl */ `
+@group(0) @binding(0) var<storage, read> src: array<u32>;
+
+fn rayzee_source( x: u32, y: u32 ) -> vec4<f32> {
+	let a = ( y * params.width + x ) * 2u;
+	return vec4<f32>( unpack2x16float( src[ a ] ), unpack2x16float( src[ a + 1u ] ) );
+}`,
+	texture: /* wgsl */ `
+@group(0) @binding(0) var src: texture_2d<f32>;
+
+fn rayzee_source( x: u32, y: u32 ) -> vec4<f32> {
+	return textureLoad( src, vec2<u32>( x, y ), 0 );
+}`,
+};
+
+const toneMapPassWGSL = ( transformWGSL, input ) => /* wgsl */ `
 struct Params {
 	width: u32,
 	height: u32,
@@ -47,11 +64,12 @@ struct Params {
 	flipY: u32,
 	exposure: f32,
 	saturation: f32,
+	alpha: u32,
 };
 
-@group(0) @binding(0) var<storage, read> src: array<u32>;
 @group(0) @binding(1) var<storage, read_write> dst: array<u32>;
 @group(0) @binding(2) var<uniform> params: Params;
+${SOURCES[ input ]}
 
 ${transformWGSL}
 
@@ -62,30 +80,31 @@ fn main( @builtin(global_invocation_id) gid: vec3<u32> ) {
 	var srcY = gid.y;
 	if ( params.flipY == 1u ) { srcY = params.height - 1u - gid.y; }
 
-	let a = ( srcY * params.width + gid.x ) * 2u;
-	let rg = unpack2x16float( src[ a ] );
-	let ba = unpack2x16float( src[ a + 1u ] );
-
-	let mapped = rayzee_tone_map( vec3<f32>( rg.x, rg.y, ba.x ), params.mode, params.exposure, params.saturation );
+	let linear = rayzee_source( gid.x, srcY );
+	let mapped = rayzee_tone_map( linear.rgb, params.mode, params.exposure, params.saturation );
 	let b8 = rayzee_to_u8( rayzee_encode( mapped, params.mode ) );
-	dst[ gid.y * params.width + gid.x ] = b8.x | ( b8.y << 8u ) | ( b8.z << 16u ) | ( 255u << 24u );
+	var a8 = 255u;
+	if ( params.alpha == 1u ) { a8 = rayzee_to_u8( vec3<f32>( linear.a ) ).x; }
+	dst[ gid.y * params.width + gid.x ] = b8.x | ( b8.y << 8u ) | ( b8.z << 16u ) | ( a8 << 24u );
 }
 `;
 
-/** Uniform blocks round up to 16 bytes; the struct above is 24. */
+/** Uniform blocks round up to 16 bytes; the struct above is 28. */
 const PARAMS_BYTES = 32;
 
 /**
- * Tone-maps a tightly packed rgba16float buffer (two `u32` per pixel) into RGBA bytes.
+ * Tone-maps a tightly packed rgba16float buffer (two `u32` per pixel), or with `input: 'texture'` a
+ * float texture read by pixel, into RGBA bytes.
  *
  * Bound to one device and one image size; `ensureSize()` reallocates when the size changes.
  */
 export class PackedToneMapper {
 
-	constructor( device, label = 'rayzee:tonemap' ) {
+	constructor( device, label = 'rayzee:tonemap', { input = 'packed' } = {} ) {
 
 		this.device = device;
 		this.label = label;
+		this.input = input;
 		this.width = 0;
 		this.height = 0;
 		this._pipeline = null;
@@ -120,7 +139,7 @@ export class PackedToneMapper {
 			label: this.label,
 			layout: 'auto',
 			compute: {
-				module: this.device.createShaderModule( { label: this.label, code: packedWGSL( wgsl ) } ),
+				module: this.device.createShaderModule( { label: this.label, code: toneMapPassWGSL( wgsl, this.input ) } ),
 				entryPoint: 'main',
 			},
 		} );
@@ -206,15 +225,17 @@ export class PackedToneMapper {
 	}
 
 	/**
-	 * @param {GPUBuffer} src packed rgba16float, `width * height * 8` bytes, STORAGE-capable
+	 * @param {GPUBuffer|GPUTexture} src packed rgba16float, `width * height * 8` bytes, STORAGE-capable;
+	 *   or with `input: 'texture'` a float texture at least `width × height`
 	 * @param {object} tone
 	 * @param {number} tone.exposure raw `renderer.toneMappingExposure`
 	 * @param {number} tone.toneMapping Three.js ToneMapping constant
 	 * @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
 	 * @returns {Promise<Uint8ClampedArray>} RGBA bytes, `width * height * 4`
 	 */
-	async toRGBA8( src, { exposure = 1, toneMapping = 0, saturation = 1, flipY = false } = {} ) {
+	async toRGBA8( src, { exposure = 1, toneMapping = 0, saturation = 1, flipY = false, preserveAlpha = false } = {} ) {
 
 		if ( this.disposed ) throw new Error( 'PackedToneMapper: disposed' );
 		if ( ! this._storage ) throw new Error( 'PackedToneMapper: call ensureSize() first' );
@@ -232,6 +253,7 @@ export class PackedToneMapper {
 		this._paramU32[ 3 ] = flipY ? 1 : 0;
 		this._paramF32[ 4 ] = exposure;
 		this._paramF32[ 5 ] = saturation;
+		this._paramU32[ 6 ] = preserveAlpha ? 1 : 0;
 		this.device.queue.writeBuffer( this._params, 0, this._paramData );
 
 		const tableEntries = [ ...this._tables.entries() ]
@@ -241,7 +263,7 @@ export class PackedToneMapper {
 			layout: this._pipeline.getBindGroupLayout( 0 ),
 			entries: [
 				...tableEntries,
-				{ binding: 0, resource: { buffer: src, size: width * height * 8 } },
+				{ binding: 0, resource: this.input === 'texture' ? src.createView() : { buffer: src, size: width * height * 8 } },
 				{ binding: 1, resource: { buffer: this._storage } },
 				{ binding: 2, resource: { buffer: this._params } },
 			],
@@ -263,6 +285,14 @@ export class PackedToneMapper {
 
 	}
 
+	/** Frees the size-dependent buffers and keeps the pipeline, for a mapper used now and then. */
+	release() {
+
+		this._releaseBuffers();
+		this.width = this.height = 0;
+
+	}
+
 	_releaseBuffers() {
 
 		this._storage?.destroy();

package/src/Processor/Workers/PackWorker.js

@@ -0,0 +1,28 @@
+/**
+ * Packs RGBA8 layers into one texture array off the main thread, for hosts without a browser, where
+ * TextureCreator.processOnCPU would otherwise hold up the BVH workers it feeds.
+ *
+ * Input:  { layers: [{ data: Uint8Array (SharedArrayBuffer-backed), width, height, flipY }], width, height }
+ * Output: { data: Uint8Array } — its buffer transferred
+ */
+
+import { resampleRGBA8 } from '../ResampleRGBA8.js';
+
+self.onmessage = function ( e ) {
+
+	const { layers, width, height } = e.data;
+
+	try {
+
+		const layerBytes = width * height * 4;
+		const data = new Uint8Array( layerBytes * layers.length );
+		layers.forEach( ( layer, i ) => resampleRGBA8( layer, data, i * layerBytes, width, height ) );
+		self.postMessage( { data }, [ data.buffer ] );
+
+	} catch ( error ) {
+
+		self.postMessage( { error: error.message } );
+
+	}
+
+};

package/src/Stages/Compositor.js

@@ -4,6 +4,16 @@ import { NoBlending, NoToneMapping } from 'three';
 import { RenderStage, StageExecutionMode } from '../Pipeline/RenderStage.js';
 import { REC709_LUMINANCE_COEFFICIENTS } from '../TSL/Common.js';
 
+// In priority order: the first one published wins.
+const LIGHT_SOURCES = [
+	'oidn:output',
+	'edgeFiltering:output',
+	'bilateralFiltering:output',
+	'asvgf:output',
+	'nrd:output',
+	'pathtracer:color',
+];
+
 /**
  * Compositor — Terminal pipeline stage.
  *
@@ -76,12 +86,21 @@ export class Compositor extends RenderStage {
 	 */
 	resolveLightTexture( context ) {
 
-		return context.getTexture( 'oidn:output' )
-			|| context.getTexture( 'edgeFiltering:output' )
-			|| context.getTexture( 'bilateralFiltering:output' )
-			|| context.getTexture( 'asvgf:output' )
-			|| context.getTexture( 'nrd:output' )
-			|| context.getTexture( 'pathtracer:color' );
+		return this.resolveLightSource( context )?.texture ?? null;
+
+	}
+
+	/** {@link resolveLightTexture} plus the context key it came from. */
+	resolveLightSource( context ) {
+
+		for ( const key of LIGHT_SOURCES ) {
+
+			const texture = context.getTexture( key );
+			if ( texture ) return { key, texture };
+
+		}
+
+		return null;
 
 	}