Initial clustered lights implementation (tiled clustering only) (#16866)

# Remaining issues
- causes issues with the default physical material falloff. was
considering preventing this in the shader but decided to leave it so
that if a user wants to use physical falloff they still can as long as
the adjust the light ranges accordingly (and the default light range is
absolutely large enough for physical falloff)
- there's no depth clipping (to prevent lights disappearing when too
close or too far from the camera). this does also mean lights behind the
camera will be marked as "contributing" to pixels in front of the camera
(their light meshes get flipped). couldn't find an easy and clean
solution to only prevent clipping if the light is within range and once
depth clustering is implemented it will fix this issue (since any lights
behind the camera won't end up in any depth slice)

# Implementation Details
When this work is more complete ill move all this over to the official
docs, but for now just using this PR as a rough set of
notes/thoughts/todos

The implementation is mainly inspired by these CoD slides:
https://advances.realtimerendering.com/s2017/2017_Sig_Improved_Culling_final.pdf

The main idea is to split the clustering into separate X/Y "tiled"
clustering AND a Z "depth" clustering, and then checking if the lights
is in both the tile and the depth slice.

## Tiled Clustering
This uses the rendering pipeline to draw meshes for each light and
writes bits out to a light mask texture if there are pixels infront of
the depth buffer (effectively finding lights that intersect the depth
buffer).

The render target with the light mask texture and depth buffer has a
resolution equal to the amount of tiles.

### Depth pre-pass (removed)
All the scene geometry is rendered to a low resolution render target.
Currently this is repeated per `ClusteredLight`, in future these depth
texture might be able to get shared

### Stencil Pass (removed)
Draws all the light geometry with depthFunction=GREATER and sets stencil
bits to 1.

This is combined with the next pass to only mark pixels that contain
light geometry both behind AND infront of the depth buffer.

However this ended up causing issues due to the low-resolution aliased
depth buffer where stencil bits weren't set for the edges of meshes.

![image](https://github.com/user-attachments/assets/66310a5d-8da1-4fb1-be6b-faae7f7fa8cb)

In future we could maybe get around this by doing a post-process pass
over the depth pre-pass to expand the max depth values out by one tile.
Although for now this just adds extra complexity and we probably don't
really need this pass.

### Light Mask Pass
Each light mesh is drawn with a different index and any fragment pixels
which pass the depth test (meaning the light is in front of the depth
pre-pass) will set its bit in the light mask texture with an atomic OR.

Atleast thats the plan on WebGPU which isn't implemented yet. WebGL
doesn't have support for storage textures or atomic operations, so we
instead use a float buffer with additive blending.

To prevent accuracy issues with floating point values we ensure the mask
doesn't go above the bits in the floating-point fraction, which limits
us to 23 lights per clusteredlight on most systems.

### Lighting pass
This light mask is then queried bit-by-bit in the lighting calculation
to figure out which lights are in that "tile"

### Light Meshes
All the light meshes are just spheres. To reduce the pixels set for
spotlights they are modified in the vertex shader so positions on the
sphere that are outside the spotlight angle are set to 0,0,0. This
causes the sphere to end up having a more cone shape

## Depth Clustering
TODO. not currently implemented. will be implemented in a different PR

CoD seems to do this in CPU which makes sense since its only a min/max
index per slice so can be cheaply calculated and uploaded.

## Not Implemented / Broken
- [x] PBR materials
- [x] I have code for point lights but its untested. I feel like they
likely won't work rn
- [x] moving the camera too close or too far from the lights make them
disappear
- this is an issue with the camera intersecting with the light geometry,
on WebGPU this can be fixed by disabling back-face culling but on WebGL
this will cause more issues due to its additive blending
- on WebGL we could test if the light mesh intersects with the camera
and draw back faces instead
- [x] spot lights that point in any other direction but down
- to make the light mesh vertex shader simpler we assume a direction of
down. this will have to get changed or (better) we just rotate the world
matrix by the light direction
- [x] lights with a default range. trying to scale the light geometry by
`Number.MAX_VALUE` seems to break it
  - maybe we should clamp it?
- [x] WebGPU support
- [x] Using instancing for the light meshes
- [x] make the amount of tiles configurable
- I don't know if this should be an options to specify the number of
tiles or to specify the size of each tile
- [ ] figure out what to do for `transferToNodeMaterialEffect`

I don't plan to support these kinda lights:
- anything that requires textures like IES textures or shadowed lights
- anything other than point/spot lights
- lights using anything other than the default falloff

Author: matanui159

packages/dev/core/src/Buffers/storageBuffer.ts

@@ -46,6 +46,15 @@ export class StorageBuffer {
         return this._buffer;
     }
 
+    /**
+     * Clears the storage buffer to zeros
+     * @param byteOffset the byte offset to start clearing (optional)
+     * @param byteLength the byte length to clear (optional)
+     */
+    public clear(byteOffset?: number, byteLength?: number): void {
+        this._engine.clearStorageBuffer(this._buffer, byteOffset, byteLength);
+    }
+
     /**
      * Updates the storage buffer
      * @param data the data used to update the storage buffer

packages/dev/core/src/Engines/engineCapabilities.ts

@@ -27,6 +27,8 @@ export interface EngineCapabilities {
     maxVertexUniformVectors: number;
     /** Maximum number of uniforms per fragment shader */
     maxFragmentUniformVectors: number;
+    /** The number of bits that can be accurately represented in shader floats */
+    shaderFloatPrecision: number;
     /** Defines if standard derivatives (dx/dy) are supported */
     standardDerivatives: boolean;
     /** Defines if s3tc texture compression is supported */
@@ -80,6 +82,8 @@ export interface EngineCapabilities {
     depthTextureExtension: boolean;
     /** Defines if float color buffer are supported */
     colorBufferFloat: boolean;
+    /** Defines if float color blending is supported */
+    blendFloat: boolean;
     /** Defines if half float color buffer are supported */
     colorBufferHalfFloat?: boolean;
     /** Gets disjoint timer query extension (null if not supported) */

packages/dev/core/src/Engines/nativeEngine.ts

@@ -286,6 +286,7 @@ export class NativeEngine extends Engine {
             maxDrawBuffers: 8,
             maxFragmentUniformVectors: 16,
             maxVertexUniformVectors: 16,
+            shaderFloatPrecision: 23, // TODO: is this correct?
             standardDerivatives: true,
             astc: null,
             pvrtc: null,
@@ -297,6 +298,7 @@ export class NativeEngine extends Engine {
             fragmentDepthSupported: false,
             highPrecisionShaderSupported: true,
             colorBufferFloat: false,
+            blendFloat: false,
             supportFloatTexturesResolve: false,
             rg11b10ufColorRenderable: false,
             textureFloat: true,

packages/dev/core/src/Engines/nullEngine.ts

@@ -133,6 +133,7 @@ export class NullEngine extends Engine {
             maxVaryingVectors: 16,
             maxFragmentUniformVectors: 16,
             maxVertexUniformVectors: 16,
+            shaderFloatPrecision: 10, // Minimum precision for mediump floats WebGL 1
             standardDerivatives: false,
             astc: null,
             pvrtc: null,
@@ -144,6 +145,7 @@ export class NullEngine extends Engine {
             fragmentDepthSupported: false,
             highPrecisionShaderSupported: true,
             colorBufferFloat: false,
+            blendFloat: false,
             supportFloatTexturesResolve: false,
             rg11b10ufColorRenderable: false,
             textureFloat: false,

packages/dev/core/src/Engines/thinEngine.ts

@@ -504,6 +504,7 @@ export class ThinEngine extends AbstractEngine {
             maxVaryingVectors: this._gl.getParameter(this._gl.MAX_VARYING_VECTORS),
             maxFragmentUniformVectors: this._gl.getParameter(this._gl.MAX_FRAGMENT_UNIFORM_VECTORS),
             maxVertexUniformVectors: this._gl.getParameter(this._gl.MAX_VERTEX_UNIFORM_VECTORS),
+            shaderFloatPrecision: 0,
             parallelShaderCompile: this._gl.getExtension("KHR_parallel_shader_compile") || undefined,
             standardDerivatives: this._webGLVersion > 1 || this._gl.getExtension("OES_standard_derivatives") !== null,
             maxAnisotropy: 1,
@@ -531,6 +532,7 @@ export class ThinEngine extends AbstractEngine {
             drawBuffersExtension: false,
             maxMSAASamples: 1,
             colorBufferFloat: !!(this._webGLVersion > 1 && this._gl.getExtension("EXT_color_buffer_float")),
+            blendFloat: this._gl.getExtension("EXT_float_blend") !== null,
             supportFloatTexturesResolve: false,
             rg11b10ufColorRenderable: false,
             colorBufferHalfFloat: !!(this._webGLVersion > 1 && this._gl.getExtension("EXT_color_buffer_half_float")),
@@ -732,6 +734,19 @@ export class ThinEngine extends AbstractEngine {
 
             if (vertexhighp && fragmenthighp) {
                 this._caps.highPrecisionShaderSupported = vertexhighp.precision !== 0 && fragmenthighp.precision !== 0;
+                this._caps.shaderFloatPrecision = Math.min(vertexhighp.precision, fragmenthighp.precision);
+            }
+            // This will check both the capability and the `useHighPrecisionFloats` option
+            if (!this._shouldUseHighPrecisionShader) {
+                const vertexmedp = this._gl.getShaderPrecisionFormat(this._gl.VERTEX_SHADER, this._gl.MEDIUM_FLOAT);
+                const fragmentmedp = this._gl.getShaderPrecisionFormat(this._gl.FRAGMENT_SHADER, this._gl.MEDIUM_FLOAT);
+                if (vertexmedp && fragmentmedp) {
+                    this._caps.shaderFloatPrecision = Math.min(vertexmedp.precision, fragmentmedp.precision);
+                }
+            }
+            if (this._caps.shaderFloatPrecision < 10) {
+                // WebGL spec requires mediump precision to atleast be 10
+                this._caps.shaderFloatPrecision = 10;
             }
         }
 

packages/dev/core/src/Engines/webgpuEngine.ts

@@ -868,6 +868,7 @@ export class WebGPUEngine extends ThinWebGPUEngine {
             maxVaryingVectors: this._deviceLimits.maxInterStageShaderVariables,
             maxFragmentUniformVectors: Math.floor(this._deviceLimits.maxUniformBufferBindingSize / 4),
             maxVertexUniformVectors: Math.floor(this._deviceLimits.maxUniformBufferBindingSize / 4),
+            shaderFloatPrecision: 23, // WGSL always uses IEEE-754 binary32 floats (which have 23 bits of significand)
             standardDerivatives: true,
             astc: (this._deviceEnabledExtensions.indexOf(WebGPUConstants.FeatureName.TextureCompressionASTC) >= 0 ? true : undefined) as any,
             s3tc: (this._deviceEnabledExtensions.indexOf(WebGPUConstants.FeatureName.TextureCompressionBC) >= 0 ? true : undefined) as any,
@@ -880,6 +881,7 @@ export class WebGPUEngine extends ThinWebGPUEngine {
             fragmentDepthSupported: true,
             highPrecisionShaderSupported: true,
             colorBufferFloat: true,
+            blendFloat: this._deviceEnabledExtensions.indexOf(WebGPUConstants.FeatureName.Float32Blendable) >= 0,
             supportFloatTexturesResolve: false, // See https://github.com/gpuweb/gpuweb/issues/3844
             rg11b10ufColorRenderable: this._deviceEnabledExtensions.indexOf(WebGPUConstants.FeatureName.RG11B10UFloatRenderable) >= 0,
             textureFloat: true,
@@ -3939,6 +3941,16 @@ export class WebGPUEngine extends ThinWebGPUEngine {
         return this._createBuffer(data, creationFlags | Constants.BUFFER_CREATIONFLAG_STORAGE, label);
     }
 
+    /**
+     * Clears a storage buffer to zeroes
+     * @param storageBuffer the storage buffer to clear
+     * @param byteOffset the byte offset to start clearing (optional)
+     * @param byteLength the byte length to clear (optional)
+     */
+    public clearStorageBuffer(storageBuffer: DataBuffer, byteOffset?: number, byteLength?: number): void {
+        this._renderEncoder.clearBuffer(storageBuffer.underlyingResource, byteOffset, byteLength);
+    }
+
     /**
      * Updates a storage buffer
      * @param buffer the storage buffer to update