A fast 2D and 3D game engine — TypeScript SDK, C++/WebAssembly core, visual editor. Ship one project to web, desktop, WeChat MiniGames, playable ads, and native Android / iOS.
TypeScript 2d-game-engine3d3d-game-engineandroidcppecsgame-editorgame-enginegamedeviostypescriptwebassemblywebglwebgpuwechat-minigame
feat(gfx): async readback seam - readPixels retired, material preview lands on WebGPU
yhh7b2ad3a7c1e8
diff --git a/desktop/public/scenes/mat-tint/tint.esshader b/desktop/public/scenes/mat-tint/tint.esshaderindex 570c78f57..021a763d3 100644--- a/desktop/public/scenes/mat-tint/tint.esshader+++ b/desktop/public/scenes/mat-tint/tint.esshader@@ -39,3 +39,44 @@ void main() {fragColor = texColor * v_color * u_tint;}#pragma end++#pragma vertex wgsl+struct FrameConstants { projection : mat4x4f };+@group(0) @binding(0) var<uniform> frame : FrameConstants;++struct VSIn {+ @location(0) a_position : vec2f,+ @location(1) a_color : vec4f,+ @location(2) a_texCoord : vec2f,+ @location(3) a_texIndex : f32,+};+struct VSOut {+ @builtin(position) pos : vec4f,+ @location(0) v_color : vec4f,+ @location(1) v_texCoord : vec2f,+};++@vertex fn vs_main(v : VSIn) -> VSOut {+ var out : VSOut;+ out.pos = frame.projection * vec4f(v.a_position, 0.0, 1.0);+ out.v_color = v.a_color;+ out.v_texCoord = v.a_texCoord;+ return out;+}+#pragma end++#pragma fragment wgsl+struct VSOut {+ @builtin(position) pos : vec4f,+ @location(0) v_color : vec4f,+ @location(1) v_texCoord : vec2f,+};++@group(1) @binding(0) var t0 : texture_2d<f32>;+@group(1) @binding(8) var s0 : sampler;++@fragment fn fs_main(v : VSOut) -> @location(0) vec4f {+ let texColor = textureSample(t0, s0, v.v_texCoord);+ return texColor * v.v_color * mc.u_tint;+}+#pragma enddiff --git a/desktop/scripts/headless-verify.mjs b/desktop/scripts/headless-verify.mjsindex 1fbbae8f8..db5bcb369 100644--- a/desktop/scripts/headless-verify.mjs+++ b/desktop/scripts/headless-verify.mjs@@ -250,16 +250,14 @@ app.whenReady().then(async () => {// Optional offscreen material-preview assertion (ESTELLA_VERIFY_PREVIEW =// {w,h,rgb:[r,g,b],tol?}): renders a scene material to an offscreen target and checks the// center pixel — proves the render-to-texture preview primitive, not just the viewport.- // The material preview reads back through GL — skipped on WebGPU (its- // buffer maps are async; a readback seam is future work).+ // The readback rides the engine's async seam, so the same awaited call+ // verifies BOTH backends (GL resolves immediately; WebGPU when the map lands).let preview = null;- if (process.env.ESTELLA_VERIFY_PREVIEW && BACKEND === 'webgpu') {- console.log('[verify:render] preview assertion skipped on webgpu');- } else if (process.env.ESTELLA_VERIFY_PREVIEW) {+ if (process.env.ESTELLA_VERIFY_PREVIEW) {const cfg = JSON.parse(process.env.ESTELLA_VERIFY_PREVIEW);- preview = await exec(`(() => {+ preview = await exec(`(async () => {const cfg = ${JSON.stringify(cfg)};- const cap = window.__estellaHeadless.api.renderSceneMaterialPreview(cfg.w, cfg.h);+ const cap = await window.__estellaHeadless.api.renderSceneMaterialPreview(cfg.w, cfg.h);if (!cap) return { ok: false, reason: 'no scene material' };const { width: w, height: h, rgba } = cap;const i = (Math.floor(h / 2) * w + Math.floor(w / 2)) * 4;diff --git a/desktop/src/engine/EditorControlSurface.ts b/desktop/src/engine/EditorControlSurface.tsindex c968dbd1d..902994746 100644--- a/desktop/src/engine/EditorControlSurface.ts+++ b/desktop/src/engine/EditorControlSurface.ts@@ -342,16 +342,18 @@ export class EditorControlSurfaceImpl {/*** Render a material to an offscreen @p w×@p h target (a "material ball" preview), found by the* handle a scene sprite carries — so a loaded scene's material can be previewed without- * re-loading it. Reuses the real render path. Null if no sprite material is in the scene.+ * re-loading it. Reuses the real render path; the pixel readback rides the engine's async+ * seam (immediate on GL, a later event-loop turn on WebGPU), so the result is awaited.+ * Null if no sprite material is in the scene.*/- renderSceneMaterialPreview(w: number, h: number): ViewportCapture | null {+ async renderSceneMaterialPreview(w: number, h: number): Promise<ViewportCapture | null> {const world = EngineHost.world;if (!world) return null;for (const e of world.getAllEntities()) {if (!world.has(e, Sprite)) continue;const mat = (world.get(e, Sprite) as { material: number }).material;if (!mat) continue;- const img = Material.renderPreview(mat, w, h);+ const img = await Material.renderPreview(mat, w, h);if (img) return { rgba: new Uint8Array(img.data), width: img.width, height: img.height };}return null;diff --git a/desktop/src/material/materialInspectorModel.ts b/desktop/src/material/materialInspectorModel.tsindex b6b506ded..e6242e443 100644--- a/desktop/src/material/materialInspectorModel.ts+++ b/desktop/src/material/materialInspectorModel.ts@@ -270,10 +270,11 @@ export function projectMaterialToHandle(asset: MaterialAssetData, ctx: MaterialC/*** Draw a live "material ball" thumbnail of the material at @p handle into @p canvas (a square),* via the engine's offscreen render-to-texture preview. No-op without a handle/canvas; call it- * after pushing edits to the handle so the thumbnail reflects them.+ * after pushing edits to the handle so the thumbnail reflects them. The preview readback is+ * async (the engine's backend-neutral seam); the canvas repaints when it lands.*/-export function renderMaterialThumbnail(handle: number, canvas: HTMLCanvasElement | null): void {+export async function renderMaterialThumbnail(handle: number, canvas: HTMLCanvasElement | null): Promise<void> {if (!handle || !canvas) return;- const img = Material.renderPreview(handle, canvas.width, canvas.height);+ const img = await Material.renderPreview(handle, canvas.width, canvas.height);if (img) canvas.getContext('2d')?.putImageData(img, 0, 0);}diff --git a/desktop/src/panels/Details.tsx b/desktop/src/panels/Details.tsxindex df66374b2..58aa781b2 100644--- a/desktop/src/panels/Details.tsx+++ b/desktop/src/panels/Details.tsx@@ -1490,7 +1490,7 @@ function MaterialAssetInspector({ path }: { path: string }) {useEffect(() => {if (loaded && asset && ctx) {projectMaterialToHandle(asset, ctx, MaterialDocument.liveHandle);- renderMaterialThumbnail(MaterialDocument.liveHandle, thumbRef.current);+ void renderMaterialThumbnail(MaterialDocument.liveHandle, thumbRef.current);}}, [revision, ctx, loaded]);diff --git a/docs/REARCHITECTURE.md b/docs/REARCHITECTURE.mdindex bde5b582b..ce7cc7dbb 100644--- a/docs/REARCHITECTURE.md+++ b/docs/REARCHITECTURE.md@@ -189,7 +189,8 @@ TS 驱动的主 pass clear 退出边界,`clear` 家族退出公共 RHI:**Phase 3 完结(切片 1-6,2026-07-07 单日)**:显式绑定布局(掩码缓存 BGL + 哑资源回填,纹理槽 8→16);`.esshader` `#pragma vertex/fragment wgsl` 孪生段 + 注入头双语发射(块变量移植规则 tc/mc/lc、std140≡WGSL 布局、feature 迷你预处理器);batch/shape/particle 内嵌归位单路径;7 模板 + 3 滤镜 + 13 后处理效果全部双语(PP 参数迁反射 MaterialConstants per-pass UBO,`u_resolution` 退役);materialGraph 单 DAG 双语发射。**SDK 启动 + resize(campaign coda)**:web 变体带 WebGPU 后端(wechat/playable 保持 GL 零胶水体积)、`WebAppOptions.backend`、`ESTELLA_VERIFY_BACKEND=webgpu` 场景断言像素精确相等、`GfxDevice::resizeBackbuffer` 每帧契约(WebGPU swapchain 重配)。**Custom-draw/Draw API 现代化(2026-07-08,最后一个 GL-only 通路闭合)**:新绑定 `draw_meshWithMaterial`——反射材质(compileEsshader)经 `MaterialStore::bindForDraw` 走 MaterialConstants(binding 1)+ 材质记录供给全部管线态,两后端同路零散装 uniform;TS 侧 18 名字 loose 表退为 raw-GLSL `createShader` 兼容路径。编辑器网格迁双语 `.esshader`(`u_model`→`u_rect` 参数 + authored vertex 声明 FrameConstants)——**WebGPU 下编辑器网格首次渲染**,GL/WebGPU 帧一致;`ESTELLA_VERIFY_GRID` 双后端 on/off 像素 diff 断言入 harness。-**剩余**:Phase 4 用户手写 `.esshader` 的 cook 期 naga 转换(归 RC6 资产管线;实测边界——mat-lit 等场景资产 shader 无孪生,WebGPU 下按设计描述性跳过);WebGPU 异步 readback seam(`readPixels` stub,材质预览断言跳过);CI 无 WebGPU 适配器(webgpu verify 仅本地)。+**WebGPU 异步 readback seam(2026-07-08,后端不对称性收口)**:同步 `readPixels` 退出 RHI,全接口统一为异步四段 `requestReadback / pollReadback / takeReadback / discardReadback`(GL = 请求时同步读、首 poll 即 Ready;WebGPU = `copyTextureToBuffer` → 256 对齐 staging + `mapAsync(AllowSpontaneous)`,跨事件循环 turn 落地;行序统一 bottom-up 契约在 take 时翻转)。RenderFrame 的两个消费者(材质预览 renderToTarget、帧调试器 replayToDrawCall)改为 pass 关闭后请求 + `pollPreview/SnapshotReadback` 落地(顺带修 snapshot 尺寸 getter 读当前帧而非快照时尺寸的隐患);TS 侧 `Material.renderPreview`/`Renderer.getSnapshotImageData` 转 Promise(`readback.ts` 单一 poll 循环,双后端同码)。离屏色纹理补 `CopySrc` usage。**材质预览断言在 WebGPU 下点亮**:mat-tint 场景(补了手写 WGSL 孪生的用户 `.esshader` 资产)双后端 EXPECT + PREVIEW 像素精确 PASS——顺带证明场景资产 shader 带孪生即可整链上 WebGPU。+**剩余**:Phase 4 用户手写 `.esshader` 的 cook 期 naga 转换(归 RC6 资产管线;无孪生的场景资产 shader 在 WebGPU 下按设计描述性跳过);CI 无 WebGPU 适配器(webgpu verify 仅本地)。见 `REARCH_WGSL.md`(本地 gitignore,同 RC6/2D_PARITY 约定):着色器版图盘点(uniform 数据已全后端中立,剩程序文本)、岔路拍板(有限集人工孪生 / 图材质 AST 双发射 / 用户材质 cook 期转换——拒绝运行时翻译器的 MB 级体积代价)、四期计划(源语言接缝 → WebGPUDevice 原型 → 双语发射 → cook 期用户材质)。**Phase 0 已落地**:最后 3 个 GLSL ES 1.00 残留(SDK outline/drop-shadow/color-matrix 滤镜)重写为 fragment-only `.esshader` 反射路径——顺带修复其设计性破损(raw 形态无 `u_projection` 来源、无属性绑定、mat4 超 `setMaterialUniform` 的 vec4 上限**从未能传入**;色彩矩阵改为 4×vec4 行 + 偏移列,新增 `Filters.colorMatrixUniforms` 助手)。全仓每个程序自此都在现代缝上(300 es + UBO 反射)。**Phase 1(源语言接缝)已落地**:RHI 补上最后一块后端中立拼图——`createProgram` 收语言标签的 `GfxShaderSource`,新增 `supportsShaderLanguage` 能力查询(GL = 仅 GLSL ES 300;`Shader::compile` 在任何 GPU 调用前对不支持的语言快速失败);语言贯穿 Shader/ResourceManager(DrawParams 重写仅对 GLSL 生效);`ShaderParser::assembleStage` 获得 `ShaderTargetLanguage` 参数(WGSL 发射 = Phase 3)。MockGfxDevice 新增 `wgslSupported` 开关 + 语言门用例;行为零变化(8 harness + 场景抽样等价)。**Phase 2 切片 1(WebGPU 后端启动)已落地**:emdawnwebgpu 端口(Dawn)集成为测试目标独立依赖(主构建零影响);`renderer/webgpu/` 新增纯映射层(GfxEnums→WGPU 全翻译,blend/模板表镜像 GLDevice 语义,load-op 规则与 RenderPassDesc 契约一致)+ 空设备安全的 `WebGPUDevice` 骨架(缓冲/纹理/WGSL 模块真实现,布局/管线描述符保留待惰性构建,pass/draw 为切片 2 结构化桩);`test_webgpu_device` 用真 Dawn 头编译验证全部描述符拼写,入 CI。diff --git a/sdk/src/frameCapture.ts b/sdk/src/frameCapture.tsindex 1810f89a7..6f891486d 100644--- a/sdk/src/frameCapture.ts+++ b/sdk/src/frameCapture.ts@@ -1,6 +1,7 @@// SPDX-License-Identifier: Apache-2.0// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Teamimport type { ESEngineModule } from './wasm';+import { awaitReadback, READBACK_READY } from './readback';/*** Memory-safety model for this module@@ -149,7 +150,15 @@ export function replayToDrawCall(module: ESEngineModule, drawCallIndex: number):module.renderer_replayToDrawCall(drawCallIndex);}-export function getSnapshotImageData(module: ESEngineModule): ImageData | null {+/**+ * Resolves with the replay snapshot's pixels once its readback lands (the async+ * seam: immediate on GL, a later event-loop turn on WebGPU). Null when no+ * snapshot is in flight or the readback failed.+ */+export async function getSnapshotImageData(module: ESEngineModule): Promise<ImageData | null> {+ if (await awaitReadback(() => module.renderer_pollSnapshotReadback()) !== READBACK_READY) {+ return null;+ }const size = module.renderer_getSnapshotSize();if (size === 0) return null;diff --git a/sdk/src/material.ts b/sdk/src/material.tsindex 0fe631d60..2fed86cb2 100644--- a/sdk/src/material.ts+++ b/sdk/src/material.ts@@ -9,6 +9,7 @@import type { ESEngineModule } from './wasm';import { CoreApiBridge } from './CoreApiBridge';import { requireResourceManager } from './resourceManager';+import { awaitReadback, READBACK_READY } from './readback';import type { Vec2, Vec3, Vec4 } from './types';import { BlendMode } from './blend';@@ -456,19 +457,26 @@ export const Material = {},/**- * Render a material to an offscreen @p w×@p h target and return its pixels (a "material ball"- * thumbnail). Reuses the real viewport render path — a unit quad lit by one directional light- * — so the preview matches how the material looks in-scene. Null if the engine isn't ready.+ * Render a material to an offscreen @p w×@p h target and resolve with its pixels (a+ * "material ball" thumbnail). Reuses the real viewport render path — a unit quad lit by one+ * directional light — so the preview matches how the material looks in-scene. The readback+ * rides the engine's async seam: immediate on GL, resolved when the staging-buffer map+ * lands on WebGPU — one awaited call either way. Null if the engine isn't ready or the+ * readback fails.*/- renderPreview(material: MaterialHandle, w: number, h: number): ImageData | null {- if (!module) return null;- module.renderer_renderMaterialPreview(material, w, h);- const size = module.renderer_getPreviewSize();- const pw = module.renderer_getPreviewWidth();- const ph = module.renderer_getPreviewHeight();+ async renderPreview(material: MaterialHandle, w: number, h: number): Promise<ImageData | null> {+ const m = module;+ if (!m) return null;+ m.renderer_renderMaterialPreview(material, w, h);+ if (await awaitReadback(() => m.renderer_pollPreviewReadback()) !== READBACK_READY) {+ return null;+ }+ const size = m.renderer_getPreviewSize();+ const pw = m.renderer_getPreviewWidth();+ const ph = m.renderer_getPreviewHeight();if (size === 0 || pw === 0 || ph === 0) return null;- const pixels = new Uint8ClampedArray(module.HEAPU8.buffer, module.renderer_getPreviewPtr(), size);- // GL reads bottom-up; flip rows so the thumbnail is upright.+ const pixels = new Uint8ClampedArray(m.HEAPU8.buffer, m.renderer_getPreviewPtr(), size);+ // Readback rows are bottom-up; flip so the thumbnail is upright.const flipped = new Uint8ClampedArray(size);const rowBytes = pw * 4;for (let y = 0; y < ph; y++) {diff --git a/sdk/src/readback.ts b/sdk/src/readback.tsnew file mode 100644index 000000000..65f6a1bbc--- /dev/null+++ b/sdk/src/readback.ts@@ -0,0 +1,34 @@+// SPDX-License-Identifier: Apache-2.0+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team+/**+ * @file readback.ts+ * @brief Polling loop for the engine's async GPU readback seam.+ *+ * The engine exposes readbacks as a poll contract (0 = pending, 1 = ready,+ * 2 = none/failed): GL completes at request time so the first poll reports 1,+ * while WebGPU resolves its staging-buffer map on a later event-loop turn —+ * the loop below yields a macrotask between polls so that turn can happen.+ * One awaited loop serves both backends.+ */++/** Poll result: the readback landed and the engine buffers serve the pixels. */+export const READBACK_READY = 1;+/** Poll result: no readback in flight, or it failed. */+export const READBACK_FAILED = 2;++/**+ * Awaits an engine readback poll until it reports ready (1) or failed (2),+ * yielding a macrotask between pending polls. Returns the terminal status;+ * a readback still pending after @p maxPolls resolves as failed.+ */+export async function awaitReadback(+ poll: () => number,+ maxPolls = 240,+): Promise<number> {+ for (let i = 0; i < maxPolls; i++) {+ const status = poll();+ if (status !== 0) return status;+ await new Promise<void>((resolve) => setTimeout(resolve, 0));+ }+ return READBACK_FAILED;+}diff --git a/sdk/src/renderer.ts b/sdk/src/renderer.tsindex add16d87f..cf1f03459 100644--- a/sdk/src/renderer.ts+++ b/sdk/src/renderer.ts@@ -186,8 +186,9 @@ export const Renderer = {replayToDrawCallImpl(module, drawCallIndex);},- getSnapshotImageData(): ImageData | null {- if (!module) return null;+ /** Resolves with the replay snapshot once its async readback lands (see frameCapture). */+ getSnapshotImageData(): Promise<ImageData | null> {+ if (!module) return Promise.resolve(null);return getSnapshotImpl(module);},};diff --git a/sdk/src/wasm.ts b/sdk/src/wasm.tsindex 87c0150af..bcc1f28ea 100644--- a/sdk/src/wasm.ts+++ b/sdk/src/wasm.ts@@ -378,11 +378,17 @@ export interface ESEngineModule {renderer_hasCapturedData(): boolean;renderer_replayToDrawCall(drawCallIndex: number): void;+ /** Lands the snapshot's async readback: 0 = pending (yield, poll again),+ * 1 = getSnapshot* serve the pixels, 2 = none/failed. GL reports 1 on the+ * first poll; WebGPU resolves on a later event-loop turn. */+ renderer_pollSnapshotReadback(): number;renderer_getSnapshotPtr(): number;renderer_getSnapshotSize(): number;renderer_getSnapshotWidth(): number;renderer_getSnapshotHeight(): number;renderer_renderMaterialPreview(materialId: number, w: number, h: number): void;+ /** Same 0/1/2 readback contract as renderer_pollSnapshotReadback. */+ renderer_pollPreviewReadback(): number;renderer_getPreviewPtr(): number;renderer_getPreviewSize(): number;renderer_getPreviewWidth(): number;diff --git a/sdk/tests/frame-capture.test.ts b/sdk/tests/frame-capture.test.tsindex fc3f7b305..32de4edb6 100644--- a/sdk/tests/frame-capture.test.ts+++ b/sdk/tests/frame-capture.test.ts@@ -32,8 +32,10 @@ function buildModule(opts: {height: number;drawCallCount?: number;entities?: number[];+ /** Async-readback poll result (0 pending / 1 ready / 2 none-failed); default ready. */+ pollStatus?: number;}): { module: ESEngineModule; heap: Uint8Array; dataPtr: number; entitiesPtr: number; snapshotPtr: number } {- const { width, height, drawCallCount = 0, entities = [] } = opts;+ const { width, height, drawCallCount = 0, entities = [], pollStatus = 1 } = opts;const RECORD_SIZE = 76;const snapshotSize = width * height * 4;const entitiesSize = entities.length * 4;@@ -69,6 +71,7 @@ function buildModule(opts: {renderer_getCapturedEntities: () => entitiesPtr,renderer_getCapturedEntityCount: () => entities.length,renderer_getCapturedCameraCount: () => 1,+ renderer_pollSnapshotReadback: () => pollStatus,renderer_getSnapshotSize: () => snapshotSize,renderer_getSnapshotWidth: () => width,renderer_getSnapshotHeight: () => height,@@ -79,9 +82,9 @@ function buildModule(opts: {}describe('getSnapshotImageData', () => {- it('returns a JS-owned buffer independent from the WASM heap', () => {+ it('returns a JS-owned buffer independent from the WASM heap', async () => {const { module, heap, snapshotPtr } = buildModule({ width: 4, height: 2 });- const img = getSnapshotImageData(module);+ const img = await getSnapshotImageData(module);expect(img).not.toBeNull();const snapshotBefore = Array.from(img!.data);@@ -94,15 +97,32 @@ describe('getSnapshotImageData', () => {expect(snapshotAfter).toEqual(snapshotBefore);});- it('returns null when the renderer has no snapshot available', () => {+ it('returns null when the renderer has no snapshot available', async () => {const zero = buildModule({ width: 0, height: 0 });- expect(getSnapshotImageData(zero.module)).toBeNull();+ expect(await getSnapshotImageData(zero.module)).toBeNull();});- it('applies vertical flip so row 0 of output is the last source row', () => {+ it('returns null when the readback reports none/failed', async () => {+ const failed = buildModule({ width: 4, height: 2, pollStatus: 2 });+ expect(await getSnapshotImageData(failed.module)).toBeNull();+ });++ it('resolves after pending polls once the readback lands', async () => {+ const w = 2, h = 2;+ const built = buildModule({ width: w, height: h });+ // First two polls report pending; the loop must yield and re-poll.+ let polls = 0;+ (built.module as { renderer_pollSnapshotReadback: () => number }).renderer_pollSnapshotReadback =+ () => (++polls < 3 ? 0 : 1);+ const img = await getSnapshotImageData(built.module);+ expect(img).not.toBeNull();+ expect(polls).toBe(3);+ });++ it('applies vertical flip so row 0 of output is the last source row', async () => {const w = 2, h = 3;const { module } = buildModule({ width: w, height: h });- const img = getSnapshotImageData(module)!;+ const img = (await getSnapshotImageData(module))!;expect(img.width).toBe(w);expect(img.height).toBe(h);diff --git a/src/esengine/bindings/RendererBindings.cpp b/src/esengine/bindings/RendererBindings.cppindex f96af43f9..9e5152af2 100644--- a/src/esengine/bindings/RendererBindings.cpp+++ b/src/esengine/bindings/RendererBindings.cpp@@ -723,6 +723,12 @@ void renderer_replayToDrawCall(i32 drawCallIndex) {g_renderFrame->replayToDrawCall(drawCallIndex);}+// Lands the snapshot's async readback: 0 = pending (poll again after yielding+// to the event loop), 1 = getSnapshot* serve the pixels, 2 = none/failed.+i32 renderer_pollSnapshotReadback() {+ return g_renderFrame ? g_renderFrame->pollSnapshotReadback() : 2;+}+uintptr_t renderer_getSnapshotPtr() {if (!g_renderFrame) return 0;return reinterpret_cast<uintptr_t>(g_renderFrame->getSnapshotPixels());@@ -768,6 +774,11 @@ void renderer_renderMaterialPreview(u32 materialId, i32 w, i32 h) {g_renderFrame->renderToTarget(reg, vp, static_cast<u32>(w), static_cast<u32>(h));}+// Same 0/1/2 contract as renderer_pollSnapshotReadback, for the material preview.+i32 renderer_pollPreviewReadback() {+ return g_renderFrame ? g_renderFrame->pollPreviewReadback() : 2;+}+uintptr_t renderer_getPreviewPtr() {return g_renderFrame ? reinterpret_cast<uintptr_t>(g_renderFrame->getPreviewPixels()) : 0;}diff --git a/src/esengine/bindings/RendererBindings.hpp b/src/esengine/bindings/RendererBindings.hppindex 12007397d..11ab9a3f4 100644--- a/src/esengine/bindings/RendererBindings.hpp+++ b/src/esengine/bindings/RendererBindings.hpp@@ -145,12 +145,14 @@ u32 renderer_getCapturedCameraCount();bool renderer_hasCapturedData();void renderer_replayToDrawCall(i32 drawCallIndex);+i32 renderer_pollSnapshotReadback();uintptr_t renderer_getSnapshotPtr();u32 renderer_getSnapshotSize();u32 renderer_getSnapshotWidth();u32 renderer_getSnapshotHeight();void renderer_renderMaterialPreview(u32 materialId, i32 w, i32 h);+i32 renderer_pollPreviewReadback();uintptr_t renderer_getPreviewPtr();u32 renderer_getPreviewSize();u32 renderer_getPreviewWidth();diff --git a/src/esengine/bindings/WebSDKEntry.cpp b/src/esengine/bindings/WebSDKEntry.cppindex 0bbc1ae9a..f5c5c47ae 100644--- a/src/esengine/bindings/WebSDKEntry.cpp+++ b/src/esengine/bindings/WebSDKEntry.cpp@@ -629,11 +629,13 @@ EMSCRIPTEN_BINDINGS(esengine_renderer) {emscripten::function("renderer_getCapturedCameraCount", &esengine::renderer_getCapturedCameraCount);emscripten::function("renderer_hasCapturedData", &esengine::renderer_hasCapturedData);emscripten::function("renderer_replayToDrawCall", &esengine::renderer_replayToDrawCall);+ emscripten::function("renderer_pollSnapshotReadback", &esengine::renderer_pollSnapshotReadback);emscripten::function("renderer_getSnapshotPtr", &esengine::renderer_getSnapshotPtr);emscripten::function("renderer_getSnapshotSize", &esengine::renderer_getSnapshotSize);emscripten::function("renderer_getSnapshotWidth", &esengine::renderer_getSnapshotWidth);emscripten::function("renderer_getSnapshotHeight", &esengine::renderer_getSnapshotHeight);emscripten::function("renderer_renderMaterialPreview", &esengine::renderer_renderMaterialPreview);+ emscripten::function("renderer_pollPreviewReadback", &esengine::renderer_pollPreviewReadback);emscripten::function("renderer_getPreviewPtr", &esengine::renderer_getPreviewPtr);emscripten::function("renderer_getPreviewSize", &esengine::renderer_getPreviewSize);emscripten::function("renderer_getPreviewWidth", &esengine::renderer_getPreviewWidth);diff --git a/src/esengine/renderer/GLDevice.cpp b/src/esengine/renderer/GLDevice.cppindex 69d016823..9fbf94cf5 100644--- a/src/esengine/renderer/GLDevice.cpp+++ b/src/esengine/renderer/GLDevice.cpp@@ -962,12 +962,38 @@ void GLDevice::endRenderPass() {}// =============================================================================-// Readback+// Readback (async seam; GL resolves at request time)// =============================================================================-void GLDevice::readPixels(i32 x, i32 y, u32 w, u32 h, GfxPixelFormat format, void* data) {- auto gl = toGLPixelFormat(format);- glReadPixels(x, y, static_cast<GLsizei>(w), static_cast<GLsizei>(h), gl.format, gl.type, data);+ReadbackHandle GLDevice::requestReadback(FramebufferHandle target, u32 w, u32 h) {+ if (w == 0 || h == 0) return ReadbackHandle::Invalid;+ std::vector<u8> pixels(static_cast<usize>(w) * h * 4);+ // Called outside a pass (framebuffer 0 bound); bind the source, read, restore.+ glBindFramebuffer(GL_FRAMEBUFFER, static_cast<GLuint>(target));+ auto gl = toGLPixelFormat(GfxPixelFormat::RGBA8);+ glReadPixels(0, 0, static_cast<GLsizei>(w), static_cast<GLsizei>(h), gl.format, gl.type,+ pixels.data());+ glBindFramebuffer(GL_FRAMEBUFFER, 0);+ const u32 id = next_readback_id_++;+ readbacks_[id] = std::move(pixels);+ return static_cast<ReadbackHandle>(id);+}++GfxReadbackStatus GLDevice::pollReadback(ReadbackHandle handle) {+ return readbacks_.count(static_cast<u32>(handle)) ? GfxReadbackStatus::Ready+ : GfxReadbackStatus::Failed;+}++bool GLDevice::takeReadback(ReadbackHandle handle, void* dest, usize destSize) {+ auto it = readbacks_.find(static_cast<u32>(handle));+ if (it == readbacks_.end() || destSize < it->second.size()) return false;+ std::memcpy(dest, it->second.data(), it->second.size());+ readbacks_.erase(it);+ return true;+}++void GLDevice::discardReadback(ReadbackHandle handle) {+ readbacks_.erase(static_cast<u32>(handle));}// =============================================================================diff --git a/src/esengine/renderer/GLDevice.hpp b/src/esengine/renderer/GLDevice.hppindex 92c204ad0..1e3866372 100644--- a/src/esengine/renderer/GLDevice.hpp+++ b/src/esengine/renderer/GLDevice.hpp@@ -106,7 +106,10 @@ public:void beginRenderPass(const RenderPassDesc& desc) override;void endRenderPass() override;- void readPixels(i32 x, i32 y, u32 w, u32 h, GfxPixelFormat format, void* data) override;+ ReadbackHandle requestReadback(FramebufferHandle target, u32 w, u32 h) override;+ GfxReadbackStatus pollReadback(ReadbackHandle handle) override;+ bool takeReadback(ReadbackHandle handle, void* dest, usize destSize) override;+ void discardReadback(ReadbackHandle handle) override;u32 createTimerQuery() override;void beginTimerQuery(u32 query) override;@@ -183,6 +186,11 @@ private:std::unordered_map<u32, BufferMeta> buffer_meta_;std::unordered_map<u32, GfxPixelFormat> texture_formats_;+ // Completed readbacks parked until taken: GL reads synchronously at request+ // time, so the async contract resolves on the caller's first poll.+ std::unordered_map<u32, std::vector<u8>> readbacks_;+ u32 next_readback_id_ = 1;+// 0 = unprobed, 1 = timer queries available, 2 = unavailable.int timer_query_state_ = 0;};diff --git a/src/esengine/renderer/GfxDevice.hpp b/src/esengine/renderer/GfxDevice.hppindex 5ca1183cb..d9becf71b 100644--- a/src/esengine/renderer/GfxDevice.hpp+++ b/src/esengine/renderer/GfxDevice.hpp@@ -334,11 +334,35 @@ public:}// =========================================================================- // Readback+ // Readback (asynchronous seam — the one backend-neutral pixel-return path)// =========================================================================- /** @brief Reads pixels from the current framebuffer */- virtual void readPixels(i32 x, i32 y, u32 w, u32 h, GfxPixelFormat format, void* data) = 0;+ /**+ * @brief Requests an RGBA8 readback of a framebuffer's color attachment.+ * @details Backend-neutral contract: GL reads synchronously (the first poll+ * reports Ready); WebGPU records a texture→staging copy and resolves+ * when the buffer map lands, so callers must poll across event-loop+ * turns. Must be called OUTSIDE a render pass. Rows land bottom-up+ * (the GL convention every capture consumer assumes). The WebGPU+ * backend reads offscreen targets only — the surface texture is not+ * copyable — so a Default-target request returns Invalid there.+ * @return A handle to poll, or Invalid when the request cannot be issued.+ */+ virtual ReadbackHandle requestReadback(FramebufferHandle target, u32 w, u32 h) = 0;++ /** @brief The state of an in-flight readback; pumps backend completion events.+ * A Failed readback is released by the poll that reported it. */+ virtual GfxReadbackStatus pollReadback(ReadbackHandle handle) = 0;++ /**+ * @brief Copies a Ready readback's pixels (w*h*4 bytes) into @p dest and releases it.+ * @return False when the handle is unknown, still Pending, or @p destSize is short —+ * a Pending readback stays alive.+ */+ virtual bool takeReadback(ReadbackHandle handle, void* dest, usize destSize) = 0;++ /** @brief Abandons a readback (any state); its resources are released. */+ virtual void discardReadback(ReadbackHandle handle) = 0;// =========================================================================// GPU Timing (optional; EXT_disjoint_timer_query on WebGL2)diff --git a/src/esengine/renderer/GfxEnums.hpp b/src/esengine/renderer/GfxEnums.hppindex f1d3e23c6..46d751ec6 100644--- a/src/esengine/renderer/GfxEnums.hpp+++ b/src/esengine/renderer/GfxEnums.hpp@@ -33,6 +33,16 @@ enum class TextureHandle : u32 { Invalid = 0 };enum class ShaderHandle : u32 { Invalid = 0 };/** @brief Handle 0 is the default framebuffer (backbuffer); it cannot be created or deleted. */enum class FramebufferHandle : u32 { Default = 0 };+/** @brief An in-flight framebuffer readback (GfxDevice::requestReadback). */+enum class ReadbackHandle : u32 { Invalid = 0 };++/** @brief State of an in-flight readback. GL completes at request time (first poll+ * reports Ready); WebGPU resolves when its staging-buffer map lands. */+enum class GfxReadbackStatus : u8 {+ Pending = 0,+ Ready = 1,+ Failed = 2,+};// =============================================================================// Texture Samplingdiff --git a/src/esengine/renderer/RenderFrame.cpp b/src/esengine/renderer/RenderFrame.cppindex 0f558949e..a2e3de106 100644--- a/src/esengine/renderer/RenderFrame.cpp+++ b/src/esengine/renderer/RenderFrame.cpp@@ -396,11 +396,15 @@ void RenderFrame::replayToDrawCall(i32 stopAtDrawCall) {frame_capture_.clearReplayMode();- u32 pixelCount = width_ * height_ * 4;- snapshot_pixels_.resize(pixelCount);- device_.readPixels(0, 0, width_, height_, GfxPixelFormat::RGBA8, snapshot_pixels_.data());-rt->unbind();++ // Async readback seam: the pass is closed first (WebGPU records the copy+ // outside a pass); pollSnapshotReadback() lands the pixels.+ if (snapshot_readback_ != ReadbackHandle::Invalid) device_.discardReadback(snapshot_readback_);+ snapshot_w_ = width_;+ snapshot_h_ = height_;+ snapshot_pixels_.clear();+ snapshot_readback_ = device_.requestReadback(rt->getFramebuffer(), width_, height_);}void RenderFrame::renderToTarget(ecs::Registry& registry, const glm::mat4& viewProjection, u32 w, u32 h) {@@ -440,13 +444,46 @@ void RenderFrame::renderToTarget(ecs::Registry& registry, const glm::mat4& viewPdraw_list_.execute(device_, pool_, context_.materials(), &frame_capture_);frame_capture_.endCapture();+ rt->unbind();+ device_.invalidatePipelineCache();++ // Async readback seam (same shape as the replay snapshot above).+ if (preview_readback_ != ReadbackHandle::Invalid) device_.discardReadback(preview_readback_);preview_w_ = w;preview_h_ = h;- preview_pixels_.resize(static_cast<usize>(w) * h * 4);- device_.readPixels(0, 0, w, h, GfxPixelFormat::RGBA8, preview_pixels_.data());+ preview_pixels_.clear();+ preview_readback_ = device_.requestReadback(rt->getFramebuffer(), w, h);+}- rt->unbind();- device_.invalidatePipelineCache();+i32 RenderFrame::pollSnapshotReadback() {+ return pollReadback(snapshot_readback_, snapshot_pixels_, snapshot_w_, snapshot_h_);+}++i32 RenderFrame::pollPreviewReadback() {+ return pollReadback(preview_readback_, preview_pixels_, preview_w_, preview_h_);+}++i32 RenderFrame::pollReadback(ReadbackHandle& handle, std::vector<u8>& pixels, u32 w, u32 h) {+ if (handle == ReadbackHandle::Invalid) {+ // No readback in flight: the last landed pixels (if any) stay available.+ return pixels.empty() ? 2 : 1;+ }+ switch (device_.pollReadback(handle)) {+ case GfxReadbackStatus::Pending:+ return 0;+ case GfxReadbackStatus::Ready: {+ pixels.resize(static_cast<usize>(w) * h * 4);+ const bool ok = device_.takeReadback(handle, pixels.data(), pixels.size());+ handle = ReadbackHandle::Invalid;+ if (!ok) pixels.clear();+ return ok ? 1 : 2;+ }+ case GfxReadbackStatus::Failed:+ default:+ handle = ReadbackHandle::Invalid;+ pixels.clear();+ return 2;+ }}void RenderFrame::setEntityClipRect(u32 entity, i32 x, i32 y, i32 w, i32 h) {diff --git a/src/esengine/renderer/RenderFrame.hpp b/src/esengine/renderer/RenderFrame.hppindex 1798151b9..dadfd4c5f 100644--- a/src/esengine/renderer/RenderFrame.hpp+++ b/src/esengine/renderer/RenderFrame.hpp@@ -159,8 +159,17 @@ public:void replayToDrawCall(i32 stopAtDrawCall);const u8* getSnapshotPixels() const { return snapshot_pixels_.data(); }u32 getSnapshotSize() const { return static_cast<u32>(snapshot_pixels_.size()); }- u32 getSnapshotWidth() const { return width_; }- u32 getSnapshotHeight() const { return height_; }+ u32 getSnapshotWidth() const { return snapshot_w_; }+ u32 getSnapshotHeight() const { return snapshot_h_; }++ /**+ * Lands the replay snapshot's async readback: 0 = still pending (poll again+ * after yielding to the event loop), 1 = pixels are in the snapshot buffer+ * (getSnapshot* serve them), 2 = no readback in flight / it failed.+ * GL completes at request time, so the first poll reports 1 — callers use+ * one polling loop for both backends.+ */+ i32 pollSnapshotReadback();/*** Render @p registry once to an offscreen @p w×@p h target with @p viewProjection and read@@ -174,6 +183,9 @@ public:u32 getPreviewWidth() const { return preview_w_; }u32 getPreviewHeight() const { return preview_h_; }+ /** Lands the preview's async readback; same 0/1/2 contract as pollSnapshotReadback(). */+ i32 pollPreviewReadback();+void addPlugin(std::unique_ptr<RenderTypePlugin> plugin);void collectAll(ecs::Registry& registry, u32 skipFlags = 0);@@ -202,14 +214,22 @@ private:RenderTargetManager::Handle current_target_ = 0;RenderStage current_stage_ = RenderStage::Transparent;+ // Polls + lands one async readback: takes into @p pixels when Ready and+ // resets @p handle. Returns the 0/1/2 contract of the public poll methods.+ i32 pollReadback(ReadbackHandle& handle, std::vector<u8>& pixels, u32 w, u32 h);+Stats stats_;GpuTimer gpu_timer_;GpuTimer gpu_timer_pp_;FrameCapture frame_capture_;std::vector<u8> snapshot_pixels_;RenderTargetManager::Handle replay_rt_ = 0;+ ReadbackHandle snapshot_readback_ = ReadbackHandle::Invalid;+ u32 snapshot_w_ = 0;+ u32 snapshot_h_ = 0;std::vector<u8> preview_pixels_;RenderTargetManager::Handle preview_rt_ = 0;+ ReadbackHandle preview_readback_ = ReadbackHandle::Invalid;u32 preview_w_ = 0;u32 preview_h_ = 0;bool in_frame_ = false;diff --git a/src/esengine/renderer/webgpu/WebGPUDevice.cpp b/src/esengine/renderer/webgpu/WebGPUDevice.cppindex 76a0ba2d3..090d2e49a 100644--- a/src/esengine/renderer/webgpu/WebGPUDevice.cpp+++ b/src/esengine/renderer/webgpu/WebGPUDevice.cpp@@ -100,6 +100,9 @@ void WebGPUDevice::shutdown() {dummy_ubo_ = BufferHandle{}; // the WGPUBuffer/WGPUTexture went with the maps abovedummy_texture_ = 0;framebuffers_.clear();+ // Erase before release: aborting a pending map fires the callback, which must+ // miss the lookup rather than see a half-dead record.+ while (!readbacks_.empty()) releaseReadback(readbacks_.begin()->first);for (auto& [key, sampler] : samplers_) {if (sampler) wgpuSamplerRelease(sampler);}@@ -369,11 +372,12 @@ TextureHandle WebGPUDevice::createTexture(const TextureDesc& desc, const void* ptd.mipLevelCount = 1;td.sampleCount = 1;// Depth-stencil textures are attachment-only: writeTexture cannot fill them- // and the engine never samples its depth attachments.+ // and the engine never samples its depth attachments. Color textures carry+ // CopySrc so an offscreen target can serve the async readback seam.td.usage = isDepthFormat(td.format)? WGPUTextureUsage_RenderAttachment: (WGPUTextureUsage_TextureBinding | WGPUTextureUsage_CopyDst |- WGPUTextureUsage_RenderAttachment);+ WGPUTextureUsage_CopySrc | WGPUTextureUsage_RenderAttachment);WGPUTexture texture = wgpuDeviceCreateTexture(device_, &td);if (!texture) {@@ -1189,7 +1193,123 @@ void WebGPUDevice::endRenderPass() {if (frame_texture_) { wgpuTextureRelease(frame_texture_); frame_texture_ = nullptr; }}-void WebGPUDevice::readPixels(i32, i32, u32, u32, GfxPixelFormat, void*) { stubOnce("readPixels"); }+// =============================================================================+// Readback (async seam: texture → staging copy, resolved when the map lands)+// =============================================================================++void WebGPUDevice::onReadbackMapped(WGPUMapAsyncStatus status, WGPUStringView /*message*/,+ void* userdata1, void* userdata2) {+ auto* self = static_cast<WebGPUDevice*>(userdata1);+ const u32 id = static_cast<u32>(reinterpret_cast<uintptr_t>(userdata2));+ auto it = self->readbacks_.find(id);+ if (it == self->readbacks_.end()) return; // taken or discarded while in flight+ it->second.status = (status == WGPUMapAsyncStatus_Success) ? GfxReadbackStatus::Ready+ : GfxReadbackStatus::Failed;+}++void WebGPUDevice::releaseReadback(u32 id) {+ auto it = readbacks_.find(id);+ if (it == readbacks_.end()) return;+ WGPUBuffer buffer = it->second.buffer;+ // Erase first: releasing a buffer with a pending map fires the callback with+ // an abort status, which must miss the lookup.+ readbacks_.erase(it);+ if (buffer) wgpuBufferRelease(buffer);+}++ReadbackHandle WebGPUDevice::requestReadback(FramebufferHandle target, u32 w, u32 h) {+ if (!device_ || w == 0 || h == 0) return ReadbackHandle::Invalid;+ if (inPass()) {+ ES_LOG_ERROR("WebGPUDevice::requestReadback: must be called outside a render pass");+ return ReadbackHandle::Invalid;+ }+ if (target == FramebufferHandle::Default) {+ // The surface texture is released at endRenderPass and carries no CopySrc;+ // page-level capture covers the presented frame instead.+ stubOnce("requestReadback(default framebuffer)");+ return ReadbackHandle::Invalid;+ }+ auto fit = framebuffers_.find(static_cast<u32>(target));+ if (fit == framebuffers_.end()) return ReadbackHandle::Invalid;+ auto tit = textures_.find(fit->second.color0);+ if (tit == textures_.end() || !tit->second.texture) return ReadbackHandle::Invalid;++ // copyTextureToBuffer requires a 256-byte row alignment; rows are compacted+ // (and flipped to the bottom-up contract) in takeReadback.+ const u32 padded = (w * 4u + 255u) & ~255u;+ WGPUBufferDescriptor bd{};+ bd.usage = WGPUBufferUsage_CopyDst | WGPUBufferUsage_MapRead;+ bd.size = static_cast<u64>(padded) * h;+ WGPUBuffer buffer = wgpuDeviceCreateBuffer(device_, &bd);+ if (!buffer) return ReadbackHandle::Invalid;++ WGPUCommandEncoder encoder = wgpuDeviceCreateCommandEncoder(device_, nullptr);+ WGPUTexelCopyTextureInfo src = WGPU_TEXEL_COPY_TEXTURE_INFO_INIT;+ src.texture = tit->second.texture;+ WGPUTexelCopyBufferInfo dst = WGPU_TEXEL_COPY_BUFFER_INFO_INIT;+ dst.buffer = buffer;+ dst.layout.offset = 0;+ dst.layout.bytesPerRow = padded;+ dst.layout.rowsPerImage = h;+ WGPUExtent3D size{w, h, 1};+ wgpuCommandEncoderCopyTextureToBuffer(encoder, &src, &dst, &size);+ WGPUCommandBuffer commands = wgpuCommandEncoderFinish(encoder, nullptr);+ wgpuCommandEncoderRelease(encoder);+ wgpuQueueSubmit(queue_, 1, &commands);+ wgpuCommandBufferRelease(commands);++ const u32 id = next_readback_id_++;+ readbacks_[id] = ReadbackRec{buffer, w, h, padded, GfxReadbackStatus::Pending};++ WGPUBufferMapCallbackInfo cb = WGPU_BUFFER_MAP_CALLBACK_INFO_INIT;+ cb.mode = WGPUCallbackMode_AllowSpontaneous;+ cb.callback = &WebGPUDevice::onReadbackMapped;+ cb.userdata1 = this;+ cb.userdata2 = reinterpret_cast<void*>(static_cast<uintptr_t>(id));+ wgpuBufferMapAsync(buffer, WGPUMapMode_Read, 0, bd.size, cb);+ return static_cast<ReadbackHandle>(id);+}++GfxReadbackStatus WebGPUDevice::pollReadback(ReadbackHandle handle) {+ // AllowSpontaneous callbacks fire from the browser's event loop on their own;+ // the pump is defensive (and required if the callback mode ever tightens).+ if (instance_) wgpuInstanceProcessEvents(instance_);+ auto it = readbacks_.find(static_cast<u32>(handle));+ if (it == readbacks_.end()) return GfxReadbackStatus::Failed;+ if (it->second.status == GfxReadbackStatus::Failed) {+ releaseReadback(static_cast<u32>(handle));+ return GfxReadbackStatus::Failed;+ }+ return it->second.status;+}++bool WebGPUDevice::takeReadback(ReadbackHandle handle, void* dest, usize destSize) {+ auto it = readbacks_.find(static_cast<u32>(handle));+ if (it == readbacks_.end() || it->second.status != GfxReadbackStatus::Ready) return false;+ ReadbackRec& rec = it->second;+ const usize tight = static_cast<usize>(rec.width) * rec.height * 4;+ if (destSize < tight) return false;+ const auto* mapped = static_cast<const u8*>(+ wgpuBufferGetConstMappedRange(rec.buffer, 0, static_cast<u64>(rec.paddedBytesPerRow) * rec.height));+ if (!mapped) {+ releaseReadback(static_cast<u32>(handle));+ return false;+ }+ // The copy lands top-down; the contract (GL readPixels) is bottom-up rows.+ auto* out = static_cast<u8*>(dest);+ const u32 rowBytes = rec.width * 4u;+ for (u32 row = 0; row < rec.height; ++row) {+ std::memcpy(out + static_cast<usize>(rec.height - 1 - row) * rowBytes,+ mapped + static_cast<usize>(row) * rec.paddedBytesPerRow, rowBytes);+ }+ wgpuBufferUnmap(rec.buffer);+ releaseReadback(static_cast<u32>(handle));+ return true;+}++void WebGPUDevice::discardReadback(ReadbackHandle handle) {+ releaseReadback(static_cast<u32>(handle));+}// =============================================================================// Timing / queries / debugdiff --git a/src/esengine/renderer/webgpu/WebGPUDevice.hpp b/src/esengine/renderer/webgpu/WebGPUDevice.hppindex 1f3e0e7a1..0b2b84c08 100644--- a/src/esengine/renderer/webgpu/WebGPUDevice.hpp+++ b/src/esengine/renderer/webgpu/WebGPUDevice.hpp@@ -123,7 +123,10 @@ public:void endRenderPass() override;void resizeBackbuffer(u32 width, u32 height) override;- void readPixels(i32 x, i32 y, u32 w, u32 h, GfxPixelFormat format, void* data) override;+ ReadbackHandle requestReadback(FramebufferHandle target, u32 w, u32 h) override;+ GfxReadbackStatus pollReadback(ReadbackHandle handle) override;+ bool takeReadback(ReadbackHandle handle, void* dest, usize destSize) override;+ void discardReadback(ReadbackHandle handle) override;u32 createTimerQuery() override;void beginTimerQuery(u32 query) override;@@ -189,6 +192,13 @@ private:u32 color0 = 0; ///< TextureHandle id of the color attachment.u32 depthStencil = 0; ///< TextureHandle id (0 = none).};+ struct ReadbackRec {+ WGPUBuffer buffer = nullptr; ///< CopyDst|MapRead staging buffer.+ u32 width = 0;+ u32 height = 0;+ u32 paddedBytesPerRow = 0; ///< Row stride in the buffer (256-aligned).+ GfxReadbackStatus status = GfxReadbackStatus::Pending;+ };/** @brief Logs a not-yet-implemented path once per entry point. */void stubOnce(const char* what);@@ -255,6 +265,17 @@ private:std::unordered_map<u32, FramebufferRec> framebuffers_;u32 next_framebuffer_id_ = 1;+ // In-flight readbacks: staging buffers whose mapAsync callback flips status.+ std::unordered_map<u32, ReadbackRec> readbacks_;+ u32 next_readback_id_ = 1;++ /** @brief mapAsync completion: flips the readback's status by id (userdata2).+ * A discarded/taken readback simply misses the lookup and no-ops. */+ static void onReadbackMapped(WGPUMapAsyncStatus status, WGPUStringView message,+ void* userdata1, void* userdata2);+ /** @brief Erases + releases a readback record (aborts a still-pending map). */+ void releaseReadback(u32 id);+// Internal clear family (region-scoped clears + mid-pass clearStencil).// Explicit layout so ONE bind group serves every write-mask variant.std::unordered_map<u32, WGPURenderPipeline> clear_pipelines_;diff --git a/tests/renderer/MockGfxDevice.hpp b/tests/renderer/MockGfxDevice.hppindex 64b6895e5..9c67e92f2 100644--- a/tests/renderer/MockGfxDevice.hpp+++ b/tests/renderer/MockGfxDevice.hpp@@ -7,6 +7,7 @@#include "esengine/renderer/GfxDevice.hpp"+#include <cstring>#include <vector>namespace esengine {@@ -44,12 +45,20 @@ struct MockGfxDevice final : GfxDevice {int setPipelineCalls = 0;int drawElementsCalls = 0;int drawElementsInstancedCalls = 0;+ int requestReadbackCalls = 0;+ int takeReadbackCalls = 0;+ int discardReadbackCalls = 0;u32 nextTextureId = 100;u32 nextBufferId = 200;u32 nextFramebufferId = 500;u32 nextVertexLayoutId = 800;u32 nextPipelineId = 0;+ u32 nextReadbackId = 900;++ FramebufferHandle lastReadbackTarget = FramebufferHandle::Default;+ u32 lastReadbackW = 0;+ u32 lastReadbackH = 0;bool createTextureFails = false; // toggle to exercise the OOM / lost-context path (-> Invalid)bool compressedSupported = true; // toggle to exercise the RGBA8 fallback path@@ -194,7 +203,22 @@ struct MockGfxDevice final : GfxDevice {void beginRenderPass(const RenderPassDesc& desc) override { ++beginRenderPassCalls; lastPassDesc = desc; }void endRenderPass() override { ++endRenderPassCalls; }- void readPixels(i32, i32, u32, u32, GfxPixelFormat, void*) override {}+ // Async readback seam: every request is immediately Ready (the GL shape);+ // takeReadback fills a fixed pattern so callers can assert data flow.+ ReadbackHandle requestReadback(FramebufferHandle target, u32 w, u32 h) override {+ ++requestReadbackCalls;+ lastReadbackTarget = target;+ lastReadbackW = w;+ lastReadbackH = h;+ return static_cast<ReadbackHandle>(nextReadbackId++);+ }+ GfxReadbackStatus pollReadback(ReadbackHandle) override { return GfxReadbackStatus::Ready; }+ bool takeReadback(ReadbackHandle, void* dest, usize destSize) override {+ ++takeReadbackCalls;+ std::memset(dest, 0x42, destSize);+ return true;+ }+ void discardReadback(ReadbackHandle) override { ++discardReadbackCalls; }u32 createTimerQuery() override { return 0; } // report "no GPU timing" like a bare backendvoid beginTimerQuery(u32) override {}diff --git a/tests/renderer/test_webgpu_device.cpp b/tests/renderer/test_webgpu_device.cppindex e0ac3e326..42b638783 100644--- a/tests/renderer/test_webgpu_device.cpp+++ b/tests/renderer/test_webgpu_device.cpp@@ -212,3 +212,18 @@ TEST_CASE("null-device skeleton: language gate + graceful degradation + bookkeepCHECK(device.getUniformBlockIndex(ShaderHandle{1}, "FrameConstants") == GFX_INVALID_UNIFORM_BLOCK);CHECK(device.getString(GfxStringName::ShadingLanguageVersion) == "WGSL");}++TEST_CASE("null-device readback: requests degrade to Invalid, polls report Failed") {+ WebGPUDevice device;++ // No device — a request cannot be issued.+ CHECK(device.requestReadback(FramebufferHandle{7}, 4, 4) == ReadbackHandle::Invalid);+ // Zero-sized requests are rejected regardless of device state.+ CHECK(device.requestReadback(FramebufferHandle{7}, 0, 4) == ReadbackHandle::Invalid);++ // Unknown handles poll as Failed and take as false; discard is a safe no-op.+ CHECK(device.pollReadback(ReadbackHandle{42}) == GfxReadbackStatus::Failed);+ u8 pixels[4] = {};+ CHECK(!device.takeReadback(ReadbackHandle{42}, pixels, sizeof(pixels)));+ device.discardReadback(ReadbackHandle{42});+}