rayzee 7.29.0 → 7.30.0

package/package.json

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

package/src/EngineDefaults.js

@@ -224,6 +224,10 @@ export const ENGINE_DEFAULTS = {
 	asvgfQualityPreset: 'medium',
 	showAsvgfHeatmap: false,
 
+	// NRD (ReBLUR port) real-time denoiser — see NRD_DEFAULTS / NRD_QUALITY_PRESETS.
+	nrdQualityPreset: 'medium',
+	nrdDebugMode: 0,
+
 	// Auto-exposure settings
 	autoExposure: false,
 	autoExposureKeyValue: 0.18,
@@ -233,6 +237,16 @@ export const ENGINE_DEFAULTS = {
 	autoExposureAdaptSpeedDark: 0.5,
 };
 
+// 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;
+
+// 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;
+
 // 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.
@@ -307,6 +321,67 @@ export const ASVGF_QUALITY_PRESETS = {
 	}
 };
 
+// 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,
+	},
+};
+
 export const CAMERA_RANGES = {
 	fov: {
 		min: 10,

package/src/PathTracerApp.js

@@ -9,6 +9,7 @@ import { PathTracer } from './Stages/PathTracer.js';
 import { NormalDepth } from './Stages/NormalDepth.js';
 import { MotionVector } from './Stages/MotionVector.js';
 import { ASVGF } from './Stages/ASVGF.js';
+import { NRD } from './Stages/NRD.js';
 import { Variance } from './Stages/Variance.js';
 import { BilateralFilter } from './Stages/BilateralFilter.js';
 import { EdgeFilter } from './Stages/EdgeFilter.js';
@@ -524,7 +525,12 @@ export class PathTracerApp extends EventDispatcher {
 		if ( this.pipeline ) {
 
 			this.pipeline.reset();
-			if ( ! soft ) this.pipeline.eventBus.emit( 'asvgf:reset' );
+			if ( ! soft ) {
+
+				this.pipeline.eventBus.emit( 'asvgf:reset' );
+				this.pipeline.eventBus.emit( 'denoiser:reset' );
+
+			}
 
 		}
 
@@ -2857,6 +2863,7 @@ export class PathTracerApp extends EventDispatcher {
 		this.pipeline.addStage( this.stages.pathTracer );
 		this.pipeline.addStage( this.stages.normalDepth );
 		this.pipeline.addStage( this.stages.motionVector );
+		this.pipeline.addStage( this.stages.nrd );
 		this.pipeline.addStage( this.stages.asvgf );
 		this.pipeline.addStage( this.stages.variance );
 		this.pipeline.addStage( this.stages.bilateralFilter );
@@ -3090,6 +3097,7 @@ export class PathTracerApp extends EventDispatcher {
 			pathTracer: this.stages.pathTracer
 		} );
 		this.stages.asvgf = new ASVGF( this.renderer, { enabled: false } );
+		this.stages.nrd = new NRD( this.renderer, { enabled: false, pathTracer: this.stages.pathTracer } );
 		this.stages.variance = new Variance( this.renderer, { enabled: false } );
 		this.stages.bilateralFilter = new BilateralFilter( this.renderer, { enabled: false } );
 		this.stages.edgeFilter = new EdgeFilter( this.renderer, { enabled: false } );
@@ -3114,6 +3122,7 @@ export class PathTracerApp extends EventDispatcher {
 				normalDepth: this.stages.normalDepth,
 				motionVector: this.stages.motionVector,
 				asvgf: this.stages.asvgf,
+				nrd: this.stages.nrd,
 				variance: this.stages.variance,
 				bilateralFilter: this.stages.bilateralFilter,
 				edgeFilter: this.stages.edgeFilter,

package/src/Processor/PackedRayBuffer.js

@@ -16,9 +16,10 @@ export const RAY_STRIDE = 7;
 export const HIT_STRIDE = 2;
 // Per-pixel G-buffer (first-hit MRT staging): 1 uvec4/pixel — half-packed normal/depth/albedo
 // (pack2x16, no f32 bitcast); read by FinalWrite:
-//   .x=packSnorm2x16(normal.xy)  .y=packSnorm2x16(normal.z, depth)  .z=packUnorm2x16(albedo.rg)  .w=packUnorm2x16(albedo.b, 0)
+//   .x=packSnorm2x16(normal.xy)  .y=packSnorm2x16(normal.z, depth)  .z=packUnorm2x16(albedo.rg)
+//   .w=packUnorm2x16(albedo.b, normHitDist)
+// normHitDist is written by Shade; writeGBuffer preserves it so the DDFA albedo commits can't zero it.
 // Separate buffer from RAY (per-pixel, not per-ray×S) — written by Generate/Shade bounce-0.
-// (A second lane reserved for an A-SVGF Tier-1 surface ID was removed — write-only, never read.)
 export const GBUFFER_STRIDE = 1;
 
 export const RAY = {
@@ -162,15 +163,35 @@ export const readRayRadiance = ( buf, id ) =>
 // One uvec4 per pixel (stride 1); AoS base = pixelIndex * GBUFFER_STRIDE.
 const gbLane = ( pixelIndex ) => uint( pixelIndex ).mul( GBUFFER_STRIDE );
 
-export const writeGBuffer = ( buf, pixelIndex, normal, depth, albedo ) =>
-	buf.element( gbLane( pixelIndex ) ).assign( uvec4(
+// hitDist = null keeps the lane's current normHitDist.
+export const writeGBuffer = ( buf, pixelIndex, normal, depth, albedo, hitDist = null ) => {
+
+	const lane = gbLane( pixelIndex );
+	const h = hitDist === null ? unpackUnorm2x16( buf.element( lane ).w ).y : float( hitDist );
+	return buf.element( lane ).assign( uvec4(
 		packSnorm2x16( vec2( normal.x, normal.y ) ),
 		packSnorm2x16( vec2( normal.z, depth ) ),
 		packUnorm2x16( vec2( albedo.x, albedo.y ) ),
-		packUnorm2x16( vec2( albedo.z, 0.0 ) ),
+		packUnorm2x16( vec2( albedo.z, h ) ),
+	) );
+
+};
+
+export const writeGBufferHitDist = ( buf, pixelIndex, normHitDist ) => {
+
+	const lane = gbLane( pixelIndex );
+	const cur = buf.element( lane ).toVar();
+	return buf.element( lane ).assign( uvec4(
+		cur.x, cur.y, cur.z,
+		packUnorm2x16( vec2( unpackUnorm2x16( cur.w ).x, normHitDist ) ),
 	) );
+
+};
+
 export const readGBuffer = ( buf, pixelIndex ) => buf.element( gbLane( pixelIndex ) );
 
+export const gbDecodeHitDist = ( packed ) => unpackUnorm2x16( packed.w ).y;
+
 // Decode for FinalWrite. normalDepth.xyz matches the prior path (normal*0.5+0.5), .w = raw depth.
 export const gbDecodeNormalDepth = ( packed ) => {
 

package/src/Processor/StorageTexturePool.js

@@ -19,17 +19,21 @@ import { createLogger, fmt } from '../utils/Logger.js';
 
 const log = createLogger( 'gpu' );
 
-function createWriteStorageTex() {
+// Compute-output StorageTexture at the reserved size, never resized (see above). LinearFilter is
+// load-bearing: textureLoad codegen requires it on a StorageTexture.
+export function createStorageTexture( type = FloatType, filter = LinearFilter ) {
 
 	const tex = new StorageTexture( MAX_STORAGE_TEXTURE_SIZE, MAX_STORAGE_TEXTURE_SIZE );
-	tex.type = FloatType;
+	tex.type = type;
 	tex.format = RGBAFormat;
-	tex.minFilter = LinearFilter;
-	tex.magFilter = LinearFilter;
+	tex.minFilter = filter;
+	tex.magFilter = filter;
 	return tex;
 
 }
 
+const createWriteStorageTex = () => createStorageTexture();
+
 export class StorageTexturePool {
 
 	constructor( width, height ) {

package/src/RenderSettings.js

@@ -182,10 +182,10 @@ export class RenderSettings extends EventDispatcher {
 
 				if ( ! isPanorama ) return;
 
-				// ASVGF is driven entirely by MotionVector, which unprojects through
-				// projectionMatrixInverse — meaningless once every pixel is its own direction.
-				// Fall back to the spatial-only denoiser rather than leaving no strategy.
-				if ( denoisingManager?.denoiserStrategy === 'asvgf' ) denoisingManager.setDenoiserStrategy( 'edgeaware' );
+				// 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' );
 				// Auto-focus raycasts via Raycaster.setFromCamera, which only knows the frustum.
 				cameraManager?.setAutoFocusMode( 'manual' );
 

package/src/Stages/Compositor.js

@@ -70,6 +70,7 @@ export class Compositor extends RenderStage {
 			|| context.getTexture( 'edgeFiltering:output' )
 			|| context.getTexture( 'bilateralFiltering:output' )
 			|| context.getTexture( 'asvgf:output' )
+			|| context.getTexture( 'nrd:output' )
 			|| context.getTexture( 'pathtracer:color' );
 
 	}