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.
TypeScript 2d-game-engine3d3d-game-engineandroidcppecsgame-editorgame-enginegamedeviostypescriptwebassemblywebglwebgpuwechat-minigame
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.mdindex 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.mdindex 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.tsindex 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 builddiff --git a/src/esengine/renderer/frame/RenderFrame.cpp b/src/esengine/renderer/frame/RenderFrame.cppindex 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 mustdiff --git a/src/esengine/renderer/frame/RenderFrame.hpp b/src/esengine/renderer/frame/RenderFrame.hppindex 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.cppindex 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.hppindex 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 rgdiff --git a/src/esengine/renderer/rhi/GfxDevice.hpp b/src/esengine/renderer/rhi/GfxDevice.hppindex 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.cppindex 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 avoid 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* bindiWGPUCommandEncoder 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.hppindex 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.tsindex 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 andiff --git a/tools/render-host/run.mjs b/tools/render-host/run.mjsindex 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.mjsindex 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 samplesawait 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 {