rayzee 7.24.0 → 7.26.0

package/src/Processor/SceneMetadata.js

@@ -0,0 +1,123 @@
+/**
+ * SceneMetadata.js
+ * Scene-level authoring metadata carried inside an asset file.
+ *
+ * glTF/GLB carries it in `extras`, which three's GLTFLoader surfaces in three
+ * places depending on where the exporter wrote it: top-level `extras` becomes
+ * `gltf.userData`, `asset.extras` stays on `gltf.asset.extras`, and a scene's
+ * `extras` becomes `gltf.scene.userData`. All three are scanned, and the payload
+ * may sit at the root or be namespaced under a `rayzee` key.
+ *
+ * Recognised payload:
+ *   {
+ *     "environment": {
+ *       "sourceFile": "https://.../brown_photostudio_02_1k.hdr",
+ *       "rotation": 0,      // degrees around Y, matches the environmentRotation setting
+ *       "intensity": 1      // drives both environmentIntensity and backgroundIntensity
+ *     }
+ *   }
+ *
+ * Values may also arrive as JSON strings — DCC custom-property round-trips often
+ * stringify nested objects — so every container is parsed leniently.
+ */
+
+const ENV_URL_KEYS = [ 'sourceFile', 'url', 'file' ];
+
+function asObject( value ) {
+
+	if ( typeof value === 'string' ) {
+
+		try {
+
+			const parsed = JSON.parse( value );
+			return ( parsed && typeof parsed === 'object' ) ? parsed : null;
+
+		} catch {
+
+			return null;
+
+		}
+
+	}
+
+	return ( value && typeof value === 'object' ) ? value : null;
+
+}
+
+function asNumber( value ) {
+
+	const n = typeof value === 'string' ? parseFloat( value ) : value;
+	return Number.isFinite( n ) ? n : undefined;
+
+}
+
+function pickPayload( container ) {
+
+	const obj = asObject( container );
+	if ( ! obj ) return null;
+
+	const scoped = asObject( obj.rayzee );
+	if ( scoped && scoped.environment !== undefined ) return scoped;
+
+	return obj.environment !== undefined ? obj : null;
+
+}
+
+function normalizeEnvironment( raw ) {
+
+	const env = asObject( raw );
+	if ( ! env ) return null;
+
+	const sourceFile = ENV_URL_KEYS
+		.map( key => env[ key ] )
+		.find( value => typeof value === 'string' && value.trim() );
+	if ( ! sourceFile ) return null;
+
+	const rotation = asNumber( env.rotation );
+	const intensity = asNumber( env.intensity );
+
+	const normalized = { sourceFile: sourceFile.trim() };
+	if ( rotation !== undefined ) normalized.rotation = rotation;
+	if ( intensity !== undefined ) normalized.intensity = Math.max( 0, intensity );
+
+	return normalized;
+
+}
+
+/**
+ * Reads scene metadata out of one `extras`-shaped container.
+ * @param {Object|string|null} container
+ * @returns {{ environment?: { sourceFile: string, rotation?: number, intensity?: number } }|null}
+ */
+export function parseSceneMetadata( container ) {
+
+	const payload = pickPayload( container );
+	if ( ! payload ) return null;
+
+	const environment = normalizeEnvironment( payload.environment );
+	return environment ? { environment } : null;
+
+}
+
+/**
+ * Reads scene metadata out of a GLTFLoader parse result.
+ * @param {Object} gltf - The object GLTFLoader resolves with
+ * @returns {{ environment?: { sourceFile: string, rotation?: number, intensity?: number } }|null}
+ */
+export function extractSceneMetadata( gltf ) {
+
+	if ( ! gltf ) return null;
+
+	const containers = [ gltf.userData, gltf.asset?.extras, gltf.scene?.userData ];
+	if ( Array.isArray( gltf.scenes ) ) containers.push( ...gltf.scenes.map( scene => scene?.userData ) );
+
+	for ( const container of containers ) {
+
+		const metadata = parseSceneMetadata( container );
+		if ( metadata ) return metadata;
+
+	}
+
+	return null;
+
+}

package/src/Processor/ToneMapCPU.js

@@ -140,15 +140,26 @@ function neutralToneMap( r, g, b, exposure, out ) {
 
 }
 
+/**
+ * Three.js clamps the fragment output with `.max( 0 )` *before* tone mapping
+ * (NodeMaterial.js, "force unsigned floats"), so the GPU curves never see a negative
+ * channel. Compositor's saturation grade (default 1.2) drives complementary channels
+ * below zero on a third of a typical frame, and AgX/Neutral mix those negatives across
+ * channels instead of clipping them — measured 7-10 levels of shadow error against the
+ * viewport until the readback clamps the same way.
+ */
+const clampNegative = fn => ( r, g, b, exposure, out ) =>
+	fn( r > 0 ? r : 0, g > 0 ? g : 0, b > 0 ? b : 0, exposure, out );
+
 /** Look-up table mapping Three.js ToneMapping constants to CPU functions. */
 export const TONE_MAP_FNS = new Map( [
-	[ NoToneMapping, noToneMap ],
-	[ LinearToneMapping, linearToneMap ],
-	[ ReinhardToneMapping, reinhardToneMap ],
-	[ CineonToneMapping, cineonToneMap ],
-	[ ACESFilmicToneMapping, acesFilmicToneMap ],
-	[ AgXToneMapping, agxToneMap ],
-	[ NeutralToneMapping, neutralToneMap ]
+	[ NoToneMapping, clampNegative( noToneMap ) ],
+	[ LinearToneMapping, clampNegative( linearToneMap ) ],
+	[ ReinhardToneMapping, clampNegative( reinhardToneMap ) ],
+	[ CineonToneMapping, clampNegative( cineonToneMap ) ],
+	[ ACESFilmicToneMapping, clampNegative( acesFilmicToneMap ) ],
+	[ AgXToneMapping, clampNegative( agxToneMap ) ],
+	[ NeutralToneMapping, clampNegative( neutralToneMap ) ]
 ] );
 
 /** sRGB gamma (1/2.2) — fast pow approximation. Prefer `linearToSRGB` when matching Three.js's output. */
@@ -165,6 +176,25 @@ export function linearToSRGB( c ) {
 
 }
 
+/**
+ * Exposure as the WebGPU output pass applies it.
+ *
+ * Three.js applies `toneMappingExposure` *inside* ToneMappingNode's tone-mapping branch, and
+ * that branch returns the colour untouched for NoToneMapping (ToneMappingNode.js: `if
+ * ( toneMapping === NoToneMapping ) return colorNode`). So exposure is a no-op on screen there,
+ * and a CPU readback that applies it anyway paints brighter than the viewport it replaces
+ * (measured +33.6 % at exposure 2).
+ *
+ * @param {number} exposure - renderer.toneMappingExposure
+ * @param {number} toneMapping - Three.js ToneMapping constant
+ * @returns {number}
+ */
+export function effectiveExposure( exposure, toneMapping ) {
+
+	return toneMapping === NoToneMapping ? 1.0 : exposure;
+
+}
+
 /** Rec.709 luminance coefficients (same as Display / Common.js). */
 const LUM_R = 0.2126, LUM_G = 0.7152, LUM_B = 0.0722;
 

package/src/RenderSettings.js

@@ -224,6 +224,7 @@ export class RenderSettings extends EventDispatcher {
 			handleRenderLimitMode: ( value ) => {
 
 				stages.pathTracer?.setRenderLimitMode?.( value );
+				reconcileCompletion?.();
 
 			},
 

package/src/Stages/PathTracerStage.js

@@ -1185,25 +1185,15 @@ export class PathTracerStage extends RenderStage {
 	}
 
 	/**
-	 * Update completion threshold based on render mode
+	 * Update completion threshold based on render mode. The ceiling holds in every limit mode —
+	 * uncapping it under a time budget lets a generous deadline silently slow every render.
 	 */
 	updateCompletionThreshold() {
 
-		const renderMode = this.renderMode.value;
-		const maxFrames = this.maxSamples.value;
-
-		if ( this.renderLimitMode === 'time' ) {
-
-			this.completionThreshold = Infinity;
-
-		} else {
-
-			this.completionThreshold = updateCompletionThreshold(
-				renderMode,
-				maxFrames
-			);
-
-		}
+		this.completionThreshold = updateCompletionThreshold(
+			this.renderMode.value,
+			this.maxSamples.value
+		);
 
 	}
 

package/src/index.js

@@ -17,6 +17,9 @@ export { EngineEvents } from './EngineEvents.js';
 // Asset URL / cache namespace overrides (call before constructing PathTracerApp)
 export { configureAssets, getAssetConfig } from './AssetConfig.js';
 
+// Scene-level authoring metadata embedded in model files (glTF `extras`)
+export { extractSceneMetadata, parseSceneMetadata } from './Processor/SceneMetadata.js';
+
 // Logging — leveled/namespaced console output shared with the workers
 export { Logger, createLogger, fmt, LOG_LEVELS } from './utils/Logger.js';
 

package/src/managers/EnvironmentManager.js

@@ -360,8 +360,11 @@ export class EnvironmentManager {
 	/**
 	 * Set environment map, build CDF, and update shader texture nodes.
 	 * @param {import('three').Texture|null} envMap
+	 * @param {Object}  [options]
+	 * @param {boolean} [options.buildCDF=true] - Skip when the caller builds the CDF itself
+	 *   (PathTracerApp.loadSceneData builds it in parallel with the BVH, then calls applyCDFResults).
 	 */
-	async setEnvironmentMap( envMap ) {
+	async setEnvironmentMap( envMap, { buildCDF = true } = {} ) {
 
 		// Free the outgoing env texture's GPU memory before it is orphaned. Skip: the
 		// reusable placeholder, an idempotent re-set of the same texture, and the HDRI
@@ -379,7 +382,7 @@ export class EnvironmentManager {
 
 		if ( envMap ) {
 
-			await this.buildEnvironmentCDF();
+			if ( buildCDF ) await this.buildEnvironmentCDF();
 
 		} else {
 
@@ -411,6 +414,35 @@ export class EnvironmentManager {
 
 	}
 
+	/**
+	 * Enter 'hdri' mode ahead of an async HDRI install, and drop the texture stashed by a
+	 * previous setMode( 'gradient' | 'color' | 'procedural' ): a new HDRI makes it
+	 * unreachable, so leaving it in place both leaks it and lets a setMode( 'hdri' )
+	 * arriving mid-download restore it over the map we are about to install.
+	 * @param {import('three').Texture} [incoming] - Never disposed, even if it is the stash.
+	 */
+	beginHDRI( incoming = null ) {
+
+		if ( this._previousHDRI && this._previousHDRI !== incoming ) this._previousHDRI.dispose?.();
+
+		this._previousHDRI = null;
+		this.envParams.mode = 'hdri';
+
+	}
+
+	/**
+	 * Install an HDRI as the active environment, switching the mode state machine to 'hdri'.
+	 * @param {import('three').Texture} envMap
+	 * @param {Object}  [options]
+	 * @param {boolean} [options.buildCDF=true]
+	 */
+	async applyHDRI( envMap, { buildCDF = true } = {} ) {
+
+		this.beginHDRI( envMap );
+		await this.setEnvironmentMap( envMap, { buildCDF } );
+
+	}
+
 	// ===== SKY GENERATORS =====
 
 	/**