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.

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.md
index 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.md
index 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: () => number
getFixedTimestep: () => number
getFrameCosts: () => FrameCosts | null
getFrameScopes: () => ReadonlyMap<string, number> | null
-getFrameTiming: () => Readonly<{ seq: number; frameMs: number; }> | null
+getFrameTiming: () => Readonly<FrameTiming> | null
getPhaseTimings: () => ReadonlyMap<string, number> | null
getPlaySpeed: () => number
getPlugin: <T extends Plugin>(ctor: new (...args: any[]) => T) => T | undefined
@@ -4834,6 +4834,18 @@ vramBytes: number
wasmBytes: 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: boolean
profile: Readonly<QualityProfile>
renderScale: number
report: () => QualityReport
-sample: (frameMs: number, gpuMs?: number) => void
+sample: (sample: Readonly<QualitySample>) => void
setCeiling: (level: QualityLevel | null) => void
setLimitation: (reason: string, active: boolean) => void
setMode: (mode: QualityMode) => void
@@ -8604,8 +8616,10 @@ waterWaves: number
## QualityReport — interface @experimental
```
+busyMs: number
drawCallBudget: number
frameMs: number
+gpuMs: number
level: QualityLevel
limitations: string[]
mode: QualityMode
@@ -8614,6 +8628,13 @@ renderScale: number
targetFps: 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): number
diff --git a/sdk/etc/index.native.api.md b/sdk/etc/index.native.api.md
index 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: () => number
getFixedTimestep: () => number
getFrameCosts: () => FrameCosts | null
getFrameScopes: () => ReadonlyMap<string, number> | null
-getFrameTiming: () => Readonly<{ seq: number; frameMs: number; }> | null
+getFrameTiming: () => Readonly<FrameTiming> | null
getPhaseTimings: () => ReadonlyMap<string, number> | null
getPlaySpeed: () => number
getPlugin: <T extends Plugin>(ctor: new (...args: any[]) => T) => T | undefined
@@ -4842,6 +4842,18 @@ vramBytes: number
wasmBytes: 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: boolean
profile: Readonly<QualityProfile>
renderScale: number
report: () => QualityReport
-sample: (frameMs: number, gpuMs?: number) => void
+sample: (sample: Readonly<QualitySample>) => void
setCeiling: (level: QualityLevel | null) => void
setLimitation: (reason: string, active: boolean) => void
setMode: (mode: QualityMode) => void
@@ -8811,8 +8823,10 @@ waterWaves: number
## QualityReport — interface @experimental
```
+busyMs: number
drawCallBudget: number
frameMs: number
+gpuMs: number
level: QualityLevel
limitations: string[]
mode: QualityMode
@@ -8821,6 +8835,13 @@ renderScale: number
targetFps: 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): number
diff --git a/sdk/etc/index.node.api.md b/sdk/etc/index.node.api.md
index 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: () => number
getFixedTimestep: () => number
getFrameCosts: () => FrameCosts | null
getFrameScopes: () => ReadonlyMap<string, number> | null
-getFrameTiming: () => Readonly<{ seq: number; frameMs: number; }> | null
+getFrameTiming: () => Readonly<FrameTiming> | null
getPhaseTimings: () => ReadonlyMap<string, number> | null
getPlaySpeed: () => number
getPlugin: <T extends Plugin>(ctor: new (...args: any[]) => T) => T | undefined
@@ -4829,6 +4829,18 @@ vramBytes: number
wasmBytes: 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: boolean
profile: Readonly<QualityProfile>
renderScale: number
report: () => QualityReport
-sample: (frameMs: number, gpuMs?: number) => void
+sample: (sample: Readonly<QualitySample>) => void
setCeiling: (level: QualityLevel | null) => void
setLimitation: (reason: string, active: boolean) => void
setMode: (mode: QualityMode) => void
@@ -8599,8 +8611,10 @@ waterWaves: number
## QualityReport — interface @experimental
```
+busyMs: number
drawCallBudget: number
frameMs: number
+gpuMs: number
level: QualityLevel
limitations: string[]
mode: QualityMode
@@ -8609,6 +8623,13 @@ renderScale: number
targetFps: 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): number
diff --git a/sdk/etc/minigame.api.md b/sdk/etc/minigame.api.md
index 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: () => number
getFixedTimestep: () => number
getFrameCosts: () => FrameCosts | null
getFrameScopes: () => ReadonlyMap<string, number> | null
-getFrameTiming: () => Readonly<{ seq: number; frameMs: number; }> | null
+getFrameTiming: () => Readonly<FrameTiming> | null
getPhaseTimings: () => ReadonlyMap<string, number> | null
getPlaySpeed: () => number
getPlugin: <T extends Plugin>(ctor: new (...args: any[]) => T) => T | undefined
@@ -4829,6 +4829,18 @@ vramBytes: number
wasmBytes: 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: boolean
profile: Readonly<QualityProfile>
renderScale: number
report: () => QualityReport
-sample: (frameMs: number, gpuMs?: number) => void
+sample: (sample: Readonly<QualitySample>) => void
setCeiling: (level: QualityLevel | null) => void
setLimitation: (reason: string, active: boolean) => void
setMode: (mode: QualityMode) => void
@@ -8896,8 +8908,10 @@ waterWaves: number
## QualityReport — interface @experimental
```
+busyMs: number
drawCallBudget: number
frameMs: number
+gpuMs: number
level: QualityLevel
limitations: string[]
mode: QualityMode
@@ -8906,6 +8920,13 @@ renderScale: number
targetFps: 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): number
diff --git a/sdk/etc/wechat.api.md b/sdk/etc/wechat.api.md
index 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: () => number
getFixedTimestep: () => number
getFrameCosts: () => FrameCosts | null
getFrameScopes: () => ReadonlyMap<string, number> | null
-getFrameTiming: () => Readonly<{ seq: number; frameMs: number; }> | null
+getFrameTiming: () => Readonly<FrameTiming> | null
getPhaseTimings: () => ReadonlyMap<string, number> | null
getPlaySpeed: () => number
getPlugin: <T extends Plugin>(ctor: new (...args: any[]) => T) => T | undefined
@@ -4829,6 +4829,18 @@ vramBytes: number
wasmBytes: 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: boolean
profile: Readonly<QualityProfile>
renderScale: number
report: () => QualityReport
-sample: (frameMs: number, gpuMs?: number) => void
+sample: (sample: Readonly<QualitySample>) => void
setCeiling: (level: QualityLevel | null) => void
setLimitation: (reason: string, active: boolean) => void
setMode: (mode: QualityMode) => void
@@ -8606,8 +8618,10 @@ waterWaves: number
## QualityReport — interface @experimental
```
+busyMs: number
drawCallBudget: number
frameMs: number
+gpuMs: number
level: QualityLevel
limitations: string[]
mode: QualityMode
@@ -8616,6 +8630,13 @@ renderScale: number
targetFps: 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): number
diff --git a/sdk/src/app/app.ts b/sdk/src/app/app.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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: nu
check();
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.ts
index 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 Team
import { 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.hpp
index 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.cpp
index 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 them
timestamp_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 /*m
const 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* bindi
WGPUCommandEncoder 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* bindi
wgpuComputePassEncoderEnd(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.hpp
index 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.ts
index 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.mjs
index 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);
}