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
perf(render): a frame of 2D sprites is not sorted again when its draw keys are the last frame's
yhhca1cbbfe2185
diff --git a/CHANGELOG.md b/CHANGELOG.mdindex e80fb670d..b4137f525 100644--- a/CHANGELOG.md+++ b/CHANGELOG.md@@ -47,6 +47,7 @@ published separately; it ships inside the editor.### Changed+- **A frame of 2D sprites is not sorted again when its draw keys are the last frame's.** The draw list sorted every command each frame, 0.15 ms for 4,000 sprites and growing as n log n, although a 2D key holds the layer, shader, blend and material and no position: sprites that move, or do not, give the same keys frame after frame. The order is a function of the key sequence alone (ties break on emit index), so a frame with the same keys takes the last frame's order and skips the sort. The draw list's finalize in a 4,000-sprite scene goes from 0.30 ms to 0.10 ms. The sort result is the same bit for bit; a frame whose keys differ is sorted as before.- **The sky's clouds are worked out at a quarter of the size, 0.9 ms cheaper.** The cloud layer marches sixteen steps a pixel, each with three octaves of noise and three more samples toward the sun, and the surfaces' shadow from it costs almost nothing: all of the 1.6 ms of the `sky_clouds` pass in the terrain-water example was the layer over the sky. The clouds are smooth, so the pass now runs at a quarter of the width and height (half before) and the composite reads it back as it did. In a cloud scene no pixel is more than 2 of 255 from the half-size picture; in the example the difference is below what two runs of the same build differ by. 1.6 ms to 0.7 ms of a 1080p frame.- **Lens flare costs a third of what it did.** The flare looked ninety places in the picture for something bright at every pixel of the full-size frame, to light almost none of them: 0.76 ms of a 1080p frame in the terrain-water example. It is now worked out at half size and laid over the full-size picture (0.22 ms and 0.07 ms), 0.47 ms less. The picture is the same except along the hard edges of whatever throws the flare, where it softens by a pixel or two (0.6 of 255 on average in a scene built to make that worst). A new render scene, `hdr-lens-flare`, is the first to check a flare on both backends.- **The engine's own examples and fixtures no longer commit a generated WebGPU shader twin.** The `wgsl full` section of a `.esshader` is a translation of its GLSL joined to the engine's headers, so every edit to an engine header (the render origin in `FrameConstants`, a lighting function) changed it in dozens of files nobody had touched: 83% of that text is the engine's own lighting code, 2% the author's. It is now derived when the shader is read: by the export (`cookAssets`), by the fixture server the render checks use, and by the editor when it serves a project of the repo. Deriving all 44 shaders takes 2.3 s. `gen-shader-twins --derived` checks that each one still translates and that none commits a twin again; a project of your own keeps its twin in the file as before, because the converters are not in a packaged editor. 18 files lose about 11,000 lines; the 248 WebGPU render scenes draw the same.diff --git a/src/esengine/renderer/draw/DrawList.cpp b/src/esengine/renderer/draw/DrawList.cppindex 15a7debaa..1319deef2 100644--- a/src/esengine/renderer/draw/DrawList.cpp+++ b/src/esengine/renderer/draw/DrawList.cpp@@ -71,7 +71,6 @@ bool joinBatchIndexRanges(TransientBufferPool& pool, DrawCommand& head, DrawCommvoid DrawList::clear() {commands_.clear();entity_counts_.fill(0);- sort_entries_.clear();skin_matrices_.clear();morph_shapes_.clear();probes_.clear();@@ -120,18 +119,28 @@ void DrawList::finalize(TransientBufferPool& pool) {return;}- sort_entries_.resize(count);- for (u32 i = 0; i < count; ++i) {- sort_entries_[i] = { commands_[i].sort_key, i };- }+ // The order the keys give is the order the last frame's identical keys gave: the sort below is a function of the key sequence alone, so a+ // frame whose keys match is not sorted again. Sprites that move rarely change their key (2D keys hold layer, shader, blend and material, not+ // where a sprite is), which makes this the common frame.+ bool sameKeys = sorted_keys_.size() == count && sort_entries_.size() == count;+ for (u32 i = 0; sameKeys && i < count; ++i) sameKeys = sorted_keys_[i] == commands_[i].sort_key;+ ES_PROFILE_COUNTER("batch.sortReused", sameKeys ? 1 : 0);+ if (!sameKeys) {+ sort_entries_.resize(count);+ sorted_keys_.resize(count);+ for (u32 i = 0; i < count; ++i) {+ sort_entries_[i] = { commands_[i].sort_key, i };+ sorted_keys_[i] = commands_[i].sort_key;+ }- // Tie-break on emit index so same-key commands keep submission order: that keeps an- // emit-contiguous run contiguous after sorting, which is what lets the merge coalesce it- // (including across different textures, now that texture is out of the key).- std::sort(sort_entries_.begin(), sort_entries_.end(),- [](const SortEntry& a, const SortEntry& b) {- return a.key < b.key || (a.key == b.key && a.index < b.index);- });+ // Tie-break on emit index so same-key commands keep submission order: that keeps an+ // emit-contiguous run contiguous after sorting, which is what lets the merge coalesce it+ // (including across different textures, now that texture is out of the key).+ std::sort(sort_entries_.begin(), sort_entries_.end(),+ [](const SortEntry& a, const SortEntry& b) {+ return a.key < b.key || (a.key == b.key && a.index < b.index);+ });+ }// Gather into a reused scratch buffer (not a fresh per-frame vector) and swap// it with commands_, so the allocation is amortized across frames.diff --git a/src/esengine/renderer/draw/DrawList.hpp b/src/esengine/renderer/draw/DrawList.hppindex d2c68b6ba..f8929047e 100644--- a/src/esengine/renderer/draw/DrawList.hpp+++ b/src/esengine/renderer/draw/DrawList.hpp@@ -255,7 +255,10 @@ private:};std::vector<StagedBlocks> staged_;void stageBlocks(const PerDrawBlockSet& blocks);+ /// The sorted order of the last finalize and the keys, in emit order, it was sorted from. The order is a function of the keys alone (ties break on+ /// emit index), and in 2D the key holds no position, so a frame of moving sprites has the keys of the frame before it.std::vector<SortEntry> sort_entries_;+ std::vector<u64> sorted_keys_;std::vector<DrawCommand> sorted_scratch_; // reused across frames to avoid a// per-frame heap alloc in finalize()std::vector<DrawCommand> stencil_commands_scratch_;diff --git a/tests/renderer/test_batch_builder.cpp b/tests/renderer/test_batch_builder.cppindex f717b78f2..dece5bfbf 100644--- a/tests/renderer/test_batch_builder.cpp+++ b/tests/renderer/test_batch_builder.cpp@@ -340,6 +340,31 @@ TEST_CASE("finalize: adjacent same-key Batch draws with different textures mergeCHECK(verts[7].texIndex == 1.0f);}+TEST_CASE("finalize: a frame with the same keys as the last takes its order, a frame with other keys is sorted again") {+ Harness h;+ BatchVertex quad[4] = {};+ // Layers say the order, textures say which draw is which: what a frame draws is read back from the merged draw's slots.+ const auto frame = [&](const i32 (&layers)[3], const u32 (&textures)[3]) {+ h.list.clear();+ h.pool.beginFrame();+ for (int i = 0; i < 3; ++i) appendQuad(h.pool, h.list, h.clips, quad, quadKey(textures[i], layers[i]));+ h.list.finalize(h.pool);+ REQUIRE(h.list.mergedDrawCallCount() == 1);+ return h.list.command(0);+ };+ const DrawCommand first = frame({3, 1, 2}, {10, 11, 12});+ CHECK((std::vector<u32>{first.texture_ids[0], first.texture_ids[1], first.texture_ids[2]} == std::vector<u32>{11, 12, 10}));+ // The same layers, so the same order, over other draws.+ const DrawCommand same = frame({3, 1, 2}, {20, 21, 22});+ CHECK((std::vector<u32>{same.texture_ids[0], same.texture_ids[1], same.texture_ids[2]} == std::vector<u32>{21, 22, 20}));+ // Other layers: the order of the frame before is not the order of this one.+ const DrawCommand other = frame({1, 3, 2}, {30, 31, 32});+ CHECK((std::vector<u32>{other.texture_ids[0], other.texture_ids[1], other.texture_ids[2]} == std::vector<u32>{30, 32, 31}));+ // And back to the first keys again, from a list that last sorted something else.+ const DrawCommand back = frame({3, 1, 2}, {40, 41, 42});+ CHECK((std::vector<u32>{back.texture_ids[0], back.texture_ids[1], back.texture_ids[2]} == std::vector<u32>{41, 42, 40}));+}+TEST_CASE("finalize: sorted Batch index gaps merge in painter order with their texture slots") {Harness h;BatchVertex quad[4] = {};diff --git a/tools/releaseNotes.mjs b/tools/releaseNotes.mjsindex a5813083c..7d12a2042 100644--- a/tools/releaseNotes.mjs+++ b/tools/releaseNotes.mjs@@ -3078,4 +3078,6 @@ export const NOTED = {{"note":"Lens flare costs a third of what it did"},"perf(render): the sky's clouds are worked out at a quarter of the size":{"note":"The sky's clouds cost 0.9 ms less"},+ "perf(render): a frame of 2D sprites is not sorted again when its draw keys are the last frame's":+ {"note":"A frame of sprites is not sorted again when its draw keys have not changed"},};