rayzee 5.7.0 → 5.7.1

package/package.json

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

package/src/PathTracerApp.js

@@ -1,4 +1,4 @@
-import { WebGPURenderer, RectAreaLightNode } from 'three/webgpu';
+import { WebGPURenderer, RectAreaLightNode, LinearSRGBColorSpace, SRGBColorSpace } from 'three/webgpu';
 import { texture as _tslTexture, cubeTexture as _tslCubeTexture } from 'three/tsl';
 import {
 	ACESFilmicToneMapping, Scene, EventDispatcher, TimestampQuery
@@ -16,7 +16,7 @@ import { AdaptiveSampling } from './Stages/AdaptiveSampling.js';
 import { EdgeFilter } from './Stages/EdgeFilter.js';
 import { AutoExposure } from './Stages/AutoExposure.js';
 import { SSRC } from './Stages/SSRC.js';
-import { Display } from './Stages/Display.js';
+import { Compositor } from './Stages/Compositor.js';
 import { RenderPipeline } from './Pipeline/RenderPipeline.js';
 import { CompletionTracker } from './Pipeline/CompletionTracker.js';
 import { ENGINE_DEFAULTS as DEFAULT_STATE, FINAL_RENDER_CONFIG, PREVIEW_RENDER_CONFIG } from './EngineDefaults.js';
@@ -286,7 +286,7 @@ export class PathTracerApp extends EventDispatcher {
 				if ( this._needsDisplayRefresh ) {
 
 					this._needsDisplayRefresh = false;
-					this.stages.display.render( this.pipeline.context );
+					this.stages.compositor.render( this.pipeline.context );
 					this._renderHelperOverlay();
 
 				}
@@ -775,7 +775,7 @@ export class PathTracerApp extends EventDispatcher {
 		// Apply all settings to stages in one shot
 		timer.start( 'Apply settings' );
 		this.settings.applyAll();
-		this.stages.display.setTransparentBackground( this.settings.get( 'transparentBackground' ) );
+		this.stages.compositor.setTransparentBackground( this.settings.get( 'transparentBackground' ) );
 		timer.end( 'Apply settings' );
 
 		timer.print();
@@ -1006,10 +1006,10 @@ export class PathTracerApp extends EventDispatcher {
 
 		if ( usePostProcess ) return dm.denoiserCanvas;
 
-		// Re-render display stage so the WebGPU canvas has valid content
-		if ( this.stages.display && this.pipeline?.context ) {
+		// Re-render compositor stage so the WebGPU canvas has valid content
+		if ( this.stages.compositor && this.pipeline?.context ) {
 
-			this.stages.display.render( this.pipeline.context );
+			this.stages.compositor.render( this.pipeline.context );
 
 		}
 
@@ -1208,6 +1208,8 @@ export class PathTracerApp extends EventDispatcher {
 
 		RectAreaLightNode.setLTC( RectAreaLightTexturesLib.init() );
 
+		this.renderer.workingColorSpace = SRGBColorSpace;
+		this.renderer.outputColorSpace = SRGBColorSpace;
 		this.renderer.toneMapping = ACESFilmicToneMapping;
 		this.renderer.toneMappingExposure = 1.0;
 		this.renderer.setPixelRatio( 1.0 );
@@ -1261,7 +1263,7 @@ export class PathTracerApp extends EventDispatcher {
 		this.pipeline.addStage( this.stages.adaptiveSampling );
 		this.pipeline.addStage( this.stages.edgeFilter );
 		this.pipeline.addStage( this.stages.autoExposure );
-		this.pipeline.addStage( this.stages.display );
+		this.pipeline.addStage( this.stages.compositor );
 
 		const initRenderW = this.canvas.clientWidth || 1;
 		const initRenderH = this.canvas.clientHeight || 1;
@@ -1367,10 +1369,13 @@ export class PathTracerApp extends EventDispatcher {
 		// Bind settings to pipeline stages
 		this.settings.bind( {
 			stages: this.stages,
+			renderer: this.renderer,
 			resetCallback: () => this.reset(),
 			reconcileCompletion: () => this._reconcileCompletion(),
 		} );
 
+		this.renderer.toneMappingExposure = this.settings.get( 'exposure' ) ?? 1.0;
+
 		// Resize handling
 		this.onResize();
 		this.resizeHandler = () => this.onResize();
@@ -1474,8 +1479,7 @@ export class PathTracerApp extends EventDispatcher {
 		this.stages.edgeFilter = new EdgeFilter( this.renderer, { enabled: false } );
 		this.stages.autoExposure = new AutoExposure( this.renderer, { enabled: DEFAULT_STATE.autoExposure ?? false } );
 
-		this.stages.display = new Display( this.renderer, {
-			exposure: ( DEFAULT_STATE.autoExposure ) ? 1.0 : ( this.settings.get( 'exposure' ) ?? 1.0 ),
+		this.stages.compositor = new Compositor( this.renderer, {
 			saturation: this.settings.get( 'saturation' ) ?? DEFAULT_STATE.saturation,
 		} );
 
@@ -1497,7 +1501,7 @@ export class PathTracerApp extends EventDispatcher {
 				edgeFilter: this.stages.edgeFilter,
 				ssrc: this.stages.ssrc,
 				autoExposure: this.stages.autoExposure,
-				display: this.stages.display,
+				compositor: this.stages.compositor,
 			},
 			pipeline: this.pipeline,
 			getExposure: () => this.settings.get( 'exposure' ) ?? 1.0,

package/src/RenderSettings.js

@@ -104,16 +104,16 @@ export class RenderSettings extends EventDispatcher {
 	 * Wires internal references. Called by PathTracerApp after init().
 	 *
 	 * @param {Object} params
-	 * @param {Object} params.stages           - Pipeline stages { pathTracer, display, autoExposure, ... }
+	 * @param {Object} params.stages           - Pipeline stages { pathTracer, compositor, autoExposure, ... }
 	 * @param {Function} params.resetCallback   - Called to reset accumulation
 	 * @param {Function} [params.reconcileCompletion] - Called when completion limits change
 	 */
-	bind( { stages, resetCallback, reconcileCompletion } ) {
+	bind( { stages, renderer, resetCallback, reconcileCompletion } ) {
 
 		this._pathTracer = stages.pathTracer;
 		this._resetCallback = resetCallback;
 		this._delegates = {};
-		this._handlers = this._buildHandlers( stages, reconcileCompletion );
+		this._handlers = this._buildHandlers( stages, renderer, reconcileCompletion );
 
 	}
 
@@ -121,22 +121,24 @@ export class RenderSettings extends EventDispatcher {
 	 * Builds handler functions for multi-stage settings that can't
 	 * be routed with a simple uniform forward.
 	 */
-	_buildHandlers( stages, reconcileCompletion ) {
+	_buildHandlers( stages, renderer, reconcileCompletion ) {
 
 		return {
 
 			handleTransparentBackground: ( value ) => {
 
 				stages.pathTracer?.setUniform( 'transparentBackground', value );
-				stages.display?.setTransparentBackground( value );
+				stages.compositor?.setTransparentBackground( value );
 
 			},
 
 			handleExposure: ( value ) => {
 
-				if ( ! stages.autoExposure?.enabled ) {
+				// Three.js applies toneMappingExposure inside the tone-mapping branch,
+				// so this has no effect when renderer.toneMapping === NoToneMapping.
+				if ( ! stages.autoExposure?.enabled && renderer ) {
 
-					stages.display?.setExposure( value );
+					renderer.toneMappingExposure = value;
 
 				}
 
@@ -144,7 +146,7 @@ export class RenderSettings extends EventDispatcher {
 
 			handleSaturation: ( value ) => {
 
-				stages.display?.setSaturation( value );
+				stages.compositor?.setSaturation( value );
 
 			},
 

package/src/Stages/Compositor.js

@@ -0,0 +1,101 @@
+import { vec4, vec3, uv, uniform, select, dot, mix } from 'three/tsl';
+import { MeshBasicNodeMaterial, QuadMesh, TextureNode } from 'three/webgpu';
+import { NoBlending } from 'three';
+import { RenderStage, StageExecutionMode } from '../Pipeline/RenderStage.js';
+import { REC709_LUMINANCE_COEFFICIENTS } from '../TSL/Common.js';
+
+/**
+ * Compositor — Terminal pipeline stage.
+ *
+ * Selects the latest upstream texture via a priority fallback chain, applies
+ * a saturation grade, sets alpha, and hands the linear HDR result to the
+ * renderer's output pass (tone mapping + sRGB gamma happen there).
+ *
+ * Exposure is not applied here — `renderer.toneMappingExposure` owns it,
+ * and Three.js applies it inside the tone-mapping branch of the output pass
+ * (so it has no effect when `renderer.toneMapping === NoToneMapping`).
+ */
+export class Compositor extends RenderStage {
+
+	constructor( renderer, options = {} ) {
+
+		super( 'Compositor', {
+			...options,
+			executionMode: StageExecutionMode.ALWAYS
+		} );
+
+		this.renderer = renderer;
+
+		// 1.0 = neutral; >1 boosts to compensate for ACES/AgX desaturation.
+		this.saturation = uniform( options.saturation ?? 1.0 );
+
+		this._transparentBackground = uniform( 0, 'int' );
+
+		// TextureNode reused across frames — only `.value` mutates, shader doesn't recompile.
+		this._sourceTexNode = new TextureNode();
+
+		const texSample = this._sourceTexNode.sample( uv() );
+
+		const luma = dot( texSample.xyz, REC709_LUMINANCE_COEFFICIENTS );
+		const gradedColor = mix( vec3( luma ), texSample.xyz, this.saturation );
+
+		const outputAlpha = select( this._transparentBackground, texSample.w, 1.0 );
+
+		this.compositorMaterial = new MeshBasicNodeMaterial();
+		this.compositorMaterial.colorNode = vec4( gradedColor, outputAlpha );
+		this.compositorMaterial.blending = NoBlending;
+
+		this.compositorQuad = new QuadMesh( this.compositorMaterial );
+
+	}
+
+	/**
+	 * Later stages in the chain take priority; `pathtracer:color` is the
+	 * baseline fallback that is always present.
+	 */
+	_resolveSourceTexture( context ) {
+
+		return context.getTexture( 'bloom:output' )
+			|| context.getTexture( 'edgeFiltering:output' )
+			|| context.getTexture( 'asvgf:output' )
+			|| context.getTexture( 'ssrc:output' )
+			|| context.getTexture( 'pathtracer:color' );
+
+	}
+
+	render( context ) {
+
+		if ( ! this.enabled ) return;
+
+		const sourceTexture = this._resolveSourceTexture( context );
+		if ( ! sourceTexture ) return;
+
+		this._sourceTexNode.value = sourceTexture;
+
+		this.renderer.setRenderTarget( null );
+		this.compositorQuad.render( this.renderer );
+
+	}
+
+	setSaturation( value ) {
+
+		this.saturation.value = value;
+
+	}
+
+	setTransparentBackground( enabled ) {
+
+		this._transparentBackground.value = enabled ? 1 : 0;
+
+	}
+
+	dispose() {
+
+		this._sourceTexNode?.dispose();
+		this.compositorMaterial?.dispose();
+		// QuadMesh extends Mesh — no dispose method; material already released above.
+		this.compositorQuad = null;
+
+	}
+
+}

package/src/Stages/NormalDepth.js

@@ -95,6 +95,14 @@ export class NormalDepth extends RenderStage {
 		this._bvhStorageNode = null;
 		this._matStorageNode = null;
 
+		// Last-seen attribute identities. PathTracer replaces these in-place
+		// across model load / BVH rebuild; the compute's bind group is locked
+		// to whatever buffer was bound at pipeline compile time, so we rebuild
+		// when any of them swaps to a new object.
+		this._lastTriAttr = null;
+		this._lastBvhAttr = null;
+		this._lastMatAttr = null;
+
 		// Compute node — built once when storage buffers are ready
 		this._computeNode = null;
 		this._computeBuilt = false;
@@ -138,50 +146,59 @@ export class NormalDepth extends RenderStage {
 		const pt = this.pathTracer;
 		if ( ! pt ) return false;
 
-		// Triangle storage
+		const matStorageAttr = pt.materialData.materialStorageAttr;
+
+		// Detect attribute identity swap (PathTracer.setTriangleData /
+		// setBVHData replace the attribute object on growth). The compute
+		// node's bind group is locked to the buffer bound at compile time —
+		// updating the storage node's .value alone leaves the GPU binding
+		// pointing at the now-discarded buffer, so every traversal misses.
+		const triSwapped = pt.triangleStorageAttr && pt.triangleStorageAttr !== this._lastTriAttr;
+		const bvhSwapped = pt.bvhStorageAttr && pt.bvhStorageAttr !== this._lastBvhAttr;
+		const matSwapped = matStorageAttr && matStorageAttr !== this._lastMatAttr;
+
+		if ( triSwapped || bvhSwapped || matSwapped ) {
+
+			// Drop compute + storage nodes so they get rebuilt against the
+			// current buffers. Cheap: this only happens on model load.
+			this._computeNode?.dispose?.();
+			this._computeNode = null;
+			this._computeBuilt = false;
+			this._triStorageNode = null;
+			this._bvhStorageNode = null;
+			this._matStorageNode = null;
+			this._dirty = true;
+
+		}
+
 		if ( pt.triangleStorageAttr && ! this._triStorageNode ) {
 
 			this._triStorageNode = storage(
 				pt.triangleStorageAttr, 'vec4', pt.triangleStorageAttr.count
 			).toReadOnly();
 
-		} else if ( pt.triangleStorageAttr && this._triStorageNode ) {
-
-			// Data changed (new model loaded) — update in-place
-			this._triStorageNode.value = pt.triangleStorageAttr;
-			this._triStorageNode.bufferCount = pt.triangleStorageAttr.count;
-
 		}
 
-		// BVH storage
 		if ( pt.bvhStorageAttr && ! this._bvhStorageNode ) {
 
 			this._bvhStorageNode = storage(
 				pt.bvhStorageAttr, 'vec4', pt.bvhStorageAttr.count
 			).toReadOnly();
 
-		} else if ( pt.bvhStorageAttr && this._bvhStorageNode ) {
-
-			this._bvhStorageNode.value = pt.bvhStorageAttr;
-			this._bvhStorageNode.bufferCount = pt.bvhStorageAttr.count;
-
 		}
 
-		// Material storage
-		const matStorageAttr = pt.materialData.materialStorageAttr;
 		if ( matStorageAttr && ! this._matStorageNode ) {
 
 			this._matStorageNode = storage(
 				matStorageAttr, 'vec4', matStorageAttr.count
 			).toReadOnly();
 
-		} else if ( matStorageAttr && this._matStorageNode ) {
-
-			this._matStorageNode.value = matStorageAttr;
-			this._matStorageNode.bufferCount = matStorageAttr.count;
-
 		}
 
+		this._lastTriAttr = pt.triangleStorageAttr || this._lastTriAttr;
+		this._lastBvhAttr = pt.bvhStorageAttr || this._lastBvhAttr;
+		this._lastMatAttr = matStorageAttr || this._lastMatAttr;
+
 		return !! ( this._triStorageNode && this._bvhStorageNode && this._matStorageNode );
 
 	}

package/src/managers/DenoisingManager.js

@@ -41,7 +41,7 @@ export class DenoisingManager extends EventDispatcher {
 		this.pipeline = pipeline;
 
 		// Stage references — only used internally for orchestration
-		this._stages = stages; // { pathTracer, asvgf, variance, bilateralFilter, adaptiveSampling, edgeFilter, ssrc, autoExposure, display }
+		this._stages = stages; // { pathTracer, asvgf, variance, bilateralFilter, adaptiveSampling, edgeFilter, ssrc, autoExposure, compositor }
 
 		this._getExposure = getExposure;
 		this._getSaturation = getSaturation;
@@ -295,9 +295,8 @@ export class DenoisingManager extends EventDispatcher {
 	}
 
 	/**
-	 * Enables/disables auto-exposure with proper exposure stacking management.
 	 * @param {boolean} enabled
-	 * @param {number}  manualExposure - The manual exposure value to restore when disabling
+	 * @param {number}  manualExposure - Restored to renderer.toneMappingExposure when disabling.
 	 */
 	setAutoExposureEnabled( enabled, manualExposure ) {
 
@@ -306,19 +305,10 @@ export class DenoisingManager extends EventDispatcher {
 
 		s.autoExposure.enabled = enabled;
 
-		if ( enabled ) {
-
-			// Neutralize Display manual exposure to avoid stacking
-			s.display?.setExposure( 1.0 );
-
-		} else {
+		// AutoExposure overwrites renderer.toneMappingExposure each frame; restore manual on disable.
+		if ( ! enabled && this.renderer ) {
 
-			s.display?.setExposure( manualExposure );
-			if ( s.display && this.renderer ) {
-
-				this.renderer.toneMappingExposure = 1.0;
-
-			}
+			this.renderer.toneMappingExposure = manualExposure;
 
 		}
 
@@ -417,10 +407,10 @@ export class DenoisingManager extends EventDispatcher {
 
 		} else {
 
-			// Re-render display stage so WebGPU canvas has valid content
-			if ( this.upscaler?.enabled && this._stages.display && context ) {
+			// Re-render compositor stage so WebGPU canvas has valid content
+			if ( this.upscaler?.enabled && this._stages.compositor && context ) {
 
-				this._stages.display.render( context );
+				this._stages.compositor.render( context );
 
 			}
 

package/src/Stages/Display.js

@@ -1,120 +0,0 @@
-import { vec4, vec3, uv, uniform, select, dot, mix } from 'three/tsl';
-import { MeshBasicNodeMaterial, QuadMesh, TextureNode } from 'three/webgpu';
-import { NoBlending } from 'three';
-import { RenderStage, StageExecutionMode } from '../Pipeline/RenderStage.js';
-import { REC709_LUMINANCE_COEFFICIENTS } from '../TSL/Common.js';
-
-/**
- * Display — Terminal pipeline stage for WebGPU.
- *
- * Reads the final colour texture from the pipeline context (using a
- * priority fallback chain), applies exposure, and renders to screen.
- *
- * When new post-processing stages are added between PathTracer and
- * Display, the fallback chain automatically picks up the latest output
- * without any wiring changes.
- */
-export class Display extends RenderStage {
-
-	constructor( renderer, options = {} ) {
-
-		super( 'Display', {
-			...options,
-			executionMode: StageExecutionMode.ALWAYS
-		} );
-
-		this.renderer = renderer;
-
-		// Exposure uniform — linear multiplier (consistent with auto-exposure)
-		this.exposure = uniform( options.exposure ?? 1.0 );
-
-		// Pre-tonemapping saturation — compensates for ACES/AgX desaturation (1.0 = neutral)
-		this.saturation = uniform( options.saturation ?? 1.0 );
-
-		// Transparent background toggle
-		this._transparentBackground = uniform( 0, 'int' );
-
-		// Updatable texture node — swap .value each frame, no shader recompile
-		this._displayTexNode = new TextureNode();
-
-		const texSample = this._displayTexNode.sample( uv() );
-
-		// Build material once (TSL compiles on first render)
-		const exposed = texSample.xyz.mul( this.exposure );
-
-		// Saturation adjustment (before tonemapping): mix between luminance and color
-		const luma = dot( exposed, REC709_LUMINANCE_COEFFICIENTS );
-		let displayShader = mix( vec3( luma ), exposed, this.saturation );
-
-		// Alpha: pass through source alpha when transparent, otherwise 1.0
-		const outputAlpha = select( this._transparentBackground, texSample.w, 1.0 );
-
-		this.displayMaterial = new MeshBasicNodeMaterial();
-		this.displayMaterial.colorNode = vec4( displayShader, outputAlpha );
-		this.displayMaterial.blending = NoBlending;
-		this.displayMaterial.toneMapped = true;
-
-		this.displayQuad = new QuadMesh( this.displayMaterial );
-
-	}
-
-	/**
-	 * Resolve the best available output texture from the pipeline context.
-	 * Later stages in the chain take priority; pathtracer:color is the
-	 * baseline fallback that is always present.
-	 */
-	_resolveDisplayTexture( context ) {
-
-		return context.getTexture( 'bloom:output' )
-			|| context.getTexture( 'edgeFiltering:output' )
-			|| context.getTexture( 'asvgf:output' )
-			|| context.getTexture( 'ssrc:output' )
-			|| context.getTexture( 'pathtracer:color' );
-
-	}
-
-	render( context ) {
-
-		if ( ! this.enabled ) return;
-
-		const displayTexture = this._resolveDisplayTexture( context );
-
-		if ( ! displayTexture ) return;
-
-		// Swap texture reference (no shader recompilation)
-		this._displayTexNode.value = displayTexture;
-
-		// Render to screen
-		this.renderer.setRenderTarget( null );
-		this.displayQuad.render( this.renderer );
-
-	}
-
-	setExposure( value ) {
-
-		this.exposure.value = value;
-
-	}
-
-	setSaturation( value ) {
-
-		this.saturation.value = value;
-
-	}
-
-	setTransparentBackground( enabled ) {
-
-		this._transparentBackground.value = enabled ? 1 : 0;
-
-	}
-
-	dispose() {
-
-		this._displayTexNode?.dispose();
-		this.displayMaterial?.dispose();
-		// QuadMesh extends Mesh — no dispose method; material already disposed.
-		this.displayQuad = null;
-
-	}
-
-}