rayzee 10.0.0 → 11.1.0

package/src/RenderSettings.js

@@ -5,13 +5,14 @@ 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)
+ * - neither   → stored only; whoever needs it reads it
  * - `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 +69,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,14 +77,17 @@ const SETTING_ROUTES = {
 	renderLimitMode: { handler: 'handleRenderLimitMode' },
 	renderTimeLimit: { handler: 'handleRenderTimeLimit', reset: false },
 	renderMode: { handler: 'handleRenderMode' },
+	integrator: { handler: 'handleIntegrator', reset: true },
+	shadowRays: { handler: 'handleShadowRays', reset: true },
 	environmentRotation: { handler: 'handleEnvironmentRotation' },
+	// Read when the kernels next build.
+	wavefrontSortMaterials: { handler: 'handleWavefrontSortMaterials', reset: false },
+	// No target: read when a model loads (setMaxTextureSize() also reprocesses the scene now).
+	maxTextureSize: { reset: false },
+	areaLightIntensityScale: { reset: false },
 
 };
 
-/**
- * Default keys to extract from ENGINE_DEFAULTS for initializing the values map.
- * Maps ENGINE_DEFAULTS key → RenderSettings key when they differ.
- */
 /** Provenance tags for getEffective(). Add-only — hosts branch on them. */
 export const SETTING_SOURCE = Object.freeze( {
 	DEFAULT: 'default',
@@ -93,11 +96,6 @@ export const SETTING_SOURCE = Object.freeze( {
 	MODE_PRESET: 'mode-preset',
 } );
 
-const DEFAULTS_KEY_MAP = {
-	bounces: 'maxBounces',
-	debugMode: 'visMode',
-};
-
 /**
  * Single source of truth for all render parameters.
  *
@@ -122,6 +120,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 +141,57 @@ 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. The layer brings its own default.
+	 * @param {string} key
+	 * @param {Object} route
+	 * @param {*} [route.default] - the value until someone sets one; else the one this store was built with
+	 * @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, { default: initial, apply, reset = true } ) {
+
+		if ( this._routes.has( key ) ) throw new Error( `setting "${key}" is already defined` );
+		this._routes.set( key, { apply, reset } );
+		const value = initial !== undefined ? initial : this._defaults[ key ];
+		if ( ! this._values.has( key ) && value !== undefined ) {
+
+			this._values.set( key, value );
+			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,33 @@ export class RenderSettings extends EventDispatcher {
 
 			},
 
+			handleIntegrator: ( value ) => {
+
+				stages.pathTracer?.setIntegrator?.( value );
+
+			},
+
+			handleShadowRays: ( value ) => {
+
+				stages.pathTracer?.setShadowRays?.( value );
+
+			},
+
 			handleEnvironmentRotation: ( value ) => {
 
 				stages.pathTracer?.environment.setEnvironmentRotation( value );
 
 			},
 
-			handleInteractionModeEnabled: ( value ) => {
+			handleWavefrontSortMaterials: ( value ) => {
 
-				stages.pathTracer?.setInteractionModeEnabled( value );
+				if ( stages.pathTracer ) stages.pathTracer.sortMaterials = value;
 
 			},
 
-			handleInteractionRenderScale: ( value ) => {
+			handleInteractionModeEnabled: ( value ) => {
 
-				onInteractionRenderScale?.( value );
+				stages.pathTracer?.setInteractionModeEnabled( value );
 
 			},
 
@@ -365,7 +386,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 +431,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 +452,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 +473,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 +491,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 +508,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 );
 
 		}
 
@@ -503,11 +523,9 @@ export class RenderSettings extends EventDispatcher {
 
 	/**
 	 * Populates the values map from ENGINE_DEFAULTS.
-	 * Handles key renames via DEFAULTS_KEY_MAP.
 	 */
 	_initDefaults( defaults ) {
 
-		// Keys that exist in both SETTING_ROUTES and ENGINE_DEFAULTS (direct match)
 		for ( const key of Object.keys( SETTING_ROUTES ) ) {
 
 			if ( key in defaults ) {
@@ -519,18 +537,6 @@ export class RenderSettings extends EventDispatcher {
 
 		}
 
-		// Keys where ENGINE_DEFAULTS uses a different name
-		for ( const [ defaultsKey, settingsKey ] of Object.entries( DEFAULTS_KEY_MAP ) ) {
-
-			if ( defaultsKey in defaults ) {
-
-				this._values.set( settingsKey, defaults[ defaultsKey ] );
-				this._sources.set( settingsKey, SETTING_SOURCE.DEFAULT );
-
-			}
-
-		}
-
 	}
 
 }

package/src/Stages/ASVGF.js

@@ -5,7 +5,8 @@ import { RenderTarget, TextureNode, StorageTexture } from 'three/webgpu';
 import { HalfFloatType, FloatType, RGBAFormat, NearestFilter, LinearFilter, Box2, Vector2 } from 'three';
 import { RenderStage, StageExecutionMode } from '../Pipeline/RenderStage.js';
 import { luminance } from '../TSL/Common.js';
-import { ALBEDO_EPS, MAX_STORAGE_TEXTURE_SIZE } from '../EngineDefaults.js';
+import { MAX_STORAGE_TEXTURE_SIZE } from '../Processor/StorageTexturePool.js';
+import { ALBEDO_EPS, ASVGF_QUALITY_PRESETS } from './DenoiserSettings.js';
 
 // Replace NaN/±Inf with a bounded value so one firefly can't permanently poison the
 // temporal EMA (mix() propagates NaN forever). Per-channel: NaN (x!=x) → 0, ±Inf → [0,1e7].
@@ -39,20 +40,20 @@ export class ASVGF extends RenderStage {
 
 		this.renderer = renderer;
 
-		this.temporalAlpha = uniform( options.temporalAlpha ?? 0.0 );
-		// > 0 is required for firefly rejection, not just anti-lag — see ENGINE_DEFAULTS.
-		this.gradientStrength = uniform( options.gradientStrength ?? 1.0 );
+		this.temporalAlpha = uniform( options.temporalAlpha ?? ASVGF_QUALITY_PRESETS.medium.temporalAlpha );
+		// > 0 is required for firefly rejection, not just anti-lag — see DENOISER_DEFAULTS.
+		this.gradientStrength = uniform( options.gradientStrength ?? ASVGF_QUALITY_PRESETS.medium.gradientStrength );
 		// σ multiplier for the per-pixel noise floor (NRD luminanceSigmaScale ≈ 2).
-		this.gradientSigmaScale = uniform( options.gradientSigmaScale ?? 2.0 );
+		this.gradientSigmaScale = uniform( options.gradientSigmaScale ?? ASVGF_QUALITY_PRESETS.medium.gradientSigmaScale );
 		// Secondary relative floor on the normalised gradient (0 = rely on σ alone).
-		this.gradientNoiseFloor = uniform( options.gradientNoiseFloor ?? 0.0 );
-		this.maxAccumFrames = uniform( options.maxAccumFrames ?? 32.0 );
+		this.gradientNoiseFloor = uniform( options.gradientNoiseFloor ?? ASVGF_QUALITY_PRESETS.medium.gradientNoiseFloor );
+		this.maxAccumFrames = uniform( options.maxAccumFrames ?? ASVGF_QUALITY_PRESETS.medium.maxAccumFrames );
 
 		this.resW = uniform( options.width || 1 );
 		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 +399,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 +648,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 +719,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 +864,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

@@ -7,6 +7,15 @@ import { RenderStage, StageExecutionMode } from '../Pipeline/RenderStage.js';
 import { luminance } from '../TSL/Common.js';
 
 // ── Histogram constants ────────────────────────────────────
+export const AUTO_EXPOSURE_DEFAULTS = {
+	autoExposure: false,
+	autoExposureKeyValue: 0.18,
+	autoExposureMinExposure: 0.1,
+	autoExposureMaxExposure: 20.0,
+	autoExposureAdaptSpeedBright: 3.0,
+	autoExposureAdaptSpeedDark: 0.5,
+};
+
 const NUM_BINS = 256;
 const MIN_LOG_LUM = - 8.0; // ln(~0.00034)  — very dark
 const MAX_LOG_LUM = 6.0; // ln(~403)     — bright specular
@@ -80,9 +89,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
@@ -104,11 +112,11 @@ export class AutoExposure extends RenderStage {
 
 		// ── Adaptation uniforms ──────────────────────────
 
-		this.keyValueU = uniform( options.keyValue ?? 0.18 );
-		this.minExposureU = uniform( options.minExposure ?? 0.1 );
-		this.maxExposureU = uniform( options.maxExposure ?? 20.0 );
-		this.adaptSpeedBrightU = uniform( options.adaptSpeedBright ?? 3.0 );
-		this.adaptSpeedDarkU = uniform( options.adaptSpeedDark ?? 0.5 );
+		this.keyValueU = uniform( options.keyValue ?? AUTO_EXPOSURE_DEFAULTS.autoExposureKeyValue );
+		this.minExposureU = uniform( options.minExposure ?? AUTO_EXPOSURE_DEFAULTS.autoExposureMinExposure );
+		this.maxExposureU = uniform( options.maxExposure ?? AUTO_EXPOSURE_DEFAULTS.autoExposureMaxExposure );
+		this.adaptSpeedBrightU = uniform( options.adaptSpeedBright ?? AUTO_EXPOSURE_DEFAULTS.autoExposureAdaptSpeedBright );
+		this.adaptSpeedDarkU = uniform( options.adaptSpeedDark ?? AUTO_EXPOSURE_DEFAULTS.autoExposureAdaptSpeedDark );
 		this.epsilonU = uniform( options.epsilon ?? 0.0001 );
 		this.deltaTimeU = uniform( 1.0 / 60.0 );
 		this.isFirstFrameU = uniform( 1.0 ); // 1.0 = true
@@ -471,15 +479,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/BilateralFilter.js

@@ -4,7 +4,8 @@ import { RenderTarget, TextureNode, StorageTexture } from 'three/webgpu';
 import { HalfFloatType, RGBAFormat, LinearFilter, Box2, Vector2 } from 'three';
 import { RenderStage, StageExecutionMode } from '../Pipeline/RenderStage.js';
 import { luminance } from '../TSL/Common.js';
-import { ALBEDO_EPS, MAX_STORAGE_TEXTURE_SIZE } from '../EngineDefaults.js';
+import { MAX_STORAGE_TEXTURE_SIZE } from '../Processor/StorageTexturePool.js';
+import { ALBEDO_EPS } from './DenoiserSettings.js';
 
 // SVGF bilateral edge-stopping weight. All three φ params are relative
 // tolerances (unitless fractions) so the filter is scale-invariant across

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;