📈 stats-gl

WebGL/WebGPU Performance Monitor tool.

🔗 Live Demo

https://github.com/RenaudRohlinger/stats-gl/assets/15867665/3fdafff4-1357-4872-9baf-0629dbaf9d8c

❗📢 Note: To support GPU monitoring on Safari you need to enable Timer Queries under WebKit Feature Flags > WebGL Timer Queries

📚 Description

stats-gl is a comprehensive tool to monitor WebGL performance. The Stats class provides methods to create performance panels, log performance metrics, and manage the display and layout of these panels. The performance metrics logged include FPS, CPU, and GPU. The GPU logging is available only if the user's browser supports the WebGL 2.0 EXT_disjoint_timer_query_webgl2 extension or WebGPU Timestamp Queries.

In addition to logging real-time performance data, the class also provides methods to calculate and display average performance metrics over a specified interval.

⬇️ Installation

Stats-gl is available as an npm package. You can install it using the following command:

1npm install stats-gl

🧑‍💻 Example Usage

Below is an example of how you can use this class in your code:

1import Stats from "stats-gl";
2
3// create a new Stats object
4const stats = new Stats({
5    trackGPU: false,
6    trackHz: false,
7    trackCPT: false,
8    logsPerSecond: 4,
9    graphsPerSecond: 30,
10    samplesLog: 40, 
11    samplesGraph: 10, 
12    precision: 2, 
13    horizontal: true,
14    minimal: false, 
15    mode: 0
16});
17
18// append the stats container to the body of the document
19document.body.appendChild( stats.dom );
20
21// begin the performance monitor
22stats.begin();
23// end the performance monitor
24stats.end();
25
26stats.begin();
27// gl.draw... second pass
28stats.end();
29
30
31// when all the passes are drawn update the logs
32stats.update();

Quick start with threejs:

1import * as THREE from 'three';
2
3// use esm module instead of cjs
4import Stats from 'https://www.unpkg.com/stats-gl?module';
5
6const container = document.getElementById( 'container' );
7
8const stats = new Stats();
9container.appendChild( stats.dom );
10
11const renderer = new THREE.WebGLRenderer( { antialias: true } ); // or WebGPURenderer
12container.appendChild( renderer.domElement );
13
14const scene = new THREE.Scene();
15
16stats.init( renderer ); // this will patch the threejs render function so no need to call begin() or end()
17
18function animate() {
19
20    requestAnimationFrame( animate );
21
22    render(); // needs async methods in WebGPU (renderAsync)
23    stats.update();
24
25}

Quick start with @react-three/fiber. A <StatsGl /> component is available through @react-three/drei:

1import { Canvas } from '@react-three/fiber'
2import { StatsGl } from '@react-three/drei'
3
4const Scene = () => (
5    <Canvas>
6        <StatsGl />
7    </Canvas>
8)

Quick start with Tresjs for Vue developers. A <StatsGl /> component is available through cientos:

1<script setup lang="ts">
2import { TresCanvas } from '@tresjs/core'
3import { StatsGl } from '@tresjs/cientos'
4</script>
5
6<template>
7  <TresCanvas>
8    <StatsGl />
9  </TresCanvas>
10</template>

⚙️ Parameters

The constructor for the Stats class accepts an options object with the following properties:

• logsPerSecond: How often to log performance data, in logs per second.
• graphsPerSecond: How often to update the graph, in graphs per second.
• trackGPU: A boolean value to enable or disable GPU tracking.
• trackHz: A boolean value to enable or disable Hz tracking.
• trackCPT: (Threejs specific) A boolean value to enable or disable Threejs Compute Shading tracking.
• samplesLog: Number of recent log samples to keep for computing averages.
• samplesGraph: Number of recent graph samples to keep for computing averages.
• precision: Precision of the data, in number of decimal places (only affects CPU and GPU).
• minimal: A boolean value to control the minimalistic mode of the panel display. If set to true, a simple click on the panel will switch between different metrics.
• mode: Sets the initial panel to display - 0 for FPS, 1 for CPU, and 2 for GPU (if supported).
• horizontal: Display the canvases on the X axis, set to align on vertical axis.

All the parameters are optional and have default values. The class also provides other methods such as begin(), end(), init(canvas), etc. which can be used based on the requirement.

🤝 Contributing

Contributions to Stats-gl are welcome.

Please report any issues or bugs you encounter.

📜 License

This project is licensed under the MIT License.

🧑‍🎨 Maintainers :

• twitter 🐈‍⬛ @onirenaud
• twitter @utsuboco