filters-and-postfx

用途

本技能用于在 Phaser 4 中为游戏对象或相机应用视觉滤镜与后处理效果。滤镜是基于 GPU 的后处理效果，在对象或相机渲染到纹理之后运行，每个滤镜对该纹理执行一次着色器处理，产生最终视觉输出。滤镜仅支持 WebGL。

主要能力

Phaser 4 提供丰富的内置滤镜，通过 FilterList 的工厂方法添加，包括：

Barrel（桶形畸变/挤压膨胀）
Blend（按混合模式混合另一纹理）
Blocky（保留原色的像素化）
Blur（高斯模糊）
Bokeh（景深散景模糊）
ColorMatrix（颜色矩阵，支持 sepia、grayscale、brightness、hue、saturate、contrast、negative、night、lsd、brown、vintagePinhole、kodachrome、technicolor、polaroid 等预设）
CombineColorMatrix（合并两个纹理的通道）
Displacement（使用置换贴图进行像素位移）
Glow（边缘发光，支持内外发光与 knockout）
GradientMap（基于亮度用 ColorRamp 重新着色）
ImageLight（基于全景环境贴图与法线贴图的图像光照）
Key（色度键，移除或隔离特定颜色）
Mask（通过纹理或游戏对象的 alpha 通道遮罩）
NormalTools（操作法线贴图）
PanoramaBlur（全景球面校正模糊，非常慢）
ParallelFilters（将输入分为两条路径处理后混合，用于自定义泛光）
Pixelate（马赛克/像素化，会混合颜色）
Quantize（减少调色板，支持 RGBA/HSVA、gamma、抖动）
Sampler（提取像素数据，不改变图像，开销大）
Shadow（带偏移、衰减、颜色的投影）
Threshold（逐通道二值阈值）
TiltShift（微缩/移轴效果）
Vignette（边缘变暗/着色，支持 NORMAL、ADD、MULTIPLY、SCREEN 混合模式）
Wipe（擦除/揭示过渡，可通过 tween 动画化 progress）

使用方式

相机默认已启用滤镜，可直接访问 camera.filters.internal 与 camera.filters.external。游戏对象（精灵、图像、容器等）必须先调用 enableFilters() 才能访问 filters。

示例：为精灵添加辉光

const sprite = this.add.sprite(400, 300, 'player');
sprite.enableFilters();
sprite.filters.internal.addGlow(0xff00ff, 4, 0, 1);

示例：为相机添加模糊

const camera = this.cameras.main;
camera.filters.internal.addBlur(0, 2, 2, 1);

每个 FilterList 暴露 filters.internal 与 filters.external 两个子列表。内部滤镜在相机变换之前应用，作用于对象局部坐标空间，仅覆盖对象/相机区域，开销更低；外部滤镜在相机变换之后应用，作用于屏幕空间，为全屏效果，开销更高。应尽可能使用内部滤镜以提升性能。

滤镜按列表顺序依次执行，前一个滤镜的输出作为下一个的输入。可通过 Controller 的 active 属性或 setActive() 临时开关滤镜，通过 remove() 移除并销毁，通过 clear() 清空全部。

遮罩在 v4 中通过滤镜实现，可使用纹理键或游戏对象作为遮罩源，支持 invert、autoUpdate、needsUpdate、viewCamera、viewTransform、scaleFactor 等控制。

ParallelFilters 可将输入分为两条路径独立处理后混合，用于替代 v3 的专用 Bloom 滤镜（配合 Threshold + Blur + ADD 混合）。

CaptureFrame 可在显示列表中捕获当前渲染状态，需相机启用 setForceComposite(true)。

适用场景

适用于 Phaser 4 游戏开发中的视觉增强，如角色发光、场景模糊、颜色分级、屏幕过渡（擦除/揭示）、遮罩裁剪、像素化风格、投影、移轴微缩效果、自定义泛光等。

限制

仅支持 WebGL，Canvas 渲染器下滤镜不工作，enableFilters() 在无 WebGL 时提前返回。
游戏对象必须调用 enableFilters()，相机默认可用。
每个带活动滤镜的对象会产生额外绘制调用，需谨慎使用并尽早做性能测试。
内部与外部滤镜的选择会影响效果表现与性能。
滤镜顺序影响最终结果。
Glow 滤镜的 quality 与 distance 创建后不可更改，需销毁重建。
CaptureFrame 需要相机启用 forceComposite。
模糊、辉光、阴影等扩展效果会自动计算 padding，可用 setPaddingOverride() 覆盖，传 null 清除。
Controller 默认随 FilterList 销毁，设置 ignoreDestroy = true 可复用，但需手动管理生命周期，最适合外部滤镜。
使用游戏对象作为遮罩源时，若 autoUpdate 为 true 则每帧渲染到 DynamicTexture，静态遮罩可设 autoUpdate = false 并用 needsUpdate = true 做一次性更新。
v4 没有专用 Bloom 滤镜，需用 ParallelFilters 配合 Threshold + Blur + ADD 混合，或使用 Phaser.Actions.AddEffectBloom 自动化。

v3 到 v4 的变化

gameObject.preFX / gameObject.postFX 被 gameObject.filters.internal / gameObject.filters.external 取代。
camera.postFX 被 camera.filters.internal / camera.filters.external 取代，相机现在同时拥有内部与外部列表。
FX.addBloom() 被 ParallelFilters + Threshold + Blur 取代。
FX.addCircle() 被移除，改用 Vignette 或圆形 Mask。

技能介绍

用途

主要能力

使用方式

适用场景

限制

v3 到 v4 的变化