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): add PipelineState as a GfxDevice concept (additive) — REARCH_RENDER P2a

esengine1b1bc9c37865
diff --git a/CMakeLists.txt b/CMakeLists.txt
index c81f6d7b2..b28d6e860 100644
--- a/CMakeLists.txt
+++ b/CMakeLists.txt
@@ -141,6 +141,7 @@ set(ESENGINE_HEADERS
src/esengine/renderer/DrawList.hpp
src/esengine/renderer/ClipState.hpp
src/esengine/renderer/FrameConstants.hpp
+ src/esengine/renderer/PipelineState.hpp
src/esengine/renderer/BatchBuilder.hpp
src/esengine/renderer/RenderTypePlugin.hpp
src/esengine/renderer/plugins/BatchPlugin.hpp
diff --git a/src/esengine/renderer/GLDevice.cpp b/src/esengine/renderer/GLDevice.cpp
index 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 bindingPoi
glUniformBlockBinding(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.hpp
index 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 esengine
diff --git a/src/esengine/renderer/GfxDevice.hpp b/src/esengine/renderer/GfxDevice.hpp
index 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.hpp
index 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.hpp
new file mode 100644
index 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 esengine
diff --git a/src/esengine/renderer/TransientBufferPool.hpp b/src/esengine/renderer/TransientBufferPool.hpp
index 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.hpp
index 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; }