vgpu-render 0.0.0-stage → 0.2.0

package/dist/text-msdf-font.js

@@ -0,0 +1,159 @@
+/**
+ * Outline-backed glyph source, using `opentype.js` to read the bundled TrueType face.
+ *
+ * Canvas2D can only hand back a coverage mask, and a mask has lost the edges that a multi-channel
+ * distance field is built from. Outlines are where those edges still exist, so this source parses
+ * the inlined subset and encodes each glyph with `msdfFromOutline`.
+ *
+ * It is the on-demand counterpart to a prebaked atlas: it works for any character the face covers
+ * and any face at all, at the cost of running the encoder on the first frame each glyph appears.
+ * Coordinates follow the Canvas2D convention the rest of the text stack uses — x to the right, y
+ * down, the pen at (0, 0) and the baseline at y = 0 — which is also what `glyph.getPath` produces.
+ */
+import * as opentype from "opentype.js";
+import { decodeEmbeddedTrueTypeFont } from "./text-font.js";
+import { msdfFromOutline } from "./text-msdf.js";
+import { DEFAULT_SDF_RANGE } from "./text-sdf.js";
+/** Turns a path's command list into outline segments, offset so the ink box starts at the origin. */
+export function commandsToSegments(commands, offsetX, offsetY) {
+    const segments = [];
+    let current;
+    let subpathStart;
+    for (const command of commands) {
+        const to = command.type === "Z" ? undefined : [command.x - offsetX, command.y - offsetY];
+        switch (command.type) {
+            case "M":
+                current = to;
+                subpathStart = to;
+                break;
+            case "L":
+                if (current !== undefined && to !== undefined)
+                    segments.push({ from: current, to });
+                current = to;
+                break;
+            case "Q":
+                if (current !== undefined && to !== undefined) {
+                    segments.push({ from: current, control1: [command.x1 - offsetX, command.y1 - offsetY], to });
+                }
+                current = to;
+                break;
+            case "C":
+                if (current !== undefined && to !== undefined) {
+                    segments.push({
+                        from: current,
+                        control1: [command.x1 - offsetX, command.y1 - offsetY],
+                        control2: [command.x2 - offsetX, command.y2 - offsetY],
+                        to,
+                    });
+                }
+                current = to;
+                break;
+            case "Z":
+                // An explicit closing edge only if the contour did not already return to its start.
+                if (current !== undefined && subpathStart !== undefined) {
+                    const [cx, cy] = current;
+                    const [sx, sy] = subpathStart;
+                    if (cx !== sx || cy !== sy)
+                        segments.push({ from: current, to: subpathStart });
+                    current = subpathStart;
+                }
+                break;
+        }
+    }
+    return segments;
+}
+/**
+ * Resolves `parse` from either build of `opentype.js`.
+ *
+ * The package ships a CommonJS entry and an ESM entry without an `exports` map, so Node's ESM
+ * loader only exposes the CommonJS default export while bundlers pick the ESM module and its named
+ * exports. Reading whichever shape we were handed keeps both paths working.
+ */
+const parseFont = (opentype.parse ??
+    opentype.default.parse);
+export class OutlineGlyphRasterizer {
+    encoding = "msdf";
+    distanceRange;
+    rasterScale;
+    /** Whether the renderer drives this source's raster per block. See `dynamicRaster` in the options. */
+    dynamicRaster;
+    #font;
+    #metrics = new Map();
+    #vertical = new Map();
+    constructor(options = {}) {
+        this.#font = parseFont(options.font ?? decodeEmbeddedTrueTypeFont().buffer);
+        this.distanceRange = options.distanceRange ?? DEFAULT_SDF_RANGE;
+        this.rasterScale = options.rasterScale ?? 1;
+        this.dynamicRaster = options.dynamicRaster ?? true;
+    }
+    /** The face this source reads, for callers that want to name it. */
+    get font() {
+        return this.#font;
+    }
+    #scale(fontSize) {
+        return fontSize / this.#font.unitsPerEm;
+    }
+    /** Ink box of one character at `fontSize`, in the pen's own coordinates. */
+    #inkBox(character, fontSize) {
+        const path = this.#font.charToGlyph(character).getPath(0, 0, fontSize);
+        if (path.commands.length === 0)
+            return { left: 0, top: 0, width: 0, height: 0 };
+        const box = path.getBoundingBox();
+        const left = Number.isFinite(box.x1) ? box.x1 : 0;
+        const top = Number.isFinite(box.y1) ? box.y1 : 0;
+        const right = Number.isFinite(box.x2) ? box.x2 : left;
+        const bottom = Number.isFinite(box.y2) ? box.y2 : top;
+        return { left, top, width: Math.max(0, right - left), height: Math.max(0, bottom - top) };
+    }
+    /**
+     * This source holds one parsed buffer, so a weight, width or slant it was not built with cannot
+     * change the outlines it returns. Keying on the family alone keeps the atlas from caching the same
+     * glyph once per axis value.
+     */
+    faceKey = (face) => face.family;
+    verticalMetrics(_face, fontSize) {
+        const cached = this.#vertical.get(String(fontSize));
+        if (cached !== undefined)
+            return cached;
+        const scale = this.#scale(fontSize);
+        const value = { ascent: this.#font.ascender * scale, descent: -this.#font.descender * scale };
+        this.#vertical.set(String(fontSize), value);
+        return value;
+    }
+    glyphMetrics(character, _face, fontSize) {
+        const key = `${fontSize}|${character}`;
+        const cached = this.#metrics.get(key);
+        if (cached !== undefined)
+            return cached;
+        const ink = this.#inkBox(character, fontSize);
+        const advance = (this.#font.charToGlyph(character).advanceWidth ?? 0) * this.#scale(fontSize);
+        const value = {
+            advance,
+            width: ink.width,
+            height: ink.height,
+            bearingLeft: ink.left,
+            bearingTop: ink.top,
+        };
+        this.#metrics.set(key, value);
+        return value;
+    }
+    rasterize(character, _face, rasterSize) {
+        const ink = this.#inkBox(character, rasterSize);
+        if (!(ink.width > 0) || !(ink.height > 0))
+            return undefined;
+        const width = Math.max(1, Math.ceil(ink.width));
+        const height = Math.max(1, Math.ceil(ink.height));
+        const path = this.#font.charToGlyph(character).getPath(0, 0, rasterSize);
+        const segments = commandsToSegments(path.commands, ink.left, ink.top);
+        return {
+            width,
+            height,
+            texels: msdfFromOutline(segments, width, height, this.distanceRange),
+            inkWidth: ink.width,
+            inkHeight: ink.height,
+            bearingLeft: ink.left,
+            bearingTop: ink.top,
+            advance: (this.#font.charToGlyph(character).advanceWidth ?? 0) * this.#scale(rasterSize),
+        };
+    }
+}

package/dist/text-msdf.d.ts

@@ -0,0 +1,70 @@
+/**
+ * Multi-channel signed distance field generation from glyph outlines.
+ *
+ * A single distance channel stores one number per texel: how far the nearest edge is. That is
+ * enough everywhere except near a corner, where two edges meet and the single value can only
+ * describe one of them, so the corner rounds off when it is rebuilt. MSDF stores a distance per
+ * *edge group* instead — three of them, in RGB — and the shader takes the median. At a corner the
+ * three channels disagree and the median keeps the one that is still nearly correct, which is what
+ * preserves the point.
+ *
+ * Curves are chopped into short straight pieces before distances are measured: exact distances to a
+ * bezier would need a numerical solve per texel, while a chord error under half a texel is invisible
+ * at the sizes this is used at. Edge group assignment follows msdfgen's rule of thumb — adjacent
+ * edges that run nearly straight through their shared vertex keep the same group, everything else
+ * advances around a three-colour wheel.
+ *
+ * The median only equals the distance to the *nearest* edge where at least two channels are
+ * saturated. Inside a stroke that sees two or three edges it resolves to the middle distance
+ * instead, and the rebuilt edge drifts by up to half a texel: measured against a super-sampled
+ * coverage reference at 24 px, the raw field is off by 0.073 (mean) and 0.513 (worst texel) in alpha
+ * units. msdfgen handles that with an error-correction pass after generating the field, whose
+ * flagship form equalises every flagged texel to its own median. That was measured here too and it
+ * made the reconstruction *worse* (0.078), because this encoder gives every channel the texel's own
+ * inside/outside sign rather than a per-edge signed distance, so the channels differ only in which
+ * edge is nearest and equalising them flattens the gradient the filter relies on.
+ *
+ * What does help is correcting the median itself against the exact shape distance: only the channel
+ * or channels needed to make that distance the middle value move, so the other channel keeps its
+ * gradient. The same measurement drops to 0.043, against 0.040 for a field whose whole edge band is
+ * made exactly right — the remainder is the resolution limit of one distance per texel plus linear
+ * filtering, not something another pass can recover.
+ *
+ * Alpha is not part of the median: it keeps the same exact shape distance uncorrected, which is what
+ * an outline of uniform width needs and what the median cannot provide at a corner.
+ */
+export type Point = readonly [number, number];
+/** One outline segment: a straight line, or a curve carrying its control points. */
+export type OutlineSegment = {
+    readonly from: Point;
+    readonly control1?: Point;
+    readonly control2?: Point;
+    readonly to: Point;
+};
+type ColoredLine = {
+    readonly from: Point;
+    readonly to: Point;
+    readonly channel: 0 | 1 | 2;
+};
+/**
+ * Assigns each segment to one of three channels. Segments that continue the same edge share a
+ * channel; a join that actually turns the outline advances to the next one, so the three edges of a
+ * corner end up on three different channels.
+ */
+export declare function colorOutlineEdges(segments: readonly OutlineSegment[]): Uint8Array;
+/** Chops curves into straight pieces, each inheriting its parent's channel. */
+export declare function flattenOutline(segments: readonly OutlineSegment[], channels: Uint8Array, steps?: number): readonly ColoredLine[];
+/**
+ * Renders one glyph outline into an RGBA8 distance field.
+ *
+ * Each channel holds the signed distance to the nearest edge in its group, averaged over the texel
+ * centre, and encoded as `distance / (2 × range) + 0.5` so 128 is the edge. Channels no edge was
+ * assigned to saturate, because a median over two real distances and one saturated value still
+ * resolves to a real edge. Alpha carries the *true* distance to the shape, which is msdfgen's
+ * `mtsdf` layout: the median in RGB preserves the corners a single channel rounds off, while a
+ * uniform-width outline reads alpha, because a per-edge median dents exactly at a corner. The field
+ * is then corrected against the exact shape distance — see the error-correction note at the top of
+ * this file.
+ */
+export declare function msdfFromOutline(segments: readonly OutlineSegment[], width: number, height: number, range: number, steps?: number): Uint8Array;
+export {};

package/dist/text-msdf.js

@@ -0,0 +1,242 @@
+/**
+ * Multi-channel signed distance field generation from glyph outlines.
+ *
+ * A single distance channel stores one number per texel: how far the nearest edge is. That is
+ * enough everywhere except near a corner, where two edges meet and the single value can only
+ * describe one of them, so the corner rounds off when it is rebuilt. MSDF stores a distance per
+ * *edge group* instead — three of them, in RGB — and the shader takes the median. At a corner the
+ * three channels disagree and the median keeps the one that is still nearly correct, which is what
+ * preserves the point.
+ *
+ * Curves are chopped into short straight pieces before distances are measured: exact distances to a
+ * bezier would need a numerical solve per texel, while a chord error under half a texel is invisible
+ * at the sizes this is used at. Edge group assignment follows msdfgen's rule of thumb — adjacent
+ * edges that run nearly straight through their shared vertex keep the same group, everything else
+ * advances around a three-colour wheel.
+ *
+ * The median only equals the distance to the *nearest* edge where at least two channels are
+ * saturated. Inside a stroke that sees two or three edges it resolves to the middle distance
+ * instead, and the rebuilt edge drifts by up to half a texel: measured against a super-sampled
+ * coverage reference at 24 px, the raw field is off by 0.073 (mean) and 0.513 (worst texel) in alpha
+ * units. msdfgen handles that with an error-correction pass after generating the field, whose
+ * flagship form equalises every flagged texel to its own median. That was measured here too and it
+ * made the reconstruction *worse* (0.078), because this encoder gives every channel the texel's own
+ * inside/outside sign rather than a per-edge signed distance, so the channels differ only in which
+ * edge is nearest and equalising them flattens the gradient the filter relies on.
+ *
+ * What does help is correcting the median itself against the exact shape distance: only the channel
+ * or channels needed to make that distance the middle value move, so the other channel keeps its
+ * gradient. The same measurement drops to 0.043, against 0.040 for a field whose whole edge band is
+ * made exactly right — the remainder is the resolution limit of one distance per texel plus linear
+ * filtering, not something another pass can recover.
+ *
+ * Alpha is not part of the median: it keeps the same exact shape distance uncorrected, which is what
+ * an outline of uniform width needs and what the median cannot provide at a corner.
+ */
+/** Straight pieces a curve is chopped into. Eight keeps the chord error well under a texel. */
+const CURVE_STEPS = 8;
+/** Directions closer than this count as one continuous edge, so they share a channel. */
+const COLLINEAR_COSINE = 0.9986;
+function unit(dx, dy) {
+    const length = Math.hypot(dx, dy);
+    return length === 0 ? [0, 0] : [dx / length, dy / length];
+}
+/** Tangent leaving a segment's start, which is where its colour has to agree with the previous one. */
+function outgoingDirection(segment) {
+    const reference = segment.control1 ?? segment.to;
+    return unit(reference[0] - segment.from[0], reference[1] - segment.from[1]);
+}
+/** Tangent arriving at a segment's end, the other half of the join test. */
+function incomingDirection(segment) {
+    const reference = segment.control2 ?? segment.control1 ?? segment.from;
+    return unit(segment.to[0] - reference[0], segment.to[1] - reference[1]);
+}
+function continuesEdge(previous, next) {
+    const incoming = incomingDirection(previous);
+    const outgoing = outgoingDirection(next);
+    return incoming[0] * outgoing[0] + incoming[1] * outgoing[1] >= COLLINEAR_COSINE;
+}
+/**
+ * Assigns each segment to one of three channels. Segments that continue the same edge share a
+ * channel; a join that actually turns the outline advances to the next one, so the three edges of a
+ * corner end up on three different channels.
+ */
+export function colorOutlineEdges(segments) {
+    const channels = new Uint8Array(segments.length);
+    let channel = 0;
+    for (let index = 0; index < segments.length; index++) {
+        if (index > 0 && !continuesEdge(segments[index - 1], segments[index]))
+            channel = (channel + 1) % 3;
+        channels[index] = channel;
+    }
+    return channels;
+}
+function evaluate(segment, t) {
+    const { from, to, control1, control2 } = segment;
+    const u = 1 - t;
+    if (control1 === undefined)
+        return to;
+    if (control2 === undefined) {
+        return [
+            u * u * from[0] + 2 * u * t * control1[0] + t * t * to[0],
+            u * u * from[1] + 2 * u * t * control1[1] + t * t * to[1],
+        ];
+    }
+    return [
+        u * u * u * from[0] + 3 * u * u * t * control1[0] + 3 * u * t * t * control2[0] + t * t * t * to[0],
+        u * u * u * from[1] + 3 * u * u * t * control1[1] + 3 * u * t * t * control2[1] + t * t * t * to[1],
+    ];
+}
+/** Chops curves into straight pieces, each inheriting its parent's channel. */
+export function flattenOutline(segments, channels, steps = CURVE_STEPS) {
+    const lines = [];
+    for (let index = 0; index < segments.length; index++) {
+        const segment = segments[index];
+        const channel = ((channels[index] ?? 0) % 3);
+        if (segment.control1 === undefined) {
+            lines.push({ from: segment.from, to: segment.to, channel });
+            continue;
+        }
+        for (let step = 0; step < steps; step++) {
+            lines.push({ from: evaluate(segment, step / steps), to: evaluate(segment, (step + 1) / steps), channel });
+        }
+    }
+    return lines;
+}
+/** Even-odd containment: a horizontal ray from the point, counting crossings to its right. */
+function isInside(px, py, lines) {
+    let inside = false;
+    for (const line of lines) {
+        const [ax, ay] = line.from;
+        const [bx, by] = line.to;
+        if (ay > py !== by > py) {
+            const crossing = ax + ((py - ay) / (by - ay)) * (bx - ax);
+            if (px < crossing)
+                inside = !inside;
+        }
+    }
+    return inside;
+}
+function distanceToLine(px, py, line) {
+    const [ax, ay] = line.from;
+    const [bx, by] = line.to;
+    const dx = bx - ax;
+    const dy = by - ay;
+    const lengthSquared = dx * dx + dy * dy;
+    if (lengthSquared === 0)
+        return Math.hypot(px - ax, py - ay);
+    const projected = ((px - ax) * dx + (py - ay) * dy) / lengthSquared;
+    const t = projected < 0 ? 0 : projected > 1 ? 1 : projected;
+    return Math.hypot(px - (ax + t * dx), py - (ay + t * dy));
+}
+/** Encodes one distance as `distance / (2 × range) + 0.5`, saturated to an 8-bit channel. */
+function encodeDistance(value, range) {
+    const encoded = Math.round((value / (2 * range) + 0.5) * 255);
+    return encoded < 0 ? 0 : encoded > 255 ? 255 : encoded;
+}
+/** Indices of three channel values in ascending order. */
+function ascending(values) {
+    const order = [0, 1, 2];
+    if (values[order[0]] > values[order[1]])
+        [order[0], order[1]] = [order[1], order[0]];
+    if (values[order[1]] > values[order[2]])
+        [order[1], order[2]] = [order[2], order[1]];
+    if (values[order[0]] > values[order[1]])
+        [order[0], order[1]] = [order[1], order[0]];
+    return order;
+}
+/**
+ * How far a texel's median may sit from the exact shape distance before it is corrected, in texels.
+ * Half a texel is the point where the reconstruction visibly shifts the edge.
+ */
+const CORRECTION_TOLERANCE = 0.5;
+/**
+ * Moves each texel's median onto the exact shape distance, in place.
+ *
+ * Only the channel or channels required to make that distance the middle value are written; the
+ * remaining channel keeps its own gradient, which is what stops a magnified edge from flattening
+ * across the corrected texel. Beyond the encoded band nothing is touched: there the coverage ramp
+ * is already saturated, so the median's exact value cannot move a pixel.
+ */
+function correctMedians(texels, distances, range) {
+    const tolerance = (CORRECTION_TOLERANCE / (2 * range)) * 255;
+    for (let index = 0; index < distances.length; index++) {
+        const shape = distances[index];
+        if (!(Math.abs(shape) <= range))
+            continue;
+        const base = index * 4;
+        const red = texels[base];
+        const green = texels[base + 1];
+        const blue = texels[base + 2];
+        const order = ascending([red, green, blue]);
+        const values = [red, green, blue];
+        const lowest = values[order[0]];
+        const median = values[order[1]];
+        const highest = values[order[2]];
+        const target = encodeDistance(shape, range);
+        if (Math.abs(median - target) <= tolerance)
+            continue;
+        if (target < median) {
+            // Lower the highest channel. Once the target is at or below the lowest one, that channel has
+            // to move as well, or it would become the new median instead.
+            texels[base + order[2]] = target;
+            if (target <= lowest)
+                texels[base + order[0]] = target;
+        }
+        else {
+            texels[base + order[0]] = target;
+            if (target >= highest)
+                texels[base + order[2]] = target;
+        }
+    }
+}
+/**
+ * Renders one glyph outline into an RGBA8 distance field.
+ *
+ * Each channel holds the signed distance to the nearest edge in its group, averaged over the texel
+ * centre, and encoded as `distance / (2 × range) + 0.5` so 128 is the edge. Channels no edge was
+ * assigned to saturate, because a median over two real distances and one saturated value still
+ * resolves to a real edge. Alpha carries the *true* distance to the shape, which is msdfgen's
+ * `mtsdf` layout: the median in RGB preserves the corners a single channel rounds off, while a
+ * uniform-width outline reads alpha, because a per-edge median dents exactly at a corner. The field
+ * is then corrected against the exact shape distance — see the error-correction note at the top of
+ * this file.
+ */
+export function msdfFromOutline(segments, width, height, range, steps = CURVE_STEPS) {
+    if (!(range > 0))
+        throw new RangeError("msdf range must be greater than zero");
+    const lines = flattenOutline(segments, colorOutlineEdges(segments), steps);
+    const texels = new Uint8Array(width * height * 4);
+    const distances = new Float64Array(width * height);
+    for (let y = 0; y < height; y++) {
+        for (let x = 0; x < width; x++) {
+            const px = x + 0.5;
+            const py = y + 0.5;
+            const inside = isInside(px, py, lines);
+            const nearest = [Number.POSITIVE_INFINITY, Number.POSITIVE_INFINITY, Number.POSITIVE_INFINITY];
+            const signed = [0, 0, 0];
+            let shapeDistance = Number.POSITIVE_INFINITY;
+            for (const line of lines) {
+                const distance = distanceToLine(px, py, line);
+                if (distance < shapeDistance)
+                    shapeDistance = distance;
+                if (distance < nearest[line.channel]) {
+                    nearest[line.channel] = distance;
+                    signed[line.channel] = inside ? distance : -distance;
+                }
+            }
+            const index = y * width + x;
+            const target = index * 4;
+            for (let channel = 0; channel < 3; channel++) {
+                const value = nearest[channel] === Number.POSITIVE_INFINITY ? (inside ? range : -range) : signed[channel];
+                texels[target + channel] = encodeDistance(value, range);
+            }
+            const shape = inside ? shapeDistance : -shapeDistance;
+            // Alpha holds the true distance, so the shader can draw an outline that keeps its width.
+            texels[target + 3] = encodeDistance(shape, range);
+            distances[index] = shape;
+        }
+    }
+    correctMedians(texels, distances, range);
+    return texels;
+}

package/dist/text-raster.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Raster-size selection for the on-demand glyph atlas.
+ *
+ * reference keys a `FontAtlas` by font size and rasterises each size at the physical pixel size it will be
+ * drawn at, so every font size comes out sharp and every font size pays for its own atlas. A debug
+ * draw frame cannot afford that shape: its text changes size continuously (a world block follows the
+ * camera) and a CJK glyph set is large, so one atlas per size would re-rasterise the same character
+ * over and over and grow without any eviction.
+ *
+ * The fix is the one browsers use for their glyph cache: rasterise at the *screen* size the glyph
+ * will occupy, quantised onto a fixed ladder of sizes. A size between two rungs takes the rung above
+ * it — at most `step`× oversampled, which the mip chain covers when the block is drawn smaller — so
+ * the glyphs the atlas holds stay bounded while the size keeps moving.
+ */
+/** Ratio between neighbouring rungs. 1.25 keeps the worst-case oversampling at a quarter of a texel. */
+export declare const DEFAULT_RASTER_STEP = 1.25;
+/** Smallest and largest raster rungs, in texels along the font size. Below `MIN_RASTER_PX` a stem is
+ * thinner than a texel; above `MAX_RASTER_PX` a glyph costs more atlas area than it can pay for. */
+export declare const MIN_RASTER_PX = 6;
+export declare const MAX_RASTER_PX = 256;
+/**
+ * The smallest raster size on the ladder that covers `screenPx`.
+ *
+ * Rounding up rather than to the nearest rung is what keeps the atlas an upper bound on what the
+ * screen asks for: a glyph is never magnified when it is decoded, only minified through the mip
+ * chain, which is the direction that still looks sharp.
+ */
+export declare function quantizeRasterPx(screenPx: number, step?: number, min?: number, max?: number): number;
+/** The raster scale a glyph of `fontSize` layout pixels needs in order to land on `rasterPx` texels. */
+export declare function rasterScaleFor(rasterPx: number, fontSize: number): number;
+/**
+ * Screen pixels one world unit covers at `point`, for the perspective and orthographic matrices the
+ * camera writes.
+ *
+ * This is the same estimate the world-width shaders use (`viewProjection[1][1] * viewportSize.y *
+ * 0.5 / clip.w`), so a raster size picked here agrees with the width the shaders compute for the
+ * block. It ignores how the block's own plane is angled to the camera, which only matters for the
+ * rung chosen; `quantizeRasterPx` absorbs a miss of one rung by oversampling.
+ */
+export declare function screenPixelsPerWorldUnit(viewProjection: ArrayLike<number>, point: readonly [number, number, number], viewportHeight: number): number;

package/dist/text-raster.js

@@ -0,0 +1,60 @@
+/**
+ * Raster-size selection for the on-demand glyph atlas.
+ *
+ * reference keys a `FontAtlas` by font size and rasterises each size at the physical pixel size it will be
+ * drawn at, so every font size comes out sharp and every font size pays for its own atlas. A debug
+ * draw frame cannot afford that shape: its text changes size continuously (a world block follows the
+ * camera) and a CJK glyph set is large, so one atlas per size would re-rasterise the same character
+ * over and over and grow without any eviction.
+ *
+ * The fix is the one browsers use for their glyph cache: rasterise at the *screen* size the glyph
+ * will occupy, quantised onto a fixed ladder of sizes. A size between two rungs takes the rung above
+ * it — at most `step`× oversampled, which the mip chain covers when the block is drawn smaller — so
+ * the glyphs the atlas holds stay bounded while the size keeps moving.
+ */
+/** Ratio between neighbouring rungs. 1.25 keeps the worst-case oversampling at a quarter of a texel. */
+export const DEFAULT_RASTER_STEP = 1.25;
+/** Smallest and largest raster rungs, in texels along the font size. Below `MIN_RASTER_PX` a stem is
+ * thinner than a texel; above `MAX_RASTER_PX` a glyph costs more atlas area than it can pay for. */
+export const MIN_RASTER_PX = 6;
+export const MAX_RASTER_PX = 256;
+/**
+ * The smallest raster size on the ladder that covers `screenPx`.
+ *
+ * Rounding up rather than to the nearest rung is what keeps the atlas an upper bound on what the
+ * screen asks for: a glyph is never magnified when it is decoded, only minified through the mip
+ * chain, which is the direction that still looks sharp.
+ */
+export function quantizeRasterPx(screenPx, step = DEFAULT_RASTER_STEP, min = MIN_RASTER_PX, max = MAX_RASTER_PX) {
+    if (Number.isNaN(screenPx) || !(screenPx > min))
+        return min;
+    if (screenPx >= max)
+        return max;
+    if (!(step > 1))
+        return Math.min(max, Math.ceil(screenPx));
+    const exponent = Math.ceil(Math.log(screenPx / min) / Math.log(step));
+    return Math.min(max, Math.max(min, Math.ceil(min * Math.pow(step, exponent))));
+}
+/** The raster scale a glyph of `fontSize` layout pixels needs in order to land on `rasterPx` texels. */
+export function rasterScaleFor(rasterPx, fontSize) {
+    return fontSize > 0 ? rasterPx / fontSize : 1;
+}
+/**
+ * Screen pixels one world unit covers at `point`, for the perspective and orthographic matrices the
+ * camera writes.
+ *
+ * This is the same estimate the world-width shaders use (`viewProjection[1][1] * viewportSize.y *
+ * 0.5 / clip.w`), so a raster size picked here agrees with the width the shaders compute for the
+ * block. It ignores how the block's own plane is angled to the camera, which only matters for the
+ * rung chosen; `quantizeRasterPx` absorbs a miss of one rung by oversampling.
+ */
+export function screenPixelsPerWorldUnit(viewProjection, point, viewportHeight) {
+    const [x, y, z] = point;
+    const clipW = viewProjection[3] * x + viewProjection[7] * y + viewProjection[11] * z + viewProjection[15];
+    // Behind or on the near plane the projection has no finite scale; fall back to one pixel per unit
+    // rather than returning a value that would send the raster ladder to its top rung.
+    if (!(clipW > 1e-4))
+        return 1;
+    const scale = Math.abs(viewProjection[5]) * viewportHeight * 0.5 / clipW;
+    return Number.isFinite(scale) && scale > 0 ? scale : 1;
+}

package/dist/text-sdf.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Signed distance field generation for the glyph atlas.
+ *
+ * Canvas2D hands back an anti-aliased coverage mask, which is enough for the bitmap path but
+ * cannot be rescaled: a texel says "80% ink", not "the edge is 0.3 px that way". A distance field
+ * stores the latter, so the fragment stage can rebuild the edge at whatever magnification the
+ * camera asks for instead of interpolating coverage between texels.
+ *
+ * The mask is binarised, an exact Euclidean distance transform (Felzenszwalb & Huttenlocher, 2012)
+ * gives the distance to the opposite side away from the edge, and partially covered texels override
+ * that with the sub-texel offset their own coverage implies — the coverage carries the detail a
+ * binary transform would throw away.
+ *
+ * Values are stored as `distance / (2 × range) + 0.5`, so 128 is the edge, and the field saturates
+ * `range` texels either side. `range` is small on purpose: only the neighbourhood of the edge is
+ * ever resampled, and a smaller range spends the 8 available bits on a narrower band.
+ */
+/** Distance in atlas texels that one side of the encoded range covers. */
+export declare const DEFAULT_SDF_RANGE = 4;
+/**
+ * Turns one glyph's coverage mask into an 8-bit distance field, one byte per texel.
+ *
+ * Positive means inside the glyph. Wholly covered and wholly empty texels take their distance from
+ * the transform; partially covered ones use `coverage - 0.5` instead, which is the sub-texel edge
+ * offset for a straight edge crossing that texel and is what keeps the field smooth across the
+ * boundary rather than quantised to whole texels.
+ */
+export declare function coverageToSdf(coverage: Uint8Array, width: number, height: number, range?: number): Uint8Array;