@driftengine/core 4.5.0 → 4.6.1

package/dist/render/surfaceTexture.d.ts

@@ -1,4 +1,4 @@
-/** A GPU image the caller supplies, sampled by the flat shader as surface colour. */
+import type { SurfaceLayerEffect } from './surfaceEffects.ts';
 /**
  * How a texture behaves past its edges and between its texels.
  *
@@ -101,6 +101,12 @@ export interface SurfaceMaterial<Texture = SurfaceTexture> {
     emissiveScale?: readonly [number, number, number];
 }
 export interface SurfaceTextureOptions {
+    /**
+     * What each layer does beyond its picture — rooms behind windows, windows lit by night, wear,
+     * animation, staying dry — one entry a layer, `undefined` for a layer with none. Read only where
+     * this texture is a material's albedo. See `surfaceEffects.ts`.
+     */
+    effects?: readonly (SurfaceLayerEffect | undefined)[];
     /**
      * `repeat` tiles the image, `clamp` stretches its edge texels.
      *
@@ -183,7 +189,17 @@ export declare class SurfaceTexture {
     private readonly mipmapped;
     /** Whether the sampler decodes sRGB on fetch. See `colorSpace`. */
     private readonly srgb;
-    constructor(gl: WebGL2RenderingContext, source: TexImageSource, options?: SurfaceTextureOptions);
+    /** How many images the array holds: 1 for `createSurfaceTexture`, the list's length otherwise. */
+    readonly layers: number;
+    /** The per-layer effects table, or null for a texture given none. See `surfaceEffects.ts`. */
+    private effectsTable;
+    /**
+     * One image, or an array of images that must share one size (`layerSize` refuses otherwise).
+     * Uploaded unflipped either way; see the constructor body for why.
+     */
+    constructor(gl: WebGL2RenderingContext, source: TexImageSource | readonly TexImageSource[], options?: SurfaceTextureOptions);
+    /** Bind the effects table to `unit`, or `fallback` for a texture given none. */
+    bindEffects(gl: WebGL2RenderingContext, unit: number, fallback: WebGLTexture): void;
     /**
      * Replace the pixels, keeping the GPU object and its sampler state.
      *

package/dist/render/surfaceTexture.js

@@ -1,4 +1,15 @@
-/** A GPU image the caller supplies, sampled by the flat shader as surface colour. */
+/**
+ * A GPU image the caller supplies, sampled by the flat shader as surface colour — or several, as
+ * the layers of one array.
+ *
+ * **Every surface texture is an array; a plain image is an array of one.** The lit pass has three of
+ * WebGL2's guaranteed sixteen texture units free, so a second set of array samplers beside the 2D
+ * ones was never affordable. Making the one set of samplers arrays costs no unit, and a one-layer
+ * array samples exactly as a 2D texture does. A mesh names its layer per vertex (`MeshData.layers`),
+ * so a merged block wearing forty facades is one draw.
+ */
+import { isSourceList, layerSize, refuseArrayUpdate, sourceSize } from './textureSource.js';
+import { SURFACE_EFFECT_TEXELS, packSurfaceEffects } from './surfaceEffects.js';
 const DEFAULT_ANISOTROPY = 4;
 /**
  * An image uploaded once and bound per draw.
@@ -14,7 +25,18 @@ export class SurfaceTexture {
     mipmapped;
     /** Whether the sampler decodes sRGB on fetch. See `colorSpace`. */
     srgb;
+    /** How many images the array holds: 1 for `createSurfaceTexture`, the list's length otherwise. */
+    layers;
+    /** The per-layer effects table, or null for a texture given none. See `surfaceEffects.ts`. */
+    effectsTable = null;
+    /**
+     * One image, or an array of images that must share one size (`layerSize` refuses otherwise).
+     * Uploaded unflipped either way; see the constructor body for why.
+     */
     constructor(gl, source, options = {}) {
+        const sources = isSourceList(source) ? source : [source];
+        const { width, height } = layerSize(sources);
+        this.layers = sources.length;
         const texture = gl.createTexture();
         if (texture === null)
             throw new Error('SurfaceTexture: createTexture failed');
@@ -22,7 +44,7 @@ export class SurfaceTexture {
         this.mipmapped = options.mipmap ?? true;
         this.srgb = (options.colorSpace ?? 'linear') === 'srgb';
         const wrap = (options.wrap ?? 'repeat') === 'repeat' ? gl.REPEAT : gl.CLAMP_TO_EDGE;
-        gl.bindTexture(gl.TEXTURE_2D, texture);
+        gl.bindTexture(gl.TEXTURE_2D_ARRAY, texture);
         /*
          * **Not flipped, and this used to be, which is the bug it is written down for.**
          *
@@ -44,15 +66,20 @@ export class SurfaceTexture {
          *
          * A caller that was mirroring its own canvas to cancel this must stop.
          */
-        gl.texImage2D(gl.TEXTURE_2D, 0, this.srgb ? gl.SRGB8_ALPHA8 : gl.RGBA, gl.RGBA, gl.UNSIGNED_BYTE, source);
-        gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_WRAP_S, wrap);
-        gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_WRAP_T, wrap);
+        /* Allocated mutable rather than with texStorage3D, so `update` can hand a one-layer texture a
+           new size, as texImage2D always could. Each layer is then written in place. */
+        gl.texImage3D(gl.TEXTURE_2D_ARRAY, 0, this.srgb ? gl.SRGB8_ALPHA8 : gl.RGBA, width, height, sources.length, 0, gl.RGBA, gl.UNSIGNED_BYTE, null);
+        for (let layer = 0; layer < sources.length; layer++) {
+            gl.texSubImage3D(gl.TEXTURE_2D_ARRAY, 0, 0, 0, layer, width, height, 1, gl.RGBA, gl.UNSIGNED_BYTE, sources[layer]);
+        }
+        gl.texParameteri(gl.TEXTURE_2D_ARRAY, gl.TEXTURE_WRAP_S, wrap);
+        gl.texParameteri(gl.TEXTURE_2D_ARRAY, gl.TEXTURE_WRAP_T, wrap);
         /* Nearest where the caller said their pixels are the subject; see `filter`. The mip chain is
            still blended between levels, because that is minification and this option is about
            magnification. */
         const nearest = options.filter === 'nearest';
-        gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_MAG_FILTER, nearest ? gl.NEAREST : gl.LINEAR);
-        gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_MIN_FILTER, this.mipmapped
+        gl.texParameteri(gl.TEXTURE_2D_ARRAY, gl.TEXTURE_MAG_FILTER, nearest ? gl.NEAREST : gl.LINEAR);
+        gl.texParameteri(gl.TEXTURE_2D_ARRAY, gl.TEXTURE_MIN_FILTER, this.mipmapped
             ? nearest
                 ? gl.NEAREST_MIPMAP_LINEAR
                 : gl.LINEAR_MIPMAP_LINEAR
@@ -60,9 +87,30 @@ export class SurfaceTexture {
                 ? gl.NEAREST
                 : gl.LINEAR);
         if (this.mipmapped)
-            gl.generateMipmap(gl.TEXTURE_2D);
+            gl.generateMipmap(gl.TEXTURE_2D_ARRAY);
         applyAnisotropy(gl, options.anisotropy ?? DEFAULT_ANISOTROPY);
-        gl.bindTexture(gl.TEXTURE_2D, null);
+        gl.bindTexture(gl.TEXTURE_2D_ARRAY, null);
+        /* Half floats, nearest, clamped: a table read by texelFetch, whose every whole number is under
+           what a half holds exactly. */
+        const effects = options.effects ?? [];
+        if (effects.length > 0) {
+            const table = gl.createTexture();
+            if (table === null)
+                throw new Error('SurfaceTexture: createTexture failed');
+            gl.bindTexture(gl.TEXTURE_2D, table);
+            gl.texImage2D(gl.TEXTURE_2D, 0, gl.RGBA16F, SURFACE_EFFECT_TEXELS, effects.length, 0, gl.RGBA, gl.FLOAT, packSurfaceEffects(effects));
+            gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_MIN_FILTER, gl.NEAREST);
+            gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_MAG_FILTER, gl.NEAREST);
+            gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_WRAP_S, gl.CLAMP_TO_EDGE);
+            gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_WRAP_T, gl.CLAMP_TO_EDGE);
+            gl.bindTexture(gl.TEXTURE_2D, null);
+            this.effectsTable = table;
+        }
+    }
+    /** Bind the effects table to `unit`, or `fallback` for a texture given none. */
+    bindEffects(gl, unit, fallback) {
+        gl.activeTexture(gl.TEXTURE0 + unit);
+        gl.bindTexture(gl.TEXTURE_2D, this.effectsTable ?? fallback);
     }
     /**
      * Replace the pixels, keeping the GPU object and its sampler state.
@@ -78,23 +126,28 @@ export class SurfaceTexture {
     update(gl, source) {
         if (this.texture === null)
             return;
-        gl.bindTexture(gl.TEXTURE_2D, this.texture);
+        refuseArrayUpdate(this.layers);
+        const { width, height } = sourceSize(source);
+        gl.bindTexture(gl.TEXTURE_2D_ARRAY, this.texture);
         /* Unflipped, matching the constructor. See it for why, and for what it cost. */
-        gl.texImage2D(gl.TEXTURE_2D, 0, this.srgb ? gl.SRGB8_ALPHA8 : gl.RGBA, gl.RGBA, gl.UNSIGNED_BYTE, source);
+        gl.texImage3D(gl.TEXTURE_2D_ARRAY, 0, this.srgb ? gl.SRGB8_ALPHA8 : gl.RGBA, width, height, 1, 0, gl.RGBA, gl.UNSIGNED_BYTE, source);
         if (this.mipmapped)
-            gl.generateMipmap(gl.TEXTURE_2D);
-        gl.bindTexture(gl.TEXTURE_2D, null);
+            gl.generateMipmap(gl.TEXTURE_2D_ARRAY);
+        gl.bindTexture(gl.TEXTURE_2D_ARRAY, null);
     }
     /** Bind to a unit for sampling. Engine-internal: the renderer owns unit assignment. */
     bind(gl, unit) {
         gl.activeTexture(gl.TEXTURE0 + unit);
-        gl.bindTexture(gl.TEXTURE_2D, this.texture);
+        gl.bindTexture(gl.TEXTURE_2D_ARRAY, this.texture);
     }
     dispose(gl) {
         if (this.texture === null)
             return;
         gl.deleteTexture(this.texture);
         this.texture = null;
+        if (this.effectsTable !== null)
+            gl.deleteTexture(this.effectsTable);
+        this.effectsTable = null;
     }
 }
 /**
@@ -112,5 +165,5 @@ function applyAnisotropy(gl, requested) {
     if (ext === null)
         return;
     const max = gl.getParameter(ext.MAX_TEXTURE_MAX_ANISOTROPY_EXT);
-    gl.texParameterf(gl.TEXTURE_2D, ext.TEXTURE_MAX_ANISOTROPY_EXT, Math.min(requested, max));
+    gl.texParameterf(gl.TEXTURE_2D_ARRAY, ext.TEXTURE_MAX_ANISOTROPY_EXT, Math.min(requested, max));
 }

package/dist/render/temporalAa.d.ts

@@ -123,6 +123,24 @@ export declare const FLICKER_MEMORY: number;
  * Threads caught in a share nearer a half spread more and need fewer.
  */
 export declare const FLICKER_WIDTH = 6;
+/**
+ * The two numbers the proof takes from the jitter's period: how much of a period one frame is, and
+ * how many spreads a proven pixel's box widens by. This resolve's are `FLICKER_MEMORY` and
+ * `FLICKER_WIDTH`; a reconstruction jitters along a longer sequence and needs its own.
+ */
+export interface FlickerRule {
+    readonly memory: number;
+    readonly width: number;
+}
+/** The temporal resolve's own: eight phases. */
+export declare const TEMPORAL_FLICKER: FlickerRule;
+/**
+ * The rule for a jitter of `phases` positions. **The width keeps the room `FLICKER_WIDTH` leaves over
+ * what eight phases need** — 4.8 — in proportion: a longer period wears the spread down further
+ * between catches, so over eighteen phases the hardest thread needs eleven spreads, and a box that
+ * reached six reset the count of exactly the pixels this is for.
+ */
+export declare function flickerRule(phases: number): FlickerRule;
 /**
  * How far apart two periods' means may be, relative to the larger, and still repeat: fully below
  * this, not at all at twice it. Above an eight-bit record's rounding and a lamp's slow breathing; far
@@ -192,7 +210,7 @@ export interface Flicker {
  * record of another surface is no record**, so the resolve starts one over wherever last frame's
  * depth says the surface is not the one it followed, before this frame widens by anything.
  */
-export declare function freshFlicker(out: Flicker, sample: number): Flicker;
+export declare function freshFlicker(out: Flicker, sample: number, rule?: FlickerRule): Flicker;
 /** Rec. 709 luma, which is what the record measures in. */
 export declare function luma(c: readonly [number, number, number]): number;
 /** One for a pixel whose reprojection did not move, falling to none at a twentieth of a pixel. */
@@ -202,20 +220,21 @@ export declare function stillness(motionPixels: number): number;
  * lands within the reach of the box it would widen to. A sample beyond that reach is something
  * arriving, and it disqualifies the frame it lands in as well as the count it carries out.
  */
-export declare function proven(record: Flicker, sample: number): boolean;
+export declare function proven(record: Flicker, sample: number, rule?: FlickerRule): boolean;
 /** How far a pixel's box widens this frame: by its spread, once proven, and only while still. */
-export declare function flickerWidening(record: Flicker, sample: number, still: number): number;
+export declare function flickerWidening(record: Flicker, sample: number, still: number, rule?: FlickerRule): number;
 /** How much of the history this frame keeps: the base blend, or more once proven. */
-export declare function flickerBlend(base: number, record: Flicker, sample: number, still: number): number;
+export declare function flickerBlend(base: number, record: Flicker, sample: number, still: number, rule?: FlickerRule): number;
 /** Whether two periods' means are the same, one to zero. */
 export declare function repeats(mean: number, previous: number): number;
 /**
  * The record carried out, from the one carried in and this frame's sample in luma. `periodStart`
  * is the first frame of the jitter's period, where the period just gathered is compared with the
  * one before. Forgotten in proportion to motion — a moving pixel's record would be a record of
- * somewhere else.
+ * somewhere else. `rule` is this resolve's eight phases unless a caller jitters along another
+ * sequence, as a reconstruction does.
  */
-export declare function nextFlicker(out: Flicker, previous: Flicker, sample: number, still: number, periodStart: boolean): Flicker;
+export declare function nextFlicker(out: Flicker, previous: Flicker, sample: number, still: number, periodStart: boolean, rule?: FlickerRule): Flicker;
 /**
  * Whether the last frame left a picture this one may sample, and where the jitter has got to.
  *

package/dist/render/temporalAa.js

@@ -176,6 +176,35 @@ export const FLICKER_MEMORY = 1 / JITTER_PERIOD;
  * Threads caught in a share nearer a half spread more and need fewer.
  */
 export const FLICKER_WIDTH = 6;
+/** The temporal resolve's own: eight phases. */
+export const TEMPORAL_FLICKER = { memory: FLICKER_MEMORY, width: FLICKER_WIDTH };
+/**
+ * The running spread of the hardest thread — one caught in a single phase of `phases` — just before
+ * its catch, as a share of its contrast: the steady state `FLICKER_WIDTH`'s comment solves for eight
+ * phases, solved for any. With m one over the period and r = (1 − m)^(p − 1), the seven, or p − 1,
+ * misses that wear it down: a = (m + ((p − 1)m² − m)·r) / (1 − (1 − m)·r).
+ */
+function hardestSpread(phases) {
+    const m = 1 / phases;
+    const r = (1 - m) ** (phases - 1);
+    return (m + ((phases - 1) * m * m - m) * r) / (1 - (1 - m) * r);
+}
+/** How many of those spreads the hardest thread's catch lands from its period's mean. */
+function widthNeeded(phases) {
+    return (1 - 1 / phases) / hardestSpread(phases);
+}
+/**
+ * The rule for a jitter of `phases` positions. **The width keeps the room `FLICKER_WIDTH` leaves over
+ * what eight phases need** — 4.8 — in proportion: a longer period wears the spread down further
+ * between catches, so over eighteen phases the hardest thread needs eleven spreads, and a box that
+ * reached six reset the count of exactly the pixels this is for.
+ */
+export function flickerRule(phases) {
+    return {
+        memory: 1 / phases,
+        width: (FLICKER_WIDTH * widthNeeded(phases)) / widthNeeded(JITTER_PERIOD),
+    };
+}
 /**
  * How far apart two periods' means may be, relative to the larger, and still repeat: fully below
  * this, not at all at twice it. Above an eight-bit record's rounding and a lamp's slow breathing; far
@@ -246,9 +275,9 @@ export const STILL_TO = 0.05;
  * record of another surface is no record**, so the resolve starts one over wherever last frame's
  * depth says the surface is not the one it followed, before this frame widens by anything.
  */
-export function freshFlicker(out, sample) {
+export function freshFlicker(out, sample, rule = TEMPORAL_FLICKER) {
     out.spread = 0;
-    out.sum = sample * FLICKER_MEMORY;
+    out.sum = sample * rule.memory;
     out.mean = sample;
     out.repeated = 0;
     return out;
@@ -270,20 +299,20 @@ export function stillness(motionPixels) {
  * lands within the reach of the box it would widen to. A sample beyond that reach is something
  * arriving, and it disqualifies the frame it lands in as well as the count it carries out.
  */
-export function proven(record, sample) {
-    return record.repeated > 0.75 && within(record, sample);
+export function proven(record, sample, rule = TEMPORAL_FLICKER) {
+    return record.repeated > 0.75 && within(record, sample, rule);
 }
 /** Whether this frame's sample lands inside the reach of the box the record would widen to. */
-function within(record, sample) {
-    return Math.abs(sample - record.mean) <= FLICKER_WIDTH * record.spread + 1 / 255;
+function within(record, sample, rule) {
+    return Math.abs(sample - record.mean) <= rule.width * record.spread + 1 / 255;
 }
 /** How far a pixel's box widens this frame: by its spread, once proven, and only while still. */
-export function flickerWidening(record, sample, still) {
-    return proven(record, sample) ? FLICKER_WIDTH * record.spread * still : 0;
+export function flickerWidening(record, sample, still, rule = TEMPORAL_FLICKER) {
+    return proven(record, sample, rule) ? rule.width * record.spread * still : 0;
 }
 /** How much of the history this frame keeps: the base blend, or more once proven. */
-export function flickerBlend(base, record, sample, still) {
-    return proven(record, sample) ? base + (FLICKER_BLEND - base) * still : base;
+export function flickerBlend(base, record, sample, still, rule = TEMPORAL_FLICKER) {
+    return proven(record, sample, rule) ? base + (FLICKER_BLEND - base) * still : base;
 }
 /** Whether two periods' means are the same, one to zero. */
 export function repeats(mean, previous) {
@@ -294,20 +323,21 @@ export function repeats(mean, previous) {
  * The record carried out, from the one carried in and this frame's sample in luma. `periodStart`
  * is the first frame of the jitter's period, where the period just gathered is compared with the
  * one before. Forgotten in proportion to motion — a moving pixel's record would be a record of
- * somewhere else.
+ * somewhere else. `rule` is this resolve's eight phases unless a caller jitters along another
+ * sequence, as a reconstruction does.
  */
-export function nextFlicker(out, previous, sample, still, periodStart) {
+export function nextFlicker(out, previous, sample, still, periodStart, rule = TEMPORAL_FLICKER) {
     const apart = Math.abs(sample - previous.mean);
     let { sum, mean, repeated } = previous;
-    if (apart > FLICKER_WIDTH * previous.spread + 1 / 255)
+    if (apart > rule.width * previous.spread + 1 / 255)
         repeated = 0;
     if (periodStart) {
         repeated = repeats(sum, mean) > 0.5 ? Math.min(1, repeated + 0.5) : 0;
         mean = sum;
         sum = 0;
     }
-    out.spread = previous.spread + (apart - previous.spread) * FLICKER_MEMORY;
-    out.sum = sum + sample * FLICKER_MEMORY;
+    out.spread = previous.spread + (apart - previous.spread) * rule.memory;
+    out.sum = sum + sample * rule.memory;
     out.mean = mean;
     out.repeated = repeated * still;
     return out;

package/dist/render/textureSource.d.ts

@@ -0,0 +1,30 @@
+/**
+ * The size of an image a caller hands over, and the one rule a texture array adds to it: every
+ * layer the same size.
+ *
+ * Backend-neutral, because both backends upload the same `TexImageSource` and must agree on its
+ * size, and on refusing an array whose layers disagree, before either touches a device.
+ */
+export interface SourceSize {
+    readonly width: number;
+    readonly height: number;
+}
+/** Width and height of any `TexImageSource`: a video by its frame, everything else by its own size. */
+export declare function sourceSize(source: TexImageSource): SourceSize;
+/**
+ * The one size every layer of an array shares, or a refusal naming the first that differs.
+ *
+ * **Refused rather than resized**, because an array layer has no size of its own — the device
+ * allocates one size for all of them — and quietly scaling a 128-pixel sign up to a 512 array, or a
+ * facade down, is a decision about quality the caller should make where they can see it. Sorting
+ * images into arrays by size is theirs; this makes sure they did.
+ */
+export declare function layerSize(sources: readonly TexImageSource[]): SourceSize;
+/** Whether a constructor argument is a list of images rather than one. */
+export declare function isSourceList(source: TexImageSource | readonly TexImageSource[]): source is readonly TexImageSource[];
+/**
+ * `update` replaces the one image of a plain texture. An array's layers are its identity — a
+ * block's facades by index — and replacing "the image" of a forty-layer array has no single
+ * meaning, so it is refused rather than guessed at.
+ */
+export declare function refuseArrayUpdate(layers: number): void;

package/dist/render/textureSource.js

@@ -0,0 +1,53 @@
+/**
+ * The size of an image a caller hands over, and the one rule a texture array adds to it: every
+ * layer the same size.
+ *
+ * Backend-neutral, because both backends upload the same `TexImageSource` and must agree on its
+ * size, and on refusing an array whose layers disagree, before either touches a device.
+ */
+/** Width and height of any `TexImageSource`: a video by its frame, everything else by its own size. */
+export function sourceSize(source) {
+    const candidate = source;
+    const width = candidate.videoWidth ?? candidate.width ?? 0;
+    const height = candidate.videoHeight ?? candidate.height ?? 0;
+    return { width: Math.max(1, width), height: Math.max(1, height) };
+}
+/**
+ * The one size every layer of an array shares, or a refusal naming the first that differs.
+ *
+ * **Refused rather than resized**, because an array layer has no size of its own — the device
+ * allocates one size for all of them — and quietly scaling a 128-pixel sign up to a 512 array, or a
+ * facade down, is a decision about quality the caller should make where they can see it. Sorting
+ * images into arrays by size is theirs; this makes sure they did.
+ */
+export function layerSize(sources) {
+    const first = sources[0];
+    if (first === undefined) {
+        throw new Error('createSurfaceTextureArray: an array needs at least one image');
+    }
+    const size = sourceSize(first);
+    for (let layer = 1; layer < sources.length; layer++) {
+        const next = sourceSize(sources[layer]);
+        if (next.width !== size.width || next.height !== size.height) {
+            throw new Error(`createSurfaceTextureArray: layer ${layer} is ${next.width}×${next.height} and layer 0 is ` +
+                `${size.width}×${size.height}. Every layer of an array is one size on the device; group ` +
+                'images into arrays by size, or scale them to one, before building the array.');
+        }
+    }
+    return size;
+}
+/** Whether a constructor argument is a list of images rather than one. */
+export function isSourceList(source) {
+    return Array.isArray(source);
+}
+/**
+ * `update` replaces the one image of a plain texture. An array's layers are its identity — a
+ * block's facades by index — and replacing "the image" of a forty-layer array has no single
+ * meaning, so it is refused rather than guessed at.
+ */
+export function refuseArrayUpdate(layers) {
+    if (layers === 1)
+        return;
+    throw new Error(`updateSurfaceTexture: this texture is an array of ${layers} layers, and update replaces the ` +
+        'one image of a plain texture. Build a new array for new layers.');
+}

package/dist/render/vertexDefaults.js

@@ -88,6 +88,8 @@ export const ABSENT_ATTRIBUTE = {
      * the thing being measured.
      */
     channel: [0, 1, 1, 1],
+    /* Layer 0: the only image a plain texture has, and the first of an array. */
+    layers: [0],
 };
 /**
  * What `uOutputTransform` means, as the shader's own integers.

package/dist/world/hlod.d.ts

@@ -0,0 +1,104 @@
+/**
+ * Which level of detail each region of a world is drawn at, and the crossfade between two.
+ *
+ * **A region is a box and one geometric error per level**, finest first: how far, in metres, that
+ * level's surface may stand from the real one. A level is good enough once its error projects under
+ * `pixelTolerance` pixels, so the distance it takes over at is `error · projectionScale / tolerance`
+ * — the rule 3D Tiles uses, and the reason the file carries errors rather than distances: a
+ * distance is a decision about one screen, and an error is a fact about the geometry.
+ *
+ * **A band around every switch, so a still eye can never flip.** A region coarsens only once the
+ * eye is `1 + hysteresis` past the level's distance and refines only once it is `1 − hysteresis`
+ * inside it, so an eye standing on a threshold — or wobbling across it by less than the band —
+ * keeps the level it has. Distance is to the region's **box**, so the region under the eye is
+ * always at its finest, whatever its size.
+ *
+ * **A change crossfades rather than pops.** Each draw carries a dither for `setDitherFade`: the
+ * level arriving at `+t`, the one leaving at `−t`, which cover every pixel exactly once. `t` runs
+ * over `fadeSec` of the caller's `dtSec`, never a clock — so **a held clock never finishes a fade**,
+ * and a capture wants `fadeSec: 0`. A region nobody can see finishes any fade at once, and a region
+ * just added fades in from nothing.
+ *
+ * What it gives up: a region is one decision, so a long one seen end-on is drawn at the level its
+ * nearest corner asks for all the way along. Smaller regions are the lever.
+ *
+ * Nothing here allocates after construction except `add`, which is not per frame.
+ */
+import type { FrustumPlanes } from '../math/frustum.ts';
+import type { BoxOccluder } from '../render/instanceCull.ts';
+/** The level of a region drawn at none of its own: past `farDistance`, or not arrived yet. */
+export declare const HLOD_NONE = 255;
+export interface HlodOptions {
+    /** The most regions the set holds at once. */
+    readonly capacity: number;
+    /** The most levels a region may carry. 4 unless stated. */
+    readonly maxLevels?: number;
+    /** How many pixels of geometric error a level may show before a finer one is drawn. 1.5 unless stated. */
+    readonly pixelTolerance?: number;
+    /** The band around each switch, as a fraction of its distance. 0.15 unless stated. */
+    readonly hysteresis?: number;
+    /** Seconds a crossfade takes. 0.4 unless stated; 0 switches at once. */
+    readonly fadeSec?: number;
+    /** Beyond this, a region is drawn at no level at all. Unbounded unless stated. */
+    readonly farDistance?: number;
+}
+/** What `select` hands back: one entry per draw, a crossfading region taking two. */
+export interface HlodDraws {
+    count: number;
+    /** The region's id, as it was added. */
+    readonly region: Uint32Array;
+    /** Which of its levels to draw. */
+    readonly level: Uint8Array;
+    /** What to pass `setDitherFade` for this draw: 0 whole, `+t` arriving, `−t` leaving. */
+    readonly dither: Float32Array;
+}
+/** Room for every region of a set of this capacity, each crossfading at once. */
+export declare function createHlodDraws(capacity: number): HlodDraws;
+/** Pixels a metre spans at one metre's distance: the screen's half of the switch distance. */
+export declare function projectionScaleOf(fovYDeg: number, heightPx: number): number;
+export declare class HlodSet {
+    readonly capacity: number;
+    readonly maxLevels: number;
+    private readonly tolerance;
+    private readonly band;
+    private readonly fadeSec;
+    private readonly far;
+    private readonly slots;
+    private readonly ids;
+    private readonly boxes;
+    private readonly errors;
+    private readonly levels;
+    /** The level each region is at, or arriving at. */
+    private readonly level;
+    /** The level a crossfade is leaving. */
+    private readonly from;
+    /** How far through its crossfade each region is; 1 is settled. */
+    private readonly fade;
+    private readonly box;
+    private count;
+    constructor(options: HlodOptions);
+    get size(): number;
+    has(id: number): boolean;
+    /** The level a region is at or arriving at, or `HLOD_NONE`. -1 for a region not in the set. */
+    levelOf(id: number): number;
+    /**
+     * Add a region: its box as min then max, and one geometric error per level, finest first and
+     * never shrinking. It arrives at no level and fades into the one the next `select` picks.
+     */
+    add(id: number, box: ArrayLike<number>, errors: ArrayLike<number>): void;
+    /** Remove a region; nothing if it is not there. The last region takes its slot. */
+    remove(id: number): void;
+    /**
+     * Decide every region's level for this view and write what to draw into `out`, returning how
+     * many draws that is. `projectionScale` is `projectionScaleOf(fov, height)`; `occluder` may be
+     * the renderer, asked after this frame's occluders are declared.
+     */
+    select(eye: ArrayLike<number>, projectionScale: number, frustum: FrustumPlanes, occluder: BoxOccluder | null, dtSec: number, out: HlodDraws): number;
+    /** The level a region at distance `d` should be at, from where it is, through the bands. */
+    private levelFor;
+    /** The distance level `index` takes over at; the level past the coarsest is the far limit. */
+    private switchAt;
+    /** Begin, reverse or redirect a crossfade toward `target`. */
+    private move;
+    private emit;
+}