rayzee 7.27.1 → 7.28.0

package/src/Processor/TextureCreator.js

@@ -1,6 +1,7 @@
 import { DataArrayTexture, RGBAFormat, LinearFilter, UnsignedByteType, SRGBColorSpace, RepeatWrapping } from "three";
 import { TEXTURE_CONSTANTS, MEMORY_CONSTANTS, DEFAULT_TEXTURE_MATRIX, MATERIAL_DATA_LAYOUT, normalizeAttenuationDistance } from '../EngineDefaults.js';
 import TexturesWorker from './Workers/TexturesWorker.js?worker&inline';
+import { ISSUE_CODES } from '../EngineIssues.js';
 
 // Canvas pooling for efficient reuse of canvas elements
 class CanvasPool {
@@ -460,6 +461,8 @@ export class TextureCreator {
 		this.maxConcurrentWorkers = TEXTURE_CONSTANTS.MAX_CONCURRENT_WORKERS;
 		this.activeWorkers = 0;
 
+		this._issues = options.issues ?? null;
+
 		// Longest-edge cap for material-texture arrays. Clamped to the hardware ceiling.
 		this.maxTextureSize = this._clampTextureSize(
 			options.maxTextureSize ?? TEXTURE_CONSTANTS.DEFAULT_MAX_TEXTURE_SIZE
@@ -479,6 +482,17 @@ export class TextureCreator {
 
 	}
 
+	/** A failed map array leaves those surfaces untextured — complete-looking and wrong. @private */
+	_reportTextureFailure( map, error ) {
+
+		this._issues?.record(
+			ISSUE_CODES.TEXTURE_BUILD_FAILED,
+			`${map} texture array failed to build — those surfaces render untextured`,
+			{ map, cause: String( error?.message ?? error ) }
+		);
+
+	}
+
 	_clampTextureSize( size ) {
 
 		const n = Math.floor( Number( size ) || TEXTURE_CONSTANTS.DEFAULT_MAX_TEXTURE_SIZE );
@@ -573,7 +587,11 @@ export class TextureCreator {
 
 		} catch ( error ) {
 
-			console.warn( 'Texture processing failed, trying fallback:', error );
+			this._issues?.warn(
+				ISSUE_CODES.TEXTURE_PROCESSING_FALLBACK,
+				'worker texture processing failed — retrying on the main thread',
+				{ cause: String( error?.message ?? error ) }
+			);
 			return await this.processOnMainThreadSync( normalized );
 
 		} finally {
@@ -1114,105 +1132,25 @@ export class TextureCreator {
 			// Create texture arrays
 			const texturePromises = [];
 
-			if ( maps && maps.length > 0 ) {
-
-				texturePromises.push(
-					this.createTexturesToDataTexture( maps )
-						.then( tex => ( { type: 'albedo', texture: tex } ) )
-						.catch( error => {
-
-							console.warn( 'Failed to create albedo textures:', error );
-							return { type: 'albedo', texture: null };
-
-						} )
-				);
-
-			}
-
-			if ( normalMaps && normalMaps.length > 0 ) {
-
-				texturePromises.push(
-					this.createTexturesToDataTexture( normalMaps )
-						.then( tex => ( { type: 'normal', texture: tex } ) )
-						.catch( error => {
-
-							console.warn( 'Failed to create normal textures:', error );
-							return { type: 'normal', texture: null };
-
-						} )
-				);
-
-			}
-
-			if ( bumpMaps && bumpMaps.length > 0 ) {
-
-				texturePromises.push(
-					this.createTexturesToDataTexture( bumpMaps )
-						.then( tex => ( { type: 'bump', texture: tex } ) )
-						.catch( error => {
-
-							console.warn( 'Failed to create bump textures:', error );
-							return { type: 'bump', texture: null };
-
-						} )
-				);
-
-			}
+			for ( const [ type, list ] of [
+				[ 'albedo', maps ],
+				[ 'normal', normalMaps ],
+				[ 'bump', bumpMaps ],
+				[ 'roughness', roughnessMaps ],
+				[ 'metalness', metalnessMaps ],
+				[ 'emissive', emissiveMaps ],
+				[ 'displacement', displacementMaps ],
+			] ) {
 
-			if ( roughnessMaps && roughnessMaps.length > 0 ) {
+				if ( ! list || list.length === 0 ) continue;
 
 				texturePromises.push(
-					this.createTexturesToDataTexture( roughnessMaps )
-						.then( tex => ( { type: 'roughness', texture: tex } ) )
+					this.createTexturesToDataTexture( list )
+						.then( texture => ( { type, texture } ) )
 						.catch( error => {
 
-							console.warn( 'Failed to create roughness textures:', error );
-							return { type: 'roughness', texture: null };
-
-						} )
-				);
-
-			}
-
-			if ( metalnessMaps && metalnessMaps.length > 0 ) {
-
-				texturePromises.push(
-					this.createTexturesToDataTexture( metalnessMaps )
-						.then( tex => ( { type: 'metalness', texture: tex } ) )
-						.catch( error => {
-
-							console.warn( 'Failed to create metalness textures:', error );
-							return { type: 'metalness', texture: null };
-
-						} )
-				);
-
-			}
-
-			if ( emissiveMaps && emissiveMaps.length > 0 ) {
-
-				texturePromises.push(
-					this.createTexturesToDataTexture( emissiveMaps )
-						.then( tex => ( { type: 'emissive', texture: tex } ) )
-						.catch( error => {
-
-							console.warn( 'Failed to create emissive textures:', error );
-							return { type: 'emissive', texture: null };
-
-						} )
-				);
-
-			}
-
-			if ( displacementMaps && displacementMaps.length > 0 ) {
-
-				texturePromises.push(
-					this.createTexturesToDataTexture( displacementMaps )
-						.then( tex => ( { type: 'displacement', texture: tex } ) )
-						.catch( error => {
-
-							console.warn( 'Failed to create displacement textures:', error );
-							return { type: 'displacement', texture: null };
+							this._reportTextureFailure( type, error );
+							return { type, texture: null };
 
 						} )
 				);
@@ -1222,6 +1160,10 @@ export class TextureCreator {
 			// Wait for all texture arrays to complete
 			const textureResults = await Promise.allSettled( texturePromises );
 
+			// allSettled would otherwise swallow a strict host's EngineIssueError.
+			const refused = textureResults.find( ( r ) => r.status === 'rejected' );
+			if ( refused ) throw refused.reason;
+
 			// Organize results
 			const textures = {};
 

package/src/Processor/ToneMapCPU.js

@@ -214,3 +214,42 @@ export function applySaturation( out, saturation ) {
 	out[ 2 ] = luma + ( out[ 2 ] - luma ) * saturation;
 
 }
+
+/**
+ * Linear float RGBA → sRGB bytes, in the output pass's order: exposure, saturation, curve,
+ * transfer function. Not interchangeable — moving any step shifts every mid-tone.
+ *
+ * @param {Float32Array} linear - RGBA, 4 floats per pixel
+ * @param {Object} options
+ * @param {number} options.exposure - renderer.toneMappingExposure, raw
+ * @param {number} options.toneMapping - Three.js ToneMapping constant
+ * @param {number} [options.saturation=1]
+ * @param {boolean} [options.preserveAlpha=false]
+ * @returns {Uint8ClampedArray} RGBA bytes
+ */
+export function toneMapToRGBA8( linear, { exposure, toneMapping, saturation = 1, preserveAlpha = false } ) {
+
+	const curve = TONE_MAP_FNS.get( toneMapping ) ?? TONE_MAP_FNS.get( NoToneMapping );
+	const gain = effectiveExposure( exposure, toneMapping );
+	const out = new Uint8ClampedArray( linear.length );
+	const scratch = [ 0, 0, 0 ];
+
+	for ( let i = 0; i < linear.length; i += 4 ) {
+
+		scratch[ 0 ] = linear[ i ] * gain;
+		scratch[ 1 ] = linear[ i + 1 ] * gain;
+		scratch[ 2 ] = linear[ i + 2 ] * gain;
+
+		applySaturation( scratch, saturation );
+		curve( scratch[ 0 ], scratch[ 1 ], scratch[ 2 ], 1.0, scratch );
+
+		out[ i ] = linearToSRGB( scratch[ 0 ] ) * 255 + 0.5;
+		out[ i + 1 ] = linearToSRGB( scratch[ 1 ] ) * 255 + 0.5;
+		out[ i + 2 ] = linearToSRGB( scratch[ 2 ] ) * 255 + 0.5;
+		out[ i + 3 ] = preserveAlpha ? linear[ i + 3 ] * 255 + 0.5 : 255;
+
+	}
+
+	return out;
+
+}

package/src/RenderSettings.js

@@ -1,6 +1,7 @@
 import { EventDispatcher, Color, Vector2, MathUtils } from 'three';
 import { ENGINE_DEFAULTS } from './EngineDefaults.js';
 import { EngineEvents } from './EngineEvents.js';
+import { ISSUE_CODES } from './EngineIssues.js';
 
 /**
  * Routing table: maps each setting key to its target stage/handler.
@@ -78,6 +79,14 @@ const SETTING_ROUTES = {
  * Default keys to extract from ENGINE_DEFAULTS for initializing the values map.
  * Maps ENGINE_DEFAULTS key → RenderSettings key when they differ.
  */
+/** Provenance tags for getEffective(). Add-only — hosts branch on them. */
+export const SETTING_SOURCE = Object.freeze( {
+	DEFAULT: 'default',
+	HOST: 'host',
+	SCENE_METADATA: 'scene-metadata',
+	MODE_PRESET: 'mode-preset',
+} );
+
 const DEFAULTS_KEY_MAP = {
 	bounces: 'maxBounces',
 	debugMode: 'visMode',
@@ -96,13 +105,23 @@ const DEFAULTS_KEY_MAP = {
  */
 export class RenderSettings extends EventDispatcher {
 
-	constructor( defaults = ENGINE_DEFAULTS ) {
+	/**
+	 * @param {Object} [defaults]
+	 * @param {Object} [options]
+	 * @param {import('./EngineIssues.js').IssueLog} [options.issues] - records unroutable keys
+	 */
+	constructor( defaults = ENGINE_DEFAULTS, { issues = null } = {} ) {
 
 		super();
 
+		this._issues = issues;
+
 		/** @type {Map<string, *>} */
 		this._values = new Map();
 
+		/** @type {Map<string, string>} - see getEffective() */
+		this._sources = new Map();
+
 		/** @type {import('./Stages/PathTracer.js').PathTracer|null} */
 		this._pathTracer = null;
 
@@ -272,24 +291,17 @@ export class RenderSettings extends EventDispatcher {
 	 * @param {boolean} [options.reset]  - Override the route's default reset behavior
 	 * @param {boolean} [options.silent] - Suppress the settingChanged event
 	 */
-	set( key, value, { reset, silent } = {} ) {
+	set( key, value, { reset, silent, source = SETTING_SOURCE.HOST } = {} ) {
 
-		const prev = this._values.get( key );
-		if ( prev === value ) return;
-
-		this._values.set( key, value );
-
-		const route = SETTING_ROUTES[ key ];
-		if ( ! route ) return;
-
-		this._applyRoute( route, value, prev );
+		const applied = this._applyOne( key, value, source );
+		if ( ! applied?.route ) return;
 
-		const shouldReset = reset !== undefined ? reset : ( route.reset ?? true );
+		const shouldReset = reset !== undefined ? reset : ( applied.route.reset ?? true );
 		if ( shouldReset ) this._resetCallback?.();
 
 		if ( ! silent ) {
 
-			this.dispatchEvent( { type: EngineEvents.SETTING_CHANGED, key, value, prev } );
+			this.dispatchEvent( { type: EngineEvents.SETTING_CHANGED, key, value, prev: applied.prev } );
 
 		}
 
@@ -301,28 +313,22 @@ export class RenderSettings extends EventDispatcher {
 	 * @param {Object} [options]
 	 * @param {boolean} [options.silent] - Suppress settingChanged events
 	 * @param {boolean} [options.reset]  - Override the routes' default reset behavior
+	 * @param {string}  [options.source] - Provenance tag; see SETTING_SOURCE
 	 */
-	setMany( updates, { silent, reset } = {} ) {
+	setMany( updates, { silent, reset, source = SETTING_SOURCE.HOST } = {} ) {
 
 		let needsReset = false;
 
 		for ( const [ key, value ] of Object.entries( updates ) ) {
 
-			const prev = this._values.get( key );
-			if ( prev === value ) continue;
+			const applied = this._applyOne( key, value, source );
+			if ( ! applied?.route ) continue;
 
-			this._values.set( key, value );
-
-			const route = SETTING_ROUTES[ key ];
-			if ( ! route ) continue;
-
-			this._applyRoute( route, value, prev );
-
-			if ( route.reset ?? true ) needsReset = true;
+			if ( applied.route.reset ?? true ) needsReset = true;
 
 			if ( ! silent ) {
 
-				this.dispatchEvent( { type: EngineEvents.SETTING_CHANGED, key, value, prev } );
+				this.dispatchEvent( { type: EngineEvents.SETTING_CHANGED, key, value, prev: applied.prev } );
 
 			}
 
@@ -333,12 +339,73 @@ export class RenderSettings extends EventDispatcher {
 
 	}
 
+	/**
+	 * Stores one value, tags its provenance and pushes it to its stage.
+	 * @returns {?{route: ?Object, prev: *}} null when the value did not change
+	 * @private
+	 */
+	_applyOne( key, value, source ) {
+
+		const prev = this._values.get( key );
+		if ( prev === value ) return null;
+
+		this._values.set( key, value );
+		this._sources.set( key, source );
+
+		const route = SETTING_ROUTES[ key ];
+		if ( ! route ) {
+
+			this._reportUnknownKey( key );
+			return { route: null, prev };
+
+		}
+
+		this._applyRoute( route, value, prev );
+		return { route, prev };
+
+	}
+
+	/** Stored but never applied: a typo becoming a wrong image. @private */
+	_reportUnknownKey( key ) {
+
+		this._issues?.record(
+			ISSUE_CODES.SETTING_UNKNOWN_KEY,
+			`unknown setting "${key}" — stored but never applied to any stage`,
+			{ key }
+		);
+
+	}
+
 	get( key ) {
 
 		return this._values.get( key );
 
 	}
 
+	/**
+	 * Every live setting with the value in force and who put it there. `routed: false` means
+	 * stored but reaching no stage — see _reportUnknownKey.
+	 *
+	 * @returns {Object<string, {value: *, source: string, routed: boolean}>}
+	 */
+	getEffective() {
+
+		const out = {};
+
+		for ( const [ key, value ] of this._values ) {
+
+			out[ key ] = {
+				value,
+				source: this._sources.get( key ) ?? SETTING_SOURCE.DEFAULT,
+				routed: SETTING_ROUTES[ key ] !== undefined,
+			};
+
+		}
+
+		return out;
+
+	}
+
 	getAll() {
 
 		return Object.fromEntries( this._values );
@@ -396,6 +463,7 @@ export class RenderSettings extends EventDispatcher {
 			if ( key in defaults ) {
 
 				this._values.set( key, defaults[ key ] );
+				this._sources.set( key, SETTING_SOURCE.DEFAULT );
 
 			}
 
@@ -407,6 +475,7 @@ export class RenderSettings extends EventDispatcher {
 			if ( defaultsKey in defaults ) {
 
 				this._values.set( settingsKey, defaults[ defaultsKey ] );
+				this._sources.set( settingsKey, SETTING_SOURCE.DEFAULT );
 
 			}
 

package/src/index.js

@@ -9,11 +9,20 @@
 import './TSL/patches.js';
 
 // Main application
-export { PathTracerApp } from './PathTracerApp.js';
+export { PathTracerApp, describeAdapter } from './PathTracerApp.js';
 
 // Event types
 export { EngineEvents } from './EngineEvents.js';
 
+// Headless rendering — the supported entry point for a caller with no screen
+export { renderHeadless, openHeadless, captureHeadless } from './Headless.js';
+
+// Degradation contract — what the engine survived instead of failing on
+export { ISSUE_CODES, ISSUE_SEVERITY, IssueLog, EngineIssueError } from './EngineIssues.js';
+
+// Settings provenance + viewer-vs-physical tuning
+export { SETTING_SOURCE } from './RenderSettings.js';
+
 // Asset URL / cache namespace overrides (call before constructing PathTracerApp)
 export { configureAssets, getAssetConfig } from './AssetConfig.js';
 
@@ -43,6 +52,8 @@ export {
 	PRODUCTION_RENDER_CONFIG,
 	INTERACTIVE_RENDER_CONFIG,
 	MAX_RESERVABLE_RENDER_SIZE,
+	RENDER_PROFILES,
+	getRenderProfile,
 } from './EngineDefaults.js';
 
 // Settings & managers (for advanced consumers)