vgpu-render 0.0.0-stage → 0.1.0

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-scenes.d.ts

@@ -0,0 +1,85 @@
+/**
+ * Screen-space text pages.
+ *
+ * These are vgpu's own capability rather than a port — the reference has no text API — so they
+ * are organised as **one page per question**:
+ *
+ * - `text-encodings` — the same text from every glyph source, at two sizes, plus the outline pair.
+ * - `text-scale` — the same sentence at six sizes, over three raster strategies at one size.
+ * - `text-world-zoom` — world-space rows meant to be magnified with the camera, which is the only way
+ *   to see what a source does once a block outgrows the raster its glyphs were built at.
+ * - `text-layout` — wrapping, justification, bounds, line height, letter spacing and spans.
+ * - `text-anchor` — the nine anchors against the marker they land on and their own bounds.
+ * - `text-cjk` — CJK wrapping, kinsoku and mixed-script runs.
+ *
+ * Three conventions run through all of them, because a comparison without them is unreadable:
+ *
+ * 1. **One sentence, repeated per condition**, with the condition labelled above the column. A page
+ *    whose rows each say something different cannot be compared at all.
+ * 2. **Every caption stays inside the width of its column**, which is the mistake this layout makes
+ *    first: overlapping captions are worse than a shorter label.
+ * 3. **A 1 px rule** in the bottom-left corner of every screen-space page, so an edge has something of
+ *    a known width next to it. It is drawn with one-pixel **points**, because `recorder.line` has no
+ *    screen-space mode: a line is a world-space segment projected through the camera, which lands as
+ *    an arbitrary diagonal on a page whose content is in pixels.
+ *
+ * Text blocks deliberately name no glyph source: they take the default one, which rasterises each
+ * glyph at the size it covers on screen. That is what a caller gets out of the box, and the thing
+ * these pages exist to show; a block that wants a fixed raster says so explicitly.
+ *
+ * A page that mixes screen-space captions with world-space content cannot work: the camera is framed
+ * around every command's position, so a caption at `[24, 520]` drags the viewport to those world
+ * coordinates and the real content ends up off-screen. `text-world-zoom` is therefore world-space end
+ * to end, captions included.
+ */
+import type { FrameRecorder } from "./frame-recorder.js";
+/**
+ * `text-encodings` — the same text from four sources.
+ *
+ * Two bands per column: the word at a normal size, and a shorter run of the same ink at more than
+ * twice that, which is where a coverage source and a distance field stop looking alike. The outline
+ * pair belongs on this page rather than its own: how a ring is obtained is a property of the encoding.
+ */
+export declare function textEncodingsScene(recorder: FrameRecorder): void;
+/**
+ * `text-scale` — three raster strategies at one size, then one size per row.
+ *
+ * The top row is the comparison the screen-driven ladder exists for: the same 26 px text under the
+ * ladder, a fixed 1× raster and a fixed 4× raster. Below it the sizes run from 8 px to 96 px, so the
+ * rung changes — and the absence of a soft step between them — are visible in one frame.
+ */
+export declare function textScaleScene(recorder: FrameRecorder): void;
+/**
+ * `text-world-zoom` — rows meant to be magnified.
+ *
+ * Screen-space text cannot be magnified: its pixel size is fixed, so a bigger block is simply a
+ * request for a new rasterisation. World-space text is where the camera does the magnifying, which is
+ * the only honest test of what a raster does past its own size — a coverage source runs into the
+ * texels it stored, a distance field keeps rebuilding the edge from them. The whole page is world
+ * space, captions included, so the framing sees one coordinate system.
+ */
+export declare function textWorldZoomScene(recorder: FrameRecorder): void;
+/**
+ * `text-layout` — what the layout can do, one row per capability.
+ *
+ * Every row is labelled on the left, and every bounded row draws the box it wrapped into: a wrapping
+ * rule is unreadable without the box it wrapped against.
+ */
+export declare function textLayoutScene(recorder: FrameRecorder): void;
+/**
+ * `text-anchor` — the nine anchors against the marker they land on.
+ *
+ * The `+` marks the position the block is given and the box is the block's own bounds, so both of the
+ * things an anchor moves between are visible at once. Captions sit above the cell rather than beside
+ * the box, which is what keeps them from being drawn over.
+ */
+export declare function textAnchorScene(recorder: FrameRecorder): void;
+/**
+ * `text-cjk` — wrapping and kinsoku, which no latin page can show.
+ *
+ * CJK has no spaces to break at, so the wrap is per character, and kinsoku is what keeps a closing
+ * mark off the start of a line and an opening bracket off its end.
+ */
+export declare function textCjkScene(recorder: FrameRecorder): void;
+/** Dispatches one of the text pages by scene id. */
+export declare function textScene(id: string, recorder: FrameRecorder): void;