rayzee 8.8.2 → 9.1.0

package/src/managers/EnvironmentManager.js

@@ -11,31 +11,51 @@ import {
 	RGBAFormat, RedFormat, FloatType, LinearFilter, Vector2, Vector3, Color, Matrix4, DataTexture,
 } from 'three';
 import { EquirectHDRInfo } from '../Processor/EquirectHDRInfo.js';
-import { ProceduralSky } from '../Processor/ProceduralSky.js';
+import { PhysicalSky } from '../Processor/PhysicalSky.js';
 import { SimpleSky } from '../Processor/SimpleSky.js';
+import { convertLinearTriple } from '../Color/WorkingMatrix.js';
 import { createLogger, fmt } from '../utils/Logger.js';
 
 const log = createLogger( 'env' );
 import { ENGINE_DEFAULTS as DEFAULT_STATE } from '../EngineDefaults.js';
 import { getActiveColorManagement } from '../Color/ColorManagement.js';
+import { loadCDF, saveCDF } from '../Storage/CDFCache.js';
+
+const SKY_WIDTH = 1024;
+const SKY_HEIGHT = 512;
+const DEG2RAD = Math.PI / 180;
+const _rotation = new Matrix4();
+
+// Bakes queued on the GPU at once. More only queue behind frames already waiting there.
+const SKY_BAKES_IN_FLIGHT = 4;
 
 export class EnvironmentManager {
 
 	/**
 	 * @param {Object} scene - Three.js scene
 	 * @param {import('./UniformManager').UniformManager} uniforms
+	 * @param {import('three/webgpu').WebGPURenderer} [renderer] - bakes the physical sky
 	 */
-	constructor( scene, uniforms ) {
+	constructor( scene, uniforms, renderer = null ) {
 
 		this.scene = scene;
 		this.uniforms = uniforms;
+		this.renderer = renderer;
 
 		// CDF computation engine
 		this.equirectHdrInfo = new EquirectHDRInfo();
 
 		// Sky renderers (lazy init)
-		this.proceduralSkyRenderer = null;
+		this.physicalSky = null;
 		this.simpleSkyRenderer = null;
+		this._sun = null;
+		this._skyRequested = false;
+		this._skyScheduled = false;
+		this._skyInFlight = 0;
+		this._skyCaughtUp = null;
+		this._resolveSky = null;
+		this._skyBakes = 0;
+		this._skyStatsBake = 0;
 
 		// Environment texture — 1×1 black placeholder for shader compilation. Filters must be
 		// Linear: DataTexture defaults to Nearest, which is unfilterable, and WGSLNodeBuilder then
@@ -71,12 +91,15 @@ export class EnvironmentManager {
 			// Solid Color Sky
 			solidSkyColor: new Color( DEFAULT_STATE.solidSkyColor ),
 
-			// Procedural Sky (Preetham Model)
+			// Physical sky. The sun direction is in the sky's own frame; environment rotation turns both.
 			skySunDirection: this._calculateInitialSunDirection(),
-			skySunIntensity: DEFAULT_STATE.skySunIntensity,
-			skyRayleighDensity: DEFAULT_STATE.skyRayleighDensity,
+			skySunStrength: DEFAULT_STATE.skySunStrength,
+			skySunSize: DEFAULT_STATE.skySunSize,
 			skyTurbidity: DEFAULT_STATE.skyTurbidity,
-			skyMieAnisotropy: DEFAULT_STATE.skyMieAnisotropy,
+			skyOzone: DEFAULT_STATE.skyOzone,
+			skyAirDensity: DEFAULT_STATE.skyAirDensity,
+			skyGroundAlbedo: new Color( DEFAULT_STATE.skyGroundAlbedo ),
+			skyAltitude: DEFAULT_STATE.skyAltitude,
 		};
 
 		/**
@@ -93,7 +116,7 @@ export class EnvironmentManager {
 	// ===== MODE STATE MACHINE =====
 
 	/**
-	 * Switches the environment mode (hdri, gradient, color, procedural).
+	 * Switches the environment mode (hdri, gradient, color, procedural — the physical sky).
 	 * Preserves the HDRI texture when switching away, restores when switching back.
 	 * @param {'hdri'|'gradient'|'color'|'procedural'} mode
 	 */
@@ -128,6 +151,8 @@ export class EnvironmentManager {
 
 		}
 
+		if ( mode !== 'procedural' && prev === 'procedural' ) this._releaseSky();
+
 		this.markDirty();
 		this.callbacks.onAutoExposureReset?.();
 		this._notifyReset();
@@ -143,6 +168,71 @@ export class EnvironmentManager {
 
 	}
 
+	// ===== SAVED SESSIONS =====
+
+	/** Where the HDRI came from (see Storage/CDFCache.js), shown or held while a sky is. */
+	get hdriSource() {
+
+		const hdri = this.envParams.mode === 'hdri' ? this.environmentTexture : this._previousHDRI;
+		return hdri?.userData?.__rayzeeSource ?? null;
+
+	}
+
+	/** The mode, the sky parameters and the HDRI's source, as plain data. */
+	serialize() {
+
+		const p = this.envParams;
+		return {
+			mode: p.mode,
+			hdri: this.hdriSource,
+			gradientZenithColor: p.gradientZenithColor.toArray(),
+			gradientHorizonColor: p.gradientHorizonColor.toArray(),
+			gradientGroundColor: p.gradientGroundColor.toArray(),
+			solidSkyColor: p.solidSkyColor.toArray(),
+			skyModel: 'atmosphere',
+			skySunDirection: p.skySunDirection.toArray(),
+			skySunStrength: p.skySunStrength,
+			skySunSize: p.skySunSize,
+			skyTurbidity: p.skyTurbidity,
+			skyOzone: p.skyOzone,
+			skyAirDensity: p.skyAirDensity,
+			skyGroundAlbedo: p.skyGroundAlbedo.toArray(),
+			skyAltitude: p.skyAltitude,
+		};
+
+	}
+
+	/**
+	 * Puts back {@link serialize}'s parameters and mode. The HDRI itself is the caller's to load
+	 * first: only it can resolve the source.
+	 */
+	async restore( state ) {
+
+		if ( ! state ) return;
+		const p = this.envParams;
+		// Sessions saved before the physical sky gave the same names other meanings.
+		const atmosphere = state.skyModel === 'atmosphere';
+		const colors = [ 'gradientZenithColor', 'gradientHorizonColor', 'gradientGroundColor', 'solidSkyColor', 'skySunDirection' ];
+		for ( const key of atmosphere ? [ ...colors, 'skyGroundAlbedo' ] : colors ) {
+
+			if ( Array.isArray( state[ key ] ) ) p[ key ].fromArray( state[ key ] );
+
+		}
+
+		if ( atmosphere ) {
+
+			for ( const key of [ 'skySunStrength', 'skySunSize', 'skyTurbidity', 'skyOzone', 'skyAirDensity', 'skyAltitude' ] ) {
+
+				if ( typeof state[ key ] === 'number' ) p[ key ] = state[ key ];
+
+			}
+
+		}
+
+		if ( state.mode && ( state.mode !== 'hdri' || p.mode !== 'hdri' ) ) await this.setMode( state.mode );
+
+	}
+
 	// ===== Aliases (match Sub-API surface for zero-churn migration) =====
 
 	/** @see envParams */
@@ -219,7 +309,7 @@ export class EnvironmentManager {
 
 		}
 
-		this.envCDFTexture?.dispose?.();
+		if ( ! this.envCDFTexture?._isPhysicalSky ) this.envCDFTexture?.dispose?.();
 		this.envCDFTexture = new DataTexture( data, texW, H, RedFormat, FloatType );
 		this.envCDFTexture.needsUpdate = true;
 
@@ -280,6 +370,7 @@ export class EnvironmentManager {
 		const rotationRadians = rotationDegrees * ( Math.PI / 180 );
 		this.environmentRotationMatrix.makeRotationY( rotationRadians );
 		this.uniforms.get( 'environmentMatrix' ).value.copy( this.environmentRotationMatrix );
+		this.refreshSun();
 
 	}
 
@@ -294,6 +385,7 @@ export class EnvironmentManager {
 
 		if ( ! this.scene.environment ) {
 
+			this._cdfSignature = null;
 			this._updateCDFTexture();
 			this.uniforms.set( 'envTotalSum', 0.0 );
 			this.uniforms.set( 'envCompensationDelta', 0.0 );
@@ -301,6 +393,9 @@ export class EnvironmentManager {
 
 		}
 
+		// Its table is built with it, on the GPU.
+		if ( this.scene.environment._isPhysicalSky ) return;
+
 		try {
 
 			const startTime = performance.now();
@@ -308,6 +403,7 @@ export class EnvironmentManager {
 
 			if ( ! textureForCDF.image ) {
 
+				this._cdfSignature = null;
 				this._updateCDFTexture();
 				this.uniforms.set( 'envTotalSum', 0.0 );
 				this.uniforms.set( 'envCompensationDelta', 0.0 );
@@ -315,7 +411,16 @@ export class EnvironmentManager {
 
 			}
 
-			if ( useWorker ) {
+			// The same pixels as last time: the tables and uniforms already describe them.
+			const signature = `${textureForCDF.uuid}:${textureForCDF.version}`;
+			if ( signature === this._cdfSignature ) return;
+
+			const cached = await loadCDF( textureForCDF ).catch( () => null );
+			if ( cached ) {
+
+				Object.assign( this.equirectHdrInfo, cached );
+
+			} else if ( useWorker ) {
 
 				await this.equirectHdrInfo.updateFromAsync( textureForCDF );
 
@@ -325,6 +430,8 @@ export class EnvironmentManager {
 
 			}
 
+			if ( ! cached ) saveCDF( textureForCDF, this.equirectHdrInfo ).catch( () => {} );
+			this._cdfSignature = signature;
 			this.cdfBuildTime = performance.now() - startTime;
 
 			this._updateCDFTexture();
@@ -340,11 +447,12 @@ export class EnvironmentManager {
 
 			log.info( fmt.list( [
 				fmt.px( this.envTexSize.x, this.envTexSize.y ),
-				`CDF ${fmt.ms( this.cdfBuildTime )}${useWorker ? '' : ' (main thread)'}`,
+				`CDF ${fmt.ms( this.cdfBuildTime )}${cached ? ' (stored)' : useWorker ? '' : ' (main thread)'}`,
 			] ) );
 
 		} catch ( error ) {
 
+			this._cdfSignature = null;
 			log.error( 'CDF build failed:', error );
 			this.uniforms.set( 'envTotalSum', 0.0 );
 			this.uniforms.set( 'envCompensationDelta', 0.0 );
@@ -391,7 +499,7 @@ export class EnvironmentManager {
 		// stashed by setMode() for a later sky→hdri restore. Only when actually
 		// installing a new non-null texture (the null-env branch keeps the old ref).
 		const oldTex = this.environmentTexture;
-		if ( envMap && oldTex && oldTex !== envMap && oldTex !== this._envPlaceholder && oldTex !== this._previousHDRI ) {
+		if ( envMap && oldTex && oldTex !== envMap && oldTex !== this._envPlaceholder && oldTex !== this._previousHDRI && ! oldTex._isPhysicalSky ) {
 
 			oldTex.dispose?.();
 
@@ -406,6 +514,7 @@ export class EnvironmentManager {
 
 		} else {
 
+			this._cdfSignature = null;
 			this._updateCDFTexture();
 			this.uniforms.set( 'envTotalSum', 0.0 );
 			this.uniforms.set( 'envCompensationDelta', 0.0 );
@@ -430,6 +539,8 @@ export class EnvironmentManager {
 
 		}
 
+		if ( envMap && oldTex?._isPhysicalSky && this.envParams.mode !== 'procedural' ) this._releaseSky();
+
 		this._notifyReset();
 
 	}
@@ -528,43 +639,158 @@ export class EnvironmentManager {
 	}
 
 	/**
-	 * Generate procedural (Preetham) sky texture and set as environment.
+	 * Bake the physical sky and set it as the environment. Requests made in one task become one
+	 * bake, queued straight away while the GPU keeps up and otherwise as soon as it finishes an
+	 * earlier one. Resolves once the environment has caught up with the latest request.
 	 */
-	async generateProceduralSkyTexture() {
+	generateProceduralSkyTexture() {
+
+		this._skyRequested = true;
+		this._skyCaughtUp ??= new Promise( resolve => void ( this._resolveSky = resolve ) );
+		this._pumpSky();
+		return this._skyCaughtUp;
+
+	}
 
-		if ( ! this.proceduralSkyRenderer ) {
+	/** @private */
+	_pumpSky() {
+
+		if ( this._skyScheduled || ! this._skyRequested || this._skyInFlight >= SKY_BAKES_IN_FLIGHT ) return;
+		this._skyScheduled = true;
+		queueMicrotask( () => {
+
+			this._skyScheduled = false;
+			if ( this._skyRequested && this._skyInFlight < SKY_BAKES_IN_FLIGHT ) this._bakePhysicalSky();
 
-			this.proceduralSkyRenderer = new ProceduralSky( 512, 256 );
+		} );
+
+	}
+
+	/** @private */
+	_settleSky() {
+
+		const resolve = this._resolveSky;
+		this._skyCaughtUp = this._resolveSky = null;
+		resolve?.();
+
+	}
+
+	/** @private */
+	async _bakePhysicalSky() {
+
+		this._skyRequested = false;
+		const p = this.envParams;
+		if ( ! this.renderer || p.mode !== 'procedural' ) {
+
+			if ( ! this.renderer ) log.warn( 'physical sky needs a renderer' );
+			if ( this._skyInFlight === 0 ) this._settleSky();
+			return;
 
 		}
 
-		const params = {
-			sunDirection: this.envParams.skySunDirection.clone(),
-			sunIntensity: this.envParams.skySunIntensity * 0.05,
-			rayleighDensity: this.envParams.skyRayleighDensity * 2.0,
-			mieDensity: this.envParams.skyTurbidity * 0.005,
-			mieAnisotropy: this.envParams.skyMieAnisotropy,
-			turbidity: this.envParams.skyTurbidity * 2.0,
-		};
+		const sky = this.physicalSky ??= new PhysicalSky( SKY_WIDTH, SKY_HEIGHT );
+		const albedo = p.skyGroundAlbedo;
+		const bake = ++ this._skyBakes;
+		const latest = () => bake === this._skyBakes && ! this._skyRequested;
+		this._skyInFlight ++;
 
 		try {
 
-			const texture = this.proceduralSkyRenderer.render( params );
-			texture._isGeneratedProcedural = true;
-			await this.setEnvironmentMap( texture );
+			const { texture, cdfTexture, sun, stats } = sky.bake( this.renderer, {
+				sunDirection: p.skySunDirection.toArray(),
+				turbidity: p.skyTurbidity,
+				ozone: p.skyOzone,
+				airDensity: p.skyAirDensity,
+				groundAlbedo: [ albedo.r, albedo.g, albedo.b ],
+				altitude: p.skyAltitude,
+				sunAngularDiameter: p.skySunSize * DEG2RAD,
+				sunStrength: p.skySunStrength,
+			} );
+			this._sun = sun;
+			this._installSky( texture, cdfTexture );
+
+			// Frames until they land normalise by an older bake's.
+			const { totalSum, compensationDelta } = await stats;
+			if ( p.mode === 'procedural' && sky === this.physicalSky && bake > this._skyStatsBake ) {
+
+				this._skyStatsBake = bake;
+				this.uniforms.set( 'envTotalSum', totalSum );
+				this.uniforms.set( 'envCompensationDelta', compensationDelta );
+				if ( latest() ) this._notifyReset();
 
-			this.uniforms.get( 'sunDirection' ).value.copy( this.envParams.skySunDirection );
-			this.uniforms.set( 'sunAngularSize', 0.0087 );
-			this.uniforms.set( 'hasSun', 1 );
+			}
 
-			log.debug( `sun synced · dir ${this.envParams.skySunDirection.toArray().map( v => v.toFixed( 2 ) ).join( ',' )}` );
+			if ( latest() ) log.debug( `physical sky ${fmt.ms( sky.getLastRenderTime() )} · sun ${sun.radiance.map( v => v.toPrecision( 3 ) ).join( ',' )}` );
 
 		} catch ( error ) {
 
-			log.error( 'procedural sky generation failed:', error );
+			log.error( 'physical sky generation failed:', error );
+
+		} finally {
+
+			this._skyInFlight --;
+			if ( latest() ) this._settleSky();
+			else this._pumpSky();
+
+		}
+
+	}
+
+	/** @private */
+	_installSky( texture, cdfTexture ) {
+
+		const oldTex = this.environmentTexture;
+		if ( oldTex && oldTex !== texture && oldTex !== this._envPlaceholder && oldTex !== this._previousHDRI ) oldTex.dispose?.();
+		if ( this.envCDFTexture !== cdfTexture ) {
+
+			this.envCDFTexture?.dispose?.();
+			this.envCDFTexture = cdfTexture;
 
 		}
 
+		// So an HDRI coming back rebuilds its own table.
+		this._cdfSignature = null;
+		texture._isGeneratedProcedural = true;
+		this.scene.environment = texture;
+		this.environmentTexture = texture;
+		this.envTexSize.set( texture.image.width, texture.image.height );
+		this.uniforms.get( 'envResolution' ).value.set( texture.image.width, texture.image.height );
+		const nodes = this.callbacks.getSceneTextureNodes?.();
+		if ( nodes?.envTex ) nodes.envTex.value = texture;
+		this.refreshSun();
+		this._notifyReset();
+
+	}
+
+	/** @private */
+	_releaseSky() {
+
+		if ( ! this.physicalSky ) return;
+		this.physicalSky.dispose( this.renderer );
+		this.physicalSky = null;
+		this._sun = null;
+		this.refreshSun();
+
+	}
+
+	/**
+	 * Push the sun to the shader: into world space through the environment rotation, and into
+	 * the working colour space. Call after either changes.
+	 */
+	refreshSun() {
+
+		const sun = this.envParams.mode === 'procedural' ? this._sun : null;
+		const on = !! sun && sun.radiance.some( v => v > 0 );
+		this.uniforms.set( 'hasSun', on ? 1 : 0 );
+		if ( ! on ) return;
+
+		const direction = this.uniforms.get( 'sunDirection' ).value;
+		direction.fromArray( sun.direction ).transformDirection( _rotation.copy( this.environmentRotationMatrix ).transpose() );
+		const rgb = [ ...sun.radiance ];
+		convertLinearTriple( rgb );
+		this.uniforms.get( 'sunRadiance' ).value.fromArray( rgb );
+		this.uniforms.get( 'sunParams' ).value.set( sun.cosHalfAngle, sun.solidAngle, 1 / ( sun.sinHalfAngle * sun.sinHalfAngle ), sun.horizonSin );
+
 	}
 
 	// ===== HELPERS =====
@@ -597,8 +823,12 @@ export class EnvironmentManager {
 
 	dispose() {
 
-		this.proceduralSkyRenderer = null;
+		this.callbacks = {};
+		this._settleSky();
+		this.physicalSky?.dispose( this.renderer );
+		this.physicalSky = null;
 		this.simpleSkyRenderer = null;
+		this._sun = null;
 
 		this.envCDFTexture?.dispose?.();
 		this.envCDFTexture = null;

package/src/managers/GoboManager.js

@@ -1,4 +1,5 @@
 import { DataArrayTexture, LinearFilter, RGBAFormat, UnsignedByteType } from 'three';
+import { cachedObjectURL } from '../Storage/DownloadCache.js';
 
 /**
  * Manages projection masks ("gobos" / "cookies") for spot lights.
@@ -256,17 +257,27 @@ export class GoboManager {
 
 }
 
-function loadImage( url ) {
+async function loadImage( url ) {
 
-	return new Promise( ( resolve, reject ) => {
+	const source = await cachedObjectURL( url );
 
-		const img = new Image();
-		img.crossOrigin = 'anonymous';
-		img.onload = () => resolve( img );
-		img.onerror = () => reject( new Error( `Failed to load gobo image: ${url}` ) );
-		img.src = url;
+	try {
 
-	} );
+		return await new Promise( ( resolve, reject ) => {
+
+			const img = new Image();
+			img.crossOrigin = 'anonymous';
+			img.onload = () => resolve( img );
+			img.onerror = () => reject( new Error( `Failed to load gobo image: ${url}` ) );
+			img.src = source.url;
+
+		} );
+
+	} finally {
+
+		source.release();
+
+	}
 
 }
 

package/src/managers/IESManager.js

@@ -1,5 +1,6 @@
 import { DataArrayTexture, LinearFilter, RGBAFormat, UnsignedByteType } from 'three';
 import { parseIES, resampleIESToGrid, deriveIESBeamAngle, deriveIESPenumbra } from '../Processor/IESParser.js';
+import { sharedDownloads } from '../Storage/DownloadCache.js';
 
 /**
  * Manages IES photometric profiles for spot lights.
@@ -63,9 +64,8 @@ export class IESManager {
 
 			try {
 
-				const res = await fetch( it.url );
-				if ( ! res.ok ) throw new Error( `HTTP ${res.status}` );
-				const text = await res.text();
+				const { file, release } = await sharedDownloads().fetch( it.url );
+				const text = await file.text().finally( release );
 				const profile = parseIES( text, it.name );
 				const grid = resampleIESToGrid( profile, gridWidth, gridHeight );
 				return { it, profile, grid };

package/src/managers/InteractionManager.js

@@ -3,9 +3,28 @@ import {
 	Raycaster,
 	SphereGeometry,
 	Mesh,
-	MeshBasicMaterial
+	MeshBasicMaterial,
+	Vector3
 } from 'three';
 import { EngineEvents } from '../EngineEvents.js';
+import { CAMERA_PROJECTION_IDS } from '../EngineDefaults.js';
+
+const _viewAxis = new Vector3();
+const _toPoint = new Vector3();
+
+/** Depth of a point along the camera's view axis — the distance the flat focal plane is measured in. */
+export function viewDepth( point, camera ) {
+
+	return _toPoint.subVectors( point, camera.position ).dot( camera.getWorldDirection( _viewAxis ) );
+
+}
+
+/** The focus distance that puts a raycast hit in focus: a panorama focuses along each ray, not on a plane. */
+export function focusDistanceOfHit( hit, camera, panorama = false ) {
+
+	return panorama ? hit.distance : viewDepth( hit.point, camera );
+
+}
 
 /**
  * InteractionManager
@@ -207,7 +226,8 @@ export class InteractionManager extends EventDispatcher {
 		if ( intersects.length > 0 ) {
 
 			const intersection = intersects[ 0 ];
-			const distance = intersection.distance;
+			const panorama = this.pathTracer?.cameraProjection?.value === CAMERA_PROJECTION_IDS.equirectangular;
+			const distance = focusDistanceOfHit( intersection, this.camera, panorama );
 
 			// Show visual indicator at focus point
 			this.showFocusPoint( intersection.point );
@@ -675,6 +695,14 @@ export class InteractionManager extends EventDispatcher {
 
 	}
 
+	/** The nearest scene surface under an NDC point, skipping the floor and helpers. */
+	pickSurface( ndcX, ndcY ) {
+
+		this.raycaster.setFromCamera( { x: ndcX, y: ndcY }, this.camera );
+		return this.filterValidIntersects( this.raycaster.intersectObjects( this.scene.children, true ) )[ 0 ] ?? null;
+
+	}
+
 	/**
 	 * Filter intersections to exclude helper objects and floor plane
 	 * @private