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(render): glyph and skeleton atlas pages come back from what made them

esenginedc5c6a193031
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 6ad5e92a3..c953922b0 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -30,7 +30,9 @@ published separately; it ships inside the editor.
grid, meshes, materials or text. Each part of the renderer rebuilt its own GPU objects,
and the ones nothing rebuilt drew with dead handles. The device now rebuilds everything it
issued behind the same handles, puts back the contents it kept, and reloads the rest from
- their assets, on WebGL2 and WebGPU alike.
+ their assets, on WebGL2 and WebGPU alike. Text pages are repainted from their glyphs and
+ skeleton atlas pages decoded again from their images, so neither keeps a second copy in
+ memory — 4 MiB for every 1024×1024 page.
- **A hot update on iOS, Android and desktop builds is still there after a restart
without a network.** The native host only stores cache files under plain names, and
diff --git a/fixtures/scenes/dragonbones-still.esscene b/fixtures/scenes/dragonbones-still.esscene
new file mode 100644
index 000000000..d11936dc5
--- /dev/null
+++ b/fixtures/scenes/dragonbones-still.esscene
@@ -0,0 +1,46 @@
+{
+ "version": 4,
+ "name": "DragonBonesStill",
+ "entities": [
+ {
+ "id": 0,
+ "name": "Camera",
+ "parent": null,
+ "children": [],
+ "components": [
+ { "type": "Transform", "data": { "position": { "x": 0, "y": 0, "z": 10 } } },
+ { "type": "Camera", "data": { "projectionType": 1, "orthoSize": 300, "isActive": true, "priority": 0 } }
+ ],
+ "visible": true
+ },
+ {
+ "id": 1,
+ "name": "DragonBoy",
+ "parent": null,
+ "children": [],
+ "components": [
+ { "type": "Transform", "data": { "position": { "x": 0, "y": -120, "z": 0 } } },
+ {
+ "type": "DragonBonesAnimation",
+ "data": {
+ "skeletonPath": "/assets/dragonbones/DragonBoy_ske.json",
+ "atlasPath": "/assets/dragonbones/DragonBoy_tex.json",
+ "armature": "Dragon",
+ "animation": "stand",
+ "timeScale": 1,
+ "loop": true,
+ "playing": false,
+ "fadeInTime": 0.2,
+ "flipX": false,
+ "flipY": false,
+ "color": { "r": 1, "g": 1, "b": 1, "a": 1 },
+ "layer": 0,
+ "skeletonScale": 1.0,
+ "enabled": true
+ }
+ }
+ ],
+ "visible": true
+ }
+ ]
+}
diff --git a/sdk/src/asset/Assets.ts b/sdk/src/asset/Assets.ts
index b6bd2f8c3..c4b34194d 100644
--- a/sdk/src/asset/Assets.ts
+++ b/sdk/src/asset/Assets.ts
@@ -15,7 +15,7 @@ import type {
import { AsyncCache } from './AsyncCache';
import { TextureContent, textureContentName, type ESEngineModule } from '../wasm';
import type { CppResourceManager } from '../wasm';
-import { requireResourceManager, getResourceManager, evictTextureDimensions } from '../wasm/resourceManager';
+import { requireResourceManager, getResourceManager, evictTextureDimensions, textureRefill } from '../wasm/resourceManager';
import type { TextureImportSettings, TextureImportSettingsResolver } from './loaders/TextureLoader';
import type { TextureFormatReport } from './textureFormatReport';
import { TextureLoader, textureResidencyKey } from './loaders/TextureLoader';
@@ -463,11 +463,9 @@ export class Assets {
}
/**
- * Refills every owed texture this layer can, and gives up on the rest.
- *
- * An asset texture is loaded the ordinary way and moved behind the handle
- * everything holds. Content nobody here can remake is forgone by name: waiting
- * for it would keep the device recovering forever.
+ * Refills every owed texture someone can: an asset texture is loaded again and
+ * moved behind its handle, any other goes to the refill its creator provided.
+ * Content nobody can remake is forgone by name, or the device recovers forever.
*/
async reuploadTexturesAfterDeviceLoss(): Promise<number> {
const rm = requireResourceManager();
@@ -476,9 +474,19 @@ export class Assets {
let restored = 0;
for (const { handle, content, path } of this.texturesAwaitingReupload()) {
if (content !== TextureContent.Asset || !path) {
- log.warn('assets', `Device recovery: texture ${handle} (${textureContentName(content)})`
- + ' has no provider to refill it; it stays blank');
- rm.forgoTextureContent?.(handle);
+ const refill = textureRefill(handle);
+ if (!refill) {
+ log.warn('assets', `Device recovery: texture ${handle} (${textureContentName(content)})`
+ + ' has no provider to refill it; it stays blank');
+ rm.forgoTextureContent?.(handle);
+ continue;
+ }
+ try {
+ if (await refill()) restored++;
+ } catch (e) {
+ log.warn('assets', `Device recovery: refilling texture ${handle}`
+ + ` (${textureContentName(content)}) failed`, e);
+ }
continue;
}
const cut = path.lastIndexOf(':');
diff --git a/sdk/src/runtime/runtimeAssets.ts b/sdk/src/runtime/runtimeAssets.ts
index 853c21955..b5cd4b764 100644
--- a/sdk/src/runtime/runtimeAssets.ts
+++ b/sdk/src/runtime/runtimeAssets.ts
@@ -13,7 +13,7 @@ import { TextureContent, type ESEngineModule } from '../wasm';
import { linearColorSpace } from '../ecs/env';
import type { Backend } from '../asset/Backend';
import type { ParsedTextureImportSettings } from '../asset/textureImportSettings';
-import { requireResourceManager } from '../wasm/resourceManager';
+import { provideTextureContent, requireResourceManager } from '../wasm/resourceManager';
import { isKtx2Path, type BasisTranscoder } from '../asset/compressed';
import { withMalloc } from '../wasm/wasmScratch';
@@ -84,10 +84,9 @@ const WRAP_MODE_MAP: Record<string, number> = { 'repeat': 0, 'clamp': 1, 'mirror
* `module` is the wasm-heap marshalling vehicle; it may be null on the native
* (embedded-Dawn) backend, whose ResourceManager takes the bytes directly. */
/**
- * A texture for an ATLAS PAGE, in whichever form the cook left it. A KTX2 page
- * goes to the ResourceManager where it can decode one (a native host's own basis)
- * and to the realm's wasm transcoder where it cannot — the choice TextureLoader
- * makes for an ordinary texture, which is why it is not made twice more.
+ * A texture for an ATLAS PAGE, in whichever form the cook left it — KTX2 through the
+ * ResourceManager or the realm's transcoder, the choice TextureLoader makes. After a
+ * device loss the page is decoded again and moved behind the handle the skeleton holds.
*/
export async function createAtlasPageTexture(
staged: string,
@@ -95,10 +94,29 @@ export async function createAtlasPageTexture(
decodePixels: (path: string) => Promise<{ width: number; height: number; pixels: Uint8Array }>,
transcoderProvider: (() => Promise<BasisTranscoder | null>) | undefined,
module: ESEngineModule | null,
+): Promise<{ handle: number; width: number; height: number }> {
+ const upload = () => uploadAtlasPage(staged, fetchBinary, decodePixels, transcoderProvider, module);
+ const page = await upload();
+ provideTextureContent(page.handle, async () => {
+ const fresh = await upload();
+ const rm = requireResourceManager();
+ const moved = rm.adoptTextureContent?.(page.handle, fresh.handle) ?? false;
+ rm.releaseTexture(fresh.handle);
+ return moved;
+ });
+ return page;
+}
+
+async function uploadAtlasPage(
+ staged: string,
+ fetchBinary: (path: string) => Promise<ArrayBuffer>,
+ decodePixels: (path: string) => Promise<{ width: number; height: number; pixels: Uint8Array }>,
+ transcoderProvider: (() => Promise<BasisTranscoder | null>) | undefined,
+ module: ESEngineModule | null,
): Promise<{ handle: number; width: number; height: number }> {
if (!isKtx2Path(staged)) {
const decoded = await decodePixels(staged);
- return { handle: createTextureFromPixels(module, decoded, TextureContent.Retained, false), ...decoded };
+ return { handle: createTextureFromPixels(module, decoded, TextureContent.AtlasPage, false), ...decoded };
}
const bytes = new Uint8Array(await fetchBinary(staged));
const rm = requireResourceManager();
@@ -112,7 +130,7 @@ export async function createAtlasPageTexture(
const rgba = transcoder.transcodeToRgba(bytes);
if (!rgba) throw new Error(`KTX2 transcode failed: ${staged}`);
const decoded = { width: rgba.width, height: rgba.height, pixels: rgba.data };
- return { handle: createTextureFromPixels(module, decoded, TextureContent.Retained, false), ...decoded };
+ return { handle: createTextureFromPixels(module, decoded, TextureContent.AtlasPage, false), ...decoded };
}
export function createTextureFromPixels(
diff --git a/sdk/src/spine/loadSpineScene.ts b/sdk/src/spine/loadSpineScene.ts
index 0443bdf85..a0b3347d5 100644
--- a/sdk/src/spine/loadSpineScene.ts
+++ b/sdk/src/spine/loadSpineScene.ts
@@ -26,7 +26,7 @@ import { SpineManager, type SpineVersion } from './SpineManager';
import { prepareSpine, spineEraOf, spinePairKey,
type SpineAssetValue, type SpineEraBinding, type SpineEraClaim, type SpineIO,
type SpinePair } from './prepareSpine';
-import { requireResourceManager } from '../wasm/resourceManager';
+import { requireResourceManager, withdrawTextureContent } from '../wasm/resourceManager';
import { createAtlasPageTexture, type RuntimeAssetSource } from '../runtime/runtimeAssets';
import type { BasisTranscoder } from '../asset/compressed';
import type { AssetsData } from '../asset/AssetPlugin';
@@ -165,7 +165,10 @@ function hostEra(
const drop = (): void => {
if (--claims > 0) return;
const rm = requireResourceManager();
- for (const handle of pages) rm.releaseTexture(handle);
+ for (const handle of pages) {
+ withdrawTextureContent(handle);
+ rm.releaseTexture(handle);
+ }
pages.length = 0;
};
return {
diff --git a/sdk/src/ui/text/atlas-page-store.ts b/sdk/src/ui/text/atlas-page-store.ts
index 3af20b28d..312a6fd9e 100644
--- a/sdk/src/ui/text/atlas-page-store.ts
+++ b/sdk/src/ui/text/atlas-page-store.ts
@@ -9,7 +9,7 @@
*/
import { TextureContent, type ESEngineModule } from '../../wasm';
import { createTextureFromPixels, updateTextureSubregion } from '../../runtime/runtimeAssets';
-import { requireResourceManager } from '../../wasm/resourceManager';
+import { provideTextureContent, requireResourceManager } from '../../wasm/resourceManager';
import type { AtlasPageStore } from './glyph-atlas';
export class EngineAtlasPageStore implements AtlasPageStore {
@@ -21,17 +21,25 @@ export class EngineAtlasPageStore implements AtlasPageStore {
* (embedded-Dawn) core, whose ResourceManager takes the bytes directly. */
constructor(private readonly module: ESEngineModule | null) {}
- createPage(size: number): number {
+ createPage(size: number, paint: (pixels: Uint8Array) => void): number {
// Blank (transparent) RGBA8 page; linear filtering keeps SDF text smooth
// when scaled, clamp avoids edge bleed at the page border.
const pixels = new Uint8Array(size * size * 4);
const handle = createTextureFromPixels(
this.module,
{ width: size, height: size, pixels },
- TextureContent.Retained,
+ TextureContent.GlyphPage,
/* flipY */ false,
{ filterMode: 'linear', wrapMode: 'clamp' },
);
+ // Repainting on demand instead of the device keeping a copy: a page is
+ // 4 MiB of wasm heap at the default size, for an event most sessions never see.
+ provideTextureContent(handle, () => {
+ const page = new Uint8Array(size * size * 4);
+ paint(page);
+ updateTextureSubregion(this.module, handle, 0, 0, size, size, page);
+ return true;
+ });
// The batch binds by GL texture id (mirrors how spine resolves its atlas
// pages); submitTextBatch gets this id as the page id.
const glId = requireResourceManager().getTextureGLId(handle);
diff --git a/sdk/src/ui/text/glyph-atlas.ts b/sdk/src/ui/text/glyph-atlas.ts
index becb4729a..16a4ad2b6 100644
--- a/sdk/src/ui/text/glyph-atlas.ts
+++ b/sdk/src/ui/text/glyph-atlas.ts
@@ -49,8 +49,12 @@ export interface GlyphRasterizer {
}
export interface AtlasPageStore {
- /** Allocate a blank `size`×`size` page; return an opaque page id (e.g. a texture handle). */
- createPage(size: number): number;
+ /**
+ * Allocate a blank `size`×`size` page; return an opaque page id (e.g. a texture
+ * handle). `paint` draws every glyph placed on the page so far into a blank
+ * page-sized RGBA buffer — how a page that lost its pixels gets them back.
+ */
+ createPage(size: number, paint: (pixels: Uint8Array) => void): number;
/** Upload `pixels` into the [x,y,w,h] sub-rect of page `pageId`. */
uploadSubRegion(pageId: number, x: number, y: number, w: number, h: number, pixels: Uint8Array): void;
}
@@ -82,6 +86,18 @@ export interface GlyphAtlasOptions {
const STYLE_COUNT_HINT = 4; // plain / bold / italic / bold-italic — for key spread only
+/** What a page's cell holds: enough to rasterize the glyph again into the same place. */
+interface GlyphPlacement {
+ codepoint: number;
+ fontFamily: string;
+ style: number;
+ pixelSize: number;
+ x: number;
+ y: number;
+ width: number;
+ height: number;
+}
+
/**
* Caches glyphs into one or more atlas pages, rasterizing on first use.
*/
@@ -95,6 +111,7 @@ export class GlyphAtlas {
private readonly cache = new Map<string, GlyphEntry | null>();
private readonly pages: number[] = [];
private readonly packers: Packer[] = [];
+ private readonly placements: GlyphPlacement[][] = [];
constructor(
private readonly rasterizer: GlyphRasterizer,
@@ -201,11 +218,16 @@ export class GlyphAtlas {
return null;
}
- this.store.uploadSubRegion(placed.pageId, placed.x, placed.y, raster.width, raster.height, raster.pixels);
+ const pageId = this.pages[placed.page];
+ this.store.uploadSubRegion(pageId, placed.x, placed.y, raster.width, raster.height, raster.pixels);
+ this.placements[placed.page].push({
+ codepoint, fontFamily, style, pixelSize,
+ x: placed.x, y: placed.y, width: raster.width, height: raster.height,
+ });
const inv = 1 / this.pageSize;
const entry: GlyphEntry = {
- pageId: placed.pageId,
+ pageId,
u0: placed.x * inv,
v0: placed.y * inv,
u1: (placed.x + raster.width) * inv,
@@ -221,7 +243,7 @@ export class GlyphAtlas {
}
/** Reserve a w×h cell across pages, opening a new page when the last is full. */
- private place(w: number, h: number): { pageId: number; x: number; y: number } | null {
+ private place(w: number, h: number): { page: number; x: number; y: number } | null {
const cellW = w + this.padding;
const cellH = h + this.padding;
if (cellW > this.pageSize || cellH > this.pageSize) return null;
@@ -231,7 +253,7 @@ export class GlyphAtlas {
for (let attempt = 0; attempt < 2; attempt++) {
const pi = this.packers.length - 1;
const pos = this.packers[pi].pack(cellW, cellH);
- if (pos) return { pageId: this.pages[pi], x: pos.x, y: pos.y };
+ if (pos) return { page: pi, x: pos.x, y: pos.y };
// Current page full → open a fresh one and retry once.
this.addPage();
}
@@ -239,8 +261,28 @@ export class GlyphAtlas {
}
private addPage(): void {
- const pageId = this.store.createPage(this.pageSize);
- this.pages.push(pageId);
+ const page = this.pages.length;
+ this.placements.push([]);
+ this.pages.push(this.store.createPage(this.pageSize, (pixels) => this.paintPage(page, pixels)));
this.packers.push(new ShelfPacker(this.pageSize, this.pageSize));
}
+
+ /**
+ * Rasterizes a page's glyphs again into the cells they were packed into. A
+ * glyph that now comes out larger (its font finished loading) is clipped to
+ * its cell rather than drawn over a neighbour's.
+ */
+ private paintPage(page: number, pixels: Uint8Array): void {
+ const size = this.pageSize;
+ for (const g of this.placements[page]) {
+ const raster = this.rasterizer.rasterize(g.codepoint, g.fontFamily, g.style, g.pixelSize);
+ if (!raster) continue;
+ const width = Math.min(raster.width, g.width);
+ const height = Math.min(raster.height, g.height);
+ for (let row = 0; row < height; row++) {
+ const from = row * raster.width * 4;
+ pixels.set(raster.pixels.subarray(from, from + width * 4), ((g.y + row) * size + g.x) * 4);
+ }
+ }
+ }
}
diff --git a/sdk/src/wasm.ts b/sdk/src/wasm.ts
index 7eb6f80d1..1e08bb1d1 100644
--- a/sdk/src/wasm.ts
+++ b/sdk/src/wasm.ts
@@ -50,7 +50,7 @@ export interface CppRegistry extends GeneratedRegistry {
export const TextureContent = {
/** Rewritten before every use (a decoded video frame). */
Transient: 0,
- /** The engine keeps the bytes (a glyph page). */
+ /** The engine keeps the bytes (a tile collection composed at load). */
Retained: 1,
/** The asset layer loads it again from its path. */
Asset: 2,
@@ -58,6 +58,10 @@ export const TextureContent = {
Canvas: 3,
/** Refilled by the video it shows. */
Video: 4,
+ /** Repainted from the glyphs placed on it. */
+ GlyphPage: 6,
+ /** A skeleton's atlas page, decoded again from its image. */
+ AtlasPage: 7,
} as const;
export type TextureContent = typeof TextureContent[keyof typeof TextureContent];
diff --git a/sdk/src/wasm/resourceManager.ts b/sdk/src/wasm/resourceManager.ts
index 7d552a1cb..0f6ea685c 100644
--- a/sdk/src/wasm/resourceManager.ts
+++ b/sdk/src/wasm/resourceManager.ts
@@ -22,6 +22,7 @@ class ResourceManagerBridge extends WasmBridge<CppResourceManager> {
const bridge = new ResourceManagerBridge();
let rm_: CppResourceManager | null = null;
const dimsCache_ = new Map<number, TextureDimensions>();
+const refills_ = new Map<number, TextureRefill>();
/** @internal Wired by the engine plugins — not part of the public API. */
export function initResourceManager(rm: CppResourceManager, module?: ESEngineModule): void {
@@ -35,12 +36,14 @@ export function initResourceManager(rm: CppResourceManager, module?: ESEngineMod
rm_ = rm;
}
dimsCache_.clear();
+ refills_.clear();
}
export function shutdownResourceManager(): void {
bridge.disconnect();
rm_ = null;
dimsCache_.clear();
+ refills_.clear();
}
export function getResourceManager(): CppResourceManager | null {
@@ -113,6 +116,28 @@ export function trimTextureCache(): number {
return rm_.trimTextureCache();
}
+/** Puts a texture's content back after a device loss; true once its handle holds it again. */
+export type TextureRefill = () => boolean | Promise<boolean>;
+
+/**
+ * @internal Names who refills `handle` when the device owes its content — for a
+ * texture no asset path can load again. Handles belong to one resource manager,
+ * so the refills go with it.
+ */
+export function provideTextureContent(handle: number, refill: TextureRefill): void {
+ refills_.set(handle, refill);
+}
+
+/** @internal The texture is being released; nothing will be owed for it. */
+export function withdrawTextureContent(handle: number): void {
+ refills_.delete(handle);
+}
+
+/** @internal Who refills `handle`, if anyone said. */
+export function textureRefill(handle: number): TextureRefill | undefined {
+ return refills_.get(handle);
+}
+
export function evictTextureDimensions(handle: number): void {
dimsCache_.delete(handle);
}
diff --git a/sdk/tests/device-recovery-refill.test.ts b/sdk/tests/device-recovery-refill.test.ts
new file mode 100644
index 000000000..0e5cd0a71
--- /dev/null
+++ b/sdk/tests/device-recovery-refill.test.ts
@@ -0,0 +1,72 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
+/**
+ * @file After a device loss, a texture no asset path can load again goes to the
+ * refill its creator provided; one nobody provided for is forgone by name.
+ */
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import { Assets } from '../src/asset/Assets';
+import type { Backend } from '../src/asset/Backend';
+import { TextureContent, type CppResourceManager, type ESEngineModule } from '../src/wasm';
+import {
+ initResourceManager,
+ provideTextureContent,
+ shutdownResourceManager,
+ textureRefill,
+ withdrawTextureContent,
+} from '../src/wasm/resourceManager';
+
+function owing(rows: Array<[number, number, string]>) {
+ const owed = new Map(rows.map(([handle, content, path]) => [handle, { content, path }]));
+ const rm = {
+ texturesAwaitingReupload: () => [...owed].map(([h, o]) => `${h}|${o.content}|${o.path}`).join('\n'),
+ forgoTextureContent: vi.fn((handle: number) => { owed.delete(handle); }),
+ adoptTextureContent: vi.fn(() => true),
+ releaseTexture: vi.fn(),
+ };
+ initResourceManager(rm as unknown as CppResourceManager);
+ const assets = new Assets({
+ backend: { resolveUrl: (p: string) => p } as unknown as Backend,
+ module: { _malloc: () => 0, _free: () => {} } as unknown as ESEngineModule,
+ });
+ return { rm, owed, assets };
+}
+
+afterEach(() => shutdownResourceManager());
+
+describe('device recovery: texture refills', () => {
+ it('asks the refill its creator provided, and forgoes content nobody provided for', async () => {
+ const { rm, owed, assets } = owing([
+ [7, TextureContent.GlyphPage, ''],
+ [8, TextureContent.Canvas, ''],
+ ]);
+ const refill = vi.fn(() => { owed.delete(7); return true; });
+ provideTextureContent(7, refill);
+
+ expect(await assets.reuploadTexturesAfterDeviceLoss()).toBe(1);
+ expect(refill).toHaveBeenCalledTimes(1);
+ expect(rm.forgoTextureContent).toHaveBeenCalledTimes(1);
+ expect(rm.forgoTextureContent).toHaveBeenCalledWith(8);
+ });
+
+ it('keeps a texture owed when its refill fails, so a later attempt can pay it', async () => {
+ const { rm, assets } = owing([[9, TextureContent.AtlasPage, 'dragon/page.png']]);
+ provideTextureContent(9, async () => { throw new Error('offline'); });
+
+ expect(await assets.reuploadTexturesAfterDeviceLoss()).toBe(0);
+ expect(rm.forgoTextureContent).not.toHaveBeenCalled();
+ expect(assets.texturesAwaitingReupload().map((t) => t.handle)).toEqual([9]);
+ });
+
+ it('forgets a withdrawn refill, and every refill when the resource manager goes', () => {
+ owing([]);
+ provideTextureContent(3, () => true);
+ provideTextureContent(4, () => true);
+ withdrawTextureContent(3);
+ expect(textureRefill(3)).toBeUndefined();
+ expect(textureRefill(4)).toBeDefined();
+
+ shutdownResourceManager();
+ expect(textureRefill(4)).toBeUndefined();
+ });
+});
diff --git a/sdk/tests/spine-atlas-page-resolve.test.ts b/sdk/tests/spine-atlas-page-resolve.test.ts
index e932c975b..96ba3da6b 100644
--- a/sdk/tests/spine-atlas-page-resolve.test.ts
+++ b/sdk/tests/spine-atlas-page-resolve.test.ts
@@ -23,6 +23,7 @@ const { rm } = vi.hoisted(() => ({
}));
vi.mock('../src/wasm/resourceManager', () => ({
requireResourceManager: () => rm,
+ provideTextureContent: () => {},
}));
import { loadSpineAssets } from '../src/spine/loadSpineScene';
diff --git a/sdk/tests/ui-glyph-atlas.test.ts b/sdk/tests/ui-glyph-atlas.test.ts
index a4d59c2ec..10bd8b80f 100644
--- a/sdk/tests/ui-glyph-atlas.test.ts
+++ b/sdk/tests/ui-glyph-atlas.test.ts
@@ -123,3 +123,73 @@ describe('REARCH_GUI P1.1c: GlyphAtlas', () => {
expect(atlas.getGlyph(HUGE, 'Arial')).toBeNull();
});
});
+
+describe('GlyphAtlas: a page painted again is the page that was uploaded', () => {
+ const PAGE = 64;
+
+ /** Every texel differs by glyph, row and column, so a misplaced or flipped cell shows. */
+ function patternRasterizer(grow = new Set<number>()) {
+ const rasterize = vi.fn((cp: number): RasterGlyph | null => {
+ if (cp === UNKNOWN) return null;
+ if (cp === SPACE) return { pixels: new Uint8Array(0), width: 0, height: 0, advance: 12, bearingX: 0, bearingY: 0 };
+ const w = grow.has(cp) ? 20 : 9 + (cp % 3), h = grow.has(cp) ? 20 : 11 + (cp % 2);
+ const pixels = new Uint8Array(w * h * 4);
+ for (let row = 0; row < h; row++) {
+ for (let col = 0; col < w; col++) {
+ pixels.fill((cp + row * 7 + col * 3) & 0xff, (row * w + col) * 4, (row * w + col + 1) * 4);
+ }
+ }
+ return { pixels, width: w, height: h, advance: w, bearingX: 0, bearingY: h };
+ });
+ return { renderSize: 48, spread: 6, rasterize } as GlyphRasterizer;
+ }
+
+ /** Keeps each page as the GPU would hold it, and the painter the atlas handed over. */
+ function imageStore() {
+ const images: Uint8Array[] = [];
+ const painters: Array<(pixels: Uint8Array) => void> = [];
+ const store: AtlasPageStore = {
+ createPage(size, paint) {
+ images.push(new Uint8Array(size * size * 4));
+ painters.push(paint);
+ return images.length - 1;
+ },
+ uploadSubRegion(pageId, x, y, w, h, pixels) {
+ for (let row = 0; row < h; row++) {
+ images[pageId].set(pixels.subarray(row * w * 4, (row + 1) * w * 4), ((y + row) * PAGE + x) * 4);
+ }
+ },
+ };
+ return { store, images, painters };
+ }
+
+ it('repaints every page byte for byte, across pages, skipping blanks', () => {
+ const { store, images, painters } = imageStore();
+ const atlas = new GlyphAtlas(patternRasterizer(), store, { pageSize: PAGE, padding: 1 });
+ for (let i = 0; i < 30; i++) atlas.getGlyph(0x100 + i, 'Arial', i % 4);
+ atlas.getGlyph(SPACE, 'Arial');
+ atlas.getGlyph(UNKNOWN, 'Arial');
+ expect(atlas.pageCount).toBe(2);
+
+ for (let page = 0; page < images.length; page++) {
+ const repainted = new Uint8Array(PAGE * PAGE * 4);
+ painters[page](repainted);
+ expect(repainted.some((v) => v !== 0)).toBe(true);
+ expect(repainted).toEqual(images[page]);
+ }
+ });
+
+ it('clips a glyph that now rasterizes larger to the cell it was given', () => {
+ const grow = new Set<number>();
+ const { store, images, painters } = imageStore();
+ const atlas = new GlyphAtlas(patternRasterizer(grow), store, { pageSize: PAGE, padding: 1 });
+ atlas.getGlyph(0x100, 'Arial');
+ atlas.getGlyph(0x101, 'Arial');
+ // The last glyph packed, so nothing painted after it covers an overflow.
+ grow.add(0x101);
+
+ const repainted = new Uint8Array(PAGE * PAGE * 4);
+ painters[0](repainted);
+ expect(repainted).toEqual(images[0]);
+ });
+});
diff --git a/src/esengine/resource/ResourceManager.hpp b/src/esengine/resource/ResourceManager.hpp
index 3c0ac50ac..d990adb6a 100644
--- a/src/esengine/resource/ResourceManager.hpp
+++ b/src/esengine/resource/ResourceManager.hpp
@@ -49,11 +49,13 @@ enum class ShaderTargetLanguage : u8; // ShaderParser.hpp
*/
enum class ResourceContent : u32 {
Transient = 0, ///< Rewritten by its owner before every use (a video frame).
- Retained = 1, ///< The device keeps the bytes (a glyph page).
+ Retained = 1, ///< The device keeps the bytes (a tile collection composed at load).
Asset = 2, ///< The asset layer loads it again from its path.
Canvas = 3, ///< Redrawn from the canvas it mirrors.
Video = 4, ///< Refilled by the next decoded frame.
Mesh = 5, ///< Geometry the asset layer replays (MeshRecovery::SourceReplayable).
+ GlyphPage = 6, ///< Repainted from the glyphs placed on it.
+ AtlasPage = 7, ///< A skeleton's atlas page, decoded again from its image.
};
/** @brief The device's policy for a content code; unknown codes are Asset, the one that asks. */
diff --git a/tools/releaseNotes.mjs b/tools/releaseNotes.mjs
index 45d614286..bee7c6c41 100644
--- a/tools/releaseNotes.mjs
+++ b/tools/releaseNotes.mjs
@@ -28,6 +28,9 @@ export const NOTES_FLOOR = 'v0.65.0';
* the reader recognises anyway.
*/
export const NOTED = {
+ 'perf(render): glyph and skeleton atlas pages come back from what made them':
+ { note: 'The picture comes back after the GPU is lost.' },
+
'feat(render): the device counts the memory it keeps to survive a loss':
{ note: '`getResourceStats()` reports the memory kept to survive a lost GPU.' },
diff --git a/tools/renderScenes.mjs b/tools/renderScenes.mjs
index 148e55e6b..9e6ccbc43 100644
--- a/tools/renderScenes.mjs
+++ b/tools/renderScenes.mjs
@@ -742,7 +742,10 @@ export const SCENES = [
{ id: "device-roundtrip-sky", tier: "pr", webgpu: true, env: { ESTELLA_VERIFY_DEVICE_LOSS: "roundtrip", ESTELLA_VERIFY_LOSS_ROUNDS: "2", ESTELLA_VERIFY_SCENE: "/scenes/mesh-sky.esscene", ESTELLA_VERIFY_W: "256", ESTELLA_VERIFY_H: "256", ESTELLA_VERIFY_STEPS: "3" } },
{ id: "device-roundtrip-env", tier: "pr", webgpu: true, env: { ESTELLA_VERIFY_DEVICE_LOSS: "roundtrip", ESTELLA_VERIFY_LOSS_ROUNDS: "2", ESTELLA_VERIFY_SCENE: "/scenes/mat-env.esscene", ESTELLA_VERIFY_W: "256", ESTELLA_VERIFY_H: "256", ESTELLA_VERIFY_STEPS: "3" } },
{ id: "device-roundtrip-light-cookie", tier: "pr", webgpu: true, env: { ESTELLA_VERIFY_DEVICE_LOSS: "roundtrip", ESTELLA_VERIFY_LOSS_ROUNDS: "2", ESTELLA_VERIFY_SCENE: "/scenes/light-cookie.esscene", ESTELLA_VERIFY_MANIFEST: "/scenes/light-cookie.textures.json", ESTELLA_VERIFY_W: "256", ESTELLA_VERIFY_H: "256", ESTELLA_VERIFY_STEPS: "3" } },
- { id: "device-roundtrip-text", tier: "pr", webgpu: true, env: { ESTELLA_VERIFY_DEVICE_LOSS: "roundtrip", ESTELLA_VERIFY_LOSS_ROUNDS: "2", ESTELLA_VERIFY_PLAY: "1", ESTELLA_VERIFY_SCENE: "/scenes/ui-screen-text.esscene", ESTELLA_VERIFY_MANIFEST: "/scenes/ui-screen-text.textures.json", ESTELLA_VERIFY_W: "640", ESTELLA_VERIFY_H: "360", ESTELLA_VERIFY_STEPS: "6" } },
+ // A glyph page and a skeleton's atlas page come back from what made them, not from a copy:
+ // the ceiling is under one 1024² page, which is 4 MiB kept on a mini-game's heap per page.
+ { id: "device-roundtrip-text", tier: "pr", webgpu: true, env: { ESTELLA_VERIFY_COUNTERS_MAX: "{\"render.retained.bytes\":65536}", ESTELLA_VERIFY_DEVICE_LOSS: "roundtrip", ESTELLA_VERIFY_LOSS_ROUNDS: "2", ESTELLA_VERIFY_PLAY: "1", ESTELLA_VERIFY_SCENE: "/scenes/ui-screen-text.esscene", ESTELLA_VERIFY_MANIFEST: "/scenes/ui-screen-text.textures.json", ESTELLA_VERIFY_W: "640", ESTELLA_VERIFY_H: "360", ESTELLA_VERIFY_STEPS: "6" } },
+ { id: "device-roundtrip-dragonbones", tier: "pr", webgpu: true, env: { ESTELLA_VERIFY_COUNTERS_MAX: "{\"render.retained.bytes\":65536}", ESTELLA_VERIFY_DEVICE_LOSS: "roundtrip", ESTELLA_VERIFY_LOSS_ROUNDS: "2", ESTELLA_VERIFY_SCENE: "/scenes/dragonbones-still.esscene", ESTELLA_VERIFY_MANIFEST: "/scenes/dragonbones-test.textures.json", ESTELLA_VERIFY_W: "256", ESTELLA_VERIFY_H: "256", ESTELLA_VERIFY_STEPS: "3" } },
{ id: "device-roundtrip-post", tier: "pr", webgpu: true, env: { ESTELLA_VERIFY_DEVICE_LOSS: "roundtrip", ESTELLA_VERIFY_LOSS_ROUNDS: "2", ESTELLA_VERIFY_PLAY: "1", ESTELLA_VERIFY_SCENE: "/scenes/ui-screen-post.esscene", ESTELLA_VERIFY_MANIFEST: "/scenes/ui-screen-post.textures.json", ESTELLA_VERIFY_W: "640", ESTELLA_VERIFY_H: "360", ESTELLA_VERIFY_STEPS: "4" } },
];