@driftengine/core 3.61.0

package/dist/render/temporalAa.d.ts

@@ -0,0 +1,104 @@
+import { mat4 } from 'gl-matrix';
+import type { ReadonlyMat4 } from 'gl-matrix';
+/**
+ * The sub-pixel sequence a temporal resolve samples along, and the state that says whether there
+ * is anything to resolve *against* yet.
+ *
+ * **Antialiasing by moving the camera rather than by taking more samples.** A frame is rasterised
+ * with the projection shifted a fraction of a pixel, so an edge that fell one side of a pixel
+ * centre falls the other side next frame, and blending the two puts the edge where it actually
+ * is. What MSAA buys per frame this buys across frames, at one extra texture and one extra pass
+ * instead of a multiplied fill rate — which is the trade a browser target wants.
+ *
+ * **This file holds only the parts that are arithmetic**, so they can be asserted without a
+ * device: where the next sample sits, what that does to a projection matrix, and whether the
+ * history is usable this frame. The resolve itself is a shader and belongs to each backend.
+ */
+/**
+ * How many frames the sequence takes to come back round.
+ *
+ * Eight rather than sixteen: the accumulation converges in eight frames instead of sixteen, and
+ * every frame of history is a frame of ghosting a moving object has to be clipped out of. The
+ * sequence is the deciding factor rather than the count — eight *distinct* low-discrepancy
+ * positions beat sixteen that clump.
+ */
+export declare const JITTER_PERIOD = 8;
+/**
+ * How much of the clipped history each resolved frame keeps.
+ *
+ * Nine parts history to one part this frame, which gives the accumulation an effective window of
+ * about ten frames — a little longer than the eight-frame period, so every offset in the sequence
+ * still contributes to what is on screen. Higher holds a ghost for longer wherever the
+ * neighbourhood clip does not catch it; lower stops converging before the period is out and leaves
+ * the crawl this exists to remove.
+ */
+export declare const TEMPORAL_HISTORY_BLEND = 0.9;
+/** Where in its pixel frame `frameIndex` samples, in pixels, centred on zero. */
+export declare function jitterOffset(frameIndex: number): readonly [number, number];
+/**
+ * `source` shifted by `offsetX`, `offsetY` pixels on a `width` by `height` target.
+ *
+ * **A clip-space translation scaled by w, and not an edit to the projection's third column.** The
+ * usual trick adds the offset to the third column, where it is multiplied by view z and the
+ * perspective divide then cancels it — which is exact, and only for a bare perspective projection.
+ * This engine's single funnel for geometry is `viewProjFor`, which carries a *combined*
+ * view-projection: there the third column multiplies world z instead of view z, and the jitter
+ * would swim with the scene's own depth. An orthographic matrix breaks it too, its w being 1.
+ *
+ * Adding `offset * w` to clip x and y is what those two cases have in common. It survives the
+ * divide as a constant screen offset at every distance, whatever produced the clip position, so
+ * this may be handed a projection or a view-projection and is correct for both — which is the
+ * property the near-and-far test beside this pins.
+ *
+ * **A zero offset returns the matrix unchanged, bit for bit.** Every published capture is taken
+ * with this off, and a jitter of zero that still ran the arithmetic would move pixels by whatever
+ * it rounded to.
+ */
+export declare function jitterProjection(out: mat4, source: ReadonlyMat4, offsetX: number, offsetY: number, width: number, height: number): mat4;
+/** A colour the resolve is working on, as three numbers rather than a texture fetch. */
+export type Rgb = [number, number, number];
+/**
+ * `history` pulled into the box `min`..`max`, along the line towards the box's centre.
+ *
+ * **This is what separates a temporal resolve from a long exposure.** Reprojection finds where a
+ * pixel *was*; nothing in it knows whether what was there is what is there now. A character
+ * walking in front of a wall reprojects onto wall, and blending nine parts of that history is a
+ * smear that follows them about. The colours actually present around the pixel this frame bound
+ * what the history is allowed to be, and anything outside those bounds is a sample of something
+ * that has gone.
+ *
+ * **Clipped towards the centre rather than clamped per channel.** A clamp moves each channel
+ * independently, so a history that is merely brighter than its surroundings lands on a corner of
+ * the box and comes back a different hue, which reads as coloured fringing along every moving
+ * edge. Shortening the whole offset by one ratio keeps the direction and changes only the length.
+ *
+ * The same arithmetic is in `TEMPORAL_RESOLVE_FRAG`, and the shader test asserts the shader still
+ * spells it this way.
+ */
+export declare function clipToNeighbourhood(out: Rgb, history: readonly [number, number, number], min: readonly [number, number, number], max: readonly [number, number, number]): Rgb;
+/**
+ * Whether the last frame left a picture this one may sample, and where the jitter has got to.
+ *
+ * **Two calls a frame, and the split is the point.** `openFrame` answers a question about the
+ * state *before* this frame writes anything, and the resolve needs that answer before it writes;
+ * `accumulated` reports that a picture now exists. One call cannot do both.
+ */
+export declare class TemporalHistory {
+    /** How many frames have been opened, which is what indexes the jitter. */
+    frameIndex: number;
+    private picture;
+    private width;
+    private height;
+    /**
+     * Open a frame at this target size, and answer whether the history may be sampled.
+     *
+     * **The jitter advances whether or not it may be.** Holding the sequence still on the frames a
+     * resize or a cut discarded would sample the same position twice running, which is one sample
+     * and not two.
+     */
+    openFrame(width: number, height: number): boolean;
+    /** A resolved picture is now in the history, at the size the frame was opened with. */
+    accumulated(): void;
+    /** Forget it — a cut, a teleport, or anything else that makes the last frame a different scene. */
+    invalidate(): void;
+}

package/dist/render/temporalAa.js

@@ -0,0 +1,194 @@
+import { mat4 } from 'gl-matrix';
+/**
+ * The sub-pixel sequence a temporal resolve samples along, and the state that says whether there
+ * is anything to resolve *against* yet.
+ *
+ * **Antialiasing by moving the camera rather than by taking more samples.** A frame is rasterised
+ * with the projection shifted a fraction of a pixel, so an edge that fell one side of a pixel
+ * centre falls the other side next frame, and blending the two puts the edge where it actually
+ * is. What MSAA buys per frame this buys across frames, at one extra texture and one extra pass
+ * instead of a multiplied fill rate — which is the trade a browser target wants.
+ *
+ * **This file holds only the parts that are arithmetic**, so they can be asserted without a
+ * device: where the next sample sits, what that does to a projection matrix, and whether the
+ * history is usable this frame. The resolve itself is a shader and belongs to each backend.
+ */
+/**
+ * How many frames the sequence takes to come back round.
+ *
+ * Eight rather than sixteen: the accumulation converges in eight frames instead of sixteen, and
+ * every frame of history is a frame of ghosting a moving object has to be clipped out of. The
+ * sequence is the deciding factor rather than the count — eight *distinct* low-discrepancy
+ * positions beat sixteen that clump.
+ */
+export const JITTER_PERIOD = 8;
+/**
+ * How much of the clipped history each resolved frame keeps.
+ *
+ * Nine parts history to one part this frame, which gives the accumulation an effective window of
+ * about ten frames — a little longer than the eight-frame period, so every offset in the sequence
+ * still contributes to what is on screen. Higher holds a ghost for longer wherever the
+ * neighbourhood clip does not catch it; lower stops converging before the period is out and leaves
+ * the crawl this exists to remove.
+ */
+export const TEMPORAL_HISTORY_BLEND = 0.9;
+/**
+ * The radical inverse of `index` in `base`, which is what makes a Halton sequence fill a gap
+ * before it fills a corner.
+ *
+ * Consecutive samples land as far from each other as the base allows, so eight of them cover the
+ * pixel evenly where eight random ones would leave holes and pairs.
+ */
+function halton(index, base) {
+    let result = 0;
+    let fraction = 1;
+    let i = index;
+    while (i > 0) {
+        fraction /= base;
+        result += fraction * (i % base);
+        i = Math.floor(i / base);
+    }
+    return result;
+}
+/**
+ * The period's offsets, centred so they sum to zero.
+ *
+ * **Halton's own mean is not the middle of the pixel** — over eight samples base two averages
+ * 0.445 rather than 0.5 — and accumulating towards a mean that is off centre resolves to a picture
+ * displaced from the depth buffer it was tested against and from every pass that did not jitter.
+ * Subtracting the period's own mean costs nothing and makes the property exact rather than
+ * approximate, which is what lets the test assert it.
+ */
+const OFFSETS = (() => {
+    const raw = [];
+    for (let i = 1; i <= JITTER_PERIOD; i++)
+        raw.push([halton(i, 2), halton(i, 3)]);
+    const meanX = raw.reduce((sum, o) => sum + o[0], 0) / JITTER_PERIOD;
+    const meanY = raw.reduce((sum, o) => sum + o[1], 0) / JITTER_PERIOD;
+    return raw.map(([x, y]) => [x - meanX, y - meanY]);
+})();
+/** Where in its pixel frame `frameIndex` samples, in pixels, centred on zero. */
+export function jitterOffset(frameIndex) {
+    const at = ((frameIndex % JITTER_PERIOD) + JITTER_PERIOD) % JITTER_PERIOD;
+    return OFFSETS[at];
+}
+/**
+ * `source` shifted by `offsetX`, `offsetY` pixels on a `width` by `height` target.
+ *
+ * **A clip-space translation scaled by w, and not an edit to the projection's third column.** The
+ * usual trick adds the offset to the third column, where it is multiplied by view z and the
+ * perspective divide then cancels it — which is exact, and only for a bare perspective projection.
+ * This engine's single funnel for geometry is `viewProjFor`, which carries a *combined*
+ * view-projection: there the third column multiplies world z instead of view z, and the jitter
+ * would swim with the scene's own depth. An orthographic matrix breaks it too, its w being 1.
+ *
+ * Adding `offset * w` to clip x and y is what those two cases have in common. It survives the
+ * divide as a constant screen offset at every distance, whatever produced the clip position, so
+ * this may be handed a projection or a view-projection and is correct for both — which is the
+ * property the near-and-far test beside this pins.
+ *
+ * **A zero offset returns the matrix unchanged, bit for bit.** Every published capture is taken
+ * with this off, and a jitter of zero that still ran the arithmetic would move pixels by whatever
+ * it rounded to.
+ */
+export function jitterProjection(out, source, offsetX, offsetY, width, height) {
+    mat4.copy(out, source);
+    if (offsetX === 0 && offsetY === 0)
+        return out;
+    const ndcX = (2 * offsetX) / width;
+    const ndcY = (2 * offsetY) / height;
+    /* Row 0 gains `ndcX` times row 3, and row 1 `ndcY` times it, which is `T * source` for a T
+       translating in clip space — done in place because that product touches nothing else. */
+    for (let column = 0; column < 4; column++) {
+        const w = source[column * 4 + 3];
+        out[column * 4 + 0] += ndcX * w;
+        out[column * 4 + 1] += ndcY * w;
+    }
+    return out;
+}
+/**
+ * `history` pulled into the box `min`..`max`, along the line towards the box's centre.
+ *
+ * **This is what separates a temporal resolve from a long exposure.** Reprojection finds where a
+ * pixel *was*; nothing in it knows whether what was there is what is there now. A character
+ * walking in front of a wall reprojects onto wall, and blending nine parts of that history is a
+ * smear that follows them about. The colours actually present around the pixel this frame bound
+ * what the history is allowed to be, and anything outside those bounds is a sample of something
+ * that has gone.
+ *
+ * **Clipped towards the centre rather than clamped per channel.** A clamp moves each channel
+ * independently, so a history that is merely brighter than its surroundings lands on a corner of
+ * the box and comes back a different hue, which reads as coloured fringing along every moving
+ * edge. Shortening the whole offset by one ratio keeps the direction and changes only the length.
+ *
+ * The same arithmetic is in `TEMPORAL_RESOLVE_FRAG`, and the shader test asserts the shader still
+ * spells it this way.
+ */
+export function clipToNeighbourhood(out, history, min, max) {
+    const centre = [0, 0, 0];
+    const offset = [0, 0, 0];
+    let ratio = 0;
+    for (let c = 0; c < 3; c++) {
+        centre[c] = (min[c] + max[c]) * 0.5;
+        offset[c] = history[c] - centre[c];
+        const extent = (max[c] - min[c]) * 0.5;
+        /*
+         * A channel with no extent cannot bound anything, so a history that differs from it at all is
+         * infinitely outside and collapses to the neighbourhood — which is the honest answer for a
+         * flat region, and the alternative is a division by zero.
+         */
+        if (extent > 1e-7)
+            ratio = Math.max(ratio, Math.abs(offset[c]) / extent);
+        else if (Math.abs(offset[c]) > 1e-7)
+            ratio = Number.POSITIVE_INFINITY;
+    }
+    if (!(ratio > 1)) {
+        out[0] = history[0];
+        out[1] = history[1];
+        out[2] = history[2];
+        return out;
+    }
+    const scale = Number.isFinite(ratio) ? 1 / ratio : 0;
+    out[0] = centre[0] + offset[0] * scale;
+    out[1] = centre[1] + offset[1] * scale;
+    out[2] = centre[2] + offset[2] * scale;
+    return out;
+}
+/**
+ * Whether the last frame left a picture this one may sample, and where the jitter has got to.
+ *
+ * **Two calls a frame, and the split is the point.** `openFrame` answers a question about the
+ * state *before* this frame writes anything, and the resolve needs that answer before it writes;
+ * `accumulated` reports that a picture now exists. One call cannot do both.
+ */
+export class TemporalHistory {
+    /** How many frames have been opened, which is what indexes the jitter. */
+    frameIndex = 0;
+    picture = false;
+    width = 0;
+    height = 0;
+    /**
+     * Open a frame at this target size, and answer whether the history may be sampled.
+     *
+     * **The jitter advances whether or not it may be.** Holding the sequence still on the frames a
+     * resize or a cut discarded would sample the same position twice running, which is one sample
+     * and not two.
+     */
+    openFrame(width, height) {
+        this.frameIndex++;
+        const usable = this.picture && width === this.width && height === this.height;
+        if (!usable)
+            this.picture = false;
+        this.width = width;
+        this.height = height;
+        return usable;
+    }
+    /** A resolved picture is now in the history, at the size the frame was opened with. */
+    accumulated() {
+        this.picture = true;
+    }
+    /** Forget it — a cut, a teleport, or anything else that makes the last frame a different scene. */
+    invalidate() {
+        this.picture = false;
+    }
+}

package/dist/render/temporalPass.d.ts

@@ -0,0 +1,54 @@
+/**
+ * The temporal resolve on WebGL2: this frame blended into where the last one was.
+ *
+ * **Two targets and a swap, because a pass cannot read the texture it is writing.** The history is
+ * sampled at a reprojected coordinate, which is somewhere else in the same image, so reading and
+ * writing one texture is a feedback loop — undefined in WebGL2 and in practice whatever the driver
+ * left in the cache. So the resolve writes into the one it did not read and the pair swaps, which
+ * costs one more full-size texture and nothing per pixel.
+ *
+ * **What it returns is what the composite must then treat as the scene.** Bloom, occlusion and the
+ * grade all read the scene texture, and reading the unresolved one would grade a stable picture
+ * from an unstable source and put the crawl back on screen through the bloom.
+ */
+export declare class TemporalPass {
+    private readonly gl;
+    /**
+     * Matched to the scene target's own format, and it has to be.
+     *
+     * A half-float scene resolved into an eight-bit history is squashed into 0 to 1 on its way in
+     * and read back squashed, so the accumulation would pull every value above white *down* over
+     * eight frames — a bloom threshold that stopped meaning brightness, and a sunset that faded
+     * while the camera held still.
+     */
+    private readonly floatColor;
+    private readonly program;
+    private readonly uniforms;
+    private readonly vao;
+    /** The pair, and which of them the next resolve writes into. */
+    private textures;
+    private framebuffers;
+    private write;
+    private width;
+    private height;
+    constructor(gl: WebGL2RenderingContext, 
+    /**
+     * Matched to the scene target's own format, and it has to be.
+     *
+     * A half-float scene resolved into an eight-bit history is squashed into 0 to 1 on its way in
+     * and read back squashed, so the accumulation would pull every value above white *down* over
+     * eight frames — a bloom threshold that stopped meaning brightness, and a sunset that faded
+     * while the camera held still.
+     */
+    floatColor: boolean);
+    private ensureSize;
+    /**
+     * Resolve `scene` against the history and return the texture now holding the resolved frame.
+     *
+     * `blend` is how much of the clipped history to keep, and **zero is the whole switch**: the
+     * first frame, the frame after a resize and the frame after a cut pass zero, and the shader
+     * then returns this frame before it touches depth or history at all.
+     */
+    temporalResolve(scene: WebGLTexture, depth: WebGLTexture, reprojection: Float32Array, width: number, height: number, blend: number): WebGLTexture;
+    dispose(): void;
+}

package/dist/render/temporalPass.js

@@ -0,0 +1,135 @@
+import { compileProgram, uniformLocations } from './shader.js';
+import { FULLSCREEN_VERT } from './shaders/fullscreen.js';
+import { TEMPORAL_RESOLVE_FRAG } from './shaders/temporalResolve.js';
+/**
+ * The temporal resolve on WebGL2: this frame blended into where the last one was.
+ *
+ * **Two targets and a swap, because a pass cannot read the texture it is writing.** The history is
+ * sampled at a reprojected coordinate, which is somewhere else in the same image, so reading and
+ * writing one texture is a feedback loop — undefined in WebGL2 and in practice whatever the driver
+ * left in the cache. So the resolve writes into the one it did not read and the pair swaps, which
+ * costs one more full-size texture and nothing per pixel.
+ *
+ * **What it returns is what the composite must then treat as the scene.** Bloom, occlusion and the
+ * grade all read the scene texture, and reading the unresolved one would grade a stable picture
+ * from an unstable source and put the crawl back on screen through the bloom.
+ */
+export class TemporalPass {
+    gl;
+    floatColor;
+    program;
+    uniforms;
+    vao;
+    /** The pair, and which of them the next resolve writes into. */
+    textures = [null, null];
+    framebuffers = [null, null];
+    write = 0;
+    width = 0;
+    height = 0;
+    constructor(gl, 
+    /**
+     * Matched to the scene target's own format, and it has to be.
+     *
+     * A half-float scene resolved into an eight-bit history is squashed into 0 to 1 on its way in
+     * and read back squashed, so the accumulation would pull every value above white *down* over
+     * eight frames — a bloom threshold that stopped meaning brightness, and a sunset that faded
+     * while the camera held still.
+     */
+    floatColor) {
+        this.gl = gl;
+        this.floatColor = floatColor;
+        this.program = compileProgram(gl, FULLSCREEN_VERT, TEMPORAL_RESOLVE_FRAG, 'temporalResolve');
+        this.uniforms = uniformLocations(gl, this.program, 'temporalPass');
+        const vao = gl.createVertexArray();
+        if (vao === null)
+            throw new Error('TemporalPass: createVertexArray failed');
+        this.vao = vao;
+    }
+    ensureSize(width, height) {
+        if (this.width === width && this.height === height && this.textures[0] !== null)
+            return;
+        const { gl } = this;
+        this.width = width;
+        this.height = height;
+        for (let i = 0; i < 2; i++) {
+            if (this.textures[i] === null)
+                this.textures[i] = gl.createTexture();
+            gl.bindTexture(gl.TEXTURE_2D, this.textures[i]);
+            if (this.floatColor) {
+                gl.texImage2D(gl.TEXTURE_2D, 0, gl.RGBA16F, width, height, 0, gl.RGBA, gl.HALF_FLOAT, null);
+            }
+            else {
+                gl.texImage2D(gl.TEXTURE_2D, 0, gl.RGBA, width, height, 0, gl.RGBA, gl.UNSIGNED_BYTE, null);
+            }
+            /* Linear, because the history is sampled between texels wherever the reprojection lands;
+               clamped, because a sample that wrapped would pull the far edge of the screen into the
+               corner — and the shader rejects an off-screen reprojection before it can anyway. */
+            gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_MIN_FILTER, gl.LINEAR);
+            gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_MAG_FILTER, gl.LINEAR);
+            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);
+            if (this.framebuffers[i] === null)
+                this.framebuffers[i] = gl.createFramebuffer();
+            gl.bindFramebuffer(gl.FRAMEBUFFER, this.framebuffers[i]);
+            gl.framebufferTexture2D(gl.FRAMEBUFFER, gl.COLOR_ATTACHMENT0, gl.TEXTURE_2D, this.textures[i], 0);
+        }
+        gl.bindFramebuffer(gl.FRAMEBUFFER, null);
+    }
+    /**
+     * Resolve `scene` against the history and return the texture now holding the resolved frame.
+     *
+     * `blend` is how much of the clipped history to keep, and **zero is the whole switch**: the
+     * first frame, the frame after a resize and the frame after a cut pass zero, and the shader
+     * then returns this frame before it touches depth or history at all.
+     */
+    temporalResolve(scene, depth, reprojection, width, height, blend) {
+        const { gl } = this;
+        this.ensureSize(width, height);
+        const target = this.write;
+        const history = 1 - this.write;
+        gl.bindFramebuffer(gl.FRAMEBUFFER, this.framebuffers[target]);
+        gl.viewport(0, 0, width, height);
+        gl.disable(gl.DEPTH_TEST);
+        gl.disable(gl.BLEND);
+        gl.disable(gl.CULL_FACE);
+        gl.depthMask(false);
+        gl.useProgram(this.program);
+        gl.activeTexture(gl.TEXTURE0);
+        gl.bindTexture(gl.TEXTURE_2D, scene);
+        gl.uniform1i(this.uniforms['uScene'] ?? null, 0);
+        gl.activeTexture(gl.TEXTURE1);
+        gl.bindTexture(gl.TEXTURE_2D, this.textures[history]);
+        gl.uniform1i(this.uniforms['uHistory'] ?? null, 1);
+        gl.activeTexture(gl.TEXTURE2);
+        gl.bindTexture(gl.TEXTURE_2D, depth);
+        gl.uniform1i(this.uniforms['uDepth'] ?? null, 2);
+        gl.uniformMatrix4fv(this.uniforms['uReprojection'] ?? null, false, reprojection);
+        gl.uniform2f(this.uniforms['uTexel'] ?? null, 1 / width, 1 / height);
+        gl.uniform1f(this.uniforms['uHistoryBlend'] ?? null, blend);
+        gl.bindVertexArray(this.vao);
+        gl.drawArrays(gl.TRIANGLES, 0, 3);
+        gl.bindVertexArray(null);
+        gl.activeTexture(gl.TEXTURE0);
+        gl.bindFramebuffer(gl.FRAMEBUFFER, null);
+        this.write = history;
+        const resolved = this.textures[target];
+        if (resolved === null)
+            throw new Error('TemporalPass: resolve target missing');
+        return resolved;
+    }
+    dispose() {
+        const { gl } = this;
+        for (let i = 0; i < 2; i++) {
+            if (this.textures[i] !== null)
+                gl.deleteTexture(this.textures[i]);
+            if (this.framebuffers[i] !== null)
+                gl.deleteFramebuffer(this.framebuffers[i]);
+            this.textures[i] = null;
+            this.framebuffers[i] = null;
+        }
+        gl.deleteProgram(this.program);
+        gl.deleteVertexArray(this.vao);
+        this.width = 0;
+        this.height = 0;
+    }
+}

package/dist/render/textLayout.d.ts

@@ -0,0 +1,88 @@
+import type { Vec3 } from '../math/color.ts';
+/**
+ * Where a string becomes cells, for both backends.
+ *
+ * **Nothing here names a device.** Laying a message out is arithmetic over the pixel font —
+ * which cells are lit, how wide the result is, which character each cell belongs to for the
+ * arrival stagger — and it produced the same two arrays whichever API was going to upload
+ * them. Keeping it in the WebGL2 class meant a second backend would have had to reimplement
+ * it, and the rule this repository learned the hard way is that anything both backends decide
+ * lives in one module and is bound twice. `waterGrid.ts` and `plumeGeometry.ts` are the same
+ * shape.
+ *
+ * A backend owns the buffers and the pipeline; this owns what goes in them.
+ */
+/**
+ * How many cells one text object may hold.
+ *
+ * Sized for a long notification rather than a paragraph — this is a display face for short
+ * shouted strings, and anything approaching a sentence should be DOM text, which is what a
+ * screen reader can read and a translator can translate.
+ */
+export declare const MAX_CELLS = 900;
+export interface TextStyle {
+    /** Pixels per cell. A 5x7 glyph is 5x and 7x this. */
+    readonly cellSize: number;
+    readonly color: Vec3;
+    /** Self-illumination, 0 for matte and ~1 for something that reads as lit. */
+    readonly glow: number;
+    readonly alpha: number;
+    /** 0 to 1 through the arrival animation. */
+    readonly reveal: number;
+    /** Radians of entry spin. Zero for text that should not tumble in. */
+    readonly spin: number;
+    /** Extra scale at the moment of arrival. */
+    readonly punch: number;
+    /** Idle vertical bob, in pixels. */
+    readonly bob: number;
+    /**
+     * Where this piece sits in a longer line, for the arrival stagger.
+     *
+     * Only needed when one line is drawn as several objects — words around a keycap. Left at
+     * the defaults, a piece staggers across itself, which is right for a line drawn in one go.
+     */
+    readonly charOffset?: number;
+    readonly charSpan?: number;
+}
+export declare const DEFAULT_TEXT_STYLE: TextStyle;
+/** Width of a string in pixels at a given cell size, without laying it out. */
+export declare function textWidthPx(text: string, cellSize: number): number;
+export declare function textHeightPx(cellSize: number): number;
+export declare class TextLayout {
+    /** Reused every upload; text changes far too often to allocate per change. */
+    readonly cells: Float32Array<ArrayBuffer>;
+    readonly chars: Float32Array<ArrayBuffer>;
+    instanceCount: number;
+    /** Characters in the current content, for the per-character stagger. */
+    charCount: number;
+    private lastKey;
+    private widthCells;
+    /** Width of the last laid-out string, in pixels at a given cell size. */
+    widthPx(cellSize: number): number;
+    /**
+     * Lay a string out, and say whether anything moved.
+     *
+     * **The return value is the whole point of the skip.** Most frames show the same message as
+     * the frame before, and re-uploading a buffer to say so is the sort of cost that only shows
+     * up on a phone. The arrays are reused in place, so a caller has no other way to tell.
+     */
+    setText(text: string): boolean;
+    /**
+     * A solid rectangle of cells, for a keycap or a backing plate.
+     *
+     * Not text. A run of block glyphs looks like the same thing and is not: glyphs are spaced a
+     * cell apart, so the "plate" comes out striped and sized in whole glyph widths rather than
+     * in cells — which is exactly how the first keycap ended up wider than the word it was
+     * behind.
+     *
+     * `bottomCell` is where the rectangle starts vertically, in the same baseline-relative cells
+     * the glyphs use, so -1 gives a cell of padding below.
+     */
+    setPlate(widthCells: number, heightCells: number, bottomCell: number): boolean;
+}
+/** Unit cube, as position/normal pairs. Two triangles per face. Built once, shared by both. */
+export declare const TEXT_CUBE: {
+    positions: Float32Array;
+    normals: Float32Array;
+    vertexCount: number;
+};