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): instanced meshes that share a material draw together and merge

yhhfcafb102dc95
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 5da2bb2cd..1d231f3ab 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -43,6 +43,7 @@ published separately; it ships inside the editor.
### Changed
+- **Instanced meshes that share a material now draw together, so a scene makes a tenth of the draw calls.** An opaque draw sorted by shader, then material, then depth, so two meshes sharing a material alternated by depth and no two neighbours were the same mesh: every instanced draw broke the merge (610 of 612 in the terrain-water example). An instanced mesh draw now puts a hash of its geometry in the top bits of the depth field, so one mesh's draws sit together and merge into one instanced call, in the scene, the depth prepass and the shadow pass alike. The example goes from 612 scene, 610 prepass and 385 shadow draws to 57, 55 and 45, from 10,709 GL calls a frame to 1,977, and from about 6.2 ms to 4.1 ms of CPU a frame. Only the order among opaque draws of one material changes, and they are order-independent (they write depth); the 262 WebGL2 render scenes still draw what they claim.
- **The GL device no longer sets state the context already holds.** Enabling or disabling depth test, stencil, culling and blend, the depth, colour and stencil write masks, and the binding of a uniform-buffer slot were each sent to the driver on every draw even when the value had not changed. The device now remembers the last value and skips the call (a buffer that is deleted forgets the slots it held). On the terrain-water example a frame makes 10,709 GL calls instead of 26,223, and the CPU side of the frame is about 0.3 to 0.5 ms lighter on a desktop browser; a phone, where each call costs more, gains more. Pixels are unchanged: the 262 WebGL2 render scenes still draw what they claim.
- **Writing one material uniform sends that one value, and asking whether the GPU can render to float no longer walks its extension list.** `Material.setUniform` re-defined the whole material and pushed every one of its uniforms into wasm (a string across the boundary each) for each value written, and then did the same for every instance that inherits it, so a system that sets twenty values a frame on a material of sixty made twelve hundred crossings. It sends the value that changed, to the instances that inherit it and not to those that override it; a value the engine already holds is not sent at all; a texture still takes the whole flush, since its lease is counted. In the terrain and water example `setUniform` went from 0.40 to 0.03 ms a frame. The post-process chain asked `supportsFloatTargets()` several times a frame and each ask read every extension the context has through the browser; it is answered once per context. The frame is 6.2-6.7 ms with the engine's profiler off (it was 6.7-6.9 after the last change, and 8.4 before it); every render scene draws what it did (262 of 262 on WebGL2, 248 of 248 on WebGPU). A value handed to two materials as one object and then edited used to reach each of them whenever it next flushed; now each sees the value as it was when written to it.
- **A mesh draw no longer searches its shader's source or rebuilds a feature list to find a program it already has.** `MaterialStore::meshProgram`, asked once per mesh draw, looked for "ES_GBUFFER" through the whole text of the material's shader every time and built nine strings and a vector before it checked its cache. The mention is found once when the source is stored and the cache is asked first. With the engine's own profiler off, the terrain and water example's frame at a CPU-bound size went from 8.4 to 6.7-6.9 ms (about 19% less), the same programs are chosen, and every render scene draws what it did (262 of 262 on WebGL2, 248 of 248 on WebGPU). Note for anyone reading the frame costs: switching the engine's profiler on (`render()`, `costs()`, `gpu()` on the cooked hook) made that frame 76% dearer, so a per-phase number from it says where time goes, not what it costs; `render.collect.mesh.<scene|depth>.walks/.visits/.ms` now say which pass walked the meshes and how many times (two per frame in that example: the scene and the sun's shadow).
diff --git a/src/esengine/renderer/draw/BatchBuilder.cpp b/src/esengine/renderer/draw/BatchBuilder.cpp
index 175330ed2..acaf8cd0f 100644
--- a/src/esengine/renderer/draw/BatchBuilder.cpp
+++ b/src/esengine/renderer/draw/BatchBuilder.cpp
@@ -97,7 +97,10 @@ void pushBatchDraw(DrawList& drawList, const ClipState& clips,
? DrawCommand::buildSortKeyYSorted(stage, layer, key.y, key.shaderId,
key.blend, 0, order)
: DrawCommand::buildSortKey(stage, layer, key.shaderId,
- key.blend, 0, key.depth, key.materialId, order);
+ key.blend, 0, key.depth, key.materialId, order,
+ key.instanceCount != 0 && key.vertexBuffer != BufferHandle::Invalid
+ ? (static_cast<u32>(key.vertexBuffer) * 2654435761u) >> 24 | 1u
+ : 0u);
// Inside a group the member's own order is all that separates siblings. Under a NESTED
// group it is the inner group's instead — a block does not come apart around another
// block's contents.
diff --git a/src/esengine/renderer/draw/DrawCommand.hpp b/src/esengine/renderer/draw/DrawCommand.hpp
index aa68e70fa..e78754a3c 100644
--- a/src/esengine/renderer/draw/DrawCommand.hpp
+++ b/src/esengine/renderer/draw/DrawCommand.hpp
@@ -196,7 +196,7 @@ struct DrawCommand {
// material groups first and depth breaks ties. Interleaved orders cost early-z.
// [63:48] layer | [47:40] order | [39:38] stage, then 38 bits the stage decides:
- // opaque [37:30] shader | [29:27] blend | [26:25] flags | [24:14] material | [13:0] depth
+ // opaque [37:30] shader | [29:27] blend | [26:25] flags | [24:14] material | [13:0] depth (or [13:6] geometry | [5:0] depth)
// blended [37:18] depth | [17:10] shader | [9:7] blend | [6:5] flags | [4:0] material
// A SortingGroup owns [63:40] for its members; [37:30] then carries the member's own
@@ -211,9 +211,13 @@ struct DrawCommand {
static_assert(static_cast<u32>(RenderStage::Overlay) <= 3,
"RenderStage outgrew the sort key's 2-bit field — re-lay the key out");
+ // `geometry`, when nonzero, is a hash of the mesh an instanced opaque draw repeats. It takes the top bits of the opaque depth field, so draws
+ // of one mesh that share a material sort together and merge into one instanced draw rather than alternating with another mesh's by depth. A
+ // batching hint like the material: a collision costs a merge, never a wrong draw. Opaque draws are order-independent, so only the coarse
+ // front-to-back order inside a mesh's run is spent.
static u64 buildSortKey(RenderStage stage, i32 layer, u32 shaderId,
BlendMode blend, u16 stateFlags, f32 depth, u32 materialId = 0,
- i32 order = 0) {
+ i32 order = 0, u32 geometry = 0) {
i32 normalizedLayer = std::clamp(layer + 32768, 0, 65535);
u64 layerKey = static_cast<u64>(normalizedLayer & 0xFFFF) << 48;
@@ -236,12 +240,15 @@ struct DrawCommand {
| (static_cast<u64>(stateFlags & 0x03) << 5)
| (static_cast<u64>(materialId) & 0x1F);
}
+ const u64 depthField = geometry != 0
+ ? (static_cast<u64>(geometry & 0xFF) << 6) | static_cast<u64>(orderedDepth >> 26)
+ : static_cast<u64>(orderedDepth >> 18);
return layerKey | orderBits(order) | stageKey
| (static_cast<u64>(shaderId & 0xFF) << 30)
| (blendBits(blend) << 27)
| (static_cast<u64>(stateFlags & 0x03) << 25)
| ((static_cast<u64>(materialId) & 0x7FF) << 14)
- | static_cast<u64>(orderedDepth >> 18);
+ | depthField;
}
/** @brief The blend field, 3 bits wide wherever it appears.
diff --git a/tests/renderer/test_sort_key.cpp b/tests/renderer/test_sort_key.cpp
index b5210c818..0c73f05ec 100644
--- a/tests/renderer/test_sort_key.cpp
+++ b/tests/renderer/test_sort_key.cpp
@@ -4,6 +4,7 @@
#include "esengine/renderer/draw/DrawCommand.hpp"
+#include <algorithm>
#include <cstdio>
using namespace esengine;
@@ -126,6 +127,18 @@ int main() {
"a scissored draw is not a stencilled one");
}
+ // An instanced mesh draw sorts by its geometry inside a material, so two meshes sharing one do not alternate by depth.
+ {
+ auto mesh = [](u32 geometry, f32 depth) {
+ return DrawCommand::buildSortKey(RenderStage::Opaque, 0, 3, BlendMode::None, 0, depth, 9, 0, geometry);
+ };
+ const u64 a1 = mesh(5, 1.0f), a2 = mesh(5, 40.0f), b1 = mesh(7, 2.0f), b2 = mesh(7, 30.0f);
+ CHECK(std::max(a1, a2) < std::min(b1, b2), "draws of one mesh sit together, whatever their depths");
+ CHECK(mesh(5, 1.0f) != mesh(5, 40.0f), "depth still orders within a mesh");
+ CHECK((mesh(5, 1.0f) >> 14) == (mesh(7, 1.0f) >> 14), "geometry stays below the material field");
+ CHECK(mesh(0, 1.0f) == opaque(0, 0, 1.0f, 3, 9), "no geometry leaves the key as it was");
+ }
+
std::printf(g_failures ? "\n%d check(s) failed\n" : "\nall checks passed\n", g_failures);
return g_failures == 0 ? 0 : 1;
}
diff --git a/tools/releaseNotes.mjs b/tools/releaseNotes.mjs
index 9821085aa..dbb5c8ab5 100644
--- a/tools/releaseNotes.mjs
+++ b/tools/releaseNotes.mjs
@@ -3034,4 +3034,6 @@ export const NOTED = {
{"note":"Writing one material uniform sends that one value"},
"perf(render): the GL device skips state sets and uniform-buffer binds the context already holds":
{"note":"The GL device skips state sets the context already holds"},
+ "perf(render): instanced meshes that share a material draw together and merge":
+ {"note":"Instanced meshes that share a material draw together and merge"},
};