rayzee 7.28.2 → 7.30.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "rayzee",
-  "version": "7.28.2",
+  "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/SceneProcessor.js

@@ -836,7 +836,7 @@ export class SceneProcessor {
 			// (the prior model-load path omitted this, leaving albedo un-decoded / too bright).
 			const buildBucket = ( list, srgb ) => list.length === 0
 				? Promise.resolve( null )
-				: this.textureCreator.createTexturesToDataTexture( list ).then( tex => {
+				: this.textureCreator.createTexturesToDataTexture( list, { srgbPool: srgb } ).then( tex => {
 
 					if ( tex && srgb ) tex.colorSpace = SRGBColorSpace;
 					return tex;

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/Processor/TextureCreator.js

@@ -1,7 +1,38 @@
-import { DataArrayTexture, RGBAFormat, LinearFilter, UnsignedByteType, SRGBColorSpace, RepeatWrapping } from "three";
+import { DataArrayTexture, RGBAFormat, LinearFilter, UnsignedByteType, SRGBColorSpace, LinearSRGBColorSpace, RepeatWrapping } from "three";
 import { TEXTURE_CONSTANTS, MEMORY_CONSTANTS, DEFAULT_TEXTURE_MATRIX, MATERIAL_DATA_LAYOUT, normalizeAttenuationDistance } from '../EngineDefaults.js';
 import TexturesWorker from './Workers/TexturesWorker.js?worker&inline';
 import { ISSUE_CODES } from '../EngineIssues.js';
+import { linearToSRGB } from './ToneMapCPU.js';
+import { createLogger } from '../utils/Logger.js';
+
+const log = createLogger( 'textures' );
+
+// A bucket array carries ONE colorSpace and the shader reads each slot from a fixed pool, so a
+// texture disagreeing with its pool cannot be re-routed — its pixels are re-encoded instead.
+const TRANSFER_LUT = { toSRGB: null, toLinear: null };
+
+function transferLUT( direction ) {
+
+	if ( ! TRANSFER_LUT[ direction ] ) {
+
+		const lut = new Uint8Array( 256 );
+		for ( let i = 0; i < 256; i ++ ) {
+
+			const c = i / 255;
+			const v = direction === 'toSRGB'
+				? linearToSRGB( c )
+				: ( c <= 0.04045 ? c / 12.92 : Math.pow( ( c + 0.055 ) / 1.055, 2.4 ) );
+			lut[ i ] = Math.max( 0, Math.min( 255, Math.round( v * 255 ) ) );
+
+		}
+
+		TRANSFER_LUT[ direction ] = lut;
+
+	}
+
+	return TRANSFER_LUT[ direction ];
+
+}
 
 // Canvas pooling for efficient reuse of canvas elements
 class CanvasPool {
@@ -541,13 +572,76 @@ export class TextureCreator {
 
 	}
 
+	/**
+	 * Re-encodes any layer whose declared colour space disagrees with its pool, so the GPU's
+	 * decode — or absence of one — lands on the values the author stored. An untagged texture
+	 * keeps its pool's convention, which is what every loader produces for glTF.
+	 *
+	 * @param {import('three').DataArrayTexture} arrayTex
+	 * @param {Array<import('three').Texture>} textures - pre-normalization list, in layer order
+	 * @param {boolean} srgbPool - true when the array is tagged SRGBColorSpace
+	 */
+	_harmonizeTransfer( arrayTex, textures, srgbPool ) {
+
+		const data = arrayTex?.image?.data;
+		if ( ! data ) return;
+
+		// Mirrors _normalizeTexturesForProcessing's skip rule, which is what sets layer order.
+		const kept = textures.filter( t => t?.image );
+		const want = srgbPool ? SRGBColorSpace : LinearSRGBColorSpace;
+		const layerSize = arrayTex.image.width * arrayTex.image.height * 4;
+		const converted = [];
+
+		for ( let layer = 0; layer < kept.length; layer ++ ) {
+
+			const declared = kept[ layer ].colorSpace;
+			// Only an explicit disagreement is acted on; NoColorSpace defers to the pool.
+			if ( declared !== SRGBColorSpace && declared !== LinearSRGBColorSpace ) continue;
+			if ( declared === want ) continue;
+
+			const lut = transferLUT( srgbPool ? 'toSRGB' : 'toLinear' );
+			const start = layer * layerSize;
+			const end = Math.min( start + layerSize, data.length );
+			// RGB only — alpha is never transfer-encoded.
+			for ( let i = start; i < end; i += 4 ) {
+
+				data[ i ] = lut[ data[ i ] ];
+				data[ i + 1 ] = lut[ data[ i + 1 ] ];
+				data[ i + 2 ] = lut[ data[ i + 2 ] ];
+
+			}
+
+			converted.push( kept[ layer ].name || kept[ layer ].source?.uuid?.slice( 0, 8 ) || `layer ${layer}` );
+
+		}
+
+		if ( converted.length === 0 ) return;
+
+		arrayTex.needsUpdate = true;
+		const names = converted.slice( 0, 4 ).join( ', ' ) + ( converted.length > 4 ? `, +${converted.length - 4} more` : '' );
+
+		if ( srgbPool ) {
+
+			log.info( `re-encoded ${converted.length}/${kept.length} linear-declared colour map(s) to sRGB so the GPU decode round-trips: ${names}` );
+
+		} else {
+
+			// Storing a decoded value in an 8-bit linear array is the lossy direction, and a
+			// transfer-encoded data map is almost always an authoring slip rather than intent.
+			log.warn( `decoded ${converted.length}/${kept.length} sRGB-declared data map(s) to linear — precision is lost in the darks, check the asset: ${names}` );
+
+		}
+
+	}
+
 	// Unified texture processing with strategy selection
-	async createTexturesToDataTexture( textures ) {
+	async createTexturesToDataTexture( textures, { srgbPool = false } = {} ) {
 
 		if ( ! textures || textures.length === 0 ) return null;
 
-		// Check cache first
-		const cacheKey = this.textureCache.generateHash( textures );
+		// Pool is part of the identity: the same list packed for the colour pool and the data pool
+		// gets different pixels (see _harmonizeTransfer), so one key must not serve both.
+		const cacheKey = `${srgbPool ? 's' : 'l'}:${this.textureCache.generateHash( textures )}`;
 		const cached = this.textureCache.get( cacheKey );
 		if ( cached ) return cached;
 
@@ -579,6 +673,7 @@ export class TextureCreator {
 			// Cache successful result
 			if ( result ) {
 
+				this._harmonizeTransfer( result, textures, srgbPool );
 				this.textureCache.set( cacheKey, result );
 
 			}
@@ -592,7 +687,9 @@ export class TextureCreator {
 				'worker texture processing failed — retrying on the main thread',
 				{ cause: String( error?.message ?? error ) }
 			);
-			return await this.processOnMainThreadSync( normalized );
+			const fallback = await this.processOnMainThreadSync( normalized );
+			this._harmonizeTransfer( fallback, textures, srgbPool );
+			return fallback;
 
 		} finally {
 

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' );
 
 	}