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(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.md
index 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.cpp
index 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, DrawComm
void 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.hpp
index 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.cpp
index 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 merge
CHECK(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.mjs
index 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"},
};