rayzee 9.4.1 → 9.5.0

package/src/managers/EnvironmentManager.js

@@ -1,6 +1,6 @@
 /**
  * EnvironmentManager.js
- * Manages HDRI loading, CDF importance sampling, procedural/gradient/solid sky
+ * Manages HDRI loading, CDF importance sampling, procedural/solid sky
  * generation, and environment rotation for the path tracing pipeline.
  *
  * Storage buffer nodes are created once and never replaced — only .value
@@ -8,18 +8,19 @@
  */
 
 import {
-	RGBAFormat, RedFormat, FloatType, LinearFilter, Vector2, Vector3, Color, Matrix4, DataTexture,
+	RGBAFormat, FloatType, LinearFilter, Vector2, Vector3, Color, Matrix4, DataTexture,
 } from 'three';
 import { EquirectHDRInfo } from '../Processor/EquirectHDRInfo.js';
-import { PhysicalSky } from '../Processor/PhysicalSky.js';
+import { packExactTable } from '../Processor/EnvironmentExactTable.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 { getActiveColorManagement } from '../Color/ActiveColor.js';
 import { loadCDF, saveCDF } from '../Storage/CDFCache.js';
+import { ISSUE_CODES } from '../EngineIssues.js';
 
 const SKY_WIDTH = 1024;
 const SKY_HEIGHT = 512;
@@ -45,7 +46,12 @@ export class EnvironmentManager {
 		// CDF computation engine
 		this.equirectHdrInfo = new EquirectHDRInfo();
 
-		// Sky renderers (lazy init)
+		// Sky renderers (lazy init). The physical sky is a capability: setProceduralSky() installs its class.
+		this.ProceduralSky = null;
+		this._loadProceduralSky = null;
+		this._proceduralSkyLoading = null;
+		/** @type {?import('../EngineIssues.js').IssueLog} */
+		this.issues = null;
 		this.physicalSky = null;
 		this.simpleSkyRenderer = null;
 		this._sun = null;
@@ -83,11 +89,6 @@ export class EnvironmentManager {
 		this.envParams = {
 			mode: 'hdri',
 
-			// Gradient Sky
-			gradientZenithColor: new Color( DEFAULT_STATE.gradientZenithColor ),
-			gradientHorizonColor: new Color( DEFAULT_STATE.gradientHorizonColor ),
-			gradientGroundColor: new Color( DEFAULT_STATE.gradientGroundColor ),
-
 			// Solid Color Sky
 			solidSkyColor: new Color( DEFAULT_STATE.solidSkyColor ),
 
@@ -104,7 +105,7 @@ export class EnvironmentManager {
 
 		/**
 		 * Optional callbacks set by the owning stage.
-		 * @type {{ onReset?: Function, onAutoExposureReset?: Function, getSceneTextureNodes?: Function }}
+		 * @type {{ onReset?: Function, onLightingChanged?: Function, getSceneTextureNodes?: Function }}
 		 */
 		this.callbacks = {};
 
@@ -116,9 +117,9 @@ export class EnvironmentManager {
 	// ===== MODE STATE MACHINE =====
 
 	/**
-	 * Switches the environment mode (hdri, gradient, color, procedural — the physical sky).
+	 * Switches the environment mode (hdri, color, procedural — the physical sky).
 	 * Preserves the HDRI texture when switching away, restores when switching back.
-	 * @param {'hdri'|'gradient'|'color'|'procedural'} mode
+	 * @param {'hdri'|'color'|'procedural'} mode
 	 */
 	async setMode( mode ) {
 
@@ -132,11 +133,7 @@ export class EnvironmentManager {
 
 		}
 
-		if ( mode === 'gradient' ) {
-
-			await this.generateGradientTexture();
-
-		} else if ( mode === 'color' ) {
+		if ( mode === 'color' ) {
 
 			await this.generateSolidColorTexture();
 
@@ -154,7 +151,7 @@ export class EnvironmentManager {
 		if ( mode !== 'procedural' && prev === 'procedural' ) this._releaseSky();
 
 		this.markDirty();
-		this.callbacks.onAutoExposureReset?.();
+		this.callbacks.onLightingChanged?.();
 		this._notifyReset();
 
 	}
@@ -185,9 +182,6 @@ export class EnvironmentManager {
 		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(),
@@ -212,7 +206,7 @@ export class EnvironmentManager {
 		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' ];
+		const colors = [ 'solidSkyColor', 'skySunDirection' ];
 		for ( const key of atmosphere ? [ ...colors, 'skyGroundAlbedo' ] : colors ) {
 
 			if ( Array.isArray( state[ key ] ) ) p[ key ].fromArray( state[ key ] );
@@ -229,7 +223,9 @@ export class EnvironmentManager {
 
 		}
 
-		if ( state.mode && ( state.mode !== 'hdri' || p.mode !== 'hdri' ) ) await this.setMode( state.mode );
+		// A session saved with the removed gradient sky keeps the sky it is already showing.
+		const known = [ 'hdri', 'color', 'procedural' ].includes( state.mode );
+		if ( known && ( state.mode !== 'hdri' || p.mode !== 'hdri' ) ) await this.setMode( state.mode );
 
 	}
 
@@ -249,13 +245,6 @@ export class EnvironmentManager {
 
 	}
 
-	/** @see generateGradientTexture */
-	generateGradient() {
-
-		return this.generateGradientTexture();
-
-	}
-
 	/** @see generateSolidColorTexture */
 	generateSolid() {
 
@@ -276,42 +265,43 @@ export class EnvironmentManager {
 	 * Initialize the packed CDF storage buffer with placeholder data.
 	 * Must be called before shader compilation so the node exists in the graph.
 	 *
-	 * 1×1 R32F placeholder until a real env CDF is built (env IS is off meanwhile).
+	 * 1×1 RGBA32F placeholder until a real env table is built (env IS is off meanwhile).
 	 * @private
 	 */
 	_initCDFTexture() {
 
-		this.envCDFTexture = new DataTexture( new Float32Array( [ 0 ] ), 1, 1, RedFormat, FloatType );
+		this.envCDFTexture = new DataTexture( new Float32Array( 4 ), 1, 1, RGBAFormat, FloatType );
 		this.envCDFTexture.needsUpdate = true;
+		this._exactTable = null;
 
 	}
 
 	/**
-	 * Rebuild the CDF texture from equirectHdrInfo. Packs the 2D conditional + 1D marginal into one
-	 * R32F texture of (W+1)×H: conditional[cy*W+cx] at texel (cx, cy); marginal[cy] at texel (W, cy).
+	 * Rebuild the CDF texture from equirectHdrInfo's table, laid out as packExactTable (EnvironmentExactTable.js)
+	 * has it.
 	 * @private
 	 */
 	_updateCDFTexture() {
 
-		const marginal = this.equirectHdrInfo.marginalData;
-		const conditional = this.equirectHdrInfo.conditionalData;
-		if ( ! marginal || ! conditional ) return;
+		const info = this.equirectHdrInfo;
+		if ( ! info.exactConditional || ! ( info.exactWidth > 0 ) ) return;
 
-		const W = this.equirectHdrInfo.width;
-		const H = this.equirectHdrInfo.height;
-		const texW = W + 1;
-		const data = new Float32Array( texW * H );
-		for ( let cy = 0; cy < H; cy ++ ) {
+		const { data, width, height } = packExactTable( info );
+		if ( ! this.envCDFTexture?._isPhysicalSky ) this.envCDFTexture?.dispose?.();
+		this.envCDFTexture = new DataTexture( data, width, height, RGBAFormat, FloatType );
+		this.envCDFTexture.needsUpdate = true;
+		this._exactTable = { radianceIntegral: info.radianceIntegral };
 
-			const dstRow = cy * texW;
-			data.set( conditional.subarray( cy * W, cy * W + W ), dstRow ); // conditional → columns [0,W)
-			data[ dstRow + W ] = marginal[ cy ]; // marginal → column W
+	}
 
-		}
+	/**
+	 * The environment as a bidirectional light source: ∫ luminance dω of the map, before intensity, while the
+	 * CDF texture carries its table; null otherwise.
+	 * @returns {?{ radianceIntegral: number }}
+	 */
+	get exactTable() {
 
-		if ( ! this.envCDFTexture?._isPhysicalSky ) this.envCDFTexture?.dispose?.();
-		this.envCDFTexture = new DataTexture( data, texW, H, RedFormat, FloatType );
-		this.envCDFTexture.needsUpdate = true;
+		return this.scene.environment ? this._exactTable ?? null : null;
 
 	}
 
@@ -388,7 +378,6 @@ export class EnvironmentManager {
 			this._cdfSignature = null;
 			this._updateCDFTexture();
 			this.uniforms.set( 'envTotalSum', 0.0 );
-			this.uniforms.set( 'envCompensationDelta', 0.0 );
 			return;
 
 		}
@@ -406,7 +395,6 @@ export class EnvironmentManager {
 				this._cdfSignature = null;
 				this._updateCDFTexture();
 				this.uniforms.set( 'envTotalSum', 0.0 );
-				this.uniforms.set( 'envCompensationDelta', 0.0 );
 				return;
 
 			}
@@ -436,7 +424,6 @@ export class EnvironmentManager {
 
 			this._updateCDFTexture();
 			this.uniforms.set( 'envTotalSum', this.equirectHdrInfo.totalSum );
-			this.uniforms.set( 'envCompensationDelta', this.equirectHdrInfo.compensationDelta );
 
 			const { width, height } = this.equirectHdrInfo;
 			if ( width && height ) {
@@ -455,7 +442,6 @@ export class EnvironmentManager {
 			this._cdfSignature = null;
 			log.error( 'CDF build failed:', error );
 			this.uniforms.set( 'envTotalSum', 0.0 );
-			this.uniforms.set( 'envCompensationDelta', 0.0 );
 
 		}
 
@@ -517,7 +503,6 @@ export class EnvironmentManager {
 			this._cdfSignature = null;
 			this._updateCDFTexture();
 			this.uniforms.set( 'envTotalSum', 0.0 );
-			this.uniforms.set( 'envCompensationDelta', 0.0 );
 
 		}
 
@@ -547,7 +532,7 @@ 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
+	 * previous setMode( '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.
@@ -576,38 +561,6 @@ export class EnvironmentManager {
 
 	// ===== SKY GENERATORS =====
 
-	/**
-	 * Generate gradient sky texture and set as environment.
-	 */
-	async generateGradientTexture() {
-
-		if ( ! this.simpleSkyRenderer ) {
-
-			this.simpleSkyRenderer = new SimpleSky( 512, 256 );
-
-		}
-
-		const params = {
-			zenithColor: this.envParams.gradientZenithColor,
-			horizonColor: this.envParams.gradientHorizonColor,
-			groundColor: this.envParams.gradientGroundColor,
-		};
-
-		try {
-
-			const texture = this.simpleSkyRenderer.renderGradient( params );
-			texture._isGeneratedProcedural = true;
-			await this.setEnvironmentMap( texture );
-			this.uniforms.set( 'hasSun', 0 );
-
-		} catch ( error ) {
-
-			log.error( 'gradient sky generation failed:', error );
-
-		}
-
-	}
-
 	/**
 	 * Generate solid color sky texture and set as environment.
 	 */
@@ -645,6 +598,29 @@ export class EnvironmentManager {
 	 */
 	generateProceduralSkyTexture() {
 
+		if ( ! this.ProceduralSky && this._loadProceduralSky ) {
+
+			this._proceduralSkyLoading ??= this._loadProceduralSky().then( ( Sky ) => {
+
+				this._proceduralSkyLoading = null;
+				if ( ! this.ProceduralSky ) this.ProceduralSky = Sky;
+
+			} );
+			return this._proceduralSkyLoading.then( () => this.generateProceduralSkyTexture() );
+
+		}
+
+		if ( ! this.ProceduralSky ) {
+
+			this.issues?.record(
+				ISSUE_CODES.CAPABILITY_MISSING,
+				'procedural mode needs the physical sky: environmentManager.setProceduralSky( PhysicalSky ), from rayzee/addons/physical-sky',
+				{ capability: 'physical-sky' }
+			);
+			return Promise.resolve();
+
+		}
+
 		this._skyRequested = true;
 		this._skyCaughtUp ??= new Promise( resolve => void ( this._resolveSky = resolve ) );
 		this._pumpSky();
@@ -688,7 +664,7 @@ export class EnvironmentManager {
 
 		}
 
-		const sky = this.physicalSky ??= new PhysicalSky( SKY_WIDTH, SKY_HEIGHT );
+		const sky = this.physicalSky ??= new this.ProceduralSky( SKY_WIDTH, SKY_HEIGHT );
 		const albedo = p.skyGroundAlbedo;
 		const bake = ++ this._skyBakes;
 		const latest = () => bake === this._skyBakes && ! this._skyRequested;
@@ -710,12 +686,12 @@ export class EnvironmentManager {
 			this._installSky( texture, cdfTexture );
 
 			// Frames until they land normalise by an older bake's.
-			const { totalSum, compensationDelta } = await stats;
+			const { totalSum, radianceIntegral } = 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 ( this._exactTable?.sky ) this._exactTable.radianceIntegral = radianceIntegral;
 				if ( latest() ) this._notifyReset();
 
 			}
@@ -736,6 +712,32 @@ export class EnvironmentManager {
 
 	}
 
+	/**
+	 * Installs the class that bakes 'procedural' mode — `PhysicalSky` from rayzee/addons/physical-sky: constructed with
+	 * (width, height), `bake( renderer, params )` returns `{ texture, cdfTexture, sun, stats }`, and `dispose( renderer )`.
+	 * @param {?Function} Sky
+	 */
+	setProceduralSky( Sky ) {
+
+		this._loadProceduralSky = null;
+		if ( Sky === this.ProceduralSky ) return;
+		this._releaseSky();
+		this.ProceduralSky = Sky;
+		if ( Sky && this.envParams.mode === 'procedural' ) this.generateProceduralSkyTexture();
+
+	}
+
+	/**
+	 * Installs the physical sky on first use: `load()` resolves to the class setProceduralSky() takes, the first time
+	 * 'procedural' mode is baked.
+	 * @param {function(): Promise<Function>} load
+	 */
+	setProceduralSkyLoader( load ) {
+
+		this._loadProceduralSky = load;
+
+	}
+
 	/** @private */
 	_installSky( texture, cdfTexture ) {
 
@@ -750,6 +752,7 @@ export class EnvironmentManager {
 
 		// So an HDRI coming back rebuilds its own table.
 		this._cdfSignature = null;
+		if ( ! this._exactTable?.sky ) this._exactTable = { radianceIntegral: 0, sky: true };
 		texture._isGeneratedProcedural = true;
 		this.scene.environment = texture;
 		this.environmentTexture = texture;

package/src/managers/MaterialDataManager.js

@@ -18,6 +18,7 @@ import { resolveMaterialTextures, MATERIAL_VALUE_SOURCE } from '../Processor/Geo
 import { convertLinearTriple, convertLinearTriples, getWorkingMatrixSpace } from '../Color/WorkingMatrix.js';
 import { createLogger, fmt } from '../utils/Logger.js';
 import { toPortable } from '../SceneState/portable.js';
+import { MATERIAL_LAYERS } from '../TSL/SceneResources.js';
 
 /** Material buffers already moved into the working space, so a re-init cannot convert twice. */
 const convertedBuffers = new WeakSet();
@@ -41,6 +42,7 @@ const TEXTURE_POOLS = [
 	[ 'displacementMap', false ], [ 'anisotropyMap', false ], [ 'transmissionMap', false ],
 	[ 'clearcoatMap', false ], [ 'clearcoatRoughnessMap', false ], [ 'sheenRoughnessMap', false ],
 	[ 'iridescenceMap', false ], [ 'iridescenceThicknessMap', false ], [ 'specularIntensityMap', false ],
+	[ 'diffuseTransmissionColorMap', true ], [ 'diffuseTransmissionMap', false ],
 ];
 
 // Scalar slots readable via getMaterialProperty().
@@ -67,6 +69,7 @@ const SCALAR_PROPERTY_OFFSETS = {
 	subsurfaceAnisotropy: M.SUBSURFACE_ANISOTROPY,
 	anisotropy: M.ANISOTROPY,
 	anisotropyRotation: M.ANISOTROPY_ROTATION, // radians, unlike the degrees hosts usually show
+	diffuseTransmission: M.DIFFUSE_TRANSMISSION,
 };
 
 export class MaterialDataManager {
@@ -119,6 +122,7 @@ export class MaterialDataManager {
 	 */
 	static COLOR_OFFSETS = [
 		M.COLOR, M.EMISSIVE, M.ATTENUATION_COLOR, M.SHEEN_COLOR, M.SPECULAR_COLOR, M.SUBSURFACE_COLOR,
+		M.DIFFUSE_TRANSMISSION_COLOR,
 	].filter( o => Number.isInteger( o ) );
 
 	/**
@@ -186,6 +190,7 @@ export class MaterialDataManager {
 		this.materialCount = Math.floor( vec4Count / PIXELS_PER_MATERIAL );
 		this._sources = [ ...sources ];
 		this._hostSet = [];
+		this.callbacks.onMaterialFeaturesChanged?.();
 		log.debug( `${fmt.n( this.materialCount )} materials (storage buffer)` );
 
 	}
@@ -300,6 +305,26 @@ export class MaterialDataManager {
 
 	}
 
+	/**
+	 * Which MATERIAL_LAYERS some material uses (its factor above 0): the kernels compile the others out.
+	 * @returns {Object<string, boolean>}
+	 */
+	materialLayers() {
+
+		const layers = Object.fromEntries( MATERIAL_LAYERS.map( ( layer ) => [ layer, false ] ) );
+		const data = this.materialStorageAttr?.array;
+		if ( ! data ) return layers;
+		for ( let i = 0; i < this.materialCount; i ++ ) {
+
+			const base = i * M.FLOATS_PER_MATERIAL;
+			for ( const layer of MATERIAL_LAYERS ) if ( data[ base + SCALAR_PROPERTY_OFFSETS[ layer ] ] > 0 ) layers[ layer ] = true;
+
+		}
+
+		return layers;
+
+	}
+
 	/**
 	 * Where a material property's value came from, as a MATERIAL_VALUE_SOURCE. `default` means the
 	 * model never said and the engine filled it in.
@@ -466,6 +491,19 @@ export class MaterialDataManager {
 			case 'subsurfaceAnisotropy': data[ stride + M.SUBSURFACE_ANISOTROPY ] = value; break;
 			case 'anisotropy': data[ stride + M.ANISOTROPY ] = value; break;
 			case 'anisotropyRotation': data[ stride + M.ANISOTROPY_ROTATION ] = value; break;
+			case 'diffuseTransmission': data[ stride + M.DIFFUSE_TRANSMISSION ] = value; break;
+			case 'diffuseTransmissionColor':
+				if ( value.r !== undefined ) {
+
+					this._writeColor( data, stride + M.DIFFUSE_TRANSMISSION_COLOR, value.r, value.g, value.b );
+
+				} else if ( Array.isArray( value ) ) {
+
+					this._writeColor( data, stride + M.DIFFUSE_TRANSMISSION_COLOR, value[ 0 ], value[ 1 ], value[ 2 ] );
+
+				}
+
+				break;
 			case 'subsurfaceColor':
 				if ( value.r !== undefined ) {
 
@@ -510,6 +548,9 @@ export class MaterialDataManager {
 
 		}
 
+		// A material layer is compiled in only while some material uses it.
+		if ( MATERIAL_LAYERS.includes( property ) ) this.callbacks.onMaterialFeaturesChanged?.();
+
 		this._notifyReset();
 
 	}
@@ -545,6 +586,7 @@ export class MaterialDataManager {
 		// Both read back the block, so they must follow the write.
 		this._patchTriangleSideForMaterial( materialIndex, data[ base + M.SIDE ] );
 		this._recomputeOpaqueBlockerForMaterial( materialIndex );
+		this.callbacks.onMaterialFeaturesChanged?.();
 
 		this.materialStorageAttr.needsUpdate = true;
 		this._notifyReset();

package/src/managers/UniformManager.js

@@ -265,7 +265,6 @@ export class UniformManager {
 		ub( 'enableEnvironment', DEFAULT_STATE.enableEnvironment );
 		u( 'environmentMatrix', new Matrix4(), 'mat4' );
 		u( 'envTotalSum', 0.0, 'float' );
-		u( 'envCompensationDelta', 0.0, 'float' );
 		u( 'envResolution', new Vector2( 1, 1 ), 'vec2' );
 		ub( 'groundProjectionEnabled', DEFAULT_STATE.groundProjectionEnabled );
 		u( 'groundProjectionRadius', DEFAULT_STATE.groundProjectionRadius, 'float' );