pixijs-filters

container.filters に 1 つのフィルタ (またはチェーン処理用の配列) を割り当てることで、視覚効果を追加します。ビルトインフィルタはぼかし、色行列、ディスプレイスメント、透明度、ノイズに対応しており、カスタムフィルタは Filter.from(...) を使用して GLSL/WGSL フラグメントシェーダーをラップします。

クイックスタート

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 (シェーダー内部、ユニフォーム型)、pixijs-blend-modes (フィルタとの合成)、pixijs-performance (フィルタチューニング、filterArea)。

コアパターン

ビルトインフィルタ

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

// Alpha (子ごとのレイヤーリングなしで均一な透明度を適用)
const alpha = new AlphaFilter({ alpha: 0.5 });

// Blur — strength/quality は均一です。strengthX/strengthY で軸を分割します。
// kernelSize は奇数である必要があります (5, 7, 9, ... 15)。
// repeatEdgePixels は透明なエッジを防ぎます
const blur = new BlurFilter({
  strength: 4,
  quality: 4,
  kernelSize: 5,
  repeatEdgePixels: false,
});

// Color matrix — brightness は多くのプリセットの 1 つです。その他:
// 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); // multiply は既存の行列の上に積み重ねます
colorMatrix.alpha = 0.7; // 70% の強度でブレンド

// Displacement — 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 },
});

// Noise — seed はノイズパターンを決定する任意の数値です。
// 同じ seed は同じパターンを再現します
const noise = new NoiseFilter({ noise: 0.5, seed: Math.random() });

sprite.filters = [blur, colorMatrix];

Filter.from() を使用したカスタムフィルタ

カスタムフィルタを作成する最も簡単な方法です。フラグメントシェーダーのみが必要で、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" },
    },
  },
});

重要なポイント:

• フラグメントシェーダーで gl_FragColor ではなく out vec4 finalColor を使用してください (GLSL ES 3.0)。
• texture2D ではなく texture() を使用してサンプリングしてください。
• WebGL は glProgram、WebGPU は gpuProgram を使用します。一方を省略するとそのレンダラーがスキップされます。
• テクスチャはユニフォームではなく resources に入ります。フィルタシステムは自動的に uTexture (入力) を提供します。
• filter.resources.{groupName}.uniforms.{name} を使用してユニフォーム値にアクセスしてください。

フィルタオプション

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;

// 1 つのフィルタインスタンスを多くのディスプレイオブジェクト間で共有
sprite1.filters = [filter];
sprite2.filters = [filter];

コミュニティフィルタ (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 }),
];

v8 の場合、コミュニティフィルタは古い @pixi/filter-* パッケージではなく pixi-filters/{name} インポートを使用します。

高度なブレンドモード

高度なブレンドモード (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";

よくある間違い

[CRITICAL] 古い Filter コンストラクタの使用 (vertex、fragment、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() でラップする必要があります。ユニフォームは resources 内に明示的な型でグループ化されます。テクスチャはユニフォームではなくリソースです。

[HIGH] v8 で @pixi/filter-* パッケージを使用

誤り:

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

正解:

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

@pixi/filter-* パッケージは v7 のみです。v8 の場合、コミュニティフィルタパッケージは pixi-filters/{name} に再構成されています。

[HIGH] コンテナ化なしで多数のフィルタを使用

各フィルタアプリケーションにはフレームバッファスイッチ、バウンド測定、テクスチャへのレンダーパスが必要です。親コンテナ上の 1 つのフィルタは、各子に同じフィルタを適用するより非常に安いです。

誤り:

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

正解:

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

[HIGH] WebGL で blendRequired フィルタを useBackBuffer なしで使用

blendRequired: true に設定するカスタムフィルタおよびほとんどの高度なコミュニティフィルタはバックバッファをサンプルします。WebGL ではレンダラーが useBackBuffer: true で初期化された場合のみ機能します。そうでない場合、PixiJS は警告をログし、フィルタはサイレントにフォールバックします:

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

WebGPU はバックバッファを無条件に有効にするため、これは WebGL にのみ影響します。

[MEDIUM] 既知のサイズのコンテナに対して filterArea を設定していない

filterArea がないと、PixiJS は getGlobalBounds() を使用してフレームごとにコンテナバウンドを測定します。これはすべての子を再帰的に歩みます。既知の寸法を持つコンテナの場合、このコストを回避するために filterArea を設定してください:

import { Rectangle } from "pixi.js";

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

API リファレンス

• Filter
• AlphaFilter
• BlurFilter
• BlurFilterPass
• ColorMatrixFilter
• DisplacementFilter
• NoiseFilter
• FilterSystem