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): 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.ts
new file mode 100644
index 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.ts
new file mode 100644
index 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.ts
index 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.ts
new file mode 100644
index 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.ts
index 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 applied
diff --git a/sdk/tests/ui-text-rasterizer.test.ts b/sdk/tests/ui-text-rasterizer.test.ts
new file mode 100644
index 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.ts
new file mode 100644
index 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();
+ });
+});