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(assets): compressed textures bill their real VRAM size; editor VRAM readout

yhhc03623c484da
diff --git a/desktop/src/engine/StatsStore.ts b/desktop/src/engine/StatsStore.ts
index ddb21d923..3ac23c6a5 100644
--- a/desktop/src/engine/StatsStore.ts
+++ b/desktop/src/engine/StatsStore.ts
@@ -1,6 +1,7 @@
// SPDX-License-Identifier: Apache-2.0
// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
import { createStore } from 'zustand/vanilla';
+import { getResourceStats } from 'esengine';
import { EngineHost } from './EngineHost';
import { SceneModel } from './SceneModel';
import { useSelection } from '@/store/selectionStore';
@@ -12,11 +13,20 @@ export interface SelTransform {
rot: number;
}
+/** Texture residency for the status bar (bytes; evictable = warm cache). */
+export interface VramReadout {
+ bytes: number;
+ budget: number;
+ evictable: number;
+}
+
export interface StatsSnapshot {
fps: number;
entities: number;
/** The transform of the single selected entity, or null (0 or >1 selected). */
selection: SelTransform | null;
+ /** Resident texture memory vs budget, or null before the engine is up. */
+ vram: VramReadout | null;
}
const round1 = (n: number) => Math.round(n * 10) / 10;
@@ -38,11 +48,25 @@ function sampleSelection(): SelTransform | null {
const selEq = (a: SelTransform | null, b: SelTransform | null): boolean =>
a === b || (!!a && !!b && a.x === b.x && a.y === b.y && a.rot === b.rot);
+/** Sample texture residency from the engine's resource stats, or null. */
+function sampleVram(): VramReadout | null {
+ const stats = getResourceStats();
+ if (!stats) return null;
+ return {
+ bytes: stats.textureBytes,
+ budget: stats.textureBudget,
+ evictable: stats.textureEvictableCount,
+ };
+}
+
+const vramEq = (a: VramReadout | null, b: VramReadout | null): boolean =>
+ a === b || (!!a && !!b && a.bytes === b.bytes && a.budget === b.budget && a.evictable === b.evictable);
+
// Live editor telemetry for the status bar: real FPS (measured here), live
// entity count, and the viewport cursor's world position. Updated a few times
// a second (not per frame) to avoid churning the status bar.
class StatsStoreImpl {
- private readonly store = createStore<StatsSnapshot>(() => ({ fps: 0, entities: 0, selection: null }));
+ private readonly store = createStore<StatsSnapshot>(() => ({ fps: 0, entities: 0, selection: null, vram: null }));
// Pointer-rate churn stays out of the slow-stats subscribers.
private readonly cursorStore = createStore<{ x: number; y: number } | null>(() => null);
@@ -67,8 +91,10 @@ class StatsStoreImpl {
this.windowStart = t;
const cur = this.store.getState();
const selection = sampleSelection();
- if (fps !== cur.fps || entities !== cur.entities || !selEq(selection, cur.selection)) {
- this.store.setState({ fps, entities, selection });
+ const vram = sampleVram();
+ if (fps !== cur.fps || entities !== cur.entities
+ || !selEq(selection, cur.selection) || !vramEq(vram, cur.vram)) {
+ this.store.setState({ fps, entities, selection, vram });
}
}
};
diff --git a/desktop/src/layout/StatusBar.tsx b/desktop/src/layout/StatusBar.tsx
index 3768ed811..42fdbd7f3 100644
--- a/desktop/src/layout/StatusBar.tsx
+++ b/desktop/src/layout/StatusBar.tsx
@@ -1,13 +1,15 @@
// SPDX-License-Identifier: Apache-2.0
// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
import { useSyncExternalStore } from 'react';
-import { Gauge, MousePointer2, Boxes, FolderOpen } from 'lucide-react';
+import { Gauge, MousePointer2, Boxes, FolderOpen, MemoryStick } from 'lucide-react';
import { useEditorStore } from '@/store/editorStore';
import { useSelection } from '@/store/selectionStore';
import { StatsStore } from '@/engine/StatsStore';
import { SubsystemIndicator } from './SubsystemIndicator';
import { Perf } from '@/components/Perf';
+const formatMb = (bytes: number) => (bytes / (1024 * 1024)).toFixed(1);
+
// Only this text node re-renders on mouse move, never the footer.
function CursorReadout() {
const cursor = useSyncExternalStore(StatsStore.subscribeCursor, StatsStore.getCursor);
@@ -63,6 +65,16 @@ export function StatusBar() {
<span className="sitem mono">
<Boxes size={11} strokeWidth={1.85} /> {stats.entities} entities
</span>
+ {stats.vram && (
+ <span
+ className="sitem mono"
+ title={`Resident texture memory / budget · ${stats.vram.evictable} cached (evictable) texture(s)`}
+ >
+ <MemoryStick size={11} strokeWidth={1.85} />
+ {formatMb(stats.vram.bytes)}
+ <span className="smute">/{formatMb(stats.vram.budget)} MB</span>
+ </span>
+ )}
<span className="sitem smute">esengine 0.10.0</span>
</footer>
);
diff --git a/sdk/src/asset/compressed.ts b/sdk/src/asset/compressed.ts
index ea4e1c6bc..ff610be04 100644
--- a/sdk/src/asset/compressed.ts
+++ b/sdk/src/asset/compressed.ts
@@ -150,11 +150,26 @@ function applyParams(gl: WebGL2RenderingContext, opts?: CompressedUploadOptions)
gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_WRAP_T, wrap);
}
-function registerGlTexture(module: ESEngineModule, texture: WebGLTexture, width: number, height: number): number {
+/**
+ * Register an uploaded GL texture with the C++ pool. `gpuBytes` is the actual
+ * VRAM size for the eviction budget — compressed formats are 4–8× smaller than
+ * the pool's RGBA8 estimate, so billing them at the estimate would squat on
+ * most of the budget. 0 keeps the estimate (RGBA8 uploads, where it's exact).
+ */
+function registerGlTexture(
+ module: ESEngineModule, texture: WebGLTexture,
+ width: number, height: number, gpuBytes = 0,
+): number {
const glObj = module.GL;
const id = glObj.getNewId(glObj.textures);
glObj.textures[id] = texture;
- return requireResourceManager().registerExternalTexture(id, width, height);
+ const rm = requireResourceManager();
+ // Older wasm builds / minimal mocks lack the sized variant — fall back to
+ // the estimate rather than fail the upload.
+ if (gpuBytes > 0 && typeof rm.registerExternalTextureSized === 'function') {
+ return rm.registerExternalTextureSized(id, width, height, gpuBytes);
+ }
+ return rm.registerExternalTexture(id, width, height);
}
/** Upload pre-transcoded compressed blocks via `gl.compressedTexImage2D`. */
@@ -176,7 +191,10 @@ export function uploadCompressedTexture(
gl.deleteTexture(texture);
throw err;
}
- return { handle: registerGlTexture(module, texture, t.width, t.height), width: t.width, height: t.height };
+ return {
+ handle: registerGlTexture(module, texture, t.width, t.height, t.data.byteLength),
+ width: t.width, height: t.height,
+ };
}
/** Fallback: upload decoded RGBA8 via `gl.texImage2D`. */
diff --git a/sdk/src/wasm.ts b/sdk/src/wasm.ts
index d905ad66f..94fb3d803 100644
--- a/sdk/src/wasm.ts
+++ b/sdk/src/wasm.ts
@@ -44,6 +44,10 @@ export interface CppResourceManager {
createTextureEx(width: number, height: number, pixels: number, pixelsLen: number, format: number, flipY: boolean, filterMode: number, wrapMode: number): number;
createShader(vertSrc: string, fragSrc: string): number;
registerExternalTexture(glTextureId: number, width: number, height: number): number;
+ /** Like registerExternalTexture, but with the actual GPU byte size for the
+ * eviction budget (compressed textures are 4–8× smaller than the RGBA8
+ * estimate the plain variant books). */
+ registerExternalTextureSized(glTextureId: number, width: number, height: number, bytes: number): number;
getTextureGLId(handle: number): number;
getTextureDimensions(handle: number): { width: number; height: number } | null;
releaseTexture(handle: number): void;
diff --git a/sdk/tests/compressed-texture.test.ts b/sdk/tests/compressed-texture.test.ts
index 06e86f49d..1f45d7983 100644
--- a/sdk/tests/compressed-texture.test.ts
+++ b/sdk/tests/compressed-texture.test.ts
@@ -142,3 +142,28 @@ describe('uploadCompressedTexture', () => {
).toThrow(/internalformat/i);
});
});
+
+describe('GPU byte accounting', () => {
+ let registerExternalTextureSized: ReturnType<typeof vi.fn>;
+ beforeEach(() => {
+ registerExternalTextureSized = vi.fn(() => 42);
+ initResourceManager({ registerExternalTexture, registerExternalTextureSized } as never);
+ });
+
+ it('books compressed uploads at their real block size, not the RGBA8 estimate', () => {
+ const gl = makeGl({ astc: true });
+ // 4×4 ASTC block data is 8 bytes here vs a 64-byte RGBA8 estimate.
+ loadCompressedTexture(gl as never, makeModule() as never, makeTranscoder(), KTX2_HEADER);
+
+ expect(registerExternalTextureSized).toHaveBeenCalledWith(7, 4, 4, 8);
+ expect(registerExternalTexture).not.toHaveBeenCalled();
+ });
+
+ it('books the RGBA8 fallback at the estimate (which is exact for RGBA8)', () => {
+ const gl = makeGl(); // no compressed support → RGBA path
+ loadCompressedTexture(gl as never, makeModule() as never, makeTranscoder(), KTX2_HEADER);
+
+ expect(registerExternalTexture).toHaveBeenCalledWith(7, 4, 4);
+ expect(registerExternalTextureSized).not.toHaveBeenCalled();
+ });
+});
diff --git a/src/esengine/bindings/ResourceManagerBindings.cpp b/src/esengine/bindings/ResourceManagerBindings.cpp
index 802d1bd07..71fa7d71b 100644
--- a/src/esengine/bindings/ResourceManagerBindings.cpp
+++ b/src/esengine/bindings/ResourceManagerBindings.cpp
@@ -74,6 +74,13 @@ u32 rm_registerExternalTexture(resource::ResourceManager& rm, u32 glTextureId,
return handle.id();
}
+u32 rm_registerExternalTextureSized(resource::ResourceManager& rm, u32 glTextureId,
+ u32 width, u32 height, u32 bytes) {
+ auto handle = rm.registerExternalTexture(glTextureId, width, height,
+ static_cast<usize>(bytes));
+ return handle.id();
+}
+
void rm_releaseTexture(resource::ResourceManager& rm, u32 handleId) {
rm.releaseTexture(resource::TextureHandle(handleId));
}
diff --git a/src/esengine/bindings/ResourceManagerBindings.hpp b/src/esengine/bindings/ResourceManagerBindings.hpp
index f17ebc16b..87e20e125 100644
--- a/src/esengine/bindings/ResourceManagerBindings.hpp
+++ b/src/esengine/bindings/ResourceManagerBindings.hpp
@@ -22,6 +22,8 @@ u32 rm_createShader(resource::ResourceManager& rm,
const std::string& vertSrc, const std::string& fragSrc);
u32 rm_registerExternalTexture(resource::ResourceManager& rm, u32 glTextureId,
u32 width, u32 height);
+u32 rm_registerExternalTextureSized(resource::ResourceManager& rm, u32 glTextureId,
+ u32 width, u32 height, u32 bytes);
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);
diff --git a/src/esengine/bindings/WebSDKEntry.cpp b/src/esengine/bindings/WebSDKEntry.cpp
index a52f91f95..f321341a5 100644
--- a/src/esengine/bindings/WebSDKEntry.cpp
+++ b/src/esengine/bindings/WebSDKEntry.cpp
@@ -396,6 +396,7 @@ EMSCRIPTEN_BINDINGS(esengine_renderer) {
.function("createTextureEx", &esengine::rm_createTextureEx)
.function("createShader", &esengine::rm_createShader)
.function("registerExternalTexture", &esengine::rm_registerExternalTexture)
+ .function("registerExternalTextureSized", &esengine::rm_registerExternalTextureSized)
.function("releaseTexture", &esengine::rm_releaseTexture)
.function("getTextureRefCount", &esengine::rm_getTextureRefCount)
.function("releaseShader", &esengine::rm_releaseShader)
diff --git a/src/esengine/resource/ResourceManager.cpp b/src/esengine/resource/ResourceManager.cpp
index a3f314b8e..0baabd1f0 100644
--- a/src/esengine/resource/ResourceManager.cpp
+++ b/src/esengine/resource/ResourceManager.cpp
@@ -198,14 +198,16 @@ u32 ResourceManager::getTextureRefCount(TextureHandle handle) const {
return textures_.getRefCount(handle);
}
-TextureHandle ResourceManager::registerExternalTexture(u32 glTextureId, u32 width, u32 height) {
+TextureHandle ResourceManager::registerExternalTexture(u32 glTextureId, u32 width, u32 height, usize bytes) {
if (!device_) return {};
auto texture = Texture::createFromExternalId(*device_, glTextureId, width, height, TextureFormat::RGBA8);
if (!texture) {
ES_LOG_ERROR("Failed to register external texture (GL ID: {})", glTextureId);
return TextureHandle();
}
- const usize bytes = static_cast<usize>(width) * height * 4;
+ if (bytes == 0) {
+ bytes = static_cast<usize>(width) * height * 4;
+ }
return textures_.add(std::move(texture), "", bytes);
}
diff --git a/src/esengine/resource/ResourceManager.hpp b/src/esengine/resource/ResourceManager.hpp
index df675fd60..602b57849 100644
--- a/src/esengine/resource/ResourceManager.hpp
+++ b/src/esengine/resource/ResourceManager.hpp
@@ -233,9 +233,13 @@ public:
* @param glTextureId The OpenGL texture ID
* @param width Texture width in pixels
* @param height Texture height in pixels
+ * @param bytes Actual GPU size for the eviction budget; 0 = estimate as
+ * RGBA8 (width × height × 4). Compressed uploads (KTX2 →
+ * ASTC/ETC2/S3TC) pass their real block size, 4–8× smaller —
+ * billing them as RGBA8 would waste most of the budget.
* @return Handle to the registered texture
*/
- TextureHandle registerExternalTexture(u32 glTextureId, u32 width, u32 height);
+ TextureHandle registerExternalTexture(u32 glTextureId, u32 width, u32 height, usize bytes = 0);
/**
* @brief Registers a texture with a path for cache lookup