rayzee 5.1.0 → 5.2.0

package/package.json

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

package/src/EngineDefaults.js

@@ -80,6 +80,7 @@ export const ENGINE_DEFAULTS = {
 	renderLimitMode: 'frames',
 	renderTimeLimit: 30,
 	renderMode: 0,
+	enableAlphaShadows: false,
 	tiles: 3,
 	tilesHelper: false,
 	showLightHelper: false,
@@ -337,6 +338,80 @@ export const TRIANGLE_DATA_LAYOUT = {
 	UV_C_MAT_OFFSET: 28
 };
 
+// Material data layout constants — single source of truth for material buffer offsets.
+// Shared between CPU writers (TextureCreator, MaterialDataManager) and GPU readers (Common.js getMaterial).
+export const MATERIAL_DATA_LAYOUT = {
+
+	SLOTS_PER_MATERIAL: 27, // vec4 slots per material
+	FLOATS_PER_MATERIAL: 108, // total floats per material (27 × 4)
+
+	// ── Flat float offsets (CPU side) ────────────────────────────────
+	// Used as: data[ materialIndex * FLOATS_PER_MATERIAL + offset ]
+	// Ordered for cache-line coherence: shadow/culling → BxDF core → maps → extended → transforms
+
+	// Slot 0: ior + transmission + thickness + emissiveIntensity   [shadow]
+	IOR: 0, TRANSMISSION: 1, THICKNESS: 2, EMISSIVE_INTENSITY: 3,
+	// Slot 1: attenuationColor.rgb + attenuationDistance            [shadow]
+	ATTENUATION_COLOR: 4, ATTENUATION_DISTANCE: 7,
+	// Slot 2: opacity + side + transparent + alphaTest              [shadow + culling]
+	OPACITY: 8, SIDE: 9, TRANSPARENT: 10, ALPHA_TEST: 11,
+	// Slot 3: alphaMode + depthWrite + normalScale                  [shadow]
+	ALPHA_MODE: 12, DEPTH_WRITE: 13, NORMAL_SCALE: 14,
+	// Slot 4: color.rgb + metalness                                 [BxDF core]
+	COLOR: 16, METALNESS: 19,
+	// Slot 5: emissive.rgb + roughness                              [BxDF core]
+	EMISSIVE: 20, ROUGHNESS: 23,
+	// Slot 6: map indices (albedo, normal, roughness, metalness)    [maps]
+	ALBEDO_MAP_INDEX: 24, NORMAL_MAP_INDEX: 25, ROUGHNESS_MAP_INDEX: 26, METALNESS_MAP_INDEX: 27,
+	// Slot 7: map indices (emissive, bump) + clearcoat              [maps]
+	EMISSIVE_MAP_INDEX: 28, BUMP_MAP_INDEX: 29, CLEARCOAT: 30, CLEARCOAT_ROUGHNESS: 31,
+	// Slot 8: dispersion + visible + sheen + sheenRoughness         [extended BxDF]
+	DISPERSION: 32, VISIBLE: 33, SHEEN: 34, SHEEN_ROUGHNESS: 35,
+	// Slot 9: sheenColor.rgb + (reserved)                           [extended BxDF]
+	SHEEN_COLOR: 36,
+	// Slot 10: specularIntensity + specularColor.rgb                [extended BxDF]
+	SPECULAR_INTENSITY: 40, SPECULAR_COLOR: 41,
+	// Slot 11: iridescence + iridescenceIOR + iridescenceThicknessRange [extended BxDF]
+	IRIDESCENCE: 44, IRIDESCENCE_IOR: 45, IRIDESCENCE_THICKNESS_RANGE: 46,
+	// Slot 12: bumpScale + displacementScale + displacementMapIndex + (padding)
+	BUMP_SCALE: 48, DISPLACEMENT_SCALE: 49, DISPLACEMENT_MAP_INDEX: 50,
+
+	// ── Transform float offsets (8 floats each: 7 matrix values + 1 padding) ──
+	ALBEDO_TRANSFORM: 52,
+	NORMAL_TRANSFORM: 60,
+	ROUGHNESS_TRANSFORM: 68,
+	METALNESS_TRANSFORM: 76,
+	EMISSIVE_TRANSFORM: 84,
+	BUMP_TRANSFORM: 92,
+	DISPLACEMENT_TRANSFORM: 100,
+
+	// ── Vec4 slot indices (GPU/TSL side) ─────────────────────────────
+	// Used with getDatafromStorageBuffer( buf, matIdx, int(slot), int(SLOTS_PER_MATERIAL) )
+	SLOT: {
+		IOR_TRANSMISSION: 0, // [shadow] ior, transmission, thickness, emissiveIntensity
+		ATTENUATION: 1, // [shadow] attenuationColor, attenuationDistance
+		OPACITY_ALPHA: 2, // [shadow+culling] opacity, side, transparent, alphaTest
+		ALPHA_MODE: 3, // [shadow] alphaMode, depthWrite, normalScale
+		COLOR_METALNESS: 4, // [BxDF] color.rgb, metalness
+		EMISSIVE_ROUGHNESS: 5, // [BxDF] emissive.rgb, roughness
+		MAP_INDICES_A: 6, // [maps] albedo, normal, roughness, metalness
+		MAP_INDICES_B: 7, // [maps] emissive, bump, clearcoat, clearcoatRoughness
+		DISPERSION_SHEEN: 8, // [extended] dispersion, visible, sheen, sheenRoughness
+		SHEEN_COLOR: 9, // [extended] sheenColor, reserved
+		SPECULAR: 10, // [extended] specularIntensity, specularColor
+		IRIDESCENCE: 11, // [extended] iridescence, iridescenceIOR, iridescenceThicknessRange
+		BUMP_DISPLACEMENT: 12, // bumpScale, displacementScale, displacementMapIndex
+		ALBEDO_TRANSFORM_A: 13, ALBEDO_TRANSFORM_B: 14,
+		NORMAL_TRANSFORM_A: 15, NORMAL_TRANSFORM_B: 16,
+		ROUGHNESS_TRANSFORM_A: 17, ROUGHNESS_TRANSFORM_B: 18,
+		METALNESS_TRANSFORM_A: 19, METALNESS_TRANSFORM_B: 20,
+		EMISSIVE_TRANSFORM_A: 21, EMISSIVE_TRANSFORM_B: 22,
+		BUMP_TRANSFORM_A: 23, BUMP_TRANSFORM_B: 24,
+		DISPLACEMENT_TRANSFORM_A: 25, DISPLACEMENT_TRANSFORM_B: 26,
+	},
+
+};
+
 // BVH node leaf markers
 export const BVH_LEAF_MARKERS = {
 	TRIANGLE_LEAF: - 1, // Leaf containing triangle references
@@ -364,14 +439,14 @@ export const DEFAULT_TEXTURE_MATRIX = [ 0, 0, 1, 1, 0, 0, 0, 1 ];
 // Render mode configurations
 export const FINAL_RENDER_CONFIG = {
 	maxSamples: 30, bounces: 20, transmissiveBounces: 8, samplesPerPixel: 1,
-	renderMode: 1, tiles: 3, tilesHelper: false,
+	renderMode: 1, enableAlphaShadows: true, tiles: 3, tilesHelper: false,
 	enableOIDN: true, oidnQuality: 'balance',
 	interactionModeEnabled: false,
 };
 
 export const PREVIEW_RENDER_CONFIG = {
 	maxSamples: ENGINE_DEFAULTS.maxSamples, bounces: ENGINE_DEFAULTS.bounces,
-	samplesPerPixel: ENGINE_DEFAULTS.samplesPerPixel, renderMode: ENGINE_DEFAULTS.renderMode,
+	samplesPerPixel: ENGINE_DEFAULTS.samplesPerPixel, renderMode: ENGINE_DEFAULTS.renderMode, enableAlphaShadows: ENGINE_DEFAULTS.enableAlphaShadows,
 	transmissiveBounces: ENGINE_DEFAULTS.transmissiveBounces,
 	tiles: ENGINE_DEFAULTS.tiles, tilesHelper: ENGINE_DEFAULTS.tilesHelper,
 	enableOIDN: false, oidnQuality: 'fast',

package/src/PathTracerApp.js

@@ -730,6 +730,7 @@ export class PathTracerApp extends EventDispatcher {
 		}, { silent: true } );
 
 		this.stages.pathTracer?.setUniform( 'renderMode', parseInt( config.renderMode ) );
+		this.stages.pathTracer?.setUniform( 'enableAlphaShadows', config.enableAlphaShadows ?? false );
 		this.stages.pathTracer?.tileManager?.setTileCount( config.tiles );
 
 		const tileHelper = this.overlayManager?.getHelper( 'tiles' );

package/src/Pipeline/RenderStage.js

@@ -142,7 +142,6 @@ export class RenderStage {
 
 		const renderMode = context.getState( 'renderMode' ) || 0;
 		const tileRenderingComplete = context.getState( 'tileRenderingComplete' );
-		const frame = context.getState( 'frame' ) || 0;
 
 		switch ( this.executionMode ) {
 

package/src/Processor/AssetLoader.js

@@ -1,4 +1,4 @@
-import { Box3, Vector3, RectAreaLight, Color, FloatType, LinearFilter, EquirectangularReflectionMapping, LinearMipmapLinearFilter,
+import { Box3, Vector3, RectAreaLight, Color, FloatType, LinearFilter, EquirectangularReflectionMapping,
 	TextureLoader, Mesh, MeshStandardMaterial, MeshPhysicalMaterial, CircleGeometry, Points, PointsMaterial, LoadingManager, EventDispatcher
 } from 'three';
 import { GLTFLoader } from 'three/addons/loaders/GLTFLoader.js';
@@ -171,8 +171,6 @@ export class AssetLoader extends EventDispatcher {
 			}
 
 			texture.generateMipmaps = true;
-			// texture.minFilter = LinearMipmapLinearFilter;
-			// texture.magFilter = LinearFilter;
 
 			this.applyEnvironmentToScene( texture );
 			this.dispatchEvent( { type: 'load', texture } );
@@ -353,7 +351,7 @@ export class AssetLoader extends EventDispatcher {
 
 	}
 
-	async findAndLoadModelFromZip( zip, filename ) {
+	async findAndLoadModelFromZip( zip ) {
 
 		const mainModelFiles = [
 			'scene.gltf', 'scene.glb', 'model.gltf', 'model.glb',
@@ -459,7 +457,6 @@ export class AssetLoader extends EventDispatcher {
 		if ( extension === 'gltf' ) {
 
 			const gltfContent = strFromU8( fileContent );
-			const gltfJson = JSON.parse( gltfContent );
 			const manager = new LoadingManager();
 			const gltfDir = filePath.split( '/' ).slice( 0, - 1 ).join( '/' );
 

package/src/Processor/EquirectHDRInfo.js

@@ -1,4 +1,4 @@
-import { DataUtils, HalfFloatType, FloatType } from 'three';
+import { DataUtils, HalfFloatType, FloatType, SRGBColorSpace } from 'three';
 
 /**
  * Binary search to find the closest index
@@ -38,18 +38,35 @@ function colorToLuminance( r, g, b ) {
 
 }
 
+/**
+ * sRGB to linear conversion (IEC 61966-2-1 transfer function)
+ */
+function sRGBToLinear( c ) {
+
+	return c <= 0.04045 ? c / 12.92 : ( ( c + 0.055 ) / 1.055 ) ** 2.4;
+
+}
+
 /**
  * Extract Float32 RGBA pixel data from an environment map.
- * Handles HalfFloat/integer type conversion and Y-flip.
+ * Handles HalfFloat/integer type conversion, canvas extraction for
+ * non-DataTexture images (JPG/PNG), sRGB-to-linear conversion, and Y-flip.
  * @returns {{ floatData: Float32Array, width: number, height: number }}
  */
 export function extractFloatData( envMap ) {
 
-	const { width, height, data } = envMap.image;
+	const { width, height } = envMap.image;
+	let data = envMap.image.data;
+	let needsSRGBToLinear = false;
 
+	// No CPU-accessible data — extract from HTMLImageElement / ImageBitmap via canvas
 	if ( ! data ) {
 
-		throw new Error( 'EquirectHDRInfo: Environment map must have CPU-accessible image data. Render target textures are not supported.' );
+		const canvas = new OffscreenCanvas( width, height );
+		const ctx = canvas.getContext( '2d' );
+		ctx.drawImage( envMap.image, 0, 0, width, height );
+		data = ctx.getImageData( 0, 0, width, height ).data;
+		needsSRGBToLinear = true;
 
 	}
 
@@ -72,7 +89,7 @@ export function extractFloatData( envMap ) {
 
 	} else {
 
-		// Integer types (Uint8, Int16, etc.)
+		// Integer types (Uint8, Uint8Clamped, Int16, etc.)
 		let maxIntValue;
 		if ( data instanceof Int8Array || data instanceof Int16Array || data instanceof Int32Array ) {
 
@@ -93,6 +110,26 @@ export function extractFloatData( envMap ) {
 
 	}
 
+	// Also flag sRGB conversion for DataTextures explicitly marked as sRGB
+	if ( ! needsSRGBToLinear && envMap.colorSpace === SRGBColorSpace ) {
+
+		needsSRGBToLinear = true;
+
+	}
+
+	// Convert sRGB to linear so CDF luminance matches GPU-sampled linear values
+	if ( needsSRGBToLinear ) {
+
+		for ( let i = 0, l = floatData.length; i < l; i += 4 ) {
+
+			floatData[ i ] = sRGBToLinear( floatData[ i ] );
+			floatData[ i + 1 ] = sRGBToLinear( floatData[ i + 1 ] );
+			floatData[ i + 2 ] = sRGBToLinear( floatData[ i + 2 ] );
+
+		}
+
+	}
+
 	// Remove Y-flip for CDF computation
 	if ( envMap.flipY ) {
 

package/src/Processor/SceneProcessor.js

@@ -820,8 +820,8 @@ export class SceneProcessor {
 
 		// Factory method for creating any additional scene elements
 		// Currently returns an empty array by default
-		const white = new Color( 0xffffff );
-		const black = new Color( 0x000000 );
+		// const white = new Color( 0xffffff );
+		// const black = new Color( 0x000000 );
 		return [
 			// { position: new Vector3( - 4, 2, 0 ), radius: 0.8, material: { color: white, emissive: black, emissiveIntensity: 0, roughness: 1.0 } },
 			// { position: new Vector3( - 1.5, 2, 0 ), radius: 0.8, material: { color: white, emissive: black, emissiveIntensity: 0, roughness: 1.0 } },

package/src/Processor/ShaderBuilder.js

@@ -17,6 +17,7 @@ import { TextureNode } from 'three/webgpu';
 import { LinearFilter, DataArrayTexture } from 'three';
 import { pathTracerMain } from '../TSL/PathTracer.js';
 import { setMeshVisibilityBuffer } from '../TSL/BVHTraversal.js';
+import { setShadowAlbedoMaps, setAlphaShadowsUniform } from '../TSL/LightsDirect.js';
 import { BuildTimer } from './BuildTimer.js';
 
 const WG_SIZE = 8;
@@ -192,6 +193,9 @@ export class ShaderBuilder {
 		// Set per-mesh visibility buffer (module-level in BVHTraversal.js, read during graph construction)
 		setMeshVisibilityBuffer( stage.meshVisibilityStorageNode );
 
+		// Set alpha-shadow uniform (module-level in LightsDirect.js, read at runtime)
+		setAlphaShadowsUniform( stage.uniforms.get( 'enableAlphaShadows' ) );
+
 		const envTex = texture( stage.environment.environmentTexture );
 
 		// Adaptive sampling texture
@@ -228,6 +232,11 @@ export class ShaderBuilder {
 		const emissiveMapsTex = mat.emissiveMaps ? texture( mat.emissiveMaps ) : createArrayPlaceholder();
 		const displacementMapsTex = mat.displacementMaps ? texture( mat.displacementMaps ) : createArrayPlaceholder();
 
+		// Set albedo texture array for alpha-aware shadow rays (module-level in LightsDirect.js).
+		// Always pass the texture node (real or placeholder) so alpha-cutout code is emitted
+		// into the shader at graph construction time. Runtime albedoMapIndex >= 0 guards sampling.
+		setShadowAlbedoMaps( albedoMapsTex );
+
 		const result = {
 			triStorage, bvhStorage, matStorage, emissiveTriStorage, lightBVHStorage,
 			envTex, adaptiveSamplingTex, marginalCDFStorage, conditionalCDFStorage,

package/src/Processor/TextureCreator.js

@@ -1,5 +1,5 @@
 import { DataArrayTexture, RGBAFormat, LinearFilter, UnsignedByteType, SRGBColorSpace } from "three";
-import { TEXTURE_CONSTANTS, MEMORY_CONSTANTS, DEFAULT_TEXTURE_MATRIX } from '../EngineDefaults.js';
+import { TEXTURE_CONSTANTS, MEMORY_CONSTANTS, DEFAULT_TEXTURE_MATRIX, MATERIAL_DATA_LAYOUT } from '../EngineDefaults.js';
 
 // Canvas pooling for efficient reuse of canvas elements
 class CanvasPool {
@@ -858,9 +858,9 @@ export class TextureCreator {
 	 */
 	createMaterialRawData( materials ) {
 
-		const pixelsRequired = TEXTURE_CONSTANTS.PIXELS_PER_MATERIAL;
-		const dataInEachPixel = TEXTURE_CONSTANTS.RGBA_COMPONENTS;
-		const dataLengthPerMaterial = pixelsRequired * dataInEachPixel;
+		// Layout is defined by MATERIAL_DATA_LAYOUT in EngineDefaults.js.
+		// The inline array below must match that layout exactly (positional order = canonical layout).
+		const dataLengthPerMaterial = MATERIAL_DATA_LAYOUT.FLOATS_PER_MATERIAL;
 		const totalMaterials = materials.length;
 
 		const size = totalMaterials * dataLengthPerMaterial;
@@ -879,19 +879,34 @@ export class TextureCreator {
 			const bumpMapMatrices = mat.bumpMapMatrices ?? DEFAULT_TEXTURE_MATRIX;
 			const displacementMapMatrices = mat.displacementMapMatrices ?? DEFAULT_TEXTURE_MATRIX;
 
+			// Slot order: shadow/culling → BxDF core → maps → extended → displacement → transforms
+			// Must match MATERIAL_DATA_LAYOUT in EngineDefaults.js exactly.
 			const materialData = [
-				mat.color.r, 				mat.color.g, 				mat.color.b, 				mat.metalness,
-				mat.emissive.r, 			mat.emissive.g, 			mat.emissive.b, 			mat.roughness,
+				// Slot 0: shadow core (ior, transmission, thickness, emissiveIntensity)
 				mat.ior, 					mat.transmission, 			mat.thickness, 				mat.emissiveIntensity,
+				// Slot 1: shadow (attenuationColor, attenuationDistance)
 				mat.attenuationColor.r, 	mat.attenuationColor.g, 	mat.attenuationColor.b, 	mat.attenuationDistance,
+				// Slot 2: shadow + culling (opacity, side, transparent, alphaTest)
+				mat.opacity, 				mat.side, 					mat.transparent, 			mat.alphaTest,
+				// Slot 3: shadow (alphaMode, depthWrite, normalScale)
+				mat.alphaMode, 				mat.depthWrite, 			mat.normalScale?.x ?? 1, 	mat.normalScale?.y ?? 1,
+				// Slot 4: BxDF core (color, metalness)
+				mat.color.r, 				mat.color.g, 				mat.color.b, 				mat.metalness,
+				// Slot 5: BxDF core (emissive, roughness)
+				mat.emissive.r, 			mat.emissive.g, 			mat.emissive.b, 			mat.roughness,
+				// Slot 6: map indices A (albedo, normal, roughness, metalness)
+				mat.map, 					mat.normalMap, 				mat.roughnessMap, 			mat.metalnessMap,
+				// Slot 7: map indices B (emissive, bump, clearcoat, clearcoatRoughness)
+				mat.emissiveMap, 			mat.bumpMap, 				mat.clearcoat, 				mat.clearcoatRoughness,
+				// Slot 8: extended BxDF (dispersion, visible, sheen, sheenRoughness)
 				mat.dispersion, 			mat.visible, 				mat.sheen, 					mat.sheenRoughness,
+				// Slot 9: extended BxDF (sheenColor, reserved)
 				mat.sheenColor.r, 			mat.sheenColor.g, 			mat.sheenColor.b, 			1,
+				// Slot 10: extended BxDF (specularIntensity, specularColor)
 				mat.specularIntensity, 		mat.specularColor.r, 		mat.specularColor.g, 		mat.specularColor.b,
+				// Slot 11: extended BxDF (iridescence)
 				mat.iridescence, 			mat.iridescenceIOR, 		mat.iridescenceThicknessRange[ 0 ], mat.iridescenceThicknessRange[ 1 ],
-				mat.map, 					mat.normalMap, 				mat.roughnessMap, 			mat.metalnessMap,
-				mat.emissiveMap, 			mat.bumpMap, 				mat.clearcoat, 				mat.clearcoatRoughness,
-				mat.opacity, 				mat.side, 					mat.transparent, 			mat.alphaTest,
-				mat.alphaMode, 				mat.depthWrite, 			mat.normalScale?.x ?? 1, 	mat.normalScale?.y ?? 1,
+				// Slot 12: displacement
 				mat.bumpScale,				mat.displacementScale,		mat.displacementMap,		0,
 				mapMatrix[ 0 ], 			mapMatrix[ 1 ], 			mapMatrix[ 2 ], 			mapMatrix[ 3 ],
 				mapMatrix[ 4 ], 			mapMatrix[ 5 ], 			mapMatrix[ 6 ], 			1,

package/src/RenderSettings.js

@@ -31,6 +31,7 @@ const SETTING_ROUTES = {
 	anamorphicRatio: { uniform: 'anamorphicRatio', reset: true },
 	samplingTechnique: { uniform: 'samplingTechnique', reset: true },
 	fireflyThreshold: { uniform: 'fireflyThreshold', reset: true },
+	enableAlphaShadows: { uniform: 'enableAlphaShadows', reset: true },
 	enableEmissiveTriangleSampling: { uniform: 'enableEmissiveTriangleSampling', reset: true },
 	emissiveBoost: { uniform: 'emissiveBoost', reset: true },
 	visMode: { uniform: 'visMode', reset: true },

package/src/TSL/BVHTraversal.js

@@ -26,7 +26,7 @@ import {
 } from 'three/tsl';
 
 import { Ray, HitInfo } from './Struct.js';
-import { getDatafromStorageBuffer, MATERIAL_SLOTS } from './Common.js';
+import { getDatafromStorageBuffer, MATERIAL_SLOTS, MATERIAL_SLOT } from './Common.js';
 import { RandomPointInCircle } from './Random.js';
 
 // ================================================================================
@@ -136,7 +136,7 @@ const fastRayAABBDst = wgslFn( `
 // Per-mesh visibility handled at BLAS-pointer level; material visibility always 1.
 export const passesSideCulling = Fn( ( [ materialIndex, rayDirection, normal, materialBuffer ] ) => {
 
-	const sideData = getDatafromStorageBuffer( materialBuffer, materialIndex, int( 10 ), int( MATERIAL_SLOTS ) );
+	const sideData = getDatafromStorageBuffer( materialBuffer, materialIndex, int( MATERIAL_SLOT.OPACITY_ALPHA ), int( MATERIAL_SLOTS ) );
 	const side = int( sideData.g );
 	const rayDotNormal = rayDirection.dot( normal );
 	const doubleSide = side.equal( int( 2 ) );
@@ -451,6 +451,12 @@ export const traverseBVHShadow = Fn( ( [
 						closestHit.hitPoint.assign( ray.origin.add( ray.direction.mul( triResult.x ) ) );
 						closestHit.normal.assign( normalize( cross( pB.sub( pA ), pC.sub( pA ) ) ) );
 
+						// Store barycentrics + triangle index for deferred UV computation.
+						// Actual UV interpolation happens in traceShadowRay only when
+						// the material needs alpha testing — zero overhead for opaque hits.
+						closestHit.uv.assign( vec2( triResult.y, triResult.z ) );
+						closestHit.triangleIndex.assign( triIndex );
+
 						// Shadow ray only needs any hit — skip remaining triangles in leaf
 						Break();
 

package/src/TSL/Common.js

@@ -5,6 +5,7 @@ import {
 	MaterialClassification,
 	MISStrategy,
 	RayTracingMaterial,
+	ShadowMaterial,
 } from './Struct.js';
 
 export const PI = 3.14159;
@@ -16,7 +17,11 @@ export const MIN_CLEARCOAT_ROUGHNESS = 0.089;
 export const MAX_ROUGHNESS = 1.0;
 export const MIN_PDF = 0.001;
 export const REC709_LUMINANCE_COEFFICIENTS = vec3( 0.2126, 0.7152, 0.0722 );
-export const MATERIAL_SLOTS = 27;
+import { MATERIAL_DATA_LAYOUT } from '../EngineDefaults.js';
+
+export const MATERIAL_SLOTS = MATERIAL_DATA_LAYOUT.SLOTS_PER_MATERIAL;
+export const MATERIAL_SLOT = MATERIAL_DATA_LAYOUT.SLOT;
+const S = MATERIAL_SLOT;
 
 // XYZ to sRGB color space conversion matrix
 export const XYZ_TO_REC709 = mat3(
@@ -313,33 +318,33 @@ export const arrayToMat3 = wgslFn( `
 
 export const getMaterial = Fn( ( [ materialIndex, materialBuffer ] ) => {
 
-	const data0 = getDatafromStorageBuffer( materialBuffer, materialIndex, int( 0 ), int( MATERIAL_SLOTS ) ).toVar();
-	const data1 = getDatafromStorageBuffer( materialBuffer, materialIndex, int( 1 ), int( MATERIAL_SLOTS ) ).toVar();
-	const data2 = getDatafromStorageBuffer( materialBuffer, materialIndex, int( 2 ), int( MATERIAL_SLOTS ) ).toVar();
-	const data3 = getDatafromStorageBuffer( materialBuffer, materialIndex, int( 3 ), int( MATERIAL_SLOTS ) ).toVar();
-	const data4 = getDatafromStorageBuffer( materialBuffer, materialIndex, int( 4 ), int( MATERIAL_SLOTS ) ).toVar();
-	const data5 = getDatafromStorageBuffer( materialBuffer, materialIndex, int( 5 ), int( MATERIAL_SLOTS ) ).toVar();
-	const data6 = getDatafromStorageBuffer( materialBuffer, materialIndex, int( 6 ), int( MATERIAL_SLOTS ) ).toVar();
-	const data7 = getDatafromStorageBuffer( materialBuffer, materialIndex, int( 7 ), int( MATERIAL_SLOTS ) ).toVar();
-	const data8 = getDatafromStorageBuffer( materialBuffer, materialIndex, int( 8 ), int( MATERIAL_SLOTS ) ).toVar();
-	const data9 = getDatafromStorageBuffer( materialBuffer, materialIndex, int( 9 ), int( MATERIAL_SLOTS ) ).toVar();
-	const data10 = getDatafromStorageBuffer( materialBuffer, materialIndex, int( 10 ), int( MATERIAL_SLOTS ) ).toVar();
-	const data11 = getDatafromStorageBuffer( materialBuffer, materialIndex, int( 11 ), int( MATERIAL_SLOTS ) ).toVar();
-	const data12 = getDatafromStorageBuffer( materialBuffer, materialIndex, int( 12 ), int( MATERIAL_SLOTS ) ).toVar();
-	const data13 = getDatafromStorageBuffer( materialBuffer, materialIndex, int( 13 ), int( MATERIAL_SLOTS ) ).toVar();
-	const data14 = getDatafromStorageBuffer( materialBuffer, materialIndex, int( 14 ), int( MATERIAL_SLOTS ) ).toVar();
-	const data15 = getDatafromStorageBuffer( materialBuffer, materialIndex, int( 15 ), int( MATERIAL_SLOTS ) ).toVar();
-	const data16 = getDatafromStorageBuffer( materialBuffer, materialIndex, int( 16 ), int( MATERIAL_SLOTS ) ).toVar();
-	const data17 = getDatafromStorageBuffer( materialBuffer, materialIndex, int( 17 ), int( MATERIAL_SLOTS ) ).toVar();
-	const data18 = getDatafromStorageBuffer( materialBuffer, materialIndex, int( 18 ), int( MATERIAL_SLOTS ) ).toVar();
-	const data19 = getDatafromStorageBuffer( materialBuffer, materialIndex, int( 19 ), int( MATERIAL_SLOTS ) ).toVar();
-	const data20 = getDatafromStorageBuffer( materialBuffer, materialIndex, int( 20 ), int( MATERIAL_SLOTS ) ).toVar();
-	const data21 = getDatafromStorageBuffer( materialBuffer, materialIndex, int( 21 ), int( MATERIAL_SLOTS ) ).toVar();
-	const data22 = getDatafromStorageBuffer( materialBuffer, materialIndex, int( 22 ), int( MATERIAL_SLOTS ) ).toVar();
-	const data23 = getDatafromStorageBuffer( materialBuffer, materialIndex, int( 23 ), int( MATERIAL_SLOTS ) ).toVar();
-	const data24 = getDatafromStorageBuffer( materialBuffer, materialIndex, int( 24 ), int( MATERIAL_SLOTS ) ).toVar();
-	const data25 = getDatafromStorageBuffer( materialBuffer, materialIndex, int( 25 ), int( MATERIAL_SLOTS ) ).toVar();
-	const data26 = getDatafromStorageBuffer( materialBuffer, materialIndex, int( 26 ), int( MATERIAL_SLOTS ) ).toVar();
+	const data0 = getDatafromStorageBuffer( materialBuffer, materialIndex, int( S.COLOR_METALNESS ), int( MATERIAL_SLOTS ) ).toVar();
+	const data1 = getDatafromStorageBuffer( materialBuffer, materialIndex, int( S.EMISSIVE_ROUGHNESS ), int( MATERIAL_SLOTS ) ).toVar();
+	const data2 = getDatafromStorageBuffer( materialBuffer, materialIndex, int( S.IOR_TRANSMISSION ), int( MATERIAL_SLOTS ) ).toVar();
+	const data3 = getDatafromStorageBuffer( materialBuffer, materialIndex, int( S.ATTENUATION ), int( MATERIAL_SLOTS ) ).toVar();
+	const data4 = getDatafromStorageBuffer( materialBuffer, materialIndex, int( S.DISPERSION_SHEEN ), int( MATERIAL_SLOTS ) ).toVar();
+	const data5 = getDatafromStorageBuffer( materialBuffer, materialIndex, int( S.SHEEN_COLOR ), int( MATERIAL_SLOTS ) ).toVar();
+	const data6 = getDatafromStorageBuffer( materialBuffer, materialIndex, int( S.SPECULAR ), int( MATERIAL_SLOTS ) ).toVar();
+	const data7 = getDatafromStorageBuffer( materialBuffer, materialIndex, int( S.IRIDESCENCE ), int( MATERIAL_SLOTS ) ).toVar();
+	const data8 = getDatafromStorageBuffer( materialBuffer, materialIndex, int( S.MAP_INDICES_A ), int( MATERIAL_SLOTS ) ).toVar();
+	const data9 = getDatafromStorageBuffer( materialBuffer, materialIndex, int( S.MAP_INDICES_B ), int( MATERIAL_SLOTS ) ).toVar();
+	const data10 = getDatafromStorageBuffer( materialBuffer, materialIndex, int( S.OPACITY_ALPHA ), int( MATERIAL_SLOTS ) ).toVar();
+	const data11 = getDatafromStorageBuffer( materialBuffer, materialIndex, int( S.ALPHA_MODE ), int( MATERIAL_SLOTS ) ).toVar();
+	const data12 = getDatafromStorageBuffer( materialBuffer, materialIndex, int( S.BUMP_DISPLACEMENT ), int( MATERIAL_SLOTS ) ).toVar();
+	const data13 = getDatafromStorageBuffer( materialBuffer, materialIndex, int( S.ALBEDO_TRANSFORM_A ), int( MATERIAL_SLOTS ) ).toVar();
+	const data14 = getDatafromStorageBuffer( materialBuffer, materialIndex, int( S.ALBEDO_TRANSFORM_B ), int( MATERIAL_SLOTS ) ).toVar();
+	const data15 = getDatafromStorageBuffer( materialBuffer, materialIndex, int( S.NORMAL_TRANSFORM_A ), int( MATERIAL_SLOTS ) ).toVar();
+	const data16 = getDatafromStorageBuffer( materialBuffer, materialIndex, int( S.NORMAL_TRANSFORM_B ), int( MATERIAL_SLOTS ) ).toVar();
+	const data17 = getDatafromStorageBuffer( materialBuffer, materialIndex, int( S.ROUGHNESS_TRANSFORM_A ), int( MATERIAL_SLOTS ) ).toVar();
+	const data18 = getDatafromStorageBuffer( materialBuffer, materialIndex, int( S.ROUGHNESS_TRANSFORM_B ), int( MATERIAL_SLOTS ) ).toVar();
+	const data19 = getDatafromStorageBuffer( materialBuffer, materialIndex, int( S.METALNESS_TRANSFORM_A ), int( MATERIAL_SLOTS ) ).toVar();
+	const data20 = getDatafromStorageBuffer( materialBuffer, materialIndex, int( S.METALNESS_TRANSFORM_B ), int( MATERIAL_SLOTS ) ).toVar();
+	const data21 = getDatafromStorageBuffer( materialBuffer, materialIndex, int( S.EMISSIVE_TRANSFORM_A ), int( MATERIAL_SLOTS ) ).toVar();
+	const data22 = getDatafromStorageBuffer( materialBuffer, materialIndex, int( S.EMISSIVE_TRANSFORM_B ), int( MATERIAL_SLOTS ) ).toVar();
+	const data23 = getDatafromStorageBuffer( materialBuffer, materialIndex, int( S.BUMP_TRANSFORM_A ), int( MATERIAL_SLOTS ) ).toVar();
+	const data24 = getDatafromStorageBuffer( materialBuffer, materialIndex, int( S.BUMP_TRANSFORM_B ), int( MATERIAL_SLOTS ) ).toVar();
+	const data25 = getDatafromStorageBuffer( materialBuffer, materialIndex, int( S.DISPLACEMENT_TRANSFORM_A ), int( MATERIAL_SLOTS ) ).toVar();
+	const data26 = getDatafromStorageBuffer( materialBuffer, materialIndex, int( S.DISPLACEMENT_TRANSFORM_B ), int( MATERIAL_SLOTS ) ).toVar();
 
 	return RayTracingMaterial( {
 		color: vec4( data0.rgb, 1.0 ),
@@ -390,6 +395,35 @@ export const getMaterial = Fn( ( [ materialIndex, materialBuffer ] ) => {
 
 } );
 
+// ── Shadow material thin reader (7 slot reads instead of 27) ─────────────
+// Only fetches fields needed by traceShadowRay: alpha, transmission, attenuation, albedo transform.
+
+export const getShadowMaterial = Fn( ( [ materialIndex, materialBuffer ] ) => {
+
+	const data2 = getDatafromStorageBuffer( materialBuffer, materialIndex, int( S.IOR_TRANSMISSION ), int( MATERIAL_SLOTS ) ).toVar();
+	const data3 = getDatafromStorageBuffer( materialBuffer, materialIndex, int( S.ATTENUATION ), int( MATERIAL_SLOTS ) ).toVar();
+	const data8 = getDatafromStorageBuffer( materialBuffer, materialIndex, int( S.MAP_INDICES_A ), int( MATERIAL_SLOTS ) ).toVar();
+	const data10 = getDatafromStorageBuffer( materialBuffer, materialIndex, int( S.OPACITY_ALPHA ), int( MATERIAL_SLOTS ) ).toVar();
+	const data11 = getDatafromStorageBuffer( materialBuffer, materialIndex, int( S.ALPHA_MODE ), int( MATERIAL_SLOTS ) ).toVar();
+	const data13 = getDatafromStorageBuffer( materialBuffer, materialIndex, int( S.ALBEDO_TRANSFORM_A ), int( MATERIAL_SLOTS ) ).toVar();
+	const data14 = getDatafromStorageBuffer( materialBuffer, materialIndex, int( S.ALBEDO_TRANSFORM_B ), int( MATERIAL_SLOTS ) ).toVar();
+
+	return ShadowMaterial( {
+		color: vec4( 1.0 ), // Shadow path never samples full textures; color.a is always 1.0
+		ior: data2.r,
+		transmission: data2.g,
+		attenuationColor: data3.rgb,
+		attenuationDistance: data3.a,
+		albedoMapIndex: int( data8.r ),
+		opacity: data10.r,
+		transparent: data10.b,
+		alphaTest: data10.a,
+		alphaMode: int( data11.r ),
+		albedoTransform: arrayToMat3( { data1: data13, data2: data14 } ),
+	} );
+
+} );
+
 // ── Edge-stopping weight (normal + depth) ──────────────────────────────────
 // Used by ASVGF and SSRC for temporal/spatial reprojection edge-stopping.
 

package/src/TSL/EmissiveSampling.js

@@ -28,7 +28,7 @@ import {
 } from 'three/tsl';
 
 import { struct } from './structProxy.js';
-import { MIN_PDF, getDatafromStorageBuffer, powerHeuristic } from './Common.js';
+import { MIN_PDF, getDatafromStorageBuffer, powerHeuristic, MATERIAL_SLOTS, MATERIAL_SLOT } from './Common.js';
 import { RandomValue } from './Random.js';
 import { calculateMaterialPDF } from './LightsSampling.js';
 
@@ -326,9 +326,8 @@ export const calculateEmissiveLightPdf = Fn( ( [
 	const area = triangleArea( triData.v0, triData.v1, triData.v2 );
 
 	// Targeted material read: only fetch emissive data (2 vec4s instead of full 27)
-	const MATERIAL_SLOTS = int( 27 );
-	const matData1 = getDatafromStorageBuffer( materialBuffer, triData.materialIndex, int( 1 ), MATERIAL_SLOTS );
-	const matData2 = getDatafromStorageBuffer( materialBuffer, triData.materialIndex, int( 2 ), MATERIAL_SLOTS );
+	const matData1 = getDatafromStorageBuffer( materialBuffer, triData.materialIndex, int( MATERIAL_SLOT.EMISSIVE_ROUGHNESS ), MATERIAL_SLOTS );
+	const matData2 = getDatafromStorageBuffer( materialBuffer, triData.materialIndex, int( MATERIAL_SLOT.IOR_TRANSMISSION ), MATERIAL_SLOTS );
 	const avgEmissive = matData1.x.add( matData1.y ).add( matData1.z ).div( 3.0 );
 	const power = max( avgEmissive.mul( matData2.a ).mul( area ), float( 1e-10 ) );
 	const selectionPdf = power.div( max( emissiveTotalPower, float( 1e-10 ) ) );