rayzee 7.29.0 → 7.30.1

package/src/Stages/NormalDepth.js

@@ -8,7 +8,7 @@ import { Ray, HitInfo, RayTracingMaterial, UVCache } from '../TSL/Struct.js';
 import { traverseBVH } from '../TSL/BVHTraversal.js';
 import { cameraRayDirection } from '../TSL/CameraRay.js';
 import { getMaterial } from '../TSL/Common.js';
-import { computeUVCache, processNormal, processBump, triangleUVTangent, buildBucketTextureNodes, refreshBucketTextureNodes, setMaterialBucketTextures } from '../TSL/TextureSampling.js';
+import { computeUVCache, processNormal, processBump, processMetalnessRoughness, triangleUVTangent, buildBucketTextureNodes, refreshBucketTextureNodes, setMaterialBucketTextures } from '../TSL/TextureSampling.js';
 
 /**
  * NormalDepth — primary-ray G-buffer for SVGF gates.
@@ -29,9 +29,10 @@ import { computeUVCache, processNormal, processBump, triangleUVTangent, buildBuc
  * map, recomputed from the SAME deterministic hit — no extra ray) so the
  * spatial denoiser's edge-stop can see normal-map detail the flat geometric
  * normal hides. Deterministic ⇒ jitter-free, so it's safe for the gates.
+ * Its .w is the sampled material roughness (NRD's normal+roughness guide).
  *
  * Publishes: pathtracer:normalDepth, pathtracer:prevNormalDepth,
- *            pathtracer:shadingNormal
+ *            pathtracer:shadingNormal (rgb = shading normal·0.5+0.5, a = roughness)
  */
 export class NormalDepth extends RenderStage {
 
@@ -257,6 +258,7 @@ export class NormalDepth extends RenderStage {
 				// Shading normal: perturb the geometric normal by the normal/bump map
 				// from the SAME hit (deterministic UV → jitter-free). Miss → geo default.
 				const shadingNormal = hit.normal.toVar();
+				const roughness = float( 1.0 ).toVar();
 				If( hit.didHit, () => {
 
 					const material = RayTracingMaterial.wrap(
@@ -274,12 +276,14 @@ export class NormalDepth extends RenderStage {
 
 					const mapped = processNormal( hit.normal, material, uvCache, uvTangent ).toVar();
 					shadingNormal.assign( processBump( mapped, material, uvCache ) );
+					// Same floor the Shade kernel applies before shading.
+					roughness.assign( processMetalnessRoughness( material, uvCache ).y.clamp( 0.05, 1.0 ) );
 
 				} );
 
 				const shadingResult = hit.didHit.select(
-					vec4( shadingNormal.mul( 0.5 ).add( 0.5 ), depth ),
-					vec4( 0.0, 0.0, 0.0, float( 65504.0 ) )
+					vec4( shadingNormal.mul( 0.5 ).add( 0.5 ), roughness ),
+					vec4( 0.0, 0.0, 0.0, 1.0 )
 				);
 
 				textureStore(

package/src/Stages/PathTracerStage.js

@@ -1157,6 +1157,9 @@ export class PathTracerStage extends RenderStage {
 		context.setTexture( 'pathtracer:normalDepth', writeTex.normalDepth );
 		context.setTexture( 'pathtracer:albedo', writeTex.albedo );
 
+		// Not the same as the context's own `accumulatedFrames`, which counts pipeline renders — this
+		// freezes when the frame retires or the camera moves, which is what a denoiser needs.
+		context.setState( 'pathtracer:samples', this.frameCount );
 		context.setState( 'interactionMode', this.cameraOptimizer?.isInInteractionMode() ?? false );
 		context.setState( 'renderMode', this.renderMode.value );
 
@@ -1224,6 +1227,7 @@ export class PathTracerStage extends RenderStage {
 					// touched here — it is owned by ASVGF_QUALITY_PRESETS, and overwriting it
 					// with a hardcoded value meant `medium` and `high` never took effect.
 					this.emit( 'asvgf:reset' );
+					this.emit( 'denoiser:reset' );
 
 				}
 

package/src/TSL/Common.js

@@ -1,4 +1,4 @@
-import { Fn, wgslFn, float, vec2, vec3, vec4, int, mat3, If, max, dot, clamp } from 'three/tsl';
+import { Fn, wgslFn, float, vec2, vec3, vec4, int, mat3, If, max, dot, clamp, select } from 'three/tsl';
 
 import {
 	AnisoFrame,
@@ -17,6 +17,13 @@ export const MIN_CLEARCOAT_ROUGHNESS = 0.089;
 export const MAX_ROUGHNESS = 1.0;
 export const MIN_PDF = 0.001;
 export const REC709_LUMINANCE_COEFFICIENTS = vec3( 0.2126, 0.7152, 0.0722 );
+
+export const FP16_MAX = 65504.0;
+
+// NaN/±Inf guard: mix() propagates NaN, so one firefly would poison a temporal history forever.
+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 } from '../EngineDefaults.js';
 
 export const MATERIAL_SLOTS = MATERIAL_DATA_LAYOUT.SLOTS_PER_MATERIAL;

package/src/TSL/FinalWriteKernel.js

@@ -14,7 +14,7 @@ import {
 } from 'three/tsl';
 
 import {
-	readRayRadiance, readGBuffer, gbDecodeNormalDepth, gbDecodeAlbedo,
+	readRayRadiance, readGBuffer, gbDecodeNormalDepth, gbDecodeAlbedo, gbDecodeHitDist,
 } from '../Processor/PackedRayBuffer.js';
 import { luminance } from './Common.js';
 
@@ -96,11 +96,14 @@ export function buildFinalWriteKernel( params ) {
 			// auxOn gates the decode + stores so a no-denoiser frame does no G-buffer read and no aux writes.
 			const finalNormalDepth = vec4( 0.0 ).toVar();
 			const finalAlbedo = vec4( 0.0 ).xyz.toVar();
+			// Albedo .w carries the hit distance — OIDN reads albedo as 3 channels, so it is free.
+			const finalHitDist = float( 0.0 ).toVar();
 			If( auxOn, () => {
 
 				const gbuf = readGBuffer( gBufferRO, rayID );
 				finalNormalDepth.assign( gbDecodeNormalDepth( gbuf ) );
 				finalAlbedo.assign( vec4( gbDecodeAlbedo( gbuf ), 0.0 ).xyz );
+				finalHitDist.assign( gbDecodeHitDist( gbuf ) );
 
 			} );
 
@@ -117,8 +120,10 @@ export function buildFinalWriteKernel( params ) {
 				finalColor.assign( select( wasFrozen, prevAccumSample.xyz, mix( prevAccumSample.xyz, sampleColor.xyz, accumulationAlpha ) ) );
 				If( auxOn.and( hasPreviousAux ), () => {
 
-					// Albedo averages cleanly (it's a colour).
-					finalAlbedo.assign( mix( texture( prevAlbedoTexture, prevUV, 0 ).xyz, finalAlbedo, auxAccumulationAlpha ) );
+					// Albedo averages cleanly (it's a colour); so does the normalized hit distance in .w.
+					const prevAlbedoSample = texture( prevAlbedoTexture, prevUV, 0 ).toVar();
+					finalAlbedo.assign( mix( prevAlbedoSample.xyz, finalAlbedo, auxAccumulationAlpha ) );
+					finalHitDist.assign( mix( prevAlbedoSample.w, finalHitDist, auxAccumulationAlpha ) );
 
 					// NORMAL: by default keep this frame's POINT-SAMPLED normal — it varies with the bump,
 					// which fast/ASVGF want to preserve edge detail. But a CLEAN-AUX OIDN model (calb_cnrm/high,
@@ -251,7 +256,7 @@ export function buildFinalWriteKernel( params ) {
 			If( auxOn, () => {
 
 				textureStore( writeNDTex, uintCoord, finalNormalDepth ).toWriteOnly();
-				textureStore( writeAlbedoTex, uintCoord, vec4( finalAlbedo, 1.0 ) ).toWriteOnly();
+				textureStore( writeAlbedoTex, uintCoord, vec4( finalAlbedo, finalHitDist ) ).toWriteOnly();
 
 			} );
 

package/src/TSL/GenerateKernel.js

@@ -96,7 +96,7 @@ export function buildGenerateKernel( params ) {
 		If( auxOn, () => {
 
 			// default: normal +Z, depth 1 (far), black albedo (background/miss). Per-CHUNK G-buffer → LOCAL slot.
-			writeGBuffer( gBufferRW, rayID, vec3( 0.0, 0.0, 1.0 ), float( 1.0 ), vec3( 0.0 ) );
+			writeGBuffer( gBufferRW, rayID, vec3( 0.0, 0.0, 1.0 ), float( 1.0 ), vec3( 0.0 ), float( 0.0 ) );
 			// DDFA: seed the see-through aux tint to white (no tint yet). RMW preserves slot-5 xyz (sigmaA).
 			writeFeatureThroughput( rayBufferRW, rayID, vec3( 1.0 ) );
 

package/src/TSL/ShadeKernel.js

@@ -7,7 +7,7 @@
 import {
 	Fn, float, vec2, vec3, vec4, int, uint,
 	bool as tslBool,
-	If, Loop, normalize, max, exp, log, clamp, dot, length, select, smoothstep, mix,
+	If, Loop, normalize, max, min, exp, log, clamp, dot, length, select, smoothstep, mix,
 	instanceIndex,
 	sampler,
 	atomicAdd, atomicLoad, atomicStore, uintBitsToFloat,
@@ -29,6 +29,7 @@ import { IndirectLightingResult, sampleCone } from './LightsCore.js';
 import { regularizePathContribution, generateSampledDirection, computeNDCDepth, handleRussianRoulette } from './PathTracerCore.js';
 import { evaluateDFG } from './MaterialProperties.js';
 import { dielectricF0 } from './Fresnel.js';
+import { NRD_HIT_DIST_A, NRD_HIT_DIST_B } from '../EngineDefaults.js';
 import { sampleClearcoat, ClearcoatResult } from './Clearcoat.js';
 import { refineDisplacedIntersection, DisplacementResult } from './Displacement.js';
 import { calculateEmissiveTriangleContribution, calculateEmissiveLightPdf, EmissiveSample } from './EmissiveSampling.js';
@@ -57,7 +58,7 @@ import {
 	readHitDistance, readHitBarycentrics, readHitNormal,
 	readHitMaterialIndex, readHitTriangleIndex,
 	writeRayOriginMeta, writeRayDirFlags, writeRayThroughputPdf, writeRayRadiance,
-	writeGBuffer, readGBuffer, gbDecodeNormalDepth,
+	writeGBuffer, writeGBufferHitDist, readGBuffer, gbDecodeNormalDepth,
 	readRayRadiance,
 	readFeatureThroughput, writeFeatureThroughput,
 } from '../Processor/PackedRayBuffer.js';
@@ -226,6 +227,17 @@ export function buildShadeKernel( params ) {
 		const sssSteps = readSssSteps( rayBufferRW, rayID ).toVar();
 		const transparentCount = readTransparentCount( rayBufferRW, rayID ).toVar();
 
+		// NRD guide: first segment after the primary scatter, plus any alpha-skip run so a cutout hole
+		// doesn't shorten it. Unconditional at depth 1, so the post-skip segment wins.
+		If( auxOn.and( cameraDepth.equal( 1 ) ), () => {
+
+			const scatterViewZ = cameraViewMatrix.mul( vec4( origin, 1.0 ) ).z.abs();
+			const norm = scatterViewZ.mul( NRD_HIT_DIST_B ).add( NRD_HIT_DIST_A );
+			const total = readMisRayT( rayBufferRW, rayID ).add( min( hitDist, float( 1e6 ) ) );
+			writeGBufferHitDist( gBufferRW, pixelIndex, total.div( max( norm, float( 1e-4 ) ) ).clamp( 0.0, 1.0 ) );
+
+		} );
+
 		// ── Analytic ground-plane shadow catcher (primary ray only, no geometry) ──
 		// A horizontal plane at y = groundCatcherHeight. For a bounce-0 ray that crosses it
 		// closer than any BVH hit (hitDist is MISS_DIST on sky rays, so the plane wins over the

package/src/TSL/TextureSampling.js

@@ -10,11 +10,12 @@ import { getDatafromStorageBuffer } from './Common.js';
 import { TEXTURE_CONSTANTS } from '../EngineDefaults.js';
 
 // ================================================================================
-// CONSOLIDATED SIZE-BUCKETED MATERIAL TEXTURES
+// CONSOLIDATED SHAPE-BUCKETED MATERIAL TEXTURES
 // ================================================================================
 // Material maps are packed into two colorSpace pools (sRGB: albedo+emissive; linear:
 // normal/bump/roughness/metalness/displacement), each split into MATERIAL_BUCKET_COUNT
-// longest-edge size buckets so a small map no longer pays a large neighbour's footprint.
+// (width, height) buckets so a small or oddly-shaped map no longer pays a large neighbour's
+// footprint. Bucket shapes are planned per scene (planTextureBuckets) — not powers of two.
 // A map's stored index encodes (bucket, layer) as bucket * BUCKET_LAYER_STRIDE + layer.
 //
 // The bucket texture nodes live at module level (same pattern as gobo/IES/shadowAlbedo):

package/src/index.js

@@ -39,6 +39,11 @@ export { Logger, createLogger, fmt, LOG_LEVELS } from './utils/Logger.js';
 export {
 	ENGINE_DEFAULTS,
 	ASVGF_QUALITY_PRESETS,
+	NRD_DEFAULTS,
+	NRD_QUALITY_PRESETS,
+	NRD_PRESET_KEYS,
+	NRD_HIT_DIST_A,
+	NRD_HIT_DIST_B,
 	CAMERA_PRESETS,
 	CAMERA_RANGES,
 	SKY_PRESETS,

package/src/managers/DenoisingManager.js

@@ -2,11 +2,11 @@ import { EventDispatcher } from 'three';
 import { OIDNDenoiser } from '../Passes/OIDNDenoiser.js';
 import { AIUpscaler } from '../Passes/AIUpscaler.js';
 import { EngineEvents } from '../EngineEvents.js';
-import { ENGINE_DEFAULTS as DEFAULT_STATE, ASVGF_QUALITY_PRESETS } from '../EngineDefaults.js';
+import { ENGINE_DEFAULTS as DEFAULT_STATE, ASVGF_QUALITY_PRESETS, NRD_DEFAULTS, NRD_QUALITY_PRESETS, NRD_PRESET_KEYS } from '../EngineDefaults.js';
 
 /**
  * Orchestrates all denoising, post-processing, and AI upscaling:
- *   - Real-time denoiser strategy switching (ASVGF / EdgeAware / None)
+ *   - Real-time denoiser strategy switching (ASVGF / NRD / EdgeAware / None)
  *   - OIDN (offline denoise on render completion)
  *   - AI Upscaler
  *   - Auto-exposure coordination
@@ -41,7 +41,7 @@ export class DenoisingManager extends EventDispatcher {
 		this.pipeline = pipeline;
 
 		// Stage references — only used internally for orchestration
-		this._stages = stages; // { pathTracer, asvgf, variance, bilateralFilter, edgeFilter, autoExposure, compositor }
+		this._stages = stages; // { pathTracer, asvgf, nrd, variance, bilateralFilter, edgeFilter, autoExposure, compositor }
 
 		this._getExposure = getExposure;
 		this._getSaturation = getSaturation;
@@ -237,30 +237,32 @@ export class DenoisingManager extends EventDispatcher {
 
 	// ── Denoiser Strategy ─────────────────────────────────────────
 
-	/**
-	 * Switches the real-time denoiser strategy.
-	 * @param {string} strategy   - 'none' | 'asvgf' | 'edgeaware'
-	 * @param {string} [asvgfPreset] - ASVGF quality preset when strategy is 'asvgf'
-	 */
 	/**
 	 * Active real-time denoiser, derived from stage state so it can't drift from
 	 * setDenoiserStrategy / setASVGFEnabled.
-	 * @returns {'asvgf'|'edgeaware'|'none'}
+	 * @returns {'asvgf'|'nrd'|'edgeaware'|'none'}
 	 */
 	get denoiserStrategy() {
 
 		if ( this._stages.asvgf?.enabled ) return 'asvgf';
+		if ( this._stages.nrd?.enabled ) return 'nrd';
 		if ( this._stages.edgeFilter?.enabled ) return 'edgeaware';
 		return 'none';
 
 	}
 
-	setDenoiserStrategy( strategy, asvgfPreset ) {
+	/**
+	 * Switches the real-time denoiser strategy.
+	 * @param {string} strategy - 'none' | 'asvgf' | 'nrd' | 'edgeaware'
+	 * @param {string} [preset] - quality preset for 'asvgf' (ASVGF_QUALITY_PRESETS) or 'nrd' (NRD_QUALITY_PRESETS)
+	 */
+	setDenoiserStrategy( strategy, preset ) {
 
 		const s = this._stages;
 
 		// Disable all real-time denoisers first
 		if ( s.asvgf ) s.asvgf.enabled = false;
+		if ( s.nrd ) s.nrd.enabled = false;
 		if ( s.variance ) s.variance.enabled = false;
 		if ( s.bilateralFilter ) s.bilateralFilter.enabled = false;
 		if ( s.edgeFilter ) s.edgeFilter.setFilteringEnabled( false );
@@ -274,7 +276,19 @@ export class DenoisingManager extends EventDispatcher {
 				if ( s.variance ) s.variance.enabled = true;
 				if ( s.bilateralFilter ) s.bilateralFilter.enabled = true;
 				s.asvgf.setTemporalEnabled?.( true );
-				this._applyASVGFPreset( asvgfPreset || 'medium' );
+				this._applyASVGFPreset( preset || 'medium' );
+				break;
+
+			case 'nrd':
+				if ( s.nrd ) {
+
+					s.nrd.enabled = true;
+					// Stale history from the last time it ran describes another view.
+					s.nrd.resetHistory?.();
+					this._applyNRDPreset( preset || 'medium' );
+
+				}
+
 				break;
 
 			case 'edgeaware':
@@ -304,6 +318,8 @@ export class DenoisingManager extends EventDispatcher {
 
 		if ( enabled ) {
 
+			// One real-time denoiser at a time.
+			if ( s.nrd ) s.nrd.enabled = false;
 			s.asvgf?.setTemporalEnabled?.( true );
 			this._applyASVGFPreset( qualityPreset || 'medium' );
 
@@ -353,19 +369,25 @@ export class DenoisingManager extends EventDispatcher {
 	 * navigation and frees their textures. Call after any consumer toggle.
 	 *
 	 * MotionVector requires NormalDepth (reads pathtracer:normalDepth) and its
-	 * consumers (ASVGF) are a subset of NormalDepth's, so NormalDepth is
+	 * consumers (ASVGF, NRD) are a subset of NormalDepth's, so NormalDepth is
 	 * always enabled whenever MotionVector is. Adaptive sampling / Variance / OIDN
 	 * do NOT read these signals, so they don't keep the G-buffer alive.
 	 */
+	/** True while a strategy that reprojects through motion vectors is active. */
+	get requiresMotionVectors() {
+
+		return !! ( this._stages.asvgf?.enabled || this._stages.nrd?.enabled );
+
+	}
+
 	_syncGBufferStages() {
 
 		const s = this._stages;
 		const nd = s.normalDepth;
 		const mv = s.motionVector;
 
-		// motionVector:* consumed by ASVGF
-		const motionNeeded = !! ( s.asvgf?.enabled );
-		// pathtracer:normalDepth consumed by ASVGF, EdgeFilter, BilateralFilter
+		const motionNeeded = this.requiresMotionVectors;
+		// pathtracer:normalDepth consumed by ASVGF, NRD, EdgeFilter, BilateralFilter
 		const normalNeeded = motionNeeded || !! ( s.edgeFilter?.enabled || s.bilateralFilter?.enabled );
 
 		if ( nd ) {
@@ -406,7 +428,7 @@ export class DenoisingManager extends EventDispatcher {
 		// disabled (lazily re-created on the next dispatch after re-enable). Every strategy/denoiser
 		// toggle funnels through here after the enabled flags above are settled, so this is the one
 		// choke point. dispose() is idempotent, so re-running it for an already-released stage is a no-op.
-		for ( const stage of [ s.asvgf, s.variance, s.bilateralFilter, s.edgeFilter, nd, mv ] ) {
+		for ( const stage of [ s.asvgf, s.nrd, s.variance, s.bilateralFilter, s.edgeFilter, nd, mv ] ) {
 
 			if ( stage && ! stage.enabled ) stage.releaseGPUMemory?.();
 
@@ -691,16 +713,42 @@ export class DenoisingManager extends EventDispatcher {
 
 	/**
 	 * Switches strategy with automatic reset (convenience wrapper).
-	 * @param {'none'|'asvgf'|'edgeaware'} strategy
-	 * @param {string} [asvgfPreset]
+	 * @param {'none'|'asvgf'|'nrd'|'edgeaware'} strategy
+	 * @param {string} [preset]
 	 */
-	setStrategy( strategy, asvgfPreset ) {
+	setStrategy( strategy, preset ) {
 
-		this.setDenoiserStrategy( strategy, asvgfPreset );
+		this.setDenoiserStrategy( strategy, preset );
 		this._onReset?.();
 
 	}
 
+	// ── NRD (ReBLUR) ─────────────────────────────────────────────
+
+	/** Updates NRD stage parameters (nrd::ReblurSettings names, see NRD_DEFAULTS). */
+	setNRDParams( params ) {
+
+		this._stages.nrd?.updateParameters( params );
+
+	}
+
+	/**
+	 * Applies an NRD quality preset.
+	 * @param {string} presetName - 'low' | 'medium' | 'high'
+	 */
+	applyNRDPreset( presetName ) {
+
+		this._applyNRDPreset( presetName );
+
+	}
+
+	/** Selects the NRD debug view (0 = beauty; see NRD.js for the others). */
+	setNRDDebugMode( mode ) {
+
+		this._stages.nrd?.updateParameters( { debugMode: mode } );
+
+	}
+
 	// ── Private ───────────────────────────────────────────────────
 
 	_setTileHelper( enabled ) {
@@ -737,12 +785,23 @@ export class DenoisingManager extends EventDispatcher {
 		const keys = [
 			'asvgf:output', 'asvgf:demodulated', 'asvgf:gradient',
 			'variance:output', 'bilateralFiltering:output',
-			'edgeFiltering:output',
+			'edgeFiltering:output', 'nrd:output',
 		];
 		keys.forEach( k => ctx.removeTexture( k ) );
 
 	}
 
+	_applyNRDPreset( presetName ) {
+
+		const preset = NRD_QUALITY_PRESETS[ presetName ];
+		if ( ! preset ) return;
+
+		const params = {};
+		for ( const key of NRD_PRESET_KEYS ) params[ key ] = NRD_DEFAULTS[ key ];
+		this._stages.nrd?.updateParameters( { ...params, ...preset } );
+
+	}
+
 	_applyASVGFPreset( presetName ) {
 
 		const preset = ASVGF_QUALITY_PRESETS[ presetName ];