rayzee 7.11.0 → 7.11.1

package/package.json

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

package/src/Processor/ShaderBuilder.js

@@ -19,6 +19,7 @@ export class ShaderBuilder {
 		// Previous-frame texture nodes (sample from MRT RenderTarget)
 		this.prevColorTexNode = null;
 		this.prevAlbedoTexNode = null;
+		this.prevNormalDepthTexNode = null;
 
 		// Scene texture nodes cache (for in-place updates on model change)
 		this._sceneTextureNodes = null;
@@ -98,6 +99,7 @@ export class ShaderBuilder {
 		const readTextures = storageTextures.getReadTextures();
 		this.prevColorTexNode = texture( readTextures.color );
 		this.prevAlbedoTexNode = texture( readTextures.albedo );
+		this.prevNormalDepthTexNode = texture( readTextures.normalDepth );
 
 		const createArrayPlaceholder = () => {
 
@@ -137,6 +139,7 @@ export class ShaderBuilder {
 
 		this.prevColorTexNode = null;
 		this.prevAlbedoTexNode = null;
+		this.prevNormalDepthTexNode = null;
 		this._sceneTextureNodes = null;
 
 	}

package/src/Stages/PathTracer.js

@@ -46,6 +46,11 @@ export class PathTracer extends PathTracerStage {
 		// uniform — NOT baked — so DenoisingManager can toggle it without a (UI-freezing) kernel rebuild.
 		this._auxGBufferEnabled = false;
 		this._auxGBufferUniform = uniform( 0, 'uint' );
+		// Clean-aux mode: temporally accumulate + renormalize the aux NORMAL (like albedo) so a clean-aux
+		// OIDN model (calb_cnrm/high, alb_nrm/balanced) gets the prefiltered-ish normal it expects instead
+		// of the point-sampled per-frame value that leaks noise. Off for fast/ASVGF (they want the bump normal).
+		this._cleanAuxNormalEnabled = false;
+		this._cleanAuxNormalUniform = uniform( 0, 'uint' );
 
 		// 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;
@@ -220,6 +225,7 @@ export class PathTracer extends PathTracerStage {
 
 			this.shaderBuilder.prevColorTexNode.value = readTextures.color;
 			this.shaderBuilder.prevAlbedoTexNode.value = readTextures.albedo;
+			this.shaderBuilder.prevNormalDepthTexNode.value = readTextures.normalDepth;
 
 		}
 
@@ -410,6 +416,19 @@ export class PathTracer extends PathTracerStage {
 
 	}
 
+	// Clean-aux normal: when a clean-aux OIDN model is active (calb_cnrm/high, alb_nrm/balanced), FinalWrite
+	// temporally accumulates + renormalizes the aux normal so the model isn't fed per-frame point-sampled
+	// noise. DenoisingManager calls this on OIDN enable + quality change. Live uniform → value flip + reset.
+	setCleanAuxNormal( enabled ) {
+
+		enabled = !! enabled;
+		if ( this._cleanAuxNormalEnabled === enabled ) return;
+		this._cleanAuxNormalEnabled = enabled;
+		this._cleanAuxNormalUniform.value = enabled ? 1 : 0;
+		this.reset();
+
+	}
+
 	// UI-driven resize (Resolution dropdown) — parent bypasses _handleResize(), so hook here too.
 	setSize( width, height ) {
 
@@ -605,6 +624,7 @@ export class PathTracer extends PathTracerStage {
 
 		const prevColor = this.shaderBuilder.prevColorTexNode;
 		const prevAlbedo = this.shaderBuilder.prevAlbedoTexNode;
+		const prevNormalDepth = this.shaderBuilder.prevNormalDepthTexNode;
 		const writeTex = this.storageTextures.getWriteTextures();
 
 		const counters = qm.getCounters();
@@ -907,10 +927,12 @@ export class PathTracer extends PathTracerStage {
 			transparentBackground: this.transparentBackground,
 			prevAccumTexture: prevColor,
 			prevAlbedoTexture: prevAlbedo,
+			prevNormalDepthTexture: prevNormalDepth,
 			renderWidth: this._wfRenderWidth,
 			renderHeight: this._wfRenderHeight,
 			visMode: this.visMode,
 			auxGBufferEnabled: this._auxGBufferUniform,
+			cleanAuxNormalEnabled: this._cleanAuxNormalUniform,
 		} );
 		this._kernelManager.register( 'finalWrite',
 			// Per-pixel (w×h) — kernel averages the S sample-slots internally.

package/src/TSL/FinalWriteKernel.js

@@ -4,7 +4,7 @@
 
 import {
 	Fn, wgslFn, float, vec2, vec4, int, uint, uvec2,
-	If, mix, select, texture, textureStore,
+	If, mix, select, texture, textureStore, length,
 	localId, workgroupId,
 } from 'three/tsl';
 
@@ -32,15 +32,19 @@ export function buildFinalWriteKernel( params ) {
 		resolution, frame,
 		enableAccumulation, hasPreviousAccumulated, accumulationAlpha, cameraIsMoving,
 		transparentBackground,
-		prevAccumTexture, prevAlbedoTexture,
+		prevAccumTexture, prevAlbedoTexture, prevNormalDepthTexture,
 		renderWidth, renderHeight,
 		visMode,
 		// Aux MRT (normalDepth + albedo) feeds only the denoiser/OIDN. Gated by a live uniform (1 = denoiser
 		// on): when off, skip the G-buffer decode, the prev-frame aux mix, and the two aux stores.
 		auxGBufferEnabled,
+		// Clean-aux normal (1 = temporally accumulate + renormalize the aux normal). On only for clean-aux
+		// OIDN models (calb_cnrm/high, alb_nrm/balanced); off for fast/ASVGF which want the bump normal.
+		cleanAuxNormalEnabled,
 	} = params;
 
 	const auxOn = auxGBufferEnabled.greaterThan( uint( 0 ) );
+	const cleanAuxNormalOn = cleanAuxNormalEnabled.greaterThan( uint( 0 ) );
 
 	const computeFn = Fn( () => {
 
@@ -80,12 +84,27 @@ export function buildFinalWriteKernel( params ) {
 				finalColor.assign( mix( prevAccumSample.xyz, sampleColor.xyz, accumulationAlpha ) );
 				If( auxOn, () => {
 
-					// Albedo averages cleanly (it's a colour). The NORMAL must NOT: averaging jittered
-					// unit normals collapses toward the flat geometric mean (worse at distance), which made
-					// OIDN smooth bump detail away. Keep this frame's point-sampled normal — it varies with
-					// the bump, which is exactly what OIDN's edge-stop needs to preserve it.
+					// Albedo averages cleanly (it's a colour).
 					finalAlbedo.assign( mix( texture( prevAlbedoTexture, prevUV, 0 ).xyz, finalAlbedo, accumulationAlpha ) );
 
+					// 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,
+					// alb_nrm/balanced) trusts the aux and is fed per-frame point-sampled NOISE → leaked noise
+					// (high) / over-smoothing (balanced). When cleanAuxNormalOn, temporally accumulate it like
+					// the colour. Average the RAW unit normals (decode 0.5+0.5 → [-1,1]) and RENORMALIZE — a
+					// plain encoded-space mix would bias toward the flat (0.5,0.5,1) mean and collapse detail.
+					// Depth (.w) stays this frame's value; guard the degenerate near-zero mean (opposing normals).
+					If( cleanAuxNormalOn, () => {
+
+						const prevN = texture( prevNormalDepthTexture, prevUV, 0 ).xyz.mul( 2.0 ).sub( 1.0 );
+						const curN = finalNormalDepth.xyz.mul( 2.0 ).sub( 1.0 ).toVar();
+						const mixedN = mix( prevN, curN, accumulationAlpha ).toVar();
+						const len = length( mixedN );
+						const avgN = select( len.greaterThan( 1e-4 ), mixedN.div( len ), curN );
+						finalNormalDepth.assign( vec4( avgN.mul( 0.5 ).add( 0.5 ), finalNormalDepth.w ) );
+
+					} );
+
 				} );
 
 				If( transparentBackground, () => {

package/src/TSL/ShadeKernel.js

@@ -54,7 +54,7 @@ import {
 	readHitDistance, readHitBarycentrics, readHitNormal,
 	readHitMaterialIndex, readHitTriangleIndex,
 	writeRayOriginMeta, writeRayDirFlags, writeRayThroughputPdf, writeRayRadiance,
-	writeGBuffer, readGBuffer, gbDecodeNormalDepth,
+	writeGBuffer, readGBuffer, gbDecodeNormalDepth, gbDecodeAlbedo,
 	readRayRadiance,
 } from '../Processor/PackedRayBuffer.js';
 
@@ -320,6 +320,11 @@ export function buildShadeKernel( params ) {
 			const wantBackdrop = isBackdropView.and( showBackground ); // draw env image as backdrop
 			const wantEnvLight = isBackdropView.not().and( enableEnvironmentLight ); // env as light on redirected bounces
 
+			// Fix ①: OIDN clean-aux for a redirected ray that escapes to the environment (e.g. smooth
+			// glass over sky). Holds the clamped env colour this ray sees; written into the aux G-buffer
+			// before the miss Return below, but only when the pixel still carries the black bounce-0 default.
+			const escapedAuxAlbedo = vec3( 0.0 ).toVar();
+
 			If( wantBackdrop.or( wantEnvLight ), () => {
 
 				// Ground projection bends the backdrop-view env lookup onto a projected sphere+disk so the lower
@@ -358,6 +363,10 @@ export function buildShadeKernel( params ) {
 
 				} );
 
+				// Fix ①: remember the (clamped) env colour this escaped ray sees, so a redirected ray
+				// that never captured a surface aux can feed OIDN a meaningful albedo below.
+				escapedAuxAlbedo.assign( clamp( envColor, vec3( 0.0 ), vec3( 1.0 ) ) );
+
 				// MIS weight for implicit env hit — prevents double-counting with NEE
 				const envMisWeight = float( 1.0 ).toVar();
 				If( isBackdropView.not().and( useEnvMapIS ), () => {
@@ -425,6 +434,25 @@ export function buildShadeKernel( params ) {
 
 			} );
 
+			// Fix ①: fill the black bounce-0 default aux for a redirected ray that reached the
+			// environment without ever locking a surface guide (smooth glass / specular transmission
+			// over sky). Only when the stored albedo is still the black default (dot < 1e-4), so a real
+			// specular-surface aux written upstream is never clobbered. Normal = the escaped ray
+			// direction (varies per pixel → OIDN sees structure that tracks the refracted view);
+			// albedo = the clamped env colour it sees; depth kept at the primary hit.
+			If( auxOn
+				.and( flags.bitAnd( uint( RAY_FLAG.AUX_LOCKED ) ).equal( uint( 0 ) ) )
+				.and( flags.bitAnd( uint( RAY_FLAG.REDIRECTED ) ).notEqual( uint( 0 ) ) ), () => {
+
+				const gPrev = readGBuffer( gBufferRW, pixelIndex );
+				If( dot( gbDecodeAlbedo( gPrev ), vec3( 1.0 ) ).lessThan( float( 1e-4 ) ), () => {
+
+					writeGBuffer( gBufferRW, pixelIndex, normalize( direction ), gbDecodeNormalDepth( gPrev ).w, escapedAuxAlbedo );
+
+				} );
+
+			} );
+
 			writeRayRadiance( rayBufferRW, rayID, currentRadiance );
 			writeRayDirFlags( rayBufferRW, rayID, direction, flags.bitAnd( uint( ~ RAY_FLAG.ACTIVE ) ) );
 			Return();
@@ -607,7 +635,23 @@ export function buildShadeKernel( params ) {
 			// (aux-extend) and may extend through specular surfaces (gap #9). Glass rays Return at the transparency
 			// block before that capture, so a glass-then-escape pixel keeps this default aux — megakernel parity
 			// (objectNormal/objectColor stay at their init for transmissive-then-miss).
-			writeGBuffer( gBufferRW, pixelIndex, vec3( 0.0, 0.0, 1.0 ), linearDepth, vec3( 0.0 ) );
+			//
+			// Fix ③: BLEND (semi-transparent) glass instead LOCKS its OWN normal + albedo here. Its per-frame
+			// stochastic alpha-skip-vs-opaque-shade outcome (MaterialTransmission.js:522-540) otherwise writes a
+			// DIFFERENT surface into the aux each frame (wall-behind on skip vs glass on opaque); with the normal
+			// not temporally averaged that becomes the speckle OIDN smears on — the visible artefact on
+			// alpha-transparent glass. A deterministic glass-surface guide every frame removes it. MASK / opaque
+			// materials keep the default + rely on the downstream aux-extend.
+			If( material.alphaMode.equal( int( 2 ) ), () => {
+
+				writeGBuffer( gBufferRW, pixelIndex, N, linearDepth, albedo.xyz );
+				flags.assign( flags.bitOr( uint( RAY_FLAG.AUX_LOCKED ) ) );
+
+			} ).Else( () => {
+
+				writeGBuffer( gBufferRW, pixelIndex, vec3( 0.0, 0.0, 1.0 ), linearDepth, vec3( 0.0 ) );
+
+			} );
 
 		} );
 
@@ -744,6 +788,26 @@ export function buildShadeKernel( params ) {
 
 			throughput.mulAssign( interaction.throughput );
 
+			// Fix ②: OIDN clean-aux for STOCHASTIC glass (rough / frosted / dispersive), whose refracted
+			// ray hits a different behind-surface every frame. Extending aux through it (the aux-extend on
+			// the opaque-hit path) captures that per-frame surface — albedo then temporally averaged, normal
+			// point-sampled — an inconsistent guide OIDN smears on. Instead lock the glass surface's OWN
+			// normal + tint here (deterministic, spatially coherent). Smooth non-dispersive glass is left
+			// alone: its refraction is a per-pixel delta, so the behind-surface aux captured downstream is
+			// already stable. Gated to a genuine dielectric event (not alpha-cutout passthrough or SSS).
+			If( auxOn
+				.and( flags.bitAnd( uint( RAY_FLAG.AUX_LOCKED ) ).equal( uint( 0 ) ) )
+				.and( interaction.isTransmissive )
+				.and( interaction.isAlphaSkip.not() )
+				.and( interaction.isSubsurface.not() )
+				.and( material.roughness.greaterThan( 0.05 ).or( material.dispersion.greaterThan( 0.0 ) ) ), () => {
+
+				const primaryDepth = gbDecodeNormalDepth( readGBuffer( gBufferRW, pixelIndex ) ).w;
+				writeGBuffer( gBufferRW, pixelIndex, N, primaryDepth, albedo.xyz );
+				flags.assign( flags.bitOr( uint( RAY_FLAG.AUX_LOCKED ) ) );
+
+			} );
+
 			// reflection stays on same side, transmission pushes through
 			const reflectOffsetDir = select( interaction.entering, N, N.negate() );
 			const offsetDir = select( interaction.didReflect, reflectOffsetDir, direction );

package/src/managers/DenoisingManager.js

@@ -368,6 +368,10 @@ export class DenoisingManager extends EventDispatcher {
 		// MRT read-targets directly). When none are active the wavefront skips those writes entirely.
 		s.pathTracer?.setAuxGBufferEnabled?.( normalNeeded || !! this.denoiser?.enabled );
 
+		// Clean-aux normal: temporally accumulate the aux normal only for OIDN clean-aux models
+		// (balanced/high). 'fast' and the real-time denoisers keep the point-sampled bump normal.
+		s.pathTracer?.setCleanAuxNormal?.( !! this.denoiser?.enabled && this.denoiser?.quality !== 'fast' );
+
 		// Reclaim VRAM: free the big 2048² StorageTextures of any denoiser/G-buffer stage that ended up
 		// 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
@@ -610,6 +614,8 @@ export class DenoisingManager extends EventDispatcher {
 	setOIDNQuality( quality ) {
 
 		this.denoiser?.updateQuality( quality );
+		// Clean-aux normal follows the model: balanced/high (clean-aux models) → accumulate; fast → keep bump.
+		this._stages.pathTracer?.setCleanAuxNormal?.( !! this.denoiser?.enabled && quality !== 'fast' );
 
 	}