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.

docs: architecture reflects the typed-handle RHI, pipelines, and render passes

yhhfebcaa3493d2
diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md
index 63701b8d3..a585c42ab 100644
--- a/docs/ARCHITECTURE.md
+++ b/docs/ARCHITECTURE.md
@@ -103,9 +103,11 @@ filtered via the per-entity component mask. The SDK exposes this as
### Renderer (`renderer/`)
-WebGL2-based, compiled to WASM. There is **one rendering path** (RC5): the legacy
+WebGL2-based, compiled to WASM. There is **one rendering path**: the legacy
`Renderer` / `BatchRenderer2D` classes were removed. Everything goes through
-`RenderFrame`, and **all** GPU access goes through `GfxDevice`.
+`RenderFrame`, and **all** GPU access goes through `GfxDevice` — a
+backend-agnostic RHI shaped so a WebGPU (or native-API) backend can slot in
+beside the WebGL2 one without touching the renderer above it.
```
┌──────────────────────────────────────────────────────────────┐
@@ -117,18 +119,36 @@ WebGL2-based, compiled to WASM. There is **one rendering path** (RC5): the legac
│ ▼ │
│ DrawList (sort + coalesce; multi-texture batch; u32 index) │
│ ▼ │
-│ GfxDevice (the only GPU entry point) │
+│ GfxDevice (the render backend boundary / RHI) │
│ └── GLDevice : public GfxDevice (the one concrete impl) │
-│ Shader · Texture · Buffer/VAO · Framebuffer · CustomGeometry │
+│ Shader · Texture · Buffer · Framebuffer · CustomGeometry │
│ all take GfxDevice&; no raw gl* outside GLDevice (CI-guarded)│
└──────────────────────────────────────────────────────────────┘
```
Key facts:
-- **`GfxDevice`** (`GfxDevice.hpp:48`) is an abstract device that owns its
- pipeline state; `GLDevice` (`GLDevice.hpp:33`) is the single concrete backend.
- A CI guard rejects raw `gl*` calls outside `GLDevice.cpp` so the abstraction
- stays the only channel. A `MockGfxDevice` harness exercises it headlessly.
+- **`GfxDevice`** (`GfxDevice.hpp`) speaks in typed handles and descriptors,
+ not GL concepts: resources are created from `BufferDesc` / `TextureDesc` /
+ `FramebufferDesc` / `VertexLayoutDesc` and addressed as `BufferHandle` /
+ `TextureHandle` / `ShaderHandle` / `FramebufferHandle` /
+ `VertexLayoutHandle` (on GL a handle's value is the GL id — zero cost).
+ There is no bind-target buffer protocol (`updateBuffer` / `resizeBuffer`
+ act on the handle) and no VAO in the interface — the vertex layout is part
+ of `PipelineDesc`, buffers bind per draw via `setVertexBuffer(slot, buffer,
+ offset)` / `setIndexBuffer`, and `GLDevice` keeps one lazily re-pointed VAO
+ per layout as a backend cache.
+- **Immutable pipelines + render passes**: every draw path binds a cached
+ `PipelineHandle` (program + vertex layout + blend + depth + stencil mode +
+ culling; `PipelineState.hpp`); framebuffer targeting and clears are
+ `beginRenderPass(RenderPassDesc)` / `endRenderPass` with load-op clear
+ semantics. The only dynamic state outside the pipeline is the scissor
+ rectangle and the stencil reference — mirroring WebGPU's split. The loose
+ blend/depth/stencil/cull setters are private to `GLDevice`. Per-frame /
+ material / light constants live in UBOs at fixed binding slots
+ (`setUniformBuffer`, the future BindGroup seam); loose `setUniform*`
+ survives for the custom-mesh and post-process shader paths.
+ A CI guard (`tools/check-gl-boundary.mjs`) rejects raw `gl*` calls outside
+ `GLDevice.cpp`; a `MockGfxDevice` harness exercises the contract headlessly.
- **`DrawList`** sorts and coalesces draw commands, merging up to 8 textures per
call; indices are **u32** (no >65535 vertex wraparound).
- **`RenderFrame`** owns transient buffers (`TransientBufferPool`), frustum
diff --git a/docs/REARCHITECTURE.md b/docs/REARCHITECTURE.md
index ddbba165a..85e8edcc3 100644
--- a/docs/REARCHITECTURE.md
+++ b/docs/REARCHITECTURE.md
@@ -158,6 +158,15 @@
- **统一 WasmBridge 基类**:SDK 仍只有 `BuiltinBridge`(`sdk/src/ecs/BuiltinBridge.ts:299`),病灶所述"五套桥接写法"尚未收敛到单一基类。
- **全 per-App 状态**:Camera/Timeline/SpriteAnimator/postprocess 等进程级全局是否已迁 per-App 资源,待审计确认。
+### 渲染后端抽象(RHI 现代化)— ✅ 已落地(2026-07-06,`6d48beba`→`aec698d3` 四批)
+在 RC5"唯一入口"的基础上,把 `GfxDevice` 从 GL 味接口升级为后端中立 RHI,使未来 WebGPU/原生后端可平行接入而 Renderer 层零改动:
+- **类型化句柄 + 描述符创建**:`Buffer/Texture/Shader/Framebuffer/VertexLayoutHandle` + `*Desc`(GL 后端句柄值=GL id,零开销);bind-target 上传协议、`texImage2D`/`pixelStorei` 等 GL 形状全部退出接口;`bindBufferBase`→`setUniformBuffer(slot, handle)`(未来 BindGroup 接缝);GPU 计时查询下沉(顺带修复 profiler 泄漏到 `RenderFrame.cpp` 的裸 `gl*`,boundary guard 恢复绿色)。
+- **顶点布局进 Pipeline、VAO 内化**:`VertexLayoutDesc`→`PipelineDesc.vertexLayout`,per-draw `setVertexBuffer(slot, buffer, offset)`/`setIndexBuffer`;GLDevice 按布局持有惰性 re-point 的 VAO 缓存(粒子实例流 rebase 语义保持);删除 `VertexArray` 包装类;`draw_mesh`/PostProcess/ImmediateDraw 全部改走真 pipeline。
+- **RenderPass**:`beginRenderPass(desc)`/`endRenderPass` 收拢 FBO 绑定 + clear(load-op 语义:强制写掩码,修复"上帧末尾 stencil-write pipeline 会静默吞掉 clear"的潜在 bug);`bindFramebuffer` 退出公共接口。TS 驱动的主 pass clear 保留在边界(多相机 scissored clear 依赖),文档标注为 WebGPU 后端的 deferred-load-op 仿真点。
+- **散装状态 setter 全部转 GLDevice 私有**:公共动态状态只剩 scissor + stencil reference(与 WebGPU 划分一致)。
+- 验证:MockGfxDevice 四套 harness、web 构建、GL boundary guard、六个 headless 渲染场景(精灵/UI 模板遮罩/后处理链/实例化粒子/Lit 材质/tilemap)+ 编辑器截图(网格 draw_mesh 路径)全绿。
+- **遗留**:散装 `setUniform*`(自定义网格 + 后处理路径)仍是 GL 式 per-program uniform——WebGPU 后端需按 sokol 方式以每 draw 暂存 UBO 仿真,或后续把这两条路径迁 UBO。
+
### 地基收口(Foundation Consolidation)— 🟡 进行中,RC6 前置(设计文档)
见 [`REARCH_FOUNDATION_CONSOLIDATION.md`](./REARCH_FOUNDATION_CONSOLIDATION.md):
- **F2 单一 `WasmBridge` 基类 + abort 守卫下沉(keystone)— ✅ 已落地**(`ac390f7d` + RM 闭环 `41bea17a`,五套桥接全部收敛,abort 守卫全子系统覆盖)。