Skip to content
Tutorials Center
My learning

Topics

Lesson 32 of 39 ยท Performance and Frameworks

Three.js Performance Fundamentals

Make Three.js scenes fast: read renderer.info, cut draw calls, share geometry and materials, dispose GPU memory, limit pixel ratio and render on demand, with measurable examples.

A 3D scene that runs at 144 frames per second on your gaming laptop can crawl on a three-year-old phone, and phones are where most visitors are. Performance in Three.js is not magic: it comes down to a handful of ideas about what the CPU and GPU each have to do every frame, and a handful of measurements that tell you where the time goes.

This lesson teaches you to measure first, then fix the usual suspects: too many draw calls, too many triangles, too many pixels, wasteful materials, and GPU memory that never gets released.

Measure before you optimize

Guessing at performance problems wastes days. Use these tools:

  • renderer.info: live counters. info.render.calls (draw calls), info.render.triangles, info.memory.geometries and info.memory.textures.
  • Browser DevTools Performance tab: shows whether the CPU (JavaScript, culling, matrix updates) or the GPU is the bottleneck.
  • stats.js or three/addons/libs/stats.module.js: an FPS meter you can drop onto a page.
  • Spector.js (browser extension): captures one frame and lists every WebGL call, which makes wasteful draws obvious.

The first question is always: CPU-bound or GPU-bound? If lowering the canvas resolution makes the frame rate jump, you are GPU-bound (too many pixels or heavy shaders). If it does not, the CPU is the limit (too many objects or draw calls, heavy JavaScript).

Where frame time goes

CPU Scene graph, culling, draw calls, your code
GPU vertices Triangles and vertex shaders
GPU pixels Resolution, overdraw, fragment shaders
Memory Textures, geometry, render targets

Find the limit first. Fixing the wrong one changes nothing.

1 / 2

Draw calls

Each mesh with its own material costs one draw call: a command the CPU sends to the GPU. The GPU can draw millions of triangles per frame, but the CPU can only issue so many calls; a few hundred is fine on desktop and a few thousand is the practical limit on mobile. Ten thousand tiny meshes is far slower than one mesh with ten thousand times the triangles.

The fixes, from simplest to most advanced:

  1. Share geometries and materials. Many meshes can use the same BufferGeometry and Material objects. This saves memory and lets Three.js skip state changes. It does not by itself reduce calls, but it is the prerequisite for the next steps.
  2. Merge static geometry into one mesh with mergeGeometries.
  3. Use InstancedMesh for many copies of the same shape (trees, bullets, bricks).
  4. Use BatchedMesh for many different shapes that share a material.

The next lesson, Instancing, Merging and LOD, goes deep on 2 to 4. The example below makes the cost of unshared objects visible.

Reading renderer.info

Both versions issue 400 draw calls: sharing saves GPU memory and setup time but not calls. Look at geometries: 400 buffers versus 1. Only instancing or merging (next lesson) drops the call count to 1. Also note that identical materials share one shader program, so programs stays small either way.

Triangles, pixels and shaders

  • Triangles. Modern GPUs handle a few million triangles per frame easily. Use models decimated for web, a lower segment count on spheres (SphereGeometry(1, 32, 16) looks fine; 128 by 128 wastes 16 times the vertices), and LOD for distant objects.
  • Pixels. Fill cost scales with resolution. A phone with devicePixelRatio 3 renders 9 times as many pixels as at ratio 1. Cap it:
JavaScript
renderer.setPixelRatio(Math.min(window.devicePixelRatio, 2));

For very heavy scenes, render at 1 or at a dynamic ratio that drops when the frame time grows.

  • Overdraw. Transparent objects and large overlapping quads make the GPU shade the same pixel many times. Keep transparent areas small, sort sensibly, and prefer alphaTest (hard cutout) over blending for foliage.
  • Materials. MeshBasicMaterial is cheapest, MeshLambertMaterial is cheaper than MeshStandardMaterial, and MeshPhysicalMaterial features such as transmission, clearcoat and sheen are the most expensive. Use the simplest material that gives the look.
  • Lights and shadows. Each light adds work to every lit pixel; keep dynamic lights to a handful. Each shadow-casting light renders the scene again. Use one directional light shadow with a tight frustum, a modest mapSize (1024 or 2048), and bake static shadows into textures when you can. See Lights and Shadows.
  • Post-processing. Each pass is a full-screen draw. Fewer, cheaper passes; consider half resolution for bloom.
  • Antialiasing. antialias: true is cheap on desktop and costly on weak mobile GPUs; consider disabling it at pixel ratio 2 or higher, where aliasing is less visible.

Freeing GPU memory with dispose

JavaScript's garbage collector cleans up your objects, but it cannot free the GPU resources behind them. Geometries (vertex buffers), textures, render targets and materials (shader programs) stay on the GPU until you call dispose(). A single-page application that loads a new model on each navigation without disposing will slowly leak memory until the tab crashes on mobile.

JavaScript
function disposeObject(root) {
  root.traverse((obj) => {
    if (obj.geometry) obj.geometry.dispose();
    const materials = Array.isArray(obj.material) ? obj.material : obj.material ? [obj.material] : [];
    for (const mat of materials) {
      for (const value of Object.values(mat)) {
        if (value && value.isTexture) value.dispose();   // map, normalMap, roughnessMap, ...
      }
      mat.dispose();
    }
  });
}

Remove the object from its parent first (scene.remove(obj)), then dispose. Do not dispose resources that other objects still share (a shared geometry or material, a cached texture): they would be re-uploaded automatically on next use, but you lose the benefit. At the very end, renderer.dispose() releases the context's own resources, and renderer.forceContextLoss() frees the WebGL context itself (browsers allow only about 16 contexts per page).

Watching info.memory while disposing

Notice that merely removing the group from the scene frees nothing; only dispose() lowers the counters. A routine that cleans up on unmount is essential in React, Vue and other component frameworks.

Render only when needed

A page with a static product viewer does not need to redraw 60 times per second when nothing moves. On-demand rendering draws a frame only after something changed: a control moved, an animation is running, an asset loaded. It saves battery and GPU heat, and lets several other things on the page stay smooth.

Render on demand

After the first frame, the counter stays at 1 until you press the button. With controls, listen to controls.addEventListener('change', invalidate) and remember to also invalidate on window resize and when textures finish loading. This is the pattern used by React Three Fiber's frameloop="demand" setting.

Other quick wins

  • Frustum culling is on by default: objects outside the view are skipped. Keep it on, and set bounding volumes correctly for displaced or skinned meshes.
  • matrixAutoUpdate = false on static objects (call updateMatrix() once) saves CPU on big scenes.
  • Texture sizes: halve a texture's dimension and you quarter its memory. Use KTX2/Basis compression for large sets.
  • Avoid allocations in the loop: reuse Vector3 temporaries; garbage collection pauses cause stutter.
  • Load smart: lazy-load models and textures below the fold, show a lightweight first frame, and use the LoadingManager (earlier lesson).
  • Test on real devices, including a low-end Android phone. A desktop GPU hides most problems.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. If lowering the canvas resolution makes the frame rate much higher, what is the likely bottleneck?

    Fewer pixels means less fragment work. If performance does not change with resolution, the limit is on the CPU side.
  2. 2. You remove a mesh with scene.remove(mesh). What happens to its geometry and textures on the GPU?

    Removal only detaches the object from the scene. GPU resources are released by geometry.dispose(), texture.dispose() and material.dispose().
  3. 3. How does sharing one geometry and one material among 400 meshes help?

    Sharing avoids 400 copies of the buffers, but drawing still takes one call per mesh. Instancing or merging reduces the calls.
  4. 4. Which line is the usual way to avoid rendering 9 times the pixels on a 3x phone screen?

    Capping the pixel ratio limits the render resolution, trading a little sharpness for a lot of fill rate.

Summary

  • Measure with renderer.info, DevTools and stats before optimizing; find whether you are CPU or GPU bound.
  • Reduce draw calls (share, merge, instance), triangles (LOD, simpler models), pixels (cap the pixel ratio) and shader cost (simple materials, few lights and shadows).
  • Call dispose() on geometries, materials, textures and render targets you no longer need; scene.remove is not enough.
  • Render on demand when nothing is animating.
  • Always test on slow devices.

Next: Instancing, Merging and LOD