rayzee 7.27.1 → 7.28.0

package/package.json

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

package/src/EngineDefaults.js

@@ -4,6 +4,45 @@
  * and should not depend on any UI framework or external modules.
  */
 
+/**
+ * Product decisions for a real-time viewer, not physical constants. Both are invisible from
+ * outside and both move output away from a reference renderer. `viewer` is the default.
+ */
+export const RENDER_PROFILES = Object.freeze( {
+	viewer: Object.freeze( {
+		areaLightIntensityScale: 0.1, // authored RectAreaLight watts from glTF placeholders
+		environmentRotation: 270.0, // degrees
+		toneMapping: 4, // ACESFilmicToneMapping
+		saturation: 1.2, // compensates for ACES desaturation — see Compositor
+	} ),
+	physical: Object.freeze( {
+		areaLightIntensityScale: 1.0,
+		environmentRotation: 0.0,
+		// AgX, matching Blender/Cycles' default view transform. ACES crushes shadows on this
+		// engine's own corpus (shade 1.48 vs AgX 3.01 from identical radiance).
+		toneMapping: 6,
+		saturation: 1.0, // no grade
+	} ),
+} );
+
+/**
+ * @param {string} [name] - a RENDER_PROFILES key
+ * @returns {{areaLightIntensityScale: number, environmentRotation: number}}
+ * @throws {Error} on an unknown name — a typo must not silently select viewer tuning
+ */
+export function getRenderProfile( name = 'viewer' ) {
+
+	const profile = RENDER_PROFILES[ name ];
+	if ( ! profile ) {
+
+		throw new Error( `unknown render profile "${name}" — expected one of ${Object.keys( RENDER_PROFILES ).join( ', ' )}` );
+
+	}
+
+	return profile;
+
+}
+
 export const ENGINE_DEFAULTS = {
 	// Canvas output
 	resolution: 512,
@@ -15,9 +54,9 @@ export const ENGINE_DEFAULTS = {
 	// to TEXTURE_CONSTANTS.MAX_TEXTURE_SIZE (hardware ceiling). Applied at scene load.
 	maxTextureSize: 4096,
 
-	toneMapping: 4,
+	toneMapping: RENDER_PROFILES.viewer.toneMapping,
 	exposure: 1,
-	saturation: 1.2,
+	saturation: RENDER_PROFILES.viewer.saturation,
 	enableEnvironment: true,
 	showBackground: true,
 	transparentBackground: false,
@@ -30,7 +69,7 @@ export const ENGINE_DEFAULTS = {
 	// primary-ray env lookup; lighting/reflections stay sharp. Samples = taps/frame (noise vs cost).
 	backgroundBlurriness: 0,
 	backgroundBlurSamples: 8,
-	environmentRotation: 270.0,
+	environmentRotation: RENDER_PROFILES.viewer.environmentRotation,
 	groundProjectionEnabled: false,
 	groundProjectionRadius: 100,
 	groundProjectionHeight: 15,

package/src/EngineEvents.js

@@ -55,4 +55,10 @@ export const EngineEvents = {
 	// Lifecycle
 	DISPOSE: 'engine:dispose',
 	DEVICE_LOST: 'engine:deviceLost',
+
+	// Degradation
+	ISSUE: 'engine:issue',
+
+	// Scene metadata
+	SCENE_METADATA_APPLIED: 'engine:sceneMetadataApplied',
 };

package/src/EngineIssues.js

@@ -0,0 +1,93 @@
+/**
+ * Structured record of what the engine degraded rather than failed on. Lenient hosts read
+ * `app.issues`; strict hosts throw at the point of degradation.
+ *
+ * Codes are API surface — add, never rename or repurpose.
+ */
+export const ISSUE_CODES = Object.freeze( {
+	ADAPTER_SOFTWARE: 'adapter.software',
+	ASSET_UNREACHABLE: 'asset.unreachable',
+	TEXTURE_BUILD_FAILED: 'texture.build_failed',
+	TEXTURE_PROCESSING_FALLBACK: 'texture.processing_fallback',
+	ENVIRONMENT_LOAD_FAILED: 'environment.load_failed',
+	SETTING_UNKNOWN_KEY: 'setting.unknown_key',
+	RENDER_SIZE_DECLINED: 'render.size_declined',
+	STAGE_RENDER_FAILED: 'stage.render_failed',
+	RENDER_RESERVE_CAPPED: 'render.reserve_capped',
+} );
+
+/** Strict throws on ERROR only. */
+export const ISSUE_SEVERITY = Object.freeze( { ERROR: 'error', WARNING: 'warning' } );
+
+export class EngineIssueError extends Error {
+
+	constructor( issue ) {
+
+		super( `[${issue.code}] ${issue.message}` );
+		this.name = 'EngineIssueError';
+		this.code = issue.code;
+		this.detail = issue.detail;
+
+	}
+
+}
+
+export class IssueLog {
+
+	/** @param {{strict?: boolean, onIssue?: function(Object): void}} [options] */
+	constructor( { strict = false, onIssue = null } = {} ) {
+
+		this.strict = strict === true;
+		this._onIssue = onIssue;
+		this._entries = [];
+
+	}
+
+	/** @throws {EngineIssueError} when strict and severity is 'error' */
+	record( code, message, detail = {}, severity = ISSUE_SEVERITY.ERROR ) {
+
+		const issue = Object.freeze( { code, message, detail, severity, at: Date.now() } );
+		this._entries.push( issue );
+
+		this._onIssue?.( issue );
+
+		if ( this.strict && severity === ISSUE_SEVERITY.ERROR ) throw new EngineIssueError( issue );
+
+		return issue;
+
+	}
+
+	warn( code, message, detail ) {
+
+		return this.record( code, message, detail, ISSUE_SEVERITY.WARNING );
+
+	}
+
+	/** @returns {Object[]} a copy */
+	get list() {
+
+		return this._entries.slice();
+
+	}
+
+	get errors() {
+
+		return this._entries.filter( ( issue ) => issue.severity === ISSUE_SEVERITY.ERROR );
+
+	}
+
+	clear() {
+
+		this._entries.length = 0;
+
+	}
+
+	/** Call from dispose(): onIssue captures the app, and this log outlives it via injectees. */
+	detach() {
+
+		this._onIssue = null;
+		this.strict = false;
+
+	}
+
+}

package/src/Headless.js

@@ -0,0 +1,114 @@
+/**
+ * The supported way to render without a person watching. Defaults are the batch renderer's —
+ * strict, physical profile, deterministic — all reversible, none reversible by accident.
+ *
+ * @example
+ * const shot = await renderHeadless( { canvas, model: url, width: 1920, height: 1080, samples: 256 } );
+ */
+
+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 {string} [options.model] - URL to load before rendering
+ * @param {number} [options.width=1920]
+ * @param {number} [options.height=1080]
+ * @param {number} [options.samples=64] - samples to accumulate
+ * @param {'linear'|'srgb'} [options.colorSpace='srgb']
+ * @param {boolean} [options.strict=true]
+ * @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 {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}>}
+ */
+export async function renderHeadless( options ) {
+
+	const app = await openHeadless( options );
+
+	try {
+
+		return await captureHeadless( app, options );
+
+	} finally {
+
+		app.dispose();
+
+	}
+
+}
+
+/**
+ * Accumulate and read back, against an app {@link openHeadless} already set up.
+ * @param {PathTracerApp} app
+ * @returns {Promise<Object>} the frame plus what the engine survived to produce it
+ */
+export async function captureHeadless( app, {
+	samples = 64,
+	colorSpace = 'srgb',
+	allowEarlyRetire = false,
+	onProgress = undefined,
+} = {} ) {
+
+	const accumulated = await app.renderFrames( samples, { onProgress, allowEarlyRetire } );
+	const frame = await app.renderToBuffer( { colorSpace } );
+
+	return {
+		...frame,
+		samples: accumulated,
+		retiredBy: accumulated < samples ? 'converged' : 'count',
+		issues: app.issues,
+		adapter: app.adapterInfo,
+	};
+
+}
+
+/**
+ * Setup only, keeping the app alive for several frames. The caller MUST dispose it.
+ * @param {Object} options - as {@link renderHeadless}, minus `samples`
+ * @returns {Promise<PathTracerApp>}
+ */
+export async function openHeadless( {
+	canvas,
+	model = null,
+	width = 1920,
+	height = 1080,
+	strict = true,
+	profile = 'physical',
+	deterministic = true,
+	settings = null,
+} = {} ) {
+
+	if ( ! canvas ) throw new Error( 'openHeadless: a canvas is required' );
+
+	const app = new PathTracerApp( canvas, { autoResize: false, strict, profile } );
+
+	try {
+
+		// Before init(): replayed once the device exists but before the stages allocate, so a
+		// >2048 render builds the storage pool once instead of building then re-building it.
+		app.setReservedRenderResolution( Math.max( width, height ) );
+
+		await app.init();
+		app.setCanvasSize( width, height );
+
+		if ( model ) await app.loadModel( model );
+		if ( settings ) app.settings.setMany( settings, { silent: true } );
+
+		// After the model: scene metadata can turn adaptive sampling back on.
+		if ( deterministic ) app.setDeterministicMode( true );
+
+		return app;
+
+	} catch ( error ) {
+
+		app.dispose(); // a half-built app still holds GPU memory
+		throw error;
+
+	}
+
+}