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.
TypeScript 2d-game-engine3d3d-game-engineandroidcppecsgame-editorgame-enginegamedeviostypescriptwebassemblywebglwebgpuwechat-minigame
// SPDX-License-Identifier: Apache-2.0
// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
/**
* @file ui/text/layout.ts
* @brief Pure text layout + glyph-quad vertex building for the SDF text path
* (TS-centric). Given the glyph atlas (which supplies
* per-glyph atlas UVs + metrics), turn a string into positioned quads
* and then into the interleaved vertex/index buffers `submitTextBatch`
* expects. No Canvas/GL here, so it is fully unit-testable.
*
* Conventions: local space, baseline at y = 0, y-up (glyph tops are positive y);
* positions are pre-transform (the entity world matrix is applied at submit).
* Glyph metrics from the atlas are in renderSize px; everything scales by
* displaySize / atlas.renderSize (SDF is resolution-independent).
*/
import type { GlyphAtlas, GlyphEntry } from './glyph-atlas';
import { TEXT_VERTEX_FLOATS } from './submit';
import { parseRichText, type TextSegment, type ImageSegment, type RichTextRun } from './rich-text-parser';
import { UI_TEXT_BOLD, UI_TEXT_ITALIC } from './text-transform';
import { TextAlign, TextOverflow } from '../core/text';
export interface TextLayoutOptions {
/** Display font size in px. */
fontSizePx: number;
/** Extra advance between glyphs, in display px. */
letterSpacing?: number;
}
/** RGBA color, channels in [0,1]. */
export type RGBA = readonly [number, number, number, number];
/** One positioned glyph quad: atlas UVs + local-space corners (y-up). `color` is
* set only by rich text (per-run); single-style layout leaves it for the caller. */
export interface LaidGlyph {
u0: number; v0: number; u1: number; v1: number;
x0: number; y0: number; // bottom-left
x1: number; y1: number; // top-right
pageId: number;
color?: RGBA;
/** The atlas entry the quad was cut from — what an outline of the glyph is grown from. */
entry?: GlyphEntry;
}
/** One placed inline `<img>` run: a box in the same local space as glyphs
* (y-up; (x,y) is the bottom-left corner). `src` is the image reference the
* renderer resolves to a texture; `tint` recolors it (null = untinted). */
export interface LaidImage {
src: string;
x: number;
y: number;
w: number;
h: number;
tint: RGBA | null;
}
/** Where one laid-out line sits: its left edge and width, and the baseline, in the same y-up local space as the glyphs. */
export interface LaidLine {
x: number;
width: number;
baseline: number;
}
export interface TextLayout {
glyphs: LaidGlyph[];
/** Each line's extent, top to bottom. Undefined for a layout that is a single line laid out on its own. */
lines?: LaidLine[];
/** Inline `<img>` placements (rich text only). Undefined/empty = none. */
images?: LaidImage[];
/** Total pen advance (display px). */
width: number;
/** Line height (display px). */
lineHeight: number;
/** The font size the text was laid out at, when that is not the one asked for ({@link TextOverflow.Shrink}). */
fontSizePx?: number;
}
/**
* Lay out a single line of text against the atlas. Glyphs missing from the
* atlas (unproducible) are skipped; whitespace advances the pen without a quad.
*/
export function layoutLine(
text: string,
atlas: GlyphAtlas,
fontFamily: string,
opts: TextLayoutOptions,
style = 0,
): TextLayout {
const pixelSize = atlas.pixelSizeFor(opts.fontSizePx, fontFamily);
const scale = opts.fontSizePx / pixelSize;
const spacing = opts.letterSpacing ?? 0;
const glyphs: LaidGlyph[] = [];
let penX = 0;
for (const ch of text) {
const cp = ch.codePointAt(0);
if (cp === undefined) continue;
const g = atlas.getGlyph(cp, fontFamily, style, pixelSize);
if (!g) continue;
if (g.width > 0 && g.height > 0) {
const x0 = penX + g.bearingX * scale;
const y1 = g.bearingY * scale; // top, above baseline
const x1 = x0 + g.width * scale;
const y0 = y1 - g.height * scale; // bottom
glyphs.push({ u0: g.u0, v0: g.v0, u1: g.u1, v1: g.v1, x0, y0, x1, y1, pageId: g.pageId, entry: g });
}
penX += g.advance * scale + spacing;
}
return { glyphs, width: penX, lineHeight: opts.fontSizePx };
}
export interface GlyphVertexData {
vertices: Float32Array; // TEXT_VERTEX_FLOATS per vertex, 4 verts/glyph
indices: Uint16Array; // 6 per glyph
}
/** Four vertices per glyph must fit the text-submit ABI's Uint16 indices. */
export const MAX_TEXT_BATCH_GLYPHS = 0x10000 / 4;
/**
* Build interleaved glyph vertices and indices, with atlas v0 at screen-top.
* `originX/Y` positions the batch inside its text box. Disable per-glyph colors
* when recoloring shadow and outline passes.
*/
export function buildGlyphVertices(
glyphs: readonly LaidGlyph[],
color: RGBA,
originX = 0,
originY = 0,
sdfBias = 0,
useGlyphColors = true,
): GlyphVertexData {
const n = glyphs.length;
if (n > MAX_TEXT_BATCH_GLYPHS) throw new RangeError('Glyph batch exceeds the Uint16 index range; split it before tessellation');
const vertices = new Float32Array(n * 4 * TEXT_VERTEX_FLOATS);
const indices = new Uint16Array(n * 6);
for (let i = 0; i < n; i++) {
const gl = glyphs[i];
const [r, g, b, a] = (useGlyphColors ? gl.color : undefined) ?? color;
const x0 = gl.x0 + originX, x1 = gl.x1 + originX;
const y0 = gl.y0 + originY, y1 = gl.y1 + originY;
const vo = i * 4 * TEXT_VERTEX_FLOATS;
// BL, BR, TR, TL — UV V uses v1 at the bottom, v0 at the top.
writeVertex(vertices, vo + 0 * TEXT_VERTEX_FLOATS, x0, y0, gl.u0, gl.v1, r, g, b, a, sdfBias);
writeVertex(vertices, vo + 1 * TEXT_VERTEX_FLOATS, x1, y0, gl.u1, gl.v1, r, g, b, a, sdfBias);
writeVertex(vertices, vo + 2 * TEXT_VERTEX_FLOATS, x1, y1, gl.u1, gl.v0, r, g, b, a, sdfBias);
writeVertex(vertices, vo + 3 * TEXT_VERTEX_FLOATS, x0, y1, gl.u0, gl.v0, r, g, b, a, sdfBias);
const io = i * 6, vb = i * 4;
indices[io] = vb; indices[io + 1] = vb + 1; indices[io + 2] = vb + 2;
indices[io + 3] = vb; indices[io + 4] = vb + 2; indices[io + 5] = vb + 3;
}
return { vertices, indices };
}
function writeVertex(
out: Float32Array, o: number,
x: number, y: number, u: number, v: number,
r: number, g: number, b: number, a: number, sdfBias: number,
): void {
out[o] = x; out[o + 1] = y; out[o + 2] = u; out[o + 3] = v;
out[o + 4] = r; out[o + 5] = g; out[o + 6] = b; out[o + 7] = a;
out[o + 8] = sdfBias;
}
export interface RichTextLayoutOptions extends TextLayoutOptions {
/** Base color for runs that don't set their own <color=...>. */
color: RGBA;
}
/** Horizontal alignment: 0 = left, 1 = center, 2 = right. */
export const TEXT_ALIGN_LEFT = 0;
export const TEXT_ALIGN_CENTER = 1;
export const TEXT_ALIGN_RIGHT = 2;
export interface MultilineTextOptions extends TextLayoutOptions {
/** Baseline-to-baseline distance in px. Default fontSizePx * 1.2. */
lineHeight?: number;
/** Horizontal alignment, defaulting to left. */
align?: TextAlign;
/** Parse rich markup (`<b>` etc.) per line. */
rich?: boolean;
/** Base color (used by rich runs without their own color). */
color?: RGBA;
/** Word-wrap width in display px (plain and rich text). 0/undefined = no wrap. */
maxWidth?: number;
/**
* Width (display px) each line is horizontally aligned within — the layout box.
* Defaults to `maxWidth`, else the widest line. Separating it from `maxWidth` lets
* horizontal align work inside a fixed box even when word-wrap is off.
*/
boxWidth?: number;
/** Height (display px) of the layout box, for {@link overflow}. 0/undefined =
* no box, so nothing can overflow one. */
boxHeight?: number;
/**
* What a run too big for the box does. Needs `boxHeight` to drop lines and a
* width to trim one. The component's own spelling, not a mirror of it: three
* numbers written twice are two answers the day somebody reorders them.
*/
overflow?: TextOverflow;
}
/** The character appended to a line the ellipsis mode cut. */
const ELLIPSIS = '\u2026';
/** Trim at codepoint boundaries using shared prefix advances, including the mark. */
function truncateLine(
line: string, measure: (s: string) => number, limit: number, ellipsis: boolean,
measurePrefixes: (s: string) => readonly number[],
): string {
if (limit <= 0 || measure(line) <= limit) return line;
const tail = ellipsis ? ELLIPSIS : '';
const tailWidth = measure(tail);
const widths = measurePrefixes(line);
const chars = [...line];
const ends = [0];
for (const ch of chars) ends.push(ends[ends.length - 1]! + ch.length);
for (let count = chars.length - 1; count >= 0; count--) {
while (count > 0 && chars[count - 1]!.trimEnd() === '') count--;
const end = ends[count]!;
if (widths[end]! + tailWidth <= limit) return line.slice(0, end) + tail;
}
return tail;
}
/** Sum of glyph advances for a string at the given size (display px). Pure. */
export function measureWidth(
text: string, atlas: GlyphAtlas, fontFamily: string, fontSizePx: number, style: number, letterSpacing = 0,
): number {
const pixelSize = atlas.pixelSizeFor(fontSizePx, fontFamily);
const scale = fontSizePx / pixelSize;
let w = 0;
for (const ch of text) {
const cp = ch.codePointAt(0);
if (cp === undefined) continue;
const g = atlas.getGlyph(cp, fontFamily, style, pixelSize);
if (g) w += g.advance * scale + letterSpacing;
}
return w;
}
/** UTF-16 prefix widths for caret placement, measured in one pass. */
export function measurePrefixWidths(
text: string, atlas: GlyphAtlas, fontFamily: string, fontSizePx: number, style: number, letterSpacing = 0,
): number[] {
const pixelSize = atlas.pixelSizeFor(fontSizePx, fontFamily);
const scale = fontSizePx / pixelSize;
const advance = (cp: number): number => {
const glyph = atlas.getGlyph(cp, fontFamily, style, pixelSize);
return glyph ? glyph.advance * scale + letterSpacing : 0;
};
const widths = new Array<number>(text.length + 1);
widths[0] = 0;
let width = 0;
for (let i = 0; i < text.length;) {
const cp = text.codePointAt(i)!;
if (cp > 0xffff) {
// A textarea can address the boundary between a surrogate pair.
// Match measuring that truncated prefix, without adding it to the
// complete code point's advance.
widths[i + 1] = width + advance(text.charCodeAt(i));
width += advance(cp);
i += 2;
} else {
width += advance(cp);
i++;
}
widths[i] = width;
}
return widths;
}
/**
* Greedy word-wrap using an arbitrary width `measure` (display px). Breaks at
* spaces; a token wider than the line (long word, or CJK runs with no spaces) is
* broken character-by-character. The single source of wrap truth — the
* atlas-backed {@link wrapLine} and the Canvas2D-backed `measureText` both call
* it, so measured heights match rendered wraps.
*/
export function wrapByMeasure(
text: string, measure: (s: string) => number, maxWidth: number,
appendWidth?: (width: number, suffix: string) => number,
): string[] {
return wrapMeasured(text, measure, maxWidth, appendWidth);
}
function wrapMeasured(
text: string, measure: (s: string) => number, maxWidth: number,
appendWidth?: (width: number, suffix: string) => number,
): string[] {
const out: string[] = [];
let cur = '';
let curWidth = 0;
const flush = () => { const t = cur.replace(/\s+$/, ''); if (t) out.push(t); cur = ''; curWidth = 0; };
const appended = (suffix: string) => appendWidth ? appendWidth(curWidth, suffix) : measure(cur + suffix);
const charBreak = (token: string) => {
for (const ch of token) {
let width = cur ? appended(ch) : appendWidth?.(0, ch) ?? 0;
if (cur && width > maxWidth) {
flush();
width = appendWidth?.(0, ch) ?? 0;
}
cur += ch;
curWidth = width;
}
};
for (const token of text.split(/(\s+)/)) {
if (token === '') continue;
if (/^\s+$/.test(token)) {
if (cur) { if (appendWidth) curWidth = appendWidth(curWidth, token); cur += token; }
continue;
}
if (!cur) {
const width = measure(token);
if (width <= maxWidth) { cur = token; curWidth = width; }
else charBreak(token);
} else {
const width = appended(token);
if (width <= maxWidth) { cur += token; curWidth = width; }
else {
flush();
const tokenWidth = measure(token);
if (tokenWidth <= maxWidth) { cur = token; curWidth = tokenWidth; }
else charBreak(token);
}
}
}
flush();
return out.length ? out : [''];
}
/** Greedy wrap using ordered glyph advances without remeasuring the current line. */
export function wrapLine(
text: string, atlas: GlyphAtlas, fontFamily: string, fontSizePx: number,
style: number, maxWidth: number, letterSpacing = 0,
): string[] {
const pixelSize = atlas.pixelSizeFor(fontSizePx, fontFamily);
const scale = fontSizePx / pixelSize;
const append = (width: number, suffix: string): number => {
for (const ch of suffix) {
const glyph = atlas.getGlyph(ch.codePointAt(0)!, fontFamily, style, pixelSize);
if (glyph) width += glyph.advance * scale + letterSpacing;
}
return width;
};
return wrapMeasured(text, s => append(0, s), maxWidth, append);
}
/**
* The largest whole-pixel font size, at most the one asked for, at which the text fits its box: no taller than
* `boxHeight` and no wider than `boxWidth` (each only when given). Line height and letter spacing scale with the
* size, as they do for a label the author sized by hand. Never below 1px: a box too small for anything shows
* the smallest text rather than none.
*
* Fitting is assumed to get easier as type gets smaller, which holds for wrapping text (fewer, shorter lines) and
* lets a binary search stand in for trying every size.
*/
export function shrinkFontSize(
text: string, atlas: GlyphAtlas, fontFamily: string, opts: MultilineTextOptions, style = 0,
): number {
const base = opts.fontSizePx;
const width = opts.boxWidth ?? 0;
const height = opts.boxHeight ?? 0;
if (!(base > 1) || (!(width > 0) && !(height > 0))) return base;
const fits = (size: number): boolean => {
const laid = layoutText(text, atlas, fontFamily, scaledTo(opts, size), style);
return (!(height > 0) || laid.lineHeight <= height + 1e-6) && (!(width > 0) || laid.width <= width + 1e-6);
};
const whole = Math.floor(base);
if (fits(whole)) return base;
let lo = 1; // the smallest size we will answer with, whether or not it fits
let hi = whole - 1; // known not to fit at `whole`
while (lo < hi) {
const mid = Math.ceil((lo + hi) / 2);
if (fits(mid)) lo = mid; else hi = mid - 1;
}
return lo;
}
/** The same layout request at another font size: line height and letter spacing follow, and nothing is clipped. */
function scaledTo(opts: MultilineTextOptions, size: number): MultilineTextOptions {
const k = size / opts.fontSizePx;
return {
...opts,
fontSizePx: size,
...(opts.lineHeight !== undefined ? { lineHeight: opts.lineHeight * k } : {}),
...(opts.letterSpacing !== undefined ? { letterSpacing: opts.letterSpacing * k } : {}),
overflow: TextOverflow.Visible,
};
}
/**
* Lay out multi-line text: splits on `\n`, lays each line out
* (rich or plain), stacks lines downward (y-up: line 0 on top) by `lineHeight`,
* and horizontally aligns each line within the widest line's block. Pure →
* unit-testable. (Word-wrap to a max width is a later addition.)
*/
export function layoutText(
text: string,
atlas: GlyphAtlas,
fontFamily: string,
opts: MultilineTextOptions,
style = 0,
): TextLayout {
if (opts.overflow === TextOverflow.Shrink) {
const size = shrinkFontSize(text, atlas, fontFamily, opts, style);
const fitted = layoutText(text, atlas, fontFamily, scaledTo(opts, size), style);
return size === opts.fontSizePx ? fitted : { ...fitted, fontSizePx: size };
}
const lineHeight = opts.lineHeight ?? opts.fontSizePx * 1.2;
const align = opts.align ?? TEXT_ALIGN_LEFT;
const baseColor = opts.color ?? ([1, 1, 1, 1] as const);
const rawLines = text.split('\n');
const wrap = !!(opts.maxWidth && opts.maxWidth > 0);
const richOpts = { fontSizePx: opts.fontSizePx, letterSpacing: opts.letterSpacing, color: baseColor };
// Word-wrap before stacking; explicit \n still hard-breaks. Rich lines wrap
// at the styled-run level so a token measures with its own size/style. Inline
// images survive the no-wrap path; wrapping is text-only (images drop) for now.
// How many lines the box has room for. Below Visible only, and never zero: a
// box too short for one line shows one clipped line rather than nothing, which
// is what every layout engine does and what a reader can act on.
const overflow = opts.overflow ?? TextOverflow.Visible;
const boxHeight = opts.boxHeight ?? 0;
// ResizeHeight keeps every line (the box grows to them) and every character (nothing is trimmed).
const keepsAll = overflow === TextOverflow.Visible || overflow === TextOverflow.ResizeHeight;
const maxLines = !keepsAll && boxHeight > 0
? Math.max(1, Math.floor(boxHeight / lineHeight))
: Infinity;
const ellipsis = overflow === TextOverflow.Ellipsis;
// The width a line may not exceed. maxWidth already wrapped to it, so this is
// for the unwrapped case — a single line in a fixed box, which is the one
// ellipsis is usually asked for.
const widthLimit = keepsAll ? 0
: (opts.maxWidth && opts.maxWidth > 0) ? opts.maxWidth
: (opts.boxWidth ?? 0);
let lineLayouts: TextLayout[];
if (opts.rich) {
// Rich text truncates by line only: trimming one means measuring per run,
// and a run's own size and style make that a different calculation.
const richLines = rawLines
.map(l => parseRichText(l))
.flatMap(runs => (wrap
? wrapRichRuns(runs.filter((r): r is TextSegment => r.type === 'text'), atlas, fontFamily, opts.fontSizePx, style, opts.maxWidth!, opts.letterSpacing ?? 0)
: [runs]));
const kept = richLines.slice(0, maxLines === Infinity ? undefined : maxLines);
if (ellipsis && kept.length < richLines.length && kept.length > 0) {
kept[kept.length - 1] = [...kept[kept.length - 1], { type: 'text', text: ELLIPSIS } as TextSegment];
}
lineLayouts = kept.map(runs => layoutRichRuns(runs, atlas, fontFamily, richOpts, style));
} else {
const plainLines = wrap
? rawLines.flatMap(l => wrapLine(l, atlas, fontFamily, opts.fontSizePx, style, opts.maxWidth!, opts.letterSpacing ?? 0))
: rawLines;
const kept = plainLines.slice(0, maxLines === Infinity ? undefined : maxLines);
const dropped = kept.length < plainLines.length;
const measure = (t: string) => measureWidth(t, atlas, fontFamily, opts.fontSizePx, style, opts.letterSpacing ?? 0);
const prefixes = (t: string) => measurePrefixWidths(t, atlas, fontFamily, opts.fontSizePx, style, opts.letterSpacing ?? 0);
const cut = kept.map((line, i) => {
const last = i === kept.length - 1;
// The last kept line carries the ellipsis when lines were dropped, even
// if it fits: the mark says "there is more", not "this line was long".
if (dropped && last && ellipsis) return truncateLine(line + ELLIPSIS, measure, widthLimit || Infinity, true, prefixes);
return widthLimit > 0 ? truncateLine(line, measure, widthLimit, ellipsis, prefixes) : line;
});
lineLayouts = cut.map(line => layoutLine(line, atlas, fontFamily, opts, style));
}
const lines = lineLayouts; // line count only below
const contentWidth = lineLayouts.reduce((m, l) => Math.max(m, l.width), 0);
// Align within the layout box when one is given (independent of word-wrap), then
// the wrap width, else the widest line.
const alignWidth = (opts.boxWidth && opts.boxWidth > 0) ? opts.boxWidth
: (opts.maxWidth && opts.maxWidth > 0) ? opts.maxWidth
: contentWidth;
const glyphs: LaidGlyph[] = [];
const images: LaidImage[] = [];
const laidLines: LaidLine[] = [];
for (let i = 0; i < lineLayouts.length; i++) {
const ll = lineLayouts[i];
const dx = align === TEXT_ALIGN_CENTER ? (alignWidth - ll.width) / 2
: align === TEXT_ALIGN_RIGHT ? (alignWidth - ll.width)
: 0;
const dy = -i * lineHeight; // y-up: first line on top
laidLines.push({ x: dx, width: ll.width, baseline: dy });
for (const g of ll.glyphs) {
glyphs.push({ ...g, x0: g.x0 + dx, x1: g.x1 + dx, y0: g.y0 + dy, y1: g.y1 + dy });
}
if (ll.images) {
for (const im of ll.images) images.push({ ...im, x: im.x + dx, y: im.y + dy });
}
}
return { glyphs, images, lines: laidLines, width: contentWidth, lineHeight: lines.length * lineHeight };
}
/**
* Lay out a single line of rich text: `<b>`, `<i>`, `<color=#rrggbb[aa]>`,
* `<font size=N>` runs (parsed by parseRichText) become glyphs carrying per-run
* color + size + bold/italic style, and `<img>` runs become inline image boxes.
* Each run scales by its own fontSize / atlas.renderSize; all share the baseline
* (y = 0). Pure → unit-testable.
*/
export function layoutRichLine(
content: string,
atlas: GlyphAtlas,
fontFamily: string,
opts: RichTextLayoutOptions,
baseStyle = 0,
): TextLayout {
return layoutRichRuns(parseRichText(content), atlas, fontFamily, opts, baseStyle);
}
/** Measure a styled run's advance width (mirrors layoutRichRuns' pen math). */
function measureRun(
text: string, run: TextSegment, atlas: GlyphAtlas, fontFamily: string,
baseSizePx: number, baseStyle: number, spacing: number,
): number {
const runSize = run.fontSize ?? baseSizePx;
const pixelSize = atlas.pixelSizeFor(runSize, fontFamily);
const scale = runSize / pixelSize;
const style = baseStyle | (run.bold ? UI_TEXT_BOLD : 0) | (run.italic ? UI_TEXT_ITALIC : 0);
let w = 0;
for (const ch of text) {
const cp = ch.codePointAt(0);
if (cp === undefined) continue;
const gph = atlas.getGlyph(cp, fontFamily, style, pixelSize);
if (gph) w += gph.advance * scale + spacing;
}
return w;
}
/**
* Greedy word-wrap over styled runs: tokens measure with their own run's
* size/style, breaks land at spaces (a single oversized token breaks
* character-by-character), and each output line is a run list ready for
* {@link layoutRichRuns}. The plain-text twin is {@link wrapLine}.
*/
export function wrapRichRuns(
runs: TextSegment[], atlas: GlyphAtlas, fontFamily: string,
baseSizePx: number, baseStyle: number, maxWidth: number, spacing = 0,
): TextSegment[][] {
interface Token { run: TextSegment; text: string; space: boolean }
const tokens: Token[] = [];
for (const run of runs) {
for (const part of run.text.split(/(\s+)/)) {
if (part === '') continue;
tokens.push({ run, text: part, space: /^\s+$/.test(part) });
}
}
const lines: TextSegment[][] = [];
let cur: Token[] = [];
let curWidth = 0;
const measure = (t: Token) =>
measureRun(t.text, t.run, atlas, fontFamily, baseSizePx, baseStyle, spacing);
const flush = () => {
while (cur.length > 0 && cur[cur.length - 1]!.space) cur.pop();
// Merge adjacent tokens of the same run back into segments.
const segs: TextSegment[] = [];
for (const t of cur) {
const last = segs[segs.length - 1];
if (last && last.bold === t.run.bold && last.italic === t.run.italic
&& last.color === t.run.color && last.fontSize === t.run.fontSize) {
last.text += t.text;
} else {
segs.push({ ...t.run, text: t.text });
}
}
if (segs.length > 0) lines.push(segs);
cur = [];
curWidth = 0;
};
const push = (t: Token) => { cur.push(t); curWidth += measure(t); };
const charBreak = (t: Token) => {
for (const ch of t.text) {
const w = measureRun(ch, t.run, atlas, fontFamily, baseSizePx, baseStyle, spacing);
if (cur.length > 0 && curWidth + w > maxWidth) flush();
push({ run: t.run, text: ch, space: false });
}
};
for (const t of tokens) {
if (t.space) {
if (cur.length > 0) push(t); // keep inter-word spaces, drop leading
continue;
}
const w = measure(t);
if (cur.length === 0) {
if (w <= maxWidth) push(t);
else charBreak(t);
} else if (curWidth + w <= maxWidth) {
push(t);
} else {
flush();
if (w <= maxWidth) push(t);
else charBreak(t);
}
}
flush();
return lines.length ? lines : [[]];
}
/** Place an `<img>` run's box on the pen. y-up local space, baseline at y = 0;
* `valign` picks the vertical anchor (ascent ≈ size×0.8, descent ≈ size×0.2),
* `offsetX/Y` nudge it, `scale` sizes it. The pen advances by the scaled width. */
function placeImage(img: ImageSegment, penX: number, fontSizePx: number): LaidImage {
const w = img.width * img.scale;
const h = img.height * img.scale;
const ascent = fontSizePx * 0.8;
const descent = fontSizePx * 0.2;
let yBottom: number;
switch (img.valign) {
case 'top': yBottom = ascent - h; break;
case 'bottom': yBottom = -descent; break;
case 'middle': yBottom = (ascent - descent) / 2 - h / 2; break;
default: yBottom = 0; break; // baseline
}
return {
src: img.src,
x: penX + img.offsetX,
y: yBottom + img.offsetY,
w, h,
tint: img.tint ? [img.tint.r, img.tint.g, img.tint.b, img.tint.a] : null,
};
}
/**
* Lay out a single rich line from its runs: text runs carry per-run color +
* size + bold/italic; `<img>` runs place an inline image box that advances the
* pen by its width. All share the baseline (y = 0). Pure → unit-testable.
*/
export function layoutRichRuns(
runs: RichTextRun[],
atlas: GlyphAtlas,
fontFamily: string,
opts: RichTextLayoutOptions,
baseStyle = 0,
): TextLayout {
const spacing = opts.letterSpacing ?? 0;
const glyphs: LaidGlyph[] = [];
const images: LaidImage[] = [];
let penX = 0;
let lineHeight = opts.fontSizePx;
for (const run of runs) {
if (run.type === 'image') {
const placed = placeImage(run, penX, opts.fontSizePx);
images.push(placed);
if (placed.h > lineHeight) lineHeight = placed.h;
penX += run.width * run.scale;
continue;
}
const runSize = run.fontSize ?? opts.fontSizePx;
const pixelSize = atlas.pixelSizeFor(runSize, fontFamily);
const scale = runSize / pixelSize;
const style = baseStyle | (run.bold ? UI_TEXT_BOLD : 0) | (run.italic ? UI_TEXT_ITALIC : 0);
const color: RGBA = run.color
? [run.color.r, run.color.g, run.color.b, run.color.a]
: opts.color;
if (runSize > lineHeight) lineHeight = runSize;
for (const ch of run.text) {
const cp = ch.codePointAt(0);
if (cp === undefined) continue;
const gph = atlas.getGlyph(cp, fontFamily, style, pixelSize);
if (!gph) continue;
if (gph.width > 0 && gph.height > 0) {
const x0 = penX + gph.bearingX * scale;
const y1 = gph.bearingY * scale;
glyphs.push({
u0: gph.u0, v0: gph.v0, u1: gph.u1, v1: gph.v1,
x0, y0: y1 - gph.height * scale, x1: x0 + gph.width * scale, y1,
pageId: gph.pageId, color, entry: gph,
});
}
penX += gph.advance * scale + spacing;
}
}
return { glyphs, images, width: penX, lineHeight };
}