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): reuse text geometry during inherited opacity fades

yhh1b08047ff6a3
diff --git a/CHANGELOG.md b/CHANGELOG.md
index c9b9eb0d8..367ac8a7c 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -22,6 +22,8 @@ published separately; it ships inside the editor.
### Fixed
+- **UI text fades reuse cached geometry.** Inherited opacity changes update vertex alpha without repeating glyph lookup, layout or index generation. Bitmap and SDF text retain their original fill, rich-text, shadow and outline alpha, restoring it without cumulative fading; authored color and layout changes still rebuild the cache.
+
- **Pointer carets keep supplementary characters intact.** Clicking single-line, multiline or password fields no longer places the caret between the UTF-16 halves of an emoji or another supplementary code point. DOM selection offsets remain UTF-16-based, and existing prefix measurement behavior is preserved.
- **Native text-input notifications survive frame boundaries.** Update systems can read browser and native Change and Submit events after UI interaction clears the previous frame. Subscription callbacks remain synchronous, including focus changes made on Submit; their records reach frame consumers without replaying callbacks. Destroyed fields and disposed editors discard queued records.
diff --git a/sdk/src/ui/text/text-renderer.ts b/sdk/src/ui/text/text-renderer.ts
index 0ea9e2870..dc3f3f693 100644
--- a/sdk/src/ui/text/text-renderer.ts
+++ b/sdk/src/ui/text/text-renderer.ts
@@ -264,6 +264,8 @@ interface CachedTextBatch {
vertices: Float32Array;
indices: Uint16Array;
pageId: number;
+ /** Original vertex alphas, retained lazily so repeated fades never compound. */
+ alphas?: Float32Array;
}
interface TextCacheEntry {
@@ -271,6 +273,7 @@ interface TextCacheEntry {
/** Atlas generation the geometry was built against (bitmap content-scale). */
gen: number;
batches: CachedTextBatch[];
+ opacity: number;
}
export class SdfTextRenderer {
@@ -316,20 +319,32 @@ export class SdfTextRenderer {
depth: number,
cullBit = 0,
): void {
+ const opacity = p.opacity ?? 1;
+ if (opacity <= 0) return;
const gen = this.atlas.generation;
- const sig = signatureOf(p);
+ const sig = textSignature(p, 1);
let entry = this.cache_.get(entity);
if (!entry || entry.gen !== gen || entry.sig !== sig) {
const batches: CachedTextBatch[] = [];
drawTextWith(this.atlas, (vertices, indices, pageId) => {
batches.push({ vertices, indices, pageId });
- }, p);
- entry = { sig, gen, batches };
+ }, { ...p, opacity: 1 });
+ entry = { sig, gen, batches, opacity: 1 };
this.cache_.set(entity, entry);
}
for (const b of entry.batches) {
+ if (entry.opacity !== opacity) {
+ if (!b.alphas) {
+ b.alphas = new Float32Array(b.vertices.length / TEXT_VERTEX_FLOATS);
+ for (let i = 0; i < b.alphas.length; i++) b.alphas[i] = b.vertices[i * TEXT_VERTEX_FLOATS + 7];
+ }
+ for (let i = 0; i < b.alphas.length; i++) {
+ b.vertices[i * TEXT_VERTEX_FLOATS + 7] = b.alphas[i] * opacity;
+ }
+ }
submitTextBatch(this.module, b.vertices, b.indices, b.pageId, transform, entity, layer, depth, this.sdf, cullBit);
}
+ entry.opacity = opacity;
}
/** Drop cached geometry for entities not drawn this frame (despawned / hidden / no longer text). */
@@ -343,6 +358,10 @@ export class SdfTextRenderer {
/** Serialize every DrawTextParams field that affects the laid-out, colored geometry. */
export function signatureOf(p: DrawTextParams): string {
+ return textSignature(p, p.opacity ?? 1);
+}
+
+function textSignature(p: DrawTextParams, opacity: number): string {
const shadow = p.shadow
? `${p.shadow.color.join(',')}:${p.shadow.dx}:${p.shadow.dy}:${p.shadow.blur ?? 0}`
: '';
@@ -354,6 +373,6 @@ export function signatureOf(p: DrawTextParams): string {
p.maxWidth ?? 0, p.boxWidth ?? 0, p.boxHeight ?? 0,
p.overflow ?? TextOverflow.Visible,
p.originX ?? 0, p.originY ?? 0,
- p.color.join(','), p.opacity ?? 1, shadow, outline,
+ p.color.join(','), opacity, shadow, outline,
]);
}
diff --git a/sdk/tests/ui-text-overflow-cache.test.ts b/sdk/tests/ui-text-overflow-cache.test.ts
index bcc81d50e..27bfc5117 100644
--- a/sdk/tests/ui-text-overflow-cache.test.ts
+++ b/sdk/tests/ui-text-overflow-cache.test.ts
@@ -8,6 +8,46 @@ vi.mock('../src/ui/text/submit', async importOriginal => ({
...await importOriginal<typeof import('../src/ui/text/submit')>(), submitTextBatch: vi.fn(),
}));
+it.each([false, true])('reuses multi-page fading geometry without cumulative alpha loss, sdf=%j', sdf => {
+ let nextPage = 1000;
+ const atlas = new GlyphAtlas({ renderSize: 48, spread: sdf ? 6 : 0, rasterize: () => ({
+ pixels: new Uint8Array(10 * 12 * 4), width: 10, height: 12,
+ advance: 11, bearingX: 1, bearingY: 10,
+ }) }, { createPage: () => nextPage++, uploadSubRegion: () => {} }, { pageSize: 32, padding: 1, sdf });
+ const renderer = Object.assign(Object.create(SdfTextRenderer.prototype), {
+ atlas, sdf, module: null, cache_: new Map(),
+ }) as SdfTextRenderer;
+ const p: DrawTextParams = {
+ text: '<color=#ff000080>ABC</color>DEF', richText: true, fontFamily: 'Arial', fontSizePx: 24,
+ color: [1, 1, 1, 0.8], shadow: { color: [0, 0, 0, 0.6], dx: 1, dy: 1 },
+ outline: { color: [0, 1, 0, 0.4], width: 1 },
+ };
+ const transform = new Float32Array(16), submit = vi.mocked(submitTextBatch);
+ submit.mockClear(); renderer.drawText(p, transform, 1, 0, 0);
+ const vertices = submit.mock.calls.map(call => call[1]);
+ expect(atlas.pageCount).toBeGreaterThan(1);
+ const indices = submit.mock.calls.map(call => call[2]);
+ const reads = vi.spyOn(atlas, 'getGlyph');
+ for (const opacity of [0.5, 0.2, 0.8, 1]) {
+ reads.mockClear(); submit.mockClear();
+ renderer.drawText({ ...p, opacity }, transform, 1, 0, 0);
+ expect(reads).not.toHaveBeenCalled();
+ expect(submit.mock.calls).toHaveLength(vertices.length);
+ for (let i = 0; i < vertices.length; i++) {
+ expect(submit.mock.calls[i][1]).toBe(vertices[i]);
+ expect(submit.mock.calls[i][2]).toBe(indices[i]);
+ }
+ const expected: Float32Array[] = [];
+ drawTextWith(atlas, v => expected.push(v), { ...p, opacity });
+ expect(submit.mock.calls.map(call => Array.from(call[1]))).toEqual(expected.map(v => Array.from(v)));
+ }
+ submit.mockClear(); renderer.drawText({ ...p, opacity: 0 }, transform, 1, 0, 0);
+ expect(submit).not.toHaveBeenCalled();
+ reads.mockClear();
+ renderer.drawText({ ...p, color: [1, 1, 0, 0.3] }, transform, 1, 0, 0);
+ expect(reads).toHaveBeenCalled();
+});
+
it('rebuilds only changed overflow geometry while other static text keeps its cached batches', () => {
const atlas = new GlyphAtlas({ renderSize: 48, spread: 0, rasterize: () => ({
pixels: new Uint8Array(10 * 12 * 4), width: 10, height: 12,
diff --git a/tools/releaseNotes.mjs b/tools/releaseNotes.mjs
index d28b3b330..29a82001a 100644
--- a/tools/releaseNotes.mjs
+++ b/tools/releaseNotes.mjs
@@ -30,6 +30,8 @@ export const NOTES_FLOOR = 'v0.65.0';
export const NOTED = {
'feat(playable): package TikTok and overseas Pangle creatives':
{ note: 'TikTok and overseas Pangle package the same playable project.' },
+ 'perf(ui): reuse text geometry during inherited opacity fades':
+ { note: 'UI text fades reuse cached geometry.' },
'fix(ui): keep pointer carets outside surrogate pairs':
{ note: 'Pointer carets keep supplementary characters intact.' },
'fix(ui): deliver native text input events within the UI frame':