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): each render-graph pass has its own GPU time, on WebGL2 and WebGPU, read through the profiler

yhhe1c79c282dd3
diff --git a/docs/GPU_PERFORMANCE_OPTIONS.md b/docs/GPU_PERFORMANCE_OPTIONS.md
index 7221673e2..924d11980 100644
--- a/docs/GPU_PERFORMANCE_OPTIONS.md
+++ b/docs/GPU_PERFORMANCE_OPTIONS.md
@@ -6,7 +6,7 @@
引擎只有**整个渲染图一个** GPU 计时器(`render.graph`),场景的网格绘制还在图外。所以这一轮每个数都是“拿掉一样东西,看整帧差多少”(消融),有的还要为了量一个着色器阶段重新编一个引擎。这能用,但慢,而且各部分不能相加。
-- **0. 逐 pass 的 GPU 计时(基础设施)。** 渲染图的每个 pass 已经有名字(`gtao_ao`、`bloom_kawase_0`、`scene-grab`、阴影的每张图…)。WebGPU 有时间戳查询(`timestamp-query`),WebGL2 有 `EXT_disjoint_timer_query_webgl2`,每个 pass 两个时间戳、几帧环形读回即可。有了它,后面每一项的取舍是一次读数,不是一次构建。这是下面所有项里投入最小、回报最直接的一项。引擎里 `GpuTimer` 和 WebGPU 的时间戳环已经在,缺的是按 pass 分。
+- **0. 逐 pass 的 GPU 计时(已落地,2026-10-26)。** 渲染图的每个 pass 带一个计时:WebGL2 在 pass 前后包一个 `EXT_disjoint_timer_query_webgl2` 查询,WebGPU 把 `timestamp-query` 挂在这个 pass 上(渲染 pass 和计算 pass 都行),结果几帧之后读回(环形,不阻塞 CPU)。只在剖析器打开时跑(每个 pass 一个查询),关着时仍是原来的整图一个计时器。读法:`engine_getGpuScopes()` 里的 `graph` 和 `pass/<名字>`;无头 harness 用 `node tools/terrain-water-cost.mjs --passes`(每个变体后打印逐 pass 表),渲染宿主用 `ESTELLA_VERIFY_GPU_PASSES=print`(两个后端都有)。这一轮拿它重新量了一遍,见 `docs/TERRAIN_WATER_GPU_COST.md` 的“逐 pass 读数”:各 pass 之和与整图计时、墙钟吻合(24.0 / 24.2 / 25.7 ms),所以以后的取舍是一次读数,不再是消融构建。**已知的限度:**一个被设备从中间切成两段的 pass(渲染中途的拷贝)在 WebGPU 上只计到切口;同名的 pass(两台相机、两个阴影视图)按名字相加。
## 按证据排序
@@ -94,7 +94,7 @@
## 建议的顺序
-1. **逐 pass GPU 计时**(第 0 项):投入最小,让后面每一步可以直接读数。
+1. ~~**逐 pass GPU 计时**(第 0 项)~~:已落地。
2. **天空与雾半分辨率加上采样**(第 1 项的第一步),再看要不要做 LUT。
3. **阴影缓存与远处级联隔帧更新**(第 3 项)。
4. **TAA 加时间上采样作为新档位**(第 2 项),要用户拍板。
diff --git a/docs/TERRAIN_WATER_GPU_COST.md b/docs/TERRAIN_WATER_GPU_COST.md
index 40bc0e054..34ecc303f 100644
--- a/docs/TERRAIN_WATER_GPU_COST.md
+++ b/docs/TERRAIN_WATER_GPU_COST.md
@@ -346,3 +346,26 @@
| 阴影 | 3.6 | 9.8 |
**最大的一块已经变成天空大气加高度雾**:默认机位上这两个就占了帧的一半以上(不是互相独立的,去掉一个另一个的成本会变,所以不能相加)。这是下一步最值的方向,见 `docs/GPU_PERFORMANCE_OPTIONS.md`。
+
+## 逐 pass 读数(2026-10-26)
+
+渲染图每个 pass 现在有自己的 GPU 计时(`node tools/terrain-water-cost.mjs --only base --passes --view N`,RTX 3060、1080p、WebGL2)。各 pass 之和与整图计时吻合,与墙钟也吻合,所以这是一张可以相加的表,消融那张不是。
+
+| pass | 机位 0 | 机位 1 | 机位 3 |
+|---|---|---|---|
+| scene(不透明加预通道) | 9.4 | 16.1 | 18.1 |
+| heightFog | 5.0 | 5.0 | 5.0 |
+| skyAtmosphere | 4.1 | 4.3 | 4.0 |
+| scene-glass(水等透明) | 2.8 | 1.4 | 3.0 |
+| shadow-atlas | 0.4 | 4.3 | 4.2 |
+| lensFlare | 0.75 | 0.75 | 0.76 |
+| gtao_ao | 0.26 | 0.44 | 0.44 |
+| scene-grab | 0.3 | 0.3 | 0.3 |
+| 其余(bloom 五级、色彩分级、FXAA、曝光…)每个 | ≤0.1 | ≤0.1 | ≤0.1 |
+| **整图 / 墙钟** | 24.2 / 25.7 | 33.8 / 35.3 | 36.5 / 38.7 |
+
+比消融表多告诉我们的几件事:
+- 天空大气单独是 4 ms,不是消融里的 7.9:消融把“拿掉它之后后面的 pass 少读了什么”也算进去了。高度雾 5.0 ms 在三个机位上一样,是与画面内容无关的固定成本(全屏、每像素一次),是后处理里最先该动的一块。
+- 不透明场景加预通道是帧的 40% 到 50%,随机位涨到 16 到 18 ms;阴影图在机位 1/3 上是 4.2 到 4.3 ms,机位 0 上只有 0.4。
+- 镜头光晕(`lensFlare`)0.75 ms 是固定的,没有人想到过它。
+- 其余全屏 pass(bloom、分级、FXAA、曝光、gtao 的模糊)加起来不到 1.5 ms:合并它们(选项第 7 项)的上限很低。
diff --git a/pipeline/src/runtime/gameHost.ts b/pipeline/src/runtime/gameHost.ts
index 00d3901f4..68e58c2a0 100644
--- a/pipeline/src/runtime/gameHost.ts
+++ b/pipeline/src/runtime/gameHost.ts
@@ -691,6 +691,19 @@ async function boot(): Promise<void> {
return {};
}
},
+ /**
+ * What the GPU spent on the last frames it has an answer for: `graph`, and `pass/<name>` for each render-graph pass.
+ * The device answers a few frames late, so a value is the newest finished frame's, not the one just drawn. Engaging
+ * the profiler is what turns the per-pass timers on.
+ */
+ gpu(): Record<string, number> {
+ module.engine_setCpuProfiling?.(true);
+ try {
+ return JSON.parse(module.engine_getGpuScopes?.() ?? '{}') as Record<string, number>;
+ } catch {
+ return {};
+ }
+ },
/**
* The capability decisions the SHIPPING renderer committed to, asked of
* the frame that drew rather than of the editor's account of what a build
diff --git a/src/esengine/renderer/frame/RenderFrame.cpp b/src/esengine/renderer/frame/RenderFrame.cpp
index 88f0bb96b..8e6115fdb 100644
--- a/src/esengine/renderer/frame/RenderFrame.cpp
+++ b/src/esengine/renderer/frame/RenderFrame.cpp
@@ -830,11 +830,35 @@ void RenderFrame::end() {
{
ES_PROFILE_SCOPE("render.graph");
- gpu_timer_.poll(device_);
- gpu_timer_.begin(device_);
- graph_.execute();
- gpu_timer_.end(device_);
- FrameProfiler::get().gpuScope("graph", gpu_timer_.lastMs());
+ // With the profiler on, each pass is timed and the graph is their sum; otherwise one query spans the graph.
+ rg::PassTimer* passTimer = nullptr;
+ if (FrameProfiler::get().enabled()) {
+ if (!pass_timer_) pass_timer_ = makeUnique<rg::PassTimer>(device_);
+ if (pass_timer_->available()) passTimer = pass_timer_.get();
+ }
+ if (passTimer) {
+ passTimer->beginFrame();
+ graph_.setPassTimer(passTimer);
+ graph_.execute();
+ graph_.setPassTimer(nullptr);
+ passTimer->endFrame();
+ // The scope names are the passes' own, under pass/ so they cannot meet a scope of another kind.
+ for (const auto& e : passTimer->last()) {
+ pass_scope_names_.try_emplace(e.name, std::string("pass/") + e.name);
+ FrameProfiler::get().gpuScope(pass_scope_names_[e.name].c_str(), e.ms);
+ }
+ if (passTimer->lastTotalMs() >= 0.0f) {
+ pass_graph_ms_ = passTimer->lastTotalMs();
+ FrameProfiler::get().gpuScope("graph", pass_graph_ms_);
+ }
+ } else {
+ gpu_timer_.poll(device_);
+ gpu_timer_.begin(device_);
+ graph_.execute();
+ gpu_timer_.end(device_);
+ pass_graph_ms_ = -1.0f;
+ FrameProfiler::get().gpuScope("graph", gpu_timer_.lastMs());
+ }
}
#ifdef ES_ENABLE_GPU_PARTICLES
// After the graph, which is where the kernels run: a frame that dispatched none (its emitters fell back to the CPU, or
@@ -857,7 +881,7 @@ void RenderFrame::end() {
}
// The graph's own time is the whole frame's — the scene pass runs inside it.
- stats_.gpu_time_ms = gpu_timer_.lastMs();
+ stats_.gpu_time_ms = pass_graph_ms_ >= 0.0f ? pass_graph_ms_ : gpu_timer_.lastMs();
// The frame's pass closes HERE, not at the next begin: a WebGPU backend
// submits on endRenderPass, and a surface texture acquired this task must
diff --git a/src/esengine/renderer/frame/RenderFrame.hpp b/src/esengine/renderer/frame/RenderFrame.hpp
index 800b9a029..d94b12f02 100644
--- a/src/esengine/renderer/frame/RenderFrame.hpp
+++ b/src/esengine/renderer/frame/RenderFrame.hpp
@@ -573,6 +573,11 @@ private:
* this one's span ends this query on GL and steals this reading on WebGPU.
*/
GpuTimer gpu_timer_;
+ /// Per-pass GPU times, made the first frame the profiler is on (it costs a query per pass).
+ Unique<rg::PassTimer> pass_timer_;
+ /// The profiler keeps a scope's name by pointer: "pass/<name>" per pass name, made once. Keyed by the timer's interned name.
+ std::unordered_map<const char*, std::string> pass_scope_names_;
+ f32 pass_graph_ms_ = -1.0f;
FrameCapture frame_capture_;
std::vector<u8> snapshot_pixels_;
RenderTargetManager::Handle replay_rt_ = 0;
diff --git a/src/esengine/renderer/graph/RenderGraph.cpp b/src/esengine/renderer/graph/RenderGraph.cpp
index 14261e3e9..b74b0cb53 100644
--- a/src/esengine/renderer/graph/RenderGraph.cpp
+++ b/src/esengine/renderer/graph/RenderGraph.cpp
@@ -21,6 +21,102 @@ RenderGraph::RenderGraph(GfxDevice& device)
RenderGraph::~RenderGraph() = default;
+// =============================================================================
+// PassTimer
+// =============================================================================
+
+bool PassTimer::available() {
+ if (state_ == 0) {
+ // The device says whether it can time by whether it will make a query.
+ const u32 probe = device_.createTimerQuery();
+ state_ = probe != 0 ? 1 : 2;
+ arming_ = device_.timesPassesByArming();
+ if (probe != 0) queries_.push_back(probe); // kept: it is the first slot's query
+ }
+ return state_ == 1;
+}
+
+u32 PassTimer::queryFor(u32 frame, u32 index) {
+ const usize at = static_cast<usize>(frame) * kMaxPasses + index;
+ if (queries_.size() <= at) queries_.resize(at + 1, 0);
+ if (queries_[at] == 0) queries_[at] = device_.createTimerQuery();
+ return queries_[at];
+}
+
+bool PassTimer::poll(Frame& frame) {
+ bool all = true;
+ for (Slot& slot : frame.slots) {
+ if (slot.done) continue;
+ u64 ns = 0;
+ if (device_.getTimerQueryNs(slot.query, &ns)) {
+ slot.done = true;
+ slot.ms = static_cast<f32>(ns) / 1.0e6f;
+ } else {
+ all = false;
+ }
+ }
+ return all;
+}
+
+void PassTimer::beginFrame() {
+ if (state_ != 1) return;
+ if (device_.timerDisjoint()) {
+ // Timing was disturbed: what is in flight is meaningless.
+ for (Frame& f : frames_) f.inflight = false;
+ }
+ for (u32 i = 0; i < kFrames; ++i) {
+ Frame& f = frames_[i];
+ if (!f.inflight || !poll(f)) continue;
+ f.inflight = false;
+ if (frameNo_[i] <= lastNo_) continue; // an older frame finishing after a newer one: skip
+ lastNo_ = frameNo_[i];
+ last_.clear();
+ lastTotal_ = 0.0f;
+ for (const Slot& slot : f.slots) {
+ lastTotal_ += slot.ms;
+ bool merged = false;
+ for (Entry& e : last_) {
+ if (e.name == slot.name) { e.ms += slot.ms; merged = true; break; }
+ }
+ if (!merged) last_.push_back({slot.name, slot.ms});
+ }
+ }
+ cur_ = (cur_ + 1) % kFrames;
+ frames_[cur_].slots.clear();
+ frames_[cur_].inflight = false; // a frame the GPU never answered is dropped, not waited for
+ frameNo_[cur_] = ++counter_;
+}
+
+void PassTimer::endFrame() {
+ if (state_ != 1) return;
+ end();
+ frames_[cur_].inflight = !frames_[cur_].slots.empty();
+}
+
+void PassTimer::begin(const std::string& name) {
+ if (state_ != 1) return;
+ end();
+ Frame& f = frames_[cur_];
+ if (f.slots.size() >= kMaxPasses) return;
+ const u32 query = queryFor(cur_, static_cast<u32>(f.slots.size()));
+ if (query == 0) return;
+ Slot slot;
+ slot.name = names_.insert(name).first->c_str();
+ slot.query = query;
+ f.slots.push_back(slot);
+ if (arming_) device_.armPassTimer(query);
+ else device_.beginTimerQuery(query);
+ open_ = true;
+}
+
+void PassTimer::end() {
+ if (!open_) return;
+ open_ = false;
+ if (arming_) device_.armPassTimer(0);
+ else device_.endTimerQuery();
+}
+
+
void RenderGraph::begin(u32 refWidth, u32 refHeight) {
// Kept, not freed: the vectors' capacity is the whole point of reusing one
// graph across frames.
@@ -196,6 +292,7 @@ void RenderGraph::execute() {
fbo = target.target;
}
+ if (timer_) timer_->begin(pass.name);
if (pass.compute) {
// A dispatch is not a draw: it runs between render passes, with nothing bound for it by the graph.
// The pass before it is still open on a device that leaves one open until the next begins; a dispatch needs it closed.
@@ -211,6 +308,7 @@ void RenderGraph::execute() {
pass.execute(ctx);
}
++executed_;
+ if (timer_) timer_->end();
for (auto& res : resources_) {
if (res.kind == Kind::Transient && res.lastRead == static_cast<i32>(i)) release(res);
}
@@ -247,6 +345,7 @@ void RenderGraph::execute() {
pass.execute(ctx);
}
++executed_;
+ if (timer_) timer_->end();
// Recycled after the pass that last read it, which is what lets a linear
// chain run on two physical targets without anyone arranging it.
diff --git a/src/esengine/renderer/graph/RenderGraph.hpp b/src/esengine/renderer/graph/RenderGraph.hpp
index f53df23b6..5fad3f9eb 100644
--- a/src/esengine/renderer/graph/RenderGraph.hpp
+++ b/src/esengine/renderer/graph/RenderGraph.hpp
@@ -29,6 +29,7 @@
#include <functional>
#include <memory>
#include <string>
+#include <unordered_set>
#include <vector>
namespace esengine {
@@ -142,6 +143,70 @@ struct PassDesc {
* the graph could hold nothing across two of them. Given one, every
* chain draws from the same targets, and so can a frame-lived resource.
*/
+/**
+ * @brief What each pass of a graph cost the GPU, read a few frames late.
+ *
+ * @details One timer query per pass per frame, in a ring so a result is fetched after the GPU has had time to finish
+ * it and the CPU never waits. A bracketing backend (GL) gets a begin/end around the pass; an arming one
+ * (WebGPU) gets the next pass named. Same-named passes of a frame (two cameras, two shadow views) are summed.
+ * Costs a query per pass, so it runs only while the profiler is on.
+ */
+class PassTimer {
+public:
+ struct Entry {
+ const char* name; ///< Interned: valid as long as the timer.
+ f32 ms;
+ };
+
+ explicit PassTimer(GfxDevice& device) : device_(device) {}
+
+ /** Whether the device can time GPU work at all; probes on first call. */
+ bool available();
+
+ /** Starts a frame: fetches what the ring has finished and claims this frame's slot. */
+ void beginFrame();
+ void endFrame();
+
+ /** Around one pass; arms or brackets by what the device does. */
+ void begin(const std::string& name);
+ void end();
+
+ /** The newest frame whose every pass was read back. Empty until one has been. */
+ const std::vector<Entry>& last() const { return last_; }
+ f32 lastTotalMs() const { return lastTotal_; }
+
+private:
+ static constexpr u32 kFrames = 4;
+ struct Slot {
+ const char* name = nullptr;
+ u32 query = 0;
+ bool done = false;
+ f32 ms = 0.0f;
+ };
+ struct Frame {
+ std::vector<Slot> slots;
+ bool inflight = false;
+ };
+
+ static constexpr u32 kMaxPasses = 128;
+ u32 queryFor(u32 frame, u32 index);
+ bool poll(Frame& frame);
+
+ GfxDevice& device_;
+ int state_ = 0; // 0 = unprobed, 1 = available, 2 = no timer
+ bool arming_ = false;
+ bool open_ = false;
+ Frame frames_[kFrames];
+ std::vector<u32> queries_;
+ std::unordered_set<std::string> names_;
+ u32 cur_ = 0;
+ u32 counter_ = 0;
+ u32 frameNo_[kFrames] = {0, 0, 0, 0};
+ u32 lastNo_ = 0;
+ std::vector<Entry> last_;
+ f32 lastTotal_ = -1.0f;
+};
+
class RenderGraph {
public:
/** Borrows the caller's pool: a frame's chains share one. */
@@ -194,6 +259,9 @@ public:
/** Culls, assigns physical targets, and runs what survives. */
void execute();
+ /** Times each pass of the next execute()s into @p timer; null stops. Borrowed. */
+ void setPassTimer(PassTimer* timer) { timer_ = timer; }
+
/** The texture behind a resource — valid for imports, and for a transient
* only while it holds a physical target. */
TextureHandle textureOf(ResourceId id) const;
@@ -260,6 +328,7 @@ private:
u32 refWidth_ = 0;
u32 refHeight_ = 0;
u32 executed_ = 0;
+ PassTimer* timer_ = nullptr;
};
} // namespace rg
diff --git a/src/esengine/renderer/rhi/GfxDevice.hpp b/src/esengine/renderer/rhi/GfxDevice.hpp
index cb96ff799..bb4302430 100644
--- a/src/esengine/renderer/rhi/GfxDevice.hpp
+++ b/src/esengine/renderer/rhi/GfxDevice.hpp
@@ -766,6 +766,20 @@ public:
/** @brief Fetches a completed query's elapsed nanoseconds; false while still pending. */
virtual bool getTimerQueryNs(u32 query, u64* outNanoseconds) = 0;
+ /**
+ * @brief True when a pass is timed by arming it, not by bracketing it with begin/endTimerQuery.
+ * @details A GL query spans whatever is issued between its two calls; a WebGPU timestamp is written by the pass that
+ * carries it, so the pass has to be named before it opens. A per-pass timer picks its calls by this.
+ */
+ virtual bool timesPassesByArming() const { return false; }
+
+ /**
+ * @brief Times the next render or compute pass into @p query (0 disarms), read back with getTimerQueryNs.
+ * @details Only where timesPassesByArming(). A pass that is split in two by the device (a mid-pass copy) is timed up
+ * to the split.
+ */
+ virtual void armPassTimer(u32 query) { (void)query; }
+
// =========================================================================
// Debug
// =========================================================================
diff --git a/src/esengine/renderer/webgpu/WebGPUDevice.cpp b/src/esengine/renderer/webgpu/WebGPUDevice.cpp
index f1a20db12..054d31fe4 100644
--- a/src/esengine/renderer/webgpu/WebGPUDevice.cpp
+++ b/src/esengine/renderer/webgpu/WebGPUDevice.cpp
@@ -234,6 +234,11 @@ void WebGPUDevice::releaseDeviceObjects() {
if (timestamp_resolve_) { wgpuBufferRelease(timestamp_resolve_); timestamp_resolve_ = nullptr; }
for (auto& s : gpu_time_ring_) { if (s.buf) wgpuBufferRelease(s.buf); s.buf = nullptr; s.pending = false; }
gpu_time_results_.clear();
+ for (auto& ps : pass_time_pool_) { if (ps.buf) wgpuBufferRelease(ps.buf); }
+ pass_time_pool_.clear();
+ pass_time_results_.clear();
+ pass_time_slot_ = kNoPassSlot;
+ armed_pass_tag_ = 0;
timestamp_supported_ = false;
timestamp_init_done_ = false;
if (clear_bind_group_) { wgpuBindGroupRelease(clear_bind_group_); clear_bind_group_ = nullptr; }
@@ -2329,7 +2334,9 @@ void WebGPUDevice::beginRenderPass(const RenderPassDesc& desc) {
// in the common case. Reserve a free ring slot; skip timing if none is free.
pass_timed_ = false;
gpu_time_slot_ = kGpuTimeRing;
- if (timestamp_supported_ && desc.target == FramebufferHandle::Default) {
+ // A pass the graph armed is timed whatever it draws to; it takes the timestamp slot the surface pass would have used.
+ pass_time_slot_ = takePassTimeSlot();
+ if (timestamp_supported_ && pass_time_slot_ == kNoPassSlot && desc.target == FramebufferHandle::Default) {
for (u32 i = 0; i < kGpuTimeRing; ++i) {
const u32 s = (gpu_time_next_ + i) % kGpuTimeRing;
if (!gpu_time_ring_[s].pending) {
@@ -2380,7 +2387,7 @@ void WebGPUDevice::beginRenderPass(const RenderPassDesc& desc) {
rp.depthStencilAttachment = &ds;
}
WGPUPassTimestampWrites tw{};
- if (pass_timed_) {
+ if (pass_timed_ || pass_time_slot_ != kNoPassSlot) {
tw.querySet = timestamp_qset_;
tw.beginningOfPassWriteIndex = 0;
tw.endOfPassWriteIndex = 1;
@@ -2415,6 +2422,9 @@ void WebGPUDevice::endRenderPass() {
// GPU timing: resolve this pass's begin/end timestamps into the reserved ring
// slot (recorded on the same encoder, so it runs after the pass on the GPU).
+ const u32 passSlot = encoder_ ? pass_time_slot_ : kNoPassSlot;
+ pass_time_slot_ = kNoPassSlot;
+ if (passSlot != kNoPassSlot) resolvePassTime(encoder_, passSlot);
const bool timed = pass_timed_ && gpu_time_slot_ < kGpuTimeRing && encoder_;
if (timed) {
wgpuCommandEncoderResolveQuerySet(encoder_, timestamp_qset_, 0, 2, timestamp_resolve_, 0);
@@ -2437,6 +2447,7 @@ void WebGPUDevice::endRenderPass() {
wgpuQueueSubmit(queue_, 1, &commands);
wgpuCommandBufferRelease(commands);
+ if (passSlot != kNoPassSlot) mapPassTime(passSlot);
if (timed) {
// Map async — drained by getTimerQueryNs a few frames later (the GpuTimer
// ring tolerates the latency).
@@ -2693,13 +2704,77 @@ void WebGPUDevice::beginTimerQuery(u32) {} // timing rides the pass: attached a
void WebGPUDevice::endTimerQuery() {}
bool WebGPUDevice::timerDisjoint() { return false; }
-bool WebGPUDevice::getTimerQueryNs(u32, u64* outNs) {
+bool WebGPUDevice::getTimerQueryNs(u32 query, u64* outNs) {
+ if (pass_time_tags_.count(query)) {
+ const auto it = pass_time_results_.find(query);
+ if (it == pass_time_results_.end()) return false;
+ if (outNs) *outNs = it->second;
+ pass_time_results_.erase(it);
+ return true;
+ }
if (gpu_time_results_.empty()) return false;
if (outNs) *outNs = gpu_time_results_.front();
gpu_time_results_.erase(gpu_time_results_.begin());
return true;
}
+void WebGPUDevice::armPassTimer(u32 query) {
+ armed_pass_tag_ = timestamp_supported_ ? query : 0;
+ if (armed_pass_tag_) pass_time_tags_.insert(armed_pass_tag_);
+}
+
+u32 WebGPUDevice::takePassTimeSlot() {
+ const u32 tag = armed_pass_tag_;
+ armed_pass_tag_ = 0;
+ if (!tag || !timestamp_supported_) return kNoPassSlot;
+ u32 slot = kNoPassSlot;
+ for (u32 i = 0; i < pass_time_pool_.size(); ++i) {
+ if (!pass_time_pool_[i].pending) { slot = i; break; }
+ }
+ if (slot == kNoPassSlot) {
+ if (pass_time_pool_.size() >= kPassTimePool) return kNoPassSlot; // readbacks are not coming back: skip, don't grow
+ WGPUBufferDescriptor bd{};
+ bd.usage = WGPUBufferUsage_MapRead | WGPUBufferUsage_CopyDst;
+ bd.size = 16;
+ PassTimeSlot fresh;
+ fresh.buf = wgpuDeviceCreateBuffer(device_, &bd);
+ if (!fresh.buf) return kNoPassSlot;
+ pass_time_pool_.push_back(fresh);
+ slot = static_cast<u32>(pass_time_pool_.size() - 1);
+ }
+ pass_time_pool_[slot].tag = tag;
+ return slot;
+}
+
+void WebGPUDevice::resolvePassTime(WGPUCommandEncoder encoder, u32 slot) {
+ wgpuCommandEncoderResolveQuerySet(encoder, timestamp_qset_, 0, 2, timestamp_resolve_, 0);
+ wgpuCommandEncoderCopyBufferToBuffer(encoder, timestamp_resolve_, 0, pass_time_pool_[slot].buf, 0, 16);
+}
+
+void WebGPUDevice::mapPassTime(u32 slot) {
+ pass_time_pool_[slot].pending = true;
+ WGPUBufferMapCallbackInfo cb = WGPU_BUFFER_MAP_CALLBACK_INFO_INIT;
+ cb.mode = WGPUCallbackMode_AllowSpontaneous;
+ cb.callback = &WebGPUDevice::onPassTimeMapped;
+ cb.userdata1 = this;
+ cb.userdata2 = reinterpret_cast<void*>(static_cast<uintptr_t>(slot));
+ wgpuBufferMapAsync(pass_time_pool_[slot].buf, WGPUMapMode_Read, 0, 16, cb);
+}
+
+void WebGPUDevice::onPassTimeMapped(WGPUMapAsyncStatus status, WGPUStringView /*message*/,
+ void* userdata1, void* userdata2) {
+ auto* self = static_cast<WebGPUDevice*>(userdata1);
+ const u32 slot = static_cast<u32>(reinterpret_cast<uintptr_t>(userdata2));
+ if (!self || slot >= self->pass_time_pool_.size()) return;
+ PassTimeSlot& ps = self->pass_time_pool_[slot];
+ if (status == WGPUMapAsyncStatus_Success && ps.buf) {
+ const auto* ts = static_cast<const u64*>(wgpuBufferGetConstMappedRange(ps.buf, 0, 16));
+ if (ts && ts[1] >= ts[0]) self->pass_time_results_[ps.tag] = ts[1] - ts[0];
+ wgpuBufferUnmap(ps.buf);
+ }
+ ps.pending = false;
+}
+
void WebGPUDevice::onGpuTimeMapped(WGPUMapAsyncStatus status, WGPUStringView /*message*/,
void* userdata1, void* userdata2) {
auto* self = static_cast<WebGPUDevice*>(userdata1);
@@ -2947,16 +3022,26 @@ bool WebGPUDevice::backendDispatchCompute(u32 id, const GfxComputeBinding* bindi
WGPUCommandEncoder encoder = wgpuDeviceCreateCommandEncoder(device_, nullptr);
WGPUComputePassDescriptor pd = WGPU_COMPUTE_PASS_DESCRIPTOR_INIT;
+ const u32 passSlot = takePassTimeSlot();
+ WGPUPassTimestampWrites tw{};
+ if (passSlot != kNoPassSlot) {
+ tw.querySet = timestamp_qset_;
+ tw.beginningOfPassWriteIndex = 0;
+ tw.endOfPassWriteIndex = 1;
+ pd.timestampWrites = &tw;
+ }
WGPUComputePassEncoder pass = wgpuCommandEncoderBeginComputePass(encoder, &pd);
wgpuComputePassEncoderSetPipeline(pass, pipeline);
wgpuComputePassEncoderSetBindGroup(pass, 0, group, 0, nullptr);
wgpuComputePassEncoderDispatchWorkgroups(pass, groupsX, groupsY, groupsZ);
wgpuComputePassEncoderEnd(pass);
wgpuComputePassEncoderRelease(pass);
+ if (passSlot != kNoPassSlot) resolvePassTime(encoder, passSlot);
WGPUCommandBuffer commands = wgpuCommandEncoderFinish(encoder, nullptr);
wgpuCommandEncoderRelease(encoder);
wgpuQueueSubmit(queue_, 1, &commands);
wgpuCommandBufferRelease(commands);
+ if (passSlot != kNoPassSlot) mapPassTime(passSlot);
wgpuBindGroupRelease(group);
return true;
}
diff --git a/src/esengine/renderer/webgpu/WebGPUDevice.hpp b/src/esengine/renderer/webgpu/WebGPUDevice.hpp
index 260002b4f..47eb11590 100644
--- a/src/esengine/renderer/webgpu/WebGPUDevice.hpp
+++ b/src/esengine/renderer/webgpu/WebGPUDevice.hpp
@@ -39,6 +39,7 @@
#include <map>
#include <string>
#include <unordered_map>
+#include <unordered_set>
#include <vector>
namespace esengine {
@@ -667,6 +668,24 @@ private:
bool pass_timed_ = false; ///< Did the current pass attach timestampWrites?
std::vector<u64> gpu_time_results_; ///< Resolved elapsed-ns, FIFO, drained by getTimerQueryNs.
void ensureTimestamps(); ///< Lazily create the query set + buffers (feature-gated).
+
+ // Per-pass timing: armPassTimer names the next pass, which carries the timestamps and has them resolved into a
+ // pooled readback buffer; the result is filed under the name (a timer query id) it was armed with.
+ bool timesPassesByArming() const override { return true; }
+ void armPassTimer(u32 query) override;
+ static constexpr u32 kNoPassSlot = ~0u;
+ static constexpr u32 kPassTimePool = 256;
+ struct PassTimeSlot { WGPUBuffer buf = nullptr; bool pending = false; u32 tag = 0; };
+ std::vector<PassTimeSlot> pass_time_pool_;
+ std::unordered_map<u32, u64> pass_time_results_; ///< Elapsed ns by tag, taken by getTimerQueryNs.
+ std::unordered_set<u32> pass_time_tags_; ///< Every id ever armed: those are answered from the map, not the FIFO.
+ u32 armed_pass_tag_ = 0;
+ u32 pass_time_slot_ = kNoPassSlot; ///< Pool slot of the open render pass, if it is timed.
+ /// Claims a pool slot for the armed tag and clears the arm; kNoPassSlot when nothing is armed or the pool is full.
+ u32 takePassTimeSlot();
+ void resolvePassTime(WGPUCommandEncoder encoder, u32 slot);
+ void mapPassTime(u32 slot);
+ static void onPassTimeMapped(WGPUMapAsyncStatus status, WGPUStringView message, void* userdata1, void* userdata2);
static void onGpuTimeMapped(WGPUMapAsyncStatus status, WGPUStringView message,
void* userdata1, void* userdata2);
diff --git a/tools/render-host/host.ts b/tools/render-host/host.ts
index 2295e9006..f41c1d84f 100644
--- a/tools/render-host/host.ts
+++ b/tools/render-host/host.ts
@@ -538,6 +538,16 @@ const api = {
}
},
+ /** What the GPU spent on the newest frame the device has answered for: `graph` and `pass/<name>`. The answer comes
+ * a few frames late and, on a browser, between tasks — a caller steps, waits, and asks again. */
+ getGpuScopes(): Record<string, number> {
+ try {
+ return JSON.parse(module?.engine_getGpuScopes?.() ?? '{}') as Record<string, number>;
+ } catch {
+ return {};
+ }
+ },
+
/** Records whole frames — TS system ms beside the engine's own C++ scope ms,
* which is the only pairing that says what SHARE of a frame is script.
* ProfileRecorder.start() engages both sides; engaging one reads as an
diff --git a/tools/render-host/run.mjs b/tools/render-host/run.mjs
index cbaf3b886..75984d1e9 100644
--- a/tools/render-host/run.mjs
+++ b/tools/render-host/run.mjs
@@ -35,6 +35,7 @@
* ESTELLA_VERIFY_SKIN_WEIGHTS colour a skinned entity by joint weights (JSON {id, joints}; see the block)
* ESTELLA_VERIFY_COUNTERS engine counters the drawn frame must report (JSON)
* ESTELLA_VERIFY_COUNTERS_MAX counters the frame must stay UNDER — a budget (JSON)
+ * ESTELLA_VERIFY_GPU_PASSES print|require — the GPU time of each render-graph pass on this backend (local; needs a timer)
* ESTELLA_VERIFY_FRAME_DEBUG capture the frame and replay it (the frame debugger)
* ESTELLA_VERIFY_UNIFORM the frame is one colour on purpose; ESTELLA_VERIFY_COUNT says which
* ESTELLA_VERIFY_EDGE how straight a straight edge is drawn (JSON: box, lit, dark, maxJag)
@@ -237,7 +238,7 @@ function finish(result, server) {
(result.seam?.ok ?? true) && (result.nineSlice?.ok ?? true) &&
(result.resize?.ok ?? true) && (result.preview?.ok ?? true) &&
(result.meshPreview?.ok ?? true) && (result.grid?.ok ?? true) && (result.studio?.ok ?? true) && (result.shading?.ok ?? true) && (result.skinWeights?.ok ?? true) &&
- (result.draws?.ok ?? true) && (result.counters?.ok ?? true) && (result.frameDebug?.ok ?? true) && (result.edge?.ok ?? true) && (result.cutoutEdge?.ok ?? true) && (result.minified?.ok ?? true) &&
+ (result.draws?.ok ?? true) && (result.counters?.ok ?? true) && (result.gpuPasses?.ok ?? true) && (result.frameDebug?.ok ?? true) && (result.edge?.ok ?? true) && (result.cutoutEdge?.ok ?? true) && (result.minified?.ok ?? true) &&
(result.roundtrip?.ok ?? true) && deviceLossOk && meshOk && pickOk;
const why = assetsOk ? '' : `: could not load ${result.missingAssets.join(', ')}`;
console.log(`\n[verify:render] ${ok ? 'PASS' : 'FAIL'} — ${SCENE} (${BACKEND})${why}`);
@@ -733,6 +734,24 @@ app.whenReady().then(async () => {
];
counters = { points, ok: points.every((p) => p.ok) };
}
+ // ESTELLA_VERIFY_GPU_PASSES=print|require: per-pass GPU time on this backend. The device answers a few frames
+ // late and between tasks, so frames are stepped with a pause until the render graph's passes report. `require`
+ // fails a backend that can time and reported nothing; it is local-only, a CI adapter may not offer a timer.
+ let gpuPasses = null;
+ if (process.env.ESTELLA_VERIFY_GPU_PASSES) {
+ await exec('window.__estellaHeadless.api.setCpuProfiling(true)');
+ let scopes = {};
+ for (let i = 0; i < 40; i++) {
+ await exec('window.__estellaHeadless.api.step(1, 1 / 60)');
+ await new Promise((r) => setTimeout(r, 40));
+ scopes = await exec('window.__estellaHeadless.api.getGpuScopes()');
+ if (Object.keys(scopes).some((k) => k.startsWith('pass/'))) break;
+ }
+ const rows = Object.entries(scopes).filter(([k]) => k.startsWith('pass/')).sort((a, b) => b[1] - a[1]);
+ console.log(`gpu passes (${BACKEND}): graph ${(scopes.graph ?? -1).toFixed(3)} ms, ${rows.length} passes`);
+ for (const [k, v] of rows) console.log(` ${k.slice(5).padEnd(30)} ${v.toFixed(3)} ms`);
+ gpuPasses = { count: rows.length, ok: process.env.ESTELLA_VERIFY_GPU_PASSES !== 'require' || rows.length > 0 };
+ }
// The frame debugger on this backend: its reasons are the merge's own counters
// for the frame, and a replay through the last draw of a pass shows more than
// one through the first.
@@ -1223,7 +1242,7 @@ app.whenReady().then(async () => {
skinWeights = { H0, H1, dA, dJoints, back,
ok: H0.hot > 20 && H1.hot > 20 && dA.differing > 300 && dJoints.differing > 300 && back.max === 0 };
}
- finish({ ok: true, studio, shading, skinWeights, entityCount, missingAssets, drawCalls, draws, counters, frameDebug, edge, cutoutEdge, minified, profile, capture, expect, twins, nineSlice, count, seam, resize, preview, meshPreview, grid, deviceLoss, roundtrip, meshResident, meshAsset, meshMaterial, meshPrefab, setField, animator, pick, cameraTarget }, server);
+ finish({ ok: true, studio, shading, skinWeights, entityCount, missingAssets, drawCalls, draws, counters, gpuPasses, frameDebug, edge, cutoutEdge, minified, profile, capture, expect, twins, nineSlice, count, seam, resize, preview, meshPreview, grid, deviceLoss, roundtrip, meshResident, meshAsset, meshMaterial, meshPrefab, setField, animator, pick, cameraTarget }, server);
} catch (e) {
finish({ ok: false, error: String((e && e.stack) || e) }, server);
}
diff --git a/tools/terrain-water-cost.mjs b/tools/terrain-water-cost.mjs
index 2d13a9bc4..55c267bf5 100644
--- a/tools/terrain-water-cost.mjs
+++ b/tools/terrain-water-cost.mjs
@@ -40,6 +40,8 @@ const VIEW = Number(flag('view', '0'));
const ONLY = flag('only', '') ? new Set(flag('only', '').split(',')) : null;
const OUT = flag('out', path.join(ROOT, 'output', 'perf', 'terrain-water-cost.json'));
const NO_EXPORT = argv.includes('--no-export');
+const PASSES = argv.includes('--passes');
+const PASSES_TOP = Number(flag('passes-top', '24'));
/** A folder to write each variant's last frame to, as `<id>-view<n>.png`. */
const SHOTS = flag('shots', '');
@@ -175,7 +177,7 @@ async function measure(server, original, variant, browser) {
}
return -1;
});
- const result = await page.evaluate(async ({ frames, samples }) => {
+ const result = await page.evaluate(async ({ frames, samples, passSamples }) => {
const c = window.__estellaCooked;
const px = new Uint8Array(4);
const gl = document.querySelector('canvas').getContext('webgl2') ?? null;
@@ -183,23 +185,43 @@ async function measure(server, original, variant, browser) {
c.render(); c.costs(); // engages the profilers: the counters and the CPU split are read after the samples
await c.step(frames, 1 / 60); sync();
const ms = [];
+ const gpuRuns = [];
for (let s = 0; s < samples; s++) {
const t0 = performance.now();
await c.step(frames, 1 / 60);
sync();
ms.push((performance.now() - t0) / frames);
}
+ // After the wall-clock samples, so the pauses do not touch them: the browser delivers a timer query's answer
+ // between tasks, not inside the burst that asked.
+ for (let s = 0; s < passSamples; s++) {
+ await c.step(frames, 1 / 60);
+ sync();
+ await new Promise((r) => setTimeout(r, 40));
+ gpuRuns.push(c.gpu?.() ?? {});
+ }
const costs = c.costs();
const cpu = costs.systems.reduce((a, x) => a + x.ms, 0);
- return { ms, counters: c.render(), cpu, native: costs.native, size: [document.querySelector('canvas').width, document.querySelector('canvas').height], gl: !!gl };
- }, { frames: FRAMES, samples: SAMPLES });
+ return { ms, gpuRuns, counters: c.render(), cpu, native: costs.native, size: [document.querySelector('canvas').width, document.querySelector('canvas').height], gl: !!gl };
+ }, { frames: FRAMES, samples: SAMPLES, passSamples: PASSES ? SAMPLES : 0 });
if (SHOTS) { await mkdir(SHOTS, { recursive: true }); await page.screenshot({ path: path.join(SHOTS, `${variant.id}-view${VIEW}.png`) }); }
- return { ms: median(result.ms), cpu: result.cpu, native: result.native, min: Math.min(...result.ms), max: Math.max(...result.ms), settled, counters: result.counters, size: result.size, errors };
+ return { ms: median(result.ms), gpu: gpuMedians(result.gpuRuns), cpu: result.cpu, native: result.native, min: Math.min(...result.ms), max: Math.max(...result.ms), settled, counters: result.counters, size: result.size, errors };
} finally {
await context.close();
}
}
+// The device answers a few frames late and one frame at a time: the median over the samples is the number to read.
+function gpuMedians(runs) {
+ const keys = new Set(runs.flatMap((r) => Object.keys(r)));
+ const out = {};
+ for (const k of keys) {
+ const v = runs.map((r) => r[k]).filter((x) => typeof x === 'number' && x >= 0);
+ if (v.length) out[k] = median(v);
+ }
+ return out;
+}
+
if (!NO_EXPORT) {
const r = spawnSync(process.execPath, [path.join(ROOT, 'pipeline/bin/estella.mjs'), 'export', path.join(ROOT, 'examples/terrain-water'), '--out', DIR, '--platform', 'web'], { stdio: 'inherit' });
if (r.status !== 0) { console.error('terrain-water-cost: the export failed'); process.exit(1); }
@@ -238,6 +260,12 @@ try {
if (!r) { table[v.id] = { label: v.label, failed: true }; continue; }
table[v.id] = { label: v.label, ...r };
if (argv.includes('--probe')) console.log(' ' + Object.entries(r.counters).filter(([k]) => k.startsWith('probe.')).map(([k, x]) => `${k.replace('probe.', '')}=${x}`).join(' '));
+ if (PASSES) {
+ const rows = Object.entries(r.gpu).filter(([k]) => k.startsWith('pass/')).sort((a, b) => b[1] - a[1]);
+ const sum = rows.reduce((t, [, x]) => t + x, 0);
+ console.log(` gpu per pass (${v.id}): graph ${(r.gpu.graph ?? -1).toFixed(2)} ms, passes sum ${sum.toFixed(2)} ms, ${rows.length} passes`);
+ for (const [k, x] of rows.slice(0, PASSES_TOP)) console.log(` ${k.slice(5).padEnd(34)} ${x.toFixed(2).padStart(7)} ms ${(100 * x / Math.max(sum, 1e-9)).toFixed(1).padStart(5)}%`);
+ }
console.log(`${v.id.padEnd(17)} ${r.ms.toFixed(2).padStart(7)} ms [${r.min.toFixed(2)}..${r.max.toFixed(2)}] cpu ${r.cpu.toFixed(2)} draws ${r.counters['batch.draws'] ?? '?'} shadow ${r.counters['render.shadow.draws'] ?? '?'} tris ${((r.counters['render.triangles'] ?? 0) / 1e6).toFixed(2)}M prepass ${r.counters['render.prepass.draws'] ?? '?'} (meshes taken ${r.counters['render.prepass.taken'] ?? '?'}, cut-out ${r.counters['render.prepass.cutout'] ?? '?'}, bent ${r.counters['render.prepass.bent'] ?? '?'}, none ${r.counters['render.prepass.noProgram'] ?? '?'}) ${r.errors.length ? 'ERRORS ' + r.errors[0] : ''}`);
}
} finally {