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.
TypeScript 2d-game-engine3d3d-game-engineandroidcppecsgame-editorgame-enginegamedeviostypescriptwebassemblywebglwebgpuwechat-minigame
feat(render): the device warns when what it keeps for a loss passes a budget
esengine2adfb8485388
diff --git a/CHANGELOG.md b/CHANGELOG.mdindex c953922b0..b25219f2e 100644--- a/CHANGELOG.md+++ b/CHANGELOG.md@@ -20,7 +20,9 @@ published separately; it ships inside the editor.picture back after a graphics reset, the engine keeps a CPU copy of some textures andbuffers — a cost no GPU figure shows, and a real one on a mini-game's memory budget.`retainedBytes` says how large it is, the resource census tracks it, and each frame- reports it as the `render.retained.bytes` counter.+ reports it as the `render.retained.bytes` counter. The engine warns once when it grows+ past `RuntimeConfig.retainedBudget` — 16 MB by default, `retainedBudget` in the build+ config, or `setRetainedBudget()`.### Fixeddiff --git a/docs/astro/src/content/docs/assets/overview.mdx b/docs/astro/src/content/docs/assets/overview.mdxindex c66e95e94..06f1fe74a 100644--- a/docs/astro/src/content/docs/assets/overview.mdx+++ b/docs/astro/src/content/docs/assets/overview.mdx@@ -245,6 +245,7 @@ const stats = getResourceStats(); // null before the engine initializes// stats.textureBytes — resident texture bytes (held + evictable)// stats.textureBudget — the current budget (0 = eviction off)// stats.textureEvictableCount — warm-cache entries awaiting revive/evict+// stats.retainedBytes — CPU copies kept to survive a GPU loss (below)// …plus shaderCount / textureCount / vertexBufferCount / indexBufferCount// and cacheHits / cacheMisses@@ -265,6 +266,19 @@ and `evictTextureDimensions(handle)` drops that cached entry — the asset systedoes this when a texture is truly freed, so you only need it if you destroy andrecreate textures around the asset system's back.+### Memory kept for a lost GPU++When the graphics context is lost (a driver reset, a mobile browser reclaiming+the GPU), the engine rebuilds every texture and buffer behind the handles your+game holds. Most content comes back from where it came from — an asset is+loaded again, a text page is repainted from its glyphs, a skeleton's atlas page+is decoded again. What has no such source (a mesh built at runtime, a tile+collection composed at load) is kept as a CPU copy, which counts against your+memory but not against any GPU figure. `stats.retainedBytes` is that copy; the+engine's own is about 28 KB. It warns once when the copy grows past+`RuntimeConfig.retainedBudget` (**16 MB** by default, `retainedBudget` in the+build config, or `setRetainedBudget(bytes)`; 0 never warns).+For watching these numbers frame-over-frame in the editor and at runtime, see[Profiling](/docs/performance/profiling/). Per-texture **sampling/filtering**parameters (pixel-art nearest vs. smooth linear) are covered in thediff --git a/docs/astro/src/content/docs/performance/profiling.mdx b/docs/astro/src/content/docs/performance/profiling.mdxindex 4f95b329b..4feb01d86 100644--- a/docs/astro/src/content/docs/performance/profiling.mdx+++ b/docs/astro/src/content/docs/performance/profiling.mdx@@ -534,6 +534,7 @@ if (stats && stats.textureBytes > stats.textureBudget * 0.9) {| `textureBytes` | Resident texture bytes (RGBA8 estimate) — held + evictable. || `textureBudget` | The current resident-byte budget (`0` = eviction off). || `textureEvictableCount` | Cached refcount-0 textures awaiting revive or eviction. |+| `retainedBytes` | CPU copies the device keeps to restore content after a GPU loss; warns past `RuntimeConfig.retainedBudget`. Also the per-frame counter `render.retained.bytes`. |`trimTextureCache()` frees every evictable entry immediately and returns howmany textures it freed — the engine calls it on OS memory warnings; call itdiff --git a/docs/astro/src/content/docs/zh-cn/assets/overview.mdx b/docs/astro/src/content/docs/zh-cn/assets/overview.mdxindex 29121d80a..547662f3d 100644--- a/docs/astro/src/content/docs/zh-cn/assets/overview.mdx+++ b/docs/astro/src/content/docs/zh-cn/assets/overview.mdx@@ -212,6 +212,7 @@ const stats = getResourceStats(); // 引擎初始化前为 null// stats.textureBytes — 常驻纹理字节数(持有 + 可逐出)// stats.textureBudget — 当前预算(0 = 逐出关闭)// stats.textureEvictableCount — 等待复活或逐出的热缓存条目数+// stats.retainedBytes — 为扛过 GPU 丢失而保留的 CPU 副本(见下)// …还有 shaderCount / textureCount / vertexBufferCount / indexBufferCount// 与 cacheHits / cacheMisses@@ -227,6 +228,15 @@ const freed = trimTextureCache(); // 立即丢弃所有可逐出纹理`{ width, height }`(首次查询后缓存在 TS 侧),`evictTextureDimensions(handle)` 丢弃那条缓存——资源系统在纹理真正释放时会这么做,所以只有绕过资源系统自己销毁重建纹理时才需要它。+### 为 GPU 丢失保留的内存++图形上下文丢失时(驱动重置、手机浏览器回收 GPU),引擎会在游戏持有的句柄背后重建每张纹理和每个+缓冲。大多数内容从它的来处回来——资产重新加载、文字页按字形重绘、骨骼图集页重新解码。没有这种+来处的内容(运行时构建的网格、加载时拼合的瓦片集)会保留一份 CPU 副本,它占你的内存,却不出现在+任何 GPU 数字里。`stats.retainedBytes` 就是这份副本;引擎自身约 28 KB。副本超过+`RuntimeConfig.retainedBudget`(默认 **16 MB**,构建配置里的 `retainedBudget`,或+`setRetainedBudget(bytes)`;0 表示从不告警)时会告警一次。+想逐帧观察这些数字(编辑器内和运行时),见[性能分析](/docs/zh-cn/performance/profiling/)。逐纹理的**采样/过滤**参数(像素风 nearest 还是平滑 linear)见[精灵指南](/docs/zh-cn/graphics/sprites/)。diff --git a/docs/astro/src/content/docs/zh-cn/performance/profiling.mdx b/docs/astro/src/content/docs/zh-cn/performance/profiling.mdxindex fbe1807ab..1496553e9 100644--- a/docs/astro/src/content/docs/zh-cn/performance/profiling.mdx+++ b/docs/astro/src/content/docs/zh-cn/performance/profiling.mdx@@ -482,6 +482,7 @@ if (stats && stats.textureBytes > stats.textureBudget * 0.9) {| `textureBytes` | 驻留贴图字节数(RGBA8 估算)——持有的 + 可逐出的。 || `textureBudget` | 当前驻留字节预算(`0` = 关闭逐出缓存)。 || `textureEvictableCount` | 引用数为 0、等待复活或逐出的缓存贴图数。 |+| `retainedBytes` | 设备为在 GPU 丢失后恢复内容而保留的 CPU 副本;超过 `RuntimeConfig.retainedBudget` 时告警。逐帧计数器为 `render.retained.bytes`。 |`trimTextureCache()` 立即释放所有可逐出条目并返回释放的贴图数——引擎在收到 OS内存警告时会调用它;在已知的内存尖峰前你也可以主动调用。被持有(有引用)的贴图diff --git a/sdk/etc/index.api.md b/sdk/etc/index.api.mdindex 957066072..ae92d1390 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: 114 public · 96 beta · 1832 experimental · 3 deprecated+Symbols: 114 public · 96 beta · 1833 experimental · 3 deprecated## ABI_LAYOUT_HASH — const @experimental```@@ -7647,6 +7647,7 @@ audioCacheBudget: number | undefineddefaultFontFamily: string | undefinedmaxDeltaTime: number | undefinedmaxFixedSteps: number | undefined+retainedBudget: number | undefinedsceneTransitionColor: string | undefinedsceneTransitionDuration: number | undefinedtextCanvasSize: number | undefined@@ -7655,7 +7656,7 @@ textureCacheBudget: number | undefined## RuntimeConfig — const @experimental```-{ sceneTransitionDuration: number; sceneTransitionColor: { r: number; g: number; b: number; a: number; }; defaultFontFamily: string; maxDeltaTime: number; maxFixedSteps: number; textCanvasSize: number; assetLoadTimeout: number; assetFailureCooldown: number; textureCacheBudget: number; audioCacheBudget: number; }+{ sceneTransitionDuration: number; sceneTransitionColor: { r: number; g: number; b: number; a: number; }; defaultFontFamily: string; maxDeltaTime: number; maxFixedSteps: number; textCanvasSize: number; assetLoadTimeout: number; assetFailureCooldown: number; textureCacheBudget: number; audioCacheBudget: number; retainedBudget: number; }```## RuntimeInitConfig — interface @experimental@@ -14277,6 +14278,11 @@ ServicesPlugin(active: boolean): void```+## setRetainedBudget — function @experimental+```+(bytes: number): void+```+## setScriptNodeLiteral — function @experimental```(graph: ScriptGraph, id: string, port: string, value: ScriptValue): ScriptGraphdiff --git a/sdk/etc/index.native.api.md b/sdk/etc/index.native.api.mdindex 2bbe5de28..a614b95fb 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: 114 public · 101 beta · 1851 experimental · 3 deprecated+Symbols: 114 public · 101 beta · 1852 experimental · 3 deprecated## ABI_LAYOUT_HASH — const @experimental```@@ -7840,6 +7840,7 @@ audioCacheBudget: number | undefineddefaultFontFamily: string | undefinedmaxDeltaTime: number | undefinedmaxFixedSteps: number | undefined+retainedBudget: number | undefinedsceneTransitionColor: string | undefinedsceneTransitionDuration: number | undefinedtextCanvasSize: number | undefined@@ -7848,7 +7849,7 @@ textureCacheBudget: number | undefined## RuntimeConfig — const @experimental```-{ sceneTransitionDuration: number; sceneTransitionColor: { r: number; g: number; b: number; a: number; }; defaultFontFamily: string; maxDeltaTime: number; maxFixedSteps: number; textCanvasSize: number; assetLoadTimeout: number; assetFailureCooldown: number; textureCacheBudget: number; audioCacheBudget: number; }+{ sceneTransitionDuration: number; sceneTransitionColor: { r: number; g: number; b: number; a: number; }; defaultFontFamily: string; maxDeltaTime: number; maxFixedSteps: number; textCanvasSize: number; assetLoadTimeout: number; assetFailureCooldown: number; textureCacheBudget: number; audioCacheBudget: number; retainedBudget: number; }```## RuntimeInitConfig — interface @experimental@@ -14520,6 +14521,11 @@ ServicesPlugin(active: boolean): void```+## setRetainedBudget — function @experimental+```+(bytes: number): void+```+## setScriptNodeLiteral — function @experimental```(graph: ScriptGraph, id: string, port: string, value: ScriptValue): ScriptGraphdiff --git a/sdk/etc/index.node.api.md b/sdk/etc/index.node.api.mdindex 9db500310..d8cbfba8f 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: 114 public · 98 beta · 1831 experimental · 3 deprecated+Symbols: 114 public · 98 beta · 1832 experimental · 3 deprecated## ANCHOR_AXES — const @experimental```@@ -7642,6 +7642,7 @@ audioCacheBudget: number | undefineddefaultFontFamily: string | undefinedmaxDeltaTime: number | undefinedmaxFixedSteps: number | undefined+retainedBudget: number | undefinedsceneTransitionColor: string | undefinedsceneTransitionDuration: number | undefinedtextCanvasSize: number | undefined@@ -7650,7 +7651,7 @@ textureCacheBudget: number | undefined## RuntimeConfig — const @experimental```-{ sceneTransitionDuration: number; sceneTransitionColor: { r: number; g: number; b: number; a: number; }; defaultFontFamily: string; maxDeltaTime: number; maxFixedSteps: number; textCanvasSize: number; assetLoadTimeout: number; assetFailureCooldown: number; textureCacheBudget: number; audioCacheBudget: number; }+{ sceneTransitionDuration: number; sceneTransitionColor: { r: number; g: number; b: number; a: number; }; defaultFontFamily: string; maxDeltaTime: number; maxFixedSteps: number; textCanvasSize: number; assetLoadTimeout: number; assetFailureCooldown: number; textureCacheBudget: number; audioCacheBudget: number; retainedBudget: number; }```## RuntimeInitConfig — interface @experimental@@ -14282,6 +14283,11 @@ ServicesPlugin(active: boolean): void```+## setRetainedBudget — function @experimental+```+(bytes: number): void+```+## setScriptNodeLiteral — function @experimental```(graph: ScriptGraph, id: string, port: string, value: ScriptValue): ScriptGraphdiff --git a/sdk/etc/minigame.api.md b/sdk/etc/minigame.api.mdindex 17a9a463b..71b5879f7 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: 114 public · 96 beta · 1853 experimental · 3 deprecated+Symbols: 114 public · 96 beta · 1854 experimental · 3 deprecated## ANCHOR_AXES — const @experimental```@@ -7890,6 +7890,7 @@ audioCacheBudget: number | undefineddefaultFontFamily: string | undefinedmaxDeltaTime: number | undefinedmaxFixedSteps: number | undefined+retainedBudget: number | undefinedsceneTransitionColor: string | undefinedsceneTransitionDuration: number | undefinedtextCanvasSize: number | undefined@@ -7898,7 +7899,7 @@ textureCacheBudget: number | undefined## RuntimeConfig — const @experimental```-{ sceneTransitionDuration: number; sceneTransitionColor: { r: number; g: number; b: number; a: number; }; defaultFontFamily: string; maxDeltaTime: number; maxFixedSteps: number; textCanvasSize: number; assetLoadTimeout: number; assetFailureCooldown: number; textureCacheBudget: number; audioCacheBudget: number; }+{ sceneTransitionDuration: number; sceneTransitionColor: { r: number; g: number; b: number; a: number; }; defaultFontFamily: string; maxDeltaTime: number; maxFixedSteps: number; textCanvasSize: number; assetLoadTimeout: number; assetFailureCooldown: number; textureCacheBudget: number; audioCacheBudget: number; retainedBudget: number; }```## RuntimeInitConfig — interface @experimental@@ -14541,6 +14542,11 @@ ServicesPlugin(active: boolean): void```+## setRetainedBudget — function @experimental+```+(bytes: number): void+```+## setScriptNodeLiteral — function @experimental```(graph: ScriptGraph, id: string, port: string, value: ScriptValue): ScriptGraphdiff --git a/sdk/etc/wasm.api.md b/sdk/etc/wasm.api.mdindex 7f1ee72cd..0c23cb24f 100644--- a/sdk/etc/wasm.api.md+++ b/sdk/etc/wasm.api.md@@ -239,6 +239,7 @@ registerTextureWithPath: (handle: number, path: string) => voidreleaseBitmapFont: (handle: number) => voidreleaseShader: (handle: number) => voidreleaseTexture: (handle: number) => void+setRetainedBudget: ((bytes: number) => void) | undefinedsetTextureBudget: (bytes: number) => voidsetTextureMetadata: (handle: number, left: number, right: number, top: number, bottom: number) => voidsupportsCompressedFormat: ((format: number) => boolean) | undefineddiff --git a/sdk/etc/wechat.api.md b/sdk/etc/wechat.api.mdindex 950a26d4e..5b61d8aad 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: 114 public · 96 beta · 1843 experimental · 3 deprecated+Symbols: 114 public · 96 beta · 1844 experimental · 3 deprecated## ANCHOR_AXES — const @experimental```@@ -7649,6 +7649,7 @@ audioCacheBudget: number | undefineddefaultFontFamily: string | undefinedmaxDeltaTime: number | undefinedmaxFixedSteps: number | undefined+retainedBudget: number | undefinedsceneTransitionColor: string | undefinedsceneTransitionDuration: number | undefinedtextCanvasSize: number | undefined@@ -7657,7 +7658,7 @@ textureCacheBudget: number | undefined## RuntimeConfig — const @experimental```-{ sceneTransitionDuration: number; sceneTransitionColor: { r: number; g: number; b: number; a: number; }; defaultFontFamily: string; maxDeltaTime: number; maxFixedSteps: number; textCanvasSize: number; assetLoadTimeout: number; assetFailureCooldown: number; textureCacheBudget: number; audioCacheBudget: number; }+{ sceneTransitionDuration: number; sceneTransitionColor: { r: number; g: number; b: number; a: number; }; defaultFontFamily: string; maxDeltaTime: number; maxFixedSteps: number; textCanvasSize: number; assetLoadTimeout: number; assetFailureCooldown: number; textureCacheBudget: number; audioCacheBudget: number; retainedBudget: number; }```## RuntimeInitConfig — interface @experimental@@ -14305,6 +14306,11 @@ ServicesPlugin(active: boolean): void```+## setRetainedBudget — function @experimental+```+(bytes: number): void+```+## setScriptNodeLiteral — function @experimental```(graph: ScriptGraph, id: string, port: string, value: ScriptValue): ScriptGraphdiff --git a/sdk/src/app/corePlugin.ts b/sdk/src/app/corePlugin.tsindex aa8ff2f08..19b6e594b 100644--- a/sdk/src/app/corePlugin.ts+++ b/sdk/src/app/corePlugin.ts@@ -1,7 +1,7 @@// SPDX-License-Identifier: Apache-2.0// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Teamimport type { Plugin } from './app';-import { initResourceManager, shutdownResourceManager, setTextureBudget, trimTextureCache } from '../wasm/resourceManager';+import { initResourceManager, shutdownResourceManager, setRetainedBudget, setTextureBudget, trimTextureCache } from '../wasm/resourceManager';import { platformOnMemoryWarning } from '../platform/base';import { RuntimeConfig } from '../defaults';import { initDrawAPI, shutdownDrawAPI } from '../render/draw';@@ -25,6 +25,7 @@ export const corePlugin: Plugin = {// pool up to this byte budget, so the next load revives them instead of// re-decoding. Without this call the pool default (0) frees at once.setTextureBudget(RuntimeConfig.textureCacheBudget);+ setRetainedBudget(RuntimeConfig.retainedBudget);// OS memory pressure → drop the texture warm cache. Held textures are// untouched; only the revive shortcut is sacrificed until it refills.offMemoryWarning = platformOnMemoryWarning(() => {diff --git a/sdk/src/core-content.ts b/sdk/src/core-content.tsindex 07ca25659..8838244cb 100644--- a/sdk/src/core-content.ts+++ b/sdk/src/core-content.ts@@ -115,7 +115,7 @@ export { LiveBindings, type LiveBindingsData } from './hotUpdateRebind';// Resource budget (VRAM)// =============================================================================-export { setTextureBudget, getResourceStats, trimTextureCache, type ResourceStats } from './wasm/resourceManager';+export { setTextureBudget, setRetainedBudget, getResourceStats, trimTextureCache, type ResourceStats } from './wasm/resourceManager';/** A texture whose content is a canvas SOMETHING ELSE draws on, re-taken on* demand — the seam a service outside the engine needs to put anotherdiff --git a/sdk/src/defaults.ts b/sdk/src/defaults.tsindex e2c5ede5e..5fefc1aec 100644--- a/sdk/src/defaults.ts+++ b/sdk/src/defaults.ts@@ -1,7 +1,7 @@// SPDX-License-Identifier: Apache-2.0// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Teamimport { COMPONENT_META } from './ecs/component.generated';-import { getResourceManager, setTextureBudget } from './wasm/resourceManager';+import { getResourceManager, setRetainedBudget, setTextureBudget } from './wasm/resourceManager';// Values with a C++ backing read the generated metadata (Canvas ctor defaults,// Sprite's editor_default annotation) so these constants cannot drift from the@@ -51,6 +51,12 @@ export const RuntimeConfig = {* apply without re-init. 0 turns the warm cache off.*/audioCacheBudget: 32 * 1024 * 1024,+ /**+ * How many bytes of CPU copies the graphics device may keep to survive a GPU+ * loss before it warns (see setRetainedBudget). The engine keeps about 28 KiB+ * of its own; this is one 2048×2048 image. 0 never warns.+ */+ retainedBudget: 16 * 1024 * 1024,};// =============================================================================@@ -68,6 +74,7 @@ export interface RuntimeBuildConfig {assetFailureCooldown?: number;textureCacheBudget?: number;audioCacheBudget?: number;+ retainedBudget?: number;}export function applyBuildRuntimeConfig(app: { setMaxDeltaTime(v: number): void; setMaxFixedSteps(v: number): void }, config: RuntimeBuildConfig): void {@@ -109,6 +116,10 @@ export function applyBuildRuntimeConfig(app: { setMaxDeltaTime(v: number): void;// default budget — push the configured value through to the pool.if (getResourceManager()) setTextureBudget(config.textureCacheBudget);}+ if (config.retainedBudget !== undefined) {+ RuntimeConfig.retainedBudget = config.retainedBudget;+ if (getResourceManager()) setRetainedBudget(config.retainedBudget);+ }if (config.audioCacheBudget !== undefined) {// AudioAPI reads this live at every budget check — no push needed.RuntimeConfig.audioCacheBudget = config.audioCacheBudget;diff --git a/sdk/src/wasm.ts b/sdk/src/wasm.tsindex 1e08bb1d1..2321a99a8 100644--- a/sdk/src/wasm.ts+++ b/sdk/src/wasm.ts@@ -143,6 +143,8 @@ export interface CppResourceManager {updateTextureSubregion(handle: number, x: number, y: number, width: number, height: number, pixels: number, pixelsLen: number): void;registerTextureWithPath(handle: number, path: string): void;setTextureBudget(bytes: number): void;+ /** Optional: the native core does not wire it. */+ setRetainedBudget?(bytes: number): void;acquireTextureByPath(path: string): number;invalidateTexturePath(path: string): boolean;trimTextureCache(): number;diff --git a/sdk/src/wasm/resourceManager.ts b/sdk/src/wasm/resourceManager.tsindex 0f6ea685c..6a9a532a8 100644--- a/sdk/src/wasm/resourceManager.ts+++ b/sdk/src/wasm/resourceManager.ts@@ -74,6 +74,15 @@ export function setTextureBudget(bytes: number): void {requireResourceManager().setTextureBudget(Math.max(0, Math.floor(bytes)));}+/**+ * Warn once when the CPU copies the graphics device keeps to survive a GPU loss+ * ({@link ResourceStats.retainedBytes}) grow past `bytes`; 0 never warns. The+ * engine applies `RuntimeConfig.retainedBudget` at startup.+ */+export function setRetainedBudget(bytes: number): void {+ requireResourceManager().setRetainedBudget?.(Math.max(0, Math.floor(bytes)));+}+/** GPU resource counts + texture residency figures. See {@link getResourceStats}. */export interface ResourceStats {shaderCount: number;diff --git a/src/esengine/bindings/ResourceManagerBindings.cpp b/src/esengine/bindings/ResourceManagerBindings.cppindex d5000a5dd..998b216ae 100644--- a/src/esengine/bindings/ResourceManagerBindings.cpp+++ b/src/esengine/bindings/ResourceManagerBindings.cpp@@ -198,6 +198,10 @@ void rm_setTextureBudget(resource::ResourceManager& rm, u32 bytes) {rm.setTextureBudget(static_cast<usize>(bytes));}+void rm_setRetainedBudget(resource::ResourceManager& rm, u32 bytes) {+ rm.setRetainedBudget(static_cast<usize>(bytes));+}+u32 rm_acquireTextureByPath(resource::ResourceManager& rm, const std::string& path) {return rm.acquireTextureByPath(path).id();}diff --git a/src/esengine/bindings/ResourceManagerBindings.hpp b/src/esengine/bindings/ResourceManagerBindings.hppindex f7eca633b..08c02b7fd 100644--- a/src/esengine/bindings/ResourceManagerBindings.hpp+++ b/src/esengine/bindings/ResourceManagerBindings.hpp@@ -61,6 +61,7 @@ void rm_releaseTexture(resource::ResourceManager& rm, u32 handleId);u32 rm_getTextureRefCount(resource::ResourceManager& rm, u32 handleId);void rm_registerTextureWithPath(resource::ResourceManager& rm, u32 handleId, const std::string& path);void rm_setTextureBudget(resource::ResourceManager& rm, u32 bytes);+void rm_setRetainedBudget(resource::ResourceManager& rm, u32 bytes);u32 rm_acquireTextureByPath(resource::ResourceManager& rm, const std::string& path);bool rm_invalidateTexturePath(resource::ResourceManager& rm, const std::string& path);u32 rm_trimTextureCache(resource::ResourceManager& rm);diff --git a/src/esengine/bindings/WebSDKEntry.cpp b/src/esengine/bindings/WebSDKEntry.cppindex e4f09d1b2..d6f85fc66 100644--- a/src/esengine/bindings/WebSDKEntry.cpp+++ b/src/esengine/bindings/WebSDKEntry.cpp@@ -494,6 +494,7 @@ EMSCRIPTEN_BINDINGS(esengine_renderer) {.function("updateTextureSubregion", &esengine::rm_updateTextureSubregion).function("registerTextureWithPath", &esengine::rm_registerTextureWithPath).function("setTextureBudget", &esengine::rm_setTextureBudget)+ .function("setRetainedBudget", &esengine::rm_setRetainedBudget).function("acquireTextureByPath", &esengine::rm_acquireTextureByPath).function("invalidateTexturePath", &esengine::rm_invalidateTexturePath).function("trimTextureCache", &esengine::rm_trimTextureCache)diff --git a/src/esengine/renderer/rhi/GfxDevice.cpp b/src/esengine/renderer/rhi/GfxDevice.cppindex 094175dad..8cc988ebd 100644--- a/src/esengine/renderer/rhi/GfxDevice.cpp+++ b/src/esengine/renderer/rhi/GfxDevice.cpp@@ -205,19 +205,37 @@ void GfxDevice::forgoContent(const GfxOwedContent& owed) {void GfxDevice::keepBytes(std::vector<u8>& slot, std::vector<u8> bytes) {retained_bytes_ -= slot.size();retained_bytes_ += bytes.size();+ const usize grownBy = bytes.size() > slot.size() ? bytes.size() - slot.size() : 0;slot = std::move(bytes);+ judgeRetainedBudget(grownBy);}void GfxDevice::dropBytes(std::vector<u8>& slot) {retained_bytes_ -= slot.size();slot = {};+ judgeRetainedBudget(0);}std::vector<u8> GfxDevice::takeBytes(std::vector<u8>& slot) {retained_bytes_ -= slot.size();+ judgeRetainedBudget(0);return std::exchange(slot, {});}+void GfxDevice::judgeRetainedBudget(usize grownBy) {+ if (retained_budget_ == 0 || retained_bytes_ <= retained_budget_) {+ over_retained_budget_ = false;+ return;+ }+ if (over_retained_budget_ || grownBy == 0) return;+ over_retained_budget_ = true;+ constexpr f64 MiB = 1024.0 * 1024.0;+ ES_LOG_WARN("The graphics device keeps {:.2f} MiB of CPU copies to restore content after a GPU loss, "+ "past its {:.2f} MiB budget (the last copy was {} bytes). Content that can be loaded "+ "or drawn again should say who refills it instead of being retained.",+ static_cast<f64>(retained_bytes_) / MiB, static_cast<f64>(retained_budget_) / MiB, grownBy);+}+void GfxDevice::eraseBuffer(u32 id) {if (auto* record = registry_.buffers.find(id)) dropBytes(record->bytes);registry_.buffers.erase(id);diff --git a/src/esengine/renderer/rhi/GfxDevice.hpp b/src/esengine/renderer/rhi/GfxDevice.hppindex 993db3423..1bd35c36f 100644--- a/src/esengine/renderer/rhi/GfxDevice.hpp+++ b/src/esengine/renderer/rhi/GfxDevice.hpp@@ -175,6 +175,15 @@ public:*/usize retainedBytes() const { return retained_bytes_; }+ /**+ * @brief Warns once when retainedBytes() grows past `bytes`; 0 never warns.+ * @details Falling back under it re-arms the warning.+ */+ void setRetainedBudget(usize bytes) {+ retained_budget_ = bytes;+ over_retained_budget_ = false;+ }+/*** @brief Gives up on the device: no further recovery will be attempted.* @details The clean end of a loss that could not be recovered from. The@@ -792,6 +801,7 @@ private:void keepBytes(std::vector<u8>& slot, std::vector<u8> bytes);void dropBytes(std::vector<u8>& slot);std::vector<u8> takeBytes(std::vector<u8>& slot);+ void judgeRetainedBudget(usize grownBy);void eraseBuffer(u32 id);void eraseTexture(u32 id);i32 nativeUniformLocation(GfxProgramRecord& record, u32 id, i32 location);@@ -807,6 +817,8 @@ private:GfxResourceRegistry registry_;u32 owed_count_ = 0;usize retained_bytes_ = 0;+ usize retained_budget_ = 0;+ bool over_retained_budget_ = false;ShaderHandle current_program_ = ShaderHandle::Invalid;PipelineHandle current_pipeline_ = PipelineHandle::Invalid;/// Native uniform locations per program for the current generation; -2 = not asked yet.diff --git a/src/esengine/resource/ResourceManager.cpp b/src/esengine/resource/ResourceManager.cppindex bab8a41a2..9e947eb1a 100644--- a/src/esengine/resource/ResourceManager.cpp+++ b/src/esengine/resource/ResourceManager.cpp@@ -356,6 +356,10 @@ void ResourceManager::setTextureBudget(usize bytes) {textures_.setBudget(bytes);}+void ResourceManager::setRetainedBudget(usize bytes) {+ if (device_) device_->setRetainedBudget(bytes);+}+TextureHandle ResourceManager::acquireTextureByPath(const std::string& path) {auto handle = textures_.findByPath(path);if (!handle.isValid()) {diff --git a/src/esengine/resource/ResourceManager.hpp b/src/esengine/resource/ResourceManager.hppindex d990adb6a..71f7ff314 100644--- a/src/esengine/resource/ResourceManager.hpp+++ b/src/esengine/resource/ResourceManager.hpp@@ -379,6 +379,9 @@ public:*/void setTextureBudget(usize bytes);+ /** @brief See GfxDevice::setRetainedBudget. */+ void setRetainedBudget(usize bytes);+/*** @brief Reuses a cached texture by its build path: returns its handle with an* added reference (reviving an evictable one), or an invalid handle ifdiff --git a/tests/renderer/test_device_loss.cpp b/tests/renderer/test_device_loss.cppindex cb8607f55..20cc35e83 100644--- a/tests/renderer/test_device_loss.cpp+++ b/tests/renderer/test_device_loss.cpp@@ -3,6 +3,7 @@// when nothing is owed. Per-backend guards: test_webgpu_device.cpp.#include "MockGfxDevice.hpp"+#include "esengine/core/Log.hpp"#include "esengine/renderer/rhi/GfxEnums.hpp"#include "esengine/renderer/rhi/Texture.hpp"@@ -321,6 +322,30 @@ int main() {CHECK(d.retainedBytes() == 0, "deleting gives every byte back");}+ // --- Growing past the retained budget is said once, until it falls back under ---+ {+ MockGfxDevice d;+ int warnings = 0;+ const u32 sink = Log::addSink([&](const LogEntry& entry) {+ if (entry.level == LogLevel::Warn && entry.message.find("budget") != std::string::npos) ++warnings;+ });+ d.setRetainedBudget(100);+ TextureDesc desc;+ desc.width = 4;+ desc.height = 4;+ const TextureHandle first = d.createTexture(desc, GfxContent::retained(), nullptr);+ CHECK(warnings == 0, "64 bytes under a 100-byte budget say nothing");+ const TextureHandle second = d.createTexture(desc, GfxContent::retained(), nullptr);+ CHECK(warnings == 1, "crossing the budget warns");+ d.createTexture(desc, GfxContent::retained(), nullptr);+ CHECK(warnings == 1, "and growing further past it does not repeat");+ d.deleteTexture(first);+ d.deleteTexture(second);+ d.createTexture(desc, GfxContent::retained(), nullptr);+ CHECK(warnings == 2, "falling back under re-arms it");+ Log::removeSink(sink);+ }+// --- A recovery that fails leaves it retryable, not half-open ---{MockGfxDevice d;diff --git a/tools/releaseNotes.mjs b/tools/releaseNotes.mjsindex bee7c6c41..652ea144c 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 = {+ 'feat(render): the device warns when what it keeps for a loss passes a budget':+ { note: '`getResourceStats()` reports the memory kept to survive a lost GPU.' },+'perf(render): glyph and skeleton atlas pages come back from what made them':{ note: 'The picture comes back after the GPU is lost.' },