rayzee 7.7.0 → 7.8.0

package/package.json

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

package/src/EngineDefaults.js

@@ -492,9 +492,53 @@ export const TEXTURE_CONSTANTS = {
 	// guaranteed minimum). The configurable maxTextureSize setting is clamped to this.
 	MAX_TEXTURE_SIZE: 8192,
 	// Default cap applied when no maxTextureSize is supplied (engine standalone use).
-	DEFAULT_MAX_TEXTURE_SIZE: 4096
+	DEFAULT_MAX_TEXTURE_SIZE: 4096,
+	// Max layers (textures) per bucket array. Also the packing stride for (bucket, layer).
+	MAX_TEXTURES_LIMIT: 128,
+	// Size buckets per colorSpace pool. Material maps are grouped into this many
+	// longest-edge size classes so a small map no longer pays a large neighbour's
+	// footprint. 4 → ~8 bound material arrays (4 sRGB + 4 linear).
+	MATERIAL_BUCKET_COUNT: 4,
+	// Packing stride: a map's stored index encodes bucketId * BUCKET_LAYER_STRIDE + layer.
+	// Also the per-bucket layer cap. Kept at the WebGPU portable maxTextureArrayLayers floor (256)
+	// so a consolidated bucket (which merges several map types of one size) stays portable.
+	BUCKET_LAYER_STRIDE: 256,
 };
 
+// Longest-edge size ladder for a given cap, ascending.
+// cap=4096, count=4 → [512, 1024, 2048, 4096].
+export function getTextureBucketSizes( maxTextureSize, count = TEXTURE_CONSTANTS.MATERIAL_BUCKET_COUNT ) {
+
+	const sizes = [];
+	for ( let i = count - 1; i >= 0; i -- ) {
+
+		sizes.push( Math.max( TEXTURE_CONSTANTS.MIN_TEXTURE_WIDTH, Math.round( maxTextureSize / Math.pow( 2, i ) ) ) );
+
+	}
+
+	return sizes;
+
+}
+
+// Bucket index for a texture, by its power-of-2 longest edge vs the cap's ladder.
+// Larger-than-cap maps land in the top bucket (downscaled to cap, as before).
+export function getTextureBucketId( width, height, maxTextureSize, count = TEXTURE_CONSTANTS.MATERIAL_BUCKET_COUNT ) {
+
+	const longest = Math.max( width || 1, height || 1 );
+	const pot = Math.pow( 2, Math.ceil( Math.log2( longest ) ) );
+	const sizes = getTextureBucketSizes( maxTextureSize, count );
+	for ( let i = 0; i < sizes.length; i ++ ) if ( pot <= sizes[ i ] ) return i;
+	return sizes.length - 1;
+
+}
+
+// Pack (bucketId, layer) into the single int slot a material map index occupies.
+export function packTextureIndex( bucketId, layer ) {
+
+	return bucketId * TEXTURE_CONSTANTS.BUCKET_LAYER_STRIDE + layer;
+
+}
+
 // Default texture matrix for materials
 export const DEFAULT_TEXTURE_MATRIX = [ 0, 0, 1, 1, 0, 0, 0, 1 ];
 

package/src/Processor/SceneProcessor.js

@@ -9,7 +9,8 @@ import { GeometryExtractor } from './GeometryExtractor.js';
 import { EmissiveTriangleBuilder } from './EmissiveTriangleBuilder.js';
 import { updateLoading } from '../Processor/utils.js';
 import { BuildTimer } from './BuildTimer.js';
-import { TRIANGLE_DATA_LAYOUT, TEXTURE_CONSTANTS } from '../EngineDefaults.js';
+import { SRGBColorSpace } from 'three';
+import { TRIANGLE_DATA_LAYOUT, TEXTURE_CONSTANTS, getTextureBucketId, packTextureIndex } from '../EngineDefaults.js';
 import { fetchAsWorker } from './Workers/fetchAsWorker.js';
 import BVH_WORKER_URL from './Workers/BVHWorker.js?worker&url';
 import BVH_REFIT_WORKER_URL from './Workers/BVHRefitWorker.js?worker&url';
@@ -79,14 +80,13 @@ export class SceneProcessor {
 		this._rebuildGeneration = 0; // Monotonic counter to discard stale background rebuilds
 		this._pendingRebuilds = new Map(); // meshIndex → worker
 
-		// Initialize texture references
-		this.albedoTextures = null;
-		this.normalTextures = null;
-		this.bumpTextures = null;
-		this.roughnessTextures = null;
-		this.metalnessTextures = null;
-		this.emissiveTextures = null;
-		this.displacementTextures = null;
+		// Initialize texture references.
+		// Material maps are packed into consolidated size-bucketed arrays (see _bucketTextures):
+		//   srgbBucketTextures[K]  — albedo + emissive  (SRGBColorSpace)
+		//   linearBucketTextures[K] — normal/bump/roughness/metalness/displacement
+		// A material's per-map index encodes (bucket, layer) via packTextureIndex.
+		this.srgbBucketTextures = null;
+		this.linearBucketTextures = null;
 		this.emissiveTriangleData = null;
 		this.emissiveTriangleCount = 0;
 		this.lightBVHNodeData = null;
@@ -762,40 +762,45 @@ export class SceneProcessor {
 
 		try {
 
-			// Material raw data for storage buffers (sync, ~1-5ms)
+			// Group the extractor's per-type arrays into consolidated colorSpace×size-bucket
+			// pools, and rewrite each material's per-map index to the packed (bucket, layer)
+			// form. Must run BEFORE createMaterialRawData (which reads mat.map etc.).
+			const { srgbLists, linearLists, remap } = this._bucketTextures();
+			this._remapMaterialTextureIndices( remap );
+
+			// Material raw data for storage buffers (sync, ~1-5ms) — now holds packed indices.
 			if ( this.materials?.length ) {
 
 				this.materialData = this.textureCreator.createMaterialRawData( this.materials );
 
 			}
 
-			// Material texture arrays → GPU DataArrayTextures
-			// All 7 map types are independent — process in parallel
-			const mapTypesList = [
-				{ data: this.maps, prop: 'albedoTextures' },
-				{ data: this.normalMaps, prop: 'normalTextures' },
-				{ data: this.bumpMaps, prop: 'bumpTextures' },
-				{ data: this.roughnessMaps, prop: 'roughnessTextures' },
-				{ data: this.metalnessMaps, prop: 'metalnessTextures' },
-				{ data: this.emissiveMaps, prop: 'emissiveTextures' },
-				{ data: this.displacementMaps, prop: 'displacementTextures' },
-			];
-
-			await Promise.all(
-				mapTypesList
-					.filter( ( { data } ) => data?.length > 0 )
-					.map( ( { data, prop } ) =>
-						this.textureCreator.createTexturesToDataTexture( data )
-							.then( result => {
-
-								this[ prop ] = result;
-
-							} )
-					)
-			);
+			// One DataArrayTexture per non-empty bucket. The sRGB pool (albedo + emissive — both
+			// authored in sRGB per glTF) carries SRGBColorSpace so the GPU decodes sRGB→linear
+			// before lighting; the linear pool (normal/roughness/metalness/bump/displacement —
+			// data textures) stays linear. Applied consistently across load AND rebuildMaterials
+			// (the prior model-load path omitted this, leaving albedo un-decoded / too bright).
+			const buildBucket = ( list, srgb ) => list.length === 0
+				? Promise.resolve( null )
+				: this.textureCreator.createTexturesToDataTexture( list ).then( tex => {
+
+					if ( tex && srgb ) tex.colorSpace = SRGBColorSpace;
+					return tex;
+
+				} );
+
+			const [ srgbTextures, linearTextures ] = await Promise.all( [
+				Promise.all( srgbLists.map( list => buildBucket( list, true ) ) ),
+				Promise.all( linearLists.map( list => buildBucket( list, false ) ) ),
+			] );
+
+			this.srgbBucketTextures = srgbTextures;
+			this.linearBucketTextures = linearTextures;
 
 			this._log( 'Material textures complete', {
 				materialData: !! this.materialData,
+				srgbBuckets: srgbTextures.map( t => ( t ? `${t.image.width}x${t.image.height}x${t.image.depth}` : '-' ) ).join( ',' ),
+				linearBuckets: linearTextures.map( t => ( t ? `${t.image.width}x${t.image.height}x${t.image.depth}` : '-' ) ).join( ',' ),
 			} );
 
 		} catch ( error ) {
@@ -807,6 +812,96 @@ export class SceneProcessor {
 
 	}
 
+	/**
+	 * Group the extractor's seven per-type texture arrays into two consolidated colorSpace
+	 * pools (sRGB: albedo+emissive; linear: normal/bump/roughness/metalness/displacement),
+	 * each split into MATERIAL_BUCKET_COUNT longest-edge size buckets. Textures are deduped
+	 * across types within a (pool, bucket) so a shared image (e.g. ORM) costs one layer.
+	 * @returns {{ srgbLists: Array<Array>, linearLists: Array<Array>, remap: Object }}
+	 *          bucket lists + per-type remap arrays (old per-type layer → packed bucket index).
+	 * @private
+	 */
+	_bucketTextures() {
+
+		const cap = this.config.maxTextureSize;
+		const K = TEXTURE_CONSTANTS.MATERIAL_BUCKET_COUNT;
+		const STRIDE = TEXTURE_CONSTANTS.BUCKET_LAYER_STRIDE;
+
+		const srgbLists = Array.from( { length: K }, () => [] );
+		const linearLists = Array.from( { length: K }, () => [] );
+		const srgbDedup = Array.from( { length: K }, () => new Map() );
+		const linearDedup = Array.from( { length: K }, () => new Map() );
+
+		// Persistent uuid → packed maps so runtime material edits (updateMaterial) can re-pack
+		// a texture's index against the CURRENT bucket layout instead of the stale per-type index.
+		this._srgbTexPacked = new Map();
+		this._linearTexPacked = new Map();
+
+		// Assign one texture to its (bucket, layer) within a pool; dedup by source uuid.
+		const assign = ( tex, lists, dedup, flat ) => {
+
+			if ( ! tex || ! tex.image ) return - 1;
+			const bucket = getTextureBucketId( tex.image.width, tex.image.height, cap, K );
+			const uuid = tex.source?.uuid ?? tex.uuid;
+			const seen = dedup[ bucket ].get( uuid );
+			if ( seen !== undefined ) return packTextureIndex( bucket, seen );
+			if ( lists[ bucket ].length >= STRIDE ) {
+
+				console.warn( `[SceneProcessor] Texture bucket ${bucket} full (${STRIDE}); dropping a map.` );
+				return - 1;
+
+			}
+
+			lists[ bucket ].push( tex );
+			const layer = lists[ bucket ].length - 1;
+			dedup[ bucket ].set( uuid, layer );
+			const packed = packTextureIndex( bucket, layer );
+			flat.set( uuid, packed );
+			return packed;
+
+		};
+
+		// Per-type arrays hold unique textures indexed by the layer the extractor assigned
+		// (= array position), so remap[type][oldLayer] = packed index.
+		const remapType = ( arr, lists, dedup, flat ) => ( arr || [] ).map( tex => assign( tex, lists, dedup, flat ) );
+
+		const remap = {
+			albedo: remapType( this.maps, srgbLists, srgbDedup, this._srgbTexPacked ),
+			emissive: remapType( this.emissiveMaps, srgbLists, srgbDedup, this._srgbTexPacked ),
+			normal: remapType( this.normalMaps, linearLists, linearDedup, this._linearTexPacked ),
+			bump: remapType( this.bumpMaps, linearLists, linearDedup, this._linearTexPacked ),
+			roughness: remapType( this.roughnessMaps, linearLists, linearDedup, this._linearTexPacked ),
+			metalness: remapType( this.metalnessMaps, linearLists, linearDedup, this._linearTexPacked ),
+			displacement: remapType( this.displacementMaps, linearLists, linearDedup, this._linearTexPacked ),
+		};
+
+		return { srgbLists, linearLists, remap };
+
+	}
+
+	/**
+	 * Rewrite each material's per-map index from the extractor's per-type layer to the
+	 * packed (bucket, layer) index. Idempotency is NOT guaranteed — call exactly once per
+	 * extraction (materials are freshly extracted on each process/rebuild).
+	 * @private
+	 */
+	_remapMaterialTextureIndices( remap ) {
+
+		const fix = ( v, table ) => ( v >= 0 && v < table.length ? table[ v ] : - 1 );
+		for ( const mat of this.materials ) {
+
+			mat.map = fix( mat.map, remap.albedo );
+			mat.emissiveMap = fix( mat.emissiveMap, remap.emissive );
+			mat.normalMap = fix( mat.normalMap, remap.normal );
+			mat.bumpMap = fix( mat.bumpMap, remap.bump );
+			mat.roughnessMap = fix( mat.roughnessMap, remap.roughness );
+			mat.metalnessMap = fix( mat.metalnessMap, remap.metalness );
+			mat.displacementMap = fix( mat.displacementMap, remap.displacement );
+
+		}
+
+	}
+
 	/**
 	 * Extract emissive triangles and build Light BVH.
 	 * MUST run after BVH reordering — emissive data stores triangle indices
@@ -905,27 +1000,42 @@ export class SceneProcessor {
      */
 	_disposeTextures() {
 
-		const textureProps = [
-			'albedoTextures', 'normalTextures', 'bumpTextures', 'roughnessTextures',
-			'metalnessTextures', 'emissiveTextures', 'displacementTextures'
-		];
+		this._disposeBucketTextures();
 
-		// Dispose each texture if it exists
-		textureProps.forEach( prop => {
+	}
 
-			if ( this[ prop ] ) {
+	/**
+	 * Dispose the consolidated bucket arrays (srgb/linear), each an Array<K> of
+	 * DataArrayTexture | null.
+	 * @private
+	 */
+	_disposeBucketTextures() {
 
-				if ( typeof this[ prop ].dispose === 'function' ) {
+		for ( const prop of [ 'srgbBucketTextures', 'linearBucketTextures' ] ) {
 
-					this[ prop ].dispose();
+			const arr = this[ prop ];
+			if ( ! arr ) continue;
+			for ( const tex of arr ) {
 
-				}
+				if ( tex && typeof tex.dispose === 'function' ) {
 
-				this[ prop ] = null;
+					try {
+
+						tex.dispose();
+
+					} catch ( error ) {
+
+						console.warn( `[SceneProcessor] Error disposing ${prop}:`, error );
+
+					}
+
+				}
 
 			}
 
-		} );
+			this[ prop ] = null;
+
+		}
 
 	}
 
@@ -969,34 +1079,9 @@ export class SceneProcessor {
 			this.displacementMaps = extractedData.displacementMaps;
 			this.sceneFeatures = extractedData.sceneFeatures; // Update material feature flags
 
-			// Create new material and texture data only
-			const params = {
-				materials: this.materials,
-				triangles: this.triangleData, // Reuse existing triangle data
-				maps: this.maps,
-				normalMaps: this.normalMaps,
-				bumpMaps: this.bumpMaps,
-				roughnessMaps: this.roughnessMaps,
-				metalnessMaps: this.metalnessMaps,
-				emissiveMaps: this.emissiveMaps,
-				displacementMaps: this.displacementMaps,
-				bvhRoot: this.bvhRoot // Reuse existing BVH
-			};
-
-			// Create only material and texture-related textures
-			const textures = await this.textureCreator.createMaterialTextures( params );
-
-			// Regenerate raw material data for storage buffers
-			this.materialData = this.textureCreator.createMaterialRawData( this.materials );
-
-			// Update texture references (keep triangle and BVH data unchanged)
-			this.albedoTextures = textures.albedoTexture;
-			this.normalTextures = textures.normalTexture;
-			this.bumpTextures = textures.bumpTexture;
-			this.roughnessTextures = textures.roughnessTexture;
-			this.metalnessTextures = textures.metalnessTexture;
-			this.emissiveTextures = textures.emissiveTexture;
-			this.displacementTextures = textures.displacementTexture;
+			// Bucket textures, remap material indices, regenerate raw material data, and
+			// build the consolidated bucket arrays — same path as the initial build.
+			await this._createMaterialTextures();
 
 			const duration = performance.now() - startTime;
 			this._log( `Material rebuild complete (${duration.toFixed( 2 )}ms)`, {
@@ -1026,37 +1111,7 @@ export class SceneProcessor {
      */
 	_disposeMaterialTextures() {
 
-		const materialTextureProps = [
-			'albedoTextures', 'normalTextures',
-			'bumpTextures', 'roughnessTextures', 'metalnessTextures', 'emissiveTextures',
-			'displacementTextures'
-		];
-
-		materialTextureProps.forEach( prop => {
-
-			if ( this[ prop ] ) {
-
-				try {
-
-					if ( typeof this[ prop ].dispose === 'function' ) {
-
-						this[ prop ].dispose();
-
-					}
-
-				} catch ( error ) {
-
-					console.warn( `[SceneProcessor] Error disposing ${prop}:`, error );
-
-				} finally {
-
-					this[ prop ] = null;
-
-				}
-
-			}
-
-		} );
+		this._disposeBucketTextures();
 
 		// Clear texture creator cache to prevent stale references
 		if ( this.textureCreator && this.textureCreator.textureCache ) {
@@ -1407,14 +1462,12 @@ export class SceneProcessor {
 		}
 
 		pathTracer.materialData.setMaterialTextures( {
-			albedoMaps: this.albedoTextures,
-			normalMaps: this.normalTextures,
-			bumpMaps: this.bumpTextures,
-			roughnessMaps: this.roughnessTextures,
-			metalnessMaps: this.metalnessTextures,
-			emissiveMaps: this.emissiveTextures,
-			displacementMaps: this.displacementTextures,
+			srgbBuckets: this.srgbBucketTextures,
+			linearBuckets: this.linearBucketTextures,
 		} );
+		// Hand the uuid→packed maps to materialData so runtime edits (updateMaterial) can
+		// re-pack a texture's index against this scene's bucket layout.
+		pathTracer.materialData.setTexturePackMaps?.( this._srgbTexPacked, this._linearTexPacked );
 
 		if ( this.emissiveTriangleData ) {
 

package/src/Processor/ShaderBuilder.js

@@ -9,7 +9,7 @@
 
 import { texture } from 'three/tsl';
 import { LinearFilter, DataArrayTexture } from 'three';
-import { setShadowAlbedoMaps, setAlphaShadowsUniform } from '../TSL/LightsDirect.js';
+import { setAlphaShadowsUniform } from '../TSL/LightsDirect.js';
 import { setGoboMapsTexture, setIESProfilesTexture } from '../TSL/LightsCore.js';
 
 export class ShaderBuilder {
@@ -30,7 +30,6 @@ export class ShaderBuilder {
 		const nodes = this._sceneTextureNodes;
 
 		const env = stage.environment;
-		const mat = stage.materialData;
 
 		if ( env.environmentTexture && nodes.envTex ) {
 
@@ -38,13 +37,8 @@ export class ShaderBuilder {
 
 		}
 
-		if ( mat.albedoMaps && nodes.albedoMapsTex ) nodes.albedoMapsTex.value = mat.albedoMaps;
-		if ( mat.normalMaps && nodes.normalMapsTex ) nodes.normalMapsTex.value = mat.normalMaps;
-		if ( mat.bumpMaps && nodes.bumpMapsTex ) nodes.bumpMapsTex.value = mat.bumpMaps;
-		if ( mat.metalnessMaps && nodes.metalnessMapsTex ) nodes.metalnessMapsTex.value = mat.metalnessMaps;
-		if ( mat.roughnessMaps && nodes.roughnessMapsTex ) nodes.roughnessMapsTex.value = mat.roughnessMaps;
-		if ( mat.emissiveMaps && nodes.emissiveMapsTex ) nodes.emissiveMapsTex.value = mat.emissiveMaps;
-		if ( mat.displacementMaps && nodes.displacementMapsTex ) nodes.displacementMapsTex.value = mat.displacementMaps;
+		// Material bucket arrays are owned by PathTracer's independent wavefront nodes
+		// (_refreshWfTextureNodes); nothing to swap here.
 		if ( stage.goboMaps && nodes.goboMapsTex ) nodes.goboMapsTex.value = stage.goboMaps;
 		if ( stage.iesProfiles && nodes.iesProfilesTex ) nodes.iesProfilesTex.value = stage.iesProfiles;
 
@@ -116,14 +110,9 @@ export class ShaderBuilder {
 
 		};
 
-		const mat = stage.materialData;
-		const albedoMapsTex = mat.albedoMaps ? texture( mat.albedoMaps ) : createArrayPlaceholder();
-		const normalMapsTex = mat.normalMaps ? texture( mat.normalMaps ) : createArrayPlaceholder();
-		const bumpMapsTex = mat.bumpMaps ? texture( mat.bumpMaps ) : createArrayPlaceholder();
-		const metalnessMapsTex = mat.metalnessMaps ? texture( mat.metalnessMaps ) : createArrayPlaceholder();
-		const roughnessMapsTex = mat.roughnessMaps ? texture( mat.roughnessMaps ) : createArrayPlaceholder();
-		const emissiveMapsTex = mat.emissiveMaps ? texture( mat.emissiveMaps ) : createArrayPlaceholder();
-		const displacementMapsTex = mat.displacementMaps ? texture( mat.displacementMaps ) : createArrayPlaceholder();
+		// Material map arrays (consolidated size buckets) are owned by PathTracer's
+		// independent wavefront nodes + setMaterialBucketTextures/setShadowAlbedoMaps —
+		// see PathTracer._buildWavefrontKernels. Nothing material-map related is bound here.
 
 		// Spot light gobo array — placeholder until GoboManager populates it.
 		const goboMapsTex = stage.goboMaps ? texture( stage.goboMaps ) : createArrayPlaceholder();
@@ -133,16 +122,9 @@ export class ShaderBuilder {
 		const iesProfilesTex = stage.iesProfiles ? texture( stage.iesProfiles ) : createArrayPlaceholder();
 		setIESProfilesTexture( iesProfilesTex );
 
-		// 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, lightBufferStorage,
 			envTex,
-			albedoMapsTex, normalMapsTex, bumpMapsTex,
-			metalnessMapsTex, roughnessMapsTex, emissiveMapsTex, displacementMapsTex,
 			goboMapsTex, iesProfilesTex,
 		};
 

package/src/Stages/NormalDepth.js

@@ -1,13 +1,13 @@
 import { Fn, vec3, vec4, float, int, uint, uvec2, uniform, normalize, mat3, storage, If,
-	texture, textureStore, workgroupId, localId } from 'three/tsl';
+	textureStore, workgroupId, localId } from 'three/tsl';
 import { RenderTarget, StorageTexture } from 'three/webgpu';
-import { HalfFloatType, RGBAFormat, NearestFilter, LinearFilter, DataArrayTexture, Matrix4, Box2, Vector2 } from 'three';
+import { HalfFloatType, RGBAFormat, NearestFilter, Matrix4, Box2, Vector2 } from 'three';
 import { RenderStage, StageExecutionMode } from '../Pipeline/RenderStage.js';
 import { MAX_STORAGE_TEXTURE_SIZE } from '../EngineDefaults.js';
 import { Ray, HitInfo, RayTracingMaterial, UVCache } from '../TSL/Struct.js';
 import { traverseBVH } from '../TSL/BVHTraversal.js';
 import { getMaterial } from '../TSL/Common.js';
-import { computeUVCache, processNormal, processBump } from '../TSL/TextureSampling.js';
+import { computeUVCache, processNormal, processBump, buildBucketTextureNodes, refreshBucketTextureNodes, setMaterialBucketTextures } from '../TSL/TextureSampling.js';
 
 /**
  * NormalDepth — primary-ray G-buffer for SVGF gates.
@@ -104,22 +104,10 @@ export class NormalDepth extends RenderStage {
 		this._computeNode = null;
 		this._computeBuilt = false;
 
-		// Normal/bump map array nodes — persistent placeholders, value swapped to
-		// the real DataArrayTextures on model load. processNormal/processBump
-		// runtime-guard on map indices, so the placeholder is never sampled.
-		this._normalMapsTex = texture( this._makePlaceholderArray() );
-		this._bumpMapsTex = texture( this._makePlaceholderArray() );
-
-	}
-
-	_makePlaceholderArray() {
-
-		const t = new DataArrayTexture( new Uint8Array( [ 128, 128, 255, 255 ] ), 1, 1, 1 );
-		t.minFilter = LinearFilter;
-		t.magFilter = LinearFilter;
-		t.generateMipmaps = false;
-		t.needsUpdate = true;
-		return t;
+		// Independent linear-pool bucket nodes for this pipeline (normal + bump live in the
+		// linear pool). Built lazily in _buildCompute from the path tracer's materialData;
+		// value-swapped on model load. processNormal/processBump runtime-guard on map indices.
+		this._linearBuckets = null;
 
 	}
 
@@ -185,10 +173,8 @@ export class NormalDepth extends RenderStage {
 
 		}
 
-		// In-place map swaps (model change) — graph closes over the node, only .value changes.
-		const md = pt.materialData;
-		if ( md?.normalMaps ) this._normalMapsTex.value = md.normalMaps;
-		if ( md?.bumpMaps ) this._bumpMapsTex.value = md.bumpMaps;
+		// In-place bucket swaps (model change) — graph closes over the nodes, only .value changes.
+		if ( this._linearBuckets ) refreshBucketTextureNodes( this._linearBuckets, pt.materialData?.linearBuckets );
 
 		this._lastTriAttr = pt.triangleStorageAttr || this._lastTriAttr;
 		this._lastBvhAttr = pt.bvhStorageAttr || this._lastBvhAttr;
@@ -203,8 +189,11 @@ export class NormalDepth extends RenderStage {
 		const triStorage = this._triStorageNode;
 		const bvhStorage = this._bvhStorageNode;
 		const matStorage = this._matStorageNode;
-		const normalMaps = this._normalMapsTex;
-		const bumpMaps = this._bumpMapsTex;
+		// Independent linear-pool bucket nodes for this pipeline (normal + bump). The sRGB pool
+		// is never sampled here, so it gets placeholders. Publish to the sampling module before
+		// the graph is built so processNormal/processBump bake in THESE (per-pipeline) nodes.
+		this._linearBuckets = buildBucketTextureNodes( this.pathTracer?.materialData?.linearBuckets );
+		setMaterialBucketTextures( buildBucketTextureNodes( null ), this._linearBuckets );
 		const camWorld = this.cameraWorldMatrix;
 		const camProjInv = this.cameraProjectionMatrixInverse;
 		const resW = this.resolutionWidth;
@@ -266,8 +255,8 @@ export class NormalDepth extends RenderStage {
 						getMaterial( hit.materialIndex, matStorage )
 					).toVar();
 					const uvCache = UVCache.wrap( computeUVCache( hit.uv, material ) ).toVar();
-					const mapped = processNormal( normalMaps, hit.normal, material, uvCache ).toVar();
-					shadingNormal.assign( processBump( bumpMaps, mapped, material, uvCache ) );
+					const mapped = processNormal( hit.normal, material, uvCache ).toVar();
+					shadingNormal.assign( processBump( mapped, material, uvCache ) );
 
 				} );
 

package/src/Stages/PathTracer.js

@@ -17,6 +17,8 @@ import { buildShadeKernel, SHADE_WG_SIZE } from '../TSL/ShadeKernel.js';
 import { buildCompactKernel, buildCompactSubgroupKernel, COMPACT_WG_SIZE } from '../TSL/CompactKernel.js';
 import { buildFinalWriteKernel, FINALWRITE_WG_SIZE } from '../TSL/FinalWriteKernel.js';
 import { buildDebugKernel, DEBUG_WG_SIZE } from '../TSL/DebugKernel.js';
+import { setMaterialBucketTextures, buildBucketTextureNodes, refreshBucketTextureNodes } from '../TSL/TextureSampling.js';
+import { setShadowAlbedoMaps } from '../TSL/LightsDirect.js';
 import {
 	buildResetGlobalHistKernel, buildGlobalHistKernel, buildGlobalPrefixKernel, buildGlobalScatterKernel,
 	SORT_GLOBAL_WG_SIZE, SORT_GLOBAL_MAX_BINS,
@@ -126,8 +128,8 @@ export class PathTracer extends PathTracerStage {
 			if ( ! m ) return null;
 			return [
 				m.materialStorageAttr,
-				m.albedoMaps, m.emissiveMaps, m.normalMaps, m.bumpMaps,
-				m.roughnessMaps, m.metalnessMaps, m.displacementMaps,
+				...( m.srgbBuckets || [] ).filter( Boolean ),
+				...( m.linearBuckets || [] ).filter( Boolean ),
 			];
 
 		} );
@@ -449,13 +451,8 @@ export class PathTracer extends PathTracerStage {
 
 		const mat = this.materialData;
 		if ( ! mat ) return;
-		if ( mat.albedoMaps && t.albedoMaps ) t.albedoMaps.value = mat.albedoMaps;
-		if ( mat.normalMaps && t.normalMaps ) t.normalMaps.value = mat.normalMaps;
-		if ( mat.bumpMaps && t.bumpMaps ) t.bumpMaps.value = mat.bumpMaps;
-		if ( mat.metalnessMaps && t.metalnessMaps ) t.metalnessMaps.value = mat.metalnessMaps;
-		if ( mat.roughnessMaps && t.roughnessMaps ) t.roughnessMaps.value = mat.roughnessMaps;
-		if ( mat.emissiveMaps && t.emissiveMaps ) t.emissiveMaps.value = mat.emissiveMaps;
-		if ( mat.displacementMaps && t.displacementMaps ) t.displacementMaps.value = mat.displacementMaps;
+		refreshBucketTextureNodes( t.srgbBuckets, mat.srgbBuckets );
+		refreshBucketTextureNodes( t.linearBuckets, mat.linearBuckets );
 
 	}
 
@@ -661,26 +658,21 @@ export class PathTracer extends PathTracerStage {
 		// Independent texture nodes (never compiled elsewhere) avoid Three.js TextureNode caching across pipelines; refreshed via _refreshWfTextureNodes.
 		const _mat = this.materialData;
 		const _env = this.environment;
-		const _placeholder = texNodes.albedoMapsTex;
-		const freshAlbedoMaps = _mat.albedoMaps ? texture( _mat.albedoMaps ) : _placeholder;
-		const freshNormalMaps = _mat.normalMaps ? texture( _mat.normalMaps ) : texNodes.normalMapsTex;
-		const freshBumpMaps = _mat.bumpMaps ? texture( _mat.bumpMaps ) : texNodes.bumpMapsTex;
-		const freshMetalnessMaps = _mat.metalnessMaps ? texture( _mat.metalnessMaps ) : texNodes.metalnessMapsTex;
-		const freshRoughnessMaps = _mat.roughnessMaps ? texture( _mat.roughnessMaps ) : texNodes.roughnessMapsTex;
-		const freshEmissiveMaps = _mat.emissiveMaps ? texture( _mat.emissiveMaps ) : texNodes.emissiveMapsTex;
-		const freshDisplacementMaps = _mat.displacementMaps ? texture( _mat.displacementMaps ) : texNodes.displacementMapsTex;
+		// Consolidated size-bucket nodes (K sRGB + K linear). Empty buckets get placeholders so
+		// every runtime branch references a valid node. Published to the sampling module before
+		// the Shade/Debug graphs are built so they bake in these (per-pipeline) nodes.
+		const freshSrgbBuckets = buildBucketTextureNodes( _mat.srgbBuckets );
+		const freshLinearBuckets = buildBucketTextureNodes( _mat.linearBuckets );
+		setMaterialBucketTextures( freshSrgbBuckets, freshLinearBuckets );
+		// Alpha-cutout shadow rays sample albedo (sRGB pool) — emitted into the shade graph now.
+		setShadowAlbedoMaps( freshSrgbBuckets );
 		const freshEnvTex = _env.environmentTexture ? texture( _env.environmentTexture ) : texNodes.envTex;
 
 		this._wfTexNodes = {
 			envTex: freshEnvTex,
 			envCDFTex: freshEnvCDF,
-			albedoMaps: freshAlbedoMaps,
-			normalMaps: freshNormalMaps,
-			bumpMaps: freshBumpMaps,
-			metalnessMaps: freshMetalnessMaps,
-			roughnessMaps: freshRoughnessMaps,
-			emissiveMaps: freshEmissiveMaps,
-			displacementMaps: freshDisplacementMaps,
+			srgbBuckets: freshSrgbBuckets,
+			linearBuckets: freshLinearBuckets,
 		};
 
 		// Material-coherence sort gate (experiment): only worthwhile above a few materials.
@@ -761,13 +753,6 @@ export class PathTracer extends PathTracerStage {
 			hitBufferRO: pb.hitBuffer.ro,
 			counters,
 			activeIndicesRO: this._sortMaterials ? qm.getSortedRO() : qm.getActiveReadRO(),
-			albedoMaps: freshAlbedoMaps,
-			normalMaps: freshNormalMaps,
-			bumpMaps: freshBumpMaps,
-			metalnessMaps: freshMetalnessMaps,
-			roughnessMaps: freshRoughnessMaps,
-			emissiveMaps: freshEmissiveMaps,
-			displacementMaps: freshDisplacementMaps,
 			envTexture: freshEnvTex,
 			environmentIntensity: this.environmentIntensity,
 			envMatrix: this.environmentMatrix,
@@ -926,12 +911,6 @@ export class PathTracer extends PathTracerStage {
 			enableEnvironmentLight: this.enableEnvironment,
 			visMode: this.visMode,
 			debugVisScale: this.debugVisScale,
-			albedoMaps: freshAlbedoMaps,
-			normalMaps: freshNormalMaps,
-			bumpMaps: freshBumpMaps,
-			metalnessMaps: freshMetalnessMaps,
-			roughnessMaps: freshRoughnessMaps,
-			emissiveMaps: freshEmissiveMaps,
 			frame: this.frame,
 		} );
 		this._kernelManager.register( 'debug',