How to Use PixiJS BlurFilter for Gaussian Blur

This article provides a quick and straightforward guide on how to apply a Gaussian blur effect in Pixi.js using its built-in BlurFilter. You will learn how to initialize the filter, apply it to a display object such as a sprite or container, and adjust its properties to control the blur intensity and rendering quality.

Step 1: Create the Blur Filter

Pixi.js features a built-in BlurFilter class that implements a highly optimized Gaussian blur. To use it, you first need to instantiate the filter class.

import { BlurFilter } from 'pixi.js';

// Instantiate a new blur filter
const blurFilter = new BlurFilter();

Step 2: Apply the Filter to a Display Object

Filters in Pixi.js are applied to display objects (like Sprite, Container, or Graphics) by assigning them to the object’s filters array.

import { Sprite } from 'pixi.js';

// Create a sprite
const mySprite = Sprite.from('path/to/image.png');

// Apply the blur filter
mySprite.filters = [blurFilter];

Step 3: Configure Filter Properties

You can customize the Gaussian blur by adjusting the properties of the BlurFilter instance:

• blur: Controls the strength of the blur. Higher numbers yield a stronger blur effect (default is 8).
• quality: Sets the number of passes the shader runs. A higher quality (e.g., 4 or 5) looks smoother but requires more GPU performance, while a lower quality (e.g., 1 or 2) is faster.
• blurX and blurY: Allows you to adjust the blur intensity independently on the horizontal and vertical axes.

// Set a strong, balanced blur
blurFilter.blur = 15;

// Increase rendering quality for smoother edges
blurFilter.quality = 4;

// Create a motion-blur style effect by blurring only horizontally
blurFilter.blurX = 20;
blurFilter.blurY = 0;

Complete Implementation Example

Below is a complete code block demonstrating how to set up a basic Pixi.js application, load a sprite, and apply a dynamic Gaussian blur effect that changes over time.

import { Application, Sprite, BlurFilter } from 'pixi.js';

async function init() {
    // Initialize the PixiJS Application
    const app = new Application();
    await app.init({ width: 800, height: 600 });
    document.body.appendChild(app.canvas);

    // Create and position a sprite
    const sprite = Sprite.from('https://pixijs.com/assets/bunny.png');
    sprite.anchor.set(0.5);
    sprite.x = app.screen.width / 2;
    sprite.y = app.screen.height / 2;
    app.stage.addChild(sprite);

    // Create the Gaussian blur filter
    const blurFilter = new BlurFilter();
    blurFilter.blur = 0; // Start with no blur
    sprite.filters = [blurFilter];

    // Animate the blur strength using the application ticker
    let count = 0;
    app.ticker.add(() => {
        count += 0.05;
        // Oscillate the blur value between 0 and 12
        blurFilter.blur = Math.abs(Math.sin(count)) * 12;
    });
}

init();