Skip to content

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

feat(render): clear becomes a pass load-op — the clear family exits the public RHI

yhhb288252bd548
diff --git a/build-tools/utils/emscripten.js b/build-tools/utils/emscripten.js
index c4b986aa1..fb70df864 100644
--- a/build-tools/utils/emscripten.js
+++ b/build-tools/utils/emscripten.js
@@ -242,5 +242,9 @@ export function runCommand(command, args, options = {}) {
}
export function getCpuCount() {
- return os.cpus().length;
+ // ESTELLA_BUILD_JOBS overrides; otherwise leave two cores free — a full-core
+ // emcc + LTO link saturates CPU and RAM and can freeze the machine outright.
+ const override = Number(process.env.ESTELLA_BUILD_JOBS);
+ if (Number.isFinite(override) && override >= 1) return Math.floor(override);
+ return Math.max(1, os.cpus().length - 2);
}
diff --git a/desktop/scripts/headless-verify.mjs b/desktop/scripts/headless-verify.mjs
index 00f495e61..7dec284a9 100644
--- a/desktop/scripts/headless-verify.mjs
+++ b/desktop/scripts/headless-verify.mjs
@@ -20,10 +20,18 @@
*/
import { app, BrowserWindow } from 'electron';
import http from 'node:http';
+import os from 'node:os';
import { readFile, writeFile } from 'node:fs/promises';
import path from 'node:path';
import { fileURLToPath } from 'node:url';
+// SwiftShader rasterizes on the CPU; run the whole electron tree below normal
+// priority (child processes inherit the class) so a verify never starves the
+// machine. Must happen before the renderer process spawns.
+try {
+ os.setPriority(os.constants.priority.PRIORITY_BELOW_NORMAL);
+} catch { /* not fatal — some sandboxes forbid it */ }
+
const DIST = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..', 'dist');
const SCENE = process.env.ESTELLA_VERIFY_SCENE ?? '/scenes/sprite-rendering.esscene';
diff --git a/docs/REARCHITECTURE.md b/docs/REARCHITECTURE.md
index be3795795..bbf269ccd 100644
--- a/docs/REARCHITECTURE.md
+++ b/docs/REARCHITECTURE.md
@@ -176,6 +176,15 @@ RC5"渲染唯一路径"的收官:所有 Renderer 只**生成命令**,Sort/Me
- 验证:新增 `tests/renderer/test_batch_builder.cpp`(8 用例 43 断言:各流 baseVertex 步长、纹理槽规则、实例化命令组装、多纹理合并 + texIndex 重写、跨流不合并、clip 盖章、execute 分发);六套 MockGfxDevice harness、web 构建、11 个 headless 像素场景(sprite / parallax-shape / text-sdf / 粒子×2 / tilemap×2 / ui-mask / lit×2 / postprocess)全 PASS;双 boundary guard 绿。
- **承诺实测 — Mesh2D 场景级 renderer(2026-07-07 第二批)**:`RenderType::Mesh` 从"仅统计枚举"变成真渲染类型。`Mesh2D` 组件(EHT 注解字段 + **未注解的变长几何 payload 置尾**——变长数据无固定 ABI 偏移,天然不进指针布局/断言);几何经唯一入口 `mesh2d_setGeometry` 上传(索引越界整体拒绝 + AABB 计算);`MeshPlugin` 全部内容 = 共享前奏 + SpritePlugin 同款材质/lit 解析 + CPU 仿射变换 + `appendIndexedBatch`——**零底层改动**,网格自动获得排序/裁剪/clip/多纹理合并/Lit2D。SDK:`Mesh2DAPI`(withScratch 批量上传)+ 场景 out-of-band codec(`geometry` 字段随 .esscene 声明式携带,particle 渐变同模式)。刻意不做:GPU 驻留网格(2D 网格顶点量小,CPU 流式与 sprite/tilemap 同模型;大网格属未来 3D 议题)。验证:mesh2d headless 场景(双三角逐顶点色,3 像素断言)一次过 + 回归 5 场景 + SDK/desktop 双侧 tsc + 全套测试 + 24 examples + 双 guard 全绿。
+### 渲染 clear → deferred load-op(WebGPU 前两片之①)— ✅ 已落地(2026-07-07)
+TS 驱动的主 pass clear 退出边界,`clear` 家族退出公共 RHI:
+- **RenderPassDesc 携带全部 load-op 值**:clear 颜色、stencil 值、可选区域(`clearW==0` = 整目标;GL = scissored clear,WebGPU 后端整目标映射真 load-op、区域用首 pass load-op 或 clear-quad 仿真)。`beginRenderPass` 自含 scissor 状态(scoped 用自己的矩形,非 scoped 强制关——真 load-op 覆盖整个附件,不被上一帧残留 scissor 否决)。
+- **clear/setClearColor/setClearStencil 降为 GLDevice 私有**;唯一例外是新的窄接口 `GfxDevice::clearStencil(value)`——mask pass 的**中帧** stencil 重置(不能重启 pass:场景可能正渲进后处理捕获;WebGPU 仿真 = stencil-write quad)。
+- **`renderer_begin` 携带 clear**(flags/rgba/区域),`renderer_clearBuffers`/`renderer_setScissor`/`renderer_clearStencil`(零调用方)三绑定退役;TS `renderPipeline` 删除 setScissor+clearBuffers 舞蹈,Canvas 背景色经 `CameraRenderParams.clearColor` 直达 pass——顺带根治 **sticky 颜色 bug**(`renderer_setClearColor` 只写 ctx state,相机路径的背景色从未到过设备)。
+- **根治了第二个双实例病灶**:TS `postprocess_*` 绑定用 ctx 服务里懒创建的 `PostProcessPipeline`,而 `RenderFrame::init` 自建私有实例——两份状态各自漂移(正是 begin 改造后主 pass 目标判断失灵、后处理全黑的根因)。修复:EstellaContext 把 RenderFrame 的实例以借用方式注册为服务(`registerService`),单实例、单一状态归属。
+- **方法论教训(已入记忆)**:排查期间多次实验跑在陈旧 wasm 上导致结论互相矛盾;现在的协议是每轮 bisect 在源里嵌标记字符串、grep 部署产物 + 比对双份 md5 后才采信结果。
+- 验证(全部本地、BelowNormal):13 个 headless 场景全 PASS(含 postprocess-effects/lut-grade 两个后处理场景、mesh2d、ui-mask、lit×2);6 套 MockGfxDevice harness、SDK 241 测试文件(renderer/renderPipeline 测试更新为 load-op 契约)、desktop 63 文件、双侧 tsc、24 examples 全绿。**WebGPU 前仅剩一片**:GLSL-only `createProgram` → WGSL 通路。
+
### CI 常绿门禁(push-gated invariants)— ✅ 已落地(2026-07-07)
此前 `build.yml` 仅 `workflow_dispatch`——boundary guards、全组件 ABI `static_assert`、各测试套件全是"约定"而非"机制"。现在**每次 push master 自动跑**:① web/playable/wechat 构建(编译期即验证生成断言 + ABI 哈希)+ 全部 15 个 C++ doctest harness(node 下执行);② 双 boundary guard + SDK tsc/构建/vitest + examples 检查 + desktop tsc/vitest(后两者此前完全不在 CI);③ headless 像素验证(sprite/mesh2d/parallax-shape/tilemap-flip/ui-mask,electron + xvfb + SwiftShader,需 `ELECTRON_DISABLE_SANDBOX`)。落地即抓到并修复三处腐化:`test_registry.cpp` 用已删除的 `View::sizeHint`、`test_sparse_set.cpp` 的局部常量撞 emscripten `PAGE_SIZE` 宏、以及一个**真回归**——单组件 `View::each` 活迭代(中途 emplace 会重访、swap-pop 移除会跳漏),多组件版早有快照契约,现已对齐。
diff --git a/sdk/src/camera/CameraPlugin.ts b/sdk/src/camera/CameraPlugin.ts
index 1e0169154..13c932e08 100644
--- a/sdk/src/camera/CameraPlugin.ts
+++ b/sdk/src/camera/CameraPlugin.ts
@@ -445,10 +445,10 @@ export function cameraPlugin(
const { width, height } = viewport();
if (width === 0 || height === 0) return;
const canvasEntity = module.registry_getCanvasEntity(cppRegistry);
+ let clearColor: { x: number; y: number; z: number; w: number } | undefined;
if (canvasEntity >= 0) {
const canvas = cppRegistry.getCanvas(canvasEntity);
- const bg = canvas.backgroundColor;
- Renderer.setClearColor(bg.x, bg.y, bg.z, bg.w);
+ clearColor = canvas.backgroundColor;
}
const elapsed = (platformNow() - startTime) / 1000;
@@ -474,6 +474,7 @@ export function cameraPlugin(
registry: { _cpp: cppRegistry },
viewProjection: IDENTITY,
width, height, elapsed,
+ clearColor,
});
} else {
pipeline.beginFrame(elapsed);
@@ -491,6 +492,7 @@ export function cameraPlugin(
clearFlags: cam.clearFlags,
elapsed,
cameraEntity: cam.entity,
+ clearColor,
});
}
pipeline.endScreenCapture();
diff --git a/sdk/src/renderPipeline.ts b/sdk/src/renderPipeline.ts
index fc4089e05..f970ebc24 100644
--- a/sdk/src/renderPipeline.ts
+++ b/sdk/src/renderPipeline.ts
@@ -31,6 +31,8 @@ export interface RenderParams {
width: number;
height: number;
elapsed: number;
+ /** Background for the pass's load-op clear (default opaque black). */
+ clearColor?: { x: number; y: number; z: number; w: number };
}
export interface CameraRenderParams {
@@ -40,6 +42,8 @@ export interface CameraRenderParams {
clearFlags: number;
elapsed: number;
cameraEntity?: Entity;
+ /** Background for the camera's load-op clear (default opaque black). */
+ clearColor?: { x: number; y: number; z: number; w: number };
}
export class RenderPipeline {
@@ -118,8 +122,7 @@ export class RenderPipeline {
Renderer.beginFrame(elapsed);
Renderer.setViewport(0, 0, width, height);
- Renderer.clearBuffers(3);
- Renderer.begin(viewProjection);
+ Renderer.begin(viewProjection, 0, /*clear color+depth*/ 3, params.clearColor);
this.submitScene(registry, viewProjection, { x: 0, y: 0, w: width, h: height }, elapsed);
Renderer.end();
}
@@ -138,11 +141,9 @@ export class RenderPipeline {
}
Renderer.setViewport(vp.x, vp.y, vp.w, vp.h);
- Renderer.setScissor(vp.x, vp.y, vp.w, vp.h, true);
- Renderer.clearBuffers(clearFlags);
- Renderer.setScissor(0, 0, 0, 0, false);
-
- Renderer.begin(viewProjection);
+ // The camera's clear rides begin as a region-scoped load-op — no scissor
+ // dance, no sticky clear state at the boundary.
+ Renderer.begin(viewProjection, 0, clearFlags, params.clearColor, vp);
this.submitScene(registry, viewProjection, vp, elapsed);
Renderer.end();
diff --git a/sdk/src/renderer.ts b/sdk/src/renderer.ts
index 9c7a1bc69..add16d87f 100644
--- a/sdk/src/renderer.ts
+++ b/sdk/src/renderer.ts
@@ -72,11 +72,20 @@ export const Renderer = {
}
},
- begin(viewProjection: Float32Array, target?: RenderTargetHandle): void {
+ /**
+ * Begins the pass. The clear rides begin as a load-op: `clearFlags` bit 0 =
+ * color, bit 1 = depth; `clearColor` is the color value; `clearRect` scopes the
+ * clear to a viewport region (omitted = the whole target). No flags = load.
+ */
+ begin(viewProjection: Float32Array, target?: RenderTargetHandle, clearFlags = 0,
+ clearColor?: { x: number; y: number; z: number; w: number },
+ clearRect?: { x: number; y: number; w: number; h: number }): void {
if (!module || !viewProjectionPtr) return;
try {
module.HEAPF32.set(viewProjection, viewProjectionPtr / 4);
- module.renderer_begin(viewProjectionPtr, target ?? 0);
+ module.renderer_begin(viewProjectionPtr, target ?? 0, clearFlags,
+ clearColor?.x ?? 0, clearColor?.y ?? 0, clearColor?.z ?? 0, clearColor?.w ?? 1,
+ clearRect?.x ?? 0, clearRect?.y ?? 0, clearRect?.w ?? 0, clearRect?.h ?? 0);
} catch (e) {
handleWasmError(e, 'Renderer.begin');
}
@@ -135,14 +144,6 @@ export const Renderer = {
module?.renderer_setViewport(x, y, w, h);
},
- setScissor(x: number, y: number, w: number, h: number, enable: boolean): void {
- module?.renderer_setScissor(x, y, w, h, enable);
- },
-
- clearBuffers(flags: number): void {
- module?.renderer_clearBuffers(flags);
- },
-
setTextureParams(textureId: number, minFilter: number, magFilter: number, wrapS: number, wrapT: number): void {
module?.renderer_setTextureParams?.(textureId, minFilter, magFilter, wrapS, wrapT);
},
diff --git a/sdk/src/wasm.ts b/sdk/src/wasm.ts
index fdb0a124d..d2289010c 100644
--- a/sdk/src/wasm.ts
+++ b/sdk/src/wasm.ts
@@ -272,7 +272,9 @@ export interface ESEngineModule {
renderer_resize(width: number, height: number): void;
renderer_beginFrame(elapsedSec: number): void;
renderer_updateTransforms(registry: CppRegistry): void;
- renderer_begin(matrixPtr: number, targetHandle: number): void;
+ renderer_begin(matrixPtr: number, targetHandle: number, clearFlags: number,
+ r: number, g: number, b: number, a: number,
+ clearX: number, clearY: number, clearW: number, clearH: number): void;
renderer_flush(): void;
renderer_end(): void;
renderer_submitSprites(registry: CppRegistry): void;
@@ -331,8 +333,6 @@ export interface ESEngineModule {
renderer_getTextureBytes?(): number;
renderer_setClearColor(r: number, g: number, b: number, a: number): void;
renderer_setViewport(x: number, y: number, w: number, h: number): void;
- renderer_setScissor(x: number, y: number, w: number, h: number, enable: boolean): void;
- renderer_clearBuffers(flags: number): void;
renderer_setTextureParams(textureId: number, minFilter: number, magFilter: number, wrapS: number, wrapT: number): void;
// Clip Rect API
@@ -341,7 +341,6 @@ export interface ESEngineModule {
renderer_clearAllClipRects(): void;
// Stencil API
- renderer_clearStencil(): void;
renderer_setEntityStencilMask(entity: number, refValue: number): void;
renderer_setEntityStencilTest(entity: number, refValue: number): void;
renderer_clearEntityStencilMask(entity: number): void;
diff --git a/sdk/tests/renderPipeline.test.ts b/sdk/tests/renderPipeline.test.ts
index 0071ee7e2..4cddd7118 100644
--- a/sdk/tests/renderPipeline.test.ts
+++ b/sdk/tests/renderPipeline.test.ts
@@ -18,8 +18,6 @@ vi.mock('../src/renderer', () => ({
setStage: vi.fn(),
setClearColor: vi.fn(),
setViewport: vi.fn(),
- setScissor: vi.fn(),
- clearBuffers: vi.fn(),
updateTransforms: vi.fn(),
beginFrame: vi.fn(),
},
@@ -87,7 +85,6 @@ describe('RenderPipeline', () => {
const callOrder: string[] = [];
(Renderer.resize as ReturnType<typeof vi.fn>).mockImplementation(() => callOrder.push('resize'));
(Renderer.setViewport as ReturnType<typeof vi.fn>).mockImplementation(() => callOrder.push('setViewport'));
- (Renderer.clearBuffers as ReturnType<typeof vi.fn>).mockImplementation(() => callOrder.push('clearBuffers'));
(Renderer.begin as ReturnType<typeof vi.fn>).mockImplementation(() => callOrder.push('begin'));
(Renderer.submitAll as ReturnType<typeof vi.fn>).mockImplementation(() => callOrder.push('submitAll'));
(Renderer.flush as ReturnType<typeof vi.fn>).mockImplementation(() => callOrder.push('flush'));
@@ -96,7 +93,7 @@ describe('RenderPipeline', () => {
pipeline.render({ registry, viewProjection, width: 800, height: 600, elapsed: 16 });
expect(callOrder).toEqual([
- 'resize', 'setViewport', 'clearBuffers', 'begin',
+ 'resize', 'setViewport', 'begin',
'submitAll', 'flush', 'end',
]);
});
@@ -106,8 +103,8 @@ describe('RenderPipeline', () => {
expect(Renderer.resize).toHaveBeenCalledWith(800, 600);
expect(Renderer.setViewport).toHaveBeenCalledWith(0, 0, 800, 600);
- expect(Renderer.clearBuffers).toHaveBeenCalledWith(3);
- expect(Renderer.begin).toHaveBeenCalledWith(viewProjection);
+ // The clear rides begin as a load-op: color+depth (3), default color.
+ expect(Renderer.begin).toHaveBeenCalledWith(viewProjection, 0, 3, undefined);
expect(Renderer.submitAll).toHaveBeenCalledWith(registry, 0, 0, 0, 800, 600);
});
});
@@ -237,18 +234,10 @@ describe('RenderPipeline', () => {
expect(Renderer.setViewport).toHaveBeenCalledWith(10, 20, 400, 300);
});
- it('sets scissor with viewportPixels then resets', () => {
- const callOrder: [string, ...any[]][] = [];
- (Renderer.setScissor as ReturnType<typeof vi.fn>).mockImplementation((...args: any[]) => {
- callOrder.push(['setScissor', ...args]);
- });
-
- pipeline.renderCamera({ registry, viewProjection, viewportPixels, clearFlags: 3, elapsed: 0 });
-
- expect(callOrder).toEqual([
- ['setScissor', 10, 20, 400, 300, true],
- ['setScissor', 0, 0, 0, 0, false],
- ]);
+ it('scopes the load-op clear to the camera viewport via begin', () => {
+ const bg = { x: 0.1, y: 0.2, z: 0.3, w: 1 };
+ pipeline.renderCamera({ registry, viewProjection, viewportPixels, clearFlags: 3, elapsed: 0, clearColor: bg });
+ expect(Renderer.begin).toHaveBeenCalledWith(viewProjection, 0, 3, bg, viewportPixels);
});
it('passes viewport params to submitAll', () => {
diff --git a/sdk/tests/renderer.test.ts b/sdk/tests/renderer.test.ts
index dd0896c3c..bd1497ef3 100644
--- a/sdk/tests/renderer.test.ts
+++ b/sdk/tests/renderer.test.ts
@@ -44,8 +44,6 @@ function createRendererMockModule() {
renderer_setClearColor: vi.fn(),
renderer_setViewport: vi.fn(),
- renderer_setScissor: vi.fn(),
- renderer_clearBuffers: vi.fn(),
renderer_setStage: vi.fn(),
renderer_getDrawCalls: vi.fn(() => 10),
@@ -194,17 +192,25 @@ describe('Renderer API', () => {
for (let i = 0; i < 16; i++) {
expect(mock.HEAPF32[offset + i]).toBe(i + 1);
}
- expect(mock.renderer_begin).toHaveBeenCalledWith(ptr, 0);
+ // No clear requested: flags 0, defaults, empty rect (load-op contract).
+ expect(mock.renderer_begin).toHaveBeenCalledWith(ptr, 0, 0, 0, 0, 0, 1, 0, 0, 0, 0);
});
it('should default target to 0 when not specified', () => {
Renderer.begin(new Float32Array(16));
- expect(mock.renderer_begin).toHaveBeenCalledWith(expect.any(Number), 0);
+ expect(mock.renderer_begin).toHaveBeenCalledWith(expect.any(Number), 0, 0, 0, 0, 0, 1, 0, 0, 0, 0);
});
it('should pass target when specified', () => {
Renderer.begin(new Float32Array(16), 5);
- expect(mock.renderer_begin).toHaveBeenCalledWith(expect.any(Number), 5);
+ expect(mock.renderer_begin).toHaveBeenCalledWith(expect.any(Number), 5, 0, 0, 0, 0, 1, 0, 0, 0, 0);
+ });
+
+ it('carries the clear as a load-op: flags, color, and region', () => {
+ Renderer.begin(new Float32Array(16), 0, 3,
+ { x: 0.2, y: 0.4, z: 0.6, w: 1 }, { x: 10, y: 20, w: 400, h: 300 });
+ expect(mock.renderer_begin).toHaveBeenCalledWith(
+ expect.any(Number), 0, 3, 0.2, 0.4, 0.6, 1, 10, 20, 400, 300);
});
});
@@ -335,16 +341,6 @@ describe('Renderer API', () => {
expect(mock.renderer_setViewport).toHaveBeenCalledWith(0, 0, 800, 600);
});
- it('should call renderer_setScissor', () => {
- Renderer.setScissor(10, 20, 100, 200, true);
- expect(mock.renderer_setScissor).toHaveBeenCalledWith(10, 20, 100, 200, true);
- });
-
- it('should call renderer_clearBuffers', () => {
- Renderer.clearBuffers(7);
- expect(mock.renderer_clearBuffers).toHaveBeenCalledWith(7);
- });
-
it('should call renderer_setStage', () => {
Renderer.setStage(RenderStage.Transparent);
expect(mock.renderer_setStage).toHaveBeenCalledWith(RenderStage.Transparent);
diff --git a/src/esengine/bindings/RendererBindings.cpp b/src/esengine/bindings/RendererBindings.cpp
index 1c9ab26ee..aec72c566 100644
--- a/src/esengine/bindings/RendererBindings.cpp
+++ b/src/esengine/bindings/RendererBindings.cpp
@@ -203,11 +203,7 @@ void renderFrame(ecs::Registry& registry, i32 viewportWidth, i32 viewportHeight)
ctx().state().viewport_height = static_cast<u32>(viewportHeight);
g_renderFrame->resize(g_viewportWidth, g_viewportHeight);
- auto* dev = g_device;
- dev->setViewport(0, 0, static_cast<u32>(viewportWidth), static_cast<u32>(viewportHeight));
- const auto& cc = ctx().state().clear_color;
- dev->setClearColor(cc.r, cc.g, cc.b, cc.a);
- dev->clear(true, true, false);
+ g_device->setViewport(0, 0, static_cast<u32>(viewportWidth), static_cast<u32>(viewportHeight));
glm::mat4 viewProjection = glm::mat4(1.0f);
@@ -240,7 +236,8 @@ void renderFrame(ecs::Registry& registry, i32 viewportWidth, i32 viewportHeight)
break;
}
- g_renderFrame->begin(viewProjection);
+ const auto& cc = ctx().state().clear_color;
+ g_renderFrame->begin(viewProjection, 0, RenderFrame::PassClear{true, true, cc});
g_renderFrame->collectAll(registry);
g_renderFrame->end();
}
@@ -266,16 +263,13 @@ void renderFrameWithMatrix(ecs::Registry& registry, i32 viewportWidth, i32 viewp
ctx().state().viewport_height = static_cast<u32>(viewportHeight);
g_renderFrame->resize(g_viewportWidth, g_viewportHeight);
- auto* dev = g_device;
- dev->setViewport(0, 0, static_cast<u32>(viewportWidth), static_cast<u32>(viewportHeight));
- const auto& cc = ctx().state().clear_color;
- dev->setClearColor(cc.r, cc.g, cc.b, cc.a);
- dev->clear(true, true, false);
+ g_device->setViewport(0, 0, static_cast<u32>(viewportWidth), static_cast<u32>(viewportHeight));
const f32* matrixData = reinterpret_cast<const f32*>(matrixPtr);
glm::mat4 viewProjection = glm::make_mat4(matrixData);
- g_renderFrame->begin(viewProjection);
+ const auto& cc = ctx().state().clear_color;
+ g_renderFrame->begin(viewProjection, 0, RenderFrame::PassClear{true, true, cc});
g_renderFrame->collectAll(registry);
g_renderFrame->end();
}
@@ -301,13 +295,21 @@ void renderer_beginFrame(f32 elapsedSec) {
}
}
-void renderer_begin(uintptr_t matrixPtr, u32 targetHandle) {
+// The pass's load-op rides begin: clearFlags bit0 = color, bit1 = depth; the color
+// value and an optional region (w == 0 = full target) come with it, so no sticky
+// clear state exists anywhere between TS and the device.
+void renderer_begin(uintptr_t matrixPtr, u32 targetHandle, i32 clearFlags,
+ f32 r, f32 g, f32 b, f32 a,
+ i32 clearX, i32 clearY, u32 clearW, u32 clearH) {
if (!g_renderFrame) return;
const f32* matrixData = reinterpret_cast<const f32*>(matrixPtr);
glm::mat4 viewProjection = glm::make_mat4(matrixData);
- g_renderFrame->begin(viewProjection, targetHandle);
+ g_renderFrame->begin(viewProjection, targetHandle,
+ RenderFrame::PassClear{(clearFlags & 1) != 0, (clearFlags & 2) != 0,
+ glm::vec4(r, g, b, a),
+ clearX, clearY, clearW, clearH});
}
void renderer_flush() {
@@ -521,24 +523,6 @@ void renderer_setViewport(i32 x, i32 y, i32 w, i32 h) {
g_device->setViewport(x, y, static_cast<u32>(w), static_cast<u32>(h));
}
-void renderer_setScissor(i32 x, i32 y, i32 w, i32 h, bool enable) {
- auto* dev = g_device;
- if (enable) {
- dev->setScissorTest(true);
- dev->setScissor(x, y, w, h);
- } else {
- dev->setScissorTest(false);
- }
-}
-
-void renderer_clearBuffers(i32 flags) {
- bool color = (flags & 1) != 0;
- bool depth = (flags & 2) != 0;
- if (color || depth) {
- g_device->clear(color, depth, false);
- }
-}
-
void renderer_diagnose() {
if (!g_initialized) {
ES_LOG_ERROR("[Diagnose] Renderer not initialized");
@@ -575,11 +559,6 @@ void renderer_clearAllClipRects() {
}
}
-void renderer_clearStencil() {
- g_device->setClearStencil(0);
- g_device->clear(false, false, true);
-}
-
void renderer_setEntityStencilMask(u32 entity, i32 refValue) {
if (g_renderFrame) {
g_renderFrame->setEntityStencilMask(entity, refValue);
diff --git a/src/esengine/bindings/RendererBindings.hpp b/src/esengine/bindings/RendererBindings.hpp
index 0e0552c17..12007397d 100644
--- a/src/esengine/bindings/RendererBindings.hpp
+++ b/src/esengine/bindings/RendererBindings.hpp
@@ -45,7 +45,9 @@ void renderFrameWithMatrix(ecs::Registry& registry, i32 viewportWidth, i32 viewp
void renderer_init(u32 width, u32 height);
void renderer_resize(u32 width, u32 height);
void renderer_beginFrame(f32 elapsedSec);
-void renderer_begin(uintptr_t matrixPtr, u32 targetHandle);
+void renderer_begin(uintptr_t matrixPtr, u32 targetHandle, i32 clearFlags,
+ f32 r, f32 g, f32 b, f32 a,
+ i32 clearX, i32 clearY, u32 clearW, u32 clearH);
void renderer_flush();
void renderer_end();
void renderer_submitSprites(ecs::Registry& registry);
@@ -121,14 +123,11 @@ f64 renderer_getTextureBytes();
void renderer_setDeltaTime(f32 dt);
void renderer_setClearColor(f32 r, f32 g, f32 b, f32 a);
void renderer_setViewport(i32 x, i32 y, i32 w, i32 h);
-void renderer_setScissor(i32 x, i32 y, i32 w, i32 h, bool enable);
-void renderer_clearBuffers(i32 flags);
void renderer_diagnose();
void renderer_setEntityClipRect(u32 entity, i32 x, i32 y, i32 w, i32 h);
void renderer_clearEntityClipRect(u32 entity);
void renderer_clearAllClipRects();
-void renderer_clearStencil();
void renderer_setEntityStencilMask(u32 entity, i32 refValue);
void renderer_setEntityStencilTest(u32 entity, i32 refValue);
void renderer_clearEntityStencilMask(u32 entity);
diff --git a/src/esengine/bindings/WebSDKEntry.cpp b/src/esengine/bindings/WebSDKEntry.cpp
index 6ce592b16..d6b709430 100644
--- a/src/esengine/bindings/WebSDKEntry.cpp
+++ b/src/esengine/bindings/WebSDKEntry.cpp
@@ -544,13 +544,10 @@ EMSCRIPTEN_BINDINGS(esengine_renderer) {
emscripten::function("renderer_setDeltaTime", &esengine::renderer_setDeltaTime);
emscripten::function("renderer_setClearColor", &esengine::renderer_setClearColor);
emscripten::function("renderer_setViewport", &esengine::renderer_setViewport);
- emscripten::function("renderer_setScissor", &esengine::renderer_setScissor);
- emscripten::function("renderer_clearBuffers", &esengine::renderer_clearBuffers);
emscripten::function("renderer_setEntityClipRect", &esengine::renderer_setEntityClipRect);
emscripten::function("renderer_clearEntityClipRect", &esengine::renderer_clearEntityClipRect);
emscripten::function("renderer_clearAllClipRects", &esengine::renderer_clearAllClipRects);
- emscripten::function("renderer_clearStencil", &esengine::renderer_clearStencil);
emscripten::function("renderer_setEntityStencilMask", &esengine::renderer_setEntityStencilMask);
emscripten::function("renderer_setEntityStencilTest", &esengine::renderer_setEntityStencilTest);
emscripten::function("renderer_clearEntityStencilMask", &esengine::renderer_clearEntityStencilMask);
diff --git a/src/esengine/core/EstellaContext.cpp b/src/esengine/core/EstellaContext.cpp
index 1d8bc0f7b..bfeff992c 100644
--- a/src/esengine/core/EstellaContext.cpp
+++ b/src/esengine/core/EstellaContext.cpp
@@ -158,12 +158,27 @@ void EstellaContext::initSubsystems() {
renderFrame->init(state_.viewport_width, state_.viewport_height);
services_.registerOwned<RenderFrame>(std::move(renderFrame));
+#ifdef ES_ENABLE_POSTPROCESS
+ // ONE PostProcessPipeline per App: the postprocess_* bindings and RenderFrame
+ // must consult the SAME instance. Registering RenderFrame's pipeline as the
+ // service (borrowed — RenderFrame owns it) stops the bindings from lazily
+ // creating a second one, whose captures RenderFrame::begin could not see.
+ if (auto* pp = services_.getService<RenderFrame>()->postProcess()) {
+ services_.registerService<PostProcessPipeline>(pp);
+ }
+#endif
+
state_.initialized = true;
- gfxDevicePtr->setClearColor(
- state_.clear_color.r, state_.clear_color.g,
- state_.clear_color.b, state_.clear_color.a);
- gfxDevicePtr->clear(true, true, false);
+ // First-frame clear as a proper pass load-op (values in the desc, no sticky state).
+ RenderPassDesc initPass{};
+ initPass.clearColor = true;
+ initPass.clearDepth = true;
+ initPass.clearColorValue[0] = state_.clear_color.r;
+ initPass.clearColorValue[1] = state_.clear_color.g;
+ initPass.clearColorValue[2] = state_.clear_color.b;
+ initPass.clearColorValue[3] = state_.clear_color.a;
+ gfxDevicePtr->beginRenderPass(initPass);
ES_LOG_INFO("EstellaContext initialized");
}
diff --git a/src/esengine/renderer/GLDevice.cpp b/src/esengine/renderer/GLDevice.cpp
index ab166d95c..a4cf546a0 100644
--- a/src/esengine/renderer/GLDevice.cpp
+++ b/src/esengine/renderer/GLDevice.cpp
@@ -916,9 +916,37 @@ void GLDevice::deleteFramebuffer(FramebufferHandle framebuffer) {
if (id != 0) glDeleteFramebuffers(1, &id);
}
+void GLDevice::clearStencil(i32 value) {
+ setClearStencil(value);
+ clear(false, false, true);
+}
+
void GLDevice::beginRenderPass(const RenderPassDesc& desc) {
glBindFramebuffer(GL_FRAMEBUFFER, static_cast<GLuint>(desc.target));
+ if (!desc.clearColor && !desc.clearDepth && !desc.clearStencil) return;
+
+ // Load-op values ride the pass — no sticky device clear state to drift.
+ if (desc.clearColor) {
+ setClearColor(desc.clearColorValue[0], desc.clearColorValue[1],
+ desc.clearColorValue[2], desc.clearColorValue[3]);
+ }
+ if (desc.clearStencil) setClearStencil(desc.clearStencilValue);
+
+ // Load-op clears are self-contained: a scoped clear rides its OWN scissor
+ // rect, an unscoped one forces the scissor OFF (a real load-op covers the
+ // whole attachment — it must not be vetoed by whatever scissor the previous
+ // frame's last draw left enabled). Scissor ends disabled either way; the
+ // next draw's command state re-applies its own.
+ const bool scoped = desc.clearW != 0;
+ if (scoped) {
+ setScissorTest(true);
+ setScissor(desc.clearX, desc.clearY,
+ static_cast<i32>(desc.clearW), static_cast<i32>(desc.clearH));
+ } else {
+ setScissorTest(false);
+ }
clear(desc.clearColor, desc.clearDepth, desc.clearStencil);
+ if (scoped) setScissorTest(false);
}
void GLDevice::endRenderPass() {
diff --git a/src/esengine/renderer/GLDevice.hpp b/src/esengine/renderer/GLDevice.hpp
index 8a0258f57..3dd00b9ae 100644
--- a/src/esengine/renderer/GLDevice.hpp
+++ b/src/esengine/renderer/GLDevice.hpp
@@ -40,9 +40,7 @@ public:
void shutdown() override;
void setViewport(i32 x, i32 y, u32 w, u32 h) override;
- void setClearColor(f32 r, f32 g, f32 b, f32 a) override;
- void setClearStencil(i32 value) override;
- void clear(bool color, bool depth, bool stencil) override;
+ void clearStencil(i32 value) override;
void setScissorTest(bool enabled) override;
void setScissor(i32 x, i32 y, i32 w, i32 h) override;
@@ -119,6 +117,12 @@ public:
i32 getInt(GfxIntParam name) override;
private:
+ // Clear machinery: backend-internal since RenderPassDesc became the only way
+ // to request clears (it carries the values; beginRenderPass applies them).
+ void setClearColor(f32 r, f32 g, f32 b, f32 a);
+ void setClearStencil(i32 value);
+ void clear(bool color, bool depth, bool stencil);
+
// The loose state setters a pipeline bundles (blend/depth/stencil/cull/masks):
// backend-internal since the pipeline became the only way to set them.
void setBlendEnabled(bool enabled);
diff --git a/src/esengine/renderer/GfxDevice.hpp b/src/esengine/renderer/GfxDevice.hpp
index 1a7ba9a07..2b8deb3fe 100644
--- a/src/esengine/renderer/GfxDevice.hpp
+++ b/src/esengine/renderer/GfxDevice.hpp
@@ -67,25 +67,23 @@ public:
/** @brief Sets the rendering viewport */
virtual void setViewport(i32 x, i32 y, u32 w, u32 h) = 0;
- /** @brief Sets the clear color */
- virtual void setClearColor(f32 r, f32 g, f32 b, f32 a) = 0;
-
- /** @brief Sets the value written to the stencil buffer by clear() */
- virtual void setClearStencil(i32 value) = 0;
-
- /**
- * @brief Clears attachments of the current pass target with load-op semantics.
- * @details Write masks left by the previous pipeline are forced open (and the
- * cached pipeline dropped); the scissor rectangle is honored. Prefer
- * the clears in RenderPassDesc — this exists for the SDK-driven
- * multi-camera flow and mid-pass stencil clears.
- */
- virtual void clear(bool color, bool depth, bool stencil) = 0;
+ // Clears are pass-scoped: RenderPassDesc carries the load-ops AND their values
+ // (color / stencil / optional region). There is no public clear entry point and
+ // no sticky clear state a pass could inherit by accident.
// =========================================================================
// Dynamic Per-Draw State (deliberately outside the pipeline; see PipelineState.hpp)
// =========================================================================
+ /**
+ * @brief Mid-pass stencil reset (the one clear that isn't a pass load-op).
+ * @details The mask pass wipes the stencil attachment of the CURRENT target
+ * before rebuilding mask refs — it must not restart the pass (the
+ * scene may be rendering into a post-process capture). GL clears the
+ * attachment; a WebGPU backend emulates with a stencil-write quad.
+ */
+ virtual void clearStencil(i32 value) = 0;
+
/** @brief Enables or disables scissor test */
virtual void setScissorTest(bool enabled) = 0;
diff --git a/src/esengine/renderer/GfxEnums.hpp b/src/esengine/renderer/GfxEnums.hpp
index bd3f0038d..d04a4f089 100644
--- a/src/esengine/renderer/GfxEnums.hpp
+++ b/src/esengine/renderer/GfxEnums.hpp
@@ -229,17 +229,24 @@ struct FramebufferDesc {
};
/**
- * @brief One render pass: a target plus which attachments to clear on entry.
- * @details Clears use the device's current clear color / clear stencil values
- * and ignore write masks a prior pipeline left restrictive (load-op
- * semantics) — but they do honor the current scissor rectangle, which
- * the TS-driven multi-camera flow relies on for per-camera clears.
+ * @brief One render pass: a target, which attachments to clear on entry, and the
+ * clear values — full load-op semantics, no sticky device clear state.
+ * @details Clears ignore write masks a prior pipeline left restrictive (the masks
+ * are forced open). An optional clear region scopes the clear to a
+ * viewport rectangle (clearW == 0 = full target): the multi-camera flow
+ * clears each camera's region on the shared default target. A WebGPU
+ * backend maps the full-target case to a real load-op and emulates the
+ * scoped case (first-pass load-op or a scissored clear-quad).
*/
struct RenderPassDesc {
FramebufferHandle target = FramebufferHandle::Default;
bool clearColor = false;
bool clearDepth = false;
bool clearStencil = false;
+ f32 clearColorValue[4] = {0.0f, 0.0f, 0.0f, 1.0f};
+ i32 clearStencilValue = 0;
+ i32 clearX = 0, clearY = 0; ///< Clear region origin (pixels).
+ u32 clearW = 0, clearH = 0; ///< Clear region size; 0 = the whole target.
};
// =============================================================================
diff --git a/src/esengine/renderer/PostProcessPipeline.cpp b/src/esengine/renderer/PostProcessPipeline.cpp
index c9e78b82a..3004ba08e 100644
--- a/src/esengine/renderer/PostProcessPipeline.cpp
+++ b/src/esengine/renderer/PostProcessPipeline.cpp
@@ -292,13 +292,23 @@ void PostProcessPipeline::applyPassPipeline(const Shader& shader) {
device_.setPipeline(device_.createPipeline(desc));
}
-void PostProcessPipeline::begin() {
+FramebufferHandle PostProcessPipeline::currentSceneFBO() const {
+ if (screenCaptureActive_ && screenFBOCreated_) return screenFBO_->handle();
+ if (inFrame_ && fboOriginalCreated_) return fboOriginal_->handle();
+ return FramebufferHandle::Default;
+}
+
+void PostProcessPipeline::begin(const f32* clearColor) {
if (!initialized_ || inFrame_ || bypass_) return;
ensureFBOs();
if (!fboOriginalCreated_) return;
- device_.beginRenderPass({fboOriginal_->handle(), /*clearColor=*/true, /*clearDepth=*/true});
+ RenderPassDesc pass{fboOriginal_->handle(), /*clearColor=*/true, /*clearDepth=*/true};
+ if (clearColor) {
+ for (int i = 0; i < 4; ++i) pass.clearColorValue[i] = clearColor[i];
+ }
+ device_.beginRenderPass(pass);
device_.setViewport(0, 0, width_, height_);
inFrame_ = true;
diff --git a/src/esengine/renderer/PostProcessPipeline.hpp b/src/esengine/renderer/PostProcessPipeline.hpp
index b59eb0e3a..72d23406f 100644
--- a/src/esengine/renderer/PostProcessPipeline.hpp
+++ b/src/esengine/renderer/PostProcessPipeline.hpp
@@ -132,8 +132,10 @@ public:
/**
* @brief Begins rendering to the pipeline
* @details Binds the input framebuffer. Render scene content after this.
+ * @p clearColor (RGBA) colors the capture's load-op clear — the
+ * camera background; null = opaque black.
*/
- void begin();
+ void begin(const f32* clearColor = nullptr);
/**
* @brief Ends and processes all passes
@@ -227,6 +229,12 @@ public:
*/
bool isScreenCaptureActive() const { return screenCaptureActive_; }
+ /** @brief The surface the scene is currently rendering into: the screen-capture
+ * FBO when the screen stack is live, the per-camera capture when
+ * in-frame, else the default target. The main-pass load-op clear must
+ * land HERE — rebinding the default target mid-capture breaks the stack. */
+ FramebufferHandle currentSceneFBO() const;
+
private:
PostProcessPass* findPass(const std::string& name);
void ensureFBOs();
diff --git a/src/esengine/renderer/RenderFrame.cpp b/src/esengine/renderer/RenderFrame.cpp
index dac8e323e..1ed27c75e 100644
--- a/src/esengine/renderer/RenderFrame.cpp
+++ b/src/esengine/renderer/RenderFrame.cpp
@@ -180,6 +180,11 @@ void RenderFrame::resize(u32 width, u32 height) {
}
void RenderFrame::begin(const glm::mat4& view_projection, RenderTargetManager::Handle target) {
+ begin(view_projection, target, PassClear{});
+}
+
+void RenderFrame::begin(const glm::mat4& view_projection, RenderTargetManager::Handle target,
+ const PassClear& clear) {
view_projection_ = view_projection;
frustum_.extractFromMatrix(view_projection);
current_target_ = target;
@@ -200,6 +205,21 @@ void RenderFrame::begin(const glm::mat4& view_projection, RenderTargetManager::H
bool usePostProcess = false;
#endif
+ // The pass's load-op clear, values carried in the desc (never sticky device
+ // state). Region-scoped when the caller renders one camera's viewport of a
+ // shared target.
+ RenderPassDesc pass{};
+ pass.clearColor = clear.color;
+ pass.clearDepth = clear.depth;
+ pass.clearColorValue[0] = clear.colorValue.r;
+ pass.clearColorValue[1] = clear.colorValue.g;
+ pass.clearColorValue[2] = clear.colorValue.b;
+ pass.clearColorValue[3] = clear.colorValue.a;
+ pass.clearX = clear.x;
+ pass.clearY = clear.y;
+ pass.clearW = clear.w;
+ pass.clearH = clear.h;
+
if (usePostProcess) {
#ifdef ES_ENABLE_POSTPROCESS
if (target != RenderTargetManager::INVALID_HANDLE) {
@@ -208,13 +228,30 @@ void RenderFrame::begin(const glm::mat4& view_projection, RenderTargetManager::H
post_process_->setOutputTarget(rt->getFramebuffer());
}
}
- post_process_->begin();
+ // Fresh begin: colors the capture's own load-op clear. When TS already
+ // began the capture (renderCamera drives pp.begin first) this no-ops...
+ post_process_->begin(pass.clearColorValue);
+ // ...so apply the camera's (possibly region-scoped) clear to the active
+ // capture surface explicitly.
+ if (pass.clearColor || pass.clearDepth) {
+ pass.target = post_process_->currentSceneFBO();
+ device_.beginRenderPass(pass);
+ }
#endif
} else if (target != RenderTargetManager::INVALID_HANDLE) {
auto* rt = target_manager_.get(target);
if (rt) {
- rt->bind();
+ pass.target = rt->getFramebuffer();
+ device_.beginRenderPass(pass);
}
+ } else {
+ // The scene may be rendering into the TS screen-capture FBO (screen post
+ // stack without a per-camera stack): the clear must land on that surface —
+ // blind-rebinding the default target here would break the capture.
+#ifdef ES_ENABLE_POSTPROCESS
+ if (post_process_) pass.target = post_process_->currentSceneFBO();
+#endif
+ device_.beginRenderPass(pass);
}
}
@@ -335,8 +372,9 @@ void RenderFrame::replayToDrawCall(i32 stopAtDrawCall) {
auto* rt = target_manager_.get(replay_rt_);
if (!rt) return;
- device_.setClearColor(0.0f, 0.0f, 0.0f, 0.0f);
- device_.beginRenderPass({rt->getFramebuffer(), /*clearColor=*/true});
+ RenderPassDesc replayPass{rt->getFramebuffer(), /*clearColor=*/true};
+ replayPass.clearColorValue[3] = 0.0f; // transparent black
+ device_.beginRenderPass(replayPass);
device_.setViewport(0, 0, width_, height_);
frame_capture_.setReplayMode(stopAtDrawCall + 1);
@@ -371,8 +409,9 @@ void RenderFrame::renderToTarget(ecs::Registry& registry, const glm::mat4& viewP
auto* rt = target_manager_.get(preview_rt_);
if (!rt) return;
- device_.setClearColor(0.0f, 0.0f, 0.0f, 0.0f);
- device_.beginRenderPass({rt->getFramebuffer(), /*clearColor=*/true});
+ RenderPassDesc previewPass{rt->getFramebuffer(), /*clearColor=*/true};
+ previewPass.clearColorValue[3] = 0.0f; // transparent black
+ device_.beginRenderPass(previewPass);
device_.setViewport(0, 0, w, h);
// A self-contained collect (begin()'s setup minus post-process) + execute (flush()'s body),
diff --git a/src/esengine/renderer/RenderFrame.hpp b/src/esengine/renderer/RenderFrame.hpp
index 23513f6c6..1798151b9 100644
--- a/src/esengine/renderer/RenderFrame.hpp
+++ b/src/esengine/renderer/RenderFrame.hpp
@@ -86,7 +86,20 @@ public:
void shutdown();
void resize(u32 width, u32 height);
+ /** @brief The frame's main-pass load-op: which attachments to clear, the color,
+ * and an optional region (w == 0 = full target — per-camera flows clear
+ * only their viewport on the shared default target). */
+ struct PassClear {
+ bool color = false;
+ bool depth = false;
+ glm::vec4 colorValue{0.0f, 0.0f, 0.0f, 1.0f};
+ i32 x = 0, y = 0;
+ u32 w = 0, h = 0;
+ };
+
void begin(const glm::mat4& view_projection, RenderTargetManager::Handle target = 0);
+ void begin(const glm::mat4& view_projection, RenderTargetManager::Handle target,
+ const PassClear& clear);
void flush();
void end();
diff --git a/src/esengine/renderer/RenderFrameMask.cpp b/src/esengine/renderer/RenderFrameMask.cpp
index 9d29f2483..aa6cfeb56 100644
--- a/src/esengine/renderer/RenderFrameMask.cpp
+++ b/src/esengine/renderer/RenderFrameMask.cpp
@@ -230,7 +230,7 @@ void RenderFrame::processMasks(ecs::Registry& registry, i32 vpX, i32 vpY, i32 vp
if (!stencilMasks.empty()) {
#ifdef ES_PLATFORM_WEB
- device_.clear(false, false, true);
+ device_.clearStencil(0);
#endif
std::vector<Entity> rootStencils;
diff --git a/tests/renderer/MockGfxDevice.hpp b/tests/renderer/MockGfxDevice.hpp
index 7e5ebd8f2..758ddf2af 100644
--- a/tests/renderer/MockGfxDevice.hpp
+++ b/tests/renderer/MockGfxDevice.hpp
@@ -80,9 +80,7 @@ struct MockGfxDevice final : GfxDevice {
void shutdown() override {}
void setViewport(i32, i32, u32, u32) override {}
- void setClearColor(f32, f32, f32, f32) override {}
- void setClearStencil(i32) override {}
- void clear(bool, bool, bool) override {}
+ void clearStencil(i32) override {}
void setScissorTest(bool) override {}
void setScissor(i32, i32, i32, i32) override {}