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(render): the device warns when what it keeps for a loss passes a budget

esengine2adfb8485388
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 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 and
buffers — 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()`.
### Fixed
diff --git a/docs/astro/src/content/docs/assets/overview.mdx b/docs/astro/src/content/docs/assets/overview.mdx
index 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 syste
does this when a texture is truly freed, so you only need it if you destroy and
recreate 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 the
diff --git a/docs/astro/src/content/docs/performance/profiling.mdx b/docs/astro/src/content/docs/performance/profiling.mdx
index 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 how
many textures it freed — the engine calls it on OS memory warnings; call it
diff --git a/docs/astro/src/content/docs/zh-cn/assets/overview.mdx b/docs/astro/src/content/docs/zh-cn/assets/overview.mdx
index 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.mdx
index 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.md
index 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 | undefined
defaultFontFamily: string | undefined
maxDeltaTime: number | undefined
maxFixedSteps: number | undefined
+retainedBudget: number | undefined
sceneTransitionColor: string | undefined
sceneTransitionDuration: number | undefined
textCanvasSize: 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): ScriptGraph
diff --git a/sdk/etc/index.native.api.md b/sdk/etc/index.native.api.md
index 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 | undefined
defaultFontFamily: string | undefined
maxDeltaTime: number | undefined
maxFixedSteps: number | undefined
+retainedBudget: number | undefined
sceneTransitionColor: string | undefined
sceneTransitionDuration: number | undefined
textCanvasSize: 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): ScriptGraph
diff --git a/sdk/etc/index.node.api.md b/sdk/etc/index.node.api.md
index 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 | undefined
defaultFontFamily: string | undefined
maxDeltaTime: number | undefined
maxFixedSteps: number | undefined
+retainedBudget: number | undefined
sceneTransitionColor: string | undefined
sceneTransitionDuration: number | undefined
textCanvasSize: 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): ScriptGraph
diff --git a/sdk/etc/minigame.api.md b/sdk/etc/minigame.api.md
index 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 | undefined
defaultFontFamily: string | undefined
maxDeltaTime: number | undefined
maxFixedSteps: number | undefined
+retainedBudget: number | undefined
sceneTransitionColor: string | undefined
sceneTransitionDuration: number | undefined
textCanvasSize: 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): ScriptGraph
diff --git a/sdk/etc/wasm.api.md b/sdk/etc/wasm.api.md
index 7f1ee72cd..0c23cb24f 100644
--- a/sdk/etc/wasm.api.md
+++ b/sdk/etc/wasm.api.md
@@ -239,6 +239,7 @@ registerTextureWithPath: (handle: number, path: string) => void
releaseBitmapFont: (handle: number) => void
releaseShader: (handle: number) => void
releaseTexture: (handle: number) => void
+setRetainedBudget: ((bytes: number) => void) | undefined
setTextureBudget: (bytes: number) => void
setTextureMetadata: (handle: number, left: number, right: number, top: number, bottom: number) => void
supportsCompressedFormat: ((format: number) => boolean) | undefined
diff --git a/sdk/etc/wechat.api.md b/sdk/etc/wechat.api.md
index 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 | undefined
defaultFontFamily: string | undefined
maxDeltaTime: number | undefined
maxFixedSteps: number | undefined
+retainedBudget: number | undefined
sceneTransitionColor: string | undefined
sceneTransitionDuration: number | undefined
textCanvasSize: 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): ScriptGraph
diff --git a/sdk/src/app/corePlugin.ts b/sdk/src/app/corePlugin.ts
index 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 Team
import 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.ts
index 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 another
diff --git a/sdk/src/defaults.ts b/sdk/src/defaults.ts
index 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 Team
import { 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.ts
index 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.ts
index 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.cpp
index 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.hpp
index 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.cpp
index 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.cpp
index 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.hpp
index 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.cpp
index 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.hpp
index 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 if
diff --git a/tests/renderer/test_device_loss.cpp b/tests/renderer/test_device_loss.cpp
index 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.mjs
index 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.' },