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(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.jsindex 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.mjsindex 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.mdindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.cppindex 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 viewpctx().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.hppindex 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 viewpvoid 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.cppindex 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.cppindex 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.cppindex 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.hppindex 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.hppindex 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.hppindex 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.cppindex 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.hppindex 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.cppindex 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::Hbool 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_POSTPROCESSif (target != RenderTargetManager::INVALID_HANDLE) {@@ -208,13 +228,30 @@ void RenderFrame::begin(const glm::mat4& view_projection, RenderTargetManager::Hpost_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& viewPauto* 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.hppindex 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.cppindex 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 vpif (!stencilMasks.empty()) {#ifdef ES_PLATFORM_WEB- device_.clear(false, false, true);+ device_.clearStencil(0);#endifstd::vector<Entity> rootStencils;diff --git a/tests/renderer/MockGfxDevice.hpp b/tests/renderer/MockGfxDevice.hppindex 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 {}