@driftengine/core 4.8.4 → 4.8.6

package/src/render/clusteredLights.ts

@@ -1,3 +1,5 @@
+import type { AreaLightBuffer } from './areaLights.ts';
+
 /**
  * The froxel table: what it looks like in memory, and the CPU binner that fills it.
  *
@@ -146,8 +148,29 @@ export const LIGHT_RECORD = {
   iesAxisX: 16,
   iesAxisY: 17,
   iesAxisZ: 18,
+  /**
+   * The light's lighting channels, a mask (`PointLightSet.lightChannels`), in the slot that was
+   * spare. A light naming channels other than the default is read as carrying a fixture, so its
+   * last texels are fetched; a plain light's are not, and the shader takes the default for it.
+   */
+  channels: 19,
 } as const;
 
+/** The lighting channel every light and every surface is on unless it says otherwise. */
+export const DEFAULT_LIGHT_CHANNELS = 1;
+
+/**
+ * A light's channels as the shader compares them: a whole mask from 1 to 255, or the default where
+ * none was named or what was named is not one. The froxel record and the uniform path both write
+ * this, so a light named badly is on channel 1 in both rather than on two different guesses.
+ */
+export function lightChannelsOf(value: number | undefined): number {
+  if (value === undefined || !Number.isInteger(value) || value < 1 || value > 255) {
+    return DEFAULT_LIGHT_CHANNELS;
+  }
+  return value;
+}
+
 /** Texels the lit pass reads for a light whose record carries no fixture. */
 export const PLAIN_LIGHT_TEXELS = 2;
 
@@ -401,6 +424,16 @@ export interface ClusterLightSet {
   readonly cookies?: Float32Array;
   /** One per light: an index into the IES atlas, or −1. */
   readonly iesProfiles?: Float32Array;
+  /** One per light: its lighting channels. See `PointLightSet.lightChannels`. */
+  readonly channels?: Float32Array;
+  /**
+   * The rectangles shaded through the table, after the `count` point lights: those of `areas` from
+   * `areaFrom` on, `areaCount` of them. The ones before `areaFrom` are the fixed arm's, which is
+   * where a rectangle's shadow lives. Absent, there are none.
+   */
+  readonly areas?: AreaLightBuffer | null;
+  readonly areaFrom?: number;
+  readonly areaCount?: number;
 }
 
 /** Where `fillClusterLightSet` reads a frame's lights from: the arrays `Environment` carries. */
@@ -416,6 +449,8 @@ export interface ClusterLightArrays {
   readonly lightIesProfiles?: Float32Array;
   readonly lightIesAxes?: Float32Array;
   readonly lightCookies?: Float32Array;
+  readonly lightChannels?: Float32Array;
+  readonly areaLights?: AreaLightBuffer | null;
 }
 
 /** A `ClusterLightSet` a renderer refills every frame. */
@@ -453,8 +488,17 @@ export function createClusterLightSet(): ClusterLightScratch {
 export function fillClusterLightSet(
   env: ClusterLightArrays,
   out: ClusterLightScratch,
+  /** How many rectangles the fixed arm shades; the rest of the buffer is clustered. */
+  areaFrom = 0,
 ): ClusterLightSet {
   out.count = Math.min(env.lightCount ?? 0, MAX_CLUSTERED_LIGHTS);
+  const areas = env.areaLights ?? null;
+  out.areas = areas;
+  out.areaFrom = areaFrom;
+  out.areaCount = Math.max(
+    0,
+    Math.min((areas?.count ?? 0) - areaFrom, MAX_CLUSTERED_LIGHTS - out.count),
+  );
   out.positions = env.lightPositions;
   out.colors = env.lightColors;
   out.radii = env.lightRadii;
@@ -465,6 +509,7 @@ export function fillClusterLightSet(
   out.iesProfiles = env.lightIesProfiles;
   out.iesAxes = env.lightIesAxes;
   out.cookies = env.lightCookies;
+  out.channels = env.lightChannels;
   return out;
 }
 
@@ -526,13 +571,16 @@ export function lightHasFixture(
   light: number,
   shadowSlots: number,
 ): boolean {
+  /* A rectangle's record always carries its axes and extents past the second texel. */
+  if (light >= lights.count) return true;
   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
+    (lights.cookies?.[light] ?? NO_IES_PROFILE) >= 0 ||
+    lightChannelsOf(lights.channels?.[light]) !== DEFAULT_LIGHT_CHANNELS
   );
 }
 
@@ -576,6 +624,10 @@ export function writeLightRecord(
   out: Uint32Array,
   at: number,
 ): void {
+  if (light >= lights.count) {
+    writeAreaRecord(lights, light, out, at);
+    return;
+  }
   const directions = lights.directions;
   const cone = lights.coneCos;
   const axes = lights.iesAxes;
@@ -612,7 +664,72 @@ export function writeLightRecord(
   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;
+  out[at + LIGHT_RECORD.channels] = floatBits(lightChannelsOf(lights.channels?.[light]));
+}
+
+/**
+ * Which rectangle of the area buffer clustered light `light` is, for a light past the point
+ * lights. See `ClusterLightSet.areas`.
+ */
+function areaSlot(lights: ClusterLightSet, light: number): number {
+  return (lights.areaFrom ?? 0) + light - lights.count;
+}
+
+/**
+ * A rectangle's record, which the shader tells from a lamp's by its **negative radius** — its
+ * reach, negated — and reads to its fifth texel: sidedness where a lamp keeps its shadow slot,
+ * the right axis where a spot keeps its direction, the half extents where its cone is, the up
+ * axis where the azimuth is, and the channels last. Never shadowed: a rectangle's occlusion is
+ * the fixed arm's, which is why the first `maxAreaLights` stay there.
+ */
+function writeAreaRecord(
+  lights: ClusterLightSet,
+  light: number,
+  out: Uint32Array,
+  at: number,
+): void {
+  const areas = lights.areas;
+  const a = areaSlot(lights, light);
+  const pos = areas?.positions;
+  const color = areas?.colors;
+  const right = areas?.right;
+  const up = areas?.up;
+  const sizes = areas?.sizes;
+  out[at + LIGHT_RECORD.positionX] = floatBits(pos?.[a * 3] ?? 0);
+  out[at + LIGHT_RECORD.positionY] = floatBits(pos?.[a * 3 + 1] ?? 0);
+  out[at + LIGHT_RECORD.positionZ] = floatBits(pos?.[a * 3 + 2] ?? 0);
+  out[at + LIGHT_RECORD.radius] = floatBits(-areaReach(lights, light));
+  out[at + LIGHT_RECORD.colorR] = floatBits(color?.[a * 3] ?? 0);
+  out[at + LIGHT_RECORD.colorG] = floatBits(color?.[a * 3 + 1] ?? 0);
+  out[at + LIGHT_RECORD.colorB] = floatBits(color?.[a * 3 + 2] ?? 0);
+  out[at + LIGHT_RECORD.sizeAndWeight] = packSizeAndWeight(0, 1, true);
+  out[at + LIGHT_RECORD.shadowSlot] = floatBits(areas?.twoSided[a] ?? 0);
+  out[at + LIGHT_RECORD.directionX] = floatBits(right?.[a * 3] ?? 1);
+  out[at + LIGHT_RECORD.directionY] = floatBits(right?.[a * 3 + 1] ?? 0);
+  out[at + LIGHT_RECORD.directionZ] = floatBits(right?.[a * 3 + 2] ?? 0);
+  out[at + LIGHT_RECORD.cosInner] = floatBits(sizes?.[a * 2] ?? 0);
+  out[at + LIGHT_RECORD.cosOuter] = floatBits(sizes?.[a * 2 + 1] ?? 0);
+  out[at + LIGHT_RECORD.iesProfile] = floatBits(NO_IES_PROFILE);
+  out[at + LIGHT_RECORD.cookie] = floatBits(NO_IES_PROFILE);
+  out[at + LIGHT_RECORD.iesAxisX] = floatBits(up?.[a * 3] ?? 0);
+  out[at + LIGHT_RECORD.iesAxisY] = floatBits(up?.[a * 3 + 1] ?? 1);
+  out[at + LIGHT_RECORD.iesAxisZ] = floatBits(up?.[a * 3 + 2] ?? 0);
+  out[at + LIGHT_RECORD.channels] = floatBits(DEFAULT_LIGHT_CHANNELS);
+}
+
+/** A clustered rectangle's reach, which its record carries negated. See `AreaLightSource.range`. */
+function areaReach(lights: ClusterLightSet, light: number): number {
+  const areas = lights.areas;
+  const a = areaSlot(lights, light);
+  const named = areas?.ranges?.[a] ?? 0;
+  if (named > 0) return named;
+  const sizes = areas?.sizes;
+  return Math.hypot(sizes?.[a * 2] ?? 0, sizes?.[a * 2 + 1] ?? 0);
+}
+
+/** How many lights the table carries: the point lights and the clustered rectangles after them. */
+export function clusteredLightTotal(lights: ClusterLightSet): number {
+  return Math.min(lights.count + (lights.areaCount ?? 0), MAX_CLUSTERED_LIGHTS);
 }
 
 /**
@@ -670,7 +787,7 @@ export function buildLightClusters(
   table: Uint32Array,
   shadowSlots: number,
 ): number {
-  const count = Math.min(lights.count, MAX_CLUSTERED_LIGHTS);
+  const count = clusteredLightTotal(lights);
 
   /*
    * The whole cluster region, not just the counts.
@@ -686,10 +803,14 @@ export function buildLightClusters(
   for (let k = 0; k <= CLUSTER_Z; k++) sliceDepths[k] = sliceNearDepth(k, near, far);
 
   for (let light = 0; light < count; light++) {
-    const x = lights.positions[light * 3] ?? 0;
-    const y = lights.positions[light * 3 + 1] ?? 0;
-    const z = lights.positions[light * 3 + 2] ?? 0;
-    const radius = lights.radii[light] ?? 0;
+    /* A rectangle past the lamps is placed by its centre and binned by its reach. */
+    const area = light >= lights.count;
+    const from = area ? (lights.areas?.positions ?? lights.positions) : lights.positions;
+    const slot = area ? areaSlot(lights, light) : light;
+    const x = from[slot * 3] ?? 0;
+    const y = from[slot * 3 + 1] ?? 0;
+    const z = from[slot * 3 + 2] ?? 0;
+    const radius = area ? areaReach(lights, light) : (lights.radii[light] ?? 0);
 
     /* The record, as the shader reads it. World space; see the note above. */
     writeLightRecord(lights, light, shadowSlots, table, lightBase(light));
@@ -706,6 +827,40 @@ export function buildLightClusters(
     /* Entirely behind the camera, so no cluster can reach it. */
     if (depth + radius <= 0) continue;
 
+    /*
+     * **A spot is binned by its cone as well as its sphere.** A 10° spot reaching thirty metres
+     * touches every froxel its sphere does and lights a sliver of them, and a stage rigged with
+     * hundreds of such fixtures put every one of them in nearly every froxel near the floor: 313
+     * lights cost 11.7 ms of a 1600x900 frame. The cone is tested against each froxel's bounding
+     * sphere in view space, which is conservative, by the construction `coneBoxGap` describes.
+     */
+    const cosOuter = lights.coneCos?.[light * 2 + 1] ?? POINT_LIGHT_COS_OUTER;
+    const directions = lights.directions;
+    let coneCos = POINT_LIGHT_COS_OUTER;
+    let coneSin = 0;
+    let axisX = 0;
+    let axisY = 0;
+    let axisZ = 0;
+    if (!area && directions !== undefined && cosOuter > -1) {
+      const dx = directions[light * 3] ?? 0;
+      const dy = directions[light * 3 + 1] ?? 0;
+      const dz = directions[light * 3 + 2] ?? 0;
+      const ax = (view[0] ?? 0) * dx + (view[4] ?? 0) * dy + (view[8] ?? 0) * dz;
+      const ay = (view[1] ?? 0) * dx + (view[5] ?? 0) * dy + (view[9] ?? 0) * dz;
+      const az = -((view[2] ?? 0) * dx + (view[6] ?? 0) * dy + (view[10] ?? 0) * dz);
+      const length = Math.sqrt(ax * ax + ay * ay + az * az);
+      /* The shader measures the cone against the direction as given, so a long one is a wider
+         cone: `dot(L, d) >= c` is `dot(L, d / |d|) >= c / |d|`. */
+      if (length > 1e-6 && cosOuter / length > -1) {
+        coneCos = cosOuter / length;
+        coneSin = Math.sqrt(Math.max(0, 1 - coneCos * coneCos));
+        axisX = ax / length;
+        axisY = ay / length;
+        axisZ = az / length;
+      }
+    }
+    const spot = coneCos > -1;
+
     /*
      * The slices the sphere could possibly touch. The tiles are derived per slice, below.
      *
@@ -765,6 +920,12 @@ export function buildLightClusters(
         for (let i = iLo; i <= iHi; i++) {
           sliceBounds(i, j, zNear, zFar, halfWNear, halfWFar, halfHNear, halfHFar, bounds);
           if (distanceSqToBounds(vx, vy, depth, bounds) > radiusSq) continue;
+          if (
+            spot &&
+            coneBoxGap(vx, vy, depth, axisX, axisY, axisZ, coneCos, coneSin, bounds) > 0
+          ) {
+            continue;
+          }
           insert(table, i + j * CLUSTER_X + k * CLUSTER_X * CLUSTER_Y, light, bounds);
         }
       }
@@ -773,6 +934,59 @@ export function buildLightClusters(
   return count;
 }
 
+/**
+ * How far a froxel lies outside a spot's cone, in metres, or a negative number where the cone
+ * reaches it: positive is a froxel the light cannot shade. Everything in view space with depth
+ * positive, as the binner holds it; `axis` is unit length and `cosA`, `sinA` are the outer cone's.
+ *
+ * **The froxel's bounding sphere against the infinite cone**, after Wronski's cone test for
+ * clustered spots. With `V` from the apex to the sphere's centre at an angle `θ` from the axis and
+ * `A` the cone's half-angle, the centre's distance from the cone is `|V| sin(θ − A)` — which is
+ * `cosA |V⊥| − (V·axis) sinA` — while `θ − A` is under a right angle, and `|V|` past it, where the
+ * nearest point of the cone is its apex. Inside the cone it is negative. So the gap is exact for
+ * the sphere, and the sphere holds the froxel: the test can only keep a light, never drop one the
+ * shader would draw. The apex case is what drops a froxel behind a spot whose sphere reaches it,
+ * which the formula alone underestimates.
+ *
+ * **What it gives up** is tightness at the near end of the frustum, where a froxel is a long thin
+ * box whose sphere is much larger than it: a spot grazing such a froxel is kept. **What would make
+ * it wrong** is a profile showing those near froxels hold the cost; testing the box's corners is
+ * the tight version, at eight dot products a pair.
+ *
+ * Exported so the conformance page can tell a disagreement at the cone's edge from a real one; the
+ * GPU binner writes the same arithmetic in WGSL.
+ */
+export function coneBoxGap(
+  px: number,
+  py: number,
+  pz: number,
+  axisX: number,
+  axisY: number,
+  axisZ: number,
+  cosA: number,
+  sinA: number,
+  box: Float32Array,
+): number {
+  const b0 = box[0] ?? 0;
+  const b1 = box[1] ?? 0;
+  const b2 = box[2] ?? 0;
+  const b3 = box[3] ?? 0;
+  const b4 = box[4] ?? 0;
+  const b5 = box[5] ?? 0;
+  const ex = (b3 - b0) * 0.5;
+  const ey = (b4 - b1) * 0.5;
+  const ez = (b5 - b2) * 0.5;
+  const vx = (b0 + b3) * 0.5 - px;
+  const vy = (b1 + b4) * 0.5 - py;
+  const vz = (b2 + b5) * 0.5 - pz;
+  const along = vx * axisX + vy * axisY + vz * axisZ;
+  const lengthSq = vx * vx + vy * vy + vz * vz;
+  const across = Math.sqrt(Math.max(lengthSq - along * along, 0));
+  const reach = Math.sqrt(lengthSq);
+  const distance = along < -sinA * reach ? reach : cosA * across - along * sinA;
+  return distance - Math.sqrt(ex * ex + ey * ey + ez * ez);
+}
+
 /** An NDC coordinate to a tile index, clamped. */
 function tileOf(ndc: number, tiles: number): number {
   const tile = Math.floor((ndc + 1) * 0.5 * tiles);

package/src/render/fixtureAtlas.ts

@@ -12,7 +12,7 @@
  * only ever reaches forward — to the next plane, and from the last to the repeat of the first — so
  * past its last row it meets the texture's edge and the clamp, never a cookie. A cookie's own
  * half-texel inset keeps it inside its band on both axes. The shader finds the bands from
- * `textureSize` and `uIesAtlasRows`, so the fold cost no uniform.
+ * `textureSize` and `uFixtureShape.x`, so the fold cost no uniform.
  *
  * **What it gives up**: every texel is four half floats where a profile needed one, a few kilobytes
  * a scene; and setting either table rebuilds the whole texture, which a consumer does once per set.

package/src/render/instanceCull.ts

@@ -71,6 +71,11 @@ export function cullInstances(
     out.tints[kept * 3] = tints[i * 3] as number;
     out.tints[kept * 3 + 1] = tints[i * 3 + 1] as number;
     out.tints[kept * 3 + 2] = tints[i * 3 + 2] as number;
+    if (out.alphas !== undefined) out.alphas[kept] = data.alphas?.[i] ?? 1;
+    const regions = data.lightmapRegions;
+    if (regions !== undefined && out.lightmapRegions !== undefined) {
+      for (let k = 0; k < 4; k++) out.lightmapRegions[kept * 4 + k] = regions[i * 4 + k] as number;
+    }
     kept++;
   }
   out.count = kept;

package/src/render/instances.ts

@@ -10,10 +10,11 @@
  * plant. This one carries a full transform, because a vehicle pitches and rolls on its suspension
  * and a yaw cannot say so.
  *
- * **What it gives up** is a matrix per instance where a scatter spends five floats: 76 bytes
+ * **What it gives up** is a matrix per instance where a scatter spends five floats: 80 bytes
  * against 44, and no wind. **What would make it wrong** is a caller wanting per-instance
- * anything else — an opacity, a morph weight — which wants another attribute, and the sixteen
- * WebGL2 guarantees are already spent.
+ * anything beyond an opacity — a morph weight, a texture cell — which wants another attribute,
+ * and the sixteen WebGL2 guarantees are already spent. The opacity rides the float the stride was
+ * padded with, which is why it costs nothing.
  */
 export interface MeshInstances {
   /**
@@ -30,6 +31,26 @@ export interface MeshInstances {
    * — the alternative is a second batch per colour, which is the thing this exists to avoid.
    */
   readonly tints: Float32Array;
+  /**
+   * One float each, the instance's opacity from 0 to 1, which a blended draw
+   * (`drawTranslucentInstanced`) multiplies into the batch's own. **Absent, or an instance past its
+   * end, is 1** — wholly opaque, which is what every instance was before 4.8.6.
+   *
+   * What lets one draw carry particles fading at different rates: without it a consumer drew a
+   * batch per opacity level, each a draw and a material of its own. It is the instance's twin of
+   * the per-vertex alpha lane (`MeshData.channel`), multiplied in where that lane is.
+   */
+  readonly alphas?: Float32Array;
+  /**
+   * Four floats each, the instance's region of its lightmap page: `[scaleU, scaleV, biasU, biasV]`,
+   * read by a draw whose material is a `lightmapModel` — instances of one mesh in one material sit
+   * in different regions of one page, each applied before the material's own region. **They ride
+   * the tint and the opacity**, which a lightmapped instance gives up (see `lightmap.ts`): where
+   * these are given, those are not read. **A lightmapped batch needs them**, since a bake is
+   * different light at each instance; one drawn without them reads its tints as its regions, and
+   * either mismatch is said once on the console.
+   */
+  readonly lightmapRegions?: Float32Array;
   /** How many instances the arrays hold. Fixed at creation; the buffers are sized from it. */
   readonly capacity: number;
   /** How many are live. The rest of the buffer is neither uploaded nor drawn. */
@@ -47,6 +68,7 @@ export function createMeshInstances(capacity: number): MeshInstances {
   return {
     models: new Float32Array(capacity * 16),
     tints: new Float32Array(capacity * 3),
+    alphas: new Float32Array(capacity).fill(1),
     capacity,
     count: 0,
   };
@@ -54,13 +76,14 @@ export function createMeshInstances(capacity: number): MeshInstances {
 
 /**
  * Floats one instance occupies in the interleaved vertex buffer: sixteen of matrix, three of
- * tint, and one of padding.
+ * tint, and the opacity.
  *
- * **Padded to twenty so the stride is 80 bytes rather than 76.** A vertex buffer's stride must be
- * a multiple of four on both backends, which 76 already is — the padding is for the *attribute*
- * offsets: the tint sits at byte 64 and a three-float attribute ending at 76 leaves the next
- * instance's first column starting there, which is legal but puts every second instance on an
- * offset no driver aligns well. One wasted float an instance is 4 bytes against 76.
+ * **Twenty so the stride is 80 bytes rather than 76.** A vertex buffer's stride must be a multiple
+ * of four on both backends, which 76 already is — the twentieth float was padding for the
+ * *attribute* offsets: the tint sits at byte 64 and a three-float attribute ending at 76 leaves the
+ * next instance's first column starting there, which is legal but puts every second instance on an
+ * offset no driver aligns well. Since 4.8.6 it carries the instance's opacity, read with the tint
+ * as one four-float attribute, so the opacity cost no attribute and no byte.
  */
 export const INSTANCE_FLOATS = 20;
 
@@ -68,7 +91,7 @@ export const INSTANCE_FLOATS = 20;
 export const INSTANCE_STRIDE = INSTANCE_FLOATS * 4;
 
 /**
- * Interleave `count` instances into `out`, matrix then tint, at `INSTANCE_FLOATS` apart.
+ * Interleave `count` instances into `out`, matrix, tint and opacity, at `INSTANCE_FLOATS` apart.
  *
  * **Interleaved rather than two buffers** so a batch's upload is one `writeBuffer` and an
  * instance's colour sits beside the matrix that places it. Shared by both backends, because
@@ -78,16 +101,22 @@ export const INSTANCE_STRIDE = INSTANCE_FLOATS * 4;
  * Writes nothing beyond `count`, and allocates nothing: `out` is the caller's staging array.
  */
 export function packInstances(instances: MeshInstances, out: Float32Array): void {
-  const { models, tints } = instances;
+  const { models, tints, alphas, lightmapRegions } = instances;
   const count = Math.min(instances.count, instances.capacity);
   for (let i = 0; i < count; i += 1) {
     const at = i * INSTANCE_FLOATS;
     const m = i * 16;
     for (let c = 0; c < 16; c += 1) out[at + c] = models[m + c] as number;
+    if (lightmapRegions !== undefined) {
+      /* The region in the tint's and the opacity's place. See `lightmapRegions`. */
+      for (let c = 0; c < 4; c += 1) out[at + 16 + c] = lightmapRegions[i * 4 + c] as number;
+      continue;
+    }
     const t = i * 3;
     out[at + 16] = tints[t] as number;
     out[at + 17] = tints[t + 1] as number;
     out[at + 18] = tints[t + 2] as number;
+    out[at + 19] = alphas?.[i] ?? 1;
   }
 }
 

package/src/render/lightBudget.ts

@@ -6,6 +6,7 @@ import {
   POINT_LIGHT_COS_OUTER,
   lampSourceRadius,
   lampWeight,
+  lightChannelsOf,
 } from './clusteredLights.ts';
 
 /**
@@ -256,12 +257,22 @@ export const CLOTH_REST_TEXTURE_UNIT = CLOTH_PARTICLES_TEXTURE_UNIT + 1;
 export const MODEL_MAP_TEXTURE_UNIT = CLOTH_REST_TEXTURE_UNIT + 1;
 
 /**
- * The two units skin's screen-space blur reads on WebGL2 — its target and the frame's depth — past
+ * The units skin's screen-space blur reads on WebGL2 — its target and the frame's depth — past
  * every unit a lit program binds, so spreading skin in the middle of a frame unbinds nothing the
  * draws after it sample. WebGL2 guarantees thirty-two.
  */
 export const SKIN_BLUR_TEXTURE_UNIT = MODEL_MAP_TEXTURE_UNIT + 1;
 export const SKIN_BLUR_DEPTH_UNIT = SKIN_BLUR_TEXTURE_UNIT + 1;
+/** And the skin's colour, which the blur's second axis multiplies the spread light by. */
+export const SKIN_BLUR_ALBEDO_UNIT = SKIN_BLUR_DEPTH_UNIT + 1;
+
+/**
+ * A sprite particle's image and the frame's depth copy its soft edge reads, on WebGL2: past every
+ * unit a lit program binds, for the skin blur's reason — a particle is drawn in the middle of a
+ * frame, and the draws after it must find their textures where they left them.
+ */
+export const PARTICLE_SPRITE_UNIT = SKIN_BLUR_ALBEDO_UNIT + 1;
+export const PARTICLE_DEPTH_UNIT = PARTICLE_SPRITE_UNIT + 1;
 
 /**
  * A cookie's tile, in texels a side.
@@ -380,6 +391,16 @@ export interface PointLightSet {
    * drawn for one spot works in another with a different angle.
    */
   readonly lightCookies?: Float32Array;
+  /**
+   * One per light: the lighting channels it lights, as a bitmask in a float — 1, 2, 3 … 255.
+   * **Absent, or a short array, is channel 1 for every light**, which is every surface's default
+   * too, so a scene that never names a channel lights everything with everything as it did.
+   *
+   * A light shades a surface only where its mask and the surface's `SurfaceMaterial.lightChannels`
+   * share a bit. What it is for: a rig of lights that belongs to some draws and not others — a
+   * character's own key and rim lights, which the floor around the character must not take.
+   */
+  readonly lightChannels?: Float32Array;
 }
 
 /** Weights are optional per consumer; a short array means every light is fully present. */
@@ -485,7 +506,8 @@ export function bindPointLights(
   gl.uniform3fv(uniforms['uLightDir[0]'] ?? null, r.directions);
   gl.uniform2fv(uniforms['uLightCone[0]'] ?? null, r.coneCos);
   gl.uniform1fv(uniforms['uLightIesProfile[0]'] ?? null, r.iesProfiles);
-  gl.uniform3fv(uniforms['uLightIesAxis[0]'] ?? null, r.iesAxes);
+  /* The azimuth and, in w, the channels. See `axesAndChannels`. */
+  gl.uniform4fv(uniforms['uLightIesAxis[0]'] ?? null, r.axesAndChannels);
   gl.uniform1fv(uniforms['uLightCookie[0]'] ?? null, r.cookies);
 }
 
@@ -561,6 +583,12 @@ export interface ResolvedPointLights {
   iesProfiles: Float32Array;
   iesAxes: Float32Array;
   cookies: Float32Array;
+  /**
+   * Owned, four a light: the photometric azimuth in xyz and the light's channels in w, which is how
+   * `uLightIesAxis` carries them — the channels in a lane the axis left, rather than in a uniform
+   * array of their own, which would cost a row a light of a budget that has none to give.
+   */
+  readonly axesAndChannels: 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
@@ -585,6 +613,7 @@ const glLights: ResolvedPointLights = {
   iesProfiles: NO_PROFILES,
   iesAxes: NO_IES_AXES,
   cookies: NO_COOKIES,
+  axesAndChannels: new Float32Array(MAX_POINT_LIGHTS * 4),
   heldSourceRadii: new Float32Array(MAX_POINT_LIGHTS),
   heldWeights: new Float32Array(MAX_POINT_LIGHTS),
 };
@@ -619,6 +648,7 @@ export function resolvePointLights(
     out.iesProfiles = NO_PROFILES;
     out.iesAxes = NO_IES_AXES;
     out.cookies = NO_COOKIES;
+    packAxesAndChannels(NO_IES_AXES, undefined, out.axesAndChannels);
     return out;
   }
   /*
@@ -711,5 +741,21 @@ export function resolvePointLights(
   out.iesProfiles = iesProfiles;
   out.iesAxes = iesAxes;
   out.cookies = cookies;
+  packAxesAndChannels(iesAxes, lights.lightChannels, out.axesAndChannels);
   return out;
 }
+
+/** The azimuth and the channels, four a light, as `uLightIesAxis` holds them. */
+function packAxesAndChannels(
+  axes: Float32Array,
+  channels: Float32Array | undefined,
+  out: Float32Array,
+): void {
+  const named = (channels?.length ?? 0) >= MAX_POINT_LIGHTS ? channels : undefined;
+  for (let light = 0; light < MAX_POINT_LIGHTS; light++) {
+    out[light * 4] = axes[light * 3] ?? 0;
+    out[light * 4 + 1] = axes[light * 3 + 1] ?? 0;
+    out[light * 4 + 2] = axes[light * 3 + 2] ?? 0;
+    out[light * 4 + 3] = lightChannelsOf(named?.[light]);
+  }
+}