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): Canvas2D SDF rasterizer + engine page store + text renderer (REARCH_GUI P1.3b)
esengine646f15210aff
diff --git a/sdk/src/ui/text/atlas-page-store.ts b/sdk/src/ui/text/atlas-page-store.tsnew file mode 100644index 000000000..d402f0594--- /dev/null+++ b/sdk/src/ui/text/atlas-page-store.ts@@ -0,0 +1,30 @@+/**+ * @file ui/text/atlas-page-store.ts+ * @brief Engine-backed AtlasPageStore for the dynamic glyph atlas (REARCH_GUI+ * P1.3): a page is an RGBA8 GPU texture, glyphs land via the P1.0+ * sub-region upload. The page id IS the texture handle, so the text+ * renderer can pass it straight to submitTextBatch as the atlas texture.+ */+import type { ESEngineModule } from '../../wasm';+import { createTextureFromPixels, updateTextureSubregion } from '../../runtimeAssets';+import type { AtlasPageStore } from './glyph-atlas';++export class EngineAtlasPageStore implements AtlasPageStore {+ constructor(private readonly module: ESEngineModule) {}++ createPage(size: number): number {+ // Blank (transparent) RGBA8 page; linear filtering keeps SDF text smooth+ // when scaled, clamp avoids edge bleed at the page border.+ const pixels = new Uint8Array(size * size * 4);+ return createTextureFromPixels(+ this.module,+ { width: size, height: size, pixels },+ /* flipY */ false,+ { filterMode: 'linear', wrapMode: 'clamp' },+ );+ }++ uploadSubRegion(pageId: number, x: number, y: number, w: number, h: number, pixels: Uint8Array): void {+ updateTextureSubregion(this.module, pageId, x, y, w, h, pixels);+ }+}diff --git a/sdk/src/ui/text/glyph-rasterizer.ts b/sdk/src/ui/text/glyph-rasterizer.tsnew file mode 100644index 000000000..442a43fb1--- /dev/null+++ b/sdk/src/ui/text/glyph-rasterizer.ts@@ -0,0 +1,115 @@+/**+ * @file ui/text/glyph-rasterizer.ts+ * @brief Canvas2D glyph rasterizer → SDF, the real GlyphRasterizer for the+ * dynamic atlas (REARCH_GUI P1.3). Works on web AND WeChat (both expose+ * a 2D canvas + getImageData; the legacy text path already relied on+ * this). Any font / CJK / emoji, since glyphs are drawn on demand.+ *+ * Testability: the Canvas2D draw/measure is a platform stub under happy-dom, so+ * rasterize() is verified at render time. The pure pixel transforms+ * (extractAlpha, sdfToAtlasRgba) + the C++ sdfFromAlpha are unit-tested.+ */+import type { ESEngineModule } from '../../wasm';+import { platformCreateCanvas } from '../../platform';+import { sdfFromAlpha } from './sdf';+import type { GlyphRasterizer, RasterGlyph } from './glyph-atlas';++/** Style bit flags (match the atlas cache-key style argument). */+export const FONT_STYLE_BOLD = 1;+export const FONT_STYLE_ITALIC = 2;++/** Extract the alpha channel from an RGBA buffer into a tight width*height buffer. Pure. */+export function extractAlpha(rgba: Uint8Array | Uint8ClampedArray, width: number, height: number): Uint8Array {+ const n = width * height;+ const out = new Uint8Array(n);+ for (let i = 0; i < n; i++) out[i] = rgba[i * 4 + 3];+ return out;+}++/** Expand a single-channel SDF into an RGBA atlas tile (RGB = 255, A = sdf). Pure. */+export function sdfToAtlasRgba(sdf: Uint8Array, width: number, height: number): Uint8Array {+ const n = width * height;+ const out = new Uint8Array(n * 4);+ for (let i = 0; i < n; i++) {+ const o = i * 4;+ out[o] = 255; out[o + 1] = 255; out[o + 2] = 255; out[o + 3] = sdf[i];+ }+ return out;+}++export interface CanvasGlyphRasterizerOptions {+ /** Size glyphs are rasterized at (SDF is resolution-independent). Default 48. */+ renderSize?: number;+ /** SDF spread / padding around the glyph ink, in px. Default 6. */+ padding?: number;+}++type Canvas2D = HTMLCanvasElement | OffscreenCanvas;+type Ctx2D = CanvasRenderingContext2D | OffscreenCanvasRenderingContext2D;++export class CanvasGlyphRasterizer implements GlyphRasterizer {+ readonly renderSize: number;+ private readonly module: ESEngineModule;+ private readonly pad: number;+ private readonly canvas: Canvas2D;+ private readonly ctx: Ctx2D | null;++ constructor(module: ESEngineModule, opts: CanvasGlyphRasterizerOptions = {}) {+ this.module = module;+ this.renderSize = opts.renderSize ?? 48;+ this.pad = opts.padding ?? 6;+ // Scratch canvas sized for the largest glyph (em + ascenders + padding).+ const dim = Math.ceil(this.renderSize * 2 + this.pad * 2);+ this.canvas = platformCreateCanvas(dim, dim);+ this.ctx = this.canvas.getContext('2d', { willReadFrequently: true }) as Ctx2D | null;+ }++ rasterize(codepoint: number, fontFamily: string, style: number): RasterGlyph | null {+ const ctx = this.ctx;+ if (!ctx) return null;+ const ch = String.fromCodePoint(codepoint);++ const weight = (style & FONT_STYLE_BOLD) ? 'bold ' : '';+ const italic = (style & FONT_STYLE_ITALIC) ? 'italic ' : '';+ ctx.font = `${italic}${weight}${this.renderSize}px ${fontFamily}`;+ ctx.textBaseline = 'alphabetic';+ ctx.textAlign = 'left';++ const m = ctx.measureText(ch);+ const advance = m.width;+ const left = m.actualBoundingBoxLeft ?? 0;+ const right = m.actualBoundingBoxRight ?? advance;+ const ascent = m.actualBoundingBoxAscent ?? this.renderSize * 0.8;+ const descent = m.actualBoundingBoxDescent ?? this.renderSize * 0.2;++ const inkW = Math.ceil(left + right);+ const inkH = Math.ceil(ascent + descent);+ if (inkW <= 0 || inkH <= 0) {+ // Whitespace: advance only, no atlas cell.+ return { pixels: new Uint8Array(0), width: 0, height: 0, advance, bearingX: 0, bearingY: 0 };+ }++ const pad = this.pad;+ const w = inkW + pad * 2;+ const h = inkH + pad * 2;+ if (w > this.canvas.width || h > this.canvas.height) return null; // glyph too large for scratch++ ctx.clearRect(0, 0, w, h);+ ctx.fillStyle = '#ffffff';+ ctx.fillText(ch, pad + left, pad + ascent);++ const img = ctx.getImageData(0, 0, w, h);+ const alpha = extractAlpha(img.data, w, h);+ const sdf = sdfFromAlpha(this.module, alpha, w, h, pad);+ if (!sdf) return null;++ return {+ pixels: sdfToAtlasRgba(sdf, w, h),+ width: w,+ height: h,+ advance,+ bearingX: left - pad, // bitmap left relative to the pen origin+ bearingY: ascent + pad, // bitmap top above the baseline+ };+ }+}diff --git a/sdk/src/ui/text/layout.ts b/sdk/src/ui/text/layout.tsindex 8453f1a7e..8d5c6431b 100644--- a/sdk/src/ui/text/layout.ts+++ b/sdk/src/ui/text/layout.ts@@ -81,24 +81,25 @@ export interface GlyphVertexData {}/**- * Build interleaved vertices (x,y,u,v,r,g,b,a) + indices for laid-out glyphs.+ * Build interleaved vertices (x,y,u,v,r,g,b,a) + indices for a set of laid-out+ * glyphs (typically the subset that shares one atlas page — see TextRenderer).* 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,+ glyphs: readonly LaidGlyph[],color: RGBA,originX = 0,originY = 0,): GlyphVertexData {- const n = layout.glyphs.length;+ const n = 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 gl = 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;diff --git a/sdk/src/ui/text/text-renderer.ts b/sdk/src/ui/text/text-renderer.tsnew file mode 100644index 000000000..6150be1b8--- /dev/null+++ b/sdk/src/ui/text/text-renderer.ts@@ -0,0 +1,85 @@+/**+ * @file ui/text/text-renderer.ts+ * @brief High-level SDF text drawing (REARCH_GUI P1.3): 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 type { ESEngineModule } from '../../wasm';+import { GlyphAtlas } from './glyph-atlas';+import { CanvasGlyphRasterizer, type CanvasGlyphRasterizerOptions } from './glyph-rasterizer';+import { EngineAtlasPageStore } from './atlas-page-store';+import { layoutLine, buildGlyphVertices, type LaidGlyph, type RGBA } from './layout';+import { submitTextBatch } from './submit';++/** Receives one (vertices, indices) batch per atlas page used by the text. */+export type GlyphBatchSink = (vertices: Float32Array, indices: Uint16Array, pageId: number) => void;++export interface DrawTextParams {+ text: string;+ fontFamily: string;+ fontSizePx: number;+ color: RGBA;+ originX?: number;+ originY?: number;+ style?: number;+}++/**+ * Lay out `text` against `atlas` and emit one quad batch per atlas page to+ * `sink`. Pure given the atlas — no engine/Canvas dependency — so the grouping+ * and geometry are unit-testable.+ */+export function drawTextWith(atlas: GlyphAtlas, sink: GlyphBatchSink, p: DrawTextParams): void {+ const layout = layoutLine(p.text, atlas, p.fontFamily, { fontSizePx: p.fontSizePx }, p.style ?? 0);+ if (layout.glyphs.length === 0) return;++ // A string can reference glyphs across several atlas pages; each page is a+ // distinct texture, so group by page and emit one batch per page.+ const byPage = new Map<number, LaidGlyph[]>();+ for (const g of layout.glyphs) {+ let arr = byPage.get(g.pageId);+ if (!arr) { arr = []; byPage.set(g.pageId, arr); }+ arr.push(g);+ }+ for (const [pageId, glyphs] of byPage) {+ const { vertices, indices } = buildGlyphVertices(glyphs, p.color, p.originX ?? 0, p.originY ?? 0);+ sink(vertices, indices, pageId);+ }+}++export interface TextRendererOptions extends CanvasGlyphRasterizerOptions {+ /** Atlas page size in texels. Default 1024. */+ pageSize?: number;+}++export class TextRenderer {+ readonly atlas: GlyphAtlas;++ constructor(private readonly module: ESEngineModule, opts: TextRendererOptions = {}) {+ this.atlas = new GlyphAtlas(+ new CanvasGlyphRasterizer(module, opts),+ new EngineAtlasPageStore(module),+ { pageSize: opts.pageSize },+ );+ }++ /**+ * 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.+ */+ drawText(+ p: DrawTextParams,+ transform: Float32Array,+ entity: number,+ layer: number,+ depth: number,+ ): void {+ drawTextWith(this.atlas, (vertices, indices, pageId) => {+ submitTextBatch(this.module, vertices, indices, pageId, transform, entity, layer, depth);+ }, p);+ }+}diff --git a/sdk/tests/ui-text-layout.test.ts b/sdk/tests/ui-text-layout.test.tsindex 2d663a5c6..a2344e005 100644--- a/sdk/tests/ui-text-layout.test.ts+++ b/sdk/tests/ui-text-layout.test.ts@@ -68,7 +68,7 @@ describe('REARCH_GUI P1.3b: text layout', () => {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);+ const { vertices, indices } = buildGlyphVertices(layout.glyphs, [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 applieddiff --git a/sdk/tests/ui-text-rasterizer.test.ts b/sdk/tests/ui-text-rasterizer.test.tsnew file mode 100644index 000000000..ab7010d0f--- /dev/null+++ b/sdk/tests/ui-text-rasterizer.test.ts@@ -0,0 +1,43 @@+/**+ * @file REARCH_GUI P1.3b — the pure pixel transforms of the Canvas2D glyph+ * rasterizer (extractAlpha + sdfToAtlasRgba) and their round-trip through+ * the C++ SDF. The Canvas2D fillText/measure is a happy-dom stub, so+ * rasterize() itself is render-time-verified; here we cover the parts that+ * can be checked headless.+ */+import { describe, it, expect, beforeAll } from 'vitest';+import type { ESEngineModule } from '../src/wasm';+import { loadWasmModule, HAS_WASM } from './helpers/loadWasm';+import { extractAlpha, sdfToAtlasRgba } from '../src/ui/text/glyph-rasterizer';+import { sdfFromAlpha } from '../src/ui/text/sdf';++describe('REARCH_GUI P1.3b: glyph rasterizer pure transforms', () => {+ it('extractAlpha pulls every 4th byte into a tight buffer', () => {+ const rgba = new Uint8Array([1, 2, 3, 10, 4, 5, 6, 20, 7, 8, 9, 30, 0, 0, 0, 40]);+ expect(Array.from(extractAlpha(rgba, 2, 2))).toEqual([10, 20, 30, 40]);+ });++ it('sdfToAtlasRgba puts the SDF in alpha with white RGB', () => {+ const out = sdfToAtlasRgba(new Uint8Array([100, 200]), 2, 1);+ expect(Array.from(out)).toEqual([255, 255, 255, 100, 255, 255, 255, 200]);+ });++ describe.skipIf(!HAS_WASM)('round-trip alpha → SDF → atlas RGBA', () => {+ let module: ESEngineModule;+ beforeAll(async () => { module = await loadWasmModule(); });++ it('atlas tile carries the SDF in alpha, white in RGB', () => {+ const W = 16, H = 16;+ const alpha = new Uint8Array(W * H);+ for (let y = 4; y <= 11; y++) for (let x = 4; x <= 11; x++) alpha[y * W + x] = 255;+ const sdf = sdfFromAlpha(module, alpha, W, H, 4)!;+ const tile = sdfToAtlasRgba(sdf, W, H);+ expect(tile.length).toBe(W * H * 4);+ // interior texel: RGB white, A == its SDF value (>128 inside)+ const c = (8 * W + 8);+ expect(tile[c * 4]).toBe(255);+ expect(tile[c * 4 + 3]).toBe(sdf[c]);+ expect(sdf[c]).toBeGreaterThan(128);+ });+ });+});diff --git a/sdk/tests/ui-text-renderer.test.ts b/sdk/tests/ui-text-renderer.test.tsnew file mode 100644index 000000000..e04ba63c9--- /dev/null+++ b/sdk/tests/ui-text-renderer.test.ts@@ -0,0 +1,57 @@+/**+ * @file REARCH_GUI P1.3b — drawTextWith orchestration: lays text out against a+ * (mock-backed) GlyphAtlas and emits one quad batch per atlas page. Pure+ * given the atlas, so the per-page grouping + geometry are headless-tested.+ */+import { describe, it, expect, vi } from 'vitest';+import {+ GlyphAtlas, type GlyphRasterizer, type AtlasPageStore, type RasterGlyph,+} from '../src/ui/text/glyph-atlas';+import { drawTextWith } from '../src/ui/text/text-renderer';++function makeAtlas(pageSize: number): GlyphAtlas {+ const rasterizer: GlyphRasterizer = {+ renderSize: 48,+ rasterize: (cp: number): RasterGlyph | null => {+ if (cp === 32) 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 = 1000;+ const store: AtlasPageStore = { createPage: () => next++, uploadSubRegion: () => {} };+ return new GlyphAtlas(rasterizer, store, { pageSize, padding: 1 });+}++describe('REARCH_GUI P1.3b: drawTextWith', () => {+ it('emits one batch covering all glyphs when they fit on a single page', () => {+ const atlas = makeAtlas(1024);+ const sink = vi.fn();+ drawTextWith(atlas, sink, { text: 'AB', fontFamily: 'Arial', fontSizePx: 24, color: [1, 1, 1, 1] });+ expect(sink).toHaveBeenCalledTimes(1);+ const [vertices, indices, pageId] = sink.mock.calls[0];+ expect(vertices.length).toBe(2 * 4 * 8);+ expect(indices.length).toBe(2 * 6);+ expect(pageId).toBe(1000);+ });++ it('groups into one batch per atlas page when glyphs span pages', () => {+ // pageSize 32 ⇒ ~4 glyphs/page; 6 distinct glyphs ⇒ 2 pages.+ const atlas = makeAtlas(32);+ const sink = vi.fn();+ drawTextWith(atlas, sink, { text: 'ABCDEF', fontFamily: 'Arial', fontSizePx: 24, color: [1, 1, 1, 1] });+ expect(atlas.pageCount).toBe(2);+ expect(sink).toHaveBeenCalledTimes(2);+ const pages = sink.mock.calls.map(c => c[2]);+ expect(new Set(pages).size).toBe(2); // distinct pages+ const totalVerts = sink.mock.calls.reduce((s, c) => s + c[0].length, 0);+ expect(totalVerts).toBe(6 * 4 * 8); // all 6 glyphs emitted+ });++ it('emits nothing for empty / whitespace-only text', () => {+ const atlas = makeAtlas(1024);+ const sink = vi.fn();+ drawTextWith(atlas, sink, { text: '', fontFamily: 'Arial', fontSizePx: 24, color: [1, 1, 1, 1] });+ drawTextWith(atlas, sink, { text: ' ', fontFamily: 'Arial', fontSizePx: 24, color: [1, 1, 1, 1] });+ expect(sink).not.toHaveBeenCalled();+ });+});