@driftengine/core 4.7.2 → 4.7.3

package/CHANGELOG.json

@@ -1,4 +1,20 @@
 [
+  {
+    "version": "4.7.3",
+    "date": "2026-10-02",
+    "entries": [
+      {
+        "kind": "fixed",
+        "short": "Clustered lighting at high resolution costs about a third less: a light out of reach is skipped after one texel, and a plain point light is read in two of its record's five.",
+        "text": "**The lit pass decides a clustered light is out of reach on the first texel of its record**, before reading the rest, and skips the photometric lookup when no profile is loaded. **A plain point light's emitter size and weight share one word as two halves**, so it is read in two texels of five; a light with a shadow slot, a cone, a profile or a cookie reads the other three, and only in a frame that has one. The uniform arm rounds size and weight the same way, so the two arms still draw one picture, and scenes of plain lights are byte-identical to 4.7.2 on both backends. At 3840 by 2160 with 320 lamps the main pass went from 17.5 to 12.0 ms at radius 8, from 26.2 to 17.2 at radius 12 and from 34.8 to 25.1 at radius 24, on WebGPU; building the clusters was 0.15 ms of the first. `demo/dev/clusterStress.html` is the workload and `scripts/cluster-stress.mjs` times every pass of it."
+      },
+      {
+        "kind": "fixed",
+        "short": "With clustered lights on, spots, photometric profiles and cookies shade as they do with it off: both renderers had been handing the binner every light as a plain point light.",
+        "text": "**Both renderers built the clustered light set from five arrays** and left out the direction, the cone, the profile, its axis and the cookie, so the record and the shader were right and the fixture never arrived: every spot lit the scene as a bare bulb. On a page holding one spot with a profile and a cookie the two arms differed by 357,706 pixels, and now differ by none on either backend. `fillClusterLightSet` is the one assembly both use. **A light given no emitter size now has none on both arms**, where the clustered arm read the light's radius in its place and widened every highlight it laid on a specular surface."
+      }
+    ]
+  },
   {
     "version": "4.7.2",
     "date": "2026-10-02",

package/dist/render/backend/webgl2/renderer.js

@@ -21,7 +21,7 @@ import { batchBoxVisible, cullsInstances } from '../../instanceCull.js';
 import { OcclusionBuffer } from '../../occlusion.js';
 import { boundsVisible } from '../../visibility.js';
 import { createPassRegistry, drainRegistry, passAt, registerIn, unregisterIn } from '../../pass.js';
-import { MAX_CLUSTERED_LIGHTS, TABLE_HEIGHT, TABLE_WIDTH, buildLightClusters, createClusterTable, } from '../../clusteredLights.js';
+import { TABLE_HEIGHT, TABLE_WIDTH, buildLightClusters, clusteredMode, createClusterLightSet, createClusterTable, fillClusterLightSet, } from '../../clusteredLights.js';
 import { clamp } from '../../../math/scalar.js';
 import { attachContextLoss } from '../../contextLoss.js';
 import { isWeakGpuFamily, webgl2RendererName } from '../../gpuCapability.js';
@@ -1464,14 +1464,7 @@ export class WebGL2Renderer {
     clusterTexture = null;
     clusterTable = null;
     /** Refilled per frame; holds references and allocates nothing. See `resolvePointLights`. */
-    clusterLights = {
-        count: 0,
-        positions: new Float32Array(0),
-        colors: new Float32Array(0),
-        radii: new Float32Array(0),
-        sourceRadii: new Float32Array(0),
-        weights: new Float32Array(0),
-    };
+    clusterLights = createClusterLightSet();
     /** near, far, tan(fovY/2), aspect — written per frame, uploaded as one vec4. */
     clusterFrustum = new Float32Array(4);
     /**
@@ -1605,13 +1598,9 @@ export class WebGL2Renderer {
         gl.uniform4fv(u['uClusterFrustum'] ?? null, this.clusterFrustum);
         gl.uniformMatrix4fv(u['uView'] ?? null, false, camera.view);
         this.clusterTable ??= createClusterTable();
-        const lights = this.clusterLights;
-        lights.count = Math.min(env.lightCount ?? 0, MAX_CLUSTERED_LIGHTS);
-        lights.positions = env.lightPositions;
-        lights.colors = env.lightColors;
-        lights.radii = env.lightRadii;
-        lights.sourceRadii = env.lightSourceRadii ?? env.lightRadii;
-        lights.weights = env.lightWeights;
+        const lights = fillClusterLightSet(env, this.clusterLights);
+        /* A slot is read only under `POINT_SHADOWS`; see `lightHasFixture`. */
+        const shadowSlots = this.quality.pointShadows ? this.lightBudget.maxLights : 0;
         buildLightClusters(lights, camera.view, near, far, tanHalfFovY, aspect, this.clusterTable, 
         /*
          * The budget this renderer's shader was built at, not the engine's own. A froxel record
@@ -1620,7 +1609,8 @@ export class WebGL2Renderer {
          * to name, and saying so here is what stops the shader having to discover it. The shader
          * guards the read as well, for a build that reaches it another way.
          */
-        this.lightBudget.maxLights);
+        shadowSlots);
+        gl.uniform1i(u['uClustered'] ?? null, clusteredMode(lights, lights.count, shadowSlots));
         gl.texSubImage2D(gl.TEXTURE_2D, 0, 0, 0, TABLE_WIDTH, TABLE_HEIGHT, gl.RGBA_INTEGER, gl.UNSIGNED_INT, this.clusterTable);
     }
     /**

package/dist/render/backend/webgpu/clusterBinner.js

@@ -1,4 +1,4 @@
-import { CLUSTER_COUNT, LIGHT_RECORD, LIGHT_TEXELS, NO_IES_PROFILE, POINT_LIGHT_COS_INNER, POINT_LIGHT_COS_OUTER, MAX_CLUSTERED_LIGHTS, TABLE_HEIGHT, TABLE_WIDTH, } from '../../clusteredLights.js';
+import { CLUSTER_COUNT, LIGHT_TEXELS, MAX_CLUSTERED_LIGHTS, TABLE_HEIGHT, TABLE_WIDTH, writeLightRecord, } from '../../clusteredLights.js';
 import { MAX_POINT_LIGHTS } from '../../lightBudget.js';
 import { CLUSTER_BIN_WGSL } from './shaders/clusterBin.wgsl.js';
 /**
@@ -45,7 +45,8 @@ export class ClusterBinner {
     paramsStaging = new ArrayBuffer(PARAMS_BYTES);
     paramsFloats = new Float32Array(this.paramsStaging);
     paramsUints = new Uint32Array(this.paramsStaging);
-    lightStaging = new Float32Array(MAX_CLUSTERED_LIGHTS * LIGHT_TEXELS * 4);
+    /* The records as bits, because one slot holds two halves that must not pass through a float. */
+    lightStaging = new Uint32Array(MAX_CLUSTERED_LIGHTS * LIGHT_TEXELS * 4);
     frame = null;
     /** The table's view, for whoever binds it into the lit pass. Null before `init`. */
     get tableView() {
@@ -130,48 +131,11 @@ export class ClusterBinner {
             return;
         const count = Math.min(frame.lights.count, MAX_CLUSTERED_LIGHTS);
         /*
-         * The records, in exactly the order `buildLightClusters` writes them, because the shader
+         * The records, by the function `buildLightClusters` writes them with, because the shader
          * copies them into the table verbatim and the lit pass reads one layout on both backends.
          */
         for (let light = 0; light < count; light++) {
-            const at = light * LIGHT_TEXELS * 4;
-            this.lightStaging[at] = frame.lights.positions[light * 3] ?? 0;
-            this.lightStaging[at + 1] = frame.lights.positions[light * 3 + 1] ?? 0;
-            this.lightStaging[at + 2] = frame.lights.positions[light * 3 + 2] ?? 0;
-            this.lightStaging[at + 3] = frame.lights.radii[light] ?? 0;
-            this.lightStaging[at + 4] = frame.lights.colors[light * 3] ?? 0;
-            this.lightStaging[at + 5] = frame.lights.colors[light * 3 + 1] ?? 0;
-            this.lightStaging[at + 6] = frame.lights.colors[light * 3 + 2] ?? 0;
-            this.lightStaging[at + 7] = frame.lights.sourceRadii[light] ?? 0;
-            this.lightStaging[at + LIGHT_RECORD.weight] = frame.lights.weights[light] ?? 1;
-            this.lightStaging[at + LIGHT_RECORD.shadowSlot] = light < frame.shadowSlots ? light : -1;
-            /*
-             * The cone, addressed through `LIGHT_RECORD` rather than by number. Two writers fill this
-             * record — the CPU binner in `clusteredLights.ts` and this — and the 2026-08-17 rule is that
-             * two implementations of one decision drift invisibly when the constants are identical. They
-             * now read the same table of offsets, so a field can only move in both at once.
-             *
-             * `POINT_LIGHT_COS_OUTER` and its inner twin are what make a light with no cone collapse to
-             * exactly the arithmetic a point light had. `scripts/cluster-check.mjs` compares the two
-             * tables byte for byte and is what would catch this being wrong anyway.
-             */
-            const directions = frame.lights.directions;
-            const cone = frame.lights.coneCos;
-            this.lightStaging[at + LIGHT_RECORD.directionX] = directions?.[light * 3] ?? 0;
-            this.lightStaging[at + LIGHT_RECORD.directionY] = directions?.[light * 3 + 1] ?? 0;
-            this.lightStaging[at + LIGHT_RECORD.directionZ] = directions?.[light * 3 + 2] ?? 0;
-            this.lightStaging[at + LIGHT_RECORD.cosInner] = cone?.[light * 2] ?? POINT_LIGHT_COS_INNER;
-            this.lightStaging[at + LIGHT_RECORD.cosOuter] =
-                cone?.[light * 2 + 1] ?? POINT_LIGHT_COS_OUTER;
-            this.lightStaging[at + LIGHT_RECORD.iesProfile] =
-                frame.lights.iesProfiles?.[light] ?? NO_IES_PROFILE;
-            /* The azimuth reference an asymmetric profile is oriented by; zero where a consumer gave
-               none, which the shader reads as no usable reference and leaves on the first plane. */
-            const axes = frame.lights.iesAxes;
-            this.lightStaging[at + LIGHT_RECORD.iesAxisX] = axes?.[light * 3] ?? 0;
-            this.lightStaging[at + LIGHT_RECORD.iesAxisY] = axes?.[light * 3 + 1] ?? 0;
-            this.lightStaging[at + LIGHT_RECORD.iesAxisZ] = axes?.[light * 3 + 2] ?? 0;
-            this.lightStaging[at + LIGHT_RECORD.cookie] = frame.lights.cookies?.[light] ?? NO_IES_PROFILE;
+            writeLightRecord(frame.lights, light, frame.shadowSlots, this.lightStaging, light * LIGHT_TEXELS * 4);
         }
         this.paramsFloats.set(frame.view, 0);
         this.paramsFloats[16] = frame.near;

package/dist/render/backend/webgpu/renderer.js

@@ -131,7 +131,7 @@ import { OcclusionBuffer } from '../../occlusion.js';
 import { boundsVisible } from '../../visibility.js';
 import { createPassRegistry, drainRegistry, passAt, registerIn, unregisterIn } from '../../pass.js';
 import { ClusterBinner } from './clusterBinner.js';
-import { MAX_CLUSTERED_LIGHTS } from '../../clusteredLights.js';
+import { clusteredMode, createClusterLightSet, fillClusterLightSet, } from '../../clusteredLights.js';
 import { computeAt, createComputeRegistry, } from '../../compute.js';
 import { GpuInstancedBatch } from './instanced.js';
 import { cutoutOf } from '../../cutoutCaster.js';
@@ -4158,6 +4158,8 @@ export class WebGPURenderer {
         iesProfiles: new Float32Array(0),
         iesAxes: new Float32Array(0),
         cookies: new Float32Array(0),
+        heldSourceRadii: new Float32Array(MAX_POINT_LIGHTS),
+        heldWeights: new Float32Array(MAX_POINT_LIGHTS),
     };
     /** Refilled per frame rather than allocated; see `resolveAtmosphere`. */
     medium = {
@@ -11325,14 +11327,7 @@ export class WebGPURenderer {
     /** near, far, tan(fovY/2), aspect. Written per frame into the fragment block. */
     clusterFrustum = new Float32Array(4);
     /** Refilled per frame; holds references and allocates nothing. */
-    clusterLights = {
-        count: 0,
-        positions: new Float32Array(0),
-        colors: new Float32Array(0),
-        radii: new Float32Array(0),
-        sourceRadii: new Float32Array(0),
-        weights: new Float32Array(0),
-    };
+    clusterLights = createClusterLightSet();
     /**
      * Reused per dispatch rather than allocated, for the reason `passContext` gives beside it: a
      * fresh object per dispatch is an allocation on a per-frame path. The contract in
@@ -11422,13 +11417,10 @@ export class WebGPURenderer {
         f[frustumAt + 2] = tanHalfFovY;
         f[frustumAt + 3] = aspect;
         f.set(camera.view, at('uView'));
-        const set = this.clusterLights;
-        set.count = Math.min(env.lightCount ?? 0, MAX_CLUSTERED_LIGHTS);
-        set.positions = env.lightPositions;
-        set.colors = env.lightColors;
-        set.radii = env.lightRadii;
-        set.sourceRadii = env.lightSourceRadii ?? env.lightRadii;
-        set.weights = env.lightWeights;
+        const set = fillClusterLightSet(env, this.clusterLights);
+        /* A slot is read only under `POINT_SHADOWS`; see `lightHasFixture`. */
+        const shadowSlots = this.quality.pointShadows ? MAX_POINT_LIGHTS : 0;
+        i[at('uClustered')] = clusteredMode(set, set.count, shadowSlots);
         binner.setFrame({
             lights: set,
             view: camera.view,
@@ -11436,7 +11428,7 @@ export class WebGPURenderer {
             far,
             tanHalfFovY,
             aspect,
-            shadowSlots: MAX_POINT_LIGHTS,
+            shadowSlots,
         });
         this.dispatchCompute(this.clusterHandle);
     }

package/dist/render/backend/webgpu/shaders/clusterBin.wgsl.d.ts

@@ -20,4 +20,4 @@
  * sort. `scripts/cluster-check.mjs` is what holds that, and the 2026-08-17 rule about two
  * implementations of one decision is why it exists at all.
  */
-export declare const CLUSTER_BIN_WGSL = "\nconst CLUSTER_X: u32 = 16u;\nconst CLUSTER_Y: u32 = 9u;\nconst CLUSTER_Z: u32 = 24u;\nconst CLUSTER_COUNT: u32 = 3456u;\nconst CLUSTER_TEXELS: u32 = 20u;\nconst MAX_LIGHTS_PER_CLUSTER: u32 = 76u;\nconst LIGHT_TEXELS: u32 = 5u;\nconst LIGHT_REGION_TEXELS: u32 = 1600u;\nconst TABLE_WIDTH: u32 = 320u;\n\nstruct Params {\n  view: mat4x4<f32>,\n  /** near, far, tan(fovY/2), aspect. */\n  frustum: vec4<f32>,\n  lightCount: u32,\n  pad0: u32,\n  pad1: u32,\n  pad2: u32,\n}\n\n@group(0) @binding(0) var<uniform> params: Params;\n/** Three vec4s a light, in exactly the record order `buildLightClusters` writes. */\n@group(0) @binding(1) var<storage, read> lights: array<vec4<f32>>;\n/**\n * Write-only, which is all core WGSL offers and all the fixed-slot layout needs.\n *\n * A read-modify-write list would need a storage buffer and an atomic counter, and it is the reason\n * a cluster owns a fixed run rather than appending into a shared one.\n */\n@group(0) @binding(2) var table: texture_storage_2d<rgba32uint, write>;\n\n/** A flat texel index to its place in the table. TABLE_WIDTH divides both regions exactly. */\nfn texelAt(texel: u32) -> vec2<i32> {\n  return vec2<i32>(i32(texel % TABLE_WIDTH), i32(texel / TABLE_WIDTH));\n}\n\nfn sliceNearDepth(slice: f32) -> f32 {\n  return params.frustum.x * pow(params.frustum.y / params.frustum.x, slice / f32(CLUSTER_Z));\n}\n\n/** Squared distance from a point to an axis-aligned box, zero inside it. */\nfn distanceSqToBounds(p: vec3<f32>, lo: vec3<f32>, hi: vec3<f32>) -> f32 {\n  let d = max(max(lo - p, p - hi), vec3<f32>(0.0));\n  return dot(d, d);\n}\n\n/** A light's view-space centre, with depth positive along the view direction. */\nfn viewOf(light: u32) -> vec3<f32> {\n  let world = lights[light * LIGHT_TEXELS];\n  let v = params.view * vec4<f32>(world.xyz, 1.0);\n  return vec3<f32>(v.x, v.y, -v.z);\n}\n\n/**\n * Squared distance from a light's view-space centre to a point.\n *\n * **Squared, matching `centreDistanceSq` in `clusteredLights.ts` rather than taking a root.** The\n * ranking is identical either way, and a square root is one more operation for the two\n * implementations to round differently.\n */\nfn centreDistanceSq(light: u32, centre: vec3<f32>) -> f32 {\n  let d = viewOf(light) - centre;\n  return dot(d, d);\n}\n\n@compute @workgroup_size(64)\nfn main(@builtin(global_invocation_id) gid: vec3<u32>) {\n  let id = gid.x;\n\n  /*\n   * The light records, written by the first invocations that have one.\n   *\n   * **Two jobs in one kernel, and it is deliberate.** The records have to reach the same texture\n   * the clusters do, because the lit pass reads both through one texture unit; writing them from\n   * the CPU instead would mean a partial texture upload racing a dispatch over the same resource.\n   * There are always more clusters than lights, so every record has an invocation.\n   */\n  if (id < params.lightCount) {\n    let record = id * LIGHT_TEXELS;\n    for (var t: u32 = 0u; t < LIGHT_TEXELS; t = t + 1u) {\n      textureStore(table, texelAt(record + t), bitcast<vec4<u32>>(lights[record + t]));\n    }\n  }\n\n  if (id >= CLUSTER_COUNT) {\n    return;\n  }\n\n  let k = id / (CLUSTER_X * CLUSTER_Y);\n  let j = (id - k * CLUSTER_X * CLUSTER_Y) / CLUSTER_X;\n  let i = id - k * CLUSTER_X * CLUSTER_Y - j * CLUSTER_X;\n\n  /* The AABB of the froxel's eight corners, exactly as `clusterViewBounds` derives it. */\n  let zNear = sliceNearDepth(f32(k));\n  let zFar = sliceNearDepth(f32(k + 1u));\n  let xLo = -1.0 + 2.0 * f32(i) / f32(CLUSTER_X);\n  let xHi = -1.0 + 2.0 * f32(i + 1u) / f32(CLUSTER_X);\n  let yLo = -1.0 + 2.0 * f32(j) / f32(CLUSTER_Y);\n  let yHi = -1.0 + 2.0 * f32(j + 1u) / f32(CLUSTER_Y);\n  let halfHNear = zNear * params.frustum.z;\n  let halfHFar = zFar * params.frustum.z;\n  let halfWNear = halfHNear * params.frustum.w;\n  let halfWFar = halfHFar * params.frustum.w;\n\n  let lo = vec3<f32>(\n    min(min(xLo * halfWNear, xLo * halfWFar), min(xHi * halfWNear, xHi * halfWFar)),\n    min(min(yLo * halfHNear, yLo * halfHFar), min(yHi * halfHNear, yHi * halfHFar)),\n    zNear,\n  );\n  let hi = vec3<f32>(\n    max(max(xLo * halfWNear, xLo * halfWFar), max(xHi * halfWNear, xHi * halfWFar)),\n    max(max(yLo * halfHNear, yLo * halfHFar), max(yHi * halfHNear, yHi * halfHFar)),\n    zFar,\n  );\n  let centre = (lo + hi) * 0.5;\n\n  var indices: array<u32, MAX_LIGHTS_PER_CLUSTER>;\n  for (var n: u32 = 0u; n < MAX_LIGHTS_PER_CLUSTER; n = n + 1u) {\n    indices[n] = 0u;\n  }\n  var count: u32 = 0u;\n\n  /* Increasing light index, which is what makes the list sorted without a sort. */\n  for (var light: u32 = 0u; light < params.lightCount; light = light + 1u) {\n    let radius = lights[light * LIGHT_TEXELS].w;\n    let v = viewOf(light);\n    if (v.z + radius <= 0.0) {\n      continue;\n    }\n    if (distanceSqToBounds(v, lo, hi) > radius * radius) {\n      continue;\n    }\n\n    if (count < MAX_LIGHTS_PER_CLUSTER) {\n      indices[count] = light;\n      count = count + 1u;\n      continue;\n    }\n\n    /*\n     * Full. Drop the farthest from the cluster's centre if this one is nearer.\n     *\n     * **The only float comparison that decides anything here**, and the reason the *order* is an\n     * integer: a float rank cannot be relied on to agree between this and the JavaScript binner,\n     * so it is confined to membership, where the conformance script forgives a light sitting\n     * within epsilon of a boundary.\n     */\n    var worstSlot: i32 = -1;\n    var worst = centreDistanceSq(light, centre);\n    for (var n: u32 = 0u; n < MAX_LIGHTS_PER_CLUSTER; n = n + 1u) {\n      let d = centreDistanceSq(indices[n], centre);\n      if (d > worst) {\n        worst = d;\n        worstSlot = i32(n);\n      }\n    }\n    if (worstSlot < 0) {\n      continue;\n    }\n    indices[u32(worstSlot)] = light;\n\n    /* Insertion sort over at most 28 integers, so the bytes stay ascending after a replacement. */\n    for (var n: u32 = 1u; n < MAX_LIGHTS_PER_CLUSTER; n = n + 1u) {\n      let value = indices[n];\n      var m: i32 = i32(n) - 1;\n      while (m >= 0 && indices[u32(m)] > value) {\n        indices[u32(m) + 1u] = indices[u32(m)];\n        m = m - 1;\n      }\n      indices[u32(m + 1)] = value;\n    }\n  }\n\n  let base = LIGHT_REGION_TEXELS + id * CLUSTER_TEXELS;\n  textureStore(table, texelAt(base), vec4<u32>(count, 0u, 0u, 0u));\n  for (var t: u32 = 0u; t < CLUSTER_TEXELS - 1u; t = t + 1u) {\n    textureStore(\n      table,\n      texelAt(base + 1u + t),\n      vec4<u32>(indices[t * 4u], indices[t * 4u + 1u], indices[t * 4u + 2u], indices[t * 4u + 3u]),\n    );\n  }\n}\n";
+export declare const CLUSTER_BIN_WGSL = "\nconst CLUSTER_X: u32 = 16u;\nconst CLUSTER_Y: u32 = 9u;\nconst CLUSTER_Z: u32 = 24u;\nconst CLUSTER_COUNT: u32 = 3456u;\nconst CLUSTER_TEXELS: u32 = 20u;\nconst MAX_LIGHTS_PER_CLUSTER: u32 = 76u;\nconst LIGHT_TEXELS: u32 = 5u;\nconst LIGHT_REGION_TEXELS: u32 = 1600u;\nconst TABLE_WIDTH: u32 = 320u;\n\nstruct Params {\n  view: mat4x4<f32>,\n  /** near, far, tan(fovY/2), aspect. */\n  frustum: vec4<f32>,\n  lightCount: u32,\n  pad0: u32,\n  pad1: u32,\n  pad2: u32,\n}\n\n@group(0) @binding(0) var<uniform> params: Params;\n/**\n * The records as `writeLightRecord` lays them out, as bits. **`u32`, not `f32`**, because one\n * slot holds two halves, and a zero weight read as a float would be a subnormal a GPU is free to\n * flush on the way through; read as bits, the copy into the table cannot change them.\n */\n@group(0) @binding(1) var<storage, read> lights: array<vec4<u32>>;\n/**\n * Write-only, which is all core WGSL offers and all the fixed-slot layout needs.\n *\n * A read-modify-write list would need a storage buffer and an atomic counter, and it is the reason\n * a cluster owns a fixed run rather than appending into a shared one.\n */\n@group(0) @binding(2) var table: texture_storage_2d<rgba32uint, write>;\n\n/** A flat texel index to its place in the table. TABLE_WIDTH divides both regions exactly. */\nfn texelAt(texel: u32) -> vec2<i32> {\n  return vec2<i32>(i32(texel % TABLE_WIDTH), i32(texel / TABLE_WIDTH));\n}\n\nfn sliceNearDepth(slice: f32) -> f32 {\n  return params.frustum.x * pow(params.frustum.y / params.frustum.x, slice / f32(CLUSTER_Z));\n}\n\n/** Squared distance from a point to an axis-aligned box, zero inside it. */\nfn distanceSqToBounds(p: vec3<f32>, lo: vec3<f32>, hi: vec3<f32>) -> f32 {\n  let d = max(max(lo - p, p - hi), vec3<f32>(0.0));\n  return dot(d, d);\n}\n\n/** A light's view-space centre, with depth positive along the view direction. */\nfn viewOf(light: u32) -> vec3<f32> {\n  let world = bitcast<vec4<f32>>(lights[light * LIGHT_TEXELS]);\n  let v = params.view * vec4<f32>(world.xyz, 1.0);\n  return vec3<f32>(v.x, v.y, -v.z);\n}\n\n/**\n * Squared distance from a light's view-space centre to a point.\n *\n * **Squared, matching `centreDistanceSq` in `clusteredLights.ts` rather than taking a root.** The\n * ranking is identical either way, and a square root is one more operation for the two\n * implementations to round differently.\n */\nfn centreDistanceSq(light: u32, centre: vec3<f32>) -> f32 {\n  let d = viewOf(light) - centre;\n  return dot(d, d);\n}\n\n@compute @workgroup_size(64)\nfn main(@builtin(global_invocation_id) gid: vec3<u32>) {\n  let id = gid.x;\n\n  /*\n   * The light records, written by the first invocations that have one.\n   *\n   * **Two jobs in one kernel, and it is deliberate.** The records have to reach the same texture\n   * the clusters do, because the lit pass reads both through one texture unit; writing them from\n   * the CPU instead would mean a partial texture upload racing a dispatch over the same resource.\n   * There are always more clusters than lights, so every record has an invocation.\n   */\n  if (id < params.lightCount) {\n    let record = id * LIGHT_TEXELS;\n    for (var t: u32 = 0u; t < LIGHT_TEXELS; t = t + 1u) {\n      textureStore(table, texelAt(record + t), lights[record + t]);\n    }\n  }\n\n  if (id >= CLUSTER_COUNT) {\n    return;\n  }\n\n  let k = id / (CLUSTER_X * CLUSTER_Y);\n  let j = (id - k * CLUSTER_X * CLUSTER_Y) / CLUSTER_X;\n  let i = id - k * CLUSTER_X * CLUSTER_Y - j * CLUSTER_X;\n\n  /* The AABB of the froxel's eight corners, exactly as `clusterViewBounds` derives it. */\n  let zNear = sliceNearDepth(f32(k));\n  let zFar = sliceNearDepth(f32(k + 1u));\n  let xLo = -1.0 + 2.0 * f32(i) / f32(CLUSTER_X);\n  let xHi = -1.0 + 2.0 * f32(i + 1u) / f32(CLUSTER_X);\n  let yLo = -1.0 + 2.0 * f32(j) / f32(CLUSTER_Y);\n  let yHi = -1.0 + 2.0 * f32(j + 1u) / f32(CLUSTER_Y);\n  let halfHNear = zNear * params.frustum.z;\n  let halfHFar = zFar * params.frustum.z;\n  let halfWNear = halfHNear * params.frustum.w;\n  let halfWFar = halfHFar * params.frustum.w;\n\n  let lo = vec3<f32>(\n    min(min(xLo * halfWNear, xLo * halfWFar), min(xHi * halfWNear, xHi * halfWFar)),\n    min(min(yLo * halfHNear, yLo * halfHFar), min(yHi * halfHNear, yHi * halfHFar)),\n    zNear,\n  );\n  let hi = vec3<f32>(\n    max(max(xLo * halfWNear, xLo * halfWFar), max(xHi * halfWNear, xHi * halfWFar)),\n    max(max(yLo * halfHNear, yLo * halfHFar), max(yHi * halfHNear, yHi * halfHFar)),\n    zFar,\n  );\n  let centre = (lo + hi) * 0.5;\n\n  var indices: array<u32, MAX_LIGHTS_PER_CLUSTER>;\n  for (var n: u32 = 0u; n < MAX_LIGHTS_PER_CLUSTER; n = n + 1u) {\n    indices[n] = 0u;\n  }\n  var count: u32 = 0u;\n\n  /* Increasing light index, which is what makes the list sorted without a sort. */\n  for (var light: u32 = 0u; light < params.lightCount; light = light + 1u) {\n    let radius = bitcast<f32>(lights[light * LIGHT_TEXELS].w);\n    let v = viewOf(light);\n    if (v.z + radius <= 0.0) {\n      continue;\n    }\n    if (distanceSqToBounds(v, lo, hi) > radius * radius) {\n      continue;\n    }\n\n    if (count < MAX_LIGHTS_PER_CLUSTER) {\n      indices[count] = light;\n      count = count + 1u;\n      continue;\n    }\n\n    /*\n     * Full. Drop the farthest from the cluster's centre if this one is nearer.\n     *\n     * **The only float comparison that decides anything here**, and the reason the *order* is an\n     * integer: a float rank cannot be relied on to agree between this and the JavaScript binner,\n     * so it is confined to membership, where the conformance script forgives a light sitting\n     * within epsilon of a boundary.\n     */\n    var worstSlot: i32 = -1;\n    var worst = centreDistanceSq(light, centre);\n    for (var n: u32 = 0u; n < MAX_LIGHTS_PER_CLUSTER; n = n + 1u) {\n      let d = centreDistanceSq(indices[n], centre);\n      if (d > worst) {\n        worst = d;\n        worstSlot = i32(n);\n      }\n    }\n    if (worstSlot < 0) {\n      continue;\n    }\n    indices[u32(worstSlot)] = light;\n\n    /* Insertion sort over at most 28 integers, so the bytes stay ascending after a replacement. */\n    for (var n: u32 = 1u; n < MAX_LIGHTS_PER_CLUSTER; n = n + 1u) {\n      let value = indices[n];\n      var m: i32 = i32(n) - 1;\n      while (m >= 0 && indices[u32(m)] > value) {\n        indices[u32(m) + 1u] = indices[u32(m)];\n        m = m - 1;\n      }\n      indices[u32(m + 1)] = value;\n    }\n  }\n\n  let base = LIGHT_REGION_TEXELS + id * CLUSTER_TEXELS;\n  textureStore(table, texelAt(base), vec4<u32>(count, 0u, 0u, 0u));\n  for (var t: u32 = 0u; t < CLUSTER_TEXELS - 1u; t = t + 1u) {\n    textureStore(\n      table,\n      texelAt(base + 1u + t),\n      vec4<u32>(indices[t * 4u], indices[t * 4u + 1u], indices[t * 4u + 2u], indices[t * 4u + 3u]),\n    );\n  }\n}\n";

package/dist/render/backend/webgpu/shaders/clusterBin.wgsl.js

@@ -43,8 +43,12 @@ struct Params {
 }
 
 @group(0) @binding(0) var<uniform> params: Params;
-/** Three vec4s a light, in exactly the record order \`buildLightClusters\` writes. */
-@group(0) @binding(1) var<storage, read> lights: array<vec4<f32>>;
+/**
+ * The records as \`writeLightRecord\` lays them out, as bits. **\`u32\`, not \`f32\`**, because one
+ * slot holds two halves, and a zero weight read as a float would be a subnormal a GPU is free to
+ * flush on the way through; read as bits, the copy into the table cannot change them.
+ */
+@group(0) @binding(1) var<storage, read> lights: array<vec4<u32>>;
 /**
  * Write-only, which is all core WGSL offers and all the fixed-slot layout needs.
  *
@@ -70,7 +74,7 @@ fn distanceSqToBounds(p: vec3<f32>, lo: vec3<f32>, hi: vec3<f32>) -> f32 {
 
 /** A light's view-space centre, with depth positive along the view direction. */
 fn viewOf(light: u32) -> vec3<f32> {
-  let world = lights[light * LIGHT_TEXELS];
+  let world = bitcast<vec4<f32>>(lights[light * LIGHT_TEXELS]);
   let v = params.view * vec4<f32>(world.xyz, 1.0);
   return vec3<f32>(v.x, v.y, -v.z);
 }
@@ -102,7 +106,7 @@ fn main(@builtin(global_invocation_id) gid: vec3<u32>) {
   if (id < params.lightCount) {
     let record = id * LIGHT_TEXELS;
     for (var t: u32 = 0u; t < LIGHT_TEXELS; t = t + 1u) {
-      textureStore(table, texelAt(record + t), bitcast<vec4<u32>>(lights[record + t]));
+      textureStore(table, texelAt(record + t), lights[record + t]);
     }
   }
 
@@ -146,7 +150,7 @@ fn main(@builtin(global_invocation_id) gid: vec3<u32>) {
 
   /* Increasing light index, which is what makes the list sorted without a sort. */
   for (var light: u32 = 0u; light < params.lightCount; light = light + 1u) {
-    let radius = lights[light * LIGHT_TEXELS].w;
+    let radius = bitcast<f32>(lights[light * LIGHT_TEXELS].w);
     let v = viewOf(light);
     if (v.z + radius <= 0.0) {
       continue;

package/dist/render/clusteredLights.d.ts

@@ -63,8 +63,16 @@ export declare const MAX_LIGHTS_PER_CLUSTER: number;
  */
 export declare const MAX_CLUSTERED_LIGHTS = 320;
 /**
- * Texels one light's record occupies: position and radius, colour and emitter size, then the
- * weight and the shadow slot.
+ * Texels one light's record occupies: position and radius, then colour with the emitter size and
+ * the weight, then the shadow slot and the fixture: direction, cone, profile, cookie and azimuth.
+ *
+ * **A plain point light is read in two of the five.** The lit pass fetches this record once per
+ * light per fragment, and at eight megapixels with lights crowded together that fetch is the
+ * frame: 320 lamps of radius 12 cost 26.2 ms of a 4K main pass when all five texels were read for
+ * every light, and 12.7 ms read in two, on the RX 9070 XT `demo/dev/clusterStress.html` was
+ * measured on. So the second texel carries a flag, `LIGHT_FIXTURE_FLAG`, and the last three are
+ * fetched only for a light that has a shadow slot, a cone, a profile or a cookie. What a plain light
+ * would have read there is what the shader assumes in their place, so the picture is the same.
  *
  * **The shadow slot is an index into the existing sixteen-wide shadow uniforms, not a layer.**
  * Clustering lifts how many lights *shade* a fragment; it does not lift how many shadow maps
@@ -102,6 +110,11 @@ export declare const LIGHT_TEXELS = 5;
  * rotating through that direction would snap its pattern round. The two obvious constructions put
  * that singularity where these fixtures actually point: `cross(worldUp, dir)` fails for a light
  * aimed straight down, which is a street light.
+ *
+ * **Reordered 2026-10-02 so a plain light's fields are the first eight**, which is what lets the
+ * shader stop after two texels. Nine values are needed by every light and eight fit in two
+ * texels, so the emitter size and the weight share slot 7 as two halves; see `packSizeAndWeight`.
+ * Slot 19 is spare.
  */
 export declare const LIGHT_RECORD: {
     readonly positionX: 0;
@@ -111,22 +124,60 @@ export declare const LIGHT_RECORD: {
     readonly colorR: 4;
     readonly colorG: 5;
     readonly colorB: 6;
-    readonly sourceRadius: 7;
-    readonly weight: 8;
-    readonly shadowSlot: 9;
-    readonly directionX: 10;
-    readonly directionY: 11;
-    readonly directionZ: 12;
-    readonly cosInner: 13;
-    readonly cosOuter: 14;
-    readonly iesProfile: 15;
+    /** The emitter size and the weight, two halves in one word, and the fixture flag. */
+    readonly sizeAndWeight: 7;
+    readonly shadowSlot: 8;
+    readonly directionX: 9;
+    readonly directionY: 10;
+    readonly directionZ: 11;
+    readonly cosInner: 12;
+    readonly cosOuter: 13;
+    readonly iesProfile: 14;
+    /** A tile of the cookie atlas, or negative for none. */
+    readonly cookie: 15;
     /** The fixture's azimuth zero, in world space. See the note above on why it cannot be derived. */
     readonly iesAxisX: 16;
     readonly iesAxisY: 17;
     readonly iesAxisZ: 18;
-    /** A tile of the cookie atlas, or negative for none. Slot 19, the one the fifth texel spared. */
-    readonly cookie: 19;
 };
+/** Texels the lit pass reads for a light whose record carries no fixture. */
+export declare const PLAIN_LIGHT_TEXELS = 2;
+/**
+ * The bit of `sizeAndWeight` that says the record's last three texels hold something: the sign of
+ * the emitter size's half, which a size never needs.
+ */
+export declare const LIGHT_FIXTURE_FLAG = 32768;
+/**
+ * A number as the sixteen bits of an IEEE half: rounded to the nearest, ties to even.
+ *
+ * **Computed here, once, and copied by both binners rather than converted on the GPU.** WGSL and
+ * GLSL both leave the rounding of `pack2x16float` to the implementation, and two producers of one
+ * table that round differently would make `scripts/cluster-check.mjs` compare noise.
+ *
+ * **A value only a subnormal half could hold is flushed to a signed zero.** A GPU may flush a
+ * subnormal it unpacks, and the fixed arm reads the same value from a uniform where nothing would;
+ * flushing it here means both arms read zero. Nothing is lost that a pixel could show: the largest
+ * value flushed is 6.1e-5, a weight no lamp is visible at.
+ */
+export declare function halfBits(value: number): number;
+/** The number a half's bits hold. Exact: every half is also a float. */
+export declare function halfValue(half: number): number;
+/**
+ * A lamp's emitter size as both arms read it: its magnitude, at half precision.
+ *
+ * **The fixed arm is rounded too, and that is what keeps the two arms one picture.**
+ * `resolvePointLights` passes the sixteen uniform lights through this and `lampWeight`, so a light
+ * moved from the uniform path to the froxel table shades with the same numbers. A negative size was
+ * never meaningful and now reads as its magnitude on both.
+ */
+export declare function lampSourceRadius(value: number): number;
+/** A lamp's weight as both arms read it: at half precision, sign kept. See `lampSourceRadius`. */
+export declare function lampWeight(value: number): number;
+/**
+ * Slot 7 of a record: the emitter size's half in the low bits, the weight's in the high, and the
+ * fixture flag in the size's sign. The shader unpacks it with `unpackHalf2x16`, which is exact.
+ */
+export declare function packSizeAndWeight(sourceRadius: number, weight: number, fixture: boolean): number;
 /**
  * The cone a light with no cone has: one that admits every direction, exactly.
  *
@@ -220,6 +271,78 @@ export interface ClusterLightSet {
     /** One per light: an index into the IES atlas, or −1. */
     readonly iesProfiles?: Float32Array;
 }
+/** Where `fillClusterLightSet` reads a frame's lights from: the arrays `Environment` carries. */
+export interface ClusterLightArrays {
+    readonly lightCount?: number;
+    readonly lightPositions: Float32Array;
+    readonly lightColors: Float32Array;
+    readonly lightRadii: Float32Array;
+    readonly lightWeights: Float32Array;
+    readonly lightSourceRadii?: Float32Array;
+    readonly lightDirections?: Float32Array;
+    readonly lightConeCos?: Float32Array;
+    readonly lightIesProfiles?: Float32Array;
+    readonly lightIesAxes?: Float32Array;
+    readonly lightCookies?: Float32Array;
+}
+/** A `ClusterLightSet` a renderer refills every frame. */
+export type ClusterLightScratch = {
+    -readonly [K in keyof ClusterLightSet]: ClusterLightSet[K];
+};
+export declare function createClusterLightSet(): ClusterLightScratch;
+/**
+ * A frame's lights as the binner reads them, in place, holding references and allocating nothing.
+ *
+ * **One assembly for both renderers, and it used to be two that had each dropped the same five
+ * fields.** Each backend copied the position, colour, radius, size and weight arrays and nothing
+ * else, so a spot's direction and cone, a profile, its axis and a cookie never reached the record:
+ * with clustering on, every fixture shaded as a bare point light. On a probe page holding one
+ * spot with a profile and a cookie the two arms differed by 357,706 pixels, the clustered one
+ * flooding the scene the cone was meant to cut. The record and both shaders were right throughout;
+ * the light never arrived.
+ *
+ * **And a light given no emitter size has none**, as the fixed arm reads it. This read the light's
+ * radius in its place, an emitter as wide as the light reaches, which widened every lamp's
+ * highlight on a specular surface on the clustered arm alone.
+ */
+export declare function fillClusterLightSet(env: ClusterLightArrays, out: ClusterLightScratch): ClusterLightSet;
+/**
+ * Whether a light's record needs its last three texels: it holds a shadow slot, a cone, a profile
+ * or a cookie. Everything else is a plain light, read in `PLAIN_LIGHT_TEXELS`.
+ *
+ * **`shadowSlots` is zero where the lit shader has no point shadows**, and both binners are handed
+ * it that way: a slot is only read under `POINT_SHADOWS`, so a light holding one in a build without
+ * them was paying for three texels the shader then ignored.
+ */
+export declare function lightHasFixture(lights: ClusterLightSet, light: number, shadowSlots: number): boolean;
+/**
+ * The value of `uClustered` for a frame: 0 with clustering off, 1 when every light is plain, 2 when
+ * any carries a fixture.
+ *
+ * **The third state is a uniform the shader can branch on for free.** The flag test on each light is
+ * a branch on a value read from a texture, and a compiler may run both sides of one; 1.3 ms of a 4K
+ * main pass of 320 plain lamps was that test. Asked once a frame here, a scene whose lights are all
+ * plain never reaches it.
+ */
+export declare function clusteredMode(lights: ClusterLightSet, count: number, shadowSlots: number): 1 | 2;
+/**
+ * One light's record, at `at` in `out`, as the lit pass reads it.
+ *
+ * **The one writer.** The CPU binner calls this into the table and the GPU binner's staging calls
+ * it into the buffer its kernel copies verbatim, so a field can only move in both at once; the
+ * 2026-08-17 rule is that two implementations of one decision drift invisibly when the constants
+ * are identical, and these were two.
+ *
+ * **A light is plain unless it has a shadow slot, a cone, a profile or a cookie**, and then the
+ * flag is clear and the shader reads two texels. Every slot is still written, so a record holds no
+ * bytes from a light that was there last frame and the two binners' tables stay comparable.
+ *
+ * The shadow slot is signed and carried as a float's bits like everything else in the record. The
+ * first `MAX_POINT_LIGHTS` lights keep the shadow slots they already have, because
+ * `resolvePointLights` orders them so the ones worth shadowing come first, and everything past that
+ * is a light without a map, which is what a scene with two hundred lamps has anyway.
+ */
+export declare function writeLightRecord(lights: ClusterLightSet, light: number, shadowSlots: number, out: Uint32Array, at: number): void;
 /**
  * Fill the table with this frame's light assignment, and answer how many lights it carried.
  *