rayzee 7.7.0 → 7.8.0

package/src/TSL/DebugKernel.js

@@ -30,7 +30,6 @@ export function buildDebugKernel( params ) {
 		bvhBuffer, triangleBuffer, materialBuffer,
 		envTexture, environmentMatrix, environmentIntensity, enableEnvironmentLight,
 		visMode, debugVisScale,
-		albedoMaps, normalMaps, bumpMaps, metalnessMaps, roughnessMaps, emissiveMaps,
 		frame,
 	} = params;
 
@@ -73,7 +72,6 @@ export function buildDebugKernel( params ) {
 					envTexture, environmentMatrix, environmentIntensity, enableEnvironmentLight,
 					visMode, debugVisScale,
 					pixelCoord, resolution,
-					albedoMaps, normalMaps, bumpMaps, metalnessMaps, roughnessMaps, emissiveMaps,
 					cameraProjectionMatrix, cameraViewMatrix,
 					frame,
 				) );

package/src/TSL/Debugger.js

@@ -71,9 +71,7 @@ export const TraceDebugMode = Fn( ( [
 	visMode, debugVisScale,
 	// Screen info
 	pixelCoord, resolution,
-	// Texture arrays (for MRT debug modes)
-	albedoMaps, normalMaps, bumpMaps,
-	metalnessMaps, roughnessMaps, emissiveMaps,
+	// Material textures are read from the module-level bucket nodes (setMaterialBucketTextures).
 	// Camera matrices (for depth debug mode)
 	cameraProjectionMatrix, cameraViewMatrix,
 	// Frame counter (for stochastic debug modes)
@@ -204,7 +202,6 @@ export const TraceDebugMode = Fn( ( [
 
 			// Sample all textures to get emissive
 			const matSamples = MaterialSamples.wrap( sampleAllMaterialTextures(
-				albedoMaps, normalMaps, bumpMaps, metalnessMaps, roughnessMaps, emissiveMaps,
 				material, hitInfo.uv, hitInfo.normal,
 			) ).toVar();
 
@@ -249,7 +246,6 @@ export const TraceDebugMode = Fn( ( [
 
 			// Get material-mapped normal (same as what's used in main shader)
 			const matSamples = MaterialSamples.wrap( sampleAllMaterialTextures(
-				albedoMaps, normalMaps, bumpMaps, metalnessMaps, roughnessMaps, emissiveMaps,
 				material, hitInfo.uv, hitInfo.normal,
 			) ).toVar();
 
@@ -296,7 +292,6 @@ export const TraceDebugMode = Fn( ( [
 			const material = RayTracingMaterial.wrap( getMaterial( hitInfo.materialIndex, materialBuffer ) ).toVar();
 
 			const matSamples = MaterialSamples.wrap( sampleAllMaterialTextures(
-				albedoMaps, normalMaps, bumpMaps, metalnessMaps, roughnessMaps, emissiveMaps,
 				material, hitInfo.uv, hitInfo.normal,
 			) ).toVar();
 
@@ -323,7 +318,6 @@ export const TraceDebugMode = Fn( ( [
 			// Get primary surface material
 			const material = RayTracingMaterial.wrap( getMaterial( hitInfo.materialIndex, materialBuffer ) ).toVar();
 			const matSamples = MaterialSamples.wrap( sampleAllMaterialTextures(
-				albedoMaps, normalMaps, bumpMaps, metalnessMaps, roughnessMaps, emissiveMaps,
 				material, hitInfo.uv, hitInfo.normal,
 			) ).toVar();
 
@@ -370,7 +364,6 @@ export const TraceDebugMode = Fn( ( [
 				// Bounce hit surface B — evaluate its contribution
 				const materialB = RayTracingMaterial.wrap( getMaterial( bounceHit.materialIndex, materialBuffer ) ).toVar();
 				const matSamplesB = MaterialSamples.wrap( sampleAllMaterialTextures(
-					albedoMaps, normalMaps, bumpMaps, metalnessMaps, roughnessMaps, emissiveMaps,
 					materialB, bounceHit.uv, bounceHit.normal,
 				) ).toVar();
 

package/src/TSL/Displacement.js

@@ -1,8 +1,8 @@
-import { Fn, float, vec2, int, If, Loop, abs, normalize, dot, max, textureSize } from 'three/tsl';
+import { Fn, float, vec2, int, If, Loop, abs, normalize, dot, max } from 'three/tsl';
 
 import { struct } from './patches.js';
 import { getDatafromStorageBuffer } from './Common.js';
-import { sampleDisplacementMap } from './TextureSampling.js';
+import { sampleDisplacementMap, bucketTexelSize, getLinearBucketTextures } from './TextureSampling.js';
 
 // Ray-displacement intersection configuration
 const MAX_MARCH_STEPS = 32;
@@ -32,7 +32,7 @@ export const DisplacementResult = struct( {
  * We find dt where h_ray(dt) = h_surf(dt).
  */
 export const refineDisplacedIntersection = Fn( ( [
-	ray, hitInfo, triangleBuffer, displacementMaps, material, bounceIndex
+	ray, hitInfo, triangleBuffer, material, bounceIndex
 ] ) => {
 
 	const resultHitPoint = hitInfo.hitPoint.toVar();
@@ -135,7 +135,7 @@ export const refineDisplacedIntersection = Fn( ( [
 
 					// Displaced surface height
 					const heightSample = sampleDisplacementMap(
-						displacementMaps, material.displacementMapIndex, marchUV, material.displacementTransform,
+						material.displacementMapIndex, marchUV, material.displacementTransform,
 					);
 					const surfaceHeight = heightSample.sub( 0.5 ).mul( scale );
 
@@ -167,7 +167,7 @@ export const refineDisplacedIntersection = Fn( ( [
 					const midUV = hitInfo.uv.add( dUV_dt.mul( midDt ) );
 					const midRayHeight = midDt.mul( dh_ray_dt );
 					const midSample = sampleDisplacementMap(
-						displacementMaps, material.displacementMapIndex, midUV, material.displacementTransform,
+						material.displacementMapIndex, midUV, material.displacementTransform,
 					);
 					const midSurfHeight = midSample.sub( 0.5 ).mul( scale );
 
@@ -189,19 +189,19 @@ export const refineDisplacedIntersection = Fn( ( [
 				const finalPoint = hitInfo.hitPoint.add( rayDir.mul( finalDt ) );
 
 				const finalHeight = sampleDisplacementMap(
-					displacementMaps, material.displacementMapIndex, finalUV, material.displacementTransform,
+					material.displacementMapIndex, finalUV, material.displacementTransform,
 				);
 				const displacedHeight = finalHeight.sub( 0.5 ).mul( scale );
 
 				// Compute displaced normal from height-field gradients using UV tangent vectors.
-				// Finite-difference step = one texel of the actual displacement-array dimensions.
-				const texel = vec2( 1.0 ).div( vec2( textureSize( displacementMaps ) ) ).toVar();
+				// Finite-difference step = one texel of the SELECTED bucket array's real dimensions.
+				const texel = bucketTexelSize( getLinearBucketTextures(), material.displacementMapIndex ).toVar();
 				const hC = finalHeight;
 				const hU = sampleDisplacementMap(
-					displacementMaps, material.displacementMapIndex, finalUV.add( vec2( texel.x, 0.0 ) ), material.displacementTransform,
+					material.displacementMapIndex, finalUV.add( vec2( texel.x, 0.0 ) ), material.displacementTransform,
 				);
 				const hV = sampleDisplacementMap(
-					displacementMaps, material.displacementMapIndex, finalUV.add( vec2( 0.0, texel.y ) ), material.displacementTransform,
+					material.displacementMapIndex, finalUV.add( vec2( 0.0, texel.y ) ), material.displacementTransform,
 				);
 
 				// Perturb normal using actual tangent/bitangent from UV parameterization

package/src/TSL/LightsDirect.js

@@ -22,28 +22,27 @@ import {
 	clamp,
 	smoothstep,
 	select,
-	texture,
 } from 'three/tsl';
 
 import { Ray, ShadowMaterial, HitInfo } from './Struct.js';
 import { REC709_LUMINANCE_COEFFICIENTS, getShadowMaterial, getDatafromStorageBuffer } from './Common.js';
 import { fresnelSchlickFloat, iorToFresnel0 } from './Fresnel.js';
 import { calculateBeerLawAbsorption } from './MaterialTransmission.js';
-import { getTransformedUV } from './TextureSampling.js';
+import { getTransformedUV, sampleBucket } from './TextureSampling.js';
 
 // Module-level state for alpha-cutout shadow testing.
-// Set by ShaderBuilder before graph construction.
+// Set by PathTracer before shade-graph construction.
 let _shadowAlbedoMaps = null;
 let _enableAlphaShadows = null;
 
 /**
- * Set the albedo texture array node for alpha-aware shadow rays.
- * Must be called before the shader graph is constructed.
- * @param {TextureNode} maps - TSL texture node for the albedo array
+ * Set the sRGB bucket texture node array for alpha-aware shadow rays (albedo alpha).
+ * Must be called before the shade graph is constructed.
+ * @param {Array} buckets - K sRGB bucket texture nodes
  */
-export function setShadowAlbedoMaps( maps ) {
+export function setShadowAlbedoMaps( buckets ) {
 
-	_shadowAlbedoMaps = maps;
+	_shadowAlbedoMaps = buckets;
 
 }
 
@@ -137,7 +136,7 @@ export const traceShadowRay = Fn( ( [
 					const uvData2 = getDatafromStorageBuffer( triangleBuffer, shadowHit.triangleIndex, int( 7 ), TRI_STRIDE );
 					const hitUV = uvData1.xy.mul( baryW ).add( uvData1.zw.mul( baryU ) ).add( uvData2.xy.mul( baryV ) );
 					const albedoUV = getTransformedUV( { uv: hitUV, transform: shadowMaterial.albedoTransform } );
-					texAlpha.assign( texture( _shadowAlbedoMaps, albedoUV ).depth( int( shadowMaterial.albedoMapIndex ) ).a );
+					texAlpha.assign( sampleBucket( _shadowAlbedoMaps, shadowMaterial.albedoMapIndex, albedoUV ).a );
 
 				} );
 

package/src/TSL/ShadeKernel.js

@@ -74,9 +74,6 @@ export function buildShadeKernel( params ) {
 		rayBufferRW, rngBufferRW, hitBufferRO, gBufferRW,
 		counters,
 		activeIndicesRO,
-		albedoMaps, normalMaps, bumpMaps,
-		metalnessMaps, roughnessMaps, emissiveMaps,
-		displacementMaps,
 		envTexture, environmentIntensity, envMatrix,
 		enableEnvironmentLight, useEnvMapIS,
 		groundProjectionEnabled, groundProjectionRadius, groundProjectionHeight, groundProjectionLevel,
@@ -533,7 +530,7 @@ export function buildShadeKernel( params ) {
 					boxTests: int( 0 ), triTests: int( 0 ),
 				} );
 				const dispResult = DisplacementResult.wrap( refineDisplacedIntersection(
-					dispRay, dispHit, triangleBuffer, displacementMaps, material, bounceIndex,
+					dispRay, dispHit, triangleBuffer, material, bounceIndex,
 				) ).toVar();
 				samplingUV.assign( dispResult.uv );
 				displacedNormal.assign( dispResult.normal );
@@ -543,8 +540,6 @@ export function buildShadeKernel( params ) {
 		);
 
 		const matSamples = MaterialSamples.wrap( sampleAllMaterialTextures(
-			albedoMaps, normalMaps, bumpMaps,
-			metalnessMaps, roughnessMaps, emissiveMaps,
 			material, samplingUV, N,
 		) ).toVar();
 

package/src/TSL/TextureSampling.js

@@ -1,9 +1,129 @@
 import { Fn, wgslFn, float, vec2, vec3, vec4, int, If, normalize, cross, abs, mix, clamp, texture, textureSize } from 'three/tsl';
+import { DataArrayTexture, LinearFilter } from 'three';
 
 import {
 	UVCache,
 	MaterialSamples,
 } from './Struct.js';
+import { TEXTURE_CONSTANTS } from '../EngineDefaults.js';
+
+// ================================================================================
+// CONSOLIDATED SIZE-BUCKETED MATERIAL TEXTURES
+// ================================================================================
+// Material maps are packed into two colorSpace pools (sRGB: albedo+emissive; linear:
+// normal/bump/roughness/metalness/displacement), each split into MATERIAL_BUCKET_COUNT
+// longest-edge size buckets so a small map no longer pays a large neighbour's footprint.
+// A map's stored index encodes (bucket, layer) as bucket * BUCKET_LAYER_STRIDE + layer.
+//
+// The bucket texture nodes live at module level (same pattern as gobo/IES/shadowAlbedo):
+// each stage sets them via setMaterialBucketTextures() right before building its graph,
+// so each pipeline bakes in its own fresh nodes (avoiding cross-pipeline TextureNode
+// caching, just like the per-type nodes did before).
+
+const _STRIDE = TEXTURE_CONSTANTS.BUCKET_LAYER_STRIDE;
+
+// Array<MATERIAL_BUCKET_COUNT> of texture nodes (never null — empty buckets get placeholders).
+let _srgbBuckets = null;
+let _linearBuckets = null;
+
+/**
+ * Set the bucket texture node arrays read by the sampling functions. Call before building
+ * any graph that samples material textures (Shade / NormalDepth / Debug kernels).
+ * @param {Array} srgb   sRGB pool nodes (albedo + emissive)
+ * @param {Array} linear linear pool nodes (normal/bump/roughness/metalness/displacement)
+ */
+export function setMaterialBucketTextures( srgb, linear ) {
+
+	_srgbBuckets = srgb;
+	_linearBuckets = linear;
+
+}
+
+// Run `fn(node, layer)` inside a runtime branch that selects the bucket node a packed
+// index points to. Emits one If/ElseIf arm per bucket; only the matching arm executes.
+// Caller must guard packedIndex >= 0.
+const withBucket = ( buckets, packedIndex, fn ) => {
+
+	const bucket = packedIndex.div( int( _STRIDE ) ).toVar();
+	const layer = packedIndex.sub( bucket.mul( int( _STRIDE ) ) ).toVar();
+	let chain = If( bucket.equal( int( 0 ) ), () => fn( buckets[ 0 ], layer ) );
+	for ( let i = 1; i < buckets.length; i ++ ) {
+
+		chain = chain.ElseIf( bucket.equal( int( i ) ), () => fn( buckets[ i ], layer ) );
+
+	}
+
+	return chain;
+
+};
+
+// Sample the bucket a packed index points to. Caller must guard packedIndex >= 0.
+export const sampleBucket = ( buckets, packedIndex, uv ) => {
+
+	const result = vec4( 0.0 ).toVar();
+	withBucket( buckets, packedIndex, ( node, layer ) => result.assign( texture( node, uv ).depth( layer ) ) );
+	return result;
+
+};
+
+// Per-axis texel size (1/dims) of the bucket a packed displacement/bump index points to,
+// for finite-difference derivative steps. Caller must guard packedIndex >= 0.
+export const bucketTexelSize = ( buckets, packedIndex ) => {
+
+	const ts = vec2( 1.0 ).toVar();
+	withBucket( buckets, packedIndex, node => ts.assign( vec2( 1.0 ).div( vec2( textureSize( node ) ) ) ) );
+	return ts;
+
+};
+
+// The linear-pool node set (displacement lives here) — for Displacement.js texel sizing.
+export function getLinearBucketTextures() {
+
+	return _linearBuckets;
+
+}
+
+// 1×1 white placeholder array so empty-bucket branches always reference a valid node.
+export function makeBucketPlaceholder() {
+
+	const t = new DataArrayTexture( new Uint8Array( [ 255, 255, 255, 255 ] ), 1, 1, 1 );
+	t.minFilter = LinearFilter;
+	t.magFilter = LinearFilter;
+	t.generateMipmaps = false;
+	t.needsUpdate = true;
+	return t;
+
+}
+
+// Build MATERIAL_BUCKET_COUNT texture nodes from a bucket array (DataArrayTexture | null per
+// bucket). Null buckets get a fresh placeholder. Each caller builds its OWN nodes so each
+// pipeline bakes in independent TextureNodes (no cross-pipeline caching).
+export function buildBucketTextureNodes( bucketArrays ) {
+
+	const K = TEXTURE_CONSTANTS.MATERIAL_BUCKET_COUNT;
+	const nodes = [];
+	for ( let i = 0; i < K; i ++ ) {
+
+		const arr = bucketArrays && bucketArrays[ i ];
+		nodes.push( texture( arr || makeBucketPlaceholder() ) );
+
+	}
+
+	return nodes;
+
+}
+
+// Update in-place the .value of bucket nodes from a fresh bucket array (model change).
+export function refreshBucketTextureNodes( nodes, bucketArrays ) {
+
+	if ( ! nodes || ! bucketArrays ) return;
+	for ( let i = 0; i < nodes.length; i ++ ) {
+
+		if ( bucketArrays[ i ] && nodes[ i ] ) nodes[ i ].value = bucketArrays[ i ];
+
+	}
+
+}
 
 // ================================================================================
 // FAST UTILITY FUNCTIONS
@@ -201,14 +321,14 @@ export const computeUVCache = Fn( ( [ baseUV, material ] ) => {
 // PROCESSING FUNCTIONS
 // ================================================================================
 
-export const processAlbedo = Fn( ( [ albedoMaps, material, uvCache ] ) => {
+export const processAlbedo = Fn( ( [ material, uvCache ] ) => {
 
 	const result = material.color.toVar();
 
 	If( material.albedoMapIndex.greaterThanEqual( int( 0 ) ), () => {
 
-		const albedoSample = texture( albedoMaps, uvCache.albedoUV ).depth( int( material.albedoMapIndex ) ).toVar();
-		// sRGB→linear handled by GPU hardware (texture.colorSpace = SRGBColorSpace → rgba8unorm-srgb format)
+		const albedoSample = sampleBucket( _srgbBuckets, material.albedoMapIndex, uvCache.albedoUV ).toVar();
+		// sRGB→linear handled by GPU hardware (sRGB bucket arrays carry SRGBColorSpace → rgba8unorm-srgb)
 		result.assign( vec4( material.color.rgb.mul( albedoSample.rgb ), material.color.a.mul( albedoSample.a ) ) );
 
 	} );
@@ -217,15 +337,15 @@ export const processAlbedo = Fn( ( [ albedoMaps, material, uvCache ] ) => {
 
 } );
 
-export const processMetalnessRoughness = Fn( ( [ metalnessMaps, roughnessMaps, material, uvCache ] ) => {
+export const processMetalnessRoughness = Fn( ( [ material, uvCache ] ) => {
 
 	const metalness = material.metalness.toVar();
 	const roughness = material.roughness.toVar();
 
 	If( material.metalnessMapIndex.greaterThanEqual( int( 0 ) ).and( material.metalnessMapIndex.equal( material.roughnessMapIndex ) ), () => {
 
-		// Same texture for both
-		const sample = texture( metalnessMaps, uvCache.metalnessUV ).depth( int( material.metalnessMapIndex ) );
+		// Same packed index → same bucket layer (e.g. ORM) → sample once.
+		const sample = sampleBucket( _linearBuckets, material.metalnessMapIndex, uvCache.metalnessUV );
 		metalness.assign( material.metalness.mul( sample.b ) );
 		roughness.assign( material.roughness.mul( sample.g ) );
 
@@ -233,14 +353,14 @@ export const processMetalnessRoughness = Fn( ( [ metalnessMaps, roughnessMaps, m
 
 		If( material.metalnessMapIndex.greaterThanEqual( int( 0 ) ), () => {
 
-			const metSample = texture( metalnessMaps, uvCache.metalnessUV ).depth( int( material.metalnessMapIndex ) );
+			const metSample = sampleBucket( _linearBuckets, material.metalnessMapIndex, uvCache.metalnessUV );
 			metalness.assign( material.metalness.mul( metSample.b ) );
 
 		} );
 
 		If( material.roughnessMapIndex.greaterThanEqual( int( 0 ) ), () => {
 
-			const rghSample = texture( roughnessMaps, uvCache.roughnessUV ).depth( int( material.roughnessMapIndex ) );
+			const rghSample = sampleBucket( _linearBuckets, material.roughnessMapIndex, uvCache.roughnessUV );
 			roughness.assign( material.roughness.mul( rghSample.g ) );
 
 		} );
@@ -251,13 +371,13 @@ export const processMetalnessRoughness = Fn( ( [ metalnessMaps, roughnessMaps, m
 
 } );
 
-export const processNormal = Fn( ( [ normalMaps, geometryNormal, material, uvCache ] ) => {
+export const processNormal = Fn( ( [ geometryNormal, material, uvCache ] ) => {
 
 	const result = geometryNormal.toVar();
 
 	If( material.normalMapIndex.greaterThanEqual( int( 0 ) ), () => {
 
-		const normalSample = texture( normalMaps, uvCache.normalUV ).depth( int( material.normalMapIndex ) );
+		const normalSample = sampleBucket( _linearBuckets, material.normalMapIndex, uvCache.normalUV );
 		const normalMap = normalSample.xyz.mul( 2.0 ).sub( 1.0 ).toVar();
 		normalMap.x.mulAssign( material.normalScale.x );
 		normalMap.y.assign( normalMap.y.negate().mul( material.normalScale.x ) );
@@ -277,21 +397,25 @@ export const processNormal = Fn( ( [ normalMaps, geometryNormal, material, uvCac
 
 } );
 
-export const processBump = Fn( ( [ bumpMaps, currentNormal, material, uvCache ] ) => {
+export const processBump = Fn( ( [ currentNormal, material, uvCache ] ) => {
 
 	const result = currentNormal.toVar();
 
 	If( material.bumpMapIndex.greaterThanEqual( int( 0 ) ).and( material.bumpScale.greaterThan( 0.0 ) ), () => {
 
-		// Texel size from the actual bump-array dimensions (finite-difference step).
-		const texelSize = vec2( 1.0 ).div( vec2( textureSize( bumpMaps ) ) ).toVar();
+		// Taps + texel size come from the SELECTED bucket node (its real dimensions), so the
+		// finite-difference step is correct per bucket — done inside one bucket-branch.
+		const bumpNormal = vec3( 0.0, 0.0, 1.0 ).toVar();
+		withBucket( _linearBuckets, material.bumpMapIndex, ( node, layer ) => {
 
-		const h_c = texture( bumpMaps, uvCache.bumpUV ).depth( int( material.bumpMapIndex ) ).r;
-		const h_u = texture( bumpMaps, vec2( uvCache.bumpUV.x.add( texelSize.x ), uvCache.bumpUV.y ) ).depth( int( material.bumpMapIndex ) ).r;
-		const h_v = texture( bumpMaps, vec2( uvCache.bumpUV.x, uvCache.bumpUV.y.add( texelSize.y ) ) ).depth( int( material.bumpMapIndex ) ).r;
+			const texelSize = vec2( 1.0 ).div( vec2( textureSize( node ) ) ).toVar();
+			const h_c = texture( node, uvCache.bumpUV ).depth( layer ).r;
+			const h_u = texture( node, vec2( uvCache.bumpUV.x.add( texelSize.x ), uvCache.bumpUV.y ) ).depth( layer ).r;
+			const h_v = texture( node, vec2( uvCache.bumpUV.x, uvCache.bumpUV.y.add( texelSize.y ) ) ).depth( layer ).r;
+			const gradient = vec2( h_u.sub( h_c ), h_v.sub( h_c ) ).mul( material.bumpScale );
+			bumpNormal.assign( normalize( vec3( gradient.x.negate(), gradient.y.negate(), 1.0 ) ) );
 
-		const gradient = vec2( h_u.sub( h_c ), h_v.sub( h_c ) ).mul( material.bumpScale );
-		const bumpNormal = normalize( vec3( gradient.x.negate(), gradient.y.negate(), 1.0 ) );
+		} );
 
 		// Build TBN matrix using current normal
 		const up = abs( currentNormal.z ).lessThan( 0.999 ).select( vec3( 0.0, 0.0, 1.0 ), vec3( 1.0, 0.0, 0.0 ) );
@@ -307,14 +431,14 @@ export const processBump = Fn( ( [ bumpMaps, currentNormal, material, uvCache ]
 
 } );
 
-export const processEmissive = Fn( ( [ emissiveMaps, material, uvCache ] ) => {
+export const processEmissive = Fn( ( [ material, uvCache ] ) => {
 
 	const emissionBase = material.emissive.mul( material.emissiveIntensity ).toVar();
 
 	If( material.emissiveMapIndex.greaterThanEqual( int( 0 ) ), () => {
 
-		const emissiveSample = texture( emissiveMaps, uvCache.emissiveUV ).depth( int( material.emissiveMapIndex ) ).toVar();
-		// sRGB→linear handled by GPU hardware (texture.colorSpace = SRGBColorSpace → rgba8unorm-srgb format)
+		const emissiveSample = sampleBucket( _srgbBuckets, material.emissiveMapIndex, uvCache.emissiveUV ).toVar();
+		// sRGB→linear handled by GPU hardware (sRGB bucket arrays carry SRGBColorSpace → rgba8unorm-srgb)
 		emissionBase.assign( emissionBase.mul( emissiveSample.rgb ) );
 
 	} );
@@ -327,10 +451,7 @@ export const processEmissive = Fn( ( [ emissiveMaps, material, uvCache ] ) => {
 // MAIN BATCHED SAMPLING FUNCTION
 // ================================================================================
 
-export const sampleAllMaterialTextures = Fn( ( [
-	albedoMaps, normalMaps, bumpMaps, metalnessMaps, roughnessMaps, emissiveMaps,
-	material, uv, geometryNormal
-] ) => {
+export const sampleAllMaterialTextures = Fn( ( [ material, uv, geometryNormal ] ) => {
 
 	const albedo = vec4( 0.0 ).toVar();
 	const emissive = vec3( 0.0 ).toVar();
@@ -351,17 +472,17 @@ export const sampleAllMaterialTextures = Fn( ( [
 		// Compute optimized UV cache with redundancy detection
 		const uvCache = UVCache.wrap( computeUVCache( uv, material ) ).toVar();
 
-		// Process samples
-		albedo.assign( processAlbedo( albedoMaps, material, uvCache ) );
+		// Process samples (bucket nodes read from module-level state)
+		albedo.assign( processAlbedo( material, uvCache ) );
 
-		const metalRough = processMetalnessRoughness( metalnessMaps, roughnessMaps, material, uvCache );
+		const metalRough = processMetalnessRoughness( material, uvCache );
 		metalness.assign( metalRough.x );
 		roughness.assign( metalRough.y );
 
-		const currentNormal = processNormal( normalMaps, geometryNormal, material, uvCache ).toVar();
-		normal.assign( processBump( bumpMaps, currentNormal, material, uvCache ) );
+		const currentNormal = processNormal( geometryNormal, material, uvCache ).toVar();
+		normal.assign( processBump( currentNormal, material, uvCache ) );
 
-		emissive.assign( processEmissive( emissiveMaps, material, uvCache ) );
+		emissive.assign( processEmissive( material, uvCache ) );
 
 	} );
 
@@ -369,15 +490,15 @@ export const sampleAllMaterialTextures = Fn( ( [
 
 } );
 
-// Sample displacement map at given UV coordinates
-export const sampleDisplacementMap = Fn( ( [ displacementMaps, displacementMapIndex, uv, transform ] ) => {
+// Sample displacement map (linear pool) at given UV coordinates.
+export const sampleDisplacementMap = Fn( ( [ displacementMapIndex, uv, transform ] ) => {
 
 	const result = float( 0.0 ).toVar();
 
 	If( displacementMapIndex.greaterThanEqual( int( 0 ) ), () => {
 
 		const transformedUV = getTransformedUV( { uv, transform } );
-		result.assign( texture( displacementMaps, transformedUV ).depth( int( displacementMapIndex ) ).r );
+		result.assign( sampleBucket( _linearBuckets, displacementMapIndex, transformedUV ).r );
 
 	} );
 

package/src/managers/MaterialDataManager.js

@@ -34,14 +34,18 @@ export class MaterialDataManager {
 		this.materialStorageNode = null;
 		this.materialCount = 0;
 
-		// Material texture arrays
-		this.albedoMaps = null;
-		this.emissiveMaps = null;
-		this.normalMaps = null;
-		this.bumpMaps = null;
-		this.roughnessMaps = null;
-		this.metalnessMaps = null;
-		this.displacementMaps = null;
+		// Consolidated size-bucketed material texture arrays (see SceneProcessor._bucketTextures):
+		//   srgbBuckets[K]  — albedo + emissive  (SRGBColorSpace)
+		//   linearBuckets[K] — normal/bump/roughness/metalness/displacement
+		// Each entry is a DataArrayTexture | null (null = empty bucket).
+		this.srgbBuckets = null;
+		this.linearBuckets = null;
+
+		// uuid → packed (bucket,layer) index maps for the current scene, handed over by the
+		// SceneProcessor that built the buckets. Let runtime material edits (updateMaterial)
+		// re-pack a texture's index against the current bucket layout.
+		this._srgbTexPacked = null;
+		this._linearTexPacked = null;
 
 		// Compiled features cache (for change detection)
 		this.compiledFeatures = null;
@@ -112,45 +116,60 @@ export class MaterialDataManager {
 	 */
 	setMaterialTextures( textures ) {
 
-		if ( textures.albedoMaps ) this.albedoMaps = textures.albedoMaps;
-		if ( textures.emissiveMaps ) this.emissiveMaps = textures.emissiveMaps;
-		if ( textures.normalMaps ) this.normalMaps = textures.normalMaps;
-		if ( textures.bumpMaps ) this.bumpMaps = textures.bumpMaps;
-		if ( textures.roughnessMaps ) this.roughnessMaps = textures.roughnessMaps;
-		if ( textures.metalnessMaps ) this.metalnessMaps = textures.metalnessMaps;
-		if ( textures.displacementMaps ) this.displacementMaps = textures.displacementMaps;
+		if ( textures.srgbBuckets ) this.srgbBuckets = textures.srgbBuckets;
+		if ( textures.linearBuckets ) this.linearBuckets = textures.linearBuckets;
 
 	}
 
 	/**
-	 * Load texture arrays from sdfs.
+	 * Receive the scene's uuid→packed texture-index maps (from the SceneProcessor that bucketed).
+	 * @param {Map|null} srgb
+	 * @param {Map|null} linear
+	 */
+	setTexturePackMaps( srgb, linear ) {
+
+		this._srgbTexPacked = srgb || null;
+		this._linearTexPacked = linear || null;
+
+	}
+
+	/**
+	 * Packed (bucket, layer) index for a Three.js texture against the current bucket layout,
+	 * or -1 if it isn't bucketed (a genuinely new texture → needs rebuildMaterials).
+	 * @param {import('three').Texture|null} texture
+	 * @param {boolean} isSrgb - true for albedo/emissive pool, false for the linear pool
+	 * @returns {number}
+	 */
+	getPackedTextureIndex( texture, isSrgb ) {
+
+		if ( ! texture ) return - 1;
+		const uuid = texture.source?.uuid ?? texture.uuid;
+		const map = isSrgb ? this._srgbTexPacked : this._linearTexPacked;
+		const packed = map?.get( uuid );
+		return packed === undefined ? - 1 : packed;
+
+	}
+
+	/**
+	 * Load consolidated bucket arrays + pack maps from the SceneProcessor.
 	 */
 	loadTexturesFromSdfs() {
 
-		this.albedoMaps = this.sdfs.albedoTextures;
-		this.emissiveMaps = this.sdfs.emissiveTextures;
-		this.normalMaps = this.sdfs.normalTextures;
-		this.bumpMaps = this.sdfs.bumpTextures;
-		this.roughnessMaps = this.sdfs.roughnessTextures;
-		this.metalnessMaps = this.sdfs.metalnessTextures;
-		this.displacementMaps = this.sdfs.displacementTextures;
+		this.srgbBuckets = this.sdfs.srgbBucketTextures;
+		this.linearBuckets = this.sdfs.linearBucketTextures;
+		this.setTexturePackMaps( this.sdfs._srgbTexPacked, this.sdfs._linearTexPacked );
 
 	}
 
 	/**
-	 * Get all texture arrays.
-	 * @returns {Object}
+	 * Get the consolidated bucket arrays.
+	 * @returns {{ srgbBuckets: Array, linearBuckets: Array }}
 	 */
 	getTextureArrays() {
 
 		return {
-			albedoMaps: this.albedoMaps,
-			emissiveMaps: this.emissiveMaps,
-			normalMaps: this.normalMaps,
-			bumpMaps: this.bumpMaps,
-			roughnessMaps: this.roughnessMaps,
-			metalnessMaps: this.metalnessMaps,
-			displacementMaps: this.displacementMaps,
+			srgbBuckets: this.srgbBuckets,
+			linearBuckets: this.linearBuckets,
 		};
 
 	}
@@ -550,6 +569,22 @@ export class MaterialDataManager {
 	updateMaterial( materialIndex, material ) {
 
 		const completeMaterialData = this.sdfs.geometryExtractor.createMaterialObject( material );
+
+		// createMaterialObject returns stale per-type indices; re-pack each map to the packed
+		// (bucket, layer) index for the CURRENT bucket layout. -1 for a texture not yet bucketed
+		// (a genuinely new map → the caller must rebuildMaterials to add it to a bucket array).
+		if ( this._srgbTexPacked || this._linearTexPacked ) {
+
+			completeMaterialData.map = this.getPackedTextureIndex( material.map, true );
+			completeMaterialData.emissiveMap = this.getPackedTextureIndex( material.emissiveMap, true );
+			completeMaterialData.normalMap = this.getPackedTextureIndex( material.normalMap, false );
+			completeMaterialData.bumpMap = this.getPackedTextureIndex( material.bumpMap, false );
+			completeMaterialData.roughnessMap = this.getPackedTextureIndex( material.roughnessMap, false );
+			completeMaterialData.metalnessMap = this.getPackedTextureIndex( material.metalnessMap, false );
+			completeMaterialData.displacementMap = this.getPackedTextureIndex( material.displacementMap, false );
+
+		}
+
 		this.updateMaterialDataFromObject( materialIndex, completeMaterialData );
 
 	}
@@ -813,13 +848,10 @@ export class MaterialDataManager {
 		this.materialStorageAttr = null;
 		this.materialStorageNode = null;
 		this.materialCount = 0;
-		this.albedoMaps = null;
-		this.emissiveMaps = null;
-		this.normalMaps = null;
-		this.bumpMaps = null;
-		this.roughnessMaps = null;
-		this.metalnessMaps = null;
-		this.displacementMaps = null;
+		this.srgbBuckets = null;
+		this.linearBuckets = null;
+		this._srgbTexPacked = null;
+		this._linearTexPacked = null;
 		this.compiledFeatures = null;
 
 	}