rayzee 7.7.0 → 7.9.0

package/src/Stages/NormalDepth.js

@@ -1,18 +1,19 @@
 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.
  *
- * RGB = geometric world normal · 0.5 + 0.5, A = linear ray distance (sky=1e6).
+ * RGB = geometric world normal · 0.5 + 0.5, A = linear ray distance (sky=65504, the
+ * max HalfFloat value — a finite sentinel so miss−miss depth diffs stay 0, not Inf−Inf=NaN).
  * Geometric (not shading) normals because shading normals carry sub-pixel
  * jitter that breaks the temporal gate's same-pixel-across-frames comparison.
  * The path tracer's MRT already carries shading normals for OIDN; this stage
@@ -104,22 +105,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 +174,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 +190,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;
@@ -248,7 +238,7 @@ export class NormalDepth extends RenderStage {
 
 				const result = hit.didHit.select(
 					vec4( encodedNormal, depth ),
-					vec4( 0.0, 0.0, 0.0, float( 1e6 ) )
+					vec4( 0.0, 0.0, 0.0, float( 65504.0 ) )
 				);
 
 				textureStore(
@@ -266,14 +256,14 @@ 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 ) );
 
 				} );
 
 				const shadingResult = hit.didHit.select(
 					vec4( shadingNormal.mul( 0.5 ).add( 0.5 ), depth ),
-					vec4( 0.0, 0.0, 0.0, float( 1e6 ) )
+					vec4( 0.0, 0.0, 0.0, float( 65504.0 ) )
 				);
 
 				textureStore(

package/src/Stages/PathTracer.js

@@ -7,7 +7,7 @@
 import { uniform, texture, storage } from 'three/tsl';
 import { StorageInstancedBufferAttribute } from 'three/webgpu';
 import { PathTracerStage } from './PathTracerStage.js';
-import { PackedRayBuffer, GBUFFER_STRIDE } from '../Processor/PackedRayBuffer.js';
+import { PackedRayBuffer, GBUFFER_STRIDE, freeStorageAttribute } from '../Processor/PackedRayBuffer.js';
 import { QueueManager, COUNTER } from '../Processor/QueueManager.js';
 import { VRAMTracker } from '../Processor/VRAMTracker.js';
 import { KernelManager } from '../Processor/KernelManager.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 );
 
 	}
 
@@ -527,7 +524,7 @@ export class PathTracer extends PathTracerStage {
 
 		if ( ! this._packedBuffers ) {
 
-			this._packedBuffers = new PackedRayBuffer( maxRays );
+			this._packedBuffers = new PackedRayBuffer( maxRays, this.renderer );
 
 		} else {
 
@@ -541,13 +538,14 @@ export class PathTracer extends PathTracerStage {
 		// per-pixel, written by Generate/Shade bounce-0 and read only by FinalWrite.
 		// 1.25× margin (same as the per-ray buffers) so it survives the in-place-resize range.
 		const gBufferVec4s = PackedRayBuffer.requiredCapacity( maxRays ) * GBUFFER_STRIDE;
+		freeStorageAttribute( this.renderer, this._gBufferAttr ); // free the outgoing G-buffer on capacity growth
 		this._gBufferAttr = new StorageInstancedBufferAttribute( new Uint32Array( gBufferVec4s * 4 ), 4 );
 		const gBufferRW = storage( this._gBufferAttr, 'uvec4' );
 		const gBufferRO = storage( this._gBufferAttr, 'uvec4' ).toReadOnly();
 
 		if ( ! this._queueManager ) {
 
-			this._queueManager = new QueueManager( this._packedBuffers.capacity );
+			this._queueManager = new QueueManager( this._packedBuffers.capacity, this.renderer );
 
 		} else {
 
@@ -661,26 +659,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 +754,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 +912,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/GenerateKernel.js

@@ -58,7 +58,11 @@ export function buildGenerateKernel( params ) {
 			const baseSeed = getDecorrelatedSeed( { pixelCoord, rayIndex: int( 0 ), frame } ).toVar();
 			const seed = pcgHash( { state: baseSeed } ).toVar();
 
-			const stratifiedJitter = getStratifiedSample( pixelCoord, int( 0 ), int( 1 ), seed, resolution, frame ).toVar();
+			// Sample index 1 (not 0) so the AA sub-pixel jitter draws a DIFFERENT STBN cell
+			// than the first-bounce BSDF sample (ShadeKernel uses sampleIndex 0). Every bounce
+			// samples at index 0, so index 1 is collision-free — this decorrelates the sub-pixel
+			// position from the first scatter direction (they were reading the identical cell).
+			const stratifiedJitter = getStratifiedSample( pixelCoord, int( 1 ), int( 1 ), seed, resolution, frame ).toVar();
 
 			const jitterScale = vec2( 2.0 ).div( resolution );
 			const jitter = stratifiedJitter.sub( 0.5 ).mul( jitterScale );

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

@@ -290,6 +290,9 @@ export const calculateIndirectLighting = Fn( ( [
 		const sampleDir = vec3( 0.0 ).toVar();
 		const samplePdf = float( 0.0 ).toVar();
 		const sampleBrdfValue = vec3( 0.0 ).toVar();
+		// Transmission lobe uses this weight instead of a reflection-BRDF eval, which is
+		// invalid for the below-surface refraction direction.
+		const transColorWeight = vec3( 1.0 ).toVar();
 
 		// Execute selected strategy (chained If/ElseIf/Else for exclusive branches)
 		// Environment removed — handled via deterministic NEE in direct lighting
@@ -312,13 +315,16 @@ export const calculateIndirectLighting = Fn( ( [
 
 			// Strategy 3: Transmission
 			const entering = dot( V, N ).greaterThan( 0.0 );
-			// pathWavelength=0 — MIS evaluation reads only direction/PDF, no spectral tint
 			const mtResult = MicrofacetTransmissionResult.wrap( sampleMicrofacetTransmission(
 				V, N, material.ior, material.roughness, entering, material.dispersion, sampleRand, rngState, float( 0.0 )
 			).toVar() );
 			sampleDir.assign( mtResult.direction );
 			samplePdf.assign( mtResult.pdf );
-			sampleBrdfValue.assign( evaluateMaterialResponse( V, sampleDir, N, material ) );
+			// evaluateMaterialResponse is reflection-only and returns a non-physical value for
+			// the below-surface refraction direction (its dots are floored to 0.001). Carry the
+			// sampler's spectral tint and apply an energy-consistent transmission throughput
+			// below (mirrors handleTransmission's material.color × colorWeight convention).
+			transColorWeight.assign( mtResult.colorWeight );
 
 		} ).Else( () => {
 
@@ -329,10 +335,7 @@ export const calculateIndirectLighting = Fn( ( [
 
 		} );
 
-		// For transmission directions (below surface), use |cos| instead of max(cos, 0)
-		const rawNoL = dot( N, sampleDir ).toVar();
-		const NoL = max( rawNoL, 0.0 ).toVar();
-		const absNoL = abs( rawNoL );
+		const NoL = max( dot( N, sampleDir ), 0.0 ).toVar();
 
 		// Calculate combined PDF for MIS (material strategies only)
 		const combinedPdf = float( 0.0 ).toVar();
@@ -380,11 +383,14 @@ export const calculateIndirectLighting = Fn( ( [
 		// MIS weight calculation
 		const misWeight = samplePdf.div( combinedPdf ).toVar();
 
-		// Throughput calculation: use |cos| for transmission, max(cos,0) for reflection strategies
-		const cosineWeight = select( selectedStrategy.equal( int( 3 ) ), absNoL, NoL );
+		// Reflection lobes: f·NoL·mis/pdf. Transmission lobe: the sampler's energy-consistent
+		// weight (material tint × dispersion colorWeight × mis) — the reflection BRDF value is
+		// invalid below the surface, so it is not used for transmission.
+		const reflThroughput = sampleBrdfValue.mul( NoL ).mul( misWeight ).div( samplePdf );
+		const transThroughput = material.color.xyz.mul( transColorWeight ).mul( misWeight );
 
 		r_direction.assign( sampleDir );
-		r_throughput.assign( sampleBrdfValue.mul( cosineWeight ).mul( misWeight ).div( samplePdf ) );
+		r_throughput.assign( select( selectedStrategy.equal( int( 3 ) ), transThroughput, reflThroughput ) );
 		r_misWeight.assign( misWeight );
 		r_pdf.assign( samplePdf );
 		r_combinedPdf.assign( combinedPdf );

package/src/TSL/LightsSampling.js

@@ -360,7 +360,6 @@ export const sampleLightWithImportance = Fn( ( [
 	If( totalLights.greaterThan( int( 0 ) ), () => {
 
 		const totalWeight = float( 0.0 ).toVar();
-		const lightIndex = int( 0 ).toVar();
 
 		// Reservoir state: winning light's type/index/importance.
 		const selectedType = int( - 1 ).toVar(); // 0=dir, 1=area, 2=point, 3=spot
@@ -375,7 +374,7 @@ export const sampleLightWithImportance = Fn( ( [
 
 			Loop( { start: int( 0 ), end: numDirectionalLights, type: 'int', condition: '<' }, ( { i } ) => {
 
-				If( lightIndex.lessThan( int( 16 ) ), () => {
+				If( i.lessThan( int( 16 ) ), () => {
 
 					const light = DirectionalLight.wrap( getDirectionalLight( directionalLightsBuffer, i ) );
 					const importance = calculateDirectionalLightImportance( light, normal, material, bounceIndex ).toVar();
@@ -389,7 +388,6 @@ export const sampleLightWithImportance = Fn( ( [
 						selectedImportance.assign( importance );
 
 					} );
-					lightIndex.addAssign( 1 );
 
 				} );
 
@@ -401,7 +399,7 @@ export const sampleLightWithImportance = Fn( ( [
 
 			Loop( { start: int( 0 ), end: numAreaLights, type: 'int', condition: '<' }, ( { i } ) => {
 
-				If( lightIndex.lessThan( int( 16 ) ), () => {
+				If( i.lessThan( int( 16 ) ), () => {
 
 					const light = AreaLight.wrap( getAreaLight( areaLightsBuffer, i ) );
 					const importance = select( light.intensity.greaterThan( 0.0 ), estimateLightImportance( light, rayOrigin, normal, material ), float( 0.0 ) ).toVar();
@@ -415,7 +413,6 @@ export const sampleLightWithImportance = Fn( ( [
 						selectedImportance.assign( importance );
 
 					} );
-					lightIndex.addAssign( 1 );
 
 				} );
 
@@ -427,7 +424,7 @@ export const sampleLightWithImportance = Fn( ( [
 
 			Loop( { start: int( 0 ), end: numPointLights, type: 'int', condition: '<' }, ( { i } ) => {
 
-				If( lightIndex.lessThan( int( 16 ) ), () => {
+				If( i.lessThan( int( 16 ) ), () => {
 
 					const light = PointLight.wrap( getPointLight( pointLightsBuffer, i ) );
 					const importance = calculatePointLightImportance( light, rayOrigin, normal, material ).toVar();
@@ -441,7 +438,6 @@ export const sampleLightWithImportance = Fn( ( [
 						selectedImportance.assign( importance );
 
 					} );
-					lightIndex.addAssign( 1 );
 
 				} );
 
@@ -453,7 +449,7 @@ export const sampleLightWithImportance = Fn( ( [
 
 			Loop( { start: int( 0 ), end: numSpotLights, type: 'int', condition: '<' }, ( { i } ) => {
 
-				If( lightIndex.lessThan( int( 16 ) ), () => {
+				If( i.lessThan( int( 16 ) ), () => {
 
 					const light = SpotLight.wrap( getSpotLight( spotLightsBuffer, i ) );
 					const importance = calculateSpotLightImportance( light, rayOrigin, normal, material ).toVar();
@@ -467,7 +463,6 @@ export const sampleLightWithImportance = Fn( ( [
 						selectedImportance.assign( importance );
 
 					} );
-					lightIndex.addAssign( 1 );
 
 				} );
 
@@ -762,7 +757,7 @@ export const calculateMaterialPDF = Fn( ( [ viewDir, lightDir, normal, material
 } );
 
 // Total light-selection weight at a shading point, replicating the NEE reservoir's
-// importance accumulation (same per-type importance fns, same 16-light cap + order).
+// importance accumulation (same per-type importance fns, same per-type 16-light cap + order).
 // Used to reconstruct the exact NEE selection pdf for MIS on the BSDF-hit path —
 // the analogue of Cycles' light_tree_pdf re-walk. Without it, the BSDF-hit MIS
 // partner assumes uniform 1/N selection, which disagrees with the importance-
@@ -776,17 +771,15 @@ export const computeTotalLightImportance = Fn( ( [
 ] ) => {
 
 	const totalWeight = float( 0.0 ).toVar();
-	const lightIndex = int( 0 ).toVar();
 
 	If( numDirectionalLights.greaterThan( int( 0 ) ), () => {
 
 		Loop( { start: int( 0 ), end: numDirectionalLights, type: 'int', condition: '<' }, ( { i } ) => {
 
-			If( lightIndex.lessThan( int( 16 ) ), () => {
+			If( i.lessThan( int( 16 ) ), () => {
 
 				const light = DirectionalLight.wrap( getDirectionalLight( directionalLightsBuffer, i ) );
 				totalWeight.addAssign( calculateDirectionalLightImportance( light, normal, material, bounceIndex ) );
-				lightIndex.addAssign( 1 );
 
 			} );
 
@@ -798,11 +791,10 @@ export const computeTotalLightImportance = Fn( ( [
 
 		Loop( { start: int( 0 ), end: numAreaLights, type: 'int', condition: '<' }, ( { i } ) => {
 
-			If( lightIndex.lessThan( int( 16 ) ), () => {
+			If( i.lessThan( int( 16 ) ), () => {
 
 				const light = AreaLight.wrap( getAreaLight( areaLightsBuffer, i ) );
 				totalWeight.addAssign( select( light.intensity.greaterThan( 0.0 ), estimateLightImportance( light, rayOrigin, normal, material ), float( 0.0 ) ) );
-				lightIndex.addAssign( 1 );
 
 			} );
 
@@ -814,11 +806,10 @@ export const computeTotalLightImportance = Fn( ( [
 
 		Loop( { start: int( 0 ), end: numPointLights, type: 'int', condition: '<' }, ( { i } ) => {
 
-			If( lightIndex.lessThan( int( 16 ) ), () => {
+			If( i.lessThan( int( 16 ) ), () => {
 
 				const light = PointLight.wrap( getPointLight( pointLightsBuffer, i ) );
 				totalWeight.addAssign( calculatePointLightImportance( light, rayOrigin, normal, material ) );
-				lightIndex.addAssign( 1 );
 
 			} );
 
@@ -830,11 +821,10 @@ export const computeTotalLightImportance = Fn( ( [
 
 		Loop( { start: int( 0 ), end: numSpotLights, type: 'int', condition: '<' }, ( { i } ) => {
 
-			If( lightIndex.lessThan( int( 16 ) ), () => {
+			If( i.lessThan( int( 16 ) ), () => {
 
 				const light = SpotLight.wrap( getSpotLight( spotLightsBuffer, i ) );
 				totalWeight.addAssign( calculateSpotLightImportance( light, rayOrigin, normal, material ) );
-				lightIndex.addAssign( 1 );
 
 			} );
 

package/src/TSL/Random.js

@@ -187,7 +187,17 @@ const computeSTBNAtlasCoord = ( pixelCoords, sampleIndex, dimensionIndex, frame
 export const sampleSTBN2D = ( pixelCoords, sampleIndex, dimensionPairIndex, frame ) => {
 
 	const coord = computeSTBNAtlasCoord( pixelCoords, sampleIndex, dimensionPairIndex, frame );
-	return stbnVec2TextureNode.load( coord ).xy;
+	const raw = stbnVec2TextureNode.load( coord ).xy;
+
+	// The atlas has only 64 temporal slices, so frame N and N+64 read the same slice: the
+	// sample repeats and accumulation stops improving past 64 frames. Decorrelate across
+	// 64-frame cycles with a Cranley-Patterson rotation (toroidal shift) by an R2 offset
+	// keyed on the cycle index (frame >> 6). The offset is uniform per cycle, preserving
+	// spatial and within-window temporal blue noise; cycle 0's offset is 0, so frames
+	// 0-63 stay bit-identical. A toroidal shift of uniform samples stays uniform (unbiased).
+	const cycle = float( uint( frame ).shiftRight( uint( 6 ) ) );
+	const rotation = fract( vec2( R2_A1, R2_A2 ).mul( cycle ) );
+	return fract( raw.add( rotation ) );
 
 };