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
fix(quality): dynamic resolution lowers the scale when the frame is late and its own run was not - a GPU timer that reads half a millisecond no longer counts as headroom, and on WebGPU that timer now covers the whole frame instead of the surface pass
yhhc47064e094ea
diff --git a/docs/GPU_PERFORMANCE_OPTIONS.md b/docs/GPU_PERFORMANCE_OPTIONS.mdindex 5256f3188..8648ad4e8 100644--- a/docs/GPU_PERFORMANCE_OPTIONS.md+++ b/docs/GPU_PERFORMANCE_OPTIONS.md@@ -6,7 +6,7 @@引擎只有**整个渲染图一个** GPU 计时器(`render.graph`),场景的网格绘制还在图外。所以这一轮每个数都是“拿掉一样东西,看整帧差多少”(消融),有的还要为了量一个着色器阶段重新编一个引擎。这能用,但慢,而且各部分不能相加。-- **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(两台相机、两个阴影视图)按名字相加。+- **0. 逐 pass 的 GPU 计时(已落地,2026-10-26)。** 渲染图的每个 pass 带一个计时:WebGL2 在 pass 前后包一个 `EXT_disjoint_timer_query_webgl2` 查询,WebGPU 把 `timestamp-query` 挂在这个 pass 上(渲染 pass 和计算 pass 都行),结果几帧之后读回(环形,不阻塞 CPU)。只在剖析器打开时跑(每个 pass 一个查询),关着时仍是原来的整图一个计时器。整图计时器在两个后端是同一个量:WebGL2 是包住整张图的一个查询,WebGPU 是计时区间内每个渲染/计算 pass 的时间之和(2026-11-11 之前 WebGPU 关着剖析器时只计上屏那一个 pass,读数远小于整帧,动态分辨率据此误判有余量,见 #120);`ESTELLA_VERIFY_GPU_FRAME=print|require` 把它和逐 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(两台相机、两个阴影视图)按名字相加。## 按证据排序diff --git a/sdk/etc/index.api.md b/sdk/etc/index.api.mdindex e9b3b8d25..16ee77208 100644--- a/sdk/etc/index.api.md+++ b/sdk/etc/index.api.md@@ -1,7 +1,7 @@# API surface — esengine/index<!-- Generated by tools/api-surface.mjs — do not edit. Run --update to accept changes. -->-Symbols: 115 public · 166 beta · 2163 experimental · 3 deprecated+Symbols: 115 public · 166 beta · 2167 experimental · 3 deprecated## ABI_LAYOUT_HASH — const @experimental```@@ -781,7 +781,7 @@ getEntityCount: () => numbergetFixedTimestep: () => numbergetFrameCosts: () => FrameCosts | nullgetFrameScopes: () => ReadonlyMap<string, number> | null-getFrameTiming: () => Readonly<{ seq: number; frameMs: number; }> | null+getFrameTiming: () => Readonly<FrameTiming> | nullgetPhaseTimings: () => ReadonlyMap<string, number> | nullgetPlaySpeed: () => numbergetPlugin: <T extends Plugin>(ctor: new (...args: any[]) => T) => T | undefined@@ -4834,6 +4834,18 @@ vramBytes: numberwasmBytes: number```+## FrameTiming — interface @experimental+```+busyMs: number+frameMs: number+seq: number+```++## FrameVerdict — type @experimental+```+'gpu-pressure' | 'frame-pressure' | 'headroom' | 'steady'+```+## GLDebug — const @experimental```{ enable(): void; disable(): void; check(context: string): number; diagnose(): void; }@@ -8552,7 +8564,7 @@ enabled: booleanprofile: Readonly<QualityProfile>renderScale: numberreport: () => QualityReport-sample: (frameMs: number, gpuMs?: number) => void+sample: (sample: Readonly<QualitySample>) => voidsetCeiling: (level: QualityLevel | null) => voidsetLimitation: (reason: string, active: boolean) => voidsetMode: (mode: QualityMode) => void@@ -8604,8 +8616,10 @@ waterWaves: number## QualityReport — interface @experimental```+busyMs: numberdrawCallBudget: numberframeMs: number+gpuMs: numberlevel: QualityLevellimitations: string[]mode: QualityMode@@ -8614,6 +8628,13 @@ renderScale: numbertargetFps: number```+## QualitySample — interface @experimental+```+busyMs: number | undefined+frameMs: number+gpuMs: number | undefined+```+## Quat — interface @public```w: number@@ -16395,6 +16416,11 @@ InputRouter(d: SwingTwistJoint3DData | SixDOFJoint3DData): string | null```+## judgeFrames — function @experimental+```+(avg: Readonly<Required<QualitySample>>, budgetMs: number): FrameVerdict+```+## layerFrontness — function @experimental```(order: LayerOrder, worldY: number, worldZ: number): numberdiff --git a/sdk/etc/index.native.api.md b/sdk/etc/index.native.api.mdindex a06a95186..eb69efdc8 100644--- a/sdk/etc/index.native.api.md+++ b/sdk/etc/index.native.api.md@@ -1,7 +1,7 @@# API surface — esengine/index.native<!-- Generated by tools/api-surface.mjs — do not edit. Run --update to accept changes. -->-Symbols: 115 public · 171 beta · 2183 experimental · 3 deprecated+Symbols: 115 public · 171 beta · 2187 experimental · 3 deprecated## ABI_LAYOUT_HASH — const @experimental```@@ -781,7 +781,7 @@ getEntityCount: () => numbergetFixedTimestep: () => numbergetFrameCosts: () => FrameCosts | nullgetFrameScopes: () => ReadonlyMap<string, number> | null-getFrameTiming: () => Readonly<{ seq: number; frameMs: number; }> | null+getFrameTiming: () => Readonly<FrameTiming> | nullgetPhaseTimings: () => ReadonlyMap<string, number> | nullgetPlaySpeed: () => numbergetPlugin: <T extends Plugin>(ctor: new (...args: any[]) => T) => T | undefined@@ -4842,6 +4842,18 @@ vramBytes: numberwasmBytes: number```+## FrameTiming — interface @experimental+```+busyMs: number+frameMs: number+seq: number+```++## FrameVerdict — type @experimental+```+'gpu-pressure' | 'frame-pressure' | 'headroom' | 'steady'+```+## GLDebug — const @experimental```{ enable(): void; disable(): void; check(context: string): number; diagnose(): void; }@@ -8759,7 +8771,7 @@ enabled: booleanprofile: Readonly<QualityProfile>renderScale: numberreport: () => QualityReport-sample: (frameMs: number, gpuMs?: number) => void+sample: (sample: Readonly<QualitySample>) => voidsetCeiling: (level: QualityLevel | null) => voidsetLimitation: (reason: string, active: boolean) => voidsetMode: (mode: QualityMode) => void@@ -8811,8 +8823,10 @@ waterWaves: number## QualityReport — interface @experimental```+busyMs: numberdrawCallBudget: numberframeMs: number+gpuMs: numberlevel: QualityLevellimitations: string[]mode: QualityMode@@ -8821,6 +8835,13 @@ renderScale: numbertargetFps: number```+## QualitySample — interface @experimental+```+busyMs: number | undefined+frameMs: number+gpuMs: number | undefined+```+## Quat — interface @public```w: number@@ -16667,6 +16688,11 @@ InputRouter(d: SwingTwistJoint3DData | SixDOFJoint3DData): string | null```+## judgeFrames — function @experimental+```+(avg: Readonly<Required<QualitySample>>, budgetMs: number): FrameVerdict+```+## layerFrontness — function @experimental```(order: LayerOrder, worldY: number, worldZ: number): numberdiff --git a/sdk/etc/index.node.api.md b/sdk/etc/index.node.api.mdindex 31074d4d0..41e8c772e 100644--- a/sdk/etc/index.node.api.md+++ b/sdk/etc/index.node.api.md@@ -1,7 +1,7 @@# API surface — esengine/index.node<!-- Generated by tools/api-surface.mjs — do not edit. Run --update to accept changes. -->-Symbols: 115 public · 168 beta · 2162 experimental · 3 deprecated+Symbols: 115 public · 168 beta · 2166 experimental · 3 deprecated## ANCHOR_AXES — const @experimental```@@ -776,7 +776,7 @@ getEntityCount: () => numbergetFixedTimestep: () => numbergetFrameCosts: () => FrameCosts | nullgetFrameScopes: () => ReadonlyMap<string, number> | null-getFrameTiming: () => Readonly<{ seq: number; frameMs: number; }> | null+getFrameTiming: () => Readonly<FrameTiming> | nullgetPhaseTimings: () => ReadonlyMap<string, number> | nullgetPlaySpeed: () => numbergetPlugin: <T extends Plugin>(ctor: new (...args: any[]) => T) => T | undefined@@ -4829,6 +4829,18 @@ vramBytes: numberwasmBytes: number```+## FrameTiming — interface @experimental+```+busyMs: number+frameMs: number+seq: number+```++## FrameVerdict — type @experimental+```+'gpu-pressure' | 'frame-pressure' | 'headroom' | 'steady'+```+## GLDebug — const @experimental```{ enable(): void; disable(): void; check(context: string): number; diagnose(): void; }@@ -8547,7 +8559,7 @@ enabled: booleanprofile: Readonly<QualityProfile>renderScale: numberreport: () => QualityReport-sample: (frameMs: number, gpuMs?: number) => void+sample: (sample: Readonly<QualitySample>) => voidsetCeiling: (level: QualityLevel | null) => voidsetLimitation: (reason: string, active: boolean) => voidsetMode: (mode: QualityMode) => void@@ -8599,8 +8611,10 @@ waterWaves: number## QualityReport — interface @experimental```+busyMs: numberdrawCallBudget: numberframeMs: number+gpuMs: numberlevel: QualityLevellimitations: string[]mode: QualityMode@@ -8609,6 +8623,13 @@ renderScale: numbertargetFps: number```+## QualitySample — interface @experimental+```+busyMs: number | undefined+frameMs: number+gpuMs: number | undefined+```+## Quat — interface @public```w: number@@ -16390,6 +16411,11 @@ InputRouter(d: SwingTwistJoint3DData | SixDOFJoint3DData): string | null```+## judgeFrames — function @experimental+```+(avg: Readonly<Required<QualitySample>>, budgetMs: number): FrameVerdict+```+## layerFrontness — function @experimental```(order: LayerOrder, worldY: number, worldZ: number): numberdiff --git a/sdk/etc/minigame.api.md b/sdk/etc/minigame.api.mdindex 45d49c3cc..606702c60 100644--- a/sdk/etc/minigame.api.md+++ b/sdk/etc/minigame.api.md@@ -1,7 +1,7 @@# API surface — esengine/minigame<!-- Generated by tools/api-surface.mjs — do not edit. Run --update to accept changes. -->-Symbols: 115 public · 166 beta · 2184 experimental · 3 deprecated+Symbols: 115 public · 166 beta · 2188 experimental · 3 deprecated## ANCHOR_AXES — const @experimental```@@ -776,7 +776,7 @@ getEntityCount: () => numbergetFixedTimestep: () => numbergetFrameCosts: () => FrameCosts | nullgetFrameScopes: () => ReadonlyMap<string, number> | null-getFrameTiming: () => Readonly<{ seq: number; frameMs: number; }> | null+getFrameTiming: () => Readonly<FrameTiming> | nullgetPhaseTimings: () => ReadonlyMap<string, number> | nullgetPlaySpeed: () => numbergetPlugin: <T extends Plugin>(ctor: new (...args: any[]) => T) => T | undefined@@ -4829,6 +4829,18 @@ vramBytes: numberwasmBytes: number```+## FrameTiming — interface @experimental+```+busyMs: number+frameMs: number+seq: number+```++## FrameVerdict — type @experimental+```+'gpu-pressure' | 'frame-pressure' | 'headroom' | 'steady'+```+## GLDebug — const @experimental```{ enable(): void; disable(): void; check(context: string): number; diagnose(): void; }@@ -8844,7 +8856,7 @@ enabled: booleanprofile: Readonly<QualityProfile>renderScale: numberreport: () => QualityReport-sample: (frameMs: number, gpuMs?: number) => void+sample: (sample: Readonly<QualitySample>) => voidsetCeiling: (level: QualityLevel | null) => voidsetLimitation: (reason: string, active: boolean) => voidsetMode: (mode: QualityMode) => void@@ -8896,8 +8908,10 @@ waterWaves: number## QualityReport — interface @experimental```+busyMs: numberdrawCallBudget: numberframeMs: number+gpuMs: numberlevel: QualityLevellimitations: string[]mode: QualityMode@@ -8906,6 +8920,13 @@ renderScale: numbertargetFps: number```+## QualitySample — interface @experimental+```+busyMs: number | undefined+frameMs: number+gpuMs: number | undefined+```+## Quat — interface @public```w: number@@ -16708,6 +16729,11 @@ InputRouter(d: SwingTwistJoint3DData | SixDOFJoint3DData): string | null```+## judgeFrames — function @experimental+```+(avg: Readonly<Required<QualitySample>>, budgetMs: number): FrameVerdict+```+## layerFrontness — function @experimental```(order: LayerOrder, worldY: number, worldZ: number): numberdiff --git a/sdk/etc/wechat.api.md b/sdk/etc/wechat.api.mdindex fcb007b6a..7680b1cc5 100644--- a/sdk/etc/wechat.api.md+++ b/sdk/etc/wechat.api.md@@ -1,7 +1,7 @@# API surface — esengine/wechat<!-- Generated by tools/api-surface.mjs — do not edit. Run --update to accept changes. -->-Symbols: 115 public · 166 beta · 2175 experimental · 3 deprecated+Symbols: 115 public · 166 beta · 2179 experimental · 3 deprecated## ANCHOR_AXES — const @experimental```@@ -776,7 +776,7 @@ getEntityCount: () => numbergetFixedTimestep: () => numbergetFrameCosts: () => FrameCosts | nullgetFrameScopes: () => ReadonlyMap<string, number> | null-getFrameTiming: () => Readonly<{ seq: number; frameMs: number; }> | null+getFrameTiming: () => Readonly<FrameTiming> | nullgetPhaseTimings: () => ReadonlyMap<string, number> | nullgetPlaySpeed: () => numbergetPlugin: <T extends Plugin>(ctor: new (...args: any[]) => T) => T | undefined@@ -4829,6 +4829,18 @@ vramBytes: numberwasmBytes: number```+## FrameTiming — interface @experimental+```+busyMs: number+frameMs: number+seq: number+```++## FrameVerdict — type @experimental+```+'gpu-pressure' | 'frame-pressure' | 'headroom' | 'steady'+```+## GLDebug — const @experimental```{ enable(): void; disable(): void; check(context: string): number; diagnose(): void; }@@ -8554,7 +8566,7 @@ enabled: booleanprofile: Readonly<QualityProfile>renderScale: numberreport: () => QualityReport-sample: (frameMs: number, gpuMs?: number) => void+sample: (sample: Readonly<QualitySample>) => voidsetCeiling: (level: QualityLevel | null) => voidsetLimitation: (reason: string, active: boolean) => voidsetMode: (mode: QualityMode) => void@@ -8606,8 +8618,10 @@ waterWaves: number## QualityReport — interface @experimental```+busyMs: numberdrawCallBudget: numberframeMs: number+gpuMs: numberlevel: QualityLevellimitations: string[]mode: QualityMode@@ -8616,6 +8630,13 @@ renderScale: numbertargetFps: number```+## QualitySample — interface @experimental+```+busyMs: number | undefined+frameMs: number+gpuMs: number | undefined+```+## Quat — interface @public```w: number@@ -16434,6 +16455,11 @@ InputRouter(d: SwingTwistJoint3DData | SixDOFJoint3DData): string | null```+## judgeFrames — function @experimental+```+(avg: Readonly<Required<QualitySample>>, budgetMs: number): FrameVerdict+```+## layerFrontness — function @experimental```(order: LayerOrder, worldY: number, worldZ: number): numberdiff --git a/sdk/src/app/app.ts b/sdk/src/app/app.tsindex c77917cff..25955f044 100644--- a/sdk/src/app/app.ts+++ b/sdk/src/app/app.ts@@ -109,6 +109,25 @@ export interface FrameCosts {scopes: ScopeCost[];}+/**+ * @experimental What the loop's own clock read for one completed frame. The one+ * place frame time is measured: the profiler, the debug channel and the quality+ * controller all take it from here instead of each keeping a clock.+ */+export interface FrameTiming {+ /** Counts completed frames, so a reader can tell a new one from the last. */+ seq: number;+ /** Interval since the previous frame, before simulation speed or delta clamping. */+ frameMs: number;+ /**+ * How long this frame's own run took, first system to last; -1 where there is+ * no clock. What is left of `frameMs` is time the loop waited for its next+ * turn, so a frame that came late with this inside the budget was not held up+ * by its systems.+ */+ busyMs: number;+}+/** A system still running, and what decides who may start beside it. */interface InflightSystem {/** Its position in the sorted list — how a dependant recognises it. */@@ -196,7 +215,7 @@ export class App {private runInBackground_ = false;private onVisibility_: (() => void) | null = null;private frameInFlight_: Promise<void> | null = null;- private frameTiming_: { seq: number; frameMs: number } | null = null;+ private frameTiming_: FrameTiming | null = null;private lastTime_ = 0;private fixedTimestep_ = 1 / 60;private fixedAccumulator_ = 0;@@ -1007,8 +1026,8 @@ export class App {return this.phaseTimings_;}- /** @experimental Completed frame interval before simulation speed or delta clamping. */- getFrameTiming(): Readonly<{ seq: number; frameMs: number }> | null {+ /** @experimental The last completed frame's clock readings; see {@link FrameTiming}. */+ getFrameTiming(): Readonly<FrameTiming> | null {return this.frameTiming_;}@@ -1620,6 +1639,8 @@ export class App {if (this.isExecutionHeld()) return;const executionEpoch = this.executionEpoch_;const current = () => !this.isExecutionHeld() && executionEpoch === this.executionEpoch_;+ const frameClock = typeof performance !== 'undefined' && typeof performance.now === 'function' ? performance : null;+ const frameStart = frameClock ? frameClock.now() : 0;this.runner_?.clearTimings();this.phaseTimings_?.clear();this.frameScopes_?.clear();@@ -1691,7 +1712,10 @@ export class App {}if (!current()) return;- this.frameTiming_ = { seq: (this.frameTiming_?.seq ?? 0) + 1, frameMs };+ this.frameTiming_ = {+ seq: (this.frameTiming_?.seq ?? 0) + 1, frameMs,+ busyMs: frameClock ? frameClock.now() - frameStart : -1,+ };for (const observe of this.frameObservers_) {try { observe(frameMs); } catch (e) {log.error('app', 'Frame observer error', e);diff --git a/sdk/src/core-render.ts b/sdk/src/core-render.tsindex 10777ed09..20ce0d60e 100644--- a/sdk/src/core-render.ts+++ b/sdk/src/core-render.ts@@ -357,10 +357,10 @@ export {type PreSceneDrawCallback,type PreSceneDrawInfo,} from './render/customDraw';-export { QualityController, parseQualityConfig, resolveQualityProfile, defaultQualityProfile, defaultQualityMode } from './render/quality';+export { QualityController, judgeFrames, parseQualityConfig, resolveQualityProfile, defaultQualityProfile, defaultQualityMode } from './render/quality';export type {QualityConfig, QualityProfile, QualityLevel, QualityMode,- QualityReport, DeviceQualityInfo, DeviceQualityRule,+ QualityReport, QualitySample, FrameVerdict, DeviceQualityInfo, DeviceQualityRule,} from './render/quality';export { Quality } from './render/qualityRuntime';export { warmShaders, shadersCompiled, pendingShaders } from './render/shaderWarmup';diff --git a/sdk/src/core-runtime.ts b/sdk/src/core-runtime.tsindex 210c922f9..e3cf38096 100644--- a/sdk/src/core-runtime.ts+++ b/sdk/src/core-runtime.ts@@ -535,6 +535,7 @@ export {addPlugin,flushPendingRegistrations,type FrameCosts,+ type FrameTiming,type Plugin,type PluginDependency,type WebAppOptions,diff --git a/sdk/src/render/quality.ts b/sdk/src/render/quality.tsindex 47f9ada45..0b683f42f 100644--- a/sdk/src/render/quality.ts+++ b/sdk/src/render/quality.ts@@ -316,13 +316,65 @@ export interface QualityReport {level: QualityLevel;renderScale: number;targetFps: number;+ /** Smoothed frame interval. */frameMs: number;+ /** Smoothed time the frame's own run took, and the GPU's time for it; -1 where the host does not say. */+ busyMs: number;+ gpuMs: number;reason: string;limitations: string[];/** The level's draw call budget (see `QualityProfile.drawCallBudget`). */drawCallBudget: number;}+/**+ * @experimental One frame's clock readings, as dynamic resolution takes them. `frameMs` is the interval since the last+ * frame; `busyMs` how long the frame's own run took (`FrameTiming.busyMs`); `gpuMs` the GPU's time for the frame. The+ * last two are optional, and a value that is not a positive number counts as not given.+ */+export interface QualitySample {+ frameMs: number;+ busyMs?: number;+ gpuMs?: number;+}++/** @experimental What a stretch of frames says about the render resolution. */+export type FrameVerdict = 'gpu-pressure' | 'frame-pressure' | 'headroom' | 'steady';++const PRESSURE = 1.1;+const HEADROOM = 0.8;++/**+ * @experimental Whether resolution should go down, may come back up, or stay, from smoothed readings (-1 = not known)+ * and the frame budget. Pure.+ *+ * A GPU reading over the budget is pressure on its own word. A small one is not headroom on its own word: a timer+ * can cover less than the frame (a tile renderer has not drawn when the pass is stamped), so what a low reading may+ * do is decided with the frame itself. A frame that came late although its own run fitted the budget waited on the+ * GPU or the display, and resolution is the lever for that; one whose run did not fit is the CPU's, and resolution+ * would buy nothing.+ */+export function judgeFrames(avg: Readonly<Required<QualitySample>>, budgetMs: number): FrameVerdict {+ const gpuKnown = avg.gpuMs > 0;+ const busyKnown = avg.busyMs > 0;+ if (gpuKnown && avg.gpuMs > budgetMs * PRESSURE) return 'gpu-pressure';+ const gpuFree = gpuKnown && avg.gpuMs < budgetMs * HEADROOM;+ if (avg.frameMs > budgetMs * PRESSURE) {+ if (busyKnown ? avg.busyMs <= budgetMs : !gpuKnown) return 'frame-pressure';+ return gpuFree ? 'headroom' : 'steady';+ }+ return (gpuKnown ? gpuFree : avg.frameMs < budgetMs * HEADROOM) ? 'headroom' : 'steady';+}++/** Pressure for this long lowers the scale a step; headroom for `RECOVER_MS` and up raises it one. */+const PRESSURE_MS = 500;+const RECOVER_MS = 2000;+const RECOVER_MAX_MS = 32000;+/** A step up that is taken back within this long was a mistake, not a change of scene. */+const BOUNCE_MS = 5000;++const known = (ms: number | undefined): ms is number => ms !== undefined && Number.isFinite(ms) && ms > 0;+/** @experimental Per-app policy; authored scene components remain unchanged. */export class QualityController {private config_: QualityConfig;@@ -332,9 +384,14 @@ export class QualityController {private ceiling_: QualityLevel | null = null;private profile_: QualityProfile = PROFILES.high;private scale_ = 1;- private average_ = 0;+ private average_: Required<QualitySample> = { frameMs: 0, busyMs: -1, gpuMs: -1 };private pressureMs_ = 0;private recoveryMs_ = 0;+ /** Sampled time, the clock the two below are read on. */+ private clockMs_ = 0;+ private raisedAt_ = -1;+ /** How long headroom must last before a step up; grows while steps up keep being taken back. */+ private recoverAfterMs_ = RECOVER_MS;private reason_ = 'disabled';private modeReason_ = 'disabled';private limitations_ = new Set<string>();@@ -358,7 +415,7 @@ export class QualityController {this.level_ = this.ceilingOf_(this.modeLevel_);this.profile_ = resolveProfile(this.level_, this.config_.profiles?.[this.level_]);this.scale_ = mode === 'off' ? 1 : this.profile_.renderScale;- this.average_ = this.pressureMs_ = this.recoveryMs_ = 0;+ this.resetSampling_(true);this.reason_ = mode === 'off' ? 'disabled' : mode !== 'auto' ? 'manual': rule ? 'device-rule' : low ? 'device-capacity' : 'device-unknown';this.modeReason_ = this.reason_;@@ -381,7 +438,7 @@ export class QualityController {this.level_ = next;this.profile_ = resolveProfile(next, this.config_.profiles?.[next]);this.scale_ = this.enabled ? this.profile_.renderScale : 1;- this.average_ = this.pressureMs_ = this.recoveryMs_ = 0;+ this.resetSampling_(true);this.reason_ = next !== this.modeLevel_ ? 'power-saver' : this.modeReason_;}@@ -390,25 +447,53 @@ export class QualityController {else this.limitations_.delete(reason);}- sample(frameMs: number, gpuMs = -1): void {+ /** Forget the running averages; `all` also forgets what was learned about stepping back up. */+ private resetSampling_(all: boolean): void {+ this.average_ = { frameMs: 0, busyMs: -1, gpuMs: -1 };+ this.pressureMs_ = this.recoveryMs_ = 0;+ if (all) { this.clockMs_ = 0; this.raisedAt_ = -1; this.recoverAfterMs_ = RECOVER_MS; }+ }++ /**+ * Take one frame's readings. Sustained pressure lowers the render scale a step towards the level's floor;+ * sustained headroom raises it back a step. See {@link judgeFrames} for what counts as which.+ */+ sample(sample: Readonly<QualitySample>): void {if (!this.enabled || !this.config_.dynamicResolution) return;+ const { frameMs } = sample;if (!Number.isFinite(frameMs) || frameMs <= 0 || frameMs > 250) {- this.average_ = this.pressureMs_ = this.recoveryMs_ = 0;+ this.resetSampling_(false);return;}- const ms = Number.isFinite(gpuMs) && gpuMs > 0 ? gpuMs : frameMs;+ const first = this.average_.frameMs === 0;const weight = 1 - Math.exp(-frameMs / 250);- this.average_ = this.average_ === 0 ? ms : this.average_ + weight * (ms - this.average_);- const budget = 1000 / (this.config_.targetFps ?? 60);- this.pressureMs_ = this.average_ > budget * 1.1 ? this.pressureMs_ + frameMs : 0;- this.recoveryMs_ = this.average_ < budget * 0.8 ? this.recoveryMs_ + frameMs : 0;- if (this.pressureMs_ >= 500) {+ const blend = (avg: number, ms: number | undefined): number =>+ !known(ms) ? -1 : first || avg < 0 ? ms : avg + weight * (ms - avg);+ this.average_ = {+ frameMs: blend(this.average_.frameMs, frameMs),+ busyMs: blend(this.average_.busyMs, sample.busyMs),+ gpuMs: blend(this.average_.gpuMs, sample.gpuMs),+ };+ this.clockMs_ += frameMs;+ const verdict = judgeFrames(this.average_, 1000 / (this.config_.targetFps ?? 60));+ const pressed = verdict === 'gpu-pressure' || verdict === 'frame-pressure';+ this.pressureMs_ = pressed ? this.pressureMs_ + frameMs : 0;+ this.recoveryMs_ = verdict === 'headroom' ? this.recoveryMs_ + frameMs : 0;+ if (this.pressureMs_ >= PRESSURE_MS) {+ // A step up that had to be taken straight back: whatever called that headroom cannot be trusted on this+ // device, so the next one waits twice as long instead of flickering between two scales.+ if (this.raisedAt_ >= 0 && this.clockMs_ - this.raisedAt_ <= BOUNCE_MS) {+ this.recoverAfterMs_ = Math.min(RECOVER_MAX_MS, this.recoverAfterMs_ * 2);+ }+ this.raisedAt_ = -1;this.scale_ = Math.max(this.profile_.minRenderScale,Math.round((this.scale_ - 0.05) * 100) / 100);- this.reason_ = this.scale_ === this.profile_.minRenderScale- ? 'resolution-floor' : gpuMs > 0 ? 'gpu-pressure' : 'frame-pressure';+ this.reason_ = this.scale_ === this.profile_.minRenderScale ? 'resolution-floor' : verdict;this.pressureMs_ = this.recoveryMs_ = 0;- } else if (this.recoveryMs_ >= 2000) {+ } else if (this.recoveryMs_ >= this.recoverAfterMs_) {+ // The last step up held, so the wait eases back towards its start.+ if (this.raisedAt_ >= 0) this.recoverAfterMs_ = Math.max(RECOVER_MS, this.recoverAfterMs_ / 2);+ this.raisedAt_ = this.scale_ < this.profile_.renderScale ? this.clockMs_ : -1;this.scale_ = Math.min(this.profile_.renderScale,Math.round((this.scale_ + 0.05) * 100) / 100);this.reason_ = this.scale_ === this.profile_.renderScale ? this.modeReason_ : 'recovery';@@ -420,7 +505,8 @@ export class QualityController {return {mode: this.config_.mode ?? 'off', level: this.level_,renderScale: this.renderScale, targetFps: this.config_.targetFps ?? 60,- frameMs: this.average_, reason: this.reason_, limitations: [...this.limitations_],+ frameMs: this.average_.frameMs, busyMs: this.average_.busyMs, gpuMs: this.average_.gpuMs,+ reason: this.reason_, limitations: [...this.limitations_],drawCallBudget: this.profile_.drawCallBudget,};}diff --git a/sdk/src/render/qualityRuntime.ts b/sdk/src/render/qualityRuntime.tsindex beba2c32b..2623b74a7 100644--- a/sdk/src/render/qualityRuntime.ts+++ b/sdk/src/render/qualityRuntime.ts@@ -80,10 +80,15 @@ export function installQuality(app: App, config: QualityConfig, authoredMsaa: nucheck();powerTimer = setInterval(check, 5000);}+ // The interval is the platform clock's, edge to edge, so it holds what the display made the loop wait; the frame's+ // own run is the loop's reading of it, and the GPU's is the renderer's.const stop = app.onFrameEnd(() => {const now = platformNow();- if (!hidden && !app.isPaused() && last > 0) quality.sample(now - last,- engineApi(app)?.renderer_getGpuTimeMs?.() ?? -1);+ if (!hidden && !app.isPaused() && last > 0) quality.sample({+ frameMs: now - last,+ busyMs: app.getFrameTiming()?.busyMs,+ gpuMs: engineApi(app)?.renderer_getGpuTimeMs?.(),+ });last = hidden || app.isPaused() ? 0 : now;});app.addPlugin({ name: 'quality', build() {}, cleanup() { stop(); hide(); show(); if (powerTimer !== null) clearInterval(powerTimer); } });diff --git a/sdk/tests/quality.test.ts b/sdk/tests/quality.test.tsindex 5a51c06f5..5c9213022 100644--- a/sdk/tests/quality.test.ts+++ b/sdk/tests/quality.test.ts@@ -2,12 +2,12 @@// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Teamimport { describe, expect, it } from 'vitest';-import { parseQualityConfig, QualityController } from '../src/render/quality';+import { judgeFrames, parseQualityConfig, QualityController } from '../src/render/quality';describe('quality selection', () => {it('keeps unconfigured projects at their authored resolution', () => {const q = new QualityController({});- for (let i = 0; i < 100; i++) q.sample(40);+ for (let i = 0; i < 100; i++) q.sample({ frameMs: 40 });expect(q.enabled).toBe(false);expect(q.renderScale).toBe(1);});@@ -56,13 +56,13 @@ describe('quality selection', () => {describe('dynamic resolution', () => {const make = () => new QualityController({ mode: 'high', dynamicResolution: true });- const sample = (q: QualityController, frames: number, frameMs: number, gpuMs = -1) => {- for (let i = 0; i < frames; i++) q.sample(frameMs, gpuMs);+ const sample = (q: QualityController, frames: number, frameMs: number, gpuMs = -1, busyMs = -1) => {+ for (let i = 0; i < frames; i++) q.sample({ frameMs, gpuMs, busyMs });};it('ignores a transient spike, then reduces resolution under sustained pressure', () => {const q = make();- q.sample(40, 40);+ q.sample({ frameMs: 40, gpuMs: 40 });expect(q.renderScale).toBe(1);sample(q, 20, 40, 40);expect(q.renderScale).toBeLessThan(1);@@ -90,6 +90,64 @@ describe('dynamic resolution', () => {expect(q.renderScale).toBeLessThanOrEqual(1);});+ // A phone whose GPU timer reads half a millisecond while the frame takes 27: the frame's own run fits the budget,+ // so the wait is the GPU's, whatever its timer says (#120).+ it('lowers resolution when the frame is late and its own run was not, however little the GPU timer reads', () => {+ const q = make();+ sample(q, 30, 27, 0.5, 15);+ expect(q.renderScale).toBeLessThan(1);+ expect(q.report().reason).toBe('frame-pressure');+ sample(q, 300, 27, 0.5, 15);+ expect(q.renderScale).toBe(0.75);+ expect(q.report()).toMatchObject({ reason: 'resolution-floor', gpuMs: 0.5, busyMs: 15 });+ expect(q.report().frameMs).toBeCloseTo(27);+ });++ it('leaves resolution alone when the frame is late because its own run is long', () => {+ const withTimer = make();+ sample(withTimer, 200, 40, 0.5, 38);+ expect(withTimer.renderScale).toBe(1);+ // No GPU timer at all: the run still says whose frame it is.+ const without = make();+ sample(without, 200, 40, -1, 38);+ expect(without.renderScale).toBe(1);+ // And with neither, a late frame is all there is to go on.+ const blind = make();+ sample(blind, 200, 40);+ expect(blind.renderScale).toBe(0.75);+ });++ it('stops stepping back up when every step up has to be taken back', () => {+ // The same phone: on budget at 0.8 and under, late above it, and a GPU timer that always claims headroom.+ const q = make();+ let changes = 0;+ const run = (ms: number) => {+ for (let t = 0; t < ms;) {+ const frameMs = q.renderScale > 0.8 ? 27 : 16.7;+ const before = q.renderScale;+ q.sample({ frameMs, gpuMs: 0.5, busyMs: 10 });+ if (q.renderScale !== before) changes++;+ t += frameMs;+ }+ };+ run(10_000);+ expect(q.renderScale).toBeLessThanOrEqual(0.85);+ changes = 0;+ run(120_000);+ // A fixed two-second wait would trade the two scales about fifty times in two minutes.+ expect(changes).toBeLessThanOrEqual(14);+ expect(q.renderScale).toBeGreaterThanOrEqual(0.8);+ });++ it('takes a step up again once the scene is lighter', () => {+ const q = make();+ sample(q, 300, 27, 0.5, 15);+ expect(q.renderScale).toBe(0.75);+ sample(q, 1500, 16.7, 0.5, 8);+ expect(q.renderScale).toBe(1);+ expect(q.report().reason).toBe('manual');+ });+it('says which post-process effects each level leaves out, and takes an override', () => {const levels = (config: object, level: 'low' | 'medium' | 'high') => {const q = new QualityController({ mode: level, ...config });@@ -106,7 +164,7 @@ describe('dynamic resolution', () => {it('does not react to background gaps, invalid clocks or a static tier', () => {const q = make();- for (const ms of [NaN, Infinity, 0, -5, 30000]) q.sample(ms);+ for (const ms of [NaN, Infinity, 0, -5, 30000]) q.sample({ frameMs: ms });expect(q.renderScale).toBe(1);expect(q.report().frameMs).toBe(0);const staticQ = new QualityController({ mode: 'low' });@@ -115,6 +173,33 @@ describe('dynamic resolution', () => {});});+describe('judgeFrames', () => {+ const budget = 1000 / 60;+ const judge = (frameMs: number, gpuMs = -1, busyMs = -1) => judgeFrames({ frameMs, gpuMs, busyMs }, budget);++ it('takes a GPU reading over the budget at its word', () => {+ expect(judge(40, 40)).toBe('gpu-pressure');+ expect(judge(40, 40, 38)).toBe('gpu-pressure');+ expect(judge(16.7, 20, 5)).toBe('gpu-pressure');+ });++ it('asks the frame before believing a small one', () => {+ expect(judge(27, 0.5, 15)).toBe('frame-pressure');+ expect(judge(27, 0.5, 26)).toBe('headroom'); // the CPU's frame, and the GPU is idle: resolution is free+ expect(judge(27, 15, 26)).toBe('steady');+ expect(judge(16.7, 0.5, 8)).toBe('headroom');+ expect(judge(16.7, 15, 8)).toBe('steady');+ });++ it('falls back to what it is given', () => {+ expect(judge(40, 5)).toBe('headroom'); // no run time: the GPU reading stands, as it always did+ expect(judge(40)).toBe('frame-pressure');+ expect(judge(40, -1, 38)).toBe('steady');+ expect(judge(10)).toBe('headroom');+ expect(judge(16.7)).toBe('steady');+ });+});+describe('what a quality level lets the chain run', () => {it('honours a list of every effect there is, however many that has become', () => {const all = Array.from({ length: 64 }, (_, i) => `effect${i}`);diff --git a/src/esengine/renderer/rhi/GfxDevice.hpp b/src/esengine/renderer/rhi/GfxDevice.hppindex fb30da858..9a4049cd1 100644--- a/src/esengine/renderer/rhi/GfxDevice.hpp+++ b/src/esengine/renderer/rhi/GfxDevice.hpp@@ -795,7 +795,11 @@ public:/** @brief Creates a GPU elapsed-time query, or 0 when the backend cannot time GPU work. */u32 createTimerQuery();- /** @brief Starts timing GPU work into a query; one query may be active at a time. */+ /**+ * @brief Starts timing GPU work into a query; one query may be active at a time.+ * @details The same span on every backend: the GPU's time for everything issued until endTimerQuery, every pass+ * included. A render pass still open at the end belongs to the span up to where the pass ends.+ */virtual void beginTimerQuery(u32 query) = 0;/** @brief Stops the active timer query */diff --git a/src/esengine/renderer/webgpu/WebGPUDevice.cpp b/src/esengine/renderer/webgpu/WebGPUDevice.cppindex 1ece100ce..c43b9294a 100644--- a/src/esengine/renderer/webgpu/WebGPUDevice.cpp+++ b/src/esengine/renderer/webgpu/WebGPUDevice.cpp@@ -181,6 +181,10 @@ void WebGPUDevice::releaseDeviceObjects() {capture_copied_ = false;pass_is_surface_ = false;pass_timed_ = false;+ span_open_ = false;+ span_closing_ = false;+ span_slot_ = kGpuTimeRing;+ span_passes_ = 0;// bind_group_/texture_group_ point INTO the cache — release the cache, not them.for (auto& e : bind_group_cache_) if (e.bg) wgpuBindGroupRelease(e.bg);@@ -2477,23 +2481,10 @@ void WebGPUDevice::beginRenderPass(const RenderPassDesc& desc) {encoder_ = wgpuDeviceCreateCommandEncoder(device_, nullptr);- // GPU timing: time the surface (present) pass — one timestamped pass per frame- // in the common case. Reserve a free ring slot; skip timing if none is free.- pass_timed_ = false;- gpu_time_slot_ = kGpuTimeRing;- // A pass the graph armed is timed whatever it draws to; it takes the timestamp slot the surface pass would have used.+ // GPU timing. A pass the graph armed is timed under its own name; any other pass that opens inside a timer span+ // adds its time to the span, whatever it draws to — the span is the frame's, not the surface pass's.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) {- gpu_time_slot_ = s;- gpu_time_next_ = (s + 1) % kGpuTimeRing;- break;- }- }- pass_timed_ = (gpu_time_slot_ < kGpuTimeRing);- }+ pass_timed_ = pass_time_slot_ == kNoPassSlot && spanTakesPass();const bool scoped = desc.clearW != 0;WGPURenderPassColorAttachment color{};@@ -2582,12 +2573,8 @@ void WebGPUDevice::endRenderPass() {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);- wgpuCommandEncoderCopyBufferToBuffer(encoder_, timestamp_resolve_, 0,- gpu_time_ring_[gpu_time_slot_].buf, 0, 16);- }+ if (pass_timed_ && encoder_) resolveSpanPass(encoder_);+ pass_timed_ = false;// A booked capture rides the pass's OWN encoder: the browser presents the// swapchain image with this submit, so a copy encoded afterwards copies a@@ -2605,19 +2592,11 @@ void WebGPUDevice::endRenderPass() {wgpuCommandBufferRelease(commands);if (passSlot != kNoPassSlot) mapPassTime(passSlot);- if (timed) {- // Map async — drained by getTimerQueryNs a few frames later (the GpuTimer- // ring tolerates the latency).- gpu_time_ring_[gpu_time_slot_].pending = true;- WGPUBufferMapCallbackInfo cb = WGPU_BUFFER_MAP_CALLBACK_INFO_INIT;- cb.mode = WGPUCallbackMode_AllowSpontaneous;- cb.callback = &WebGPUDevice::onGpuTimeMapped;- cb.userdata1 = this;- cb.userdata2 = reinterpret_cast<void*>(static_cast<uintptr_t>(gpu_time_slot_));- wgpuBufferMapAsync(gpu_time_ring_[gpu_time_slot_].buf, WGPUMapMode_Read, 0, 16, cb);+ // The span was closed while this pass was still open: it was the last one in it.+ if (span_closing_) {+ span_closing_ = false;+ finishSpan();}- pass_timed_ = false;- gpu_time_slot_ = kGpuTimeRing;}/** Give the swapchain texture back: the frame is over (see GfxDevice::endFrame).@@ -2833,7 +2812,7 @@ void WebGPUDevice::ensureTimestamps() {WGPUQuerySetDescriptor qd{};qd.type = WGPUQueryType_Timestamp;- qd.count = 2; // begin + end of the timed pass+ qd.count = 2; // begin + end of the pass being timed; resolved out before the next pass reuses themtimestamp_qset_ = wgpuDeviceCreateQuerySet(device_, &qd);if (!timestamp_qset_) return;@@ -2844,21 +2823,78 @@ void WebGPUDevice::ensureTimestamps() {for (u32 i = 0; i < kGpuTimeRing; ++i) {WGPUBufferDescriptor bd{};bd.usage = WGPUBufferUsage_MapRead | WGPUBufferUsage_CopyDst;- bd.size = 16;+ bd.size = 16 * kSpanPasses;gpu_time_ring_[i].buf = wgpuDeviceCreateBuffer(device_, &bd);}timestamp_supported_ = timestamp_resolve_ && gpu_time_ring_[0].buf;}-// One query set serves every timer: timing rides the surface pass, so a query id+// One query set serves every timer: timing rides the passes, so a query id// only has to exist for the engine's GpuTimer to turn on.bool WebGPUDevice::backendCreateTimerQuery(u32) {ensureTimestamps();return timestamp_supported_;}-void WebGPUDevice::beginTimerQuery(u32) {} // timing rides the pass: attached at beginRenderPass, resolved at endRenderPass-void WebGPUDevice::endTimerQuery() {}+// A span is what GL's GL_TIME_ELAPSED gives between the same two calls: the GPU's time for everything issued inside+// it. WebGPU can only stamp a pass, so every pass that opens inside the span is stamped and the span is their sum.+void WebGPUDevice::beginTimerQuery(u32) {+ if (!timestamp_supported_) return;+ span_closing_ = false;+ span_slot_ = kGpuTimeRing;+ span_passes_ = 0;+ for (u32 i = 0; i < kGpuTimeRing; ++i) {+ const u32 s = (gpu_time_next_ + i) % kGpuTimeRing;+ if (!gpu_time_ring_[s].pending) {+ span_slot_ = s;+ gpu_time_next_ = (s + 1) % kGpuTimeRing;+ break;+ }+ }+ // With every readback still in flight the span goes untimed, and says so with a zero rather than no answer:+ // the caller keeps one query in flight per span and would otherwise wait on this one for good.+ span_open_ = true;+}++void WebGPUDevice::endTimerQuery() {+ if (!span_open_) return;+ span_open_ = false;+ // A pass still open belongs to the span and has not been stamped yet; its end finishes the span.+ if (pass_) span_closing_ = true;+ else finishSpan();+}++bool WebGPUDevice::spanTakesPass() const {+ return timestamp_supported_ && span_open_ && span_slot_ < kGpuTimeRing && span_passes_ < kSpanPasses;+}++void WebGPUDevice::resolveSpanPass(WGPUCommandEncoder encoder) {+ wgpuCommandEncoderResolveQuerySet(encoder, timestamp_qset_, 0, 2, timestamp_resolve_, 0);+ wgpuCommandEncoderCopyBufferToBuffer(encoder, timestamp_resolve_, 0,+ gpu_time_ring_[span_slot_].buf, 16ull * span_passes_, 16);+ ++span_passes_;+}++void WebGPUDevice::finishSpan() {+ const u32 slot = span_slot_;+ const u32 passes = span_passes_;+ span_slot_ = kGpuTimeRing;+ span_passes_ = 0;+ if (!timestamp_supported_) return;+ if (slot >= kGpuTimeRing || passes == 0) {+ if (gpu_time_results_.size() < 16) gpu_time_results_.push_back(0);+ return;+ }+ // Map async — drained by getTimerQueryNs a few frames later (the GpuTimer ring tolerates the latency).+ gpu_time_ring_[slot].pending = true;+ gpu_time_ring_[slot].passes = passes;+ WGPUBufferMapCallbackInfo cb = WGPU_BUFFER_MAP_CALLBACK_INFO_INIT;+ cb.mode = WGPUCallbackMode_AllowSpontaneous;+ cb.callback = &WebGPUDevice::onGpuTimeMapped;+ cb.userdata1 = this;+ cb.userdata2 = reinterpret_cast<void*>(static_cast<uintptr_t>(slot));+ wgpuBufferMapAsync(gpu_time_ring_[slot].buf, WGPUMapMode_Read, 0, 16ull * passes, cb);+}bool WebGPUDevice::timerDisjoint() { return false; }bool WebGPUDevice::getTimerQueryNs(u32 query, u64* outNs) {@@ -2938,11 +2974,16 @@ void WebGPUDevice::onGpuTimeMapped(WGPUMapAsyncStatus status, WGPUStringView /*mconst u32 slot = static_cast<u32>(reinterpret_cast<uintptr_t>(userdata2));if (!self || slot >= kGpuTimeRing) return;WGPUBuffer buf = self->gpu_time_ring_[slot].buf;+ const u32 passes = self->gpu_time_ring_[slot].passes;if (status == WGPUMapAsyncStatus_Success && buf) {- const auto* ts = static_cast<const u64*>(wgpuBufferGetConstMappedRange(buf, 0, 16));+ const auto* ts = static_cast<const u64*>(wgpuBufferGetConstMappedRange(buf, 0, 16ull * passes));+ // The span is the sum of its passes; a pair that ran backwards (a timestamp reset) counts for nothing.+ u64 total = 0;+ for (u32 i = 0; ts && i < passes; ++i) {+ if (ts[2 * i + 1] >= ts[2 * i]) total += ts[2 * i + 1] - ts[2 * i];+ }// Cap the FIFO so a stalled consumer can't grow it without bound.- if (ts && ts[1] >= ts[0] && self->gpu_time_results_.size() < 16)- self->gpu_time_results_.push_back(ts[1] - ts[0]);+ if (ts && self->gpu_time_results_.size() < 16) self->gpu_time_results_.push_back(total);wgpuBufferUnmap(buf);}self->gpu_time_ring_[slot].pending = false;@@ -3180,8 +3221,11 @@ bool WebGPUDevice::backendDispatchCompute(u32 id, const GfxComputeBinding* bindiWGPUCommandEncoder encoder = wgpuDeviceCreateCommandEncoder(device_, nullptr);WGPUComputePassDescriptor pd = WGPU_COMPUTE_PASS_DESCRIPTOR_INIT;const u32 passSlot = takePassTimeSlot();+ // A kernel is the frame's GPU time as much as a draw is. No render pass is open here to carry a span past its+ // end, so this one is resolved and counted before the call returns.+ const bool inSpan = passSlot == kNoPassSlot && spanTakesPass();WGPUPassTimestampWrites tw{};- if (passSlot != kNoPassSlot) {+ if (passSlot != kNoPassSlot || inSpan) {tw.querySet = timestamp_qset_;tw.beginningOfPassWriteIndex = 0;tw.endOfPassWriteIndex = 1;@@ -3194,6 +3238,7 @@ bool WebGPUDevice::backendDispatchCompute(u32 id, const GfxComputeBinding* bindiwgpuComputePassEncoderEnd(pass);wgpuComputePassEncoderRelease(pass);if (passSlot != kNoPassSlot) resolvePassTime(encoder, passSlot);+ if (inSpan) resolveSpanPass(encoder);WGPUCommandBuffer commands = wgpuCommandEncoderFinish(encoder, nullptr);wgpuCommandEncoderRelease(encoder);wgpuQueueSubmit(queue_, 1, &commands);diff --git a/src/esengine/renderer/webgpu/WebGPUDevice.hpp b/src/esengine/renderer/webgpu/WebGPUDevice.hppindex 39fb37037..2c5e27a0e 100644--- a/src/esengine/renderer/webgpu/WebGPUDevice.hpp+++ b/src/esengine/renderer/webgpu/WebGPUDevice.hpp@@ -651,22 +651,32 @@ private:// GPU timing — the WebGPU analog of GLDevice's GL_TIME_ELAPSED timer, so the// profiler's gpuMs/gpuScopes populate on both backends. Active only when the// device has the timestamp-query feature; otherwise createTimerQuery returns 0- // and timing stays off (unchanged behavior). The surface (present) pass writes- // a begin/end timestamp; endRenderPass resolves them into a ring of readback- // buffers mapped asynchronously, and getTimerQueryNs drains the elapsed ns into- // the engine's GpuTimer (whose ring already tolerates a few frames of latency).+ // and timing stays off (unchanged behavior). begin/endTimerQuery bracket a span;+ // every render or compute pass that opens inside it writes a begin/end timestamp,+ // resolved into the span's readback buffer, and the span is their sum — the+ // whole frame's GPU time, as GL's query gives it, not one pass's. The buffers are+ // mapped asynchronously and getTimerQueryNs drains the elapsed ns into the+ // engine's GpuTimer (whose ring already tolerates a few frames of latency).bool timestamp_supported_ = false;bool timestamp_init_done_ = false;WGPUQuerySet timestamp_qset_ = nullptr; ///< 2 slots: begin/end of the timed pass.WGPUBuffer timestamp_resolve_ = nullptr; ///< QueryResolve target (16 bytes).static constexpr u32 kGpuTimeRing = 4;- struct GpuTimeSlot { WGPUBuffer buf = nullptr; bool pending = false; };+ /// Passes one span can sum. A frame with more is timed up to here, which reads low rather than wrong-way.+ static constexpr u32 kSpanPasses = 96;+ struct GpuTimeSlot { WGPUBuffer buf = nullptr; bool pending = false; u32 passes = 0; };GpuTimeSlot gpu_time_ring_[kGpuTimeRing] = {};u32 gpu_time_next_ = 0; ///< Round-robin cursor into the ring.- u32 gpu_time_slot_ = kGpuTimeRing; ///< Slot reserved for the in-flight timed pass (== kGpuTimeRing: none).- bool pass_timed_ = false; ///< Did the current pass attach timestampWrites?+ bool span_open_ = false; ///< Between beginTimerQuery and endTimerQuery.+ bool span_closing_ = false; ///< Ended with a render pass still open; that pass's end finishes it.+ u32 span_slot_ = kGpuTimeRing; ///< Ring slot the open span resolves into (== kGpuTimeRing: none).+ u32 span_passes_ = 0; ///< Passes resolved into it so far.+ bool pass_timed_ = false; ///< Does the open render pass carry timestamps for the span?std::vector<u64> gpu_time_results_; ///< Resolved elapsed-ns, FIFO, drained by getTimerQueryNs.void ensureTimestamps(); ///< Lazily create the query set + buffers (feature-gated).+ bool spanTakesPass() const; ///< Should a pass opening now be stamped for the span?+ void resolveSpanPass(WGPUCommandEncoder encoder); ///< After such a pass ends, on its encoder.+ void finishSpan(); ///< Map the span's buffer; its sum arrives in gpu_time_results_.// 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.diff --git a/tools/render-host/host.ts b/tools/render-host/host.tsindex e91b8a6d5..9279c959a 100644--- a/tools/render-host/host.ts+++ b/tools/render-host/host.ts@@ -644,6 +644,12 @@ const api = {}},+ /** The GPU's time for a whole frame as a shipped game reads it — the number dynamic resolution steers by. -1 until+ * the device has answered, and late in the same way as the scopes below. */+ getGpuTimeMs(): number {+ return module?.renderer_getGpuTimeMs?.() ?? -1;+ },+/** 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> {diff --git a/tools/render-host/run.mjs b/tools/render-host/run.mjsindex 74e7fdb82..46131c615 100644--- a/tools/render-host/run.mjs+++ b/tools/render-host/run.mjs@@ -240,7 +240,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.lightingSplit?.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.draws?.ok ?? true) && (result.lightingSplit?.ok ?? true) && (result.counters?.ok ?? true) && (result.gpuPasses?.ok ?? true) && (result.gpuFrame?.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}`);@@ -750,6 +750,39 @@ app.whenReady().then(async () => {];counters = { points, ok: points.every((p) => p.ok) };}+ // ESTELLA_VERIFY_GPU_FRAME=print|require: the frame's GPU time read the way a shipped game reads it (profiler+ // off, one span over the graph) beside the sum of its passes (profiler on). They are the same question asked two+ // ways, and a backend that answers the first with one pass of the frame reads far under the second — which is+ // how a phone held 37 fps with dynamic resolution on (#120). `require` fails when the two disagree by more than+ // half; local-only like the pass timer, and for a scene with passes off the surface, or there is nothing to miss.+ let gpuFrame = null;+ if (process.env.ESTELLA_VERIFY_GPU_FRAME) {+ const settle = async (read, done) => {+ const seen = [];+ for (let i = 0; i < 60 && seen.length < 8; i++) {+ await exec('window.__estellaHeadless.api.step(1, 1 / 60)');+ await new Promise((r) => setTimeout(r, 40));+ const value = await exec(read);+ if (done(value)) seen.push(value);+ }+ return seen;+ };+ const mean = (values) => (values.length ? values.reduce((a, b) => a + b, 0) / values.length : -1);+ await exec('window.__estellaHeadless.api.setCpuProfiling(false)');+ const spans = await settle('window.__estellaHeadless.api.getGpuTimeMs()', (ms) => ms > 0);+ await exec('window.__estellaHeadless.api.setCpuProfiling(true)');+ const scoped = await settle('window.__estellaHeadless.api.getGpuScopes()', (s) => Object.keys(s).some((k) => k.startsWith('pass/')));+ // Left as the run had it: a gate below that reads the last frame's counters needs the profiler it turned on.+ if (!(process.env.ESTELLA_VERIFY_COUNTERS || process.env.ESTELLA_VERIFY_COUNTERS_MAX || process.env.ESTELLA_VERIFY_FRAME_DEBUG || PREPASS)) {+ await exec('window.__estellaHeadless.api.setCpuProfiling(false)');+ }+ const sums = scoped.map((s) => Object.entries(s).filter(([k]) => k.startsWith('pass/')).reduce((a, [, v]) => a + v, 0));+ const passCount = scoped.length ? Object.keys(scoped[scoped.length - 1]).filter((k) => k.startsWith('pass/')).length : 0;+ const frameMs = mean(spans), passesMs = mean(sums);+ const agree = frameMs > 0 && passesMs > 0 && frameMs >= passesMs * 0.5 && frameMs <= passesMs * 2;+ console.log(`gpu frame (${BACKEND}): span ${frameMs.toFixed(3)} ms over ${spans.length} frames, passes ${passesMs.toFixed(3)} ms (${passCount} passes) — ${agree ? 'agree' : 'DISAGREE'}`);+ gpuFrame = { frameMs, passesMs, passCount, ok: process.env.ESTELLA_VERIFY_GPU_FRAME !== 'require' || agree };+ }// 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.@@ -1310,7 +1343,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, lightingSplit, 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);+ finish({ ok: true, studio, shading, lightingSplit, skinWeights, entityCount, missingAssets, drawCalls, draws, counters, gpuPasses, gpuFrame, 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);}