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
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.tsindex 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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('AB', 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]);+ });+});