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
feat(render): a spot light casts a real shadow map
yhh2fd87a2b6704
diff --git a/CHANGELOG.md b/CHANGELOG.mdindex 65e4e3b1e..9ca3484d1 100644--- a/CHANGELOG.md+++ b/CHANGELOG.md@@ -14,6 +14,32 @@ published separately; it ships inside the editor.## [Unreleased]+### Added++- **A spot light casts a real shadow map.** Until now exactly one light in a scene+ could cast one, and it had to be the sun: everything else fell back to the+ world-space boxes of `ShadowCaster2D`, which know nothing about the meshes in front+ of them. A spot now claims a tile from the atlas and renders its cone through the+ same pass a cascade goes through — the same collect, the same vertex stage, the same+ depth packing — differing only in the projection it hands over.++ That projection is the cone as the frustum it is, with clip z running `[0, 1]` over+ `[near, far]`, for the reason the orthographic one is written out by hand: a+ GL-convention perspective puts half its volume below zero and the second backend+ discards it. The near plane is a fraction of the light's reach rather than a+ constant, so where the depth spends its precision follows the scene's scale instead+ of a number.++ Who gets a tile is a decision now rather than an accident of the code: spots reserve+ one cell each first, and the sun takes as many cascades as still fit, so a scene with+ spot shadows loses its farthest directional slice rather than losing the spots.++ Gate `spot-shadow`, both backends: a spot above and to the left of a blocker, and the+ ground it throws onto. The shadow is offset from the caster — a point light projects+ rather than sweeps — and the probes either side of x = 162 are where its edge lands.+ Verified against the defect: with `meshShadows` off the shadowed probe reads 163+ instead of 0 while the three lit probes do not move at all.+### Changed- **A shadow map lands where the atlas says, and a light reads its own.** Two facts@@ -88,6 +114,23 @@ published separately; it ships inside the editor.### Fixed+- **A cone's shadow bias is derived from a cone's depth.** The bias every tile got was+ `1/range` per world unit — true of an orthographic map, whose depth is linear in+ distance, and wrong by orders of magnitude for a perspective one, whose depth is+ hyperbolic and nearly flat at the far plane. The first spot map rendered correctly+ and then shadowed nothing: its bias came out at 0.047 against a real depth difference+ of 0.004. A projection reports `depthPerWorld` now — `1/range` for the orthographic+ case, `near/(far*(far-near))` for the cone — so there is one bias expression and the+ difference between the two lives in one number. The orthographic value is unchanged+ to the bit.++- **A spot's aim is stored as it is.** A cone with no component in the plane got the+ substitute `(0, -1)` written into its data, because the plane's half of the shading+ has nowhere else to read an axis from. That substitute then tilted the+ THREE-dimensional axis too: a spot aimed straight down had its 3D cone come out at 45+ degrees. The fallback moved into the shader, where the plane's convention is applied;+ `ES_SURFACE_3D` reads the aim the light actually has.+- **A frame is given a depth buffer by what it draws, not by a setting that stoppedcovering it.** An opaque mesh has declared its own depth test and write since itstopped waiting for a depth layer to grant them (`MeshPlugin.cpp:240`, "an opaquediff --git a/desktop/public/scenes/spot-shadow.esscene b/desktop/public/scenes/spot-shadow.esscenenew file mode 100644index 000000000..23ad95b26--- /dev/null+++ b/desktop/public/scenes/spot-shadow.esscene@@ -0,0 +1,34 @@+{+ "version": 1,+ "name": "SpotShadow",+ "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": 0, "y": 0, "z": -200 }, "scale": { "x": 600, "y": 600, "z": 1 } } },+ { "type": "Mesh2D", "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": 0, "y": 0, "z": 0 }, "scale": { "x": 150, "y": 150, "z": 1 } } },+ { "type": "Mesh2D", "data": { "mesh": "/scenes/shadow-quad.esmesh", "color": { "r": 1, "g": 1, "b": 1, "a": 1 }, "lit": true, "opaque": true, "enabled": true } }+ ]+ },+ {+ "id": 3, "name": "Spot", "parent": null, "children": [], "visible": true,+ "components": [+ { "type": "Transform", "data": { "position": { "x": -100, "y": 0, "z": 400 } } },+ { "type": "Light2D", "data": { "type": 3, "color": { "r": 1, "g": 1, "b": 1, "a": 1 }, "intensity": 1, "radius": 2000, "innerAngle": 80, "outerAngle": 90, "meshShadows": true } }+ ]+ }+ ]+}diff --git a/desktop/public/scenes/spot-shadow.textures.json b/desktop/public/scenes/spot-shadow.textures.jsonnew file mode 100644index 000000000..0967ef424--- /dev/null+++ b/desktop/public/scenes/spot-shadow.textures.json@@ -0,0 +1 @@+{}diff --git a/src/esengine/renderer/frame/RenderFrame.cpp b/src/esengine/renderer/frame/RenderFrame.cppindex a23257269..1183cc89f 100644--- a/src/esengine/renderer/frame/RenderFrame.cpp+++ b/src/esengine/renderer/frame/RenderFrame.cpp@@ -673,7 +673,7 @@ static glm::vec3 lightForward(ecs::Transform* transform) {void RenderFrame::collectLights(ecs::Registry& registry) {LightStore& lights = context_.lights();lights.clear();- shadow_light_slot_ = -1;+ shadow_casters_.clear();environment_texture_id_ = 0;draw_sky_ = false;@@ -682,6 +682,7 @@ void RenderFrame::collectLights(ecs::Registry& registry) {// whichever happened to come last in iteration order. Ambient lights sum without a cap.std::vector<CollectedLight>& collected = light_scratch_;collected.clear();+ bool haveSun = false;// A light's Transform need is type-dependent. Ambient is a flat scene-wide term and// reads none of it; Directional takes only the rotation, so it works without one and@@ -707,6 +708,7 @@ void RenderFrame::collectLights(ecs::Registry& registry) {GpuLight2D gpu;bool castsMeshShadow = false;+ ShadowCaster caster;gpu.color = glm::vec4(rgb, light.intensity);// shadow.x = penumbra softness (all types); shadow.y = directional march distance (only the// directional branch of shadowFactor2D reads it; 0 keeps directional shadows off).@@ -718,10 +720,14 @@ void RenderFrame::collectLights(ecs::Registry& registry) {// that slot on their falloff radius.const glm::vec3 aim = lightForward(registry.tryGet<ecs::Transform>(entity));gpu.posDir = glm::vec4(aim.x, aim.y, 1.0f, aim.z);- if (light.meshShadows && shadow_light_slot_ < 0) {+ // One sun: a second set of cascades would claim the atlas a first one is+ // already spending, and two suns is not a scene anybody authors.+ if (light.meshShadows && !haveSun) {+ haveSun = true;castsMeshShadow = true;- shadow_light_dir_ = aim;- shadow_light_extent_ = std::max(light.shadowExtent, 0.0f);+ caster.directional = true;+ caster.dir = aim;+ caster.extent = std::max(light.shadowExtent, 0.0f);}} else { // Point / Spot — world position from the Transform, w=falloff radius.auto* transform = registry.tryGet<ecs::Transform>(entity);@@ -738,18 +744,26 @@ void RenderFrame::collectLights(ecs::Registry& registry) {// Split across two slots because the two shading halves read different// parts: the plane's xy, and the whole of it in three.const glm::vec3 aim = lightForward(transform);- // A cone aimed straight into the screen has no axis IN the plane, and the- // plane's half of the shading has nowhere else to read one from — so it- // keeps the direction an unrotated spot has always lit along.- glm::vec2 planar(aim.x, aim.y);- if (glm::dot(planar, planar) <= 1e-8f) planar = glm::vec2(0.0f, -1.0f);- gpu.spot = glm::vec4(planar.x, planar.y,+ // The aim as it IS. A cone with no component in the plane needs a+ // substitute there, but that belongs where the plane's convention is+ // applied — stored, it tilts the three-dimensional axis as well.+ gpu.spot = glm::vec4(aim.x, aim.y,std::cos(glm::radians(light.innerAngle * 0.5f)),std::cos(glm::radians(light.outerAngle * 0.5f)));gpu.shadow.w = aim.z;+ // A cone's map is the cone: where it stands, which way it points, how+ // wide it opens and how far it reaches are the whole projection.+ if (light.meshShadows) {+ castsMeshShadow = true;+ caster.directional = false;+ caster.dir = aim;+ caster.pos = p;+ caster.range = std::max(light.radius, 0.0f);+ caster.outerAngle = light.outerAngle;+ }}}- collected.push_back({gpu, castsMeshShadow});+ collected.push_back({gpu, castsMeshShadow, caster});}if (collected.size() > MAX_LIGHTS_2D) {@@ -762,7 +776,11 @@ void RenderFrame::collectLights(ecs::Registry& registry) {collected.resize(MAX_LIGHTS_2D);}for (u32 slot = 0; slot < collected.size(); ++slot) {- if (collected[slot].castsMeshShadow) shadow_light_slot_ = static_cast<i32>(slot);+ if (collected[slot].castsMeshShadow) {+ ShadowCaster caster = collected[slot].caster;+ caster.slot = slot;+ shadow_casters_.push_back(caster);+ }lights.addLight(collected[slot].gpu);}@@ -860,13 +878,48 @@ static f32 splitFraction(u32 i, u32 count, f32 nearDist, f32 farDist) {return (d - nearDist) / std::max(farDist - nearDist, 1e-6f);}+/// One tile's projection and what its depths are worth, so one bias expression serves+/// every kind of light: an orthographic depth is linear in distance and a cone's is+/// not, and `depthPerWorld` is exactly that difference.+struct ShadowProjection {+ glm::mat4 matrix{1.0f};+ /// How much world the map spans across, at its widest.+ f32 radius = 1.0f;+ /// How much stored depth one world unit is worth, where the map is coarsest.+ f32 depthPerWorld = 1.0f;+};++/**+ * The frustum a cone sees, with clip z running [0, 1] over [near, far].+ *+ * @details That range is the point: a GL-convention perspective puts half its volume+ * below zero, which the second backend discards. This matrix is free to be+ * built either way — its depths are only compared against a copy of itself.+ */+static glm::mat4 spotProjection(f32 fovDegrees, f32 nearDist, f32 farDist) {+ const f32 half = glm::radians(std::clamp(fovDegrees, 1.0f, 179.0f) * 0.5f);+ const f32 cot = 1.0f / std::tan(half);+ glm::mat4 proj(0.0f);+ proj[0][0] = cot;+ proj[1][1] = cot;+ proj[2][2] = farDist / (nearDist - farDist);+ proj[2][3] = -1.0f;+ proj[3][2] = (nearDist * farDist) / (nearDist - farDist);+ return proj;+}++/// An up that cannot be parallel to @p dir, whichever way it points.+static glm::vec3 shadowUp(const glm::vec3& dir) {+ return std::abs(dir.z) > 0.99f ? glm::vec3(0.0f, 1.0f, 0.0f) : glm::vec3(0.0f, 0.0f, 1.0f);+}+void RenderFrame::renderShadowMap(ecs::Registry& registry) {shadow_texture_id_ = 0;// Zeroed first, and the atlas given back: a tile that outlived its map would// shadow the scene against geometry from a frame that no longer exists.shadow_atlas_.reset();context_.lights().setShadowTiles(nullptr, nullptr, 0, glm::vec4(0.0f));- if (!in_frame_ || shadow_light_slot_ < 0 || !device_.isDeviceUsable()) return;+ if (!in_frame_ || shadow_casters_.empty() || !device_.isDeviceUsable()) return;if (shadow_rt_ == 0) {shadow_rt_ = target_manager_.create(kShadowAtlasSize, kShadowAtlasSize,@@ -881,9 +934,6 @@ void RenderFrame::renderShadowMap(ecs::Registry& registry) {// an orthographic view already spends its texels evenly over what it can see.const glm::vec4 eye = invVP * glm::vec4(0.0f, 0.0f, 1.0f, 0.0f);const bool perspective = std::abs(eye.w) > 1e-6f;- // A fixed reach is the author saying what the map covers; splitting it would- // hand three quarters of the atlas to slices they never asked for.- const u32 cascades = (perspective && shadow_light_extent_ <= 0.0f) ? MAX_SHADOW_CASCADES : 1;glm::vec3 corners[8];frustumCorners(invVP, corners);@@ -901,143 +951,205 @@ void RenderFrame::renderShadowMap(ecs::Registry& registry) {farDist = std::max(farDist, nearDist * 1.001f);}- // The shader lights a surface from normalize(-aim), so rays travel the other way.- const glm::vec3 toLight = glm::normalize(-shadow_light_dir_);- // An up that cannot be parallel to it, whichever way the light points.- const glm::vec3 up = std::abs(toLight.z) > 0.99f ? glm::vec3(0.0f, 1.0f, 0.0f)- : glm::vec3(0.0f, 0.0f, 1.0f);- // Rotation only, for snapping a centre to the map's grid in the light's own axes.- const glm::mat4 lightRot = glm::lookAt(glm::vec3(0.0f), -toLight, up);- const glm::mat4 lightRotInv = glm::inverse(lightRot);+ // Who gets what. A spot reserves first at one cell, because a sun claiming the+ // atlas whole would leave every other caster mapless; the sun then takes as many+ // cascades as still fit, losing its farthest slice rather than the spots.+ struct TilePlan {+ u32 first = 0;+ u32 count = 0;+ };+ std::vector<TilePlan> plan(shadow_casters_.size());+ for (usize i = 0; i < shadow_casters_.size(); ++i) {+ if (shadow_casters_[i].directional) continue;+ const i32 at = shadow_atlas_.allocate(1, 1);+ if (at >= 0) plan[i] = {static_cast<u32>(at), 1};+ }+ for (usize i = 0; i < shadow_casters_.size(); ++i) {+ const ShadowCaster& caster = shadow_casters_[i];+ if (!caster.directional) continue;+ // A fixed reach is the author saying what the map covers; splitting it would+ // hand the rest of the atlas to slices they never asked for.+ u32 want = (perspective && caster.extent <= 0.0f) ? MAX_SHADOW_CASCADES : 1;+ for (; want > 0; --want) {+ const i32 at = shadow_atlas_.allocate(want, kShadowCascadeCells);+ if (at >= 0) { plan[i] = {static_cast<u32>(at), want}; break; }+ }+ }const glm::mat4 sceneVP = view_projection_;const GfxDevice::Viewport sceneViewport = device_.viewport();- // Every tile this light needs or none of them: half a cascade set leaves the- // rest of the fragments reading depths that belong to somebody else.- const i32 firstTile = shadow_atlas_.allocate(cascades, kShadowCascadeCells);- if (firstTile < 0) return;glm::mat4 matrices[MAX_SHADOW_TILES];glm::vec4 tiles[MAX_SHADOW_TILES];bool cleared = false;-- for (u32 c = 0; c < cascades; ++c) {- const ShadowTile& tile = shadow_atlas_.tile(static_cast<u32>(firstTile) + c);- glm::vec3 centre(0.0f);- f32 radius = 1.0f;- if (cascades == 1) {- // What the map covers: the 3D geometry, unless the light asked for a fixed- // reach. A radius, so coverage does not change as the light turns.- const CameraView view = computeCameraView(sceneVP);- const f32 fitted = haveBounds- ? 0.5f * glm::length(boundsMax - boundsMin)- : 0.5f * glm::length(glm::vec2(view.right - view.left, view.top - view.bottom));- radius = shadow_light_extent_ > 0.0f ? shadow_light_extent_ : std::max(fitted, 1.0f);- centre = haveBounds ? (boundsMin + boundsMax) * 0.5f- : glm::vec3(view.center.x, view.center.y, 0.0f);- } else {- // This slice of the view, as a sphere: a box would grow and shrink as the- // light turns, and the texel density with it.- const f32 t0 = splitFraction(c, cascades, nearDist, farDist);- const f32 t1 = splitFraction(c + 1, cascades, nearDist, farDist);- glm::vec3 slice[8];- for (u32 i = 0; i < 4; ++i) {- const glm::vec3 ray = corners[i + 4] - corners[i];- slice[i] = corners[i] + ray * t0;- slice[i + 4] = corners[i] + ray * t1;+ bool anyTile = false;++ for (usize ci = 0; ci < shadow_casters_.size(); ++ci) {+ const ShadowCaster& caster = shadow_casters_[ci];+ const TilePlan& mine = plan[ci];+ if (mine.count == 0) continue;+ anyTile = true;++ // The shader lights a surface from normalize(-aim), so rays travel the other way.+ const glm::vec3 toLight = glm::normalize(-caster.dir);+ const glm::vec3 up = shadowUp(toLight);+ // Rotation only, for snapping a centre to the map's grid in the light's own axes.+ const glm::mat4 lightRot = glm::lookAt(glm::vec3(0.0f), -toLight, up);+ const glm::mat4 lightRotInv = glm::inverse(lightRot);++ for (u32 c = 0; c < mine.count; ++c) {+ const u32 tileIndex = mine.first + c;+ const ShadowTile& tile = shadow_atlas_.tile(tileIndex);+ ShadowProjection projection;++ if (!caster.directional) {+ // A fraction of the reach and not a constant: a perspective depth+ // spends its precision next to the near plane, and one fixed in world+ // units would put that wherever the scene's scale happened to be.+ const f32 reach = std::max(caster.range, 1e-3f);+ const f32 nearPlane = std::max(reach * 0.005f, 1e-3f);+ projection.matrix = spotProjection(caster.outerAngle, nearPlane, reach)+ * glm::lookAt(caster.pos, caster.pos + caster.dir,+ shadowUp(caster.dir));+ // What the cone covers where it is widest, which is what a texel of+ // this tile is worth — the same two numbers the cascades report.+ projection.radius = std::tan(glm::radians(+ std::clamp(caster.outerAngle, 1.0f, 179.0f) * 0.5f)) * reach;+ // A cone's depth is hyperbolic; at the far plane, flattest and where+ // self-shadowing is worst, a world unit is worth this much of it. An+ // orthographic map's 1/range is the same question of a linear depth.+ projection.depthPerWorld = nearPlane+ / (reach * std::max(reach - nearPlane, 1.0f));+ } else {+ glm::vec3 centre(0.0f);+ f32 radius = 1.0f;+ if (mine.count == 1) {+ // What the map covers: the 3D geometry, unless the light asked for a+ // fixed reach. A radius, so coverage does not change as the light turns.+ const CameraView view = computeCameraView(sceneVP);+ const f32 fitted = haveBounds+ ? 0.5f * glm::length(boundsMax - boundsMin)+ : 0.5f * glm::length(glm::vec2(view.right - view.left,+ view.top - view.bottom));+ radius = caster.extent > 0.0f ? caster.extent : std::max(fitted, 1.0f);+ centre = haveBounds ? (boundsMin + boundsMax) * 0.5f+ : glm::vec3(view.center.x, view.center.y, 0.0f);+ } else {+ // This slice of the view, as a sphere: a box would grow and shrink as+ // the light turns, and the texel density with it.+ const f32 t0 = splitFraction(c, mine.count, nearDist, farDist);+ const f32 t1 = splitFraction(c + 1, mine.count, nearDist, farDist);+ glm::vec3 slice[8];+ for (u32 i = 0; i < 4; ++i) {+ const glm::vec3 ray = corners[i + 4] - corners[i];+ slice[i] = corners[i] + ray * t0;+ slice[i + 4] = corners[i] + ray * t1;+ }+ for (const glm::vec3& p : slice) centre += p;+ centre *= 0.125f;+ for (const glm::vec3& p : slice) {+ radius = std::max(radius, glm::length(p - centre));+ }+ // Snap to the map's own texel grid, in the light's axes: without it the+ // cascade slides continuously with the camera and every shadow edge+ // crawls along the geometry a texel at a time.+ const f32 texel = (radius * 2.0f) / static_cast<f32>(tile.size);+ glm::vec3 inLight = glm::vec3(lightRot * glm::vec4(centre, 1.0f));+ inLight.x = std::floor(inLight.x / texel) * texel;+ inLight.y = std::floor(inLight.y / texel) * texel;+ centre = glm::vec3(lightRotInv * glm::vec4(inLight, 1.0f));+ }++ // ★ How far back the near plane goes. A cascade covers a slice of the VIEW,+ // but what shadows it can stand anywhere between the slice and the light —+ // clip at the slice and the caster is not drawn, and nothing says why.+ f32 castDistance = radius * 2.0f;+ if (haveBounds) {+ for (u32 i = 0; i < 8; ++i) {+ const glm::vec3 corner((i & 1) ? boundsMax.x : boundsMin.x,+ (i & 2) ? boundsMax.y : boundsMin.y,+ (i & 4) ? boundsMax.z : boundsMin.z);+ castDistance = std::max(castDistance, glm::dot(corner - centre, toLight));+ }+ }+ const glm::mat4 lightView = glm::lookAt(centre + toLight * castDistance,+ centre, up);+ // Written out rather than built from math::ortho: this maps the occluders it+ // draws onto exactly [0,1], so it needs no conversion for either device —+ // which is what lets the depths it writes be compared against the receiver's.+ glm::mat4 lightProj(1.0f);+ const f32 range = castDistance + radius * 2.0f;+ lightProj[0][0] = 1.0f / radius;+ lightProj[1][1] = 1.0f / radius;+ lightProj[2][2] = -1.0f / range;+ lightProj[3][2] = 0.0f;+ projection.matrix = lightProj * lightView;+ projection.radius = radius;+ projection.depthPerWorld = 1.0f / std::max(range, 1.0f);}- for (const glm::vec3& p : slice) centre += p;- centre *= 0.125f;- for (const glm::vec3& p : slice) radius = std::max(radius, glm::length(p - centre));- // Snap to the map's own texel grid, in the light's axes: without it the- // cascade slides continuously with the camera and every shadow edge- // crawls along the geometry a texel at a time.- const f32 texel = (radius * 2.0f) / static_cast<f32>(tile.size);- glm::vec3 inLight = glm::vec3(lightRot * glm::vec4(centre, 1.0f));- inLight.x = std::floor(inLight.x / texel) * texel;- inLight.y = std::floor(inLight.y / texel) * texel;- centre = glm::vec3(lightRotInv * glm::vec4(inLight, 1.0f));- }- // ★ How far back the near plane goes. A cascade covers a slice of the VIEW,- // but what shadows it can stand anywhere between the slice and the light —- // clip at the slice and the caster is not drawn, and nothing says why.- f32 castDistance = radius * 2.0f;- if (haveBounds) {- for (u32 i = 0; i < 8; ++i) {- const glm::vec3 corner((i & 1) ? boundsMax.x : boundsMin.x,- (i & 2) ? boundsMax.y : boundsMin.y,- (i & 4) ? boundsMax.z : boundsMin.z);- castDistance = std::max(castDistance, glm::dot(corner - centre, toLight));- }+ matrices[tileIndex] = projection.matrix;+ // The tile's rect, and in its w the bias it needs — scaled by what a texel+ // of THIS tile is worth: the number stopping a near cascade shadowing+ // itself would let a coarser one detach from whatever casts into it.+ tiles[tileIndex] = shadow_atlas_.unitRect(tileIndex);+ tiles[tileIndex].w = kShadowBias * std::max(projection.radius, 1.0f)+ / (0.5f * static_cast<f32>(tile.size))+ * (4.0f * std::max(projection.radius, 1.0f))+ * projection.depthPerWorld;++ // A self-contained pass, in the shape renderToTarget uses: swap what the+ // frame looks through, collect what casts, draw, hand the target back. The+ // atlas is cleared once — white, which is depth 1 unpacked: nothing here.+ RenderPassDesc pass{rt->getFramebuffer(), /*clearColor=*/!cleared};+ pass.clearDepth = !cleared;+ pass.clearColorValue[0] = pass.clearColorValue[1] = pass.clearColorValue[2] = 1.0f;+ pass.clearColorValue[3] = 1.0f;+ device_.beginRenderPass(pass);+ cleared = true;+ device_.setViewport(tile.x, tile.y, tile.size, tile.size);++ view_projection_ = projection.matrix;+ frustum_.extractFromMatrix(projection.matrix);+ pool_.beginFrame();+ draw_list_.clear();++ auto ctx = makeContext();+ ctx.shadow_pass = true;+ RenderCollectContext collectCtx{registry, frustum_, clip_state_, pool_, draw_list_,+ ctx, computeCameraView(projection.matrix)};+ for (auto& plugin : plugins_) plugin->collect(collectCtx);++ draw_list_.finalize(pool_);+ pool_.upload();+ // Not a camera's: this projection spans exactly the occluders it draws, so+ // it sits inside either clip volume as built, and the depths it writes are+ // compared against the copy of it the receiving shader holds.+ context_.updateFrameConstants(projection.matrix);+ // The depth variant is still a Lit2D shader and still declares the light block,+ // and a draw whose declared UBO is unbound is undefined behaviour that draws+ // nothing — the whole pass came back empty for exactly this.+ context_.lights().uploadAndBind();+ draw_list_.execute(device_, pool_, context_.materials(), context_.getWhiteTextureId(),+ nullptr, context_.skinUbo());}- const glm::mat4 lightView = glm::lookAt(centre + toLight * castDistance, centre, up);- // Written out rather than built from math::ortho: this maps the occluders it- // draws onto exactly [0,1], so it needs no conversion for either device — which- // is what lets the depths it writes be compared against the receiver's own copy.- glm::mat4 lightProj(1.0f);- const f32 range = castDistance + radius * 2.0f;- lightProj[0][0] = 1.0f / radius;- lightProj[1][1] = 1.0f / radius;- lightProj[2][2] = -1.0f / range;- lightProj[3][2] = 0.0f;- matrices[c] = lightProj * lightView;- // The tile's rect, and in its w the bias it needs — scaled by what a texel- // of THIS tile is worth: the number stopping a near cascade shadowing- // itself would let a coarser one detach from whatever casts into it.- tiles[c] = shadow_atlas_.unitRect(static_cast<u32>(firstTile) + c);- tiles[c].w = kShadowBias * std::max(radius, 1.0f)- / (0.5f * static_cast<f32>(tile.size))- * (4.0f * std::max(radius, 1.0f) / std::max(range, 1.0f));-- // A self-contained pass, in the shape renderToTarget uses: swap what the frame is- // looking through, collect only what casts, draw, and hand the target back.- // The whole atlas, once — a later clear would wipe what an earlier tile- // wrote, and each tile only ever tests inside its own viewport. White is- // depth 1 unpacked: a texel nobody drew into never shadows.- RenderPassDesc pass{rt->getFramebuffer(), /*clearColor=*/!cleared};- pass.clearDepth = !cleared;- pass.clearColorValue[0] = pass.clearColorValue[1] = pass.clearColorValue[2] = 1.0f;- pass.clearColorValue[3] = 1.0f;- device_.beginRenderPass(pass);- cleared = true;- device_.setViewport(tile.x, tile.y, tile.size, tile.size);-- view_projection_ = matrices[c];- frustum_.extractFromMatrix(matrices[c]);- pool_.beginFrame();- draw_list_.clear();-- auto ctx = makeContext();- ctx.shadow_pass = true;- RenderCollectContext collectCtx{registry, frustum_, clip_state_, pool_, draw_list_, ctx,- computeCameraView(matrices[c])};- for (auto& plugin : plugins_) plugin->collect(collectCtx);-- draw_list_.finalize(pool_);- pool_.upload();- // Not a camera's: this projection spans exactly the occluders it draws, so- // it sits inside either clip volume as built, and the depths it writes are- // compared against the copy of it the receiving shader holds.- context_.updateFrameConstants(matrices[c]);- // The depth variant is still a Lit2D shader and still declares the light block,- // and a draw whose declared UBO is unbound is undefined behaviour that draws- // nothing — the whole pass came back empty for exactly this.- context_.lights().uploadAndBind();- draw_list_.execute(device_, pool_, context_.materials(), context_.getWhiteTextureId(),- nullptr, context_.skinUbo());}rt->unbind();device_.invalidatePipelineCache();- shadow_texture_id_ = static_cast<u32>(rt->getColorTexture());- context_.lights().setShadowTiles(- matrices, tiles, cascades,- glm::vec4(1.0f, 1.0f / static_cast<f32>(kShadowAtlasSize), 0.0f, 0.0f));- // Which of them this light reads. Without it a fragment would test against every- // map in the atlas, including ones rendered from somewhere it cannot see.- context_.lights().setLightShadowTiles(static_cast<u32>(shadow_light_slot_),- static_cast<u32>(firstTile), cascades);+ if (anyTile) {+ shadow_texture_id_ = static_cast<u32>(rt->getColorTexture());+ context_.lights().setShadowTiles(+ matrices, tiles, shadow_atlas_.tileCount(),+ glm::vec4(1.0f, 1.0f / static_cast<f32>(kShadowAtlasSize), 0.0f, 0.0f));+ // Which of them each light reads. Without it a fragment would test against+ // every map in the atlas, including ones rendered from where it cannot see.+ for (usize i = 0; i < shadow_casters_.size(); ++i) {+ if (plan[i].count == 0) continue;+ context_.lights().setLightShadowTiles(shadow_casters_[i].slot,+ plan[i].first, plan[i].count);+ }+ }// Back to the frame's own target and camera. The scene has drawn nothing yet, so// re-opening the pass costs a load rather than the frame's contents.diff --git a/src/esengine/renderer/frame/RenderFrame.hpp b/src/esengine/renderer/frame/RenderFrame.hppindex 5e2d59bf7..da3e2a809 100644--- a/src/esengine/renderer/frame/RenderFrame.hpp+++ b/src/esengine/renderer/frame/RenderFrame.hpp@@ -359,19 +359,39 @@ private:u32 initBatchShader();resource::ShaderHandle compileBatchVariant(const std::vector<std::string>& features);- /// A collected light and whether it casts the frame's mesh shadow. Paired rather- /// than flagged inside the GPU struct, because the cap sort reorders these and the- /// answer has to travel with the light.+ /**+ * @brief What a light needs a shadow map FOR — everything the pass differs by.+ *+ * @details A directional light's map covers a stretch of the view and a spot's+ * covers its cone, so they build different projections; everything after+ * that is one pass. Kept as a description rather than a flag on the light+ * because the cap sort reorders those and this has to survive it.+ */+ struct ShadowCaster {+ u32 slot = 0;+ bool directional = true;+ /// Which way it points — the aim, not the direction light travels.+ glm::vec3 dir{0.0f, 0.0f, -1.0f};+ /// Where it stands. Spot only; a directional light has no position.+ glm::vec3 pos{0.0f};+ /// Directional: a fixed reach, or 0 to fit what the camera can see.+ f32 extent = 0.0f;+ /// Spot: how far its falloff reaches, and how wide the cone opens (degrees).+ f32 range = 0.0f;+ f32 outerAngle = 0.0f;+ };+ /// A collected light and the map it asked for, if any. Paired rather than flagged+ /// inside the GPU struct, because the cap sort reorders these and the answer has+ /// to travel with the light.struct CollectedLight {GpuLight2D gpu;bool castsMeshShadow;+ ShadowCaster caster;};std::vector<CollectedLight> light_scratch_; // reused across frames; collectLights only- /// Which light slot casts the map, and the direction + coverage it asked for.- /// Written by collectLights, read by renderShadowMap; -1 = nobody asked.- i32 shadow_light_slot_ = -1;- glm::vec3 shadow_light_dir_{0.0f, 0.0f, -1.0f};- f32 shadow_light_extent_ = 0.0f;+ /// Every light that asked for a map this frame, in UBO slot order. Written by+ /// collectLights, read by renderShadowMap; empty = nobody asked.+ std::vector<ShadowCaster> shadow_casters_;RenderTargetManager::Handle shadow_rt_ = 0;/// Who owns which square of it. Rebuilt every frame: a tile means nothing once/// the depths in it belong to a frame that is gone.diff --git a/src/esengine/resource/ShaderParser.cpp b/src/esengine/resource/ShaderParser.cppindex 1520163d4..993796ace 100644--- a/src/esengine/resource/ShaderParser.cpp+++ b/src/esengine/resource/ShaderParser.cpp@@ -929,7 +929,10 @@ fn lightVector(pd : vec4f, sh : vec4f, worldPos : vec3f) -> vec3f {}fn lightDistance(toLight : vec3f) -> f32 { return length(toLight.xy); }fn spotCone(sp : vec4f, sh : vec4f, toLight : vec3f, dist : f32) -> f32 {- let axis = normalize(sp.xy);+ // A cone aimed out of the plane has no axis IN it, and this half of the shading+ // has nowhere else to read one — so it lights the way an unrotated spot always has.+ var axis = vec2f(0.0, -1.0);+ if (dot(sp.xy, sp.xy) > 1e-8) { axis = normalize(sp.xy); }var toFrag = axis;if (dist > 0.0001) { toFrag = -toLight.xy / dist; }return smoothstep(sp.w, sp.z, dot(axis, toFrag));@@ -1547,7 +1550,10 @@ ShaderParser::AssembledStage ShaderParser::assembleStageEx(const ParsedShader& p"highp float lightDistance(in highp vec3 toLight) { return length(toLight.xy); }\n""highp float spotCone(in highp vec4 sp, in highp vec4 sh, in highp vec3 toLight,\n"" in highp float dist) {\n"- " highp vec2 axis = normalize(sp.xy);\n"+ // A cone aimed out of the plane has no axis IN it, and this half of the+ // shading has nowhere else to read one, so it keeps lighting the way an+ // unrotated spot always has.+ " highp vec2 axis = dot(sp.xy, sp.xy) > 1e-8 ? normalize(sp.xy) : vec2(0.0, -1.0);\n"" highp vec2 toFrag = (dist > 0.0001) ? -toLight.xy / dist : axis;\n"" return smoothstep(sp.w, sp.z, dot(axis, toFrag));\n""}\n"diff --git a/tools/renderScenes.mjs b/tools/renderScenes.mjsindex 563381346..8bb816b5e 100644--- a/tools/renderScenes.mjs+++ b/tools/renderScenes.mjs@@ -76,6 +76,10 @@ export const SCENES = [// coverage derived from the camera's NDC z=0 slice is the whole view for the// orthographic one above and a sliver near the near plane for this one.{ id: "mesh-shadow-caster-behind", tier: "pr", webgpu: true, env: { ESTELLA_VERIFY_SCENE: "/scenes/mesh-shadow-caster-behind.esscene", ESTELLA_VERIFY_W: "256", ESTELLA_VERIFY_H: "256", ESTELLA_VERIFY_STEPS: "2", ESTELLA_VERIFY_EXPECT: "[{\"x\":0.7,\"y\":0.21,\"rgb\":[0,0,0],\"tol\":20},{\"x\":0.48,\"y\":0.21,\"rgb\":[255,255,255],\"tol\":20},{\"x\":0.7,\"y\":0.6,\"rgb\":[255,255,255],\"tol\":20}]" } },+ // A CONE casting, through the tile and the pass a cascade uses. The shadow is offset+ // from the caster because a point light projects rather than sweeps; the probes either+ // side of x = 162 are its edge, and the caster is lit because it must not shadow itself.+ { id: "spot-shadow", tier: "pr", webgpu: true, env: { ESTELLA_VERIFY_SCENE: "/scenes/spot-shadow.esscene", ESTELLA_VERIFY_MANIFEST: "/scenes/spot-shadow.textures.json", ESTELLA_VERIFY_W: "256", ESTELLA_VERIFY_H: "256", ESTELLA_VERIFY_STEPS: "2", ESTELLA_VERIFY_EXPECT: "[{\"x\":0.7,\"y\":0.5,\"rgb\":[0,0,0],\"tol\":20},{\"x\":0.8,\"y\":0.5,\"rgb\":[155,155,155],\"tol\":25},{\"x\":0.25,\"y\":0.5,\"rgb\":[178,178,178],\"tol\":25},{\"x\":0.5,\"y\":0.5,\"rgb\":[196,196,196],\"tol\":25}]" } },{ id: "mesh-shadow-cascade", tier: "pr", webgpu: true, env: { ESTELLA_VERIFY_SCENE: "/scenes/mesh-shadow-cascade.esscene", ESTELLA_VERIFY_W: "256", ESTELLA_VERIFY_H: "256", ESTELLA_VERIFY_STEPS: "2", ESTELLA_VERIFY_EXPECT: "[{\"x\":0.657,\"y\":0.452,\"rgb\":[0,0,0],\"tol\":20},{\"x\":0.6,\"y\":0.452,\"rgb\":[252,252,252],\"tol\":20},{\"x\":0.72,\"y\":0.452,\"rgb\":[252,252,252],\"tol\":20}]" } },{ id: "mesh-shadow-perspective", tier: "pr", webgpu: true, env: { ESTELLA_VERIFY_SCENE: "/scenes/mesh-shadow-perspective.esscene", ESTELLA_VERIFY_W: "256", ESTELLA_VERIFY_H: "256", ESTELLA_VERIFY_STEPS: "2", ESTELLA_VERIFY_EXPECT: "[{\"x\":0.86,\"y\":0.5,\"rgb\":[0,0,0],\"tol\":20},{\"x\":0.10,\"y\":0.5,\"rgb\":[228,228,228],\"tol\":20},{\"x\":0.5,\"y\":0.5,\"rgb\":[228,228,228],\"tol\":20}]" } },// A sun aimed OUT of the plane: 0.25 in x and 0.25 in depth throws the blocker's