rayzee 11.8.0 → 11.9.0

package/src/TSL/Displacement.js

@@ -1,33 +1,39 @@
 import { sceneResources } from './SceneResources.js';
-import { Fn, float, vec2, int, If, Loop, abs, normalize, dot, max, uintBitsToFloat } from 'three/tsl';
+import {
+	Fn, wgslFn, float, vec2, int, bool as tslBool, If, Loop, Break, abs, normalize, dot, cross, min, max, clamp, ceil, select, uintBitsToFloat,
+} from 'three/tsl';
 
 import { struct } from './patches.js';
 import { triangleRow, instanceRows, instanceDirToWorld } from './Common.js';
 import { sampleDisplacementMap, bucketTexelSize } from './TextureSampling.js';
 
-// Ray-displacement intersection configuration
-const MAX_MARCH_STEPS = 32;
-const MIN_MARCH_STEPS = 16;
-const BINARY_STEPS = 5;
+const MIN_MARCH_STEPS = 8;
+const MAX_MARCH_STEPS = 64;
+const MAX_BOUNCE_MARCH_STEPS = 16;
+const STEPS_PER_TEXEL = 0.25;
+const BINARY_STEPS = 6;
+const SLOPE_TEXELS = 1.5;
 
 export const DisplacementResult = struct( {
 	hitPoint: 'vec3',
 	uv: 'vec2',
 	normal: 'vec3',
-	height: 'float',
 } );
 
+// Texture-space UV per raw UV, per axis.
+const uvTransformScale = /*@__PURE__*/ wgslFn( `
+	fn uvTransformScale( transform: mat3x3f ) -> vec2f {
+		return max( vec2f( length( transform[0].xy ), length( transform[1].xy ) ), vec2f( 1e-6 ) );
+	}
+` );
+
 /**
  * Tessellation-free displacement mapping via analytical UV ray marching.
  *
- * Instead of projecting march points onto the triangle to get barycentrics (which
- * causes UV distortion from clamping), this computes the ray's UV trajectory
- * analytically using the triangle's actual tangent vectors (dP/du, dP/dv).
- *
  * The ray is parameterized as: P(dt) = hitPoint + rayDir * dt
  * UV along the ray:           UV(dt) = hitUV + dUV_dt * dt
  * Ray height above surface:   h_ray(dt) = dt * dot(rayDir, N)
- * Displaced surface height:   h_surf(dt) = (sample(UV(dt)) - 0.5) * scale
+ * Displaced surface height:   h_surf(dt) = sample(UV(dt)) * displacementScale + displacementBias, as three.js
  *
  * We find dt where h_ray(dt) = h_surf(dt).
  */
@@ -38,7 +44,6 @@ export const refineDisplacedIntersection = Fn( ( [
 	const resultHitPoint = hitInfo.hitPoint.toVar();
 	const resultUV = hitInfo.uv.toVar();
 	const resultNormal = hitInfo.normal.toVar();
-	const resultHeight = float( 0.0 ).toVar();
 
 	// Fetch triangle vertex data
 	const triIdx = hitInfo.triangleIndex;
@@ -83,16 +88,13 @@ export const refineDisplacedIntersection = Fn( ( [
 		const B = edge2.mul( dUV1.x ).sub( edge1.mul( dUV2.x ) ).mul( invDet ).toVar();
 		const N = hitInfo.normal.toVar();
 
-		const scale = material.displacementScale.div( float( 10.0 ) ); // Arbitrary scale factor for height
+		const scale = material.displacementScale;
+		const bias = material.displacementBias;
 		const rayDir = ray.direction;
 
-		// Compute UV velocity along the ray: dUV/dt
-		// Project ray direction onto surface tangent plane
 		const NdotD = dot( rayDir, N ).toVar();
 		const rayProj = rayDir.sub( N.mul( NdotD ) ).toVar();
 
-		// Solve: rayProj = du_dt * T + dv_dt * B
-		// Using the Gram matrix inverse of [T, B]
 		const TdotT = dot( T, T );
 		const TdotB = dot( T, B );
 		const BdotB = dot( B, B );
@@ -100,89 +102,60 @@ export const refineDisplacedIntersection = Fn( ( [
 
 		If( abs( detJ ).greaterThan( 1e-10 ), () => {
 
+			// Dual basis of (T, B): dot( Td, T ) = 1, dot( Td, B ) = 0, and likewise Bd.
 			const invDetJ = float( 1.0 ).div( detJ );
-			const rayProjDotT = dot( rayProj, T );
-			const rayProjDotB = dot( rayProj, B );
-
-			const du_dt = BdotB.mul( rayProjDotT ).sub( TdotB.mul( rayProjDotB ) ).mul( invDetJ );
-			const dv_dt = TdotT.mul( rayProjDotB ).sub( TdotB.mul( rayProjDotT ) ).mul( invDetJ );
-			const dUV_dt = vec2( du_dt, dv_dt ).toVar();
-
-			// Ray height change per unit dt: how fast the ray moves along the surface normal
-			const dh_ray_dt = NdotD.toVar();
-
-			// March range: displacement shell extends ±0.5*scale from base surface
-			// Compute dt range to traverse the full shell
-			const absNdotD = max( abs( dh_ray_dt ), 0.001 );
-			const dtShell = scale.div( absNdotD ).toVar();
+			const Td = T.mul( BdotB ).sub( B.mul( TdotB ) ).mul( invDetJ ).toVar();
+			const Bd = B.mul( TdotT ).sub( T.mul( TdotB ) ).mul( invDetJ ).toVar();
+			const dUV_dt = vec2( dot( rayProj, Td ), dot( rayProj, Bd ) ).toVar();
 
-			// Adaptive step count: full steps on primary ray, half on deeper bounces
-			const marchSteps = int( bounceIndex.equal( int( 0 ) ).select(
-				int( MAX_MARCH_STEPS ), int( MIN_MARCH_STEPS )
-			) ).toVar();
+			// +1 when the ray arrives from the side N points to.
+			const side = select( NdotD.lessThan( 0.0 ), float( 1.0 ), float( - 1.0 ) ).toVar();
+			const under = ( dt, height ) => dt.mul( NdotD ).sub( height.mul( scale ).add( bias ) ).mul( side ).lessThanEqual( 0.0 );
+			const heightAt = uv => sampleDisplacementMap( material.displacementMapIndex, uv, material.displacementTransform );
 
-			// Start from above the shell, march through
-			const dtStart = dtShell.negate().toVar();
-			const dtEnd = dtShell;
-			const dtStep = dtEnd.sub( dtStart ).div( float( marchSteps ) ).toVar();
+			// Enter the shell [bias, bias + scale] on the ray's side, never behind the ray's origin.
+			const top = max( bias, bias.add( scale ) );
+			const bottom = min( bias, bias.add( scale ) );
+			const slope = side.negate().mul( max( abs( NdotD ), 0.001 ) );
+			const dtStart = max( select( side.greaterThan( 0.0 ), top, bottom ).div( slope ), hitInfo.dst.negate() ).toVar();
+			const dtEnd = select( side.greaterThan( 0.0 ), bottom, top ).div( slope ).toVar();
 
-			// Track for binary refinement
-			const prevDt = dtStart.toVar();
-			const currDt = dtStart.toVar();
-			const found = int( 0 ).toVar();
+			// One step per few texels the ray crosses, so a grazing ray does not step over the gaps.
+			const texelsPerUV = uvTransformScale( { transform: material.displacementTransform } )
+				.div( bucketTexelSize( sceneResources( builder ).linearBuckets, material.displacementMapIndex ) ).toVar();
+			const texelsCrossed = dUV_dt.mul( texelsPerUV ).length().mul( dtEnd.sub( dtStart ) );
+			const maxSteps = select( bounceIndex.equal( int( 0 ) ), float( MAX_MARCH_STEPS ), float( MAX_BOUNCE_MARCH_STEPS ) );
+			const marchSteps = select( dtEnd.greaterThan( dtStart ),
+				int( clamp( ceil( texelsCrossed.mul( STEPS_PER_TEXEL ) ), float( MIN_MARCH_STEPS ), maxSteps ) ), int( 0 ) ).toVar();
+			const dtStep = dtEnd.sub( dtStart ).div( max( float( marchSteps ), 1.0 ) ).toVar();
 
-			// Linear march through displacement shell
-			Loop( { start: int( 0 ), end: marchSteps, type: 'int', condition: '<' }, ( { i } ) => {
+			const loDt = dtStart.toVar();
+			const hiDt = dtStart.toVar();
+			const found = tslBool( false ).toVar();
 
-				If( found.equal( int( 0 ) ), () => {
+			Loop( { start: int( 1 ), end: marchSteps.add( 1 ), type: 'int', condition: '<' }, ( { i } ) => {
 
-					const dt = dtStart.add( dtStep.mul( float( i ) ) ).toVar();
+				const dt = dtStart.add( dtStep.mul( float( i ) ) ).toVar();
 
-					// UV at this point along the ray
-					const marchUV = hitInfo.uv.add( dUV_dt.mul( dt ) );
+				If( under( dt, heightAt( hitInfo.uv.add( dUV_dt.mul( dt ) ) ) ), () => {
 
-					// Ray height above base surface at this dt
-					const rayHeight = dt.mul( dh_ray_dt );
-
-					// Displaced surface height
-					const heightSample = sampleDisplacementMap(
-						material.displacementMapIndex, marchUV, material.displacementTransform,
-					);
-					const surfaceHeight = heightSample.sub( 0.5 ).mul( scale );
-
-					// Ray crosses below displaced surface → intersection
-					If( rayHeight.lessThanEqual( surfaceHeight ).and( i.greaterThan( int( 0 ) ) ), () => {
-
-						found.assign( 1 );
-						currDt.assign( dt );
-
-					} ).Else( () => {
-
-						prevDt.assign( dt );
-
-					} );
+					found.assign( true );
+					hiDt.assign( dt );
+					Break();
 
 				} );
 
-			} );
+				loDt.assign( dt );
 
-			// Binary refinement
-			If( found.equal( int( 1 ) ), () => {
+			} );
 
-				const loDt = prevDt.toVar();
-				const hiDt = currDt.toVar();
+			If( found, () => {
 
 				Loop( { start: int( 0 ), end: int( BINARY_STEPS ), type: 'int', condition: '<' }, () => {
 
 					const midDt = loDt.add( hiDt ).mul( 0.5 ).toVar();
-					const midUV = hitInfo.uv.add( dUV_dt.mul( midDt ) );
-					const midRayHeight = midDt.mul( dh_ray_dt );
-					const midSample = sampleDisplacementMap(
-						material.displacementMapIndex, midUV, material.displacementTransform,
-					);
-					const midSurfHeight = midSample.sub( 0.5 ).mul( scale );
 
-					If( midRayHeight.lessThanEqual( midSurfHeight ), () => {
+					If( under( midDt, heightAt( hitInfo.uv.add( dUV_dt.mul( midDt ) ) ) ), () => {
 
 						hiDt.assign( midDt );
 
@@ -194,40 +167,20 @@ export const refineDisplacedIntersection = Fn( ( [
 
 				} );
 
-				// Final intersection
 				const finalDt = loDt.add( hiDt ).mul( 0.5 ).toVar();
 				const finalUV = hitInfo.uv.add( dUV_dt.mul( finalDt ) ).toVar();
-				const finalPoint = hitInfo.hitPoint.add( rayDir.mul( finalDt ) );
-
-				const finalHeight = sampleDisplacementMap(
-					material.displacementMapIndex, finalUV, material.displacementTransform,
-				);
-				const displacedHeight = finalHeight.sub( 0.5 ).mul( scale );
-
-				// Compute displaced normal from height-field gradients using UV tangent vectors.
-				// Finite-difference step = one texel of the SELECTED bucket array's real dimensions.
-				const texel = bucketTexelSize( sceneResources( builder ).linearBuckets, material.displacementMapIndex ).toVar();
-				const hC = finalHeight;
-				const hU = sampleDisplacementMap(
-					material.displacementMapIndex, finalUV.add( vec2( texel.x, 0.0 ) ), material.displacementTransform,
-				);
-				const hV = sampleDisplacementMap(
-					material.displacementMapIndex, finalUV.add( vec2( 0.0, texel.y ) ), material.displacementTransform,
-				);
-
-				// Perturb normal using actual tangent/bitangent from UV parameterization
-				const Tn = normalize( T ).toVar();
-				const Bn = normalize( B ).toVar();
-				const gradU = hU.sub( hC ).mul( scale );
-				const gradV = hV.sub( hC ).mul( scale );
-				const displacedNormal = normalize(
-					N.sub( Tn.mul( gradU ) ).sub( Bn.mul( gradV ) )
-				);
-
-				resultHitPoint.assign( finalPoint );
+
+				// Central differences over a few texels: an 8-bit map's steps make one-texel slopes flicker.
+				const step = vec2( SLOPE_TEXELS ).div( texelsPerUV ).toVar();
+				const dhdu = heightAt( finalUV.add( vec2( step.x, 0.0 ) ) ).sub( heightAt( finalUV.sub( vec2( step.x, 0.0 ) ) ) ).mul( scale ).div( step.x.mul( 2.0 ) );
+				const dhdv = heightAt( finalUV.add( vec2( 0.0, step.y ) ) ).sub( heightAt( finalUV.sub( vec2( 0.0, step.y ) ) ) ).mul( scale ).div( step.y.mul( 2.0 ) );
+				resultNormal.assign( normalize( N.sub( Td.mul( dhdu ) ).sub( Bd.mul( dhdv ) ) ) );
+
+				// A point behind the base triangle goes up onto its plane: rays spawned below it would hit it.
+				const faceN = normalize( cross( Td, Bd ) );
+				const moveDir = select( finalDt.greaterThan( 0.0 ), rayDir.sub( faceN.mul( dot( rayDir, faceN ) ) ), rayDir );
+				resultHitPoint.assign( hitInfo.hitPoint.add( moveDir.mul( finalDt ) ) );
 				resultUV.assign( finalUV );
-				resultNormal.assign( displacedNormal );
-				resultHeight.assign( displacedHeight );
 
 			} );
 
@@ -235,6 +188,6 @@ export const refineDisplacedIntersection = Fn( ( [
 
 	} );
 
-	return DisplacementResult( { hitPoint: resultHitPoint, uv: resultUV, normal: resultNormal, height: resultHeight } );
+	return DisplacementResult( { hitPoint: resultHitPoint, uv: resultUV, normal: resultNormal } );
 
 } );

package/src/TSL/LightsDirect.js

@@ -2,7 +2,7 @@
 // Direct lighting calculations including shadow ray tracing
 // and contribution calculations for all light types.
 
-import { sceneResources } from './SceneResources.js';
+import { sceneResources, usesTransmissionMaps } from './SceneResources.js';
 import {
 	Fn,
 	float,
@@ -30,6 +30,7 @@ import { Ray, ShadowMaterial, HitInfo } from './Struct.js';
 import {
 	REC709_LUMINANCE_COEFFICIENTS, getShadowMaterial, instanceRows,
 	instanceFaceNormalToWorld, triangleRow, shadowFlagsSettle, offsetRayOrigin,
+	getDatafromStorageBuffer, MATERIAL_SLOT, MATERIAL_SLOTS,
 } from './Common.js';
 import { fresnelDielectric } from './Fresnel.js';
 import { calculateBeerLawAbsorption } from './MaterialTransmission.js';
@@ -49,7 +50,8 @@ const makeTraceShadowRay = ( refractiveBlocks ) => Fn( ( [
 	materialBuffer,
 ], builder ) => {
 
-	const { alphaShadows, shadowAlbedoMaps } = sceneResources( builder );
+	const { alphaShadows, shadowAlbedoMaps, linearBuckets } = sceneResources( builder );
+	const transmissionMaps = ! refractiveBlocks && usesTransmissionMaps( builder );
 	const transmittance = float( 1.0 ).toVar();
 	const rayOrigin = origin.toVar();
 	const remainingDist = float( maxDist ).toVar();
@@ -88,6 +90,19 @@ const makeTraceShadowRay = ( refractiveBlocks ) => Fn( ( [
 		// Fetch material for the hit surface (thin reader: 7 slots instead of 27)
 		const shadowMaterial = ShadowMaterial.wrap( getShadowMaterial( shadowHit.materialIndex, materialBuffer ) );
 
+		// The hit's texture coordinates through the albedo transform, which Shade reads the extension maps with too.
+		const hitTextureUV = () => {
+
+			const baryU = shadowHit.uv.x;
+			const baryV = shadowHit.uv.y;
+			const baryW = float( 1.0 ).sub( baryU ).sub( baryV );
+			const uvData1 = uintBitsToFloat( triangleRow( triangleBuffer, shadowHit.triangleIndex, 3 ) );
+			const uvData2 = uintBitsToFloat( triangleRow( triangleBuffer, shadowHit.triangleIndex, 4 ).xy );
+			const hitUV = uvData1.xy.mul( baryW ).add( uvData1.zw.mul( baryU ) ).add( uvData2.mul( baryV ) );
+			return getTransformedUV( { uv: hitUV, transform: shadowMaterial.albedoTransform } );
+
+		};
+
 		// ---------------------------------------------------------------
 		// Alpha-cutout handling (MASK / BLEND with albedo texture alpha)
 		// Gated by runtime uniform + alphaMode check — zero overhead for opaque materials.
@@ -106,14 +121,7 @@ const makeTraceShadowRay = ( refractiveBlocks ) => Fn( ( [
 
 				If( shadowMaterial.albedoMapIndex.greaterThanEqual( int( 0 ) ), () => {
 
-					const baryU = shadowHit.uv.x;
-					const baryV = shadowHit.uv.y;
-					const baryW = float( 1.0 ).sub( baryU ).sub( baryV );
-					const uvData1 = uintBitsToFloat( triangleRow( triangleBuffer, shadowHit.triangleIndex, 3 ) );
-					const uvData2 = uintBitsToFloat( triangleRow( triangleBuffer, shadowHit.triangleIndex, 4 ).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 );
+					texAlpha.assign( sampleBucket( shadowAlbedoMaps, shadowMaterial.albedoMapIndex, hitTextureUV() ).a );
 
 				} );
 
@@ -167,6 +175,20 @@ const makeTraceShadowRay = ( refractiveBlocks ) => Fn( ( [
 
 		} : () => {
 
+			let transmission = shadowMaterial.transmission;
+			if ( transmissionMaps ) {
+
+				// glTF's transmission is the factor × the map's R: where the map is black the surface is opaque.
+				transmission = transmission.toVar();
+				const mapIndex = int( getDatafromStorageBuffer( materialBuffer, shadowHit.materialIndex, int( MATERIAL_SLOT.EXT_MAP_INDICES_A ), int( MATERIAL_SLOTS ) ).r ).toVar();
+				If( mapIndex.greaterThanEqual( int( 0 ) ), () => {
+
+					transmission.mulAssign( sampleBucket( linearBuckets, mapIndex, hitTextureUV() ).r );
+
+				} );
+
+			}
+
 			// 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.
@@ -204,7 +226,7 @@ const makeTraceShadowRay = ( refractiveBlocks ) => Fn( ( [
 			// Shadow rays go straight through, so both faces see the outside-in angle and eta.
 			const fresnel = fresnelDielectric( abs( dot( dir, N ) ), max( shadowMaterial.ior, 1.0 ) );
 
-			const matTransmittance = float( 1.0 ).sub( fresnel ).mul( shadowMaterial.transmission );
+			const matTransmittance = float( 1.0 ).sub( fresnel ).mul( transmission );
 			transmittance.mulAssign( matTransmittance );
 
 			// Early exit if almost no light passes through

package/src/TSL/SceneResources.js

@@ -13,6 +13,7 @@
  * @property {?Node} alphaShadows - int uniform, 1 = shadow rays test texture alpha; null = never
  * @property {?Object<string, boolean>} materialLayers - the MATERIAL_LAYERS some material uses; null = all of them
  * @property {boolean} [lightRadius] - some point or spot light has a radius (path tracing only); false = all are points
+ * @property {boolean} [transmissionMaps] - some material has a transmission map; false = shadow rays never sample one
  */
 
 import { context } from 'three/tsl';
@@ -60,3 +61,10 @@ export function usesLightRadius( builder ) {
 	return builder.context[ KEY ]?.lightRadius ?? true;
 
 }
+
+/** Whether the kernel being built has shadow rays sample transmission maps. Outside a scene kernel (a test) it does. */
+export function usesTransmissionMaps( builder ) {
+
+	return builder.context[ KEY ]?.transmissionMaps ?? true;
+
+}

package/src/TSL/ShadeKernel.js

@@ -917,7 +917,7 @@ export function buildShadeKernel( params ) {
 		const displacedNormal = N.toVar();
 		If(
 			material.displacementMapIndex.greaterThanEqual( int( 0 ) )
-				.and( material.displacementScale.greaterThan( 0.0 ) ),
+				.and( material.displacementScale.notEqual( 0.0 ) ),
 			() => {
 
 				const dispRay = Ray( { origin, direction } );
@@ -1003,7 +1003,7 @@ export function buildShadeKernel( params ) {
 		const albedo = matSamples.albedo.toVar();
 		If(
 			material.displacementMapIndex.greaterThanEqual( int( 0 ) )
-				.and( material.displacementScale.greaterThan( 0.0 ) ),
+				.and( material.displacementScale.notEqual( 0.0 ) ),
 			() => {
 
 				N.assign( normalize( displacedNormal.add( matSamples.normal.sub( normalize( hitNormal ) ) ) ) );

package/src/TSL/Struct.js

@@ -36,6 +36,7 @@ export const RayTracingMaterial = struct( {
 	bumpMapIndex: 'int',
 	bumpScale: 'float',
 	displacementScale: 'float',
+	displacementBias: 'float',
 	metalnessMapIndex: 'int',
 	roughnessMapIndex: 'int',
 	displacementMapIndex: 'int',

package/src/managers/MaterialDataManager.js

@@ -342,6 +342,16 @@ export class MaterialDataManager {
 
 	}
 
+	/** Whether some material has a transmission map: only then do shadow rays sample one. */
+	hasTransmissionMaps() {
+
+		const data = this.materialStorageAttr?.array;
+		if ( ! data ) return false;
+		for ( let i = 0; i < this.materialCount; i ++ ) if ( data[ i * M.FLOATS_PER_MATERIAL + M.TRANSMISSION_MAP_INDEX ] >= 0 ) return true;
+		return false;
+
+	}
+
 	/**
 	 * Where a material property's value came from, as a MATERIAL_VALUE_SOURCE. `default` means the
 	 * model never said and the engine filled it in.
@@ -503,6 +513,7 @@ export class MaterialDataManager {
 				break;
 			case 'bumpScale': data[ stride + M.BUMP_SCALE ] = value; break;
 			case 'displacementScale': data[ stride + M.DISPLACEMENT_SCALE ] = value; break;
+			case 'displacementBias': data[ stride + M.DISPLACEMENT_BIAS ] = value; break;
 			case 'subsurface': data[ stride + M.SUBSURFACE ] = value; break;
 			case 'subsurfaceRadiusScale': data[ stride + M.SUBSURFACE_RADIUS_SCALE ] = value; break;
 			case 'subsurfaceAnisotropy': data[ stride + M.SUBSURFACE_ANISOTROPY ] = value; break;