rayzee 9.1.2 → 9.2.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "rayzee",
-  "version": "9.1.2",
+  "version": "9.2.1",
   "type": "module",
   "description": "Real-time WebGPU path tracing engine built on Three.js",
   "main": "dist/rayzee.umd.js",
@@ -9,7 +9,8 @@
     ".": {
       "import": "./dist/rayzee.es.js",
       "require": "./dist/rayzee.umd.js"
-    }
+    },
+    "./node": "./src/node/index.js"
   },
   "files": [
     "dist",

package/src/AssetConfig.js

@@ -5,7 +5,6 @@
  * Usage:
  *   import { configureAssets } from 'rayzee';
  *   configureAssets({
- *     stbnScalarAtlas: '/assets/stbn_scalar_atlas.png',
  *     dracoDecoderPath: '/draco/',
  *     cacheNamespace: 'my-app',
  *   });
@@ -14,10 +13,6 @@
  */
 
 const config = {
-	// STBN blue-noise atlases (NVIDIA-RTX/STBN). Decoded as Float32 textures.
-	stbnScalarAtlas: 'https://assets.rayzee.atulmourya.com/noise/stbn_scalar_atlas.png',
-	stbnVec2Atlas: 'https://assets.rayzee.atulmourya.com/noise/stbn_vec2_atlas.png',
-
 	// onnxruntime-web (loaded lazily by AI upscaler worker via dynamic import).
 	ortRuntimeUrl: 'https://cdn.jsdelivr.net/npm/onnxruntime-web@1.24.3/dist/ort.webgpu.bundle.min.mjs',
 	ortWasmPaths: 'https://cdn.jsdelivr.net/npm/onnxruntime-web@1.24.3/dist/',
@@ -62,6 +57,8 @@ const config = {
 	storage: 'auto',
 };
 
+const configured = new Set();
+
 /**
  * Override asset URLs and cache namespace. Partial — only provided keys are replaced.
  * @param {Partial<typeof config>} overrides
@@ -70,6 +67,14 @@ export function configureAssets( overrides ) {
 
 	if ( ! overrides ) return;
 	Object.assign( config, overrides );
+	for ( const key of Object.keys( overrides ) ) configured.add( key );
+
+}
+
+/** Whether a host set this key, as opposed to it being the default. */
+export function isAssetConfigured( key ) {
+
+	return configured.has( key );
 
 }
 

package/src/EngineEvents.js

@@ -35,6 +35,9 @@ export const EngineEvents = {
 	TRANSFORM_MODE_CHANGED: 'engine:transformModeChanged',
 
 	// Camera
+	CAMERA_SWITCHED: 'engine:cameraSwitched',
+	CAMERAS_UPDATED: 'engine:camerasUpdated',
+	FOCUS_CHANGED: 'engine:focusChanged',
 	AUTO_FOCUS_UPDATED: 'engine:autoFocusUpdated',
 	ORTHO_HEIGHT_UPDATED: 'engine:orthoHeightUpdated',
 	AUTO_EXPOSURE_UPDATED: 'engine:autoExposureUpdated',
@@ -63,9 +66,46 @@ export const EngineEvents = {
 	// Degradation
 	ISSUE: 'engine:issue',
 
-	// Scene metadata
+	// Scene and assets
+	MODEL_LOADED: 'engine:modelLoaded',
+	OBJECT3D_LOADED: 'engine:object3dLoaded',
+	MODEL_ADDED: 'engine:modelAdded',
+	SCENE_OBJECT_REMOVED: 'engine:sceneObjectRemoved',
+	SCENE_UNLOADED: 'engine:sceneUnloaded',
+	SCENE_REBUILD: 'engine:sceneRebuild',
+	SCENE_SPILLED: 'engine:sceneSpilled',
 	SCENE_METADATA_APPLIED: 'engine:sceneMetadataApplied',
+	ENVIRONMENT_LOADED: 'engine:environmentLoaded',
+	TEXTURES_REPROCESSED: 'engine:texturesReprocessed',
+
+	// Render size
+	RESOLUTION_CHANGED: 'engine:resolutionChanged',
+	RESERVED_RENDER_SIZE_CHANGED: 'engine:reservedRenderSizeChanged',
 
 	// Storage (OPFS): usage or entries changed
 	STORAGE_CHANGED: 'engine:storageChanged',
 };
+
+/**
+ * The names these events had before they moved under `engine:`. The app dispatches each under both
+ * until the next major.
+ */
+export const LEGACY_EVENT_NAMES = Object.freeze( {
+	[ EngineEvents.RENDER_COMPLETE ]: 'RenderComplete',
+	[ EngineEvents.RENDER_RESET ]: 'RenderReset',
+	[ EngineEvents.CAMERA_SWITCHED ]: 'CameraSwitched',
+	[ EngineEvents.CAMERAS_UPDATED ]: 'CamerasUpdated',
+	[ EngineEvents.FOCUS_CHANGED ]: 'focusChanged',
+	[ EngineEvents.MODEL_LOADED ]: 'ModelLoaded',
+	[ EngineEvents.OBJECT3D_LOADED ]: 'Object3DLoaded',
+	[ EngineEvents.MODEL_ADDED ]: 'ModelAdded',
+	[ EngineEvents.SCENE_OBJECT_REMOVED ]: 'SceneObjectRemoved',
+	[ EngineEvents.SCENE_UNLOADED ]: 'SceneUnloaded',
+	[ EngineEvents.SCENE_REBUILD ]: 'SceneRebuild',
+	[ EngineEvents.SCENE_SPILLED ]: 'SceneSpilled',
+	[ EngineEvents.SCENE_METADATA_APPLIED ]: 'SceneMetadataApplied',
+	[ EngineEvents.ENVIRONMENT_LOADED ]: 'EnvironmentLoaded',
+	[ EngineEvents.TEXTURES_REPROCESSED ]: 'TexturesReprocessed',
+	[ EngineEvents.RESOLUTION_CHANGED ]: 'resolution_changed',
+	[ EngineEvents.RESERVED_RENDER_SIZE_CHANGED ]: 'reserved_render_size_changed',
+} );

package/src/EngineIssues.js

@@ -30,6 +30,9 @@ export const ISSUE_CODES = Object.freeze( {
 	STORAGE_READ_FAILED: 'storage.read_failed',
 	STORAGE_ENTRY_CORRUPT: 'storage.entry_corrupt',
 	STORAGE_CACHE_MISMATCH: 'storage.cache_mismatch',
+	DENOISER_UNAVAILABLE: 'denoiser.unavailable',
+	OUTPUT_SOURCE_FALLBACK: 'output.source_fallback',
+	LIGHT_PLACEHOLDER_SKIPPED: 'light.placeholder_skipped',
 } );
 
 /** Strict throws on ERROR only. */

package/src/Headless.js

@@ -3,7 +3,7 @@
  * strict, physical profile, deterministic — all reversible, none reversible by accident.
  *
  * @example
- * const shot = await renderHeadless( { canvas, model: url, width: 1920, height: 1080, samples: 256 } );
+ * const shot = await renderHeadless( { model: url, width: 1920, height: 1080, samples: 256 } );
  */
 
 import { PathTracerApp } from './PathTracerApp.js';
@@ -11,7 +11,9 @@ import { PathTracerApp } from './PathTracerApp.js';
  * One render, start to finish, disposing the app afterwards.
  *
  * @param {Object} options
- * @param {HTMLCanvasElement} options.canvas - needed for the WebGPU surface, not for output
+ * @param {HTMLCanvasElement} [options.canvas] - leave it out and the app runs headless, on a canvas of
+ *   its own (see PathTracerApp's `headless` option); pass one only to also present to it
+ * @param {number} [options.hostMemoryGB] - see PathTracerApp; needed outside Chrome for renders above 2048
  * @param {string} [options.model] - URL to load before rendering
  * @param {number} [options.width=1920]
  * @param {number} [options.height=1080]
@@ -21,10 +23,12 @@ import { PathTracerApp } from './PathTracerApp.js';
  * @param {string} [options.profile='physical'] - see RENDER_PROFILES
  * @param {boolean} [options.deterministic=true]
  * @param {boolean} [options.allowEarlyRetire=false] - needs `deterministic: false` to be reachable
+ * @param {boolean} [options.denoise=false] - one final OIDN pass, read back instead of the raw accumulation
  * @param {Object} [options.settings] - applied after the model loads
  * @param {function(number): void} [options.onProgress] - running sample count
  * @returns {Promise<{data: Float32Array|Uint8ClampedArray, width: number, height: number,
- *   colorSpace: string, samples: number, retiredBy: string, issues: Object[], adapter: Object}>}
+ *   colorSpace: string, source: string, samples: number, retiredBy: string, issues: Object[], adapter: Object,
+ *   provenance: Object}>} `provenance` is {@link PathTracerApp#getProvenance} at the moment of capture
  */
 export async function renderHeadless( options ) {
 
@@ -51,11 +55,23 @@ export async function captureHeadless( app, {
 	samples = 64,
 	colorSpace = 'srgb',
 	allowEarlyRetire = false,
+	denoise = false,
 	onProgress = undefined,
 } = {} ) {
 
+	// Before accumulating: OIDN reads the albedo and normal buffers, which are only written while it is
+	// on. Not setOIDNEnabled(), whose refresh would wake the loop; renderFrames resets anyway.
+	const dm = app.denoisingManager;
+	if ( denoise && dm && ! dm.finalDenoise ) {
+
+		dm.applyOIDNEnabled( true );
+		dm._syncGBufferStages();
+
+	}
+
 	const accumulated = await app.renderFrames( samples, { onProgress, allowEarlyRetire } );
-	const frame = await app.renderToBuffer( { colorSpace } );
+	if ( denoise ) await app.runFinalDenoise();
+	const frame = await app.renderToBuffer( { colorSpace, source: denoise ? 'display' : 'accumulation' } );
 
 	return {
 		...frame,
@@ -63,6 +79,7 @@ export async function captureHeadless( app, {
 		retiredBy: accumulated < samples ? 'converged' : 'count',
 		issues: app.issues,
 		adapter: app.adapterInfo,
+		provenance: app.getProvenance(),
 	};
 
 }
@@ -82,12 +99,11 @@ export async function openHeadless( {
 	deterministic = true,
 	settings = null,
 	storage = false,
+	hostMemoryGB = undefined,
 } = {} ) {
 
-	if ( ! canvas ) throw new Error( 'openHeadless: a canvas is required' );
-
 	// Off unless asked for: cached state from an earlier run must not change what a batch renders.
-	const app = new PathTracerApp( canvas, { autoResize: false, strict, profile, storage } );
+	const app = new PathTracerApp( canvas ?? null, { autoResize: false, strict, profile, storage, hostMemoryGB } );
 
 	try {
 

package/src/HeadlessCanvas.js

@@ -0,0 +1,104 @@
+/**
+ * A canvas for a render nobody watches. three.js reads its size and asks it for a WebGPU context;
+ * the camera controls attach listeners to it. Here the context presents into a plain texture, and
+ * the listeners go nowhere, so no document, window or swapchain is needed. Read results with
+ * `renderToBuffer()`; there is no picture to capture from it.
+ */
+
+const inert = {
+	addEventListener() {},
+	removeEventListener() {},
+	dispatchEvent() {
+
+		return true;
+
+	},
+};
+
+class HeadlessGPUContext {
+
+	constructor( canvas ) {
+
+		this.canvas = canvas;
+		this._configuration = null;
+		this._texture = null;
+
+	}
+
+	configure( configuration ) {
+
+		this.unconfigure();
+		this._configuration = configuration;
+
+	}
+
+	unconfigure() {
+
+		this._texture?.destroy();
+		this._texture = null;
+		this._configuration = null;
+
+	}
+
+	getConfiguration() {
+
+		return this._configuration;
+
+	}
+
+	getCurrentTexture() {
+
+		if ( ! this._configuration ) throw new Error( 'HeadlessGPUContext: getCurrentTexture() before configure()' );
+
+		const width = Math.max( 1, this.canvas.width );
+		const height = Math.max( 1, this.canvas.height );
+
+		if ( this._texture?.width !== width || this._texture?.height !== height ) {
+
+			const { device, format, usage } = this._configuration;
+			this._texture?.destroy();
+			this._texture = device.createTexture( { label: 'headless-canvas', size: [ width, height ], format, usage } );
+
+		}
+
+		return this._texture;
+
+	}
+
+}
+
+/**
+ * @param {number} [width=1]
+ * @param {number} [height=1]
+ */
+export function createHeadlessCanvas( width = 1, height = 1 ) {
+
+	const ownerDocument = { ...inert, defaultView: null };
+
+	const canvas = {
+		...inert,
+		isHeadlessCanvas: true,
+		width,
+		height,
+		clientWidth: 0,
+		clientHeight: 0,
+		style: {},
+		parentNode: null,
+		ownerDocument,
+		getRootNode: () => ownerDocument,
+		getBoundingClientRect() {
+
+			return { x: 0, y: 0, left: 0, top: 0, right: this.width, bottom: this.height, width: this.width, height: this.height };
+
+		},
+		setPointerCapture() {},
+		releasePointerCapture() {},
+		hasPointerCapture: () => false,
+		focus() {},
+		getContext: ( type ) => ( type === 'webgpu' ? context : null ),
+	};
+
+	const context = new HeadlessGPUContext( canvas );
+	return canvas;
+
+}

package/src/Passes/OIDNDenoiser.js

@@ -12,7 +12,9 @@ async function getInitUNetFromBuffer() {
 
 	if ( ! _initUNetFromBuffer ) {
 
-		_initUNetFromBuffer = ( await import( 'oidn-web' ) ).initUNetFromBuffer;
+		// The bundle, not the package main: that is raw tsc output with extensionless imports,
+		// which Node's ESM resolver refuses.
+		_initUNetFromBuffer = ( await import( 'oidn-web/dist/oidn.js' ) ).initUNetFromBuffer;
 
 	}
 
@@ -365,7 +367,7 @@ export class OIDNDenoiser extends EventDispatcher {
 
 	}
 
-	async _setupUNetDenoiser() {
+	_setupUNetDenoiser() {
 
 		if ( this.state.isLoading ) {
 
@@ -373,10 +375,24 @@ export class OIDNDenoiser extends EventDispatcher {
 			// nothing would ever fetch them. Reachable on every render now that the refreshes and
 			// the finished image use different tiers. Flag it; the running load picks it up.
 			this._reloadPending = true;
-			return;
+			return Promise.resolve();
 
 		}
 
+		this._loading = this._loadUNet();
+		return this._loading;
+
+	}
+
+	/** Resolves once no weights are loading, including a reload queued behind the current one. */
+	whenLoaded() {
+
+		return this.state.isLoading ? this._loading : Promise.resolve();
+
+	}
+
+	async _loadUNet() {
+
 		do {
 
 			this._reloadPending = false;
@@ -389,7 +405,7 @@ export class OIDNDenoiser extends EventDispatcher {
 			} catch ( error ) {
 
 				log.error( 'UNet weights failed to load:', error );
-				this.dispatchEvent( { type: 'error', error: new Error( `Denoiser loading failed: ${error.message}` ) } );
+				this.dispatchEvent( { type: 'error', error: new Error( `Denoiser loading failed: ${error.message}` ), url: this._generateTzaUrl() } );
 
 			} finally {
 
@@ -973,6 +989,15 @@ export class OIDNDenoiser extends EventDispatcher {
 
 	}
 
+	/** Bytes of the GPU memory this pass allocates itself; oidn-web's network is not among them. */
+	gpuBytes() {
+
+		const { color, albedo, normal } = this._gpuInputBuffers;
+		const out = this._outGPUTexture ? this._outTexSize.width * this._outTexSize.height * 8 : 0; // rgba16float
+		return ( color?.size ?? 0 ) + ( albedo?.size ?? 0 ) + ( normal?.size ?? 0 ) + ( this._gpuInputPadBuffer?.size ?? 0 ) + out;
+
+	}
+
 	/**
 	 * Makes sure the output picture exists at the render size. A resize makes a new one rather than
 	 * resizing in place: three.js caches the card-side handle against the wrapper, so the wrapper

package/src/Passes/OIDNTemporalHistory.js

@@ -423,6 +423,13 @@ export class OIDNTemporalHistory {
 
 	}
 
+	gpuBytes() {
+
+		if ( ! this._sets ) return 0;
+		return this._sets.length * 3 * this.width * this.height * 16 + this._picked.size + this._copies.size;
+
+	}
+
 	_ensure( width, height ) {
 
 		if ( ! width || ! height ) return false;