pixijs-filters

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Attach visual effects by assigning one filter (or an array for chaining) to

container.filters

. Built-in filters cover blur, color matrix, displacement, alpha, and noise; custom filters wrap a GLSL/WGSL fragment shader via

Filter.from(...)

通过给

container.filters

赋值单个滤镜（或数组实现链式效果）来添加视觉效果。内置滤镜包含模糊、颜色矩阵、位移、透明度和噪点效果；自定义滤镜可通过

Filter.from(...)

封装GLSL/WGSL片段着色器。

Quick Start

快速开始

const sprite = new Sprite(await Assets.load("hero.png"));
app.stage.addChild(sprite);

const blur = new BlurFilter({ strength: 4, quality: 4 });
const colorMatrix = new ColorMatrixFilter();
colorMatrix.brightness(1.2, false);

sprite.filters = [blur, colorMatrix];

const container = new Container();
container.filters = [new BlurFilter({ strength: 2 })];
container.filterArea = new Rectangle(0, 0, 800, 600);
app.stage.addChild(container);

Related skills:

pixijs-custom-rendering

(shader internals, uniform types),

pixijs-blend-modes

(composing with filters),

pixijs-performance

(filter tuning, filterArea).

const sprite = new Sprite(await Assets.load("hero.png"));
app.stage.addChild(sprite);

const blur = new BlurFilter({ strength: 4, quality: 4 });
const colorMatrix = new ColorMatrixFilter();
colorMatrix.brightness(1.2, false);

sprite.filters = [blur, colorMatrix];

const container = new Container();
container.filters = [new BlurFilter({ strength: 2 })];
container.filterArea = new Rectangle(0, 0, 800, 600);
app.stage.addChild(container);

相关技能：

pixijs-custom-rendering

（着色器内部机制、uniform类型）、

pixijs-blend-modes

（与滤镜组合使用）、

pixijs-performance

（滤镜调优、filterArea）。

Core Patterns

核心模式

Built-in filters

内置滤镜

import {
  AlphaFilter,
  BlurFilter,
  ColorMatrixFilter,
  DisplacementFilter,
  NoiseFilter,
  Assets,
  Sprite,
} from "pixi.js";

// Alpha (uniform transparency without per-child layering)
const alpha = new AlphaFilter({ alpha: 0.5 });

// Blur — strength/quality are uniform; strengthX/strengthY split axes;
// kernelSize must be odd (5, 7, 9, ... 15); repeatEdgePixels avoids transparent edges
const blur = new BlurFilter({
  strength: 4,
  quality: 4,
  kernelSize: 5,
  repeatEdgePixels: false,
});

// Color matrix — brightness is one of many presets. Others: tint, hue,
// contrast, saturate, desaturate, greyscale/grayscale, blackAndWhite,
// negative, sepia, technicolor, polaroid, kodachrome, browni, vintage,
// colorTone, night, predator, lsd, reset. Direct access via
// `colorMatrix.matrix` (20-element array) and `colorMatrix.alpha` (blend
// between original and transformed).
const colorMatrix = new ColorMatrixFilter();
colorMatrix.brightness(1.5, false);
colorMatrix.contrast(0.5, true); // multiply stacks on top of existing matrix
colorMatrix.alpha = 0.7; // blend at 70% strength

// Displacement — scale is a number or PointData
const displacementTexture = await Assets.load("displacement_map.png");
const displacementSprite = new Sprite(displacementTexture);
const displacement = new DisplacementFilter({
  sprite: displacementSprite,
  scale: { x: 20, y: 10 },
});

// Noise — seed is an arbitrary number that determines the noise pattern; same seed reproduces the same pattern
const noise = new NoiseFilter({ noise: 0.5, seed: Math.random() });

sprite.filters = [blur, colorMatrix];

import {
  AlphaFilter,
  BlurFilter,
  ColorMatrixFilter,
  DisplacementFilter,
  NoiseFilter,
  Assets,
  Sprite,
} from "pixi.js";

// Alpha（统一透明度，无需子元素分层设置）
const alpha = new AlphaFilter({ alpha: 0.5 });

// 模糊滤镜 — strength/quality为统一参数；strengthX/strengthY可分别设置轴向；
// kernelSize必须为奇数（5、7、9……15）；repeatEdgePixels可避免边缘透明
const blur = new BlurFilter({
  strength: 4,
  quality: 4,
  kernelSize: 5,
  repeatEdgePixels: false,
});

// 颜色矩阵滤镜 — brightness是众多预设之一。其他预设包括：tint、hue、
// contrast、saturate、desaturate、greyscale/grayscale、blackAndWhite、
// negative、sepia、technicolor、polaroid、kodachrome、browni、vintage、
// colorTone、night、predator、lsd、reset。可通过
// `colorMatrix.matrix`（20元素数组）和`colorMatrix.alpha`（原始效果与转换效果的混合度）直接调整参数。
const colorMatrix = new ColorMatrixFilter();
colorMatrix.brightness(1.5, false);
colorMatrix.contrast(0.5, true); // 叠加到现有矩阵上
colorMatrix.alpha = 0.7; // 混合强度为70%

// 位移滤镜 — scale可以是数值或PointData对象
const displacementTexture = await Assets.load("displacement_map.png");
const displacementSprite = new Sprite(displacementTexture);
const displacement = new DisplacementFilter({
  sprite: displacementSprite,
  scale: { x: 20, y: 10 },
});

// 噪点滤镜 — seed是决定噪点图案的任意数值；相同seed会生成相同图案
const noise = new NoiseFilter({ noise: 0.5, seed: Math.random() });

sprite.filters = [blur, colorMatrix];

Custom filter with Filter.from()

使用Filter.from()创建自定义滤镜

The simplest way to create a custom filter. Only a fragment shader is needed; PixiJS provides a default vertex shader.

import { Filter } from "pixi.js";

const filter = Filter.from({
  gl: {
    fragment: `
            in vec2 vTextureCoord;
            out vec4 finalColor;
            uniform sampler2D uTexture;
            uniform float uTime;

            void main() {
                vec2 uv = vTextureCoord;
                uv.x += sin(uv.y * 10.0 + uTime) * 0.02;
                finalColor = texture(uTexture, uv);
            }
        `,
  },
  resources: {
    timeUniforms: {
      uTime: { value: 0, type: "f32" },
    },
  },
});

sprite.filters = filter;

app.ticker.add((ticker) => {
  filter.resources.timeUniforms.uniforms.uTime += 0.04 * ticker.deltaTime;
});

For more control, construct

GlProgram

GpuProgram

objects directly:

import { Filter, GlProgram } from "pixi.js";

const glProgram = GlProgram.from({ fragment: fragmentSrc, vertex: vertexSrc });

const filter = new Filter({
  glProgram,
  resources: {
    timeUniforms: {
      uTime: { value: 0, type: "f32" },
    },
  },
});

Key points:

Use
```
out vec4 finalColor
```
in fragment shaders, not
```
gl_FragColor
```
(GLSL ES 3.0).
Use
```
texture()
```
to sample, not
```
texture2D
```
.
```
glProgram
```
for WebGL,
```
gpuProgram
```
for WebGPU. Omitting one skips that renderer.
Textures go in
```
resources
```
, not uniforms. The filter system auto-provides
```
uTexture
```
(the input).

Access uniform values via

filter.resources.{groupName}.uniforms.{name}

这是创建自定义滤镜最简单的方式。仅需提供片段着色器；PixiJS会提供默认的顶点着色器。

import { Filter } from "pixi.js";

const filter = Filter.from({
  gl: {
    fragment: `
            in vec2 vTextureCoord;
            out vec4 finalColor;
            uniform sampler2D uTexture;
            uniform float uTime;

            void main() {
                vec2 uv = vTextureCoord;
                uv.x += sin(uv.y * 10.0 + uTime) * 0.02;
                finalColor = texture(uTexture, uv);
            }
        `,
  },
  resources: {
    timeUniforms: {
      uTime: { value: 0, type: "f32" },
    },
  },
});

sprite.filters = filter;

app.ticker.add((ticker) => {
  filter.resources.timeUniforms.uniforms.uTime += 0.04 * ticker.deltaTime;
});

如需更多控制，可直接构造

GlProgram

GpuProgram

对象：

import { Filter, GlProgram } from "pixi.js";

const glProgram = GlProgram.from({ fragment: fragmentSrc, vertex: vertexSrc });

const filter = new Filter({
  glProgram,
  resources: {
    timeUniforms: {
      uTime: { value: 0, type: "f32" },
    },
  },
});

关键点：

在片段着色器中使用
```
out vec4 finalColor
```
，而非
```
gl_FragColor
```
（GLSL ES 3.0规范）。
使用
```
texture()
```
进行采样，而非
```
texture2D
```
。
```
glProgram
```
适用于WebGL，
```
gpuProgram
```
适用于WebGPU。省略其中一个则会跳过对应渲染器。
纹理需放在
```
resources
```
中，而非uniforms。滤镜系统会自动提供
```
uTexture
```
（输入纹理）。

通过

filter.resources.{groupName}.uniforms.{name}

访问uniform值。

Filter options

滤镜配置选项

import { Filter, GlProgram, Rectangle } from "pixi.js";

const filter = new Filter({
  glProgram: GlProgram.from({ fragment }),
  resources: {},
  resolution: 0.5, // default 1. Lower = faster, blurrier
  padding: 10, // default 0. Extra pixels for effects that extend bounds
  antialias: "off", // default 'off'. 'on' | 'off' | 'inherit'
  blendMode: "normal", // default 'normal'
  blendRequired: false, // default false. true if shader samples uBackTexture
  clipToViewport: true, // default true
});

// Optimization: set known bounds to avoid per-frame measurement
container.filterArea = new Rectangle(0, 0, 800, 600);

// Toggle without rebuilding the filter array
filter.enabled = false;

// Share one filter instance across many display objects
sprite1.filters = [filter];
sprite2.filters = [filter];

import { Filter, GlProgram, Rectangle } from "pixi.js";

const filter = new Filter({
  glProgram: GlProgram.from({ fragment }),
  resources: {},
  resolution: 0.5, // 默认值1。值越低，速度越快，模糊度越高
  padding: 10, // 默认值0。为超出边界的效果预留额外像素
  antialias: "off", // 默认值'off'。可选值：'on' | 'off' | 'inherit'
  blendMode: "normal", // 默认值'normal'
  blendRequired: false, // 默认值false。若着色器采样uBackTexture则设为true
  clipToViewport: true, // 默认值true
});

// 优化：设置已知边界，避免逐帧测量
container.filterArea = new Rectangle(0, 0, 800, 600);

// 无需重建滤镜数组即可启用/禁用滤镜
filter.enabled = false;

// 在多个显示对象间共享单个滤镜实例
sprite1.filters = [filter];
sprite2.filters = [filter];

Community filters (pixi-filters)

社区滤镜（pixi-filters）

import { AdjustmentFilter } from "pixi-filters/adjustment";
import { GlowFilter } from "pixi-filters/glow";

sprite.filters = [
  new AdjustmentFilter({ brightness: 1.2, contrast: 1.1 }),
  new GlowFilter({ distance: 15, outerStrength: 2 }),
];

For v8, community filters use

pixi-filters/{name}

imports, not the old

@pixi/filter-*

packages.

import { AdjustmentFilter } from "pixi-filters/adjustment";
import { GlowFilter } from "pixi-filters/glow";

sprite.filters = [
  new AdjustmentFilter({ brightness: 1.2, contrast: 1.1 }),
  new GlowFilter({ distance: 15, outerStrength: 2 }),
];

对于v8版本，社区滤镜需使用

pixi-filters/{name}

格式导入，而非旧版的

@pixi/filter-*

包。

Advanced blend modes

高级混合模式

Advanced blend modes (

color-burn

overlay

hard-light

, etc.) are powered by the filter system and must be imported before use. They also require

useBackBuffer: true

on WebGL; see the

pixijs-blend-modes

skill for the full list.

import "pixi.js/advanced-blend-modes";

await app.init({ useBackBuffer: true });
sprite.blendMode = "color-burn";

高级混合模式（

color-burn

、

overlay

、

hard-light

等）由滤镜系统提供，使用前必须先导入。在WebGL环境下还需设置

useBackBuffer: true

；完整列表请查看

pixijs-blend-modes

技能。

import "pixi.js/advanced-blend-modes";

await app.init({ useBackBuffer: true });
sprite.blendMode = "color-burn";

Common Mistakes

常见错误

[CRITICAL] Using old Filter constructor (vertex, fragment, uniforms)

[严重] 使用旧版Filter构造函数（vertex、fragment、uniforms）

Wrong:

import { Filter } from "pixi.js";

const filter = new Filter(vertex, fragment, { uTime: 0 });

Correct:

import { Filter, GlProgram } from "pixi.js";

const filter = new Filter({
  glProgram: GlProgram.from({ fragment, vertex }),
  resources: {
    timeUniforms: { uTime: { value: 0, type: "f32" } },
  },
});

v8 uses an options object. Shaders must be wrapped in

GlProgram.from()

GpuProgram.from()

. Uniforms are grouped in

resources

with explicit types. Textures are resources, not uniforms.

错误写法：

import { Filter } from "pixi.js";

const filter = new Filter(vertex, fragment, { uTime: 0 });

正确写法：

import { Filter, GlProgram } from "pixi.js";

const filter = new Filter({
  glProgram: GlProgram.from({ fragment, vertex }),
  resources: {
    timeUniforms: { uTime: { value: 0, type: "f32" } },
  },
});

v8版本使用配置对象。着色器必须通过

GlProgram.from()

或

GpuProgram.from()

封装。Uniform需分组放在

resources

中并指定明确类型。纹理属于resources，而非uniforms。

[HIGH] Using @pixi/filter-* packages for v8

[高风险] 为v8版本使用@pixi/filter-*包

Wrong:

import { AdjustmentFilter } from "@pixi/filter-adjustment";

Correct:

import { AdjustmentFilter } from "pixi-filters/adjustment";

@pixi/filter-*

packages are v7 only. For v8, the community filters package restructured to

pixi-filters/{name}

错误写法：

import { AdjustmentFilter } from "@pixi/filter-adjustment";

正确写法：

import { AdjustmentFilter } from "pixi-filters/adjustment";

@pixi/filter-*

包仅适用于v7版本。v8版本的社区滤镜包已重构为

pixi-filters/{name}

格式。

[HIGH] Using too many filters without containerizing

[高风险] 未使用容器批量处理却添加过多滤镜

Each filter application requires a framebuffer switch, bounds measurement, and render-to-texture pass. One filter on a parent container is much cheaper than the same filter on each child.

Wrong:

for (const child of container.children) {
  child.filters = [new BlurFilter({ strength: 4 })];
}

Correct:

container.filters = [new BlurFilter({ strength: 4 })];

每次应用滤镜都需要切换帧缓冲、测量边界并执行渲染到纹理的操作。在父容器上添加一个滤镜的成本远低于给每个子元素都添加相同滤镜。

错误写法：

for (const child of container.children) {
  child.filters = [new BlurFilter({ strength: 4 })];
}

正确写法：

container.filters = [new BlurFilter({ strength: 4 })];

[HIGH] Using a blendRequired filter without useBackBuffer on WebGL

[高风险] 在WebGL环境下使用blendRequired滤镜却未设置useBackBuffer

Custom filters and most advanced community filters that set

blendRequired: true

sample the back buffer. On WebGL that only works if the renderer was initialized with

useBackBuffer: true

; otherwise PixiJS logs a warning and the filter silently falls back:

await app.init({ useBackBuffer: true });

WebGPU enables the back buffer unconditionally, so this only affects WebGL.

设置

blendRequired: true

的自定义滤镜和多数高级社区滤镜会采样后台缓冲。在WebGL环境下，只有当渲染器初始化时设置

useBackBuffer: true

才能正常工作；否则PixiJS会记录警告并自动回退：

await app.init({ useBackBuffer: true });

WebGPU会无条件启用后台缓冲，因此该问题仅影响WebGL环境。

[MEDIUM] Not setting filterArea for known-size containers

[中等风险] 未给已知尺寸的容器设置filterArea

Without

filterArea

, PixiJS measures the container bounds every frame via

getGlobalBounds()

, which recursively walks all children. For containers with known dimensions, set

filterArea

to avoid this cost:

import { Rectangle } from "pixi.js";

container.filterArea = new Rectangle(0, 0, 800, 600);
container.filters = [someFilter];

若未设置

filterArea

，PixiJS会通过

getGlobalBounds()

逐帧测量容器边界，这会递归遍历所有子元素。对于尺寸已知的容器，设置

filterArea

可避免此性能损耗：

import { Rectangle } from "pixi.js";

container.filterArea = new Rectangle(0, 0, 800, 600);
container.filters = [someFilter];

pixijs-filters

Original

Translation

Quick Start

快速开始

Core Patterns

核心模式

Built-in filters

内置滤镜

Custom filter with Filter.from()

使用Filter.from()创建自定义滤镜

Filter options

滤镜配置选项

Community filters (pixi-filters)

社区滤镜（pixi-filters）

Advanced blend modes

高级混合模式

Common Mistakes

常见错误

[CRITICAL] Using old Filter constructor (vertex, fragment, uniforms)

[严重] 使用旧版Filter构造函数（vertex、fragment、uniforms）

[HIGH] Using @pixi/filter-* packages for v8

[高风险] 为v8版本使用@pixi/filter-*包

[HIGH] Using too many filters without containerizing

[高风险] 未使用容器批量处理却添加过多滤镜

[HIGH] Using a blendRequired filter without useBackBuffer on WebGL

[高风险] 在WebGL环境下使用blendRequired滤镜却未设置useBackBuffer

[MEDIUM] Not setting filterArea for known-size containers

[中等风险] 未给已知尺寸的容器设置filterArea

API Reference

API参考