pixijs-blend-modes

container.blendMode を設定して、GPU ブレンド式（標準モード）またはフィルタベースの高度なモードでディスプレイオブジェクトをコンポジットします。ブレンドモードの遷移はレンダリングバッチを破るため、同じモードのシブリングをグループ化してください。

クイックスタート

const light = new Sprite(await Assets.load("light.png"));
light.blendMode = "add";
app.stage.addChild(light);

const shadow = new Sprite(await Assets.load("shadow.png"));
shadow.blendMode = "multiply";
app.stage.addChild(shadow);

import "pixi.js/advanced-blend-modes";
const overlay = new Sprite(await Assets.load("overlay.png"));
overlay.blendMode = "color-burn";
app.stage.addChild(overlay);

関連スキル: pixijs-filters（高度なモードはフィルタパイプラインを使用）、pixijs-performance（ブレンドモードのバッチ処理）、pixijs-color（色操作）。

コアパターン

標準ブレンドモード

標準モードは組み込まれており、GPU ブレンド式を直接使用します:

import { Sprite } from "pixi.js";

sprite.blendMode = "normal"; // 標準的なアルファコンポジット（ルートで実質的なデフォルト）
sprite.blendMode = "add"; // 加算（明るくする、グロー効果）
sprite.blendMode = "multiply"; // 乗算（暗くする、影効果）
sprite.blendMode = "screen"; // スクリーン（明るくする、ドッジ効果）
sprite.blendMode = "erase"; // レンダーターゲットからピクセルを消去
sprite.blendMode = "none"; // ブレンディングなし、目的地を上書き
sprite.blendMode = "inherit"; // 親から継承（これが実際のデフォルト値）
sprite.blendMode = "min"; // ソースと目的地の最小値を保持（WebGL2+ のみ）
sprite.blendMode = "max"; // ソースと目的地の最大値を保持（WebGL2+ のみ）

これらはハードウェアアクセラレーション対応で、コストが低くなります。フィルタは必要ありません。

高度なブレンドモード

高度なモードは明示的なインポートが必要で、拡張機能を登録します。WebGL レンダラーでは初期化時に useBackBuffer: true も必要です。そうでない場合、PixiJS は警告をログし、ブレンドは静かに標準モードに戻ります:

import "pixi.js/advanced-blend-modes";
import { Application, Sprite, Assets } from "pixi.js";

const app = new Application();
await app.init({ useBackBuffer: true }); // WebGL での高度なモードに必須

const texture = await Assets.load("overlay.png");
const overlay = new Sprite(texture);
overlay.blendMode = "color-burn";

利用可能な高度なモード:

モード	効果
color-burn	コントラストを増加させて暗くする
color-dodge	コントラストを減少させて明るくする
darken	2 つのレイヤーの暗い方を保持
difference	絶対差
divide	下部を上部で割る
exclusion	差に類似、低コントラスト
hard-light	上部レイヤーに基づいて乗算またはスクリーン
hard-mix	高コントラスト閾値ブレンド
lighten	2 つのレイヤーの明るい方を保持
linear-burn	加算と減算で暗くする
linear-dodge	レイヤーを加算で合成
linear-light	上部レイヤーに基づいてリニアバーンまたはドッジ
luminosity	上部の輝度、下部の色相・彩度
negation	反転差
overlay	下部レイヤーに基づいて乗算またはスクリーン
pin-light	明るさ比較に基づいて置換
saturation	上部の彩度、下部の色相・輝度
soft-light	ソフトなオーバーレイ効果
subtract	上部から下部を減算
vivid-light	上部レイヤーに基づいてカラーバーンまたはドッジ
color	上部の色相と彩度、下部の輝度

高度なブレンドモードは標準モードと同じように blendMode プロパティで設定します。内部的にフィルタを使用するため、標準モードより多くのコストがかかります。

バッチ効率的な順序付け

異なるブレンドモードはレンダリングバッチを破ります。遷移を最小化するようにオブジェクトを順序付けます:

import { Container, Sprite } from "pixi.js";

const scene = new Container();
scene.addChild(screenSprite1); // 'screen'
scene.addChild(screenSprite2); // 'screen'
scene.addChild(normalSprite1); // 'normal'
scene.addChild(normalSprite2); // 'normal'

2 つの描画呼び出し。交互の順序（screen, normal, screen, normal）は 4 つを生成します。

よくある間違い

[HIGH] advanced-blend-modes 拡張機能のインポート忘れ

間違い:

import { Sprite } from "pixi.js";

sprite.blendMode = "color-burn"; // 静かに標準モードに戻る

正解:

import "pixi.js/advanced-blend-modes";
import { Sprite } from "pixi.js";

sprite.blendMode = "color-burn";

高度なブレンドモード（color-burn、overlay など）は拡張機能のインポートが必要です。インポートがない場合、標準モード（normal、add、multiply、screen）のみが利用可能です。無効なモードは静かに戻ります。

[MEDIUM] 隣接するオブジェクト間でのブレンドモード混在

異なるブレンドモードはレンダリングバッチを破ります。screen / normal / screen / normal は 4 つの描画呼び出しを生成し、screen / screen / normal / normal は 2 つを生成します。子要素を並べ替えて、同じブレンドモードのオブジェクトを隣接させます。

[HIGH] v7 BLEND_MODES enum の使用

間違い:

import { BLEND_MODES } from "pixi.js";

sprite.blendMode = BLEND_MODES.ADD; // ランタイムエラー: BLEND_MODES は未定義

正解:

sprite.blendMode = "add";

v8 では、BLEND_MODES は TypeScript の型のみ（文字列リテラルのユニオン）です。ランタイム enum エクスポートはないため、BLEND_MODES.ADD は undefined のプロパティにアクセスします。文字列形式を使用してください。

[HIGH] useBackBuffer なしでの高度なブレンドモード

間違い:

import "pixi.js/advanced-blend-modes";
await app.init({
  /* no useBackBuffer */
});
sprite.blendMode = "color-burn"; // 警告をログ、戻る

正解:

import "pixi.js/advanced-blend-modes";
await app.init({ useBackBuffer: true });
sprite.blendMode = "color-burn";

高度なモードはバックバッファから読み込みます。WebGL では、バックバッファが有効でない場合、ブレンドは静かに戻ります。WebGPU はバックバッファを無条件で有効にします。

API リファレンス

• Container.blendMode
• OverlayBlend
• ColorBurnBlend
• ColorDodgeBlend
• HardLightBlend
• SoftLightBlend
• DifferenceBlend