rayzee 9.3.0 → 10.0.0

package/package.json

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

package/src/EngineDefaults.js

@@ -544,7 +544,10 @@ export const TRIANGLE_DATA_LAYOUT = {
 };
 
 export const TRI_MATERIAL_MASK = 0xffffff;
-export const TRI_SIDE_SHIFT = 24; // 0 front, 1 back, 2 double
+export const TRI_SIDE_SHIFT = 24; // 0 front, 1 back, 2 double, 3 cutaway
+// Front only for every ray, shadow rays too: a cut-away wall or roof. Set by `material.userData.cutaway`
+// at extraction, or `app.setMaterialsSide( indices, MATERIAL_SIDE_CUTAWAY )` on a built scene.
+export const MATERIAL_SIDE_CUTAWAY = 3;
 export const TRI_BLOCKER_SHIFT = 26; // 1 = blocks shadow rays whatever the settings
 export const TRI_BLOCKER_ALPHA_SHIFT = 27; // 1 = blocks them unless alpha-cutout shadows are on
 

package/src/PathTracerApp.js

@@ -3531,6 +3531,27 @@ export class PathTracerApp extends EventDispatcher {
 
 	}
 
+	/**
+	 * Sets one side on many materials at once — `MATERIAL_SIDE_CUTAWAY` for a cut-away room — in a
+	 * single pass over the triangles, where `setMaterialProperty( i, 'side', … )` makes one per material.
+	 * @param {Iterable<number>} materialIndices
+	 * @param {number} side
+	 */
+	setMaterialsSide( materialIndices, side ) {
+
+		const indices = [ ...materialIndices ];
+		if ( this._sdf?.spilled ) {
+
+			this.ensureSceneResident().then( () => this.setMaterialsSide( indices, side ) );
+			return;
+
+		}
+
+		this.stages.pathTracer?.materialData.setMaterialsSide( indices, side );
+		this.reset();
+
+	}
+
 	setMaterialProperty( materialIndex, property, value ) {
 
 		// These rewrite triangle records, which a spilled scene has to read back first.

package/src/Processor/GeometryExtractor.js

@@ -1,6 +1,6 @@
 import { BufferAttribute, Vector3, Vector2, Color, Matrix3, Matrix4, FrontSide, BackSide, DoubleSide, RGBAFormat } from "three";
 import {
-	TEXTURE_CONSTANTS, TRIANGLE_DATA_LAYOUT, MATERIAL_DEFAULTS, packNormalOct, packTriangleFlags
+	TEXTURE_CONSTANTS, TRIANGLE_DATA_LAYOUT, MATERIAL_DEFAULTS, packNormalOct, packTriangleFlags, MATERIAL_SIDE_CUTAWAY
 } from '../EngineDefaults.js';
 import { ISSUE_CODES } from '../EngineIssues.js';
 import { ChunkedRecords, SHARED_MEMORY_AVAILABLE } from './ChunkedRecords.js';
@@ -1171,6 +1171,7 @@ export class GeometryExtractor {
 	getMaterialSide( material ) {
 
 		if ( material.transmission > 0.0 ) return 2;
+		if ( material.userData?.cutaway === true ) return MATERIAL_SIDE_CUTAWAY;
 		switch ( material.side ) {
 
 			case FrontSide: return 0;

package/src/TSL/BVHTraversal.js

@@ -24,7 +24,7 @@ import {
 	bool as tslBool,
 } from 'three/tsl';
 
-import { BVH_LEAF_MARKERS, BVH_MAX_INDEX, BVH_FOLDED_LEAF_MAX, TRI_MATERIAL_MASK, TRI_SIDE_SHIFT, TLAS_LEAF_IDENTITY } from '../EngineDefaults.js';
+import { BVH_LEAF_MARKERS, BVH_MAX_INDEX, BVH_FOLDED_LEAF_MAX, TRI_MATERIAL_MASK, TRI_SIDE_SHIFT, TLAS_LEAF_IDENTITY, MATERIAL_SIDE_CUTAWAY } from '../EngineDefaults.js';
 import { HitInfo } from './Struct.js';
 import {
 	getDatafromStorageBuffer, instanceRows, instanceNormalToWorld, unpackTriangleNormal, triangleRow, shadowFlagsSettle
@@ -213,12 +213,12 @@ const fastRayAABBDst = wgslFn( `
 // MAIN BVH TRAVERSAL
 // ================================================================================
 
-// Side from a triangle's flags word (row 4 .z): 0 front, 1 back, 2 double.
+// Side from a triangle's flags word (row 4 .z): 0 front, 1 back, 2 double, 3 cutaway (front, every ray).
 export const triangleSide = ( flags ) => int( flags.shiftRight( uint( TRI_SIDE_SHIFT ) ).bitAnd( uint( 3 ) ) );
 
 // Whether a face of this side is seen by a ray; rayDotNormal < 0 is a front hit.
 export const sideAccepts = ( side, rayDotNormal ) => side.equal( int( 2 ) )
-	.or( side.equal( int( 0 ) ).and( rayDotNormal.lessThan( - 0.0001 ) ) )
+	.or( side.equal( int( 0 ) ).or( side.equal( int( MATERIAL_SIDE_CUTAWAY ) ) ).and( rayDotNormal.lessThan( - 0.0001 ) ) )
 	.or( side.equal( int( 1 ) ).and( rayDotNormal.greaterThan( 0.0001 ) ) );
 
 // Factory: the boxTests/triTests debug counters are compiled OUT of the hot closest-hit
@@ -324,7 +324,7 @@ const makeTraverseBVH = ( trackStats ) => Fn( ( [
 				);
 
 				// Side culling (inline; per-mesh visibility is at the BLAS-pointer level).
-				If( eitherSide.or( sideAccepts( side, rayDotNormal ) ), () => {
+				If( eitherSide.and( side.notEqual( int( MATERIAL_SIDE_CUTAWAY ) ) ).or( sideAccepts( side, rayDotNormal ) ), () => {
 
 					closestHit.didHit.assign( true );
 					closestHit.dst.assign( t );
@@ -579,27 +579,43 @@ export const traverseBVHShadow = Fn( ( [
 				// Per-mesh visibility is handled at the BLAS-pointer level.
 				const uvData2 = triangleRow( triangleBuffer, triIndex, 4 ).toVar();
 
-				closestHit.didHit.assign( true );
-				closestHit.dst.assign( triResult.x );
-				closestHit.materialIndex.assign( int( uvData2.z.bitAnd( uint( TRI_MATERIAL_MASK ) ) ) );
-				closestHit.meshIndex.assign( int( uvData2.w ) );
-				closestHit.instanceLeaf.assign( instLeaf );
+				// A cutaway face is see-through from behind for shadow rays too.
+				const seen = tslBool( true ).toVar();
+				If( triangleSide( uvData2.z ).equal( int( MATERIAL_SIDE_CUTAWAY ) ), () => {
 
-				// Hit point is cheap (origin + dir*t). Geometric normal is deferred
-				// to traceShadowRay — only the transmission branch needs it, so we
-				// skip the cross+normalize for the (much more common) opaque-blocker
-				// and alpha-cutout paths. Normal stays vec3(0) from struct init.
-				closestHit.hitPoint.assign( worldOrigin.add( worldDirection.mul( triResult.x ) ) );
+					const w = float( 1.0 ).sub( triResult.y ).sub( triResult.z );
+					const n = unpackTriangleNormal( triangleRow( triangleBuffer, triIndex, 0 ).w ).mul( w )
+						.add( unpackTriangleNormal( triangleRow( triangleBuffer, triIndex, 1 ).w ).mul( triResult.y ) )
+						.add( unpackTriangleNormal( triangleRow( triangleBuffer, triIndex, 2 ).w ).mul( triResult.z ) );
+					seen.assign( rayDirection.dot( normalize( n ) ).lessThan( - 0.0001 ) );
 
-				closestHit.uv.assign( vec2( triResult.y, triResult.z ) );
-				closestHit.triangleIndex.assign( triIndex );
+				} );
+
+				If( seen, () => {
+
+					closestHit.didHit.assign( true );
+					closestHit.dst.assign( triResult.x );
+					closestHit.materialIndex.assign( int( uvData2.z.bitAnd( uint( TRI_MATERIAL_MASK ) ) ) );
+					closestHit.meshIndex.assign( int( uvData2.w ) );
+					closestHit.instanceLeaf.assign( instLeaf );
 
-				// An opaque blocker settles the ray. A surface light passes through has to be
-				// the nearest one, or the layers behind the first find are never counted.
-				If( shadowFlagsSettle( uvData2.z ), () => {
+					// Hit point is cheap (origin + dir*t). Geometric normal is deferred
+					// to traceShadowRay — only the transmission branch needs it, so we
+					// skip the cross+normalize for the (much more common) opaque-blocker
+					// and alpha-cutout paths. Normal stays vec3(0) from struct init.
+					closestHit.hitPoint.assign( worldOrigin.add( worldDirection.mul( triResult.x ) ) );
 
-					blocked.assign( true );
-					Break();
+					closestHit.uv.assign( vec2( triResult.y, triResult.z ) );
+					closestHit.triangleIndex.assign( triIndex );
+
+					// An opaque blocker settles the ray. A surface light passes through has to be
+					// the nearest one, or the layers behind the first find are never counted.
+					If( shadowFlagsSettle( uvData2.z ), () => {
+
+						blocked.assign( true );
+						Break();
+
+					} );
 
 				} );
 

package/src/index.js

@@ -78,6 +78,7 @@ export {
 	MAX_RESERVABLE_RENDER_SIZE,
 	RENDER_PROFILES,
 	getRenderProfile,
+	MATERIAL_SIDE_CUTAWAY,
 } from './EngineDefaults.js';
 export { sunPosition, timeForSunElevation, dayOfYearForMonth } from './Processor/SunPosition.js';
 

package/src/managers/MaterialDataManager.js

@@ -672,12 +672,43 @@ export class MaterialDataManager {
 
 	}
 
+	/**
+	 * One side for several materials in a single pass over the triangles; per-material edits scan
+	 * every triangle once each.
+	 * @param {Iterable<number>} materialIndices
+	 * @param {number} side - 0 front, 1 back, 2 double, MATERIAL_SIDE_CUTAWAY
+	 */
+	setMaterialsSide( materialIndices, side ) {
+
+		if ( ! this.materialStorageAttr ) return;
+
+		const indices = new Set( materialIndices );
+		const data = this.materialStorageAttr.array;
+		for ( const i of indices ) {
+
+			data[ i * M.FLOATS_PER_MATERIAL + M.SIDE ] = side;
+			( this._hostSet[ i ] ??= new Map() ).set( 'side', side );
+
+		}
+
+		this._patchTriangleFlagForMaterials( indices, TRI_SIDE_SHIFT, 2, side );
+		this.materialStorageAttr.needsUpdate = true;
+		this._notifyReset();
+
+	}
+
+	_patchTriangleFlagForMaterial( materialIndex, shift, width, value ) {
+
+		this._patchTriangleFlagForMaterials( new Set( [ materialIndex ] ), shift, width, value );
+
+	}
+
 	/**
 	 * Generic helper: rewrite `width` bits at `shift` in the flags lane of every triangle
-	 * whose materialIndex matches, then fire onTriangleDataChanged.
+	 * whose materialIndex is in `indices`, then fire onTriangleDataChanged.
 	 * @private
 	 */
-	_patchTriangleFlagForMaterial( materialIndex, shift, width, value ) {
+	_patchTriangleFlagForMaterials( indices, shift, width, value ) {
 
 		const triInfo = this.callbacks.getTriangleData?.();
 		// Chunked past the ~2 GB array cap; a flat array is the single-chunk case.
@@ -694,7 +725,7 @@ export class MaterialDataManager {
 
 			const triData = records ? records.chunkFor( i ) : flat;
 			const base = records ? records.baseOf( i ) : i * stride;
-			if ( ( triData[ base + TRI_FLAGS_OFFSET ] & TRI_MATERIAL_MASK ) === materialIndex ) {
+			if ( indices.has( triData[ base + TRI_FLAGS_OFFSET ] & TRI_MATERIAL_MASK ) ) {
 
 				triData[ base + TRI_FLAGS_OFFSET ] = ( ( triData[ base + TRI_FLAGS_OFFSET ] & ~ mask ) | bits ) >>> 0;
 				patched ++;