Skip to content

A fast 2D and 3D game engine — TypeScript SDK, C++/WebAssembly core, visual editor. Ship one project to web, desktop, WeChat MiniGames, playable ads, and native Android / iOS.

30.9 KB
Raw Blame
// SPDX-License-Identifier: Apache-2.0
// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
/**
 * @file    ui/text/text-renderer.ts
 * @brief   High-level SDF text drawing: owns the dynamic glyph
 *          atlas and turns a string into batched glyph quads via the engine.
 *
 * `drawTextWith` is the pure orchestration (inject atlas + a submit sink → unit-
 * testable, incl. the per-page grouping that a string spanning multiple atlas
 * pages requires). `TextRenderer` wires it to the real Canvas2D rasterizer +
 * engine page store + submitTextBatch.
 */
import { createTextCullGeometry, textClipPlanes, clipTextGeometry, type TextCullGeometry } from './text-culling';
import type { ESEngineModule } from '../../wasm';
import { platformHasGlyphRasterizer } from '../../platform';
import { GlyphAtlas } from './glyph-atlas';
import { CanvasGlyphRasterizer, type CanvasGlyphRasterizerOptions } from './glyph-rasterizer';
import { NativeGlyphRasterizer } from './native-glyph-rasterizer';
import { EngineAtlasPageStore } from './atlas-page-store';
import { TextAlign, TextVerticalAlign, TextOverflow } from '../core/text';
import { layoutText, buildGlyphVertices, MAX_TEXT_BATCH_GLYPHS, type LaidGlyph, type RGBA, type TextLayout } from './layout';
import { submitTextBatch, TEXT_VERTEX_FLOATS, TextGlyphMode } from './submit';
import { bitmapFontOf, fontAscent } from './bitmap-font';
import { DEFAULT_ASCENT } from './text-transform';
import { withScratch } from '../../wasm/wasmScratch';
import type { EngineApi } from '../../ecs/bridge/engineApi';

/** Receives index-safe glyph batches, each bound to one atlas page. */
/** @p mode is how the page is read; left out, it is whatever the renderer's own kind draws (a distance field, or a plain bitmap page). */
export type GlyphBatchSink = (vertices: Float32Array, indices: Uint16Array, pageId: number, mode?: TextGlyphMode) => void;

export interface DrawTextParams {
    text: string;
    fontFamily: string;
    fontSizePx: number;
    color: RGBA;
    /** Inherited opacity applied to every fill, rich-color, shadow and outline vertex. */
    opacity?: number;
    originX?: number;
    originY?: number;
    style?: number;
    /** Parse `<b>/<i>/<color>/<font size>` markup. */
    richText?: boolean;
    /** Horizontal alignment. The component's own spelling, so the mapping from
     *  number to meaning is written once. */
    align?: TextAlign;
    /** Baseline-to-baseline distance (px) for multi-line text. */
    lineHeight?: number;
    /** Extra advance between glyphs (px). */
    letterSpacing?: number;
    /** Word-wrap width in px (plain text); 0/undefined = no wrap. */
    maxWidth?: number;
    /** Box width (px) horizontal align positions the block within; 0/undefined = boxless (anchor to origin). */
    boxWidth?: number;
    /** Vertical alignment within boxHeight. */
    verticalAlign?: TextVerticalAlign;
    /** Box height (px) for vertical alignment; 0/undefined = boxless (anchor to origin). */
    boxHeight?: number;
    /** What a run too big for the box does. */
    overflow?: TextOverflow;
    /** A bar under each line. */
    underline?: boolean;
    /**
     * Drop shadow: an offset, recolored copy of the glyphs drawn behind the fill.
     * `blur` (px, 0 = hard) spreads that copy into a ring so the shadow reads as
     * a soft mass rather than a second stamp of the text.
     */
    shadow?: { color: RGBA; dx: number; dy: number; blur?: number };
    /** Outline: recolored glyph copies fanned out by `width` px around the fill. */
    outline?: { color: RGBA; width: number };
}

// 8-direction offsets (unit) for the outline fan — scaled by the outline width.
// The bitmap atlas's only way to widen a glyph; see outlineBias.
const OUTLINE_OFFSETS: ReadonlyArray<readonly [number, number]> = [
    [-1, -1], [0, -1], [1, -1],
    [-1, 0], [1, 0],
    [-1, 1], [0, 1], [1, 1],
];

/**
 * An outline width in text px as the edge shift the SDF shader applies, or 0 when
 * these glyphs are coverage rather than distance (no edge to shift).
 *
 * A glyph is rasterized at the atlas's renderSize and drawn at fontSizePx, so one
 * atlas texel covers fontSizePx/renderSize text px; the atlas encodes `spread`
 * texels into half its range. Both conversions are in the value, which therefore
 * says the same thing at every font size and every zoom.
 *
 * Asking for more than the spread cannot dilate further — the field simply stops
 * there — so an over-wide request degrades to the widest real outline instead of
 * flooding the glyph's cell.
 */
function outlineBias(atlas: GlyphAtlas, fontSizePx: number, widthPx: number): number {
    const perTexel = atlas.distancePerTexel;
    if (perTexel <= 0 || fontSizePx <= 0) return 0;
    return widthPx * (atlas.renderSize / fontSizePx) * perTexel;
}

/**
 * A blurred shadow is the glyphs stamped around a ring, which is the same shape
 * the outline already takes — one mechanism for "spread these glyphs out", not
 * two. Two rings plus the centre approximate a Gaussian closely enough at the
 * sizes UI text uses. Unlike the outline, a blur wants a SOFTER edge rather than
 * a moved one, which the single distance the vertices carry cannot express.
 */
const SHADOW_RING: ReadonlyArray<readonly [number, number, number]> = [
    // [x, y, radius fraction] — the inner ring carries most of the mass.
    [0, 0, 0],
    [-0.55, -0.55, 1], [0, -0.78, 1], [0.55, -0.55, 1],
    [-0.78, 0, 1], [0.78, 0, 1],
    [-0.55, 0.55, 1], [0, 0.78, 1], [0.55, 0.55, 1],
];

/** The widest blur one ring of taps covers: past it its copies stand apart, and a shadow is the label eight times over. */
const SHADOW_RING_REACH = 3;
/** The most copies a blurred shadow is drawn as, however wide: each is the whole label again. */
const MOST_SHADOW_TAPS = 64;

/**
 * Where a blurred shadow's copies go, as offsets from the shadow's own place.
 *
 * A blur of a few pixels is one ring. A wider one is as many rings as keep each copy within a stroke's thickness of its neighbours
 * (a share of the font size, and never coarser than a quarter of the blur), so they read as one soft shape: a title set large with a
 * blur of eighteen pixels drew nine separate copies of itself fourteen pixels apart, blocks of dark squares round every stroke.
 */
export function shadowTaps(blur: number, fontSize: number): ReadonlyArray<readonly [number, number]> {
    if (blur <= SHADOW_RING_REACH) return SHADOW_RING.map(([x, y, r]) => [x * blur * r, y * blur * r] as const);
    const reach = blur * 0.78;
    let gap = Math.max(1.5, Math.min(blur / 4, fontSize * 0.07));
    const ringsOf = (g: number): number[] => {
        const rings = Math.max(1, Math.ceil(reach / g));
        return Array.from({ length: rings }, (_, k) => Math.max(6, Math.ceil((2 * Math.PI * reach * (k + 1) / rings) / g)));
    };
    let rings = ringsOf(gap);
    while (1 + rings.reduce((a, b) => a + b, 0) > MOST_SHADOW_TAPS) { gap *= 1.15; rings = ringsOf(gap); }
    const taps: [number, number][] = [[0, 0]];
    rings.forEach((count, k) => {
        const radius = reach * (k + 1) / rings.length;
        // Every other ring is turned half a step, so the copies of one do not line up with those of the next.
        const turn = (k % 2) * Math.PI / count;
        for (let i = 0; i < count; i++) taps.push([Math.cos(turn + 2 * Math.PI * i / count) * radius, Math.sin(turn + 2 * Math.PI * i / count) * radius]);
    });
    return taps;
}

/**
 * Per-tap alpha for `n` stacked copies that should composite to `target`.
 * Straight division under-shoots badly: eight layers of `a/8` reach
 * 1-(1-a/8)^8, not `a`. This is that inverted.
 */
export function tapAlpha(target: number, n: number): number {
    if (n <= 1) return target;
    return 1 - Math.pow(1 - Math.min(1, Math.max(0, target)), 1 / n);
}

/**
 * How far a laid-out block sits from `originX`. `layoutText` already aligned each
 * line — within the box width when there is one, within the widest line when there
 * is not — so this only has the boxless job: anchoring the whole block against the
 * origin, left edge / centre / right edge.
 *
 * @param boxWidth the layout box's width; 0 ⇒ boxless, the origin IS the box
 */
export function textBlockOffsetX(
    align: number | undefined, boxWidth: number, blockWidth: number,
): number {
    if (boxWidth > 0 || !align) return 0;
    return -(align === 1 ? blockWidth / 2 : blockWidth); // 1 center, 2 right
}

/**
 * How far a laid-out block sits from `originY`, once vertical alignment and
 * half-leading are applied.
 *
 * Split out because the boxless case was wrong in a way only arithmetic shows:
 * `rectTextBox` hands the boxed path an origin already carrying the baseline
 * (`-0.8em`), and the boxless path started from a bare 0. Middle therefore
 * centred the block on a baseline rather than on the entity, and every world
 * label sat 0.8em high — half a square, on a chessboard.
 *
 * @param boxHeight  the layout box's height; 0 ⇒ boxless, the origin IS the box
 * @param lineHeight the laid block's height
 */
export function textBlockOriginY(
    originY: number, boxHeight: number, lineHeight: number, fontSizePx: number,
    verticalAlign: number | undefined, lineHeightPx: number | undefined, ascent = DEFAULT_ASCENT,
): number {
    let y = originY;
    // Boxless: the entity origin is a zero-height box, so it gets the same
    // baseline the boxed path already receives from rectTextBox. Applied for
    // every alignment, not only the ones that then shift — otherwise Top means
    // "baseline on the origin" while Middle means "block centred on it", and the
    // three do not sit on one ladder.
    if (boxHeight <= 0) y -= fontSizePx * ascent;
    // Shift the block down (y-up) by the slack between box and content. With a
    // zero-height box the slack is -blockHeight, which anchors the block to the origin.
    if (verticalAlign) {
        const slack = boxHeight - lineHeight;
        y -= verticalAlign === 1 ? slack / 2 : slack; // 1 middle, 2 bottom
    }
    // Half-leading. A lineHeight above 1em adds space around the text, and that
    // space belongs half above the first baseline and half below the last — the
    // caller hands us a baseline a flat 0.8em under the line top, which puts all
    // of it below. The block then rides (lineHeight - 1em)/2 too high inside its
    // own box: at the default 1.2, every centred label sits 0.1em above where it
    // should, which on a 60px label is a visible 6px.
    return y - Math.max(0, ((lineHeightPx ?? fontSizePx * 1.2) - fontSizePx) / 2);
}

/**
 * Lay out text against the atlas and emit index-safe quad batches to the sink.
 * Pure given the atlas, so grouping and geometry are unit-testable.
 */
/**
 * Draw a bar under each line. The font has no underline to ask for, but it has an underscore: its middle is a bar of the font's own thickness
 * and depth below the baseline, and a glyph quad can be stretched across the line along that middle (the distance field is flat there).
 */
function addUnderlines(layout: TextLayout, atlas: GlyphAtlas, fontFamily: string, fontSizePx: number, style: number): void {
    if (!layout.lines || layout.lines.length === 0) return;
    const pixelSize = atlas.pixelSizeFor(fontSizePx, fontFamily);
    const g = atlas.getGlyph(0x5f, fontFamily, style, pixelSize);
    if (!g || g.width <= 0 || g.height <= 0) return;
    const scale = fontSizePx / pixelSize;
    const span = g.u1 - g.u0;
    const u0 = g.u0 + span * 0.4, u1 = g.u0 + span * 0.6;
    const top = g.bearingY * scale, bottom = top - g.height * scale;
    for (const line of layout.lines) {
        if (line.width <= 0) continue;
        layout.glyphs.push({
            u0, v0: g.v0, u1, v1: g.v1,
            x0: line.x, x1: line.x + line.width, y0: line.baseline + bottom, y1: line.baseline + top, pageId: g.pageId,
        });
    }
}

/** Glyphs grouped by the atlas page (texture) they sample, each group cut to one
 *  batch's worth — a string can reference glyphs across several pages. */
function pageChunks(glyphs: readonly LaidGlyph[]): Array<[number, readonly LaidGlyph[]]> {
    const byPage = new Map<number, LaidGlyph[]>();
    for (const g of glyphs) {
        let arr = byPage.get(g.pageId);
        if (!arr) { arr = []; byPage.set(g.pageId, arr); }
        arr.push(g);
    }
    const chunks: Array<[number, readonly LaidGlyph[]]> = [];
    for (const [pageId, list] of byPage) {
        for (let start = 0; start < list.length; start += MAX_TEXT_BATCH_GLYPHS) {
            chunks.push([pageId, list.length <= MAX_TEXT_BATCH_GLYPHS
                ? list : list.slice(start, start + MAX_TEXT_BATCH_GLYPHS)]);
        }
    }
    return chunks;
}

/**
 * The outline of laid-out coverage glyphs: each glyph's own cell grown by
 * @p widthPx (text px), placed over the glyph's box grown by the same amount.
 * The radius is asked in rasterized texels, halved to 0.5-texel steps so labels
 * of one size share cells. A quad cut from no glyph (an underline bar) is solid,
 * and grows by simply being drawn larger. Null when any glyph cannot be grown —
 * the caller then has one fallback for the whole label, never a mixed ring.
 */
export function outlineGlyphs(atlas: GlyphAtlas, glyphs: readonly LaidGlyph[], widthPx: number): LaidGlyph[] | null {
    const out: LaidGlyph[] = [];
    for (const g of glyphs) {
        const entry = g.entry;
        if (!entry) {
            out.push({ ...g, color: undefined, x0: g.x0 - widthPx, y0: g.y0 - widthPx, x1: g.x1 + widthPx, y1: g.y1 + widthPx });
            continue;
        }
        if (entry.width <= 0) return null;
        const perTexel = (g.x1 - g.x0) / entry.width;          // text px per rasterized texel
        if (!(perTexel > 0)) return null;
        const radius = Math.max(0.5, Math.round((widthPx / perTexel) * 2) / 2);
        const grown = atlas.outlined(entry, radius);
        if (!grown) return null;
        const grow = ((grown.width - entry.width) / 2) * perTexel;
        out.push({
            u0: grown.u0, v0: grown.v0, u1: grown.u1, v1: grown.v1,
            x0: g.x0 - grow, y0: g.y0 - grow, x1: g.x1 + grow, y1: g.y1 + grow,
            pageId: grown.pageId,
        });
    }
    return out;
}

export function drawTextWith(atlas: GlyphAtlas, sink: GlyphBatchSink, p: DrawTextParams): number {
    if (atlas.metricsOnly) throw new Error('Measurement atlases cannot submit text.');
    const opacity = p.opacity ?? 1;
    if (opacity <= 0) return 0;
    const layout = layoutText(p.text, atlas, p.fontFamily, {
        fontSizePx: p.fontSizePx,
        letterSpacing: p.letterSpacing,
        lineHeight: p.lineHeight,
        align: p.align,
        rich: p.richText,
        color: p.color,
        maxWidth: p.maxWidth,
        boxWidth: p.boxWidth,
        boxHeight: p.boxHeight,
        overflow: p.overflow,
    }, p.style ?? 0);
    if (layout.glyphs.length === 0) return layout.lineHeight;
    if (p.underline) addUnderlines(layout, atlas, p.fontFamily, layout.fontSizePx ?? p.fontSizePx, p.style ?? 0);

    // Position the block within its box: [originX .. originX+boxWidth] × [originY .. -boxHeight].
    // A boxless label (box 0×0) collapses the box to the entity origin, so align/verticalAlign
    // ANCHOR the whole block to it rather than silently doing nothing — one rule, both cases.
    const boxHeight = p.boxHeight ?? 0;
    const boxWidth = p.boxWidth ?? 0;

    // A Shrink label was laid out smaller than it was asked for, so everything measured in em from here — the baseline,
    // half-leading, the outline — is measured in the size it got. A boxed origin already carries 0.8em of the asked-for
    // size (rectTextBox), which is put right.
    const fontSizePx = layout.fontSizePx ?? p.fontSizePx;
    // Where this font puts its baseline under the line top: a bitmap font's own number, 0.8em for the rest.
    const ascent = fontAscent(p.fontFamily, DEFAULT_ASCENT);
    const lineHeightPx = p.lineHeight !== undefined ? p.lineHeight * fontSizePx / p.fontSizePx : undefined;
    const originY = textBlockOriginY(
        (p.originY ?? 0) + (p.originY !== undefined ? (p.fontSizePx - fontSizePx) * ascent : 0),
        boxHeight, layout.lineHeight, fontSizePx, p.verticalAlign, lineHeightPx, ascent,
    );

    // Split oversized pages once, before emitting effects.
    const chunks = pageChunks(layout.glyphs);

    const baseX = (p.originX ?? 0) + textBlockOffsetX(p.align, boxWidth, layout.width);
    // Emit the glyph set once per page, recolored + offset. All passes are SDF
    // glyphs in the same atlas/layer, so they batch and draw in submit order —
    // shadow + outline first (behind), fill last (on top).
    // A font with its outline baked into the page is read through two lenses (see BmFont.outlineInAlpha): Mask for everything
    // that is a shape — shadow, the outline ring — and Fill for the glyph. The page's own colours never show, so the ring is
    // whatever colour the outline asks for, and without an outline there is no ring at all.
    const baked = bitmapFontOf(p.fontFamily)?.outlineInAlpha === true;
    const emitChunks = (set: ReadonlyArray<readonly [number, readonly LaidGlyph[]]>, color: RGBA, dx: number, dy: number,
                        bias = 0, useGlyphColors = false, mode?: TextGlyphMode): void => {
        for (const [pageId, glyphs] of set) {
            const { vertices, indices } = buildGlyphVertices(glyphs, color, baseX + dx, originY + dy, bias, useGlyphColors);
            if (opacity !== 1) {
                for (let i = 7; i < vertices.length; i += TEXT_VERTEX_FLOATS) vertices[i] *= opacity;
            }
            sink(vertices, indices, pageId, mode);
        }
    };
    const emitPass = (color: RGBA, dx: number, dy: number, bias = 0, useGlyphColors = false, mode?: TextGlyphMode): void =>
        emitChunks(chunks, color, dx, dy, bias, useGlyphColors, mode);
    const emitGlyphs = (glyphs: readonly LaidGlyph[], color: RGBA): void => emitChunks(pageChunks(glyphs), color, 0, 0);

    // A label's shadow and outline belong to it: they fade with its own alpha, so
    // a text faded out by its colour leaves no shadow behind (Unity's rule; CSS
    // keeps the shadow, which every fade then had to undo by hand).
    const fillAlpha = Math.max(0, Math.min(1, p.color[3]));
    const decoration = (c: RGBA): RGBA => [c[0], c[1], c[2], c[3] * fillAlpha];

    // Shadow (offset drop copy). y-up local space: a positive screen-down offset
    // moves the copy toward -y.
    if (p.shadow && p.shadow.color[3] * fillAlpha > 0) {
        const { dx, dy } = p.shadow;
        const color = decoration(p.shadow.color);
        const blur = p.shadow.blur ?? 0;
        if (blur > 0) {
            const taps = shadowTaps(blur, fontSizePx);
            const a = tapAlpha(color[3], taps.length);
            const tap: RGBA = [color[0], color[1], color[2], a];
            for (const [ox, oy] of taps) emitPass(tap, dx + ox, -dy + oy, 0, false, baked ? TextGlyphMode.Mask : undefined);
        } else {
            emitPass(color, dx, -dy, 0, false, baked ? TextGlyphMode.Mask : undefined);
        }
    }
    // Outline: the glyphs grown by the width, drawn once behind the fill. On a
    // distance-field atlas the shader grows them (the edge it reads is moved), so
    // the shape survives any width. A coverage atlas has no distance to move, so
    // it places each glyph grown into its own cell (GlyphAtlas.outlined) — a ring,
    // where stamping eight offset copies drew the label eight more times.
    const outlineColor = p.outline ? decoration(p.outline.color) : null;
    if (baked) {
        // The page has the ring already: it is drawn, not grown, so the width only says whether there is one.
        if (p.outline && p.outline.width > 0 && outlineColor![3] > 0) emitPass(outlineColor!, 0, 0, 0, false, TextGlyphMode.Mask);
    } else if (p.outline && p.outline.width > 0 && outlineColor![3] > 0) {
        const w = p.outline.width;
        const bias = outlineBias(atlas, fontSizePx, w);
        const ring = bias > 0 ? null : outlineGlyphs(atlas, layout.glyphs, w);
        if (bias > 0) emitPass(outlineColor!, 0, 0, bias);
        else if (ring) emitGlyphs(ring, outlineColor!);
        // A glyph the atlas cannot grow (a bitmap font without a baked ring) keeps the stamp.
        else for (const [ox, oy] of OUTLINE_OFFSETS) emitPass(outlineColor!, ox * w, oy * w);
    }
    // Fill (on top).
    emitPass(p.color, 0, 0, 0, true, baked ? TextGlyphMode.Fill : undefined);
    return layout.lineHeight;
}

export interface TextRendererOptions extends CanvasGlyphRasterizerOptions {
    /** Cache glyph metrics without creating or uploading GPU pages. */
    metricsOnly?: boolean;
    /** Atlas page size in texels. Default 1024. */
    pageSize?: number;
    /** Device pixel ratio for bitmap-mode per-size rasterization. Default 1. */
    dpr?: number;
}

/** One laid-out, tessellated page batch in the entity's local (untransformed) space. */
interface CachedTextBatch extends TextCullGeometry {
    vertices: Float32Array;
    indices: Uint16Array;
    pageId: number;
    /** How the page is read; absent means the renderer's own kind. */
    mode?: TextGlyphMode;
    /** Original vertex alphas, retained lazily so repeated fades never compound. */
    alphas?: Float32Array;
}

interface TextCacheEntry {
    sig: string;
    /** Atlas generation the geometry was built against (bitmap content-scale). */
    gen: number;
    batches: CachedTextBatch[];
    opacity: number;
}

export class SdfTextRenderer {
    readonly atlas: GlyphAtlas;
    private readonly sdf: boolean;
    /** How a batch with no mode of its own is read: by the kind of atlas this renderer keeps. */
    private get defaultMode(): TextGlyphMode { return this.sdf ? TextGlyphMode.Sdf : TextGlyphMode.Color; }
    private readonly cache_ = new Map<number, TextCacheEntry>();
    private readonly clipPlanes_ = new Float64Array(36);
    private readonly drawn_ = new Set<number>();
    /** The atlas pages the retained labels of this renderer draw from, so the pages outlive the frames the labels are not rebuilt in. */
    private readonly retainedPages_ = new Map<number, number[]>();
    /** Pages held for glyphs not on screen yet, by the preload holding them. */
    private readonly pinnedPages_ = new Map<object, Set<number>>();

    /** `module` is null on the native core (no wasm heap); the glyph source is
     *  then the platform's own rasterizer, since there is no 2D canvas to draw
     *  glyphs on. Everything above the rasterizer — atlas, layout, batching — is
     *  the same code either way. */
    constructor(private readonly module: ESEngineModule | null, opts: TextRendererOptions = {}) {
        this.sdf = opts.sdf ?? true;
        const rasterizer = platformHasGlyphRasterizer()
            ? new NativeGlyphRasterizer({ renderSize: opts.renderSize, padding: opts.padding, sdf: this.sdf })
            : new CanvasGlyphRasterizer(module, { ...opts, maxGlyphSize: Math.min(opts.maxGlyphSize ?? Infinity, opts.pageSize ?? 1024) });
        this.atlas = new GlyphAtlas(
            rasterizer,
            opts.metricsOnly ? null : new EngineAtlasPageStore(module),
            { pageSize: opts.pageSize, sdf: this.sdf, dpr: opts.dpr },
        );
    }

    /** See {@link GlyphAtlas.setContentScale} — no-op for the SDF atlas. */
    setContentScale(scale: number): void {
        this.atlas.setContentScale(scale);
    }

    setDevicePixelRatio(dpr: number): void {
        this.atlas.setDevicePixelRatio(dpr);
    }

    /** Previous frame has submitted; remove unused layouts and their GPU pages. */
    beginFrame(): void {
        if (this.atlas.metricsOnly) return;
        for (const entity of this.cache_.keys()) {
            if (!this.drawn_.has(entity)) this.cache_.delete(entity);
        }
        const pages = new Set<number>();
        for (const entry of this.cache_.values()) {
            for (const batch of entry.batches) pages.add(batch.pageId);
        }
        for (const list of this.retainedPages_.values()) for (const pageId of list) pages.add(pageId);
        for (const pinned of this.pinnedPages_.values()) for (const pageId of pinned) pages.add(pageId);
        this.drawn_.clear();
        this.atlas.retainPages(pages);
    }

    /**
     * Put a glyph on the atlas for text that is not drawn yet, at the size a layout of @p fontSizePx will ask for, and hold its page for
     * @p holder: nothing refers to a page of preloaded glyphs, and the next beginFrame would release it.
     */
    preloadGlyph(holder: object, codepoint: number, fontFamily: string, style: number, fontSizePx: number): void {
        const glyph = this.atlas.getGlyph(codepoint, fontFamily, style, this.atlas.pixelSizeFor(fontSizePx, fontFamily));
        if (!glyph || glyph.width <= 0) return;
        let pinned = this.pinnedPages_.get(holder);
        if (!pinned) this.pinnedPages_.set(holder, pinned = new Set());
        pinned.add(glyph.pageId);
    }

    /** Let go of the pages @p holder was holding: the next beginFrame releases those no text uses. */
    releasePreload(holder: object): void {
        this.pinnedPages_.delete(holder);
    }

    dispose(): void {
        this.drawn_.clear();
        this.cache_.clear();
        this.pinnedPages_.clear();
        this.retainedPages_.clear();
        this.atlas.dispose();
    }

    /**
     * Draw a line of text. `transform` is the entity's column-major world mat4;
     * glyph local positions (baseline y=0, y-up) are transformed at submit.
     *
     * The tessellated geometry is local-space (transform-independent), so it is
     * cached per entity keyed by the layout signature + atlas generation: a static
     * label re-submits its cached quads with the current transform each frame
     * instead of re-laying-out and re-tessellating every glyph.
     */
    drawText(
        p: DrawTextParams,
        transform: Float32Array,
        entity: number,
        layer: number,
        depth: number,
        cullBit = 0,
        viewProjection?: Float32Array,
    ): void {
        if (this.atlas.metricsOnly) throw new Error('Measurement atlases cannot submit text.');
        const opacity = p.opacity ?? 1;
        if (opacity <= 0) return;
        this.drawn_.add(entity);
        const gen = this.atlas.generation;
        const sig = textSignature(p, 1);
        let entry = this.cache_.get(entity);
        if (!entry || entry.gen !== gen || entry.sig !== sig) {
            const batches: CachedTextBatch[] = [];
            drawTextWith(this.atlas, (vertices, indices, pageId, mode) => {
                batches.push({ ...createTextCullGeometry(vertices, indices), pageId, ...(mode !== undefined ? { mode } : {}) });
            }, { ...p, opacity: 1 });
            entry = { sig, gen, batches, opacity: 1 };
            this.cache_.set(entity, entry);
        }
        const planes = viewProjection && textClipPlanes(this.clipPlanes_, viewProjection, transform) ? this.clipPlanes_ : null;
        for (const b of entry.batches) {
            if (entry.opacity !== opacity) {
                if (!b.alphas) {
                    b.alphas = new Float32Array(b.vertices.length / TEXT_VERTEX_FLOATS);
                    for (let i = 0; i < b.alphas.length; i++) b.alphas[i] = b.vertices[i * TEXT_VERTEX_FLOATS + 7];
                }
                for (let i = 0; i < b.alphas.length; i++) {
                    b.vertices[i * TEXT_VERTEX_FLOATS + 7] = b.alphas[i] * opacity;
                }
            }
            const visible = clipTextGeometry(b, planes);
            if (visible) submitTextBatch(this.module, visible.vertices, visible.indices, b.pageId, transform, entity, layer, depth, b.mode ?? this.defaultMode, cullBit);
        }
        entry.opacity = opacity;
    }

    /** Drop cached geometry for entities not drawn this frame (despawned / hidden / no longer text). */
    /**
     * Lay a label out and hand its glyph quads to the engine, which keeps them and submits them every frame (see RetainedText.hpp). Called when the
     * label is new or changed; an unchanged label costs the engine's own loop and nothing here beyond {@link markDrawn}.
     */
    retain(
        api: EngineApi, p: DrawTextParams, entity: number,
        screen: boolean, hasBox: boolean, layer: number, boxWidth: number, boxHeight: number, autoKind: boolean,
    ): number {
        if (this.atlas.metricsOnly) throw new Error('Measurement atlases cannot submit text.');
        const batches: Array<{ vertices: Float32Array; indices: Uint16Array; pageId: number; mode?: TextGlyphMode }> = [];
        const blockHeight = drawTextWith(this.atlas, (vertices, indices, pageId, mode) => {
            batches.push({ vertices, indices, pageId, ...(mode !== undefined ? { mode } : {}) });
        }, { ...p, opacity: 1 });
        api.renderer_retainedTextBegin!(entity, this.sdf ? 1 : 0, screen ? 1 : 0, hasBox ? 1 : 0, layer, boxWidth, boxHeight, autoKind ? 1 : 0);
        for (const b of batches) {
            const vertexCount = (b.vertices.length / TEXT_VERTEX_FLOATS) | 0;
            if (vertexCount <= 0 || b.indices.length <= 0) continue;
            const vBytes = new Uint8Array(b.vertices.buffer, b.vertices.byteOffset, b.vertices.byteLength);
            const iBytes = new Uint8Array(b.indices.buffer, b.indices.byteOffset, b.indices.byteLength);
            withScratch({ _malloc: size => api._malloc!(size), _free: ptr => api._free!(ptr) }, alloc => {
                const vPtr = alloc(vBytes.byteLength);
                const iPtr = alloc(iBytes.byteLength);
                api.HEAPU8!.set(vBytes, vPtr);
                api.HEAPU8!.set(iBytes, iPtr);
                api.renderer_retainedTextBatch!(entity, vPtr, vertexCount, iPtr, b.indices.length, b.pageId, b.mode ?? this.defaultMode);
            });
        }
        this.retainedPages_.set(entity, batches.map(b => b.pageId));
        this.drawn_.add(entity);
        this.cache_.delete(entity);
        return blockHeight;
    }

    /** A retained label that is not rebuilt this frame is still on screen: its atlas pages must stay. */
    markDrawn(entity: number): void {
        this.drawn_.add(entity);
    }

    /** Release what a retained label held here (the engine's copy is cleared by the caller). */
    forget(entity: number): void {
        this.retainedPages_.delete(entity);
        this.drawn_.delete(entity);
    }

    retainOnly(live: Set<number>): void {
        if (this.cache_.size === 0) return;
        for (const e of this.cache_.keys()) {
            if (!live.has(e)) this.cache_.delete(e);
        }
    }
}

/** Serialize every DrawTextParams field that affects the laid-out, colored geometry. */
export function signatureOf(p: DrawTextParams): string {
    return textSignature(p, p.opacity ?? 1);
}

function textSignature(p: DrawTextParams, opacity: number): string {
    const shadow = p.shadow
        ? `${p.shadow.color.join(',')}:${p.shadow.dx}:${p.shadow.dy}:${p.shadow.blur ?? 0}`
        : '';
    const outline = p.outline ? `${p.outline.color.join(',')}:${p.outline.width}` : '';
    return JSON.stringify([
        p.text, p.fontFamily, p.fontSizePx, p.style ?? 0,
        p.richText ? 1 : 0, p.align ?? 0, p.verticalAlign ?? 0,
        p.lineHeight ?? 0, p.letterSpacing ?? 0,
        p.maxWidth ?? 0, p.boxWidth ?? 0, p.boxHeight ?? 0,
        p.overflow ?? TextOverflow.Visible, p.underline ? 1 : 0,
        p.originX ?? 0, p.originY ?? 0,
        p.color.join(','), opacity, shadow, outline,
    ]);
}