@driftengine/core 4.7.2 → 4.7.4

package/src/render/clusteredLights.ts

@@ -69,8 +69,16 @@ export const MAX_LIGHTS_PER_CLUSTER = (CLUSTER_TEXELS - 1) * 4;
 export 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
@@ -109,6 +117,11 @@ export 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 const LIGHT_RECORD = {
   positionX: 0,
@@ -118,23 +131,101 @@ export const LIGHT_RECORD = {
   colorR: 4,
   colorG: 5,
   colorB: 6,
-  sourceRadius: 7,
-  weight: 8,
-  shadowSlot: 9,
-  directionX: 10,
-  directionY: 11,
-  directionZ: 12,
-  cosInner: 13,
-  cosOuter: 14,
-  iesProfile: 15,
+  /** The emitter size and the weight, two halves in one word, and the fixture flag. */
+  sizeAndWeight: 7,
+  shadowSlot: 8,
+  directionX: 9,
+  directionY: 10,
+  directionZ: 11,
+  cosInner: 12,
+  cosOuter: 13,
+  iesProfile: 14,
+  /** A tile of the cookie atlas, or negative for none. */
+  cookie: 15,
   /** The fixture's azimuth zero, in world space. See the note above on why it cannot be derived. */
   iesAxisX: 16,
   iesAxisY: 17,
   iesAxisZ: 18,
-  /** A tile of the cookie atlas, or negative for none. Slot 19, the one the fifth texel spared. */
-  cookie: 19,
 } as const;
 
+/** Texels the lit pass reads for a light whose record carries no fixture. */
+export 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 const LIGHT_FIXTURE_FLAG = 0x8000;
+
+const halfScratch = new Float32Array(1);
+const halfScratchBits = new Uint32Array(halfScratch.buffer);
+
+/**
+ * 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 function halfBits(value: number): number {
+  halfScratch[0] = value;
+  const x = halfScratchBits[0] ?? 0;
+  const sign = (x >>> 16) & 0x8000;
+  const exponent = (x >>> 23) & 0xff;
+  const mantissa = x & 0x7fffff;
+  if (exponent === 0xff) return sign | 0x7c00 | (mantissa === 0 ? 0 : 0x200);
+  const e = exponent - 127 + 15;
+  if (e >= 0x1f) return sign | 0x7c00;
+  if (e <= 0) return sign;
+  const truncated = (e << 10) | (mantissa >>> 13);
+  const rest = mantissa & 0x1fff;
+  /* A carry out of the mantissa lands in the exponent, which is the correct rounding up. */
+  const rounded =
+    rest > 0x1000 || (rest === 0x1000 && (truncated & 1) === 1) ? truncated + 1 : truncated;
+  return sign | rounded;
+}
+
+/** The number a half's bits hold. Exact: every half is also a float. */
+export function halfValue(half: number): number {
+  const sign = (half & 0x8000) === 0 ? 1 : -1;
+  const exponent = (half >>> 10) & 0x1f;
+  const mantissa = half & 0x3ff;
+  if (exponent === 0) return sign * mantissa * 2 ** -24;
+  if (exponent === 0x1f) return mantissa === 0 ? sign * Infinity : Number.NaN;
+  return sign * (1 + mantissa / 1024) * 2 ** (exponent - 15);
+}
+
+/**
+ * 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 function lampSourceRadius(value: number): number {
+  return halfValue(halfBits(Math.abs(value)));
+}
+
+/** A lamp's weight as both arms read it: at half precision, sign kept. See `lampSourceRadius`. */
+export function lampWeight(value: number): number {
+  return halfValue(halfBits(value));
+}
+
+/**
+ * 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 function packSizeAndWeight(sourceRadius: number, weight: number, fixture: boolean): number {
+  const size = halfBits(Math.abs(sourceRadius)) & 0x7fff;
+  return ((halfBits(weight) << 16) | size | (fixture ? LIGHT_FIXTURE_FLAG : 0)) >>> 0;
+}
+
 /**
  * The cone a light with no cone has: one that admits every direction, exactly.
  *
@@ -312,6 +403,71 @@ export interface ClusterLightSet {
   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] };
+
+/** No emitter size at all, which is what the fixed arm reads for a light that was given none. */
+const NO_SOURCE_SIZES = new Float32Array(0);
+
+export function createClusterLightSet(): ClusterLightScratch {
+  return {
+    count: 0,
+    positions: NO_SOURCE_SIZES,
+    colors: NO_SOURCE_SIZES,
+    radii: NO_SOURCE_SIZES,
+    sourceRadii: NO_SOURCE_SIZES,
+    weights: NO_SOURCE_SIZES,
+  };
+}
+
+/**
+ * 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 function fillClusterLightSet(
+  env: ClusterLightArrays,
+  out: ClusterLightScratch,
+): ClusterLightSet {
+  out.count = Math.min(env.lightCount ?? 0, MAX_CLUSTERED_LIGHTS);
+  out.positions = env.lightPositions;
+  out.colors = env.lightColors;
+  out.radii = env.lightRadii;
+  out.sourceRadii = env.lightSourceRadii ?? NO_SOURCE_SIZES;
+  out.weights = env.lightWeights;
+  out.directions = env.lightDirections;
+  out.coneCos = env.lightConeCos;
+  out.iesProfiles = env.lightIesProfiles;
+  out.iesAxes = env.lightIesAxes;
+  out.cookies = env.lightCookies;
+  return out;
+}
+
 /*
  * Scratch, at module scope, because `buildLightClusters` runs per frame on WebGL2 and the house
  * rule forbids allocating there.
@@ -357,6 +513,108 @@ function distanceSqToBounds(x: number, y: number, z: number, b: Float32Array): n
   return dx * dx + dy * dy + dz * dz;
 }
 
+/**
+ * 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 function lightHasFixture(
+  lights: ClusterLightSet,
+  light: number,
+  shadowSlots: number,
+): boolean {
+  const cone = lights.coneCos;
+  return (
+    light < shadowSlots ||
+    (cone?.[light * 2] ?? POINT_LIGHT_COS_INNER) !== POINT_LIGHT_COS_INNER ||
+    (cone?.[light * 2 + 1] ?? POINT_LIGHT_COS_OUTER) !== POINT_LIGHT_COS_OUTER ||
+    (lights.iesProfiles?.[light] ?? NO_IES_PROFILE) >= 0 ||
+    (lights.cookies?.[light] ?? NO_IES_PROFILE) >= 0
+  );
+}
+
+/**
+ * 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 function clusteredMode(lights: ClusterLightSet, count: number, shadowSlots: number): 1 | 2 {
+  for (let light = 0; light < count; light++) {
+    if (lightHasFixture(lights, light, shadowSlots)) return 2;
+  }
+  return 1;
+}
+
+/**
+ * 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 function writeLightRecord(
+  lights: ClusterLightSet,
+  light: number,
+  shadowSlots: number,
+  out: Uint32Array,
+  at: number,
+): void {
+  const directions = lights.directions;
+  const cone = lights.coneCos;
+  const axes = lights.iesAxes;
+  const shadowSlot = light < shadowSlots ? light : NO_SHADOW_SLOT;
+  const cosInner = cone?.[light * 2] ?? POINT_LIGHT_COS_INNER;
+  const cosOuter = cone?.[light * 2 + 1] ?? POINT_LIGHT_COS_OUTER;
+  const profile = lights.iesProfiles?.[light] ?? NO_IES_PROFILE;
+  const cookie = lights.cookies?.[light] ?? NO_IES_PROFILE;
+  const fixture = lightHasFixture(lights, light, shadowSlots);
+
+  out[at + LIGHT_RECORD.positionX] = floatBits(lights.positions[light * 3] ?? 0);
+  out[at + LIGHT_RECORD.positionY] = floatBits(lights.positions[light * 3 + 1] ?? 0);
+  out[at + LIGHT_RECORD.positionZ] = floatBits(lights.positions[light * 3 + 2] ?? 0);
+  out[at + LIGHT_RECORD.radius] = floatBits(lights.radii[light] ?? 0);
+  out[at + LIGHT_RECORD.colorR] = floatBits(lights.colors[light * 3] ?? 0);
+  out[at + LIGHT_RECORD.colorG] = floatBits(lights.colors[light * 3 + 1] ?? 0);
+  out[at + LIGHT_RECORD.colorB] = floatBits(lights.colors[light * 3 + 2] ?? 0);
+  out[at + LIGHT_RECORD.sizeAndWeight] = packSizeAndWeight(
+    lights.sourceRadii[light] ?? 0,
+    lights.weights[light] ?? 1,
+    fixture,
+  );
+  out[at + LIGHT_RECORD.shadowSlot] = floatBits(shadowSlot);
+  /* A light that declared no cone gets the one that admits everything; see the constants. */
+  out[at + LIGHT_RECORD.directionX] = floatBits(directions?.[light * 3] ?? 0);
+  out[at + LIGHT_RECORD.directionY] = floatBits(directions?.[light * 3 + 1] ?? 0);
+  out[at + LIGHT_RECORD.directionZ] = floatBits(directions?.[light * 3 + 2] ?? 0);
+  out[at + LIGHT_RECORD.cosInner] = floatBits(cosInner);
+  out[at + LIGHT_RECORD.cosOuter] = floatBits(cosOuter);
+  out[at + LIGHT_RECORD.iesProfile] = floatBits(profile);
+  out[at + LIGHT_RECORD.cookie] = floatBits(cookie);
+  /* Zero where a consumer gave none, which the shader reads as "no usable reference" and falls
+     back to the first plane, the behaviour every symmetric profile has anyway. */
+  out[at + LIGHT_RECORD.iesAxisX] = floatBits(axes?.[light * 3] ?? 0);
+  out[at + LIGHT_RECORD.iesAxisY] = floatBits(axes?.[light * 3 + 1] ?? 0);
+  out[at + LIGHT_RECORD.iesAxisZ] = floatBits(axes?.[light * 3 + 2] ?? 0);
+  out[at + 19] = 0;
+}
+
 /**
  * Fill the table with this frame's light assignment, and answer how many lights it carried.
  *
@@ -434,51 +692,7 @@ export function buildLightClusters(
     const radius = lights.radii[light] ?? 0;
 
     /* The record, as the shader reads it. World space; see the note above. */
-    const record = lightBase(light);
-    table[record] = floatBits(x);
-    table[record + 1] = floatBits(y);
-    table[record + 2] = floatBits(z);
-    table[record + 3] = floatBits(radius);
-    table[record + 4] = floatBits(lights.colors[light * 3] ?? 0);
-    table[record + 5] = floatBits(lights.colors[light * 3 + 1] ?? 0);
-    table[record + 6] = floatBits(lights.colors[light * 3 + 2] ?? 0);
-    table[record + 7] = floatBits(lights.sourceRadii[light] ?? 0);
-    table[record + 8] = floatBits(lights.weights[light] ?? 1);
-    /*
-     * Signed, and carried as a float's bits like everything else in the record so the shader
-     * reads the whole texel one way. The first `MAX_POINT_LIGHTS` lights keep the shadow slots
-     * they already have — `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.
-     */
-    table[record + LIGHT_RECORD.shadowSlot] = floatBits(
-      light < shadowSlots ? light : NO_SHADOW_SLOT,
-    );
-
-    /*
-     * The cone, and a light that declared none gets the one that admits everything. Written for
-     * every light rather than only for spots, because the shader reads the same six slots either
-     * way and a record left at whatever the last frame put there is a cone nobody asked for.
-     */
-    const cone = lights.coneCos;
-    const directions = lights.directions;
-    const iesAxes = lights.iesAxes;
-    table[record + LIGHT_RECORD.directionX] = floatBits(directions?.[light * 3] ?? 0);
-    table[record + LIGHT_RECORD.directionY] = floatBits(directions?.[light * 3 + 1] ?? 0);
-    table[record + LIGHT_RECORD.directionZ] = floatBits(directions?.[light * 3 + 2] ?? 0);
-    table[record + LIGHT_RECORD.cosInner] = floatBits(cone?.[light * 2] ?? POINT_LIGHT_COS_INNER);
-    table[record + LIGHT_RECORD.cosOuter] = floatBits(
-      cone?.[light * 2 + 1] ?? POINT_LIGHT_COS_OUTER,
-    );
-    table[record + LIGHT_RECORD.iesProfile] = floatBits(
-      lights.iesProfiles?.[light] ?? NO_IES_PROFILE,
-    );
-    /* Zero where a consumer gave none, which the shader reads as "no usable reference" and falls
-       back to the first plane — the behaviour every symmetric profile has anyway. */
-    table[record + LIGHT_RECORD.iesAxisX] = floatBits(iesAxes?.[light * 3] ?? 0);
-    table[record + LIGHT_RECORD.iesAxisY] = floatBits(iesAxes?.[light * 3 + 1] ?? 0);
-    table[record + LIGHT_RECORD.iesAxisZ] = floatBits(iesAxes?.[light * 3 + 2] ?? 0);
-    table[record + LIGHT_RECORD.cookie] = floatBits(lights.cookies?.[light] ?? NO_IES_PROFILE);
+    writeLightRecord(lights, light, shadowSlots, table, lightBase(light));
 
     /* Column-major, as gl-matrix builds it. The view looks down -z, so depth is -vz. */
     const vx = (view[0] ?? 0) * x + (view[4] ?? 0) * y + (view[8] ?? 0) * z + (view[12] ?? 0);

package/src/render/lightBudget.ts

@@ -1,7 +1,12 @@
 /** Fixed point-light budget shared by CPU selection and the flat shader. */
 import type { AreaLightBuffer } from './areaLights.ts';
 import type { ResolvedAreaShadows } from './areaShadowSet.ts';
-import { POINT_LIGHT_COS_INNER, POINT_LIGHT_COS_OUTER } from './clusteredLights.ts';
+import {
+  POINT_LIGHT_COS_INNER,
+  POINT_LIGHT_COS_OUTER,
+  lampSourceRadius,
+  lampWeight,
+} from './clusteredLights.ts';
 
 /**
  * How many point lights the shading pass shades against at once.
@@ -531,6 +536,14 @@ export interface ResolvedPointLights {
   iesProfiles: Float32Array;
   iesAxes: Float32Array;
   cookies: Float32Array;
+  /**
+   * Owned, `MAX_POINT_LIGHTS` long: the emitter sizes and weights as the froxel record carries
+   * them, at half precision. `sourceRadii` and `weights` point here once a light set resolves, so
+   * a lamp on the uniform path and the same lamp in the table shade with the same numbers. See
+   * `lampSourceRadius`.
+   */
+  readonly heldSourceRadii: Float32Array;
+  readonly heldWeights: Float32Array;
 }
 
 /** One per GL binder, refilled per call: holds references, allocates nothing. */
@@ -547,6 +560,8 @@ const glLights: ResolvedPointLights = {
   iesProfiles: NO_PROFILES,
   iesAxes: NO_IES_AXES,
   cookies: NO_COOKIES,
+  heldSourceRadii: new Float32Array(MAX_POINT_LIGHTS),
+  heldWeights: new Float32Array(MAX_POINT_LIGHTS),
 };
 
 /**
@@ -659,8 +674,13 @@ export function resolvePointLights(
   out.positions = positions;
   out.colors = colors;
   out.radii = radii;
-  out.sourceRadii = sourceRadii;
-  out.weights = weights;
+  /* Rounded as the clustered record rounds them; see `heldSourceRadii`. */
+  for (let light = 0; light < MAX_POINT_LIGHTS; light++) {
+    out.heldSourceRadii[light] = lampSourceRadius(sourceRadii[light] ?? 0);
+    out.heldWeights[light] = lampWeight(weights[light] ?? 1);
+  }
+  out.sourceRadii = out.heldSourceRadii;
+  out.weights = out.heldWeights;
   out.directions = directions;
   out.coneCos = coneCos;
   out.iesProfiles = iesProfiles;

package/src/render/mesh.ts

@@ -30,8 +30,6 @@ import { validateMeshData } from '@driftengine/drft';
  * well. Both halves are fixed — `flat.ts` normalises the lobe, and this is the width that
  * actually matches.
  */
-/* The engine's fixed lobe, stated once in `vertexDefaults.ts` so both backends read one number. */
-const DEFAULT_ROUGHNESS = ABSENT_ATTRIBUTE['roughness']?.[0] ?? 0.4277;
 
 /** Attribute locations are fixed engine-wide (`layout(location = n)` in GLSL). */
 const ATTR_POSITION = 0;

package/src/render/plumeRenderer.ts

@@ -62,39 +62,9 @@ export interface PlumeOptions {
   tint?: Vec3;
 }
 
-/**
- * Blades in each plume's cross, and the vertices that costs.
- *
- * **Two, crossed at 90°, instead of one card turned to face the viewer.** A single
- * billboard has no three-dimensional structure to see: orbiting a fire showed the
- * identical silhouette from every angle, because every card shared one camera-derived
- * axis and the whole plume swivelled as a sheet. Reported twice: the fire did not read
- * as three-dimensional, it read as something that moved with the camera — and after a
- * first attempt that only *leaned* edge-on cards toward the viewer, it still did,
- * correctly, because leaning still rotates whichever cards are edge-on, so the ensemble
- * still tracks the viewer.
- *
- * A cross cannot track anything: both blades are fixed in world space, so turning
- * around a fire genuinely brings one broadside as the other goes edge-on, which is
- * the parallax a volume has. It also removes the reason billboarding existed — a
- * blade going edge-on no longer vanishes, because its partner is square-on at that
- * exact moment.
- *
- * Two rather than three because the plumes blend additively and are drawn in
- * quantity: the third blade costs 50% more geometry for a difference the eye does not
- * separate at the sizes these are drawn.
- */
-const BLADES = 2;
 /* The shared count, so both backends step a plume's vertices the same way. */
 const VERTS_PER_PLUME = PLUME_VERTS;
 
-const CORNERS = [
-  [-1, -1],
-  [1, -1],
-  [1, 1],
-  [-1, 1],
-] as const;
-
 export class PlumeRenderer {
   private readonly program: WebGLProgram;
   private readonly uniforms: Record<string, WebGLUniformLocation>;

package/src/render/shaders/flat/main.ts

@@ -939,7 +939,7 @@ export const MAIN_GLSL = `void main() {
     int clusterBaseTexel = LIGHT_REGION_TEXELS
       + (clusterTileX + clusterTileY * CLUSTER_X + clusterSlice * CLUSTER_X * CLUSTER_Y)
         * CLUSTER_TEXELS;
-    int clusterLights = uClustered == 1 ? int(clusterTexel(clusterBaseTexel).x) : 0;
+    int clusterLights = uClustered != 0 ? int(clusterTexel(clusterBaseTexel).x) : 0;
 
     /* The fixture atlas's size, asked once: its cookie band and its profile rows are found from it. */
     vec2 fixtureSize = vec2(textureSize(uFixtureAtlas, 0));
@@ -968,7 +968,7 @@ export const MAIN_GLSL = `void main() {
       float iesProfile;
       vec3 iesAxis;
       float cookie;
-      if (uClustered == 1) {
+      if (uClustered != 0) {
       if (slot >= clusterLights) break;
       /*
        * Four indices to a texel. Selected with compares rather than by indexing the vector,
@@ -983,32 +983,65 @@ export const MAIN_GLSL = `void main() {
       i = int(packed);
       int record = i * LIGHT_TEXELS;
       uvec4 rec0 = clusterTexel(record);
-      uvec4 rec1 = clusterTexel(record + 1);
-      uvec4 rec2 = clusterTexel(record + 2);
       lightPos = vec3(
         uintBitsToFloat(rec0.x), uintBitsToFloat(rec0.y), uintBitsToFloat(rec0.z));
       lightRadius = uintBitsToFloat(rec0.w);
+      /*
+       * **Out of reach is decided on the first texel, before the rest of the record is read.**
+       * A froxel holds every light whose sphere touches its box, so most of the lights a fragment
+       * walks never reach it, and each one used to cost all five texels before the falloff below
+       * said so. Both falloffs are zero at and past the radius, so this skips only lights the
+       * \`continue\` after the falloff would have skipped anyway: 17.5 ms of a 4K main pass with
+       * 320 lamps was 12.3 with this and the profile guard below, byte for byte the same picture.
+       */
+      if (length(lightPos - vWorldPos) >= lightRadius) continue;
+      /*
+       * **The second texel, and for a plain point light the last one.** The emitter size and the
+       * weight are two halves in one word, which is how nine numbers fit in two texels;
+       * \`unpackHalf2x16\` widens them exactly, and the fixed arm reads the same two values rounded
+       * the same way, so the arms stay one picture. See \`packSizeAndWeight\`.
+       */
+      uvec4 rec1 = clusterTexel(record + 1);
       lightColor = vec3(
         uintBitsToFloat(rec1.x), uintBitsToFloat(rec1.y), uintBitsToFloat(rec1.z));
-      lightSourceRadius = uintBitsToFloat(rec1.w);
-      lightWeight = uintBitsToFloat(rec2.x);
-      shadowSlot = int(uintBitsToFloat(rec2.y));
+      vec2 sizeAndWeight = unpackHalf2x16(rec1.w);
+      lightSourceRadius = abs(sizeAndWeight.x);
+      lightWeight = sizeAndWeight.y;
       /*
-       * The fourth texel, which is the cone. See LIGHT_RECORD in clusteredLights.ts: the
-       * direction spans rec2.z, rec2.w and rec3.x, because the record is a run of floats rather
-       * than a struct and a vec3 does not respect texel boundaries.
+       * **The fixture, read only for a light that has one.** What a plain light's record holds in
+       * the last three texels is exactly these values, so a light carrying no shadow slot, cone,
+       * profile or cookie shades the same whether they are read or assumed, and at heavy overlap
+       * reading them was a third of the pass. A branch on a value from a texture around
+       * \`texelFetch\` is not the 2026-08-07 case: an integer fetch takes no derivative.
+       *
+       * **Inside a branch on \`uClustered\` first**, which is 2 only in a frame where some light
+       * carries a fixture. The test on each light's flag is a branch on a value read from a
+       * texture, which a compiler may run both sides of, and it cost 1.3 ms of a 4K pass whose 320
+       * lamps were all plain; a uniform branch costs nothing, so such a frame never reaches it.
        */
-      uvec4 rec3 = clusterTexel(record + 3);
-      lightDir = vec3(
-        uintBitsToFloat(rec2.z), uintBitsToFloat(rec2.w), uintBitsToFloat(rec3.x));
-      lightCone = vec2(uintBitsToFloat(rec3.y), uintBitsToFloat(rec3.z));
-      iesProfile = uintBitsToFloat(rec3.w);
-      /* The fifth texel, which is the photometric azimuth. See LIGHT_RECORD in clusteredLights.ts
-         for why it costs a texel rather than being derived from the direction. */
-      uvec4 rec4 = clusterTexel(record + 4);
-      iesAxis = vec3(
-        uintBitsToFloat(rec4.x), uintBitsToFloat(rec4.y), uintBitsToFloat(rec4.z));
-      cookie = uintBitsToFloat(rec4.w);
+      shadowSlot = -1;
+      lightDir = vec3(0.0);
+      lightCone = vec2(-1.0, -2.0);
+      iesProfile = -1.0;
+      iesAxis = vec3(0.0);
+      cookie = -1.0;
+      if (uClustered == 2) {
+        if ((rec1.w & LIGHT_FIXTURE_FLAG) != 0u) {
+          uvec4 rec2 = clusterTexel(record + 2);
+          uvec4 rec3 = clusterTexel(record + 3);
+          uvec4 rec4 = clusterTexel(record + 4);
+          shadowSlot = int(uintBitsToFloat(rec2.x));
+          lightDir = vec3(
+            uintBitsToFloat(rec2.y), uintBitsToFloat(rec2.z), uintBitsToFloat(rec2.w));
+          lightCone = vec2(uintBitsToFloat(rec3.x), uintBitsToFloat(rec3.y));
+          iesProfile = uintBitsToFloat(rec3.z);
+          cookie = uintBitsToFloat(rec3.w);
+          /* The photometric azimuth. See LIGHT_RECORD in clusteredLights.ts for why it costs a
+             texel rather than being derived from the direction. */
+          iesAxis = vec3(
+            uintBitsToFloat(rec4.x), uintBitsToFloat(rec4.y), uintBitsToFloat(rec4.z));
+        }
+      }
       } else {
       i = slot;
       if (i >= uLightCount || i >= MAX_LIGHTS) break;
@@ -1227,20 +1260,25 @@ export const MAIN_GLSL = `void main() {
        * and the result is selected afterwards with a \`mix\` on a compare — which is arithmetic
        * rather than control flow.
        *
-       * **What it costs** is one texture fetch per light per fragment on every scene, whether or
-       * not anything loaded a profile. **What would make it wrong** is a scene where that fetch is
-       * measurable against the shadow taps in the same loop, which would be a scene with many
-       * lights and no shadows at all — at which point the honest answer is a permutation flag, and
-       * \`ARCHITECTURE.md\` section 1 has the arithmetic for whether it earns one.
+       * **And skipped outright where nothing loaded a profile**, behind \`uIesAtlasRows\`, which is
+       * one while the atlas holds only its row of ones. A uniform is provably uniform control
+       * flow, so this branch is not the one the rule forbids. It was paid on every scene until a
+       * 4K frame of 320 lamps and no shadows measured it at 0.7 ms of the main pass, rising to
+       * 2.3 ms with the lamps overlapping, which is the scene this note used to say would make
+       * the fetch wrong. Every light then reads 1, which is what \`step(0.0, iesProfile)\` gave
+       * each of them anyway.
        */
       float iesRow = max(iesProfile, 0.0);
       /* The direction the fixture throws toward this fragment, which both angles are measured on. */
       vec3 iesRay = -toLight / max(dist, 1e-4);
       /* The angle from the fixture's axis, as a fraction of the 0-to-180 arc every row spans. */
-      float iesAngle = acos(clamp(dot(iesRay, lightDir), -1.0, 1.0));
-      /* Clamped to the row's first and last texel centres, which is what the edge clamp of a
-         texture exactly one row wide gave; the atlas can be wider now, with cookies beside it. */
-      float iesU = clamp(iesAngle / PI_IES * IES_WIDTH, 0.5, IES_WIDTH - 0.5) / fixtureSize.x;
+      float iesU = 0.0;
+      if (uIesAtlasRows > 1.0) {
+        float iesAngle = acos(clamp(dot(iesRay, lightDir), -1.0, 1.0));
+        /* Clamped to the row's first and last texel centres, which is what the edge clamp of a
+           texture exactly one row wide gave; the atlas can be wider now, with cookies beside it. */
+        iesU = clamp(iesAngle / PI_IES * IES_WIDTH, 0.5, IES_WIDTH - 0.5) / fixtureSize.x;
+      }
       /*
        * **The azimuth about the fixture's own axis**, behind a branch on a uniform so a scene whose
        * profiles are all axially symmetric pays none of this arithmetic. A \`uniform float\` is
@@ -1315,14 +1353,15 @@ export const MAIN_GLSL = `void main() {
        * version this replaced took two explicit fetches and a \`mix\`, and cost **18,315 gzipped
        * bytes on \`core-only\`** across the sixteen fragment permutations.
        */
-      float iesBase = iesRow * (uIesPlaneCount + 1.0);
-      /* The profiles are the atlas's bottom rows, below any cookies. */
-      float iesTop = fixtureSize.y - uIesAtlasRows;
-      float iesV = uIesAtlasRows <= 1.0
-        ? (iesTop + 0.5) / fixtureSize.y
-        : (iesTop + iesBase + iesTurns * uIesPlaneCount + 0.5) / fixtureSize.y;
-      float iesGain = textureLod(uFixtureAtlas, vec2(iesU, iesV), 0.0).r;
-      float photometric = mix(1.0, iesGain, step(0.0, iesProfile));
+      float photometric = 1.0;
+      if (uIesAtlasRows > 1.0) {
+        float iesBase = iesRow * (uIesPlaneCount + 1.0);
+        /* The profiles are the atlas's bottom rows, below any cookies. */
+        float iesTop = fixtureSize.y - uIesAtlasRows;
+        float iesV = (iesTop + iesBase + iesTurns * uIesPlaneCount + 0.5) / fixtureSize.y;
+        float iesGain = textureLod(uFixtureAtlas, vec2(iesU, iesV), 0.0).r;
+        photometric = mix(1.0, iesGain, step(0.0, iesProfile));
+      }
 
       float shape = (uLightFalloff == 1 ? falloff : falloff * falloff) * coneFalloff * photometric;
       glassGlow += lightColor * backNdl * shape * lightWeight * shaded * lampGlass;

package/src/render/shaders/flat/preamble.ts

@@ -6,6 +6,7 @@ import {
   CLUSTER_X,
   CLUSTER_Y,
   CLUSTER_Z,
+  LIGHT_FIXTURE_FLAG,
   LIGHT_REGION_TEXELS,
   LIGHT_TEXELS,
   MAX_LIGHTS_PER_CLUSTER,
@@ -659,6 +660,7 @@ uniform float uHighlightGain;
 #define CLUSTER_TEXELS ${CLUSTER_TEXELS}
 #define MAX_LIGHTS_PER_CLUSTER ${MAX_LIGHTS_PER_CLUSTER}
 #define LIGHT_TEXELS ${LIGHT_TEXELS}
+#define LIGHT_FIXTURE_FLAG ${LIGHT_FIXTURE_FLAG}u
 #define LIGHT_REGION_TEXELS ${LIGHT_REGION_TEXELS}
 #define CLUSTER_TABLE_WIDTH ${TABLE_WIDTH}
 uniform highp usampler2D uClusterTable;  // wgsl:share shadow