rayzee 9.2.0 → 9.2.1

package/package.json

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

package/src/PathTracerApp.js

@@ -32,6 +32,7 @@ import { nameFromUrl } from './Storage/DownloadCache.js';
 import { fileIdentity, identityKey } from './Storage/identity.js';
 import { SETTING_SOURCE } from './RenderSettings.js';
 import { toneMapToRGBA8 } from './Processor/ToneMapCPU.js';
+import { PackedToneMapper } from './Processor/ToneMapGPU.js';
 import { ColorManagement, setActiveColorManagement } from './Color/ColorManagement.js';
 import { getViewTransform } from './Color/ViewTransforms.js';
 import { AssetLoader } from './Processor/AssetLoader.js';
@@ -786,6 +787,8 @@ export class PathTracerApp extends EventDispatcher {
 		this.color = null;
 		this._textureReadback?.dispose();
 		this._textureReadback = null;
+		this._readbackToneMapper?.dispose();
+		this._readbackToneMapper = null;
 
 		this.interactionManager?.deselect?.();
 		this.transformManager?.detach?.();
@@ -3016,6 +3019,24 @@ export class PathTracerApp extends EventDispatcher {
 		// The pool over-allocates to the reserve, so the texture is larger than the frame.
 		const { width, height } = stage;
 
+		if ( colorSpace === 'srgb' ) {
+
+			const shown = source === 'display' ? this._displaySource( target ) : null;
+			const tone = {
+				exposure: this.renderer.toneMappingExposure,
+				toneMapping: this.renderer.toneMapping,
+				saturation: this.settings.get( 'saturation' ) ?? 1,
+				preserveAlpha,
+			};
+
+			const data = await this._toneMapOnGPU( shown?.texture ?? null, target, width, height, tone )
+				?? toneMapToRGBA8( shown
+					? await this._readTexture( shown.texture, width, height )
+					: await this.renderer.readRenderTargetPixelsAsync( target, 0, 0, width, height, 0 ), tone );
+			return { data, width, height, colorSpace, source: shown?.source ?? 'accumulation' };
+
+		}
+
 		const { data: linear, source: read } = source === 'display'
 			? await this._readDisplaySource( target, width, height )
 			: { data: await this.renderer.readRenderTargetPixelsAsync( target, 0, 0, width, height, 0 ), source: 'accumulation' };
@@ -3031,25 +3052,42 @@ export class PathTracerApp extends EventDispatcher {
 		// A named space is a delivery buffer, not a picture: scene-referred float in whatever the
 		// config calls that space. Saving an EXR for a compositor and grading through an sRGB view
 		// on screen are different questions, and this is the one that answers the first.
-		if ( named ) {
+		const { rgba, colorSpace: got } = this.color.exportPixels( linear, colorSpace );
+		return { data: rgba, width, height, colorSpace: got, source: read };
 
-			const { rgba, colorSpace: got } = this.color.exportPixels( linear, colorSpace );
-			return { data: rgba, width, height, colorSpace: got, source: read };
+	}
 
-		}
+	/**
+	 * Display bytes tone-mapped on the card, or null to do it on the CPU. On the CPU it took 1.4 s at
+	 * 4096×2160 on an M-series Mac and 10 s on a cloud L4's host; the GPU pass matches it within one
+	 * level (`tests/gpu/toneMapParity.test.js`).
+	 */
+	async _toneMapOnGPU( shown, accumulation, width, height, tone ) {
 
-		return {
-			data: toneMapToRGBA8( linear, {
-				exposure: this.renderer.toneMappingExposure,
-				toneMapping: this.renderer.toneMapping,
-				saturation: this.settings.get( 'saturation' ) ?? 1,
-				preserveAlpha,
-			} ),
-			width,
-			height,
-			colorSpace,
-			source: read,
-		};
+		const backend = this.renderer?.backend;
+		if ( ! backend?.device ) return null;
+
+		try {
+
+			const texture = shown ? this._readbackPass().draw( shown, width, height ).texture : accumulation.textures[ 0 ];
+			const gpuTexture = backend.get( texture ).texture;
+			if ( ! gpuTexture ) return null;
+
+			this._readbackToneMapper ??= new PackedToneMapper( backend.device, 'rayzee:readback-tonemap', { input: 'texture' } );
+			this._readbackToneMapper.ensureSize( width, height );
+			return await this._readbackToneMapper.toRGBA8( gpuTexture, tone );
+
+		} catch ( error ) {
+
+			log.warn( `renderToBuffer: tone mapping on the GPU failed, doing it on the CPU: ${error?.message ?? error}` );
+			return null;
+
+		} finally {
+
+			this._readbackToneMapper?.release();
+			if ( shown ) this._textureReadback?.release();
+
+		}
 
 	}
 
@@ -3655,32 +3693,56 @@ export class PathTracerApp extends EventDispatcher {
 	}
 
 	/**
-	 * What the Compositor is drawing from, as linear float. Falls back to the accumulation when no
-	 * denoiser has published anything, which is also what the viewport shows then.
+	 * What a `'display'` read shows: the texture a denoiser published, or null for the raw
+	 * accumulation — recorded as a fallback when a denoiser is in use.
 	 * @private
 	 */
-	async _readDisplaySource( accumulation, width, height ) {
+	_displaySource( accumulation ) {
 
 		const context = this.pipeline?.context;
 		const found = context && this.stages.compositor?.resolveLightSource( context );
-		if ( ! found || found.key === 'pathtracer:color' || found.texture === accumulation.texture ) {
+		if ( found && found.key !== 'pathtracer:color' && found.texture !== accumulation.texture ) {
 
-			if ( this._denoiserInUse() ) {
+			return { texture: found.texture, source: found.key.split( ':' )[ 0 ] };
 
-				this._issues.record(
-					ISSUE_CODES.OUTPUT_SOURCE_FALLBACK,
-					'renderToBuffer: \'display\' was asked for, but no denoiser has published a picture — returned the raw accumulation',
-					{ requested: 'display', read: 'accumulation' }
-				);
+		}
 
-			}
+		if ( this._denoiserInUse() ) {
 
-			return { data: await this.renderer.readRenderTargetPixelsAsync( accumulation, 0, 0, width, height, 0 ), source: 'accumulation' };
+			this._issues.record(
+				ISSUE_CODES.OUTPUT_SOURCE_FALLBACK,
+				'renderToBuffer: \'display\' was asked for, but no denoiser has published a picture — returned the raw accumulation',
+				{ requested: 'display', read: 'accumulation' }
+			);
 
 		}
 
-		this._textureReadback ??= new TextureReadback( this.renderer );
-		return { data: await this._textureReadback.read( found.texture, width, height ), source: found.key.split( ':' )[ 0 ] };
+		return null;
+
+	}
+
+	/**
+	 * What the Compositor is drawing from, as linear float. Falls back to the accumulation when no
+	 * denoiser has published anything, which is also what the viewport shows then.
+	 * @private
+	 */
+	async _readDisplaySource( accumulation, width, height ) {
+
+		const shown = this._displaySource( accumulation );
+		if ( ! shown ) return { data: await this.renderer.readRenderTargetPixelsAsync( accumulation, 0, 0, width, height, 0 ), source: 'accumulation' };
+		return { data: await this._readTexture( shown.texture, width, height ), source: shown.source };
+
+	}
+
+	_readbackPass() {
+
+		return ( this._textureReadback ??= new TextureReadback( this.renderer ) );
+
+	}
+
+	_readTexture( texture, width, height ) {
+
+		return this._readbackPass().read( texture, width, height );
 
 	}
 

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/Storage/DownloadCache.js

@@ -191,15 +191,37 @@ export class DownloadCache {
 		if ( this._revalidating.has( key ) ) return;
 		this._revalidating.add( key );
 
+		let changed = false;
+
 		try {
 
-			const head = await fetch( url, { ...fetchOptions, method: 'HEAD' } );
-			if ( ! head.ok ) return;
+			// One byte, not HEAD: a CORS rule that allows GET — the engine's own asset host — refuses
+			// HEAD, and a single-range Range header needs no preflight.
+			const headers = new Headers( fetchOptions?.headers );
+			headers.set( 'Range', 'bytes=0-0' );
+			const probe = await fetch( url, { ...fetchOptions, headers } );
+			probe.body?.cancel().catch( () => {} );
+
+			if ( probe.ok ) {
+
+				const lastModified = header( probe, 'last-modified' );
+				// A 206 carries the size in Content-Range, unreadable cross-origin unless exposed; a server
+				// that ignores Range answers 200 with the whole length.
+				const length = probe.status === 206
+					? Number( header( probe, 'content-range' )?.match( /\/(\d+)$/ )?.[ 1 ] ) || null
+					: Number( header( probe, 'content-length' ) ) || null;
+				changed = !! ( ( lastModified && extra.lastModified && lastModified !== extra.lastModified )
+					|| ( length && extra.contentLength && length !== extra.contentLength ) );
 
-			const lastModified = header( head, 'last-modified' );
-			const length = Number( header( head, 'content-length' ) ) || null;
-			const changed = ( lastModified && extra.lastModified && lastModified !== extra.lastModified )
-				|| ( length && extra.contentLength && length !== extra.contentLength );
+			}
+
+		} catch {
+
+			// Offline, or the server refuses the probe: keep serving the stored copy.
+
+		}
+
+		try {
 
 			if ( changed ) {
 
@@ -208,13 +230,14 @@ export class DownloadCache {
 
 			} else {
 
+				// Stamped when the check failed too, or a refusing server is asked again on every load.
 				await this._area.patchMeta( key, { extra: { ...extra, checkedAt: Date.now() } } );
 
 			}
 
 		} catch {
 
-			// Offline, or the server refuses HEAD: keep serving the stored copy.
+			// The stored copy stays.
 
 		} finally {