rayzee 8.6.0 → 8.7.0

package/package.json

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

package/src/AssetConfig.js

@@ -45,12 +45,13 @@ const config = {
 	// AI upscaler ONNX model base URL. Quality presets resolve relative paths against this.
 	upscalerModelBaseUrl: 'https://huggingface.co/notaneimu/onnx-image-models/resolve/main/',
 
-	// DLSS runtime bundle. A plain script the host serves, not a module: it installs
-	// `globalThis.DLSSRuntime`, so it cannot be imported and the host must publish it somewhere.
-	dlssRuntimeUrl: '/dlss/dlss-runtime.js',
+	// Neural post-pass runtime. A plain script the host serves, not a module: it installs
+	// `globalThis.NeuralRuntime`, so it cannot be imported and the host must publish it somewhere.
+	neuralRuntimeUrl: '/neural/neural-runtime.js',
 
-	// Base for the DLSS weight manifests the runtime fetches (`generated/...` beneath this).
-	dlssAssetBaseUrl: 'https://pub-6e048ff014374f11bef33d76b6c2b5ef.r2.dev/v1',
+	// Base for the neural weight manifests the runtime fetches (`generated/...` beneath this). No
+	// default: the weights are not redistributable, so a host supplies its own copy.
+	neuralAssetBaseUrl: null,
 
 	// Prefix used when the engine writes to client-side stores (IndexedDB, etc).
 	// Set to a unique value to avoid collisions when multiple apps embed the engine on the same origin.

package/src/Passes/OIDNDenoiser.js

@@ -688,6 +688,14 @@ export class OIDNDenoiser extends EventDispatcher {
 		this._computeInputScale( device, width * height );
 		this._applyColorScale( device, width * height );
 
+		// A final denoise is shown tile by tile, so the tiles still to come must show this render
+		// rather than the blank or previous-view picture the output holds between runs.
+		if ( ! continuous && ! this._hasOutput ) {
+
+			this._unpackToTexture( this._gpuInputBuffers.color, width, { x: 0, y: 0, width, height }, false );
+
+		}
+
 		// Pass GPU storage buffers to oidn-web (GPUBuffer path, well-tested)
 		const config = {
 			color: { data: this._gpuInputBuffers.color, width, height },
@@ -996,11 +1004,12 @@ export class OIDNDenoiser extends EventDispatcher {
 	/**
 	 * Writes a rectangle of the denoised buffer into the output picture, on the card.
 	 *
-	 * @param {GPUBuffer} src - denoised rgba32float, full image
+	 * @param {GPUBuffer} src - rgba32float, full image, scaled by the input autoexposure
 	 * @param {number} srcWidth
 	 * @param {{x: number, y: number, width: number, height: number}} rect
+	 * @param {boolean} [denoised=true] - false for the raw render laid under a tiled run
 	 */
-	_unpackToTexture( src, srcWidth, rect ) {
+	_unpackToTexture( src, srcWidth, rect, denoised = true ) {
 
 		const device = this.gpuDevice;
 		if ( ! device || ! this._ensureScalePipelines( device ) ) return;
@@ -1047,7 +1056,7 @@ export class OIDNDenoiser extends EventDispatcher {
 			// Set here rather than when the run resolves: 'end' is dispatched from execute()'s
 			// finally, which runs first, so a listener that waits for the run would see the very
 			// first denoise as having produced nothing.
-			this._hasOutput = true;
+			if ( denoised ) this._hasOutput = true;
 
 		} finally {
 
@@ -1060,8 +1069,7 @@ export class OIDNDenoiser extends EventDispatcher {
 
 	/**
 	 * Promise wrapper around tileExecute for the GPU path. Each tile is written straight into the
-	 * output picture on the card, so there is nothing to await between a tile finishing and it
-	 * being visible.
+	 * output picture on the card; 'tileProgress' is what puts it on screen.
 	 */
 	_executeWithAbortGPU( config, continuous = false ) {
 

package/src/PathTracerApp.js

@@ -1,7 +1,7 @@
 import { WebGPURenderer, RectAreaLightNode, SRGBColorSpace, LinearSRGBColorSpace } from 'three/webgpu';
 import { texture as _tslTexture, cubeTexture as _tslCubeTexture } from 'three/tsl';
 import {
-	Scene, EventDispatcher, Box3
+	Scene, EventDispatcher, Box3, Vector3
 } from 'three';
 import { RectAreaLightTexturesLib } from 'three/addons/lights/RectAreaLightTexturesLib.js';
 import { SceneHelpers } from './SceneHelpers.js';
@@ -195,6 +195,7 @@ export class PathTracerApp extends EventDispatcher {
 		this.assetLoader = null;
 		this._sdf = null;
 		this._animRefitInFlight = false;
+		this._emittersMoved = false;
 		// Max material-texture dimension (longest edge); applied on each scene build.
 		this._maxTextureSize = DEFAULT_STATE.maxTextureSize;
 
@@ -1165,6 +1166,7 @@ export class PathTracerApp extends EventDispatcher {
 		// Stop any running animation before rebuilding scene data
 		this.animationManager.dispose();
 		this._animRefitInFlight = false;
+		this._emittersMoved = false;
 
 		// Tag the primary (replace-loaded) model so it appears in the scene-object list.
 		this._tagPrimarySceneObject();
@@ -1654,6 +1656,95 @@ export class PathTracerApp extends EventDispatcher {
 
 	}
 
+	/** Apply a pose from AnimationManager: placements, visibility, and a followed camera. @private */
+	_applyAnimationPose( { meshIndices, visibilityChanged, cameras } ) {
+
+		if ( ! this._sdf?.instanceTable ) return;
+		let changed = false;
+
+		if ( meshIndices.length > 0 ) {
+
+			this._sdf.updateMeshTransforms( meshIndices );
+			this.stages.pathTracer?.updateBufferRanges( [], [ this._sdf.computeTLASDirtyRange() ] );
+			if ( this._sdf.movesEmitters( meshIndices ) ) {
+
+				this._emittersMoved = true;
+				// Deferred while playing: the rebuild uploads a scene-sized map, and sampling
+				// already reads each emitter through its placement.
+				if ( ! this.animationManager.isPlaying ) this._refreshMovedEmitters();
+
+			}
+
+			changed = true;
+
+		}
+
+		if ( visibilityChanged ) {
+
+			this.stages.pathTracer?.updateAllMeshVisibility();
+			this._refreshEmissiveForVisibility();
+			changed = true;
+
+		}
+
+		if ( cameras.length > 0 && this._followAnimatedCamera( cameras ) ) changed = true;
+
+		if ( changed ) this.reset();
+
+	}
+
+	/** @private */
+	_refreshMovedEmitters() {
+
+		if ( ! this._emittersMoved ) return;
+		this._emittersMoved = false;
+		this._uploadEmissivePayload( this._sdf?.refreshEmissiveTransforms() ?? null );
+
+	}
+
+	/**
+	 * Move the view with the selected camera's animated original — the camera list holds copies.
+	 * @returns {boolean} whether the view moved
+	 * @private
+	 */
+	_followAnimatedCamera( cameras ) {
+
+		const cm = this.cameraManager;
+		const selected = cm.currentCameraIndex > 0 ? cm.cameras[ cm.currentCameraIndex ] : null;
+		const uuid = selected?.userData?.__rayzeeSourceUuid;
+		const source = uuid && cameras.find( c => c.uuid === uuid );
+		if ( ! source ) return false;
+
+		source.updateWorldMatrix( true, false );
+		const worldScale = new Vector3();
+		source.matrixWorld.decompose( selected.position, selected.quaternion, worldScale );
+		// Only the mirror survives.
+		selected.scale.set( Math.sign( worldScale.x ) || 1, Math.sign( worldScale.y ) || 1, Math.sign( worldScale.z ) || 1 );
+		if ( source.isPerspectiveCamera ) selected.fov = source.fov;
+
+		const camera = cm.camera;
+		const controls = cm.controls;
+		const distance = controls ? controls.target.distanceTo( camera.position ) : 0;
+
+		camera.position.copy( selected.position );
+		camera.quaternion.copy( selected.quaternion );
+		camera.scale.copy( selected.scale );
+		if ( camera.isPerspectiveCamera && selected.isPerspectiveCamera ) camera.fov = selected.fov;
+		camera.updateProjectionMatrix();
+		camera.updateMatrixWorld( true );
+
+		// Pivot ahead at the same distance, so controls.update() keeps the pose.
+		if ( controls ) {
+
+			const forward = new Vector3( 0, 0, - 1 ).applyQuaternion( camera.quaternion );
+			controls.target.copy( camera.position ).addScaledVector( forward, distance || 1 );
+
+		}
+
+		return true;
+
+	}
+
 	/**
 	 * Apply new transforms for objects that moved, without touching their geometry.
 	 *
@@ -2873,10 +2964,11 @@ export class PathTracerApp extends EventDispatcher {
 		const table = this._sdf?.instanceTable;
 		if ( ! table ) return;
 
+		// The emitter list names meshes, the table placements.
 		const hidden = new Set();
 		for ( let i = 0; i < table.count; i ++ ) {
 
-			if ( table.isSet[ i ] && ! table.visible[ i ] ) hidden.add( i );
+			if ( table.isSet[ i ] && ! table.visible[ i ] ) hidden.add( table.sourceMesh[ i ] );
 
 		}
 
@@ -3410,6 +3502,7 @@ export class PathTracerApp extends EventDispatcher {
 
 		// Animation lifecycle → wake + refit flag
 		this.animationManager.wakeCallback = () => this.wake();
+		this.animationManager.applyPoseCallback = ( pose ) => this._applyAnimationPose( pose );
 		this._forwardEvents( this.animationManager, [
 			EngineEvents.ANIMATION_STARTED,
 			EngineEvents.ANIMATION_PAUSED,
@@ -3418,6 +3511,7 @@ export class PathTracerApp extends EventDispatcher {
 		this._addTrackedListener( this.animationManager, EngineEvents.ANIMATION_PAUSED, () => {
 
 			this._animRefitInFlight = false;
+			this._refreshMovedEmitters();
 
 		} );
 		this._addTrackedListener( this.animationManager, EngineEvents.ANIMATION_STOPPED, () => {
@@ -3538,6 +3632,7 @@ export class PathTracerApp extends EventDispatcher {
 			this.animationManager.onFinished = () => {
 
 				this._animRefitInFlight = false;
+				this._refreshMovedEmitters();
 				this.dispatchEvent( { type: EngineEvents.ANIMATION_FINISHED } );
 
 			};

package/src/Processor/AssetLoader.js

@@ -787,10 +787,11 @@ export class AssetLoader extends EventDispatcher {
 		};
 
 		const pbrtStart = performance.now();
-		const { group, environment, report, warnings, meshCount, entryPath: loadedEntry, candidates,
-			parseMs, buildMs, triangleCount, placementCount, mergedShapes, skippedForBudget,
+		const { group, environment, animations, report, warnings, meshCount, entryPath: loadedEntry, candidates,
+			frames, parseMs, buildMs, triangleCount, placementCount, mergedShapes, skippedForBudget,
 			droppedNoTemplate } = await loadPBRTScene( {
 			vfs: zip, source, entryPath, plyParser, imageFromBytes, envFromBytes,
+			animation: options.animation,
 			maxTriangles: options.maxTriangles,
 			maxPlacements: options.maxPlacements,
 			mergeShapesAbove: options.mergeShapesAbove,
@@ -802,15 +803,17 @@ export class AssetLoader extends EventDispatcher {
 		// SceneProcessor.performanceMetrics.
 		this.lastPBRTStats = {
 			parseMs, buildMs, loaderMs: performance.now() - pbrtStart,
-			triangleCount, placementCount, mergedShapes, skippedForBudget, droppedNoTemplate, meshCount
+			triangleCount, placementCount, mergedShapes, skippedForBudget, droppedNoTemplate, meshCount,
+			frames: frames?.length ?? 1
 		};
 
-		// An archive can hold several independent scenes (transparent-machines ships five
-		// animation frames). Only one is loaded, so name it and the alternatives rather
-		// than leave the user comparing against a reference of a different scene.
-		if ( candidates.length > 1 ) {
+		// An archive can hold several independent scenes (bistro ships three views). Only one is
+		// loaded, so name it and the alternatives rather than leave the user comparing against a
+		// reference of a different scene. A frame sequence loads whole, as its animation.
+		const loaded = new Set( frames ?? [ loadedEntry ] );
+		const others = candidates.filter( p => ! loaded.has( p ) );
+		if ( others.length > 0 ) {
 
-			const others = candidates.filter( p => p !== loadedEntry );
 			console.warn( `PBRT archive holds ${candidates.length} scenes; loaded "${loadedEntry}". Others: ${others.join( ', ' )}` );
 			this._issues?.record(
 				ISSUE_CODES.ASSET_AMBIGUOUS_ENTRY,
@@ -849,6 +852,7 @@ export class AssetLoader extends EventDispatcher {
 		group.name = loadedEntry || filename;
 		this.releaseTargetModel();
 		this.targetModel = group;
+		this.animations = animations ?? [];
 
 		// The light's own orientation and `scale` are already baked into the texture, so the
 		// scene is only correct at rotation 0 / intensity 1 — pinned, whatever the host's defaults.
@@ -2032,6 +2036,8 @@ export class AssetLoader extends EventDispatcher {
 
 				// Clone the camera to avoid modifying the original
 				const camera = object.clone();
+				// The clip animates the original; this lets the copy follow it.
+				camera.userData.__rayzeeSourceUuid = object.uuid;
 
 				// Apply world transforms — cameras may be children of
 				// transformed nodes, so local position/quaternion != world.

package/src/Processor/EmissiveTriangleBuilder.js

@@ -72,6 +72,7 @@ export class EmissiveTriangleBuilder {
 	extractEmissiveTriangles( triangleData, materials, triangleCount, table = null ) {
 
 		this.emissiveTriangles = [];
+		this._emissiveMeshes = null;
 		this.totalEmissivePower = 0;
 		this._totalTriangleCount = triangleCount;
 
@@ -172,6 +173,7 @@ export class EmissiveTriangleBuilder {
 					triangleIndex: i,
 					materialIndex: materialIndex,
 					meshIndex: meshIndex,
+					sideSign,
 					instanceLeaf: hasInstance ? table.tlasLeafIndex[ placement ] : - 1,
 					power: power,
 					area: area,
@@ -203,6 +205,74 @@ export class EmissiveTriangleBuilder {
 
 	}
 
+	/** Mesh indices owning at least one emissive triangle. */
+	get emissiveMeshes() {
+
+		return this._emissiveMeshes ??= new Set( this.emissiveTriangles.map( t => t.meshIndex ) );
+
+	}
+
+	/**
+	 * Re-measure every emitter at its placement's current matrix. Call buildLightBVH() after.
+	 * @param {Uint32Array|object} triangleData - packed triangle records, flat or chunked
+	 * @param {import('./InstanceTable.js').InstanceTable} table
+	 */
+	refreshTransforms( triangleData, table ) {
+
+		const chunked = triangleData && triangleData.chunks ? triangleData : null;
+		const chunkedF = chunked ? chunked.viewAs( Float32Array ) : null;
+		const flatF = chunked ? null : new Float32Array( triangleData.buffer, triangleData.byteOffset, triangleData.length );
+		const FLOATS_PER_TRIANGLE = TRIANGLE_DATA_LAYOUT.FLOATS_PER_TRIANGLE;
+		const m = table.world;
+
+		this.totalEmissivePower = 0;
+
+		for ( const tri of this.emissiveTriangles ) {
+
+			const f = chunked ? chunkedF.chunkFor( tri.triangleIndex ) : flatF;
+			const b = chunked ? chunked.baseOf( tri.triangleIndex ) : tri.triangleIndex * FLOATS_PER_TRIANGLE;
+			const v = [ f[ b ], f[ b + 1 ], f[ b + 2 ], f[ b + 4 ], f[ b + 5 ], f[ b + 6 ], f[ b + 8 ], f[ b + 9 ], f[ b + 10 ] ];
+
+			// As extraction resolves it.
+			const placement = table.placementRunOf?.( tri.meshIndex )?.start ?? - 1;
+			if ( placement >= 0 && table.isSet[ placement ] ) {
+
+				const o = placement * 16;
+				for ( let k = 0; k < 9; k += 3 ) {
+
+					const x = v[ k ], y = v[ k + 1 ], z = v[ k + 2 ];
+					v[ k ] = m[ o ] * x + m[ o + 4 ] * y + m[ o + 8 ] * z + m[ o + 12 ];
+					v[ k + 1 ] = m[ o + 1 ] * x + m[ o + 5 ] * y + m[ o + 9 ] * z + m[ o + 13 ];
+					v[ k + 2 ] = m[ o + 2 ] * x + m[ o + 6 ] * y + m[ o + 10 ] * z + m[ o + 14 ];
+
+				}
+
+			}
+
+			const [ v0x, v0y, v0z, v1x, v1y, v1z, v2x, v2y, v2z ] = v;
+			const area = this._calculateTriangleArea( v0x, v0y, v0z, v1x, v1y, v1z, v2x, v2y, v2z );
+			const e = tri.emissive;
+			tri.power = ( 0.2126 * e.r + 0.7152 * e.g + 0.0722 * e.b ) * tri.emissiveIntensity * area;
+			tri.area = area;
+
+			const nx = ( v1y - v0y ) * ( v2z - v0z ) - ( v1z - v0z ) * ( v2y - v0y );
+			const ny = ( v1z - v0z ) * ( v2x - v0x ) - ( v1x - v0x ) * ( v2z - v0z );
+			const nz = ( v1x - v0x ) * ( v2y - v0y ) - ( v1y - v0y ) * ( v2x - v0x );
+			const nl = ( Math.sqrt( nx * nx + ny * ny + nz * nz ) || 1 ) / tri.sideSign;
+			tri.nx = nx / nl; tri.ny = ny / nl; tri.nz = nz / nl;
+
+			tri.cx = ( v0x + v1x + v2x ) / 3; tri.cy = ( v0y + v1y + v2y ) / 3; tri.cz = ( v0z + v1z + v2z ) / 3;
+			tri.bMinX = Math.min( v0x, v1x, v2x ); tri.bMinY = Math.min( v0y, v1y, v2y ); tri.bMinZ = Math.min( v0z, v1z, v2z );
+			tri.bMaxX = Math.max( v0x, v1x, v2x ); tri.bMaxY = Math.max( v0y, v1y, v2y ); tri.bMaxZ = Math.max( v0z, v1z, v2z );
+
+			this.totalEmissivePower += tri.power;
+
+		}
+
+		this._buildDataArrays();
+
+	}
+
 	/**
 	 * Calculate triangle area using cross product
 	 */