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
perf(ui): keep text measurement atlases off GPU
yhh235beaf4f821
diff --git a/CHANGELOG.md b/CHANGELOG.mdindex f712ea0cc..98575198d 100644--- a/CHANGELOG.md+++ b/CHANGELOG.md@@ -20,6 +20,8 @@ published separately; it ships inside the editor.### Fixed+- **Text measurement avoids GPU glyph pages.** Input caret measurements and inline rich-text layout retain the same rasterized glyph advances, bearings and dimensions in CPU caches without packing or uploading textures. Ordinary text drawing keeps its existing atlas; measurement-only atlases reject draw submission instead of emitting invalid texture references.+- **Inline rich text releases its own measurement atlas.** Cleanup belongs to each App, so closing an older preview cannot remove a newer preview's inline image children. Exiting releases measurement glyph pages and repeated cleanup remains safe.- **Input fields release their measurement glyph pages on exit.** App teardown disposes the caret measurement atlas as well as the visible text atlas, preventing a 4 MiB page from accumulating on each preview restart. Cleanup stays scoped to the exiting App.diff --git a/sdk/src/ui/text/glyph-atlas.ts b/sdk/src/ui/text/glyph-atlas.tsindex 1b3ce5b9a..23b1d6c18 100644--- a/sdk/src/ui/text/glyph-atlas.ts+++ b/sdk/src/ui/text/glyph-atlas.ts@@ -117,7 +117,7 @@ export class GlyphAtlas {constructor(private readonly rasterizer: GlyphRasterizer,- private readonly store: AtlasPageStore,+ private readonly store: AtlasPageStore | null,opts: GlyphAtlasOptions = {},) {this.pageSize = opts.pageSize ?? 1024;@@ -126,6 +126,9 @@ export class GlyphAtlas {this.dpr = opts.dpr ?? 1;}+ /** A null store keeps metrics in CPU memory without drawable atlas pages. */+ get metricsOnly(): boolean { return this.store === null; }+/** Number of atlas pages currently allocated. */get pageCount(): number { return this.pages.length; }@@ -139,7 +142,7 @@ export class GlyphAtlas {this.generation_++;const errors: unknown[] = [];for (const page of pages) {- try { this.store.releasePage?.(page); } catch (error) { errors.push(error); }+ try { this.store?.releasePage?.(page); } catch (error) { errors.push(error); }}if (errors.length) throw new Error(`Failed to release glyph atlas pages: ${errors.map(String).join('; ')}`);}@@ -228,6 +231,20 @@ export class GlyphAtlas {return entry;}+ if (!this.store) {+ if (raster.width + this.padding > this.pageSize || raster.height + this.padding > this.pageSize) {+ this.cache.set(k, null);+ return null;+ }+ const entry: GlyphEntry = {+ pageId: -1, u0: 0, v0: 0, u1: 0, v1: 0,+ width: raster.width, height: raster.height,+ advance: raster.advance, bearingX: raster.bearingX, bearingY: raster.bearingY,+ };+ this.cache.set(k, entry);+ return entry;+ }+const placed = this.place(raster.width, raster.height);if (!placed) {// Glyph larger than a whole page — cannot atlas it. Cache null.@@ -278,6 +295,7 @@ export class GlyphAtlas {}private addPage(): void {+ if (!this.store) throw new Error('Measurement atlases cannot allocate pages.');const page = this.pages.length;this.placements.push([]);this.pages.push(this.store.createPage(this.pageSize, (pixels) => this.paintPage(page, pixels)));diff --git a/sdk/src/ui/text/inline-image-plugin.ts b/sdk/src/ui/text/inline-image-plugin.tsindex 35bc510c7..adf088cb1 100644--- a/sdk/src/ui/text/inline-image-plugin.ts+++ b/sdk/src/ui/text/inline-image-plugin.ts@@ -70,7 +70,7 @@ export class InlineImagePlugin implements Plugin {// the images after the text runs (see `layoutText`). SDF so metrics are// resolution-independent; sub-pixel drift vs the draw atlas is invisible.let measurer: SdfTextRenderer | null = null;- const atlas = () => (measurer ??= new SdfTextRenderer(module)).atlas;+ const atlas = () => (measurer ??= new SdfTextRenderer(module, { metricsOnly: true })).atlas;const childrenOf = new Map<Entity, Entity[]>();const textureOf = new Map<string, number>(); // src → handle (0 = failed)diff --git a/sdk/src/ui/text/text-input-plugin.ts b/sdk/src/ui/text/text-input-plugin.tsindex 0aa916e08..c08cc1640 100644--- a/sdk/src/ui/text/text-input-plugin.ts+++ b/sdk/src/ui/text/text-input-plugin.ts@@ -99,7 +99,7 @@ export class TextInputPlugin implements Plugin {const alignOffsetOf = new Map<Entity, number>();let measureRenderer: SdfTextRenderer | null = null;const ensureMeasure = (): SdfTextRenderer => {- if (!measureRenderer) measureRenderer = new SdfTextRenderer(module);+ if (!measureRenderer) measureRenderer = new SdfTextRenderer(module, { metricsOnly: true });return measureRenderer;};diff --git a/sdk/src/ui/text/text-renderer.ts b/sdk/src/ui/text/text-renderer.tsindex 1ca572fcd..3cdef389c 100644--- a/sdk/src/ui/text/text-renderer.ts+++ b/sdk/src/ui/text/text-renderer.ts@@ -173,6 +173,7 @@ export function textBlockOriginY(* Pure given the atlas, so grouping and geometry are unit-testable.*/export function drawTextWith(atlas: GlyphAtlas, sink: GlyphBatchSink, p: DrawTextParams): void {+ if (atlas.metricsOnly) throw new Error('Measurement atlases cannot submit text.');const opacity = p.opacity ?? 1;if (opacity <= 0) return;const layout = layoutText(p.text, atlas, p.fontFamily, {@@ -259,6 +260,8 @@ export function drawTextWith(atlas: GlyphAtlas, sink: GlyphBatchSink, p: DrawTex}export interface TextRendererOptions extends CanvasGlyphRasterizerOptions {+ /** Cache glyph metrics without creating or uploading GPU pages. */+ metricsOnly?: boolean;/** Atlas page size in texels. Default 1024. */pageSize?: number;/** Device pixel ratio for bitmap-mode per-size rasterization. Default 1. */@@ -298,7 +301,7 @@ export class SdfTextRenderer {: new CanvasGlyphRasterizer(module, opts);this.atlas = new GlyphAtlas(rasterizer,- new EngineAtlasPageStore(module),+ opts.metricsOnly ? null : new EngineAtlasPageStore(module),{ pageSize: opts.pageSize, sdf: this.sdf, dpr: opts.dpr },);}@@ -330,6 +333,7 @@ export class SdfTextRenderer {depth: number,cullBit = 0,): void {+ if (this.atlas.metricsOnly) throw new Error('Measurement atlases cannot submit text.');const opacity = p.opacity ?? 1;if (opacity <= 0) return;const gen = this.atlas.generation;diff --git a/sdk/tests/native-text.test.ts b/sdk/tests/native-text.test.tsindex 6d7c7435d..f1b163e16 100644--- a/sdk/tests/native-text.test.ts+++ b/sdk/tests/native-text.test.ts@@ -19,6 +19,7 @@ import { setPlatform } from '../src/platform/base';import { setRendererBackend } from '../src/render/renderer';import { setNativeTextSubmit, TEXT_VERTEX_FLOATS } from '../src/ui/text/submit';import { Camera, Canvas, Transform } from '../src/ecs/component';+import { SdfTextRenderer } from '../src/ui/text/text-renderer';import { Text, TextRenderMode } from '../src/ui/core/text';import { PTR_ACCESSORS } from '../src/ecs/bridge/ptrAccessors.generated';import type { PlatformGlyphRequest } from '../src/platform/types';@@ -177,6 +178,24 @@ function buildScene(app: ReturnType<typeof createNativeApp>, setScene: (canvas:}describe('a frame on the native core', () => {+ it('measures native glyphs without allocating or uploading texture pages', async () => {+ const host = makeHostScope();+ const app = createNativeApp(makeBridge(host.scope), host.scope);+ await app.tick(0);+ const renderer = new SdfTextRenderer(null, { metricsOnly: true });+ const glyph = renderer.atlas.getGlyph('Ω'.codePointAt(0)!, 'Arial');+ expect(glyph).not.toBeNull();+ expect(host.rasterizeSpy).toHaveBeenCalled();+ expect(host.textures.size).toBe(0);+ expect(host.uploads).toEqual([]);+ expect(renderer.atlas.pageCount).toBe(0);+ expect(() => renderer.drawText({+ text: 'Ω', fontFamily: 'Arial', fontSizePx: 32, color: [1, 1, 1, 1],+ }, new Float32Array(16), 1, 0, 0)).toThrow('Measurement atlases cannot submit text');+ renderer.dispose();+ app.quit({ keepRenderer: true });+ });+it('isolates glyph pages between apps and releases only the quitting owner', async () => {const first = makeHostScope();const appA = createNativeApp(makeBridge(first.scope), first.scope);diff --git a/sdk/tests/text-input-plugin-lifecycle.test.ts b/sdk/tests/text-input-plugin-lifecycle.test.tsindex c1ce4d0f6..6611656a9 100644--- a/sdk/tests/text-input-plugin-lifecycle.test.ts+++ b/sdk/tests/text-input-plugin-lifecycle.test.ts@@ -3,6 +3,7 @@import { afterEach, expect, it, vi } from 'vitest';import type { TextEditorEvent } from '../src/platform/types';import { bootMockApp } from './helpers/mockApp';+import { log } from '../src/util/logger';const measurements = vi.hoisted(() => [] as Array<{ dispose: ReturnType<typeof vi.fn> }>);const dimensions = vi.hoisted(() => ({ width: vi.fn(() => 0), height: vi.fn(() => 0) }));@@ -13,7 +14,7 @@ vi.mock('../src/ui/util/helpers', async original => ({}));vi.mock('../src/ui/text/text-renderer', () => ({SdfTextRenderer: class {- atlas = { renderSize: 64, getGlyph: () => ({ advance: 16 }) };+ atlas = { renderSize: 64, pixelSizeFor: () => 64, getGlyph: () => ({ advance: 16 }) };dispose = vi.fn();constructor() { measurements.push(this); }},@@ -66,6 +67,7 @@ afterEach(() => {measurements.length = 0;dimensions.width.mockReturnValue(0);dimensions.height.mockReturnValue(0);+ vi.restoreAllMocks();});it.each(['change', 'composition', 'submit'] as const)('delivers native %s after UI clearing and before Update consumers', async kind => {@@ -205,6 +207,7 @@ it.each(['entity', 'ancestor', 'interaction'] as const)('rejects queued input af});it('releases each App measurement atlas without disposing the newer field atlas', async () => {+ const errors = vi.spyOn(log, 'error').mockImplementation(() => {});dimensions.width.mockReturnValue(160);dimensions.height.mockReturnValue(40);const plugin = new TextInputPlugin();@@ -217,6 +220,7 @@ it('releases each App measurement atlas without disposing the newer field atlas'return app;};const first = await prepare(), second = await prepare();+ expect(errors).not.toHaveBeenCalled();expect(measurements).toHaveLength(2);first.quit();expect(measurements[0].dispose).toHaveBeenCalledOnce();diff --git a/sdk/tests/ui-glyph-atlas.test.ts b/sdk/tests/ui-glyph-atlas.test.tsindex c2785438a..7cb84b9f6 100644--- a/sdk/tests/ui-glyph-atlas.test.ts+++ b/sdk/tests/ui-glyph-atlas.test.ts@@ -14,6 +14,8 @@ import {type RasterGlyph,} from '../src/ui/text/glyph-atlas';+import { layoutText } from '../src/ui/text/layout';+const UNKNOWN = 0xffff;const SPACE = 32;const HUGE = 0xaaaa;@@ -62,6 +64,29 @@ describe('REARCH_GUI P1.1c: GlyphAtlas', () => {expect(rasterizer.rasterize).toHaveBeenCalledTimes(calls + 1);});+ it('matches measured rich layout without allocating pages, including styles and wrapping', () => {+ const metricsRasterizer = makeRasterizer();+ const metrics = new GlyphAtlas(metricsRasterizer, null);+ const rendered = new GlyphAtlas(makeRasterizer(), makeStore());+ const content = 'A Ω <b>styled</b><img src="icon.png" width="18" height="16"> text\nnext line';+ const options = { fontSizePx: 24, maxWidth: 90, boxWidth: 120, rich: true, color: [1, 1, 1, 1] as const };+ const measured = layoutText(content, metrics, 'Arial', options);+ const expected = layoutText(content, rendered, 'Arial', options);+ expect({ width: measured.width, lineHeight: measured.lineHeight, images: measured.images })+ .toEqual({ width: expected.width, lineHeight: expected.lineHeight, images: expected.images });+ expect(measured.glyphs.map(({ x0, y0, x1, y1 }) => ({ x0, y0, x1, y1 })))+ .toEqual(expected.glyphs.map(({ x0, y0, x1, y1 }) => ({ x0, y0, x1, y1 })));+ expect(metrics.pageCount).toBe(0);+ expect(rendered.pageCount).toBeGreaterThan(0);+ const calls = metricsRasterizer.rasterize.mock.calls.length;+ layoutText(content, metrics, 'Arial', options);+ expect(metricsRasterizer.rasterize).toHaveBeenCalledTimes(calls);+ metrics.dispose();+ layoutText(content, metrics, 'Arial', options);+ expect(metricsRasterizer.rasterize.mock.calls.length).toBeGreaterThan(calls);+ expect(metrics.pageCount).toBe(0);+ });+it('rasterizes, packs and uploads on first use; returns UVs + metrics', () => {const r = makeRasterizer();const s = makeStore();diff --git a/sdk/tests/ui-text-renderer.test.ts b/sdk/tests/ui-text-renderer.test.tsindex 810fa331f..44ec159d5 100644--- a/sdk/tests/ui-text-renderer.test.ts+++ b/sdk/tests/ui-text-renderer.test.ts@@ -13,7 +13,7 @@ import {import { drawTextWith, signatureOf, tapAlpha } from '../src/ui/text/text-renderer';import type { DrawTextParams } from '../src/ui/text/text-renderer';-function makeAtlas(pageSize: number, spread = 6): GlyphAtlas {+function makeAtlas(pageSize: number, spread = 6, metricsOnly = false): GlyphAtlas {const rasterizer: GlyphRasterizer = {renderSize: 48,spread,@@ -24,10 +24,18 @@ function makeAtlas(pageSize: number, spread = 6): GlyphAtlas {};let next = 1000;const store: AtlasPageStore = { createPage: () => next++, uploadSubRegion: () => {} };- return new GlyphAtlas(rasterizer, store, { pageSize, padding: 1 });+ return new GlyphAtlas(rasterizer, metricsOnly ? null : store, { pageSize, padding: 1 });}describe('REARCH_GUI P1.3b: drawTextWith', () => {+ it('rejects measurement glyphs before emitting invalid texture references', () => {+ const sink = vi.fn();+ expect(() => drawTextWith(makeAtlas(64, 6, true), sink, {+ text: 'A', fontFamily: 'Arial', fontSizePx: 24, color: [1, 1, 1, 1],+ })).toThrow('Measurement atlases cannot submit text');+ expect(sink).not.toHaveBeenCalled();+ });+it.each([16384, 16385, 32769])('preserves every glyph when one atlas page carries %i quads', count => {const batches: Array<{ vertices: Float32Array; indices: Uint16Array }> = [];drawTextWith(makeAtlas(1024), (vertices, indices) => batches.push({ vertices, indices }), {diff --git a/tools/releaseNotes.mjs b/tools/releaseNotes.mjsindex 0d4ac99a4..796df7b75 100644--- a/tools/releaseNotes.mjs+++ b/tools/releaseNotes.mjs@@ -28,6 +28,8 @@ export const NOTES_FLOOR = 'v0.65.0';* the reader recognises anyway.*/export const NOTED = {+ 'perf(ui): keep text measurement atlases off GPU':+ { note: 'Text measurement avoids GPU glyph pages.' },'fix(ui): scope inline text cleanup and release measurement pages':{ note: 'Inline rich text releases its own measurement atlas.' },'docs(poki): document official Inspector URL validation':