rayzee 7.31.1 → 8.0.0

package/package.json

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

package/src/EngineDefaults.js

@@ -533,25 +533,122 @@ export const AF_DEFAULTS = {
 	SNAP_THRESHOLD: 0.5,
 };
 
-// Triangle data layout constants - shared between GeometryExtractor and TextureCreator
+/**
+ * Triangle record: 5 uvec4 lanes (80 bytes). The buffer is declared `uvec4` so packed lanes
+ * keep their exact bit pattern — a packSnorm2x16 result can land in the f32 NaN range, and an
+ * f32 lane may canonicalise it (the same reason the G-buffer is uvec4). Positions and UVs are
+ * written as f32 through a Float32Array view of the same memory and read back with
+ * `uintBitsToFloat`, so they carry full precision; only normals are compressed.
+ *
+ * Was 32 floats (128 B) with 4 dead padding lanes. At 128 B the 2 GB V8 ArrayBuffer cap put a
+ * hard ceiling of 16.7M triangles on the scene — 80 B lifts that to 26.8M and cuts geometry
+ * VRAM by the same 37.5%. Each normal now rides in its position's spare .w lane, so the three
+ * vec4 loads the intersection test already does carry the normals with them.
+ */
 export const TRIANGLE_DATA_LAYOUT = {
-	FLOATS_PER_TRIANGLE: 32,
+	FLOATS_PER_TRIANGLE: 20,
 
-	// Positions (3 vec4s = 12 floats)
-	POSITION_A_OFFSET: 0,
+	POSITION_A_OFFSET: 0, // f32 xyz + packed normal A
 	POSITION_B_OFFSET: 4,
 	POSITION_C_OFFSET: 8,
 
-	// Normals (3 vec4s = 12 floats)
-	NORMAL_A_OFFSET: 12,
-	NORMAL_B_OFFSET: 16,
-	NORMAL_C_OFFSET: 20,
+	NORMAL_A_PACKED_OFFSET: 3, // oct16 in each position's .w lane
+	NORMAL_B_PACKED_OFFSET: 7,
+	NORMAL_C_PACKED_OFFSET: 11,
 
-	// UVs and Material (2 vec4s = 8 floats)
-	UV_AB_OFFSET: 24,
-	UV_C_MAT_OFFSET: 28
+	UV_AB_OFFSET: 12, // f32 uvA.xy, uvB.xy
+	UV_C_OFFSET: 16, // f32 uvC.xy
+	MATERIAL_FLAGS_OFFSET: 18, // materialIndex | side << 24 | shadowBlockerBits << 26 (two bits)
+	MESH_INDEX_OFFSET: 19
 };
 
+export const TRI_MATERIAL_MASK = 0xffffff;
+export const TRI_SIDE_SHIFT = 24; // 0 front, 1 back, 2 double
+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
+
+/**
+ * How a shadow ray settles on this material without fetching it, mirroring traceShadowRay:
+ * bit 0 set = always a blocker; bit 1 set = a blocker while alpha-cutout shadows are off
+ * (MASK/BLEND with nothing else letting light through); 0 = light may pass, so the shadow
+ * traversal has to find the nearest such surface.
+ */
+export function shadowBlockerBits( material ) {
+
+	if ( ! material ) return 0;
+	const solid = ( material.transmission || 0 ) === 0
+		&& ( ( material.transparent | 0 ) === 0 || ( material.opacity ?? 1 ) >= 1 );
+	if ( ! solid ) return 0;
+	return ( material.alphaMode | 0 ) === 0 ? 1 : 2;
+
+}
+
+/**
+ * Material index plus the per-triangle flags the shader reads without touching the
+ * material buffer: `side` for inline culling and the two shadow-blocker bits.
+ */
+export function packTriangleFlags( materialIndex, material ) {
+
+	return ( ( materialIndex & TRI_MATERIAL_MASK )
+		| ( ( material?.side ?? 0 ) << TRI_SIDE_SHIFT )
+		| ( shadowBlockerBits( material ) << TRI_BLOCKER_SHIFT ) ) >>> 0;
+
+}
+
+/**
+ * Octahedral-encode a unit normal into one u32 (two snorm16). Worst-case error is ~0.03°,
+ * well under what normal maps and barycentric interpolation already contribute.
+ * A degenerate (zero-length) normal encodes as +Z rather than NaN.
+ */
+export function packNormalOct( x, y, z ) {
+
+	const len = Math.sqrt( x * x + y * y + z * z );
+	if ( len > 0 ) {
+
+		x /= len; y /= len; z /= len;
+
+	} else {
+
+		x = 0; y = 0; z = 1;
+
+	}
+
+	const sum = Math.abs( x ) + Math.abs( y ) + Math.abs( z );
+	let u = x / sum, v = y / sum;
+	if ( z < 0 ) {
+
+		const au = u, av = v;
+		u = ( 1 - Math.abs( av ) ) * ( au >= 0 ? 1 : - 1 );
+		v = ( 1 - Math.abs( au ) ) * ( av >= 0 ? 1 : - 1 );
+
+	}
+
+	const qu = Math.round( Math.min( 1, Math.max( - 1, u ) ) * 32767 ) & 0xffff;
+	const qv = Math.round( Math.min( 1, Math.max( - 1, v ) ) * 32767 ) & 0xffff;
+	return ( ( qv << 16 ) | qu ) >>> 0;
+
+}
+
+/** Inverse of packNormalOct; writes into `out` (length >= 3) and returns it. */
+export function unpackNormalOct( packed, out ) {
+
+	const u = ( ( packed << 16 ) >> 16 ) / 32767;
+	const v = ( packed >> 16 ) / 32767;
+	let x = u, y = v, z = 1 - Math.abs( u ) - Math.abs( v );
+	if ( z < 0 ) {
+
+		const ax = x, ay = y;
+		x = ( 1 - Math.abs( ay ) ) * ( ax >= 0 ? 1 : - 1 );
+		y = ( 1 - Math.abs( ax ) ) * ( ay >= 0 ? 1 : - 1 );
+
+	}
+
+	const len = Math.sqrt( x * x + y * y + z * z ) || 1;
+	out[ 0 ] = x / len; out[ 1 ] = y / len; out[ 2 ] = z / len;
+	return out;
+
+}
+
 // Material data layout constants — single source of truth for material buffer offsets.
 // Shared between CPU writers (TextureCreator, MaterialDataManager) and GPU readers (Common.js getMaterial).
 export const MATERIAL_DATA_LAYOUT = {
@@ -652,11 +749,69 @@ export const MATERIAL_DATA_LAYOUT = {
 export const normalizeAttenuationDistance = d => ( Number.isFinite( d ) && d > 0 ? d : 0 );
 
 // BVH node leaf markers
+/**
+ * Node tags, written into slot [3] of a BVH node as a raw u32 bit pattern.
+ *
+ * Node indices, triangle offsets and counts are integers living inside a Float32Array. Written as
+ * float *values* they round silently past 2^24 (16,777,216): in a 24M-node scene half of every
+ * BLAS pointer landed on a neighbouring node and that geometry vanished from the render with no
+ * error at all. Every one of those fields is written as a u32 bit pattern instead, exact to 2^30.
+ *
+ * Tags sit above {@link BVH_MAX_INDEX} so a single unsigned compare separates a leaf from an inner
+ * node's left-child index. All three are ordinary finite floats — nothing lands in the NaN range,
+ * which an f32 storage buffer is free to canonicalise.
+ */
+export const BVH_MAX_INDEX = 0x40000000; // 2^30
+
+/**
+ * Slot [1] of a BLAS-pointer leaf holds its placement index, which {@link BVH_MAX_INDEX} keeps
+ * below 2^30. Bit 30 is therefore free to say the leaf's matrix is identity: geometry no other
+ * placement shares is baked to world space at extraction, and a ray reaching it needs no
+ * transform at all. Mask the bit off before using the slot as an index.
+ */
+export const TLAS_LEAF_IDENTITY = 0x40000000;
+export const TLAS_PLACEMENT_MASK = 0x3fffffff;
+
 export const BVH_LEAF_MARKERS = {
-	TRIANGLE_LEAF: - 1, // Leaf containing triangle references
-	BLAS_POINTER_LEAF: - 2, // TLAS leaf pointing to a BLAS root node
+	TRIANGLE_LEAF: 0x40000000, // leaf containing triangle references
+	BLAS_POINTER_LEAF: 0x40000001, // TLAS leaf pointing to a BLAS root node
+	FRONTIER: 0x40000002, // parallel-build placeholder, overwritten during assembly
 };
 
+/** A u32 view over a float buffer, for writing index fields as exact bit patterns. */
+export function bvhIndexView( f32 ) {
+
+	return new Uint32Array( f32.buffer, f32.byteOffset, f32.length );
+
+}
+
+/**
+ * Refuse to build a BVH whose indices would collide with the leaf tags.
+ *
+ * Throws rather than degrades: the failure this replaces was a scene that rendered with half its
+ * geometry silently missing, which is far worse than a scene that refuses to load. Guarding the
+ * totals covers every individual write, since no index can exceed the count it indexes into.
+ *
+ * @param {number} count - node or triangle total about to be indexed
+ * @param {string} what - what the count is, for the message
+ * @throws {RangeError}
+ */
+export function assertBVHIndexFits( count, what ) {
+
+	if ( count >= BVH_MAX_INDEX ) {
+
+		throw new RangeError(
+			`${what} is ${count.toLocaleString()}, at or past the BVH index limit of ` +
+			`${BVH_MAX_INDEX.toLocaleString()}. Node indices are stored as u32 bit patterns and the ` +
+			'leaf tags occupy everything above that.'
+		);
+
+	}
+
+	return count;
+
+}
+
 // Texture processing constants
 export const TEXTURE_CONSTANTS = {
 	PIXELS_PER_MATERIAL: 30,

package/src/EngineIssues.js

@@ -8,6 +8,8 @@ export const ISSUE_CODES = Object.freeze( {
 	ADAPTER_SOFTWARE: 'adapter.software',
 	ASSET_UNREACHABLE: 'asset.unreachable',
 	ASSET_AMBIGUOUS_ENTRY: 'asset.ambiguous_entry',
+	ASSET_ARCHIVE_TOO_LARGE: 'asset.archive_too_large',
+	ASSET_ENTRY_TOO_LARGE: 'asset.entry_too_large',
 	TEXTURE_BUILD_FAILED: 'texture.build_failed',
 	TEXTURE_PROCESSING_FALLBACK: 'texture.processing_fallback',
 	TEXTURE_LIMIT_EXCEEDED: 'texture.limit_exceeded',
@@ -16,6 +18,9 @@ export const ISSUE_CODES = Object.freeze( {
 	RENDER_SIZE_DECLINED: 'render.size_declined',
 	STAGE_RENDER_FAILED: 'stage.render_failed',
 	RENDER_RESERVE_CAPPED: 'render.reserve_capped',
+	SCENE_MEMORY_BUDGET: 'scene.memory_budget',
+	EMISSIVE_INSTANCES_COLLAPSED: 'emissive.instances_collapsed',
+	REFIT_SHARED_GEOMETRY: 'refit.shared_geometry',
 } );
 
 /** Strict throws on ERROR only. */

package/src/PathTracerApp.js

@@ -122,6 +122,9 @@ export class PathTracerApp extends EventDispatcher {
 	 *   rendering a plausible wrong image. See EngineIssues.js; read `app.issues` when off.
 	 * @param {string} [options.profile='viewer'] - Which tuning to apply where the viewer's
 	 *   product decisions differ from the physical answer. See RENDER_PROFILES.
+	 * @param {number} [options.maxSceneBytes] - refuse a scene whose estimated host memory is
+	 *   above this. The default refuses where the renderer process would be killed instead of
+	 *   throwing; raise it deliberately, on a fresh browser. See HostMemory.js.
 	 *
 	 * The engine dispatches `EngineEvents.FRAME` after each animate() iteration so hosts can
 	 * tick external instrumentation (e.g. a stats panel) without coupling the engine to it.
@@ -144,6 +147,8 @@ export class PathTracerApp extends EventDispatcher {
 
 		this.canvas = canvas;
 		this._autoResize = options.autoResize !== false;
+		// A scene budget the host may raise; read where SceneProcessor is built, well after this.
+		this._maxSceneBytes = options.maxSceneBytes;
 		this._container = options.container || null;
 		// Apply the environment authored into a model file's metadata on load. See _beginSceneMetadataEnvironment().
 		this._applySceneMetadataEnabled = options.applySceneMetadata !== false;
@@ -796,6 +801,18 @@ export class PathTracerApp extends EventDispatcher {
 
 	}
 
+	/**
+	 * Lists the independently loadable parts of an archive without unpacking it, so a host
+	 * can offer a choice for a scene too large to load whole.
+	 * @param {File} file
+	 * @returns {Promise<{kind:string, root:string|null, elements:Array, entryCount:number, totalBytes:number}>}
+	 */
+	async inspectArchive( file ) {
+
+		return await this.assetLoader.inspectArchive( file );
+
+	}
+
 	/**
 	 * Loads a user-supplied File (drag-drop, file picker) — model, archive, or environment
 	 * map, dispatched by extension.
@@ -808,9 +825,11 @@ export class PathTracerApp extends EventDispatcher {
 	 * LOAD_IN_PROGRESS before anything is touched.
 	 *
 	 * @param {File} file
+	 * @param {object} [options] - forwarded to the archive loader: `element` to load one
+	 *   subtree of a multi-part scene, `pbrtEntry` to choose among several .pbrt scenes.
 	 * @returns {Promise<void>}
 	 */
-	async loadFile( file ) {
+	async loadFile( file, options = {} ) {
 
 		const format = this.assetLoader?.getFileFormat( file?.name || '' );
 		if ( ! format ) throw new Error( `Unsupported file format: ${file?.name}` );
@@ -818,7 +837,7 @@ export class PathTracerApp extends EventDispatcher {
 		if ( format.type !== 'environment' && format.type !== 'image' ) {
 
 			await this._loadWithSceneRebuild(
-				() => this.assetLoader.loadAssetFromFile( file ),
+				() => this.assetLoader.loadAssetFromFile( file, options ),
 				{ type: 'ModelLoaded', filename: file.name }
 			);
 			return;
@@ -904,7 +923,7 @@ export class PathTracerApp extends EventDispatcher {
 		}
 
 		// Reprocess the loaded scene so the new cap takes effect immediately.
-		if ( reprocess && this._maxTextureSize !== prev && this._sdf?.triangleData && ! this._loadingInProgress ) {
+		if ( reprocess && this._maxTextureSize !== prev && this._sdf?.triangles && ! this._loadingInProgress ) {
 
 			this._loadingInProgress = true;
 			try {
@@ -948,6 +967,14 @@ export class PathTracerApp extends EventDispatcher {
 			this.dispatchEvent( eventPayload );
 			this._dispatchCamerasUpdated();
 
+		} catch ( error ) {
+
+			// loadFn released the previous model before this one was known to be loadable, so
+			// there is nothing to fall back to. Leaving it half-built would keep the last
+			// frame's buffers on screen under a scene that no longer exists.
+			if ( ! error || error.code !== 'LOAD_IN_PROGRESS' ) this._discardFailedLoad();
+			throw error;
+
 		} finally {
 
 			this._loadingInProgress = false;
@@ -956,6 +983,27 @@ export class PathTracerApp extends EventDispatcher {
 
 	}
 
+	/**
+	 * Put the engine back to an empty scene after a load failed part-way. The failure itself is
+	 * rethrown for the host to report; this only makes sure what is on screen matches it.
+	 * @private
+	 */
+	_discardFailedLoad() {
+
+		try {
+
+			this._clearAppendedModels();
+			this.assetLoader?.releaseTargetModel();
+			this.reset();
+
+		} catch ( cleanupError ) {
+
+			console.warn( 'PathTracerApp: could not clear the scene after a failed load', cleanupError );
+
+		}
+
+	}
+
 	/**
 	 * Scene-level authoring metadata carried by the current model file (glTF `extras`),
 	 * or null when the file has none. See {@link module:Processor/SceneMetadata}.
@@ -1198,7 +1246,7 @@ export class PathTracerApp extends EventDispatcher {
 	_sceneSummaryParts() {
 
 		const pt = this.stages.pathTracer;
-		const meshes = this._sdf?.instanceTable?.entries?.filter( Boolean ).length ?? 0;
+		const meshes = this._sdf?.instanceTable?.setCount ?? 0;
 		const maps = this._sdf?.geometryExtractor?.maps?.length ?? 0;
 
 		return [
@@ -1497,16 +1545,22 @@ export class PathTracerApp extends EventDispatcher {
 	 * Topology must stay the same (same triangle count and connectivity).
 	 * Call this per-frame for skeletal/morph-target animation.
 	 *
-	 * @param {Float32Array} newPositions - 9 floats per triangle (ax,ay,az, bx,by,bz, cx,cy,cz) for every triangle in the scene, meshes in {@link sceneMeshes} order and triangles in index order
-	 * @param {Float32Array} [newNormals] - Optional 9 floats per triangle smooth normals. If omitted, face normals are computed from positions.
+	 * Positions come in one of two shapes. A **callback** `(meshIndex, triCount) => Float32Array`
+	 * is asked for one mesh at a time and may return the same scratch buffer each call — prefer it,
+	 * since it never holds more than one mesh. A **scene-wide Float32Array** of 9 floats per
+	 * triangle for every triangle (meshes in {@link sceneMeshes} order, triangles in index order)
+	 * still works, but is 1,030 MB at 30M triangles and will not allocate at that size.
+	 *
+	 * @param {Float32Array|function(number, number): Float32Array} newPositions - (ax,ay,az, bx,by,bz, cx,cy,cz) per triangle, world space
+	 * @param {Float32Array|function(number, number): Float32Array} [newNormals] - Optional smooth normals, same two shapes. If omitted, face normals are computed from positions.
 	 * @returns {Promise<{ refitTimeMs: number }>}
 	 */
 	async refitBVH( newPositions, newNormals ) {
 
 		const result = await this._sdf.refitBVH( newPositions, newNormals );
 
-		this.stages.pathTracer.updateTriangleData( this._sdf.triangleData );
-		this.stages.pathTracer.updateBVHData( this._sdf.bvhData );
+		this.stages.pathTracer.updateTriangleData( this._sdf.triangles );
+		this.stages.pathTracer.updateBVHData( this._sdf.bvh );
 		this.reset();
 
 		return result;
@@ -1518,8 +1572,9 @@ export class PathTracerApp extends EventDispatcher {
 	 * Faster than refitBVH for single-object transforms in multi-mesh scenes.
 	 *
 	 * @param {number[]} affectedMeshIndices - Mesh indices to refit
-	 * @param {Float32Array} newPositions - 9 floats per triangle in original mesh order
-	 * @param {Float32Array} [newNormals] - Optional smooth normals
+	 * @param {Float32Array|function(number, number): Float32Array} newPositions - the same two shapes
+	 *   {@link refitBVH} takes; only the affected meshes are asked for
+	 * @param {Float32Array|function(number, number): Float32Array} [newNormals] - Optional smooth normals
 	 * @returns {{ refitTimeMs: number }}
 	 */
 	refitBLASes( affectedMeshIndices, newPositions, newNormals ) {
@@ -1531,11 +1586,12 @@ export class PathTracerApp extends EventDispatcher {
 		this.reset();
 
 		// Kick off background rebuild for optimal SAH quality
-		this._sdf.scheduleBackgroundRebuild( affectedMeshIndices, () => {
+		this._sdf.scheduleBackgroundRebuild( affectedMeshIndices, ( meshIndex ) => {
 
-			// Swap complete — upload updated buffers and restart accumulation
-			this.stages.pathTracer.updateTriangleData( this._sdf.triangleData );
-			this.stages.pathTracer.updateBVHData( this._sdf.bvhData );
+			// Swap complete — upload just that mesh's triangles and nodes, plus the TLAS. A whole
+			// re-upload here is gigabytes on a large scene, for one mesh's worth of change.
+			const dirty = this._sdf.computeBLASDirtyRanges( [ meshIndex ] );
+			this.stages.pathTracer.updateBufferRanges( dirty.triRanges, dirty.bvhRanges );
 			this.reset();
 
 		} );
@@ -1544,6 +1600,28 @@ export class PathTracerApp extends EventDispatcher {
 
 	}
 
+	/**
+	 * Apply new transforms for objects that moved, without touching their geometry.
+	 *
+	 * This is the right call for a gizmo drag or any other rigid move: triangles are stored in
+	 * each object's own space, so only the placement matrix changes. {@link refitBLASes} is for
+	 * geometry that actually deformed — on a rigid move it rewrites vertices needlessly, and
+	 * drags along any other object sharing the same geometry.
+	 *
+	 * @param {number[]} meshIndices - indices into {@link sceneMeshes}
+	 * @returns {{ refitTimeMs: number, placements: number }}
+	 */
+	updateMeshTransforms( meshIndices ) {
+
+		const result = this._sdf.updateMeshTransforms( meshIndices );
+
+		this.stages.pathTracer.updateBufferRanges( [], [ this._sdf.computeTLASDirtyRange() ] );
+		this.reset();
+
+		return result;
+
+	}
+
 	// ═══════════════════════════════════════════════════════════════
 	// Resize
 	// ═══════════════════════════════════════════════════════════════
@@ -2503,6 +2581,25 @@ export class PathTracerApp extends EventDispatcher {
 
 	}
 
+	/**
+	 * CPU-side memory for the last scene build: what the preflight predicted, what each phase
+	 * allocated, and what was live at each phase boundary.
+	 *
+	 * Note that `performance.memory.usedJSHeapSize` does NOT count SharedArrayBuffer, and the
+	 * triangle and BVH stores are SAB-backed — so the browser's own heap reading under-reports
+	 * a large scene by several gigabytes and this is the figure to trust.
+	 *
+	 * @returns {?{preflight: ?Object, allocatedBytes: number, peakLiveBytes: number,
+	 *   byPhase: Object, samples: Object[]}} null before a scene is built
+	 */
+	getHostMemoryInfo() {
+
+		const sp = this._sdf;
+		if ( ! sp?.memory ) return null;
+		return { preflight: sp.memoryPreflight, ...sp.memory.report };
+
+	}
+
 	// Idempotent: registers the cross-stage texture provider and re-measures on
 	// allocation events (scene/env load, resize) so peak is caught even while idle.
 	_ensureVRAMWiring() {
@@ -2631,13 +2728,13 @@ export class PathTracerApp extends EventDispatcher {
 	 */
 	_refreshEmissiveForVisibility() {
 
-		const entries = this._sdf?.instanceTable?.entries;
-		if ( ! entries ) return;
+		const table = this._sdf?.instanceTable;
+		if ( ! table ) return;
 
 		const hidden = new Set();
-		for ( const entry of entries ) {
+		for ( let i = 0; i < table.count; i ++ ) {
 
-			if ( entry && entry.visible === false ) hidden.add( entry.meshIndex );
+			if ( table.isSet[ i ] && ! table.visible[ i ] ) hidden.add( i );
 
 		}
 
@@ -2856,7 +2953,11 @@ export class PathTracerApp extends EventDispatcher {
 
 	_initAssetPipeline() {
 
-		this._sdf = new SceneProcessor( { issues: this._issues } );
+		this._sdf = new SceneProcessor( {
+			issues: this._issues,
+			// Spread into defaults, so only pass it when the host actually set one.
+			...( this._maxSceneBytes === undefined ? {} : { maxSceneBytes: this._maxSceneBytes } ),
+		} );
 		this.assetLoader = new AssetLoader(
 			this.meshScene, this.cameraManager.camera, this.cameraManager.controls,
 			{ issues: this._issues, profile: this._profile }