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.

feat(renderer): the finalize spike has an author, and it is not the work

esengine8f06bbf31f47
diff --git a/bench/residency/README.md b/bench/residency/README.md
index 990e2779c..51a182034 100644
--- a/bench/residency/README.md
+++ b/bench/residency/README.md
@@ -630,6 +630,48 @@ separate mechanism that has been visible in every run here and has never been
decomposed — they carry no collect, and they land outside every arrival window.
That is the next cut.
+### Render Finalize Spike Decomposition — the author, not yet a fix
+
+`render.finalize` held two synchronous calls and no scopes inside it, so a 9–15 ms
+spike visible in every run here had a name and no author. It has one now, and the
+top level was enough:
+
+| | steady | spiking |
+| --- | --- | --- |
+| `render.finalize` | 0.1 ms | 4.3–7.4 ms |
+| `render.finalize.upload` | 0.1 ms | 4.3–7.4 ms |
+| `render.finalize.drawList` | 0.1–0.2 ms | 0.1–0.2 ms |
+
+`upload` equals `finalize` to the printed digit on every spike across eight runs
+(f166 7.4, f209 4.3, f205 4.8, f166 6.0, f169 5.4). `drawList.finalize` — the sort
+and the coalesce — is not it.
+
+**And the work does not change.** The counters say what the upload was ASKED to
+move on the very frame it cost 6 ms:
+
+ steady 0.80 ms streams 1 vtx 50028 B idx 0 B grows 0 writes 1
+ f166 6.90 ms streams 1 vtx 50028 B idx 0 B grows 0 writes 1
+ f169 6.20 ms streams 1 vtx 50028 B idx 0 B grows 0 writes 1
+
+One stream, one `updateBuffer`, the same 50 028 bytes, no buffer growth — and
+sixty times the cost. This is not a workload spike. It is the same call, on the
+same bytes, occasionally blocking.
+
+Destructively: skipping the `updateBuffer` calls and leaving everything else about
+the frame standing, `render.finalize` does not reach the 4 ms spike list once in
+eight runs, against five spikes in eight wired runs. The largest frames that
+remain are publication frames, whose render scopes total 1.9 ms of a 16 ms wall.
+
+**What this measures, and what it does not.** These scopes bracket the CALL. In
+WebGL2 `updateBuffer` is `glBufferSubData`, which may block on the driver and
+therefore shows here; anything the GPU does afterwards has its own clock and is
+not in this number. A wall clock cannot stand in for GPU time — that needs
+timestamp queries, which is a different instrument and not this one.
+
+Not optimised, deliberately. The next question is why the same write blocks, and
+the shape of the answer (buffer still in flight, orphaning, a second stream)
+decides the fix. Measuring it as fixed before that would be picking one.
+
### Instrumentation, and how it is kept honest
The driver's probe used to call `enableStats()` on every read, swapping the maps
diff --git a/bench/residency/heavy.mjs b/bench/residency/heavy.mjs
index 77768438c..bacd2061a 100755
--- a/bench/residency/heavy.mjs
+++ b/bench/residency/heavy.mjs
@@ -567,12 +567,26 @@ function report(arm, frames, delivery) {
.sort((a, b) => b.f.ms - a.f.ms).slice(0, 6);
if (spikes.length > 0) {
console.log('\n every frame more than 4 ms above steady state:');
+ const calm = frames.slice(-60).find((f) => f.upload && f.upload[1] > 0);
+ if (calm) {
+ console.log(` steady ${calm.ms.toFixed(2).padStart(7)} ms`
+ + ` upload streams ${calm.upload[0]} vtx ${calm.upload[1]}B`
+ + ` idx ${calm.upload[2]}B grows ${calm.upload[3]} writes ${calm.upload[4]}`);
+ }
for (const { i, f } of spikes) {
const own = arrived && i >= arrivalAt && i < arrivalAt + window.length;
console.log(` f${String(i).padEnd(5)}${f.ms.toFixed(2).padStart(7)} ms`
+ ` collect ${(f.collect ?? 0).toFixed(2).padStart(6)}`
+ ` drawn ${String(drawn(f)).padStart(5)}`
+ ` ${own ? '(the arrival)' : '(NOT the arrival)'}`);
+ // Beside the cost, what the upload was asked to move on that very
+ // frame — and what a quiet frame was asked to move, so "the same
+ // bytes cost ten times as much" is readable rather than inferred.
+ const u = f.upload;
+ if (u) {
+ console.log(` upload streams ${u[0]} vtx ${u[1]}B idx ${u[2]}B`
+ + ` grows ${u[3]} writes ${u[4]}`);
+ }
// A spike with no collect in it is a different mechanism wearing the
// same shape, and naming it needs its own scopes rather than the
// window's — which is what made it look like a delayed arrival.
diff --git a/src/esengine/renderer/frame/RenderFrame.cpp b/src/esengine/renderer/frame/RenderFrame.cpp
index d9ef5bfb7..95439d588 100644
--- a/src/esengine/renderer/frame/RenderFrame.cpp
+++ b/src/esengine/renderer/frame/RenderFrame.cpp
@@ -467,8 +467,16 @@ void RenderFrame::flush() {
// host asks for them before the graph has run.
{
ES_PROFILE_SCOPE("render.finalize");
- draw_list_.finalize(pool_);
- pool_.upload();
+ // Around the CALLS, which are synchronous: what the device does with an
+ // upload afterwards is its own clock and cannot be read off this one.
+ {
+ ES_PROFILE_SCOPE("render.finalize.drawList");
+ draw_list_.finalize(pool_);
+ }
+ {
+ ES_PROFILE_SCOPE("render.finalize.upload");
+ pool_.upload();
+ }
}
// The rect the scene draws into. Opening a pass resets the viewport, so the
diff --git a/src/esengine/renderer/rhi/TransientBufferPool.cpp b/src/esengine/renderer/rhi/TransientBufferPool.cpp
index 053ef9336..1389e7cc8 100644
--- a/src/esengine/renderer/rhi/TransientBufferPool.cpp
+++ b/src/esengine/renderer/rhi/TransientBufferPool.cpp
@@ -2,6 +2,7 @@
// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
#include "./TransientBufferPool.hpp"
#include "../../core/Log.hpp"
+#include "../../core/FrameProfiler.hpp"
#include <cstring>
#include <algorithm>
@@ -123,11 +124,18 @@ u32 TransientBufferPool::appendIndices(LayoutId layout, const u32* data, u32 cou
}
void TransientBufferPool::upload() {
+ // What the upload was ASKED to move, beside what it cost. A spike that tracks
+ // bytes is workload; a spike at unchanged bytes is the allocation or driver
+ // path, and one number cannot tell those apart.
+ u32 streams = 0, vertexBytes = 0, indexBytes = 0, grows = 0, writes = 0;
// Growth goes through resizeBuffer, which keeps the handle stable, so per-draw
// buffer bindings and the backend's cached vertex state stay valid.
for (auto& s : streams_) {
if (s.vbo == BufferHandle::Invalid) continue;
if (s.vertex_write_pos == 0 && s.index_write_pos == 0) continue;
+ ++streams;
+ vertexBytes += s.vertex_write_pos;
+ indexBytes += s.index_write_pos * static_cast<u32>(sizeof(u32));
// Grow to the STAGING capacity, which already doubles — not to what this
// frame needed, which reallocates every frame for a workload creeping
@@ -135,8 +143,10 @@ void TransientBufferPool::upload() {
if (s.vertex_write_pos > s.vbo_capacity) {
s.vbo_capacity = static_cast<u32>(s.vertex_staging.size());
device_.resizeBuffer(s.vbo, s.vbo_capacity, s.vertex_staging.data());
+ ++grows;
} else if (s.vertex_write_pos > 0) {
device_.updateBuffer(s.vbo, 0, s.vertex_staging.data(), s.vertex_write_pos);
+ ++writes;
}
u32 eboBytes = s.index_write_pos * sizeof(u32);
@@ -145,10 +155,17 @@ void TransientBufferPool::upload() {
s.ebo_capacity = static_cast<u32>(s.index_staging.size());
device_.resizeBuffer(s.ebo, static_cast<u32>(s.ebo_capacity * sizeof(u32)),
s.index_staging.data());
+ ++grows;
} else if (eboBytes > 0) {
device_.updateBuffer(s.ebo, 0, s.index_staging.data(), eboBytes);
+ ++writes;
}
}
+ ES_PROFILE_COUNTER("render.upload.streams", streams);
+ ES_PROFILE_COUNTER("render.upload.vertexBytes", vertexBytes);
+ ES_PROFILE_COUNTER("render.upload.indexBytes", indexBytes);
+ ES_PROFILE_COUNTER("render.upload.grows", grows);
+ ES_PROFILE_COUNTER("render.upload.writes", writes);
}
void TransientBufferPool::bindLayout(LayoutId layout) {
diff --git a/tools/launchers/residency-run.mjs b/tools/launchers/residency-run.mjs
index f57b90955..49a2a55b6 100644
--- a/tools/launchers/residency-run.mjs
+++ b/tools/launchers/residency-run.mjs
@@ -341,6 +341,14 @@ async function main() {
// makes a frame expensive, so recording it only there cannot answer
// whether a cheap arrival had one.
row.compiles = counters['render.mesh.programCompiles'] ?? 0;
+ // What the upload was ASKED to move, on EVERY frame: a spike that tracks
+ // bytes is workload, and one at unchanged bytes is the allocation path.
+ // Five numbers rather than the table, which overruns the pipe.
+ row.upload = [counters['render.upload.streams'] ?? 0,
+ counters['render.upload.vertexBytes'] ?? 0,
+ counters['render.upload.indexBytes'] ?? 0,
+ counters['render.upload.grows'] ?? 0,
+ counters['render.upload.writes'] ?? 0];
row.domains = {};
for (const c of costs.systems) row.domains[c.domain] = (row.domains[c.domain] ?? 0) + c.ms;
for (const d of Object.keys(row.domains)) row.domains[d] = Math.round(row.domains[d] * 1000) / 1000;