@driftengine/core 4.4.2 → 4.6.0

package/dist/render/driftLight/denseField.js

@@ -0,0 +1,109 @@
+/**
+ * DriftLight for a whole world: every fixed light summed into one dense grid, baked offline.
+ *
+ * **Dense, where the courtyard field is sparse, because a city is lit nearly everywhere.** A brick
+ * earns its index and its shared faces where light is rare; street lamps reaching thirty metres
+ * forty metres apart leave almost no cell dark, so the sparseness buys nothing and the shared
+ * faces cost 2.4× the samples. At 8 m a sample, a two-kilometre city 128 m tall is 256 × 16 × 256
+ * samples, two half-float texels each: 16 MB on the GPU, and the renderer's lookup is one filtered
+ * fetch for the light and one for its direction.
+ *
+ * **The same sample as every other bake.** `sampleFieldLight` is shared with `bakeBrick`, so a dense
+ * volume and a brick agree bit for bit wherever both have a sample. The order a sample's lights are
+ * summed in does not have to match for that: the sum runs in double precision and is stored in
+ * single, which the last bits of a few terms in another order do not reach.
+ *
+ * **Lights are bucketed first**, four samples a bucket on every axis, so a sample sums only the
+ * lights whose reach touches its bucket rather than all of them: a city of ten thousand lamps is a
+ * few dozen candidates a sample. Offline and allocation-free per sample; it may take seconds.
+ *
+ * What it gives up is resolution: at 8 m a lamp's pool is a few samples across, which is why this
+ * stands in only past the exact lights, where a pool is a few dozen pixels.
+ */
+import { sampleFieldLight } from './bake.js';
+/** The most samples along x or z: WebGL2 promises 256 on every axis of a 3D texture. */
+export const DENSE_MAX_AXIS = 256;
+/** The most along y, which holds the light and then the direction: two layers in 256. */
+export const DENSE_MAX_HEIGHT = 128;
+/** Samples a bucket spans on each axis. */
+const BUCKET = 4;
+/**
+ * Sum `lights` over the box `bounds` (min xyz, max xyz) at `spacing` metres. `distance` occludes, or
+ * null for none. The first sample stands on the box's min corner.
+ */
+export function bakeDenseField(lights, falloff, distance, bounds, spacing) {
+    if (!(spacing > 0))
+        throw new Error(`bakeDenseField: spacing is ${String(spacing)}`);
+    const origin = [
+        bounds[0],
+        bounds[1],
+        bounds[2],
+    ];
+    const dims = [0, 0, 0];
+    for (let axis = 0; axis < 3; axis++) {
+        const extent = bounds[axis + 3] - origin[axis];
+        dims[axis] = Math.max(1, Math.floor(extent / spacing + 1e-9) + 1);
+    }
+    if (dims[0] > DENSE_MAX_AXIS || dims[2] > DENSE_MAX_AXIS || dims[1] > DENSE_MAX_HEIGHT) {
+        throw new Error(`bakeDenseField: ${dims.join(' × ')} samples, and a volume holds ${DENSE_MAX_AXIS} across, ` +
+            `${DENSE_MAX_HEIGHT} up and ${DENSE_MAX_AXIS} deep; a coarser spacing fits it.`);
+    }
+    /* Each light listed in every bucket its reach touches, in the order the scene listed them. */
+    const buckets = [
+        Math.ceil(dims[0] / BUCKET),
+        Math.ceil(dims[1] / BUCKET),
+        Math.ceil(dims[2] / BUCKET),
+    ];
+    const bucketCount = buckets[0] * buckets[1] * buckets[2];
+    const span = spacing * BUCKET;
+    const range = (light, axis, out) => {
+        const at = axis === 0 ? light.x : axis === 1 ? light.y : light.z;
+        const lo = Math.floor((at - light.radius - origin[axis]) / span);
+        const hi = Math.floor((at + light.radius - origin[axis]) / span);
+        out[axis * 2] = Math.max(0, lo);
+        out[axis * 2 + 1] = Math.min(buckets[axis] - 1, hi);
+        return out[axis * 2] <= out[axis * 2 + 1];
+    };
+    const cells = new Int32Array(6);
+    const start = new Uint32Array(bucketCount + 1);
+    const each = (fill) => {
+        for (let index = 0; index < lights.length; index++) {
+            const light = lights[index];
+            if (!(light.radius > 0))
+                continue;
+            if (!range(light, 0, cells) || !range(light, 1, cells) || !range(light, 2, cells))
+                continue;
+            for (let z = cells[4]; z <= cells[5]; z++) {
+                for (let y = cells[2]; y <= cells[3]; y++) {
+                    for (let x = cells[0]; x <= cells[1]; x++) {
+                        fill(x + buckets[0] * (y + buckets[1] * z), index);
+                    }
+                }
+            }
+        }
+    };
+    each((bucket) => {
+        start[bucket + 1] = start[bucket + 1] + 1;
+    });
+    for (let b = 0; b < bucketCount; b++)
+        start[b + 1] = start[b + 1] + start[b];
+    const listed = new Uint32Array(start[bucketCount]);
+    const cursor = start.slice(0, bucketCount);
+    each((bucket, light) => {
+        listed[cursor[bucket]] = light;
+        cursor[bucket] = cursor[bucket] + 1;
+    });
+    const count = dims[0] * dims[1] * dims[2];
+    const light = new Float32Array(count * 4);
+    const direction = new Float32Array(count * 4);
+    for (let k = 0; k < dims[2]; k++) {
+        for (let j = 0; j < dims[1]; j++) {
+            for (let i = 0; i < dims[0]; i++) {
+                const bucket = Math.floor(i / BUCKET) +
+                    buckets[0] * (Math.floor(j / BUCKET) + buckets[1] * Math.floor(k / BUCKET));
+                sampleFieldLight(origin[0] + i * spacing, origin[1] + j * spacing, origin[2] + k * spacing, lights, listed, start[bucket], start[bucket + 1], falloff, distance, light, direction, (i + dims[0] * (j + dims[1] * k)) * 4);
+            }
+        }
+    }
+    return { origin, spacing, dims, light, direction };
+}

package/dist/render/driftLight/lightField.d.ts

@@ -29,6 +29,7 @@ import type { GlobalFieldInstance } from '../gi/globalField.ts';
 import type { FieldLight } from './bake.ts';
 import type { PointLightFalloff } from './falloff.ts';
 import type { LightFieldLayout } from './layout.ts';
+import type { DriftLightVolumes } from './presence.ts';
 /** Seconds the summed light takes to fade in once the field is whole. */
 export declare const FIELD_FADE_SEC = 0.5;
 /** A light a field sums: a `PointLightSource`, whose `inLightField` the field sets. */
@@ -51,7 +52,7 @@ export interface LightFieldOptions {
      */
     readonly fadeSec?: number;
 }
-export declare class LightField {
+export declare class LightField implements DriftLightVolumes {
     readonly layout: LightFieldLayout;
     /** Texels on each axis of the atlas. */
     readonly atlasSize: readonly [number, number, number];
@@ -67,17 +68,14 @@ export declare class LightField {
     readonly fadeSec: number;
     /** The summed light's brightness, for a scene that dims all its lamps at once: dawn, a switch. */
     scale: number;
-    /** Where the frame's choice was centred, which the shader measures the radius from. */
-    readonly centre: Float32Array<ArrayBuffer>;
     private readonly lights;
     private readonly falloff;
     private readonly distance;
     private readonly lightBlock;
     private readonly directionBlock;
+    private readonly showing;
     private baked;
     private taken;
-    private eased;
-    private shown;
     constructor(lights: readonly LightFieldSource[], options: LightFieldOptions);
     /** Whether every brick has been baked. */
     get ready(): boolean;
@@ -87,6 +85,13 @@ export declare class LightField {
     get radius(): number;
     /** How much of the summed light is in the frame, 0 until the field is whole, then up to 1. */
     get presence(): number;
+    /** Where the frame's choice was centred, which the shader measures the radius from. */
+    get centre(): Float32Array;
+    get empty(): boolean;
+    get indexDims(): readonly [number, number, number];
+    get index(): Uint32Array;
+    get sampleOrigin(): readonly [number, number, number];
+    get signedSpacing(): number;
     /** The texel at which brick `brick`'s light block starts; its direction block is 4 along x. */
     atlasCorner(brick: number): [number, number, number];
     /** Bake up to `bricks` more bricks into the atlas, and answer how many were baked. */

package/dist/render/driftLight/lightField.js

@@ -29,10 +29,9 @@ import { distanceToInstances } from '../gi/globalField.js';
 import { halfBits } from '../halfFloat.js';
 import { BRICK_TEXELS, bakeBrick } from './bake.js';
 import { BRICK_SAMPLES, layoutLightField } from './layout.js';
+import { FieldPresence } from './presence.js';
 /** Seconds the summed light takes to fade in once the field is whole. */
 export const FIELD_FADE_SEC = 0.5;
-/** How fast the shading radius grows back, per second, when the choice reaches further again. */
-const RADIUS_GROWTH_PER_SEC = 2;
 /** Bricks along each axis of the atlas: 256 texels a side, the least 3D texture WebGL2 promises. */
 const ATLAS_BRICKS = [32, 64, 64];
 /** A brick's footprint in the atlas: its light block and its direction block side by side. */
@@ -53,17 +52,14 @@ export class LightField {
     fadeSec;
     /** The summed light's brightness, for a scene that dims all its lamps at once: dawn, a switch. */
     scale = 1;
-    /** Where the frame's choice was centred, which the shader measures the radius from. */
-    centre = new Float32Array(3);
     lights;
     falloff;
     distance;
     lightBlock = new Float32Array(BRICK_TEXELS * 4);
     directionBlock = new Float32Array(BRICK_TEXELS * 4);
+    showing;
     baked = 0;
     taken = 0;
-    eased = 0;
-    shown = 0;
     constructor(lights, options) {
         for (const light of lights)
             light.inLightField = true;
@@ -80,6 +76,7 @@ export class LightField {
         this.falloff = options.falloff;
         this.band = options.band ?? 2;
         this.fadeSec = Math.max(0, options.fadeSec ?? FIELD_FADE_SEC);
+        this.showing = new FieldPresence(this.fadeSec);
         const fields = options.fields ?? [];
         this.occluded = fields.length > 0;
         this.distance = this.occluded ? distanceToInstances(fields) : null;
@@ -107,11 +104,30 @@ export class LightField {
     }
     /** The radius, in metres from `centre`, inside which lights are shaded exactly. */
     get radius() {
-        return this.eased;
+        return this.showing.radius;
     }
     /** How much of the summed light is in the frame, 0 until the field is whole, then up to 1. */
     get presence() {
-        return this.shown;
+        return this.showing.presence;
+    }
+    /** Where the frame's choice was centred, which the shader measures the radius from. */
+    get centre() {
+        return this.showing.centre;
+    }
+    get empty() {
+        return this.layout.count === 0;
+    }
+    get indexDims() {
+        return this.layout.dims;
+    }
+    get index() {
+        return this.layout.index;
+    }
+    get sampleOrigin() {
+        return this.layout.origin;
+    }
+    get signedSpacing() {
+        return this.layout.spacing;
     }
     /** The texel at which brick `brick`'s light block starts; its direction block is 4 along x. */
     atlasCorner(brick) {
@@ -146,17 +162,7 @@ export class LightField {
      * which is only less exact. While nothing is summed the radius simply follows.
      */
     follow(complete, x, y, z, dtSec) {
-        this.centre[0] = x;
-        this.centre[1] = y;
-        this.centre[2] = z;
-        const showing = this.shown > 0;
-        if (!showing || complete < this.eased)
-            this.eased = complete;
-        else
-            this.eased += (complete - this.eased) * (1 - Math.exp(-RADIUS_GROWTH_PER_SEC * dtSec));
-        if (this.ready) {
-            this.shown = this.fadeSec > 0 ? Math.min(1, this.shown + dtSec / this.fadeSec) : 1;
-        }
+        this.showing.follow(this.ready, complete, x, y, z, dtSec);
     }
     /** Write the brick just baked into its place in the atlas, as half floats. */
     place(brick) {

package/dist/render/driftLight/presence.d.ts

@@ -0,0 +1,50 @@
+/**
+ * How much of a DriftLight field is in the frame, and the radius inside which the frame's exact
+ * lights take over from it — the part every kind of field shares, kept once.
+ *
+ * **The radius shrinks at once and grows back slowly.** A pixel inside it that a left-out light
+ * reaches would be shaded short, so it cannot lag a shrink; a pixel it has not reached yet takes the
+ * summed light, which is only less exact, so a grow may ease. While nothing is summed the radius
+ * simply follows. The presence fades in over `fadeSec` once the field is whole, so a field
+ * completing in view does not pop — and a held clock never finishes a fade, so a field behind a
+ * loading screen asks for none.
+ */
+export declare class FieldPresence {
+    readonly fadeSec: number;
+    /** Where the frame's choice was centred, which the shader measures the radius from. */
+    readonly centre: Float32Array<ArrayBuffer>;
+    private eased;
+    private shown;
+    constructor(fadeSec: number);
+    /** The radius, in metres from `centre`, inside which lights are shaded exactly. */
+    get radius(): number;
+    /** How much of the summed light is in the frame, 0 until the field is whole, then up to 1. */
+    get presence(): number;
+    /** Follow the frame's choice: `complete` from the selection, centred at (x, y, z). */
+    follow(ready: boolean, complete: number, x: number, y: number, z: number, dtSec: number): void;
+}
+/**
+ * What a backend uploads and binds for a field of either kind, and what the uniforms are made of.
+ *
+ * A sparse field's index finds its bricks; a dense one brings a 1×1×1 index of nothing, so the
+ * upload and the bind are one code path, and says it is dense by a negative spacing.
+ */
+export interface DriftLightVolumes {
+    readonly ready: boolean;
+    /** Nothing summed at all: nothing to upload. */
+    readonly empty: boolean;
+    readonly indexDims: readonly [number, number, number];
+    readonly index: Uint32Array;
+    readonly atlasSize: readonly [number, number, number];
+    /** Half floats, four channels a texel, x fastest. */
+    readonly atlas: Uint16Array;
+    readonly presence: number;
+    readonly radius: number;
+    readonly band: number;
+    readonly scale: number;
+    readonly centre: Float32Array;
+    /** The world position of the first sample. */
+    readonly sampleOrigin: readonly [number, number, number];
+    /** Metres between samples, negative for a dense volume: the shader's mode. */
+    readonly signedSpacing: number;
+}

package/dist/render/driftLight/presence.js

@@ -0,0 +1,43 @@
+/**
+ * How much of a DriftLight field is in the frame, and the radius inside which the frame's exact
+ * lights take over from it — the part every kind of field shares, kept once.
+ *
+ * **The radius shrinks at once and grows back slowly.** A pixel inside it that a left-out light
+ * reaches would be shaded short, so it cannot lag a shrink; a pixel it has not reached yet takes the
+ * summed light, which is only less exact, so a grow may ease. While nothing is summed the radius
+ * simply follows. The presence fades in over `fadeSec` once the field is whole, so a field
+ * completing in view does not pop — and a held clock never finishes a fade, so a field behind a
+ * loading screen asks for none.
+ */
+/** How fast the shading radius grows back, per second, when the choice reaches further again. */
+const RADIUS_GROWTH_PER_SEC = 2;
+export class FieldPresence {
+    fadeSec;
+    /** Where the frame's choice was centred, which the shader measures the radius from. */
+    centre = new Float32Array(3);
+    eased = 0;
+    shown = 0;
+    constructor(fadeSec) {
+        this.fadeSec = fadeSec;
+    }
+    /** The radius, in metres from `centre`, inside which lights are shaded exactly. */
+    get radius() {
+        return this.eased;
+    }
+    /** How much of the summed light is in the frame, 0 until the field is whole, then up to 1. */
+    get presence() {
+        return this.shown;
+    }
+    /** Follow the frame's choice: `complete` from the selection, centred at (x, y, z). */
+    follow(ready, complete, x, y, z, dtSec) {
+        this.centre[0] = x;
+        this.centre[1] = y;
+        this.centre[2] = z;
+        if (this.shown <= 0 || complete < this.eased)
+            this.eased = complete;
+        else
+            this.eased += (complete - this.eased) * (1 - Math.exp(-RADIUS_GROWTH_PER_SEC * dtSec));
+        if (ready)
+            this.shown = this.fadeSec > 0 ? Math.min(1, this.shown + dtSec / this.fadeSec) : 1;
+    }
+}

package/dist/render/driftLight/uniforms.d.ts

@@ -13,11 +13,11 @@
  * pixel the shader shades exactly inside the radius the selection promised. A mirror's camera, far
  * from the centre, gets a smaller radius and more of the volume, which is the safe direction.
  */
-import type { LightField } from './lightField.ts';
+import type { DriftLightVolumes } from './presence.ts';
 export interface DriftLightUniforms {
     /** How much of the summed light is in, the radius, the band, the scale. */
     readonly light: Float32Array;
-    /** The first brick's first sample, and the metres between samples. */
+    /** The first sample, and the metres between samples — negative for a dense volume. */
     readonly origin: Float32Array;
 }
 export declare function createDriftLightUniforms(): DriftLightUniforms;
@@ -25,4 +25,4 @@ export declare function createDriftLightUniforms(): DriftLightUniforms;
  * Fill `out` for `field`, or for no field, seen from `eye`; `probePass` while a probe's faces are
  * being drawn.
  */
-export declare function resolveDriftLight(field: LightField | null, probePass: boolean, eye: ArrayLike<number>, out: DriftLightUniforms): void;
+export declare function resolveDriftLight(field: DriftLightVolumes | null, probePass: boolean, eye: ArrayLike<number>, out: DriftLightUniforms): void;

package/dist/render/driftLight/uniforms.js

@@ -24,18 +24,17 @@ export function createDriftLightUniforms() {
  * being drawn.
  */
 export function resolveDriftLight(field, probePass, eye, out) {
-    if (field === null || !field.ready || field.presence <= 0 || field.layout.count === 0) {
+    if (field === null || !field.ready || field.presence <= 0 || field.empty) {
         out.light.fill(0);
         return;
     }
-    const { layout } = field;
     const offset = Math.hypot((eye[0] ?? 0) - field.centre[0], (eye[1] ?? 0) - field.centre[1], (eye[2] ?? 0) - field.centre[2]);
     out.light[0] = field.presence;
     out.light[1] = probePass ? 0 : Math.max(0, field.radius - offset);
     out.light[2] = field.band;
     out.light[3] = field.scale;
-    out.origin[0] = layout.origin[0];
-    out.origin[1] = layout.origin[1];
-    out.origin[2] = layout.origin[2];
-    out.origin[3] = layout.spacing;
+    out.origin[0] = field.sampleOrigin[0];
+    out.origin[1] = field.sampleOrigin[1];
+    out.origin[2] = field.sampleOrigin[2];
+    out.origin[3] = field.signedSpacing;
 }

package/dist/render/driftLight/worldLightField.d.ts

@@ -0,0 +1,41 @@
+/**
+ * A world's DriftLight: a dense volume baked offline (`bakeDenseField`), handed to the renderer
+ * whole, standing in for every fixed light past the frame's exact choice.
+ *
+ * **Whole from the start**, because nothing is baked in the page: `ready` is true on construction
+ * and the volume fades in over `fadeSec` from the first `follow`. The lights it summed are the
+ * scene's to mark `inLightField`, so the selection knows not to count them twice — a volume carries
+ * no list of the lights it came from.
+ *
+ * **Light and direction side by side along y**, the short axis: a city is 256 samples across and a
+ * few dozen up, and a 3D texture promises 256 on every axis, so stacking the two there keeps both
+ * inside one texture and one sampler. The shader keeps each lookup inside its own half.
+ */
+import type { DenseLightVolume } from './denseField.ts';
+import type { DriftLightVolumes } from './presence.ts';
+export interface WorldLightFieldOptions {
+    /** Metres over which exact and summed light crossfade at the shading radius. Two by default. */
+    readonly band?: number;
+    /** Seconds the volume fades in over; zero behind a loading screen, whose clock may be held. */
+    readonly fadeSec?: number;
+}
+export declare class WorldLightField implements DriftLightVolumes {
+    readonly ready = true;
+    readonly empty = false;
+    readonly indexDims: readonly [number, number, number];
+    readonly index: Uint32Array<ArrayBuffer>;
+    readonly atlasSize: readonly [number, number, number];
+    readonly atlas: Uint16Array;
+    readonly band: number;
+    readonly sampleOrigin: readonly [number, number, number];
+    readonly signedSpacing: number;
+    /** The summed light's brightness, for a scene that dims all its lamps at once. */
+    scale: number;
+    private readonly showing;
+    constructor(volume: DenseLightVolume, options?: WorldLightFieldOptions);
+    get radius(): number;
+    get presence(): number;
+    get centre(): Float32Array;
+    /** Follow the frame's choice, as `LightField.follow` does. */
+    follow(complete: number, x: number, y: number, z: number, dtSec: number): void;
+}

package/dist/render/driftLight/worldLightField.js

@@ -0,0 +1,66 @@
+/**
+ * A world's DriftLight: a dense volume baked offline (`bakeDenseField`), handed to the renderer
+ * whole, standing in for every fixed light past the frame's exact choice.
+ *
+ * **Whole from the start**, because nothing is baked in the page: `ready` is true on construction
+ * and the volume fades in over `fadeSec` from the first `follow`. The lights it summed are the
+ * scene's to mark `inLightField`, so the selection knows not to count them twice — a volume carries
+ * no list of the lights it came from.
+ *
+ * **Light and direction side by side along y**, the short axis: a city is 256 samples across and a
+ * few dozen up, and a 3D texture promises 256 on every axis, so stacking the two there keeps both
+ * inside one texture and one sampler. The shader keeps each lookup inside its own half.
+ */
+import { halfBits } from '../halfFloat.js';
+import { FieldPresence } from './presence.js';
+/** The index a dense volume binds in the sparse one's place: one cell, no brick. */
+const NO_INDEX = new Uint32Array(1);
+export class WorldLightField {
+    ready = true;
+    empty = false;
+    indexDims = [1, 1, 1];
+    index = NO_INDEX;
+    atlasSize;
+    atlas;
+    band;
+    sampleOrigin;
+    signedSpacing;
+    /** The summed light's brightness, for a scene that dims all its lamps at once. */
+    scale = 1;
+    showing;
+    constructor(volume, options = {}) {
+        const [x, y, z] = volume.dims;
+        this.atlasSize = [x, y * 2, z];
+        this.atlas = new Uint16Array(x * y * 2 * z * 4);
+        for (let k = 0; k < z; k++) {
+            for (let j = 0; j < y; j++) {
+                for (let i = 0; i < x; i++) {
+                    const from = (i + x * (j + y * k)) * 4;
+                    const light = (i + x * (j + 2 * y * k)) * 4;
+                    const direction = (i + x * (j + y + 2 * y * k)) * 4;
+                    for (let c = 0; c < 4; c++) {
+                        this.atlas[light + c] = halfBits(volume.light[from + c]);
+                        this.atlas[direction + c] = halfBits(volume.direction[from + c]);
+                    }
+                }
+            }
+        }
+        this.band = options.band ?? 2;
+        this.sampleOrigin = volume.origin;
+        this.signedSpacing = -volume.spacing;
+        this.showing = new FieldPresence(Math.max(0, options.fadeSec ?? 0.5));
+    }
+    get radius() {
+        return this.showing.radius;
+    }
+    get presence() {
+        return this.showing.presence;
+    }
+    get centre() {
+        return this.showing.centre;
+    }
+    /** Follow the frame's choice, as `LightField.follow` does. */
+    follow(complete, x, y, z, dtSec) {
+        this.showing.follow(true, complete, x, y, z, dtSec);
+    }
+}

package/dist/render/fixtureAtlas.d.ts

@@ -0,0 +1,20 @@
+export interface FixtureAtlasLayout {
+    readonly width: number;
+    readonly height: number;
+    /** Rows of cookie tiles at the top: `COOKIE_TILE`, or 0 with none loaded. */
+    readonly cookieRows: number;
+    /** The first row of the profiles, below the cookies. */
+    readonly iesTop: number;
+}
+/** The atlas for `iesRows` rows of profile and `cookieTiles` cookies. */
+export declare function fixtureAtlasLayout(iesRows: number, cookieTiles: number): FixtureAtlasLayout;
+/**
+ * The profiles' rows as the atlas holds them: `data` one float a texel, `width` across and `rows`
+ * down, spread into the red channel of a four-channel image the atlas's size, the rest ones. The
+ * cookie band is left zero for the backend to fill from its images.
+ */
+export declare function fixtureAtlasTexels(layout: FixtureAtlasLayout, ies: {
+    readonly data: Float32Array;
+    readonly width: number;
+    readonly height: number;
+}): Float32Array;

package/dist/render/fixtureAtlas.js

@@ -0,0 +1,49 @@
+/**
+ * What a light fixture throws, in one texture: its spot cookies in the top band, its photometric
+ * profiles in the rows below.
+ *
+ * **One binding for two tables, because the lit stage had one sampler left.** The cookie atlas and
+ * the photometric atlas were two small float textures read with `textureLod`, and the widest lit
+ * shader bound fifteen of the sixteen fragment samplers WebGL2 guarantees — so the next sampler had
+ * to be found by folding two into one, which is what this is. Both describe a fixture's emission
+ * pattern, and both are 128 texels across, which is what lets them share a texture exactly.
+ *
+ * **Cookies on top, profiles at the bottom, and the order is load-bearing.** A profile's row blend
+ * 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.
+ *
+ * **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.
+ */
+import { IES_ATLAS_WIDTH } from './iesProfile.js';
+import { COOKIE_TILE } from './lightBudget.js';
+/** The atlas for `iesRows` rows of profile and `cookieTiles` cookies. */
+export function fixtureAtlasLayout(iesRows, cookieTiles) {
+    const cookieRows = cookieTiles > 0 ? COOKIE_TILE : 0;
+    return {
+        width: Math.max(IES_ATLAS_WIDTH, COOKIE_TILE * cookieTiles),
+        height: cookieRows + iesRows,
+        cookieRows,
+        iesTop: cookieRows,
+    };
+}
+/**
+ * The profiles' rows as the atlas holds them: `data` one float a texel, `width` across and `rows`
+ * down, spread into the red channel of a four-channel image the atlas's size, the rest ones. The
+ * cookie band is left zero for the backend to fill from its images.
+ */
+export function fixtureAtlasTexels(layout, ies) {
+    const out = new Float32Array(layout.width * layout.height * 4);
+    for (let row = 0; row < ies.height; row++) {
+        for (let x = 0; x < ies.width; x++) {
+            const at = ((layout.iesTop + row) * layout.width + x) * 4;
+            out[at] = ies.data[row * ies.width + x];
+            out[at + 1] = 1;
+            out[at + 2] = 1;
+            out[at + 3] = 1;
+        }
+    }
+    return out;
+}

package/dist/render/glass.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Glass: how much light a surface lets through, how milky it is, and the colour it takes.
+ *
+ * **A thin pane, not a volume.** Glass here is a surface that shows the scene behind it — by
+ * `transmission`, blurred by `frost`, tinted — keeps its own highlight and reflection, and glows
+ * with the lights behind it in proportion to how frosted it is. The one depth it has is the path
+ * absorption refraction already applies (`TranslucentMeshOptions.thicknessM`). What it gives up is
+ * everything a solid of glass does inside itself: a sculpture or a thick block under-darkens and
+ * does not bend light twice. What would make it wrong is a scene whose glass is mostly that.
+ *
+ * **Zero transmission is not glass**, whatever the frost says: a surface letting nothing through is
+ * opaque, and every branch the shader gates on transmission is skipped for it. This module is also
+ * the reference the shader's Fresnel is held to (`schlickFresnel`), stated once in TypeScript.
+ */
+import type { Vec3 } from '../math/color.ts';
+export interface GlassOptions {
+    /** Share of light that passes, 0 (opaque) to 1 (clear). */
+    readonly transmission: number;
+    /** How milky, 0 (see-through) to 1 (fully diffusing: what is behind is blurred away). */
+    readonly frost: number;
+    /** The colour light takes through it. White, the default, is clear glass. */
+    readonly tint?: Vec3;
+}
+/** A `GlassOptions` clamped and defaulted, in a caller-owned object so a draw allocates nothing. */
+export interface ResolvedGlass {
+    transmission: number;
+    frost: number;
+    tint: [number, number, number];
+}
+/**
+ * Resolve `options` into `out`, and say whether it is glass at all.
+ *
+ * Not glass — absent, or letting nothing through — zeroes `out` and tints it white, so a binder that
+ * uploads `out` either way uploads the state that switches the shader's glass branch off.
+ */
+export declare function resolveGlass(options: GlassOptions | undefined, out: ResolvedGlass): boolean;
+/**
+ * Schlick's Fresnel for glass, `F0 = 0.04`: the share of light a pane reflects at a view angle.
+ *
+ * `cosView` is clamped at 0.05, the floor the shader's path length already uses, so a silhouette
+ * seen exactly edge-on is a very reflective pane rather than a division by zero.
+ */
+export declare function schlickFresnel(cosView: number): number;
+/** How much of what is behind a pane is seen through it at a view angle. */
+export declare function glassSeenShare(transmission: number, cosView: number): number;

package/dist/render/glass.js

@@ -0,0 +1,39 @@
+const clamp01 = (value) => Math.min(1, Math.max(0, value));
+/**
+ * Resolve `options` into `out`, and say whether it is glass at all.
+ *
+ * Not glass — absent, or letting nothing through — zeroes `out` and tints it white, so a binder that
+ * uploads `out` either way uploads the state that switches the shader's glass branch off.
+ */
+export function resolveGlass(options, out) {
+    const transmission = clamp01(options?.transmission ?? 0);
+    if (options === undefined || transmission <= 0) {
+        out.transmission = 0;
+        out.frost = 0;
+        out.tint[0] = 1;
+        out.tint[1] = 1;
+        out.tint[2] = 1;
+        return false;
+    }
+    out.transmission = transmission;
+    out.frost = clamp01(options.frost);
+    const tint = options.tint;
+    out.tint[0] = tint === undefined ? 1 : clamp01(tint[0]);
+    out.tint[1] = tint === undefined ? 1 : clamp01(tint[1]);
+    out.tint[2] = tint === undefined ? 1 : clamp01(tint[2]);
+    return true;
+}
+/**
+ * Schlick's Fresnel for glass, `F0 = 0.04`: the share of light a pane reflects at a view angle.
+ *
+ * `cosView` is clamped at 0.05, the floor the shader's path length already uses, so a silhouette
+ * seen exactly edge-on is a very reflective pane rather than a division by zero.
+ */
+export function schlickFresnel(cosView) {
+    const c = Math.min(1, Math.max(0.05, cosView));
+    return 0.04 + 0.96 * (1 - c) ** 5;
+}
+/** How much of what is behind a pane is seen through it at a view angle. */
+export function glassSeenShare(transmission, cosView) {
+    return transmission * (1 - schlickFresnel(cosView));
+}