rayzee 7.6.0 → 7.8.0

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 ),
 			];
 
 		} );
@@ -200,7 +202,6 @@ export class PathTracer extends PathTracerStage {
 		if ( this.shaderBuilder.prevColorTexNode ) {
 
 			this.shaderBuilder.prevColorTexNode.value = readTextures.color;
-			this.shaderBuilder.prevNormalDepthTexNode.value = readTextures.normalDepth;
 			this.shaderBuilder.prevAlbedoTexNode.value = readTextures.albedo;
 
 		}
@@ -450,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 );
 
 	}
 
@@ -570,7 +566,6 @@ export class PathTracer extends PathTracerStage {
 		this._wfMaxRayCount.value = maxRays;
 
 		const prevColor = this.shaderBuilder.prevColorTexNode;
-		const prevND = this.shaderBuilder.prevNormalDepthTexNode;
 		const prevAlbedo = this.shaderBuilder.prevAlbedoTexNode;
 		const writeTex = this.storageTextures.getWriteTextures();
 
@@ -663,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.
@@ -763,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,
@@ -885,7 +868,6 @@ export class PathTracer extends PathTracerStage {
 			cameraIsMoving: this.cameraIsMoving,
 			transparentBackground: this.transparentBackground,
 			prevAccumTexture: prevColor,
-			prevNormalDepthTexture: prevND,
 			prevAlbedoTexture: prevAlbedo,
 			renderWidth: this._wfRenderWidth,
 			renderHeight: this._wfRenderHeight,
@@ -929,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',

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/FinalWriteKernel.js

@@ -32,7 +32,7 @@ export function buildFinalWriteKernel( params ) {
 		resolution, frame,
 		enableAccumulation, hasPreviousAccumulated, accumulationAlpha, cameraIsMoving,
 		transparentBackground,
-		prevAccumTexture, prevNormalDepthTexture, prevAlbedoTexture,
+		prevAccumTexture, prevAlbedoTexture,
 		renderWidth, renderHeight,
 		visMode,
 		// Aux MRT (normalDepth + albedo) feeds only the denoiser/OIDN. Gated by a live uniform (1 = denoiser
@@ -80,7 +80,10 @@ export function buildFinalWriteKernel( params ) {
 				finalColor.assign( mix( prevAccumSample.xyz, sampleColor.xyz, accumulationAlpha ) );
 				If( auxOn, () => {
 
-					finalNormalDepth.assign( mix( texture( prevNormalDepthTexture, prevUV, 0 ), finalNormalDepth, accumulationAlpha ) );
+					// Albedo averages cleanly (it's a colour). The NORMAL must NOT: averaging jittered
+					// unit normals collapses toward the flat geometric mean (worse at distance), which made
+					// OIDN smooth bump detail away. Keep this frame's point-sampled normal — it varies with
+					// the bump, which is exactly what OIDN's edge-stop needs to preserve it.
 					finalAlbedo.assign( mix( texture( prevAlbedoTexture, prevUV, 0 ).xyz, finalAlbedo, accumulationAlpha ) );
 
 				} );

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 );
 
 	} );