rayzee 7.31.1 → 8.0.0

package/src/TSL/Displacement.js

@@ -1,14 +1,13 @@
-import { Fn, float, vec2, int, If, Loop, abs, normalize, dot, max } from 'three/tsl';
+import { Fn, float, vec2, int, If, Loop, abs, normalize, dot, max, uintBitsToFloat } from 'three/tsl';
 
 import { struct } from './patches.js';
-import { getDatafromStorageBuffer } from './Common.js';
+import { getDatafromStorageBuffer, TRI_STRIDE, instanceRows, instanceDirToWorld } from './Common.js';
 import { sampleDisplacementMap, bucketTexelSize, getLinearBucketTextures } from './TextureSampling.js';
 
 // Ray-displacement intersection configuration
 const MAX_MARCH_STEPS = 32;
 const MIN_MARCH_STEPS = 16;
 const BINARY_STEPS = 5;
-const TRI_STRIDE = 8;
 
 export const DisplacementResult = struct( {
 	hitPoint: 'vec3',
@@ -32,7 +31,7 @@ export const DisplacementResult = struct( {
  * We find dt where h_ray(dt) = h_surf(dt).
  */
 export const refineDisplacedIntersection = Fn( ( [
-	ray, hitInfo, triangleBuffer, material, bounceIndex
+	ray, hitInfo, triangleBuffer, material, bounceIndex, bvhBuffer, instanceLeaf
 ] ) => {
 
 	const resultHitPoint = hitInfo.hitPoint.toVar();
@@ -43,21 +42,32 @@ export const refineDisplacedIntersection = Fn( ( [
 	// Fetch triangle vertex data
 	const triIdx = hitInfo.triangleIndex;
 
-	const pA = getDatafromStorageBuffer( triangleBuffer, triIdx, int( 0 ), int( TRI_STRIDE ) ).xyz.toVar();
-	const pB = getDatafromStorageBuffer( triangleBuffer, triIdx, int( 1 ), int( TRI_STRIDE ) ).xyz;
-	const pC = getDatafromStorageBuffer( triangleBuffer, triIdx, int( 2 ), int( TRI_STRIDE ) ).xyz;
+	const pA = uintBitsToFloat( getDatafromStorageBuffer( triangleBuffer, triIdx, int( 0 ), int( TRI_STRIDE ) ).xyz ).toVar();
+	const pB = uintBitsToFloat( getDatafromStorageBuffer( triangleBuffer, triIdx, int( 1 ), int( TRI_STRIDE ) ).xyz );
+	const pC = uintBitsToFloat( getDatafromStorageBuffer( triangleBuffer, triIdx, int( 2 ), int( TRI_STRIDE ) ).xyz );
 
-	const uvData1 = getDatafromStorageBuffer( triangleBuffer, triIdx, int( 6 ), int( TRI_STRIDE ) ).toVar();
-	const uvData2 = getDatafromStorageBuffer( triangleBuffer, triIdx, int( 7 ), int( TRI_STRIDE ) );
+	const uvData1 = uintBitsToFloat( getDatafromStorageBuffer( triangleBuffer, triIdx, int( 3 ), int( TRI_STRIDE ) ) ).toVar();
+	const uvData2 = uintBitsToFloat( getDatafromStorageBuffer( triangleBuffer, triIdx, int( 4 ), int( TRI_STRIDE ) ).xy );
 
 	const uvA = uvData1.xy.toVar();
 	const uvB = uvData1.zw;
-	const uvC = uvData2.xy;
+	const uvC = uvData2;
 
-	// Compute tangent vectors from triangle edges + UV differences
+	// Compute tangent vectors from triangle edges + UV differences. The ray, the hit point and
+	// the normal are all in world space; a triangle that belongs to a placement is not, so its
+	// edges are moved before they are used, or the marching frame is half in each space.
 	const edge1 = pB.sub( pA ).toVar();
 	const edge2 = pC.sub( pA ).toVar();
 
+	If( instanceLeaf.greaterThanEqual( int( 0 ) ), () => {
+
+		const rows = instanceRows( bvhBuffer, instanceLeaf );
+		const r = { r0: rows[ 0 ].xyz, r1: rows[ 1 ].xyz, r2: rows[ 2 ].xyz };
+		edge1.assign( instanceDirToWorld( { ...r, v: edge1 } ) );
+		edge2.assign( instanceDirToWorld( { ...r, v: edge2 } ) );
+
+	} );
+
 	const dUV1 = uvB.sub( uvA ).toVar();
 	const dUV2 = uvC.sub( uvA ).toVar();
 	const det = dUV1.x.mul( dUV2.y ).sub( dUV2.x.mul( dUV1.y ) ).toVar();

package/src/TSL/EmissiveSampling.js

@@ -22,10 +22,17 @@ import {
 	cos,
 	acos,
 	atan,
+	uint,
+	uintBitsToFloat,
 } from 'three/tsl';
 
 import { struct } from './patches.js';
-import { MIN_PDF, getDatafromStorageBuffer, powerHeuristic, MATERIAL_SLOTS, MATERIAL_SLOT, computeDotProductsAniso } from './Common.js';
+import {
+	MIN_PDF, getDatafromStorageBuffer, powerHeuristic, MATERIAL_SLOTS, MATERIAL_SLOT,
+	computeDotProductsAniso, instanceRows, instanceNormalToWorld, instancePointToWorld,
+	unpackTriangleNormal, TRI_STRIDE
+} from './Common.js';
+import { TRI_MATERIAL_MASK } from '../EngineDefaults.js';
 import { getRandomSample1D, getRandomSample2D } from './Random.js';
 import { calculateMaterialPDFFromDots } from './LightsSampling.js';
 import { evaluateMaterialResponseFromDots } from './MaterialEvaluation.js';
@@ -272,7 +279,6 @@ export const isEmissive = Fn( ( [ material ] ) => {
 // TRIANGLE DATA ACCESS
 // ================================================================================
 
-const TRI_STRIDE = 8;
 const EMISSIVE_STRIDE = 2; // 2 vec4s per emissive entry
 
 export const TriangleData = struct( {
@@ -283,26 +289,40 @@ export const TriangleData = struct( {
 
 // Fetch triangle vertices from storage buffer
 // Returns data packed in a struct-like way
-export const fetchTriangleData = Fn( ( [ triangleIndex, triangleBuffer ] ) => {
-
-	// Positions
-	const pos0 = getDatafromStorageBuffer( triangleBuffer, triangleIndex, int( 0 ), int( TRI_STRIDE ) );
-	const pos1 = getDatafromStorageBuffer( triangleBuffer, triangleIndex, int( 1 ), int( TRI_STRIDE ) );
-	const pos2 = getDatafromStorageBuffer( triangleBuffer, triangleIndex, int( 2 ), int( TRI_STRIDE ) );
+/**
+ * A triangle's vertices and normals in WORLD space.
+ *
+ * Storage is per instance in object space, so `instanceLeaf` names the TLAS leaf whose
+ * transform brings it back out; pass -1 for geometry that is already in world space.
+ */
+export const fetchTriangleData = Fn( ( [ triangleIndex, triangleBuffer, bvhBuffer, instanceLeaf ] ) => {
+
+	// Positions carry their packed normal in .w
+	const pos0 = getDatafromStorageBuffer( triangleBuffer, triangleIndex, int( 0 ), int( TRI_STRIDE ) ).toVar();
+	const pos1 = getDatafromStorageBuffer( triangleBuffer, triangleIndex, int( 1 ), int( TRI_STRIDE ) ).toVar();
+	const pos2 = getDatafromStorageBuffer( triangleBuffer, triangleIndex, int( 2 ), int( TRI_STRIDE ) ).toVar();
+
+	const uvMat = getDatafromStorageBuffer( triangleBuffer, triangleIndex, int( 4 ), int( TRI_STRIDE ) );
+
+	const v0 = uintBitsToFloat( pos0.xyz ).toVar(), v1 = uintBitsToFloat( pos1.xyz ).toVar(), v2 = uintBitsToFloat( pos2.xyz ).toVar();
+	const n0 = unpackTriangleNormal( pos0.w ).toVar(), n1 = unpackTriangleNormal( pos1.w ).toVar(), n2 = unpackTriangleNormal( pos2.w ).toVar();
+
+	If( instanceLeaf.greaterThanEqual( int( 0 ) ), () => {
+
+		const rows = instanceRows( bvhBuffer, instanceLeaf );
+		v0.assign( instancePointToWorld( rows, v0 ) );
+		v1.assign( instancePointToWorld( rows, v1 ) );
+		v2.assign( instancePointToWorld( rows, v2 ) );
+		n0.assign( normalize( instanceNormalToWorld( rows, n0 ) ) );
+		n1.assign( normalize( instanceNormalToWorld( rows, n1 ) ) );
+		n2.assign( normalize( instanceNormalToWorld( rows, n2 ) ) );
 
-	// Normals
-	const norm0 = getDatafromStorageBuffer( triangleBuffer, triangleIndex, int( 3 ), int( TRI_STRIDE ) );
-	const norm1 = getDatafromStorageBuffer( triangleBuffer, triangleIndex, int( 4 ), int( TRI_STRIDE ) );
-	const norm2 = getDatafromStorageBuffer( triangleBuffer, triangleIndex, int( 5 ), int( TRI_STRIDE ) );
-
-	// Material index (stored in last vec4)
-	const uvMat = getDatafromStorageBuffer( triangleBuffer, triangleIndex, int( 7 ), int( TRI_STRIDE ) );
+	} );
 
 	// Return all data as a struct
 	return TriangleData( {
-		v0: pos0.xyz, v1: pos1.xyz, v2: pos2.xyz,
-		n0: norm0.xyz, n1: norm1.xyz, n2: norm2.xyz,
-		materialIndex: int( uvMat.z ),
+		v0, v1, v2, n0, n1, n2,
+		materialIndex: int( uvMat.z.bitAnd( uint( TRI_MATERIAL_MASK ) ) ),
 	} );
 
 } );
@@ -312,9 +332,10 @@ export const fetchTriangleData = Fn( ( [ triangleIndex, triangleBuffer ] ) => {
 // Uses same heuristic as sampleEmissiveTriangle for MIS consistency
 export const calculateEmissiveLightPdf = Fn( ( [
 	triangleIndex, hitDistance, rayDir, shadingPoint, triangleBuffer, materialBuffer, emissiveTotalPower,
+	bvhBuffer, instanceLeaf,
 ] ) => {
 
-	const triData = TriangleData.wrap( fetchTriangleData( triangleIndex, triangleBuffer ) );
+	const triData = TriangleData.wrap( fetchTriangleData( triangleIndex, triangleBuffer, bvhBuffer, instanceLeaf ) );
 	const area = triangleArea( triData.v0, triData.v1, triData.v2 );
 
 	// Targeted material read: only fetch emissive data (2 vec4s instead of full 27)
@@ -391,7 +412,7 @@ export const sampleEmissiveTriangle = Fn( ( [
 	rngState,
 	pixelCoord, resolution, frame, dimBase,
 	emissiveTriangleBuffer, emissiveVec4Offset, emissiveTriangleCount, emissiveTotalPower,
-	triangleBuffer,
+	triangleBuffer, bvhBuffer,
 ] ) => {
 
 	const result = EmissiveSample( {
@@ -423,9 +444,12 @@ export const sampleEmissiveTriangle = Fn( ( [
 		const samplePower = max( emissiveData0.g, float( 1e-10 ) );
 		const emission = emissiveData1.xyz;
 		const area = emissiveData1.w;
+		// Slot 3 carries the emitter's TLAS leaf; the selection pdf it used to hold is
+		// recomputed from power and the total, so the word was free.
+		const emissiveInstance = int( emissiveData0.a );
 
 		// Fetch triangle geometry
-		const triData = TriangleData.wrap( fetchTriangleData( triangleIndex, triangleBuffer ) );
+		const triData = TriangleData.wrap( fetchTriangleData( triangleIndex, triangleBuffer, bvhBuffer, emissiveInstance ) );
 
 		const xi = getRandomSample2D( pixelCoord, int( 0 ), dimBase.add( int( 3 ) ), rngState, resolution, frame ).toVar();
 
@@ -532,7 +556,7 @@ export const calculateEmissiveTriangleContributionDebug = Fn( ( [
 	pixelCoord, resolution, frame, dimBase,
 	emissiveBoost,
 	emissiveTriangleBuffer, emissiveVec4Offset, emissiveTriangleCount, emissiveTotalPower,
-	triangleBuffer,
+	triangleBuffer, bvhBuffer,
 	// Callback functions to avoid circular deps
 	traceShadowRayFn,
 	calculateRayOffsetFn,
@@ -553,7 +577,7 @@ export const calculateEmissiveTriangleContributionDebug = Fn( ( [
 		hitPoint, normal, rngState,
 		pixelCoord, resolution, frame, dimBase,
 		emissiveTriangleBuffer, emissiveVec4Offset, emissiveTriangleCount, emissiveTotalPower,
-		triangleBuffer,
+		triangleBuffer, bvhBuffer,
 	) );
 
 	If( emissiveSample.valid.and( emissiveSample.pdf.greaterThan( 0.0 ) ), () => {
@@ -614,7 +638,7 @@ export const calculateEmissiveTriangleContribution = Fn( ( [
 	pixelCoord, resolution, frame, dimBase,
 	emissiveBoost,
 	emissiveTriangleBuffer, emissiveVec4Offset, emissiveTriangleCount, emissiveTotalPower,
-	triangleBuffer,
+	triangleBuffer, bvhBuffer,
 	traceShadowRayFn,
 	calculateRayOffsetFn,
 ] ) => {
@@ -625,7 +649,7 @@ export const calculateEmissiveTriangleContribution = Fn( ( [
 		pixelCoord, resolution, frame, dimBase,
 		emissiveBoost,
 		emissiveTriangleBuffer, emissiveVec4Offset, emissiveTriangleCount, emissiveTotalPower,
-		triangleBuffer,
+		triangleBuffer, bvhBuffer,
 		traceShadowRayFn,
 		calculateRayOffsetFn,
 	) );

package/src/TSL/ExtendKernel.js

@@ -3,7 +3,7 @@
  */
 
 import {
-	Fn, uint,
+	Fn, uint, int,
 	If,
 	instanceIndex,
 	atomicLoad,
@@ -71,7 +71,8 @@ export function buildExtendKernel( params ) {
 			hitInfo.uv.x, hitInfo.uv.y,
 			hitInfo.normal,
 			uint( hitInfo.materialIndex ),
-			uint( hitInfo.meshIndex ),
+			// Biased by one: leaf 0 is real, so 0 has to mean "no instance".
+			uint( hitInfo.instanceLeaf.add( int( 1 ) ) ),
 		);
 
 	} );

package/src/TSL/LightBVHSampling.js

@@ -110,7 +110,7 @@ export const sampleLightBVHTriangle = Fn( ( [
 	lbvhBuffer,
 	emissiveTriangleBuffer,
 	emissiveVec4Offset,
-	triangleBuffer,
+	triangleBuffer, bvhBuffer,
 ] ) => {
 
 	const result = EmissiveSample( {
@@ -256,9 +256,10 @@ export const sampleLightBVHTriangle = Fn( ( [
 		const triangleIndex = int( emissiveData0.r );
 		const emission = emissiveData1.xyz;
 		const area = emissiveData1.w;
+		const emissiveInstance = int( emissiveData0.a );
 
 		// Fetch triangle geometry
-		const triData = TriangleData.wrap( fetchTriangleData( triangleIndex, triangleBuffer ) );
+		const triData = TriangleData.wrap( fetchTriangleData( triangleIndex, triangleBuffer, bvhBuffer, emissiveInstance ) );
 
 		const xi = getRandomSample2D( pixelCoord, int( 0 ), dimBase.add( int( 3 ) ), rngState, resolution, frame ).toVar();
 
@@ -361,7 +362,7 @@ export const sampleLightBVHTriangle = Fn( ( [
 // float per absolute triangleIndex (4 packed per vec4): the root→leaf left(0)/right(1) choices.
 export const calculateLightBVHPdf = Fn( ( [
 	triangleIndex, hitDistance, rayDir, shadingPoint,
-	lightBuffer, emissiveVec4Offset, reverseMapVec4Offset, triangleBuffer,
+	lightBuffer, emissiveVec4Offset, reverseMapVec4Offset, triangleBuffer, bvhBuffer,
 ] ) => {
 
 	const result = float( 0.0 ).toVar();
@@ -462,6 +463,7 @@ export const calculateLightBVHPdf = Fn( ( [
 			const leafTotalPower = max( d0.w, float( 1e-10 ) );
 
 			const targetPower = float( 0.0 ).toVar();
+			const targetInstance = int( - 1 ).toVar();
 			Loop( { start: int( 0 ), end: emissiveCount }, ( { i } ) => {
 
 				const entryIdx = emissiveStart.add( i );
@@ -469,6 +471,7 @@ export const calculateLightBVHPdf = Fn( ( [
 				If( int( emData0.r ).equal( triIdx ), () => {
 
 					targetPower.assign( max( emData0.g, float( 0.0 ) ) );
+					targetInstance.assign( int( emData0.a ) );
 					Break();
 
 				} );
@@ -478,7 +481,7 @@ export const calculateLightBVHPdf = Fn( ( [
 			selectionPdf.mulAssign( targetPower.div( leafTotalPower ) );
 
 			// Convert selection pdf → solid-angle measure using the SAME heuristic as the sampler.
-			const triData = TriangleData.wrap( fetchTriangleData( triIdx, triangleBuffer ) );
+			const triData = TriangleData.wrap( fetchTriangleData( triIdx, triangleBuffer, bvhBuffer, targetInstance ) );
 			If( useSphericalSampling( triData.v0, triData.v1, triData.v2, shadingPoint ), () => {
 
 				const solidAngle = sphericalTriangleSolidAngle( triData.v0, triData.v1, triData.v2, shadingPoint );

package/src/TSL/LightsDirect.js

@@ -22,10 +22,14 @@ import {
 	clamp,
 	smoothstep,
 	select,
+	uintBitsToFloat,
 } from 'three/tsl';
 
 import { Ray, ShadowMaterial, HitInfo } from './Struct.js';
-import { REC709_LUMINANCE_COEFFICIENTS, getShadowMaterial, getDatafromStorageBuffer } from './Common.js';
+import {
+	REC709_LUMINANCE_COEFFICIENTS, getShadowMaterial, getDatafromStorageBuffer, instanceRows,
+	instanceFaceNormalToWorld, TRI_STRIDE, getAlphaShadowsUniform, shadowFlagsSettle
+} from './Common.js';
 import { fresnelSchlickFloat, iorToFresnel0 } from './Fresnel.js';
 import { calculateBeerLawAbsorption } from './MaterialTransmission.js';
 import { getTransformedUV, sampleBucket } from './TextureSampling.js';
@@ -33,7 +37,8 @@ import { getTransformedUV, sampleBucket } from './TextureSampling.js';
 // Module-level state for alpha-cutout shadow testing.
 // Set by PathTracer before shade-graph construction.
 let _shadowAlbedoMaps = null;
-let _enableAlphaShadows = null;
+
+export { setAlphaShadowsUniform } from './Common.js';
 
 /**
  * Set the sRGB bucket texture node array for alpha-aware shadow rays (albedo alpha).
@@ -46,16 +51,6 @@ export function setShadowAlbedoMaps( buckets ) {
 
 }
 
-/**
- * Set the runtime uniform node that toggles alpha-cutout shadows.
- * @param {UniformNode} node - TSL int uniform (0 = disabled, 1 = enabled)
- */
-export function setAlphaShadowsUniform( node ) {
-
-	_enableAlphaShadows = node;
-
-}
-
 // ================================================================================
 // SHADOW RAY TRACING
 // ================================================================================
@@ -94,13 +89,11 @@ export const traceShadowRay = Fn( ( [
 
 		} );
 
-		// Opaque fast-path: check the per-triangle blocker flag (NORMAL_A.w, set at
-		// extraction time when alphaMode/transparent/transmission/opacity all indicate
-		// a fully opaque surface). Short-circuits the 7-slot getShadowMaterial fetch
-		// and the entire alpha/transmission/transparent decision tree below.
-		const TRI_STRIDE_SR = int( 8 );
-		const blocker = getDatafromStorageBuffer( triangleBuffer, shadowHit.triangleIndex, int( 3 ), TRI_STRIDE_SR ).w;
-		If( blocker.greaterThan( 0.5 ), () => {
+		// Opaque fast-path: check the per-triangle blocker bit, set at extraction time when
+		// alphaMode/transparent/transmission/opacity all indicate a fully opaque surface.
+		// Short-circuits the 7-slot getShadowMaterial fetch and the whole alpha decision tree.
+		const flags = getDatafromStorageBuffer( triangleBuffer, shadowHit.triangleIndex, int( 4 ), int( TRI_STRIDE ) ).z;
+		If( shadowFlagsSettle( flags ), () => {
 
 			transmittance.assign( 0.0 );
 			Break();
@@ -118,7 +111,8 @@ export const traceShadowRay = Fn( ( [
 		// ---------------------------------------------------------------
 		const alphaCutout = tslBool( false ).toVar();
 
-		if ( _enableAlphaShadows ) If( _enableAlphaShadows.equal( int( 1 ) ), () => {
+		const alphaShadows = getAlphaShadowsUniform();
+		if ( alphaShadows ) If( alphaShadows.equal( int( 1 ) ), () => {
 
 			// Sample texture alpha once (shared by MASK and BLEND paths).
 			// Deferred UV: barycentrics in shadowHit.uv, triangle index in shadowHit.triangleIndex.
@@ -131,10 +125,9 @@ export const traceShadowRay = Fn( ( [
 					const baryU = shadowHit.uv.x;
 					const baryV = shadowHit.uv.y;
 					const baryW = float( 1.0 ).sub( baryU ).sub( baryV );
-					const TRI_STRIDE = int( 8 );
-					const uvData1 = getDatafromStorageBuffer( triangleBuffer, shadowHit.triangleIndex, int( 6 ), TRI_STRIDE );
-					const uvData2 = getDatafromStorageBuffer( triangleBuffer, shadowHit.triangleIndex, int( 7 ), TRI_STRIDE );
-					const hitUV = uvData1.xy.mul( baryW ).add( uvData1.zw.mul( baryU ) ).add( uvData2.xy.mul( baryV ) );
+					const uvData1 = uintBitsToFloat( getDatafromStorageBuffer( triangleBuffer, shadowHit.triangleIndex, int( 3 ), int( TRI_STRIDE ) ) );
+					const uvData2 = uintBitsToFloat( getDatafromStorageBuffer( triangleBuffer, shadowHit.triangleIndex, int( 4 ), int( TRI_STRIDE ) ).xy );
+					const hitUV = uvData1.xy.mul( baryW ).add( uvData1.zw.mul( baryU ) ).add( uvData2.mul( baryV ) );
 					const albedoUV = getTransformedUV( { uv: hitUV, transform: shadowMaterial.albedoTransform } );
 					texAlpha.assign( sampleBucket( _shadowAlbedoMaps, shadowMaterial.albedoMapIndex, albedoUV ).a );
 
@@ -188,11 +181,19 @@ export const traceShadowRay = Fn( ( [
 			// Deferred geometric-normal compute — refetch triangle positions and
 			// derive the normal here so opaque/alpha-cutout shadow hits don't pay
 			// the cross+normalize cost in BVH traversal.
-			const TRI_STRIDE_N = int( 8 );
-			const pA = getDatafromStorageBuffer( triangleBuffer, shadowHit.triangleIndex, int( 0 ), TRI_STRIDE_N ).xyz;
-			const pB = getDatafromStorageBuffer( triangleBuffer, shadowHit.triangleIndex, int( 1 ), TRI_STRIDE_N ).xyz;
-			const pC = getDatafromStorageBuffer( triangleBuffer, shadowHit.triangleIndex, int( 2 ), TRI_STRIDE_N ).xyz;
-			const geomNormal = normalize( cross( pB.sub( pA ), pC.sub( pA ) ) );
+			const pA = uintBitsToFloat( getDatafromStorageBuffer( triangleBuffer, shadowHit.triangleIndex, int( 0 ), int( TRI_STRIDE ) ).xyz );
+			const pB = uintBitsToFloat( getDatafromStorageBuffer( triangleBuffer, shadowHit.triangleIndex, int( 1 ), int( TRI_STRIDE ) ).xyz );
+			const pC = uintBitsToFloat( getDatafromStorageBuffer( triangleBuffer, shadowHit.triangleIndex, int( 2 ), int( TRI_STRIDE ) ).xyz );
+			// Positions are in the blocker's object space; the cross product is a normal, so
+			// it rides the inverse-transpose back out rather than the forward matrix.
+			const objNormal = normalize( cross( pB.sub( pA ), pC.sub( pA ) ) ).toVar();
+			If( shadowHit.instanceLeaf.greaterThanEqual( int( 0 ) ), () => {
+
+				objNormal.assign( normalize( instanceFaceNormalToWorld( instanceRows( bvhBuffer, shadowHit.instanceLeaf ), objNormal ) ) );
+
+			} );
+
+			const geomNormal = objNormal;
 			shadowHit.normal.assign( geomNormal );
 
 			const entering = dot( dir, geomNormal ).lessThan( 0.0 );

package/src/TSL/ShadeKernel.js

@@ -56,7 +56,7 @@ import {
 	readTransparentCount,
 	readMisRayT,
 	readHitDistance, readHitBarycentrics, readHitNormal,
-	readHitMaterialIndex, readHitTriangleIndex,
+	readHitMaterialIndex, readHitTriangleIndex, readHitInstanceLeaf,
 	writeRayOriginMeta, writeRayDirFlags, writeRayThroughputPdf, writeRayRadiance,
 	writeGBuffer, writeGBufferHitDist, readGBuffer, gbDecodeNormalDepth,
 	readRayRadiance,
@@ -219,6 +219,7 @@ export function buildShadeKernel( params ) {
 		const hitUV = readHitBarycentrics( hitBufferRO, rayID ).toVar();
 		const hitMatIdx = readHitMaterialIndex( hitBufferRO, rayID ).toVar();
 		const hitTriIdx = readHitTriangleIndex( hitBufferRO, rayID ).toVar();
+		const hitInstance = readHitInstanceLeaf( hitBufferRO, rayID ).toVar();
 
 		// per-ray camera-bounce depth — advances ONLY on opaque scatter (free bounces don't); drives termination (maxBounces). Megakernel: effectiveBounces.
 		const cameraDepth = readPathBounces( rayBufferRW, rayID ).toVar();
@@ -620,7 +621,7 @@ export function buildShadeKernel( params ) {
 					boxTests: int( 0 ), triTests: int( 0 ),
 				} );
 				const dispResult = DisplacementResult.wrap( refineDisplacedIntersection(
-					dispRay, dispHit, triangleBuffer, material, bounceIndex,
+					dispRay, dispHit, triangleBuffer, material, bounceIndex, bvhBuffer, hitInstance,
 				) ).toVar();
 				samplingUV.assign( dispResult.uv );
 				displacedNormal.assign( dispResult.normal );
@@ -634,7 +635,7 @@ export function buildShadeKernel( params ) {
 		const uvTangent = vec4( 0.0 ).toVar();
 		If( material.normalMapIndex.greaterThanEqual( int( 0 ) ), () => {
 
-			uvTangent.assign( triangleUVTangent( triangleBuffer, int( hitTriIdx ), N, material.normalTransform ) );
+			uvTangent.assign( triangleUVTangent( triangleBuffer, int( hitTriIdx ), N, material.normalTransform, bvhBuffer, hitInstance ) );
 
 		} );
 
@@ -1024,7 +1025,7 @@ export function buildShadeKernel( params ) {
 
 							lightPdf.assign( calculateLightBVHPdf(
 								int( hitTriIdx ), misDist, direction, misOrigin,
-								lightBuffer, emissiveVec4Offset, reverseMapVec4Offset, triangleBuffer,
+								lightBuffer, emissiveVec4Offset, reverseMapVec4Offset, triangleBuffer, bvhBuffer,
 							) );
 
 						} ).Else( () => {
@@ -1032,6 +1033,7 @@ export function buildShadeKernel( params ) {
 							lightPdf.assign( calculateEmissiveLightPdf(
 								int( hitTriIdx ), misDist, direction, misOrigin,
 								triangleBuffer, materialBuffer, emissiveTotalPower,
+								bvhBuffer, hitInstance,
 							) );
 
 						} );
@@ -1217,7 +1219,7 @@ export function buildShadeKernel( params ) {
 							lightBuffer,
 							lightBuffer,
 							emissiveVec4Offset,
-							triangleBuffer,
+							triangleBuffer, bvhBuffer,
 						) );
 
 						// No rough-diffuse secondary-bounce skip here: dropping NEE while the emissive-hit
@@ -1274,7 +1276,7 @@ export function buildShadeKernel( params ) {
 							_pixelCoord, resolution, frame, dimBase,
 							emissiveBoost,
 							lightBuffer, emissiveVec4Offset, emissiveTriangleCount, emissiveTotalPower,
-							triangleBuffer,
+							triangleBuffer, bvhBuffer,
 							traceShadowRayWrapped,
 							calculateRayOffset,
 						);

package/src/TSL/Struct.js

@@ -122,6 +122,9 @@ export const HitInfo = struct( {
 	uv: 'vec2',
 	materialIndex: 'int',
 	meshIndex: 'int',
+	// TLAS leaf that owns the hit: triangles are stored per instance in object space, so
+	// anything that needs them in world space reads the transform back off this node.
+	instanceLeaf: 'int',
 	triangleIndex: 'int',
 	boxTests: 'int',
 	triTests: 'int',

package/src/TSL/TextureSampling.js

@@ -1,4 +1,4 @@
-import { Fn, wgslFn, float, vec2, vec3, vec4, int, If, normalize, cross, dot, length, sign, 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, uintBitsToFloat } from 'three/tsl';
 import { DataArrayTexture, LinearFilter } from 'three';
 
 import {
@@ -6,7 +6,7 @@ import {
 	MaterialSamples,
 	ExtMapResult,
 } from './Struct.js';
-import { getDatafromStorageBuffer } from './Common.js';
+import { getDatafromStorageBuffer, instanceRows, instanceDirToWorld, TRI_STRIDE } from './Common.js';
 import { TEXTURE_CONSTANTS } from '../EngineDefaults.js';
 
 // ================================================================================
@@ -405,15 +405,22 @@ const uvTransformJacobian = /*@__PURE__*/ wgslFn( `
  * @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 ] ) => {
+/**
+ * Tangent frame for a triangle, in world space.
+ *
+ * Positions are stored per instance in object space, so T and B come out in that space
+ * and are carried across before they meet the world-space geometric normal — otherwise
+ * the handedness test mixes two frames and normal maps light from the wrong side.
+ */
+export const triangleUVTangent = Fn( ( [ triangleBuffer, triIndex, geometryNormal, transform, bvhBuffer, instanceLeaf ] ) => {
 
-	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 S = int( TRI_STRIDE );
+	const pA = uintBitsToFloat( getDatafromStorageBuffer( triangleBuffer, triIndex, int( 0 ), S ).xyz );
+	const e1 = uintBitsToFloat( getDatafromStorageBuffer( triangleBuffer, triIndex, int( 1 ), S ).xyz ).sub( pA );
+	const e2 = uintBitsToFloat( 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 uvAB = uintBitsToFloat( getDatafromStorageBuffer( triangleBuffer, triIndex, int( 3 ), S ) );
+	const uvC = uintBitsToFloat( getDatafromStorageBuffer( triangleBuffer, triIndex, int( 4 ), S ).xy );
 	const d1 = uvAB.zw.sub( uvAB.xy );
 	const d2 = uvC.sub( uvAB.xy );
 
@@ -436,6 +443,14 @@ export const triangleUVTangent = Fn( ( [ triangleBuffer, triIndex, geometryNorma
 
 		} );
 
+		If( instanceLeaf.greaterThanEqual( int( 0 ) ), () => {
+
+			const rows = instanceRows( bvhBuffer, instanceLeaf );
+			T.assign( instanceDirToWorld( { r0: rows[ 0 ].xyz, r1: rows[ 1 ].xyz, r2: rows[ 2 ].xyz, v: T } ) );
+			B.assign( instanceDirToWorld( { r0: rows[ 0 ].xyz, r1: rows[ 1 ].xyz, r2: rows[ 2 ].xyz, v: B } ) );
+
+		} );
+
 		If( length( T ).greaterThan( 1e-12 ), () => {
 
 			result.assign( vec4( normalize( T ), sign( dot( cross( geometryNormal, T ), B ) ) ) );