vgpu-render 0.0.0-stage → 0.1.0

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

@@ -0,0 +1,36 @@
+/**
+ * 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 { 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>;
+    verticalMetrics(_fontFamily: string, fontSize: number): VerticalMetrics;
+    glyphMetrics(character: string, _fontFamily: string, fontSize: number): GlyphMetrics;
+    rasterize(character: string, fontFamily: string, fontSize: number): RasterizedGlyph | undefined;
+}

package/dist/text-msdf-baked.js

@@ -0,0 +1,112 @@
+/**
+ * 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;
+    }
+    verticalMetrics(_fontFamily, fontSize) {
+        const scale = fontSize / BAKED_MSDF_BAKE_SIZE;
+        return { ascent: BAKED_MSDF_ASCENT * scale, descent: BAKED_MSDF_DESCENT * scale };
+    }
+    glyphMetrics(character, _fontFamily, 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, fontFamily, 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, fontFamily, 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,79 @@
+/**
+ * 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 { 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;
+    verticalMetrics(_fontFamily: string, fontSize: number): VerticalMetrics;
+    glyphMetrics(character: string, _fontFamily: string, fontSize: number): GlyphMetrics;
+    rasterize(character: string, _fontFamily: string, rasterSize: number): RasterizedGlyph | undefined;
+}
+export {};

package/dist/text-msdf-font.js

@@ -0,0 +1,153 @@
+/**
+ * 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) };
+    }
+    verticalMetrics(_fontFamily, 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, _fontFamily, 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, _fontFamily, 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 {};