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
fix(render): a frame is given depth by what it draws, not by a setting that stopped covering it
yhhdde90da0b162
diff --git a/CHANGELOG.md b/CHANGELOG.mdindex ea2483697..73dc3265b 100644--- a/CHANGELOG.md+++ b/CHANGELOG.md@@ -60,6 +60,53 @@ published separately; it ships inside the editor.### Fixed+- **A frame is given a depth buffer by what it draws, not by a setting that stopped+ covering it.** An opaque mesh has declared its own depth test and write since it+ stopped waiting for a depth layer to grant them (`MeshPlugin.cpp:240`, "an opaque+ surface says so itself"). Whether the frame HAD a depth buffer to test against was+ still decided somewhere else entirely: the post-process capture took its depth+ attachment from the project's depth-layer mask alone. The two never spoke.++ So a project that declares no depth layer and engages the capture — one post effect,+ or the linear colour space a PBR pipeline is built for — rendered its opaque meshes+ into a target with no depth attachment. The test did not fail; it passed, because+ there was nothing to fail against. And an opaque draw sorts front-to-back for+ early-z, so what is painted last is what is furthest away: the picture inverted+ rather than degrading, and nothing said so.++ Nothing in the corpus stood there. All four 3D projects — `3d-starter`,+ `lighting-3d`, `model-import`, `physics-3d` — ship gamma and ship no post stack,+ which is the only combination that worked.++ `DrawList::needsDepth()` is the one answer now: the declared layer mask OR any+ command that tests or writes depth, accumulated where commands ENTER the list so a+ render path added later cannot produce a depth draw it fails to count.++ The capture's attachments are chosen when it is BUILT, which is before the frame has+ collected anything — so the frame cannot be asked and the previous one is asked+ instead, through `RenderFrame::beginFrame()`. That is the frame's own opening, which+ `begin()` is not: `begin()`/`end()` bracket one CAMERA, so an answer applied there+ would let a 2D camera drop the buffer a 3D camera two lines later is about to test+ against. Three states, conservative by default: nothing has answered yet (boot) ⇒+ the frame gets depth, so a 3D scene is right on the first frame it draws — the frame+ a thumbnail, a preview or a pixel gate takes; a frame answered and nothing in it+ resolved by depth ⇒ released, so a 2D project still pays for one frame's attachment+ and no more; anything ever resolved by depth ⇒ kept for good, a latch rather than a+ per-frame answer because culling makes a per-frame one flap — the lone mesh that+ leaves the frustum would take the buffer with it.++ What remains is one frame, stated rather than discovered: a world with no+ depth-resolving renderable that gains its first. It self-heals on the next frame and+ never returns, and it is the price of an attachment chosen before the content that+ needs it is known.++ Gate `mesh-depth-through-capture`, both backends: two opaque cubes overlapping on+ screen, the red one 120 units nearer, booted linear and declaring no depth layer. It+ was landed red on purpose one commit earlier. Measured against the two controls that+ differ in one thing each — gamma with no layer (capture bypassed, default surface+ carries depth) and linear with layer 1 (capture built with depth) both drew red;+ linear with no layer drew green.+- **A skinned mesh's channels reach the inspector as numbers.** `meshSummary`'s nametable stopped at `Tangent`, so every skinned import — the only meshes that carry thejoint channels — described itself as `position, uv, color, #5, #6`.diff --git a/src/esengine/bindings/RendererBindings.cpp b/src/esengine/bindings/RendererBindings.cppindex 78198fe53..bbdd83fd8 100644--- a/src/esengine/bindings/RendererBindings.cpp+++ b/src/esengine/bindings/RendererBindings.cpp@@ -484,6 +484,8 @@ void renderer_beginFrame(f32 elapsedSec) {if (auto* rc = ctx().tryGet<RenderContext>()) {rc->setFrameTime(elapsedSec, g_viewportWidth, g_viewportHeight);}+ // The frame's own opening, which begin() is not: it runs once per camera.+ if (g_renderFrame) g_renderFrame->beginFrame();}// The pass's load-op rides begin: clearFlags bit0 = color, bit1 = depth; the colordiff --git a/src/esengine/renderer/draw/DrawList.cpp b/src/esengine/renderer/draw/DrawList.cppindex cfdb24f92..fea0879a5 100644--- a/src/esengine/renderer/draw/DrawList.cpp+++ b/src/esengine/renderer/draw/DrawList.cpp@@ -46,6 +46,7 @@ void DrawList::clear() {sort_entries_.clear();skin_matrices_.clear();merged_draw_calls_ = 0;+ depth_required_ = false;}u32 DrawList::addSkinMatrices(const glm::mat4* matrices, u32 count) {@@ -55,6 +56,10 @@ u32 DrawList::addSkinMatrices(const glm::mat4* matrices, u32 count) {}void DrawList::push(const DrawCommand& cmd) {+ // Accumulated where commands ENTER, not scanned where the answer is wanted:+ // push is the one funnel every render path goes through, so a path added+ // later cannot produce a depth draw this fails to count. See needsDepth.+ depth_required_ = depth_required_ || cmd.depth_test || cmd.depth_write;commands_.push_back(cmd);}diff --git a/src/esengine/renderer/draw/DrawList.hpp b/src/esengine/renderer/draw/DrawList.hppindex eda812ed5..4ea218dec 100644--- a/src/esengine/renderer/draw/DrawList.hpp+++ b/src/esengine/renderer/draw/DrawList.hpp@@ -61,6 +61,24 @@ public:void setDepthMask(u32 mask) { depth_mask_ = mask; }u32 depthMask() const { return depth_mask_; }+ /**+ * @brief Whether a frame holding these draws has to be handed a depth buffer.+ *+ * @details Two things resolve by depth and they are ONE question. A layer the+ * project declared depth-resolved is one; a draw that declared it for+ * ITSELF is the other — an opaque mesh writes and tests depth without+ * waiting for a layer to grant it, which is what lets one model hide+ * another in a project that never heard of 2.5D. Asking only the mask+ * is how an opaque mesh came to test against an attachment nobody+ * made: a depth test with no buffer behind it does not fail, it+ * passes, and an opaque draw sorts front-to-back for early-z — so the+ * furthest is painted last and the picture inverts rather than+ * degrading.+ *+ * This is the whole answer, so nobody downstream needs a second one.+ */+ bool needsDepth() const { return depth_mask_ != 0 || depth_required_; }+// Bit i set ⇒ the camera being rendered draws layer i. A camera property, not a// scene one, so it is set per camera (RenderFrame::begin clears the list each time).void setCullingMask(u32 mask) { culling_mask_ = mask; }@@ -114,6 +132,8 @@ private:u32 merged_draw_calls_ = 0;u32 ysort_mask_ = 0;u32 depth_mask_ = 0;+ /// Any command pushed this collect that tests or writes depth — see needsDepth.+ bool depth_required_ = false;u32 culling_mask_ = 0xFFFFFFFFu; // every layer, until a camera says otherwise};diff --git a/src/esengine/renderer/frame/RenderFrame.cpp b/src/esengine/renderer/frame/RenderFrame.cppindex 264f165a3..aba9d7a60 100644--- a/src/esengine/renderer/frame/RenderFrame.cpp+++ b/src/esengine/renderer/frame/RenderFrame.cpp@@ -141,9 +141,10 @@ void RenderFrame::init(u32 width, u32 height) {#ifdef ES_ENABLE_POSTPROCESSpost_process_ = makeUnique<PostProcessPipeline>(device_, context_, resource_manager_);post_process_->setLinearOutput(linear_color_);- // Depth layers may have been declared before the pipeline existed (the mask- // arrives with the project, init happens on the first frame).- post_process_->setSceneNeedsDepth(draw_list_.depthMask() != 0);+ // The requirement may have been declared before the pipeline existed (a depth+ // layer arrives with the project, init happens on the first frame) — and until+ // a frame has answered, the answer is that the capture carries depth.+ applySceneDepthNeed();post_process_->init(width, height);#endif@@ -220,6 +221,27 @@ void RenderFrame::resize(u32 width, u32 height) {#endif}+void RenderFrame::beginFrame() {+ // Last frame's answer becomes this frame's, once. A frame that collected+ // nothing answered nothing — an editor frame that only blits, a frame the host+ // skipped — so it neither latches nor releases.+ if (frame_collected_) {+ depth_answered_ = true;+ if (frame_depth_seen_) depth_seen_ = true;+ }+ frame_collected_ = false;+ frame_depth_seen_ = false;+ applySceneDepthNeed();+}++void RenderFrame::applySceneDepthNeed() {+#ifdef ES_ENABLE_POSTPROCESS+ if (!post_process_) return;+ post_process_->setSceneNeedsDepth(!depth_answered_ || depth_seen_+ || draw_list_.depthMask() != 0);+#endif+}+void RenderFrame::begin(const glm::mat4& view_projection, RenderTargetManager::Handle target) {begin(view_projection, target, PassClear{});}@@ -1094,6 +1116,14 @@ void RenderFrame::collectAll(ecs::Registry& registry, u32 skipFlags) {if (skipFlags != 0 && (skipFlags & plugin->skipFlag()) != 0) continue;plugin->collect(collectCtx);}++ // What this camera drew is part of what the FRAME drew: OR-ed across the+ // frame's cameras and applied at the next beginFrame, never mid-frame. The+ // capture is scratch each camera composites out of, so rebuilding it between+ // two of them would drop the pixels the first one has not composited yet —+ // and the editor's grid, which draws between begin() and this collect.+ frame_collected_ = true;+ frame_depth_seen_ = frame_depth_seen_ || draw_list_.needsDepth();}glm::vec3 srgbToLinearCpu(const glm::vec3& c) {diff --git a/src/esengine/renderer/frame/RenderFrame.hpp b/src/esengine/renderer/frame/RenderFrame.hppindex d8fe03fc8..cdcb79500 100644--- a/src/esengine/renderer/frame/RenderFrame.hpp+++ b/src/esengine/renderer/frame/RenderFrame.hpp@@ -105,6 +105,19 @@ public:u32 w = 0, h = 0;};+ /**+ * @brief Opens the FRAME, once, before any of its cameras.+ *+ * @details begin()/end() bracket one CAMERA — a frame runs the pair once per+ * camera — so a decision that must hold steady across a frame cannot+ * be made there. This is where the scene's depth requirement is rolled+ * forward and applied (@ref applySceneDepthNeed): the attachment the+ * capture is built with then stays put for every camera in the frame,+ * instead of a 2D camera's answer dropping the buffer a 3D camera two+ * lines later is about to test against.+ */+ void beginFrame();+void begin(const glm::mat4& view_projection, RenderTargetManager::Handle target = 0);void begin(const glm::mat4& view_projection, RenderTargetManager::Handle target,const PassClear& clear);@@ -168,9 +181,9 @@ public:void setYSortLayers(u32 mask) { draw_list_.setYSortMask(mask); }void setDepthLayers(u32 mask) {draw_list_.setDepthMask(mask);- // The scene target needs a depth attachment exactly when some layer resolves- // by depth; before init there is no pipeline yet, and it reads the mask itself.- if (post_process_) post_process_->setSceneNeedsDepth(mask != 0);+ // Through the one applier: the mask is no longer the whole answer, only+ // half of it. Before init there is no pipeline yet, and init asks again.+ applySceneDepthNeed();}u32 depthLayers() const { return draw_list_.depthMask(); }@@ -265,6 +278,16 @@ private:u32 preview_h_ = 0;bool in_frame_ = false;bool flushed_ = false;+ /// Depth state for the capture's attachment — see applySceneDepthNeed.+ /// Latched on for good: what once resolved by depth may leave the frustum.+ bool depth_seen_ = false;+ /// This frame's cameras, OR-ed; rolled into depth_seen_ at the next beginFrame.+ bool frame_depth_seen_ = false;+ /// Whether this frame collected at all — an uncollected frame answers nothing,+ /// so it must not be read as "nothing here needs depth".+ bool frame_collected_ = false;+ /// Whether ANY frame has answered yet. Until one has, the answer is "give it one".+ bool depth_answered_ = false;u32 width_ = 0;u32 height_ = 0;@@ -290,6 +313,33 @@ private:RenderFrameContext makeContext();void buildClipState();++ /**+ * @brief Tells the capture whether to carry a depth attachment, from the one+ * answer there is.+ *+ * @details The capture's attachments are chosen when it is BUILT, which is+ * before the frame has collected anything — so the frame cannot be+ * asked, and the previous one is asked instead. Three states, and the+ * conservative one is the default:+ *+ * - Nothing answered yet (boot): the frame gets depth. A 3D scene is+ * therefore right on the first frame it draws, which is the frame a+ * single-shot capture — a thumbnail, a preview, a pixel gate — takes.+ * - A frame answered and nothing in it resolved by depth: released, so+ * a 2D project pays for one frame's attachment and no more. That is+ * the cost this flag exists to save and it is still saved.+ * - Anything ever resolved by depth: kept, permanently. A latch and not+ * a per-frame answer, because culling makes a per-frame one flap —+ * the lone mesh that leaves the frustum would take the buffer with it+ * and the frame it comes back on would have none.+ *+ * What remains is one frame: a world with no depth-resolving renderable+ * that gains its first. It self-heals on the next frame and never+ * returns, which is the price of an attachment chosen before the+ * content that needs it is known.+ */+ void applySceneDepthNeed();/// Gathers the scene's enabled Light2D components into the per-frame LightConstants UBO/// (point/directional into the light array, ambient summed). Run each frame in collectAll;/// flush() uploads + binds the result so Lit2D material shaders read it.