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.

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.md
index 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 name
table stopped at `Tangent`, so every skinned import — the only meshes that carry the
joint channels — described itself as `position, uv, color, #5, #6`.
diff --git a/src/esengine/bindings/RendererBindings.cpp b/src/esengine/bindings/RendererBindings.cpp
index 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 color
diff --git a/src/esengine/renderer/draw/DrawList.cpp b/src/esengine/renderer/draw/DrawList.cpp
index 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.hpp
index 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.cpp
index 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_POSTPROCESS
post_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.hpp
index 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.