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.

feat(text): pure SDF text layout + glyph-vertex building (REARCH_GUI P1.3b)

esengine533528830dfc
diff --git a/sdk/src/ui/text/glyph-atlas.ts b/sdk/src/ui/text/glyph-atlas.ts
index bcf161244..04f42ab48 100644
--- a/sdk/src/ui/text/glyph-atlas.ts
+++ b/sdk/src/ui/text/glyph-atlas.ts
@@ -92,6 +92,9 @@ export class GlyphAtlas {
/** Number of atlas pages currently allocated. */
get pageCount(): number { return this.pages.length; }
+ /** The px size glyphs are rasterized at; layout scales by displaySize/renderSize. */
+ get renderSize(): number { return this.rasterizer.renderSize; }
+
private key(codepoint: number, fontFamily: string, style: number): string {
return `${fontFamily}|${codepoint}|${style % STYLE_COUNT_HINT}`;
}
diff --git a/sdk/src/ui/text/layout.ts b/sdk/src/ui/text/layout.ts
new file mode 100644
index 000000000..8453f1a7e
--- /dev/null
+++ b/sdk/src/ui/text/layout.ts
@@ -0,0 +1,126 @@
+/**
+ * @file ui/text/layout.ts
+ * @brief Pure text layout + glyph-quad vertex building for the SDF text path
+ * (REARCH_GUI P1.3, 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 } from './glyph-atlas';
+import { TEXT_VERTEX_FLOATS } from './submit';
+
+export interface TextLayoutOptions {
+ /** Display font size in px. */
+ fontSizePx: number;
+ /** Extra advance between glyphs, in display px. */
+ letterSpacing?: number;
+}
+
+/** One positioned glyph quad: atlas UVs + local-space corners (y-up). */
+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;
+}
+
+export interface TextLayout {
+ glyphs: LaidGlyph[];
+ /** Total pen advance (display px). */
+ width: number;
+ /** Line height (display px). */
+ lineHeight: 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 scale = opts.fontSizePx / atlas.renderSize;
+ 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);
+ 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 });
+ }
+ penX += g.advance * scale + spacing;
+ }
+
+ return { glyphs, width: penX, lineHeight: opts.fontSizePx };
+}
+
+/** RGBA color, channels in [0,1]. */
+export type RGBA = readonly [number, number, number, number];
+
+export interface GlyphVertexData {
+ vertices: Float32Array; // TEXT_VERTEX_FLOATS per vertex, 4 verts/glyph
+ indices: Uint16Array; // 6 per glyph
+}
+
+/**
+ * Build interleaved vertices (x,y,u,v,r,g,b,a) + indices for laid-out glyphs.
+ * Atlas v0 (top) maps to the screen-top corner, v1 (bottom) to screen-bottom,
+ * so the quad samples the glyph upright. `originX/Y` offsets all glyphs (e.g. to
+ * place the text by its UIRect-resolved anchor).
+ */
+export function buildGlyphVertices(
+ layout: TextLayout,
+ color: RGBA,
+ originX = 0,
+ originY = 0,
+): GlyphVertexData {
+ const n = layout.glyphs.length;
+ const vertices = new Float32Array(n * 4 * TEXT_VERTEX_FLOATS);
+ const indices = new Uint16Array(n * 6);
+ const [r, g, b, a] = color;
+
+ for (let i = 0; i < n; i++) {
+ const gl = layout.glyphs[i];
+ 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);
+ writeVertex(vertices, vo + 1 * TEXT_VERTEX_FLOATS, x1, y0, gl.u1, gl.v1, r, g, b, a);
+ writeVertex(vertices, vo + 2 * TEXT_VERTEX_FLOATS, x1, y1, gl.u1, gl.v0, r, g, b, a);
+ writeVertex(vertices, vo + 3 * TEXT_VERTEX_FLOATS, x0, y1, gl.u0, gl.v0, r, g, b, a);
+
+ 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,
+): 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;
+}
diff --git a/sdk/tests/ui-text-layout.test.ts b/sdk/tests/ui-text-layout.test.ts
new file mode 100644
index 000000000..2d663a5c6
--- /dev/null
+++ b/sdk/tests/ui-text-layout.test.ts
@@ -0,0 +1,83 @@
+/**
+ * @file REARCH_GUI P1.3b — pure text layout + glyph-vertex building. Driven via
+ * a real GlyphAtlas backed by mock rasterizer/store (no Canvas/GL), so the
+ * scaling, pen advance, quad geometry and vertex/index packing are fully
+ * verified headless.
+ */
+import { describe, it, expect } from 'vitest';
+import {
+ GlyphAtlas, type GlyphRasterizer, type AtlasPageStore, type RasterGlyph,
+} from '../src/ui/text/glyph-atlas';
+import { layoutLine, buildGlyphVertices } from '../src/ui/text/layout';
+
+const SPACE = 32;
+const UNKNOWN = 0xffff;
+
+function makeAtlas(): GlyphAtlas {
+ const rasterizer: GlyphRasterizer = {
+ renderSize: 48,
+ rasterize: (cp: number): RasterGlyph | null => {
+ if (cp === UNKNOWN) return null;
+ if (cp === SPACE) return { pixels: new Uint8Array(0), width: 0, height: 0, advance: 12, bearingX: 0, bearingY: 0 };
+ return { pixels: new Uint8Array(10 * 12 * 4), width: 10, height: 12, advance: 11, bearingX: 1, bearingY: 10 };
+ },
+ };
+ let next = 1;
+ const store: AtlasPageStore = {
+ createPage: () => next++,
+ uploadSubRegion: () => { /* no-op */ },
+ };
+ return new GlyphAtlas(rasterizer, store, { pageSize: 64, padding: 1 });
+}
+
+describe('REARCH_GUI P1.3b: text layout', () => {
+ it('scales metrics by fontSize/renderSize and advances the pen', () => {
+ const atlas = makeAtlas();
+ const layout = layoutLine('AB', atlas, 'Arial', { fontSizePx: 24 }); // scale 0.5
+ expect(layout.glyphs.length).toBe(2);
+ expect(layout.width).toBeCloseTo(11); // 2 × advance(11)×0.5
+ const a = layout.glyphs[0];
+ expect(a.x0).toBeCloseTo(0.5); // bearingX(1)×0.5
+ expect(a.y1).toBeCloseTo(5); // bearingY(10)×0.5
+ expect(a.x1).toBeCloseTo(5.5); // x0 + width(10)×0.5
+ expect(a.y0).toBeCloseTo(-1); // y1 - height(12)×0.5
+ expect(layout.glyphs[1].x0).toBeCloseTo(6); // advance 5.5 + bearingX 0.5
+ });
+
+ it('whitespace advances without emitting a quad', () => {
+ const atlas = makeAtlas();
+ const layout = layoutLine('A B', atlas, 'Arial', { fontSizePx: 24 });
+ expect(layout.glyphs.length).toBe(2); // space has no quad
+ expect(layout.width).toBeCloseTo(5.5 + 6 + 5.5); // A + space(12×0.5) + B
+ expect(layout.glyphs[1].x0).toBeCloseTo(12); // (5.5+6) + 0.5
+ });
+
+ it('skips glyphs the atlas cannot produce (no advance)', () => {
+ const atlas = makeAtlas();
+ const layout = layoutLine('A￿B', atlas, 'Arial', { fontSizePx: 24 });
+ expect(layout.glyphs.length).toBe(2);
+ expect(layout.width).toBeCloseTo(11);
+ });
+
+ it('letterSpacing adds between glyphs', () => {
+ const atlas = makeAtlas();
+ const layout = layoutLine('AB', atlas, 'Arial', { fontSizePx: 24, letterSpacing: 3 });
+ expect(layout.width).toBeCloseTo(11 + 2 * 3);
+ });
+
+ it('builds 4 verts + 6 indices per glyph with correct stride and color', () => {
+ const atlas = makeAtlas();
+ const layout = layoutLine('AB', atlas, 'Arial', { fontSizePx: 24 });
+ const { vertices, indices } = buildGlyphVertices(layout, [1, 0, 0, 1], 100, 200);
+ expect(vertices.length).toBe(2 * 4 * 8);
+ expect(indices.length).toBe(2 * 6);
+ // first vertex = bottom-left of glyph 0, with origin applied
+ expect(vertices[0]).toBeCloseTo(0.5 + 100); // x
+ expect(vertices[1]).toBeCloseTo(-1 + 200); // y
+ expect(vertices[4]).toBe(1); // r
+ expect(vertices[5]).toBe(0); // g
+ expect(vertices[7]).toBe(1); // a
+ // quad winding
+ expect(Array.from(indices.slice(0, 6))).toEqual([0, 1, 2, 0, 2, 3]);
+ });
+});