vgpu-render 0.0.0-stage → 0.2.0

package/dist/text-font.js

@@ -0,0 +1,261 @@
+/**
+ * Browser-side font loading and glyph rasterisation for the text renderer.
+ *
+ * reference rasterises glyphs with swash into a `FontAtlas`
+ * (`the reference implementation`); the equivalent rasteriser in a browser is
+ * Canvas2D, so `fillText` plays the role of `swash::scale::Render` and the browser's font
+ * stack stands in for font discovery. The bundled font is inlined exactly the way reference
+ * inlines `FiraMono-subset.ttf` with `include_bytes!`, so nothing is fetched at runtime.
+ *
+ * The subset deliberately has no CJK coverage; pass a different family through the text
+ * options when those are needed.
+ *
+ * Everything here is browser-only. Layout depends on the `TextMeasurer` interface alone, so
+ * unit tests keep running in plain Node, and the GPU tests inject their own rasteriser.
+ */
+import { FIRA_MONO_MEDIUM_SUBSET_BASE64, FIRA_MONO_MEDIUM_SUBSET_TTF_BASE64 } from "./assets/fira-mono-medium-subset.js";
+import { coverageToSdf, DEFAULT_SDF_RANGE } from "./text-sdf.js";
+import { fontFaceKey } from "./text-layout.js";
+/**
+ * Family name the bundled font is registered under. It is deliberately not `"Fira Mono"` so
+ * a locally installed face can never shadow the inlined one.
+ */
+export const DEFAULT_FONT_FAMILY = "vgpu-render-fira-mono";
+/**
+ * Fira Mono's hhea metrics are 935 / -265 per 1000 upem, i.e. exactly the 1.2 em line box
+ * reference default `LineHeight` assumes. They are the fallback when a browser reports no font
+ * bounding box.
+ */
+const FALLBACK_ASCENT_RATIO = 0.935;
+const FALLBACK_DESCENT_RATIO = 0.265;
+const INITIAL_SURFACE_SIZE = 256;
+/** Decodes a base64 payload into bytes. Shared by the inlined font and the prebaked atlas. */
+export function decodeBase64Bytes(base64) {
+    const binary = atob(base64);
+    const bytes = new Uint8Array(binary.length);
+    for (let index = 0; index < binary.length; index++)
+        bytes[index] = binary.charCodeAt(index);
+    return bytes;
+}
+const registeredFamilies = new Map();
+/**
+ * Registers a family whose weights are separate faces, each carrying its own `weight` descriptor.
+ *
+ * This is the only way to get more than one drawn weight out of Canvas2D: the font shorthand carries a
+ * single synthesised bold step, and `font-variation-settings` does not exist there, but the browser
+ * does select a face by the weight it was registered with. Registering the same family once per
+ * weight therefore turns `weight: 700` into a real bold face instead of an emboldened regular one.
+ *
+ * Idempotent per family, like `loadDefaultFont`, and browser-only.
+ */
+export function loadFontFaces(family, faces) {
+    const existing = registeredFamilies.get(family);
+    if (existing !== undefined)
+        return existing;
+    const registration = registerFontFaces(family, faces);
+    registeredFamilies.set(family, registration);
+    return registration;
+}
+async function registerFontFaces(family, faces) {
+    const fonts = typeof document === "undefined" ? undefined : document.fonts;
+    if (fonts === undefined || typeof FontFace === "undefined") {
+        throw new Error("registering a font family requires a browser environment");
+    }
+    const loaded = faces.map(async (face) => {
+        const definition = new FontFace(family, decodeBase64Bytes(face.woff2Base64), { weight: String(face.weight) });
+        await definition.load();
+        return definition;
+    });
+    for (const definition of await Promise.all(loaded))
+        fonts.add(definition);
+}
+/** Decodes the inlined WOFF2 bytes of the bundled font, which is what `FontFace` takes. */
+export function decodeEmbeddedFont() {
+    return decodeBase64Bytes(FIRA_MONO_MEDIUM_SUBSET_BASE64);
+}
+/**
+ * Decodes the inlined TrueType bytes of the same subset. The outline-based encoders need this one:
+ * `opentype.js` reads glyph outlines, and it cannot decompress the WOFF2 container.
+ */
+export function decodeEmbeddedTrueTypeFont() {
+    return decodeBase64Bytes(FIRA_MONO_MEDIUM_SUBSET_TTF_BASE64);
+}
+let defaultFont;
+/**
+ * Registers the bundled font with the document, once per page. Measuring or drawing with
+ * `DEFAULT_FONT_FAMILY` before this resolves falls back to another face, so await it before
+ * the first frame that draws text.
+ */
+export function loadDefaultFont() {
+    defaultFont ??= registerDefaultFont();
+    return defaultFont;
+}
+async function registerDefaultFont() {
+    const fonts = typeof document === "undefined" ? undefined : document.fonts;
+    if (fonts === undefined || typeof FontFace === "undefined") {
+        throw new Error("loading the bundled text font requires a browser environment");
+    }
+    const face = new FontFace(DEFAULT_FONT_FAMILY, decodeEmbeddedFont());
+    await face.load();
+    fonts.add(face);
+}
+/**
+ * The CSS font shorthand that selects `face` at `fontSize`.
+ *
+ * Order follows the shorthand's grammar — style, weight, stretch, size, family — because Canvas2D
+ * parses the value as one. Two of the axes are conditional:
+ *
+ * - `font-stretch` keywords are only kept by the parser when the face has a `wdth` axis. A static
+ *   face drops the keyword and draws every stop identically, which is why the bundled subset cannot
+ *   show a `FontWidth` difference at all.
+ * - `italic` is the only slant Canvas2D keeps; `oblique <angle>` reads back as plain `italic`.
+ *
+ * A weight the loaded face does not carry is synthesised by the browser (one emboldened step, which
+ * keeps the advance), so `weight` at least changes what is drawn for the bundled static face.
+ */
+export function canvasFontString(face, fontSize) {
+    const style = face.style === "italic" ? "italic " : "";
+    const stretch = face.width === "normal" ? "" : `${face.width} `;
+    return `${style}${face.weight} ${stretch}${fontSize}px "${face.family}"`;
+}
+/**
+ * Canvas2D glyph source, doubling as the layout `TextMeasurer` so the canvas is only set up
+ * once per canvas-configured face and every `measureText` result is cached.
+ *
+ * Metrics follow Canvas2D's convention: the pen sits at the origin and the baseline is y = 0
+ * with y growing downwards. `actualBoundingBoxLeft` is a *leftward* distance, so a glyph that
+ * starts right of the pen reports a negative value — negating it yields the ink's left edge
+ * in pen space, which is what the atlas stores.
+ */
+export class CanvasGlyphRasterizer {
+    encoding;
+    distanceRange;
+    rasterScale;
+    /**
+     * Whether the renderer drives this source's raster size from the size a block covers on screen.
+     * A Canvas2D face can be asked for any size, so it defaults to `true`; a source that needs a fixed
+     * raster — a pixel-accurate comparison against another renderer, say — turns it off.
+     */
+    dynamicRaster;
+    #surface;
+    #metrics = new Map();
+    #vertical = new Map();
+    constructor(options = {}) {
+        this.encoding = options.encoding ?? "bitmap";
+        this.distanceRange = options.distanceRange ?? DEFAULT_SDF_RANGE;
+        this.rasterScale = options.rasterScale ?? 1;
+        this.dynamicRaster = options.dynamicRaster ?? true;
+    }
+    #ensureSurface() {
+        if (this.#surface === undefined) {
+            if (typeof document === "undefined") {
+                throw new Error("glyph rasterisation requires a browser environment");
+            }
+            const canvas = document.createElement("canvas");
+            canvas.width = INITIAL_SURFACE_SIZE;
+            canvas.height = INITIAL_SURFACE_SIZE;
+            const context = canvas.getContext("2d", { willReadFrequently: true });
+            if (context === null)
+                throw new Error("a 2D canvas context is required to rasterise glyphs");
+            this.#surface = { canvas, context };
+        }
+        return this.#surface;
+    }
+    #font(face, fontSize) {
+        return canvasFontString(face, fontSize);
+    }
+    verticalMetrics(face, fontSize) {
+        const key = `${fontFaceKey(face)}|${fontSize}`;
+        const cached = this.#vertical.get(key);
+        if (cached !== undefined)
+            return cached;
+        const context = this.#ensureSurface().context;
+        context.font = this.#font(face, fontSize);
+        const metrics = context.measureText("M");
+        const ascent = metrics.fontBoundingBoxAscent > 0 ? metrics.fontBoundingBoxAscent : fontSize * FALLBACK_ASCENT_RATIO;
+        const descent = metrics.fontBoundingBoxDescent > 0 ? metrics.fontBoundingBoxDescent : fontSize * FALLBACK_DESCENT_RATIO;
+        const value = { ascent, descent };
+        this.#vertical.set(key, value);
+        return value;
+    }
+    glyphMetrics(character, face, fontSize) {
+        const key = `${fontFaceKey(face)}|${fontSize}|${character}`;
+        const cached = this.#metrics.get(key);
+        if (cached !== undefined)
+            return cached;
+        const context = this.#ensureSurface().context;
+        context.font = this.#font(face, fontSize);
+        const metrics = context.measureText(character);
+        const bearingLeft = -metrics.actualBoundingBoxLeft;
+        const value = {
+            advance: metrics.width,
+            width: metrics.actualBoundingBoxRight - bearingLeft,
+            height: metrics.actualBoundingBoxAscent + metrics.actualBoundingBoxDescent,
+            bearingLeft,
+            bearingTop: -metrics.actualBoundingBoxAscent,
+        };
+        this.#metrics.set(key, value);
+        return value;
+    }
+    rasterize(character, face, rasterSize) {
+        // The raster size *is* the face size here: `measureText` and the fill both work in the texels the
+        // atlas will store, and the layout's own measurements never pass through this path.
+        const glyph = this.glyphMetrics(character, face, rasterSize);
+        if (!(glyph.width > 0) || !(glyph.height > 0))
+            return undefined;
+        // The ink box is fractional; the mask rounds up so no edge pixel is lost.
+        const width = Math.max(1, Math.ceil(glyph.width));
+        const height = Math.max(1, Math.ceil(glyph.height));
+        const { canvas, context } = this.#ensureSurface();
+        if (canvas.width < width || canvas.height < height) {
+            canvas.width = Math.max(canvas.width, width);
+            canvas.height = Math.max(canvas.height, height);
+        }
+        context.clearRect(0, 0, width, height);
+        context.font = this.#font(face, rasterSize);
+        context.textAlign = "left";
+        context.textBaseline = "alphabetic";
+        context.fillStyle = "#fff";
+        // Place the pen so the ink box starts at (0, 0): the baseline sits `-bearingTop` down.
+        context.fillText(character, -glyph.bearingLeft, -glyph.bearingTop);
+        const pixels = context.getImageData(0, 0, width, height).data;
+        const coverage = new Uint8Array(width * height);
+        for (let index = 0; index < coverage.length; index++)
+            coverage[index] = pixels[index * 4 + 3];
+        return {
+            width,
+            height,
+            texels: encodeCoverage(coverage, width, height, this.encoding, this.distanceRange),
+            inkWidth: glyph.width,
+            inkHeight: glyph.height,
+            bearingLeft: glyph.bearingLeft,
+            bearingTop: glyph.bearingTop,
+            advance: glyph.advance,
+        };
+    }
+}
+/** Packs Canvas2D coverage into the RGBA layout the chosen encoding expects. */
+export function encodeCoverage(coverage, width, height, encoding, range) {
+    const texels = new Uint8Array(coverage.length * 4);
+    if (encoding === "bitmap") {
+        // A tintable alpha mask: RGB stays 255 so the shader can colour it.
+        for (let index = 0; index < coverage.length; index++) {
+            const target = index * 4;
+            texels[target] = 255;
+            texels[target + 1] = 255;
+            texels[target + 2] = 255;
+            texels[target + 3] = coverage[index];
+        }
+        return texels;
+    }
+    // A signed distance in red, and the same distance in alpha so the shader can outline the glyph.
+    // It comes from the mask's coverage rather than from the outline, which makes it a little coarser
+    // than the msdf encoder's — fine for a ring, not what the edge itself is rebuilt from.
+    const field = coverageToSdf(coverage, width, height, range);
+    for (let index = 0; index < field.length; index++) {
+        const target = index * 4;
+        texels[target] = field[index];
+        texels[target + 3] = field[index];
+    }
+    return texels;
+}

package/dist/text-layout.d.ts

@@ -0,0 +1,175 @@
+/**
+ * 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.
+ */
+export type Rgba = readonly [number, number, number, number];
+/** Vertical font metrics, in the same units as the font size the measurer was asked for. */
+export type VerticalMetrics = {
+    readonly ascent: number;
+    readonly descent: number;
+};
+/**
+ * Per-character metrics, mirroring the `Placement` swash reports to reference: an advance along
+ * the baseline plus the ink box relative to the pen.
+ */
+export type GlyphMetrics = {
+    /** Pen advance for this character. */
+    readonly advance: number;
+    /** Ink box width. Zero for whitespace. */
+    readonly width: number;
+    /** Ink box height. Zero for whitespace. */
+    readonly height: number;
+    /** Ink box left edge relative to the pen, y down: positive moves right. */
+    readonly bearingLeft: number;
+    /** Ink box top edge relative to the baseline, y down: positive is below the baseline. */
+    readonly bearingTop: number;
+};
+/**
+ * reference `FontStyle`, minus `Oblique(angle)`.
+ *
+ * Canvas2D accepts the `italic` keyword in its font shorthand and silently drops the slant angle —
+ * `oblique 14deg` reads back as `italic` — so an oblique angle could not be honoured and is left out
+ * rather than accepted and ignored. A face without an italic face is slanted by the browser.
+ */
+export type TextFontStyle = "normal" | "italic";
+/**
+ * reference `FontWidth` stops, spelled as the CSS `font-stretch` keywords Canvas2D understands.
+ *
+ * reference takes a percentage (`FontWidth::SEMI_CONDENSED` is 87.5), but Canvas2D rejects a percentage in
+ * the font shorthand and only accepts these nine keywords. The axis is inert unless the face actually
+ * carries a `wdth` axis: a static face like the bundled subset keeps the keyword out of its resolved
+ * font, so every stop draws the same width there.
+ */
+export type TextFontWidth = "ultra-condensed" | "extra-condensed" | "condensed" | "semi-condensed" | "normal" | "semi-expanded" | "expanded" | "extra-expanded" | "ultra-expanded";
+/** Every `FontWidth` stop, in reference order. */
+export declare const TEXT_FONT_WIDTHS: readonly TextFontWidth[];
+/** Every `FontStyle` variant this implementation can honour. */
+export declare const TEXT_FONT_STYLES: readonly TextFontStyle[];
+/** reference `FontWeight::NORMAL`, and the value the CSS font shorthand defaults to. */
+export declare const DEFAULT_FONT_WEIGHT = 400;
+/** reference `FontWeight` range, 1 to 1000. */
+export declare const MIN_FONT_WEIGHT = 1;
+export declare const MAX_FONT_WEIGHT = 1000;
+/**
+ * One face request: everything that decides which glyphs a character rasterises to.
+ *
+ * This is the unit the glyph atlas keys on, so two blocks that differ only in weight cannot share a
+ * rasterised glyph. A source with a single fixed face reports the parts it cannot change through
+ * `GlyphRasterizer.faceKey`.
+ */
+export type FontFace = {
+    readonly family: string;
+    readonly weight: number;
+    readonly style: TextFontStyle;
+    readonly width: TextFontWidth;
+};
+/** A face with the axes left optional, which is how callers and spans express one. */
+export type FontFaceOptions = {
+    readonly family: string;
+    readonly weight?: number | undefined;
+    readonly style?: TextFontStyle | undefined;
+    readonly width?: TextFontWidth | undefined;
+};
+/** Folds a face's optional axes into the complete request the measurer and the atlas take. */
+export declare function resolveFontFace(options: FontFaceOptions): FontFace;
+/** Every field that can change which glyphs are rasterised, joined into one cache key. */
+export declare function fontFaceKey(face: FontFace): string;
+/** Source of glyph metrics. The browser implementation measures through Canvas2D. */
+export interface TextMeasurer {
+    /** Vertical metrics for a `fontSize`-sized instance of `face`. */
+    verticalMetrics(face: FontFace, fontSize: number): VerticalMetrics;
+    /** Metrics for one character. Whitespace returns a zero-size ink box. */
+    glyphMetrics(character: string, face: FontFace, fontSize: number): GlyphMetrics;
+}
+/** Reference `Justify`. `start`/`end` resolve to left/right in this LTR-only layout. */
+export type TextJustify = "left" | "center" | "right" | "justified" | "start" | "end";
+/** Reference `LineBreak`, minus the Unicode-correct word segmentation reference gets from parley. */
+export type TextLineBreak = "word" | "character" | "word-or-character" | "none";
+/** Normalized anchor: x 0 = left, 1 = right; y 0 = top, 1 = bottom (local y grows down). */
+export type TextAnchorPoint = readonly [number, number];
+/** Reference `Anchor` presets, named for the block corner that lands on the position. */
+export type TextAnchor = "center" | "top-left" | "top-center" | "top-right" | "center-left" | "center-right" | "bottom-left" | "bottom-center" | "bottom-right";
+export declare function resolveTextAnchor(anchor: TextAnchor): TextAnchorPoint;
+/** One section of a text block, the equivalent of a reference `TextSpan`. */
+export type TextSpanInput = {
+    readonly text: string;
+    readonly color?: Rgba;
+    readonly fontSize?: number;
+    readonly fontFamily?: string;
+    readonly weight?: number;
+    readonly style?: TextFontStyle;
+    readonly width?: TextFontWidth;
+};
+/** reference `LineHeight` default, `RelativeToFont(1.2)`. */
+export declare const DEFAULT_LINE_HEIGHT_SCALE = 1.2;
+export type TextLayoutOptions = {
+    readonly color: Rgba;
+    readonly fontSize: number;
+    readonly fontFamily: string;
+    /** Block default for `FontFace.weight`; spans override it. */
+    readonly weight?: number | undefined;
+    /** Block default for `FontFace.style`; spans override it. */
+    readonly style?: TextFontStyle | undefined;
+    /** Block default for `FontFace.width`; spans override it. */
+    readonly width?: TextFontWidth | undefined;
+    /**
+     * Absolute line height in layout units, reference `LineHeight::Px`. When omitted the line height
+     * is `lineHeightScale` times the line's own largest font size, which is reference
+     * `LineHeight::RelativeToFont` — the default, and the reason a line holding a larger span gets
+     * a taller box rather than being clipped to the block's own size.
+     */
+    readonly lineHeight?: number | undefined;
+    /** Multiple of the line's largest font size, reference `LineHeight::RelativeToFont`. Default `1.2`. */
+    readonly lineHeightScale?: number | undefined;
+    /**
+     * Added after every character, the last one on a line included: parley adds it to each cluster's
+     * advance, and the trailing whitespace a line breaks at carries its share into the block width.
+     */
+    readonly letterSpacing: number;
+    readonly justify: TextJustify;
+    readonly lineBreak: TextLineBreak;
+    /**
+     * `TextBounds`. Only `width` feeds layout: it is the wrap width. `height` is not a layout input,
+     * matching reference, whose `Text2d` never truncates lines against it (it only sizes the node).
+     */
+    readonly bounds?: readonly [number, number] | undefined;
+    readonly anchor: TextAnchorPoint;
+};
+/** One laid-out glyph, ready to become an instance once its atlas rectangle is known. */
+export type PositionedGlyph = {
+    readonly character: string;
+    readonly face: FontFace;
+    readonly fontSize: number;
+    readonly color: Rgba;
+    /** Ink box centre relative to the block's anchor point, y down. */
+    readonly center: readonly [number, number];
+    readonly width: number;
+    readonly height: number;
+};
+export type TextLayoutResult = {
+    readonly glyphs: readonly PositionedGlyph[];
+    /** Block size before the anchor offset is applied. */
+    readonly size: readonly [number, number];
+    readonly lineCount: number;
+};
+/**
+ * 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 declare function layoutText(spans: readonly TextSpanInput[], options: TextLayoutOptions, measurer: TextMeasurer): TextLayoutResult;