vgpu-render 0.0.0-stage → 0.2.0

package/dist/text-layout.js

@@ -0,0 +1,390 @@
+/**
+ * Text layout for the debug text renderer.
+ *
+ * Ported from reference `TextPipeline::update_text_layout_info`
+ * (`the reference implementation`): a text block is wrapped to its `TextBounds`, split
+ * into lines, justified, and turned into one positioned glyph per character. Each glyph
+ * carries its ink box and resolved colour, which is what the GPU pass later instantiates as
+ * a quad.
+ *
+ * Two deliberate differences from reference:
+ *
+ * - There is no shaping. Characters advance one at a time and never form ligatures or
+ *   reorder runs, which suits the monospaced debug font the library bundles.
+ * - Every metric comes from an injected `TextMeasurer`. reference reads parley and swash here;
+ *   staying behind an interface keeps this module free of browser APIs and unit-testable in
+ *   plain Node, and it is also the seam the GPU tests use to feed synthetic glyphs.
+ *
+ * Layout happens in one local space: origin at the block's anchor point, x to the right and
+ * **y down**, matching Canvas2D. The renderer flips y for spaces where up is +y.
+ */
+/** Every `FontWidth` stop, in reference order. */
+export const TEXT_FONT_WIDTHS = [
+    "ultra-condensed",
+    "extra-condensed",
+    "condensed",
+    "semi-condensed",
+    "normal",
+    "semi-expanded",
+    "expanded",
+    "extra-expanded",
+    "ultra-expanded",
+];
+/** Every `FontStyle` variant this implementation can honour. */
+export const TEXT_FONT_STYLES = ["normal", "italic"];
+/** reference `FontWeight::NORMAL`, and the value the CSS font shorthand defaults to. */
+export const DEFAULT_FONT_WEIGHT = 400;
+/** reference `FontWeight` range, 1 to 1000. */
+export const MIN_FONT_WEIGHT = 1;
+export const MAX_FONT_WEIGHT = 1000;
+/** Folds a face's optional axes into the complete request the measurer and the atlas take. */
+export function resolveFontFace(options) {
+    return {
+        family: options.family,
+        weight: options.weight ?? DEFAULT_FONT_WEIGHT,
+        style: options.style ?? "normal",
+        width: options.width ?? "normal",
+    };
+}
+/** Every field that can change which glyphs are rasterised, joined into one cache key. */
+export function fontFaceKey(face) {
+    return `${face.family}|${face.weight}|${face.width}|${face.style}`;
+}
+const TEXT_ANCHORS = {
+    center: [0.5, 0.5],
+    "top-left": [0, 0],
+    "top-center": [0.5, 0],
+    "top-right": [1, 0],
+    "center-left": [0, 0.5],
+    "center-right": [1, 0.5],
+    "bottom-left": [0, 1],
+    "bottom-center": [0.5, 1],
+    "bottom-right": [1, 1],
+};
+export function resolveTextAnchor(anchor) {
+    const point = TEXT_ANCHORS[anchor];
+    if (point === undefined) {
+        throw new RangeError(`unknown text anchor "${anchor}"`);
+    }
+    return point;
+}
+/** reference `LineHeight` default, `RelativeToFont(1.2)`. */
+export const DEFAULT_LINE_HEIGHT_SCALE = 1.2;
+function isWhitespace(character) {
+    return character === " " || character === "\t";
+}
+/**
+ * Characters that break between themselves rather than at spaces.
+ *
+ * UAX #14 calls these classes ID (ideographic) and the punctuation around them. Without this a whole
+ * Chinese sentence arrives as one word token, so `word` breaking can only move it as a block and a
+ * bounded block overflows its bounds instead of wrapping.
+ */
+function isCjkCharacter(character) {
+    const code = character.codePointAt(0) ?? 0;
+    return ((code >= 0x2e80 && code <= 0x303f) || // CJK radicals, symbols and punctuation
+        (code >= 0x3040 && code <= 0x30ff) || // hiragana, katakana
+        (code >= 0x3400 && code <= 0x4dbf) || // CJK unified ideographs extension A
+        (code >= 0x4e00 && code <= 0x9fff) || // CJK unified ideographs
+        (code >= 0xf900 && code <= 0xfaff) || // CJK compatibility ideographs
+        (code >= 0xff00 && code <= 0xffef) || // full-width forms
+        (code >= 0xac00 && code <= 0xd7af) || // hangul syllables
+        (code >= 0x20000 && code <= 0x3ffff) // extensions B and beyond
+    );
+}
+/**
+ * Kinsoku (禁则) sets: punctuation that may not open a line, and brackets that may not close one.
+ *
+ * The line breaker only knows how to move a token, so the rule is expressed by gluing the character
+ * to its neighbour instead: a closing mark joins the run before it, an opening mark the run after.
+ */
+const NO_LINE_START = new Set([
+    ",", ".", "!", "?", ":", ";", ")", "]", "}", ".", ")", "]", "}", "%",
+    "\u3001", "\u3002", "\uff0c", "\uff0e", "\uff01", "\uff1f", "\uff1a", "\uff1b", "\uff09", "\uff3d", "\uff5d", "\uff05",
+    "\u300d", "\u300f", "\u3011", "\u300b", "\u3009", "\u3015", "\u2019", "\u201d",
+]);
+const NO_LINE_END = new Set(["(", "[", "{", "\uff08", "\uff3b", "\uff5b", "\u300c", "\u300e", "\u3010", "\u300a", "\u3008", "\u3014", "\u2018", "\u201c"]);
+/** Appends one character to the token that is already open, or starts a new one. */
+function glueToLastToken(tokens, character) {
+    const last = tokens[tokens.length - 1];
+    if (last === undefined || last.kind === "break") {
+        tokens.push({ kind: "word", characters: [character] });
+        return;
+    }
+    tokens[tokens.length - 1] = { kind: last.kind, characters: [...last.characters, character] };
+}
+/** Splits the flattened block into word / spaces / hard-break tokens. */
+function tokenize(items) {
+    const tokens = [];
+    let current = [];
+    let kind;
+    const flush = () => {
+        if (kind !== undefined && current.length > 0)
+            tokens.push({ kind, characters: current });
+        current = [];
+        kind = undefined;
+    };
+    for (const item of items) {
+        if (item.character === "\n") {
+            flush();
+            tokens.push({ kind: "break", characters: [] });
+            continue;
+        }
+        // CJK text carries no spaces to break at, so each ideograph becomes its own token and the greedy
+        // breaker can wrap between any two of them. Kinsoku is applied here rather than in the breaker
+        // because it can only move a whole token: a mark that may not open a line is glued to the run it
+        // belongs to, and one that may not close a line to the character that follows it.
+        if (!item.isSpace && isCjkCharacter(item.character)) {
+            const previous = current[current.length - 1] ?? tokens[tokens.length - 1]?.characters.at(-1);
+            const glue = previous !== undefined && (NO_LINE_START.has(item.character) || NO_LINE_END.has(previous.character));
+            if (glue) {
+                if (current.length > 0)
+                    current.push(item);
+                else
+                    glueToLastToken(tokens, item);
+                kind = "word";
+                continue;
+            }
+            flush();
+            tokens.push({ kind: "word", characters: [item] });
+            continue;
+        }
+        const next = item.isSpace ? "space" : "word";
+        if (kind !== undefined && next !== kind)
+            flush();
+        kind = next;
+        current.push(item);
+    }
+    flush();
+    return tokens;
+}
+/** Advance of a run. `letterSpacing` lands after every character, the last one included. */
+function runWidth(characters, letterSpacing) {
+    let width = 0;
+    for (const character of characters)
+        width += character.advance + letterSpacing;
+    return width;
+}
+/** Measures one broken line into the two advances and the line box size reference works from. */
+function measureLine(characters, letterSpacing) {
+    // UAX #14 never leaves a space at the start of a line, and the breakers reference runs drop it there.
+    let start = 0;
+    while (start < characters.length && characters[start].isSpace)
+        start++;
+    const content = start === 0 ? characters : characters.slice(start);
+    let end = content.length;
+    while (end > 0 && content[end - 1].isSpace)
+        end--;
+    let fontSize = 0;
+    let face;
+    // The line box follows the line's own largest run, so the face recorded here is that run's.
+    for (const character of content) {
+        if (character.fontSize > fontSize) {
+            fontSize = character.fontSize;
+            face = character.face;
+        }
+    }
+    return {
+        characters: content.slice(0, end),
+        advance: runWidth(content.slice(0, end), letterSpacing),
+        fullAdvance: runWidth(content, letterSpacing),
+        fontSize,
+        face,
+        isEmpty: content.length === 0,
+    };
+}
+/** Splits a word token one character at a time, the fallback for `word-or-character`. */
+function splitCharacters(token) {
+    return token.characters.map((character) => ({ kind: "word", characters: [character] }));
+}
+/**
+ * Greedy line breaker. Words move whole to the next line when they no longer fit, matching
+ * reference `LineBreak::WordBoundary`; `character` strategies hand single characters to the same
+ * loop, and `none` only honours explicit newlines.
+ */
+function breakLines(tokens, maxWidth, lineBreak, letterSpacing) {
+    const lines = [];
+    let line = [];
+    const pushLine = () => {
+        lines.push(line);
+        line = [];
+    };
+    const addCharacters = (characters) => {
+        for (const character of characters) {
+            if (maxWidth !== undefined && line.length > 0 && lineWidth(line, letterSpacing) + character.advance + letterSpacing > maxWidth) {
+                // The space a line breaks at stays on that line as trailing whitespace — it may even take the
+                // line past its bounds, which is why a bounded block can report a wider width. Carrying it to
+                // the next line instead would push the following characters right by one space.
+                if (character.isSpace)
+                    line.push(character);
+                lines.push(line);
+                line = [];
+                if (character.isSpace)
+                    continue;
+            }
+            line.push(character);
+        }
+    };
+    for (const token of tokens) {
+        if (token.kind === "break") {
+            pushLine();
+            continue;
+        }
+        if (maxWidth === undefined || lineBreak === "none") {
+            line.push(...token.characters);
+            continue;
+        }
+        if (lineBreak === "character") {
+            addCharacters(token.characters);
+            continue;
+        }
+        const width = lineWidth(line, letterSpacing) + runWidth(token.characters, letterSpacing);
+        const fits = width <= maxWidth || lineWidth(line, letterSpacing) === 0;
+        if (fits) {
+            line.push(...token.characters);
+            continue;
+        }
+        if (token.kind === "space") {
+            // A space that no longer fits ends the line and belongs to it, as the trailing whitespace
+            // parley keeps for its width even though it is not drawn.
+            line.push(...token.characters);
+            lines.push(line);
+            line = [];
+            continue;
+        }
+        // A word too wide for an empty line falls back to per-character breaking.
+        lines.push(line);
+        line = [];
+        const splittable = lineBreak === "word-or-character" || runWidth(token.characters, letterSpacing) > maxWidth;
+        if (splittable)
+            addCharacters(token.characters);
+        else
+            line.push(...token.characters);
+    }
+    pushLine();
+    return lines.map((characters) => measureLine(characters, letterSpacing));
+}
+function lineWidth(characters, letterSpacing) {
+    return runWidth(characters, letterSpacing);
+}
+function countSpaces(characters) {
+    let count = 0;
+    for (const character of characters)
+        if (character.isSpace)
+            count++;
+    return count;
+}
+/**
+ * Lays out one text block. `options.anchor` decides which part of the block lands on the
+ * position the renderer is given; the returned glyph centres are already offset for it.
+ */
+export function layoutText(spans, options, measurer) {
+    const items = [];
+    const blockFace = resolveFontFace({
+        family: options.fontFamily,
+        weight: options.weight,
+        style: options.style,
+        width: options.width,
+    });
+    for (const span of spans) {
+        const fontSize = span.fontSize ?? options.fontSize;
+        const face = resolveFontFace({
+            family: span.fontFamily ?? options.fontFamily,
+            weight: span.weight ?? options.weight,
+            style: span.style ?? options.style,
+            width: span.width ?? options.width,
+        });
+        const color = span.color ?? options.color;
+        // Iterating the string yields code points, so surrogate pairs stay whole.
+        for (const character of span.text) {
+            if (character === "\n") {
+                items.push({ character, face, fontSize, color, advance: 0, width: 0, height: 0, bearingLeft: 0, bearingTop: 0, isSpace: false });
+                continue;
+            }
+            const metrics = measurer.glyphMetrics(character, face, fontSize);
+            items.push({
+                character,
+                face,
+                fontSize,
+                color,
+                advance: metrics.advance,
+                width: metrics.width,
+                height: metrics.height,
+                bearingLeft: metrics.bearingLeft,
+                bearingTop: metrics.bearingTop,
+                isSpace: isWhitespace(character),
+            });
+        }
+    }
+    const maxWidth = options.bounds?.[0];
+    const lines = breakLines(tokenize(items), maxWidth, options.lineBreak, options.letterSpacing);
+    // reference resolves the line box per line, from that line's own largest run: a relative
+    // `LineHeight` multiplies the run's size, so a line holding a larger span grows its box
+    // instead of being held to the block's default size.
+    const boxes = lines.map((line) => {
+        const fontSize = line.fontSize > 0 ? line.fontSize : options.fontSize;
+        const base = measurer.verticalMetrics(line.face ?? blockFace, fontSize);
+        const height = options.lineHeight ?? (options.lineHeightScale ?? DEFAULT_LINE_HEIGHT_SCALE) * fontSize;
+        return { base, height, halfLeading: (height - (base.ascent + base.descent)) / 2 };
+    });
+    // The block is what reference reports and anchors on: `Layout::full_width`, which keeps the
+    // whitespace each line broke at, over the summed line boxes. Both are rounded up.
+    const blockWidth = Math.ceil(lines.reduce((widest, line) => Math.max(widest, line.fullAdvance), 0));
+    let blockHeight = boxes.reduce((sum, box) => sum + box.height, 0);
+    // parley leaves a trailing empty line's box out of the layout height.
+    if (lines.length > 1 && lines[lines.length - 1].isEmpty)
+        blockHeight -= boxes[boxes.length - 1].height;
+    blockHeight = Math.ceil(blockHeight);
+    const offsetX = -options.anchor[0] * blockWidth;
+    const offsetY = -options.anchor[1] * blockHeight;
+    // `Alignment` works inside parley's `max_advance`: the bounds width when bounded, otherwise the
+    // widest line. That is a smaller box than `full_width` whenever a line breaks at a space.
+    const alignBox = maxWidth ?? lines.reduce((widest, line) => Math.max(widest, line.advance), 0);
+    const glyphs = [];
+    let penY = 0;
+    for (let lineIndex = 0; lineIndex < lines.length; lineIndex++) {
+        const line = lines[lineIndex];
+        const box = boxes[lineIndex];
+        const isLastLine = lineIndex === lines.length - 1;
+        let penX = alignPenX(options.justify, line.advance, alignBox);
+        let stretch = 0;
+        if (options.justify === "justified" && !isLastLine && maxWidth !== undefined) {
+            const spaces = countSpaces(line.characters);
+            if (spaces > 0 && alignBox > line.advance) {
+                stretch = (alignBox - line.advance) / spaces;
+                penX = 0;
+            }
+        }
+        const baseline = penY + box.halfLeading + box.base.ascent;
+        for (const character of line.characters) {
+            if (character.width > 0 && character.height > 0) {
+                glyphs.push({
+                    character: character.character,
+                    face: character.face,
+                    fontSize: character.fontSize,
+                    color: character.color,
+                    center: [offsetX + penX + character.bearingLeft + character.width / 2, offsetY + baseline + character.bearingTop + character.height / 2],
+                    width: character.width,
+                    height: character.height,
+                });
+            }
+            penX += character.advance + options.letterSpacing;
+            if (character.isSpace)
+                penX += stretch;
+        }
+        penY += box.height;
+    }
+    return { glyphs, size: [blockWidth, blockHeight], lineCount: lines.length };
+}
+/** Reference `Justify` → the pen offset for one line inside the box `Alignment` gets. */
+function alignPenX(justify, lineWidth, box) {
+    switch (justify) {
+        case "center":
+            return (box - lineWidth) / 2;
+        case "right":
+        case "end":
+            return box - lineWidth;
+        default:
+            return 0;
+    }
+}

package/dist/text-msdf-baked.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Prebaked multi-channel distance field glyph source.
+ *
+ * The counterpart to `OutlineGlyphRasterizer`: instead of parsing a face and running the encoder on
+ * the first frame a glyph appears, this reads the atlas that `bun scripts/bake-msdf-atlas.ts`
+ * produced and slices each glyph out of it. Nothing here links `opentype.js`, and no encoding ever
+ * runs — at the cost of a fixed character set and a payload that ships whether or not it is used.
+ *
+ * The page travels gzipped, so `load()` has to resolve before any glyph is asked for. Decompression
+ * uses the platform `DecompressionStream`, which is why the payload is not a PNG: it keeps the whole
+ * path free of image decoding and usable in Node, where the tests run.
+ *
+ * Because the page stores every glyph at one fixed raster, the metrics it carries are scaled by
+ * `fontSize / bakeSize` rather than re-rasterised. That is exactly what makes a distance field worth
+ * baking: one set of texels serves every size.
+ */
+import { type GlyphRasterizer, type RasterizedGlyph } from "./text-font.js";
+import type { FontFace, GlyphMetrics, TextMeasurer, VerticalMetrics } from "./text-layout.js";
+export declare class BakedMsdfRasterizer implements GlyphRasterizer, TextMeasurer {
+    #private;
+    readonly encoding: "msdf";
+    readonly distanceRange = 4;
+    readonly bakeSize = 24;
+    /**
+     * Every glyph already sits in a page baked at `bakeSize`, so another raster size cannot be
+     * honoured: the renderer keeps this source on its own raster instead of following the screen.
+     */
+    readonly dynamicRaster = false;
+    /** True once the page is decompressed and glyphs can be sliced out of it. */
+    get ready(): boolean;
+    /** Decompresses the inlined page. Idempotent, so calling it per frame is harmless. */
+    load(): Promise<void>;
+    /**
+     * The page stores one face, so the axes cannot change a sliced glyph. Keying on the family alone
+     * keeps the atlas from packing the same texels once per requested weight.
+     */
+    readonly faceKey: (face: FontFace) => string;
+    verticalMetrics(_face: FontFace, fontSize: number): VerticalMetrics;
+    glyphMetrics(character: string, _face: FontFace, fontSize: number): GlyphMetrics;
+    rasterize(character: string, face: FontFace, fontSize: number): RasterizedGlyph | undefined;
+}

package/dist/text-msdf-baked.js

@@ -0,0 +1,117 @@
+/**
+ * Prebaked multi-channel distance field glyph source.
+ *
+ * The counterpart to `OutlineGlyphRasterizer`: instead of parsing a face and running the encoder on
+ * the first frame a glyph appears, this reads the atlas that `bun scripts/bake-msdf-atlas.ts`
+ * produced and slices each glyph out of it. Nothing here links `opentype.js`, and no encoding ever
+ * runs — at the cost of a fixed character set and a payload that ships whether or not it is used.
+ *
+ * The page travels gzipped, so `load()` has to resolve before any glyph is asked for. Decompression
+ * uses the platform `DecompressionStream`, which is why the payload is not a PNG: it keeps the whole
+ * path free of image decoding and usable in Node, where the tests run.
+ *
+ * Because the page stores every glyph at one fixed raster, the metrics it carries are scaled by
+ * `fontSize / bakeSize` rather than re-rasterised. That is exactly what makes a distance field worth
+ * baking: one set of texels serves every size.
+ */
+import { BAKED_MSDF_ASCENT, BAKED_MSDF_BAKE_SIZE, BAKED_MSDF_DESCENT, BAKED_MSDF_DISTANCE_RANGE, BAKED_MSDF_GLYPHS, BAKED_MSDF_PAGE_GZIP_BASE64, BAKED_MSDF_PAGE_SIZE, } from "./assets/fira-mono-msdf-atlas.js";
+import { decodeBase64Bytes } from "./text-font.js";
+function bakedGlyph(character) {
+    return BAKED_MSDF_GLYPHS[character];
+}
+export class BakedMsdfRasterizer {
+    encoding = "msdf";
+    distanceRange = BAKED_MSDF_DISTANCE_RANGE;
+    bakeSize = BAKED_MSDF_BAKE_SIZE;
+    /**
+     * Every glyph already sits in a page baked at `bakeSize`, so another raster size cannot be
+     * honoured: the renderer keeps this source on its own raster instead of following the screen.
+     */
+    dynamicRaster = false;
+    #metrics = new Map();
+    #page;
+    /** True once the page is decompressed and glyphs can be sliced out of it. */
+    get ready() {
+        return this.#page !== undefined;
+    }
+    /** Decompresses the inlined page. Idempotent, so calling it per frame is harmless. */
+    async load() {
+        if (this.#page !== undefined)
+            return;
+        const compressed = decodeBase64Bytes(BAKED_MSDF_PAGE_GZIP_BASE64);
+        const stream = new Blob([compressed]).stream().pipeThrough(new DecompressionStream("gzip"));
+        const buffer = await new Response(stream).arrayBuffer();
+        const page = new Uint8Array(buffer);
+        const expected = BAKED_MSDF_PAGE_SIZE * BAKED_MSDF_PAGE_SIZE * 4;
+        if (page.byteLength !== expected) {
+            throw new Error(`the prebaked atlas decompressed to ${page.byteLength} bytes, expected ${expected}`);
+        }
+        this.#page = page;
+    }
+    /**
+     * The page stores one face, so the axes cannot change a sliced glyph. Keying on the family alone
+     * keeps the atlas from packing the same texels once per requested weight.
+     */
+    faceKey = (face) => face.family;
+    verticalMetrics(_face, fontSize) {
+        const scale = fontSize / BAKED_MSDF_BAKE_SIZE;
+        return { ascent: BAKED_MSDF_ASCENT * scale, descent: BAKED_MSDF_DESCENT * scale };
+    }
+    glyphMetrics(character, _face, fontSize) {
+        const key = `${fontSize}|${character}`;
+        const cached = this.#metrics.get(key);
+        if (cached !== undefined)
+            return cached;
+        const baked = bakedGlyph(character);
+        const scale = fontSize / BAKED_MSDF_BAKE_SIZE;
+        const value = baked === undefined
+            ? { advance: 0, width: 0, height: 0, bearingLeft: 0, bearingTop: 0 }
+            : {
+                advance: baked[8] * scale,
+                width: baked[6] * scale,
+                height: baked[7] * scale,
+                bearingLeft: baked[4] * scale,
+                bearingTop: baked[5] * scale,
+            };
+        this.#metrics.set(key, value);
+        return value;
+    }
+    rasterize(character, face, fontSize) {
+        const page = this.#page;
+        if (page === undefined)
+            throw new Error("BakedMsdfRasterizer.load() must resolve before glyphs are requested");
+        const baked = bakedGlyph(character);
+        if (baked === undefined)
+            return undefined;
+        const pageSize = BAKED_MSDF_PAGE_SIZE;
+        const left = Math.round(baked[0] * pageSize);
+        const top = Math.round(baked[1] * pageSize);
+        // `ceil`, not `round`: the atlas maps the ink box exactly (`inkWidth` below), so the texels it
+        // stores have to be at least as large as that box. Rounding down lets the UV rectangle read past
+        // the columns this slice wrote, which pulls the glyph's edge inwards.
+        const width = Math.ceil((baked[2] - baked[0]) * pageSize);
+        const height = Math.ceil((baked[3] - baked[1]) * pageSize);
+        // Whitespace is in the table for its advance, but there is no ink box to slice out of the page.
+        if (width <= 0 || height <= 0)
+            return undefined;
+        const texels = new Uint8Array(width * height * 4);
+        for (let row = 0; row < height; row++) {
+            const from = ((top + row) * pageSize + left) * 4;
+            texels.set(page.subarray(from, from + width * 4), row * width * 4);
+        }
+        // The texels stay at their baked size; only the placement scales with the requested font size.
+        const scale = fontSize / BAKED_MSDF_BAKE_SIZE;
+        const metrics = this.glyphMetrics(character, face, fontSize);
+        return {
+            width,
+            height,
+            texels,
+            // The bake carries the ink box at the bake size, which is what the atlas has to map.
+            inkWidth: baked[6],
+            inkHeight: baked[7],
+            bearingLeft: metrics.bearingLeft,
+            bearingTop: metrics.bearingTop,
+            advance: metrics.advance,
+        };
+    }
+}

package/dist/text-msdf-font.d.ts

@@ -0,0 +1,85 @@
+/**
+ * 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 type { Font } from "opentype.js";
+import { type GlyphRasterizer, type RasterizedGlyph } from "./text-font.js";
+import { type OutlineSegment } from "./text-msdf.js";
+import type { FontFace, GlyphMetrics, TextMeasurer, VerticalMetrics } from "./text-layout.js";
+/** The subset of `opentype.js`'s path commands this source understands. */
+type OutlineCommand = {
+    readonly type: "M";
+    readonly x: number;
+    readonly y: number;
+} | {
+    readonly type: "L";
+    readonly x: number;
+    readonly y: number;
+} | {
+    readonly type: "Q";
+    readonly x1: number;
+    readonly y1: number;
+    readonly x: number;
+    readonly y: number;
+} | {
+    readonly type: "C";
+    readonly x1: number;
+    readonly y1: number;
+    readonly x2: number;
+    readonly y2: number;
+    readonly x: number;
+    readonly y: number;
+} | {
+    readonly type: "Z";
+};
+export type OutlineGlyphRasterizerOptions = {
+    /** TrueType bytes to read. Defaults to the inlined subset. */
+    readonly font?: ArrayBuffer;
+    /** Distance in texels either side of the edge that the encoded field covers. */
+    readonly distanceRange?: number;
+    /**
+     * Default rasterisation scale: a request that names no scale of its own is encoded at
+     * `fontSize * rasterScale` texels while layout and quads stay in font pixels, exactly as the
+     * Canvas2D sources do it. The renderer overrides it per block with the size the block covers on
+     * screen (see `text-raster`), so the atlas asks for the finer size and the same outline is encoded
+     * at a raster that matches it.
+     */
+    readonly rasterScale?: number;
+    /**
+     * Whether the renderer drives this source's raster size from the size a block covers on screen.
+     * Outlines encode at any size, so it defaults to `true`; a fixed raster is only for a comparison
+     * that has to stay at one raster size on purpose.
+     */
+    readonly dynamicRaster?: boolean;
+};
+/** Turns a path's command list into outline segments, offset so the ink box starts at the origin. */
+export declare function commandsToSegments(commands: readonly OutlineCommand[], offsetX: number, offsetY: number): readonly OutlineSegment[];
+export declare class OutlineGlyphRasterizer implements GlyphRasterizer, TextMeasurer {
+    #private;
+    readonly encoding: "msdf";
+    readonly distanceRange: number;
+    readonly rasterScale: number;
+    /** Whether the renderer drives this source's raster per block. See `dynamicRaster` in the options. */
+    readonly dynamicRaster: boolean;
+    constructor(options?: OutlineGlyphRasterizerOptions);
+    /** The face this source reads, for callers that want to name it. */
+    get font(): Font;
+    /**
+     * 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.
+     */
+    readonly faceKey: (face: FontFace) => string;
+    verticalMetrics(_face: FontFace, fontSize: number): VerticalMetrics;
+    glyphMetrics(character: string, _face: FontFace, fontSize: number): GlyphMetrics;
+    rasterize(character: string, _face: FontFace, rasterSize: number): RasterizedGlyph | undefined;
+}
+export {};