rayzee 6.0.1 → 6.1.0

package/src/managers/GoboManager.js

@@ -0,0 +1,277 @@
+import { DataArrayTexture, LinearFilter, RGBAFormat, UnsignedByteType } from 'three';
+
+/**
+ * Manages projection masks ("gobos" / "cookies") for spot lights.
+ *
+ * Loads a library of grayscale images into a single GPU `DataArrayTexture`;
+ * spot lights reference layers by index via `light.userData.gobo`. The TSL
+ * shader projects the surface direction onto the light's local plane and
+ * multiplies emission by the mask, producing classic "light through a window"
+ * or dappled-foliage shadows without any extra geometry.
+ *
+ * Library layers must all share the same square resolution (default 256×256).
+ * Images are rasterised through a 2D canvas so non-square sources scale to fit.
+ *
+ * Usage:
+ * ```js
+ * const entries = await app.goboManager.loadLibrary( [
+ *     { name: 'window', url: '/lightmasks/window_a.png' },
+ *     { name: 'leaves', url: '/lightmasks/foliage_canopy_a.png' },
+ * ] );
+ * app.goboManager.setSpotLightGobo( spotLight.uuid, 'window', 1.0 );
+ * ```
+ */
+export class GoboManager {
+
+	/**
+	 * @param {import('../Stages/PathTracer.js').PathTracer} pathTracer
+	 * @param {Object} [options]
+	 * @param {Function} [options.onReset] - Called after gobo state changes so the host can reset accumulation
+	 */
+	constructor( pathTracer, options = {} ) {
+
+		this.pathTracer = pathTracer;
+		this._onReset = options.onReset || null;
+
+		/** @type {DataArrayTexture | null} */
+		this.texture = null;
+
+		/** @type {Array<{ name: string, index: number }>} */
+		this.entries = [];
+
+		this._size = 256;
+
+	}
+
+	/**
+	 * Load a list of gobo images into a single DataArrayTexture.
+	 * Replaces any previously loaded library.
+	 *
+	 * @param {Array<{ name: string, url: string }>} items
+	 * @param {Object} [options]
+	 * @param {number} [options.size=256] - Per-layer square resolution
+	 * @returns {Promise<Array<{ name: string, index: number }>>}
+	 */
+	async loadLibrary( items, { size = 256 } = {} ) {
+
+		if ( ! Array.isArray( items ) || items.length === 0 ) return [];
+
+		this._size = size;
+		const images = await Promise.all( items.map( it => loadImage( it.url ) ) );
+
+		const width = size;
+		const height = size;
+		const depth = images.length;
+		const data = new Uint8Array( width * height * depth * 4 );
+
+		const cnv = document.createElement( 'canvas' );
+		cnv.width = width;
+		cnv.height = height;
+		const ctx = cnv.getContext( '2d', { willReadFrequently: true } );
+
+		for ( let i = 0; i < depth; i ++ ) {
+
+			ctx.clearRect( 0, 0, width, height );
+			ctx.drawImage( images[ i ], 0, 0, width, height );
+			const img = ctx.getImageData( 0, 0, width, height );
+			data.set( img.data, i * width * height * 4 );
+
+		}
+
+		const tex = new DataArrayTexture( data, width, height, depth );
+		tex.minFilter = LinearFilter;
+		tex.magFilter = LinearFilter;
+		tex.format = RGBAFormat;
+		tex.type = UnsignedByteType;
+		tex.generateMipmaps = false;
+		tex.needsUpdate = true;
+
+		const old = this.texture;
+		this.texture = tex;
+		this.entries = items.map( ( it, i ) => ( { name: it.name, index: i } ) );
+
+		// Hand the new texture to the shader graph and refresh light data.
+		this.pathTracer.goboMaps = tex;
+		this.pathTracer.shaderBuilder?.updateGoboMaps?.( tex );
+
+		// Free old GPU memory after the new one is bound.
+		old?.dispose?.();
+
+		return this.entries;
+
+	}
+
+	/**
+	 * Returns the loaded library entries (name → index lookup).
+	 * @returns {Array<{ name: string, index: number }>}
+	 */
+	getEntries() {
+
+		return this.entries.slice();
+
+	}
+
+	/**
+	 * Assign a gobo to a spot or directional light by uuid.
+	 *
+	 * @param {string} uuid - Light's uuid
+	 * @param {string | null} name - Gobo entry name (or null to clear)
+	 * @param {Object} [opts]
+	 * @param {number} [opts.intensity=1.0] - Mask strength [0,1]
+	 * @param {boolean} [opts.inverted=false] - If true, sample (1 - mask)
+	 * @param {number} [opts.scale=5.0] - World units per gobo tile (directional only)
+	 * @returns {boolean} True if the light was found and updated
+	 */
+	setLightGobo( uuid, name, opts = {} ) {
+
+		const { intensity = 1.0, inverted = false, scale = 5.0 } = opts;
+		const light = this._findGoboLight( uuid );
+		if ( ! light ) return false;
+
+		light.userData = light.userData || {};
+
+		if ( name == null ) {
+
+			delete light.userData.gobo;
+
+		} else {
+
+			const entry = this.entries.find( e => e.name === name );
+			if ( ! entry ) {
+
+				console.warn( `GoboManager: unknown gobo "${name}"` );
+				return false;
+
+			}
+
+			light.userData.gobo = {
+				name: entry.name,
+				index: entry.index,
+				intensity: clamp01( intensity ),
+				inverted: !! inverted,
+				scale: Math.max( 1e-4, scale ),
+			};
+
+		}
+
+		this.pathTracer.updateLights();
+		this._onReset?.();
+		return true;
+
+	}
+
+	/**
+	 * Toggle inversion on an existing gobo assignment without losing
+	 * the chosen mask or intensity.
+	 * @param {string} uuid
+	 * @param {boolean} inverted
+	 * @returns {boolean}
+	 */
+	setLightGoboInverted( uuid, inverted ) {
+
+		const light = this._findGoboLight( uuid );
+		if ( ! light?.userData?.gobo ) return false;
+
+		light.userData.gobo.inverted = !! inverted;
+		this.pathTracer.updateLights();
+		this._onReset?.();
+		return true;
+
+	}
+
+	/**
+	 * Update the gobo projection scale for a directional light without
+	 * touching the chosen mask, intensity, or inverted flag.
+	 * @param {string} uuid
+	 * @param {number} scale
+	 * @returns {boolean}
+	 */
+	setLightGoboScale( uuid, scale ) {
+
+		const light = this._findGoboLight( uuid );
+		if ( ! light?.userData?.gobo ) return false;
+
+		light.userData.gobo.scale = Math.max( 1e-4, scale );
+		this.pathTracer.updateLights();
+		this._onReset?.();
+		return true;
+
+	}
+
+	/**
+	 * Returns the gobo descriptor currently assigned to a light, or null.
+	 * @param {string} uuid
+	 */
+	getLightGobo( uuid ) {
+
+		const light = this._findGoboLight( uuid );
+		return light?.userData?.gobo || null;
+
+	}
+
+	// ── Back-compat thin wrappers ─────────────────────────────────────
+
+	setSpotLightGobo( uuid, name, intensity = 1.0, inverted = false ) {
+
+		return this.setLightGobo( uuid, name, { intensity, inverted } );
+
+	}
+
+	setSpotLightGoboInverted( uuid, inverted ) {
+
+		return this.setLightGoboInverted( uuid, inverted );
+
+	}
+
+	getSpotLightGobo( uuid ) {
+
+		return this.getLightGobo( uuid );
+
+	}
+
+	dispose() {
+
+		this.texture?.dispose?.();
+		this.texture = null;
+		this.entries = [];
+		this.pathTracer = null;
+		this._onReset = null;
+
+	}
+
+	_findGoboLight( uuid ) {
+
+		const obj = this.pathTracer?.scene?.getObjectByProperty?.( 'uuid', uuid );
+		if ( ! obj ) return null;
+		return ( obj.isSpotLight || obj.isDirectionalLight ) ? obj : null;
+
+	}
+
+	_findSpotLight( uuid ) {
+
+		const obj = this.pathTracer?.scene?.getObjectByProperty?.( 'uuid', uuid );
+		return obj && obj.isSpotLight ? obj : null;
+
+	}
+
+}
+
+function loadImage( url ) {
+
+	return 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 = url;
+
+	} );
+
+}
+
+function clamp01( v ) {
+
+	return Math.max( 0, Math.min( 1, v ) );
+
+}

package/src/managers/IESManager.js

@@ -0,0 +1,268 @@
+import { DataArrayTexture, LinearFilter, RGBAFormat, UnsignedByteType } from 'three';
+import { parseIES, resampleIESToGrid, deriveIESBeamAngle, deriveIESPenumbra } from '../Processor/IESParser.js';
+
+/**
+ * Manages IES photometric profiles for spot lights.
+ *
+ * Pulls .ies files over HTTP, parses each into an angular candela grid,
+ * resamples to a fixed-size 2D texture (U = horizontal angle, V = vertical
+ * angle), and stacks all profiles into a single `DataArrayTexture` referenced
+ * per-light through `light.userData.ies = { name, index, intensity }`.
+ *
+ * Shader sampling math lives in `LightsCore.js (sampleIESProfile)`.
+ *
+ * Usage:
+ * ```js
+ * const entries = await app.iesManager.loadLibrary([
+ *     { name: 'parallel-beam', url: '/iesprofiles/parallel-beam.ies' },
+ * ]);
+ * app.iesManager.setSpotLightProfile(spotLight.uuid, 'parallel-beam', 1.0);
+ * ```
+ */
+export class IESManager {
+
+	/**
+	 * @param {import('../Stages/PathTracer.js').PathTracer} pathTracer
+	 * @param {Object} [options]
+	 * @param {Function} [options.onReset] - reset accumulation after assignment changes
+	 */
+	constructor( pathTracer, options = {} ) {
+
+		this.pathTracer = pathTracer;
+		this._onReset = options.onReset || null;
+
+		/** @type {DataArrayTexture | null} */
+		this.texture = null;
+
+		/** @type {Array<{ name: string, index: number, maxCandela: number, photometricType: number }>} */
+		this.entries = [];
+
+		this._gridWidth = 128; // horizontal samples (U axis)
+		this._gridHeight = 128; // vertical samples (V axis)
+
+	}
+
+	/**
+	 * Load a list of IES profiles. Replaces any previously loaded library.
+	 *
+	 * @param {Array<{ name: string, url: string }>} items
+	 * @param {Object} [options]
+	 * @param {number} [options.gridWidth=128]
+	 * @param {number} [options.gridHeight=128]
+	 * @returns {Promise<Array<{ name: string, index: number }>>}
+	 */
+	async loadLibrary( items, { gridWidth = 128, gridHeight = 128 } = {} ) {
+
+		if ( ! Array.isArray( items ) || items.length === 0 ) return [];
+
+		this._gridWidth = gridWidth;
+		this._gridHeight = gridHeight;
+
+		// Fetch + parse in parallel; tolerate individual failures.
+		const results = await Promise.all( items.map( async ( it ) => {
+
+			try {
+
+				const res = await fetch( it.url );
+				if ( ! res.ok ) throw new Error( `HTTP ${res.status}` );
+				const text = await res.text();
+				const profile = parseIES( text, it.name );
+				const grid = resampleIESToGrid( profile, gridWidth, gridHeight );
+				return { it, profile, grid };
+
+			} catch ( err ) {
+
+				console.warn( `IESManager: failed to load "${it.name}": ${err.message}` );
+				return null;
+
+			}
+
+		} ) );
+
+		const okResults = results.filter( r => r !== null );
+		if ( okResults.length === 0 ) return [];
+
+		const depth = okResults.length;
+		const pixelsPerLayer = gridWidth * gridHeight;
+		// Expand single-channel grid to RGBA so the texture format matches the
+		// placeholder bound at shader-compile time (DataArrayTexture rebinds
+		// require matching format). R channel carries the value; G/B copy R for
+		// safer linear filtering, A=255.
+		const data = new Uint8Array( pixelsPerLayer * 4 * depth );
+
+		const entries = [];
+		for ( let i = 0; i < depth; i ++ ) {
+
+			const grid = okResults[ i ].grid;
+			const dst = i * pixelsPerLayer * 4;
+			for ( let p = 0; p < pixelsPerLayer; p ++ ) {
+
+				const v = grid[ p ];
+				data[ dst + p * 4 + 0 ] = v;
+				data[ dst + p * 4 + 1 ] = v;
+				data[ dst + p * 4 + 2 ] = v;
+				data[ dst + p * 4 + 3 ] = 255;
+
+			}
+
+			const profile = okResults[ i ].profile;
+			const suggestedAngle = deriveIESBeamAngle( profile );
+			entries.push( {
+				name: okResults[ i ].it.name,
+				index: i,
+				maxCandela: profile.maxCandela,
+				photometricType: profile.photometricType,
+				suggestedAngle,
+				suggestedPenumbra: deriveIESPenumbra( profile, suggestedAngle ),
+				lumens: profile.lumens,
+			} );
+
+		}
+
+		const tex = new DataArrayTexture( data, gridWidth, gridHeight, depth );
+		tex.format = RGBAFormat;
+		tex.type = UnsignedByteType;
+		tex.minFilter = LinearFilter;
+		tex.magFilter = LinearFilter;
+		tex.generateMipmaps = false;
+		tex.needsUpdate = true;
+
+		const old = this.texture;
+		this.texture = tex;
+		this.entries = entries;
+
+		// Hand the texture to the path tracer's shader graph.
+		this.pathTracer.iesProfiles = tex;
+		this.pathTracer.shaderBuilder?.updateIESProfiles?.( tex );
+
+		old?.dispose?.();
+
+		return this.entries.map( ( { name, index } ) => ( { name, index } ) );
+
+	}
+
+	/**
+	 * Returns the loaded library entries.
+	 */
+	getEntries() {
+
+		return this.entries.slice();
+
+	}
+
+	/**
+	 * Assign or clear an IES profile on a spot light.
+	 *
+	 * When `applyAutoCone` is true (default), the spot light's photometrically
+	 * meaningful parameters are derived from the profile and applied:
+	 *   - cone half-angle (snug clip outside the IES emission)
+	 *   - penumbra (transition band matching the IES soft edge)
+	 *   - decay (forced to 2 — physically correct inverse-square)
+	 *
+	 * @param {string} uuid
+	 * @param {string | null} name - profile name (or null to clear)
+	 * @param {number} [intensity=1.0] - blend [0,1] between flat (0) and full profile (1)
+	 * @param {Object} [opts]
+	 * @param {boolean} [opts.applyAutoCone=true]
+	 * @returns {{ applied: boolean, suggestedAngle: number | null, suggestedPenumbra: number | null, suggestedDecay: number | null, fixtureLumens: number | null }}
+	 *   host can mirror the suggested values into UI state.
+	 */
+	setSpotLightProfile( uuid, name, intensity = 1.0, { applyAutoCone = true } = {} ) {
+
+		const light = this._findSpotLight( uuid );
+		const empty = { applied: false, suggestedAngle: null, suggestedPenumbra: null, suggestedDecay: null, fixtureLumens: null };
+		if ( ! light ) return empty;
+
+		light.userData = light.userData || {};
+		let suggestedAngle = null;
+		let suggestedPenumbra = null;
+		let suggestedDecay = null;
+		let fixtureLumens = null;
+
+		if ( name == null ) {
+
+			delete light.userData.ies;
+
+		} else {
+
+			const entry = this.entries.find( e => e.name === name );
+			if ( ! entry ) {
+
+				console.warn( `IESManager: unknown profile "${name}"` );
+				return empty;
+
+			}
+
+			fixtureLumens = Number.isFinite( entry.lumens ) ? entry.lumens : null;
+
+			light.userData.ies = {
+				name: entry.name,
+				index: entry.index,
+				intensity: clamp01( intensity ),
+				fixtureLumens,
+			};
+
+			if ( applyAutoCone ) {
+
+				if ( Number.isFinite( entry.suggestedAngle ) ) {
+
+					light.angle = entry.suggestedAngle;
+					suggestedAngle = entry.suggestedAngle;
+
+				}
+
+				if ( Number.isFinite( entry.suggestedPenumbra ) ) {
+
+					light.penumbra = entry.suggestedPenumbra;
+					suggestedPenumbra = entry.suggestedPenumbra;
+
+				}
+
+				// IES is a photometric measurement that assumes inverse-square falloff.
+				light.decay = 2;
+				suggestedDecay = 2;
+
+			}
+
+		}
+
+		this.pathTracer.updateLights();
+		this._onReset?.();
+		return { applied: true, suggestedAngle, suggestedPenumbra, suggestedDecay, fixtureLumens };
+
+	}
+
+	/**
+	 * Returns the current IES descriptor on a spot light (or null).
+	 */
+	getSpotLightProfile( uuid ) {
+
+		const light = this._findSpotLight( uuid );
+		return light?.userData?.ies || null;
+
+	}
+
+	dispose() {
+
+		this.texture?.dispose?.();
+		this.texture = null;
+		this.entries = [];
+		this.pathTracer = null;
+		this._onReset = null;
+
+	}
+
+	_findSpotLight( uuid ) {
+
+		const obj = this.pathTracer?.scene?.getObjectByProperty?.( 'uuid', uuid );
+		return obj && obj.isSpotLight ? obj : null;
+
+	}
+
+}
+
+function clamp01( v ) {
+
+	return Math.max( 0, Math.min( 1, v ) );
+
+}

package/src/managers/LightManager.js

@@ -129,11 +129,14 @@ export class LightManager extends EventDispatcher {
 	}
 
 	/**
-	 * Reprocesses all scene lights and updates the path tracer uniform buffers.
+	 * Reprocesses all scene lights and updates the path tracer uniform buffers,
+	 * and refreshes any visible helper gizmos so they reflect parameter changes
+	 * (intensity, cone angle, position, target, distance) without rebuilding.
 	 */
 	updateLights() {
 
 		this.pathTracer?.updateLights();
+		if ( this.sceneHelpers?.visible ) this.sceneHelpers.update();
 
 	}
 
@@ -332,6 +335,35 @@ export class LightManager extends EventDispatcher {
 		} else if ( light.type === 'SpotLight' && light.target ) {
 
 			descriptor.target = [ light.target.position.x, light.target.position.y, light.target.position.z ];
+			descriptor.distance = light.distance ?? 0;
+			descriptor.penumbra = light.penumbra ?? 0;
+			descriptor.decay = light.decay ?? 2;
+
+		} else if ( light.type === 'PointLight' ) {
+
+			descriptor.distance = light.distance ?? 0;
+			descriptor.decay = light.decay ?? 2;
+
+		}
+
+		if ( ( light.type === 'SpotLight' || light.type === 'DirectionalLight' ) && light.userData?.gobo ) {
+
+			descriptor.gobo = light.userData.gobo.name;
+			descriptor.goboIntensity = light.userData.gobo.intensity;
+			descriptor.goboInverted = !! light.userData.gobo.inverted;
+			if ( light.type === 'DirectionalLight' ) {
+
+				descriptor.goboScale = light.userData.gobo.scale ?? 5.0;
+
+			}
+
+		}
+
+		if ( light.type === 'SpotLight' && light.userData?.ies ) {
+
+			descriptor.ies = light.userData.ies.name;
+			descriptor.iesIntensity = light.userData.ies.intensity ?? 1.0;
+			descriptor.fixtureLumens = light.userData.ies.fixtureLumens ?? null;
 
 		}
 

package/src/managers/TransformManager.js

@@ -49,7 +49,7 @@ export class TransformManager {
 	 * Provide mesh data from SceneProcessor after scene load.
 	 * Required for position extraction during BVH refit.
 	 */
-	setMeshData( meshes, triangleCount ) {
+	setMeshData( meshes ) {
 
 		this._meshes = meshes;
 		this._meshTriRanges = [];
@@ -72,8 +72,8 @@ export class TransformManager {
 
 		}
 
-		this._posBuffer = new Float32Array( triangleCount * 9 );
-		this._normalBuffer = new Float32Array( triangleCount * 9 );
+		this._posBuffer = new Float32Array( offset * 9 );
+		this._normalBuffer = new Float32Array( offset * 9 );
 
 	}
 

package/src/managers/UniformManager.js

@@ -184,6 +184,9 @@ export class UniformManager {
 		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' );
+		u( 'groundProjectionHeight', DEFAULT_STATE.groundProjectionHeight, 'float' );
 
 		// Sun parameters
 		u( 'sunDirection', new Vector3( 0, 1, 0 ), 'vec3' );
@@ -202,10 +205,10 @@ export class UniformManager {
 
 		// Light buffer nodes - pre-allocate for up to 16 lights per type (shader hard cap)
 		this._lightBuffers = {
-			directional: uniformArray( new Float32Array( 8 * 16 ), 'float' ),
+			directional: uniformArray( new Float32Array( 12 * 16 ), 'float' ),
 			area: uniformArray( new Float32Array( 13 * 16 ), 'float' ),
 			point: uniformArray( new Float32Array( 9 * 16 ), 'float' ),
-			spot: uniformArray( new Float32Array( 14 * 16 ), 'float' ),
+			spot: uniformArray( new Float32Array( 20 * 16 ), 'float' ),
 		};
 
 		// Camera matrices
@@ -249,9 +252,6 @@ export class UniformManager {
 		// Resolution (for RNG seeding)
 		u( 'resolution', new Vector2( width, height ), 'vec2' );
 
-		// Scene data
-		u( 'totalTriangleCount', 0, 'int' );
-
 	}
 
 	/**