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): Voxel GI on WebGPU reads the sun's shadow map back into its cache and feeds each bounce back, so light the camera does not see and light past the first bounce reach the picture
yhhf105c3d2dbea
diff --git a/CHANGELOG.md b/CHANGELOG.mdindex 5d95d8aaf..bd22c56bb 100644--- a/CHANGELOG.md+++ b/CHANGELOG.md@@ -16,6 +16,8 @@ published separately; it ships inside the editor.### Added+- **Voxel GI lights what the camera does not see, and bounces light more than once (WebGPU).** The cache now reads the sun's shadow map back into the world, so a surface the sun lights behind or beside the camera still sends light into the view. Each surface also gives off again the bounce light it received, so a corner or a floor in shade gets light that took two or more bounces to reach it. In a sunlit room whose lit patch is behind the camera, the walls went from no bounce light to 10–30% of a path tracer's. With 12 cm voxels, the room with the patch in view went from 2–57% to 43–62%. Two inspector controls tune it: **Off-screen Sun Albedo** (the colour the shadow map cannot give, assumed) and **Multi-bounce**. A fine grid (voxels a sample a frame lands in) no longer drops every voxel: a count truncated by the cache's ageing had kept them below the two samples a ray asks for. The WebGL2 fallback still sees only the picture.+- **A model of many parts that moves: `CompositeBatch`.** Put it on the root of a ship, a vehicle or a moving platform assembled from many meshes, and while the game runs its parts are drawn in a few draws parented to the root: a mesh repeated four times or more (a deck plank, a rail post) as one instanced set that copies no vertices, every other part merged by draw state into chunks of the root's own space. Moving, turning or scaling the root moves the whole model and merges nothing again. Adding, removing, re-meshing or re-placing a part re-merges only its chunk within half a second (`CompositeBatchingRes.refresh(root)` looks at once), and a part that keeps moving inside the model is let go to draw itself. The root reports what it drew, and so does `get_stats`. On a model of 2,004 parts, the meshes handed to the renderer went from 2,003 to 5 and the CPU frame from 3.3 ms to 1.2–1.4 ms; a model of about a hundred parts costs the same either way. A part under a composite is never also statically batched.### Fixeddiff --git a/sdk/src/postprocess/effects.ts b/sdk/src/postprocess/effects.tsindex afd3955f8..a45c359df 100644--- a/sdk/src/postprocess/effects.ts+++ b/sdk/src/postprocess/effects.ts@@ -480,6 +480,12 @@ registerEffect({{ name: 'u_blend', label: 'Temporal Blend', min: 0.02, max: 1, step: 0.01, defaultValue: 0.2 },// 1 shows the gathered light alone.{ name: 'u_debug', label: 'Show GI Only', min: 0, max: 1, step: 1, defaultValue: 0 },+ // What the sun lights off screen is read from its shadow map, which holds no colour: such a surface is lit as one of this albedo.+ // 0 leaves the sun out, and the cache then knows only what the picture shows. WebGPU only.+ { name: 'u_sunAlbedo', label: 'Off-screen Sun Albedo', min: 0, max: 1, step: 0.01, defaultValue: 0.6 },+ // How much of the light a surface was bounced gives off again, which is what carries light past the first bounce (into a+ // corner, onto a face only another lit face sees). 0 is one bounce. WebGPU only.+ { name: 'u_bounceFeedback', label: 'Multi-bounce', min: 0, max: 1, step: 0.01, defaultValue: 1 },],});diff --git a/sdk/tests/compute-effect.test.ts b/sdk/tests/compute-effect.test.tsindex efc2cd18e..c4de62c4a 100644--- a/sdk/tests/compute-effect.test.ts+++ b/sdk/tests/compute-effect.test.ts@@ -115,10 +115,14 @@ describe('native effects', () => {// The native side reads these by name, with these defaults when one is not set.expect(def!.uniforms.map((u) => u.name)).toEqual(['u_intensity', 'u_rays', 'u_voxelSize', 'u_range', 'u_maxBounce', 'u_decay', 'u_bias', 'u_divisor', 'u_blend', 'u_debug',+ 'u_sunAlbedo', 'u_bounceFeedback',]);const defaults = Object.fromEntries(def!.uniforms.map((u) => [u.name, u.defaultValue]));expect(defaults.u_rays).toBe(8);expect(defaults.u_divisor).toBe(2);+ // VoxelGIParams' own defaults (VoxelGI.hpp): the sun's off-screen light on, and every bounce fed back.+ expect(defaults.u_sunAlbedo).toBe(0.6);+ expect(defaults.u_bounceFeedback).toBe(1);});it('pushes a native pass by its kind, and leaves it out on a core that cannot', () => {diff --git a/src/esengine/renderer/frame/PostProcessPipeline.cpp b/src/esengine/renderer/frame/PostProcessPipeline.cppindex b9c842d4c..5b129f1be 100644--- a/src/esengine/renderer/frame/PostProcessPipeline.cpp+++ b/src/esengine/renderer/frame/PostProcessPipeline.cpp@@ -1192,6 +1192,8 @@ void PostProcessPipeline::runChain(std::vector<PostProcessPass>& passes, rg::Resgi.divisor = static_cast<u32>(std::max(get("u_divisor", static_cast<f32>(gi.divisor)), 1.0f));gi.debug = get("u_debug", gi.debug);gi.blend = get("u_blend", gi.blend);+ gi.sunAlbedo = get("u_sunAlbedo", gi.sunAlbedo);+ gi.bounceFeedback = get("u_bounceFeedback", gi.bounceFeedback);auto& cache = voxel_gis_[temporalKey_];if (!cache) {// A handful of cameras at most have a cache each; one past that evicts another's, which rebuilds when its camera returns.@@ -1202,7 +1204,8 @@ void PostProcessPipeline::runChain(std::vector<PostProcessPass>& passes, rg::Res}voxel_gis_[temporalKey_] = makeUnique<VoxelGI>(device_, context_);}- input = voxel_gis_[temporalKey_]->declare(*graph_, input, scene, gi, width_, height_);+ input = voxel_gis_[temporalKey_]->declare(*graph_, input, scene, gi, width_, height_,+ TextureHandle{shadow_texture_}, shadow_resource_);}continue;}diff --git a/src/esengine/renderer/frame/VoxelGI.cpp b/src/esengine/renderer/frame/VoxelGI.cppindex eafa449f8..71c2a269d 100644--- a/src/esengine/renderer/frame/VoxelGI.cpp+++ b/src/esengine/renderer/frame/VoxelGI.cpp@@ -27,7 +27,7 @@ struct GI {origin : vec4i, // xyz: the window's first cell; w: the framedims : vec4u, // xyz: voxels per axis; w: rays per pointa : vec4f, // x: voxel size, y: what the grid keeps, z: the brightest a surface gives, w: intensity- b : vec4f, // x: how far a ray looks (cells), y: where it starts (cells), z: unused, w: debug+ b : vec4f, // x: how far a ray looks (cells), y: where it starts (cells), z: how much of the last bounce feeds back, w: debugview : vec4f, // x: the gather's divisor, y: 1 when the last gather is a history to blend with, z: how much of this one goes inprevViewProjection : mat4x4f,};@@ -39,6 +39,10 @@ struct GI {const WORDS : u32 = 8u;const FIXED : f32 = 1024.0;const FACING : f32 = 256.0;+// A sample counts COUNT, not 1: the grid ages by a factor below one each frame and truncates, and a count of 1 aged to 0.93 truncates+// to 0 — a voxel that one sample a frame lands in (a small voxel, or one far away) then never reached the 2 a ray asks for, and a+// fine grid drew no bounce at all.+const COUNT : u32 = 16u;fn hash3(c : vec3i) -> u32 {var h = (u32(c.x) * 73856093u) ^ (u32(c.y) * 19349663u) ^ (u32(c.z) * 83492791u);@@ -103,11 +107,15 @@ fn main(@builtin(global_invocation_id) id : vec3u) {})WGSL";-/// The lit picture into the voxels its visible surfaces stand in.+/// The lit picture into the voxels its visible surfaces stand in, with the bounce light the last gather found on them: what a surface+/// gives off is what it was lit by, the bounce included, so each frame carries the light one surface further and the cache converges on+/// the light of every bounce rather than of the first.const char* kInject = R"WGSL(@group(0) @binding(4) var scene : texture_2d<f32>;@group(0) @binding(5) var depthTex : texture_depth_2d;@group(0) @binding(6) var gbuffer : texture_2d<f32>;+@group(0) @binding(8) var albedoTex : texture_2d<f32>;+@group(0) @binding(9) var histTex : texture_2d<f32>;@compute @workgroup_size(8, 8)fn main(@builtin(global_invocation_id) id : vec3u) {@@ -124,11 +132,18 @@ fn main(@builtin(global_invocation_id) id : vec3u) {let cell = vec3i(floor(p / gi.a.x));if (!inWindow(cell)) { return; }let base = wrapIndex(cell) * WORDS;- let c = clamp(textureLoad(scene, t, 0).rgb, vec3f(0.0), vec3f(gi.a.z));+ var lit = textureLoad(scene, t, 0).rgb;+ let albedo = textureLoad(albedoTex, t, 0);+ if (gi.view.y > 0.5 && albedo.a > 0.5) {+ let div = i32(gi.view.x);+ let q = clamp(t / div, vec2i(0), vec2i(textureDimensions(histTex)) - vec2i(1));+ lit = lit + albedo.rgb * textureLoad(histTex, q, 0).rgb * (gi.a.w * gi.b.z);+ }+ let c = clamp(lit, vec3f(0.0), vec3f(gi.a.z));atomicAdd(&grid[base], u32(c.r * FIXED));atomicAdd(&grid[base + 1u], u32(c.g * FIXED));atomicAdd(&grid[base + 2u], u32(c.b * FIXED));- atomicAdd(&grid[base + 3u], 1u);+ atomicAdd(&grid[base + 3u], COUNT);let f = n * 0.5 + 0.5;atomicAdd(&grid[base + 4u], u32(f.x * FACING));atomicAdd(&grid[base + 5u], u32(f.y * FACING));@@ -136,7 +151,74 @@ fn main(@builtin(global_invocation_id) id : vec3u) {})WGSL";-/// Rays from each visible surface through the grid, at a fraction of the picture's size.+/// What the sun lights, whether the camera sees it or not: every texel of the sun shadow map is a surface the sun reaches, so the map+/// is read back into world positions (the inverse of each tile matrix) and their direct light injected where they stand. Its colour is+/// not in the map, so it is lit as a surface of one assumed albedo; where the camera also sees it, the picture colour averages in beside it.+const char* kSun = R"WGSL(+struct Sun {+ light : vec4f, // rgb: the sun colour times its intensity; w: the albedo a surface is taken to have+ toLight : vec4f, // xyz: unit vector toward the sun; w: how many tiles+ samples : vec4u, // x: samples per tile side+ rect : array<vec4f, 4>, // each tile square in the atlas, low corner and side, in GL terms+ inverse : array<mat4x4f, 4>, // each tile clip space back to the world+};+// The atlas holds depth packed into colour (what the lit shaders unpack), not a depth texture.+@group(0) @binding(4) var shadowTex : texture_2d<f32>;+@group(0) @binding(10) var<uniform> sun : Sun;++fn shadowPoint(k : u32, uv : vec2f, size : vec2f) -> vec4f {+ let rect = sun.rect[k];+ let base = vec2f(rect.x, 1.0 - rect.y - rect.z);+ let at = base + vec2f(uv.x, 1.0 - uv.y) * rect.z;+ let texel = clamp(vec2i(at * size), vec2i(0), vec2i(size) - vec2i(1));+ let c = textureLoad(shadowTex, texel, 0).rgb;+ let d = dot(c, vec3f(1.0, 1.0 / 255.0, 1.0 / 65025.0));+ // The map stores clip z remapped to [0, 1] (z * 0.5 + 0.5, as the lit shaders compare it): undone before the inverse.+ let w = sun.inverse[k] * vec4f(uv * 2.0 - 1.0, d * 2.0 - 1.0, 1.0);+ return vec4f(w.xyz / w.w, d);+}++@compute @workgroup_size(8, 8)+fn main(@builtin(global_invocation_id) id : vec3u) {+ let n = sun.samples.x;+ let k = id.x / n;+ if (k >= u32(sun.toLight.w) || id.y >= n) { return; }+ let size = vec2f(textureDimensions(shadowTex));+ let step = 1.0 / f32(n);+ let uv = (vec2f(f32(id.x % n), f32(id.y)) + 0.5) * step;+ let p = shadowPoint(k, uv, size);+ if (p.w >= 1.0 || p.w <= 0.0) { return; }+ let px = shadowPoint(k, uv + vec2f(step, 0.0), size).xyz;+ let py = shadowPoint(k, uv + vec2f(0.0, step), size).xyz;+ let vs = gi.a.x;+ // A neighbour across a depth edge (the top of a wall against the floor) gives no tangent: those samples carry no normal.+ let ex = px - p.xyz;+ let ey = py - p.xyz;+ if (length(ex) > vs * 4.0 || length(ey) > vs * 4.0) { return; }+ // Two neighbours on one texel (or on a line) give no plane: normalizing nothing is a NaN, and one NaN turned into the grid's+ // fixed point poisons every ray that meets its voxel.+ let cr = cross(ex, ey);+ let area = dot(cr, cr);+ if (!(area > 1e-12)) { return; }+ var nrm = cr * inverseSqrt(area);+ let L = sun.toLight.xyz;+ if (dot(nrm, L) < 0.0) { nrm = -nrm; }+ let cell = vec3i(floor((p.xyz + nrm * (vs * 0.25)) / vs));+ if (!inWindow(cell)) { return; }+ let base = wrapIndex(cell) * WORDS;+ let c = clamp(sun.light.rgb * (sun.light.w * max(dot(nrm, L), 0.0)), vec3f(0.0), vec3f(gi.a.z));+ atomicAdd(&grid[base], u32(c.r * FIXED));+ atomicAdd(&grid[base + 1u], u32(c.g * FIXED));+ atomicAdd(&grid[base + 2u], u32(c.b * FIXED));+ atomicAdd(&grid[base + 3u], COUNT);+ let f = nrm * 0.5 + 0.5;+ atomicAdd(&grid[base + 4u], u32(f.x * FACING));+ atomicAdd(&grid[base + 5u], u32(f.y * FACING));+ atomicAdd(&grid[base + 6u], u32(f.z * FACING));+}+)WGSL";++/// Rays from each visible surface through the grid, at a fraction of the picture size.const char* kGather = R"WGSL(@group(0) @binding(5) var depthTex : texture_depth_2d;@group(0) @binding(6) var gbuffer : texture_2d<f32>;@@ -183,8 +265,8 @@ fn trace(origin : vec3f, dir : vec3f) -> vec3f {if (tags[idx] != hash3(cell)) { continue; }let base = idx * WORDS;let count = atomicLoad(&grid[base + 3u]);- if (count < 2u) { continue; }- let inv = 1.0 / f32(count);+ if (count < 2u * COUNT) { continue; }+ let inv = f32(COUNT) / f32(count);let facing = (vec3f(f32(atomicLoad(&grid[base + 4u])), f32(atomicLoad(&grid[base + 5u])), f32(atomicLoad(&grid[base + 6u]))) * inv / FACING) * 2.0 - 1.0;// A surface is met from the side it faces. One facing away is behind the ray, or the ray skims along it.if (dot(normalize(facing), dir) > -0.15) { continue; }@@ -295,6 +377,7 @@ const char* const kCommon = "";const char* const kSurface = "";const char* const kMaintain = "";const char* const kInject = "";+const char* const kSun = "";const char* const kGather = "";const char* const kApply = "";#endif@@ -313,6 +396,17 @@ struct ParamsBlock {};static_assert(sizeof(ParamsBlock) == 144, "the GI block is five vec4s and a matrix");+/// The sun shadow tiles as the sun kernel reads them back (see kSun).+struct SunBlock {+ f32 light[4];+ f32 toLight[4];+ u32 samples[4];+ f32 rect[4][4];+ f32 inverse[4][16];+};+static_assert(sizeof(SunBlock) == 368, "the sun block is three vec4s, four rects and four matrices");+constexpr u32 kSunTiles = 4;+} // namespaceVoxelGI::VoxelGI(GfxDevice& device, RenderContext& context) : device_(device), context_(context) {}@@ -322,7 +416,7 @@ VoxelGI::~VoxelGI() {}void VoxelGI::release() {- for (BufferHandle* b : {&grid_, &tags_, ¶ms_}) {+ for (BufferHandle* b : {&grid_, &tags_, ¶ms_, &sun_}) {if (*b != BufferHandle::Invalid) device_.deleteBuffer(*b);*b = BufferHandle::Invalid;}@@ -332,7 +426,7 @@ void VoxelGI::release() {}historyWidth_ = historyHeight_ = 0;historyValid_ = false;- for (ComputeHandle* c : {&maintain_, &inject_, &gather_, &apply_}) {+ for (ComputeHandle* c : {&maintain_, &inject_, &gather_, &apply_, &sunInject_}) {if (*c != ComputeHandle::Invalid) device_.deleteCompute(*c);*c = ComputeHandle::Invalid;}@@ -347,8 +441,10 @@ bool VoxelGI::ensure() {grid_ = device_.createBuffer({GfxBufferUsage::Storage, voxels * kVoxelWords * 4u, false}, GfxContent::transient(), nullptr);tags_ = device_.createBuffer({GfxBufferUsage::Storage, voxels * 4u, false}, GfxContent::transient(), nullptr);params_ = device_.createBuffer({GfxBufferUsage::Uniform, sizeof(ParamsBlock), true}, GfxContent::transient(), nullptr);+ sun_ = device_.createBuffer({GfxBufferUsage::Uniform, sizeof(SunBlock), true}, GfxContent::transient(), nullptr);}- if (grid_ == BufferHandle::Invalid || tags_ == BufferHandle::Invalid || params_ == BufferHandle::Invalid) {+ if (grid_ == BufferHandle::Invalid || tags_ == BufferHandle::Invalid || params_ == BufferHandle::Invalid+ || sun_ == BufferHandle::Invalid) {ES_LOG_ERROR("VoxelGI: could not allocate the voxel cache");failed_ = true;return false;@@ -365,7 +461,8 @@ bool VoxelGI::ensure() {return true;};return make(maintain_, join(kCommon, kMaintain), "maintain") && make(inject_, join(kCommon, kSurface, kInject), "inject")- && make(gather_, join(kCommon, kSurface, kGather), "gather") && make(apply_, join(kCommon, kApply), "apply");+ && make(gather_, join(kCommon, kSurface, kGather), "gather") && make(apply_, join(kCommon, kApply), "apply")+ && make(sunInject_, join(kCommon, kSun), "sun");}bool VoxelGI::ensureHistory(u32 width, u32 height) {@@ -410,6 +507,7 @@ void VoxelGI::writeParams(const VoxelGIParams& p) {block.a[3] = p.intensity;block.b[0] = std::clamp(p.range, 1.0f, 90.0f);block.b[1] = std::max(p.bias, 0.0f);+ block.b[2] = std::clamp(p.bounceFeedback, 0.0f, 1.0f);block.b[3] = p.debug;block.view[0] = static_cast<f32>(std::clamp(p.divisor, 1u, 4u));// A change of voxel size makes every voxel a different place, so what was gathered under the old one is not history.@@ -433,8 +531,44 @@ void VoxelGI::writeParams(const VoxelGIParams& p) {++frame_;}+u32 VoxelGI::writeSun(const VoxelGIParams& p) {+ // The first directional light that owns shadow tiles: the sun whose map says what it reaches.+ const LightConstants& lc = context_.lights().data();+ if (lc.shadowParams.x < 0.5f || p.sunAlbedo <= 0.0f) return 0;+ // Every slot, not a count: an empty slot reads as no light (zero colour, zero tiles).+ for (u32 i = 0; i < MAX_LIGHTS; ++i) {+ const GpuLight& l = lc.lights[i];+ const bool directional = l.posDir.z > 0.5f && l.posDir.z < 1.5f;+ const u32 tiles = static_cast<u32>(std::fmod(std::max(l.shadowMap.y, 0.0f), LIGHT_TILE_BITS));+ if (!directional || tiles == 0) continue;+ const u32 first = static_cast<u32>(std::max(l.shadowMap.x, 0.0f));+ if (first >= MAX_SHADOW_TILES) continue;+ SunBlock block{};+ const glm::vec3 aim = glm::normalize(glm::vec3(l.posDir.x, l.posDir.y, l.posDir.w));+ block.light[0] = l.color.r * l.color.a;+ block.light[1] = l.color.g * l.color.a;+ block.light[2] = l.color.b * l.color.a;+ block.light[3] = p.sunAlbedo;+ block.toLight[0] = -aim.x;+ block.toLight[1] = -aim.y;+ block.toLight[2] = -aim.z;+ const u32 used = std::min({tiles, kSunTiles, MAX_SHADOW_TILES - first});+ block.toLight[3] = static_cast<f32>(used);+ block.samples[0] = kSunSamples;+ for (u32 k = 0; k < used; ++k) {+ const glm::vec4& r = lc.shadowTile[first + k];+ block.rect[k][0] = r.x; block.rect[k][1] = r.y; block.rect[k][2] = r.z; block.rect[k][3] = r.w;+ const glm::mat4 inv = glm::inverse(lc.shadowMatrix[first + k]);+ std::copy(glm::value_ptr(inv), glm::value_ptr(inv) + 16, block.inverse[k]);+ }+ device_.updateBuffer(sun_, 0, &block, sizeof(block));+ return used;+ }+ return 0;+}+rg::ResourceId VoxelGI::declare(rg::RenderGraph& graph, rg::ResourceId input, rg::ResourceId scene, const VoxelGIParams& params,- u32 width, u32 height) {+ u32 width, u32 height, TextureHandle shadowAtlas, rg::ResourceId shadowResource) {if (!ensure() || input == rg::kNoResource || scene == rg::kNoResource) return input;// The passes are tied together by what each writes, since the graph only runs what the image reaches. The first two write a@@ -484,11 +618,12 @@ rg::ResourceId VoxelGI::declare(rg::RenderGraph& graph, rg::ResourceId input, rgpass.reads = {input};pass.dependencies = {scene, maintainDone};pass.write = injectDone;- pass.execute = [this, &graph, scene, width, height](const rg::PassContext& ctx) {+ pass.execute = [this, &graph, scene, width, height, cur](const rg::PassContext& ctx) {const TextureHandle depth = graph.depthTextureOf(scene);const TextureHandle gbuffer = graph.gbufferTextureOf(scene);- if (depth == TextureHandle::Invalid || gbuffer == TextureHandle::Invalid) return;- const GfxComputeBinding bindings[7] = {+ const TextureHandle albedo = graph.albedoTextureOf(scene);+ if (depth == TextureHandle::Invalid || gbuffer == TextureHandle::Invalid || albedo == TextureHandle::Invalid) return;+ const GfxComputeBinding bindings[9] = {GfxComputeBinding::uniform(0, context_.frameUbo()),GfxComputeBinding::uniform(1, params_),GfxComputeBinding::storage(2, grid_),@@ -496,8 +631,36 @@ rg::ResourceId VoxelGI::declare(rg::RenderGraph& graph, rg::ResourceId input, rgGfxComputeBinding::sampled(4, ctx.input(0)),GfxComputeBinding::depth(5, depth),GfxComputeBinding::sampled(6, gbuffer),+ GfxComputeBinding::sampled(8, albedo),+ // The last frame gather: written by the gather of the frame before, so the other of the two.+ GfxComputeBinding::sampled(9, history_[cur ^ 1u]),+ };+ device_.dispatchCompute(inject_, bindings, 9, (width / 2 + 7) / 8, (height / 2 + 7) / 8);+ };+ graph.addPass(std::move(pass));+ }++ // The sun own light into the grid, after the picture and before anything reads it.+ rg::ResourceId sunDone = injectDone;+ if (shadowAtlas != TextureHandle::Invalid && shadowResource != rg::kNoResource && p.sunAlbedo > 0.0f) {+ sunDone = graph.createTarget(token);+ rg::PassDesc pass;+ pass.name = "gi_sun";+ pass.compute = true;+ pass.dependencies = {shadowResource, injectDone};+ pass.write = sunDone;+ pass.execute = [this, p, shadowAtlas](const rg::PassContext&) {+ const u32 tiles = writeSun(p);+ if (tiles == 0) return;+ const GfxComputeBinding bindings[6] = {+ GfxComputeBinding::uniform(0, context_.frameUbo()),+ GfxComputeBinding::uniform(1, params_),+ GfxComputeBinding::storage(2, grid_),+ GfxComputeBinding::storage(3, tags_),+ GfxComputeBinding::sampled(4, shadowAtlas),+ GfxComputeBinding::uniform(10, sun_),};- device_.dispatchCompute(inject_, bindings, 7, (width / 2 + 7) / 8, (height / 2 + 7) / 8);+ device_.dispatchCompute(sunInject_, bindings, 6, (kSunSamples * tiles + 7) / 8, (kSunSamples + 7) / 8);};graph.addPass(std::move(pass));}@@ -507,7 +670,7 @@ rg::ResourceId VoxelGI::declare(rg::RenderGraph& graph, rg::ResourceId input, rgrg::PassDesc pass;pass.name = "gi_gather";pass.compute = true;- pass.dependencies = {scene, injectDone};+ pass.dependencies = {scene, sunDone};pass.write = gathered;pass.execute = [this, &graph, scene, cur](const rg::PassContext&) {const TextureHandle depth = graph.depthTextureOf(scene);diff --git a/src/esengine/renderer/frame/VoxelGI.hpp b/src/esengine/renderer/frame/VoxelGI.hppindex 76ee454de..941fe4832 100644--- a/src/esengine/renderer/frame/VoxelGI.hpp+++ b/src/esengine/renderer/frame/VoxelGI.hpp@@ -58,6 +58,11 @@ struct VoxelGIParams {f32 debug = 0.0f;/// How much of each frame's gather goes into the picture the next frame builds on (the rest is what the last frames agreed on).f32 blend = 0.2f;+ /// The albedo a surface the sun lights is taken to have where the camera does not see it (the shadow map holds no colour);+ /// 0 leaves the sun out of the cache, which then knows only what the picture shows.+ f32 sunAlbedo = 0.6f;+ /// How much of the light the last gather found on a surface it gives off again (the bounces after the first): 0 is one bounce.+ f32 bounceFeedback = 1.0f;};class VoxelGI {@@ -74,7 +79,11 @@ public:* @return The resource holding @p input with the gathered light added; @p input itself when there is nothing to do.*/rg::ResourceId declare(rg::RenderGraph& graph, rg::ResourceId input, rg::ResourceId scene, const VoxelGIParams& params,- u32 width, u32 height);+ u32 width, u32 height, TextureHandle shadowAtlas = TextureHandle::Invalid,+ rg::ResourceId shadowResource = rg::kNoResource);++ /** Samples a side of each sun shadow tile the sun kernel reads back into the grid. */+ static constexpr u32 kSunSamples = 256;/** Frees the device objects (the grid, the programs). */void release();@@ -90,16 +99,20 @@ private:/// The two pictures the gathers accumulate into, made again when their size changes.bool ensureHistory(u32 width, u32 height);void writeParams(const VoxelGIParams& p);+ /// Fills the sun block from the frame lights; the number of shadow tiles it carries, 0 when there is no sun with a map.+ u32 writeSun(const VoxelGIParams& p);GfxDevice& device_;RenderContext& context_;BufferHandle grid_ = BufferHandle::Invalid;BufferHandle tags_ = BufferHandle::Invalid;BufferHandle params_ = BufferHandle::Invalid;+ BufferHandle sun_ = BufferHandle::Invalid;ComputeHandle maintain_ = ComputeHandle::Invalid;ComputeHandle inject_ = ComputeHandle::Invalid;ComputeHandle gather_ = ComputeHandle::Invalid;ComputeHandle apply_ = ComputeHandle::Invalid;+ ComputeHandle sunInject_ = ComputeHandle::Invalid;bool failed_ = false;u32 frame_ = 0;TextureHandle history_[2] = {TextureHandle::Invalid, TextureHandle::Invalid};diff --git a/tools/releaseNotes.mjs b/tools/releaseNotes.mjsindex fec404399..6ae377751 100644--- a/tools/releaseNotes.mjs+++ b/tools/releaseNotes.mjs@@ -3814,4 +3814,12 @@ export const NOTED = {{"note":"A model of many parts that moves: `CompositeBatch`."},"feat(mcp): get_stats reports what each CompositeBatch root draws, and the composite-batch check holds the batch":{"note":"A model of many parts that moves: `CompositeBatch`."},+ "fix(lightmap): built-in meshes carry the lightmap UV set the bake lays its charts by, so a baked cube or sphere draws its lightmap instead of nothing":+ {"note":"Baked lighting shows on built-in meshes."},+ "fix(lightmap): a bake reflects light 8 times by default, since two left a light-walled room at half the light Cycles gives it; the render lab takes MeshRenderer.color as the linear albedo it is":+ {"note":"Baked lighting reflects light 8 times by default, not 2."},+ "feat(render): the scene pass writes each surface's diffuse colour beside its normal, so Voxel GI and SSGI reflect bounce light by what it lands on instead of a grey guessed from the lit picture; render gates hold the baked and voxel-lit GI room":+ {"note":"Bounce light takes the colour of what it lands on."},+ "feat(render): Voxel GI on WebGPU reads the sun's shadow map back into its cache and feeds each bounce back, so light the camera does not see and light past the first bounce reach the picture":+ {"note":"Voxel GI lights what the camera does not see, and bounces light more than once (WebGPU)."},};diff --git a/tools/render-lab/README.md b/tools/render-lab/README.mdindex 0483dd575..65a73703f 100644--- a/tools/render-lab/README.md+++ b/tools/render-lab/README.md@@ -55,7 +55,13 @@ Each figure is a region's linear value in the engine as a share of Cycles' value- **The bake is right once it bounces enough.** With 8 bounces it lands within 5–18% of Cycles, and with 12 within 4–10%. Two bounces, which was the default, left a light-walled room at about half its light. The default is 8 now, and the inspector goes to 16. More bounces cost little: a 252k-lumel bake took 1.7 s at 2 bounces and 2.4 s at 8.- **The real-time methods give a fraction of the bounce.** Voxel GI gives 0.04–0.15 of it, SSGI about none. Faces that only a later bounce reaches get nothing.-- **Nothing off screen.** Both real-time methods seed from the frame's own picture, so `gi_away` is black under them. A surface cache lit independently of the view is what changes this.+- **Nothing off screen, until the sun's map.** Both real-time methods seeded from the frame's own picture, so `gi_away` was black under them. The WebGPU cache now also reads the sun's shadow map back into world points (kernel `gi_sun`). With the default cascades `gi_away` gets 0.12–0.31 of Cycles, and with a fixed 6 m reach 0.10–0.28. `gi_leak` stays black.+- **One bounce, until the feedback.** The WebGPU inject adds albedo × the last gather, so light keeps bouncing.+ - 12 cm voxels, `gi_room`: ceiling 0.50–0.57, red wall 0.55–0.62, back wall 0.43–0.50, floor in shade 0.51–0.58 (was 0).+ - Default 40 cm: frame light share 1.09 (mean |d| 0.0092, the lowest of every run). The ceiling and red wall overshoot (1.4–1.6) because a coarse voxel straddles both sides of a corner.+ - The block face that only the off-screen, unlit front wall sees stays at 0.02: what the camera neither sees nor the sun lights is still missing.+- **Fine grids drew nothing.** Below about 12 cm one sample a frame lands in a voxel, and the cache ages its count by 0.93 and truncates (1 → 0). It never reached the 2 a ray asks for. Samples now count 16.+- **Shadow map traps.** The atlas is packed colour (unpack the rgb), not a depth texture, and a depth binding silently falls back to a dummy. Its z is clip z × 0.5 + 0.5, so undo it before the inverse, or every point lands toward the light and a closed room fills with sun.- **No colour bleed, until the albedo attachment.** On the red wall the real-time red channel was 0.11–0.15 of Cycles while green and blue were 0.5–0.85, so the bounce arrived grey. Both effects guessed the receiver's colour from the lit picture, which is black where the sun does not reach. Since the scene pass writes the albedo beside the normal, Voxel GI gives:- WebGL2: ceiling 0.72–0.90, red wall 0.75/0.73/0.77, back wall 0.32–0.45.- WebGPU compute: ceiling 0.57–0.71, red wall 0.48–0.57.diff --git a/tools/renderScenes.mjs b/tools/renderScenes.mjsindex 97c559a13..3b07100ac 100644--- a/tools/renderScenes.mjs+++ b/tools/renderScenes.mjs@@ -165,8 +165,9 @@ export const SCENES = [// engine's, each within 4 of Cycles' own render of the same room (tools/render-lab, gi_room).{ id: "gi-room-baked", tier: "pr", webgpu: true, env: { "ESTELLA_VERIFY_COLORSPACE": "linear", "ESTELLA_VERIFY_SCENE": "/scenes/gi-room-baked.esscene", "ESTELLA_VERIFY_MANIFEST": "/scenes/gi-room-baked.textures.json", "ESTELLA_VERIFY_TEXTURES": "runtime", "ESTELLA_VERIFY_W": "320", "ESTELLA_VERIFY_H": "180", "ESTELLA_VERIFY_STEPS": "4", "ESTELLA_VERIFY_EXPECT": "[{\"x\":0.5,\"y\":0.099,\"rgb\":[66,63,60],\"tol\":10},{\"x\":0.239,\"y\":0.508,\"rgb\":[69,30,26],\"tol\":10},{\"x\":0.761,\"y\":0.508,\"rgb\":[23,46,21],\"tol\":10},{\"x\":0.441,\"y\":0.344,\"rgb\":[61,55,53],\"tol\":10},{\"x\":0.375,\"y\":0.711,\"rgb\":[64,54,51],\"tol\":10}]" } },// The same room unbaked, lit by Voxel GI: the bounce light on the red wall is red, because it is reflected by the albedo the wall wrote beside its- // normal. Before the albedo attachment it was guessed from the lit picture, and a wall the sun does not reach came out grey.- { id: "gi-room-voxel", tier: "pr", webgpu: true, env: { "ESTELLA_VERIFY_PLAY": "1", "ESTELLA_VERIFY_COLORSPACE": "linear", "ESTELLA_VERIFY_SCENE": "/scenes/gi-room-voxel.esscene", "ESTELLA_VERIFY_MANIFEST": "/scenes/gi-room-voxel.textures.json", "ESTELLA_VERIFY_W": "320", "ESTELLA_VERIFY_H": "180", "ESTELLA_VERIFY_STEPS": "120", "ESTELLA_VERIFY_EXPECT": "[{\"x\":0.5,\"y\":0.099,\"rgb\":[58,58,58],\"tol\":16},{\"x\":0.239,\"y\":0.508,\"rgb\":[64,28,25],\"tol\":16},{\"x\":0.761,\"y\":0.508,\"rgb\":[18,41,20],\"tol\":16}]" } },+ // normal. Before the albedo attachment it was guessed from the lit picture, and a wall the sun does not reach came out grey. WebGPU has its own+ // numbers: its cache also takes the sun's shadow map and feeds each bounce back (several bounces), which the WebGL2 fallback does not.+ { id: "gi-room-voxel", tier: "pr", webgpu: { "ESTELLA_VERIFY_EXPECT": "[{\"x\":0.5,\"y\":0.099,\"rgb\":[85,81,80],\"tol\":18},{\"x\":0.239,\"y\":0.508,\"rgb\":[85,42,37],\"tol\":18},{\"x\":0.761,\"y\":0.508,\"rgb\":[21,40,18],\"tol\":18}]" }, env: { "ESTELLA_VERIFY_PLAY": "1", "ESTELLA_VERIFY_COLORSPACE": "linear", "ESTELLA_VERIFY_SCENE": "/scenes/gi-room-voxel.esscene", "ESTELLA_VERIFY_MANIFEST": "/scenes/gi-room-voxel.textures.json", "ESTELLA_VERIFY_W": "320", "ESTELLA_VERIFY_H": "180", "ESTELLA_VERIFY_STEPS": "120", "ESTELLA_VERIFY_EXPECT": "[{\"x\":0.5,\"y\":0.099,\"rgb\":[58,58,58],\"tol\":16},{\"x\":0.239,\"y\":0.508,\"rgb\":[64,28,25],\"tol\":16},{\"x\":0.761,\"y\":0.508,\"rgb\":[18,41,20],\"tol\":16}]" } },{ id: "lightmap-model", tier: "pr", webgpu: true, env: { "ESTELLA_VERIFY_MESH_MATERIAL": "/scenes/lightmap-model/rough.esmaterial", "ESTELLA_VERIFY_SCENE": "/scenes/lightmap-model.esscene", "ESTELLA_VERIFY_MANIFEST": "/scenes/lightmap-model.textures.json", "ESTELLA_VERIFY_W": "256", "ESTELLA_VERIFY_H": "256", "ESTELLA_VERIFY_STEPS": "2", "ESTELLA_VERIFY_EXPECT": "[{\"x\":0.25,\"y\":0.4,\"rgb\":[0,255,255],\"tol\":20},{\"x\":0.25,\"y\":0.6,\"rgb\":[128,255,0],\"tol\":20},{\"x\":0.75,\"y\":0.4,\"rgb\":[29,255,61],\"tol\":20},{\"x\":0.75,\"y\":0.6,\"rgb\":[29,255,61],\"tol\":20}]" } },// Why the rectangle rides the per-object record: ONE mesh and ONE atlas, and// the two objects drawn from them read different halves of it. A rectangle