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): preloadGlyphs puts a text's characters on the atlas ahead of time, a slice a frame, so the frame that shows them does not pay for them

yhh9e1a97c8afe6
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 78c1555be..bc13d0c32 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -16,6 +16,7 @@ published separately; it ships inside the editor.
### Added
+- **Glyphs can be put on the atlas before they are shown.** The first page of a novel is hundreds of new characters, all landing in one frame. `preloadGlyphs(app, label, text, { budgetMs })` makes them ahead of time, a slice a frame, drawn as that `Text` will draw them, and returns `progress`, `done` and `release()`. On a Snapdragon 8 Elite a book's 2992 characters at 28 px took 145 ms over 25 frames with the worst frame at 9.5 ms, after which the first page's frame went from 49 to 11 ms and no page made a new glyph. Preloaded glyphs hold their atlas pages (4 MB each, a few hundred characters at that size) until `release()`.
- **Voxel GI lights what the camera does not see, and bounces light more than once.** The cache now reads the sun's shadow map back into the world, so a surface the sun lights behind or beside the camera still sends light into the view. Each surface also gives off again the bounce light it received, so a corner or a floor in shade gets light that took two or more bounces to reach it. A ray now brings what it meets at full strength however far it went (it used to fade with distance, 40% at 4 m with 12 cm voxels). Each voxel is weighed by how much of it a surface covers, so a bright patch no longer lights like the whole voxel around it. Together these keep the result close to a path tracer's whatever the voxel size. In a sunlit test room the whole frame carries 0.95 of Cycles' light at the default size and 0.74 at 12 cm voxels; before, it was 0.54 at the default and darker the finer the grid. With the lit patch behind the camera, the walls went from no bounce light to 25–57%. A closed room the sun only lights from outside stays dark. Two inspector controls tune it: **Off-screen Sun Albedo** (the colour the shadow map cannot give, assumed) and **Multi-bounce**. A fine grid no longer drops every voxel: a count truncated by the cache's ageing had kept them below the two samples a ray asks for. The WebGL2 fallback does the same in its own passes: each voxel asks the sun's map whether a sunlit surface stands in it, and traces two rays through last frame's grid for the light it is given. In the test room it carries 1.00 of Cycles' light at the default size (it was 0.56) and 0.80 at 12 cm; with the lit patch behind the camera 0.20 (it was 0). Its voxel pass costs about 1.3 ms more at 720p on a desktop.
- **A model of many parts that moves: `CompositeBatch`.** Put it on the root of a ship, a vehicle or a moving platform assembled from many meshes, and while the game runs its parts are drawn in a few draws parented to the root: a mesh repeated four times or more (a deck plank, a rail post) as one instanced set that copies no vertices, every other part merged by draw state into chunks of the root's own space. Moving, turning or scaling the root moves the whole model and merges nothing again. Adding, removing, re-meshing or re-placing a part re-merges only its chunk within half a second (`CompositeBatchingRes.refresh(root)` looks at once), and a part that keeps moving inside the model is let go to draw itself. The root reports what it drew, and so does `get_stats`. On a model of 2,004 parts, the meshes handed to the renderer went from 2,003 to 5 and the CPU frame from 3.3 ms to 1.2–1.4 ms; a model of about a hundred parts costs the same either way. A part under a composite is never also statically batched.
diff --git a/docs/astro/src/content/docs/ui/text.mdx b/docs/astro/src/content/docs/ui/text.mdx
index 34e4b78e6..a77894ec0 100644
--- a/docs/astro/src/content/docs/ui/text.mdx
+++ b/docs/astro/src/content/docs/ui/text.mdx
@@ -299,6 +299,25 @@ first, in `strokeColor`, then the glyph in `color`. `strokeWidth` only says whet
there is a ring (the page's ring is drawn, not grown), and without one only the
glyph is drawn, so the outline can be any colour, translucent, or absent.
+## Preloading glyphs
+
+A character is made the first time it appears, and that takes time: one or two go unnoticed, but the first page of a novel is hundreds of new characters, all in one frame. If you know what is coming, make them on a loading screen:
+
+```ts
+import { preloadGlyphs } from 'esengine';
+
+const preload = preloadGlyphs(app, label, chapterText, { budgetMs: 8 });
+showProgress(() => preload.progress);
+await preload.done;
+// ...when the chapter is over:
+preload.release();
+```
+
+- The font, size, style and render mode are read from `label`'s `Text`, which need not be visible yet.
+- It spends at most `budgetMs` a frame (4 by default). Repeated characters cost nothing.
+- Preloaded glyphs hold their atlas pages until `release()`. A 1024×1024 page takes 4 MB of video memory and holds a few hundred characters at novel sizes.
+- Text in a rich-text size or an outline is another atlas cell, and is still made when it first shows.
+
## Localization
Set `i18nKey` instead of hand-writing `content`: while a Localization resource
diff --git a/docs/astro/src/content/docs/zh-cn/ui/text.mdx b/docs/astro/src/content/docs/zh-cn/ui/text.mdx
index 3c373d742..84e7fa546 100644
--- a/docs/astro/src/content/docs/zh-cn/ui/text.mdx
+++ b/docs/astro/src/content/docs/zh-cn/ui/text.mdx
@@ -263,6 +263,25 @@ addStartupSystem(buildBubble);
再用 `color` 画字形。`strokeWidth` 只表示有没有圈(页面里的圈是画出来的,不是长出来
的);没有它时只画字形,所以描边可以是任意颜色、半透明,或者没有。
+## 预加载字形
+
+字第一次出现时才生成,要花时间:一两个字没感觉,但小说第一页有几百个新字,会全部挤在同一帧里。知道接下来要显示什么的话,可以在加载界面提前生成:
+
+```ts
+import { preloadGlyphs } from 'esengine';
+
+const preload = preloadGlyphs(app, label, chapterText, { budgetMs: 8 });
+showProgress(() => preload.progress);
+await preload.done;
+// ……这一章读完后:
+preload.release();
+```
+
+- 字体、字号、粗斜体、渲染模式都从 `label` 这个 `Text` 读取,它可以先不显示。
+- 每帧最多花 `budgetMs` 毫秒(默认 4),重复的字不花时间。
+- 预加载的字会一直占着图集页,直到调用 `release()`。一页 1024×1024 占 4 MB 显存,小说字号下约放两三百字。
+- 富文本里改了字号的文字和带描边的文字是另外的图集单元,仍在第一次显示时生成。
+
## 本地化
不要手写 `content`,改设 `i18nKey`:存在 Localization 资源时(安装
diff --git a/sdk/etc/index.api.md b/sdk/etc/index.api.md
index 13068e027..cdeb0dc52 100644
--- a/sdk/etc/index.api.md
+++ b/sdk/etc/index.api.md
@@ -1,7 +1,7 @@
# API surface — esengine/index
<!-- Generated by tools/api-surface.mjs — do not edit. Run --update to accept changes. -->
-Symbols: 115 public · 164 beta · 2046 experimental · 3 deprecated
+Symbols: 115 public · 164 beta · 2049 experimental · 3 deprecated
## ABI_LAYOUT_HASH — const @experimental
```
@@ -4877,6 +4877,18 @@ static prototype: GestureDetector
PlatformImage | PlatformCanvas | ImageBitmap
```
+## GlyphPreload — interface @experimental
+```
+done: Promise<void>
+progress: number
+release: () => void
+```
+
+## GlyphPreloadOptions — interface @experimental
+```
+budgetMs: number | undefined
+```
+
## GpAxis — const @public
```
(axis: number, pad?: number, scale?: number) => Binding
@@ -11374,6 +11386,7 @@ width: number
build: (app: App) => void
cleanup: (app?: App) => void
name: string
+preload: (app: App, entity: Entity, text: string, options?: GlyphPreloadOptions) => GlyphPreload
static new (): TextPlugin
static prototype: TextPlugin
```
@@ -16230,6 +16243,11 @@ PostProcessPlugin
PrefabsPlugin
```
+## preloadGlyphs — function @experimental
+```
+(app: App, entity: Entity, text: string, options?: GlyphPreloadOptions): GlyphPreload
+```
+
## preloadNestedPrefabs — function @experimental
```
(prefab: PrefabData, loadPrefab: (path: string) => Promise<PrefabData>, cache: Map<string, PrefabData>, visited?: Set<string>, depth?: number): Promise<void>
diff --git a/sdk/etc/index.native.api.md b/sdk/etc/index.native.api.md
index 73df06fff..c5539cc0a 100644
--- a/sdk/etc/index.native.api.md
+++ b/sdk/etc/index.native.api.md
@@ -1,7 +1,7 @@
# API surface — esengine/index.native
<!-- Generated by tools/api-surface.mjs — do not edit. Run --update to accept changes. -->
-Symbols: 115 public · 169 beta · 2065 experimental · 3 deprecated
+Symbols: 115 public · 169 beta · 2068 experimental · 3 deprecated
## ABI_LAYOUT_HASH — const @experimental
```
@@ -4885,6 +4885,18 @@ static prototype: GestureDetector
PlatformImage | PlatformCanvas | ImageBitmap
```
+## GlyphPreload — interface @experimental
+```
+done: Promise<void>
+progress: number
+release: () => void
+```
+
+## GlyphPreloadOptions — interface @experimental
+```
+budgetMs: number | undefined
+```
+
## GpAxis — const @public
```
(axis: number, pad?: number, scale?: number) => Binding
@@ -11587,6 +11599,7 @@ width: number
build: (app: App) => void
cleanup: (app?: App) => void
name: string
+preload: (app: App, entity: Entity, text: string, options?: GlyphPreloadOptions) => GlyphPreload
static new (): TextPlugin
static prototype: TextPlugin
```
@@ -16493,6 +16506,11 @@ PostProcessPlugin
PrefabsPlugin
```
+## preloadGlyphs — function @experimental
+```
+(app: App, entity: Entity, text: string, options?: GlyphPreloadOptions): GlyphPreload
+```
+
## preloadNestedPrefabs — function @experimental
```
(prefab: PrefabData, loadPrefab: (path: string) => Promise<PrefabData>, cache: Map<string, PrefabData>, visited?: Set<string>, depth?: number): Promise<void>
diff --git a/sdk/etc/index.node.api.md b/sdk/etc/index.node.api.md
index 801d7b7d5..95d569f5b 100644
--- a/sdk/etc/index.node.api.md
+++ b/sdk/etc/index.node.api.md
@@ -1,7 +1,7 @@
# API surface — esengine/index.node
<!-- Generated by tools/api-surface.mjs — do not edit. Run --update to accept changes. -->
-Symbols: 115 public · 166 beta · 2045 experimental · 3 deprecated
+Symbols: 115 public · 166 beta · 2048 experimental · 3 deprecated
## ANCHOR_AXES — const @experimental
```
@@ -4872,6 +4872,18 @@ static prototype: GestureDetector
PlatformImage | PlatformCanvas | ImageBitmap
```
+## GlyphPreload — interface @experimental
+```
+done: Promise<void>
+progress: number
+release: () => void
+```
+
+## GlyphPreloadOptions — interface @experimental
+```
+budgetMs: number | undefined
+```
+
## GpAxis — const @public
```
(axis: number, pad?: number, scale?: number) => Binding
@@ -11369,6 +11381,7 @@ width: number
build: (app: App) => void
cleanup: (app?: App) => void
name: string
+preload: (app: App, entity: Entity, text: string, options?: GlyphPreloadOptions) => GlyphPreload
static new (): TextPlugin
static prototype: TextPlugin
```
@@ -16235,6 +16248,11 @@ PostProcessPlugin
PrefabsPlugin
```
+## preloadGlyphs — function @experimental
+```
+(app: App, entity: Entity, text: string, options?: GlyphPreloadOptions): GlyphPreload
+```
+
## preloadNestedPrefabs — function @experimental
```
(prefab: PrefabData, loadPrefab: (path: string) => Promise<PrefabData>, cache: Map<string, PrefabData>, visited?: Set<string>, depth?: number): Promise<void>
diff --git a/sdk/etc/minigame.api.md b/sdk/etc/minigame.api.md
index 278930160..adf91ecac 100644
--- a/sdk/etc/minigame.api.md
+++ b/sdk/etc/minigame.api.md
@@ -1,7 +1,7 @@
# API surface — esengine/minigame
<!-- Generated by tools/api-surface.mjs — do not edit. Run --update to accept changes. -->
-Symbols: 115 public · 164 beta · 2067 experimental · 3 deprecated
+Symbols: 115 public · 164 beta · 2070 experimental · 3 deprecated
## ANCHOR_AXES — const @experimental
```
@@ -4872,6 +4872,18 @@ static prototype: GestureDetector
PlatformImage | PlatformCanvas | ImageBitmap
```
+## GlyphPreload — interface @experimental
+```
+done: Promise<void>
+progress: number
+release: () => void
+```
+
+## GlyphPreloadOptions — interface @experimental
+```
+budgetMs: number | undefined
+```
+
## GpAxis — const @public
```
(axis: number, pad?: number, scale?: number) => Binding
@@ -11665,6 +11677,7 @@ width: number
build: (app: App) => void
cleanup: (app?: App) => void
name: string
+preload: (app: App, entity: Entity, text: string, options?: GlyphPreloadOptions) => GlyphPreload
static new (): TextPlugin
static prototype: TextPlugin
```
@@ -16542,6 +16555,11 @@ PostProcessPlugin
PrefabsPlugin
```
+## preloadGlyphs — function @experimental
+```
+(app: App, entity: Entity, text: string, options?: GlyphPreloadOptions): GlyphPreload
+```
+
## preloadNestedPrefabs — function @experimental
```
(prefab: PrefabData, loadPrefab: (path: string) => Promise<PrefabData>, cache: Map<string, PrefabData>, visited?: Set<string>, depth?: number): Promise<void>
diff --git a/sdk/etc/wechat.api.md b/sdk/etc/wechat.api.md
index 93afba55d..434610e1a 100644
--- a/sdk/etc/wechat.api.md
+++ b/sdk/etc/wechat.api.md
@@ -1,7 +1,7 @@
# API surface — esengine/wechat
<!-- Generated by tools/api-surface.mjs — do not edit. Run --update to accept changes. -->
-Symbols: 115 public · 164 beta · 2058 experimental · 3 deprecated
+Symbols: 115 public · 164 beta · 2061 experimental · 3 deprecated
## ANCHOR_AXES — const @experimental
```
@@ -4872,6 +4872,18 @@ static prototype: GestureDetector
PlatformImage | PlatformCanvas | ImageBitmap
```
+## GlyphPreload — interface @experimental
+```
+done: Promise<void>
+progress: number
+release: () => void
+```
+
+## GlyphPreloadOptions — interface @experimental
+```
+budgetMs: number | undefined
+```
+
## GpAxis — const @public
```
(axis: number, pad?: number, scale?: number) => Binding
@@ -11376,6 +11388,7 @@ width: number
build: (app: App) => void
cleanup: (app?: App) => void
name: string
+preload: (app: App, entity: Entity, text: string, options?: GlyphPreloadOptions) => GlyphPreload
static new (): TextPlugin
static prototype: TextPlugin
```
@@ -16268,6 +16281,11 @@ PostProcessPlugin
PrefabsPlugin
```
+## preloadGlyphs — function @experimental
+```
+(app: App, entity: Entity, text: string, options?: GlyphPreloadOptions): GlyphPreload
+```
+
## preloadNestedPrefabs — function @experimental
```
(prefab: PrefabData, loadPrefab: (path: string) => Promise<PrefabData>, cache: Map<string, PrefabData>, visited?: Set<string>, depth?: number): Promise<void>
diff --git a/sdk/src/core-ui.ts b/sdk/src/core-ui.ts
index 80f0c925b..559b57637 100644
--- a/sdk/src/core-ui.ts
+++ b/sdk/src/core-ui.ts
@@ -29,6 +29,9 @@ export {
UILayoutGeneration,
UIMask,
measureText,
+ preloadGlyphs,
+ type GlyphPreload,
+ type GlyphPreloadOptions,
inspectTextLayout,
type TextInspection,
type TextInspectionOptions,
diff --git a/sdk/src/ui/index.ts b/sdk/src/ui/index.ts
index ba36ef596..7a0d488f4 100644
--- a/sdk/src/ui/index.ts
+++ b/sdk/src/ui/index.ts
@@ -352,7 +352,8 @@ export { BUILTIN_UI_PREFABS, BUILTIN_UI_WIDGET_NAMES } from './widgets/prefabs/g
// All text — display (Text) and editable (TextInput) — now renders through the
// SDF glyph atlas; the Canvas2D TextRenderer was retired.
-export { TextPlugin, textPlugin, resolveTextRenderMode, glyphContentScale } from './text/plugin';
+export { TextPlugin, textPlugin, preloadGlyphs, resolveTextRenderMode, glyphContentScale } from './text/plugin';
+export type { GlyphPreload, GlyphPreloadOptions } from './text/glyph-preload';
export { InlineImagePlugin, inlineImagePlugin } from './text/inline-image-plugin';
export { measureText, type MeasureTextOptions, type TextMetrics } from './text/measure-text';
export { inspectTextLayout, type TextInspection, type TextInspectionOptions } from './text/inspect-text';
diff --git a/sdk/src/ui/text/glyph-preload.ts b/sdk/src/ui/text/glyph-preload.ts
new file mode 100644
index 000000000..c98b6b770
--- /dev/null
+++ b/sdk/src/ui/text/glyph-preload.ts
@@ -0,0 +1,91 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
+/**
+ * @file ui/text/glyph-preload.ts
+ * @brief Putting glyphs on the atlas before they are shown, a few milliseconds a frame.
+ *
+ * A character costs the frame it first appears in. One is nothing; the first page
+ * of a novel is hundreds, and on a phone that frame runs long. A game knows what it
+ * is about to show, so it can spend that time on its loading screen instead, spread
+ * over frames rather than in one.
+ *
+ * This holds only the walk: which character is next, and when the frame's budget is
+ * spent. Producing a glyph is the sink's, so a preloaded glyph is the same atlas cell
+ * the layout would have asked for (TextPlugin.preload).
+ */
+
+export interface GlyphPreloadOptions {
+ /** Milliseconds of glyph work per frame. A loading screen with nothing else to do can give it more. Default 4. */
+ budgetMs?: number;
+}
+
+export interface GlyphPreload {
+ /** Characters done over characters asked for, 0 to 1. */
+ readonly progress: number;
+ /** Resolves when every character is on the atlas, or the preload was released first. */
+ readonly done: Promise<void>;
+ /**
+ * Stop, if it has not finished, and let the atlas pages go. Preloaded glyphs keep their pages until this is called, since a page no
+ * text is showing is otherwise released at the next frame: call it when the chapter they were for is over. Text showing them keeps
+ * what it uses.
+ */
+ release(): void;
+}
+
+export const DEFAULT_PRELOAD_BUDGET_MS = 4;
+
+/** The distinct characters of @p text that have a glyph to make: control characters (a line break) do not. */
+export function preloadCodepoints(text: string): number[] {
+ const seen = new Set<number>();
+ for (const ch of text) {
+ const cp = ch.codePointAt(0)!;
+ if (cp >= 0x20) seen.add(cp);
+ }
+ return [...seen];
+}
+
+export class GlyphPreloadJob implements GlyphPreload {
+ readonly done: Promise<void>;
+ private resolve_!: () => void;
+ private next_ = 0;
+ private finished_ = false;
+
+ /** @param onRelease Lets go of what the job holds; called once, by release() only. */
+ constructor(
+ private readonly codepoints: readonly number[],
+ private readonly budgetMs: number,
+ private readonly onRelease: () => void,
+ ) {
+ this.done = new Promise((resolve) => { this.resolve_ = resolve; });
+ if (codepoints.length === 0) this.finish();
+ }
+
+ get progress(): number {
+ return this.codepoints.length === 0 ? 1 : this.next_ / this.codepoints.length;
+ }
+
+ get finished(): boolean { return this.finished_; }
+
+ /** Feed @p make characters until the budget on @p now is spent. At least one, so a slow device still gets there. */
+ step(make: (codepoint: number) => void, now: () => number): void {
+ if (this.finished_) return;
+ const end = now() + this.budgetMs;
+ do {
+ make(this.codepoints[this.next_]!);
+ this.next_++;
+ } while (this.next_ < this.codepoints.length && now() < end);
+ if (this.next_ >= this.codepoints.length) this.finish();
+ }
+
+ /** No more work is coming: the entity is gone, or the host is. */
+ finish(): void {
+ if (this.finished_) return;
+ this.finished_ = true;
+ this.resolve_();
+ }
+
+ release(): void {
+ this.finish();
+ this.onRelease();
+ }
+}
diff --git a/sdk/src/ui/text/plugin.ts b/sdk/src/ui/text/plugin.ts
index 14755f402..44a0304a9 100644
--- a/sdk/src/ui/text/plugin.ts
+++ b/sdk/src/ui/text/plugin.ts
@@ -29,7 +29,8 @@ import { UICameraInfo, type UICameraData } from '../core/ui-camera-info';
import { ScreenOverlay } from '../core/screen-overlay';
import { getUINodeWidth, getUINodeHeight, ensureUIVisual } from '../util/helpers';
import { resolveTextFamily } from './font-registry';
-import { platformDevicePixelRatio } from '../../platform';
+import { DEFAULT_PRELOAD_BUDGET_MS, GlyphPreloadJob, preloadCodepoints, type GlyphPreload, type GlyphPreloadOptions } from './glyph-preload';
+import { platformDevicePixelRatio, platformNow } from '../../platform';
import { engineApi, type EngineApi } from '../../ecs/bridge/engineApi';
import { withScratch } from '../../wasm/wasmScratch';
// UI quads use layer = base + uiOrder, off the C++ declaration that owns it.
@@ -147,6 +148,17 @@ export function sameSnapshot(s: TextSnapshot, t: TextData, family: string): bool
&& s.hr === t.shadowColor.r && s.hg === t.shadowColor.g && s.hb === t.shadowColor.b && s.ha === t.shadowColor.a;
}
+/** How many frames a preload waits for the projection before it takes the size it can get. */
+const PRELOAD_PROJECTION_FRAMES = 30;
+
+/** One preload and where it stands. The object is also what holds its atlas pages. */
+interface PreloadRun {
+ entity: Entity;
+ framesWaited: number;
+ renderer: SdfTextRenderer | null;
+ job: GlyphPreloadJob;
+}
+
/** The two domains a Text can belong to, and the state each keeps. */
interface TextDomainState {
bitmap: SdfTextRenderer | null;
@@ -162,8 +174,12 @@ export class TextPlugin implements Plugin {
matrix: Float32Array;
matrixHeap: Float32Array | null;
retained: Map<number, RetainedLabel>;
+ preloads: PreloadRun[];
}>();
+ /** Apps this plugin was built on: only those step a preload. */
+ private readonly built_ = new WeakSet<App>();
+
private stateFor(app: App) {
let state = this.states_.get(app);
if (!state) {
@@ -172,6 +188,7 @@ export class TextPlugin implements Plugin {
screen: { bitmap: null, sdf: null },
matrix: new Float32Array(16), matrixHeap: null,
retained: new Map(),
+ preloads: [],
};
this.states_.set(app, state);
}
@@ -183,6 +200,7 @@ export class TextPlugin implements Plugin {
const state = this.states_.get(app);
if (!state) return;
this.states_.delete(app);
+ for (const run of state.preloads) run.job.finish();
const errors: unknown[] = [];
for (const renderer of [state.world.bitmap, state.world.sdf, state.screen.bitmap, state.screen.sdf]) {
try { renderer?.dispose(); } catch (error) { errors.push(error); }
@@ -192,6 +210,7 @@ export class TextPlugin implements Plugin {
build(app: App): void {
registerComponent('Text', Text);
+ this.built_.add(app);
const world = app.world;
@@ -203,6 +222,11 @@ export class TextPlugin implements Plugin {
}
}, { name: 'TextPageLifetimeSystem' }));
+ app.addSystemToSchedule(Schedule.PreUpdate, defineSystem([], () => {
+ const state = this.states_.get(app);
+ if (state && state.preloads.length > 0) this.stepPreloads(app, state.preloads);
+ }, { name: 'TextGlyphPreloadSystem' }));
+
// A Text node inside a UINode is a UI render node: ensure it carries a
// UIVisual (visualType None — not drawn as a quad) so the UI
// render-order pass assigns it a uiOrder and the SDF glyphs sort with
@@ -589,6 +613,64 @@ export class TextPlugin implements Plugin {
state.sdf?.retainOnly(seen);
}
+ /**
+ * Put the glyphs of @p text on the atlas ahead of time, a slice a frame, as @p entity's Text will draw them: its font, size, style and
+ * pipeline, in its domain. Everything is read from the Text rather than asked for again, since a glyph at another size or in another
+ * atlas is a different cell and preloading it would buy nothing. See {@link preloadGlyphs}.
+ */
+ preload(app: App, entity: Entity, text: string, options: GlyphPreloadOptions = {}): GlyphPreload {
+ const budgetMs = options.budgetMs !== undefined && options.budgetMs > 0 ? options.budgetMs : DEFAULT_PRELOAD_BUDGET_MS;
+ const state = this.stateFor(app);
+ const run: PreloadRun = {
+ entity,
+ framesWaited: 0,
+ renderer: null,
+ job: new GlyphPreloadJob(preloadCodepoints(text), budgetMs, () => {
+ run.renderer?.releasePreload(run);
+ const at = state.preloads.indexOf(run);
+ if (at >= 0) state.preloads.splice(at, 1);
+ }),
+ };
+ // With nothing to draw with (a logic-only host) there is no atlas to fill.
+ if (!this.built_.has(app) || !app.pipeline) run.job.finish();
+ if (!run.job.finished) state.preloads.push(run);
+ return run.job;
+ }
+
+ private stepPreloads(app: App, runs: PreloadRun[]): void {
+ // One at a time, so that the budget is the frame's and not each preload's.
+ const run = runs.find((r) => !r.job.finished);
+ if (!run) return;
+ const world = app.world;
+ if (!world.valid(run.entity) || !world.has(run.entity, Text) || !world.has(run.entity, Transform)) {
+ run.job.finish();
+ return;
+ }
+ const api = engineApi(app);
+ const registry = world.getCppRegistry() as CppRegistry | null;
+ const screen = !!(api?.ui_isScreenDomain && registry) && api.ui_isScreenDomain(registry, run.entity as number);
+ // Bitmap glyphs are rasterized for the projection that draws them, which is known from the first frame on. Asked before it, they would
+ // be another size than the ones drawn. A scene that never has one draws no text, so this does not wait for ever.
+ if (!this.projectionKnown(app, screen) && run.framesWaited++ < PRELOAD_PROJECTION_FRAMES) return;
+
+ const t = world.get(run.entity, Text) as TextData;
+ const tr = world.get(run.entity, Transform) as TransformData;
+ const family = resolveTextFamily(t.font, t.fontFamily);
+ const kind = bitmapFontOf(family) ? 'bitmap' : resolveTextRenderMode(t.renderMode, tr.worldScale.x);
+ const dpr = platformDevicePixelRatio();
+ const contentScale = screen ? this.screenContentScale(app, dpr) : this.worldContentScale(app, dpr);
+ const appState = this.stateFor(app);
+ const renderer = this.rendererFor(app, screen ? appState.screen : appState.world, kind, contentScale, dpr);
+ run.renderer = renderer;
+ const style = (t.bold ? UI_TEXT_BOLD : 0) | (t.italic ? UI_TEXT_ITALIC : 0);
+ run.job.step((codepoint) => renderer.preloadGlyph(run, codepoint, family, style, t.fontSize), platformNow);
+ }
+
+ private projectionKnown(app: App, screen: boolean): boolean {
+ if (screen) return app.hasResource(ScreenOverlay) && app.getResource(ScreenOverlay).active;
+ return !!(app.getResource(UICameraInfo) as UICameraData | undefined)?.valid;
+ }
+
/** World text rasterizes for the camera showing it — zoom in, get sharper. */
private worldContentScale(app: App, dpr: number): number {
const cam = app.getResource(UICameraInfo) as UICameraData | undefined;
@@ -632,3 +714,16 @@ export class TextPlugin implements Plugin {
}
export const textPlugin = new TextPlugin();
+
+/**
+ * Put the glyphs of @p text on the atlas before they are shown, so the frame that shows them does not pay for them. The first page of a
+ * novel is hundreds of new characters, and they all land in one frame otherwise. Give it what is coming (a chapter, the next scene's
+ * lines) on a loading screen and wait on `done`, or let it run behind the game: it spends `budgetMs` a frame.
+ *
+ * @param entity The Text that will show them, which says how they are drawn. It need not be visible.
+ * @param text Repeated characters cost nothing. Text in a rich-text size or an outline is another cell, and is made when it first shows.
+ * @returns Call `release()` when the text is over: the glyphs hold their atlas pages until then.
+ */
+export function preloadGlyphs(app: App, entity: Entity, text: string, options?: GlyphPreloadOptions): GlyphPreload {
+ return textPlugin.preload(app, entity, text, options);
+}
diff --git a/sdk/src/ui/text/text-renderer.ts b/sdk/src/ui/text/text-renderer.ts
index 865e7b778..adef89ce2 100644
--- a/sdk/src/ui/text/text-renderer.ts
+++ b/sdk/src/ui/text/text-renderer.ts
@@ -398,6 +398,8 @@ export class SdfTextRenderer {
private readonly drawn_ = new Set<number>();
/** The atlas pages the retained labels of this renderer draw from, so the pages outlive the frames the labels are not rebuilt in. */
private readonly retainedPages_ = new Map<number, number[]>();
+ /** Pages held for glyphs not on screen yet, by the preload holding them. */
+ private readonly pinnedPages_ = new Map<object, Set<number>>();
/** `module` is null on the native core (no wasm heap); the glyph source is
* then the platform's own rasterizer, since there is no 2D canvas to draw
@@ -435,13 +437,32 @@ export class SdfTextRenderer {
for (const batch of entry.batches) pages.add(batch.pageId);
}
for (const list of this.retainedPages_.values()) for (const pageId of list) pages.add(pageId);
+ for (const pinned of this.pinnedPages_.values()) for (const pageId of pinned) pages.add(pageId);
this.drawn_.clear();
this.atlas.retainPages(pages);
}
+ /**
+ * Put a glyph on the atlas for text that is not drawn yet, at the size a layout of @p fontSizePx will ask for, and hold its page for
+ * @p holder: nothing refers to a page of preloaded glyphs, and the next beginFrame would release it.
+ */
+ preloadGlyph(holder: object, codepoint: number, fontFamily: string, style: number, fontSizePx: number): void {
+ const glyph = this.atlas.getGlyph(codepoint, fontFamily, style, this.atlas.pixelSizeFor(fontSizePx, fontFamily));
+ if (!glyph || glyph.width <= 0) return;
+ let pinned = this.pinnedPages_.get(holder);
+ if (!pinned) this.pinnedPages_.set(holder, pinned = new Set());
+ pinned.add(glyph.pageId);
+ }
+
+ /** Let go of the pages @p holder was holding: the next beginFrame releases those no text uses. */
+ releasePreload(holder: object): void {
+ this.pinnedPages_.delete(holder);
+ }
+
dispose(): void {
this.drawn_.clear();
this.cache_.clear();
+ this.pinnedPages_.clear();
this.retainedPages_.clear();
this.atlas.dispose();
}
diff --git a/sdk/tests/glyph-preload.test.ts b/sdk/tests/glyph-preload.test.ts
new file mode 100644
index 000000000..441c22a7f
--- /dev/null
+++ b/sdk/tests/glyph-preload.test.ts
@@ -0,0 +1,109 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
+/**
+ * @file Preloading glyphs: the walk spends a frame's budget and no more, and a
+ * preloaded glyph survives the page release that runs every frame, which
+ * drops any page no text is showing.
+ */
+import { describe, it, expect, vi } from 'vitest';
+import { GlyphPreloadJob, preloadCodepoints } from '../src/ui/text/glyph-preload';
+import { GlyphAtlas, type AtlasPageStore, type GlyphRasterizer, type RasterGlyph } from '../src/ui/text/glyph-atlas';
+
+describe('preloadCodepoints', () => {
+ it('keeps each character once and leaves out line breaks', () => {
+ expect(preloadCodepoints('下下载\n载 A\t')).toEqual([0x4e0b, 0x8f7d, 0x20, 0x41]);
+ });
+ it('reads a character past the BMP as one', () => {
+ expect(preloadCodepoints('𠀋')).toEqual([0x2000b]);
+ });
+});
+
+describe('GlyphPreloadJob', () => {
+ const job = (cps: number[], budget = 4) => new GlyphPreloadJob(cps, budget, () => {});
+
+ it('stops for the frame when the budget is spent, and goes on the next', () => {
+ let clock = 0;
+ const made: number[] = [];
+ const j = job([1, 2, 3, 4, 5], 4);
+ const make = (cp: number) => { made.push(cp); clock += 2; };
+ j.step(make, () => clock);
+ expect(made).toEqual([1, 2]);
+ expect(j.progress).toBeCloseTo(0.4);
+ j.step(make, () => clock);
+ expect(made).toEqual([1, 2, 3, 4]);
+ expect(j.finished).toBe(false);
+ });
+
+ it('makes one a frame even when one costs more than the budget', () => {
+ let clock = 0;
+ const made: number[] = [];
+ const j = job([1, 2], 4);
+ const make = (cp: number) => { made.push(cp); clock += 100; };
+ j.step(make, () => clock);
+ expect(made).toEqual([1]);
+ j.step(make, () => clock);
+ expect(made).toEqual([1, 2]);
+ expect(j.finished).toBe(true);
+ });
+
+ it('resolves done when the last character is made', async () => {
+ const j = job([1]);
+ j.step(() => {}, () => 0);
+ await expect(j.done).resolves.toBeUndefined();
+ expect(j.progress).toBe(1);
+ });
+
+ it('is done at once with nothing to make', async () => {
+ const j = job([]);
+ expect(j.finished).toBe(true);
+ expect(j.progress).toBe(1);
+ await j.done;
+ });
+
+ it('released early: stops, resolves, lets go once it is asked to', async () => {
+ const onRelease = vi.fn();
+ const j = new GlyphPreloadJob([1, 2, 3], 4, onRelease);
+ const make = vi.fn();
+ j.release();
+ await j.done;
+ j.step(make, () => 0);
+ expect(make).not.toHaveBeenCalled();
+ expect(onRelease).toHaveBeenCalledTimes(1);
+ });
+
+ it('finishing does not let go: the glyphs stay until release', () => {
+ const onRelease = vi.fn();
+ const j = new GlyphPreloadJob([1], 4, onRelease);
+ j.step(() => {}, () => 0);
+ expect(j.finished).toBe(true);
+ expect(onRelease).not.toHaveBeenCalled();
+ });
+});
+
+describe('the page release a preload has to survive', () => {
+ function atlas() {
+ const rasterize = vi.fn((): RasterGlyph => ({
+ pixels: new Uint8Array(10 * 12 * 4), width: 10, height: 12, advance: 11, bearingX: 1, bearingY: 10,
+ }));
+ const rasterizer = { renderSize: 48, spread: 6, rasterize } as unknown as GlyphRasterizer;
+ let next = 100;
+ const store = { createPage: () => next++, uploadSubRegion: () => {} } as unknown as AtlasPageStore;
+ return { atlas: new GlyphAtlas(rasterizer, store, { pageSize: 256 }), rasterize };
+ }
+
+ it('a page nothing pins is released, and its glyph is made again', () => {
+ const { atlas: a, rasterize } = atlas();
+ a.getGlyph(0x4e0b, 'f');
+ a.retainPages(new Set());
+ a.getGlyph(0x4e0b, 'f');
+ expect(rasterize).toHaveBeenCalledTimes(2);
+ });
+
+ it('a pinned page keeps its glyph, and showing it costs no raster', () => {
+ const { atlas: a, rasterize } = atlas();
+ const glyph = a.getGlyph(0x4e0b, 'f')!;
+ a.retainPages(new Set([glyph.pageId]));
+ a.getGlyph(0x4e0b, 'f');
+ expect(rasterize).toHaveBeenCalledTimes(1);
+ });
+});
diff --git a/tools/goldenProjects.mjs b/tools/goldenProjects.mjs
index d1ecdec25..a4b83b600 100644
--- a/tools/goldenProjects.mjs
+++ b/tools/goldenProjects.mjs
@@ -92,6 +92,7 @@ export const CENSUS_FLOOR = '0.60.0';
* that does not exist, and release notes are a different act. Theirs is ungated.
*/
export const SHIPPED = {
+ "Glyphs can be put on the atlas before they are shown.": { notCertifiable: "A pure frame-time saving that changes no pixel, covered by the glyph-preload tests and measured on a device; no golden project shows enough new characters at once to notice." },
"Connect AI tools to the editor from one dialog.": { notCertifiable: "The connect dialog is an editor feature, covered by the mcp-connect editor authoring check and the editor tests; a packaged game carries no editor and no MCP endpoint." },
"Dynamic planar reflections.": { notCertifiable: "Planar reflection is covered by the planar-reflection and planar-reflection-off render-scene pixel gates, tools/tests/planar-reflection.e2e.mjs, test_planar_reflection and the planar-reflection editor authoring check; no golden project carries a reflecting surface." },
"SUD OpenPaaS development export.": { notCertifiable: "The OpenPaaS export is covered by the pipeline export and package tests, the native SUD runtime end-to-end check and the packer verification; no golden project is packaged for OpenPaaS." },
diff --git a/tools/releaseNotes.mjs b/tools/releaseNotes.mjs
index 12ec5a998..ab94f3b56 100644
--- a/tools/releaseNotes.mjs
+++ b/tools/releaseNotes.mjs
@@ -3840,4 +3840,6 @@ export const NOTED = {
{"note":"A new character costs a phone about a third of what it did."},
"fix(native): a bench lifts the pacer's frame-rate cap as well as its floor, so a phone's benched frame reads what it cost":
{"internal":"only the bench switches reach it; a game never runs with them on"},
+ "feat(text): preloadGlyphs puts a text's characters on the atlas ahead of time, a slice a frame, so the frame that shows them does not pay for them":
+ {"note":"Glyphs can be put on the atlas before they are shown."},
};