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): add PipelineState as a GfxDevice concept (additive) — REARCH_RENDER P2a
esengine1b1bc9c37865
diff --git a/CMakeLists.txt b/CMakeLists.txtindex c81f6d7b2..b28d6e860 100644--- a/CMakeLists.txt+++ b/CMakeLists.txt@@ -141,6 +141,7 @@ set(ESENGINE_HEADERSsrc/esengine/renderer/DrawList.hppsrc/esengine/renderer/ClipState.hppsrc/esengine/renderer/FrameConstants.hpp+ src/esengine/renderer/PipelineState.hppsrc/esengine/renderer/BatchBuilder.hppsrc/esengine/renderer/RenderTypePlugin.hppsrc/esengine/renderer/plugins/BatchPlugin.hppdiff --git a/src/esengine/renderer/GLDevice.cpp b/src/esengine/renderer/GLDevice.cppindex e1deff289..78eb36f2b 100644--- a/src/esengine/renderer/GLDevice.cpp+++ b/src/esengine/renderer/GLDevice.cpp@@ -586,6 +586,77 @@ void GLDevice::uniformBlockBinding(u32 programId, u32 blockIndex, u32 bindingPoiglUniformBlockBinding(programId, blockIndex, bindingPoint);}+// =============================================================================+// Pipeline State+// =============================================================================++PipelineHandle GLDevice::createPipeline(const PipelineDesc& desc) {+ for (u32 i = 0; i < pipelines_.size(); ++i) {+ if (pipelines_[i] == desc) {+ return static_cast<PipelineHandle>(i + 1);+ }+ }+ pipelines_.push_back(desc);+ return static_cast<PipelineHandle>(pipelines_.size()); // 1-based; 0 == Invalid+}++void GLDevice::applyStencilMode(GfxStencilMode mode) {+ // Mirrors the former StateTracker stencil sequences. The reference value is applied+ // separately by setStencilReference (it is dynamic, not pipeline state).+ switch (mode) {+ case GfxStencilMode::Off:+ setStencilTest(false);+ setStencilMask(0xFF);+ setColorMask(true, true, true, true);+ break;+ case GfxStencilMode::Write:+ setStencilTest(true);+ setStencilOp(GfxStencilOp::Keep, GfxStencilOp::Keep, GfxStencilOp::Replace);+ setColorMask(false, false, false, false);+ setStencilMask(0xFF);+ break;+ case GfxStencilMode::Test:+ setStencilTest(true);+ setStencilOp(GfxStencilOp::Keep, GfxStencilOp::Keep, GfxStencilOp::Keep);+ setColorMask(true, true, true, true);+ setStencilMask(0x00);+ break;+ }+}++void GLDevice::setPipeline(PipelineHandle handle) {+ if (handle == current_pipeline_ || handle == PipelineHandle::Invalid) return;++ u32 index = static_cast<u32>(handle) - 1;+ if (index >= pipelines_.size()) return;+ const PipelineDesc& desc = pipelines_[index];++ useProgram(desc.program);+ setBlendEnabled(desc.blendEnabled);+ setBlendMode(desc.blend);+ setDepthTest(desc.depthTest);+ setDepthWrite(desc.depthWrite);+ setCulling(desc.cullEnabled);+ if (desc.cullEnabled) setCullFace(desc.cullFront);+ applyStencilMode(desc.stencil);++ current_pipeline_ = handle;+ current_stencil_mode_ = desc.stencil;+}++void GLDevice::setStencilReference(i32 ref) {+ switch (current_stencil_mode_) {+ case GfxStencilMode::Write:+ setStencilFunc(GfxStencilFunc::Always, ref, 0xFF);+ break;+ case GfxStencilMode::Test:+ setStencilFunc(GfxStencilFunc::Equal, ref, 0xFF);+ break;+ case GfxStencilMode::Off:+ break;+ }+}+// =============================================================================// VAO Operations// =============================================================================diff --git a/src/esengine/renderer/GLDevice.hpp b/src/esengine/renderer/GLDevice.hppindex 35af25f12..e2222c427 100644--- a/src/esengine/renderer/GLDevice.hpp+++ b/src/esengine/renderer/GLDevice.hpp@@ -17,6 +17,8 @@#include "GfxDevice.hpp"+#include <vector>+namespace esengine {// =============================================================================@@ -88,6 +90,10 @@ public:u32 getUniformBlockIndex(u32 programId, const char* name) override;void uniformBlockBinding(u32 programId, u32 blockIndex, u32 bindingPoint) override;+ PipelineHandle createPipeline(const PipelineDesc& desc) override;+ void setPipeline(PipelineHandle handle) override;+ void setStencilReference(i32 ref) override;+u32 createVertexArray() override;void deleteVertexArray(u32 vaoId) override;void bindVertexArray(u32 vaoId) override;@@ -129,6 +135,16 @@ public:std::string getString(GfxStringName name) override;i32 getInt(GfxIntParam name) override;bool supportsCompressedFormat(GfxCompressedFormat format) override;++private:+ // Pipeline cache: a handle is (index + 1) into pipelines_; PipelineHandle::Invalid is 0.+ // WebGL2 has no native pipeline object, so a pipeline is applied as a bundle of GL+ // state, deduped by comparing handles (same pipeline -> skip the whole state apply).+ void applyStencilMode(GfxStencilMode mode);++ std::vector<PipelineDesc> pipelines_;+ PipelineHandle current_pipeline_ = PipelineHandle::Invalid;+ GfxStencilMode current_stencil_mode_ = GfxStencilMode::Off;};} // namespace esenginediff --git a/src/esengine/renderer/GfxDevice.hpp b/src/esengine/renderer/GfxDevice.hppindex 5bf16f2dc..35bd64b88 100644--- a/src/esengine/renderer/GfxDevice.hpp+++ b/src/esengine/renderer/GfxDevice.hpp@@ -20,6 +20,7 @@#include "../core/Types.hpp"#include "BlendMode.hpp"#include "GfxEnums.hpp"+#include "PipelineState.hpp"#include "Texture.hpp"#include <string>@@ -231,6 +232,19 @@ public:/** @brief Links a program's uniform block to an indexed binding point. */virtual void uniformBlockBinding(u32 programId, u32 blockIndex, u32 bindingPoint) = 0;+ // =========================================================================+ // Pipeline State (immutable "how to draw"; see PipelineState.hpp)+ // =========================================================================++ /** @brief Resolves a pipeline description to a cached handle (creating it on first use). */+ virtual PipelineHandle createPipeline(const PipelineDesc& desc) = 0;++ /** @brief Binds a pipeline: applies its program, blend, depth, stencil compare/op and culling. */+ virtual void setPipeline(PipelineHandle handle) = 0;++ /** @brief Sets the dynamic stencil reference for the bound pipeline's stencil mode (no-op if Off). */+ virtual void setStencilReference(i32 ref) = 0;+// =========================================================================// VAO Operations// =========================================================================diff --git a/src/esengine/renderer/GfxEnums.hpp b/src/esengine/renderer/GfxEnums.hppindex e8e18dd11..b21cfe3a5 100644--- a/src/esengine/renderer/GfxEnums.hpp+++ b/src/esengine/renderer/GfxEnums.hpp@@ -28,6 +28,22 @@ enum class GfxBufferTarget : u8 {Uniform,};+// =============================================================================+// Vertex Layout Id+// =============================================================================++/**+ * @brief Identifies a transient vertex stream / vertex format. Each layout has its own+ * VBO+EBO+VAO in TransientBufferPool and is part of a pipeline's identity.+ */+enum class LayoutId : u8 {+ Batch = 0,+ Shape = 2,+ MatSprite = 3,+};++static constexpr u32 LAYOUT_COUNT = 4;+// =============================================================================// Data Type (vertex attributes, index type, pixel data type)// =============================================================================diff --git a/src/esengine/renderer/PipelineState.hpp b/src/esengine/renderer/PipelineState.hppnew file mode 100644index 000000000..98f41bd06--- /dev/null+++ b/src/esengine/renderer/PipelineState.hpp@@ -0,0 +1,58 @@+/**+ * @file PipelineState.hpp+ * @brief Immutable GPU pipeline state — the backend-agnostic unit of "how to draw".+ * @details A PipelineState bundles everything that is fixed for a draw and that WebGPU+ * bakes into an immutable GPURenderPipeline: the shader program, the vertex+ * layout, blend, depth, stencil compare/op, and culling. The renderer resolves+ * a PipelineDesc to an opaque PipelineHandle once (cached) and thereafter binds+ * it with GfxDevice::setPipeline. Per-draw dynamic state — scissor rectangle and+ * stencil reference — stays out of the pipeline (see setScissor/setStencilReference),+ * mirroring WebGPU's split. This is the keystone abstraction that lets a WebGPU+ * backend slot in beside the WebGL2 one (docs/REARCH_RENDER.md P2).+ *+ * @author ESEngine Team+ * @date 2026+ *+ * @copyright Copyright (c) 2026 ESEngine Team+ * Licensed under the MIT License.+ */+#pragma once++#include "../core/Types.hpp"+#include "BlendMode.hpp"+#include "GfxEnums.hpp" // LayoutId++namespace esengine {++/**+ * @brief Stencil behaviour baked into a pipeline. The reference value is dynamic+ * (GfxDevice::setStencilReference), the compare/op/masks are pipeline state.+ */+enum class GfxStencilMode : u8 {+ Off, ///< No stencil test; full color write.+ Write, ///< Write the reference where drawn (mask fill): func Always, op Replace, color write off.+ Test, ///< Draw only where the stencil equals the reference (mask clip): func Equal, op Keep.+};++/**+ * @brief Immutable description of a draw pipeline. Equality keys the pipeline cache, so+ * two draws with the same description share one PipelineHandle.+ */+struct PipelineDesc {+ u32 program = 0;+ LayoutId vertexLayout = LayoutId::Batch;+ BlendMode blend = BlendMode::Normal;+ bool blendEnabled = true;+ bool depthTest = false;+ bool depthWrite = false;+ GfxStencilMode stencil = GfxStencilMode::Off;+ bool cullEnabled = false;+ bool cullFront = false;++ bool operator==(const PipelineDesc&) const = default;+};++/** @brief Opaque handle to a cached pipeline; PipelineHandle{0} is the null/invalid handle. */+enum class PipelineHandle : u32 { Invalid = 0 };++} // namespace esenginediff --git a/src/esengine/renderer/TransientBufferPool.hpp b/src/esengine/renderer/TransientBufferPool.hppindex bec4f274d..090fed1a4 100644--- a/src/esengine/renderer/TransientBufferPool.hpp+++ b/src/esengine/renderer/TransientBufferPool.hpp@@ -8,13 +8,8 @@namespace esengine {-enum class LayoutId : u8 {- Batch = 0,- Shape = 2,- MatSprite = 3,-};--static constexpr u32 LAYOUT_COUNT = 4;+// LayoutId / LAYOUT_COUNT now live in GfxEnums.hpp (a leaf header) so PipelineState can+// reference LayoutId without pulling in the GfxDevice include cycle./*** Per-frame vertex/index staging with one independent VBO+EBO+VAO per layout.diff --git a/tests/renderer/MockGfxDevice.hpp b/tests/renderer/MockGfxDevice.hppindex d9fc4b1c8..68fea87db 100644--- a/tests/renderer/MockGfxDevice.hpp+++ b/tests/renderer/MockGfxDevice.hpp@@ -114,6 +114,12 @@ struct MockGfxDevice final : GfxDevice {u32 getUniformBlockIndex(u32, const char*) override { return GFX_INVALID_UNIFORM_BLOCK; }void uniformBlockBinding(u32, u32, u32) override {}+ u32 nextPipelineId = 0;+ int setPipelineCalls = 0;+ PipelineHandle createPipeline(const PipelineDesc&) override { return static_cast<PipelineHandle>(++nextPipelineId); }+ void setPipeline(PipelineHandle) override { ++setPipelineCalls; }+ void setStencilReference(i32) override {}+u32 createVertexArray() override { ++createVertexArrayCalls; return nextVaoId++; }void deleteVertexArray(u32) override { ++deleteVertexArrayCalls; }void bindVertexArray(u32 vaoId) override { ++bindVertexArrayCalls; lastVao = vaoId; }