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.

perf(ui): keep text measurement atlases off GPU

yhh235beaf4f821
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.mjs
index 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':