@driftengine/core 4.8.4 → 4.8.6

package/dist/render/bloomChain.d.ts

@@ -57,6 +57,50 @@ export declare function bloomProfileWarning(quality: {
     readonly hdrScene: boolean;
     readonly bloomThreshold: number;
 }): string | null;
+/**
+ * How a frame's bloom answers the light it is given, beside the strength and threshold `setBloom`
+ * already takes. Absent, or a field absent, is the response every frame had before 4.8.6.
+ *
+ * **Why it exists: one band over the colour less the threshold washes a stage built for another
+ * engine.** Unreal's standard bloom keeps `saturate((L − threshold) / 2)` of a colour rather than
+ * the colour less the threshold, and spreads it over six bands, each in a tint of its own. A
+ * stage authored against that — a threshold of 0.1 and tints summing below one — came out white
+ * here, because subtracting so low a threshold keeps nearly every light in the frame at full
+ * strength. These are the two things that differ, as numbers.
+ */
+export interface BloomResponse {
+    /**
+     * Scene units over which a colour comes in, from none of it at the threshold to all of it this
+     * far past. **0, the default, subtracts instead**: a colour keeps what it has past the threshold,
+     * the response since bloom shipped. Unreal's is 2 after exposure, so a frame exposed by `e` that
+     * wants it passes `2 / e`, as it passes the threshold over the exposure.
+     *
+     * Brightness is still the largest channel rather than luminance, for the reason
+     * `shaders/bloom.ts` gives; on a neutral colour the two are equal.
+     */
+    readonly ramp?: number;
+    /**
+     * Each level's colour, three numbers a level, finest first: the halo at a few pixels first and
+     * at a twentieth of the frame last. **White, the default, is the identity**; a level not named
+     * takes white. Not clamped above one, which is how a tint carries a strength past the 0..1 the
+     * dial gives — a stage asking for twice the light names tints twice as bright.
+     *
+     * At most `BLOOM_LEVELS` levels. A frame too small for that many uses the first it has room for.
+     */
+    readonly tints?: ArrayLike<number>;
+}
+/** Floats `resolveBloomResponse` writes: the ramp, then a tint a level. */
+export declare const BLOOM_RESPONSE_FLOATS: number;
+/**
+ * A response as both backends bind it, into a caller-owned `out` of `BLOOM_RESPONSE_FLOATS`: the
+ * ramp, then `BLOOM_LEVELS` tints, white where none was named. Refuses a tint list that is not
+ * whole colours or names more levels than the pyramid has, naming the length — a caller error with
+ * one correct outcome. A ramp that is not a positive number is the subtraction; a tint channel
+ * that is not a number or is below zero is zero.
+ */
+export declare function resolveBloomResponse(response: BloomResponse | null | undefined, out: Float32Array): void;
+/** The response every frame had before 4.8.6: the subtraction, every level white. */
+export declare function defaultBloomResponse(): Float32Array;
 /** One level of the pyramid: level 0 is half the frame and each one after it half again. */
 export interface BloomLevelSize {
     readonly width: number;

package/dist/render/bloomChain.js

@@ -67,6 +67,34 @@ export function bloomProfileWarning(quality) {
     }
     return null;
 }
+/** Floats `resolveBloomResponse` writes: the ramp, then a tint a level. */
+export const BLOOM_RESPONSE_FLOATS = 1 + BLOOM_LEVELS * 3;
+/**
+ * A response as both backends bind it, into a caller-owned `out` of `BLOOM_RESPONSE_FLOATS`: the
+ * ramp, then `BLOOM_LEVELS` tints, white where none was named. Refuses a tint list that is not
+ * whole colours or names more levels than the pyramid has, naming the length — a caller error with
+ * one correct outcome. A ramp that is not a positive number is the subtraction; a tint channel
+ * that is not a number or is below zero is zero.
+ */
+export function resolveBloomResponse(response, out) {
+    const ramp = response?.ramp ?? 0;
+    out[0] = Number.isFinite(ramp) && ramp > 0 ? ramp : 0;
+    const tints = response?.tints;
+    if (tints !== undefined && (tints.length % 3 !== 0 || tints.length > BLOOM_LEVELS * 3)) {
+        throw new Error(`setBloom: ${tints.length} tint values is not up to ${BLOOM_LEVELS} whole colours, three ` +
+            'numbers a level, finest first');
+    }
+    for (let i = 0; i < BLOOM_LEVELS * 3; i++) {
+        const value = tints !== undefined && i < tints.length ? tints[i] : 1;
+        out[1 + i] = Number.isFinite(value) && value > 0 ? value : 0;
+    }
+}
+/** The response every frame had before 4.8.6: the subtraction, every level white. */
+export function defaultBloomResponse() {
+    const out = new Float32Array(BLOOM_RESPONSE_FLOATS);
+    resolveBloomResponse(null, out);
+    return out;
+}
 /**
  * The pyramid for a frame of this size, largest first, or an empty list where none would fit.
  *

package/dist/render/bloomPass.d.ts

@@ -46,7 +46,9 @@ export declare class BloomPass {
      * `threshold` is in scene units, so it only separates a light from white paint on a target
      * that kept the range. The caller owns that decision and the warning that goes with it.
      */
-    run(scene: WebGLTexture, width: number, height: number, threshold: number): WebGLTexture | null;
+    run(scene: WebGLTexture, width: number, height: number, threshold: number, 
+    /** The ramp, then each level's tint: `resolveBloomResponse`'s floats. */
+    response: Float32Array): WebGLTexture | null;
     /** One source texel in UV, which is what the thirteen taps are laid out in. */
     private uploadTexel;
     private release;

package/dist/render/bloomPass.js

@@ -130,7 +130,9 @@ export class BloomPass {
      * `threshold` is in scene units, so it only separates a light from white paint on a target
      * that kept the range. The caller owns that decision and the warning that goes with it.
      */
-    run(scene, width, height, threshold) {
+    run(scene, width, height, threshold, 
+    /** The ramp, then each level's tint: `resolveBloomResponse`'s floats. */
+    response) {
         if (!this.ensureSize(width, height))
             return null;
         const { gl } = this;
@@ -153,6 +155,7 @@ export class BloomPass {
         gl.bindTexture(gl.TEXTURE_2D, scene);
         gl.uniform1i(this.prefilterUniforms['uSource'] ?? null, 0);
         gl.uniform1f(this.prefilterUniforms['uThreshold'] ?? null, threshold);
+        gl.uniform1f(this.prefilterUniforms['uRamp'] ?? null, response[0] ?? 0);
         this.uploadTexel(this.prefilterUniforms, width, height);
         gl.drawArrays(gl.TRIANGLES, 0, 3);
         /* Down the chain. Each level reads the one above it, which was written a draw ago. */
@@ -174,8 +177,13 @@ export class BloomPass {
          * every octave at once. Additive blending rather than a second target to ping-pong through:
          * a level is only ever read while a *different* level is bound, so there is no feedback.
          */
+        /*
+         * Each level's tint rides the blend: the level being added onto is multiplied by its own as the
+         * octave below is added, and the deepest by `uScale` on the first draw, the only one reading it
+         * before anything has been added to it. White everywhere is `ONE, ONE` exactly.
+         */
         gl.enable(gl.BLEND);
-        gl.blendFunc(gl.ONE, gl.ONE);
+        gl.blendFunc(gl.ONE, gl.CONSTANT_COLOR);
         gl.useProgram(this.upsampleProgram);
         gl.uniform1i(this.upsampleUniforms['uSource'] ?? null, 0);
         gl.uniform1f(this.upsampleUniforms['uRadius'] ?? null, BLOOM_FILTER_RADIUS_UV);
@@ -184,11 +192,17 @@ export class BloomPass {
             const source = levels[index];
             if (target === undefined || source === undefined)
                 break;
+            const deepest = index === levels.length - 1;
+            const into = 1 + (index - 1) * 3;
+            const from = 1 + index * 3;
+            gl.blendColor(response[into] ?? 1, response[into + 1] ?? 1, response[into + 2] ?? 1, 1);
+            gl.uniform3f(this.upsampleUniforms['uScale'] ?? null, deepest ? (response[from] ?? 1) : 1, deepest ? (response[from + 1] ?? 1) : 1, deepest ? (response[from + 2] ?? 1) : 1);
             gl.bindFramebuffer(gl.FRAMEBUFFER, target.framebuffer);
             gl.viewport(0, 0, target.width, target.height);
             gl.bindTexture(gl.TEXTURE_2D, source.texture);
             gl.drawArrays(gl.TRIANGLES, 0, 3);
         }
+        gl.blendColor(0, 0, 0, 0);
         gl.disable(gl.BLEND);
         gl.bindVertexArray(null);
         gl.bindFramebuffer(gl.FRAMEBUFFER, null);

package/dist/render/clusteredLights.d.ts

@@ -1,3 +1,4 @@
+import type { AreaLightBuffer } from './areaLights.ts';
 /**
  * The froxel table: what it looks like in memory, and the CPU binner that fills it.
  *
@@ -139,7 +140,21 @@ export declare const LIGHT_RECORD: {
     readonly iesAxisX: 16;
     readonly iesAxisY: 17;
     readonly 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.
+     */
+    readonly channels: 19;
 };
+/** The lighting channel every light and every surface is on unless it says otherwise. */
+export declare 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 declare function lightChannelsOf(value: number | undefined): number;
 /** Texels the lit pass reads for a light whose record carries no fixture. */
 export declare const PLAIN_LIGHT_TEXELS = 2;
 /**
@@ -270,6 +285,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. */
 export interface ClusterLightArrays {
@@ -284,6 +309,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. */
 export type ClusterLightScratch = {
@@ -305,7 +332,9 @@ export declare function createClusterLightSet(): ClusterLightScratch;
  * 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;
+export declare function fillClusterLightSet(env: ClusterLightArrays, out: ClusterLightScratch, 
+/** How many rectangles the fixed arm shades; the rest of the buffer is clustered. */
+areaFrom?: number): 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`.
@@ -343,6 +372,8 @@ export declare function clusteredMode(lights: ClusterLightSet, count: number, sh
  * 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;
+/** How many lights the table carries: the point lights and the clustered rectangles after them. */
+export declare function clusteredLightTotal(lights: ClusterLightSet): number;
 /**
  * Fill the table with this frame's light assignment, and answer how many lights it carried.
  *
@@ -389,3 +420,26 @@ export declare function writeLightRecord(lights: ClusterLightSet, light: number,
  * Fills a caller-owned table and allocates nothing.
  */
 export declare function buildLightClusters(lights: ClusterLightSet, view: Float32Array, near: number, far: number, tanHalfFovY: number, aspect: number, table: Uint32Array, shadowSlots: number): number;
+/**
+ * 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 declare function coneBoxGap(px: number, py: number, pz: number, axisX: number, axisY: number, axisZ: number, cosA: number, sinA: number, box: Float32Array): number;

package/dist/render/clusteredLights.js

@@ -139,7 +139,26 @@ 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,
 };
+/** 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) {
+    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;
 /**
@@ -354,8 +373,14 @@ export function createClusterLightSet() {
  * 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, out) {
+export function fillClusterLightSet(env, out, 
+/** How many rectangles the fixed arm shades; the rest of the buffer is clustered. */
+areaFrom = 0) {
     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;
@@ -366,6 +391,7 @@ export function fillClusterLightSet(env, out) {
     out.iesProfiles = env.lightIesProfiles;
     out.iesAxes = env.lightIesAxes;
     out.cookies = env.lightCookies;
+    out.channels = env.lightChannels;
     return out;
 }
 /*
@@ -418,12 +444,16 @@ function distanceSqToBounds(x, y, z, b) {
  * them was paying for three texels the shader then ignored.
  */
 export function lightHasFixture(lights, light, shadowSlots) {
+    /* 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);
 }
 /**
  * The value of `uClustered` for a frame: 0 with clustering off, 1 when every light is plain, 2 when
@@ -459,6 +489,10 @@ export function clusteredMode(lights, count, shadowSlots) {
  * is a light without a map, which is what a scene with two hundred lamps has anyway.
  */
 export function writeLightRecord(lights, light, shadowSlots, out, at) {
+    if (light >= lights.count) {
+        writeAreaRecord(lights, light, out, at);
+        return;
+    }
     const directions = lights.directions;
     const cone = lights.coneCos;
     const axes = lights.iesAxes;
@@ -490,7 +524,64 @@ export function writeLightRecord(lights, light, shadowSlots, out, at) {
     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, light) {
+    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, light, out, at) {
+    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, light) {
+    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) {
+    return Math.min(lights.count + (lights.areaCount ?? 0), MAX_CLUSTERED_LIGHTS);
 }
 /**
  * Fill the table with this frame's light assignment, and answer how many lights it carried.
@@ -538,7 +629,7 @@ export function writeLightRecord(lights, light, shadowSlots, out, at) {
  * Fills a caller-owned table and allocates nothing.
  */
 export function buildLightClusters(lights, view, near, far, tanHalfFovY, aspect, table, shadowSlots) {
-    const count = Math.min(lights.count, MAX_CLUSTERED_LIGHTS);
+    const count = clusteredLightTotal(lights);
     /*
      * The whole cluster region, not just the counts.
      *
@@ -553,10 +644,14 @@ export function buildLightClusters(lights, view, near, far, tanHalfFovY, aspect,
     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));
         /* Column-major, as gl-matrix builds it. The view looks down -z, so depth is -vz. */
@@ -570,6 +665,39 @@ export function buildLightClusters(lights, view, near, far, tanHalfFovY, aspect,
         /* 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.
          *
@@ -617,6 +745,10 @@ export function buildLightClusters(lights, view, near, far, tanHalfFovY, aspect,
                     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);
                 }
             }
@@ -624,6 +756,48 @@ export function buildLightClusters(lights, view, near, far, tanHalfFovY, aspect,
     }
     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, py, pz, axisX, axisY, axisZ, cosA, sinA, box) {
+    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, tiles) {
     const tile = Math.floor((ndc + 1) * 0.5 * tiles);

package/dist/render/fixtureAtlas.js

@@ -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/dist/render/instanceCull.js

@@ -44,6 +44,13 @@ export function cullInstances(data, local, frustum, out) {
         out.tints[kept * 3] = tints[i * 3];
         out.tints[kept * 3 + 1] = tints[i * 3 + 1];
         out.tints[kept * 3 + 2] = tints[i * 3 + 2];
+        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];
+        }
         kept++;
     }
     out.count = kept;

package/dist/render/instances.d.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. */
@@ -45,19 +66,20 @@ export interface MeshInstances {
 export declare 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 declare const INSTANCE_FLOATS = 20;
 /** Bytes one instance occupies. See `INSTANCE_FLOATS`. */
 export declare const INSTANCE_STRIDE: number;
 /**
- * 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