Determining the frame rate for your scene

When you create large Three.js applications with many objects and animations, it is good to keep an eye on the frame rate at which the browser can render your scene. You can do this yourself using log statements from your animation loop, but luckily, there is already a good solution available that integrates great with Three.js (which isn't that strange since it was originally written for Three.js).

Getting ready

For this recipe, we'll use the stats.js JavaScript library that you can download from its GitHub repository at https://github.com/mrdoob/stats.js/. To use this library, you have to include it at the top of your HTML file such as this:

    <script src="../libs/stats.min.js"></script>

We've also provided a ready to use example for this recipe. If you open the 01.06-determine-framerate.html file in your browser, you can directly see how this library shows the current framerate, which you can see at the top-left of the browser, as shown in the following screenshot:

Let's take a look at the steps you need to take to add this to your Three.js application.

How to do it...

Adding this functionality to your scene only takes a couple of small steps, which are as follows:

1. Firstly, we have to create the stats object and position it. For this, we create a simple function:

       function createStats() {
         var stats = new Stats();
         stats.setMode(0);
   
         stats.domElement.style.position = 'absolute';
         stats.domElement.style.left = '0';
         stats.domElement.style.top = '0';
   
         return stats;
       }

   We create the statistics object by calling new Stats(). The Stats.js library supports two different modes that we can set with the setMode function. If we pass 0 as an argument, you see the frames rendered in the last second, and if we set the mode to 1, we see the milliseconds that were needed to render the last frame. For this recipe, we want to see the framerate, so we set the mode to 0.

2. Now that we can create the statistics object, we need to append the init method we've seen in the skeleton recipes:

       // global variables
       var renderer;
       var scene;
       var camera;
       var stats;
   
       function init() {
         ...
         stats = createStats();
         document.body.appendChild( stats.domElement );
   
         // call the render function
         render();
       }

   As you can see we created a new global variable called stats, which we'll use to access our statistics object. In the init method, we use the function we just created, and add the stats object to our HTML body.

3. We're almost there. The only thing we need to do now is make sure that we update the stats object whenever the render function is called. This way, the stats object can calculate either the framerate or the time it took to run the render function:

       function render() {
         requestAnimationFrame(render);
   
         scene.getObjectByName('cube').rotation.x+=0.05;
         renderer.render(scene, camera);
         stats.update();
       }

How it works...

We mentioned that Stats.js provides two modes. It either shows the framerate or the time it took to render the last frame. The Stats.js library works by simply keeping track of the time passed between calls and its update function. If you're monitoring the framerate, it counts how often the update was called within the last second, and shows that value. If you're monitoring the render time, it just shows the time between calls and the update function.