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"; // standard alpha compositing (effective default at root)
sprite.blendMode = "add"; // additive (lighten, glow effects)
sprite.blendMode = "multiply"; // multiply (darken, shadow effects)
sprite.blendMode = "screen"; // screen (lighten, dodge effects)
sprite.blendMode = "erase"; // erase pixels from render target
sprite.blendMode = "none"; // no blending, overwrites destination
sprite.blendMode = "inherit"; // inherit from parent (this is the actual default value)
sprite.blendMode = "min"; // keeps minimum of source and destination (WebGL2+ only)
sprite.blendMode = "max"; // keeps maximum of source and destination (WebGL2+ only)

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

高度なブレンドモード

高度なモードでは、拡張機能を登録するための明示的なインポートが必要です。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 }); // required for advanced modes on 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"; // silently falls back to normal

正しい例：

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 列挙型を使用する

誤り：

import { BLEND_MODES } from "pixi.js";

sprite.blendMode = BLEND_MODES.ADD; // runtime error: BLEND_MODES is undefined

正しい例：

sprite.blendMode = "add";

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

[HIGH] useBackBuffer なしで高度なブレンドモードを使用する

誤り：

import "pixi.js/advanced-blend-modes";
await app.init({
  /* no useBackBuffer */
});
sprite.blendMode = "color-burn"; // logs a warning, falls back

正しい例：

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

高度なモードはバックバッファーから読み込みます。WebGL では、バックバッファーが有効でない場合、ブレンドは通知なくフォールバックします。WebGPU ではバックバッファーが常に有効になります。

［MEDIUM］高 DPI レンダラーで高度なブレンドモードがクリップまたは拡大縮小される

高度なブレンドモードはフィルターベースであり、解像度のデフォルト値が 1 の Filter.defaultOptions を使用します。高 DPI のレンダーターゲットでは、ブレンドされたオブジェクトがクリップされたり、拡大縮小されたり、一部にしか適用されていないように見えることがあります。

誤った例：

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

sprite.blendMode = "overlay"; // renders at resolution 1, can clip on retina

正しい例：

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

Filter.defaultOptions.resolution = "inherit"; // set before creating affected objects

sprite.blendMode = "overlay";

Filter.defaultOptions.resolution = "inherit" を設定すると、高度なブレンドモードをレンダーターゲットの解像度で描画できます。メモリ使用量と実行時コストが増えるため、忠実度が重要な箇所に適用してください。

API リファレンス

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