Skip to content

A fast 2D and 3D game engine — TypeScript SDK, C++/WebAssembly core, visual editor. Ship one project to web, desktop, WeChat MiniGames, playable ads, and native Android / iOS.

feat(render): the device counts every draw a frame asks of the GPU, every pass included, and a quality level holds a draw call budget against it

yhhf001348a9dad
diff --git a/desktop b/desktop
index 98b847df0..6522a4a66 160000
--- a/desktop
+++ b/desktop
@@ -1 +1 @@
-Subproject commit 98b847df0e354da9a5b52ea8417ffaedf31eb7bf
+Subproject commit 6522a4a66da1ae75b6ced024d5cb265513bfb7ee
diff --git a/docs/astro/src/content/docs/performance/profiling.mdx b/docs/astro/src/content/docs/performance/profiling.mdx
index 865a47b6c..d4be9608f 100644
--- a/docs/astro/src/content/docs/performance/profiling.mdx
+++ b/docs/astro/src/content/docs/performance/profiling.mdx
@@ -65,7 +65,9 @@ the render counters are the current frame's):
| `entityCount` | number | Live entities in the world. |
| `systemTimings` | `Map<string, number>` | CPU ms per system this frame, keyed by system name. |
| `phaseTimings` | `Map<string, number>` | CPU ms per schedule phase this frame. |
-| `drawCalls` | number | GPU draw calls issued this frame. |
+| `drawCalls` | number | Draws of the scene's and the overlay's lists after batching: what the frame capture lists. |
+| `gpuDraws` | number | Every draw the GPU was asked for this frame, every pass included: shadow maps, the depth pre-pass, reflections, motion vectors and post-processing as well as the scene. |
+| `drawCallBudget` | number | The draw call budget of the quality level in force; 0 when the app has no quality levels. |
| `triangles` | number | Triangles submitted this frame. |
| `sprites` | number | Sprites rendered this frame. |
| `text` | number | Text entities rendered this frame. |
@@ -108,7 +110,7 @@ addSystem(feedOverlay);
The render counters in `FrameStats` come from `Renderer.getStats()`, which you
can also call directly (no stats plugin needed) — it returns a `RenderStats`
-with the same seven fields: `drawCalls`, `triangles`, `sprites`, `text`,
+with the same fields: `drawCalls`, `gpuDraws`, `triangles`, `sprites`, `text`,
`skeletal`, `meshes`, `culled`.
```typescript
@@ -118,6 +120,28 @@ const rs = Renderer.getStats();
console.log(`${rs.drawCalls} draw calls, ${rs.triangles} triangles`);
```
+### Where the draws went
+
+`drawCalls` and `gpuDraws` are different numbers on purpose. On the `dusk-fort` example, a lit scene with a
+shadowing sun and a post-process volume, the lists draw 18 times and the GPU is asked for 52: 17 shadow casters
+and 17 post-processing and other passes the lists never see. A budget is held to `gpuDraws`.
+
+`drawBudgetReport` splits a frame's `gpuDraws` by pass, from the engine counters a frame stats report carries
+(`batch.draws`, `render.shadow.draws`, `render.prepass.draws`, `render.planar.draws`, `render.motion.draws`,
+`render.cover.draws`). What no pass claims is `other`, so the shares always add up to the GPU's count. The per-pass
+counters are published only while the frame profiler is on; without them, everything but the lists is `other`.
+
+```typescript
+import { drawBudgetReport } from 'esengine';
+
+const r = drawBudgetReport(gpuDraws, budget, counters);
+for (const p of r.passes) console.log(`${p.pass}: ${p.draws}`);
+if (r.over > 0) console.warn(`${r.over} draws over the budget of ${r.budget}`);
+```
+
+The editor's Profiler shows the same breakdown in its **Render** module. The budget itself is a setting of each
+[quality level](/docs/performance/quality-levels/).
+
## Building your own tooling
Two small utilities back the plugin and are exported for custom tooling:
diff --git a/docs/astro/src/content/docs/performance/quality-levels.mdx b/docs/astro/src/content/docs/performance/quality-levels.mdx
index f7ae3a86d..3a670efb4 100644
--- a/docs/astro/src/content/docs/performance/quality-levels.mdx
+++ b/docs/astro/src/content/docs/performance/quality-levels.mdx
@@ -29,7 +29,7 @@ to.
| Group | Settings |
|---|---|
-| Rendering | Render scale, Min render scale, Anti-aliasing (MSAA or Temporal), MSAA, Depth pre-pass, Detail distance, 2D rain shelter mask |
+| Rendering | Render scale, Min render scale, Anti-aliasing (MSAA or Temporal), MSAA, Depth pre-pass, Detail distance, Draw call budget, 2D rain shelter mask |
| Shadows | Atlas size, Cell size, Cascades, Distance, 2D soft-shadow samples |
| Reflections and particles | Planar reflection scale, max size and updates per second, Particle limit |
| Water | Water waves (1 to 4), Water ripple cells, and the Displacement, Mirror and Caustics switches. Shown once the level is not Off and the water module is in the build |
@@ -54,6 +54,14 @@ at Medium.
cheaper mesh at 60 m and is not drawn as itself past 150 m does so at 30 m and 75 m, and its far cards take over sooner.
Low keeps 0.5, Medium 0.8 and High all of it, so the same world draws a fraction of the triangles on a phone.
+**Draw call budget** is the most draws a frame at the level should ask of the GPU: 150 at Low, 400 at Medium and 1,500 at
+High. Every pass counts, not only the scene's own list: each shadow cascade draws its casters again, the depth pre-pass draws
+the opaque scene again, and post-processing adds a draw per pass. Nothing is held back to meet it. The Profiler's **Render**
+module shows the frame's GPU draws against the budget and splits them by pass, and the stats overlay turns the count red past
+it. A draw costs the CPU and the driver more than the GPU, and on a phone or in a mini game it is what a 3D scene runs out of
+first. To bring it down, see [Static batching](/docs/performance/static-batching/) for many different meshes and fewer shadow
+cascades for the shadow pass.
+
## Leaving effects out
Every post-process effect the engine has is in the list, ticked where the level runs it. An unticked effect is skipped
diff --git a/docs/astro/src/content/docs/zh-cn/performance/profiling.mdx b/docs/astro/src/content/docs/zh-cn/performance/profiling.mdx
index 116eb32c6..3cf3f2f20 100644
--- a/docs/astro/src/content/docs/zh-cn/performance/profiling.mdx
+++ b/docs/astro/src/content/docs/zh-cn/performance/profiling.mdx
@@ -62,7 +62,9 @@ addSystem(watchPerf);
| `entityCount` | number | 世界中的存活实体数。 |
| `systemTimings` | `Map<string, number>` | 本帧每个系统的 CPU 毫秒数,按系统名索引。 |
| `phaseTimings` | `Map<string, number>` | 本帧每个调度阶段的 CPU 毫秒数。 |
-| `drawCalls` | number | 本帧发出的 GPU draw call 数。 |
+| `drawCalls` | number | 场景和叠加层绘制列表合批后的 draw 数,也就是帧捕获列出的那些。 |
+| `gpuDraws` | number | 本帧向 GPU 发出的全部 draw,所有 pass 都算:除了场景,还有阴影贴图、深度预通道、反射、运动矢量和后处理。 |
+| `drawCallBudget` | number | 当前画质档位的 draw call 预算;应用没有画质档位时为 0。 |
| `triangles` | number | 本帧提交的三角形数。 |
| `sprites` | number | 本帧渲染的精灵数。 |
| `text` | number | 本帧渲染的文本实体数。 |
@@ -100,7 +102,7 @@ addSystem(feedOverlay);
## 渲染器计数 — `Renderer.getStats()`
`FrameStats` 里的渲染计数来自 `Renderer.getStats()`,也可以直接调用(不需要
-stats 插件)——它返回一个 `RenderStats`,同样是那七个字段:`drawCalls`、
+stats 插件)——它返回一个 `RenderStats`,字段相同:`drawCalls`、`gpuDraws`、
`triangles`、`sprites`、`text`、`skeletal`、`meshes`、`culled`。
```typescript
@@ -110,6 +112,22 @@ const rs = Renderer.getStats();
console.log(`${rs.drawCalls} draw calls, ${rs.triangles} triangles`);
```
+### draw 都去了哪里
+
+`drawCalls` 和 `gpuDraws` 是有意不同的两个数。在 `dusk-fort` 示例里(有投影的太阳和后处理体积的光照场景),绘制列表画了 18 次,GPU 却收到 52 次:17 次是阴影投影物,17 次是后处理和其他绘制列表看不到的 pass。预算比的是 `gpuDraws`。
+
+`drawBudgetReport` 根据帧统计报告里的引擎计数(`batch.draws`、`render.shadow.draws`、`render.prepass.draws`、`render.planar.draws`、`render.motion.draws`、`render.cover.draws`),把一帧的 `gpuDraws` 按 pass 拆开。没有被任何 pass 认领的算作 `other`,所以各部分加起来总是等于 GPU 的数。各 pass 的计数只在帧分析器开着时才发布;没有时,除了绘制列表都算在 `other` 里。
+
+```typescript
+import { drawBudgetReport } from 'esengine';
+
+const r = drawBudgetReport(gpuDraws, budget, counters);
+for (const p of r.passes) console.log(`${p.pass}: ${p.draws}`);
+if (r.over > 0) console.warn(`超出预算 ${r.budget} 共 ${r.over}`);
+```
+
+编辑器 Profiler 的**渲染**模块显示同样的拆分。预算本身是每个[画质档位](/docs/zh-cn/performance/quality-levels/)的设置。
+
## 自建工具
插件背后有两个小工具类,均已导出供自定义工具使用:
diff --git a/docs/astro/src/content/docs/zh-cn/performance/quality-levels.mdx b/docs/astro/src/content/docs/zh-cn/performance/quality-levels.mdx
index faf3a61df..abd47a345 100644
--- a/docs/astro/src/content/docs/zh-cn/performance/quality-levels.mdx
+++ b/docs/astro/src/content/docs/zh-cn/performance/quality-levels.mdx
@@ -27,7 +27,7 @@ import { Aside } from '@astrojs/starlight/components';
| 分组 | 设置 |
|---|---|
-| 渲染 | 渲染比例、最小渲染比例、抗锯齿方式(MSAA 或时间性)、MSAA、深度预通道、细节距离、2D 雨遮罩尺寸 |
+| 渲染 | 渲染比例、最小渲染比例、抗锯齿方式(MSAA 或时间性)、MSAA、深度预通道、细节距离、Draw call 预算、2D 雨遮罩尺寸 |
| 阴影 | 图集尺寸、单元尺寸、级联数、距离、2D 软阴影采样数 |
| 反射与粒子 | 平面反射的比例、最大尺寸和每秒更新次数,粒子上限 |
| 水体 | 水体波数(1 到 4)、水体涟漪格数,以及位移、镜面、焦散三个开关。档位不是关闭、且构建里带水体模块时才显示 |
@@ -44,6 +44,8 @@ import { Aside } from '@astrojs/starlight/components';
**细节距离**是一档里放置的植物保留多少比例的距离:0.5 时,原本 60 米换成更省网格、150 米外不再画本体的树,会在 30 米和 75 米处这样做,远景卡片也更早接手。低档保留 0.5、中档 0.8、高档全部,所以同一个世界在手机上画的三角形只有一小部分。
+**Draw call 预算**是这一档每帧最多应向 GPU 发出的 draw 数:低档 150、中档 400、高档 1500。所有 pass 都算,不只是场景自己的绘制列表:每个阴影级联都要把投影物再画一次,深度预通道要把不透明场景再画一次,后处理每个 pass 也要一次 draw。不会为了达标而少画什么。Profiler 的**渲染**模块显示这一帧的 GPU draw 数和预算,并按 pass 拆开;统计浮层在超出时把数字标红。一次 draw 花在 CPU 和驱动上的比花在 GPU 上的多,在手机和小游戏里,3D 场景最先用完的就是它。要降下来,不同网格很多时看[静态合并](/docs/zh-cn/performance/static-batching/),阴影那部分则减少级联数。
+
## 去掉一些效果
引擎有的每个后处理效果都在列表里,该档位运行的打勾。没勾选的效果在这个档位被跳过,不管相机的体积是否要求它——而且是整个跳过:
diff --git a/sdk/etc/index.api.md b/sdk/etc/index.api.md
index d5f27abd6..c234b213d 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 · 161 beta · 1998 experimental · 3 deprecated
+Symbols: 115 public · 161 beta · 2002 experimental · 3 deprecated
## ABI_LAYOUT_HASH — const @experimental
```
@@ -3600,6 +3600,14 @@ textureRotated: (position: Vec2, size: Vec2, rotation: number, textureHandle: nu
withDepthState: (state: { test: boolean; write: boolean; }, draw: () => void) => boolean
```
+## DrawBudgetReport — interface @experimental
+```
+budget: number
+draws: number
+over: number
+passes: DrawPassShare[]
+```
+
## DrawCallInfo — interface @experimental
```
blendMode: number
@@ -3641,6 +3649,17 @@ viewProjection: Float32Array<ArrayBufferLike>
width: number
```
+## DrawPass — type @experimental
+```
+'lists' | 'shadow' | 'prepass' | 'reflection' | 'motion' | 'cover' | 'other'
+```
+
+## DrawPassShare — interface @experimental
+```
+draws: number
+pass: DrawPass
+```
+
## DrawRank — interface @experimental
```
groupInner: number | null | undefined
@@ -4573,10 +4592,12 @@ systemTimings: Map<string, number>
## FrameStats — interface @experimental
```
culled: number
+drawCallBudget: number
drawCalls: number
entityCount: number
fps: number
frameTimeMs: number
+gpuDraws: number
meshes: number
phaseTimings: Map<string, number>
skeletal: number
@@ -4597,6 +4618,7 @@ cppScopes: Record<string, number>
drawCalls: number
entities: number
frameMs: number | undefined
+gpuDraws: number | undefined
gpuMs: number
gpuScopes: Record<string, number>
phases: Record<string, number>
@@ -7997,6 +8019,7 @@ static prototype: QualityController
antialiasing: "msaa" | "temporal"
depthPrepass: boolean
detailScale: number
+drawCallBudget: number
minRenderScale: number
msaaSamples: 2 | 1 | 4 | 8
particleLimit: number
@@ -8022,6 +8045,7 @@ waterWaves: number
## QualityReport — interface @experimental
```
+drawCallBudget: number
frameMs: number
level: QualityLevel
limitations: string[]
@@ -8413,6 +8437,7 @@ Transparent = 2
```
culled: number
drawCalls: number
+gpuDraws: number
meshes: number
skeletal: number
sprites: number
@@ -14425,6 +14450,11 @@ DragPlugin
(map: BasinMap, x: number, z: number): { x: number; z: number; y: number; }[]
```
+## drawBudgetReport — function @experimental
+```
+(gpuDraws: number, budget: number, counters: Readonly<Record<string, number>>, listDraws?: number): DrawBudgetReport
+```
+
## drawPhysics3DDebug — function @experimental
```
(app: App, contacts?: readonly Contact3D[]): void
diff --git a/sdk/etc/index.native.api.md b/sdk/etc/index.native.api.md
index 1c87c2a1e..04d6527ff 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 · 166 beta · 2017 experimental · 3 deprecated
+Symbols: 115 public · 166 beta · 2021 experimental · 3 deprecated
## ABI_LAYOUT_HASH — const @experimental
```
@@ -3608,6 +3608,14 @@ textureRotated: (position: Vec2, size: Vec2, rotation: number, textureHandle: nu
withDepthState: (state: { test: boolean; write: boolean; }, draw: () => void) => boolean
```
+## DrawBudgetReport — interface @experimental
+```
+budget: number
+draws: number
+over: number
+passes: DrawPassShare[]
+```
+
## DrawCallInfo — interface @experimental
```
blendMode: number
@@ -3649,6 +3657,17 @@ viewProjection: Float32Array<ArrayBufferLike>
width: number
```
+## DrawPass — type @experimental
+```
+'lists' | 'shadow' | 'prepass' | 'reflection' | 'motion' | 'cover' | 'other'
+```
+
+## DrawPassShare — interface @experimental
+```
+draws: number
+pass: DrawPass
+```
+
## DrawRank — interface @experimental
```
groupInner: number | null | undefined
@@ -4581,10 +4600,12 @@ systemTimings: Map<string, number>
## FrameStats — interface @experimental
```
culled: number
+drawCallBudget: number
drawCalls: number
entityCount: number
fps: number
frameTimeMs: number
+gpuDraws: number
meshes: number
phaseTimings: Map<string, number>
skeletal: number
@@ -4605,6 +4626,7 @@ cppScopes: Record<string, number>
drawCalls: number
entities: number
frameMs: number | undefined
+gpuDraws: number | undefined
gpuMs: number
gpuScopes: Record<string, number>
phases: Record<string, number>
@@ -8200,6 +8222,7 @@ static prototype: QualityController
antialiasing: "msaa" | "temporal"
depthPrepass: boolean
detailScale: number
+drawCallBudget: number
minRenderScale: number
msaaSamples: 2 | 1 | 4 | 8
particleLimit: number
@@ -8225,6 +8248,7 @@ waterWaves: number
## QualityReport — interface @experimental
```
+drawCallBudget: number
frameMs: number
level: QualityLevel
limitations: string[]
@@ -8626,6 +8650,7 @@ Transparent = 2
```
culled: number
drawCalls: number
+gpuDraws: number
meshes: number
skeletal: number
sprites: number
@@ -14678,6 +14703,11 @@ DragPlugin
(map: BasinMap, x: number, z: number): { x: number; z: number; y: number; }[]
```
+## drawBudgetReport — function @experimental
+```
+(gpuDraws: number, budget: number, counters: Readonly<Record<string, number>>, listDraws?: number): DrawBudgetReport
+```
+
## drawPhysics3DDebug — function @experimental
```
(app: App, contacts?: readonly Contact3D[]): void
diff --git a/sdk/etc/index.node.api.md b/sdk/etc/index.node.api.md
index 8b8922598..a5a9e04d7 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 · 163 beta · 1997 experimental · 3 deprecated
+Symbols: 115 public · 163 beta · 2001 experimental · 3 deprecated
## ANCHOR_AXES — const @experimental
```
@@ -3595,6 +3595,14 @@ textureRotated: (position: Vec2, size: Vec2, rotation: number, textureHandle: nu
withDepthState: (state: { test: boolean; write: boolean; }, draw: () => void) => boolean
```
+## DrawBudgetReport — interface @experimental
+```
+budget: number
+draws: number
+over: number
+passes: DrawPassShare[]
+```
+
## DrawCallInfo — interface @experimental
```
blendMode: number
@@ -3636,6 +3644,17 @@ viewProjection: Float32Array<ArrayBufferLike>
width: number
```
+## DrawPass — type @experimental
+```
+'lists' | 'shadow' | 'prepass' | 'reflection' | 'motion' | 'cover' | 'other'
+```
+
+## DrawPassShare — interface @experimental
+```
+draws: number
+pass: DrawPass
+```
+
## DrawRank — interface @experimental
```
groupInner: number | null | undefined
@@ -4568,10 +4587,12 @@ systemTimings: Map<string, number>
## FrameStats — interface @experimental
```
culled: number
+drawCallBudget: number
drawCalls: number
entityCount: number
fps: number
frameTimeMs: number
+gpuDraws: number
meshes: number
phaseTimings: Map<string, number>
skeletal: number
@@ -4592,6 +4613,7 @@ cppScopes: Record<string, number>
drawCalls: number
entities: number
frameMs: number | undefined
+gpuDraws: number | undefined
gpuMs: number
gpuScopes: Record<string, number>
phases: Record<string, number>
@@ -7992,6 +8014,7 @@ static prototype: QualityController
antialiasing: "msaa" | "temporal"
depthPrepass: boolean
detailScale: number
+drawCallBudget: number
minRenderScale: number
msaaSamples: 2 | 1 | 4 | 8
particleLimit: number
@@ -8017,6 +8040,7 @@ waterWaves: number
## QualityReport — interface @experimental
```
+drawCallBudget: number
frameMs: number
level: QualityLevel
limitations: string[]
@@ -8408,6 +8432,7 @@ Transparent = 2
```
culled: number
drawCalls: number
+gpuDraws: number
meshes: number
skeletal: number
sprites: number
@@ -14420,6 +14445,11 @@ DragPlugin
(map: BasinMap, x: number, z: number): { x: number; z: number; y: number; }[]
```
+## drawBudgetReport — function @experimental
+```
+(gpuDraws: number, budget: number, counters: Readonly<Record<string, number>>, listDraws?: number): DrawBudgetReport
+```
+
## drawPhysics3DDebug — function @experimental
```
(app: App, contacts?: readonly Contact3D[]): void
diff --git a/sdk/etc/minigame.api.md b/sdk/etc/minigame.api.md
index 11b64a616..1cc304786 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 · 161 beta · 2019 experimental · 3 deprecated
+Symbols: 115 public · 161 beta · 2023 experimental · 3 deprecated
## ANCHOR_AXES — const @experimental
```
@@ -3595,6 +3595,14 @@ textureRotated: (position: Vec2, size: Vec2, rotation: number, textureHandle: nu
withDepthState: (state: { test: boolean; write: boolean; }, draw: () => void) => boolean
```
+## DrawBudgetReport — interface @experimental
+```
+budget: number
+draws: number
+over: number
+passes: DrawPassShare[]
+```
+
## DrawCallInfo — interface @experimental
```
blendMode: number
@@ -3636,6 +3644,17 @@ viewProjection: Float32Array<ArrayBufferLike>
width: number
```
+## DrawPass — type @experimental
+```
+'lists' | 'shadow' | 'prepass' | 'reflection' | 'motion' | 'cover' | 'other'
+```
+
+## DrawPassShare — interface @experimental
+```
+draws: number
+pass: DrawPass
+```
+
## DrawRank — interface @experimental
```
groupInner: number | null | undefined
@@ -4568,10 +4587,12 @@ systemTimings: Map<string, number>
## FrameStats — interface @experimental
```
culled: number
+drawCallBudget: number
drawCalls: number
entityCount: number
fps: number
frameTimeMs: number
+gpuDraws: number
meshes: number
phaseTimings: Map<string, number>
skeletal: number
@@ -4592,6 +4613,7 @@ cppScopes: Record<string, number>
drawCalls: number
entities: number
frameMs: number | undefined
+gpuDraws: number | undefined
gpuMs: number
gpuScopes: Record<string, number>
phases: Record<string, number>
@@ -8287,6 +8309,7 @@ static prototype: QualityController
antialiasing: "msaa" | "temporal"
depthPrepass: boolean
detailScale: number
+drawCallBudget: number
minRenderScale: number
msaaSamples: 2 | 1 | 4 | 8
particleLimit: number
@@ -8312,6 +8335,7 @@ waterWaves: number
## QualityReport — interface @experimental
```
+drawCallBudget: number
frameMs: number
level: QualityLevel
limitations: string[]
@@ -8703,6 +8727,7 @@ Transparent = 2
```
culled: number
drawCalls: number
+gpuDraws: number
meshes: number
skeletal: number
sprites: number
@@ -14726,6 +14751,11 @@ DragPlugin
(map: BasinMap, x: number, z: number): { x: number; z: number; y: number; }[]
```
+## drawBudgetReport — function @experimental
+```
+(gpuDraws: number, budget: number, counters: Readonly<Record<string, number>>, listDraws?: number): DrawBudgetReport
+```
+
## drawPhysics3DDebug — function @experimental
```
(app: App, contacts?: readonly Contact3D[]): void
diff --git a/sdk/etc/wasm.api.md b/sdk/etc/wasm.api.md
index d16ee4cbd..f604560e3 100644
--- a/sdk/etc/wasm.api.md
+++ b/sdk/etc/wasm.api.md
@@ -482,6 +482,7 @@ renderer_getCapturedTextures: () => number
renderer_getCulled: () => number
renderer_getDrawCalls: () => number
renderer_getEstimatedGpuBytes: (() => number) | undefined
+renderer_getGpuDrawCalls: (() => number) | undefined
renderer_getGpuTimeMs: (() => number) | undefined
renderer_getLiveObjects: (() => GfxLiveObjects | null) | undefined
renderer_getMeshes: () => number
diff --git a/sdk/etc/wechat.api.md b/sdk/etc/wechat.api.md
index 9d2367b27..04ed520da 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 · 161 beta · 2010 experimental · 3 deprecated
+Symbols: 115 public · 161 beta · 2014 experimental · 3 deprecated
## ANCHOR_AXES — const @experimental
```
@@ -3595,6 +3595,14 @@ textureRotated: (position: Vec2, size: Vec2, rotation: number, textureHandle: nu
withDepthState: (state: { test: boolean; write: boolean; }, draw: () => void) => boolean
```
+## DrawBudgetReport — interface @experimental
+```
+budget: number
+draws: number
+over: number
+passes: DrawPassShare[]
+```
+
## DrawCallInfo — interface @experimental
```
blendMode: number
@@ -3636,6 +3644,17 @@ viewProjection: Float32Array<ArrayBufferLike>
width: number
```
+## DrawPass — type @experimental
+```
+'lists' | 'shadow' | 'prepass' | 'reflection' | 'motion' | 'cover' | 'other'
+```
+
+## DrawPassShare — interface @experimental
+```
+draws: number
+pass: DrawPass
+```
+
## DrawRank — interface @experimental
```
groupInner: number | null | undefined
@@ -4568,10 +4587,12 @@ systemTimings: Map<string, number>
## FrameStats — interface @experimental
```
culled: number
+drawCallBudget: number
drawCalls: number
entityCount: number
fps: number
frameTimeMs: number
+gpuDraws: number
meshes: number
phaseTimings: Map<string, number>
skeletal: number
@@ -4592,6 +4613,7 @@ cppScopes: Record<string, number>
drawCalls: number
entities: number
frameMs: number | undefined
+gpuDraws: number | undefined
gpuMs: number
gpuScopes: Record<string, number>
phases: Record<string, number>
@@ -7999,6 +8021,7 @@ static prototype: QualityController
antialiasing: "msaa" | "temporal"
depthPrepass: boolean
detailScale: number
+drawCallBudget: number
minRenderScale: number
msaaSamples: 2 | 1 | 4 | 8
particleLimit: number
@@ -8024,6 +8047,7 @@ waterWaves: number
## QualityReport — interface @experimental
```
+drawCallBudget: number
frameMs: number
level: QualityLevel
limitations: string[]
@@ -8415,6 +8439,7 @@ Transparent = 2
```
culled: number
drawCalls: number
+gpuDraws: number
meshes: number
skeletal: number
sprites: number
@@ -14452,6 +14477,11 @@ DragPlugin
(map: BasinMap, x: number, z: number): { x: number; z: number; y: number; }[]
```
+## drawBudgetReport — function @experimental
+```
+(gpuDraws: number, budget: number, counters: Readonly<Record<string, number>>, listDraws?: number): DrawBudgetReport
+```
+
## drawPhysics3DDebug — function @experimental
```
(app: App, contacts?: readonly Contact3D[]): void
diff --git a/sdk/src/core-content.ts b/sdk/src/core-content.ts
index 4de78b580..09249ad9d 100644
--- a/sdk/src/core-content.ts
+++ b/sdk/src/core-content.ts
@@ -857,6 +857,7 @@ export {
mergeMeshes, planStaticBatches, STATIC_BATCH_DEFAULTS,
type StaticBatchGroup, type StaticBatchLimits, type StaticBatchRefusal, type StaticBatchReport,
} from './render/staticBatch';
+export { drawBudgetReport, type DrawBudgetReport, type DrawPass, type DrawPassShare } from './render/drawBudget';
// =============================================================================
// Tilemap
diff --git a/sdk/src/ecs/bridge/nativeBindings.ts b/sdk/src/ecs/bridge/nativeBindings.ts
index 04dbb4da1..d204f5f7b 100644
--- a/sdk/src/ecs/bridge/nativeBindings.ts
+++ b/sdk/src/ecs/bridge/nativeBindings.ts
@@ -153,6 +153,7 @@ export const RENDERER_BINDINGS = {
* module exposes under the same names, so the two paths report identically. */
export const RENDERER_STATS_BINDINGS = {
drawCalls: 'es_renderer_getDrawCalls',
+ gpuDraws: 'es_renderer_getGpuDrawCalls',
triangles: 'es_renderer_getTriangles',
sprites: 'es_renderer_getSprites',
text: 'es_renderer_getText',
diff --git a/sdk/src/ecs/bridge/nativeEngineApi.generated.ts b/sdk/src/ecs/bridge/nativeEngineApi.generated.ts
index ece62d8ea..eb4a3d3a1 100644
--- a/sdk/src/ecs/bridge/nativeEngineApi.generated.ts
+++ b/sdk/src/ecs/bridge/nativeEngineApi.generated.ts
@@ -173,6 +173,7 @@ export interface NativeEngineApi {
renderer_getCulled?(): number;
renderer_getDrawCalls?(): number;
renderer_getEstimatedGpuBytes?(): number;
+ renderer_getGpuDrawCalls?(): number;
renderer_getGpuTimeMs?(): number;
renderer_getMeshes?(): number;
renderer_getPendingShaders?(): number;
@@ -511,6 +512,7 @@ export function createNativeEngineApi(
bind('renderer_getCulled', 'es_renderer_getCulled', false);
bind('renderer_getDrawCalls', 'es_renderer_getDrawCalls', false);
bind('renderer_getEstimatedGpuBytes', 'es_renderer_getEstimatedGpuBytes', false);
+ bind('renderer_getGpuDrawCalls', 'es_renderer_getGpuDrawCalls', false);
bind('renderer_getGpuTimeMs', 'es_renderer_getGpuTimeMs', false);
bind('renderer_getMeshes', 'es_renderer_getMeshes', false);
bind('renderer_getPendingShaders', 'es_renderer_getPendingShaders', false);
diff --git a/sdk/src/ecs/bridge/nativeRenderer.ts b/sdk/src/ecs/bridge/nativeRenderer.ts
index fbe6a0d5f..cdb352504 100644
--- a/sdk/src/ecs/bridge/nativeRenderer.ts
+++ b/sdk/src/ecs/bridge/nativeRenderer.ts
@@ -209,6 +209,7 @@ export function createNativeRendererBackend(
};
return {
drawCalls: read(RENDERER_STATS_BINDINGS.drawCalls),
+ gpuDraws: read(RENDERER_STATS_BINDINGS.gpuDraws),
triangles: read(RENDERER_STATS_BINDINGS.triangles),
sprites: read(RENDERER_STATS_BINDINGS.sprites),
text: read(RENDERER_STATS_BINDINGS.text),
diff --git a/sdk/src/render/drawBudget.ts b/sdk/src/render/drawBudget.ts
new file mode 100644
index 000000000..836b0a682
--- /dev/null
+++ b/sdk/src/render/drawBudget.ts
@@ -0,0 +1,73 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
+/**
+ * @file drawBudget.ts
+ * @brief Where a frame's draws went, pass by pass, held against the level's draw call budget.
+ *
+ * @details The device counts every draw it issues (`render.gpu.draws`); the scene's and the overlay's
+ * lists count theirs after batching (`batch.draws`), and the passes that draw the scene again
+ * count their own (shadow maps, the depth prepass, planar reflections, motion vectors, the
+ * cover pass). What none of them claims — post-processing, a blit, the editor's grid — is
+ * `other`, so the shares always add up to the device's total and a pass nobody counts is still
+ * seen. The per-pass counters are published only while the frame profiler is on; without them
+ * everything but the lists is `other`.
+ */
+
+/** A part of the frame, by what drew it. @experimental */
+export type DrawPass = 'lists' | 'shadow' | 'prepass' | 'reflection' | 'motion' | 'cover' | 'other';
+
+/** @experimental */
+export interface DrawPassShare {
+ pass: DrawPass;
+ draws: number;
+}
+
+/** @experimental */
+export interface DrawBudgetReport {
+ /** Every draw the GPU was asked for. */
+ draws: number;
+ /** The budget it is held to; 0 is none. */
+ budget: number;
+ /** By how many it went past the budget; 0 within it. */
+ over: number;
+ /** The draws by pass, largest first, the empty ones left out. */
+ passes: DrawPassShare[];
+}
+
+const COUNTERS: readonly [Exclude<DrawPass, 'other'>, string][] = [
+ ['lists', 'batch.draws'],
+ ['shadow', 'render.shadow.draws'],
+ ['prepass', 'render.prepass.draws'],
+ ['reflection', 'render.planar.draws'],
+ ['motion', 'render.motion.draws'],
+ ['cover', 'render.cover.draws'],
+];
+
+/**
+ * A frame's draws by pass. @p gpuDraws is the device's own count; @p counters the frame's engine
+ * counters by name (a frame stats report's `cppCounters`), and @p listDraws the lists' count to use
+ * when the counters do not carry it (they are absent while the profiler is off).
+ *
+ * @experimental
+ */
+export function drawBudgetReport(
+ gpuDraws: number, budget: number, counters: Readonly<Record<string, number>>, listDraws = 0,
+): DrawBudgetReport {
+ const passes: DrawPassShare[] = [];
+ let claimed = 0;
+ for (const [pass, name] of COUNTERS) {
+ const value = counters[name] ?? (pass === 'lists' ? listDraws : 0);
+ const draws = Math.max(0, Math.round(value));
+ if (draws === 0) continue;
+ passes.push({ pass, draws });
+ claimed += draws;
+ }
+ // The device's count is the truth; a share a pass claims past it (a counter from a frame other than the
+ // one counted) is not taken from `other`, which never goes below nothing.
+ const total = Math.max(0, Math.round(gpuDraws));
+ const other = total - claimed;
+ if (other > 0) passes.push({ pass: 'other', draws: other });
+ passes.sort((a, b) => b.draws - a.draws);
+ const limit = Math.max(0, Math.round(budget));
+ return { draws: total, budget: limit, over: limit > 0 ? Math.max(0, total - limit) : 0, passes };
+}
diff --git a/sdk/src/render/quality.ts b/sdk/src/render/quality.ts
index cbf1f7b43..5f0c78c2a 100644
--- a/sdk/src/render/quality.ts
+++ b/sdk/src/render/quality.ts
@@ -78,6 +78,12 @@ export interface QualityProfile {
* is that many silhouettes added up. Fewer is cheaper and shows the edge as bands; sixteen is where the bands stop reading as separate shadows.
*/
shadowSoftSamples: number;
+ /**
+ * The most draws a frame at this level should ask of the GPU, every pass counted (shadows, prepass, reflections and post-processing with the
+ * scene). Nothing is held back to meet it: the profiler and the stats overlay show a frame over it, and the frame debugger says where the draws
+ * went. Draw calls cost the CPU and the driver more than the GPU, and on a phone or in a mini game they are what a 3D scene runs out of first.
+ */
+ drawCallBudget: number;
}
export interface DeviceQualityRule {
@@ -131,7 +137,7 @@ const PROFILES: Record<QualityLevel, QualityProfile> = {
shadowDistance: 0, detailScale: 0.5, particleLimit: 1000, postProcess: true, ssao: false,
waterWaves: 2, waterRippleCells: 32, waterDisplacement: false, waterMirror: false, waterCaustics: false,
skipEffects: ['ssr', 'taa', 'depthOfField', 'lightShafts', 'motionBlur', 'lensFlare', 'gtao', 'subsurface', 'voxelGI'],
- shelterMaskSize: 256, shadowSoftSamples: 8,
+ shelterMaskSize: 256, shadowSoftSamples: 8, drawCallBudget: 150,
},
medium: {
renderScale: 1, minRenderScale: 0.65, msaaSamples: 2, antialiasing: 'temporal',
@@ -140,7 +146,7 @@ const PROFILES: Record<QualityLevel, QualityProfile> = {
shadowDistance: 0, detailScale: 0.8, particleLimit: 5000, postProcess: true, ssao: true,
waterWaves: 3, waterRippleCells: 64, waterDisplacement: true, waterMirror: true, waterCaustics: true,
skipEffects: ['ssr', 'depthOfField'],
- shelterMaskSize: 512, shadowSoftSamples: 12,
+ shelterMaskSize: 512, shadowSoftSamples: 12, drawCallBudget: 400,
},
high: {
renderScale: 1, minRenderScale: 0.75, msaaSamples: 4, antialiasing: 'msaa',
@@ -151,7 +157,7 @@ const PROFILES: Record<QualityLevel, QualityProfile> = {
shadowDistance: 0, detailScale: 1, particleLimit: 20000, postProcess: true, ssao: true,
waterWaves: 4, waterRippleCells: 128, waterDisplacement: true, waterMirror: true, waterCaustics: true,
skipEffects: [],
- shelterMaskSize: 1024, shadowSoftSamples: 16,
+ shelterMaskSize: 1024, shadowSoftSamples: 16, drawCallBudget: 1500,
},
};
@@ -256,6 +262,7 @@ function resolveProfile(level: QualityLevel, value: unknown): QualityProfile {
: base.skipEffects,
shelterMaskSize: Math.round(finite(r.shelterMaskSize, base.shelterMaskSize, 64, 2048)),
shadowSoftSamples: Math.round(finite(r.shadowSoftSamples, base.shadowSoftSamples, 1, 32)),
+ drawCallBudget: Math.round(finite(r.drawCallBudget, base.drawCallBudget, 1, 100000)),
};
}
@@ -288,6 +295,8 @@ export interface QualityReport {
frameMs: number;
reason: string;
limitations: string[];
+ /** The level's draw call budget (see `QualityProfile.drawCallBudget`). */
+ drawCallBudget: number;
}
/** @experimental Per-app policy; authored scene components remain unchanged. */
@@ -388,6 +397,7 @@ export class QualityController {
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_],
+ drawCallBudget: this.profile_.drawCallBudget,
};
}
}
diff --git a/sdk/src/render/renderer.ts b/sdk/src/render/renderer.ts
index e87ce6b45..5628981d5 100644
--- a/sdk/src/render/renderer.ts
+++ b/sdk/src/render/renderer.ts
@@ -21,7 +21,13 @@ export enum RenderStage {
export type RenderTargetHandle = number;
export interface RenderStats {
+ /** The draws of the scene's and the overlay's lists, after batching: what the draw calls a frame debugger lists add up to. */
drawCalls: number;
+ /**
+ * Every draw the GPU was asked for, every pass included: shadow maps, the depth prepass, reflections, motion vectors and post-processing as well as
+ * the scene. This is the number a draw call budget is held to.
+ */
+ gpuDraws: number;
triangles: number;
sprites: number;
text: number;
@@ -158,7 +164,7 @@ export interface LodDecision {
screenSize: number;
}
-const NO_STATS: RenderStats = { drawCalls: 0, triangles: 0, sprites: 0, text: 0, skeletal: 0, meshes: 0, culled: 0 };
+const NO_STATS: RenderStats = { drawCalls: 0, gpuDraws: 0, triangles: 0, sprites: 0, text: 0, skeletal: 0, meshes: 0, culled: 0 };
const bridge = new CoreApiBridge('renderer');
let module: ESEngineModule | null = null;
@@ -292,6 +298,7 @@ function wasmBackend(m: ESEngineModule): RendererBackend {
},
getStats: () => ({
drawCalls: m.renderer_getDrawCalls(),
+ gpuDraws: m.renderer_getGpuDrawCalls?.() ?? 0,
triangles: m.renderer_getTriangles(),
sprites: m.renderer_getSprites(),
text: m.renderer_getText(),
diff --git a/sdk/src/runtime/frameStats.ts b/sdk/src/runtime/frameStats.ts
index 73626594a..6acf56895 100644
--- a/sdk/src/runtime/frameStats.ts
+++ b/sdk/src/runtime/frameStats.ts
@@ -20,6 +20,8 @@ export interface FrameStatsReport {
* profile tree is folded from. Null while the app has stats off. */
costs: FrameCosts | null;
drawCalls: number;
+ /** Every draw the GPU was asked for, every pass included; what `quality.drawCallBudget` is held to. */
+ gpuDraws?: number;
triangles: number;
sprites: number;
entities: number;
@@ -56,6 +58,7 @@ export function frameStatsReport(app: App): FrameStatsReport {
phases: Object.fromEntries(app.getPhaseTimings() ?? []),
costs: app.getFrameCosts(),
drawCalls: m?.renderer_getDrawCalls?.() ?? 0,
+ gpuDraws: m?.renderer_getGpuDrawCalls?.() ?? 0,
triangles: m?.renderer_getTriangles?.() ?? 0,
sprites: m?.renderer_getSprites?.() ?? 0,
entities: app.world.getAllEntities().length,
diff --git a/sdk/src/stats-overlay.ts b/sdk/src/stats-overlay.ts
index c0e9111c1..1774cd418 100644
--- a/sdk/src/stats-overlay.ts
+++ b/sdk/src/stats-overlay.ts
@@ -118,6 +118,8 @@ export class StatsOverlay {
sections.push(
'<div style="color:#8c8c8c;border-bottom:1px solid rgba(60,60,60,0.8);padding-bottom:3px;margin-bottom:3px;margin-top:4px">Rendering</div>' +
`<div>DC: <span style="color:#d19a66">${stats.drawCalls}</span>` +
+ ` GPU: <span style="color:${stats.drawCallBudget > 0 && stats.gpuDraws > stats.drawCallBudget ? '#e06c75' : '#d19a66'}">${stats.gpuDraws}${stats.drawCallBudget > 0 ? ` / ${stats.drawCallBudget}` : ''}</span></div>` +
+ `<div>` +
` Tri: <span style="color:#d19a66">${stats.triangles}</span></div>` +
`<div>Sprites: <span style="color:#d19a66">${stats.sprites}</span>` +
` Culled: <span style="color:#d19a66">${stats.culled}</span></div>`
diff --git a/sdk/src/stats.ts b/sdk/src/stats.ts
index 6d4066074..6d390c587 100644
--- a/sdk/src/stats.ts
+++ b/sdk/src/stats.ts
@@ -5,6 +5,7 @@ import { defineResource, Res, Time } from './ecs/resource';
import { defineSystem, GetWorld, Schedule } from './ecs/system';
import type { App, Plugin } from './app/app';
import { StatsOverlay, type StatsPosition } from './stats-overlay';
+import { Quality } from './render/qualityRuntime';
export interface FrameStats {
fps: number;
@@ -13,6 +14,10 @@ export interface FrameStats {
systemTimings: Map<string, number>;
phaseTimings: Map<string, number>;
drawCalls: number;
+ /** Every draw the GPU was asked for, every pass included (see `RenderStats.gpuDraws`). */
+ gpuDraws: number;
+ /** The draw call budget of the quality level in force; 0 when the app has no quality controller. */
+ drawCallBudget: number;
triangles: number;
sprites: number;
text: number;
@@ -29,6 +34,8 @@ export function defaultFrameStats(): FrameStats {
systemTimings: new Map(),
phaseTimings: new Map(),
drawCalls: 0,
+ gpuDraws: 0,
+ drawCallBudget: 0,
triangles: 0,
sprites: 0,
text: 0,
@@ -203,6 +210,8 @@ export class StatsPlugin implements Plugin {
const renderStats = Renderer.getStats();
stats.drawCalls = renderStats.drawCalls;
+ stats.gpuDraws = renderStats.gpuDraws;
+ stats.drawCallBudget = app.hasResource(Quality) ? app.getResource(Quality)?.profile.drawCallBudget ?? 0 : 0;
stats.triangles = renderStats.triangles;
stats.sprites = renderStats.sprites;
stats.text = renderStats.text;
diff --git a/sdk/src/wasm.ts b/sdk/src/wasm.ts
index 960d1c893..565b96182 100644
--- a/sdk/src/wasm.ts
+++ b/sdk/src/wasm.ts
@@ -684,6 +684,8 @@ export interface ESEngineModule {
*/
es_getMallocBytes?(): number;
renderer_getDrawCalls(): number;
+ /** Every draw the GPU was asked for in the last frame, every pass included. Optional: older engine builds do not carry it. */
+ renderer_getGpuDrawCalls?(): number;
/**
* GPU objects the device has created and not destroyed, for the resource
* census. Null when no device is initialized — a census must record those
diff --git a/sdk/tests/draw-budget.test.ts b/sdk/tests/draw-budget.test.ts
new file mode 100644
index 000000000..6d82ccbf4
--- /dev/null
+++ b/sdk/tests/draw-budget.test.ts
@@ -0,0 +1,41 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
+import { describe, expect, it } from 'vitest';
+import { drawBudgetReport } from '../src/render/drawBudget';
+import { defaultQualityProfile, parseQualityConfig, resolveQualityProfile } from '../src/render/quality';
+
+describe('a frame\'s draws by pass', () => {
+ it('gives each counted pass its share and leaves the rest to other, so the shares add up to the device', () => {
+ const r = drawBudgetReport(120, 150, { 'batch.draws': 40, 'render.shadow.draws': 50, 'render.prepass.draws': 20 });
+ expect(r.passes).toEqual([
+ { pass: 'shadow', draws: 50 }, { pass: 'lists', draws: 40 }, { pass: 'prepass', draws: 20 }, { pass: 'other', draws: 10 },
+ ]);
+ expect(r.passes.reduce((n, p) => n + p.draws, 0)).toBe(120);
+ expect(r.over).toBe(0);
+ });
+
+ it('says by how much a frame went past its budget, and nothing when there is no budget', () => {
+ expect(drawBudgetReport(180, 150, {}).over).toBe(30);
+ expect(drawBudgetReport(180, 0, {}).over).toBe(0);
+ });
+
+ it('takes the lists\' own count while the profiler publishes no counters', () => {
+ const r = drawBudgetReport(30, 150, {}, 12);
+ expect(r.passes).toEqual([{ pass: 'other', draws: 18 }, { pass: 'lists', draws: 12 }]);
+ });
+
+ it('never has a negative other when a pass claims more than the device counted', () => {
+ const r = drawBudgetReport(10, 150, { 'batch.draws': 12 });
+ expect(r.passes).toEqual([{ pass: 'lists', draws: 12 }]);
+ });
+});
+
+describe('the draw call budget of a quality level', () => {
+ it('is smaller on the weaker levels, and a project can set its own', () => {
+ expect(defaultQualityProfile('low').drawCallBudget).toBeLessThan(defaultQualityProfile('medium').drawCallBudget);
+ expect(defaultQualityProfile('medium').drawCallBudget).toBeLessThan(defaultQualityProfile('high').drawCallBudget);
+ expect(resolveQualityProfile('low', { drawCallBudget: 90 }).drawCallBudget).toBe(90);
+ const config = parseQualityConfig({ mode: 'low', profiles: { low: { drawCallBudget: 'many' } } });
+ expect(config.profiles?.low?.drawCallBudget).toBe(defaultQualityProfile('low').drawCallBudget);
+ });
+});
diff --git a/sdk/tests/renderer.test.ts b/sdk/tests/renderer.test.ts
index 0281505af..fccfaa115 100644
--- a/sdk/tests/renderer.test.ts
+++ b/sdk/tests/renderer.test.ts
@@ -47,6 +47,7 @@ function createRendererMockModule() {
renderer_setStage: vi.fn(),
renderer_getDrawCalls: vi.fn(() => 10),
+ renderer_getGpuDrawCalls: vi.fn(() => 31),
renderer_getTriangles: vi.fn(() => 500),
renderer_getSprites: vi.fn(() => 25),
renderer_getText: vi.fn(() => 5),
@@ -131,6 +132,7 @@ describe('Renderer API', () => {
const stats = Renderer.getStats();
expect(stats).toEqual({
drawCalls: 0,
+ gpuDraws: 0,
triangles: 0,
sprites: 0,
text: 0,
@@ -376,6 +378,7 @@ describe('Renderer API', () => {
const stats = Renderer.getStats();
expect(stats).toEqual({
drawCalls: 10,
+ gpuDraws: 31,
triangles: 500,
sprites: 25,
text: 5,
diff --git a/src/esengine/bindings/RendererBindings.cpp b/src/esengine/bindings/RendererBindings.cpp
index c83b25bf3..d8d5235c8 100644
--- a/src/esengine/bindings/RendererBindings.cpp
+++ b/src/esengine/bindings/RendererBindings.cpp
@@ -1015,6 +1015,11 @@ u32 renderer_getDrawCalls() {
return g_renderFrame->stats().draw_calls;
}
+u32 renderer_getGpuDrawCalls() {
+ if (!g_renderFrame) return 0;
+ return g_renderFrame->stats().gpu_draws;
+}
+
#ifdef __EMSCRIPTEN__
/**
* The local-space XY box of what a MeshRenderer DRAWS — resident geometry when it has
diff --git a/src/esengine/bindings/RendererBindings.hpp b/src/esengine/bindings/RendererBindings.hpp
index 4968e4f5f..a2537a74e 100644
--- a/src/esengine/bindings/RendererBindings.hpp
+++ b/src/esengine/bindings/RendererBindings.hpp
@@ -226,6 +226,8 @@ u32 renderer_getTargetDepthTexture(u32 handle);
void renderer_releaseTarget(u32 handle);
u32 renderer_getTargetTexture(u32 handle);
u32 renderer_getDrawCalls();
+/// Every draw the GPU was asked for in the last frame, every pass included (shadows, prepass, reflections, post-processing).
+u32 renderer_getGpuDrawCalls();
#ifdef __EMSCRIPTEN__
/// GPU objects the device has not destroyed, for the resource census. Null when
/// no device is initialized — absent counters, not zeroed ones.
diff --git a/src/esengine/bindings/WebSDKEntry.cpp b/src/esengine/bindings/WebSDKEntry.cpp
index ddc2bdbfe..30d691f31 100644
--- a/src/esengine/bindings/WebSDKEntry.cpp
+++ b/src/esengine/bindings/WebSDKEntry.cpp
@@ -767,6 +767,7 @@ EMSCRIPTEN_BINDINGS(esengine_renderer) {
emscripten::function("renderer_getTargetTexture", &esengine::renderer_getTargetTexture);
emscripten::function("renderer_getTargetDepthTexture", &esengine::renderer_getTargetDepthTexture);
emscripten::function("renderer_getDrawCalls", &esengine::renderer_getDrawCalls);
+ emscripten::function("renderer_getGpuDrawCalls", &esengine::renderer_getGpuDrawCalls);
emscripten::function("renderer_getLiveObjects", &esengine::renderer_getLiveObjects);
emscripten::function("renderer_getTriangles", &esengine::renderer_getTriangles);
emscripten::function("renderer_getSprites", &esengine::renderer_getSprites);
diff --git a/src/esengine/renderer/frame/RenderFrame.cpp b/src/esengine/renderer/frame/RenderFrame.cpp
index 5ecc379a4..c1f21c0ee 100644
--- a/src/esengine/renderer/frame/RenderFrame.cpp
+++ b/src/esengine/renderer/frame/RenderFrame.cpp
@@ -618,6 +618,7 @@ void RenderFrame::flush() {
void RenderFrame::endFrame() {
frame_capture_.endFrame();
device_.endFrame();
+ stats_.gpu_draws = device_.takeDraws();
publishFrameCounters();
// Once per frame and not per camera: a commit at each camera's end kept only
// the last camera's scopes and counters.
@@ -636,6 +637,7 @@ void RenderFrame::tallyPass(const DrawList& list) {
void RenderFrame::publishFrameCounters() {
if (!FrameProfiler::get().enabled()) return;
ES_PROFILE_COUNTER("batch.draws", stats_.draw_calls);
+ ES_PROFILE_COUNTER("render.gpu.draws", stats_.gpu_draws);
ES_PROFILE_COUNTER("batch.merged", frame_merged_);
// Emitted per reason and only where it happened, so a clean frame publishes
// nothing rather than a wall of zeroes for a caller to read past.
diff --git a/src/esengine/renderer/frame/RenderFrame.hpp b/src/esengine/renderer/frame/RenderFrame.hpp
index 6024aebd3..368b4e8ba 100644
--- a/src/esengine/renderer/frame/RenderFrame.hpp
+++ b/src/esengine/renderer/frame/RenderFrame.hpp
@@ -87,6 +87,8 @@ class RenderFrame {
public:
struct Stats {
u32 draw_calls = 0;
+ /// Every draw the GPU was asked for in the frame, every pass included; `draw_calls` is the scene's and the overlay's lists only.
+ u32 gpu_draws = 0;
u32 triangles = 0;
u32 sprites = 0;
u32 skeletal = 0;
diff --git a/src/esengine/renderer/rhi/GLDevice.cpp b/src/esengine/renderer/rhi/GLDevice.cpp
index 9c88b5714..ae530bee3 100644
--- a/src/esengine/renderer/rhi/GLDevice.cpp
+++ b/src/esengine/renderer/rhi/GLDevice.cpp
@@ -1273,6 +1273,7 @@ u32 GLDevice::primitiveMode() const {
void GLDevice::drawElements(u32 indexCount, GfxDataType indexType, u32 byteOffset) {
if (!isDeviceUsable()) return;
prepareVertexState();
+ countDraw();
glDrawElements(primitiveMode(), static_cast<GLsizei>(indexCount), toGLDataType(indexType),
reinterpret_cast<const void*>(static_cast<uintptr_t>(byteOffset)));
}
@@ -1280,12 +1281,14 @@ void GLDevice::drawElements(u32 indexCount, GfxDataType indexType, u32 byteOffse
void GLDevice::drawArrays(u32 first, u32 vertexCount) {
if (!isDeviceUsable()) return;
prepareVertexState();
+ countDraw();
glDrawArrays(primitiveMode(), static_cast<GLint>(first), static_cast<GLsizei>(vertexCount));
}
void GLDevice::drawElementsInstanced(u32 indexCount, GfxDataType indexType, u32 byteOffset, u32 instanceCount) {
if (!isDeviceUsable()) return;
prepareVertexState();
+ countDraw();
glDrawElementsInstanced(primitiveMode(), static_cast<GLsizei>(indexCount), toGLDataType(indexType),
reinterpret_cast<const void*>(static_cast<uintptr_t>(byteOffset)),
static_cast<GLsizei>(instanceCount));
diff --git a/src/esengine/renderer/rhi/GfxDevice.hpp b/src/esengine/renderer/rhi/GfxDevice.hpp
index 5b595de91..9398ccf22 100644
--- a/src/esengine/renderer/rhi/GfxDevice.hpp
+++ b/src/esengine/renderer/rhi/GfxDevice.hpp
@@ -186,6 +186,14 @@ public:
*/
usize retainedBytes() const { return retained_bytes_; }
+ /**
+ * @brief Every draw the GPU was asked for since the last call, and the tally started again.
+ * @details Counted where the backends issue them, so it holds every pass a frame has: the scene and
+ * the overlay, and the shadow maps, depth prepass, reflections, motion vectors and
+ * post-processing that the draw lists' own count leaves out. An instanced draw is one.
+ */
+ u32 takeDraws() { const u32 n = draws_; draws_ = 0; return n; }
+
/**
* @brief Warns once when retainedBytes() grows past `bytes`; 0 never warns.
* @details Falling back under it re-arms the warning.
@@ -845,6 +853,9 @@ public:
virtual u32 nativeTextureName(TextureHandle texture) const { (void)texture; return 0; }
protected:
+ /** @brief A backend has issued one draw (see takeDraws). */
+ void countDraw() { ++draws_; }
+
// =========================================================================
// Backend primitives. `id` is the handle's value; the backend maps it to its
// own object for the current generation and nothing else.
@@ -991,6 +1002,7 @@ private:
GfxResourceRegistry registry_;
u32 owed_count_ = 0;
usize retained_bytes_ = 0;
+ u32 draws_ = 0;
usize retained_budget_ = 0;
bool over_retained_budget_ = false;
ShaderHandle current_program_ = ShaderHandle::Invalid;
diff --git a/src/esengine/renderer/webgpu/WebGPUDevice.cpp b/src/esengine/renderer/webgpu/WebGPUDevice.cpp
index f9610a582..88336f94d 100644
--- a/src/esengine/renderer/webgpu/WebGPUDevice.cpp
+++ b/src/esengine/renderer/webgpu/WebGPUDevice.cpp
@@ -2160,12 +2160,14 @@ void WebGPUDevice::drawElements(u32 indexCount, GfxDataType indexType, u32 index
wgpuRenderPassEncoderSetIndexBuffer(pass_, it->second.buffer, toWGPUIndexFormat(indexType),
0, it->second.size);
const u32 indexSize = (indexType == GfxDataType::UnsignedShort) ? 2 : 4;
+ countDraw();
wgpuRenderPassEncoderDrawIndexed(pass_, indexCount, 1, indexByteOffset / indexSize, 0, 0);
}
void WebGPUDevice::drawArrays(u32 firstVertex, u32 vertexCount) {
if (!isDeviceUsable() || !pass_) return;
flushBindGroup();
+ countDraw();
wgpuRenderPassEncoderDraw(pass_, vertexCount, 1, firstVertex, 0);
}
@@ -2178,6 +2180,7 @@ void WebGPUDevice::drawElementsInstanced(u32 indexCount, GfxDataType indexType,
wgpuRenderPassEncoderSetIndexBuffer(pass_, it->second.buffer, toWGPUIndexFormat(indexType),
0, it->second.size);
const u32 indexSize = (indexType == GfxDataType::UnsignedShort) ? 2 : 4;
+ countDraw();
wgpuRenderPassEncoderDrawIndexed(pass_, indexCount, instanceCount,
indexByteOffset / indexSize, 0, 0);
}
diff --git a/tools/check-project-settings.mjs b/tools/check-project-settings.mjs
index 42b708b06..9a057a311 100644
--- a/tools/check-project-settings.mjs
+++ b/tools/check-project-settings.mjs
@@ -299,6 +299,7 @@ const BLOCKS = [
waterCaustics: { ui: 'project.rendering.quality.waterCaustics' },
shelterMaskSize: { ui: 'project.rendering.quality.shelterMaskSize' },
shadowSoftSamples: { ui: 'project.rendering.quality.shadowSoftSamples' },
+ drawCallBudget: { ui: 'project.rendering.quality.drawCallBudget' },
skipEffects: { ui: 'project.rendering.quality.effects' },
},
},