rayzee 7.22.8 → 7.22.9

package/package.json

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

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, buildBucketTextureNodes, refreshBucketTextureNodes, setMaterialBucketTextures } from '../TSL/TextureSampling.js';
+import { computeUVCache, processNormal, processBump, triangleUVTangent, buildBucketTextureNodes, refreshBucketTextureNodes, setMaterialBucketTextures } from '../TSL/TextureSampling.js';
 
 /**
  * NormalDepth — primary-ray G-buffer for SVGF gates.
@@ -263,7 +263,16 @@ export class NormalDepth extends RenderStage {
 						getMaterial( hit.materialIndex, matStorage )
 					).toVar();
 					const uvCache = UVCache.wrap( computeUVCache( hit.uv, material ) ).toVar();
-					const mapped = processNormal( hit.normal, material, uvCache ).toVar();
+					// Same UV tangent frame the Shade kernel uses, or the aux normal disagrees
+					// with the shading normal it is supposed to guide the denoiser with.
+					const uvTangent = vec4( 0.0 ).toVar();
+					If( material.normalMapIndex.greaterThanEqual( int( 0 ) ), () => {
+
+						uvTangent.assign( triangleUVTangent( triStorage, hit.triangleIndex, hit.normal, material.normalTransform ) );
+
+					} );
+
+					const mapped = processNormal( hit.normal, material, uvCache, uvTangent ).toVar();
 					shadingNormal.assign( processBump( mapped, material, uvCache ) );
 
 				} );

package/src/TSL/Debugger.js

@@ -202,7 +202,7 @@ export const TraceDebugMode = Fn( ( [
 
 			// Sample all textures to get emissive
 			const matSamples = MaterialSamples.wrap( sampleAllMaterialTextures(
-				material, hitInfo.uv, hitInfo.normal,
+				material, hitInfo.uv, hitInfo.normal, vec4( 0.0 ),
 			) ).toVar();
 
 			const emissiveColor = matSamples.emissive.toVar();
@@ -246,7 +246,7 @@ export const TraceDebugMode = Fn( ( [
 
 			// Get material-mapped normal (same as what's used in main shader)
 			const matSamples = MaterialSamples.wrap( sampleAllMaterialTextures(
-				material, hitInfo.uv, hitInfo.normal,
+				material, hitInfo.uv, hitInfo.normal, vec4( 0.0 ),
 			) ).toVar();
 
 			const worldNormal = normalize( matSamples.normal );
@@ -292,7 +292,7 @@ export const TraceDebugMode = Fn( ( [
 			const material = RayTracingMaterial.wrap( getMaterial( hitInfo.materialIndex, materialBuffer ) ).toVar();
 
 			const matSamples = MaterialSamples.wrap( sampleAllMaterialTextures(
-				material, hitInfo.uv, hitInfo.normal,
+				material, hitInfo.uv, hitInfo.normal, vec4( 0.0 ),
 			) ).toVar();
 
 			const objectColor = matSamples.albedo.rgb;
@@ -318,7 +318,7 @@ export const TraceDebugMode = Fn( ( [
 			// Get primary surface material
 			const material = RayTracingMaterial.wrap( getMaterial( hitInfo.materialIndex, materialBuffer ) ).toVar();
 			const matSamples = MaterialSamples.wrap( sampleAllMaterialTextures(
-				material, hitInfo.uv, hitInfo.normal,
+				material, hitInfo.uv, hitInfo.normal, vec4( 0.0 ),
 			) ).toVar();
 
 			const albedoA = matSamples.albedo.rgb;
@@ -364,7 +364,7 @@ export const TraceDebugMode = Fn( ( [
 				// Bounce hit surface B — evaluate its contribution
 				const materialB = RayTracingMaterial.wrap( getMaterial( bounceHit.materialIndex, materialBuffer ) ).toVar();
 				const matSamplesB = MaterialSamples.wrap( sampleAllMaterialTextures(
-					materialB, bounceHit.uv, bounceHit.normal,
+					materialB, bounceHit.uv, bounceHit.normal, vec4( 0.0 ),
 				) ).toVar();
 
 				// Emissive contribution from surface B

package/src/TSL/ShadeKernel.js

@@ -17,7 +17,7 @@ import {
 import { sampleEnvironment, sampleEquirectProbability, sampleEquirect, groundProjectedEnvDir } from './Environment.js';
 import { getMaterial, powerHeuristic, balanceHeuristic, classifyMaterial, REC709_LUMINANCE_COEFFICIENTS, PI_INV, EPSILON, diffuseGroundMaterial } from './Common.js';
 import { cosineWeightedSample } from './MaterialSampling.js';
-import { sampleAllMaterialTextures, processAnisotropyMap, applyExtensionMaps, getTransformedUV } from './TextureSampling.js';
+import { sampleAllMaterialTextures, processAnisotropyMap, applyExtensionMaps, getTransformedUV, triangleUVTangent } from './TextureSampling.js';
 import { evaluateMaterialResponse } from './MaterialEvaluation.js';
 import { calculateDirectLightingUnified, calculateMaterialPDF } from './LightsSampling.js';
 import { traceShadowRay, calculateRayOffset } from './LightsDirect.js';
@@ -616,8 +616,17 @@ export function buildShadeKernel( params ) {
 			}
 		);
 
+		// Normal-map tangent frame. Only paid for when there is a normal map: the arbitrary
+		// cross(up, N) fallback inside processNormal is what runs otherwise.
+		const uvTangent = vec4( 0.0 ).toVar();
+		If( material.normalMapIndex.greaterThanEqual( int( 0 ) ), () => {
+
+			uvTangent.assign( triangleUVTangent( triangleBuffer, int( hitTriIdx ), N, material.normalTransform ) );
+
+		} );
+
 		const matSamples = MaterialSamples.wrap( sampleAllMaterialTextures(
-			material, samplingUV, N,
+			material, samplingUV, N, uvTangent,
 		) ).toVar();
 
 		// DDFA: snapshot the UNCLAMPED roughness (before the min-0.05 clamp below) for the specular↔diffuse

package/src/TSL/TextureSampling.js

@@ -1,4 +1,4 @@
-import { Fn, wgslFn, float, vec2, vec3, vec4, int, If, normalize, cross, abs, atan, mix, clamp, texture, textureSize } from 'three/tsl';
+import { Fn, wgslFn, float, vec2, vec3, vec4, int, If, normalize, cross, dot, length, sign, abs, atan, mix, clamp, texture, textureSize } from 'three/tsl';
 import { DataArrayTexture, LinearFilter } from 'three';
 
 import {
@@ -6,6 +6,7 @@ import {
 	MaterialSamples,
 	ExtMapResult,
 } from './Struct.js';
+import { getDatafromStorageBuffer } from './Common.js';
 import { TEXTURE_CONSTANTS } from '../EngineDefaults.js';
 
 // ================================================================================
@@ -382,7 +383,80 @@ export const processMetalnessRoughness = Fn( ( [ material, uvCache ] ) => {
 
 } );
 
-export const processNormal = Fn( ( [ geometryNormal, material, uvCache ] ) => {
+// (t[1][1], t[0][1]) — the row of the inverse 2x2 linear part that maps dP/du onto dP/du',
+// up to the determinant, which drops out under the normalize that follows.
+const uvTransformJacobian = /*@__PURE__*/ wgslFn( `
+	fn uvTransformJacobian( t: mat3x3f ) -> vec2f {
+		return vec2f( t[1][1], t[0][1] );
+	}
+` );
+
+/**
+ * Build the UV tangent for one triangle, as vec4( T.xyz, handedness ).
+ *
+ * Returned in the *transformed* UV space of `transform`, since that is the space the normal
+ * map is sampled in — the inverse of the transform's 2x2 linear part maps dP/du back onto
+ * dP/du'. A pure repeat/scale leaves the direction alone; a rotated transform does not.
+ * w == 0 signals a degenerate parameterisation, which processNormal treats as "no frame".
+ *
+ * @param {Node} triangleBuffer packed triangle storage (8 vec4 stride)
+ * @param {Node} triIndex       absolute triangle index
+ * @param {Node} geometryNormal shading-space normal, for the handedness test
+ * @param {Node} transform      the normal map's mat3 UV transform
+ */
+export const triangleUVTangent = Fn( ( [ triangleBuffer, triIndex, geometryNormal, transform ] ) => {
+
+	const S = int( 8 );
+	const pA = getDatafromStorageBuffer( triangleBuffer, triIndex, int( 0 ), S ).xyz;
+	const e1 = getDatafromStorageBuffer( triangleBuffer, triIndex, int( 1 ), S ).xyz.sub( pA );
+	const e2 = getDatafromStorageBuffer( triangleBuffer, triIndex, int( 2 ), S ).xyz.sub( pA );
+
+	const uvAB = getDatafromStorageBuffer( triangleBuffer, triIndex, int( 6 ), S );
+	const uvC = getDatafromStorageBuffer( triangleBuffer, triIndex, int( 7 ), S ).xy;
+	const d1 = uvAB.zw.sub( uvAB.xy );
+	const d2 = uvC.sub( uvAB.xy );
+
+	const det = d1.x.mul( d2.y ).sub( d1.y.mul( d2.x ) );
+	const result = vec4( 0.0 ).toVar();
+
+	If( abs( det ).greaterThan( 1e-12 ), () => {
+
+		const r = float( 1.0 ).div( det );
+		const T = e1.mul( d2.y ).sub( e2.mul( d1.y ) ).mul( r ).toVar();
+		const B = e2.mul( d1.x ).sub( e1.mul( d2.x ) ).mul( r ).toVar();
+
+		// Re-express in the map's transformed UV space (inverse of the 2x2 linear part).
+		const uvJ = uvTransformJacobian( { t: transform } );
+		const Tt = T.mul( uvJ.x ).sub( B.mul( uvJ.y ) ).toVar();
+
+		If( length( Tt ).greaterThan( 1e-12 ), () => {
+
+			T.assign( Tt );
+
+		} );
+
+		If( length( T ).greaterThan( 1e-12 ), () => {
+
+			result.assign( vec4( normalize( T ), sign( dot( cross( geometryNormal, T ), B ) ) ) );
+
+		} );
+
+	} );
+
+	return result;
+
+} );
+
+/**
+ * Per-triangle tangent frame from the UV parameterisation.
+ *
+ * `uvTangent` is vec4( T.xyz, handedness ); w == 0 means "no usable frame" (degenerate or
+ * missing UVs) and falls back to the arbitrary cross(up, N) frame. A frame unrelated to the
+ * texture's U axis rotates the whole perturbation: on a vertical fluted-glass panel the
+ * arbitrary frame comes out 90 deg off, so the rib normals tilt up/down instead of across
+ * the ribs.
+ */
+export const processNormal = Fn( ( [ geometryNormal, material, uvCache, uvTangent ] ) => {
 
 	const result = geometryNormal.toVar();
 
@@ -393,10 +467,25 @@ export const processNormal = Fn( ( [ geometryNormal, material, uvCache ] ) => {
 		normalMap.x.mulAssign( material.normalScale.x );
 		normalMap.y.assign( normalMap.y.negate().mul( material.normalScale.x ) );
 
-		// Fast TBN construction
-		const up = abs( geometryNormal.z ).lessThan( 0.999 ).select( vec3( 0.0, 0.0, 1.0 ), vec3( 1.0, 0.0, 0.0 ) );
-		const tangent = normalize( cross( up, geometryNormal ) );
-		const bitangent = cross( geometryNormal, tangent );
+		const tangent = vec3( 0.0 ).toVar();
+		const handedness = float( 1.0 ).toVar();
+
+		// Gram-Schmidt against the interpolated normal, which is not exactly triangle-planar.
+		const perp = uvTangent.xyz.sub( geometryNormal.mul( dot( geometryNormal, uvTangent.xyz ) ) ).toVar();
+
+		If( abs( uvTangent.w ).greaterThan( 0.5 ).and( length( perp ).greaterThan( 1e-6 ) ), () => {
+
+			tangent.assign( normalize( perp ) );
+			handedness.assign( uvTangent.w );
+
+		} ).Else( () => {
+
+			const up = abs( geometryNormal.z ).lessThan( 0.999 ).select( vec3( 0.0, 0.0, 1.0 ), vec3( 1.0, 0.0, 0.0 ) );
+			tangent.assign( normalize( cross( up, geometryNormal ) ) );
+
+		} );
+
+		const bitangent = cross( geometryNormal, tangent ).mul( handedness );
 
 		result.assign( normalize(
 			tangent.mul( normalMap.x ).add( bitangent.mul( normalMap.y ) ).add( geometryNormal.mul( normalMap.z ) )
@@ -563,7 +652,7 @@ export const processEmissive = Fn( ( [ material, uvCache ] ) => {
 // MAIN BATCHED SAMPLING FUNCTION
 // ================================================================================
 
-export const sampleAllMaterialTextures = Fn( ( [ material, uv, geometryNormal ] ) => {
+export const sampleAllMaterialTextures = Fn( ( [ material, uv, geometryNormal, uvTangent ] ) => {
 
 	const albedo = vec4( 0.0 ).toVar();
 	const emissive = vec3( 0.0 ).toVar();
@@ -591,7 +680,7 @@ export const sampleAllMaterialTextures = Fn( ( [ material, uv, geometryNormal ]
 		metalness.assign( metalRough.x );
 		roughness.assign( metalRough.y );
 
-		const currentNormal = processNormal( geometryNormal, material, uvCache ).toVar();
+		const currentNormal = processNormal( geometryNormal, material, uvCache, uvTangent ).toVar();
 		normal.assign( processBump( currentNormal, material, uvCache ) );
 
 		emissive.assign( processEmissive( material, uvCache ) );