@driftengine/core 4.13.3 → 4.13.5

package/dist/render/fog.d.ts

@@ -42,6 +42,25 @@ export interface FogOptions {
      */
     readonly near: number;
     readonly far: number;
+    /** The medium's second layer: its extinction per metre at the camera's height. Absent, none. */
+    readonly density2?: number;
+    /** And its reciprocal scale height. */
+    readonly heightFalloff2?: number;
+    /**
+     * The least of a surface the haze must leave, `Atmosphere.fogMaxOpacity`'s complement. Absent or 0,
+     * no floor.
+     */
+    readonly floor?: number;
+    /** Metres past which the haze hides nothing. Absent or 0, none. */
+    readonly cutoff?: number;
+    /** The sun's glow in the haze: its colour. Absent or black, none. */
+    readonly glowColour?: Rgb;
+    /** The glow's lobe: the cosine of the angle from its light, to this power. */
+    readonly glowExponent?: number;
+    /** Surface → the glow's light, a unit vector. */
+    readonly glowDirection?: Rgb;
+    /** Metres past the haze's start before the glow begins. */
+    readonly glowStart?: number;
 }
 /** What distance converges toward: the day's haze, or the water column. */
 export declare function mediumColour(fog: FogOptions): [number, number, number];
@@ -50,6 +69,19 @@ export declare function mediumColour(fog: FogOptions): [number, number, number];
  * 0 is perfectly clear, 1 is the medium's own colour.
  */
 export declare function mediumFog(fog: FogOptions, dist: number, pointY: number): number;
+/**
+ * The haze's optical depth from where it begins along the ray to a point at `pointY`, `dist` metres
+ * away: each layer's density at the eye carried over what is left of the ray, the second only where
+ * there is one. `mediumFog` and `mediumGlow` both integrate it.
+ */
+export declare function hazeDepth(fog: FogOptions, dist: number, pointY: number): number;
+/**
+ * The sun's light the haze scatters toward the eye along a ray to a point at `pointY`, `dist`
+ * metres away in the unit direction `toPoint`, into `out`: added after the fog, never mixed. A lobe
+ * of `cos^exponent` about the light, by as much of the ray past the glow's start as the haze hides.
+ * None in a linear ramp, past the cutoff, or under water.
+ */
+export declare function mediumGlow(fog: FogOptions, dist: number, pointY: number, toPoint: ArrayLike<number>, out: [number, number, number]): [number, number, number];
 /** `FogOptions` with its fields writable, which is what a caller holds and refills a frame at a time. */
 export interface FogTarget {
     colour: [number, number, number];
@@ -62,6 +94,14 @@ export interface FogTarget {
     mode: number;
     near: number;
     far: number;
+    density2: number;
+    heightFalloff2: number;
+    floor: number;
+    cutoff: number;
+    glowColour: [number, number, number];
+    glowExponent: number;
+    glowDirection: [number, number, number];
+    glowStart: number;
 }
 /** A target for `atmosphereFog`, allocated once, outside the frame loop. */
 export declare function createFogTarget(): FogTarget;
@@ -79,4 +119,6 @@ export declare function createFogTarget(): FogTarget;
  * @param underwater The renderer's `underwaterAtmosphere` quality, which gates the second medium
  * on the forward path; pass the same.
  */
-export declare function atmosphereFog(atmosphere: Atmosphere, eyeY: number, underwater: boolean, out: FogTarget): FogTarget;
+export declare function atmosphereFog(atmosphere: Atmosphere & {
+    readonly directionalDir?: ArrayLike<number>;
+}, eyeY: number, underwater: boolean, out: FogTarget): FogTarget;

package/dist/render/fog.js

@@ -16,7 +16,7 @@
  * block that declares everything it uses can be pasted into any program; a function takes them as
  * one argument instead, and the backends keep their own packing.
  */
-import { resolveAtmosphere } from './atmosphere.js';
+import { createResolvedAtmosphere, resolveAtmosphere, } from './atmosphere.js';
 /** Beer-Lambert through a haze layer that thins with height. `uFogMode` 0. */
 export const MEDIUM_FOG = 0;
 /** A ramp between two distances, which is a look rather than a medium. `uFogMode` 1. */
@@ -53,15 +53,37 @@ export function mediumFog(fog, dist, pointY) {
      * is perfectly clear, which Beer-Lambert can never be, and height falloff has no meaning here
      * because a ramp is defined on distance alone. `shaders/fog.ts` argues the whole of it.
      */
+    /* Past the cutoff the air hides nothing, in either mode; the water column keeps its own law. */
+    const cutoff = fog.cutoff ?? 0;
+    const cut = cutoff > 0 && dist > cutoff;
+    const floor = fog.floor ?? 0;
     if (fog.mode === LINEAR_FOG) {
         /* A consumer asking for a hard cut writes `far === near`; the guard is why that is a cut. */
         const span = Math.max(fog.far - fog.near, 1e-4);
-        const ramp = Math.min(1, Math.max(0, (dist - fog.near) / span));
+        const ramp = cut ? 0 : Math.min(Math.min(1, Math.max(0, (dist - fog.near) / span)), 1 - floor);
         if (fog.underwaterFactor <= 0)
             return ramp;
         const wetLinear = fog.underwaterDensity * dist;
         return mix(ramp, 1 - Math.pow(2, -wetLinear * wetLinear * 1.442695), fog.underwaterFactor);
     }
+    /*
+     * Beer-Lambert through both layers, leaving at least `floor` of the surface: a floor on what
+     * survives rather than a ceiling on the depth, so the curve keeps its shape above it.
+     */
+    const air = cut ? 0 : 1 - Math.max(Math.exp(-hazeDepth(fog, dist, pointY)), floor);
+    if (fog.underwaterFactor <= 0)
+        return air;
+    /* Water is its own medium and keeps its own curve, so crossing the surface changes nothing
+       about how the water column reads. */
+    const wet = fog.underwaterDensity * dist;
+    return mix(air, 1 - Math.pow(2, -wet * wet * 1.442695), fog.underwaterFactor);
+}
+/**
+ * The haze's optical depth from where it begins along the ray to a point at `pointY`, `dist` metres
+ * away: each layer's density at the eye carried over what is left of the ray, the second only where
+ * there is one. `mediumFog` and `mediumGlow` both integrate it.
+ */
+export function hazeDepth(fog, dist, pointY) {
     /*
      * **Where the medium begins along the ray**, `near` — the linear mode's slot, which this mode
      * never read before `Atmosphere.fogStart`. The ray is integrated from that point on: the density
@@ -77,14 +99,50 @@ export function mediumFog(fog, dist, pointY) {
      * `t = 0` the quotient is 0/0, and 1e-4 of a scale height is 8 mm.
      */
     const denom = Math.abs(rest) < 1e-4 ? 1e-4 : rest;
-    const air = 1 -
-        Math.exp((-fog.density * Math.exp(-t * before) * (dist - start) * (1 - Math.exp(-denom))) / denom);
-    if (fog.underwaterFactor <= 0)
-        return air;
-    /* Water is its own medium and keeps its own curve, so crossing the surface changes nothing
-       about how the water column reads. */
-    const wet = fog.underwaterDensity * dist;
-    return mix(air, 1 - Math.pow(2, -wet * wet * 1.442695), fog.underwaterFactor);
+    let depth = (fog.density * Math.exp(-t * before) * (dist - start) * (1 - Math.exp(-denom))) / denom;
+    const density2 = fog.density2 ?? 0;
+    if (density2 > 0) {
+        const t2 = (pointY - fog.eyeY) * (fog.heightFalloff2 ?? 0);
+        const rest2 = t2 * (1 - before);
+        const denom2 = Math.abs(rest2) < 1e-4 ? 1e-4 : rest2;
+        depth +=
+            (density2 * Math.exp(-t2 * before) * (dist - start) * (1 - Math.exp(-denom2))) / denom2;
+    }
+    return depth;
+}
+/**
+ * The sun's light the haze scatters toward the eye along a ray to a point at `pointY`, `dist`
+ * metres away in the unit direction `toPoint`, into `out`: added after the fog, never mixed. A lobe
+ * of `cos^exponent` about the light, by as much of the ray past the glow's start as the haze hides.
+ * None in a linear ramp, past the cutoff, or under water.
+ */
+export function mediumGlow(fog, dist, pointY, toPoint, out) {
+    out[0] = 0;
+    out[1] = 0;
+    out[2] = 0;
+    const colour = fog.glowColour;
+    if (fog.mode === LINEAR_FOG || colour === undefined)
+        return out;
+    if (Math.max(colour[0], colour[1], colour[2]) <= 0)
+        return out;
+    const cutoff = fog.cutoff ?? 0;
+    if (cutoff > 0 && dist > cutoff)
+        return out;
+    const span = dist - Math.min(fog.near, dist);
+    if (span <= 0)
+        return out;
+    const perMetre = hazeDepth(fog, dist, pointY) / span;
+    const hidden = 1 - Math.exp(-perMetre * Math.max(span - (fog.glowStart ?? 0), 0));
+    const toward = fog.glowDirection ?? [0, 1, 0];
+    const cosine = toPoint[0] * toward[0] +
+        toPoint[1] * toward[1] +
+        toPoint[2] * toward[2];
+    const lobe = Math.pow(Math.min(1, Math.max(0, cosine)), fog.glowExponent ?? 1);
+    const share = lobe * hidden * (1 - fog.underwaterFactor);
+    out[0] = colour[0] * share;
+    out[1] = colour[1] * share;
+    out[2] = colour[2] * share;
+    return out;
 }
 /** A target for `atmosphereFog`, allocated once, outside the frame loop. */
 export function createFogTarget() {
@@ -99,21 +157,18 @@ export function createFogTarget() {
         mode: MEDIUM_FOG,
         near: 0,
         far: 1,
+        density2: 0,
+        heightFalloff2: 0,
+        floor: 0,
+        cutoff: 0,
+        glowColour: [0, 0, 0],
+        glowExponent: 1,
+        glowDirection: [0, 1, 0],
+        glowStart: 0,
     };
 }
 /** `resolveAtmosphere`'s own target, reused, because this runs a frame at a time. */
-const RESOLVED = {
-    fogColor: new Float32Array(3),
-    underwaterColor: new Float32Array(3),
-    fogDensity: 0,
-    fogHeightFalloff: 0,
-    fogEyeY: 0,
-    fogMode: 0,
-    fogNear: 0,
-    fogFar: 1,
-    underwaterFogDensity: 0,
-    underwaterFactor: 0,
-};
+const RESOLVED = createResolvedAtmosphere();
 /**
  * The haze an `Environment` makes at a camera's height, as `GpuDrivenView.fog` takes it.
  *
@@ -144,5 +199,15 @@ export function atmosphereFog(atmosphere, eyeY, underwater, out) {
     out.mode = medium.fogMode;
     out.near = medium.fogNear;
     out.far = medium.fogFar;
+    out.density2 = medium.fogLayer2[0];
+    out.heightFalloff2 = medium.fogLayer2[1];
+    out.floor = medium.fogLayer2[2];
+    out.cutoff = medium.fogLayer2[3];
+    for (let c = 0; c < 3; c++) {
+        out.glowColour[c] = medium.fogGlow[c];
+        out.glowDirection[c] = medium.fogGlowDir[c];
+    }
+    out.glowExponent = medium.fogGlow[3];
+    out.glowStart = medium.fogGlowDir[3];
     return out;
 }

package/dist/render/globalMedium.d.ts

@@ -11,6 +11,10 @@
  * and this asks what the journey adds — which is every point along it the sun can see, and is the
  * only one of the two that can put the shape of a doorway on a floor.
  */
+import type { Vec3 } from '../math/color.ts';
+import type { FogLayer } from './atmosphere.ts';
+import type { ResolvedPointLights } from './lightBudget.ts';
+import type { ResolvedPointShadows } from './pointShadowImage.ts';
 /**
  * The most steps a march may take, which is the shader's own loop bound.
  *
@@ -38,6 +42,11 @@ export declare const MAX_GLOBAL_MEDIUM_STEPS = 64;
  * entitled to it and to the frame rate that comes with it.
  */
 export declare const WEAK_GPU_MEDIUM_STEPS = 16;
+/**
+ * The most lamps the march lights the medium with, which is the lit stage's own per-pixel set:
+ * the lamps a frame shades with uniforms, each with the shadow it already has.
+ */
+export declare const MAX_MEDIUM_LAMPS = 16;
 /**
  * How thick the air is, this frame.
  *
@@ -55,13 +64,15 @@ export interface GlobalMediumOptions {
      */
     readonly density: number;
     /**
-     * How much of what the medium takes out of a ray comes back as light rather than as heat, 0 to 1.
+     * How much of what the medium takes out of a ray comes back as light rather than as heat, 0 to 1,
+     * or a colour, a share a channel.
      *
      * Near 1 for water droplets, which is fog, cloud and steam; lower for smoke, which is soot and
      * absorbs most of what it intercepts. It is the difference between a white fog that a torch
-     * lights up and a black smoke that swallows the same torch.
+     * lights up and a black smoke that swallows the same torch. A colour is a medium that keeps more
+     * of one light than another: a faintly blue haze returns the sky's blue a little more readily.
      */
-    readonly albedo: number;
+    readonly albedo: number | Vec3;
     /**
      * Henyey-Greenstein anisotropy, -1 back to 1 forward. 0 is isotropic.
      *
@@ -72,14 +83,58 @@ export interface GlobalMediumOptions {
      */
     readonly anisotropy: number;
     /**
-     * Where the march stops, in metres. Beyond it the medium is not sampled and nothing is added.
+     * Where the medium ends, in metres: past it the air neither scatters nor absorbs.
      *
-     * A bound on the *integral*, not on the fog: extinction is still integrated over the whole
-     * distance a ray travels, so a far wall behind this bound is still obscured. What stops is the
-     * search for light to scatter, which is what costs — and past a few extinction lengths there is
-     * no transmittance left for a sample to contribute through.
+     * **This said extinction went on past it, and the march never did that**: it integrates from
+     * the eye to here or to the surface, whichever is nearer, and nothing after. Which is what a
+     * medium standing for the near part of the environment's haze wants: the haze takes the rest of
+     * the ray when its `fogStart` is this distance, and the two never lay one stretch of air twice.
+     * **What it gives up** is a medium of its own beyond the reach, which the haze has to be.
+     */
+    readonly maxDistance: number;
+    /**
+     * Reciprocal scale height, per metre: `density` is the extinction at `baseY`, thinning above it
+     * as the haze does (`Atmosphere.fogHeightFalloff`). Absent or 0, the medium is as thick
+     * everywhere, as it always was.
      */
+    readonly heightFalloff?: number;
+    /** The height `density` is measured at. Default 0. */
+    readonly baseY?: number;
+    /**
+     * A second layer, summed with the first, its own density at its own height thinning by its own
+     * falloff: `Atmosphere.fogLayer2`'s shape, so a medium standing for the near part of a two-layer
+     * haze can be that haze.
+     */
+    readonly layer2?: FogLayer | null;
+    /** How strongly the sun scatters in it, as a share of how strongly it lights a surface. Default 1. */
+    readonly sunScatter?: number;
+    /** The same for the sky's fill, which lights a shadowed medium from every side. Default 1. */
+    readonly skyScatter?: number;
+    /**
+     * The same for the lamps, each through its own shadow and times its own `lightMediumScatter`.
+     * **Default 0**: a medium was the sun's and the sky's until there was this, and a scene that
+     * never asks keeps that picture and that cost. The lamps are the lit stage's per-pixel set,
+     * shaped by their cones; a photometric profile and a cookie shape the pool on a surface and not
+     * the shaft in the air.
+     */
+    readonly lampScatter?: number;
+}
+/** A medium with every field filled in and clamped: what both backends' passes are handed. */
+export interface ResolvedGlobalMedium {
+    readonly density: number;
+    /** A colour, three shares. */
+    readonly albedo: readonly [number, number, number];
+    readonly anisotropy: number;
     readonly maxDistance: number;
+    readonly heightFalloff: number;
+    readonly baseY: number;
+    /** The second layer's density at its own height, 0 for none, its falloff and that height. */
+    readonly density2: number;
+    readonly heightFalloff2: number;
+    readonly baseY2: number;
+    readonly sunScatter: number;
+    readonly skyScatter: number;
+    readonly lampScatter: number;
 }
 /**
  * What a renderer starts with: off, and everything else at a value that means "ordinary air".
@@ -97,7 +152,16 @@ export declare const DEFAULT_GLOBAL_MEDIUM: GlobalMediumOptions;
  * function by zero, which is a NaN that a half-float target spreads over the whole screen rather
  * than reporting; a `maxDistance` of zero is a march with no length that still costs its steps.
  */
-export declare function resolveGlobalMedium(options: Partial<GlobalMediumOptions>): GlobalMediumOptions;
+export declare function resolveGlobalMedium(options: Partial<GlobalMediumOptions>): ResolvedGlobalMedium;
+/** `setGlobalMedium`'s object form: a density, and any of the rest. */
+export type GlobalMediumSettings = Partial<GlobalMediumOptions> & {
+    readonly density: number;
+};
+/**
+ * `setGlobalMedium`'s two forms, its four numbers or the object, read one way for both backends:
+ * a density that is not a number is none.
+ */
+export declare function resolveGlobalMediumSettings(density: number | GlobalMediumSettings, albedo?: number | Vec3, anisotropy?: number, maxDistance?: number): ResolvedGlobalMedium;
 /**
  * Whether this frame draws the medium at all.
  *
@@ -105,7 +169,7 @@ export declare function resolveGlobalMedium(options: Partial<GlobalMediumOptions
  * `density: 0` is pixel-identical to the pass being absent is only true if neither backend runs a
  * composite at zero, and a second copy of this test is where that stops being true.
  */
-export declare function mediumActive(options: GlobalMediumOptions, steps: number): boolean;
+export declare function mediumActive(options: Pick<GlobalMediumOptions, 'density'>, steps: number): boolean;
 /**
  * The march's target size.
  *
@@ -122,3 +186,41 @@ export declare function mediumTargetSize(width: number, height: number, halfReso
     width: number;
     height: number;
 };
+/**
+ * The lamps as the march reads them: eight vectors a lamp, each array `MAX_MEDIUM_LAMPS` of them.
+ *
+ * **Decided here and bound twice**, on the split `resolvePointLights` draws: which lamps light the
+ * medium, how bright and through which maps is arithmetic both backends run, and a backend only
+ * uploads the arrays. A lamp's shadows are the lit stage's own, the static map and the live one,
+ * read where the frame left them, so the shaft in the air and the pool on the floor are cut by the
+ * same casters.
+ */
+export interface ResolvedMediumLamps {
+    /** How many lamps light the medium: none while `lampScatter` is 0. */
+    count: number;
+    /** 1 for inverse-square, 0 for the smooth falloff: the frame's own rule. */
+    falloff: number;
+    /** Where each lamp is, and how far it reaches. */
+    readonly position: Float32Array;
+    /** Its colour, times its presence and its scatter, and its own falloff exponent (0 for none). */
+    readonly color: Float32Array;
+    /** The direction it shines, a spot's axis: `lightDirections`. */
+    readonly aim: Float32Array;
+    /** Its cone's two cosines, inner and outer, as the lit stage takes them. */
+    readonly cone: Float32Array;
+    /** Its static shadow: the layer (−1 for none), the near plane, and how present the map is. */
+    readonly shadow: Float32Array;
+    /** The static map's projection: its origin and its far plane. */
+    readonly shadowAt: Float32Array;
+    /** Its live shadow, by the same layout, and the live map's projection. */
+    readonly live: Float32Array;
+    readonly liveAt: Float32Array;
+}
+/** A target for `resolveMediumLamps`, made once outside the frame loop. */
+export declare function createResolvedMediumLamps(): ResolvedMediumLamps;
+/**
+ * The frame's lamps as the medium is lit by them, into `out`: the lit stage's resolved lamps and
+ * their resolved shadows, a lamp's scatter `lampScatter` times its own `lightMediumScatter` (1 where
+ * absent). Allocates nothing; a lamp past the count keeps whatever it held, which nothing reads.
+ */
+export declare function resolveMediumLamps(medium: ResolvedGlobalMedium, lights: ResolvedPointLights, shadows: ResolvedPointShadows | null, scatter: Float32Array | undefined, out: ResolvedMediumLamps): ResolvedMediumLamps;

package/dist/render/globalMedium.js

@@ -11,6 +11,7 @@
  * and this asks what the journey adds — which is every point along it the sun can see, and is the
  * only one of the two that can put the shape of a doorway on a floor.
  */
+import { MAX_POINT_LIGHTS } from './lightBudget.js';
 /**
  * The most steps a march may take, which is the shader's own loop bound.
  *
@@ -38,6 +39,11 @@ export const MAX_GLOBAL_MEDIUM_STEPS = 64;
  * entitled to it and to the frame rate that comes with it.
  */
 export const WEAK_GPU_MEDIUM_STEPS = 16;
+/**
+ * The most lamps the march lights the medium with, which is the lit stage's own per-pixel set:
+ * the lamps a frame shades with uniforms, each with the shadow it already has.
+ */
+export const MAX_MEDIUM_LAMPS = MAX_POINT_LIGHTS;
 /**
  * What a renderer starts with: off, and everything else at a value that means "ordinary air".
  *
@@ -61,14 +67,47 @@ export const DEFAULT_GLOBAL_MEDIUM = {
  */
 export function resolveGlobalMedium(options) {
     const d = DEFAULT_GLOBAL_MEDIUM;
+    const albedo = options.albedo ?? d.albedo;
+    const share = (value) => Math.min(1, Math.max(0, Number.isFinite(value) ? value : 0));
+    const layer2 = options.layer2 ?? null;
+    const density2 = layer2 === null ? 0 : Math.max(0, layer2.density);
+    const finite = (value, fallback) => value !== undefined && Number.isFinite(value) ? value : fallback;
     return {
         density: Math.max(0, options.density ?? d.density),
-        albedo: Math.min(1, Math.max(0, options.albedo ?? d.albedo)),
+        albedo: typeof albedo === 'number'
+            ? [share(albedo), share(albedo), share(albedo)]
+            : [share(albedo[0]), share(albedo[1]), share(albedo[2])],
         /* Short of the poles, where `(1 - g^2)` over `(1 + g^2 - 2g)^1.5` is 0/0. */
         anisotropy: Math.min(0.95, Math.max(-0.95, options.anisotropy ?? d.anisotropy)),
         maxDistance: Math.max(1e-3, options.maxDistance ?? d.maxDistance),
+        heightFalloff: finite(options.heightFalloff, 0),
+        baseY: finite(options.baseY, 0),
+        density2,
+        heightFalloff2: layer2 === null ? 0 : finite(layer2.heightFalloff, 0),
+        baseY2: layer2 === null ? 0 : finite(layer2.baseY, 0),
+        sunScatter: Math.max(0, finite(options.sunScatter, 1)),
+        skyScatter: Math.max(0, finite(options.skyScatter, 1)),
+        lampScatter: Math.max(0, finite(options.lampScatter, 0)),
     };
 }
+/**
+ * `setGlobalMedium`'s two forms, its four numbers or the object, read one way for both backends:
+ * a density that is not a number is none.
+ */
+export function resolveGlobalMediumSettings(density, albedo, anisotropy, maxDistance) {
+    if (typeof density === 'object') {
+        return resolveGlobalMedium({
+            ...density,
+            density: Number.isFinite(density.density) ? density.density : 0,
+        });
+    }
+    return resolveGlobalMedium({
+        density: Number.isFinite(density) ? density : 0,
+        albedo,
+        anisotropy,
+        maxDistance,
+    });
+}
 /**
  * Whether this frame draws the medium at all.
  *
@@ -98,3 +137,59 @@ export function mediumTargetSize(width, height, halfResolution) {
         height: Math.max(1, Math.ceil(Math.max(1, height) / divisor)),
     };
 }
+/** A target for `resolveMediumLamps`, made once outside the frame loop. */
+export function createResolvedMediumLamps() {
+    const vectors = () => new Float32Array(MAX_MEDIUM_LAMPS * 4);
+    return {
+        count: 0,
+        falloff: 0,
+        position: vectors(),
+        color: vectors(),
+        aim: vectors(),
+        cone: vectors(),
+        shadow: vectors(),
+        shadowAt: vectors(),
+        live: vectors(),
+        liveAt: vectors(),
+    };
+}
+/**
+ * The frame's lamps as the medium is lit by them, into `out`: the lit stage's resolved lamps and
+ * their resolved shadows, a lamp's scatter `lampScatter` times its own `lightMediumScatter` (1 where
+ * absent). Allocates nothing; a lamp past the count keeps whatever it held, which nothing reads.
+ */
+export function resolveMediumLamps(medium, lights, shadows, scatter, out) {
+    const count = medium.lampScatter > 0 ? Math.min(lights.count, MAX_MEDIUM_LAMPS) : 0;
+    out.count = count;
+    out.falloff = lights.falloff;
+    const own = scatter !== undefined && scatter.length >= count ? scatter : undefined;
+    for (let i = 0; i < count; i++) {
+        const at = i * 4;
+        const strength = medium.lampScatter * Math.max(0, own?.[i] ?? 1) * lights.weights[i];
+        for (let c = 0; c < 3; c++) {
+            out.position[at + c] = lights.positions[i * 3 + c];
+            out.color[at + c] = lights.colors[i * 3 + c] * strength;
+            out.aim[at + c] = lights.directions[i * 3 + c];
+        }
+        out.position[at + 3] = lights.radii[i];
+        out.color[at + 3] = lights.conesAndFalloffs[at + 2];
+        out.aim[at + 3] = 0;
+        out.cone[at] = lights.conesAndFalloffs[at];
+        out.cone[at + 1] = lights.conesAndFalloffs[at + 1];
+        out.cone[at + 2] = 0;
+        out.cone[at + 3] = 0;
+        out.shadow[at] = shadows === null ? -1 : shadows.layers[i];
+        out.shadow[at + 1] = shadows === null ? 0 : shadows.near[i];
+        out.shadow[at + 2] = shadows === null ? 0 : shadows.presence[i];
+        out.shadow[at + 3] = 0;
+        out.live[at] = shadows === null ? -1 : shadows.liveLayers[i];
+        out.live[at + 1] = shadows === null ? 0 : shadows.liveNear[i];
+        out.live[at + 2] = shadows === null ? 0 : shadows.liveWeights[i];
+        out.live[at + 3] = 0;
+        for (let k = 0; k < 4; k++) {
+            out.shadowAt[at + k] = shadows === null ? 1 : shadows.projections[at + k];
+            out.liveAt[at + k] = shadows === null ? 1 : shadows.liveProjections[at + k];
+        }
+    }
+    return out;
+}

package/dist/render/globalMediumPass.d.ts

@@ -1,6 +1,6 @@
 import type { ReadonlyMat4 } from 'gl-matrix';
-import type { GlobalMediumOptions } from './globalMedium.ts';
-/** What the march needs about the light, which is the sun and the sky and nothing else. */
+import type { ResolvedGlobalMedium, ResolvedMediumLamps } from './globalMedium.ts';
+/** What the march needs about the light: the sun, the sky, and the lamps that scatter. */
 export interface MediumLight {
     /** Surface → sun, normalised. `Environment.directionalDir` unchanged. */
     readonly sunDir: ArrayLike<number>;
@@ -16,6 +16,10 @@ export interface MediumLight {
     /** The sun's static, moving and peeled maps, as one array. See `shadowMap.ts`. */
     readonly sunShadows: WebGLTexture;
     readonly peeledEnabled: boolean;
+    /** The lamps that scatter, as `resolveMediumLamps` lays them out: none while `lampScatter` is 0. */
+    readonly lamps: ResolvedMediumLamps;
+    /** The lamps' shadow array, the lit stage's; the placeholder where there is none. */
+    readonly pointShadows: WebGLTexture;
 }
 /**
  * The global participating medium on WebGL2: a half-res march, then a depth-aware composite.
@@ -90,7 +94,7 @@ export declare class GlobalMediumPass {
      * `DEPTH_01_TO_CLIP` carries a stored depth back into the clip space the first was built in,
      * and pairing either with a clip-corrected matrix applies the remap twice.
      */
-    marchMedium(depth: WebGLTexture, frameWidth: number, frameHeight: number, half: boolean, steps: number, options: GlobalMediumOptions, viewProjection: ReadonlyMat4, projection: ReadonlyMat4, eye: ArrayLike<number>, light: MediumLight): boolean;
+    marchMedium(depth: WebGLTexture, frameWidth: number, frameHeight: number, half: boolean, steps: number, options: ResolvedGlobalMedium, viewProjection: ReadonlyMat4, projection: ReadonlyMat4, eye: ArrayLike<number>, light: MediumLight): boolean;
     /**
      * Composite the march over whatever framebuffer is bound, upsampled depth-aware.
      *

package/dist/render/globalMediumPass.js

@@ -161,13 +161,19 @@ export class GlobalMediumPass {
         gl.activeTexture(gl.TEXTURE1);
         gl.bindTexture(gl.TEXTURE_2D_ARRAY, light.sunShadows);
         gl.uniform1i(u['uSunShadows'] ?? null, 1);
+        gl.activeTexture(gl.TEXTURE2);
+        gl.bindTexture(gl.TEXTURE_2D_ARRAY, light.pointShadows);
+        gl.uniform1i(u['uPointShadows'] ?? null, 2);
         gl.uniformMatrix4fv(u['uDepthToWorld'] ?? null, false, this.depthToWorld);
         gl.uniform3f(u['uCameraPos'] ?? null, eye[0] ?? 0, eye[1] ?? 0, eye[2] ?? 0);
         gl.uniform3f(u['uSunDir'] ?? null, light.sunDir[0] ?? 0, light.sunDir[1] ?? 1, light.sunDir[2] ?? 0);
         gl.uniform3f(u['uSunColor'] ?? null, light.sunColor[0] ?? 0, light.sunColor[1] ?? 0, light.sunColor[2] ?? 0);
         gl.uniform3f(u['uAmbient'] ?? null, light.ambient[0] ?? 0, light.ambient[1] ?? 0, light.ambient[2] ?? 0);
         gl.uniform1f(u['uDensity'] ?? null, options.density);
-        gl.uniform1f(u['uAlbedo'] ?? null, options.albedo);
+        gl.uniform2f(u['uHeight'] ?? null, options.heightFalloff, options.baseY);
+        gl.uniform3f(u['uLayer2'] ?? null, options.density2, options.heightFalloff2, options.baseY2);
+        gl.uniform3f(u['uAlbedo'] ?? null, options.albedo[0], options.albedo[1], options.albedo[2]);
+        gl.uniform2f(u['uScatter'] ?? null, options.sunScatter, options.skyScatter);
         gl.uniform1f(u['uAnisotropy'] ?? null, options.anisotropy);
         gl.uniform1f(u['uMaxDistance'] ?? null, options.maxDistance);
         gl.uniform1i(u['uSteps'] ?? null, steps);
@@ -175,6 +181,20 @@ export class GlobalMediumPass {
         gl.uniformMatrix4fv(u['uLightViewProj'] ?? null, false, light.lightViewProj);
         gl.uniformMatrix4fv(u['uMovingLightViewProj'] ?? null, false, light.movingLightViewProj);
         gl.uniform1i(u['uPeeledShadowEnabled'] ?? null, light.peeledEnabled ? 1 : 0);
+        const lamps = light.lamps;
+        gl.uniform1i(u['uLampCount'] ?? null, lamps.count);
+        gl.uniform1i(u['uLampFalloff'] ?? null, lamps.falloff);
+        /* As `name[0]`, the only spelling an array uniform answers to: see `bindPointShadows`. */
+        if (lamps.count > 0) {
+            gl.uniform4fv(u['uLampPosition[0]'] ?? null, lamps.position);
+            gl.uniform4fv(u['uLampColor[0]'] ?? null, lamps.color);
+            gl.uniform4fv(u['uLampAim[0]'] ?? null, lamps.aim);
+            gl.uniform4fv(u['uLampCone[0]'] ?? null, lamps.cone);
+            gl.uniform4fv(u['uLampShadow[0]'] ?? null, lamps.shadow);
+            gl.uniform4fv(u['uLampShadowAt[0]'] ?? null, lamps.shadowAt);
+            gl.uniform4fv(u['uLampLive[0]'] ?? null, lamps.live);
+            gl.uniform4fv(u['uLampLiveAt[0]'] ?? null, lamps.liveAt);
+        }
         gl.drawArrays(gl.TRIANGLES, 0, 3);
         gl.bindVertexArray(null);
         /* Released down to unit 0, for the reason `SsrPass` records: a binding outlives the frame that
@@ -182,6 +202,7 @@ export class GlobalMediumPass {
         for (const unit of [gl.TEXTURE3, gl.TEXTURE2, gl.TEXTURE1, gl.TEXTURE0]) {
             gl.activeTexture(unit);
             gl.bindTexture(gl.TEXTURE_2D, null);
+            gl.bindTexture(gl.TEXTURE_2D_ARRAY, null);
         }
         gl.bindFramebuffer(gl.FRAMEBUFFER, null);
         return true;

package/dist/render/hairLobes.d.ts

@@ -46,6 +46,16 @@ export declare const HAIR_MIN_BETA = 0.05;
  * and its integral 4π times that. Over π: **1.33**.
  */
 export declare const HAIR_SCATTER_SPHERE = 1.33;
+/**
+ * How far every lobe is widened for light from every side, in radians: the angle a source would
+ * subtend to widen them as much, `sourceRadius / 2·dist` in `hairLight`'s terms.
+ *
+ * **0.2, the real-time form's own value**, which stands one direction in for the sphere: a lobe as
+ * narrow as a lamp's would put the whole sky's light into one highlight wherever the eye's
+ * direction happens to meet it. What it gives up is the sky's shape: a sun low in a clear sky and
+ * an even overcast light hair through the same widened lobes.
+ */
+export declare const HAIR_AREA = 0.2;
 /** A longitudinal lobe: a normalised Gaussian of width `beta` at `x` from its centre. */
 export declare function hairLongitudinal(beta: number, x: number): number;
 /** Schlick's Fresnel for the strand at a cosine, clamped to the unit interval. */
@@ -61,10 +71,25 @@ export declare const HAIR_OUT: {
 /**
  * One light on a strand, in lamp units and unshadowed, into `out` (`HAIR_OUT`'s layout: R is grey,
  * the rest colours). `tangent`, `toLight` and `toEye` are unit vectors but for a tangent that could
- * not be made one, which comes in as zeros; `fibre` is the base colour.
+ * not be made one, which comes in as zeros; `fibre` is the base colour; `specular` is the strand's,
+ * the model map's red, which scales the reflected lobe by twice it, so 0.5 draws the lobe as the
+ * fit gives it and 0 is a strand that reflects nothing off its surface.
  *
  * **A lamp with a size widens every lobe by the angle it subtends**, `sourceRadius / 2·dist` as
  * `sphereLobe` takes it, and the lobes are normalised Gaussians, so a wider one carries the same
  * light rather than more. The sun passes zeros.
  */
-export declare function hairLight(tangent: ArrayLike<number>, toLight: ArrayLike<number>, toEye: ArrayLike<number>, fibre: Vec3, roughness: number, shift: number, scatter: number, backlit: number, sourceRadius: number, dist: number, out: Float64Array): void;
+export declare function hairLight(tangent: ArrayLike<number>, toLight: ArrayLike<number>, toEye: ArrayLike<number>, fibre: Vec3, roughness: number, shift: number, specular: number, scatter: number, backlit: number, sourceRadius: number, dist: number, out: Float64Array): void;
+/**
+ * The share of light from every side a strand returns, a colour into `out`, with the one
+ * direction's lobes it is made of into `lobes` (`HAIR_OUT`'s layout). `normal` is the surface's,
+ * which stands in for the flattened eye where the eye runs along the strand and there is none.
+ *
+ * **One direction for the sphere**: the eye flattened across the strand, `V − T(V·T)`, unshadowed,
+ * with no light from behind and so no transmitted lobe, every lobe widened by `HAIR_AREA`. Twice
+ * the sum, and at most all of what arrives. **Why twice**: the scatter's half is then
+ * `HAIR_SCATTER_SPHERE`, its own answer to an even sky — along the flattened eye its shape is
+ * `mix(1/2, 1, 0.33)`, 0.665, which doubled is that constant's 1.33 — so the lobes ride on a
+ * scatter the sphere's quadrature already holds to, and R and TRT are what the direction adds.
+ */
+export declare function hairIndirect(tangent: ArrayLike<number>, toEye: ArrayLike<number>, normal: ArrayLike<number>, fibre: Vec3, roughness: number, shift: number, specular: number, scatter: number, lobes: Float64Array, out: Float64Array): void;