rayzee 9.4.1 → 9.5.0

package/src/RenderSettings.js

@@ -5,13 +5,13 @@ import { ISSUE_CODES } from './EngineIssues.js';
 import { toPortable, fromPortable } from './SceneState/portable.js';
 
 /**
- * Routing table: maps each setting key to its target stage/handler.
+ * The renderer core's settings: maps each key to its target.
  *
  * - `uniform`  → forwarded to PathTracer.setUniform(uniform, value)
  * - `handler`  → calls a named handler method for multi-stage settings
- * - `delegate` → routes to a named manager's updateParam(param, value)
  * - `reset`    → whether to reset accumulation after the change (default true)
- * - `after`    → optional method to call on PathTracer after the uniform is set
+ *
+ * Other layers add their own keys with {@link RenderSettings#define}.
  */
 const SETTING_ROUTES = {
 
@@ -68,7 +68,6 @@ const SETTING_ROUTES = {
 	panoramaLonRange: { handler: 'handlePanoramaLonRange', reset: true },
 	panoramaLatRange: { handler: 'handlePanoramaLatRange', reset: true },
 	interactionModeEnabled: { handler: 'handleInteractionModeEnabled', reset: false },
-	interactionRenderScale: { handler: 'handleInteractionRenderScale', reset: false },
 	maxSamples: { handler: 'handleMaxSamples', reset: false },
 	transparentBackground: { handler: 'handleTransparentBackground' },
 	backgroundColor: { handler: 'handleBackgroundColor', reset: true },
@@ -77,6 +76,7 @@ const SETTING_ROUTES = {
 	renderLimitMode: { handler: 'handleRenderLimitMode' },
 	renderTimeLimit: { handler: 'handleRenderTimeLimit', reset: false },
 	renderMode: { handler: 'handleRenderMode' },
+	integrator: { handler: 'handleIntegrator', reset: true },
 	environmentRotation: { handler: 'handleEnvironmentRotation' },
 
 };
@@ -122,6 +122,12 @@ export class RenderSettings extends EventDispatcher {
 
 		this._issues = issues;
 
+		/** Default values, kept for keys another layer defines later */
+		this._defaults = defaults;
+
+		/** @type {Map<string, Object>} - the core's routes and those other layers define */
+		this._routes = new Map( Object.entries( SETTING_ROUTES ) );
+
 		/** @type {Map<string, *>} */
 		this._values = new Map();
 
@@ -137,39 +143,55 @@ export class RenderSettings extends EventDispatcher {
 		/** @type {Object<string, Function>} - Named handlers for multi-stage settings */
 		this._handlers = {};
 
-		/** @type {Object<string, Object>} - Named delegate managers */
-		this._delegates = {};
-
 		// Initialize values from ENGINE_DEFAULTS
 		this._initDefaults( defaults );
 
 	}
 
 	/**
-	 * Wires internal references. Called by PathTracerApp after init().
+	 * Wires the core's settings to their targets. Called by the renderer during init().
 	 *
 	 * @param {Object} params
-	 * @param {Object} params.stages           - Pipeline stages { pathTracer, compositor, autoExposure, ... }
+	 * @param {Object} params.stages           - Pipeline stages { pathTracer, compositor }
 	 * @param {Function} params.resetCallback   - Called to reset accumulation
 	 * @param {Function} [params.reconcileCompletion] - Called when completion limits change
-	 * @param {Object} [params.denoisingManager] - Needed to force ASVGF off under panorama
-	 * @param {Function} [params.onInteractionRenderScale] - Applies a new moving-camera render scale
+	 * @param {Function} [params.applyExposure] - Shows a new `exposure`
 	 * @param {Function} [params.onCameraProjection] - The camera's side of a `cameraProjection` change
 	 */
 	bind( params ) {
 
 		this._pathTracer = params.stages.pathTracer;
 		this._resetCallback = params.resetCallback;
-		this._delegates = {};
 		this._handlers = this._buildHandlers( params );
 
 	}
 
+	/**
+	 * Adds a setting of another layer — the viewer's, or an add-on's — with the same provenance, events, session
+	 * saving and reset as the core's. Its default comes from the defaults this store was built with.
+	 * @param {string} key
+	 * @param {Object} route
+	 * @param {function(*, *): void} route.apply - called with ( value, prev ) on every change, and by applyAll()
+	 * @param {boolean} [route.reset=true] - reset accumulation after a change
+	 */
+	define( key, { apply, reset = true } ) {
+
+		if ( this._routes.has( key ) ) throw new Error( `setting "${key}" is already defined` );
+		this._routes.set( key, { apply, reset } );
+		if ( ! this._values.has( key ) && key in this._defaults ) {
+
+			this._values.set( key, this._defaults[ key ] );
+			this._sources.set( key, SETTING_SOURCE.DEFAULT );
+
+		}
+
+	}
+
 	/**
 	 * Builds handler functions for multi-stage settings that can't
 	 * be routed with a simple uniform forward.
 	 */
-	_buildHandlers( { stages, renderer, resetCallback, reconcileCompletion, denoisingManager, onInteractionRenderScale, onCameraProjection } ) {
+	_buildHandlers( { stages, resetCallback, reconcileCompletion, applyExposure, onCameraProjection } ) {
 
 		// UniformManager copies into the existing node, so one scratch vector serves every write.
 		const panoScratch = new Vector2();
@@ -187,13 +209,6 @@ export class RenderSettings extends EventDispatcher {
 				stages.pathTracer?.setUniform( 'cameraProjection', CAMERA_PROJECTION_IDS[ value ] ?? CAMERA_PROJECTION_IDS.perspective );
 				onCameraProjection?.( value );
 
-				if ( value !== 'equirectangular' ) return;
-
-				// 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 ( denoisingManager?.requiresMotionVectors ) denoisingManager.setDenoiserStrategy( 'edgeaware' );
-
 			},
 
 			handleDofMode: ( value ) => stages.pathTracer?.setUniform( 'dofMode', value === 'look' ? 1 : 0 ),
@@ -220,13 +235,7 @@ export class RenderSettings extends EventDispatcher {
 
 			handleExposure: ( value ) => {
 
-				// Three.js applies toneMappingExposure inside the tone-mapping branch,
-				// so this has no effect when renderer.toneMapping === NoToneMapping.
-				if ( ! stages.autoExposure?.enabled && renderer ) {
-
-					renderer.toneMappingExposure = value;
-
-				}
+				applyExposure?.( value );
 
 			},
 
@@ -274,21 +283,21 @@ export class RenderSettings extends EventDispatcher {
 
 			},
 
-			handleEnvironmentRotation: ( value ) => {
+			handleIntegrator: ( value ) => {
 
-				stages.pathTracer?.environment.setEnvironmentRotation( value );
+				stages.pathTracer?.setIntegrator?.( value );
 
 			},
 
-			handleInteractionModeEnabled: ( value ) => {
+			handleEnvironmentRotation: ( value ) => {
 
-				stages.pathTracer?.setInteractionModeEnabled( value );
+				stages.pathTracer?.environment.setEnvironmentRotation( value );
 
 			},
 
-			handleInteractionRenderScale: ( value ) => {
+			handleInteractionModeEnabled: ( value ) => {
 
-				onInteractionRenderScale?.( value );
+				stages.pathTracer?.setInteractionModeEnabled( value );
 
 			},
 
@@ -365,7 +374,7 @@ export class RenderSettings extends EventDispatcher {
 		this._values.set( key, value );
 		this._sources.set( key, source );
 
-		const route = SETTING_ROUTES[ key ];
+		const route = this._routes.get( key );
 		if ( ! route ) {
 
 			this._reportUnknownKey( key );
@@ -410,7 +419,7 @@ export class RenderSettings extends EventDispatcher {
 			out[ key ] = {
 				value,
 				source: this._sources.get( key ) ?? SETTING_SOURCE.DEFAULT,
-				routed: SETTING_ROUTES[ key ] !== undefined,
+				routed: this._routes.has( key ),
 			};
 
 		}
@@ -431,7 +440,7 @@ export class RenderSettings extends EventDispatcher {
 		const out = {};
 		for ( const [ key, value ] of this._values ) {
 
-			if ( this._sources.get( key ) !== SETTING_SOURCE.HOST || ! SETTING_ROUTES[ key ] ) continue;
+			if ( this._sources.get( key ) !== SETTING_SOURCE.HOST || ! this._routes.has( key ) ) continue;
 			const portable = toPortable( value );
 			if ( portable !== undefined ) out[ key ] = portable;
 
@@ -452,7 +461,7 @@ export class RenderSettings extends EventDispatcher {
 		const unknown = [];
 		for ( const [ key, value ] of Object.entries( values ?? {} ) ) {
 
-			if ( SETTING_ROUTES[ key ] ) known[ key ] = fromPortable( value );
+			if ( this._routes.has( key ) ) known[ key ] = fromPortable( value );
 			else unknown.push( key );
 
 		}
@@ -470,7 +479,7 @@ export class RenderSettings extends EventDispatcher {
 
 		for ( const [ key, value ] of this._values ) {
 
-			const route = SETTING_ROUTES[ key ];
+			const route = this._routes.get( key );
 			if ( ! route ) continue;
 
 			// prev is undefined on initial apply — handlers should not rely on it
@@ -487,15 +496,14 @@ export class RenderSettings extends EventDispatcher {
 		if ( route.uniform ) {
 
 			this._pathTracer?.setUniform( route.uniform, value );
-			if ( route.after ) this._pathTracer?.[ route.after ]?.();
 
 		} else if ( route.handler ) {
 
 			this._handlers[ route.handler ]?.( value, prev );
 
-		} else if ( route.delegate ) {
+		} else {
 
-			this._delegates[ route.delegate ]?.updateParam?.( route.param, value );
+			route.apply( value, prev );
 
 		}
 

package/src/Stages/ASVGF.js

@@ -52,7 +52,7 @@ export class ASVGF extends RenderStage {
 		this.resH = uniform( options.height || 1 );
 
 		this.temporalEnabledU = uniform( 1.0 );
-		// 1.0 for one frame after asvgf:reset → forces a fresh sample so stale pre-reset
+		// 1.0 for one frame after pipeline:historyReset → forces a fresh sample so stale pre-reset
 		// (wrong-scene) history isn't blended in (mirrors Variance's _needsWarmReset).
 		this.forceResetU = uniform( 0.0 );
 
@@ -398,7 +398,7 @@ export class ASVGF extends RenderStage {
 				const demodResult = vec4( currentLighting, 1.0 ).toVar();
 				const modulatedResult = vec4( currentColor, currentAlpha ).toVar();
 
-				// forceResetU skips the blend for one frame after asvgf:reset → re-anchors
+				// forceResetU skips the blend for one frame after pipeline:historyReset → re-anchors
 				// history to the current (post-reset) scene instead of the stale ping-pong.
 				If( temporalEnabledU.greaterThan( 0.5 ).and( forceResetU.lessThan( 0.5 ) ), () => {
 
@@ -647,9 +647,7 @@ export class ASVGF extends RenderStage {
 
 	setupEventListeners() {
 
-		this.on( 'asvgf:reset', () => this.resetTemporalData() );
-
-		this.on( 'asvgf:updateParameters', ( data ) => this.updateParameters( data ) );
+		this.on( 'pipeline:historyReset', () => this.resetTemporalData() );
 
 	}
 
@@ -720,7 +718,7 @@ export class ASVGF extends RenderStage {
 
 		}
 
-		// One-shot fresh re-anchor after asvgf:reset, threaded through the SINGLE
+		// One-shot fresh re-anchor after pipeline:historyReset, threaded through the SINGLE
 		// writeNode dispatch (a dual-node warmup would alias the read target — see setSize).
 		this.forceResetU.value = this._needsWarmReset ? 1.0 : 0.0;
 		this.renderer.compute( writeNode );
@@ -865,7 +863,7 @@ export class ASVGF extends RenderStage {
 
 	reset() {
 
-		// No-op: motion vectors handle camera moves; explicit asvgf:reset
+		// No-op: motion vectors handle camera moves; explicit pipeline:historyReset
 		// clears history on scene/mode change.
 
 	}

package/src/Stages/AutoExposure.js

@@ -80,9 +80,8 @@ const adaptExposure = /*@__PURE__*/ wgslFn( `
  * Execution: ALWAYS
  *
  * Events listened:
- *   pipeline:reset              — reset temporal history
- *   autoexposure:toggle         — enable/disable
- *   autoexposure:updateParameters — update key value, speeds, bounds, percentiles
+ *   pipeline:reset              — soft reset (keeps the exposure, discards an in-flight readback)
+ *   pipeline:lightingChanged    — a new model or environment: start the exposure history over
  *
  * Textures published:  (none — publishes state, not textures)
  * Textures read:       edgeFiltering:output > asvgf:output > pathtracer:color
@@ -471,15 +470,7 @@ export class AutoExposure extends RenderStage {
 	setupEventListeners() {
 
 		this.on( 'pipeline:reset', () => this.reset() );
-		this.on( 'autoexposure:resetHistory', () => this.resetHistory() );
-
-		this.on( 'autoexposure:toggle', ( enabled ) => {
-
-			this.enabled = enabled;
-
-		} );
-
-		this.on( 'autoexposure:updateParameters', ( data ) => data && this.updateParameters( data ) );
+		this.on( 'pipeline:lightingChanged', () => this.resetHistory() );
 
 	}
 

package/src/Stages/Compositor.js

@@ -4,15 +4,6 @@ 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.
@@ -36,6 +27,10 @@ export class Compositor extends RenderStage {
 
 		this.renderer = renderer;
 
+		// In priority order: the first one published wins. Whoever builds the pipeline names the
+		// processed pictures; the accumulation is the fallback that is always there.
+		this._lightSources = [ ...( options.displaySources ?? [] ), 'pathtracer:color' ];
+
 		// 1.0 = neutral; >1 boosts to compensate for ACES/AgX desaturation.
 		this.saturation = uniform( options.saturation ?? 1.0 );
 
@@ -71,18 +66,8 @@ export class Compositor extends RenderStage {
 	}
 
 	/**
-	 * Later stages in the chain take priority; `pathtracer:color` is the
-	 * baseline fallback that is always present.
-	 */
-	_resolveSourceTexture( context ) {
-
-		return context.getTexture( 'bloom:output' ) || this.resolveLightTexture( context );
-
-	}
-
-	/**
-	 * The newest scene-referred image the pipeline holds — denoised when a denoiser has run — without
-	 * bloom, which is a look added on top rather than light in the scene.
+	 * The picture to show: the first published of the display sources, else `pathtracer:color` — the newest
+	 * scene-referred image the pipeline holds, denoised when a denoiser has run.
 	 */
 	resolveLightTexture( context ) {
 
@@ -93,7 +78,7 @@ export class Compositor extends RenderStage {
 	/** {@link resolveLightTexture} plus the context key it came from. */
 	resolveLightSource( context ) {
 
-		for ( const key of LIGHT_SOURCES ) {
+		for ( const key of this._lightSources ) {
 
 			const texture = context.getTexture( key );
 			if ( texture ) return { key, texture };
@@ -215,7 +200,7 @@ export class Compositor extends RenderStage {
 
 		}
 
-		const sourceTexture = this._resolveSourceTexture( context );
+		const sourceTexture = this.resolveLightTexture( context );
 		if ( ! sourceTexture ) return;
 
 		this._sourceTexNode.value = sourceTexture;

package/src/Stages/NRD.js

@@ -133,7 +133,7 @@ function hash01( n ) {
  * Reads:     pathtracer:color, pathtracer:albedo (.w = normHitDist), pathtracer:normalDepth,
  *            pathtracer:shadingNormal (.w = roughness), motionVector:screenSpace
  * Publishes: nrd:output
- * Events:    denoiser:reset
+ * Events:    pipeline:historyReset
  */
 export class NRD extends RenderStage {
 
@@ -148,6 +148,11 @@ export class NRD extends RenderStage {
 		this.pathTracer = options.pathTracer || null;
 		this.settings = { ...NRD_DEFAULTS, ...( options.settings || {} ) };
 
+		// The path tracer's hit distance, normalised by view depth as ReBLUR reads it (pathtracer:albedo.w).
+		this._releaseHitDistance = this.pathTracer?.requestOutput?.( 'hitDistance', {
+			encode: ( distance, viewZ ) => distance.div( max( viewZ.mul( NRD_HIT_DIST_B ).add( NRD_HIT_DIST_A ), float( 1e-4 ) ) ).clamp( 0.0, 1.0 ),
+		} ) ?? null;
+
 		const w = options.width || 1;
 		const h = options.height || 1;
 
@@ -1185,7 +1190,7 @@ export class NRD extends RenderStage {
 
 	setupEventListeners() {
 
-		this.on( 'denoiser:reset', () => this.resetHistory() );
+		this.on( 'pipeline:historyReset', () => this.resetHistory() );
 
 	}
 
@@ -1383,6 +1388,8 @@ export class NRD extends RenderStage {
 
 	dispose() {
 
+		this._releaseHitDistance?.();
+		this._releaseHitDistance = null;
 		this._disposeKernels();
 		this._disposeStorage();
 		this.outputTarget?.dispose();

package/src/Stages/NormalDepth.js

@@ -8,7 +8,8 @@ import { Ray, HitInfo, RayTracingMaterial, UVCache } from '../TSL/Struct.js';
 import { traverseBVH } from '../TSL/BVHTraversal.js';
 import { cameraRayOf, cameraRayUniforms } from '../TSL/CameraRay.js';
 import { getMaterial } from '../TSL/Common.js';
-import { computeUVCache, processNormal, processBump, processMetalnessRoughness, triangleUVTangent, buildBucketTextureNodes, refreshBucketTextureNodes, setMaterialBucketTextures } from '../TSL/TextureSampling.js';
+import { computeUVCache, processNormal, processBump, processMetalnessRoughness, triangleUVTangent, buildBucketTextureNodes, refreshBucketTextureNodes } from '../TSL/TextureSampling.js';
+import { withSceneResources } from '../TSL/SceneResources.js';
 
 /**
  * NormalDepth — primary-ray G-buffer for SVGF gates.
@@ -207,11 +208,13 @@ export class NormalDepth extends RenderStage {
 		const triStorage = this._triStorageNode;
 		const bvhStorage = this._bvhStorageNode;
 		const matStorage = this._matStorageNode;
-		// Independent linear-pool bucket nodes for this pipeline (normal + bump). The sRGB pool
-		// is never sampled here, so it gets placeholders. Publish to the sampling module before
-		// the graph is built so processNormal/processBump bake in THESE (per-pipeline) nodes.
+		// Independent linear-pool bucket nodes for this pipeline (normal + bump), in its kernel's build
+		// context (SceneResources.js). The sRGB pool is never sampled here, so it gets placeholders.
 		this._linearBuckets = buildBucketTextureNodes( this.pathTracer?.materialData?.linearBuckets );
-		setMaterialBucketTextures( buildBucketTextureNodes( null ), this._linearBuckets );
+		const resources = {
+			srgbBuckets: buildBucketTextureNodes( null ), linearBuckets: this._linearBuckets,
+			shadowAlbedoMaps: null, goboMaps: null, iesProfiles: null, alphaShadows: null,
+		};
 		const camWorld = this.cameraWorldMatrix;
 		const camProjInv = this.cameraProjectionMatrixInverse;
 		const resW = this.resolutionWidth;
@@ -308,7 +311,7 @@ export class NormalDepth extends RenderStage {
 
 		} );
 
-		this._computeNode = computeFn( camWorld, camProjInv ).compute(
+		this._computeNode = withSceneResources( computeFn( camWorld, camProjInv ), resources ).compute(
 			[ this._dispatchX, this._dispatchY, 1 ],
 			[ WG_SIZE, WG_SIZE, 1 ]
 		);