rayzee 10.0.0 → 11.1.0

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;
@@ -133,7 +132,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 +147,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 +1189,7 @@ export class NRD extends RenderStage {
 
 	setupEventListeners() {
 
-		this.on( 'denoiser:reset', () => this.resetHistory() );
+		this.on( 'pipeline:historyReset', () => this.resetHistory() );
 
 	}
 
@@ -1383,6 +1387,8 @@ export class NRD extends RenderStage {
 
 	dispose() {
 
+		this._releaseHitDistance?.();
+		this._releaseHitDistance = null;
 		this._disposeKernels();
 		this._disposeStorage();
 		this.outputTarget?.dispose();

package/src/Stages/NormalDepth.js

@@ -3,12 +3,14 @@ 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';
 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 +209,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;
@@ -245,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(
@@ -308,7 +312,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 ]
 		);