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: fit shadow maps to placed and deformed geometry

yhhfa13ec0e2ae2
diff --git a/.github/workflows/build.yml b/.github/workflows/build.yml
index 873a5a951..51b466cdf 100644
--- a/.github/workflows/build.yml
+++ b/.github/workflows/build.yml
@@ -105,6 +105,15 @@ jobs:
run: node tools/tests/render-clock.e2e.mjs --webgl-only
- name: Check native placement bounds with genuine headless Chromium
run: node tools/tests/placement-bounds.e2e.mjs --webgl-only
+ - name: Check instance and deformed shadow coverage with genuine headless Chromium
+ run: node tools/tests/placement-shadows.e2e.mjs --webgl-only
+ - name: Upload native placement shadow observations
+ if: always()
+ uses: actions/upload-artifact@v7
+ with:
+ name: placement-shadow-runtime
+ path: output/placement-shadows/
+ retention-days: 3
- name: Upload native placement observations
if: always()
uses: actions/upload-artifact@v7
diff --git a/docs/astro/src/content/docs/performance/static-batching.mdx b/docs/astro/src/content/docs/performance/static-batching.mdx
index f605f3b4b..b742cf4f4 100644
--- a/docs/astro/src/content/docs/performance/static-batching.mdx
+++ b/docs/astro/src/content/docs/performance/static-batching.mdx
@@ -112,6 +112,11 @@ mesh LODs and the material's declared `vertexbounds`. Those bounds include
placement rotation, scale and shear. A material that moves vertices must declare
its full local displacement so a visible surface is not culled at a view edge.
+Shadow-map coverage uses the same usable LOD geometry and declared displacement,
+transformed through every placement and its parent. Empty instance groups add no
+bounds. Receiver, caster and hair-focus bounds are gathered in one traversal, so
+instancing does not move a shadow map away from the geometry it must cover.
+
Measured in the editor's Play on WebGL2, a model of 2,004 parts (1,600 planks, 400 posts and four
props) under one root:
diff --git a/docs/astro/src/content/docs/zh-cn/performance/static-batching.mdx b/docs/astro/src/content/docs/zh-cn/performance/static-batching.mdx
index 7a37adff3..fac5779fc 100644
--- a/docs/astro/src/content/docs/zh-cn/performance/static-batching.mdx
+++ b/docs/astro/src/content/docs/zh-cn/performance/static-batching.mdx
@@ -100,6 +100,9 @@ world.insert(ship, CompositeBatch, {});
植被和组合模型共用的原生实例组,会把两个网格 LOD 和材质声明的 `vertexbounds` 一起计入每个实例的范围,
并覆盖实例的旋转、缩放与剪切。会移动顶点的材质必须声明完整的局部变形范围,避免仍在画面中的表面在视野边缘被剔除。
+阴影贴图使用相同的有效 LOD 网格和材质变形范围,并计入每个实例及其父实体的变换;空实例组不占范围。
+接收阴影的场景范围、投影物范围和头发精细阴影范围在一次遍历中收集,避免实例化后阴影贴图偏离实际几何。
+
在编辑器 Play、WebGL2 下实测,一个根节点下 2,004 个部件(1,600 块甲板、400 根柱子、4 个道具):
| | 不加 | `CompositeBatch` |
diff --git a/fixtures/scenes/placement-shadow-bend.esscene b/fixtures/scenes/placement-shadow-bend.esscene
new file mode 100644
index 000000000..be50c5181
--- /dev/null
+++ b/fixtures/scenes/placement-shadow-bend.esscene
@@ -0,0 +1,30 @@
+{
+ "version": 4,
+ "name": "PlacementShadowBend",
+ "entities": [
+ { "id": 0, "name": "Camera", "parent": null, "children": [], "visible": true,
+ "components": [
+ { "type": "Transform", "data": { "position": { "x": 0, "y": 0, "z": 10 } } },
+ { "type": "Camera", "data": { "projectionType": 1, "orthoSize": 300, "isActive": true, "priority": 0 } }
+ ]
+ },
+ { "id": 1, "name": "Receiver", "parent": null, "children": [], "visible": true,
+ "components": [
+ { "type": "Transform", "data": { "position": { "x": 0, "y": 0, "z": -200 }, "scale": { "x": 600, "y": 600, "z": 1 } } },
+ { "type": "MeshRenderer", "data": { "mesh": "/scenes/shadow-quad.esmesh", "lit": true, "opaque": true, "enabled": true, "castShadows": false } }
+ ]
+ },
+ { "id": 2, "name": "Displaced caster behind camera", "parent": null, "children": [], "visible": true,
+ "components": [
+ { "type": "Transform", "data": { "scale": { "x": 150, "y": 150, "z": 1 } } },
+ { "type": "MeshRenderer", "data": { "mesh": "/scenes/shadow-quad.esmesh", "material": "/scenes/placement-shadow-bend/caster.esmaterial", "opaque": true, "enabled": true } }
+ ]
+ },
+ { "id": 3, "name": "Sun", "parent": null, "children": [], "visible": true,
+ "components": [
+ { "type": "Transform", "data": {} },
+ { "type": "Light", "data": { "type": 1, "intensity": 1, "direction": { "x": 0, "y": 0 }, "meshShadows": true, "shadowExtent": 300 } }
+ ]
+ }
+ ]
+}
diff --git a/fixtures/scenes/placement-shadow-bend/caster.esmaterial b/fixtures/scenes/placement-shadow-bend/caster.esmaterial
new file mode 100644
index 000000000..65f2acb75
--- /dev/null
+++ b/fixtures/scenes/placement-shadow-bend/caster.esmaterial
@@ -0,0 +1,11 @@
+{
+ "version": "1.0",
+ "type": "material",
+ "name": "Displaced shadow caster",
+ "shader": "caster.esshader",
+ "properties": {},
+ "blendMode": 0,
+ "depthTest": true,
+ "depthWrite": true,
+ "cull": 0
+}
diff --git a/fixtures/scenes/placement-shadow-bend/caster.esshader b/fixtures/scenes/placement-shadow-bend/caster.esshader
new file mode 100644
index 000000000..5d8be965d
--- /dev/null
+++ b/fixtures/scenes/placement-shadow-bend/caster.esshader
@@ -0,0 +1,26 @@
+#pragma shader "DisplacedShadowCaster"
+#pragma version 300 es
+#pragma domain Unlit
+#pragma vertexbounds 5000
+
+#pragma vertexoffset
+void esMaterialVertex(inout vec3 local, inout vec3 localNormal, in vec2 uv) {
+ local.z += 5000.0;
+}
+#pragma end
+
+#pragma vertexoffset wgsl
+fn esMaterialVertex(local: ptr<function, vec3f>, localNormal: ptr<function, vec3f>, uv: vec2f) {
+ (*local).z += 5000.0;
+}
+#pragma end
+
+#pragma fragment
+precision highp float;
+out vec4 fragColor;
+void main() { fragColor = vec4(0.0, 1.0, 0.0, 1.0); }
+#pragma end
+
+#pragma fragment wgsl
+@fragment fn fs_main(v: VSOut) -> @location(0) vec4f { return vec4f(0.0, 1.0, 0.0, 1.0); }
+#pragma end
diff --git a/src/esengine/renderer/draw/MeshGeometry.hpp b/src/esengine/renderer/draw/MeshGeometry.hpp
new file mode 100644
index 000000000..82d24e027
--- /dev/null
+++ b/src/esengine/renderer/draw/MeshGeometry.hpp
@@ -0,0 +1,81 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
+/**
+ * @file MeshGeometry.hpp
+ * @brief Shared mesh LOD eligibility and local bounds for drawing and shadow fitting.
+ */
+#pragma once
+
+#include "../lod/LodSelection.hpp"
+#include "../../ecs/components/LODGroup.hpp"
+#include "../../ecs/components/MeshRenderer.hpp"
+#include "../../resource/Mesh.hpp"
+#include "../../resource/ResourceManager.hpp"
+#include <algorithm>
+
+namespace esengine {
+
+/** Bounds include every usable level so selecting a different level cannot change the selection metric. */
+struct LodLevels {
+ const Mesh* mesh[lod::kMaxStandIns + 1]{};
+ lod::LevelSet set;
+ glm::vec3 localMin{0.0f};
+ glm::vec3 localMax{0.0f};
+ bool gap = false;
+ bool disordered = false;
+ bool skinMismatch = false;
+};
+
+/** False when neither a usable stand-in nor a valid cull size can replace the base mesh. */
+inline bool gatherLodLevels(resource::ResourceManager& resources, const ecs::LODGroup& group,
+ const Mesh& base, LodLevels& out) {
+ out = LodLevels{};
+ out.mesh[0] = &base;
+ out.localMin = base.localMin;
+ out.localMax = base.localMax;
+ out.set.cull = group.cullSize;
+ out.set.hysteresis = group.hysteresis;
+
+ const resource::MeshHandle handles[lod::kMaxStandIns] = {group.lod1, group.lod2, group.lod3};
+ const f32 sizes[lod::kMaxStandIns] = {group.lod1Size, group.lod2Size, group.lod3Size};
+ for (u8 i = 0; i < lod::kMaxStandIns; ++i) {
+ const Mesh* standIn = handles[i].isValid() ? resources.getMesh(handles[i]) : nullptr;
+ if (!standIn || !standIn->isDrawable()) {
+ // A missing level ends the reachable prefix, even if later slots are populated.
+ for (u8 j = static_cast<u8>(i + 1); j < lod::kMaxStandIns; ++j) {
+ if (handles[j].isValid()) out.gap = true;
+ }
+ break;
+ }
+ if (base.isSkinned() && standIn->inverseBind.size() != base.inverseBind.size()) {
+ out.skinMismatch = true;
+ break;
+ }
+ if (i > 0 && sizes[i] >= sizes[i - 1]) out.disordered = true;
+ out.mesh[i + 1] = standIn;
+ out.set.takeOver[i] = sizes[i];
+ out.set.count = static_cast<u8>(i + 1);
+ out.localMin = glm::min(out.localMin, standIn->localMin);
+ out.localMax = glm::max(out.localMax, standIn->localMax);
+ }
+ // A cull size alone cannot validate a group whose first stand-in has an incompatible skeleton.
+ return out.set.count > 0 || (out.set.cull > 0.0f && !out.skinMismatch);
+}
+
+/** A placement's coarse mesh shares the base draw layout; an incompatible mesh cannot affect its bounds. */
+inline const Mesh* placementCoarseMesh(resource::ResourceManager& resources, const Mesh& base,
+ const ecs::MeshInstances& placements) {
+ const Mesh* coarse = placements.lod1Mesh.isValid() ? resources.getMesh(placements.lod1Mesh) : nullptr;
+ return coarse && coarse->isDrawable() && coarse->hasNormals == base.hasNormals
+ && coarse->hasTangents == base.hasTangents && coarse->hasLightmapUV == base.hasLightmapUV ? coarse : nullptr;
+}
+
+/** Displacement is local to the geometry and must be included before any placement or parent transform. */
+inline void meshLocalBounds(const Mesh& base, const Mesh* coarse, f32 displacement,
+ glm::vec3& lo, glm::vec3& hi) {
+ const glm::vec3 padding(std::max(displacement, 0.0f));
+ lo = (coarse ? glm::min(base.localMin, coarse->localMin) : base.localMin) - padding;
+ hi = (coarse ? glm::max(base.localMax, coarse->localMax) : base.localMax) + padding;
+}
+
+} // namespace esengine
diff --git a/src/esengine/renderer/frame/RenderFrame.cpp b/src/esengine/renderer/frame/RenderFrame.cpp
index 45fef0350..0f1299861 100644
--- a/src/esengine/renderer/frame/RenderFrame.cpp
+++ b/src/esengine/renderer/frame/RenderFrame.cpp
@@ -1,5 +1,9 @@
// SPDX-License-Identifier: Apache-2.0
// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
+/**
+ * @file RenderFrame.cpp
+ * @brief Assemble and submit shared scene views, lighting and shadow passes.
+ */
#include "./RenderFrame.hpp"
#ifdef ES_ENABLE_GPU_PARTICLES
#include "./GpuParticles.hpp"
@@ -9,6 +13,8 @@
#include "../store/LightStore.hpp"
#include "../draw/BatchBuilder.hpp"
#include "../draw/ImmediateDraw.hpp"
+#include "../draw/MeshGeometry.hpp"
+#include "../draw/PlacementBounds.hpp"
#include "../../ecs/components/Transform.hpp"
#include "../../ecs/components/Light.hpp"
#include "../../ecs/components/Occluder.hpp"
@@ -1934,48 +1940,54 @@ bool RenderFrame::collectEnvironment(const ecs::Light& light, const glm::vec3& s
return true;
}
-/// The world box every GPU-resident mesh occupies, or false when none does: what a shadow map
-/// covers, and what a face is tested against before it gathers. MeshPlugin culls by the same
-/// boxes, so a frustum missing this misses all. @p castersOnly leaves out what casts nothing.
-bool RenderFrame::meshWorldBounds(ecs::Registry& registry, glm::vec3& outMin, glm::vec3& outMax, bool castersOnly) {
- auto meshes = registry.activeView<ecs::Transform, ecs::MeshRenderer>();
- bool any = false;
- for (auto entity : meshes) {
- const auto& mesh = meshes.get<ecs::MeshRenderer>(entity);
- if (!mesh.enabled || !mesh.mesh.isValid() || (castersOnly && !mesh.castShadows)) continue;
- const Mesh* resident = resource_manager_.getMesh(mesh.mesh);
- if (!resident) continue;
- auto& transform = meshes.get<ecs::Transform>(entity);
- transform.ensureDecomposed();
- glm::vec3 centre(0.0f), half(0.0f);
- orientedWorldAabb(rebased(transform.worldPosition), transform.worldRotation, transform.worldScale,
- resident->localMin, resident->localMax, centre, half);
- outMin = any ? glm::min(outMin, centre - half) : centre - half;
- outMax = any ? glm::max(outMax, centre + half) : centre + half;
- any = true;
- }
- return any;
-}
-
-bool RenderFrame::hairWorldBounds(ecs::Registry& registry, glm::vec3& outMin, glm::vec3& outMax) {
+RenderFrame::ShadowBounds RenderFrame::gatherShadowBounds(ecs::Registry& registry, bool includeHair) {
auto meshes = registry.activeView<ecs::Transform, ecs::MeshRenderer>();
- bool any = false;
+ ShadowBounds bounds;
for (auto entity : meshes) {
const auto& mesh = meshes.get<ecs::MeshRenderer>(entity);
- if (!mesh.enabled || !mesh.mesh.isValid() || mesh.material == 0) continue;
- if (context_.materials().hairShadowDensity(mesh.material) <= 0.0f) continue;
+ if (!mesh.enabled || !mesh.mesh.isValid()) continue;
const Mesh* resident = resource_manager_.getMesh(mesh.mesh);
if (!resident) continue;
+ const auto* placements = registry.tryGet<ecs::MeshInstances>(entity);
+ if (placements && placements->transforms.empty()) continue;
+ const auto& materials = context_.materials();
+ const f32 bend = materials.vertexBounds(mesh.material);
+ const bool hair = includeHair && materials.hairShadowDensity(mesh.material) > 0.0f;
+ glm::vec3 lo, hi;
+ meshLocalBounds(*resident, placements ? placementCoarseMesh(resource_manager_, *resident, *placements) : nullptr, bend, lo, hi);
+ if (!placements) {
+ const auto* group = registry.tryGet<ecs::LODGroup>(entity);
+ LodLevels levels;
+ if (group && group->enabled && gatherLodLevels(resource_manager_, *group, *resident, levels)) {
+ lo = levels.localMin - glm::vec3(bend);
+ hi = levels.localMax + glm::vec3(bend);
+ }
+ }
auto& transform = meshes.get<ecs::Transform>(entity);
transform.ensureDecomposed();
- glm::vec3 centre(0.0f), half(0.0f);
- orientedWorldAabb(rebased(transform.worldPosition), transform.worldRotation, transform.worldScale,
- resident->localMin, resident->localMax, centre, half);
- outMin = any ? glm::min(outMin, centre - half) : centre - half;
- outMax = any ? glm::max(outMax, centre + half) : centre + half;
- any = true;
+ const glm::vec3 position = rebased(transform.worldPosition);
+ const auto include = [&](const glm::vec3& centre, const glm::vec3& half) {
+ bounds.all.include(centre, half);
+ if (mesh.castShadows) bounds.casters.include(centre, half);
+ if (hair) bounds.hair.include(centre, half);
+ };
+ if (placements) {
+ const glm::mat3 linear(glm::mat4_cast(transform.worldRotation) * glm::scale(glm::mat4(1.0f), transform.worldScale));
+ const glm::vec3 localCentre = (lo + hi) * 0.5f, localHalf = (hi - lo) * 0.5f;
+ for (usize i = 0; i + 16 <= placements->transforms.size(); i += 16) {
+ const f32* r = placements->transforms.data() + i;
+ const glm::vec3 origin = position + linear * glm::vec3(r[3], r[7], r[11]);
+ glm::vec3 centre, half;
+ placement_bounds::transformedBox(linear, r, origin, localCentre, localHalf, centre, half);
+ include(centre, half);
+ }
+ } else {
+ glm::vec3 centre, half;
+ orientedWorldAabb(position, transform.worldRotation, transform.worldScale, lo, hi, centre, half);
+ include(centre, half);
+ }
}
- return any;
+ return bounds;
}
/// The camera frustum's eight world corners, near plane first (GL clip z in [-1,1],
@@ -2106,17 +2118,21 @@ void RenderFrame::buildShadowPlan(ecs::Registry& registry) {
glm::vec3 corners[8];
frustumCorners(invVP, corners);
- glm::vec3 boundsMin(0.0f), boundsMax(0.0f);
- const bool haveBounds = meshWorldBounds(registry, boundsMin, boundsMax);
+ const ShadowBounds sceneBounds = gatherShadowBounds(registry, perspective);
+ const auto& boundsMin = sceneBounds.all.min;
+ const auto& boundsMax = sceneBounds.all.max;
+ const bool haveBounds = sceneBounds.all.valid;
// A map of a fixed size goes where the shadows come from. Centred on everything, a backdrop far behind a character takes it away from her: a large
// receiver says nothing of where a shadow can start.
- glm::vec3 castersMin(0.0f), castersMax(0.0f);
- const bool haveCasters = meshWorldBounds(registry, castersMin, castersMax, true);
+ const auto& castersMin = sceneBounds.casters.min;
+ const auto& castersMax = sceneBounds.casters.max;
+ const bool haveCasters = sceneBounds.casters.valid;
// Hair is layers of cards a few millimetres apart, which a cascade spread over the view cannot tell apart: its texel is as wide as the gap.
// So a perspective sun with cascades of its own also gets one fitted to the hair alone, first in its list (the nearest tile covering a
// fragment wins), and everything that falls inside it, the face under a fringe included, is shadowed at that resolution.
- glm::vec3 hairMin(0.0f), hairMax(0.0f);
- const bool haveHair = perspective && hairWorldBounds(registry, hairMin, hairMax);
+ const auto& hairMin = sceneBounds.hair.min;
+ const auto& hairMax = sceneBounds.hair.max;
+ const bool haveHair = sceneBounds.hair.valid;
f32 nearDist = 0.0f, farDist = 1.0f;
if (perspective) {
diff --git a/src/esengine/renderer/frame/RenderFrame.hpp b/src/esengine/renderer/frame/RenderFrame.hpp
index f84e2f5e3..51b398e76 100644
--- a/src/esengine/renderer/frame/RenderFrame.hpp
+++ b/src/esengine/renderer/frame/RenderFrame.hpp
@@ -1,5 +1,9 @@
// SPDX-License-Identifier: Apache-2.0
// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
+/**
+ * @file RenderFrame.hpp
+ * @brief Frame resources and the shared scene rendering contract.
+ */
#pragma once
#include "../../core/Types.hpp"
@@ -875,12 +879,18 @@ private:
/// to give back.
void releaseFrameTargets();
- /// The world box the resident meshes occupy — what a shadow map must cover.
- /// False when nothing 3D is in the scene.
- bool meshWorldBounds(ecs::Registry& registry, glm::vec3& outMin, glm::vec3& outMax, bool castersOnly = false);
- /// The box the meshes drawn with a hair-shadow material occupy (MaterialStore::hairShadowDensity above zero), or false when there are none:
- /// what the sun's focus cascade is fitted to.
- bool hairWorldBounds(ecs::Registry& registry, glm::vec3& outMin, glm::vec3& outMax);
+ struct MeshBounds {
+ glm::vec3 min{0.0f}, max{0.0f};
+ bool valid = false;
+ void include(const glm::vec3& centre, const glm::vec3& half) {
+ min = valid ? glm::min(min, centre - half) : centre - half;
+ max = valid ? glm::max(max, centre + half) : centre + half;
+ valid = true;
+ }
+ };
+ struct ShadowBounds { MeshBounds all, casters, hair; };
+ /// One traversal supplies receiver coverage, caster depth and the hair focus cascade from the geometry actually drawn.
+ ShadowBounds gatherShadowBounds(ecs::Registry& registry, bool includeHair);
/// Opens the frame's own target with @p clear's load-op, for begin() to bind it
/// eagerly. Every other pass of the frame is the graph's to open.
void openPass(const PassClear& clear, RenderTargetManager::Handle target);
diff --git a/src/esengine/renderer/plugins/MeshPlugin.cpp b/src/esengine/renderer/plugins/MeshPlugin.cpp
index 0c86df618..fa18fa934 100644
--- a/src/esengine/renderer/plugins/MeshPlugin.cpp
+++ b/src/esengine/renderer/plugins/MeshPlugin.cpp
@@ -1,5 +1,9 @@
// SPDX-License-Identifier: Apache-2.0
// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
+/**
+ * @file MeshPlugin.cpp
+ * @brief Collect mesh geometry for scene, shadow, depth and motion passes.
+ */
#include "MeshPlugin.hpp"
#include "../draw/BatchBuilder.hpp"
#include "../store/MaterialStore.hpp"
@@ -16,6 +20,7 @@
#include "../draw/BillboardFacing.hpp"
#include "../draw/ImpostorFrames.hpp"
#include "../draw/PlacementBounds.hpp"
+#include "../draw/MeshGeometry.hpp"
#include "../draw/BatchBuilder.hpp"
#include "../../ecs/components/Impostor.hpp"
#include "../../resource/Mesh.hpp"
@@ -176,70 +181,6 @@ bool morphShapes(ecs::Registry& registry, Entity entity, const Mesh& mesh,
return true;
}
-/**
- * @brief The levels a group can actually be drawn at, in the order they take over.
- *
- * @details Entry 0 is the renderer's own mesh: a group says what may STAND IN for
- * it. `localMin/Max` are the UNION over every entry, so what is measured
- * does not change with what is drawn — bounds read off the current level
- * feed back into the choice that picked it and oscillate.
- */
-struct LodLevels {
- const Mesh* mesh[lod::kMaxStandIns + 1]{};
- lod::LevelSet set;
- glm::vec3 localMin{0.0f};
- glm::vec3 localMax{0.0f};
- /// A slot filled after an empty one, which nothing will ever select.
- bool gap = false;
- /// Thresholds that do not descend, or a stand-in the base's skeleton cannot pose.
- bool disordered = false;
- bool skinMismatch = false;
-};
-
-/**
- * @brief Reads a group into the levels it can be drawn at. False when it declares
- * neither a usable stand-in nor a cull size, which leaves the renderer's own
- * mesh the whole answer. A group with only a cull size is a real one: the
- * mesh itself to a distance, then nothing (a tuft of grass has no cheaper
- * version, and still is not worth drawing past sixty metres).
- */
-bool gatherLodLevels(resource::ResourceManager& resources, const ecs::LODGroup& group,
- const Mesh& base, LodLevels& out) {
- out = LodLevels{};
- out.mesh[0] = &base;
- out.localMin = base.localMin;
- out.localMax = base.localMax;
- out.set.cull = group.cullSize;
- out.set.hysteresis = group.hysteresis;
-
- const resource::MeshHandle handles[lod::kMaxStandIns] = {group.lod1, group.lod2, group.lod3};
- const f32 sizes[lod::kMaxStandIns] = {group.lod1Size, group.lod2Size, group.lod3Size};
- for (u8 i = 0; i < lod::kMaxStandIns; ++i) {
- const Mesh* standIn = handles[i].isValid() ? resources.getMesh(handles[i]) : nullptr;
- if (!standIn || !standIn->isDrawable()) {
- // Ordered slots: a level nothing hands over TO is a level nothing
- // reaches, so the run ends here and a later one is an authoring gap.
- for (u8 j = static_cast<u8>(i + 1); j < lod::kMaxStandIns; ++j) {
- if (handles[j].isValid()) out.gap = true;
- }
- break;
- }
- if (base.isSkinned() && standIn->inverseBind.size() != base.inverseBind.size()) {
- out.skinMismatch = true;
- break;
- }
- if (i > 0 && sizes[i] >= sizes[i - 1]) out.disordered = true;
- out.mesh[i + 1] = standIn;
- out.set.takeOver[i] = sizes[i];
- out.set.count = static_cast<u8>(i + 1);
- out.localMin = glm::min(out.localMin, standIn->localMin);
- out.localMax = glm::max(out.localMax, standIn->localMax);
- }
- // A skin whose stand-in the skeleton cannot pose is refused whole: a cull size alone is not a reason to keep a group that was authored against
- // levels it cannot have.
- return out.set.count > 0 || (out.set.cull > 0.0f && !out.skinMismatch);
-}
-
/** @brief Says once what a group declares that nothing will ever use. */
void reportLodAuthoring(const LodLevels& levels, bool& warned) {
if (warned || !(levels.gap || levels.disordered || levels.skinMismatch)) return;
@@ -824,19 +765,15 @@ void MeshPlugin::collect(RenderCollectContext& collect_ctx) {
const f32 bend = material ? ctx.materials->vertexBounds(mesh.material) : 0.0f;
const bool depthTested = mesh.opaque || (material && material->depthTest);
- const Mesh* placementCoarse = placements && placements->lod1Mesh.isValid()
- ? ctx.resources.getMesh(placements->lod1Mesh) : nullptr;
- if (placementCoarse && (!placementCoarse->isDrawable() || placementCoarse->hasNormals != resident->hasNormals
- || placementCoarse->hasTangents != resident->hasTangents
- || placementCoarse->hasLightmapUV != resident->hasLightmapUV)) placementCoarse = nullptr;
+ const Mesh* placementCoarse = placements ? placementCoarseMesh(ctx.resources, *resident, *placements) : nullptr;
f32 placementRadius = 0.0f;
glm::vec3 placementCentre(0.0f), placementHalf(0.0f);
if (placements) {
- const glm::vec3 lo = placementCoarse ? glm::min(resident->localMin, placementCoarse->localMin) : resident->localMin;
- const glm::vec3 hi = placementCoarse ? glm::max(resident->localMax, placementCoarse->localMax) : resident->localMax;
- placementRadius = placement_bounds::radius(lo, hi, bend);
+ glm::vec3 lo, hi;
+ meshLocalBounds(*resident, placementCoarse, bend, lo, hi);
+ placementRadius = placement_bounds::radius(lo, hi, 0.0f);
placementCentre = (lo + hi) * 0.5f;
- placementHalf = (hi - lo) * 0.5f + glm::vec3(bend);
+ placementHalf = (hi - lo) * 0.5f;
}
// Placements can rotate or shear independently. One origin-centred sphere includes both LODs and local deformation.
const glm::vec3 reach(placements ? placementRadius * placements->maxScale : 0.0f);
diff --git a/tools/renderScenes.mjs b/tools/renderScenes.mjs
index a00532233..98f421b22 100644
--- a/tools/renderScenes.mjs
+++ b/tools/renderScenes.mjs
@@ -56,6 +56,39 @@ export function sceneWatchdogMs(backend, host) {
* verbatim — an empty one is the default sprite scene.
*/
export const SCENES = [
+ ...[
+ { id: 'mesh-shadow-placements', scene: 'mesh-shadow', shadowX: 0.708 },
+ { id: 'mesh-shadow-placements-perspective', scene: 'mesh-shadow-perspective', shadowX: 0.86 },
+ ].map(test => ({
+ id: test.id, tier: 'pr', webgpu: true,
+ env: {
+ ESTELLA_VERIFY_SCENE: `/scenes/${test.scene}.esscene`,
+ ESTELLA_VERIFY_W: '256', ESTELLA_VERIFY_H: '256', ESTELLA_VERIFY_STEPS: '3',
+ ESTELLA_VERIFY_PLACEMENTS: JSON.stringify([
+ { entity: 1, transforms: [600, 0, 0, 0, 0, 600, 0, 0, 0, 0, 1, -200, 1, 1, 1, 1] },
+ { entity: 2, transforms: [150, 0, 0, 0, 0, 150, 0, 0, 0, 0, 1, 0, 1, 1, 1, 1] },
+ ]),
+ ESTELLA_VERIFY_SET_FIELD: JSON.stringify([1, 2].flatMap(entity => [
+ { entity, component: 'Transform', key: 'position', value: { x: 0, y: 0, z: 0 } },
+ { entity, component: 'Transform', key: 'scale', value: { x: 1, y: 1, z: 1 } },
+ ])),
+ ESTELLA_VERIFY_EXPECT: JSON.stringify([
+ { x: test.shadowX, y: 0.5, rgb: [0, 0, 0], tol: 20 },
+ { x: 0.1, y: 0.5, rgb: [228, 228, 228], tol: 20 },
+ ]),
+ },
+ })),
+ {
+ id: 'shadow-vertex-displacement', tier: 'pr', webgpu: true,
+ env: {
+ ESTELLA_VERIFY_SCENE: '/scenes/placement-shadow-bend.esscene',
+ ESTELLA_VERIFY_W: '256', ESTELLA_VERIFY_H: '256', ESTELLA_VERIFY_STEPS: '3',
+ ESTELLA_VERIFY_EXPECT: JSON.stringify([
+ { x: 0.5, y: 0.5, rgb: [0, 0, 0], tol: 20 },
+ { x: 0.1, y: 0.5, rgb: [255, 255, 255], tol: 20 },
+ ]),
+ },
+ },
...[
{ id: 'placements-bent', entity: 2, projection: 1, records: [1, 0, 0, -300, 0, 1, 0, 0, 0, 0, 1, 0, 1, 1, 1, 1], x: 0.5, y: 0.5, coarse: 0 },
{ id: 'placements-bent-scaled', entity: 2, projection: 1, records: [3, 0, 0, -900, 0, 3, 0, 0, 0, 0, 3, 0, 1, 1, 1, 1], x: 0.5, y: 0.5, coarse: 0 },
diff --git a/tools/tests/placement-shadows.e2e.mjs b/tools/tests/placement-shadows.e2e.mjs
new file mode 100644
index 000000000..57d0f69c2
--- /dev/null
+++ b/tools/tests/placement-shadows.e2e.mjs
@@ -0,0 +1,104 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
+/**
+ * @file placement-shadows.e2e.mjs
+ * @brief Compare shadow coverage before and after native mesh instancing.
+ */
+import { chromium } from 'playwright';
+import { readFile, writeFile, mkdir } from 'node:fs/promises';
+import { createRequire } from 'node:module';
+import { fileURLToPath } from 'node:url';
+import path from 'node:path';
+import assert from 'node:assert/strict';
+import { serveHost } from '../lib/staticServer.mjs';
+import { requireCurrentEngine } from '../lib/engineBuild.mjs';
+
+const { PNG } = createRequire(new URL('../../pipeline/package.json', import.meta.url))('pngjs');
+const root = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '../..');
+const host = path.join(root, 'build/render-host');
+const out = path.join(root, 'output/placement-shadows');
+requireCurrentEngine(root, path.join(host, 'wasm'));
+await mkdir(out, { recursive: true });
+const server = await serveHost(host);
+const browser = await chromium.launch({ channel: 'chromium', headless: true,
+ args: ['--enable-unsafe-webgpu', '--ignore-gpu-blocklist', '--enable-unsafe-swiftshader', '--mute-audio'] });
+const report = { status: 'failed', checks: [] };
+try {
+ for (const backend of process.argv.includes('--webgl-only') ? ['webgl2'] : ['webgl2', 'webgpu']) {
+ const page = await browser.newPage({ viewport: { width: 256, height: 256 } });
+ const errors = [];
+ page.on('pageerror', error => errors.push(String(error)));
+ page.on('console', event => { if (event.type() === 'error') errors.push(event.text()); });
+ await page.route('**/favicon.ico', route => route.fulfill({ status: 204 }));
+ for (const scene of ['mesh-shadow', 'mesh-shadow-perspective', 'mesh-shadow-cascade', 'mesh-shadow-caster-behind',
+ 'mesh-shadow-tilt-sun', 'point-shadow-pair', 'spot-shadow', 'placement-shadow-bend']) {
+ // Scene loading appends entities, so each independent fixture gets a fresh world.
+ await page.goto(`http://127.0.0.1:${server.address().port}/?w=256&h=256&backend=${backend}`);
+ await page.evaluate(async () => { await window.__estellaHeadless.ready; });
+ const document = JSON.parse(await readFile(path.join(root, 'fixtures/scenes', `${scene}.esscene`), 'utf8'));
+ const meshes = document.entities.filter(entity => entity.components.some(c => c.type === 'MeshRenderer'));
+ assert.ok(meshes.every(entity => entity.parent == null), 'The fixture conversion requires unparented meshes');
+ const loaded = await page.evaluate(scene => window.__estellaHeadless.api.loadScene(`/scenes/${scene}.esscene`), scene);
+ assert.deepEqual(loaded.missing, []);
+ const capture = async suffix => {
+ const raw = await page.evaluate(async () => {
+ const { api } = window.__estellaHeadless;
+ await api.step(2);
+ if (!await api.waitForShaders()) throw new Error('Shader compilation did not finish');
+ await api.step(2);
+ const image = await api.captureViewportPixels();
+ return { width: image.width, height: image.height, rgba: Array.from(image.rgba) };
+ });
+ const image = new PNG({ width: raw.width, height: raw.height });
+ const bytes = Buffer.from(raw.rgba), stride = raw.width * 4;
+ for (let y = 0; y < raw.height; y++) bytes.copy(image.data, y * stride, (raw.height - y - 1) * stride, (raw.height - y) * stride);
+ await writeFile(path.join(out, `${backend}-${scene}-${suffix}.png`), PNG.sync.write(image));
+ return image.data;
+ };
+ const reference = await capture('individual');
+ const shadowPresent = scene === 'placement-shadow-bend' ? reference[(128 * 256 + 128) * 4] < 20 : undefined;
+ await page.evaluate(async meshes => {
+ const { api } = window.__estellaHeadless;
+ for (const entity of meshes) {
+ const transform = entity.components.find(c => c.type === 'Transform')?.data ?? {};
+ const p = transform.position ?? { x: 0, y: 0, z: 0 };
+ const s = transform.scale ?? { x: 1, y: 1, z: 1 };
+ const q = transform.rotation ?? { x: 0, y: 0, z: 0, w: 1 };
+ const { x, y, z, w } = q;
+ api.setMeshPlacements(entity.id, [
+ (1 - 2 * (y * y + z * z)) * s.x, 2 * (x * y - w * z) * s.y, 2 * (x * z + w * y) * s.z, p.x,
+ 2 * (x * y + w * z) * s.x, (1 - 2 * (x * x + z * z)) * s.y, 2 * (y * z - w * x) * s.z, p.y,
+ 2 * (x * z - w * y) * s.x, 2 * (y * z + w * x) * s.y, (1 - 2 * (x * x + y * y)) * s.z, p.z,
+ 1, 1, 1, 1,
+ ]);
+ await api.setField(entity.id, 'Transform', 'position', '', { x: 0, y: 0, z: 0 });
+ await api.setField(entity.id, 'Transform', 'rotation', '', { x: 0, y: 0, z: 0, w: 1 });
+ await api.setField(entity.id, 'Transform', 'scale', '', { x: 1, y: 1, z: 1 });
+ }
+ }, meshes);
+ const instances = await capture('instances');
+ let changed = 0, maxChannel = 0, litPixels = 0;
+ for (let i = 0; i < reference.length; i += 4) {
+ const delta = Math.max(...[0, 1, 2].map(c => Math.abs(reference[i + c] - instances[i + c])));
+ maxChannel = Math.max(maxChannel, delta);
+ if (delta > 2) changed++;
+ if (reference[i] > 100 && reference[i + 1] > 100 && reference[i + 2] > 100) litPixels++;
+ }
+ assert.ok(litPixels > 1000, 'The reference must contain a visible lit receiver');
+ report.checks.push({ backend, scene, changed, maxChannel, shadowPresent });
+ console.log(JSON.stringify(report.checks.at(-1)));
+ }
+ assert.deepEqual(errors, []);
+ await page.close();
+ }
+ assert.ok(report.checks.every(row => row.changed === 0 && row.shadowPresent !== false),
+ 'Instancing must preserve shadow coverage, including deformed casters behind the camera');
+ report.status = 'checks-passed';
+} catch (error) {
+ report.error = String(error);
+ throw error;
+} finally {
+ await writeFile(path.join(out, 'report.json'), JSON.stringify(report, null, 2));
+ await browser.close();
+ await new Promise(resolve => server.close(resolve));
+}