filters-and-postfx

Phaser 4 のフィルターとポストFX

クイックスタート

スプライトにグロー効果を追加します:

// In your Scene's create() method:
const sprite = this.add.sprite(400, 300, 'player');

// Step 1: Enable the filter system on the game object (WebGL only)
sprite.enableFilters();

// Step 2: Add filters via .filters.internal or .filters.external
sprite.filters.internal.addGlow(0xff00ff, 4, 0, 1);

カメラにブラーを追加します:

// Cameras have filters enabled by default - no enableFilters() needed
const camera = this.cameras.main;
camera.filters.internal.addBlur(0, 2, 2, 1);

---

基本概念

v4 でのフィルターの仕組み

フィルターは、オブジェクトまたはカメラがテクスチャにレンダリングされた後に適用される、GPU ベースのポストプロセッシング効果です。各フィルターはそのテクスチャに対してシェーダーパスを実行し、最終的な視覚出力を生成します。フィルターは WebGL 専用です。

フィルターを適用したカメラのレンダリングパイプライン:

1. オブジェクトがカメラと同じサイズのテクスチャにレンダリングされます。
2. 内部フィルターがそのテクスチャを処理し、オブジェクト/カメラのローカル空間で効果を適用します。
3. テクスチャがコンテキストサイズのテクスチャに描画され、カメラの変換(位置、回転、ズーム)が適用されます。
4. 外部フィルターがそのコンテキストテクスチャを処理し、スクリーン空間で効果を適用します。
5. 最終的なテクスチャが出力に合成されます。

内部フィルターと外部フィルター

すべての FilterList は filters.internal と filters.external の 2 つのサブリストを公開します。この区別は、カメラ/オブジェクトの変換に対してフィルターが いつ 実行されるかを制御します:

• 内部 -- カメラ変換の前に適用されます。効果はオブジェクトのローカル座標空間で動作します。回転したオブジェクトに対する水平ブラーは、オブジェクトと一緒に回転して表示されます。内部フィルターはオブジェクト/カメラの領域のみをカバーするため、負荷が軽くなります。
• 外部 -- カメラ変換の後に適用されます。効果はスクリーン空間で動作します。回転したオブジェクトに対する水平ブラーは、常に画面上で水平にぼけます。外部フィルターは全画面に適用され、負荷が高くなります。

パフォーマンスを向上させるため、可能な限り内部フィルターを使用してください。

FilterList

FilterList(Phaser.GameObjects.Components.FilterList)は、フィルターコントローラーを保持するコンテナです。以下を提供します:

• add(filter, index) -- オプションのインデックスに Controller インスタンスを追加します
• remove(filter, forceDestroy) -- フィルターを削除して破棄します
• clear() -- すべてのフィルターを削除して破棄します
• getActive() -- active === true であるすべてのフィルターを返します
• list -- Controller の生の配列(並べ替えても安全です)
• 便利なファクトリメソッド: addBlur()、addGlow()、addMask() など

フィルターコントローラー

すべてのフィルターは Phaser.Filters.Controller のサブクラスです。Controller の一般的なプロパティ:

プロパティ	型	説明
active	boolean	フィルターを削除せずにオン/オフを切り替えます
camera	Camera	このフィルターを所有するカメラ
renderNode	string	シェーダーのレンダーノード ID
paddingOverride	Rectangle	自動パディング計算を上書きします
ignoreDestroy	boolean	true の場合、FilterList が破棄されてもフィルターは存続します(再利用のため)

主なメソッド: setActive(bool)、setPaddingOverride(left, top, right, bottom)、getPadding()、destroy()。

ゲームオブジェクトでフィルターを有効にする

カメラではフィルターがデフォルトで利用可能です。ゲームオブジェクトでは利用できません -- 最初に enableFilters() を呼び出す必要があります:

const sprite = this.add.sprite(400, 300, 'hero');
sprite.enableFilters();

// Now sprite.filters is available
sprite.filters.internal.addGlow();
sprite.filters.external.addVignette();

enableFilters() はゲームオブジェクトに内部の filterCamera を作成し、フィルター処理のためにオブジェクトをテクスチャにレンダリングする役割を担います。チェーン用に this を返します。

有効化後のゲームオブジェクトの関連プロパティ:

プロパティ	デフォルト	説明
filterCamera	null -> Camera	フィルターレンダリングに使用される内部カメラ
filters	null -> {internal, external}	FilterList のペアへのアクセス
renderFilters	true	すべてのフィルターレンダリングのマスタートグル
filtersAutoFocus	true	オブジェクトを追従するようにカメラを自動調整します
filtersFocusContext	false	オブジェクトの境界ではなくレンダリングコンテキストにフォーカスします
filtersForceComposite	false	アクティブなフィルターがなくても常にフレームバッファに描画します
maxFilterSize	null -> Vector2	フィルターフレームバッファの最大テクスチャサイズ

アクティブなフィルターが実際にレンダリングされるかどうかを確認するには willRenderFilters() を使用します。

---

一般的なパターン

ゲームオブジェクトにフィルターを追加する

const sprite = this.add.sprite(400, 300, 'enemy');
sprite.enableFilters();

// Add a glow
const glow = sprite.filters.internal.addGlow(0x00ff00, 4);

// Modify at runtime
glow.outerStrength = 8;
glow.color = 0xff0000;

// Temporarily disable
glow.setActive(false);

// Remove and destroy
sprite.filters.internal.remove(glow);

カメラフィルター

const camera = this.cameras.main;

// Internal: effect in camera-local space
const blur = camera.filters.internal.addBlur(0, 2, 2, 1);

// External: effect in screen space
const vignette = camera.filters.external.addVignette(0.5, 0.5, 0.5, 0.5);

// Color grading via ColorMatrix
const cm = camera.filters.internal.addColorMatrix();
cm.colorMatrix.sepia();

複数のフィルターの連鎖

フィルターはリストの順序で実行されます。各フィルターは前のフィルターの出力を受け取ります:

const cam = this.cameras.main;

// First: apply color grading
const cm = cam.filters.internal.addColorMatrix();
cm.colorMatrix.brightness(0.2);

// Second: apply blur to the color-graded result
cam.filters.internal.addBlur(1, 2, 2, 1);

// Third: add a vignette on top
cam.filters.external.addVignette(0.5, 0.5, 0.5, 0.8);

フィルターによるマスク

v4 のマスクはフィルターとして実装されています。テクスチャまたはゲームオブジェクトのアルファチャンネルを使用して可視性を制御します:

// Mask with a static texture
sprite.enableFilters();
sprite.filters.internal.addMask('maskTexture');

// Mask with a game object (renders to DynamicTexture automatically)
const maskShape = this.add.circle(0, 0, 100, 0xffffff);
sprite.enableFilters();
const mask = sprite.filters.internal.addMask(maskShape);

// Invert the mask
mask.invert = true;

// Control auto-updating for game object masks
mask.autoUpdate = true;  // default: re-renders each frame
mask.needsUpdate = true; // force a one-time update

// Use a specific camera for viewing the mask object
sprite.filters.external.addMask(maskShape, false, this.cameras.main);

内部マスクはフィルター対象のオブジェクトに一致します。外部マスクはカメラコンテキストに一致します。viewCamera パラメーターを使用して、どのカメラがマスクのゲームオブジェクトをレンダリングするかを制御します。

ワイプ / リビールトランジション

const camera = this.cameras.main;
const wipe = camera.filters.external.addWipe(0.1, 0, 0);

// Animate via tween
this.tweens.add({
    targets: wipe,
    progress: 1,
    duration: 2000,
    ease: 'Linear'
});

// Direction helpers
wipe.setLeftToRight();
wipe.setTopToBottom();
wipe.setRevealEffect();   // reveal mode
wipe.setWipeEffect();     // wipe mode

// Wipe to another texture (for scene transitions)
wipe.setTexture('nextSceneCapture');

ParallelFilters（カスタムブルームとコンポジット）

ParallelFilters は入力を 2 つのパスに分割し、それぞれを個別に処理してから、結果をブレンドします。これは v3 の専用ブルームフィルターを置き換えるものです:

const camera = this.cameras.main;
const pf = camera.filters.internal.addParallelFilters();

// Top path: threshold bright areas, then blur them
pf.top.addThreshold(0.5, 1);
pf.top.addBlur();

// Configure the blend (how top combines onto bottom)
pf.blend.blendMode = Phaser.BlendModes.ADD;
pf.blend.amount = 0.5;

// Bottom path: left empty = uses original input

シーンレベルのエフェクトのための CaptureFrame

CaptureFrame は、ディスプレイリスト内に現れる時点での現在のレンダリング状態をキャプチャします。その前にレンダリングされたオブジェクトはキャプチャされ、その後にレンダリングされたオブジェクトはキャプチャされません:

// Requires composite mode on the camera
this.cameras.main.setForceComposite(true);

// Objects rendered before CaptureFrame are captured
const bg = this.add.image(400, 300, 'background');

// Create the capture point
const capture = this.add.captureFrame('myCapture');

// Display the captured texture with filters applied
const display = this.add.image(400, 300, 'myCapture');
display.enableFilters();
display.filters.internal.addBlur(0, 4, 4, 2);

---

組み込みフィルター一覧

フィルター	追加メソッド	説明
Barrel	addBarrel(amount)	ピンチ/拡大歪み。amount=1 はニュートラル。
Blend	addBlend(texture, blendMode, amount, color)	ブレンドモードを使用して別のテクスチャをブレンドします。標準 WebGL では利用できないモードをサポートします。
Blocky	addBlocky(config)	元の色を保持するピクセル化（ブレンドなし）。アンチエイリアスなしで最適です。
Blur	addBlur(quality, x, y, strength, color, steps)	ガウスぼかし。品質: 0=低、1=中、2=高。
Bokeh	addBokeh(radius, amount, contrast)	被写界深度ボケぼかしエフェクト。
ColorMatrix	addColorMatrix()	マトリックスによる色操作。セピア、グレースケール、明るさ、色相などには .colorMatrix にアクセスします。
CombineColorMatrix	addCombineColorMatrix(texture)	カラーマトリックスを介して 2 つのテクスチャのチャンネルを結合します。アルファ転送に便利です。
Displacement	addDisplacement(texture, x, y)	ディスプレイスメントマップテクスチャを使用したピクセル変位。値は非常に小さい浮動小数点数です（例: 0.005）。
Glow	addGlow(color, outerStrength, innerStrength, scale, knockout, quality, distance)	エッジ周辺の光るハロー。内側/外側グローとノックアウトモードをサポートします。
GradientMap	addGradientMap(config)	明るさに基づく ColorRamp を使用して画像を再着色します。
ImageLight	addImageLight(config)	パノラマ環境マップとノーマルマップを使用したイメージベースライティング。
Key	addKey(config)	クロマキー: 特定の色を削除または分離します。設定: { color, threshold, feather, isolate }。
Mask	addMask(mask, invert, viewCamera, viewTransform, scaleFactor)	テクスチャまたはゲームオブジェクトによるアルファマスキング。
NormalTools	addNormalTools(config)	ノーマルマップを操作します: 回転、向きパワーの調整、グレースケールの向きデータの出力。
PanoramaBlur	addPanoramaBlur(config)	パノラマ画像用の球面補正ぼかし。ImageLight と併用します。非常に低速です。
ParallelFilters	addParallelFilters()	入力を 2 つのフィルターパスに分割し、結果をブレンドします。カスタムブルームに使用します。
Pixelate	addPixelate(amount)	モザイク/ピクセル化エフェクト。ピクセルサイズ = 2 + amount。色をブレンドします（Blocky とは異なります）。
Quantize	addQuantize(config)	カラーパレットを削減します。RGBA/HSVA モード、ガンマ、オフセット、ディザリングをサポートします。
Sampler	addSampler(callback, region)	レンダリングからピクセルデータを抽出します。画像は変更しません。負荷が高いです。
Shadow	addShadow(x, y, decay, power, color, samples, intensity)	オフセット、減衰、色を指定したドロップシャドウ。
Threshold	addThreshold(edge1, edge2, invert)	チャンネルごとの二値しきい値。エッジはチャンネルごとの制御のために配列にできます。
TiltShift	addTiltShift(radius, amount, contrast, blurX, blurY, strength)	ミニチュア/チルトシフトエフェクト（内部的に Bokeh を使用）。
Vignette	addVignette(x, y, radius, strength, color, blendMode)	エッジの暗化/着色。NORMAL、ADD、MULTIPLY、SCREEN ブレンドモードをサポートします。
Wipe	addWipe(wipeWidth, direction, axis, reveal, wipeTexture)	ワイプ/リビールトランジション。progress をトゥイーンでアニメーション化します。

---

API クイックリファレンス

フィルターの有効化とアクセス

// Game objects: must enable first
gameObject.enableFilters();
gameObject.filters.internal.addBlur();
gameObject.filters.external.addGlow();

// Cameras: filters available immediately
camera.filters.internal.addBlur();
camera.filters.external.addGlow();

FilterList メソッド

const list = camera.filters.internal;

list.addBlur();                    // Factory method (one per filter type)
list.add(controllerInstance);      // Add a pre-built controller
list.add(controller, 2);           // Insert at index 2
list.remove(controller);           // Remove and destroy
list.clear();                      // Remove and destroy all
list.getActive();                  // Get all active controllers
list.list;                         // Raw array (reorder safely)

Controller 共通 API

controller.active = false;                  // Disable without removing
controller.setActive(true);                 // Enable (returns this)
controller.setPaddingOverride(10, 10, 10, 10); // Override padding
controller.setPaddingOverride(null);        // Clear override
controller.ignoreDestroy = true;            // Survive FilterList.destroy()
controller.destroy();                       // Manual cleanup

Mask フィルター API

const mask = list.addMask('texKey');       // From texture key
const mask = list.addMask(gameObject);     // From game object
mask.invert = true;                         // Invert mask
mask.autoUpdate = false;                    // Stop auto-updating GO masks
mask.needsUpdate = true;                    // Force one update
mask.setTexture('newKey');                  // Change texture source
mask.setGameObject(newGO);                 // Change GO source
mask.viewCamera = otherCamera;             // Camera for GO rendering
mask.viewTransform = 'local';              // 'local' or 'world'
mask.scaleFactor = 0.5;                    // Scale mask texture size

ColorMatrix プリセット

const cm = list.addColorMatrix();
cm.colorMatrix.sepia();
cm.colorMatrix.grayscale(1);
cm.colorMatrix.brightness(0.3);
cm.colorMatrix.hue(90);
cm.colorMatrix.saturate(-0.5);
cm.colorMatrix.contrast(0.3);
cm.colorMatrix.blackWhite();
cm.colorMatrix.negative();
cm.colorMatrix.desaturate();
cm.colorMatrix.night(0.5);
cm.colorMatrix.lsd();
cm.colorMatrix.brown();
cm.colorMatrix.vintagePinhole();
cm.colorMatrix.kodachrome();
cm.colorMatrix.technicolor();
cm.colorMatrix.polaroid();
cm.colorMatrix.shiftToBGR();

---

注意点

1. WebGL 専用 -- フィルターは Canvas レンダラーでは動作しません。enableFilters() は WebGL が利用できない場合、早期にリターンします。

2. ゲームオブジェクトには enableFilters() が必要 -- カメラはデフォルトでフィルターを持ちます。スプライト、画像、コンテナ、その他のゲームオブジェクトは、filters にアクセスする前に enableFilters() が必要です。

3. パフォーマンスコスト -- アクティブなフィルターを持つ各オブジェクトは、追加のドローコールを生成します（ベースレンダリング用に 1 つ、アクティブなフィルターごとに 1 つ）。使用は控えめにし、早い段階でパフォーマンステストを行ってください。

4. 内部と外部の違いは重要 -- 内部フィルターはより低コストです（オブジェクト領域サイズ）。外部フィルターは全画面です。オブジェクトと一緒に回転すべきブラーは内部フィルターでなければならず、画面に固定されたままにすべきブラーは外部フィルターでなければなりません。

5. フィルターの順序は重要 -- フィルターはリストの順序で順次適用されます。あるフィルターの出力が次のフィルターに入力されます。

6. Glow の quality と distance は不変 -- Glow フィルターの quality と distance は作成後に変更できません。変更するにはフィルターを破棄して再作成してください。

7. CaptureFrame には forceComposite が必要 -- CaptureFrame が動作するには、カメラに setForceComposite(true) を設定するか、別の方法でフレームバッファにレンダリングする必要があります。

8. 拡大するエフェクトのためのパディング -- Blur、Glow、Shadow などのフィルターは、レンダーテクスチャを拡大するためのパディングを自動的に計算できます。必要に応じて setPaddingOverride() で上書きしてください。オーバーライドをクリアするには null を渡します。カメラで使用する場合は、camera.getPaddingWrapper(x) を使って画像の端の外側のより広いワールドをレンダリングします。

9. コントローラーの再利用 -- デフォルトでは、コントローラーはその FilterList が破棄されるときに破棄されます。複数のオブジェクト間でコントローラーを再利用するには ignoreDestroy = true を設定しますが、ライフサイクルを手動で管理する必要があります。外部フィルターで最もよく機能します。

10. マスクのゲームオブジェクトレンダリング -- ゲームオブジェクトをマスクソースとして使用する場合、毎フレーム DynamicTexture にレンダリングされます（autoUpdate が true の場合）。静的マスクのパフォーマンスを向上させるには、autoUpdate = false を設定し、ワンショット更新には needsUpdate = true を使用します。

11. Bloom フィルターはなし -- v4 には専用の Bloom フィルターがありません。代わりに Threshold + Blur + ADD ブレンドを組み合わせた ParallelFilters を使用するか（一般的なパターンを参照）、Phaser.Actions.AddEffectBloom を使ってプロセスを自動化してください。

---

v3 から v4 への変更点

v3 (FX)	v4 (Filters)	備考
gameObject.preFX / gameObject.postFX	gameObject.filters.internal / gameObject.filters.external	preFX/postFX は内部/外部フィルターリストに置き換えられました
camera.postFX	camera.filters.internal / camera.filters.external	カメラは内部リストと外部リストの両方を持つようになりました
FX.addBloom()	ParallelFilters + Threshold + Blur を使用	専用の Bloom フィルターはなし。ParallelFilters または Phaser.Actions.AddEffectBloom で構築します
FX.addCircle()	Vignette または Mask を使用	Circle エフェクトは削除されました。半径付きの Vignette や円形 Mask を使用するか、Phaser.Actions.AddMaskShape で自動化してください
FX.addGradient()	Gradient GameObject + Quantize を使用	新しい Gradient GameObject がグラデーションをレンダリングします。必要に応じて Quantize でステップを追加できます
Glow の quality は 0〜1 の小数	Glow の quality は整数（デフォルト 10）	ラインサンプリングが確率的サンプリングに置き換えられました。値が低いほど高品質になります
camera.setMask()	camera.filters.internal.addMask()	マスクは独立したシステムではなくフィルターになりました
gameObject.setMask()	gameObject.filters.internal.addMask()	同じ統一されたフィルターシステムです
FX コントローラー	Phaser.Filters.Controller のサブクラス	同じパターン: 可変プロパティを持つコントローラーオブジェクトを返します
--	ゲームオブジェクトには enableFilters() が必要	ゲームオブジェクト向けの新しい明示的なオプトイン手順です
--	Blocky、Quantize、Key、Blend、CombineColorMatrix、ImageLight、NormalTools、PanoramaBlur、ParallelFilters、Sampler	v4 で追加された新しいフィルターです

---

ソースファイルマップ

ファイル	説明
src/gameobjects/components/Filters.js	ゲームオブジェクトに enableFilters()、filterCamera、filters を追加するミックスイン
src/gameobjects/components/FilterList.js	すべての add*() ファクトリメソッドを備えた FilterList クラス
src/filters/Controller.js	すべてのフィルターの基底 Controller クラス
src/filters/Barrel.js	樽型歪みフィルター
src/filters/Blend.js	テクスチャブレンドフィルター
src/filters/Blocky.js	色を保持するピクセレーションフィルター
src/filters/Blur.js	ガウスぼかしフィルター
src/filters/Bokeh.js	ボケ / チルトシフトフィルター
src/filters/ColorMatrix.js	カラーマトリックスフィルター（セピア、グレースケールなど）
src/filters/CombineColorMatrix.js	デュアルテクスチャチャンネル合成フィルター
src/filters/Displacement.js	ディスプレイスメントマップフィルター
src/filters/Glow.js	グロー / アウトラインフィルター
src/filters/GradientMap.js	グラデーションマップ再着色フィルター
src/filters/ImageLight.js	画像ベースライティングフィルター
src/filters/Key.js	クロマキーフィルター
src/filters/Mask.js	アルファマスクフィルター（テクスチャまたはゲームオブジェクト）
src/filters/NormalTools.js	ノーマルマップ操作フィルター
src/filters/PanoramaBlur.js	球面パノラマぼかしフィルター
src/filters/ParallelFilters.js	ブレンド付きの並列フィルターパス
src/filters/Pixelate.js	ピクセレーションフィルター
src/filters/Quantize.js	色量子化フィルター
src/filters/Sampler.js	ピクセルサンプリング / 読み戻しフィルター
src/filters/Shadow.js	ドロップシャドウフィルター
src/filters/Threshold.js	しきい値フィルター
src/filters/Vignette.js	ビネットフィルター
src/filters/Wipe.js	ワイプ / リビールトランジションフィルター
src/gameobjects/captureframe/CaptureFrame.js	シーンレベルのキャプチャ用 CaptureFrame ゲームオブジェクト

---

関連: sprites-and-images.md, cameras.md, v4-new-features.md