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
fix(render): a video and a canvas come back after the GPU is lost
esengine3487666be2f3
diff --git a/CHANGELOG.md b/CHANGELOG.mdindex b25219f2e..1100d6413 100644--- a/CHANGELOG.md+++ b/CHANGELOG.md@@ -34,7 +34,9 @@ published separately; it ships inside the editor.issued behind the same handles, puts back the contents it kept, and reloads the rest fromtheir assets, on WebGL2 and WebGPU alike. Text pages are repainted from their glyphs andskeleton atlas pages decoded again from their images, so neither keeps a second copy in- memory — 4 MiB for every 1024×1024 page.+ memory — 4 MiB for every 1024×1024 page. A video and an open-data leaderboard come back+ too: their frames were going into a texture the lost context had already destroyed, so a+ paused video stayed blank for good.- **A hot update on iOS, Android and desktop builds is still there after a restartwithout a network.** The native host only stores cache files under plain names, anddiff --git a/fixtures/scenes/video-ended.esscene b/fixtures/scenes/video-ended.esscenenew file mode 100644index 000000000..31b03ddcb--- /dev/null+++ b/fixtures/scenes/video-ended.esscene@@ -0,0 +1,47 @@+{+ "version": 4,+ "name": "VideoEnded",+ "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": "Screen",+ "parent": null,+ "children": [],+ "components": [+ { "type": "Transform", "data": { "position": { "x": 0, "y": 0, "z": 0 } } },+ {+ "type": "Sprite",+ "data": {+ "size": { "x": 600, "y": 600 },+ "color": { "r": 1, "g": 1, "b": 1, "a": 1 }+ }+ },+ {+ "type": "Video",+ "data": {+ "source": "/scenes/video-playback.mp4",+ "autoplay": true,+ "loop": false,+ "muted": true,+ "volume": 1,+ "playbackRate": 1,+ "fitSize": false,+ "enabled": true+ }+ }+ ],+ "visible": true+ }+ ]+}diff --git a/fixtures/scenes/video-ended.textures.json b/fixtures/scenes/video-ended.textures.jsonnew file mode 100644index 000000000..0967ef424--- /dev/null+++ b/fixtures/scenes/video-ended.textures.json@@ -0,0 +1 @@+{}diff --git a/sdk/etc/wasm.api.md b/sdk/etc/wasm.api.mdindex 0c23cb24f..a14af96c9 100644--- a/sdk/etc/wasm.api.md+++ b/sdk/etc/wasm.api.md@@ -227,6 +227,7 @@ getResourceStats: () => { shaderCount: number; textureCount: number; vertexBuffegetShaderRefCount: (handle: number) => numbergetTextureDimensions: (handle: number) => { width: number; height: number; } | nullgetTextureGLId: (handle: number) => number+getTextureNativeId: ((handle: number) => number) | undefinedgetTextureRefCount: (handle: number) => numberinvalidateTexturePath: (path: string) => booleanloadBitmapFont: (fntContent: string, textureHandle: number, texWidth: number, texHeight: number) => number@@ -239,6 +240,7 @@ registerTextureWithPath: (handle: number, path: string) => voidreleaseBitmapFont: (handle: number) => voidreleaseShader: (handle: number) => voidreleaseTexture: (handle: number) => void+restoreTextureContent: ((handle: number) => void) | undefinedsetRetainedBudget: ((bytes: number) => void) | undefinedsetTextureBudget: (bytes: number) => voidsetTextureMetadata: (handle: number, left: number, right: number, top: number, bottom: number) => voiddiff --git a/sdk/src/asset/canvasTexture.ts b/sdk/src/asset/canvasTexture.tsindex fc4ae6e74..2a7427afc 100644--- a/sdk/src/asset/canvasTexture.ts+++ b/sdk/src/asset/canvasTexture.ts@@ -10,18 +10,23 @@* other way — so its content has to be re-taken, and the handle it is behind* must not change when it is (a component holding the handle keeps holding it).*- * It rides the same seam a file texture does: a JS-created GL texture handed to- * the ResourceManager with {@link registerExternalTexture}, and the SAME upload- * conventions (orientation, color space, sampling) as `TextureLoader` — see- * {@link ./glTextureUpload}. What differs is only what a moving image needs:+ * It rides the same seam a file texture does: the upload bridge hands a GL+ * texture to the device and every take writes into whatever texture the device+ * holds, with the SAME conventions (orientation, color space, sampling) as+ * `TextureLoader` — see {@link ./glTextureUpload}. What differs is only what a+ * moving image needs:* no mipmaps (a chain regenerated every frame is pure waste), clamped wrap* (nothing tiles a leaderboard), and `update()`.*/import { TextureContent } from '../wasm';-import { requireResourceManager } from '../wasm/resourceManager';+import {+ provideTextureContent, requireResourceManager, withdrawTextureContent,+} from '../wasm/resourceManager';import type { App } from '../app/app';-import { findWebGL2Context } from './loaders/TextureLoader';-import { uploadBoundTextureImage, applyBoundTextureSampling, type GlImageSource } from './glTextureUpload';+import {+ uploadBoundTextureImage, applyBoundTextureSampling, findWebGL2Context, handOverNewTexture,+ writeDeviceTexture, type GlImageSource,+} from './glTextureUpload';/** A texture backed by a canvas someone else draws on. */export interface CanvasTexture {@@ -33,7 +38,7 @@ export interface CanvasTexture {/** Re-take the source's current content. Cheap to call, not free: one* `texImage2D` of the whole surface. Callers gate on visibility. */update(): void;- /** Release the GL texture. The handle is dead afterwards. */+ /** End it: the device frees the texture and the handle is dead afterwards. */destroy(): void;}@@ -53,32 +58,27 @@ export function createCanvasTexture(const gl = findWebGL2Context(module?.GL);if (!gl || !module) return null;- const texture = gl.createTexture();- if (!texture) return null;-+ let size = { width: source.width, height: source.height };// A canvas is an element source, so orientation is the pixel-store flag's// to apply — the same `flip` a raw <img> upload takes, and for the same// reason: the engine's texture space is bottom-up and the source is not.- const take = (): { width: number; height: number } => {- gl.bindTexture(gl.TEXTURE_2D, texture);- uploadBoundTextureImage(gl, source, true);- return { width: source.width, height: source.height };+ const take = (ctx: WebGL2RenderingContext): void => {+ uploadBoundTextureImage(ctx, source, true);+ size = { width: source.width, height: source.height };};- let size: { width: number; height: number };- try {- size = take();- applyBoundTextureSampling(gl, { filter: 'linear', wrap: 'clamp', mipmaps: false });- } catch (err) {- gl.deleteTexture(texture);- throw err;- }+ const handle = handOverNewTexture(module, gl, (ctx) => {+ take(ctx);+ applyBoundTextureSampling(ctx, { filter: 'linear', wrap: 'clamp', mipmaps: false });+ }, { width: size.width, height: size.height, content: TextureContent.Canvas });- const glObj = module.GL;- const glTextureId = glObj.getNewId(glObj.textures);- glObj.textures[glTextureId] = texture;- const rm = requireResourceManager();- const handle = rm.registerExternalTexture(glTextureId, size.width, size.height, TextureContent.Canvas);+ // After a device loss the canvas itself is untouched, so the content comes+ // back by taking it again — into whatever texture the device rebuilt.+ provideTextureContent(handle, () => {+ if (!writeDeviceTexture(module, handle, take)) return false;+ requireResourceManager().restoreTextureContent?.(handle);+ return true;+ });let alive = true;return {@@ -87,13 +87,13 @@ export function createCanvasTexture(get height() { return size.height; },update() {if (!alive) return;- size = take();+ writeDeviceTexture(module, handle, take);},destroy() {if (!alive) return;alive = false;- gl.deleteTexture(texture);- delete glObj.textures[glTextureId];+ withdrawTextureContent(handle);+ requireResourceManager().releaseTexture(handle);},};}diff --git a/sdk/src/asset/compressed.ts b/sdk/src/asset/compressed.tsindex 1de803dc8..7fab4067e 100644--- a/sdk/src/asset/compressed.ts+++ b/sdk/src/asset/compressed.ts@@ -15,8 +15,7 @@* entry backs the non-WebGL2 fallback path instead.*/import { TextureContent, type ESEngineModule } from '../wasm';-import { requireResourceManager } from '../wasm/resourceManager';-import { applyBoundTextureSampling } from './glTextureUpload';+import { applyBoundTextureSampling, handOverNewTexture } from './glTextureUpload';// =============================================================================// Format vocabulary@@ -228,28 +227,6 @@ function applyParams(gl: WebGL2RenderingContext, opts?: CompressedUploadOptions)applyBoundTextureSampling(gl, { filter: opts?.filter, wrap: opts?.wrap, mipmaps: false });}-/**- * 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;- 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, TextureContent.Asset);- }- return rm.registerExternalTexture(id, width, height, TextureContent.Asset);-}-/** Upload pre-transcoded compressed blocks via `gl.compressedTexImage2D`. */export function uploadCompressedTexture(gl: WebGL2RenderingContext, module: ESEngineModule,@@ -258,42 +235,28 @@ export function uploadCompressedTexture(): UploadedTexture {const internalFormat = glInternalFormat(support, fmt, opts?.srgb ?? false);if (internalFormat == null) throw new Error(`compressed upload: no GL internalformat for ${fmt}`);- const texture = gl.createTexture();- if (!texture) throw new Error('compressed upload: gl.createTexture failed');- try {- gl.bindTexture(gl.TEXTURE_2D, texture);- gl.compressedTexImage2D(gl.TEXTURE_2D, 0, internalFormat, t.width, t.height, 0, t.data);- applyParams(gl, opts);- } catch (err) {- // Release the GL texture if the upload throws — don't leak it.- gl.deleteTexture(texture);- throw err;- }- return {- handle: registerGlTexture(module, texture, t.width, t.height, t.data.byteLength),- width: t.width, height: t.height,- };+ // gpuBytes is the ACTUAL VRAM size for the eviction budget — a compressed+ // format is 4–8× smaller than the pool's RGBA8 estimate, and billing it at+ // the estimate would squat on most of the budget.+ const handle = handOverNewTexture(module, gl, (g) => {+ g.compressedTexImage2D(g.TEXTURE_2D, 0, internalFormat, t.width, t.height, 0, t.data);+ applyParams(g, opts);+ }, { width: t.width, height: t.height, content: TextureContent.Asset, gpuBytes: t.data.byteLength });+ return { handle, width: t.width, height: t.height };}/** Fallback: upload decoded RGBA8 via `gl.texImage2D`. */export function uploadRgbaTexture(gl: WebGL2RenderingContext, module: ESEngineModule, r: RgbaResult, opts?: CompressedUploadOptions,): UploadedTexture {- const texture = gl.createTexture();- if (!texture) throw new Error('rgba upload: gl.createTexture failed');- try {- gl.bindTexture(gl.TEXTURE_2D, texture);+ const handle = handOverNewTexture(module, gl, (g) => {// Linear pipeline: the decoded pixels are sRGB-encoded color, same as// the PNG path — store them in an sRGB format so sampling linearizes.- const internalFormat = opts?.srgb ? gl.SRGB8_ALPHA8 : gl.RGBA;- gl.texImage2D(gl.TEXTURE_2D, 0, internalFormat, r.width, r.height, 0, gl.RGBA, gl.UNSIGNED_BYTE, r.data);- applyParams(gl, opts);- } catch (err) {- // Release the GL texture if the upload throws — don't leak it.- gl.deleteTexture(texture);- throw err;- }- return { handle: registerGlTexture(module, texture, r.width, r.height), width: r.width, height: r.height };+ const internalFormat = opts?.srgb ? g.SRGB8_ALPHA8 : g.RGBA;+ g.texImage2D(g.TEXTURE_2D, 0, internalFormat, r.width, r.height, 0, g.RGBA, g.UNSIGNED_BYTE, r.data);+ applyParams(g, opts);+ }, { width: r.width, height: r.height, content: TextureContent.Asset });+ return { handle, width: r.width, height: r.height };}// =============================================================================diff --git a/sdk/src/asset/glTextureUpload.ts b/sdk/src/asset/glTextureUpload.tsindex b3aba3fa1..88f541beb 100644--- a/sdk/src/asset/glTextureUpload.ts+++ b/sdk/src/asset/glTextureUpload.ts@@ -2,9 +2,10 @@// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team/*** @file glTextureUpload.ts- * @brief The one place an image-like source becomes GL texture content in the- * engine's conventions: vertical orientation, color-space encoding and- * sampler state.+ * @brief The bridge between a JS image source and the device's texture: the+ * engine's upload conventions (orientation, color-space encoding,+ * sampler state), and the only place a GL texture is created here and+ * handed to the device.** Extracted for the same reason {@link ./glTexParams} was — a second uploader* arrived (the open data context's shared canvas, re-uploaded every frame it is@@ -20,6 +21,8 @@import { linearColorSpace } from '../ecs/env';import { glWrapMode, type TextureWrap } from './glTexParams';import type { PlatformCanvas, PlatformImage } from '../platform/types';+import { requireResourceManager } from '../wasm/resourceManager';+import type { ESEngineModule, TextureContent } from '../wasm';/** Anything WebGL will take directly as texture content. */export type GlImageSource = PlatformImage | PlatformCanvas | ImageBitmap;@@ -77,3 +80,94 @@ export function applyBoundTextureSampling(gl: WebGL2RenderingContext, sampling?:gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_WRAP_T, glWrap);if (useMipmaps) gl.generateMipmap(gl.TEXTURE_2D);}++// =============================================================================+// The device's texture+// =============================================================================++function isWebGL2(ctx: unknown): ctx is WebGL2RenderingContext {+ return !!ctx && typeof (ctx as WebGL2RenderingContext).texStorage2D === 'function';+}++/**+ * The engine's WebGL2 context, looked up through emscripten's GL bookkeeping.+ * Duck-typed on `texStorage2D`: WeChat MiniGames have no `WebGL2RenderingContext`+ * global, where an `instanceof` check THREW and read as "no context", refusing+ * every KTX2 texture. Falls back to any registered context when none is current.+ */+export function findWebGL2Context(glObj: ESEngineModule['GL'] | undefined): WebGL2RenderingContext | null {+ try {+ const current = glObj?.currentContext?.GLctx;+ if (isWebGL2(current)) return current;+ for (const rec of glObj?.contexts ?? []) {+ if (rec && isWebGL2(rec.GLctx)) return rec.GLctx;+ }+ } catch {+ // fall through — treated as "no WebGL2 context"+ }+ return null;+}++/** What a texture handed to the device is, beyond its pixels. */+export interface HandOverDesc {+ width: number;+ height: number;+ /** Who refills it after a device loss (see {@link TextureContent}). */+ content: TextureContent;+ /** On-GPU bytes for the residency budget, when they are not width*height*4. */+ gpuBytes?: number;+}++/**+ * Create a GL texture, let `write` fill the bound texture, and hand it to the+ * device; returns the engine handle. The device owns it from here — it deletes the+ * object with the handle and builds a replacement after a loss, so nothing outside+ * this file may keep the WebGLTexture.+ */+export function handOverNewTexture(+ module: ESEngineModule,+ gl: WebGL2RenderingContext,+ write: (gl: WebGL2RenderingContext) => void,+ desc: HandOverDesc,+): number {+ const texture = gl.createTexture();+ if (!texture) throw new Error('the GL context gave no texture (is it lost?)');+ try {+ gl.bindTexture(gl.TEXTURE_2D, texture);+ write(gl);+ } catch (err) {+ gl.deleteTexture(texture);+ throw err;+ }+ const glObj = module.GL;+ const id = glObj.getNewId(glObj.textures);+ glObj.textures[id] = texture;+ const rm = requireResourceManager();+ return desc.gpuBytes !== undefined && rm.registerExternalTextureSized+ ? rm.registerExternalTextureSized(id, desc.width, desc.height, desc.gpuBytes, desc.content)+ : rm.registerExternalTexture(id, desc.width, desc.height, desc.content);+}++/**+ * Write into the texture the device has behind `handle` RIGHT NOW.+ *+ * After a device loss that is a different native object, so a caller that kept+ * its own would be uploading into a dead one — which is exactly how a video came+ * back blank. False when there is no context or the handle has no texture yet.+ */+export function writeDeviceTexture(+ module: ESEngineModule | null | undefined,+ handle: number,+ write: (gl: WebGL2RenderingContext) => void,+): boolean {+ const gl = findWebGL2Context(module?.GL);+ if (!gl || !module || !handle) return false;+ // The backend's own name, asked for at every write: the id a handle resolves+ // to is a different object after every device loss.+ const id = requireResourceManager().getTextureNativeId?.(handle) ?? 0;+ const texture = id ? module.GL.textures[id] : null;+ if (!texture) return false;+ gl.bindTexture(gl.TEXTURE_2D, texture);+ write(gl);+ return true;+}diff --git a/sdk/src/asset/loaders/TextureLoader.ts b/sdk/src/asset/loaders/TextureLoader.tsindex 077a600fe..25fa4dd1c 100644--- a/sdk/src/asset/loaders/TextureLoader.ts+++ b/sdk/src/asset/loaders/TextureLoader.ts@@ -16,7 +16,9 @@ import {type BasisTranscoder, type TextureUploadDecision,} from '../compressed';import { TextureFormatLog, type TextureFormatReport } from '../textureFormatReport';-import { uploadBoundTextureImage, applyBoundTextureSampling } from '../glTextureUpload';+import {+ uploadBoundTextureImage, applyBoundTextureSampling, handOverNewTexture, findWebGL2Context,+} from '../glTextureUpload';import { createTextureFromPixels, type TextureParams } from '../../runtime/runtimeAssets';/**@@ -392,30 +394,11 @@ export class TextureLoader implements AssetLoader<TextureResult> {width: number, height: number, flip: boolean,settings?: TextureImportSettings,): TextureResult {- // createTexture returns null on a lost context — don't `!`-assert it- // into the calls below.- const texture = gl.createTexture();- if (!texture) {- throw new Error('TextureLoader: gl.createTexture() returned null (GL context lost?)');- }- try {- gl.bindTexture(gl.TEXTURE_2D, texture);- uploadBoundTextureImage(gl, img, flip, settings?.srgb);- applyBoundTextureSampling(gl, settings);- } catch (err) {- // Upload threw (e.g. context lost mid-call); release the GL texture- // instead of leaking it.- gl.deleteTexture(texture);- throw err;- }-// This path runs only with a live WebGL2 context, which implies a module.- const glObj = this.module_!.GL;- const glTextureId = glObj.getNewId(glObj.textures);- glObj.textures[glTextureId] = texture;-- const rm = requireResourceManager();- const handle = rm.registerExternalTexture(glTextureId, width, height, TextureContent.Asset);+ const handle = handOverNewTexture(this.module_!, gl, (g) => {+ uploadBoundTextureImage(g, img, flip, settings?.srgb);+ applyBoundTextureSampling(g, settings);+ }, { width, height, content: TextureContent.Asset });return { handle, width, height };}@@ -446,28 +429,3 @@ export class TextureLoader implements AssetLoader<TextureResult> {}}-/**- * The engine's WebGL2 context, looked up through emscripten's GL bookkeeping.- * Duck-typed on `texStorage2D` (a WebGL2-only method): WeChat MiniGames have no- * `WebGL2RenderingContext` global — an `instanceof` check THREW there and read- * as "no context", refusing every KTX2 texture — and instanceof lies across- * realms anyway. Falls back to any registered context when none is current yet- * (a host registers the context before the renderer's first frame makes it- * current). Exported for tests.- */-export function findWebGL2Context(glObj: ESEngineModule['GL'] | undefined): WebGL2RenderingContext | null {- try {- const current = glObj?.currentContext?.GLctx;- if (isWebGL2(current)) return current;- for (const rec of glObj?.contexts ?? []) {- if (rec && isWebGL2(rec.GLctx)) return rec.GLctx;- }- } catch {- // fall through — treated as "no WebGL2 context"- }- return null;-}--function isWebGL2(ctx: unknown): ctx is WebGL2RenderingContext {- return !!ctx && typeof (ctx as WebGL2RenderingContext).texStorage2D === 'function';-}diff --git a/sdk/src/ecs/bridge/nativeEngineApi.generated.ts b/sdk/src/ecs/bridge/nativeEngineApi.generated.tsindex 7aab3de53..bff9072cd 100644--- a/sdk/src/ecs/bridge/nativeEngineApi.generated.ts+++ b/sdk/src/ecs/bridge/nativeEngineApi.generated.ts@@ -202,6 +202,7 @@ export interface NativeEngineApi {rm_getBitmapFontRefCount?(rm: unknown, handleId: number): number;rm_getShaderRefCount?(rm: unknown, handleId: number): number;rm_getTextureGLId?(rm: unknown, handleId: number): number;+ rm_getTextureNativeId?(rm: unknown, handle: number): number;rm_getTextureRefCount?(rm: unknown, handleId: number): number;rm_invalidateTexturePath?(rm: unknown, path: string): boolean;rm_loadBitmapFont?(rm: unknown, fntContent: string, textureHandle: number, texWidth: number, texHeight: number): number;@@ -213,6 +214,7 @@ export interface NativeEngineApi {rm_releaseBitmapFont?(rm: unknown, handleId: number): void;rm_releaseShader?(rm: unknown, handleId: number): void;rm_releaseTexture?(rm: unknown, handleId: number): void;+ rm_restoreTextureContent?(rm: unknown, handle: number): void;rm_setRetainedBudget?(rm: unknown, bytes: number): void;rm_setTextureBudget?(rm: unknown, bytes: number): void;rm_setTextureMetadata?(rm: unknown, handleId: number, left: number, right: number, top: number, bottom: number): void;@@ -469,6 +471,7 @@ export function createNativeEngineApi(bind('rm_getBitmapFontRefCount', 'es_rm_getBitmapFontRefCount', true);bind('rm_getShaderRefCount', 'es_rm_getShaderRefCount', true);bind('rm_getTextureGLId', 'es_rm_getTextureGLId', true);+ bind('rm_getTextureNativeId', 'es_rm_getTextureNativeId', true);bind('rm_getTextureRefCount', 'es_rm_getTextureRefCount', true);bind('rm_invalidateTexturePath', 'es_rm_invalidateTexturePath', true);bind('rm_loadBitmapFont', 'es_rm_loadBitmapFont', true);@@ -480,6 +483,7 @@ export function createNativeEngineApi(bind('rm_releaseBitmapFont', 'es_rm_releaseBitmapFont', true);bind('rm_releaseShader', 'es_rm_releaseShader', true);bind('rm_releaseTexture', 'es_rm_releaseTexture', true);+ bind('rm_restoreTextureContent', 'es_rm_restoreTextureContent', true);bind('rm_setRetainedBudget', 'es_rm_setRetainedBudget', true);bind('rm_setTextureBudget', 'es_rm_setTextureBudget', true);bind('rm_setTextureMetadata', 'es_rm_setTextureMetadata', true);diff --git a/sdk/src/render/renderer.ts b/sdk/src/render/renderer.tsindex bf509392f..7d5f90f10 100644--- a/sdk/src/render/renderer.ts+++ b/sdk/src/render/renderer.ts@@ -5,7 +5,7 @@ import { CoreApiBridge } from '../wasm/CoreApiBridge';import { handleWasmError } from '../wasm/wasmError';import { requireResourceManager } from '../wasm/resourceManager';import { platformOnContextLost } from '../platform';-import { findWebGL2Context } from '../asset/loaders/TextureLoader';+import { findWebGL2Context } from '../asset/glTextureUpload';import { decodeFrameCapture, replayToDrawCall as replayToDrawCallImpl, getSnapshotImageData as getSnapshotImpl, type FrameCaptureData } from './frameCapture';import { acquireWebGPUDevice } from './webgpuBoot';diff --git a/sdk/src/video/WasmVideoBackend.ts b/sdk/src/video/WasmVideoBackend.tsindex 1820789ab..f5b1d1a20 100644--- a/sdk/src/video/WasmVideoBackend.ts+++ b/sdk/src/video/WasmVideoBackend.ts@@ -24,7 +24,9 @@ import type { SideModule } from '../sideModules/host';import type { AudioAPI } from '../audio/Audio';import type { AudioHandle } from '../audio/PlatformAudioBackend';import { createTextureFromPixels, updateTextureSubregion } from '../runtime/runtimeAssets';-import { requireResourceManager } from '../wasm/resourceManager';+import {+ provideTextureContent, requireResourceManager, withdrawTextureContent,+} from '../wasm/resourceManager';import { getPlatform } from '../platform/base';import { log } from '../util/logger';@@ -327,12 +329,25 @@ class WasmVideoStreamHandle implements VideoStreamHandle {/* flipY */ false,{ filterMode: 'linear', wrapMode: 'clamp' },);+ // After a device loss the decoder still holds the frame that was on+ // screen, so it is uploaded again — a paused video comes back too.+ provideTextureContent(this.texture_, () => this.refillFrame_(module));this.onReady?.();} else {updateTextureSubregion(module, this.texture_, 0, 0, this.width_, this.height_, pixels);}}+ /** Uploads the decoder's current frame again; the whole image settles the debt. */+ private refillFrame_(module: ESEngineModule | null): boolean {+ const video = this.mod_;+ if (!video || !this.texture_ || this.disposed_) return false;+ if (!video._es_video_frame_rgba(this.decoder_, this.framePtr_, this.frameBytes_)) return false;+ updateTextureSubregion(module, this.texture_, 0, 0, this.width_, this.height_,+ video.HEAPU8.subarray(this.framePtr_, this.framePtr_ + this.frameBytes_));+ return true;+ }+// === transport ==========================================================get textureHandle(): number { return this.texture_; }@@ -415,6 +430,7 @@ class WasmVideoStreamHandle implements VideoStreamHandle {this.framePtr_ = 0;}if (this.texture_) {+ withdrawTextureContent(this.texture_);requireResourceManager().releaseTexture(this.texture_);this.texture_ = 0;}diff --git a/sdk/src/video/WebVideoBackend.ts b/sdk/src/video/WebVideoBackend.tsindex 14049eb20..76e272e0f 100644--- a/sdk/src/video/WebVideoBackend.ts+++ b/sdk/src/video/WebVideoBackend.ts@@ -6,8 +6,13 @@import { TextureContent, type ESEngineModule } from '../wasm';import type { PlatformVideoBackend, VideoStreamHandle, VideoStreamOptions } from './PlatformVideoBackend';import { createTextureFromPixels, updateTextureSubregion } from '../runtime/runtimeAssets';-import { requireResourceManager } from '../wasm/resourceManager';-import { findWebGL2Context } from '../asset/loaders/TextureLoader';+import {+ provideTextureContent, requireResourceManager, withdrawTextureContent,+} from '../wasm/resourceManager';+import {+ findWebGL2Context, handOverNewTexture, writeDeviceTexture, uploadBoundTextureImage,+ applyBoundTextureSampling,+} from '../asset/glTextureUpload';import { linearColorSpace } from '../ecs/env';import { log } from '../util/logger';@@ -22,11 +27,9 @@ class WebVideoStreamHandle implements VideoStreamHandle {onError?: (error: unknown) => void;private readonly video_: HTMLVideoElement;- // Zero-copy GL path (WebGL2).+ // Zero-copy GL path (WebGL2). No WebGLTexture is kept: the device owns the+ // object and replaces it after a loss (see writeDeviceTexture).private gl_: WebGL2RenderingContext | null = null;- private glTexture_: WebGLTexture | null = null;- private glTexId_ = 0;- private glPool_: Record<number, WebGLTexture> | null = null;private pathChosen_ = false;// CPU fallback path (WebGPU / no GL context).private canvas_: HTMLCanvasElement | null = null;@@ -145,35 +148,46 @@ class WebVideoStreamHandle implements VideoStreamHandle {}}- // Zero-copy: texImage2D the frame straight onto the engine's GL context, then- // register it as an external texture. UNPACK_FLIP_Y gives the bottom-first+ // Zero-copy: the frame goes straight into the texture the device holds, which+ // is a NEW object after every device loss. UNPACK_FLIP_Y gives the bottom-first// orientation a Sprite samples upright (matching image uploads).private uploadGL_(module: ESEngineModule, gl: WebGL2RenderingContext): void {- if (this.glTexture_) {- gl.bindTexture(gl.TEXTURE_2D, this.glTexture_);- gl.pixelStorei(gl.UNPACK_FLIP_Y_WEBGL, 1);- gl.texSubImage2D(gl.TEXTURE_2D, 0, 0, 0, gl.RGBA, gl.UNSIGNED_BYTE, this.video_);- gl.pixelStorei(gl.UNPACK_FLIP_Y_WEBGL, 0);+ if (this.texture_) {+ writeDeviceTexture(module, this.texture_, (g) => {+ g.pixelStorei(g.UNPACK_FLIP_Y_WEBGL, 1);+ g.texSubImage2D(g.TEXTURE_2D, 0, 0, 0, g.RGBA, g.UNSIGNED_BYTE, this.video_);+ g.pixelStorei(g.UNPACK_FLIP_Y_WEBGL, 0);+ });return;}- const tex = gl.createTexture();- if (!tex) throw new Error('gl.createTexture failed');- this.glTexture_ = tex;- gl.bindTexture(gl.TEXTURE_2D, tex);- gl.pixelStorei(gl.UNPACK_FLIP_Y_WEBGL, 1);- const internal = linearColorSpace() ? gl.SRGB8_ALPHA8 : gl.RGBA;- gl.texImage2D(gl.TEXTURE_2D, 0, internal, gl.RGBA, gl.UNSIGNED_BYTE, this.video_);- gl.pixelStorei(gl.UNPACK_FLIP_Y_WEBGL, 0);- gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_MIN_FILTER, gl.LINEAR);- gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_MAG_FILTER, gl.LINEAR);- gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_WRAP_S, gl.CLAMP_TO_EDGE);- gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_WRAP_T, gl.CLAMP_TO_EDGE);- const pool = module.GL.textures;- const id = module.GL.getNewId(pool);- pool[id] = tex;- this.glTexId_ = id;- this.glPool_ = pool;- this.texture_ = requireResourceManager().registerExternalTexture(id, this.width_, this.height_, TextureContent.Video);+ this.texture_ = handOverNewTexture(module, gl, (g) => {+ uploadBoundTextureImage(g, this.video_, /* flip */ true);+ applyBoundTextureSampling(g, { filter: 'linear', wrap: 'clamp', mipmaps: false });+ }, { width: this.width_, height: this.height_, content: TextureContent.Video });+ provideTextureContent(this.texture_, () => this.refillFrame_(module));+ }++ /**+ * Puts the frame on screen back after a device loss. The whole image, not a+ * sub-rectangle: the device rebuilt its texture from a description that does+ * not carry the color space this upload chose, so the storage is respecified+ * here — a paused video would otherwise come back washed out in linear mode.+ */+ private refillFrame_(module: ESEngineModule): boolean {+ if (this.disposed_ || !this.texture_) return false;+ if (!this.gl_) {+ // CPU path: the upload goes through the device, which settles its own debt.+ this.uploadCPU_(module);+ return true;+ }+ if (this.video_.readyState < 2) return false; // no frame yet; the next pump pays+ const wrote = writeDeviceTexture(module, this.texture_, (g) => {+ uploadBoundTextureImage(g, this.video_, /* flip */ true);+ applyBoundTextureSampling(g, { filter: 'linear', wrap: 'clamp', mipmaps: false });+ });+ if (!wrote) return false;+ requireResourceManager().restoreTextureContent?.(this.texture_);+ return true;}private uploadCPU_(module: ESEngineModule): void {@@ -196,6 +210,7 @@ class WebVideoStreamHandle implements VideoStreamHandle {/* flipY */ false,{ filterMode: 'linear', wrapMode: 'clamp' },);+ provideTextureContent(this.texture_, () => this.refillFrame_(module));} else {updateTextureSubregion(module, this.texture_, 0, 0, this.width_, this.height_, pixels);}@@ -235,16 +250,10 @@ class WebVideoStreamHandle implements VideoStreamHandle {this.video_.removeAttribute('src');try { this.video_.load(); } catch { /* ignore */ }if (this.texture_) {+ withdrawTextureContent(this.texture_);requireResourceManager().releaseTexture(this.texture_);this.texture_ = 0;}- // The engine's external texture is non-owning (owns_=false), so delete the- // JS-side GL texture ourselves after dropping the engine ref.- if (this.gl_ && this.glTexture_) {- this.gl_.deleteTexture(this.glTexture_);- if (this.glPool_ && this.glTexId_) delete this.glPool_[this.glTexId_];- this.glTexture_ = null;- }this.canvas_ = null;this.ctx_ = null;}diff --git a/sdk/src/wasm.ts b/sdk/src/wasm.tsindex 2321a99a8..cd94a6627 100644--- a/sdk/src/wasm.ts+++ b/sdk/src/wasm.ts@@ -120,6 +120,8 @@ export interface CppResourceManager {texturesAwaitingReupload?(): string;/** Give up on an owed texture's content: it keeps blank storage. */forgoTextureContent?(handle: number): void;+ /** Its provider wrote the pixels itself (the JS upload bridge); the debt is paid. */+ restoreTextureContent?(handle: number): void;/*** Move a freshly loaded texture's pixels behind an owed handle; the source* is left empty for its release. Optional: absent on an older wasm build.@@ -134,6 +136,9 @@ export interface CppResourceManager {/** Every live mesh as `handle:realized`. Optional: absent on an older wasm build. */meshRealizations?(): string;getTextureGLId(handle: number): number;+ /** The backend's own name for the texture's object (an emscripten GL texture id),+ * valid until the next device loss; 0 where the backend has none. */+ getTextureNativeId?(handle: number): number;getTextureDimensions(handle: number): { width: number; height: number } | null;releaseTexture(handle: number): void;getTextureRefCount(handle: number): number;diff --git a/sdk/tests/canvas-texture.test.ts b/sdk/tests/canvas-texture.test.tsindex 38657211a..7abdad52b 100644--- a/sdk/tests/canvas-texture.test.ts+++ b/sdk/tests/canvas-texture.test.ts@@ -8,7 +8,7 @@* every re-take, because a component is holding it.*/import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';-import { initResourceManager, shutdownResourceManager } from '../src/wasm/resourceManager';+import { initResourceManager, shutdownResourceManager, textureRefill } from '../src/wasm/resourceManager';import { setLinearColorSpace } from '../src/ecs/env';import { createCanvasTexture } from '../src/asset/canvasTexture';import { TextureContent, type ESEngineModule } from '../src/wasm';@@ -32,7 +32,7 @@ function makeGl() {UNPACK_FLIP_Y_WEBGL, UNPACK_PREMULTIPLY_ALPHA_WEBGL: 0x9241,// isWebGL2's duck test.texStorage2D: vi.fn(),- createTexture: vi.fn(() => ({}) as WebGLTexture),+ createTexture: vi.fn(() => ({ tag: 'first' }) as unknown as WebGLTexture),deleteTexture: vi.fn(),bindTexture: vi.fn(),texImage2D: vi.fn(),@@ -62,9 +62,18 @@ function makeSource(width: number, height: number) {}let registerExternalTexture: ReturnType<typeof vi.fn>;+let releaseTexture: ReturnType<typeof vi.fn>;+let restoreTextureContent: ReturnType<typeof vi.fn>;beforeEach(() => {registerExternalTexture = vi.fn(() => 42);- initResourceManager({ registerExternalTexture } as never);+ releaseTexture = vi.fn();+ restoreTextureContent = vi.fn();+ // getTextureGLId is how every re-take finds the texture the DEVICE has: the+ // id it hands back is the one the bridge registered, until a loss replaces it.+ initResourceManager({+ registerExternalTexture, releaseTexture, restoreTextureContent,+ getTextureNativeId: vi.fn(() => 7),+ } as never);});afterEach(() => {shutdownResourceManager();@@ -148,18 +157,49 @@ describe('createCanvasTexture', () => {expect(createCanvasTexture(undefined, makeSource(8, 8))).toBeNull();});- it('releases the GL texture on destroy, and a re-take afterwards is a no-op', () => {+ it('gives the texture back to the device on destroy, and a re-take afterwards is a no-op', () => {const gl = makeGl();- const app = makeApp(gl);- const tex = createCanvasTexture(app, makeSource(8, 8))!;+ const tex = createCanvasTexture(makeApp(gl), makeSource(8, 8))!;+ const handle = tex.handle;tex.destroy();- expect(gl.deleteTexture).toHaveBeenCalledTimes(1);- const gpu = app.wasmModule!.GL as unknown as { textures: Record<number, unknown> };- expect(gpu.textures[7]).toBeUndefined();+ // The device owns the object since the hand-over, so ending it is one+ // release — deleting the GL texture here would pull it out from under it.+ expect(releaseTexture).toHaveBeenCalledWith(handle);+ expect(gl.deleteTexture).not.toHaveBeenCalled();+ expect(textureRefill(handle)).toBeUndefined();const uploads = gl.texImage2D.mock.calls.length;tex.update();tex.destroy();expect(gl.texImage2D.mock.calls.length).toBe(uploads);- expect(gl.deleteTexture).toHaveBeenCalledTimes(1);+ expect(releaseTexture).toHaveBeenCalledTimes(1);+ });++ it('takes the canvas again into the texture the device rebuilt, and says the debt is paid', () => {+ const gl = makeGl();+ const app = makeApp(gl);+ const tex = createCanvasTexture(app, makeSource(8, 8))!;+ const pool = (app.wasmModule!.GL as unknown as { textures: Record<number, WebGLTexture> }).textures;+ const beforeLoss = pool[7];++ // What a device loss leaves: the same handle, a different native texture.+ const rebuilt = { tag: 'after-loss' } as unknown as WebGLTexture;+ pool[7] = rebuilt;+ expect(textureRefill(tex.handle)!()).toBe(true);++ expect(gl.bindTexture).toHaveBeenLastCalledWith(gl.TEXTURE_2D, rebuilt);+ expect(gl.bindTexture).not.toHaveBeenLastCalledWith(gl.TEXTURE_2D, beforeLoss);+ expect(gl.texImage2D).toHaveBeenCalledTimes(2);+ expect(restoreTextureContent).toHaveBeenCalledWith(tex.handle);+ });++ it('leaves the content owed when there is no context to take it with', () => {+ const gl = makeGl();+ const app = makeApp(gl);+ const tex = createCanvasTexture(app, makeSource(8, 8))!;+ const pool = (app.wasmModule!.GL as unknown as { textures: Record<number, WebGLTexture> }).textures;+ delete pool[7];++ expect(textureRefill(tex.handle)!()).toBe(false);+ expect(restoreTextureContent).not.toHaveBeenCalled();});});diff --git a/sdk/tests/texture-upload-leak.test.ts b/sdk/tests/texture-upload-leak.test.tsindex 95f1359fd..060663c08 100644--- a/sdk/tests/texture-upload-leak.test.ts+++ b/sdk/tests/texture-upload-leak.test.ts@@ -32,11 +32,11 @@ function mockGl(opts?: { createReturnsNull?: boolean; throwOnUpload?: boolean })}describe('TextureLoader.createTextureWebGL2', () => {- it('throws clearly when gl.createTexture() returns null (no `!` assert)', () => {+ it('throws clearly when the context gives no texture (no `!` assert)', () => {const loader = new TextureLoader({} as any);const { gl } = mockGl({ createReturnsNull: true });expect(() => (loader as any).createTextureWebGL2(gl, {} as any, 4, 4, true))- .toThrow(/createTexture\(\) returned null/);+ .toThrow(/gave no texture/);});it('releases the GL texture when the upload throws (no leak)', () => {diff --git a/sdk/tests/texture-webgl2-context.test.ts b/sdk/tests/texture-webgl2-context.test.tsindex abdda097e..028d851b2 100644--- a/sdk/tests/texture-webgl2-context.test.ts+++ b/sdk/tests/texture-webgl2-context.test.ts@@ -8,7 +8,7 @@* not-yet-current context.*/import { describe, it, expect, vi, afterEach } from 'vitest';-import { findWebGL2Context } from '../src/asset/loaders/TextureLoader';+import { findWebGL2Context } from '../src/asset/glTextureUpload';import type { ESEngineModule } from '../src/wasm';type GLObj = ESEngineModule['GL'];diff --git a/src/esengine/bindings/ResourceManagerBindings.cpp b/src/esengine/bindings/ResourceManagerBindings.cppindex 998b216ae..7d4fef211 100644--- a/src/esengine/bindings/ResourceManagerBindings.cpp+++ b/src/esengine/bindings/ResourceManagerBindings.cpp@@ -136,6 +136,14 @@ void rm_forgoTextureContent(resource::ResourceManager& rm, u32 handle) {rm.forgoTextureContent(resource::TextureHandle(handle));}+void rm_restoreTextureContent(resource::ResourceManager& rm, u32 handle) {+ rm.restoreTextureContent(resource::TextureHandle(handle));+}++u32 rm_getTextureNativeId(resource::ResourceManager& rm, u32 handle) {+ return rm.textureNativeId(resource::TextureHandle(handle));+}+bool rm_adoptTextureContent(resource::ResourceManager& rm, u32 target, u32 source) {return rm.adoptTextureContent(resource::TextureHandle(target), resource::TextureHandle(source));}diff --git a/src/esengine/bindings/ResourceManagerBindings.hpp b/src/esengine/bindings/ResourceManagerBindings.hppindex 08c02b7fd..b065c5538 100644--- a/src/esengine/bindings/ResourceManagerBindings.hpp+++ b/src/esengine/bindings/ResourceManagerBindings.hpp@@ -41,6 +41,8 @@ u32 rm_wrapDeviceTexture(resource::ResourceManager& rm, u32 textureId, u32 width/** @brief Gives up on an owed texture's content; it keeps blank storage. */void rm_forgoTextureContent(resource::ResourceManager& rm, u32 handle);+void rm_restoreTextureContent(resource::ResourceManager& rm, u32 handle);+u32 rm_getTextureNativeId(resource::ResourceManager& rm, u32 handle);/** @brief The textures the device is waiting for content for, as `handle|content|path` lines. */std::string rm_texturesAwaitingReupload(resource::ResourceManager& rm);diff --git a/src/esengine/bindings/WebSDKEntry.cpp b/src/esengine/bindings/WebSDKEntry.cppindex d6f85fc66..9268777d0 100644--- a/src/esengine/bindings/WebSDKEntry.cpp+++ b/src/esengine/bindings/WebSDKEntry.cpp@@ -481,6 +481,8 @@ EMSCRIPTEN_BINDINGS(esengine_renderer) {.function("wrapDeviceTexture", &esengine::rm_wrapDeviceTexture).function("texturesAwaitingReupload", &esengine::rm_texturesAwaitingReupload).function("forgoTextureContent", &esengine::rm_forgoTextureContent)+ .function("restoreTextureContent", &esengine::rm_restoreTextureContent)+ .function("getTextureNativeId", &esengine::rm_getTextureNativeId).function("meshesAwaitingRemat", &esengine::rm_meshesAwaitingRemat).function("meshRealizations", &esengine::rm_meshRealizations).function("adoptTextureContent", &esengine::rm_adoptTextureContent)diff --git a/src/esengine/renderer/rhi/GLDevice.hpp b/src/esengine/renderer/rhi/GLDevice.hppindex b26adddf8..6c24a3cd5 100644--- a/src/esengine/renderer/rhi/GLDevice.hpp+++ b/src/esengine/renderer/rhi/GLDevice.hpp@@ -92,7 +92,7 @@ public:i32 getInt(GfxIntParam name) override;/** @brief This generation's GL name behind a texture, for a host uploading into it. */- u32 nativeTextureName(TextureHandle texture) const { return nameOf(texture_names_, static_cast<u32>(texture)); }+ u32 nativeTextureName(TextureHandle texture) const override { return nameOf(texture_names_, static_cast<u32>(texture)); }protected:void captureDeviceIdentity() override;diff --git a/src/esengine/renderer/rhi/GfxDevice.cpp b/src/esengine/renderer/rhi/GfxDevice.cppindex 8cc988ebd..c0aef9754 100644--- a/src/esengine/renderer/rhi/GfxDevice.cpp+++ b/src/esengine/renderer/rhi/GfxDevice.cpp@@ -198,6 +198,16 @@ void GfxDevice::forgoContent(const GfxOwedContent& owed) {settleRecovery();}+void GfxDevice::restoreContent(const GfxOwedContent& owed) {+ if (owed.kind == GfxOwedContent::Kind::Texture) {+ if (auto* record = registry_.textures.find(owed.id); record && record->owed) {+ payTexture(owed.id, *record);+ }+ return;+ }+ forgoContent(owed);+}+// =============================================================================// Kept bytes// =============================================================================diff --git a/src/esengine/renderer/rhi/GfxDevice.hpp b/src/esengine/renderer/rhi/GfxDevice.hppindex 1bd35c36f..d148a629a 100644--- a/src/esengine/renderer/rhi/GfxDevice.hpp+++ b/src/esengine/renderer/rhi/GfxDevice.hpp@@ -168,6 +168,14 @@ public:*/void forgoContent(const GfxOwedContent& owed);+ /**+ * @brief Settles one owed object whose provider wrote its contents itself.+ * @details For content the device cannot upload: a JS-side path that draws a+ * canvas or a video frame straight into the native texture behind the+ * handle. The provider says so, because the device never saw the write.+ */+ void restoreContent(const GfxOwedContent& owed);+/*** @brief CPU bytes the device holds to put content back after a loss.* @details Retained content, plus the initial bytes of objects created while@@ -690,6 +698,14 @@ public:/** @brief GPU objects alive right now (see {@link GfxLiveObjects}), read off the registry. */GfxLiveObjects liveObjects() const;+ /**+ * @brief The backend's own name for the object behind `texture`, or 0.+ * @details For a host that writes the contents itself — a JS video frame or+ * canvas going straight into the texture. It is only valid until the+ * next device loss, which is why it is asked for at every write.+ */+ virtual u32 nativeTextureName(TextureHandle texture) const { (void)texture; return 0; }+protected:// =========================================================================// Backend primitives. `id` is the handle's value; the backend maps it to itsdiff --git a/src/esengine/resource/ResourceManager.cpp b/src/esengine/resource/ResourceManager.cppindex 9e947eb1a..b02785622 100644--- a/src/esengine/resource/ResourceManager.cpp+++ b/src/esengine/resource/ResourceManager.cpp@@ -342,6 +342,22 @@ void ResourceManager::forgoTextureContent(TextureHandle handle) {}}+void ResourceManager::restoreTextureContent(TextureHandle handle) {+ const Texture* texture = textures_.get(handle);+ if (!device_ || !texture) return;+ for (const GfxOwedContent& entry : device_->owedContent()) {+ if (entry.kind == GfxOwedContent::Kind::Texture && entry.id == texture->getId()) {+ device_->restoreContent(entry);+ return;+ }+ }+}++u32 ResourceManager::textureNativeId(TextureHandle handle) const {+ const Texture* texture = textures_.get(handle);+ return device_ && texture ? device_->nativeTextureName(texture->handle()) : 0;+}+void ResourceManager::registerTextureWithPath(TextureHandle handle, const std::string& path) {if (handle.isValid() && !path.empty()) {textures_.setPath(handle, path);diff --git a/src/esengine/resource/ResourceManager.hpp b/src/esengine/resource/ResourceManager.hppindex 71f7ff314..8d9e7baf4 100644--- a/src/esengine/resource/ResourceManager.hpp+++ b/src/esengine/resource/ResourceManager.hpp@@ -345,6 +345,17 @@ public:*/void forgoTextureContent(TextureHandle handle);+ /**+ * @brief Settles an owed texture whose provider wrote the pixels itself.+ * @details See GfxDevice::restoreContent — for a JS-side upload straight into+ * the native texture, which the device cannot see.+ */+ void restoreTextureContent(TextureHandle handle);++ /** @brief The backend's own name for a texture's object, for a host that writes+ * its pixels itself; 0 when there is none. See GfxDevice::nativeTextureName. */+ u32 textureNativeId(TextureHandle handle) const;+/*** @brief Gets the cached path for a texture* @param handle The texture handlediff --git a/tools/check-gl-boundary.mjs b/tools/check-gl-boundary.mjsindex 8388dc897..42148c603 100644--- a/tools/check-gl-boundary.mjs+++ b/tools/check-gl-boundary.mjs@@ -1,15 +1,20 @@#!/usr/bin/env node// SPDX-License-Identifier: Apache-2.0// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team-// =============================================================================-// GL boundary guard (RC5)-//-// Enforces the keystone invariant: raw OpenGL/WebGL calls (`glXxx(...)`) may-// appear ONLY in the single backend implementation (renderer/rhi/GLDevice.cpp).-// Every other translation unit must reach the GPU through GfxDevice/StateTracker.-//-// Run: node tools/check-gl-boundary.mjs (exit 1 on violation)-// =============================================================================+/**+ * @file check-gl-boundary.mjs+ * @brief Who may touch a GPU object directly, on both sides of the wasm boundary.+ *+ * @details C++: raw `glXxx(...)` calls only in renderer/rhi/GLDevice.cpp; everything+ * else reaches the GPU through GfxDevice. SDK: a GL texture object is+ * created, registered and looked up only in the upload bridge+ * (asset/glTextureUpload.ts) — a module that kept its own would write into+ * the object the device replaced at the last loss, which is how a video and+ * a leaderboard came back blank. Writing into the texture the bridge bound+ * is every caller's business and is not matched here.+ *+ * Run: node tools/check-gl-boundary.mjs (exit 1 on violation)+ */import { existsSync, readdirSync, readFileSync, statSync } from 'node:fs';import { join } from 'node:path';@@ -35,11 +40,11 @@ for (const allowed of ALLOWED) {const GL_CALL = /\bgl[A-Z]\w*\s*\(/;const SOURCE_EXT = /\.(cpp|cc|cxx|hpp|hxx|h)$/;-function walk(dir, out = []) {+function walk(dir, out = [], ext = SOURCE_EXT) {for (const entry of readdirSync(dir)) {const p = join(dir, entry);- if (statSync(p).isDirectory()) walk(p, out);- else if (SOURCE_EXT.test(entry)) out.push(p);+ if (statSync(p).isDirectory()) walk(p, out, ext);+ else if (ext.test(entry)) out.push(p);}return out;}@@ -63,4 +68,43 @@ if (violations.length > 0) {process.exit(1);}-console.log('GL boundary OK: no gl* calls outside GLDevice.cpp.');+// --- SDK side: who may own a GL texture object -------------------------------++const SDK_ROOT = 'sdk/src';+const BRIDGE = 'sdk/src/asset/glTextureUpload.ts';+// The type surface declares these entry points; declaring is not calling.+const SDK_EXEMPT = new Set([BRIDGE, 'sdk/src/wasm.ts']);+const SDK_RULES = [+ [/\.createTexture\s*\(\s*\)/, 'creates a GL texture (the device owns them: handOverNewTexture)'],+ [/\.bindTexture\s*\(/, 'binds a texture itself (writeDeviceTexture binds the one the device has)'],+ [/\bGL\.textures\b|\.getNewId\s*\(/, "reaches into emscripten's texture pool"],+ [/\.registerExternalTextureS?i?z?e?d?\s*\(/, 'hands a native id to the device outside the bridge'],+];+const SDK_EXT = /\.ts$/;++if (!existsSync(BRIDGE)) {+ console.error(`GL boundary guard is stale: the upload bridge ${BRIDGE} does not exist.`);+ process.exit(1);+}++const sdkViolations = [];+for (const file of walk(SDK_ROOT, [], SDK_EXT)) {+ const rel = file.replace(/\\/g, '/');+ if (SDK_EXEMPT.has(rel) || rel.endsWith('.generated.ts')) continue;+ const lines = readFileSync(file, 'utf8').split('\n');+ lines.forEach((line, i) => {+ for (const [pattern, why] of SDK_RULES) {+ if (pattern.test(line)) sdkViolations.push(` ${rel}:${i + 1}: ${why}\n ${line.trim()}`);+ }+ });+}++if (sdkViolations.length > 0) {+ console.error(`GL texture boundary violation — only ${BRIDGE} owns GL texture objects:\n`);+ console.error(sdkViolations.join('\n'));+ console.error(`\n${sdkViolations.length} violation(s). Take a handle from handOverNewTexture and`+ + ' write through writeDeviceTexture, so a device loss cannot leave you uploading into a dead object.');+ process.exit(1);+}++console.log('GL boundary OK: no gl* calls outside GLDevice.cpp, and GL textures only in the upload bridge.');diff --git a/tools/releaseNotes.mjs b/tools/releaseNotes.mjsindex 652ea144c..b73760a92 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 = {+ 'fix(render): a video and a canvas come back after the GPU is lost':+ { note: 'The picture comes back after the GPU is lost.' },+'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.' },diff --git a/tools/renderScenes.mjs b/tools/renderScenes.mjsindex 9e6ccbc43..0c5afb33d 100644--- a/tools/renderScenes.mjs+++ b/tools/renderScenes.mjs@@ -746,6 +746,10 @@ export const SCENES = [// 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" } },+ // A video that has ENDED, so the only way its frame comes back is the provider:+ // a playing one would paper over a missing refill with its next frame, and the+ // clip is one still image, so nothing else can tell the two apart.+ { id: "device-roundtrip-video", tier: "nightly", webgpu: true, env: { ESTELLA_VERIFY_DEVICE_LOSS: "roundtrip", ESTELLA_VERIFY_LOSS_ROUNDS: "2", ESTELLA_VERIFY_PLAY: "1", ESTELLA_VERIFY_SETTLE_MS: "4000", ESTELLA_VERIFY_SCENE: "/scenes/video-ended.esscene", ESTELLA_VERIFY_MANIFEST: "/scenes/video-ended.textures.json", ESTELLA_VERIFY_W: "256", ESTELLA_VERIFY_H: "256", ESTELLA_VERIFY_STEPS: "2" } },{ 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" } },];