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.

fix(text): bound native measurement advance history

yhh7bd5ca3bc365
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 24ac21a73..cb6ab1d1c 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -14,6 +14,10 @@ published separately; it ships inside the editor.
## [Unreleased]
+### Fixed
+
+- **Public native text measurement retains a bounded advance cache.** Historical font revisions, sizes and missing-glyph estimates retire from a 4096-entry working set. A second-chance clock keeps recently queried advances reusable without reinserting Map entries on every character; failed host measurements leave retained entries intact. Widths, wrapping and the Canvas measurement path retain their existing behavior.
+
### Added
- **Spatial rotation adds a view-axis outer ring.** The outer ring remains a screen circle and uses the presented camera axis captured at the press, with absolute twist snapping and the same undo/cancel path. Local inner rings use their rotated world axis; rotation writes, including Alt copies, convert through each target's parent frame. Flat 2D retains its existing Z ring.
diff --git a/sdk/src/ui/text/measure-text.ts b/sdk/src/ui/text/measure-text.ts
index 8effa8fba..eef6e4d23 100644
--- a/sdk/src/ui/text/measure-text.ts
+++ b/sdk/src/ui/text/measure-text.ts
@@ -47,23 +47,48 @@ type Measurer = (s: string) => number;
let ctx_: CanvasRenderingContext2D | null | undefined;
/** Pen advances from the platform's own glyph source, by
- * `family|style|size|codepoint`. A device rasterizes each glyph once here, as
- * the draw atlas does for the sizes it draws at. */
-const advances_ = new Map<string, number>();
+ * `family|style|size|codepoint`. Retain a bounded working set so historical
+ * font revisions and sizes do not accumulate across long-running sessions. */
+const advances_ = new Map<string, { advance: number; used: boolean }>();
+const ADVANCE_CACHE_LIMIT = 4096;
+const advanceSlots_: string[] = [];
+let advanceHand_ = 0;
function platformAdvance(
codepoint: number, family: string, style: number, fontSize: number,
): number {
const key = `${family}|${style}|${fontSize}|${codepoint}`;
const hit = advances_.get(key);
- if (hit !== undefined) return hit;
+ if (hit !== undefined) {
+ hit.used = true;
+ return hit.advance;
+ }
// Plain coverage at the display size: the advance is all this wants, and a
// bitmap glyph is a fraction of the work an SDF one costs to produce.
const glyph = platformRasterizeGlyph({
codepoint, fontFamily: family, style, pixelSize: fontSize, sdf: false, padding: 0,
});
const advance = glyph ? glyph.advance : fontSize * 0.6;
- advances_.set(key, advance);
+ if (advanceSlots_.length < ADVANCE_CACHE_LIMIT) {
+ advanceSlots_.push(key);
+ } else {
+ // Second-chance clock: hits only set a bit, avoiding Map reinsertion on
+ // every character. The next insertion retires an unused slot; a used
+ // slot gets one more traversal before it can be replaced.
+ for (;;) {
+ const oldKey = advanceSlots_[advanceHand_];
+ const old = advances_.get(oldKey)!;
+ if (!old.used) {
+ advances_.delete(oldKey);
+ advanceSlots_[advanceHand_] = key;
+ advanceHand_ = (advanceHand_ + 1) % ADVANCE_CACHE_LIMIT;
+ break;
+ }
+ old.used = false;
+ advanceHand_ = (advanceHand_ + 1) % ADVANCE_CACHE_LIMIT;
+ }
+ }
+ advances_.set(key, { advance, used: false });
return advance;
}
diff --git a/sdk/tests/measure-text-cache.test.ts b/sdk/tests/measure-text-cache.test.ts
new file mode 100644
index 000000000..e9f20d02f
--- /dev/null
+++ b/sdk/tests/measure-text-cache.test.ts
@@ -0,0 +1,83 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
+import { afterEach, beforeEach, expect, it, vi } from 'vitest';
+
+const host = vi.hoisted(() => ({ rasterize: vi.fn() }));
+vi.mock('../src/platform', () => ({
+ platformHasGlyphRasterizer: () => true,
+ platformRasterizeGlyph: host.rasterize,
+}));
+
+beforeEach(() => {
+ vi.resetModules();
+ vi.stubGlobal('document', undefined);
+ host.rasterize.mockReset().mockImplementation(({ pixelSize, codepoint }) => ({
+ advance: pixelSize / 2 + codepoint % 3,
+ }));
+});
+afterEach(() => vi.unstubAllGlobals());
+
+it('retires historical font measurements while retaining recently used advances', async () => {
+ const { measureText } = await import('../src/ui/text/measure-text');
+ const measure = (fontFamily: string) => measureText('W', { fontSize: 20, fontFamily }).width;
+ const first = measure('old');
+ const hot = measure('hot');
+ for (let i = 0; i < 8192; i++) {
+ measure(`font-${i}`);
+ expect(measure('hot')).toBe(hot);
+ }
+ const calls = host.rasterize.mock.calls.length;
+ expect(measure('font-8191')).toBe(first);
+ expect(host.rasterize).toHaveBeenCalledTimes(calls);
+ expect(measure('old')).toBe(first);
+ expect(host.rasterize).toHaveBeenCalledTimes(calls + 1);
+ expect(host.rasterize.mock.calls.filter(([r]) => r.fontFamily === 'hot')).toHaveLength(1);
+});
+
+it('bounds fallback advances for unavailable glyphs too', async () => {
+ const { measureText } = await import('../src/ui/text/measure-text');
+ host.rasterize.mockReturnValue(null);
+ const measure = (fontFamily: string) => measureText('中', { fontSize: 20, fontFamily }).width;
+ expect(measure('missing')).toBe(12);
+ for (let i = 0; i < 4096; i++) measure(`missing-${i}`);
+ const calls = host.rasterize.mock.calls.length;
+ expect(measure('missing')).toBe(12);
+ expect(host.rasterize).toHaveBeenCalledTimes(calls + 1);
+});
+
+it('keeps zero advances cached and separates size, style and supplementary characters', async () => {
+ const { measureText } = await import('../src/ui/text/measure-text');
+ host.rasterize.mockReturnValue({ advance: 0 });
+ expect(measureText('🙂🙂', { fontSize: 20, letterSpacing: 2 }).width).toBe(4);
+ expect(host.rasterize).toHaveBeenCalledTimes(1);
+ measureText('🙂', { fontSize: 21 });
+ measureText('🙂', { fontSize: 20, bold: true });
+ measureText('🙂', { fontSize: 20, italic: true });
+ expect(host.rasterize).toHaveBeenCalledTimes(4);
+});
+
+it('can retire a full recently used working set without losing subsequent measurements', async () => {
+ const { measureText } = await import('../src/ui/text/measure-text');
+ const measure = (fontFamily: string) => measureText('W', { fontSize: 20, fontFamily }).width;
+ for (let i = 0; i < 4096; i++) measure(`font-${i}`);
+ for (let i = 0; i < 4096; i++) measure(`font-${i}`);
+ expect(host.rasterize).toHaveBeenCalledTimes(4096);
+ expect(measure('replacement')).toBe(10);
+ expect(measure('replacement')).toBe(10);
+ expect(host.rasterize).toHaveBeenCalledTimes(4097);
+ measure('font-0');
+ expect(host.rasterize).toHaveBeenCalledTimes(4098);
+});
+
+it('keeps retained measurements available after a host rasterization error', async () => {
+ const { measureText } = await import('../src/ui/text/measure-text');
+ const measure = (fontFamily: string) => measureText('W', { fontSize: 20, fontFamily }).width;
+ for (let i = 0; i < 4096; i++) measure(`font-${i}`);
+ host.rasterize.mockImplementationOnce(() => { throw new Error('host unavailable'); });
+ expect(() => measure('replacement')).toThrow('host unavailable');
+ const calls = host.rasterize.mock.calls.length;
+ expect(measure('font-0')).toBe(10);
+ expect(host.rasterize).toHaveBeenCalledTimes(calls);
+ expect(measure('replacement')).toBe(10);
+ expect(host.rasterize).toHaveBeenCalledTimes(calls + 1);
+});
diff --git a/tools/releaseNotes.mjs b/tools/releaseNotes.mjs
index 77a99c0ed..7d070afc9 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 = {
+ 'fix(text): bound native measurement advance history':
+ { note: 'Public native text measurement retains a bounded advance cache.' },
'fix(text): isolate font reload ownership and glyph caches':
{ note: 'Font reloads retain independent handles and glyph caches.' },
'fix(text): encode font paths without identity collisions':