@driftengine/core 4.4.2 → 4.6.0

package/src/render/driftLight/denseField.ts

@@ -0,0 +1,149 @@
+/**
+ * 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 type { FieldLight } from './bake.ts';
+import { sampleFieldLight } from './bake.ts';
+import type { PointLightFalloff } from './falloff.ts';
+import type { DistanceAt } from './visibility.ts';
+
+/** 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;
+
+export interface DenseLightVolume {
+  /** The world position of sample (0, 0, 0). */
+  readonly origin: readonly [number, number, number];
+  /** Metres between two samples. */
+  readonly spacing: number;
+  /** Samples on each axis. */
+  readonly dims: readonly [number, number, number];
+  /** Four floats a sample, x fastest then y then z: the colour, then 1 for a sample and 0 inside. */
+  readonly light: Float32Array;
+  /** Four floats a sample: the direction light arrives from, weighted by brightness, then 0. */
+  readonly direction: Float32Array;
+}
+
+/**
+ * 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: readonly FieldLight[],
+  falloff: PointLightFalloff,
+  distance: DistanceAt | null,
+  bounds: ArrayLike<number>,
+  spacing: number,
+): DenseLightVolume {
+  if (!(spacing > 0)) throw new Error(`bakeDenseField: spacing is ${String(spacing)}`);
+  const origin: [number, number, number] = [
+    bounds[0] as number,
+    bounds[1] as number,
+    bounds[2] as number,
+  ];
+  const dims: [number, number, number] = [0, 0, 0];
+  for (let axis = 0; axis < 3; axis++) {
+    const extent = (bounds[axis + 3] as number) - (origin[axis] as number);
+    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),
+  ] as const;
+  const bucketCount = buckets[0] * buckets[1] * buckets[2];
+  const span = spacing * BUCKET;
+  const range = (light: FieldLight, axis: number, out: Int32Array): boolean => {
+    const at = axis === 0 ? light.x : axis === 1 ? light.y : light.z;
+    const lo = Math.floor((at - light.radius - (origin[axis] as number)) / span);
+    const hi = Math.floor((at + light.radius - (origin[axis] as number)) / span);
+    out[axis * 2] = Math.max(0, lo);
+    out[axis * 2 + 1] = Math.min((buckets[axis] as number) - 1, hi);
+    return (out[axis * 2] as number) <= (out[axis * 2 + 1] as number);
+  };
+  const cells = new Int32Array(6);
+  const start = new Uint32Array(bucketCount + 1);
+  const each = (fill: (bucket: number, light: number) => void): void => {
+    for (let index = 0; index < lights.length; index++) {
+      const light = lights[index] as FieldLight;
+      if (!(light.radius > 0)) continue;
+      if (!range(light, 0, cells) || !range(light, 1, cells) || !range(light, 2, cells)) continue;
+      for (let z = cells[4] as number; z <= (cells[5] as number); z++) {
+        for (let y = cells[2] as number; y <= (cells[3] as number); y++) {
+          for (let x = cells[0] as number; x <= (cells[1] as number); x++) {
+            fill(x + buckets[0] * (y + buckets[1] * z), index);
+          }
+        }
+      }
+    }
+  };
+  each((bucket) => {
+    start[bucket + 1] = (start[bucket + 1] as number) + 1;
+  });
+  for (let b = 0; b < bucketCount; b++)
+    start[b + 1] = (start[b + 1] as number) + (start[b] as number);
+  const listed = new Uint32Array(start[bucketCount] as number);
+  const cursor = start.slice(0, bucketCount);
+  each((bucket, light) => {
+    listed[cursor[bucket] as number] = light;
+    cursor[bucket] = (cursor[bucket] as number) + 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] as number,
+          start[bucket + 1] as number,
+          falloff,
+          distance,
+          light,
+          direction,
+          (i + dims[0] * (j + dims[1] * k)) * 4,
+        );
+      }
+    }
+  }
+  return { origin, spacing, dims, light, direction };
+}

package/src/render/driftLight/lightField.ts

@@ -34,11 +34,11 @@ import type { FieldLight } from './bake.ts';
 import type { PointLightFalloff } from './falloff.ts';
 import { BRICK_SAMPLES, layoutLightField } from './layout.ts';
 import type { LightFieldLayout } from './layout.ts';
+import { FieldPresence } from './presence.ts';
+import type { DriftLightVolumes } from './presence.ts';
 
 /** 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: readonly [number, number, number] = [32, 64, 64];
 /** A brick's footprint in the atlas: its light block and its direction block side by side. */
@@ -66,7 +66,7 @@ export interface LightFieldOptions {
   readonly fadeSec?: number;
 }
 
-export class LightField {
+export class LightField implements DriftLightVolumes {
   readonly layout: LightFieldLayout;
   /** Texels on each axis of the atlas. */
   readonly atlasSize: readonly [number, number, number];
@@ -82,18 +82,15 @@ export class LightField {
   readonly fadeSec: number;
   /** 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. */
-  readonly centre = new Float32Array(3);
 
   private readonly lights: readonly FieldLight[];
   private readonly falloff: PointLightFalloff;
   private readonly distance: ((x: number, y: number, z: number) => number) | null;
   private readonly lightBlock = new Float32Array(BRICK_TEXELS * 4);
   private readonly directionBlock = new Float32Array(BRICK_TEXELS * 4);
+  private readonly showing: FieldPresence;
   private baked = 0;
   private taken = 0;
-  private eased = 0;
-  private shown = 0;
 
   constructor(lights: readonly LightFieldSource[], options: LightFieldOptions) {
     for (const light of lights) light.inLightField = true;
@@ -110,6 +107,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;
@@ -143,12 +141,37 @@ export class LightField {
 
   /** The radius, in metres from `centre`, inside which lights are shaded exactly. */
   get radius(): number {
-    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(): number {
-    return this.shown;
+    return this.showing.presence;
+  }
+
+  /** Where the frame's choice was centred, which the shader measures the radius from. */
+  get centre(): Float32Array {
+    return this.showing.centre;
+  }
+
+  get empty(): boolean {
+    return this.layout.count === 0;
+  }
+
+  get indexDims(): readonly [number, number, number] {
+    return this.layout.dims;
+  }
+
+  get index(): Uint32Array {
+    return this.layout.index;
+  }
+
+  get sampleOrigin(): readonly [number, number, number] {
+    return this.layout.origin;
+  }
+
+  get signedSpacing(): number {
+    return this.layout.spacing;
   }
 
   /** The texel at which brick `brick`'s light block starts; its direction block is 4 along x. */
@@ -195,15 +218,7 @@ export class LightField {
    * which is only less exact. While nothing is summed the radius simply follows.
    */
   follow(complete: number, x: number, y: number, z: number, dtSec: number): void {
-    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. */

package/src/render/driftLight/presence.ts

@@ -0,0 +1,69 @@
+/**
+ * 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 {
+  /** Where the frame's choice was centred, which the shader measures the radius from. */
+  readonly centre = new Float32Array(3);
+  private eased = 0;
+  private shown = 0;
+
+  constructor(readonly fadeSec: number) {}
+
+  /** The radius, in metres from `centre`, inside which lights are shaded exactly. */
+  get radius(): number {
+    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(): number {
+    return this.shown;
+  }
+
+  /** 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 {
+    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;
+  }
+}
+
+/**
+ * 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/src/render/driftLight/uniforms.ts

@@ -14,12 +14,12 @@
  * 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;
 }
 
@@ -35,16 +35,15 @@ export function createDriftLightUniforms(): DriftLightUniforms {
  * being drawn.
  */
 export function resolveDriftLight(
-  field: LightField | null,
+  field: DriftLightVolumes | null,
   probePass: boolean,
   eye: ArrayLike<number>,
   out: DriftLightUniforms,
 ): void {
-  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] as number),
     (eye[1] ?? 0) - (field.centre[1] as number),
@@ -54,8 +53,8 @@ export function resolveDriftLight(
   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/src/render/driftLight/worldLightField.ts

@@ -0,0 +1,83 @@
+/**
+ * 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.ts';
+import type { DenseLightVolume } from './denseField.ts';
+import { FieldPresence } from './presence.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;
+}
+
+/** 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 implements DriftLightVolumes {
+  readonly ready = true;
+  readonly empty = false;
+  readonly indexDims: readonly [number, number, number] = [1, 1, 1];
+  readonly index = NO_INDEX;
+  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 = 1;
+  private readonly showing: FieldPresence;
+
+  constructor(volume: DenseLightVolume, options: WorldLightFieldOptions = {}) {
+    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] as number);
+            this.atlas[direction + c] = halfBits(volume.direction[from + c] as number);
+          }
+        }
+      }
+    }
+    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(): number {
+    return this.showing.radius;
+  }
+
+  get presence(): number {
+    return this.showing.presence;
+  }
+
+  get centre(): Float32Array {
+    return this.showing.centre;
+  }
+
+  /** Follow the frame's choice, as `LightField.follow` does. */
+  follow(complete: number, x: number, y: number, z: number, dtSec: number): void {
+    this.showing.follow(true, complete, x, y, z, dtSec);
+  }
+}

package/src/render/fixtureAtlas.ts

@@ -0,0 +1,63 @@
+/**
+ * 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.ts';
+import { COOKIE_TILE } from './lightBudget.ts';
+
+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 function fixtureAtlasLayout(iesRows: number, cookieTiles: number): FixtureAtlasLayout {
+  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: FixtureAtlasLayout,
+  ies: { readonly data: Float32Array; readonly width: number; readonly height: number },
+): Float32Array {
+  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] as number;
+      out[at + 1] = 1;
+      out[at + 2] = 1;
+      out[at + 3] = 1;
+    }
+  }
+  return out;
+}

package/src/render/glass.ts

@@ -0,0 +1,74 @@
+/**
+ * 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];
+}
+
+const clamp01 = (value: number): number => 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: GlassOptions | undefined, out: ResolvedGlass): boolean {
+  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: number): number {
+  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: number, cosView: number): number {
+  return transmission * (1 - schlickFresnel(cosView));
+}