@unikia/upe-renderer 0.0.0-stage → 0.187.11

package/examples/jsm/tsl/lighting/ClusteredLightsNode.js

@@ -0,0 +1,994 @@
+import { DataTexture, FloatType, RGBAFormat, Vector2, Vector3, LightsNode, NodeUpdateType, NodeUtils, PointLightNode, SpotLightNode } from 'three/webgpu';
+
+import {
+	instancedArray, nodeProxy, int, float, vec3, vec4, ivec2, ivec4, uniform, Break, Loop, positionView,
+	Fn, If, textureLoad, instanceIndex, screenCoordinate, directPointLight,
+	renderGroup,
+	min, max, pow, log, clamp, dot, smoothstep
+} from 'three/tsl';
+
+const _vector3 = /*@__PURE__*/ new Vector3();
+const _direction = /*@__PURE__*/ new Vector3();
+const _targetPosition = /*@__PURE__*/ new Vector3();
+const _size = /*@__PURE__*/ new Vector2();
+
+// light data texture rows
+
+const POSITION_ROW = 0; // world position, cutoff distance
+const COLOR_ROW = 1; // color * intensity, decay
+const SPOT_ROW = 2; // scaled world spot direction, scaled cone cosine
+const BOUNDS_ROW = 3; // world bounding sphere center, radius ( negative if unbounded )
+const ROWS = 4;
+
+/**
+ * A custom version of `LightsNode` implementing Forward+ clustered shading:
+ * the view frustum is subdivided into a 3D grid of clusters (X × Y screen tiles
+ * times an exponentially-spaced set of Z depth slices), and each cluster holds
+ * only the point and spot lights whose bounding spheres intersect it. At shading time each fragment
+ * looks up its cluster and loops over just that cluster's lights. Unlike 2D tiled
+ * lighting, clustered shading culls lights that share screen pixels but lie at
+ * different depths — suitable for 3D scenes with real depth complexity.
+ *
+ * @augments LightsNode
+ * @three_import import { clusteredLights } from 'three/addons/tsl/lighting/ClusteredLightsNode.js';
+ */
+class ClusteredLightsNode extends LightsNode {
+
+	static get type() {
+
+		return 'ClusteredLightsNode';
+
+	}
+
+	/**
+	 * Constructs a new clustered lights node.
+	 *
+	 * @param {number} [maxLights=1024] - Maximum number of point and spot lights.
+	 * @param {number} [tileSize=32] - Screen tile size in pixels (cluster XY size).
+	 * @param {number} [zSlices=24] - Number of exponential depth slices.
+	 * @param {number} [maxLightsPerCluster=64] - Per-cluster light-list capacity.
+	 */
+	constructor( maxLights = 1024, tileSize = 32, zSlices = 24, maxLightsPerCluster = 64 ) {
+
+		super();
+
+		/**
+		 * This flag can be used for type testing.
+		 *
+		 * @type {boolean}
+		 * @readonly
+		 * @default true
+		 */
+		this.isClusteredLightsNode = true;
+
+		this.materialLights = [];
+		this.clusteredLights = [];
+
+		this.maxLights = maxLights;
+		this.tileSize = tileSize;
+		this.zSlices = zSlices;
+		this.maxLightsPerCluster = maxLightsPerCluster;
+
+		this._chunksPerCluster = Math.ceil( maxLightsPerCluster / 4 );
+
+		this._bufferSize = null;
+		this._isWebGLBackend = false;
+		this._needsRebuild = false;
+		this._invocationsPerCluster = 1;
+		this._lightIndexes = null;
+		this._renderer = null;
+		this._screenClusterIndex = null;
+		this._compute = null;
+
+		const lightsData = new Float32Array( maxLights * 4 * ROWS );
+		this._lightsTexture = new DataTexture( lightsData, maxLights, ROWS, RGBAFormat, FloatType );
+
+		// Per Z-slice light range for Z-culling (CPU-sorted, uploaded each frame)
+
+		this._zSliceRangesData = new Float32Array( zSlices * 4 );
+		this._zSliceRangesTexture = new DataTexture( this._zSliceRangesData, zSlices, 1, RGBAFormat, FloatType );
+
+		this._lightViewZ = new Float32Array( maxLights );
+		this._lightSortOrder = [];
+
+		this._lightsCount = uniform( 0, 'int' );
+
+		// Render-group uniforms: shared between compute and fragment passes,
+		// updated manually each frame in updateBefore (compute lacks a camera context).
+		this._cameraNear = uniform( 0 ).setName( 'clusteredCameraNear' ).setGroup( renderGroup );
+		this._cameraFar = uniform( 0 ).setName( 'clusteredCameraFar' ).setGroup( renderGroup );
+		this._cameraViewMatrix = uniform( 'mat4' ).setName( 'clusteredCameraViewMatrix' ).setGroup( renderGroup );
+		this._cameraProjectionMatrix = uniform( 'mat4' ).setName( 'clusteredCameraProjectionMatrix' ).setGroup( renderGroup );
+
+		this._gridDimensions = uniform( new Vector2() );
+
+		this.updateBeforeType = NodeUpdateType.RENDER;
+
+	}
+
+	/**
+	 * Overwrites the default {@link LightsNode#customCacheKey} implementation by
+	 * including the node identity and resource version into the cache key.
+	 *
+	 * @return {number} The custom cache key.
+	 */
+	customCacheKey() {
+
+		// First use allocates the grid after material cache keys have been computed.
+		// Keep that allocation stable, but never share bindings between lights nodes.
+		return NodeUtils.hash( this.id, this.version, super.customCacheKey() );
+
+	}
+
+	/**
+	 * Updates the light data and the light ranges of the depth slices.
+	 *
+	 * @private
+	 * @param {Camera} camera - The camera.
+	 */
+	_updateLightsTexture( camera ) {
+
+		const { _lightsTexture: lightsTexture, clusteredLights } = this;
+
+		const data = lightsTexture.image.data;
+		const lineSize = lightsTexture.image.width * 4;
+		const count = Math.min( clusteredLights.length, this.maxLights );
+
+		this._lightsCount.value = count;
+
+		// Sort lights by the view-space depth of their bounding spheres for Z-culling
+
+		const viewZ = this._lightViewZ;
+		const order = this._lightSortOrder;
+
+		for ( let i = 0; i < count; i ++ ) {
+
+			this._getBoundingSphereCenter( clusteredLights[ i ], _vector3 );
+			_vector3.applyMatrix4( camera.matrixWorldInverse );
+			viewZ[ i ] = _vector3.z;
+			order[ i ] = i;
+
+		}
+
+		order.length = count;
+		order.sort( ( a, b ) => viewZ[ a ] - viewZ[ b ] );
+
+		// Write sorted lights to texture
+
+		for ( let i = 0; i < count; i ++ ) {
+
+			const light = clusteredLights[ order[ i ] ];
+
+			const offset = i * 4;
+
+			_vector3.setFromMatrixPosition( light.matrixWorld );
+
+			let rowOffset = lineSize * POSITION_ROW + offset;
+
+			data[ rowOffset + 0 ] = _vector3.x;
+			data[ rowOffset + 1 ] = _vector3.y;
+			data[ rowOffset + 2 ] = _vector3.z;
+			data[ rowOffset + 3 ] = light.distance;
+
+			rowOffset = lineSize * COLOR_ROW + offset;
+
+			data[ rowOffset + 0 ] = light.color.r * light.intensity;
+			data[ rowOffset + 1 ] = light.color.g * light.intensity;
+			data[ rowOffset + 2 ] = light.color.b * light.intensity;
+			data[ rowOffset + 3 ] = light.decay;
+
+			// The spot attenuation smoothstep( coneCos, penumbraCos, dot( L, direction ) ) is stored
+			// as smoothstep( 0, 1, dot( L, direction * scale ) - coneCos * scale ) with
+			// scale = 1 / ( penumbraCos - coneCos ). Point lights store a constant attenuation of 1.
+
+			rowOffset = lineSize * SPOT_ROW + offset;
+
+			if ( light.isSpotLight === true ) {
+
+				const coneCos = Math.cos( light.angle );
+				const penumbraCos = Math.cos( light.angle * ( 1 - light.penumbra ) );
+				const scale = 1 / Math.max( penumbraCos - coneCos, 1e-4 );
+
+				this._getSpotDirection( light, _direction ).multiplyScalar( scale );
+
+				data[ rowOffset + 0 ] = _direction.x;
+				data[ rowOffset + 1 ] = _direction.y;
+				data[ rowOffset + 2 ] = _direction.z;
+				data[ rowOffset + 3 ] = coneCos * scale;
+
+			} else {
+
+				data[ rowOffset + 0 ] = 0;
+				data[ rowOffset + 1 ] = 0;
+				data[ rowOffset + 2 ] = 0;
+				data[ rowOffset + 3 ] = - 1;
+
+			}
+
+			this._getBoundingSphereCenter( light, _vector3 );
+
+			rowOffset = lineSize * BOUNDS_ROW + offset;
+
+			data[ rowOffset + 0 ] = _vector3.x;
+			data[ rowOffset + 1 ] = _vector3.y;
+			data[ rowOffset + 2 ] = _vector3.z;
+			data[ rowOffset + 3 ] = this._getBoundingSphereRadius( light );
+
+		}
+
+		lightsTexture.needsUpdate = true;
+
+		// Compute per Z-slice light ranges
+
+		const zRanges = this._zSliceRangesData;
+
+		const near = camera.near;
+		const far = camera.far;
+		const NZ = this.zSlices;
+
+		for ( let z = 0; z < NZ; z ++ ) {
+
+			// Exponential Z-slice bounds (view-space, negative values)
+			const sliceNear = - ( near * Math.pow( far / near, z / NZ ) );
+			const sliceFar = - ( near * Math.pow( far / near, ( z + 1 ) / NZ ) );
+
+			let rangeStart = count;
+			let rangeEnd = 0;
+
+			for ( let i = 0; i < count; i ++ ) {
+
+				const vz = viewZ[ order[ i ] ];
+				const r = data[ lineSize * BOUNDS_ROW + i * 4 + 3 ];
+				const radius = r >= 0 ? r : far;
+
+				// Bounding sphere Z: [vz - radius, vz + radius]
+				// Slice Z: [sliceFar, sliceNear] (both negative, sliceFar < sliceNear)
+				if ( vz + radius >= sliceFar && vz - radius <= sliceNear ) {
+
+					if ( i < rangeStart ) rangeStart = i;
+					if ( i + 1 > rangeEnd ) rangeEnd = i + 1;
+
+				}
+
+			}
+
+			if ( rangeStart >= count ) {
+
+				rangeStart = 0;
+				rangeEnd = 0;
+
+			}
+
+			zRanges[ z * 4 ] = rangeStart;
+			zRanges[ z * 4 + 1 ] = rangeEnd;
+
+		}
+
+		this._zSliceRangesTexture.needsUpdate = true;
+
+	}
+
+	/**
+	 * Returns the normalized world-space direction pointing from the spot light's
+	 * target to the spot light.
+	 *
+	 * @private
+	 * @param {SpotLight} light - The spot light.
+	 * @param {Vector3} target - The target vector.
+	 * @return {Vector3} The direction.
+	 */
+	_getSpotDirection( light, target ) {
+
+		_targetPosition.setFromMatrixPosition( light.target.matrixWorld );
+
+		return target.setFromMatrixPosition( light.matrixWorld ).sub( _targetPosition ).normalize();
+
+	}
+
+	/**
+	 * Returns the world-space center of the light's bounding sphere. For spot lights,
+	 * this is the center of the smallest sphere enclosing the cone.
+	 *
+	 * @private
+	 * @param {PointLight|SpotLight} light - The light.
+	 * @param {Vector3} target - The target vector.
+	 * @return {Vector3} The bounding sphere center.
+	 */
+	_getBoundingSphereCenter( light, target ) {
+
+		target.setFromMatrixPosition( light.matrixWorld );
+
+		if ( light.isSpotLight === true && light.distance > 0 ) {
+
+			const angle = Math.min( light.angle, Math.PI / 2 );
+			const offset = angle > Math.PI / 4 ? light.distance * Math.cos( angle ) : light.distance / ( 2 * Math.cos( angle ) );
+
+			// _getSpotDirection() points away from the cone, so step backwards
+
+			target.addScaledVector( this._getSpotDirection( light, _direction ), - offset );
+
+		}
+
+		return target;
+
+	}
+
+	/**
+	 * Returns the radius of the light's bounding sphere.
+	 *
+	 * @private
+	 * @param {PointLight|SpotLight} light - The light.
+	 * @return {number} The bounding sphere radius. `-1` if the light has no cutoff distance.
+	 */
+	_getBoundingSphereRadius( light ) {
+
+		if ( light.distance <= 0 ) return - 1;
+
+		if ( light.isSpotLight === true ) {
+
+			const angle = Math.min( light.angle, Math.PI / 2 );
+
+			return angle > Math.PI / 4 ? light.distance * Math.sin( angle ) : light.distance / ( 2 * Math.cos( angle ) );
+
+		}
+
+		return light.distance;
+
+	}
+
+	/**
+	 * Updates the light data and assigns the lights to the clusters.
+	 *
+	 * @param {NodeFrame} frame - A reference to the current node frame.
+	 */
+	updateBefore( frame ) {
+
+		const { renderer, camera } = frame;
+
+		this._initGrid( renderer );
+
+		this._updateLightsTexture( camera );
+
+		this._cameraNear.value = camera.near;
+		this._cameraFar.value = camera.far;
+		this._cameraViewMatrix.value = camera.matrixWorldInverse;
+		this._cameraProjectionMatrix.value = camera.projectionMatrix;
+
+		renderer.compute( this._compute );
+
+	}
+
+	/**
+	 * Configures this node with an array of lights. Point and spot lights without
+	 * shadows are clustered (except lights with a `colorNode`, spot lights with a
+	 * projected `map` and light types with their own light node, like `IESSpotLight`
+	 * or `ProjectorLight`), all other lights use the default lighting.
+	 *
+	 * @param {Array<Light>} lights - An array of lights.
+	 * @return {ClusteredLightsNode} A reference to this node.
+	 */
+	setLights( lights ) {
+
+		const { clusteredLights, materialLights } = this;
+
+		let materialIndex = 0;
+		let clusteredIndex = 0;
+
+		for ( const light of lights ) {
+
+			if ( this._isClusteredLight( light ) ) {
+
+				clusteredLights[ clusteredIndex ++ ] = light;
+
+			} else {
+
+				materialLights[ materialIndex ++ ] = light;
+
+			}
+
+		}
+
+		materialLights.length = materialIndex;
+		clusteredLights.length = clusteredIndex;
+
+		return super.setLights( lights );
+
+	}
+
+	/**
+	 * Returns `true` if the given light can be clustered.
+	 *
+	 * @private
+	 * @param {Light} light - The light.
+	 * @return {boolean} Whether the light is clustered or not.
+	 */
+	_isClusteredLight( light ) {
+
+		// Shadows, color nodes (any light) and projected maps (spot lights) are not supported.
+
+		if ( light.castShadow === true || light.colorNode ) return false;
+
+		// Only lights shaded by the plain point and spot light nodes are clustered. Subclasses
+		// registered with their own light node (e.g. IESSpotLight, ProjectorLight) keep the
+		// default lighting, since clustering would shade them as plain spot lights.
+
+		if ( light._lightNode === PointLightNode ) return true;
+
+		return light._lightNode === SpotLightNode && ! light.map;
+
+	}
+
+	/**
+	 * Returns the lights that are not clustered.
+	 *
+	 * @return {Array<Light>} The lights using the default lighting.
+	 */
+	getBuiltinLights() {
+
+		return this.materialLights;
+
+	}
+
+	/**
+	 * Returns the light index stored at the given slot of the fragment's cluster.
+	 *
+	 * @private
+	 * @param {number|Node<int>} element - The slot.
+	 * @return {Node<int>} The 1-based light index. `0` marks the end of the list.
+	 */
+	_getTile( element ) {
+
+		element = int( element );
+
+		const stride = int( 4 );
+		const chunkOffset = element.div( stride );
+		const idx = this._screenClusterIndex.mul( int( this._chunksPerCluster ) ).add( chunkOffset );
+
+		return this._lightIndexes.element( idx ).element( element.mod( stride ) );
+
+	}
+
+	/**
+	 * Returns the number of lights in the fragment's cluster. Useful for debugging.
+	 *
+	 * @param {Node<int>} zSliceNode - The depth slice to inspect. A negative value selects the fragment's own cluster.
+	 * @return {Node<int>} The light count.
+	 */
+	getClusterLightCount( zSliceNode ) {
+
+		const getCount = Fn( ( [ zSliceNode ] ) => {
+
+			const count = int( 0 ).toVar();
+
+			const debugClusterIndex = this._screenClusterIndex.toVar();
+
+			If( zSliceNode.greaterThanEqual( int( 0 ) ), () => {
+
+				const tileSize = int( this.tileSize );
+				const screenTile = screenCoordinate.div( tileSize ).floor();
+				const NX = int( this._gridDimensions.x );
+				const NY = int( this._gridDimensions.y );
+
+				debugClusterIndex.assign(
+					int( screenTile.x )
+						.add( int( screenTile.y ).mul( NX ) )
+						.add( zSliceNode.mul( NX.mul( NY ) ) )
+				);
+
+			} );
+
+			Loop( this.maxLightsPerCluster, ( { i } ) => {
+
+				const element = int( i );
+				const stride = int( 4 );
+				const chunkOffset = element.div( stride );
+				const idx = debugClusterIndex.mul( int( this._chunksPerCluster ) ).add( chunkOffset );
+				const lightIndex = this._lightIndexes.element( idx ).element( element.mod( stride ) );
+
+				If( lightIndex.equal( int( 0 ) ), () => {
+
+					Break();
+
+				} );
+
+				count.addAssign( int( 1 ) );
+
+			} );
+
+			return count;
+
+		} );
+
+		return getCount( zSliceNode );
+
+	}
+
+	/**
+	 * Returns the shading data of the light at the given index.
+	 *
+	 * @private
+	 * @param {number|Node<int>} index - The light index.
+	 * @return {Object} The light's view position, distance, color, decay, view-space spot direction and spot offset.
+	 */
+	_getLightData( index ) {
+
+		index = int( index );
+
+		const dataA = textureLoad( this._lightsTexture, ivec2( index, POSITION_ROW ) );
+		const dataB = textureLoad( this._lightsTexture, ivec2( index, COLOR_ROW ) );
+		const dataC = textureLoad( this._lightsTexture, ivec2( index, SPOT_ROW ) );
+
+		const viewPosition = this._cameraViewMatrix.mul( vec4( dataA.xyz, 1.0 ) ).xyz;
+		const distance = dataA.w;
+		const color = dataB.rgb;
+		const decay = dataB.w;
+		const spotDirection = this._cameraViewMatrix.mul( vec4( dataC.xyz, 0.0 ) ).xyz;
+		const spotOffset = dataC.w;
+
+		return {
+			viewPosition,
+			distance,
+			color,
+			decay,
+			spotDirection,
+			spotOffset
+		};
+
+	}
+
+	/**
+	 * Returns the culling data of the light at the given index.
+	 *
+	 * @private
+	 * @param {number|Node<int>} index - The light index.
+	 * @return {Object} The view-space center and the radius of the light's bounding sphere. A negative radius marks an unbounded light.
+	 */
+	_getLightBounds( index ) {
+
+		const data = textureLoad( this._lightsTexture, ivec2( int( index ), BOUNDS_ROW ) );
+
+		const center = this._cameraViewMatrix.mul( vec4( data.xyz, 1.0 ) ).xyz;
+		const radius = data.w;
+
+		return { center, radius };
+
+	}
+
+	/**
+	 * Sets up the default lights and the clustered point and spot lights.
+	 *
+	 * @param {NodeBuilder} builder - A reference to the current node builder.
+	 * @param {Array<LightingNode>} lightNodes - An array of lighting nodes.
+	 */
+	setupLights( builder, lightNodes ) {
+
+		this._initGrid( builder.renderer );
+
+		//
+
+		const lightingModel = builder.context.reflectedLight;
+
+		lightingModel.directDiffuse.toStack();
+		lightingModel.directSpecular.toStack();
+
+		super.setupLights( builder, lightNodes );
+
+		Fn( () => {
+
+			Loop( this.maxLightsPerCluster, ( { i } ) => {
+
+				const lightIndex = this._getTile( i );
+
+				If( lightIndex.equal( int( 0 ) ), () => {
+
+					Break();
+
+				} );
+
+				const { color, decay, viewPosition, distance, spotDirection, spotOffset } = this._getLightData( lightIndex.sub( 1 ) );
+
+				const lightVector = viewPosition.sub( positionView );
+
+				// spot cone attenuation, always 1 for point lights
+				const spotAttenuation = smoothstep( 0, 1, dot( lightVector.normalize(), spotDirection ).sub( spotOffset ) ).toVar();
+
+				// Early-out: skip full BRDF if fragment is beyond the light's cutoff or outside the spot cone
+				const inRange = distance.equal( 0 ).or( dot( lightVector, lightVector ).lessThanEqual( distance.mul( distance ) ) );
+
+				If( inRange.and( spotAttenuation.greaterThan( 0 ) ), () => {
+
+					builder.lightsNode.setupDirectLight( builder, this, directPointLight( {
+						color: color.mul( spotAttenuation ),
+						lightVector,
+						cutoffDistance: distance,
+						decayExponent: decay
+					} ) );
+
+				} );
+
+			} );
+
+		}, 'void' )();
+
+	}
+
+	/**
+	 * Rounds the given size up to a multiple of the tile size.
+	 *
+	 * @private
+	 * @param {number} value - The size.
+	 * @return {number} The fitted size.
+	 */
+	_getBufferFitSize( value ) {
+
+		const multiple = this.tileSize;
+
+		return Math.ceil( value / multiple ) * multiple;
+
+	}
+
+	/**
+	 * Sets the size of the cluster grid. Must be called outside of rendering. Not required
+	 * with {@link ClusteredLighting}, which fits the grid at the beginning of each render.
+	 *
+	 * @param {number} width - The drawing buffer width.
+	 * @param {number} height - The drawing buffer height.
+	 * @return {ClusteredLightsNode} A reference to this node.
+	 */
+	setSize( width, height ) {
+
+		this._resize( this._getBufferFitSize( width ), this._getBufferFitSize( height ) );
+
+		return this;
+
+	}
+
+	/**
+	 * Fits the cluster grid to the framebuffer of the render that is about to start. Called by
+	 * {@link ClusteredLighting} before the render objects of the render are prepared. Since each
+	 * render depth has its own node, no pending command buffer uses the resources of this node at
+	 * this point, so a rebuild can free the replaced resources immediately.
+	 */
+	updateSize() {
+
+		if ( this._renderer !== null ) this._fitToRenderer( this._renderer );
+
+	}
+
+	/**
+	 * Creates the cluster grid on first use. While rendering, the grid is never rebuilt: the
+	 * replaced resources could still be used by a command buffer that was not submitted yet.
+	 *
+	 * @private
+	 * @param {Renderer} renderer - The renderer.
+	 */
+	_initGrid( renderer ) {
+
+		this._renderer = renderer;
+
+		if ( this._compute === null ) this._fitToRenderer( renderer );
+
+	}
+
+	/**
+	 * Fits the cluster grid to the framebuffer the renderer is rendering to.
+	 *
+	 * @private
+	 * @param {Renderer} renderer - The renderer.
+	 */
+	_fitToRenderer( renderer ) {
+
+		// the grid must match the framebuffer being rendered: a render target (e.g. a reflector
+		// with a resolution scale) can differ from the drawing buffer
+
+		const renderTarget = renderer.getRenderTarget();
+
+		if ( renderTarget !== null ) {
+
+			_size.set( renderTarget.width, renderTarget.height );
+
+		} else {
+
+			renderer.getDrawingBufferSize( _size );
+
+		}
+
+		// the compute differs per backend, so a backend change requires a rebuild
+
+		const isWebGLBackend = renderer.backend.isWebGLBackend === true;
+
+		if ( this._compute !== null && this._isWebGLBackend !== isWebGLBackend ) this._needsRebuild = true;
+
+		this._isWebGLBackend = isWebGLBackend;
+
+		this._resize( this._getBufferFitSize( _size.width ), this._getBufferFitSize( _size.height ) );
+
+	}
+
+	/**
+	 * Resizes the cluster grid. The grid dimensions are uniforms, so resizing only updates
+	 * them and the compute count; the compute and the storage are rebuilt only when the
+	 * storage has to grow (or the backend changed).
+	 *
+	 * @private
+	 * @param {number} width - The fitted width.
+	 * @param {number} height - The fitted height.
+	 */
+	_resize( width, height ) {
+
+		if ( this._needsRebuild === false && this._bufferSize !== null && this._bufferSize.width === width && this._bufferSize.height === height ) return;
+
+		const NX = Math.floor( width / this.tileSize );
+		const NY = Math.floor( height / this.tileSize );
+		const clusterCount = NX * NY * this.zSlices;
+
+		const requiredElements = clusterCount * this._chunksPerCluster;
+
+		if ( this._needsRebuild === true || this._compute === null || this._lightIndexes.value.array.length / 4 < requiredElements ) {
+
+			this._create( clusterCount );
+
+		}
+
+		this._gridDimensions.value.set( NX, NY );
+		this._compute.count = clusterCount * this._invocationsPerCluster;
+
+		if ( this._bufferSize === null ) this._bufferSize = new Vector2();
+
+		this._bufferSize.set( width, height );
+
+	}
+
+	/**
+	 * Creates the light index storage, the compute node and the fragment cluster lookup.
+	 * The storage is allocated with headroom so that most resizes do not need a rebuild.
+	 *
+	 * @private
+	 * @param {number} clusterCount - The number of clusters of the current grid.
+	 */
+	_create( clusterCount ) {
+
+		const { tileSize, zSlices, _chunksPerCluster: chunksPerCluster } = this;
+
+		const NZ = zSlices;
+
+		// grid dimensions as uniforms: shaders do not depend on the drawing buffer size
+
+		const grid = this._gridDimensions;
+		const NX = int( grid.x );
+		const NY = int( grid.y );
+
+		// Per-cluster light-index storage (ivec4 chunks), grown geometrically.
+
+		const requiredElements = clusterCount * chunksPerCluster;
+		const previousElements = this._lightIndexes !== null ? this._lightIndexes.value.array.length / 4 : 0;
+		const elements = previousElements === 0 ? Math.ceil( requiredElements * 1.5 ) : Math.max( requiredElements, previousElements * 2 );
+
+		// rebuilds only happen outside of rendering (see _initGrid()), so the replaced resources can be freed
+
+		if ( this._compute !== null ) {
+
+			// Replacing storage requires new material bindings. The initial allocation does not.
+			this.needsUpdate = true;
+
+			this._compute.dispose();
+			this._lightIndexes.value.dispose();
+
+		}
+
+		// instanced storage: WebGL computes use gl_InstanceID as instanceIndex; PBO: random access in the fragment stage
+		const lightIndexes = instancedArray( new Int32Array( elements * 4 ), 'ivec4' ).setPBO( true ).setName( 'lightIndexes' );
+
+		// view-space AABB of the given cluster
+
+		const getClusterBounds = ( clusterIndex ) => {
+
+			// view-space scale factors derived from the projection matrix:
+			//   view_x = ndc_x * (-view_z) / focal_x = ndc_x * (-view_z) * invFocalX
+			//   view_y = ndc_y * (-view_z) / focal_y = ndc_y * (-view_z) * invFocalY
+			// where focal_x = projMatrix[0][0] and focal_y = projMatrix[1][1].
+			const invFocalX = float( 1 ).div( this._cameraProjectionMatrix.element( 0 ).element( 0 ) );
+			const invFocalY = float( 1 ).div( this._cameraProjectionMatrix.element( 1 ).element( 1 ) );
+
+			// 3D cluster coordinates
+			const cx = clusterIndex.mod( NX );
+			const cy = clusterIndex.div( NX ).mod( NY );
+			const cz = clusterIndex.div( NX.mul( NY ) );
+
+			// NDC X/Y bounds of the cluster.
+			// Y is flipped: cy=0 is the top screen row (fragment y=0), which is NDC y=+1.
+			const ndcXmin = float( cx ).mul( 2.0 ).div( grid.x ).sub( 1.0 );
+			const ndcXmax = float( cx.add( int( 1 ) ) ).mul( 2.0 ).div( grid.x ).sub( 1.0 );
+			const ndcYmax = float( 1 ).sub( float( cy ).mul( 2.0 ).div( grid.y ) );
+			const ndcYmin = float( 1 ).sub( float( cy.add( int( 1 ) ) ).mul( 2.0 ).div( grid.y ) );
+
+			// View-space Z bounds (negative, exponential slicing)
+			const farOverNear = this._cameraFar.div( this._cameraNear );
+			const zNearCluster = this._cameraNear.mul( pow( farOverNear, float( cz ).mul( 1.0 / NZ ) ) ).negate();
+			const zFarCluster = this._cameraNear.mul( pow( farOverNear, float( cz.add( int( 1 ) ) ).mul( 1.0 / NZ ) ) ).negate();
+
+			const scaleNearX = zNearCluster.negate().mul( invFocalX );
+			const scaleFarX = zFarCluster.negate().mul( invFocalX );
+			const scaleNearY = zNearCluster.negate().mul( invFocalY );
+			const scaleFarY = zFarCluster.negate().mul( invFocalY );
+
+			const xMinNear = ndcXmin.mul( scaleNearX );
+			const xMaxNear = ndcXmax.mul( scaleNearX );
+			const xMinFar = ndcXmin.mul( scaleFarX );
+			const xMaxFar = ndcXmax.mul( scaleFarX );
+
+			const yMinNear = ndcYmin.mul( scaleNearY );
+			const yMaxNear = ndcYmax.mul( scaleNearY );
+			const yMinFar = ndcYmin.mul( scaleFarY );
+			const yMaxFar = ndcYmax.mul( scaleFarY );
+
+			// AABB of the 8 view-space corners (tile boundaries can straddle the view axis)
+			const aabbMinX = min( xMinNear, xMinFar );
+			const aabbMaxX = max( xMaxNear, xMaxFar );
+			const aabbMinY = min( yMinNear, yMinFar );
+			const aabbMaxY = max( yMaxNear, yMaxFar );
+
+			const aabbMin = vec3( aabbMinX, aabbMinY, zFarCluster );
+			const aabbMax = vec3( aabbMaxX, aabbMaxY, zNearCluster );
+
+			return { cz, aabbMin, aabbMax };
+
+		};
+
+		// sphere-AABB intersection in view space
+
+		const intersectsCluster = ( lightIdx, aabbMin, aabbMax ) => {
+
+			const { center, radius } = this._getLightBounds( lightIdx );
+
+			const closest = max( aabbMin, min( center, aabbMax ) );
+			const diff = center.sub( closest );
+			const distSq = dot( diff, diff );
+
+			return radius.lessThan( 0 ).or( distSq.lessThanEqual( radius.mul( radius ) ) );
+
+		};
+
+		// Each invocation fills `chunksPerInvocation` ivec4 chunks of one cluster. WebGL computes
+		// run via transform feedback and can only write their own element, so there each
+		// invocation fills a single chunk; WebGPU uses one invocation per cluster.
+
+		const chunksPerInvocation = this._isWebGLBackend ? 1 : chunksPerCluster;
+		const invocationsPerCluster = chunksPerCluster / chunksPerInvocation;
+
+		this._invocationsPerCluster = invocationsPerCluster;
+
+		const compute = Fn( () => {
+
+			const clusterIndex = int( instanceIndex.div( invocationsPerCluster ) );
+			const firstChunk = int( instanceIndex.mod( invocationsPerCluster ) ).mul( chunksPerInvocation );
+			const firstSlot = firstChunk.mul( 4 );
+			const lastSlot = firstSlot.add( chunksPerInvocation * 4 );
+
+			const { cz, aabbMin, aabbMax } = getClusterBounds( clusterIndex );
+
+			const chunks = ivec4( 0 ).toArray( chunksPerInvocation ).toVar();
+			const index = int( 0 ).toVar();
+
+			// Z-culling: only test lights that can reach this cluster's Z-slice
+			const zRange = textureLoad( this._zSliceRangesTexture, ivec2( cz, 0 ) );
+			const rangeStart = int( zRange.x );
+			const rangeEnd = int( zRange.y );
+
+			Loop( this.maxLights, ( { i } ) => {
+
+				const lightIdx = rangeStart.add( i );
+
+				If( index.greaterThanEqual( lastSlot ).or( lightIdx.greaterThanEqual( rangeEnd ) ), () => {
+
+					Break();
+
+				} );
+
+				If( intersectsCluster( lightIdx, aabbMin, aabbMax ), () => {
+
+					// slots before firstSlot belong to other invocations of this cluster
+					If( index.greaterThanEqual( firstSlot ), () => {
+
+						const slot = index.sub( firstSlot );
+
+						chunks.element( slot.div( 4 ) ).element( slot.mod( 4 ) ).assign( lightIdx.add( int( 1 ) ) );
+
+					} );
+
+					index.addAssign( int( 1 ) );
+
+				} );
+
+			} );
+
+			const firstElement = clusterIndex.mul( chunksPerCluster ).add( firstChunk );
+
+			const writeChunks = () => {
+
+				Loop( chunksPerInvocation, ( { i } ) => {
+
+					lightIndexes.element( firstElement.add( i ) ).assign( chunks.element( i ) );
+
+				} );
+
+			};
+
+			if ( this._isWebGLBackend === true ) {
+
+				// WebGL binds the transform feedback buffers per compute program, and programs are shared by
+				// identical code. The (always true) capacity and node id constants give each node and storage
+				// allocation its own program, so a compute never writes to the storage of another one.
+
+				If( firstElement.lessThan( int( elements ) ).and( int( this.id ).notEqual( int( - 1 ) ) ), writeChunks );
+
+			} else {
+
+				writeChunks();
+
+			}
+
+		} )().compute( clusterCount * invocationsPerCluster ).setName( 'Update Clustered Lights' );
+
+		// shading-side: fragment → cluster index
+
+		const getScreenClusterIndex = Fn( () => {
+
+			const screenTile = screenCoordinate.div( tileSize ).floor();
+
+			// view-space depth from positionView (negative in front); take magnitude
+			const viewDepth = positionView.z.negate();
+
+			// exponential Z slice: tz = floor( log(depth/near) / log(far/near) * NZ )
+			const invLogFarOverNear = float( 1 ).div( log( this._cameraFar.div( this._cameraNear ) ) );
+			const sliceFloat = log( viewDepth.div( this._cameraNear ) ).mul( invLogFarOverNear ).mul( float( NZ ) );
+			const zSlice = clamp( sliceFloat.floor(), float( 0 ), float( NZ - 1 ) );
+
+			return int( screenTile.x )
+				.add( int( screenTile.y ).mul( NX ) )
+				.add( int( zSlice ).mul( NX.mul( NY ) ) );
+
+		} );
+
+		const screenClusterIndex = getScreenClusterIndex().toVar();
+
+		// assigns
+
+		this._lightIndexes = lightIndexes;
+		this._screenClusterIndex = screenClusterIndex;
+		this._compute = compute;
+		this._needsRebuild = false;
+
+	}
+
+	/**
+	 * Frees the GPU resources allocated by this node.
+	 */
+	dispose() {
+
+		if ( this._compute !== null ) this._compute.dispose();
+		if ( this._lightIndexes !== null ) this._lightIndexes.value.dispose();
+
+		this._lightsTexture.dispose();
+		this._zSliceRangesTexture.dispose();
+
+		super.dispose();
+
+	}
+
+}
+
+export default ClusteredLightsNode;
+
+/**
+ * TSL function that creates a clustered lights node.
+ *
+ * @tsl
+ * @function
+ * @param {number} [maxLights=1024] - Maximum number of point and spot lights.
+ * @param {number} [tileSize=32] - Screen tile size in pixels.
+ * @param {number} [zSlices=24] - Depth slice count.
+ * @param {number} [maxLightsPerCluster=64] - Per-cluster light-list capacity.
+ * @return {ClusteredLightsNode} The clustered lights node.
+ */
+export const clusteredLights = /*@__PURE__*/ nodeProxy( ClusteredLightsNode );