diff --git a/docs/user-manual/optimization/mini-stats.md b/docs/user-manual/optimization/mini-stats.md index 8d097ebd633..e647dbe614a 100644 --- a/docs/user-manual/optimization/mini-stats.md +++ b/docs/user-manual/optimization/mini-stats.md @@ -2,35 +2,103 @@ title: MiniStats --- -MiniStats is a lightweight graphical display of an application's key performance statistics. It shows draw call count, frame time, CPU load and (where supported) GPU load. +MiniStats is a lightweight graphical overlay that displays real-time performance metrics for your PlayCanvas application. It provides essential statistics including draw call count, frame time, CPU load, and GPU load, helping you identify performance bottlenecks during development. + +## Enabling MiniStats Editor users can enable the MiniStats panel via the Launch button menu: Launch Menu -Clicking on the MiniStats will cycle through three supported sizes: +## Display Sizes + +Clicking on the MiniStats overlay cycles through three display sizes: small (compact numeric values), medium, and large. The medium and large sizes add graphical timelines and detailed sub-timing breakdowns for both CPU and GPU. Mini Stats -The information displayed is as follows: +## Basic Statistics + +The following metrics are always displayed: + +| Metric | Description | +|--------|-------------| +| **DrawCalls** | The number of draw calls dispatched each frame. Each draw call has overhead on both CPU and GPU, so minimizing this number improves performance. | +| **Frame** | Total time in milliseconds for the browser to process each frame. Target 16.67ms for 60 FPS or 33.33ms for 30 FPS. | +| **GPU** | Time in milliseconds for the GPU to render each frame. See [GPU Timing Requirements](#gpu-timing-requirements) below. | +| **CPU** | Time in milliseconds for CPU-side frame processing, split into update (red) and render (green) portions. | + +## Detailed Timing Mode + +When using medium or large display sizes, MiniStats shows additional timing breakdowns for both CPU and GPU that help identify specific performance bottlenecks. + +### CPU Sub-Timings + +In detailed mode, the CPU graph expands to show individual timing components: + +| Stat | Description | +|------|-------------| +| **scriptUpdate** | Time spent executing script `update` methods | +| **scriptPostUpdate** | Time spent executing script `postUpdate` methods | +| **render** | CPU time spent preparing rendering commands and managing GPU resources | +| **physics** | Time spent in physics simulation | +| **anim** | Time spent updating the animation system | +| **gsplatSort** | Time spent sorting Gaussian splats for rendering. This runs in a Web Worker thread and is non-blocking, so it does not impact main thread performance. | + +:::note +Some CPU stats only appear once they have non-zero values. For example, `physics` only appears if your scene uses physics simulation. +::: + +### GPU Pass Timings -* **DrawCalls** - The number of rendered objects dispatched every frame. Each draw call has a cost on the CPU and GPU, so minimizing this number is sensible. -* **Frame** - The total time in milliseconds for the browser to process each frame. -* **GPU** - Shows the time in milliseconds to render each frame by the GPU. This stat is supported by both WebGL 2 and WebGPU flavors of the Engine but there are some requirements: - * WebGL 2: The underlying WebGL implementation must support the [`EXT_disjoint_timer_query_webgl2`](https://web3dsurvey.com/webgl2/extensions/EXT_disjoint_timer_query_webgl2) extension. You can confirm whether your browser supports this extension by visiting [WebGL Report](https://webglreport.com/?v=2). - * WebGPU: The underlying WebGPU implementation must support the GPU Adapter feature [`timestamp-query`](https://web3dsurvey.com/webgpu/features/timestamp-query). -* **CPU** - Shows the time in milliseconds to render each frame by the CPU. +In detailed mode, individual GPU render pass and compute pass timings are displayed, showing how long each stage takes. Passes with the same name are aggregated into a single timing value. Common passes include: -The CPU and GPU graphs display a breakdown of the update and render portion of the frame using red and green respectively. +- **Forward** - Main scene rendering +- **Downsample** - Post-processing downsampling stages +- **Upsample** - Post-processing upsampling stages +- **Compose** - Final frame composition +- **Compute** passes - GPU compute shader dispatches + +:::important[WebGPU Only] +Detailed GPU pass timing is only available when using the **WebGPU** graphics backend. + +**WebGL2 does not support detailed GPU profiling** - only the overall GPU frame time is shown. This limitation exists because WebGL's timer query extension only supports measuring elapsed time for the entire frame. Browser security restrictions (Spectre mitigations) prevent the fine-grained timestamp queries needed for per-pass measurements. +::: + +## GPU Timing Requirements + +GPU timing requires specific browser/API support: + +| Backend | Requirement | +|---------|-------------| +| **WebGL 2** | The [`EXT_disjoint_timer_query_webgl2`](https://web3dsurvey.com/webgl2/extensions/EXT_disjoint_timer_query_webgl2) extension must be supported. Check [WebGL Report](https://webglreport.com/?v=2) to verify browser support. | +| **WebGPU** | The [`timestamp-query`](https://web3dsurvey.com/webgpu/features/timestamp-query) adapter feature must be available. This is enabled automatically when supported. | ## Using MiniStats Outside of the Editor -While the MiniStats panel is incorporated into the Editor's Launch page, you can also use it independent of the Editor. To add MiniStats to your application, simply call: +While the MiniStats panel is incorporated into the Editor's Launch page, you can also use it independently. To add MiniStats to your application: ```javascript const miniStats = new pc.MiniStats(app); ``` -For more details on available methods and properties, refer to the [MiniStats API reference](https://api.playcanvas.com/engine/classes/MiniStats.html). +You can customize the display with options: + +```javascript +const miniStats = new pc.MiniStats(app, { + startSizeIndex: 1, // Start with medium size + cpu: { + enabled: true, + watermark: 33 // Show 33ms budget line + }, + gpu: { + enabled: true, + watermark: 33 + } +}); +``` + +For the complete API, refer to the [MiniStats API reference](https://api.playcanvas.com/engine/classes/MiniStats.html). See the [MiniStats example](https://playcanvas.github.io/#/misc/mini-stats) for a demonstration of customization options. + +## See It In Action -Take a look at the [Engine Examples Browser](https://playcanvas.github.io/) to see MiniStats in action in an Engine-only context. +Visit the [Engine Examples Browser](https://playcanvas.github.io/) to see MiniStats in action. Try clicking on the overlay to cycle through the different display sizes and observe the detailed timing breakdowns. diff --git a/static/img/user-manual/optimization/mini-stats/mini-stats.gif b/static/img/user-manual/optimization/mini-stats/mini-stats.gif index 9c27d931950..992d1ffa34f 100644 Binary files a/static/img/user-manual/optimization/mini-stats/mini-stats.gif and b/static/img/user-manual/optimization/mini-stats/mini-stats.gif differ