rayzee 7.22.7 → 7.22.9

package/package.json

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

package/src/EngineDefaults.js

@@ -604,7 +604,8 @@ export const PRODUCTION_RENDER_CONFIG = {
 	// so easy scenes finish well under it while hard GI scenes use the full budget.
 	maxSamples: 150, bounces: 20, transmissiveBounces: 8, maxSubsurfaceSteps: 64,
 	renderMode: 1, enableAlphaShadows: true,
-	enableOIDN: true, oidnQuality: 'balance',
+	// 'high' is the only tier that reaches OIDN's _large weights (calb_cnrm); ~2x denoise cost.
+	enableOIDN: true, oidnQuality: 'high',
 	interactionModeEnabled: false,
 	// 0.94 against the eroded count ≈ the old raw-count 0.98; erosion holds the fraction a few points lower.
 	useAdaptiveSampling: true,

package/src/Passes/OIDNDenoiser.js

@@ -52,20 +52,65 @@ import { getAssetConfig } from '../AssetConfig.js';
 const _tmOut = new Float32Array( 3 );
 
 const MODEL_CONFIG = {
-	// clean-aux models — first-hit albedo/normal are deterministic per pixel
+	// No cleanAux flag in oidn-web, so the blob is it — and must match what setCleanAuxNormal
+	// feeds: `fast` point-samples the normal (noisy aux), balance/high accumulate it. calb_cnrm
+	// is also the only model with a `_large` blob.
 	QUALITY_MODELS: {
 		fast: 'rt_hdr_alb_nrm_small',
-		balance: 'rt_hdr_alb_nrm',
+		balance: 'rt_hdr_calb_cnrm',
 		high: 'rt_hdr_calb_cnrm_large'
 	},
 	DEFAULT_OPTIONS: {
 		enableOIDN: true,
 		oidnQuality: 'fast',
 		debugGbufferMaps: true,
-		tileSize: 256
+		// Tiles run at tileSize + 2*overlap (96px, 112 for _large), so small tiles pay that padding
+		// every tile: 256 puts 3.06x the pixels through the UNet at 512². Measured 3.64x faster.
+		tileSize: 512
 	}
 };
 
+// Stands in for OIDN's inputScale, which oidn-web only applies on its CPU path — the GPUBuffer
+// path leaves the uniform at 1.0. Equivalent because oidn-web does PUForward(col*inputScale) in
+// and PUInverse(..)/inputScale out, so pre-multiplying here and dividing it back out of the
+// output exposure round-trips. Alpha is preserved for _cacheInputAlpha.
+const COLOR_SCALE_WGSL = /* wgsl */`
+@group(0) @binding(0) var<storage, read_write> col: array<vec4<f32>>;
+@group(0) @binding(1) var<uniform> scale: f32;
+
+@compute @workgroup_size(64)
+fn main( @builtin(global_invocation_id) gid: vec3<u32>,
+		 @builtin(num_workgroups) nwg: vec3<u32> ) {
+	let i = gid.y * nwg.x * 64u + gid.x;
+	if ( i >= arrayLength( &col ) ) { return; }
+	let c = col[ i ];
+	col[ i ] = vec4<f32>( c.xyz * scale, c.w );
+}
+`;
+
+const SCALE_WG_SIZE = 64;
+// 1D would exceed maxComputeWorkgroupsPerDimension (65535) past ~2048², so the dispatch is 2D.
+const SCALE_MAX_WG_X = 32768;
+
+// OIDN's autoexposure, mirroring oidn-web's avgLogLum. Whole-frame, so it cannot seam per tile.
+const OIDN_AUTOEXPOSURE_KEY = 0.18;
+
+function oidnInputScale( f32, pixelCount ) {
+
+	let logSum = 0;
+	for ( let i = 0; i < pixelCount; i ++ ) {
+
+		const o = i * 4;
+		const lum = 0.212671 * f32[ o ] + 0.71516 * f32[ o + 1 ] + 0.072169 * f32[ o + 2 ];
+		logSum += Math.log2( Math.max( lum, 0 ) + 0.0001 );
+
+	}
+
+	const scale = OIDN_AUTOEXPOSURE_KEY / Math.pow( 2, logSum / pixelCount );
+	return Number.isFinite( scale ) && scale > 0 ? scale : 1.0;
+
+}
+
 export class OIDNDenoiser extends EventDispatcher {
 
 	constructor( output, renderer, scene, camera, options = {} ) {
@@ -110,6 +155,11 @@ export class OIDNDenoiser extends EventDispatcher {
 		// order guarantees the overwrites are serialized).
 		this._gpuInputPadBuffer = null;
 		this._gpuInputPaddedRowBytes = 0;
+		// 1.0 until the first readback.
+		this._colorScalePipeline = null;
+		this._colorScaleBindGroup = null;
+		this._colorScaleUniform = null;
+		this._oidnInputScale = 1.0;
 		// Pooled MAP_READ staging buffer for _cacheInputAlpha. Only allocated
 		// when transparent-background readback is used, destroyed on resolution
 		// change or dispose. Same spirit as r184's ReadbackBuffer — we can't use
@@ -130,6 +180,8 @@ export class OIDNDenoiser extends EventDispatcher {
 		this.quality = this.config.oidnQuality;
 		this.debugGbufferMaps = this.config.debugGbufferMaps;
 		this.tileSize = this.config.tileSize;
+		// tileSize actually baked into the live UNet, so a runtime change forces a rebuild.
+		this._activeTileSize = 0;
 
 		// State management
 		this.state = {
@@ -212,8 +264,8 @@ export class OIDNDenoiser extends EventDispatcher {
 		this.state.isLoading = true;
 		const tzaUrl = this._generateTzaUrl();
 
-		// Skip setup if URL hasn't changed
-		if ( this.currentTZAUrl === tzaUrl && this.unet ) {
+		// maxTileSize is a constructor arg, so comparing the URL alone left tileSize changes inert.
+		if ( this.currentTZAUrl === tzaUrl && this._activeTileSize === this.tileSize && this.unet ) {
 
 			this.state.isLoading = false;
 			return;
@@ -251,6 +303,7 @@ export class OIDNDenoiser extends EventDispatcher {
 			} );
 
 			this.currentTZAUrl = tzaUrl;
+			this._activeTileSize = this.tileSize;
 			this.dispatchEvent( { type: 'loaded' } );
 			log.debug( 'UNet weights loaded:', tzaUrl );
 
@@ -477,21 +530,18 @@ export class OIDNDenoiser extends EventDispatcher {
 
 		copyTex( textures.color, this._gpuInputBuffers.color );
 		copyTex( textures.albedo, this._gpuInputBuffers.albedo );
+		// The normal stays [0,1]-encoded. This contradicts OIDN's API ("must be in the [-1,1]
+		// range") but is right for this port: OIDN's own getNormal (cpu_input_process.isph) does
+		// `value*0.5+0.5` before the network, and oidn-web omits that remap. Decoding to [-1,1]
+		// measured 0.878 -> 2.439 denoise ratio at 64 spp. Do not "fix" it.
 		copyTex( textures.normal, this._gpuInputBuffers.normal );
 
 		device.queue.submit( [ encoder.finish() ] );
 
-		// Cache alpha channel from input color buffer when transparent background is enabled.
-		// OIDN only processes RGB — the alpha channel is lost, so we read it before denoising.
-		if ( this.getTransparentBackground() ) {
-
-			await this._cacheInputAlpha( device, width, height );
-
-		} else {
-
-			this._cachedAlpha = null;
-
-		}
+		// One readback serves the autoexposure scale and the alpha OIDN discards. Must precede the scale.
+		await this._readbackColor( device, width, height );
+		if ( globalThis.__OIDN_NO_INPUT_SCALE ) this._oidnInputScale = 1.0;
+		this._applyColorScale( device, width * height );
 
 		// Draw the current noisy frame as the base — denoised tiles paint on top progressively
 		this.ctx.drawImage( this.input, 0, 0, width, height );
@@ -571,6 +621,10 @@ export class OIDNDenoiser extends EventDispatcher {
 
 		this._alphaReadbackBuffer?.destroy();
 		this._alphaReadbackMapped = false;
+		// Bind group holds the destroyed buffer; the pipeline is device-scoped and survives.
+		this._colorScaleBindGroup = null;
+		this._colorScaleUniform?.destroy();
+		this._colorScaleUniform = null;
 		this._gpuInputBuffers = { color: null, albedo: null, normal: null };
 		this._gpuInputPadBuffer = null;
 		this._gpuInputPaddedRowBytes = 0;
@@ -580,10 +634,10 @@ export class OIDNDenoiser extends EventDispatcher {
 	}
 
 	/**
-	 * Reads the alpha channel from the input color GPU buffer and caches it as a Uint8Array.
-	 * Called before OIDN denoising when transparent background is enabled.
+	 * Reads back the colour buffer for the autoexposure scale, plus alpha when transparent
+	 * background is on (OIDN discards alpha).
 	 */
-	async _cacheInputAlpha( device, width, height ) {
+	async _readbackColor( device, width, height ) {
 
 		const byteSize = width * height * 16; // rgba32float, tightly packed
 
@@ -620,13 +674,20 @@ export class OIDNDenoiser extends EventDispatcher {
 		}
 
 		const f32 = new Float32Array( staging.getMappedRange() );
-
-		// Extract alpha channel as uint8 (pre-multiplied is not needed — alpha is 0 or 1)
 		const pixelCount = width * height;
-		const alpha = new Uint8Array( pixelCount );
-		for ( let i = 0; i < pixelCount; i ++ ) {
 
-			alpha[ i ] = Math.min( Math.max( f32[ i * 4 + 3 ] * 255, 0 ), 255 ) | 0;
+		this._oidnInputScale = oidnInputScale( f32, pixelCount );
+
+		let alpha = null;
+		if ( this.getTransparentBackground() ) {
+
+			// Alpha as uint8; pre-multiplication is not needed — alpha is 0 or 1
+			alpha = new Uint8Array( pixelCount );
+			for ( let i = 0; i < pixelCount; i ++ ) {
+
+				alpha[ i ] = Math.min( Math.max( f32[ i * 4 + 3 ] * 255, 0 ), 255 ) | 0;
+
+			}
 
 		}
 
@@ -638,6 +699,81 @@ export class OIDNDenoiser extends EventDispatcher {
 
 	}
 
+	/** Display exposure with the input scale divided back out — output arrives pre-multiplied. */
+	_outputExposure() {
+
+		return this.getExposure() / this._oidnInputScale;
+
+	}
+
+	/** Pre-multiplies the colour buffer by the autoexposure scale. */
+	_applyColorScale( device, pixelCount ) {
+
+		const scale = this._oidnInputScale;
+		if ( ! this._ensureColorScalePipeline( device ) ) return;
+
+		device.queue.writeBuffer( this._colorScaleUniform, 0, new Float32Array( [ scale ] ) );
+
+		const wgTotal = Math.ceil( pixelCount / SCALE_WG_SIZE );
+		const wgX = Math.min( wgTotal, SCALE_MAX_WG_X );
+		const wgY = Math.ceil( wgTotal / wgX );
+
+		const encoder = device.createCommandEncoder( { label: 'oidn-color-scale' } );
+		const pass = encoder.beginComputePass( { label: 'oidn-color-scale' } );
+		pass.setPipeline( this._colorScalePipeline );
+		pass.setBindGroup( 0, this._colorScaleBindGroup );
+		pass.dispatchWorkgroups( wgX, wgY, 1 );
+		pass.end();
+		device.queue.submit( [ encoder.finish() ] );
+
+	}
+
+	/** @returns {GPUComputePipeline|null} */
+	_ensureColorScalePipeline( device ) {
+
+		const buffer = this._gpuInputBuffers.color;
+		if ( ! device || ! buffer ) return null;
+
+		if ( ! this._colorScalePipeline ) {
+
+			this._colorScalePipeline = device.createComputePipeline( {
+				label: 'oidn-color-scale',
+				layout: 'auto',
+				compute: {
+					module: device.createShaderModule( { label: 'oidn-color-scale', code: COLOR_SCALE_WGSL } ),
+					entryPoint: 'main'
+				}
+			} );
+
+		}
+
+		if ( ! this._colorScaleUniform ) {
+
+			this._colorScaleUniform = device.createBuffer( {
+				label: 'oidn-color-scale-uniform',
+				size: 16, // min uniform binding size
+				usage: GPUBufferUsage.UNIFORM | GPUBufferUsage.COPY_DST
+			} );
+
+		}
+
+		if ( ! this._colorScaleBindGroup ) {
+
+			this._colorScaleBindGroup = device.createBindGroup( {
+				label: 'oidn-color-scale',
+				layout: this._colorScalePipeline.getBindGroupLayout( 0 ),
+				entries: [
+					{ binding: 0, resource: { buffer } },
+					{ binding: 1, resource: { buffer: this._colorScaleUniform } }
+				]
+			} );
+
+		}
+
+		return this._colorScalePipeline;
+
+	}
+
 	/**
 	 * Promise wrapper around tileExecute for the GPU path.
 	 * Outputs a GPUBuffer — copied to a staging buffer then converted to ImageData for the 2D canvas.
@@ -754,7 +890,7 @@ export class OIDNDenoiser extends EventDispatcher {
 
 						const f32 = new Float32Array( staging.getMappedRange() );
 						const tileImageData = new ImageData( clampedW, clampedH );
-						const exposure = this.getExposure();
+						const exposure = this._outputExposure();
 						const saturation = this.getSaturation();
 						const tmFn = TONE_MAP_FNS.get( this.getToneMapping() ) || TONE_MAP_FNS.get( ACESFilmicToneMapping );
 						const alpha = this._cachedAlpha;
@@ -856,7 +992,7 @@ export class OIDNDenoiser extends EventDispatcher {
 			const float32 = new Float32Array( stagingBuffer.getMappedRange() );
 
 			const imageData = new ImageData( width, height );
-			const exposure = this.getExposure();
+			const exposure = this._outputExposure();
 			const saturation = this.getSaturation();
 			const tmFn = TONE_MAP_FNS.get( this.getToneMapping() ) || TONE_MAP_FNS.get( ACESFilmicToneMapping );
 			const alpha = this._cachedAlpha;
@@ -962,6 +1098,7 @@ export class OIDNDenoiser extends EventDispatcher {
 		// TFJS tears down the cached backend's buffers/textures.
 		removeOidnTfjsBackend();
 		this._destroyGPUInputBuffers();
+		this._colorScalePipeline = null;
 
 		// Clean up DOM
 		if ( this.output?.parentNode ) {

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