rayzee 5.4.1 → 5.4.2

package/package.json

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

package/src/Processor/GeometryExtractor.js

@@ -618,7 +618,22 @@ export class GeometryExtractor {
 		this.triangleData[ offset + TRIANGLE_DATA_LAYOUT.NORMAL_A_OFFSET + 0 ] = normalA.x;
 		this.triangleData[ offset + TRIANGLE_DATA_LAYOUT.NORMAL_A_OFFSET + 1 ] = normalA.y;
 		this.triangleData[ offset + TRIANGLE_DATA_LAYOUT.NORMAL_A_OFFSET + 2 ] = normalA.z;
-		this.triangleData[ offset + TRIANGLE_DATA_LAYOUT.NORMAL_A_OFFSET + 3 ] = 0; // vec4 padding
+		// Repurposed padding: opaque-blocker fast-path flag for shadow rays.
+		// 1.0 = surface fully blocks light (no alpha, transmission, or transparency) →
+		//       traceShadowRay can skip the 7-slot getShadowMaterial fetch.
+		// 0.0 = requires full material evaluation.
+		{
+
+			const mat = this.materials[ materialIndex ];
+			const isOpaqueBlocker = mat
+				&& ( mat.alphaMode | 0 ) === 0
+				&& ( mat.transparent | 0 ) === 0
+				&& ( mat.transmission || 0 ) === 0
+				&& ( mat.opacity ?? 1 ) >= 1
+				? 1.0 : 0.0;
+			this.triangleData[ offset + TRIANGLE_DATA_LAYOUT.NORMAL_A_OFFSET + 3 ] = isOpaqueBlocker;
+
+		}
 
 		this.triangleData[ offset + TRIANGLE_DATA_LAYOUT.NORMAL_B_OFFSET + 0 ] = normalB.x;
 		this.triangleData[ offset + TRIANGLE_DATA_LAYOUT.NORMAL_B_OFFSET + 1 ] = normalB.y;
@@ -628,7 +643,9 @@ export class GeometryExtractor {
 		this.triangleData[ offset + TRIANGLE_DATA_LAYOUT.NORMAL_C_OFFSET + 0 ] = normalC.x;
 		this.triangleData[ offset + TRIANGLE_DATA_LAYOUT.NORMAL_C_OFFSET + 1 ] = normalC.y;
 		this.triangleData[ offset + TRIANGLE_DATA_LAYOUT.NORMAL_C_OFFSET + 2 ] = normalC.z;
-		this.triangleData[ offset + TRIANGLE_DATA_LAYOUT.NORMAL_C_OFFSET + 3 ] = 0; // vec4 padding
+		// Repurposed padding: per-triangle side flag (0=front, 1=back, 2=double).
+		// Lets BVH traversal do side culling without a material-buffer read per hit.
+		this.triangleData[ offset + TRIANGLE_DATA_LAYOUT.NORMAL_C_OFFSET + 3 ] = this.materials[ materialIndex ]?.side ?? 0;
 
 		// UVs and material index (2 vec4s = 8 floats)
 		// First vec4: uvA.x, uvA.y, uvB.x, uvB.y

package/src/Stages/PathTracer.js

@@ -114,6 +114,19 @@ export class PathTracer extends RenderStage {
 		// Initialize material data manager
 		this.materialData = new MaterialDataManager( this.sdfs );
 		this.materialData.callbacks.onReset = () => this.reset();
+		// Triangle data carries the per-triangle `side` flag (NORMAL_C.w). The
+		// authoritative CPU array is triangleStorageAttr.array (not sdfs.triangleData,
+		// which isn't populated on the PathTracerApp build path). The patch mutates
+		// the array in place — only a dirty flag is needed for GPU re-upload.
+		this.materialData.callbacks.getTriangleData = () => ( {
+			array: this.triangleStorageAttr?.array,
+			count: this.triangleCount,
+		} );
+		this.materialData.callbacks.onTriangleDataChanged = () => {
+
+			if ( this.triangleStorageAttr ) this.triangleStorageAttr.needsUpdate = true;
+
+		};
 
 		// Initialize environment manager
 		this.environment = new EnvironmentManager( this.scene, this.uniforms );

package/src/TSL/BVHTraversal.js

@@ -224,28 +224,34 @@ export const traverseBVH = Fn( ( [
 						const u = triResult.y;
 						const v = triResult.z;
 
-						// Fetch normals + material data for visibility check (4 reads)
+						// Fetch normals for side-culling (3 reads). Slot 7 (uvData2,
+						// carries matIdx + meshIndex) is deferred to post-traversal —
+						// it's only needed for the one winning triangle, not per candidate.
+						// normalCData.w carries the per-triangle side flag (0/1/2).
 						const nA = getDatafromStorageBuffer( triangleBuffer, triIndex, int( 3 ), int( TRI_STRIDE ) ).xyz;
 						const nB = getDatafromStorageBuffer( triangleBuffer, triIndex, int( 4 ), int( TRI_STRIDE ) ).xyz;
-						const nC = getDatafromStorageBuffer( triangleBuffer, triIndex, int( 5 ), int( TRI_STRIDE ) ).xyz;
-						const uvData2 = getDatafromStorageBuffer( triangleBuffer, triIndex, int( 7 ), int( TRI_STRIDE ) );
-
-						const matIdx = int( uvData2.z );
+						const normalCData = getDatafromStorageBuffer( triangleBuffer, triIndex, int( 5 ), int( TRI_STRIDE ) );
+						const nC = normalCData.xyz;
+						const side = int( normalCData.w ).toVar();
 
 						// Interpolate normal
 						const w = float( 1.0 ).sub( u ).sub( v );
 						const normal = normalize( nA.mul( w ).add( nB.mul( u ) ).add( nC.mul( v ) ) ).toVar();
 
-						// Side culling check (per-mesh visibility handled at BLAS-pointer level)
-						If( passesSideCulling( matIdx, rayDirection, normal, materialBuffer ), () => {
+						// Side culling (inline; per-mesh visibility is at the BLAS-pointer level).
+						// 0=front (reject back-facing), 1=back (reject front-facing), 2=double (pass).
+						const rayDotNormal = rayDirection.dot( normal );
+						const sidePass = side.equal( int( 2 ) )
+							.or( side.equal( int( 0 ) ).and( rayDotNormal.lessThan( - 0.0001 ) ) )
+							.or( side.equal( int( 1 ) ).and( rayDotNormal.greaterThan( 0.0001 ) ) );
+						If( sidePass, () => {
 
 							closestHit.didHit.assign( true );
 							closestHit.dst.assign( t );
 							closestHit.normal.assign( normal );
-							closestHit.materialIndex.assign( matIdx );
-							closestHit.meshIndex.assign( int( uvData2.w ) );
 
-							// Defer hitPoint + UV computation to post-traversal
+							// Defer materialIndex/meshIndex/hitPoint/UV to post-traversal
+							// (all re-derived from closestTriIdx with a single uvData2 fetch below).
 							closestTriIdx.assign( triIndex );
 							closestU.assign( u );
 							closestV.assign( v );
@@ -324,7 +330,7 @@ export const traverseBVH = Fn( ( [
 
 	} );
 
-	// Deferred: compute hitPoint and UVs once for the final closest hit
+	// Deferred: compute hitPoint, UVs, and fetch matIdx/meshIndex once for the final closest hit
 	If( closestHit.didHit, () => {
 
 		closestHit.hitPoint.assign( ray.origin.add( ray.direction.mul( closestHit.dst ) ) );
@@ -335,6 +341,8 @@ export const traverseBVH = Fn( ( [
 		closestHit.uv.assign(
 			uvData1.xy.mul( w ).add( uvData1.zw.mul( closestU ) ).add( uvData2.xy.mul( closestV ) )
 		);
+		closestHit.materialIndex.assign( int( uvData2.z ) );
+		closestHit.meshIndex.assign( int( uvData2.w ) );
 		closestHit.triangleIndex.assign( closestTriIdx );
 
 	} );

package/src/TSL/LightsDirect.js

@@ -130,6 +130,19 @@ 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 ), () => {
+
+			transmittance.assign( 0.0 );
+			Break();
+
+		} );
+
 		// Fetch material for the hit surface (thin reader: 7 slots instead of 27)
 		const shadowMaterial = ShadowMaterial.wrap( getShadowMaterial( shadowHit.materialIndex, materialBuffer ) );
 

package/src/TSL/TextureSampling.js

@@ -281,7 +281,7 @@ export const processBump = Fn( ( [ bumpMaps, currentNormal, material, uvCache ]
 
 	const result = currentNormal.toVar();
 
-	If( material.bumpMapIndex.greaterThanEqual( int( 0 ) ), () => {
+	If( material.bumpMapIndex.greaterThanEqual( int( 0 ) ).and( material.bumpScale.greaterThan( 0.0 ) ), () => {
 
 		// Approximate texel size
 		const texelSize = vec2( 1.0 / 1024.0 ).toVar();

package/src/managers/MaterialDataManager.js

@@ -9,9 +9,16 @@
 
 import { StorageInstancedBufferAttribute } from 'three/webgpu';
 import { storage } from 'three/tsl';
-import { TEXTURE_CONSTANTS, MATERIAL_DATA_LAYOUT as M } from '../EngineDefaults.js';
+import { MATERIAL_DATA_LAYOUT as M, TRIANGLE_DATA_LAYOUT as T } from '../EngineDefaults.js';
 
 const PIXELS_PER_MATERIAL = M.SLOTS_PER_MATERIAL;
+// Per-triangle float offsets used by _patchTriangleSideForMaterial / _patchTriangleBlockerForMaterial.
+const TRI_MAT_IDX_OFFSET = T.UV_C_MAT_OFFSET + 2; // uvData2.z in shader
+const TRI_SIDE_OFFSET = T.NORMAL_C_OFFSET + 3; // normalCData.w in shader
+const TRI_BLOCKER_OFFSET = T.NORMAL_A_OFFSET + 3; // nA.w in shader (opaque-blocker fast path)
+
+// Material properties that affect the shadow-ray opaque-blocker flag.
+const BLOCKER_PROPS = new Set( [ 'transmission', 'transparent', 'opacity', 'alphaMode' ] );
 
 export class MaterialDataManager {
 
@@ -41,7 +48,7 @@ export class MaterialDataManager {
 
 		/**
 		 * Optional callbacks set by the owning stage.
-		 * @type {{ onReset?: Function, onFeaturesChanged?: Function }}
+		 * @type {{ onReset?: Function, onFeaturesChanged?: Function, getTriangleData?: Function, onTriangleDataChanged?: Function }}
 		 */
 		this.callbacks = {};
 
@@ -275,7 +282,11 @@ export class MaterialDataManager {
 			case 'clearcoat': data[ stride + M.CLEARCOAT ] = value; break;
 			case 'clearcoatRoughness': data[ stride + M.CLEARCOAT_ROUGHNESS ] = value; break;
 			case 'opacity': data[ stride + M.OPACITY ] = value; break;
-			case 'side': data[ stride + M.SIDE ] = value; break;
+			case 'side': data[ stride + M.SIDE ] = value;
+				// Side is also mirrored into per-triangle data (NORMAL_C.w) so BVH
+				// traversal can do side culling without reading the material buffer.
+				this._patchTriangleSideForMaterial( materialIndex, value );
+				break;
 			case 'transparent': data[ stride + M.TRANSPARENT ] = value; break;
 			case 'alphaTest': data[ stride + M.ALPHA_TEST ] = value; break;
 			case 'alphaMode': data[ stride + M.ALPHA_MODE ] = value; break;
@@ -304,6 +315,13 @@ export class MaterialDataManager {
 
 		this.materialStorageAttr.needsUpdate = true;
 
+		// Recompute triangle-data opaque-blocker flag when any input to it changes.
+		if ( BLOCKER_PROPS.has( property ) ) {
+
+			this._recomputeOpaqueBlockerForMaterial( materialIndex );
+
+		}
+
 		const featureProperties = [ 'transmission', 'clearcoat', 'sheen', 'iridescence', 'dispersion', 'transparent', 'opacity', 'alphaTest' ];
 		if ( featureProperties.includes( property ) ) {
 
@@ -414,6 +432,10 @@ export class MaterialDataManager {
 		data[ stride + M.CLEARCOAT_ROUGHNESS ] = materialData.clearcoatRoughness ?? 0;
 		data[ stride + M.OPACITY ] = materialData.opacity ?? 1;
 		data[ stride + M.SIDE ] = materialData.side ?? 0;
+		// Mirror side into per-triangle data so BVH traversal avoids a material-buffer read.
+		this._patchTriangleSideForMaterial( materialIndex, materialData.side ?? 0 );
+		// Recompute shadow-ray opaque-blocker flag (reads alphaMode/transparent/transmission/opacity from buffer).
+		this._recomputeOpaqueBlockerForMaterial( materialIndex );
 		data[ stride + M.TRANSPARENT ] = materialData.transparent ?? 0;
 		data[ stride + M.ALPHA_TEST ] = materialData.alphaTest ?? 0;
 		data[ stride + M.ALPHA_MODE ] = materialData.alphaMode ?? 0;
@@ -657,6 +679,74 @@ export class MaterialDataManager {
 
 	}
 
+	/**
+	 * Rewrite the per-triangle `side` flag (NORMAL_C.w) for every triangle whose
+	 * materialIndex matches. Linear over triangles because there's no reverse
+	 * index — side edits are a rare UI action so the scan cost is acceptable.
+	 * @private
+	 */
+	/**
+	 * Re-derive the shadow-ray opaque-blocker flag for a material from its
+	 * current buffer values and patch NORMAL_A.w on every matching triangle.
+	 * Kept in sync with the blocker definition in GeometryExtractor.
+	 * @private
+	 */
+	_recomputeOpaqueBlockerForMaterial( materialIndex ) {
+
+		const matBuf = this.materialStorageAttr?.array;
+		if ( ! matBuf ) return;
+
+		const matStride = materialIndex * M.FLOATS_PER_MATERIAL;
+		const alphaMode = matBuf[ matStride + M.ALPHA_MODE ] | 0;
+		const transparent = matBuf[ matStride + M.TRANSPARENT ] | 0;
+		const transmission = matBuf[ matStride + M.TRANSMISSION ] || 0;
+		const opacity = matBuf[ matStride + M.OPACITY ] ?? 1;
+		const isOpaqueBlocker = ( alphaMode === 0 && transparent === 0 && transmission === 0 && opacity >= 1 ) ? 1.0 : 0.0;
+
+		this._patchTriangleFlagForMaterial( materialIndex, TRI_BLOCKER_OFFSET, isOpaqueBlocker );
+
+	}
+
+	/**
+	 * Generic helper: patch a single per-triangle float at `triOffset` for every
+	 * triangle whose materialIndex matches, then fire onTriangleDataChanged.
+	 * @private
+	 */
+	_patchTriangleFlagForMaterial( materialIndex, triOffset, value ) {
+
+		const triInfo = this.callbacks.getTriangleData?.();
+		const triData = triInfo?.array;
+		const triCount = triInfo?.count | 0;
+		if ( ! triData || triCount === 0 ) return;
+
+		const stride = T.FLOATS_PER_TRIANGLE;
+		let patched = 0;
+		for ( let i = 0; i < triCount; i ++ ) {
+
+			const base = i * stride;
+			if ( triData[ base + TRI_MAT_IDX_OFFSET ] === materialIndex ) {
+
+				triData[ base + triOffset ] = value;
+				patched ++;
+
+			}
+
+		}
+
+		if ( patched > 0 && this.callbacks.onTriangleDataChanged ) {
+
+			this.callbacks.onTriangleDataChanged();
+
+		}
+
+	}
+
+	_patchTriangleSideForMaterial( materialIndex, sideValue ) {
+
+		this._patchTriangleFlagForMaterial( materialIndex, TRI_SIDE_OFFSET, sideValue );
+
+	}
+
 	// ===== DISPOSAL =====
 
 	dispose() {