rayzee 9.5.0 → 11.0.0

package/src/RenderSettings.js

@@ -9,6 +9,7 @@ import { toPortable, fromPortable } from './SceneState/portable.js';
  *
  * - `uniform`  → forwarded to PathTracer.setUniform(uniform, value)
  * - `handler`  → calls a named handler method for multi-stage settings
+ * - neither   → stored only; whoever needs it reads it
  * - `reset`    → whether to reset accumulation after the change (default true)
  *
  * Other layers add their own keys with {@link RenderSettings#define}.
@@ -77,14 +78,16 @@ const SETTING_ROUTES = {
 	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.
  *
@@ -168,19 +166,21 @@ export class RenderSettings extends EventDispatcher {
 
 	/**
 	 * 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.
+	 * 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, { apply, reset = true } ) {
+	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 } );
-		if ( ! this._values.has( key ) && key in this._defaults ) {
+		const value = initial !== undefined ? initial : this._defaults[ key ];
+		if ( ! this._values.has( key ) && value !== undefined ) {
 
-			this._values.set( key, this._defaults[ key ] );
+			this._values.set( key, value );
 			this._sources.set( key, SETTING_SOURCE.DEFAULT );
 
 		}
@@ -289,12 +289,24 @@ export class RenderSettings extends EventDispatcher {
 
 			},
 
+			handleShadowRays: ( value ) => {
+
+				stages.pathTracer?.setShadowRays?.( value );
+
+			},
+
 			handleEnvironmentRotation: ( value ) => {
 
 				stages.pathTracer?.environment.setEnvironmentRotation( value );
 
 			},
 
+			handleWavefrontSortMaterials: ( value ) => {
+
+				if ( stages.pathTracer ) stages.pathTracer.sortMaterials = value;
+
+			},
+
 			handleInteractionModeEnabled: ( value ) => {
 
 				stages.pathTracer?.setInteractionModeEnabled( value );
@@ -503,7 +515,7 @@ export class RenderSettings extends EventDispatcher {
 
 		} else {
 
-			route.apply( value, prev );
+			route.apply?.( value, prev );
 
 		}
 
@@ -511,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 ) {
@@ -527,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,14 +40,14 @@ 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 );

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
@@ -103,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

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/DenoiserSettings.js

@@ -0,0 +1,182 @@
+
+// Ray distance NormalDepth writes on a miss. Max finite half-float, so miss−miss diffs stay 0
+// rather than Inf−Inf=NaN.
+export const GBUFFER_MISS_DEPTH = 65504.0;
+export const GBUFFER_MISS_THRESHOLD = 6e4;
+
+// Albedo demodulation safety floor. ASVGF and BilateralFilter MUST use the
+// same value — demod (`color / safeAlbedo`) and remod (`lighting * safeAlbedo`)
+// only round-trip exactly when both sides agree.
+export const ALBEDO_EPS = 0.01;
+
+export const ASVGF_QUALITY_PRESETS = {
+	// phiColor / phiDepth are RELATIVE tolerances (fractions). Bigger = more
+	// permissive. The adaptive temporal gradient (gradientStrength > 0) is always
+	// on: it measures real change in units of noise σ (gradientSigmaScale), so a
+	// static scene reads ~0 (no convergence penalty) and only moving lights / anim
+	// / disocclusion drop history. See ASVGF._buildGradientCompute.
+	low: {
+		temporalAlpha: 0.1,
+		gradientStrength: 0.8,
+		gradientSigmaScale: 2.5,
+		gradientNoiseFloor: 0.05,
+		atrousIterations: 3,
+		phiColor: 1.0,
+		phiNormal: 64.0,
+		phiDepth: 0.1,
+		phiLuminance: 6.0,
+		maxAccumFrames: 16,
+		varianceBoost: 0.5
+	},
+	medium: {
+		temporalAlpha: 0.03,
+		gradientStrength: 1.0,
+		gradientSigmaScale: 2.5,
+		gradientNoiseFloor: 0.05,
+		atrousIterations: 4,
+		phiColor: 0.5,
+		phiNormal: 128.0,
+		phiDepth: 0.05,
+		phiLuminance: 4.0,
+		maxAccumFrames: 64,
+		varianceBoost: 1.0
+	},
+	high: {
+		temporalAlpha: 0.0,
+		gradientStrength: 1.0,
+		gradientSigmaScale: 2.5,
+		gradientNoiseFloor: 0.05,
+		atrousIterations: 6,
+		phiColor: 0.3,
+		phiNormal: 256.0,
+		phiDepth: 0.02,
+		phiLuminance: 2.0,
+		maxAccumFrames: 128,
+		varianceBoost: 1.5
+	}
+};
+
+// normHitDist = hitDist / (A + B·viewZ). A constant, not a uniform: the Shade write and the NRD
+// decode must agree, and the normalization is a pure round trip.
+export const NRD_HIT_DIST_A = 3.0;
+export const NRD_HIT_DIST_B = 0.1;
+
+// NRD ReBLUR port (Stages/NRD.js). Names follow nrd::ReblurSettings so NVIDIA's tuning notes apply.
+export const NRD_DEFAULTS = {
+	maxAccumulatedFrameNum: 30,
+	maxFastAccumulatedFrameNum: 6,
+	maxStabilizedFrameNum: 63,
+	historyFixFrameNum: 3,
+	historyFixBasePixelStride: 14,
+	prepassBlurRadius: 30,
+	minBlurRadius: 1,
+	maxBlurRadius: 30,
+	lobeAngleFraction: 0.15,
+	roughnessFraction: 0.15,
+	planeDistanceSensitivity: 0.02,
+	minHitDistanceWeight: 0.1,
+	fastHistoryClampingSigmaScale: 2.0,
+	fireflySuppressorMinRelativeScale: 2.0,
+	enableAntiFirefly: true,
+	antilagLuminanceSigmaScale: 2.0,
+	antilagLuminanceSensitivity: 3.0,
+	disocclusionThreshold: 0.01,
+	convergenceS: 1.0,
+	convergenceB: 0.2,
+	convergenceP: 0.8,
+	// Share of the lobe the normal weight accepts before any history exists. NRD's own constant is
+	// 0.75, which its source flags as probably too much; at that width it smears curved surfaces.
+	lobeVolumePercent: 0.1,
+	// Progressive handover: input sample count at which the denoiser passes the render through untouched.
+	// 0 = 2 · maxAccumulatedFrameNum.
+	handoverFrames: 0,
+};
+
+// Keys a preset may override. Applying one resets every key to its default first, so a preset only
+// states its deltas and `medium` can be empty.
+export const NRD_PRESET_KEYS = [
+	'maxAccumulatedFrameNum', 'maxFastAccumulatedFrameNum', 'maxStabilizedFrameNum',
+	'historyFixFrameNum', 'prepassBlurRadius', 'maxBlurRadius', 'enableAntiFirefly',
+];
+
+export const NRD_QUALITY_PRESETS = {
+	// Short history + no pre-pass: most responsive, noisiest.
+	low: {
+		maxAccumulatedFrameNum: 16,
+		maxFastAccumulatedFrameNum: 4,
+		maxStabilizedFrameNum: 16,
+		historyFixFrameNum: 2,
+		prepassBlurRadius: 0,
+		maxBlurRadius: 20,
+		enableAntiFirefly: false,
+	},
+	// nrd::ReblurSettings defaults.
+	medium: {},
+	// Longer history and wider kernels: smoother, more lag on lighting change.
+	high: {
+		maxAccumulatedFrameNum: 45,
+		maxFastAccumulatedFrameNum: 8,
+		historyFixFrameNum: 4,
+		prepassBlurRadius: 40,
+		maxBlurRadius: 40,
+	},
+};
+
+const ASVGF_MEDIUM = ASVGF_QUALITY_PRESETS.medium;
+
+// What the live denoisers, the final OIDN pass and the AI upscaler start with; a host's own state seeds from these.
+export const DENOISER_DEFAULTS = {
+	denoiserStrategy: 'none', // the live view's denoiser: 'none' | 'edgeaware' | 'asvgf' | 'nrd' | 'oidn'
+
+	// EdgeAware denoiser (spatial-only SVGF à-trous). filterStrength: final blend
+	// (0 = raw, 1 = filtered). edgeAtrousIterations: à-trous passes (step 1,2,4,8,16).
+	// edgePhiLuminance: variance-scaled luminance edge-stop. edgePhiNormal: normal cone
+	// exponent. edgePhiDepth: RELATIVE depth tolerance (fraction of ray distance).
+	filterStrength: 1.0,
+	edgeAtrousIterations: 5,
+	edgePhiLuminance: 4.0,
+	edgePhiNormal: 64.0,
+	edgePhiDepth: 0.1,
+
+	enableOIDN: false,
+	oidnQuality: 'fast',
+	// OIDN as the live-view denoiser, refreshing the accumulating image. Set by choosing 'oidn' in
+	// the real-time denoiser list, so that only ever one thing denoises the live view — not by
+	// `enableOIDN`, which is the separate question of whether the finished image gets a pass.
+	continuousDenoise: false,
+	// Lower bound on the gap between cadence denoises. DenoisingManager also floors that gap at a
+	// multiple of what the last denoise actually cost, and above ~1024² that is what binds — this
+	// value only governs where a denoise is cheap. 8 ms measured 31 refreshes/sec at 512² at an
+	// unchanged sample rate; 50 ms measured 18/sec for nothing in return.
+	continuousDenoiseInterval: 8,
+	// While the view moves, feed OIDN the reprojected history of restarted frames, not one sample.
+	oidnTemporalHistory: true,
+
+	enableUpscaler: false,
+	upscalerScale: 2,
+	upscalerQuality: 'fast',
+	upscalerHdr: true,
+
+	// ASVGF runs its quality preset whenever it is switched on, so its values are that preset's.
+	enableASVGF: false,
+	asvgfQualityPreset: 'medium',
+	asvgfTemporalAlpha: ASVGF_MEDIUM.temporalAlpha,
+	asvgfAtrousIterations: ASVGF_MEDIUM.atrousIterations,
+	asvgfPhiColor: ASVGF_MEDIUM.phiColor,
+	asvgfPhiNormal: ASVGF_MEDIUM.phiNormal,
+	asvgfPhiDepth: ASVGF_MEDIUM.phiDepth,
+	asvgfPhiLuminance: ASVGF_MEDIUM.phiLuminance,
+	asvgfVarianceBoost: ASVGF_MEDIUM.varianceBoost,
+	asvgfMaxAccumFrames: ASVGF_MEDIUM.maxAccumFrames,
+	// Must be > 0: the gradient also rejects fireflies before the EMA smears them across
+	// ~1/alpha frames. At 0 the denoiser measures ~3x worse than no denoiser at 1 spp.
+	asvgfGradientStrength: ASVGF_MEDIUM.gradientStrength,
+	asvgfGradientSigmaScale: ASVGF_MEDIUM.gradientSigmaScale,
+	asvgfGradientNoiseFloor: ASVGF_MEDIUM.gradientNoiseFloor,
+	asvgfDebugMode: 0,
+	showAsvgfHeatmap: false,
+
+	// NRD (ReBLUR port) real-time denoiser — see NRD_DEFAULTS / NRD_QUALITY_PRESETS.
+	nrdQualityPreset: 'medium',
+	nrdDebugMode: 0,
+};

package/src/Stages/EdgeFilter.js

@@ -5,7 +5,8 @@ import { RenderTarget, TextureNode, StorageTexture } from 'three/webgpu';
 import { FloatType, 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';
 
 // NormalDepth writes depth ≈ 65504 for miss (env/background) rays. This sits below
 // the sentinel and above any real ray distance, so it's a clean hit/miss flag.

package/src/Stages/MotionVector.js

@@ -3,7 +3,7 @@ import { Fn, vec2, vec3, vec4, float, int, uint, ivec2, uvec2, uniform, If,
 import { RenderTarget, TextureNode, StorageTexture } from 'three/webgpu';
 import { HalfFloatType, RGBAFormat, NearestFilter, Matrix4, Box2, Vector2 } from 'three';
 import { RenderStage, StageExecutionMode } from '../Pipeline/RenderStage.js';
-import { MAX_STORAGE_TEXTURE_SIZE } from '../EngineDefaults.js';
+import { MAX_STORAGE_TEXTURE_SIZE } from '../Processor/StorageTexturePool.js';
 import { cameraRayPoint, cameraRayUniforms } from '../TSL/CameraRay.js';
 
 /**

package/src/Stages/NRD.js

@@ -8,9 +8,8 @@ import { createStorageTexture } from '../Processor/StorageTexturePool.js';
 import { sanitizeRGB, sanitize1, FP16_MAX } from '../TSL/Common.js';
 import { cameraRayPoint, cameraRayUniforms, isOrthographic } from '../TSL/CameraRay.js';
 import {
-	ALBEDO_EPS, GBUFFER_MISS_THRESHOLD as MISS_THRESHOLD, NRD_DEFAULTS,
-	NRD_HIT_DIST_A, NRD_HIT_DIST_B,
-} from '../EngineDefaults.js';
+	NRD_DEFAULTS, NRD_HIT_DIST_A, NRD_HIT_DIST_B, ALBEDO_EPS, GBUFFER_MISS_THRESHOLD as MISS_THRESHOLD,
+} from './DenoiserSettings.js';
 
 const NRD_EPS = 1e-6;
 const NORMAL_ENCODING_ERROR = 1.5 / 255.0;

package/src/Stages/NormalDepth.js

@@ -3,7 +3,8 @@ import { Fn, vec2, vec4, float, int, uint, uvec2, uvec4, uniform, min, storage,
 import { RenderTarget, StorageTexture } from 'three/webgpu';
 import { HalfFloatType, RGBAFormat, RedIntegerFormat, UnsignedIntType, NearestFilter, Matrix4, Box2, Vector2 } from 'three';
 import { RenderStage, StageExecutionMode } from '../Pipeline/RenderStage.js';
-import { MAX_STORAGE_TEXTURE_SIZE } from '../EngineDefaults.js';
+import { MAX_STORAGE_TEXTURE_SIZE } from '../Processor/StorageTexturePool.js';
+import { GBUFFER_MISS_DEPTH } from './DenoiserSettings.js';
 import { Ray, HitInfo, RayTracingMaterial, UVCache } from '../TSL/Struct.js';
 import { traverseBVH } from '../TSL/BVHTraversal.js';
 import { cameraRayOf, cameraRayUniforms } from '../TSL/CameraRay.js';
@@ -248,7 +249,7 @@ export class NormalDepth extends RenderStage {
 
 				const result = hit.didHit.select(
 					vec4( encodedNormal, depth ),
-					vec4( 0.0, 0.0, 0.0, float( 65504.0 ) )
+					vec4( 0.0, 0.0, 0.0, float( GBUFFER_MISS_DEPTH ) )
 				);
 
 				textureStore(

package/src/Stages/PathTracer.js

@@ -16,6 +16,7 @@ import { KernelManager } from '../Processor/KernelManager.js';
 import { buildGenerateKernel, GENERATE_WG_SIZE } from '../TSL/GenerateKernel.js';
 import { buildExtendKernel, EXTEND_WG_SIZE } from '../TSL/ExtendKernel.js';
 import { buildShadeKernel, SHADE_WG_SIZE } from '../TSL/ShadeKernel.js';
+import { buildVisibilityFoldKernel, buildVisibilityClearKernel } from '../TSL/LightVisibility.js';
 import { buildCompactKernel, buildCompactSubgroupKernel, COMPACT_WG_SIZE } from '../TSL/CompactKernel.js';
 import { buildFinalWriteKernel, FINALWRITE_WG_SIZE } from '../TSL/FinalWriteKernel.js';
 import { buildDebugKernel, DEBUG_WG_SIZE } from '../TSL/DebugKernel.js';
@@ -25,7 +26,8 @@ import {
 	buildResetGlobalHistKernel, buildGlobalHistKernel, buildGlobalPrefixKernel, buildGlobalScatterKernel,
 	SORT_GLOBAL_WG_SIZE, SORT_GLOBAL_MAX_BINS,
 } from '../TSL/SortGlobalKernels.js';
-import { ENGINE_DEFAULTS, MAX_STORAGE_TEXTURE_SIZE } from '../EngineDefaults.js';
+import { ENGINE_DEFAULTS } from '../EngineDefaults.js';
+import { MAX_STORAGE_TEXTURE_SIZE } from '../Processor/StorageTexturePool.js';
 import { ISSUE_CODES } from '../EngineIssues.js';
 import { createLogger, fmt } from '../utils/Logger.js';
 import { deviceMemoryGB } from '../Processor/HostMemory.js';
@@ -40,6 +42,9 @@ export const LIST_WG_SIZE = 256;
 
 // Resized per bounce iteration, each from its own registered workgroup size. Unregistered entries
 // (the sort passes when _sortMaterials is off) are skipped by setDispatchForCount.
+const PICKED_SHADOW_RAYS = [ 'two', 'one' ];
+const SHADOW_RAY_MODES = [ 'all', ...PICKED_SHADOW_RAYS ];
+
 export const BOUNCE_KERNELS = [ 'extend', 'shade', 'connect', 'merge', 'globalHist', 'globalScatter', 'compact', 'compactCopyback', 'lightCopyback' ];
 
 export class PathTracer extends PathTracerStage {
@@ -83,9 +88,10 @@ export class PathTracer extends PathTracerStage {
 		// CPU sizes per-bounce kernels from last frame's survivor curve; kernels bound on ENTERING_COUNT so over-sizing is safe. (indirect dispatch not viable — three.js doesn't sync compute-written indirect buffers across submissions)
 		this._useDynamicDispatch = true;
 
-		// Global material-coherence sort: set per-build from ENGINE_DEFAULTS + material count (>8).
+		// Global material-coherence sort: the wavefrontSortMaterials setting, applied per build above 8 materials.
 		// Reorders entering rays into material-pure workgroups before Shade; runs under dynamic dispatch
 		// (compact reads the unsorted active list, so the survivor set is unchanged). Measured −8% at 1024²/8b.
+		this.sortMaterials = options.sortMaterials ?? ENGINE_DEFAULTS.wavefrontSortMaterials;
 		this._sortMaterials = false;
 
 		// Flag-gated off: perf-neutral vs atomic-append and adds a 'subgroups' feature dependency.
@@ -153,6 +159,9 @@ export class PathTracer extends PathTracerStage {
 		this._outputsChanged = false;
 		// The material layers the kernels were compiled with (_layersToCompile).
 		this._compiledLayers = null;
+		this._shadowRays = 'all';
+		this._compiledPick = null;
+		this._learnsVisibility = false;
 
 		// Integrators other than the path tracer's own, by name (registerIntegrator); the chosen one's instance, or
 		// null for plain path tracing, which builds exactly the unidirectional kernels.
@@ -333,6 +342,44 @@ export class PathTracer extends PathTracerStage {
 
 	}
 
+	/**
+	 * Shadow rays a hit for the lamps, sky, sun and emitters: 'all', one per kind; 'two', the strongest and one picked
+	 * from the rest; 'one', one picked, by unshadowed light and where each kind gets through. Rebuilds the kernels
+	 * before the next frame; bidirectional integrators ignore it.
+	 * @param {'all'|'two'|'one'} mode
+	 */
+	setShadowRays( mode ) {
+
+		if ( ! SHADOW_RAY_MODES.includes( mode ) ) {
+
+			log.warn( `shadowRays: unknown mode "${mode}", using 'all'` );
+			mode = 'all';
+
+		}
+
+		if ( this._shadowRays === mode ) return;
+		this._shadowRays = mode;
+		this._outputsChanged = true;
+
+	}
+
+	/**
+	 * The lightPick variant to compile, or null for a ray per light kind: also when the scene has no more kinds than the
+	 * variant traces rays, where it would only add its bookkeeping.
+	 */
+	_pickedShadowRays() {
+
+		if ( this._integrator || ! PICKED_SHADOW_RAYS.includes( this._shadowRays ) ) return null;
+		const environment = this.enableEnvironment.value > 0;
+		const lamps = this.numDirectionalLights.value + this.numAreaLights.value + this.numPointLights.value + this.numSpotLights.value;
+		const kinds = Number( lamps > 0 )
+			+ Number( environment && this.envTotalSum.value > 0 )
+			+ Number( environment && this.hasSun.value > 0 )
+			+ Number( this.enableEmissiveTriangleSampling.value > 0 && this.emissiveTriangleCount.value > 0 );
+		return kinds > ( this._shadowRays === 'two' ? 2 : 1 ) ? this._shadowRays : null;
+
+	}
+
 	get integrator() {
 
 		return this._integrator?.name ?? 'path';
@@ -362,6 +409,8 @@ export class PathTracer extends PathTracerStage {
 
 		}
 
+		if ( PICKED_SHADOW_RAYS.includes( this._shadowRays ) && this._pickedShadowRays() !== this._compiledPick ) this._outputsChanged = true;
+
 		if ( this._lightBufferRealloc || this._outputsChanged ) {
 
 			if ( this._kernelManager ) this._kernelManager.dispose();
@@ -511,6 +560,12 @@ export class PathTracer extends PathTracerStage {
 
 		// An integrator's light subpaths first, through the same pool; every camera chunk then connects to them.
 		const integrator = this._integrator?.beginFrame( loopBound ) ? this._integrator : null;
+		// A camera move keeps what was learned (it is kept per place in the scene); a repeatable render starts afresh.
+		if ( this._learnsVisibility && frameValue === 0 && ( this._pinSeedToFrame || this._lockstep || ! this.cameraChanged ) ) {
+
+			km.dispatch( 'visibilityClear' );
+
+		}
 
 		// Blender-style row-band streaming: the fixed-budget path pool processes the image in bands of ≤ chunkRows
 		// rows (one chunk when the frame fits the budget → identical to the pre-chunking path). See spec.
@@ -650,6 +705,7 @@ export class PathTracer extends PathTracerStage {
 
 		}
 
+		if ( this._learnsVisibility ) km.dispatch( 'visibilityFold' );
 		this._maybeReadbackCounters();
 
 		// Skip the normalDepth/albedo copies when aux is off — the wavefront didn't write them and
@@ -1510,6 +1566,11 @@ export class PathTracer extends PathTracerStage {
 		const prevNormalDepth = this.shaderBuilder.prevNormalDepthTexNode;
 		const writeTex = this.storageTextures.getWriteTextures();
 
+		const picked = this._pickedShadowRays();
+		this._compiledPick = picked;
+		const learnsVisibility = picked !== null;
+		this._learnsVisibility = learnsVisibility;
+		qm.setVisibilityTable( learnsVisibility );
 		const counters = qm.getCounters();
 
 		// Copy ACTIVE_RAY_COUNT into bounceCounts[currentBounce] for the readback survivor curve.
@@ -1813,8 +1874,7 @@ export class PathTracer extends PathTracerStage {
 		};
 
 		// Material-coherence sort gate (experiment): only worthwhile above a few materials.
-		this._sortMaterials = ( ENGINE_DEFAULTS.wavefrontSortMaterials ?? false )
-			&& ( this.materialData?.materialCount ?? 0 ) > 8;
+		this._sortMaterials = this.sortMaterials && ( this.materialData?.materialCount ?? 0 ) > 8;
 
 		const extFn = buildExtendKernel( {
 			bvhBuffer: freshBvh,
@@ -1945,6 +2005,8 @@ export class PathTracer extends PathTracerStage {
 			bidirectional: this._integrator?.uniforms ?? null,
 			hitDistanceEncode: this._outputs.get( 'hitDistance' )?.encode ?? null,
 			materialLayers: this._compiledLayers,
+			shadowRays: picked,
+			cameraWorldMatrix: this.cameraWorldMatrix,
 		} );
 		this._kernelManager.register( 'shade',
 			own( shadeFn() ).compute(
@@ -1952,6 +2014,12 @@ export class PathTracer extends PathTracerStage {
 				[ SHADE_WG_SIZE, 1, 1 ]
 			)
 		);
+		if ( learnsVisibility ) {
+
+			this._kernelManager.register( 'visibilityClear', buildVisibilityClearKernel( { counters } ) );
+			this._kernelManager.register( 'visibilityFold', buildVisibilityFoldKernel( { counters } ) );
+
+		}
 
 		// Subgroup prefix-sum variant when supported.
 		const subgroupsOK = this._useSubgroupCompact

package/src/Stages/PathTracerStage.js

@@ -20,7 +20,8 @@ import { SceneProcessor } from '../Processor/SceneProcessor.js';
 import { LightSerializer } from '../Processor/LightSerializer';
 
 // Constants
-import { ENGINE_DEFAULTS as DEFAULT_STATE, TRIANGLE_DATA_LAYOUT } from '../EngineDefaults.js';
+import { ENGINE_DEFAULTS as DEFAULT_STATE } from '../EngineDefaults.js';
+import { TRIANGLE_DATA_LAYOUT } from '../Processor/BufferLayout.js';
 import { TRI_GEO_ROWS, TRI_SHADE_ROWS } from '../TSL/Common.js';
 import { createLogger, fmt } from '../utils/Logger.js';
 

package/src/Stages/Variance.js

@@ -4,7 +4,7 @@ import { RenderTarget, TextureNode, StorageTexture } from 'three/webgpu';
 import { FloatType, RGBAFormat, LinearFilter, Box2, Vector2 } from 'three';
 import { RenderStage, StageExecutionMode } from '../Pipeline/RenderStage.js';
 import { luminance } from '../TSL/Common.js';
-import { MAX_STORAGE_TEXTURE_SIZE } from '../EngineDefaults.js';
+import { MAX_STORAGE_TEXTURE_SIZE } from '../Processor/StorageTexturePool.js';
 
 // NaN/±Inf guard: a poisoned luminance would otherwise corrupt the moment EMA forever
 // (mean/meanSq → variance → BilateralFilter sigmaL). NaN (x!=x) → 0, ±Inf → [0,1e7].

package/src/TSL/BVHTraversal.js

@@ -25,7 +25,10 @@ import {
 	bool as tslBool,
 } from 'three/tsl';
 
-import { BVH_LEAF_MARKERS, BVH_MAX_INDEX, BVH_FOLDED_LEAF_MAX, TRI_MATERIAL_MASK, TRI_SIDE_SHIFT, TLAS_LEAF_IDENTITY } from '../EngineDefaults.js';
+import {
+	TRI_MATERIAL_MASK, TRI_SIDE_SHIFT, BVH_LEAF_MARKERS, BVH_MAX_INDEX, BVH_FOLDED_LEAF_MAX,
+	TLAS_LEAF_IDENTITY,
+} from '../Processor/BufferLayout.js';
 import { HitInfo } from './Struct.js';
 import {
 	getDatafromStorageBuffer, instanceRows, instanceNormalToWorld, unpackTriangleNormal, triangleRow, shadowFlagsSettle

package/src/TSL/Common.js

@@ -39,7 +39,7 @@ export const FP16_MAX = 65504.0;
 export const sanitize1 = ( x, ceiling = 1e7 ) => select( x.equal( x ), x, float( 0.0 ) ).clamp( 0.0, ceiling );
 export const sanitizeRGB = ( c, ceiling = 1e7 ) =>
 	vec3( sanitize1( c.x, ceiling ), sanitize1( c.y, ceiling ), sanitize1( c.z, ceiling ) );
-import { MATERIAL_DATA_LAYOUT, TRI_BLOCKER_SHIFT, TRI_BLOCKER_ALPHA_SHIFT } from '../EngineDefaults.js';
+import { TRI_BLOCKER_SHIFT, TRI_BLOCKER_ALPHA_SHIFT, MATERIAL_DATA_LAYOUT } from '../Processor/BufferLayout.js';
 
 export const MATERIAL_SLOTS = MATERIAL_DATA_LAYOUT.SLOTS_PER_MATERIAL;
 export const MATERIAL_SLOT = MATERIAL_DATA_LAYOUT.SLOT;

package/src/TSL/EmissiveSampling.js

@@ -32,7 +32,7 @@ import {
 	computeDotProductsAniso, instanceRows, instanceNormalToWorld, instancePointToWorld,
 	unpackTriangleNormal, triangleRow, SHADOW_END
 } from './Common.js';
-import { TRI_MATERIAL_MASK } from '../EngineDefaults.js';
+import { TRI_MATERIAL_MASK } from '../Processor/BufferLayout.js';
 import { getRandomSample1D, getRandomSample2D } from './Random.js';
 import { calculateMaterialPDFFromDots } from './LightsSampling.js';
 import { evaluateMaterialResponseFromDots, evaluateDiffuseTransmission } from './MaterialEvaluation.js';