rayzee 7.26.3 → 7.26.5

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "rayzee",
-  "version": "7.26.3",
+  "version": "7.26.5",
   "type": "module",
   "description": "Real-time WebGPU path tracing engine built on Three.js",
   "main": "dist/rayzee.umd.js",

package/src/Processor/GeometryExtractor.js

@@ -6,6 +6,53 @@ const log = createLogger( 'geometry' );
 
 const MAX_TEXTURES_LIMIT = 128;
 
+/**
+ * glTF 2.0 alphaMode for a three.js material: 0 OPAQUE, 1 MASK, 2 BLEND.
+ *
+ * The single definition of this rule. alphaMode is the only alpha field the shader reads
+ * (MaterialTransmission takes the opaque fast path on 0 and gates its MASK branch on 1), so
+ * any control that changes alpha behaviour has to route through here or it does nothing.
+ *
+ * @param {import('three').Material} material
+ * @returns {0|1|2}
+ */
+export function deriveAlphaMode( material ) {
+
+	// Follow glTF 2.0 specification for alphaMode
+	// Check if material explicitly sets alphaMode (from glTF loader)
+	if ( material.userData?.gltfExtensions?.KHR_materials_unlit?.alphaMode ) {
+
+		const mode = material.userData.gltfExtensions.KHR_materials_unlit.alphaMode;
+		if ( mode === 'BLEND' ) return 2;
+		if ( mode === 'MASK' ) return 1;
+		return 0; // OPAQUE
+
+	}
+
+	// Fallback logic based on material properties
+	if ( material.alphaTest > 0.0 ) {
+
+		return 1; // MASK - alphaTest takes priority
+
+	}
+
+	if ( material.transparent && material.opacity < 1.0 ) {
+
+		return 2; // BLEND - transparent with opacity < 1
+
+	}
+
+	// Check for alpha in diffuse texture
+	if ( material.map && material.map.format === RGBAFormat && material.transparent ) {
+
+		return 2; // BLEND - has alpha texture and transparent flag
+
+	}
+
+	return 0; // OPAQUE
+
+}
+
 export class GeometryExtractor {
 
 	constructor() {
@@ -189,42 +236,6 @@ export class GeometryExtractor {
 
 	}
 
-	getMaterialAlphaMode( material ) {
-
-		// Follow glTF 2.0 specification for alphaMode
-		// Check if material explicitly sets alphaMode (from glTF loader)
-		if ( material.userData?.gltfExtensions?.KHR_materials_unlit?.alphaMode ) {
-
-			const mode = material.userData.gltfExtensions.KHR_materials_unlit.alphaMode;
-			if ( mode === 'BLEND' ) return 2;
-			if ( mode === 'MASK' ) return 1;
-			return 0; // OPAQUE
-
-		}
-
-		// Fallback logic based on material properties
-		if ( material.alphaTest > 0.0 ) {
-
-			return 1; // MASK - alphaTest takes priority
-
-		}
-
-		if ( material.transparent && material.opacity < 1.0 ) {
-
-			return 2; // BLEND - transparent with opacity < 1
-
-		}
-
-		// Check for alpha in diffuse texture
-		if ( material.map && material.map.format === RGBAFormat && material.transparent ) {
-
-			return 2; // BLEND - has alpha texture and transparent flag
-
-		}
-
-		return 0; // OPAQUE
-
-	}
 
 	getMaterialType( material ) {
 
@@ -424,7 +435,7 @@ export class GeometryExtractor {
 			// Transparency and alpha
 			transparent: material.transparent ? 1 : 0,
 			alphaTest: material.alphaTest ?? defaults.alphaTest,
-			alphaMode: this.getMaterialAlphaMode( material ),
+			alphaMode: deriveAlphaMode( material ),
 
 			// Rendering properties
 			side: this.getMaterialSide( material ),

package/src/TSL/LightsSampling.js

@@ -330,6 +330,67 @@ export const samplePointLightWithAttenuation = Fn( ( [ light, rayOrigin, lightSe
 
 } );
 
+// Sun sampling. `angle` is angular diameter: 0 is a hard shadow, >0 cone-samples the disc.
+//
+// intensity is IRRADIANCE (Blender Sun "Strength"), already integrated over the disc, so it has
+// to become radiance before NEE divides by the 1/solidAngle cone pdf. Passing it through raw
+// scaled the sun BY its own solid angle — a real 0.53° sun measured ~15000x too dark.
+export const sampleDirectionalLight = Fn( ( [ light, rayOrigin, lightSelectionPdf, uCos, uPhi ] ) => {
+
+	const ls_valid = tslBool( false ).toVar();
+	const ls_direction = vec3( 0.0, 1.0, 0.0 ).toVar();
+	const ls_emission = vec3( 0.0 ).toVar();
+	const ls_pdf = float( 0.0 ).toVar();
+
+	If( light.intensity.greaterThan( 0.0 ), () => {
+
+		const w = normalize( light.direction ).toVar();
+		const emission = light.color.mul( light.intensity ).mul( sampleDirectionalGoboMask( light, rayOrigin ) ).toVar();
+
+		ls_direction.assign( w );
+		ls_pdf.assign( lightSelectionPdf );
+
+		If( light.angle.greaterThan( 0.0 ), () => {
+
+			const cosHalfAngle = cos( light.angle.mul( 0.5 ) ).toVar();
+			const cosTheta = mix( cosHalfAngle, float( 1.0 ), uCos ).toVar();
+			const sinTheta = sqrt( max( float( 0.0 ), float( 1.0 ).sub( cosTheta.mul( cosTheta ) ) ) ).toVar();
+			const phi = float( TWO_PI ).mul( uPhi ).toVar();
+
+			const u = normalize( cross(
+				select( abs( w.x ).greaterThan( 0.9 ), vec3( 0.0, 1.0, 0.0 ), vec3( 1.0, 0.0, 0.0 ) ),
+				w
+			) ).toVar();
+			const v = cross( w, u ).toVar();
+
+			ls_direction.assign( normalize(
+				w.mul( cosTheta ).add( u.mul( cos( phi ) ).add( v.mul( sin( phi ) ) ).mul( sinTheta ) )
+			) );
+
+			// Guard the division: (1 - cosHalfAngle) underflows to zero at tiny angles.
+			const solidAngle = float( TWO_PI ).mul( max( float( 1.0 ).sub( cosHalfAngle ), 1e-10 ) ).toVar();
+			emission.assign( emission.div( solidAngle ) );
+			ls_pdf.assign( lightSelectionPdf.div( solidAngle ) );
+
+		} );
+
+		ls_emission.assign( emission );
+		ls_valid.assign( tslBool( true ) );
+
+	} );
+
+	return LightSample( {
+		valid: ls_valid,
+		direction: ls_direction,
+		emission: ls_emission,
+		distance: float( 1e6 ),
+		pdf: ls_pdf,
+		lightType: int( LIGHT_TYPE_DIRECTIONAL ),
+		selectionTotalWeight: float( 0.0 ),
+	} );
+
+} );
+
 // =============================================================================
 // Importance-Weighted Light Sampling
 // =============================================================================
@@ -496,12 +557,16 @@ export const sampleLightWithImportance = Fn( ( [
 
 					If( light.intensity.greaterThan( 0.0 ), () => {
 
-						const dirGoboMask = sampleDirectionalGoboMask( light, rayOrigin );
-						r_direction.assign( normalize( light.direction ) );
-						r_emission.assign( light.color.mul( light.intensity ).mul( dirGoboMask ) );
-						r_distance.assign( 1e6 );
-						r_lightType.assign( int( LIGHT_TYPE_DIRECTIONAL ) );
-						r_valid.assign( tslBool( true ) );
+						const dirSample = LightSample.wrap( sampleDirectionalLight(
+							light, rayOrigin, lightSelectionPdf, randomSeed.y,
+							getRandomSample1D( pixelCoord, int( 0 ), dimBase.add( int( 14 ) ), rngState, resolution, frame )
+						) );
+						r_valid.assign( dirSample.valid );
+						r_direction.assign( dirSample.direction );
+						r_emission.assign( dirSample.emission );
+						r_distance.assign( dirSample.distance );
+						r_pdf.assign( dirSample.pdf );
+						r_lightType.assign( dirSample.lightType );
 						sampled.assign( tslBool( true ) );
 
 					} );
@@ -601,39 +666,17 @@ export const sampleLightWithImportance = Fn( ( [
 
 				const light = DirectionalLight.wrap( getDirectionalLight( directionalLightsBuffer, selectedIdx ) );
 
-				const direction = normalize( light.direction ).toVar();
-				const dirPdf = float( 1.0 ).toVar();
-
-				If( light.angle.greaterThan( 0.0 ), () => {
-
-					const cosHalfAngle = cos( light.angle.mul( 0.5 ) ).toVar();
-					const cosTheta = mix( cosHalfAngle, float( 1.0 ), randomSeed.y ).toVar();
-					const sinTheta = sqrt( max( float( 0.0 ), float( 1.0 ).sub( cosTheta.mul( cosTheta ) ) ) ).toVar();
-					const phi = float( TWO_PI ).mul( getRandomSample1D( pixelCoord, int( 0 ), dimBase.add( int( 14 ) ), rngState, resolution, frame ) ).toVar();
-
-					const w = normalize( light.direction ).toVar();
-					const u = normalize( cross(
-						select( abs( w.x ).greaterThan( 0.9 ), vec3( 0.0, 1.0, 0.0 ), vec3( 1.0, 0.0, 0.0 ) ),
-						w
-					) ).toVar();
-					const v = cross( w, u ).toVar();
-
-					direction.assign( normalize(
-						w.mul( cosTheta ).add( u.mul( cos( phi ) ).add( v.mul( sin( phi ) ) ).mul( sinTheta ) )
-					) );
-					// Guard division: (1.0 - cosHalfAngle) could be zero if angle is 0
-					const solidAngle = float( TWO_PI ).mul( max( float( 1.0 ).sub( cosHalfAngle ), 1e-10 ) );
-					dirPdf.assign( float( 1.0 ).div( solidAngle ) );
-
-				} );
-
-				const dirGoboMask = sampleDirectionalGoboMask( light, rayOrigin );
-				r_direction.assign( direction );
-				r_emission.assign( light.color.mul( light.intensity ).mul( dirGoboMask ) );
-				r_distance.assign( 1e6 );
-				r_pdf.assign( dirPdf.mul( pdf ) );
-				r_lightType.assign( int( LIGHT_TYPE_DIRECTIONAL ) );
-				r_valid.assign( tslBool( true ) );
+				const dirSample = LightSample.wrap( sampleDirectionalLight(
+					light, rayOrigin, pdf, randomSeed.y,
+					getRandomSample1D( pixelCoord, int( 0 ), dimBase.add( int( 14 ) ), rngState, resolution, frame )
+				) );
+
+				r_direction.assign( dirSample.direction );
+				r_emission.assign( dirSample.emission );
+				r_distance.assign( dirSample.distance );
+				r_pdf.assign( dirSample.pdf );
+				r_lightType.assign( dirSample.lightType );
+				r_valid.assign( dirSample.valid );
 
 			} );
 

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';
 
+// glTF alphaMode derivation — the one definition, shared with hosts that edit materials
+export { deriveAlphaMode } from './Processor/GeometryExtractor.js';
+
 // Scene-level authoring metadata embedded in model files (glTF `extras`)
 export { extractSceneMetadata, parseSceneMetadata } from './Processor/SceneMetadata.js';
 

package/src/managers/LightManager.js

@@ -324,6 +324,13 @@ export class LightManager extends EventDispatcher {
 
 			angle = MathUtils.radToDeg( light.angle );
 
+		} else if ( light.type === 'DirectionalLight' ) {
+
+			// Sun angular diameter. Lives on userData because three.js gives DirectionalLight no
+			// angle property, and an ad-hoc one would not survive the light.clone() in
+			// transferSceneLights. Reported here or the panel reads back 0 and the slider snaps home.
+			angle = MathUtils.radToDeg( light.userData?.angle ?? 0 );
+
 		}
 
 		const descriptor = {

package/src/managers/UniformManager.js

@@ -29,6 +29,9 @@ export class UniformManager {
 		/** @type {Set<string>} Uniforms that store boolean values as int 0/1 */
 		this._booleans = new Set();
 
+		/** @type {Set<string>} Uniforms already warned about an array value (warn once each) */
+		this._arrayWarned = new Set();
+
 		/** @type {Object} Light buffer uniformArray nodes */
 		this._lightBuffers = {};
 
@@ -64,6 +67,32 @@ export class UniformManager {
 
 		}
 
+		// Hosts wire UI controls straight to these, and slider components commonly emit [n]
+		// rather than n. A scalar uniform has no meaningful array value, and nothing downstream
+		// rejects one: the array lands in .value verbatim and poisons every later read. That is
+		// not hypothetical — maxBounces received [20], and PathTracer's `maxBounces +
+		// transmissiveBounces + maxSubsurfaceSteps` then evaluated to the STRING '2058', so the
+		// bounce loop ran to 2058 on any frame the survivor curve could not early-exit and hung
+		// the tab. Unwrap and warn once per uniform, so the caller is named rather than the
+		// symptom surfacing somewhere unrelated.
+		if ( Array.isArray( value ) && value.length === 1
+			&& ( this._booleans.has( name ) || typeof node.value === 'number' ) ) {
+
+			if ( ! this._arrayWarned.has( name ) ) {
+
+				this._arrayWarned.add( name );
+				console.warn(
+					`UniformManager: "${name}" was set to [${value[ 0 ]}] but expects a scalar — ` +
+					'unwrapping. Fix the caller; a slider handler is probably forwarding its ' +
+					'array value unchanged.'
+				);
+
+			}
+
+			value = value[ 0 ];
+
+		}
+
 		if ( this._booleans.has( name ) ) {
 
 			node.value = value ? 1 : 0;
@@ -324,6 +353,7 @@ export class UniformManager {
 
 		this._uniforms.clear();
 		this._booleans.clear();
+		this._arrayWarned.clear();
 		this._lightBuffers = {};
 
 	}