@driftengine/core 3.61.0

package/dist/render/sdfFont.d.ts

@@ -0,0 +1,77 @@
+/**
+ * An SDF font's metrics, parsed once and asked many times.
+ *
+ * The atlas image is the consumer's business — it arrives as a `TexImageSource` like every
+ * other texture this engine takes, and the engine still fetches nothing. This owns only
+ * the numbers that turn a string into quads.
+ */
+export interface SdfGlyph {
+    readonly advance: number;
+    /** The glyph's ink box in font units, y-up: `planeTop` is above `planeBottom`. */
+    readonly planeLeft: number;
+    readonly planeBottom: number;
+    readonly planeRight: number;
+    readonly planeTop: number;
+    /**
+     * The glyph's cell in the atlas texture, in texels.
+     *
+     * **The single statement of this convention — nowhere else should restate it, only rely on
+     * it.** These run the same direction the atlas PNG's own rows do, and the same direction
+     * `createSurfaceTexture` actually uploads: `SurfaceTexture` (both backends) does not flip an
+     * `ImageBitmap` source, so texture `v = 0` samples the PNG's own row 0, its top. `atlasTop`
+     * is therefore the *smaller* number — nearer row 0 — and `atlasBottom` the larger one,
+     * unlike `planeTop`/`planeBottom` above, which are a world-space quantity and stay y-up.
+     * `writeUv` in `sdfTextLayout.ts` divides these by `atlasWidth`/`atlasHeight` and uses the
+     * result as `v` directly: no flip, because these already agree with what the texture does.
+     *
+     * A version that flipped these to be y-up — matching the plane box's own sign, so that
+     * "a texel and a plane coordinate agree on which way is up" — shipped for two days
+     * (2026-08-16) and flipped every glyph onto the wrong row of its atlas, because
+     * `SurfaceTexture` had already stopped flipping the upload two days earlier. Two
+     * conventions that each sound reasonable alone cancelled into a bug neither side's unit
+     * tests could see, because neither one renders a real texture.
+     */
+    readonly atlasLeft: number;
+    readonly atlasBottom: number;
+    readonly atlasRight: number;
+    readonly atlasTop: number;
+}
+export interface SdfFont {
+    readonly family: string;
+    readonly unitsPerEm: number;
+    readonly ascender: number;
+    readonly descender: number;
+    readonly lineHeight: number;
+    readonly distanceRange: number;
+    readonly atlasWidth: number;
+    readonly atlasHeight: number;
+    /**
+     * Keys in the glyph table that are more than one character, longest first.
+     *
+     * A *pre-shaped run*: a string the generator handed to the platform's own text stack,
+     * which joined, reordered and shaped it, baked as one atlas cell. The runtime draws
+     * quads from metrics and does no shaping at all, so a script that joins its letters or
+     * reads right to left cannot be assembled from single glyphs at draw time. `أبو` came
+     * out as three disconnected isolated forms marching the wrong way; as one run it comes
+     * out as the word.
+     *
+     * Longest first because `sdfTextLayout.ts` takes the first match at the pen, and a
+     * shorter run that is a prefix of a longer one must not win.
+     */
+    readonly runs: readonly string[];
+    glyph(character: string): SdfGlyph | null;
+    kerning(left: string, right: string): number;
+}
+/**
+ * Validate and index a metrics document.
+ *
+ * **Throws on a version it does not recognise**, which is the fail-fast-at-init rule
+ * earning its keep: the alternative is reading a field that moved and drawing text that is
+ * subtly misplaced, and misplaced text looks like a layout bug for as long as it takes to
+ * suspect the file.
+ *
+ * Required numeric fields fail at load, not draw: `unitsPerEm` scales every plane and atlas
+ * coordinate, so a missing one produces wrong sizes that look plausible until a frame lands
+ * beside a reference and they do not match. Every other required field is checked the same way.
+ */
+export declare function parseSdfFont(document: unknown): SdfFont;

package/dist/render/sdfFont.js

@@ -0,0 +1,86 @@
+/**
+ * An SDF font's metrics, parsed once and asked many times.
+ *
+ * The atlas image is the consumer's business — it arrives as a `TexImageSource` like every
+ * other texture this engine takes, and the engine still fetches nothing. This owns only
+ * the numbers that turn a string into quads.
+ */
+const SUPPORTED_VERSION = 1;
+/**
+ * Validate and index a metrics document.
+ *
+ * **Throws on a version it does not recognise**, which is the fail-fast-at-init rule
+ * earning its keep: the alternative is reading a field that moved and drawing text that is
+ * subtly misplaced, and misplaced text looks like a layout bug for as long as it takes to
+ * suspect the file.
+ *
+ * Required numeric fields fail at load, not draw: `unitsPerEm` scales every plane and atlas
+ * coordinate, so a missing one produces wrong sizes that look plausible until a frame lands
+ * beside a reference and they do not match. Every other required field is checked the same way.
+ */
+export function parseSdfFont(document) {
+    if (typeof document !== 'object' || document === null) {
+        throw new Error('parseSdfFont: expected a metrics object');
+    }
+    const source = document;
+    if (source['version'] !== SUPPORTED_VERSION) {
+        throw new Error(`parseSdfFont: metrics version ${String(source['version'])}, this build reads ${SUPPORTED_VERSION}`);
+    }
+    if (typeof source['atlas'] !== 'object' || source['atlas'] === null) {
+        throw new Error('parseSdfFont: atlas field must be an object');
+    }
+    const atlas = source['atlas'];
+    if (typeof source['metrics'] !== 'object' || source['metrics'] === null) {
+        throw new Error('parseSdfFont: metrics field must be an object');
+    }
+    const metrics = source['metrics'];
+    if (typeof source['glyphs'] !== 'object' || source['glyphs'] === null) {
+        throw new Error('parseSdfFont: glyphs field must be an object');
+    }
+    const glyphs = source['glyphs'];
+    const kerning = (source['kerning'] ?? {});
+    // Validate required numeric fields
+    const requiredMetricsFields = ['unitsPerEm', 'ascender', 'descender', 'lineHeight'];
+    for (const field of requiredMetricsFields) {
+        if (typeof metrics[field] !== 'number') {
+            throw new Error(`parseSdfFont: metrics.${field} is required and must be a number`);
+        }
+    }
+    const requiredAtlasFields = ['distanceRange', 'width', 'height'];
+    for (const field of requiredAtlasFields) {
+        if (typeof atlas[field] !== 'number') {
+            throw new Error(`parseSdfFont: atlas.${field} is required and must be a number`);
+        }
+    }
+    return {
+        family: String(source['family'] ?? 'unnamed'),
+        unitsPerEm: metrics['unitsPerEm'],
+        ascender: metrics['ascender'],
+        descender: metrics['descender'],
+        lineHeight: metrics['lineHeight'],
+        distanceRange: atlas['distanceRange'],
+        atlasWidth: atlas['width'],
+        atlasHeight: atlas['height'],
+        runs: multiCharacterKeys(glyphs),
+        glyph(character) {
+            return glyphs[character] ?? null;
+        },
+        kerning(left, right) {
+            return kerning[`${left}\u0000${right}`] ?? 0;
+        },
+    };
+}
+/**
+ * Every key that spans more than one UTF-16 unit, longest first.
+ *
+ * Length in UTF-16 units rather than code points, because the one consumer of this order
+ * is `String.prototype.startsWith`, which counts the same way. Ties break lexicographically
+ * so that the order is a property of the table and not of the order it was written in: an
+ * atlas is committed and diffed, and a list that reshuffled when a glyph was added would
+ * make every rebake look like a change.
+ */
+function multiCharacterKeys(glyphs) {
+    return Object.keys(glyphs)
+        .filter((key) => key.length > 1)
+        .sort((a, b) => b.length - a.length || (a < b ? -1 : a > b ? 1 : 0));
+}

package/dist/render/sdfTextLayout.d.ts

@@ -0,0 +1,46 @@
+/**
+ * A string as quads, in metres, from a font's metrics.
+ *
+ * **No GL here, for the reason `textLayout.ts` gives:** which quads a string produces is
+ * the same arithmetic on either backend, so it lives once and the two renderers own only
+ * their buffers. It is also the half worth testing, and testing it needs no context.
+ *
+ * The local frame is x right, y up from the baseline, z zero. A caller supplies the basis
+ * that puts that somewhere -- `billboardMatrixY` for a label that faces the camera, a model
+ * matrix for one lying on a surface.
+ */
+import type { SdfFont } from './sdfFont.ts';
+export interface SdfTextStyle {
+    /** Cap height to baseline-to-baseline scale, in metres per em. */
+    readonly size: number;
+    readonly anchorX: 'left' | 'center' | 'right';
+    readonly anchorY: 'top' | 'middle' | 'baseline' | 'bottom';
+    /** Extra advance between glyphs, in ems. */
+    readonly letterSpacing: number;
+    /** Multiplier on the font's own line height. */
+    readonly lineHeight: number;
+}
+export declare const DEFAULT_SDF_TEXT_STYLE: SdfTextStyle;
+export declare class SdfTextLayout {
+    readonly positions: Float32Array<ArrayBuffer>;
+    readonly uvs: Float32Array<ArrayBuffer>;
+    readonly indices: Uint32Array<ArrayBuffer>;
+    quadCount: number;
+    width: number;
+    height: number;
+    private key;
+    constructor();
+    /**
+     * Lay a string out. Returns whether anything moved, so a caller can skip the upload.
+     *
+     * The key covers the style as well as the text, because a size change moves every vertex
+     * and a string that only compared its characters would keep the old geometry at the new
+     * size -- which reads as the wrong font rather than as a stale buffer.
+     *
+     * A *piece* is one code point, unless the font carries a pre-shaped run that starts here,
+     * in which case it is that run and it draws as a single quad. See `SdfFont.runs`: the
+     * engine does no shaping, so a script that joins or reorders its letters has to arrive
+     * already shaped, as one cell.
+     */
+    set(font: SdfFont, text: string, style: SdfTextStyle): boolean;
+}

package/dist/render/sdfTextLayout.js

@@ -0,0 +1,145 @@
+export const DEFAULT_SDF_TEXT_STYLE = {
+    size: 1,
+    anchorX: 'left',
+    anchorY: 'baseline',
+    letterSpacing: 0,
+    lineHeight: 1,
+};
+/** Longest string this lays out. Beyond it, the tail is dropped rather than grown into. */
+const MAX_QUADS = 512;
+export class SdfTextLayout {
+    positions = new Float32Array(MAX_QUADS * 4 * 3);
+    uvs = new Float32Array(MAX_QUADS * 4 * 2);
+    indices = new Uint32Array(MAX_QUADS * 6);
+    quadCount = 0;
+    width = 0;
+    height = 0;
+    key = '';
+    constructor() {
+        /* The index pattern never changes; only how much of it is drawn. */
+        for (let quad = 0; quad < MAX_QUADS; quad++) {
+            const v = quad * 4;
+            const i = quad * 6;
+            this.indices[i] = v;
+            this.indices[i + 1] = v + 1;
+            this.indices[i + 2] = v + 2;
+            this.indices[i + 3] = v;
+            this.indices[i + 4] = v + 2;
+            this.indices[i + 5] = v + 3;
+        }
+    }
+    /**
+     * Lay a string out. Returns whether anything moved, so a caller can skip the upload.
+     *
+     * The key covers the style as well as the text, because a size change moves every vertex
+     * and a string that only compared its characters would keep the old geometry at the new
+     * size -- which reads as the wrong font rather than as a stale buffer.
+     *
+     * A *piece* is one code point, unless the font carries a pre-shaped run that starts here,
+     * in which case it is that run and it draws as a single quad. See `SdfFont.runs`: the
+     * engine does no shaping, so a script that joins or reorders its letters has to arrive
+     * already shaped, as one cell.
+     */
+    set(font, text, style) {
+        const key = `${text}\u0000${style.size}\u0000${style.anchorX}\u0000${style.anchorY}\u0000${style.letterSpacing}\u0000${style.lineHeight}\u0000${font.family}`;
+        if (key === this.key)
+            return false;
+        this.key = key;
+        const scale = style.size / font.unitsPerEm;
+        let penX = 0;
+        let quads = 0;
+        let at = 0;
+        let piece = text.length > 0 ? pieceAt(font, text, 0) : '';
+        while (at < text.length && quads < MAX_QUADS) {
+            const nextAt = at + piece.length;
+            const next = nextAt < text.length ? pieceAt(font, text, nextAt) : '';
+            const glyph = font.glyph(piece);
+            if (glyph !== null) {
+                const left = penX + glyph.planeLeft * scale;
+                const right = penX + glyph.planeRight * scale;
+                const bottom = glyph.planeBottom * scale;
+                const top = glyph.planeTop * scale;
+                /* A glyph with no area -- a space -- advances and draws nothing. */
+                if (right > left && top > bottom) {
+                    const v = quads * 4;
+                    write(this.positions, v, left, bottom, right, top);
+                    writeUv(this.uvs, v, glyph.atlasLeft / font.atlasWidth, glyph.atlasBottom / font.atlasHeight, glyph.atlasRight / font.atlasWidth, glyph.atlasTop / font.atlasHeight);
+                    quads++;
+                }
+                penX += (glyph.advance + font.kerning(piece, next)) * scale;
+                penX += style.letterSpacing * style.size;
+            }
+            at = nextAt;
+            piece = next;
+        }
+        this.quadCount = quads;
+        this.width = penX;
+        this.height = (font.ascender - font.descender) * scale;
+        const shiftX = style.anchorX === 'center' ? -penX / 2 : style.anchorX === 'right' ? -penX : 0;
+        const shiftY = style.anchorY === 'middle'
+            ? -((font.ascender + font.descender) / 2) * scale
+            : style.anchorY === 'top'
+                ? -font.ascender * scale
+                : style.anchorY === 'bottom'
+                    ? -font.descender * scale
+                    : 0;
+        if (shiftX !== 0 || shiftY !== 0) {
+            for (let vertex = 0; vertex < quads * 4; vertex++) {
+                this.positions[vertex * 3] = this.positions[vertex * 3] + shiftX;
+                this.positions[vertex * 3 + 1] = this.positions[vertex * 3 + 1] + shiftY;
+            }
+        }
+        return true;
+    }
+}
+/** Four corners of a quad, counter-clockwise from bottom-left, at z = 0. */
+function write(out, vertex, left, bottom, right, top) {
+    const at = vertex * 3;
+    out[at] = left;
+    out[at + 1] = bottom;
+    out[at + 2] = 0;
+    out[at + 3] = right;
+    out[at + 4] = bottom;
+    out[at + 5] = 0;
+    out[at + 6] = right;
+    out[at + 7] = top;
+    out[at + 8] = 0;
+    out[at + 9] = left;
+    out[at + 10] = top;
+    out[at + 11] = 0;
+}
+/**
+ * The matching atlas corners. `atlasBottom`/`atlasTop` are already texel space -- not y-up,
+ * see `SdfGlyph`'s own comment for the convention and why nothing here flips them.
+ */
+function writeUv(out, vertex, left, bottom, right, top) {
+    const at = vertex * 2;
+    out[at] = left;
+    out[at + 1] = bottom;
+    out[at + 2] = right;
+    out[at + 3] = bottom;
+    out[at + 4] = right;
+    out[at + 5] = top;
+    out[at + 6] = left;
+    out[at + 7] = top;
+}
+/**
+ * What to draw at this position: the longest pre-shaped run that starts here, or the single
+ * code point that does.
+ *
+ * Runs arrive longest first (see `SdfFont.runs`), so the first match is the right one. A
+ * font with no runs skips the loop entirely and this is the same per-code-point walk the
+ * layout has always done, which is the regression that matters: every atlas baked before
+ * runs existed has to lay out identically.
+ *
+ * `startsWith` with an offset rather than a slice, because comparing a substring means
+ * building one, and this runs once per character of every label a scene sets.
+ */
+function pieceAt(font, text, at) {
+    for (const run of font.runs) {
+        if (run.length <= text.length - at && text.startsWith(run, at))
+            return run;
+    }
+    const code = text.codePointAt(at);
+    return code !== undefined && code > 0xffff ? text.slice(at, at + 2) : text.charAt(at);
+}

package/dist/render/sdfTextRenderer.d.ts

@@ -0,0 +1,75 @@
+import type { ReadonlyMat4 } from 'gl-matrix';
+import type { Vec3 } from '../math/color.ts';
+import type { SdfFont } from './sdfFont.ts';
+import type { SdfTextStyle } from './sdfTextLayout.ts';
+import type { SurfaceTexture } from './surfaceTexture.ts';
+/**
+ * Text from a signed distance field, on WebGL2.
+ *
+ * Same job as `textRenderer.ts` for the pixel font: a program, a VAO, buffers, one draw call
+ * per string, reached only through `renderer.createSdfText()` and its `setSdfText` /
+ * `drawSdfText` / `disposeSdfText`. Where this differs from that file, it is because SDF text
+ * genuinely differs:
+ *
+ * - **A flat quad per glyph, not an instanced cube.** The pixel font is lit geometry; an SDF
+ *   glyph is a distance field sampled by a fragment shader, so a quad textured with the field
+ *   is the whole glyph. One `drawElements` call draws every quad the string laid out.
+ * - **Coverage, not a solid.** The field's antialiased edge is an alpha value, so the draw
+ *   blends and never writes depth — see `draw` for what happens if it does.
+ * - **World geometry, not a screen overlay.** The pixel font builds its own projection from a
+ *   viewport and pixel origin; SDF text takes a model matrix and draws against the scene's own
+ *   view-projection, the same one `drawMesh` uses. A caller supplies the basis — see
+ *   `sdfTextLayout.ts`.
+ * - **The atlas is the caller's.** `setSdfText` retains it, exactly as `setSurfaceTexture`
+ *   retains a material's texture, so `draw` needs nothing handed to it again every frame.
+ *
+ * `aPosition`/`aUv` are hardcoded to locations 0/1 below, matching `sdfText.ts`'s own
+ * `layout(location = ...)` qualifiers — the same convention `text.ts`/`textRenderer.ts`
+ * follow. That file is the one written-down source of truth both this and the WGSL naga
+ * generates from it read; querying the locations at runtime instead would just be a second
+ * source of truth that happens to agree with the first until one of them changes.
+ */
+export declare class SdfTextRenderer {
+    private readonly gl;
+    private readonly program;
+    private readonly uniforms;
+    private readonly vao;
+    private readonly positionBuffer;
+    private readonly uvBuffer;
+    private readonly buffers;
+    private readonly layout;
+    /** Set by `setText`; `draw` reads neither the class nor the atlas from anywhere else. */
+    private font;
+    private atlas;
+    constructor(gl: WebGL2RenderingContext);
+    /**
+     * Lay a string out against a font, and retain the atlas `draw` will sample.
+     *
+     * The atlas is retained here rather than taken by `draw` for the same reason
+     * `setSurfaceTexture` retains a material's texture: a caller that draws the same label
+     * every frame should not have to keep handing over an object nothing about the frame
+     * changed. A no-op, and no re-upload, when neither the text nor the style moved.
+     */
+    setText(font: SdfFont, atlas: SurfaceTexture, text: string, style: SdfTextStyle): void;
+    /**
+     * Draw the laid-out string at `model`, against the scene's own view-projection.
+     *
+     * Nothing draws before a `setText` call has produced at least one quad, before a font and
+     * an atlas are both on hand, or once opacity has faded a label out — a caller may call
+     * this unconditionally.
+     *
+     * Returns whether a draw call was actually issued. `Renderer.drawSdfText` uses this to
+     * know whether `SDF_TEXT_TEXTURE_UNIT` was touched at all, since that unit doubles as
+     * `SURFACE_TEXTURE_UNIT` and the caller has to put the right texture back on it — but only
+     * when this class actually rebound it to the atlas.
+     */
+    /**
+     * `outputTransform` and `outputExposure` come from the renderer rather than from here, because
+     * whether this pass grades depends on whether anything after it will. See `Renderer.gradeCode`.
+     */
+    draw(viewProj: ReadonlyMat4, model: Float32Array, color: Vec3, opacity: number, outputTransform: number, outputExposure: number): boolean;
+    dispose(): void;
+    /** Both vertex buffers, from the arrays `layout.set` filled in place. */
+    private upload;
+    private dynamicAttribute;
+}

package/dist/render/sdfTextRenderer.js

@@ -0,0 +1,194 @@
+import { SdfTextLayout } from './sdfTextLayout.js';
+import { compileProgram, uniformLocations } from './shader.js';
+import { SDF_TEXT_FRAG, SDF_TEXT_VERT } from './shaders/sdfText.js';
+import { SDF_TEXT_TEXTURE_UNIT } from './lightBudget.js';
+/**
+ * Text from a signed distance field, on WebGL2.
+ *
+ * Same job as `textRenderer.ts` for the pixel font: a program, a VAO, buffers, one draw call
+ * per string, reached only through `renderer.createSdfText()` and its `setSdfText` /
+ * `drawSdfText` / `disposeSdfText`. Where this differs from that file, it is because SDF text
+ * genuinely differs:
+ *
+ * - **A flat quad per glyph, not an instanced cube.** The pixel font is lit geometry; an SDF
+ *   glyph is a distance field sampled by a fragment shader, so a quad textured with the field
+ *   is the whole glyph. One `drawElements` call draws every quad the string laid out.
+ * - **Coverage, not a solid.** The field's antialiased edge is an alpha value, so the draw
+ *   blends and never writes depth — see `draw` for what happens if it does.
+ * - **World geometry, not a screen overlay.** The pixel font builds its own projection from a
+ *   viewport and pixel origin; SDF text takes a model matrix and draws against the scene's own
+ *   view-projection, the same one `drawMesh` uses. A caller supplies the basis — see
+ *   `sdfTextLayout.ts`.
+ * - **The atlas is the caller's.** `setSdfText` retains it, exactly as `setSurfaceTexture`
+ *   retains a material's texture, so `draw` needs nothing handed to it again every frame.
+ *
+ * `aPosition`/`aUv` are hardcoded to locations 0/1 below, matching `sdfText.ts`'s own
+ * `layout(location = ...)` qualifiers — the same convention `text.ts`/`textRenderer.ts`
+ * follow. That file is the one written-down source of truth both this and the WGSL naga
+ * generates from it read; querying the locations at runtime instead would just be a second
+ * source of truth that happens to agree with the first until one of them changes.
+ */
+export class SdfTextRenderer {
+    gl;
+    program;
+    uniforms;
+    vao;
+    positionBuffer;
+    uvBuffer;
+    buffers = [];
+    layout = new SdfTextLayout();
+    /** Set by `setText`; `draw` reads neither the class nor the atlas from anywhere else. */
+    font = null;
+    atlas = null;
+    constructor(gl) {
+        this.gl = gl;
+        this.program = compileProgram(gl, SDF_TEXT_VERT, SDF_TEXT_FRAG, 'sdfText');
+        this.uniforms = uniformLocations(gl, this.program, 'sdfTextRenderer');
+        const vao = gl.createVertexArray();
+        if (vao === null)
+            throw new Error('Failed to create SDF text VAO');
+        this.vao = vao;
+        gl.bindVertexArray(vao);
+        /*
+         * Positions and UVs are `DYNAMIC_DRAW` and start already sized to `layout`'s own
+         * capacity, uploaded from its (all-zero, at this point) arrays. `bufferData` with a
+         * typed array both allocates and uploads in the one call, and the array is already the
+         * exact size a full string can reach, so there is no separate "how big" to track here.
+         *
+         * Locations 0 and 1 are `sdfText.ts`'s own `layout(location = ...)` qualifiers, not a
+         * guess — see the class comment.
+         */
+        this.positionBuffer = this.dynamicAttribute(0, this.layout.positions, 3);
+        this.uvBuffer = this.dynamicAttribute(1, this.layout.uvs, 2);
+        /*
+         * The index buffer, `STATIC_DRAW` and written once. `SdfTextLayout` fills its whole
+         * `0,1,2,0,2,3` pattern for every quad it could ever hold at construction — see its own
+         * comment — so nothing about a later `set()` call ever changes this buffer's contents,
+         * only how much of it `draw` asks to be drawn.
+         */
+        const indexBuffer = gl.createBuffer();
+        if (indexBuffer === null)
+            throw new Error('Failed to create SDF text index buffer');
+        this.buffers.push(indexBuffer);
+        gl.bindBuffer(gl.ELEMENT_ARRAY_BUFFER, indexBuffer);
+        gl.bufferData(gl.ELEMENT_ARRAY_BUFFER, this.layout.indices, gl.STATIC_DRAW);
+        gl.bindVertexArray(null);
+    }
+    /**
+     * Lay a string out against a font, and retain the atlas `draw` will sample.
+     *
+     * The atlas is retained here rather than taken by `draw` for the same reason
+     * `setSurfaceTexture` retains a material's texture: a caller that draws the same label
+     * every frame should not have to keep handing over an object nothing about the frame
+     * changed. A no-op, and no re-upload, when neither the text nor the style moved.
+     */
+    setText(font, atlas, text, style) {
+        this.font = font;
+        this.atlas = atlas;
+        if (this.layout.set(font, text, style))
+            this.upload();
+    }
+    /**
+     * Draw the laid-out string at `model`, against the scene's own view-projection.
+     *
+     * Nothing draws before a `setText` call has produced at least one quad, before a font and
+     * an atlas are both on hand, or once opacity has faded a label out — a caller may call
+     * this unconditionally.
+     *
+     * Returns whether a draw call was actually issued. `Renderer.drawSdfText` uses this to
+     * know whether `SDF_TEXT_TEXTURE_UNIT` was touched at all, since that unit doubles as
+     * `SURFACE_TEXTURE_UNIT` and the caller has to put the right texture back on it — but only
+     * when this class actually rebound it to the atlas.
+     */
+    /**
+     * `outputTransform` and `outputExposure` come from the renderer rather than from here, because
+     * whether this pass grades depends on whether anything after it will. See `Renderer.gradeCode`.
+     */
+    draw(viewProj, model, color, opacity, outputTransform, outputExposure) {
+        if (this.layout.quadCount === 0 || opacity <= 0 || this.font === null || this.atlas === null) {
+            return false;
+        }
+        const gl = this.gl;
+        const font = this.font;
+        gl.useProgram(this.program);
+        gl.bindVertexArray(this.vao);
+        /*
+         * Blending on, depth writes off. Text is coverage: the field's antialiased edge is an
+         * alpha value, not a solid surface, and writing depth from it punches a hole in whatever
+         * sits behind that edge — a bug that looks like a broken font rather than a depth bug.
+         *
+         * Depth *testing* is left alone, deliberately, rather than reasserted the way the pixel
+         * font's own `TextRenderer.draw` reasserts it. That renderer is a screen overlay running
+         * at the end of the frame and has to recover state a sky or an earlier pass may have
+         * left behind. SDF text is world geometry drawn inside the mesh pass, where an enabled
+         * depth test and `LEQUAL` are already the ambient state — the same assumption
+         * `drawTranslucentMesh` makes for exactly the same reason.
+         */
+        gl.depthMask(false);
+        gl.enable(gl.BLEND);
+        gl.blendFunc(gl.SRC_ALPHA, gl.ONE_MINUS_SRC_ALPHA);
+        this.atlas.bind(gl, SDF_TEXT_TEXTURE_UNIT);
+        const u = this.uniforms;
+        gl.uniform1i(u['uOutputTransform'] ?? null, outputTransform);
+        gl.uniform1f(u['uOutputExposure'] ?? null, outputExposure);
+        setMat4(gl, u['uViewProj'], viewProj);
+        setMat4(gl, u['uModel'], model);
+        setVec3(gl, u['uColor'], color);
+        setFloat(gl, u['uOpacity'], opacity);
+        setFloat(gl, u['uDistanceRange'], font.distanceRange);
+        setVec2(gl, u['uAtlasSize'], font.atlasWidth, font.atlasHeight);
+        const atlasLoc = u['uAtlas'];
+        if (atlasLoc !== undefined)
+            gl.uniform1i(atlasLoc, SDF_TEXT_TEXTURE_UNIT);
+        gl.drawElements(gl.TRIANGLES, this.layout.quadCount * 6, gl.UNSIGNED_INT, 0);
+        gl.bindVertexArray(null);
+        gl.disable(gl.BLEND);
+        gl.depthMask(true);
+        return true;
+    }
+    dispose() {
+        const gl = this.gl;
+        for (const buffer of this.buffers)
+            gl.deleteBuffer(buffer);
+        this.buffers.length = 0;
+        gl.deleteVertexArray(this.vao);
+        gl.deleteProgram(this.program);
+    }
+    /** Both vertex buffers, from the arrays `layout.set` filled in place. */
+    upload() {
+        const gl = this.gl;
+        const vertexCount = this.layout.quadCount * 4;
+        gl.bindBuffer(gl.ARRAY_BUFFER, this.positionBuffer);
+        gl.bufferSubData(gl.ARRAY_BUFFER, 0, this.layout.positions, 0, vertexCount * 3);
+        gl.bindBuffer(gl.ARRAY_BUFFER, this.uvBuffer);
+        gl.bufferSubData(gl.ARRAY_BUFFER, 0, this.layout.uvs, 0, vertexCount * 2);
+    }
+    dynamicAttribute(location, initial, size) {
+        const gl = this.gl;
+        const buffer = gl.createBuffer();
+        if (buffer === null)
+            throw new Error('Failed to create SDF text buffer');
+        this.buffers.push(buffer);
+        gl.bindBuffer(gl.ARRAY_BUFFER, buffer);
+        gl.bufferData(gl.ARRAY_BUFFER, initial, gl.DYNAMIC_DRAW);
+        gl.enableVertexAttribArray(location);
+        gl.vertexAttribPointer(location, size, gl.FLOAT, false, 0, 0);
+        return buffer;
+    }
+}
+function setFloat(gl, location, value) {
+    if (location !== undefined)
+        gl.uniform1f(location, value);
+}
+function setVec2(gl, location, x, y) {
+    if (location !== undefined)
+        gl.uniform2f(location, x, y);
+}
+function setVec3(gl, location, value) {
+    if (location !== undefined)
+        gl.uniform3f(location, value[0], value[1], value[2]);
+}
+function setMat4(gl, location, value) {
+    if (location !== undefined)
+        gl.uniformMatrix4fv(location, false, value);
+}

package/dist/render/seaState.d.ts

@@ -0,0 +1,25 @@
+/**
+ * How rough the sea is for a given wind.
+ *
+ * Wind does not push existing waves around — it *builds* them. A calm sea is
+ * nearly flat with no whitecaps; a strong wind raises steep crests that break.
+ * Steering the swell without changing its size would leave the water equally
+ * choppy in a dead calm and a gale, which is the giveaway that the weather is
+ * decoration rather than a cause.
+ */
+export interface SeaState {
+    /** Multiplier on the Gerstner steepness the surface was authored with. */
+    steepness: number;
+    /** How readily crests break into foam, 0 for none. */
+    foam: number;
+}
+export declare function seaStateForWind(windSpeed: number): SeaState;
+/**
+ * The same surface state, asked for directly instead of derived from wind.
+ *
+ * Shares this module's floor and ceiling so an indoor body and an outdoor one at the
+ * same roughness look the same — the point is where the number *comes from*, not a
+ * second scale with its own feel. Foam is deliberately reachable: a sluice or a pump
+ * outfall breaks without any wind at all.
+ */
+export declare function seaStateForAgitation(agitation: number): SeaState;