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 blended surface is ordered against water and glass by the pixel, so a pane in front of water is no longer covered by it

yhhef7287bae21b
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 6deef347e..d0b8ce360 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -35,6 +35,7 @@ published separately; it ships inside the editor.
- **Contact shadows and screen-space bounce light.** Contact Shadows and Screen Space GI effects add small sharp shadows at contacts and one bounce of colour between surfaces, and the weather softens the sun's shadows. `contactShadows` marches a short ray toward the scene's sun in the depth buffer; `ssgi` gathers eight rays a pixel over the G-buffer's normals at half size into a float target and averages the neighbours on the same surface before laying the light, times the receiver's colour, over the picture. The Weather component raises the sun's `sourceAngle` and lowers its `shadowStrength` as the sky clouds over.
- **Terrain and Foliage.** A Terrain component makes ground from a heightmap or noise, paints it with grass, dirt, snow and rock layers and draws it in chunks that coarsen with distance; a Foliage component scatters grass or a mesh over it, swaying in the wind and thinning out with distance.
- **Separate material maps packed on import.** Importing an FBX with separate metalness, roughness and occlusion images now packs them into the one map the Model shader samples, instead of dropping them. Occlusion goes in red, roughness in green and metal in blue, each from its image's red channel (a glossiness map is inverted); a channel with no image stays at full so the material's own value speaks. Only PNG and DDS can be read.
+- **Blended surfaces ordered against water.** A blended surface (a pane, a particle, a leaf card) is now ordered against water and glass by the pixel and not by when it was drawn: one under the surface is seen through the water, one in front of it lies on the water instead of being covered, and where there is no water it is blended once. The frame is drawn in layers only when it holds both a refracting surface and a blended draw.
- **Ripples and wakes.** A body of water keeps what disturbs it. With `ripples` above 0 the water steps a window of its surface (that follows the camera) with the wave equation: `Waters.disturb(x, y, z, radius, strength)` and a `Floating` body's wake (`wake`) put in bumps that spread as rings, fade, and bend the shading and the reflection, and leave foam that lingers and thins (`rippleSpeed`, `rippleDamping`, `foamFade`). `Waters.sample` carries the ripples, and `Waters.rippleAt` gives them alone.
- **Waterline, caustics, shafts and a mirror under the water.** Under water the picture is lit and bounded like water. A camera with its lens half in the water has a waterline across it, soft and sliding as it dips; what it sees is lit by the web of caustics the waves focus the sun into (the Water material's `u_causticStrength`, `u_causticScale` and `u_causticSpeed`, also drawn on what lies under the water seen from above); the water along each ray scatters the sun into shafts (`u_shaftStrength`); and the surface seen from below, past the critical angle, mirrors the world beneath it.
- **Underwater view.** A camera under water sees through it. Whenever the active camera is below a water body's surface an Underwater effect is added to the post-process volumes: the light of each pixel is taken out colour by colour (red first) by the distance it crossed, with the same absorption and density the surface's material draws with, and the water gives back its own colour, dimmer the deeper the camera is. The surface seen from below turns over and, past the critical angle, reflects whole (Snell's window).
diff --git a/desktop b/desktop
index 1070ab90d..b8832e2ea 160000
--- a/desktop
+++ b/desktop
@@ -1 +1 @@
-Subproject commit 1070ab90d1db616e6681dd7cca6cde80fd6ab79a
+Subproject commit b8832e2eacec0efb8703e1d28d792f898d0bbd3e
diff --git a/docs/astro/src/content/docs/graphics/water.mdx b/docs/astro/src/content/docs/graphics/water.mdx
index 5a6eb5e96..4fe6b13da 100644
--- a/docs/astro/src/content/docs/graphics/water.mdx
+++ b/docs/astro/src/content/docs/graphics/water.mdx
@@ -201,7 +201,11 @@ What is not there yet, so nobody is surprised:
- It needs the same engine-copied scene as glass (a post-process chain is running) and a device whose render targets can hold floats for the depth.
Without the chain the water is drawn over the scene as a translucent surface; without float targets the depth is `u_fallbackDepth` everywhere, so
there is no shore foam and no change of colour with depth.
-- Like glass, it refracts the opaque scene only: a boat's hull seen through it is, but another transparent surface is not.
+- Blended surfaces (a pane, a particle, a leaf card) are ordered against water and glass by the pixel: when a frame has both, it is drawn in layers (the opaque scene, the blended draws
+ over it for the picture the water refracts, the opaque scene put back and the water drawn, then the blended draws again depth-tested against the water). A blended thing under the surface is
+ seen through it, one in front lies on it, and where there is no water it is blended once. It costs two more full-screen copies of the scene and a second pass over the blended draws, only in frames
+ that have both. A blended draw with no depth test, or one that crosses the surface, is drawn whole on both sides of it, and one in front of the water is seen through it a second time, faintly,
+ as the picture the water refracts holds it.
- A river does not carve the ground, rapids and falls are not foamed by how fast or steep the water runs, and two bodies do not blend where they meet.
A lake's outline is a polygon on a plane: it does not follow a curved shore, and the waves die toward the shore without breaking on it.
- Things float (see [Floating](#floating)) and make a wake (see [Ripples](#ripples)); nothing swims yet.
diff --git a/docs/astro/src/content/docs/zh-cn/graphics/water.mdx b/docs/astro/src/content/docs/zh-cn/graphics/water.mdx
index ac06caebf..f37ffbce4 100644
--- a/docs/astro/src/content/docs/zh-cn/graphics/water.mdx
+++ b/docs/astro/src/content/docs/zh-cn/graphics/water.mdx
@@ -135,7 +135,7 @@ curve.nearest(x, z); // 在 xz 平面上离它最近的地方:s、距离、在
还没有的部分,免得让人意外:
- 它需要与玻璃相同的、由引擎拷贝的场景(有后处理链在运行),以及渲染目标能存浮点数的设备来存深度。没有链时,水作为半透明表面画在场景上;没有浮点目标时,深度处处是 `u_fallbackDepth`,所以没有岸边泡沫,颜色也不随水深变化。
-- 与玻璃一样,它只折射不透明场景:透过它能看到船体,但看不到另一个透明表面。
+- 混合(半透明)表面(玻璃板、粒子、叶片卡片)与水和玻璃是按像素排序的:一帧里两者都有时,场景分层绘制(不透明场景;在其上画混合物体,作为水折射的画面;把不透明场景放回去再画水;最后把混合物体按水的深度再画一遍)。水下的混合物体能透过水看到,水前的躺在水面上,没有水的地方只混合一次。代价是多两次全屏场景拷贝和对混合物体的第二遍绘制,只在同时有两者的帧里发生。没有深度测试的混合物体,或横跨水面的,在水面两侧都整个画出;水前面的物体会因为水折射的画面里包含它,而在水里被淡淡地再看到一次。
- 河流不会切削地面,急流和瀑布不会按水流的快慢或陡度起泡沫,两个水体相接处也不会融合。湖泊的轮廓是平面上的多边形:它不跟随弯曲的岸线,波浪向岸边消失而不是在岸上破碎。
- 东西可以漂浮(见[漂浮](#漂浮)),也会激起尾迹(见[涟漪](#涟漪));还没有东西能游泳。
- 焦散和光束只跟随第一盏平行光,来自一个图案而不是模拟:这张网并不响应波浪的真实形状。从上面看时,焦散把水下的东西当作朝上的面(画面里那里没有法线),所以水面下的一面墙会像地板一样被照亮。
diff --git a/src/esengine/renderer/draw/DrawList.cpp b/src/esengine/renderer/draw/DrawList.cpp
index 9c5c73731..840cf514e 100644
--- a/src/esengine/renderer/draw/DrawList.cpp
+++ b/src/esengine/renderer/draw/DrawList.cpp
@@ -362,6 +362,14 @@ bool DrawList::anyUsesSceneColor(const MaterialStore& materials) const {
return false;
}
+bool DrawList::anyBlendedWithoutSceneColor(const MaterialStore& materials) const {
+ for (u32 i = 0; i < merged_draw_calls_; ++i) {
+ const auto& cmd = commands_[i];
+ if (cmd.blend_mode != BlendMode::None && !(cmd.material_id != 0 && materials.usesSceneColor(cmd.material_id))) return true;
+ }
+ return false;
+}
+
bool DrawList::anyUsesSceneDepth(const MaterialStore& materials) const {
for (u32 i = 0; i < merged_draw_calls_; ++i) {
if (commands_[i].material_id != 0 && materials.usesSceneDepth(commands_[i].material_id)) return true;
@@ -386,9 +394,18 @@ void DrawList::execute(GfxDevice& device, TransientBufferPool& buffers,
for (u32 i = 0; i < merged_draw_calls_; ++i) {
const auto& cmd = commands_[i];
const StagedBlocks& staged = staged_[i];
- if (phase != Phase::All
- && (cmd.material_id != 0 && materials.usesSceneColor(cmd.material_id)) != (phase == Phase::SceneColorOnly)) {
- continue;
+ if (phase != Phase::All) {
+ const bool refracts = cmd.material_id != 0 && materials.usesSceneColor(cmd.material_id);
+ const bool blended = cmd.blend_mode != BlendMode::None;
+ bool drawn = false;
+ switch (phase) {
+ case Phase::WithoutSceneColor: drawn = !refracts; break;
+ case Phase::SceneColorOnly: drawn = refracts; break;
+ case Phase::OpaqueOnly: drawn = !refracts && !blended; break;
+ case Phase::BlendedOnly: drawn = !refracts && blended; break;
+ case Phase::All: drawn = true; break;
+ }
+ if (!drawn) continue;
}
const GfxStencilMode stencil = stencilModeOf(cmd.state_flags);
diff --git a/src/esengine/renderer/draw/DrawList.hpp b/src/esengine/renderer/draw/DrawList.hpp
index 427ad1822..b0efc1c83 100644
--- a/src/esengine/renderer/draw/DrawList.hpp
+++ b/src/esengine/renderer/draw/DrawList.hpp
@@ -57,7 +57,7 @@ public:
// (filling with the draw's own tex re-pointed all 8 units on every tex change).
/// Which of the list's draws an execute makes. A draw whose material reads the picture behind it (`u_sceneColor`) has to be
/// made after a copy of that picture is taken, so the frame executes the list twice: the rest, then those.
- enum class Phase : u8 { All, WithoutSceneColor, SceneColorOnly };
+ enum class Phase : u8 { All, WithoutSceneColor, SceneColorOnly, OpaqueOnly, BlendedOnly };
void execute(GfxDevice& device, TransientBufferPool& buffers,
MaterialStore& materials, u32 white_texture_id = 0,
FrameCapture* capture = nullptr,
@@ -65,6 +65,8 @@ public:
/// Whether any merged draw reads the picture behind it.
bool anyUsesSceneColor(const MaterialStore& materials) const;
+ /// Whether the list holds a blended draw that does not refract: what has to be ordered against a refracting surface by where it is, not by when it was drawn.
+ bool anyBlendedWithoutSceneColor(const MaterialStore& materials) const;
/// Whether any merged draw reads the distance to the opaque scene behind it.
bool anyUsesSceneDepth(const MaterialStore& materials) const;
diff --git a/src/esengine/renderer/frame/RenderFrame.cpp b/src/esengine/renderer/frame/RenderFrame.cpp
index 264f10b63..2124f40bc 100644
--- a/src/esengine/renderer/frame/RenderFrame.cpp
+++ b/src/esengine/renderer/frame/RenderFrame.cpp
@@ -249,7 +249,7 @@ void RenderFrame::drawScene(DrawList::Phase phase) {
#ifdef ES_ENABLE_POSTPROCESS
// The atlas the meshes reflect, for an effect that adds a reflection of its own where the scene's ray found none.
if (post_process_) post_process_->setEnvironmentTexture(environment_texture_id_);
- if (phase == DrawList::Phase::SceneColorOnly) {
+ if (phase == DrawList::Phase::SceneColorOnly || phase == DrawList::Phase::BlendedOnly) {
// The second half of a scene drawn in two: the same camera, shifted the same way, and a frame that must not step the
// temporal view a second time.
jitter = scene_jitter_;
@@ -676,13 +676,25 @@ void RenderFrame::end() {
bool glass = false;
#ifdef ES_ENABLE_POSTPROCESS
glass = usePostProcess && draw_list_.anyUsesSceneColor(context_.materials());
+#endif
+ // A blended surface (a pane, a particle, a leaf card) writes no depth, so drawn before the water it is covered by it wherever the water is in
+ // front of the pixel's opaque, whichever side of the surface it is on. So where there are any, the scene is built in layers: the opaque
+ // scene, then the blended draws over it (the picture the water refracts, so what is under the surface is seen through it), then the opaque
+ // scene put back and the water drawn, and last the blended draws once more, depth-tested against the water now: those in front of the
+ // surface land on it, those behind it fail and are only seen through it. The pixels the water does not cover were put back, so they are blended once.
+ bool layered = false;
+#ifdef ES_ENABLE_POSTPROCESS
+ layered = glass && draw_list_.anyBlendedWithoutSceneColor(context_.materials());
#endif
rg::PassDesc glassPass;
+ rg::PassDesc blendedPass, overPass;
+ rg::ResourceId grabOpaque = rg::kNoResource;
rg::ResourceId grab = rg::kNoResource;
rg::ResourceId grabDepth = rg::kNoResource;
if (glass) {
#ifdef ES_ENABLE_POSTPROCESS
grab = graph_.createTarget(post_process_->grabTarget());
+ if (layered) grabOpaque = graph_.createTarget(post_process_->grabTarget());
// The distance to what stands behind, for a surface that measures the water in front of it: only when one asks, and
// only where a float target can hold distances.
if (draw_list_.anyUsesSceneDepth(context_.materials()) && post_process_->canGrabDepth()) {
@@ -692,18 +704,32 @@ void RenderFrame::end() {
glassPass.name = "scene-glass";
glassPass.dependencies.push_back(grab);
if (grabDepth != rg::kNoResource) glassPass.dependencies.push_back(grabDepth);
- glassPass.execute = [this, grab, grabDepth](const rg::PassContext&) {
+ if (layered) {
+ blendedPass = scene;
+ blendedPass.name = "scene-blended";
+ blendedPass.dependencies.push_back(grabOpaque);
+ if (grabDepth != rg::kNoResource) blendedPass.dependencies.push_back(grabDepth);
+ blendedPass.execute = [this](const rg::PassContext&) { drawScene(DrawList::Phase::BlendedOnly); };
+ overPass = scene;
+ overPass.name = "scene-blended-over";
+ overPass.dependencies.push_back(grab);
+ overPass.execute = [this](const rg::PassContext&) {
+ drawScene(DrawList::Phase::BlendedOnly);
+ if (presented_overlay_draw_) presented_overlay_draw_->flushDeferred();
+ };
+ }
+ glassPass.execute = [this, grab, grabDepth, layered](const rg::PassContext&) {
context_.materials().setSceneColor(graph_.textureOf(grab));
if (grabDepth != rg::kNoResource) context_.materials().setSceneDepth(graph_.textureOf(grabDepth));
drawScene(DrawList::Phase::SceneColorOnly);
context_.materials().setSceneColor(TextureHandle::Invalid);
context_.materials().setSceneDepth(TextureHandle::Invalid);
- if (presented_overlay_draw_) presented_overlay_draw_->flushDeferred();
+ if (!layered && presented_overlay_draw_) presented_overlay_draw_->flushDeferred();
};
#endif
}
- scene.execute = [this, glass](const rg::PassContext&) {
- drawScene(glass ? DrawList::Phase::WithoutSceneColor : DrawList::Phase::All);
+ scene.execute = [this, glass, layered](const rg::PassContext&) {
+ drawScene(layered ? DrawList::Phase::OpaqueOnly : glass ? DrawList::Phase::WithoutSceneColor : DrawList::Phase::All);
if (!glass && presented_overlay_draw_) presented_overlay_draw_->flushDeferred();
};
graph_.addPass(std::move(scene));
@@ -712,7 +738,7 @@ void RenderFrame::end() {
rg::PassDesc copy;
copy.name = "scene-grab";
copy.reads = {scene_resource_};
- copy.write = grab;
+ copy.write = layered ? grabOpaque : grab;
copy.execute = [this](const rg::PassContext&) { post_process_->grabScene(); };
graph_.addPass(std::move(copy));
if (grabDepth != rg::kNoResource) {
@@ -724,7 +750,24 @@ void RenderFrame::end() {
graph_.addPass(std::move(copyDepth));
}
#endif
+ if (layered) {
+ graph_.addPass(std::move(blendedPass));
+ rg::PassDesc copyBlended;
+ copyBlended.name = "scene-grab-blended";
+ copyBlended.reads = {scene_resource_};
+ copyBlended.write = grab;
+ copyBlended.execute = [this](const rg::PassContext&) { post_process_->grabScene(); };
+ graph_.addPass(std::move(copyBlended));
+ // The opaque scene put back: what the blended draws left in the pixels is theirs to leave again, in the pass after the water.
+ rg::PassDesc restore;
+ restore.name = "scene-restore";
+ restore.reads = {grabOpaque};
+ restore.write = scene_resource_;
+ restore.execute = [this](const rg::PassContext&) { post_process_->grabScene(); };
+ graph_.addPass(std::move(restore));
+ }
graph_.addPass(std::move(glassPass));
+ if (layered) graph_.addPass(std::move(overPass));
}
}
diff --git a/tools/releaseNotes.mjs b/tools/releaseNotes.mjs
index d76f27ddb..be23daaf8 100644
--- a/tools/releaseNotes.mjs
+++ b/tools/releaseNotes.mjs
@@ -2567,6 +2567,8 @@ export const NOTED = {
{"note":"Water holds things up. A Floating component on an entity with a RigidBody3D floats it: a buoyant force against gravity (`buoyancy` is the water's density against the body's, so 2 floats it half under) and a drag against its velocity relative to the water, which brings it to rest in a lake and carries it with a river's current, applied at a few points of the body so waves tip it. It works from the CPU's own water surface, so it needs no renderer, and it needs the 3D physics module, which gains force and mass queries."},
"feat(water): a camera under the surface sees through the water, fogged and tinted by what it has crossed":
{"note":"A camera under water sees through it. Whenever the active camera is below a water body's surface an Underwater effect is added to the post-process volumes: the light of each pixel is taken out colour by colour (red first) by the distance it crossed, with the same absorption and density the surface's material draws with, and the water gives back its own colour, dimmer the deeper the camera is. The surface seen from below turns over and, past the critical angle, reflects whole (Snell's window)."},
+ "fix(render): a blended surface is ordered against water and glass by the pixel, so a pane in front of water is no longer covered by it":
+ {"note":"A blended surface (a pane, a particle, a leaf card) is now ordered against water and glass by the pixel and not by when it was drawn: one under the surface is seen through the water, one in front of it lies on the water instead of being covered, and where there is no water it is blended once. The frame is drawn in layers only when it holds both a refracting surface and a blended draw."},
"feat(water): water keeps ripples and foam, a disturbance spreads as a ring, and what moves in it makes a wake":
{"note":"A body of water keeps what disturbs it. With `ripples` above 0 the water steps a window of its surface (that follows the camera) with the wave equation: `Waters.disturb(x, y, z, radius, strength)` and a `Floating` body's wake (`wake`) put in bumps that spread as rings, fade, and bend the shading and the reflection, and leave foam that lingers and thins (`rippleSpeed`, `rippleDamping`, `foamFade`). `Waters.sample` carries the ripples, and `Waters.rippleAt` gives them alone."},
"feat(water): a waterline across the lens, caustics, light shafts, and a mirror under the surface":