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): coalesce sorted 2d batch index gaps

yhhbdce077d5bb1
diff --git a/CHANGELOG.md b/CHANGELOG.md
index d10ad69a1..61266891f 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -16,6 +16,8 @@ published separately; it ships inside the editor.
### Fixed
+- **Sorted 2D batches join across emission index gaps.** Compatible transient quads reuse contiguous index ranges in painter order even when their producers emitted them apart, reducing UI and text draw calls without combining different clipping states or external buffers. Mixed sprite/text batches retain their original per-type entity statistics.
+
- **Runtime hierarchy inspection follows native parent additions and removals.** The tree and selected details use current component membership before reading a parent, so native edits appear immediately even when the SDK's cached hierarchy membership is stale. Detaching a node clears its parent instead of reporting the empty getter's sentinel; disabled nodes remain included.
- **Runtime tree inspection indexes script component names once per snapshot.** Large script catalogues no longer require a name search for every component on every entity. The index is rebuilt for each group read, so registration, removal, aliases and context changes remain visible; builtin membership is still read from the current core.
diff --git a/src/esengine/renderer/draw/DrawList.cpp b/src/esengine/renderer/draw/DrawList.cpp
index 320fc566b..e0c5b9043 100644
--- a/src/esengine/renderer/draw/DrawList.cpp
+++ b/src/esengine/renderer/draw/DrawList.cpp
@@ -41,10 +41,33 @@ bool relocateInstance(TransientBufferPool& pool, DrawCommand& cmd, u32 expectedA
cmd.vertex_byte_offset = at;
return true;
}
+
+bool joinBatchIndexRanges(TransientBufferPool& pool, DrawCommand& head, DrawCommand& next) {
+ const u32 used = pool.indicesUsed(LayoutId::Batch);
+ const u32 vertexBytes = pool.vertexBytesUsed(LayoutId::Batch);
+ const u32 stride = pool.vertexStride(LayoutId::Batch);
+ if (stride == 0) return false;
+ const auto owned = [&](const DrawCommand& cmd) {
+ return cmd.vertex_buffer == BufferHandle::Invalid && cmd.index_buffer == BufferHandle::Invalid
+ && cmd.index_count != 0 && cmd.index_offset <= used && cmd.index_count <= used - cmd.index_offset
+ && cmd.vertex_byte_offset <= vertexBytes
+ && cmd.vertex_count <= (vertexBytes - cmd.vertex_byte_offset) / stride;
+ };
+ if (!owned(head) || !owned(next) || head.depth_bias != next.depth_bias) return false;
+ u32 at;
+ if (head.index_offset + head.index_count != used) {
+ if (!pool.copyIndexRange(LayoutId::Batch, head.index_offset, head.index_count, at)) return false;
+ head.index_offset = at;
+ }
+ if (!pool.copyIndexRange(LayoutId::Batch, next.index_offset, next.index_count, at)) return false;
+ next.index_offset = at;
+ return head.index_offset + head.index_count == next.index_offset;
+}
} // namespace
void DrawList::clear() {
commands_.clear();
+ entity_counts_.fill(0);
sort_entries_.clear();
skin_matrices_.clear();
morph_shapes_.clear();
@@ -77,6 +100,8 @@ void DrawList::push(const DrawCommand& cmd) {
// push is the one funnel every render path goes through, so a path added
// later cannot produce a depth draw this fails to count. See needsDepth.
depth_required_ = depth_required_ || cmd.depth_test || cmd.depth_write;
+ const auto type = static_cast<u32>(cmd.type);
+ if (type < entity_counts_.size()) entity_counts_[type] += cmd.entity_count;
commands_.push_back(cmd);
}
@@ -122,6 +147,10 @@ void DrawList::finalize(TransientBufferPool& pool) {
if (writeIdx > 0) {
DrawCommand& head = commands_[writeIdx - 1];
blocker = head.mergeBlocker(commands_[i]);
+ if (blocker == BatchBreak::IndexGap && head.layout_id == LayoutId::Batch
+ && joinBatchIndexRanges(pool, head, commands_[i])) {
+ blocker = head.mergeBlocker(commands_[i]);
+ }
if (blocker == BatchBreak::None && head.instance_count != 0) {
// One more instance of geometry already being drawn. The head's
// own record moves first, so the run has somewhere to grow.
@@ -381,4 +410,4 @@ void DrawList::execute(GfxDevice& device, TransientBufferPool& buffers,
}
}
-} // namespace esengine
\ No newline at end of file
+} // namespace esengine
diff --git a/src/esengine/renderer/draw/DrawList.hpp b/src/esengine/renderer/draw/DrawList.hpp
index 491d715ec..a01a9dc75 100644
--- a/src/esengine/renderer/draw/DrawList.hpp
+++ b/src/esengine/renderer/draw/DrawList.hpp
@@ -69,6 +69,11 @@ public:
u32 addProbe(const ProbeConstants& probe);
u32 commandCount() const { return static_cast<u32>(commands_.size()); }
+ /** Entities by original submission type, independent of a merged run's head. */
+ u32 sourceEntityCount(RenderType type) const {
+ const auto index = static_cast<u32>(type);
+ return index < entity_counts_.size() ? entity_counts_[index] : 0;
+ }
u32 mergedDrawCallCount() const { return merged_draw_calls_; }
/** How many of the last finalize's draws started for @p reason. */
u32 breakCount(BatchBreak reason) const { return breaks_[static_cast<u32>(reason)]; }
@@ -192,6 +197,7 @@ private:
};
std::vector<DrawCommand> commands_;
+ std::array<u32, static_cast<u32>(RenderType::Trail) + 1> entity_counts_{};
/// Every skinned draw's bone matrices for this frame, indexed by skin_offset.
std::vector<glm::mat4> skin_matrices_;
std::vector<MorphConstants> morph_shapes_;
diff --git a/src/esengine/renderer/frame/RenderFrame.cpp b/src/esengine/renderer/frame/RenderFrame.cpp
index a5243d29b..e1ae38e3c 100644
--- a/src/esengine/renderer/frame/RenderFrame.cpp
+++ b/src/esengine/renderer/frame/RenderFrame.cpp
@@ -439,23 +439,16 @@ void RenderFrame::accumulateStats(const DrawList& list) {
// instance_count times; a batched one merged its indices in already. The
// multiply is what stops the number meaning two things on the two paths.
stats_.triangles += (cmd.index_count / 3) * (cmd.instance_count ? cmd.instance_count : 1);
- switch (cmd.type) {
- case RenderType::Sprite:
- case RenderType::UIElement:
- stats_.sprites += cmd.entity_count; break;
- case RenderType::Text: stats_.text += cmd.entity_count; break;
- case RenderType::Mesh:
- case RenderType::ExternalMesh:
- case RenderType::Trail:
- stats_.meshes += cmd.entity_count; break;
+ }
+ stats_.sprites += list.sourceEntityCount(RenderType::Sprite) + list.sourceEntityCount(RenderType::UIElement);
+ stats_.text += list.sourceEntityCount(RenderType::Text);
+ stats_.meshes += list.sourceEntityCount(RenderType::Mesh) + list.sourceEntityCount(RenderType::ExternalMesh)
+ + list.sourceEntityCount(RenderType::Trail);
#ifdef ES_ENABLE_PARTICLES
- case RenderType::Particle: stats_.particles += cmd.entity_count; break;
+ stats_.particles += list.sourceEntityCount(RenderType::Particle);
#endif
- case RenderType::Shape: stats_.shapes += cmd.entity_count; break;
- case RenderType::Skeletal: stats_.skeletal += cmd.entity_count; break;
- default: break;
- }
- }
+ stats_.shapes += list.sourceEntityCount(RenderType::Shape);
+ stats_.skeletal += list.sourceEntityCount(RenderType::Skeletal);
}
void RenderFrame::flush() {
diff --git a/src/esengine/renderer/rhi/TransientBufferPool.cpp b/src/esengine/renderer/rhi/TransientBufferPool.cpp
index 98a8d27de..5d04796cf 100644
--- a/src/esengine/renderer/rhi/TransientBufferPool.cpp
+++ b/src/esengine/renderer/rhi/TransientBufferPool.cpp
@@ -238,6 +238,21 @@ u32 TransientBufferPool::indicesUsed(LayoutId layout) const {
return stream(layout).index_write_pos;
}
+const u32* TransientBufferPool::indexData(LayoutId layout) const {
+ return stream(layout).index_staging.data();
+}
+
+bool TransientBufferPool::copyIndexRange(LayoutId layout, u32 offset, u32 count, u32& copiedAt) {
+ auto& s = stream(layout);
+ if (count == 0 || offset > s.index_write_pos || count > s.index_write_pos - offset
+ || count > ~u32{0} - s.index_write_pos) return false;
+ copiedAt = allocIndices(layout, count);
+ // Allocation can grow the vector; resolve both addresses afterwards.
+ std::memmove(s.index_staging.data() + copiedAt, s.index_staging.data() + offset,
+ static_cast<usize>(count) * sizeof(u32));
+ return true;
+}
+
BufferHandle TransientBufferPool::vertexBuffer(LayoutId layout) const {
return stream(layout).vbo;
}
diff --git a/src/esengine/renderer/rhi/TransientBufferPool.hpp b/src/esengine/renderer/rhi/TransientBufferPool.hpp
index 62be2c1b2..4896afa95 100644
--- a/src/esengine/renderer/rhi/TransientBufferPool.hpp
+++ b/src/esengine/renderer/rhi/TransientBufferPool.hpp
@@ -43,6 +43,8 @@ public:
u32 appendVertices(LayoutId layout, const void* data, u32 byteSize);
u32 appendIndices(LayoutId layout, const u32* data, u32 count);
+ /** Copy a valid written range to the stream tail; false leaves the stream unchanged. */
+ bool copyIndexRange(LayoutId layout, u32 offset, u32 count, u32& copiedAt);
/** Upload every non-empty stream's staging to its VBO/EBO. */
void upload();
@@ -70,6 +72,7 @@ public:
u8* vertexData(LayoutId layout);
u32 vertexBytesUsed(LayoutId layout) const;
u32 indicesUsed(LayoutId layout) const;
+ const u32* indexData(LayoutId layout) const;
BufferHandle vertexBuffer(LayoutId layout) const;
BufferHandle indexBuffer(LayoutId layout) const;
diff --git a/tests/renderer/test_batch_builder.cpp b/tests/renderer/test_batch_builder.cpp
index ec450903f..abe8e6e8a 100644
--- a/tests/renderer/test_batch_builder.cpp
+++ b/tests/renderer/test_batch_builder.cpp
@@ -212,6 +212,74 @@ TEST_CASE("finalize: adjacent same-key Batch draws with different textures merge
CHECK(verts[7].texIndex == 1.0f);
}
+TEST_CASE("finalize: sorted Batch index gaps merge in painter order with their texture slots") {
+ Harness h;
+ BatchVertex quad[4] = {};
+ appendQuad(h.pool, h.list, h.clips, quad, quadKey(10, 3));
+ appendQuad(h.pool, h.list, h.clips, quad, quadKey(11, 1));
+ appendQuad(h.pool, h.list, h.clips, quad, quadKey(12, 2));
+ h.list.finalize(h.pool);
+ REQUIRE(h.list.mergedDrawCallCount() == 1);
+ const auto& cmd = h.list.command(0);
+ REQUIRE(cmd.index_count == 18);
+ const u32 expected[] = {4,5,6,6,7,4, 8,9,10,10,11,8, 0,1,2,2,3,0};
+ const auto* indices = h.pool.indexData(LayoutId::Batch) + cmd.index_offset;
+ for (u32 i = 0; i < 18; i++) CHECK(indices[i] == expected[i]);
+ REQUIRE(cmd.texture_count == 3);
+ CHECK(cmd.texture_ids[0] == 11);
+ CHECK(cmd.texture_ids[1] == 12);
+ CHECK(cmd.texture_ids[2] == 10);
+ const auto* verts = reinterpret_cast<const BatchVertex*>(h.pool.vertexData(LayoutId::Batch));
+ CHECK(verts[0].texIndex == 2);
+ CHECK(verts[4].texIndex == 0);
+ CHECK(verts[8].texIndex == 1);
+}
+
+TEST_CASE("index range copies survive staging growth and reject unwritten sources") {
+ MockGfxDevice device;
+ TransientBufferPool pool{device};
+ pool.init(64, 2);
+ const u32 values[] = {9,8,7,6,5,4};
+ pool.appendIndices(LayoutId::Batch, values, 6);
+ u32 at = 99;
+ REQUIRE(pool.copyIndexRange(LayoutId::Batch, 0, 6, at));
+ CHECK(at == 6);
+ for (u32 i = 0; i < 6; i++) CHECK(pool.indexData(LayoutId::Batch)[at + i] == values[i]);
+ CHECK_FALSE(pool.copyIndexRange(LayoutId::Batch, 12, 1, at));
+ CHECK_FALSE(pool.copyIndexRange(LayoutId::Batch, 0, 13, at));
+ CHECK(pool.indicesUsed(LayoutId::Batch) == 12);
+ pool.shutdown();
+}
+
+TEST_CASE("finalize: mixed Sprite and Text runs preserve source type counts") {
+ Harness h;
+ BatchVertex quad[4] = {};
+ auto sprite = quadKey(10, 2), text = quadKey(11, 1);
+ text.type = RenderType::Text;
+ appendQuad(h.pool, h.list, h.clips, quad, sprite);
+ appendQuad(h.pool, h.list, h.clips, quad, text);
+ h.list.finalize(h.pool);
+ REQUIRE(h.list.mergedDrawCallCount() == 1);
+ CHECK(h.list.sourceEntityCount(RenderType::Sprite) == 1);
+ CHECK(h.list.sourceEntityCount(RenderType::Text) == 1);
+ h.list.clear();
+ CHECK(h.list.sourceEntityCount(RenderType::Sprite) == 0);
+ CHECK(h.list.sourceEntityCount(RenderType::Text) == 0);
+}
+
+TEST_CASE("finalize: external Batch buffers retain their separate index ranges") {
+ Harness h;
+ BatchVertex quad[4] = {};
+ appendQuad(h.pool, h.list, h.clips, quad, quadKey(10, 2));
+ appendQuad(h.pool, h.list, h.clips, quad, quadKey(10, 1));
+ auto a = h.list.command(0), b = h.list.command(1);
+ a.vertex_buffer = b.vertex_buffer = static_cast<BufferHandle>(123);
+ h.list.clear(); h.list.push(a); h.list.push(b);
+ h.list.finalize(h.pool);
+ CHECK(h.list.mergedDrawCallCount() == 2);
+ CHECK(h.pool.indicesUsed(LayoutId::Batch) == 12);
+}
+
TEST_CASE("finalize: different streams never coalesce; instanced draws stay one per emitter") {
Harness h;
BatchVertex quad[4] = {};
@@ -1034,7 +1102,7 @@ TEST_CASE("opaque: material still outranks depth, since order cannot change the
// 20 bits is sign + exponent + 11 mantissa bits, so the step is ~2^-11 of the
// exponent's range: about 0.004 around z=10. Closer than that shares a key and
// keeps submission order, which is the quantization talking, not a rule.
-TEST_CASE("transparent: hundredths of depth separate; thousandths share a bucket") {
+TEST_CASE("transparent: sorted index runs preserve distinct depth keys and quantized ties") {
Harness h;
BatchVertex quad[4] = {};
@@ -1042,19 +1110,27 @@ TEST_CASE("transparent: hundredths of depth separate; thousandths share a bucket
BatchDrawKey farther = quadKey(2, 3); farther.materialId = 1; farther.depth = 10.00f;
appendQuad(h.pool, h.list, h.clips, quad, nearer);
appendQuad(h.pool, h.list, h.clips, quad, farther);
+ CHECK(h.list.command(1).sort_key < h.list.command(0).sort_key);
h.list.finalize(h.pool);
- REQUIRE(h.list.mergedDrawCallCount() == 2);
+ REQUIRE(h.list.mergedDrawCallCount() == 1);
CHECK(h.list.command(0).texture_ids[0] == 2);
- CHECK(h.list.command(1).texture_ids[0] == 1);
+ CHECK(h.list.command(0).texture_ids[1] == 1);
+ const auto* sorted = h.pool.indexData(LayoutId::Batch) + h.list.command(0).index_offset;
+ CHECK(sorted[0] == 4);
+ CHECK(sorted[6] == 0);
Harness fine;
BatchDrawKey a = quadKey(1, 3); a.materialId = 1; a.depth = 10.001f;
BatchDrawKey b = quadKey(2, 3); b.materialId = 1; b.depth = 10.000f;
appendQuad(fine.pool, fine.list, fine.clips, quad, a);
appendQuad(fine.pool, fine.list, fine.clips, quad, b);
+ CHECK(fine.list.command(0).sort_key == fine.list.command(1).sort_key);
fine.list.finalize(fine.pool);
CHECK(fine.list.mergedDrawCallCount() == 1);
+ const auto* tied = fine.pool.indexData(LayoutId::Batch) + fine.list.command(0).index_offset;
+ CHECK(tied[0] == 0);
+ CHECK(tied[6] == 4);
}
// ─── Transient buffer growth ─────────────────────────────────────────────────
@@ -1179,11 +1255,18 @@ TEST_CASE("group: an outsider cannot be drawn between two members") {
appendQuad(h.pool, h.list, h.clips, quad, high);
h.list.finalize(h.pool);
- REQUIRE(h.list.mergedDrawCallCount() == 3);
+ REQUIRE(h.list.mergedDrawCallCount() == 2);
// The two members adjacent and in their stated order, the outsider clear of both.
CHECK(h.list.command(0).texture_ids[0] == 1);
- CHECK(h.list.command(1).texture_ids[0] == 3);
- CHECK(h.list.command(2).texture_ids[0] == 2);
+ CHECK(h.list.command(0).texture_ids[1] == 3);
+ CHECK(h.list.command(1).texture_ids[0] == 2);
+ const auto* indices = h.pool.indexData(LayoutId::Batch) + h.list.command(0).index_offset;
+ CHECK(indices[0] == 0);
+ CHECK(indices[6] == 8);
+ const auto members = h.list.runEntities(0);
+ REQUIRE(members.size() == 2);
+ CHECK(members[0] == Entity(11));
+ CHECK(members[1] == Entity(12));
}
// Everything derived from a layer has to come from the GROUP's layer. A member whose
@@ -1266,8 +1349,15 @@ TEST_CASE("group: a nested group's contents stay one block") {
appendQuad(h.pool, h.list, h.clips, quad, blockHigh);
h.list.finalize(h.pool);
- REQUIRE(h.list.mergedDrawCallCount() == 3);
- CHECK(h.list.command(2).texture_ids[0] == 2); // the sibling is above the whole block
+ REQUIRE(h.list.mergedDrawCallCount() == 2);
+ CHECK(h.list.command(1).texture_ids[0] == 2); // the sibling is above the whole block
+ const auto* indices = h.pool.indexData(LayoutId::Batch) + h.list.command(0).index_offset;
+ CHECK(indices[0] == 0);
+ CHECK(indices[6] == 8);
+ const auto members = h.list.runEntities(0);
+ REQUIRE(members.size() == 2);
+ CHECK(members[0] == Entity(41));
+ CHECK(members[1] == Entity(42));
}
// A group that is not there changes nothing — the field that decides is the table,
diff --git a/tools/releaseNotes.mjs b/tools/releaseNotes.mjs
index 2e0ae9c49..f55f629fc 100644
--- a/tools/releaseNotes.mjs
+++ b/tools/releaseNotes.mjs
@@ -28,6 +28,8 @@ export const NOTES_FLOOR = 'v0.65.0';
* the reader recognises anyway.
*/
export const NOTED = {
+ 'perf(renderer): coalesce sorted 2d batch index gaps':
+ { note: 'Sorted 2D batches join across emission index gaps.' },
'fix(inspector): read current native parent membership in runtime snapshots':
{ note: 'Runtime hierarchy inspection follows native parent additions and removals.' },
'perf(inspector): index script names once per runtime tree snapshot':
diff --git a/tools/renderScenes.mjs b/tools/renderScenes.mjs
index 09587bd23..e1293c90c 100644
--- a/tools/renderScenes.mjs
+++ b/tools/renderScenes.mjs
@@ -68,7 +68,7 @@ export const SCENES = [
// What the BATCHER achieved, which no pixel can show: nineteen sprites over two
// textures reach the GPU as three draws. Every break is accounted for to its
// reason — one run head, two index gaps, no state break at all.
- { id: "sprite-batch", tier: "pr", webgpu: true, env: { ESTELLA_VERIFY_SCENE: "/scenes/sprite-rendering.esscene", ESTELLA_VERIFY_MANIFEST: "/scenes/sprite-rendering.textures.json", ESTELLA_VERIFY_W: "256", ESTELLA_VERIFY_H: "256", ESTELLA_VERIFY_STEPS: "2", ESTELLA_VERIFY_COUNTERS: "{\"render.sprites\":19,\"batch.draws\":3,\"batch.merged\":16,\"batch.break.runStart\":1,\"batch.break.indexGap\":2}" } },
+ { id: "sprite-batch", tier: "pr", webgpu: true, env: { ESTELLA_VERIFY_SCENE: "/scenes/sprite-rendering.esscene", ESTELLA_VERIFY_MANIFEST: "/scenes/sprite-rendering.textures.json", ESTELLA_VERIFY_W: "256", ESTELLA_VERIFY_H: "256", ESTELLA_VERIFY_STEPS: "2", ESTELLA_VERIFY_COUNTERS: "{\"render.sprites\":19,\"batch.draws\":1,\"batch.merged\":18,\"batch.break.runStart\":1}" } },
// Editor grid on/off pixel diff — guards the custom-draw reflected material path (drawMeshWithMaterial + MaterialConstants UBO).
{ id: "editor-grid", tier: "pr", webgpu: true, env: { ESTELLA_VERIFY_GRID: "64", ESTELLA_VERIFY_STEPS: "3" } },
// The same grid respaced after it has drawn: a uniform changed after its first upload has to reach the frame, which on WebGPU it once did not (the grid stayed where the view first looked).