Three.js WebGLRenderer autoClear Explained

In Three.js, the WebGLRenderer features an autoClear property that dictates whether the renderer should automatically wipe the canvas before drawing a new frame. This article explains what the autoClear property does, how it impacts rendering behavior, and the specific scenarios where setting it to false is necessary to achieve advanced visual effects like trails, multi-scene overlays, and post-processing.

What is the autoClear Property?

By default, the autoClear property of the WebGLRenderer is set to true. This means that every time you call renderer.render(scene, camera), the renderer automatically clears the color, depth, and stencil buffers of the canvas.

Clearing the canvas ensures that the previous frame is completely erased before the new frame is drawn. Without this default behavior, moving objects would leave a “hall of mirrors” trail behind them, as every new position of the object would be painted on top of its previous positions.

To disable this behavior, you set the property to false:

renderer.autoClear = false;

When autoClear is set to false, the renderer will not clear the canvas on its own. You assume full responsibility for clearing the buffers when necessary.

When Should You Set autoClear to False?

Setting autoClear to false is required in several common advanced rendering techniques.

1. Rendering Multiple Scenes (Layering)

If you want to render multiple scenes on top of one another within a single frame—such as rendering a 3D background scene, followed by a main gameplay scene, and finally a 3D heads-up display (HUD)—you must set autoClear to false.

If autoClear were left as true, rendering the second scene would erase the first scene. With autoClear disabled, you can layer scenes like this:

// Disable automatic clearing
renderer.autoClear = false;

function animate() {
    requestAnimationFrame(animate);

    // 1. Manually clear the buffers once at the start of the frame
    renderer.clear();

    // 2. Render the background scene
    renderer.render(backgroundScene, camera);

    // 3. Render the main scene on top of the background
    renderer.clearDepth(); // Clear depth buffer so foreground doesn't clip
    renderer.render(mainScene, camera);

    // 4. Render the UI scene on top of everything
    renderer.render(uiScene, uiCamera);
}

2. Creating Motion Blur and Trails

To create a trail or ghosting effect behind moving objects, you can prevent the renderer from clearing the color buffer. Instead of wiping the canvas, you can paint a semi-transparent, screen-filling black (or colored) quad over the canvas at the start of every frame.

This partially obscures the previous frames, causing older frames to gradually fade away over time rather than disappearing instantly.

3. Implementing Post-Processing Pipelines

When using Three.js’s EffectComposer for post-processing effects (like bloom, depth of field, or color correction), you often need to manage multiple render passes.

Many custom post-processing setups require disabling autoClear on the main renderer so that individual passes can read from, write to, and combine different buffers without the renderer accidentally clearing the data between passes.