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.

perf(renderer): a shadow face outside the geometry stops gathering it mesh by mesh

yhhb2eb7e41805f
diff --git a/fixtures/scenes/point-shadow-offset.esscene b/fixtures/scenes/point-shadow-offset.esscene
new file mode 100644
index 000000000..f8f10182d
--- /dev/null
+++ b/fixtures/scenes/point-shadow-offset.esscene
@@ -0,0 +1,34 @@
+{
+ "version": 3,
+ "name": "PointShadowOffset",
+ "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": "Ground", "parent": null, "children": [], "visible": true,
+ "components": [
+ { "type": "Transform", "data": { "position": { "x": -60, "y": 0, "z": -150 }, "scale": { "x": 320, "y": 100, "z": 1 } } },
+ { "type": "MeshRenderer", "data": { "mesh": "/scenes/shadow-quad.esmesh", "color": { "r": 1, "g": 1, "b": 1, "a": 1 }, "lit": true, "opaque": true, "enabled": true } }
+ ]
+ },
+ {
+ "id": 2, "name": "Blocker", "parent": null, "children": [], "visible": true,
+ "components": [
+ { "type": "Transform", "data": { "position": { "x": -90, "y": 0, "z": -80 }, "scale": { "x": 60, "y": 60, "z": 1 } } },
+ { "type": "MeshRenderer", "data": { "mesh": "/scenes/shadow-quad.esmesh", "color": { "r": 1, "g": 1, "b": 1, "a": 1 }, "lit": true, "opaque": true, "enabled": true } }
+ ]
+ },
+ {
+ "id": 3, "name": "Lamp", "parent": null, "children": [], "visible": true,
+ "components": [
+ { "type": "Transform", "data": { "position": { "x": 0, "y": 0, "z": 0 } } },
+ { "type": "Light", "data": { "type": 0, "color": { "r": 1, "g": 1, "b": 1, "a": 1 }, "intensity": 1, "radius": 600, "meshShadows": true } }
+ ]
+ }
+ ]
+}
diff --git a/src/esengine/renderer/RenderTypePlugin.hpp b/src/esengine/renderer/RenderTypePlugin.hpp
index 0642de74e..c3864c598 100644
--- a/src/esengine/renderer/RenderTypePlugin.hpp
+++ b/src/esengine/renderer/RenderTypePlugin.hpp
@@ -15,6 +15,8 @@
#include "../resource/ResourceManager.hpp"
#include <glm/glm.hpp>
+#include <glm/gtc/matrix_access.hpp>
+#include <glm/gtc/quaternion.hpp>
#include <cmath>
@@ -116,6 +118,28 @@ inline glm::vec2 flatTurnZ(const glm::quat& rotation) {
2.0f * rotation.w * rotation.z / n};
}
+/**
+ * @brief The world AABB of a turned box: its centre and half-extents, from a local
+ * box and the position, rotation and scale that place it.
+ *
+ * @details Each axis takes |R| * halfExtents, which is exact for a box. One function
+ * because two things derive it — a mesh's cull and a shadow map's fit — and
+ * a rotation dropped from either bounds a model by a box smaller than itself.
+ */
+inline void orientedWorldAabb(const glm::vec3& position, const glm::quat& rotation,
+ const glm::vec3& scale, const glm::vec3& localMin,
+ const glm::vec3& localMax, glm::vec3& outCentre,
+ glm::vec3& outHalf) {
+ const glm::mat3 basis = glm::mat3_cast(rotation);
+ const glm::vec3 scaledHalf = glm::abs((localMax - localMin) * 0.5f * scale);
+ outCentre = position + basis * ((localMin + localMax) * 0.5f * scale);
+ outHalf = {
+ glm::dot(glm::abs(glm::row(basis, 0)), scaledHalf),
+ glm::dot(glm::abs(glm::row(basis, 1)), scaledHalf),
+ glm::dot(glm::abs(glm::row(basis, 2)), scaledHalf),
+ };
+}
+
/**
* @brief World AABB half-extents of a flat box turned by @p turn (from flatTurnZ).
* |R| * half, exact for a box. An unturned entity gets @p half back, so the
diff --git a/src/esengine/renderer/frame/RenderFrame.cpp b/src/esengine/renderer/frame/RenderFrame.cpp
index 4042e4aca..da5e5129c 100644
--- a/src/esengine/renderer/frame/RenderFrame.cpp
+++ b/src/esengine/renderer/frame/RenderFrame.cpp
@@ -821,9 +821,9 @@ 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 has to cover, casters and receivers alike. Rotation is ignored,
-/// the same approximation MeshPlugin's own cull uses.
+/// 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. Each mesh
+/// contributes the box MeshPlugin culls it by, so a frustum missing this misses all.
bool RenderFrame::meshWorldBounds(ecs::Registry& registry, glm::vec3& outMin, glm::vec3& outMax) {
auto meshes = registry.view<ecs::Transform, ecs::MeshRenderer>();
bool any = false;
@@ -834,10 +834,9 @@ bool RenderFrame::meshWorldBounds(ecs::Registry& registry, glm::vec3& outMin, gl
if (!resident) continue;
auto& transform = meshes.get<ecs::Transform>(entity);
transform.ensureDecomposed();
- const glm::vec3 scale = transform.worldScale;
- const glm::vec3 centre = transform.worldPosition
- + (resident->localMin + resident->localMax) * 0.5f * scale;
- const glm::vec3 half = glm::abs((resident->localMax - resident->localMin) * 0.5f * scale);
+ glm::vec3 centre(0.0f), half(0.0f);
+ orientedWorldAabb(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;
@@ -997,6 +996,7 @@ void RenderFrame::renderShadowMap(ecs::Registry& registry) {
// face that stopped being skipped would look exactly like one that never was.
u32 shadowTiles = 0;
u32 shadowDraws = 0;
+ u32 shadowCollects = 0;
for (usize ci = 0; ci < shadow_casters_.size(); ++ci) {
const ShadowCaster& caster = shadow_casters_[ci];
@@ -1094,11 +1094,20 @@ void RenderFrame::renderShadowMap(ecs::Registry& registry) {
// is derived there out of this matrix and the size of the square.
tiles[tileIndex] = shadow_atlas_.unitRect(tileIndex);
+ view_projection_ = projection;
+ frustum_.extractFromMatrix(projection);
+ // A face whose frustum misses the whole of the geometry gathers nothing, and
+ // asking each mesh in turn is the only way to find that out otherwise. The
+ // box every mesh is inside answers it once, for the price of one test.
+ if (haveBounds && !frustum_.intersectsAABB((boundsMin + boundsMax) * 0.5f,
+ (boundsMax - boundsMin) * 0.5f)) {
+ continue;
+ }
+ ++shadowCollects;
+
// What the tile would hold, gathered before a pass is opened for it. Only
// the plugins that cast are asked: a map holds depth, and everything else
// would write colour into a texture every receiver reads back as one.
- view_projection_ = projection;
- frustum_.extractFromMatrix(projection);
pool_.beginFrame();
draw_list_.clear();
@@ -1153,6 +1162,7 @@ void RenderFrame::renderShadowMap(ecs::Registry& registry) {
ES_PROFILE_COUNTER("render.shadow.tiles", shadowTiles);
ES_PROFILE_COUNTER("render.shadow.draws", shadowDraws);
+ ES_PROFILE_COUNTER("render.shadow.collects", shadowCollects);
rt->unbind();
device_.invalidatePipelineCache();
diff --git a/src/esengine/renderer/plugins/MeshPlugin.cpp b/src/esengine/renderer/plugins/MeshPlugin.cpp
index 4f834da39..e833e149d 100644
--- a/src/esengine/renderer/plugins/MeshPlugin.cpp
+++ b/src/esengine/renderer/plugins/MeshPlugin.cpp
@@ -178,7 +178,13 @@ void MeshPlugin::collect(RenderCollectContext& collect_ctx) {
if (!mesh.enabled || (mesh.indices.empty() && !mesh.mesh.isValid())) continue;
auto& transform = meshView.get<ecs::Transform>(entity);
- glm::vec3 position = parallaxedWorldPosition(transform, mesh.parallax, collect_ctx.camera);
+ // Parallax is a CAMERA trick — a renderable shifted toward the view centre to
+ // scroll slower. A shadow pass looks from a light, whose centre means nothing to
+ // it, and its map is fitted to unshifted bounds: a caster stands where it is.
+ transform.ensureDecomposed();
+ const glm::vec3 position = ctx.shadow_pass
+ ? transform.worldPosition
+ : parallaxedWorldPosition(transform, mesh.parallax, collect_ctx.camera);
const auto& rotation = transform.worldRotation;
const auto& scale = transform.worldScale;
@@ -193,19 +199,8 @@ void MeshPlugin::collect(RenderCollectContext& collect_ctx) {
const glm::vec3 localMin = resident ? resident->localMin : glm::vec3(mesh.localMin, 0.0f);
const glm::vec3 localMax = resident ? resident->localMax : glm::vec3(mesh.localMax, 0.0f);
- // The world AABB of the ORIENTED box: each axis takes |R| * halfExtents,
- // exact for a box. Ignoring the rotation bounds a turned model by a box
- // smaller than itself, so it vanishes while still partly on screen.
- const glm::vec3 localCenter = (localMin + localMax) * 0.5f;
- const glm::vec3 localHalf = (localMax - localMin) * 0.5f;
- const glm::mat3 basis = glm::mat3_cast(rotation);
- const glm::vec3 scaledHalf = glm::abs(localHalf * scale);
- const glm::vec3 aabbCenter = position + basis * (localCenter * scale);
- const glm::vec3 halfExtents{
- glm::dot(glm::abs(glm::row(basis, 0)), scaledHalf),
- glm::dot(glm::abs(glm::row(basis, 1)), scaledHalf),
- glm::dot(glm::abs(glm::row(basis, 2)), scaledHalf),
- };
+ glm::vec3 aabbCenter(0.0f), halfExtents(0.0f);
+ orientedWorldAabb(position, rotation, scale, localMin, localMax, aabbCenter, halfExtents);
if (!frustum.intersectsAABB(aabbCenter, halfExtents)) continue;
u32 textureId = ctx.white_texture_id;
diff --git a/tools/renderScenes.mjs b/tools/renderScenes.mjs
index a076f4f3a..fc752ad71 100644
--- a/tools/renderScenes.mjs
+++ b/tools/renderScenes.mjs
@@ -110,6 +110,10 @@ export const SCENES = [
// sprite stands opposite a mesh blocker, both between lamp and floor: black unpacks as
// depth 0, so a collected sprite would shadow its half — which has to come back lit.
{ id: "shadow-map-meshes-only", tier: "pr", webgpu: true, env: { ESTELLA_VERIFY_SCENE: "/scenes/shadow-map-meshes-only.esscene", ESTELLA_VERIFY_W: "256", ESTELLA_VERIFY_H: "256", ESTELLA_VERIFY_STEPS: "2", ESTELLA_VERIFY_EXPECT: "[{\"x\":0.167,\"y\":0.5,\"rgb\":[102,102,102],\"tol\":20},{\"x\":0.833,\"y\":0.5,\"rgb\":[0,0,0],\"tol\":20},{\"x\":0.667,\"y\":0.5,\"rgb\":[108,108,108],\"tol\":25},{\"x\":0.5,\"y\":0.5,\"rgb\":[242,242,242],\"tol\":20}]" } },
+ // A lamp with every mesh off to one side. Four of its six faces miss the box the whole
+ // of the geometry sits in and never gather at all; a fifth gathers and comes back empty.
+ // Both skips are invisible in a pixel, which is what the two counters are here for.
+ { id: "point-shadow-offset", tier: "pr", webgpu: true, env: { ESTELLA_VERIFY_SCENE: "/scenes/point-shadow-offset.esscene", ESTELLA_VERIFY_W: "256", ESTELLA_VERIFY_H: "256", ESTELLA_VERIFY_STEPS: "2", ESTELLA_VERIFY_COUNTERS: "{\"render.shadow.tiles\":2,\"render.shadow.collects\":3}", ESTELLA_VERIFY_EXPECT: "[{\"x\":0.20,\"y\":0.5,\"rgb\":[0,0,0],\"tol\":20},{\"x\":0.35,\"y\":0.5,\"rgb\":[135,135,135],\"tol\":25},{\"x\":0.5,\"y\":0.5,\"rgb\":[191,191,191],\"tol\":25},{\"x\":0.6,\"y\":0.5,\"rgb\":[173,173,173],\"tol\":25}]" } },
// TWO point lights, which nothing else in the corpus has: twelve faces claimed from a
// sixteen-cell atlas, ten of them drawn. The dark probes are dim and not black because the
// far lamp reaches that floor past the near blocker — the second map read, not a leak.