Skip to content

A fast 2D and 3D game engine — TypeScript SDK, C++/WebAssembly core, visual editor. Ship one project to web, desktop, WeChat MiniGames, playable ads, and native Android / iOS.

feat(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.esshader
index 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 end
diff --git a/desktop/scripts/headless-verify.mjs b/desktop/scripts/headless-verify.mjs
index 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.ts
index 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.ts
index 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.tsx
index 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.md
index 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.ts
index 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 Team
import 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.ts
index 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.ts
new file mode 100644
index 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.ts
index 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.ts
index 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.ts
index 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.cpp
index 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.hpp
index 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.cpp
index 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.cpp
index 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.hpp
index 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.hpp
index 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.hpp
index 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 Sampling
diff --git a/src/esengine/renderer/RenderFrame.cpp b/src/esengine/renderer/RenderFrame.cpp
index 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& viewP
draw_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.hpp
index 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.cpp
index 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 above
dummy_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* p
td.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 / debug
diff --git a/src/esengine/renderer/webgpu/WebGPUDevice.hpp b/src/esengine/renderer/webgpu/WebGPUDevice.hpp
index 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.hpp
index 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 backend
void beginTimerQuery(u32) override {}
diff --git a/tests/renderer/test_webgpu_device.cpp b/tests/renderer/test_webgpu_device.cpp
index 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 + bookkeep
CHECK(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});
+}