rayzee 5.1.1 → 5.3.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "rayzee",
-  "version": "5.1.1",
+  "version": "5.3.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' );
@@ -1013,6 +1014,7 @@ export class PathTracerApp extends EventDispatcher {
 
 		this._sdf = new SceneProcessor();
 		this.assetLoader = new AssetLoader( this.meshScene, this.cameraManager.camera, this.cameraManager.controls );
+		this.assetLoader.setRenderer( this.renderer );
 		this.assetLoader.createFloorPlane();
 
 		this.cameraManager.controls.addEventListener( 'change', () => {

package/src/Processor/AssetLoader.js

@@ -4,6 +4,7 @@ import { Box3, Vector3, RectAreaLight, Color, FloatType, LinearFilter, Equirecta
 import { GLTFLoader } from 'three/addons/loaders/GLTFLoader.js';
 import { HDRLoader } from 'three/addons/loaders/HDRLoader.js';
 import { DRACOLoader } from 'three/addons/loaders/DRACOLoader.js';
+import { KTX2Loader } from 'three/addons/loaders/KTX2Loader.js';
 import { EXRLoader } from 'three/addons/loaders/EXRLoader.js';
 import { createMeshesFromMultiMaterialMesh } from 'three/addons/utils/SceneUtils.js';
 import { MeshoptDecoder } from 'three/addons/libs/meshopt_decoder.module.js';
@@ -41,6 +42,13 @@ export class AssetLoader extends EventDispatcher {
 		this.loaderCache = {};
 		this.uploadedFileInfo = null;
 		this.animations = [];
+		this.renderer = null;
+
+	}
+
+	setRenderer( renderer ) {
+
+		this.renderer = renderer;
 
 	}
 
@@ -698,8 +706,31 @@ export class AssetLoader extends EventDispatcher {
 		dracoLoader.setDecoderConfig( { type: 'js' } );
 		dracoLoader.setDecoderPath( 'https://www.gstatic.com/draco/v1/decoders/' );
 
+		const ktx2Loader = new KTX2Loader();
+		ktx2Loader.setTranscoderPath( 'https://cdn.jsdelivr.net/npm/three@0.183.2/examples/jsm/libs/basis/' );
+
+		if ( this.renderer ) {
+
+			ktx2Loader.detectSupport( this.renderer );
+
+			// Force RGBA output for Basis Universal textures. GPU-compressed
+			// texture arrays (CompressedArrayTexture) are blocked by a Three.js
+			// TSL limitation: the node compiler maintains global state that
+			// survives dispose(), so swapping texture array formats between
+			// DataArrayTexture and CompressedArrayTexture at runtime causes
+			// WGSL compilation failures (unresolved uniform bindings).
+			ktx2Loader.workerConfig = {
+				astcSupported: false, etc1Supported: false, etc2Supported: false,
+				dxtSupported: false, bptcSupported: false, pvrtcSupported: false,
+			};
+
+		}
+
+		this.loaderCache.ktx2 = ktx2Loader;
+
 		const loader = new GLTFLoader();
 		loader.setDRACOLoader( dracoLoader );
+		loader.setKTX2Loader( ktx2Loader );
 		loader.setMeshoptDecoder( MeshoptDecoder );
 
 		this.loaderCache.gltf = loader;

package/src/Processor/GeometryExtractor.js

@@ -542,55 +542,29 @@ export class GeometryExtractor {
 		for ( let i = 0; i < triangleCount; i ++ ) {
 
 			const i3 = i * 3;
+			const idxA = indices ? indices[ i3 + 0 ] : i3 + 0;
+			const idxB = indices ? indices[ i3 + 1 ] : i3 + 1;
+			const idxC = indices ? indices[ i3 + 2 ] : i3 + 2;
 
-			// Get vertices
-			if ( indices ) {
+			this.getVertex( positions, idxA, posA );
+			this.getVertex( positions, idxB, posB );
+			this.getVertex( positions, idxC, posC );
 
-				this.getVertexFromIndices( positions, indices[ i3 + 0 ], posA );
-				this.getVertexFromIndices( positions, indices[ i3 + 1 ], posB );
-				this.getVertexFromIndices( positions, indices[ i3 + 2 ], posC );
+			this.getVertex( normals, idxA, normalA );
+			this.getVertex( normals, idxB, normalB );
+			this.getVertex( normals, idxC, normalC );
 
-				this.getVertexFromIndices( normals, indices[ i3 + 0 ], normalA );
-				this.getVertexFromIndices( normals, indices[ i3 + 1 ], normalB );
-				this.getVertexFromIndices( normals, indices[ i3 + 2 ], normalC );
+			if ( uvs ) {
 
-				if ( uvs ) {
-
-					this.getVertexFromIndices( uvs, indices[ i3 + 0 ], uvA );
-					this.getVertexFromIndices( uvs, indices[ i3 + 1 ], uvB );
-					this.getVertexFromIndices( uvs, indices[ i3 + 2 ], uvC );
-
-				} else {
-
-					uvA.set( 0, 0 );
-					uvB.set( 0, 0 );
-					uvC.set( 0, 0 );
-
-				}
+				this.getVertex( uvs, idxA, uvA );
+				this.getVertex( uvs, idxB, uvB );
+				this.getVertex( uvs, idxC, uvC );
 
 			} else {
 
-				this.getVertex( positions, i3 + 0, posA );
-				this.getVertex( positions, i3 + 1, posB );
-				this.getVertex( positions, i3 + 2, posC );
-
-				this.getVertex( normals, i3 + 0, normalA );
-				this.getVertex( normals, i3 + 1, normalB );
-				this.getVertex( normals, i3 + 2, normalC );
-
-				if ( uvs ) {
-
-					this.getVertex( uvs, i3 + 0, uvA );
-					this.getVertex( uvs, i3 + 1, uvB );
-					this.getVertex( uvs, i3 + 2, uvC );
-
-				} else {
-
-					uvA.set( 0, 0 );
-					uvB.set( 0, 0 );
-					uvC.set( 0, 0 );
-
-				}
+				uvA.set( 0, 0 );
+				uvB.set( 0, 0 );
+				uvC.set( 0, 0 );
 
 			}
 
@@ -689,37 +663,18 @@ export class GeometryExtractor {
 	}
 
 	// Optimized attribute access methods
-	getVertexFromIndices( attribute, index, target ) {
-
-		if ( attribute.itemSize === 2 ) {
-
-			target.x = attribute.array[ index * 2 ];
-			target.y = attribute.array[ index * 2 + 1 ];
-
-		} else if ( attribute.itemSize === 3 ) {
-
-			target.x = attribute.array[ index * 3 ];
-			target.y = attribute.array[ index * 3 + 1 ];
-			target.z = attribute.array[ index * 3 + 2 ];
-
-		}
-
-		return target;
-
-	}
-
 	getVertex( attribute, index, target ) {
 
 		if ( attribute.itemSize === 2 ) {
 
-			target.x = attribute.array[ index * 2 ];
-			target.y = attribute.array[ index * 2 + 1 ];
+			target.x = attribute.getX( index );
+			target.y = attribute.getY( index );
 
-		} else if ( attribute.itemSize === 3 ) {
+		} else if ( attribute.itemSize >= 3 ) {
 
-			target.x = attribute.array[ index * 3 ];
-			target.y = attribute.array[ index * 3 + 1 ];
-			target.z = attribute.array[ index * 3 + 2 ];
+			target.x = attribute.getX( index );
+			target.y = attribute.getY( index );
+			target.z = attribute.getZ( index );
 
 		}
 

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 {
@@ -496,8 +496,11 @@ export class TextureCreator {
 		const cached = this.textureCache.get( cacheKey );
 		if ( cached ) return cached;
 
+		// Normalize non-drawable images (KTX2 CompressedTexture RGBA, DataTexture)
+		const { normalized, bitmapsToClose } = await this._normalizeTexturesForProcessing( textures );
+
 		// Select optimal processing strategy
-		const strategy = this.selectProcessingStrategy( textures );
+		const strategy = this.selectProcessingStrategy( normalized );
 		let result;
 
 		try {
@@ -505,19 +508,19 @@ export class TextureCreator {
 			switch ( strategy.method ) {
 
 				case 'worker-direct':
-					result = await this.processWithWorkerDirect( textures );
+					result = await this.processWithWorkerDirect( normalized );
 					break;
 				case 'worker-chunked':
-					result = await this.processWithWorkerChunked( textures, strategy.chunkSize );
+					result = await this.processWithWorkerChunked( normalized, strategy.chunkSize );
 					break;
 				case 'main-batch':
-					result = await this.processOnMainThreadBatch( textures, strategy.batchSize );
+					result = await this.processOnMainThreadBatch( normalized, strategy.batchSize );
 					break;
 				case 'main-streaming':
-					result = await this.processOnMainThreadStreaming( textures );
+					result = await this.processOnMainThreadStreaming( normalized );
 					break;
 				default:
-					result = await this.processOnMainThreadSync( textures );
+					result = await this.processOnMainThreadSync( normalized );
 
 			}
 
@@ -533,7 +536,11 @@ export class TextureCreator {
 		} catch ( error ) {
 
 			console.warn( 'Texture processing failed, trying fallback:', error );
-			return await this.processOnMainThreadSync( textures );
+			return await this.processOnMainThreadSync( normalized );
+
+		} finally {
+
+			for ( const bmp of bitmapsToClose ) bmp.close();
 
 		}
 
@@ -858,9 +865,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 +886,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,
@@ -1243,6 +1265,109 @@ export class TextureCreator {
 
 	}
 
+	// ── KTX2 / DataTexture normalization ────────────────────────────────
+
+	/**
+	 * Normalize textures so every entry has a drawable `.image`.
+	 * - RGBA CompressedTexture (KTX2 Basis → RGBA): pixel data from mipmaps[0]
+	 * - GPU-compressed texture (BC7/ASTC/ETC2): warning (should be pre-decompressed)
+	 * - DataTexture (raw RGBA pixels): pixel data from image.data
+	 * - Regular texture: passed through as-is
+	 *
+	 * Bitmap creation is parallelized via Promise.all.
+	 */
+	async _normalizeTexturesForProcessing( textures ) {
+
+		const normalized = [];
+		const bitmapsToClose = [];
+		const bitmapJobs = []; // { index, promise }
+
+		for ( const tex of textures ) {
+
+			if ( ! tex?.image ) continue;
+
+			// RGBA CompressedTexture (KTX2 Basis transcode wraps output as CompressedTexture)
+			if ( tex.isCompressedTexture && tex.format === RGBAFormat && tex.mipmaps?.[ 0 ]?.data ) {
+
+				const mip = tex.mipmaps[ 0 ];
+				const idx = normalized.length;
+				normalized.push( null ); // placeholder — filled after Promise.all
+				bitmapJobs.push( { index: idx, promise: _rawPixelsToBitmap( mip.data, mip.width, mip.height ) } );
+				continue;
+
+			}
+
+			// True GPU-compressed texture in a mixed group — can't extract pixels on CPU.
+			// All-compressed groups are handled by the CompressedArrayTexture path upstream.
+			if ( tex.isCompressedTexture ) {
+
+				console.warn( '[TextureCreator] GPU-compressed texture in mixed group — using placeholder' );
+				normalized.push( null );
+				continue;
+
+			}
+
+			// DataTexture with raw pixel array
+			if ( tex.image.data && ! ( tex.image instanceof HTMLImageElement ) &&
+				! ( tex.image instanceof HTMLCanvasElement ) &&
+				! ( typeof ImageBitmap !== 'undefined' && tex.image instanceof ImageBitmap ) ) {
+
+				const idx = normalized.length;
+				normalized.push( null );
+				bitmapJobs.push( { index: idx, promise: _rawPixelsToBitmap( tex.image.data, tex.image.width, tex.image.height ) } );
+				continue;
+
+			}
+
+			normalized.push( tex );
+
+		}
+
+		// Resolve all bitmap conversions in parallel
+		if ( bitmapJobs.length > 0 ) {
+
+			const results = await Promise.allSettled( bitmapJobs.map( j => j.promise ) );
+
+			for ( let i = 0; i < bitmapJobs.length; i ++ ) {
+
+				const { index } = bitmapJobs[ i ];
+				const result = results[ i ];
+
+				if ( result.status === 'fulfilled' ) {
+
+					const bitmap = result.value;
+					bitmapsToClose.push( bitmap );
+					normalized[ index ] = { image: bitmap };
+
+				} else {
+
+					console.warn( '[TextureCreator] Failed to create ImageBitmap:', result.reason );
+
+				}
+
+			}
+
+		}
+
+		// Replace any remaining nulls (failed conversions) with a 1x1 white placeholder
+		// to preserve array indexing alignment with material texture indices.
+		for ( let i = 0; i < normalized.length; i ++ ) {
+
+			if ( normalized[ i ] === null ) {
+
+				const placeholder = new Uint8ClampedArray( [ 255, 255, 255, 255 ] );
+				const bitmap = await createImageBitmap( new ImageData( placeholder, 1, 1 ) );
+				bitmapsToClose.push( bitmap );
+				normalized[ i ] = { image: bitmap };
+
+			}
+
+		}
+
+		return { normalized, bitmapsToClose };
+
+	}
+
 	createFallbackTexture() {
 
 		const data = new Uint8Array( [ 255, 255, 255, 255 ] );
@@ -1276,3 +1401,14 @@ export class TextureCreator {
 	}
 
 }
+
+// ── Helpers ──────────────────────────────────────────────────────────
+
+/** Convert raw RGBA pixel data to an ImageBitmap (zero-copy Uint8ClampedArray view). */
+function _rawPixelsToBitmap( data, width, height ) {
+
+	const clamped = new Uint8ClampedArray( data.buffer, data.byteOffset, data.byteLength );
+	return createImageBitmap( new ImageData( clamped, width, height ) );
+
+}
+

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 ) );
@@ -268,7 +268,7 @@ export const traverseBVH = Fn( ( [
 				} );
 
 				// If we found a very close hit, we can terminate early
-				If( closestHit.didHit.and( closestHit.dst.lessThan( 1e-6 ) ), () => {
+				If( closestHit.didHit.and( closestHit.dst.lessThan( 0.001 ) ), () => {
 
 					Break();
 
@@ -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();