rayzee 7.5.0 → 7.6.0

package/package.json

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

package/src/EngineDefaults.js

@@ -10,6 +10,11 @@ export const ENGINE_DEFAULTS = {
 	canvasWidth: 512,
 	canvasHeight: 512,
 
+	// Max material-texture dimension (longest edge) used when processing a scene's
+	// textures into GPU arrays. Larger = sharper textures but ~quadratic VRAM. Clamped
+	// to TEXTURE_CONSTANTS.MAX_TEXTURE_SIZE (hardware ceiling). Applied at scene load.
+	maxTextureSize: 4096,
+
 	toneMapping: 4,
 	exposure: 1,
 	saturation: 1.2,
@@ -88,6 +93,10 @@ export const ENGINE_DEFAULTS = {
 	performanceModeAdaptive: 'medium',
 
 	fireflyThreshold: 3.0,
+	// Wavefront material-coherence sort: global counting-sort of entering rays by material before
+	// Shade (material-pure workgroups), under dynamic dispatch. Measured −8% at 1024²/8b. Gated on
+	// material count > 8; the histogram bin count is sized per-scene to the material count.
+	wavefrontSortMaterials: true,
 	renderLimitMode: 'frames',
 	renderTimeLimit: 30,
 	renderMode: 0,
@@ -479,7 +488,11 @@ export const TEXTURE_CONSTANTS = {
 	BUFFER_POOL_SIZE: 20,
 	CANVAS_POOL_SIZE: 12,
 	CACHE_SIZE_LIMIT: 50,
-	MAX_TEXTURE_SIZE: 8192
+	// Hardware ceiling for a single texture-array dimension (WebGPU maxTextureDimension2D
+	// guaranteed minimum). The configurable maxTextureSize setting is clamped to this.
+	MAX_TEXTURE_SIZE: 8192,
+	// Default cap applied when no maxTextureSize is supplied (engine standalone use).
+	DEFAULT_MAX_TEXTURE_SIZE: 4096
 };
 
 // Default texture matrix for materials

package/src/PathTracerApp.js

@@ -103,6 +103,8 @@ export class PathTracerApp extends EventDispatcher {
 		this.assetLoader = null;
 		this._sdf = null;
 		this._animRefitInFlight = false;
+		// Max material-texture dimension (longest edge); applied on each scene build.
+		this._maxTextureSize = DEFAULT_STATE.maxTextureSize;
 
 		// ── Pipeline & stages ──
 		this.pipeline = null;
@@ -667,6 +669,47 @@ export class PathTracerApp extends EventDispatcher {
 
 	}
 
+	/**
+	 * Set the max material-texture dimension (longest edge) used when processing a
+	 * scene's textures into GPU arrays. Clamped to the hardware ceiling. Larger =
+	 * sharper textures, ~quadratic VRAM. By default reprocesses the current scene so
+	 * the change is visible without a manual reload.
+	 * @param {number} size
+	 * @param {Object} [opts]
+	 * @param {boolean} [opts.reprocess=true] - Rebuild the current scene now.
+	 * @returns {Promise<void>}
+	 */
+	async setMaxTextureSize( size, { reprocess = true } = {} ) {
+
+		const prev = this._maxTextureSize;
+		const clamped = this._sdf?.setMaxTextureSize( size );
+		this._maxTextureSize = clamped ?? size;
+		if ( typeof this.stages?.pathTracer?.sdfs?.setMaxTextureSize === 'function' ) {
+
+			this.stages.pathTracer.sdfs.setMaxTextureSize( this._maxTextureSize );
+
+		}
+
+		// Reprocess the loaded scene so the new cap takes effect immediately.
+		if ( reprocess && this._maxTextureSize !== prev && this._sdf?.triangleData && ! this._loadingInProgress ) {
+
+			this._loadingInProgress = true;
+			try {
+
+				await this.loadSceneData();
+				this.reset();
+				this.dispatchEvent( { type: 'TexturesReprocessed', maxTextureSize: this._maxTextureSize } );
+
+			} finally {
+
+				this._loadingInProgress = false;
+
+			}
+
+		}
+
+	}
+
 	/** Shared pipeline: load asset → sync controls → build BVH → reset → dispatch events */
 	async _loadWithSceneRebuild( loadFn, eventPayload ) {
 
@@ -730,6 +773,7 @@ export class PathTracerApp extends EventDispatcher {
 
 		// Build BVH
 		timer.start( 'BVH build (SceneProcessor)' );
+		this._sdf.setMaxTextureSize( this._maxTextureSize );
 		await this._sdf.buildBVH( this.meshScene );
 		timer.end( 'BVH build (SceneProcessor)' );
 

package/src/Processor/KernelManager.js

@@ -12,8 +12,7 @@
 const WORKGROUP_SIZES = {
 	generate: [ 16, 16, 1 ], // 2D screen-space
 	extend: [ 256, 1, 1 ], // 1D ray-parallel
-	sort: [ 256, 1, 1 ], // 1D ray-parallel
-	shade: [ 256, 1, 1 ], // 1D ray-parallel (sorted)
+	shade: [ 256, 1, 1 ], // 1D ray-parallel (material-sorted when sort enabled)
 	connect: [ 256, 1, 1 ], // 1D shadow-ray-parallel
 	accumulate: [ 256, 1, 1 ], // 1D shadow-ray-parallel
 	compact: [ 256, 1, 1 ], // 1D ray-parallel

package/src/Processor/QueueManager.js

@@ -40,6 +40,9 @@ export class QueueManager {
 		// A/B alternate: one read by current bounce, other written by compaction
 		this.activeIndices = null;
 		this.activeIndicesRO = null;
+		this.sortedIndices = null;
+		this.sortedIndicesRO = null;
+		this.sortGlobalHistogram = null;
 		this.pingPong = 0; // 0 = read A / write B, 1 = read B / write A
 
 		if ( maxRays > 0 ) {
@@ -83,11 +86,23 @@ export class QueueManager {
 			b: storage( attrB, 'uint' ).toReadOnly(),
 		};
 
+		// Material-sort output: a material-reordered permutation of the active index
+		// list, written by the global material sort and read by Shade in place of activeIndices.
+		const sortAttr = new StorageInstancedBufferAttribute( new Uint32Array( capacity ), 1 );
+		this._sortAttr = sortAttr;
+		this.sortedIndices = storage( sortAttr, 'uint' );
+		this.sortedIndicesRO = storage( sortAttr, 'uint' ).toReadOnly();
+
+		// Global material-sort histogram, sized to the bin cap (SORT_GLOBAL_MAX_BINS=256); kernels use
+		// only the first `bins` entries (= per-scene material count). 256 × 4B = 1KB.
+		this._sortGlobalHistAttr = new StorageInstancedBufferAttribute( new Uint32Array( 256 ), 1 );
+		this.sortGlobalHistogram = storage( this._sortGlobalHistAttr, 'uint' ).toAtomic();
+
 		this.pingPong = 0;
 
 		const totalBytes = (
 			COUNTER.COUNT * 4 +
-			capacity * 4 * 2
+			capacity * 4 * 3
 		);
 
 		console.log(
@@ -131,6 +146,24 @@ export class QueueManager {
 
 	}
 
+	getSortedRW() {
+
+		return this.sortedIndices;
+
+	}
+
+	getSortedRO() {
+
+		return this.sortedIndicesRO;
+
+	}
+
+	getSortGlobalHistogram() {
+
+		return this.sortGlobalHistogram;
+
+	}
+
 	// raw attribute for `renderer.getArrayBufferAsync(...)` readback
 	getCountersAttribute() {
 
@@ -167,6 +200,9 @@ export class QueueManager {
 		this.counters = null;
 		this.activeIndices = null;
 		this.activeIndicesRO = null;
+		this.sortedIndices = null;
+		this.sortedIndicesRO = null;
+		this.sortGlobalHistogram = null;
 		this.capacity = 0;
 
 	}

package/src/Processor/SceneProcessor.js

@@ -9,7 +9,7 @@ import { GeometryExtractor } from './GeometryExtractor.js';
 import { EmissiveTriangleBuilder } from './EmissiveTriangleBuilder.js';
 import { updateLoading } from '../Processor/utils.js';
 import { BuildTimer } from './BuildTimer.js';
-import { TRIANGLE_DATA_LAYOUT } from '../EngineDefaults.js';
+import { TRIANGLE_DATA_LAYOUT, TEXTURE_CONSTANTS } from '../EngineDefaults.js';
 import { fetchAsWorker } from './Workers/fetchAsWorker.js';
 import BVH_WORKER_URL from './Workers/BVHWorker.js?worker&url';
 import BVH_REFIT_WORKER_URL from './Workers/BVHRefitWorker.js?worker&url';
@@ -41,6 +41,7 @@ export class SceneProcessor {
 			verbose: false,
 			useFloat32Array: true,
 			textureQuality: 'adaptive', // 'low', 'medium', 'high', 'adaptive'
+			maxTextureSize: TEXTURE_CONSTANTS.DEFAULT_MAX_TEXTURE_SIZE, // longest-edge cap for material textures
 			enableTextureCache: true,
 			maxConcurrentTextureTasks: Math.min( navigator.hardwareConcurrency || 4, 6 ),
 			// Treelet optimization configuration
@@ -109,6 +110,17 @@ export class SceneProcessor {
 
 	}
 
+	/**
+	 * Set the max material-texture dimension applied on the next scene build.
+	 * @param {number} size - Longest-edge cap (clamped to the hardware ceiling).
+	 */
+	setMaxTextureSize( size ) {
+
+		this.config.maxTextureSize = size;
+		return this.textureCreator?.setMaxTextureSize( size );
+
+	}
+
 	/**
      * Initialize processing components with configuration
      * @private
@@ -131,7 +143,7 @@ export class SceneProcessor {
 		} );
 
 		// Create and configure texture creator
-		this.textureCreator = new TextureCreator();
+		this.textureCreator = new TextureCreator( { maxTextureSize: this.config.maxTextureSize } );
 		// The optimized TextureCreator will auto-detect capabilities and select optimal methods
 
 		// Create emissive triangle builder for direct lighting

package/src/Processor/TextureCreator.js

@@ -446,6 +446,11 @@ export class TextureCreator {
 		this.maxConcurrentWorkers = TEXTURE_CONSTANTS.MAX_CONCURRENT_WORKERS;
 		this.activeWorkers = 0;
 
+		// Longest-edge cap for material-texture arrays. Clamped to the hardware ceiling.
+		this.maxTextureSize = this._clampTextureSize(
+			options.maxTextureSize ?? TEXTURE_CONSTANTS.DEFAULT_MAX_TEXTURE_SIZE
+		);
+
 		// Initialize high-performance components
 		this.canvasPool = new CanvasPool();
 		this.bufferPool = new SmartBufferPool( {
@@ -460,6 +465,25 @@ export class TextureCreator {
 
 	}
 
+	_clampTextureSize( size ) {
+
+		const n = Math.floor( Number( size ) || TEXTURE_CONSTANTS.DEFAULT_MAX_TEXTURE_SIZE );
+		return Math.max( TEXTURE_CONSTANTS.MIN_TEXTURE_WIDTH, Math.min( n, TEXTURE_CONSTANTS.MAX_TEXTURE_SIZE ) );
+
+	}
+
+	setMaxTextureSize( size ) {
+
+		const clamped = this._clampTextureSize( size );
+		if ( clamped === this.maxTextureSize ) return clamped; // unchanged — keep cache
+		this.maxTextureSize = clamped;
+		// Cache keys don't encode size — drop cached arrays so a new cap takes effect.
+		this.textureCache?.dispose();
+		this.textureCache = new TextureCache();
+		return this.maxTextureSize;
+
+	}
+
 	detectCapabilities() {
 
 		return {
@@ -656,7 +680,7 @@ export class TextureCreator {
 
 				worker.postMessage( {
 					textures: texturesData,
-					maxTextureSize: TEXTURE_CONSTANTS.MAX_TEXTURE_SIZE,
+					maxTextureSize: this.maxTextureSize,
 					method: 'direct-transfer'
 				}, transferables );
 
@@ -1256,7 +1280,8 @@ export class TextureCreator {
 		maxWidth = Math.pow( 2, Math.ceil( Math.log2( maxWidth ) ) );
 		maxHeight = Math.pow( 2, Math.ceil( Math.log2( maxHeight ) ) );
 
-		while ( maxWidth >= TEXTURE_CONSTANTS.MAX_TEXTURE_SIZE / 2 || maxHeight >= TEXTURE_CONSTANTS.MAX_TEXTURE_SIZE / 2 ) {
+		// Halve only while a dimension exceeds the cap (preserves native res up to the cap).
+		while ( maxWidth > this.maxTextureSize || maxHeight > this.maxTextureSize ) {
 
 			maxWidth = Math.max( 1, Math.floor( maxWidth / 2 ) );
 			maxHeight = Math.max( 1, Math.floor( maxHeight / 2 ) );

package/src/Processor/Workers/TexturesWorker.js

@@ -3,7 +3,7 @@ let canvas, ctx;
 // Memory limits and chunking configuration
 const MEMORY_LIMITS = {
 	MAX_BYTES_PER_TEXTURE: 256 * 1024 * 1024, // 256MB per texture array
-	MAX_TEXTURE_DIMENSION: 4096, // Maximum dimension for a single texture
+	MAX_TEXTURE_DIMENSION: 8192, // Hardware ceiling (WebGPU maxTextureDimension2D guaranteed min); the per-scene maxTextureSize setting is the actual knob
 	CHUNK_SIZE: 8, // Optimized: Process textures in chunks of 8 for better memory locality
 	ADAPTIVE_CHUNK_SIZE: true, // Enable adaptive chunk sizing based on texture dimensions
 	MEMORY_SAFETY_FACTOR: 0.8 // Use only 80% of estimated available memory
@@ -627,8 +627,8 @@ function calculateOptimalDimensions( textures, maxTextureSize ) {
 	maxWidth = Math.min( maxWidth, maxTextureSize, MEMORY_LIMITS.MAX_TEXTURE_DIMENSION );
 	maxHeight = Math.min( maxHeight, maxTextureSize, MEMORY_LIMITS.MAX_TEXTURE_DIMENSION );
 
-	// Additional safety check
-	while ( maxWidth >= maxTextureSize / 2 || maxHeight >= maxTextureSize / 2 ) {
+	// Halve only while a dimension exceeds the cap (preserves native res up to the cap).
+	while ( maxWidth > maxTextureSize || maxHeight > maxTextureSize ) {
 
 		maxWidth = Math.max( 1, Math.floor( maxWidth / 2 ) );
 		maxHeight = Math.max( 1, Math.floor( maxHeight / 2 ) );

package/src/Stages/PathTracer.js

@@ -17,6 +17,11 @@ 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 {
+	buildResetGlobalHistKernel, buildGlobalHistKernel, buildGlobalPrefixKernel, buildGlobalScatterKernel,
+	SORT_GLOBAL_WG_SIZE, SORT_GLOBAL_MAX_BINS,
+} from '../TSL/SortGlobalKernels.js';
+import { ENGINE_DEFAULTS } from '../EngineDefaults.js';
 import {
 	Fn, uint, atomicStore, atomicLoad, instanceIndex, If, Return,
 } from 'three/tsl';
@@ -43,6 +48,11 @@ export class PathTracer extends PathTracerStage {
 		// CPU sizes per-bounce kernels from last frame's survivor curve; kernels bound on ENTERING_COUNT so over-sizing is safe. (indirect dispatch not viable — three.js doesn't sync compute-written indirect buffers across submissions)
 		this._useDynamicDispatch = true;
 
+		// Global material-coherence sort: set per-build from ENGINE_DEFAULTS + material count (>8).
+		// Reorders entering rays into material-pure workgroups before Shade; runs under dynamic dispatch
+		// (compact reads the unsorted active list, so the survivor set is unchanged). Measured −8% at 1024²/8b.
+		this._sortMaterials = false;
+
 		// Flag-gated off: perf-neutral vs atomic-append and adds a 'subgroups' feature dependency.
 		this._useSubgroupCompact = false;
 
@@ -90,7 +100,7 @@ export class PathTracer extends PathTracerStage {
 			if ( ! qm ) return null;
 			return [
 				qm._countersAttr, qm._bounceCountsAttr,
-				qm._attrA, qm._attrB,
+				qm._attrA, qm._attrB, qm._sortAttr,
 			];
 
 		} );
@@ -250,6 +260,7 @@ export class PathTracer extends PathTracerStage {
 			this._wfCurrentBounce.value = bounce;
 
 			// Functional-compaction path (dynamic dispatch): copyback keeps the read buffer dense, kernels sized to live survivors. Dynamic-off uses the full path (ENTERING=maxRays, identity buffer).
+			// Material sort is compatible: shade reads sortedIndices while compact still reads the UNSORTED active list (getActiveReadRO), so the survivor set is unchanged.
 			const useFunctionalCompaction = this._useDynamicDispatch;
 			if ( useFunctionalCompaction ) {
 
@@ -281,6 +292,8 @@ export class PathTracer extends PathTracerStage {
 				const wg = [ Math.ceil( sized / 256 ), 1, 1 ];
 				km.setDispatchCount( 'extend', wg );
 				km.setDispatchCount( 'shade', wg );
+				km.setDispatchCount( 'globalHist', wg );
+				km.setDispatchCount( 'globalScatter', wg );
 				km.setDispatchCount( 'compact', wg );
 				km.setDispatchCount( 'compactCopyback', wg );
 
@@ -291,11 +304,23 @@ export class PathTracer extends PathTracerStage {
 				km.setDispatchCount( 'extend', full );
 				km.setDispatchCount( 'shade', full );
 				km.setDispatchCount( 'compact', full );
+				km.setDispatchCount( 'globalHist', full );
+				km.setDispatchCount( 'globalScatter', full );
 
 			}
 
 			// Extend/Shade kept separate (not fused): a fused kernel's register pressure drops occupancy more than fusion saves.
 			km.dispatch( 'extend' );
+			if ( this._sortMaterials ) {
+
+				// Global material counting sort (material-pure workgroups): reset, histogram, prefix-sum, scatter.
+				km.dispatch( 'resetGlobalHist' );
+				km.dispatch( 'globalHist' );
+				km.dispatch( 'globalPrefix' );
+				km.dispatch( 'globalScatter' );
+
+			}
+
 			km.dispatch( 'shade' );
 
 			km.dispatch( 'resetActiveCounter' );
@@ -660,6 +685,10 @@ export class PathTracer extends PathTracerStage {
 			displacementMaps: freshDisplacementMaps,
 		};
 
+		// Material-coherence sort gate (experiment): only worthwhile above a few materials.
+		this._sortMaterials = ( ENGINE_DEFAULTS.wavefrontSortMaterials ?? false )
+			&& ( this.materialData?.materialCount ?? 0 ) > 8;
+
 		const extFn = buildExtendKernel( {
 			bvhBuffer: freshBvh,
 			triangleBuffer: freshTri,
@@ -677,6 +706,50 @@ export class PathTracer extends PathTracerStage {
 			)
 		);
 
+		// Material-coherence sort: reorder the entering-ray indices by material between
+		// Extend and Shade. Histogram is workgroup-shared (patches.js §4); Shade reads the output.
+		if ( this._sortMaterials ) {
+
+			const sgHist = qm.getSortGlobalHistogram();
+			const sortBins = Math.min( SORT_GLOBAL_MAX_BINS, this.materialData?.materialCount ?? SORT_GLOBAL_MAX_BINS );
+			this._kernelManager.register( 'resetGlobalHist',
+				buildResetGlobalHistKernel( { sortGlobalHistogram: sgHist, bins: sortBins } )().compute(
+					[ 1, 1, 1 ], [ SORT_GLOBAL_WG_SIZE, 1, 1 ]
+				)
+			);
+			this._kernelManager.register( 'globalHist',
+				buildGlobalHistKernel( {
+					hitBufferRO: pb.hitBuffer.ro,
+					activeIndicesReadRO: qm.getActiveReadRO(),
+					sortGlobalHistogram: sgHist,
+					counters,
+					bins: sortBins,
+				} )().compute(
+					[ Math.ceil( maxRays / SORT_GLOBAL_WG_SIZE ), 1, 1 ],
+					[ SORT_GLOBAL_WG_SIZE, 1, 1 ]
+				)
+			);
+			this._kernelManager.register( 'globalPrefix',
+				buildGlobalPrefixKernel( { sortGlobalHistogram: sgHist, bins: sortBins } )().compute(
+					[ 1, 1, 1 ], [ 1, 1, 1 ]
+				)
+			);
+			this._kernelManager.register( 'globalScatter',
+				buildGlobalScatterKernel( {
+					hitBufferRO: pb.hitBuffer.ro,
+					activeIndicesReadRO: qm.getActiveReadRO(),
+					sortedIndicesRW: qm.getSortedRW(),
+					sortGlobalHistogram: sgHist,
+					counters,
+					bins: sortBins,
+				} )().compute(
+					[ Math.ceil( maxRays / SORT_GLOBAL_WG_SIZE ), 1, 1 ],
+					[ SORT_GLOBAL_WG_SIZE, 1, 1 ]
+				)
+			);
+
+		}
+
 		const shadeFn = buildShadeKernel( {
 			gBufferRW,
 			envCompensationDelta: this.envCompensationDelta,
@@ -689,7 +762,7 @@ export class PathTracer extends PathTracerStage {
 			rngBufferRW: pb.rngBuffer.rw,
 			hitBufferRO: pb.hitBuffer.ro,
 			counters,
-			activeIndicesRO: qm.getActiveReadRO(),
+			activeIndicesRO: this._sortMaterials ? qm.getSortedRO() : qm.getActiveReadRO(),
 			albedoMaps: freshAlbedoMaps,
 			normalMaps: freshNormalMaps,
 			bumpMaps: freshBumpMaps,

package/src/TSL/Displacement.js

@@ -1,4 +1,4 @@
-import { Fn, float, vec2, int, If, Loop, abs, normalize, dot, max } from 'three/tsl';
+import { Fn, float, vec2, int, If, Loop, abs, normalize, dot, max, textureSize } from 'three/tsl';
 
 import { struct } from './patches.js';
 import { getDatafromStorageBuffer } from './Common.js';
@@ -8,7 +8,6 @@ import { sampleDisplacementMap } from './TextureSampling.js';
 const MAX_MARCH_STEPS = 32;
 const MIN_MARCH_STEPS = 16;
 const BINARY_STEPS = 5;
-const NORMAL_TEXEL_SIZE = 1.0 / 1024.0;
 const TRI_STRIDE = 8;
 
 export const DisplacementResult = struct( {
@@ -194,14 +193,15 @@ export const refineDisplacedIntersection = Fn( ( [
 				);
 				const displacedHeight = finalHeight.sub( 0.5 ).mul( scale );
 
-				// Compute displaced normal from height-field gradients using UV tangent vectors
-				const h = float( NORMAL_TEXEL_SIZE );
+				// 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();
 				const hC = finalHeight;
 				const hU = sampleDisplacementMap(
-					displacementMaps, material.displacementMapIndex, finalUV.add( vec2( h, 0.0 ) ), material.displacementTransform,
+					displacementMaps, material.displacementMapIndex, finalUV.add( vec2( texel.x, 0.0 ) ), material.displacementTransform,
 				);
 				const hV = sampleDisplacementMap(
-					displacementMaps, material.displacementMapIndex, finalUV.add( vec2( 0.0, h ) ), material.displacementTransform,
+					displacementMaps, material.displacementMapIndex, finalUV.add( vec2( 0.0, texel.y ) ), material.displacementTransform,
 				);
 
 				// Perturb normal using actual tangent/bitangent from UV parameterization

package/src/TSL/SortGlobalKernels.js

@@ -0,0 +1,135 @@
+/**
+ * SortGlobalKernels.js — GLOBAL material counting sort of the entering rays.
+ *
+ * Unlike a per-workgroup sort (locally coherent only), this orders rays by material
+ * ACROSS ALL workgroups, so each material's rays occupy one contiguous region of sortedIndices.
+ * For materials with many rays that means whole material-PURE workgroups/subgroups → real shading
+ * coherence. MEASURED −8% vs no-sort at 1024²/8b (per-WG sort was neutral).
+ *
+ * Four passes (counting sort): reset → histogram → exclusive prefix sum → scatter.
+ *   - histogram uses a per-workgroup local histogram (workgroup-shared atomics, patches.js §4)
+ *     flushed to the global histogram once per bin per workgroup, cutting global-atomic contention
+ *     from O(rays) to O(workgroups × bins).
+ *   - the prefix-summed histogram doubles as the per-bin running cursor in scatter.
+ *
+ * `bins` is chosen per-scene by the caller (= material count, capped). Materials ≥ bins clamp into
+ * the last bin (graceful coherence loss). Capped at SORT_GLOBAL_MAX_BINS so a single 256-thread
+ * workgroup can zero/flush exactly one bin per thread (no per-thread loop needed).
+ */
+
+import {
+	Fn, uint,
+	If, Loop,
+	instanceIndex, localId,
+	workgroupBarrier,
+	atomicAdd, atomicLoad, atomicStore,
+} from 'three/tsl';
+
+import { workgroupAtomicArray } from './patches.js';
+import { readHitMaterialIndex } from '../Processor/PackedRayBuffer.js';
+import { COUNTER } from '../Processor/QueueManager.js';
+
+const WG_SIZE = 256;
+export const SORT_GLOBAL_MAX_BINS = 256;
+
+// Pass 1 — zero the global histogram.
+export function buildResetGlobalHistKernel( { sortGlobalHistogram, bins = SORT_GLOBAL_MAX_BINS } ) {
+
+	return Fn( () => {
+
+		If( instanceIndex.lessThan( uint( bins ) ), () => {
+
+			atomicStore( sortGlobalHistogram.element( instanceIndex ), uint( 0 ) );
+
+		} );
+
+	} );
+
+}
+
+// Pass 2 — histogram: per-workgroup local count (on-chip), flushed to global once per bin/WG.
+export function buildGlobalHistKernel( { hitBufferRO, activeIndicesReadRO, sortGlobalHistogram, counters, bins = SORT_GLOBAL_MAX_BINS } ) {
+
+	return Fn( () => {
+
+		const tid = instanceIndex;
+		const lid = localId.x;
+		const local = workgroupAtomicArray( 'uint', bins );
+
+		If( lid.lessThan( uint( bins ) ), () => {
+
+			atomicStore( local.element( lid ), uint( 0 ) );
+
+		} );
+		workgroupBarrier();
+
+		const entering = atomicLoad( counters.element( uint( COUNTER.ENTERING_COUNT ) ) );
+		If( tid.lessThan( entering ), () => {
+
+			const rayID = activeIndicesReadRO.element( tid );
+			const bin = uint( readHitMaterialIndex( hitBufferRO, rayID ) ).clamp( uint( 0 ), uint( bins - 1 ) );
+			atomicAdd( local.element( bin ), uint( 1 ) );
+
+		} );
+		workgroupBarrier();
+
+		If( lid.lessThan( uint( bins ) ), () => {
+
+			const c = atomicLoad( local.element( lid ) );
+			If( c.greaterThan( uint( 0 ) ), () => {
+
+				atomicAdd( sortGlobalHistogram.element( lid ), c );
+
+			} );
+
+		} );
+
+	} );
+
+}
+
+// Pass 3 — exclusive prefix sum over global bins (single thread; dispatch [1,1,1]).
+export function buildGlobalPrefixKernel( { sortGlobalHistogram, bins = SORT_GLOBAL_MAX_BINS } ) {
+
+	return Fn( () => {
+
+		If( instanceIndex.equal( uint( 0 ) ), () => {
+
+			const running = uint( 0 ).toVar();
+			Loop( { start: uint( 0 ), end: uint( bins ), type: 'uint' }, ( { i } ) => {
+
+				const slot = sortGlobalHistogram.element( i );
+				const c = atomicLoad( slot );
+				atomicStore( slot, running );
+				running.addAssign( c );
+
+			} );
+
+		} );
+
+	} );
+
+}
+
+// Pass 4 — scatter: atomicAdd on the prefix-summed histogram gives each ray its global slot
+// within its material's contiguous region.
+export function buildGlobalScatterKernel( { hitBufferRO, activeIndicesReadRO, sortedIndicesRW, sortGlobalHistogram, counters, bins = SORT_GLOBAL_MAX_BINS } ) {
+
+	return Fn( () => {
+
+		const tid = instanceIndex;
+		const entering = atomicLoad( counters.element( uint( COUNTER.ENTERING_COUNT ) ) );
+		If( tid.lessThan( entering ), () => {
+
+			const rayID = activeIndicesReadRO.element( tid );
+			const bin = uint( readHitMaterialIndex( hitBufferRO, rayID ) ).clamp( uint( 0 ), uint( bins - 1 ) );
+			const pos = atomicAdd( sortGlobalHistogram.element( bin ), uint( 1 ) );
+			sortedIndicesRW.element( pos ).assign( rayID );
+
+		} );
+
+	} );
+
+}
+
+export { WG_SIZE as SORT_GLOBAL_WG_SIZE };

package/src/TSL/TextureSampling.js

@@ -1,4 +1,4 @@
-import { Fn, wgslFn, float, vec2, vec3, vec4, int, If, normalize, cross, abs, mix, clamp, texture } from 'three/tsl';
+import { Fn, wgslFn, float, vec2, vec3, vec4, int, If, normalize, cross, abs, mix, clamp, texture, textureSize } from 'three/tsl';
 
 import {
 	UVCache,
@@ -283,8 +283,8 @@ export const processBump = Fn( ( [ bumpMaps, currentNormal, material, uvCache ]
 
 	If( material.bumpMapIndex.greaterThanEqual( int( 0 ) ).and( material.bumpScale.greaterThan( 0.0 ) ), () => {
 
-		// Approximate texel size
-		const texelSize = vec2( 1.0 / 1024.0 ).toVar();
+		// Texel size from the actual bump-array dimensions (finite-difference step).
+		const texelSize = vec2( 1.0 ).div( vec2( textureSize( bumpMaps ) ) ).toVar();
 
 		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;