企业官网建设流程全解析

Phaser 4 Filters 与 Post-FX 完整指南：从 Glow、Blur 到自定义 Bloom 的 GPU 后处理管线

【免费下载链接】phaserPhaser is a fun, free and fast 2D game framework for making HTML5 games for desktop and mobile web browsers, supporting Canvas and WebGL rendering.项目地址: https://gitcode.com/gh_mirrors/ph/phaser

导读

本文是 Phaser 4（当前仓库gh_mirrors/ph/phaser）中滤镜与后期处理（Post-FX）系统的完整实战指南。Phaser 4 用一套统一的 GPU 滤镜管线取代了 Phaser 3 的 FX 系统：摄像机与游戏对象均可挂载内部/外部两类滤镜列表，通过FilterList与Phaser.Filters.Controller组织二十余种内置滤镜（辉光、高斯模糊、色阶矩阵、桶形畸变、置换、色键抠像、遮罩、擦除转场等），并可用ParallelFilters自由组合出自定义 Bloom。读完本文，你将掌握：如何为游戏对象开启滤镜、如何区分并正确选用 internal/external 滤镜、如何串联多个滤镜、如何用 Mask 实现遮罩、如何用 Wipe 制作转场，以及如何用源码级视角理解滤镜的渲染管线与性能开销。

本文以仓库内技能文档 skills/filters-and-postfx/SKILL.md 为骨架，并结合src/filters/、src/gameobjects/components/下的实现源码与tests/filters/中的测试用例进行深度佐证。

快速上手

在 Scene 的create()方法中，为精灵添加辉光（Glow）效果：

const sprite = this.add.sprite(400, 300, 'player'); // 第 1 步：为游戏对象开启滤镜系统（仅 WebGL） sprite.enableFilters(); // 第 2 步：通过 .filters.internal 或 .filters.external 添加滤镜 sprite.filters.internal.addGlow(0xff00ff, 4, 0, 1);

为摄像机添加模糊效果则更简单——摄像机默认就开启了滤镜，无需调用enableFilters()：

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

核心概念：v4 的滤镜是如何工作的

滤镜即 GPU 后处理

滤镜（Filter）是基于 GPU 的后处理效果：对象或摄像机先渲染到一张纹理上，然后每个滤镜对这张纹理执行一次着色器（shader）通道，最终生成视觉输出。滤镜仅在 WebGL 渲染器下可用。

带滤镜的摄像机完整渲染管线如下（该流程同时记录在 FilterList.js 源码注释 中）：

1. 场景对象渲染到一张与摄像机等大的纹理；
2. 内部滤镜（Internal filters）处理该纹理，在对象/摄像机局部空间施加效果（纹理尺寸可能因模糊等效果而扩展）；
3. 纹理被绘制到一张与上下文（context）等大的纹理上，同时应用摄像机自身的变换（位置、旋转、缩放）；
4. 外部滤镜（External filters）处理该上下文纹理，在屏幕空间施加效果（同样可按需扩展）；
5. 最终纹理合成到输出。

Internal 与 External 的区别

每个FilterList都暴露两个子列表：filters.internal与filters.external。二者的本质区别是滤镜相对于摄像机/对象变换的执行时机：

一个典型例子：对一个旋转 45° 的游戏对象施加水平模糊——

• 使用internal滤镜时，模糊会随对象一起旋转 45°；
• 使用external滤镜时，模糊始终在屏幕上保持水平。

尽量优先使用 internal 滤镜以获得更好性能（这一点在 FilterList 源码注释 中也有明确建议）。

FilterList：滤镜容器

FilterList（Phaser.GameObjects.Components.FilterList）是持有滤镜控制器的容器，位于 src/gameobjects/components/FilterList.js。它提供的核心 API：

• add(filter, index)—— 添加一个 Controller 实例，可选插入位置（索引为负时从尾部倒数插入，见源码splice逻辑）；
• remove(filter, forceDestroy)—— 移除并销毁滤镜；forceDestroy=true时即使设置了ignoreDestroy也会强制销毁；
• clear()—— 移除并销毁全部滤镜（ignoreDestroy的滤镜除外）；
• getActive()—— 返回所有active === true的滤镜（内部通过list.filter(isActive)实现）；
• list—— 原始 Controller 数组，可直接调整顺序（重排是安全的）；
• 便捷工厂方法：addBlur()、addGlow()、addMask()等（每个滤镜类型对应一个）。

Filter Controller：每个滤镜的控制器

每个滤镜都是Phaser.Filters.Controller的子类，基类实现位于 src/filters/Controller.js。常用属性：

关键方法：setActive(bool)、setPaddingOverride(left, top, right, bottom)（传null清除、不传参则置 0）、getPadding()、destroy()（置空renderNode与camera引用）。

源码细节：getPadding()返回paddingOverride || currentPadding；渲染时通过getPaddingCeil()对 padding 做Math.ceil取整并写入currentPadding，避免非整数造成质量损失（见 Controller.js）。

为游戏对象开启滤镜

摄像机默认可用滤镜，游戏对象则必须显式调用enableFilters()：

const sprite = this.add.sprite(400, 300, 'hero'); sprite.enableFilters(); // 现在 sprite.filters 可用 sprite.filters.internal.addGlow(); sprite.filters.external.addVignette();

enableFilters()的实现位于 src/gameobjects/components/Filters.js，它的具体行为包括：

• WebGL 检测：若!this.scene.renderer.gl则直接返回this，在 Canvas 渲染器下静默失效；
• 惰性加载并创建内部filterCamera（new Camera(0, 0, 1, 1).setScene(scene, false)），并设置isObjectInversion = true以计算对象的逆矩阵；
• 同步roundPixels配置（全局roundPixels开启时跟随，避免非整数坐标导致抗锯齿模糊）；
• 初始化maxFilterSize：默认取渲染器的getMaxTextureSize()（WebGL 下硬件上限至少为 4096），可用更小值节省内存或阻止纹理扩容；
• 为无明确边界的对象（无getBounds、宽高为 0 或未定义）自动开启filtersFocusContext = true；
• 通过addRenderStep(this.renderWebGLFilters, renderWebGLIndex)把滤镜渲染注册为紧邻renderWebGL之前的渲染步骤。

开启后，游戏对象上出现以下相关属性：

可用willRenderFilters()判断是否真的有活动滤镜会执行渲染——其逻辑为renderFilters && filters && (internal 或 external 有活动滤镜 || filtersForceComposite)（见 Filters.js）。

源码机制：renderWebGLFilters渲染步骤会先执行focusFilters()（自动聚焦，把滤镜摄像机尺寸设为对象尺寸并同步旋转/缩放/原点，处理 flipX/flipY），再通过renderer.cameraRenderNode.run(...)将对象渲染到帧缓冲，最后把滤镜摄像机的渲染列表并入当前绘制上下文的渲染列表。临时将对象的scrollFactor置 1 是刻意设计——scrollFactor 会被烘焙进变换矩阵，无法用于精确聚焦（见 Filters.js）。

手动聚焦也提供了 API：focusFiltersOverride(x, y, width, height)可自定义聚焦位置与尺寸，调用后会关闭filtersAutoFocus；setFiltersAutoFocus(value)、setFiltersFocusContext(value)、setFiltersForceComposite(value)、setRenderFilters(value)则提供了对应属性的链式 setter。

常见实战模式

给游戏对象叠加滤镜

const sprite = this.add.sprite(400, 300, 'enemy'); sprite.enableFilters(); // 添加辉光 const glow = sprite.filters.internal.addGlow(0x00ff00, 4); // 运行时修改 glow.outerStrength = 8; glow.color = 0xff0000; // 临时停用（不删除） glow.setActive(false); // 移除并销毁 sprite.filters.internal.remove(glow);

摄像机滤镜

const camera = this.cameras.main; // Internal：效果处于摄像机局部空间 const blur = camera.filters.internal.addBlur(0, 2, 2, 1); // External：效果处于屏幕空间 const vignette = camera.filters.external.addVignette(0.5, 0.5, 0.5, 0.5); // 通过 ColorMatrix 做调色 const cm = camera.filters.internal.addColorMatrix(); cm.colorMatrix.sepia();

串联多个滤镜（链式处理）

滤镜按列表顺序依次执行，每个滤镜接收上一个滤镜的输出：

const cam = this.cameras.main; // 第一层：调色 const cm = cam.filters.internal.addColorMatrix(); cm.colorMatrix.brightness(0.2); // 第二层：对调色结果做模糊 cam.filters.internal.addBlur(1, 2, 2, 1); // 第三层：顶部叠加暗角 cam.filters.external.addVignette(0.5, 0.5, 0.5, 0.8);

用滤镜实现遮罩（Mask）

v4 中遮罩本身就是滤镜——利用纹理或游戏对象的 alpha 通道控制可见性（见 Mask.js 源码注释 与 FilterList.js 中 addMask 的 JSDoc）：

// 用静态纹理做遮罩 sprite.enableFilters(); sprite.filters.internal.addMask('maskTexture'); // 用游戏对象做遮罩（自动渲染到 DynamicTexture） const maskShape = this.add.circle(0, 0, 100, 0xffffff); sprite.enableFilters(); const mask = sprite.filters.internal.addMask(maskShape); // 反转遮罩 mask.invert = true; // 控制游戏对象遮罩的自动更新 mask.autoUpdate = true; // 默认：每帧重新渲染 mask.needsUpdate = true; // 强制一次性更新 // 指定渲染遮罩对象所用的摄像机 sprite.filters.external.addMask(maskShape, false, this.cameras.main);

遮罩语义：internal 遮罩匹配被过滤的对象（适合跟随动画精灵的效果）；external 遮罩匹配摄像机上下文（适合覆盖整个视图的效果）。viewCamera参数控制遮罩游戏对象由哪个摄像机渲染（不指定时使用场景主摄像机）。

源码与测试佐证：Mask控制器使用游戏对象时会把对象捕获（capture）到DynamicTexture。测试 tests/filters/Mask.test.js 验证了：maskGameObject的更新会置needsUpdate = true；scaleFactor = 2时 DynamicTexture 尺寸翻倍（100 → 200）；viewTransform: 'local'会被透传到 capture 选项；destroy()会清理 DynamicTexture 并置空引用。

Wipe / Reveal 转场

const camera = this.cameras.main; const wipe = camera.filters.external.addWipe(0.1, 0, 0); // 用 Tween 驱动 progress 动画 this.tweens.add({ targets: wipe, progress: 1, duration: 2000, ease: 'Linear' }); // 方向辅助方法 wipe.setLeftToRight(); wipe.setTopToBottom(); wipe.setRevealEffect(); // 揭示模式（reveal） wipe.setWipeEffect(); // 擦除模式（wipe） // 擦除到另一张纹理（用于场景转场） wipe.setTexture('nextSceneCapture');

addWipe的参数组合（direction/axis）决定方向：左→右为 (0,0)、右→左为 (1,0)、上→下为 (0,1)、下→上为 (1,1)（见 FilterList.js 中 addWipe 的 JSDoc）。

ParallelFilters：自定义 Bloom 与合成

ParallelFilters将输入拆分为两条独立路径分别处理，最后混合结果。它取代了 v3 的专用 Bloom 滤镜。其实现位于 src/filters/ParallelFilters.js：

• 自身是一个 Controller（renderNode为'FilterParallelFilters'），内部持有两个FilterList（top与bottom）和一个Blend控制器（blend）；
• top输出作为混合纹理叠加到bottom输出上；任一路径为空时与原始输入混合（可用于保留会被滤镜过程丢失的原始图像数据）；
• 由于ParallelFilters与FilterList存在循环依赖，addParallelFilters()工厂方法是注入到FilterList.prototype上的，而非直接写在 FilterList 类中（见 ParallelFilters.js）。测试 tests/filters/ParallelFilters.test.js 验证了该方法的存在、返回类型、入列行为以及 top/bottom/blend 三者相互独立。

const camera = this.cameras.main; const pf = camera.filters.internal.addParallelFilters(); // 顶部分支：先阈值化提亮区域，再模糊 pf.top.addThreshold(0.5, 1); pf.top.addBlur(); // 配置混合（top 如何叠加到 bottom） pf.blend.blendMode = Phaser.BlendModes.ADD; pf.blend.amount = 0.5; // 底部分支留空 = 使用原始输入

性能提示：ParallelFilters 并非并行加速，而是复用输入的便捷手段，这点在源码注释中明确说明："It does not gain performance benefits from parallel processing"（见 ParallelFilters.js）。

如果不想手搭，可直接使用自动化 ActionPhaser.Actions.AddEffectBloom。它的实现位于 src/actions/AddEffectBloom.js，内部正是按"ParallelFilters + Threshold + Blur + ADD 混合"的方式构建 Bloom，并返回{ item, parallelFilters, threshold, blur }对象数组供进一步控制：

// 对场景摄像机应用 Bloom Phaser.Actions.AddEffectBloom(this.cameras.main); // 访问组成 Bloom 的滤镜并销毁 const { parallelFilters, threshold, blur } = Phaser.Actions.AddEffectBloom(this.cameras.main)[0]; parallelFilters.destroy();

其配置项及默认值（见源码第 80-85 行）：threshold=0.5、blurRadius=2、blurSteps=4、blurQuality=0、blendAmount=1、blendMode=ADD，另有useInternal开关决定挂到 internal 还是 external 列表。Bloom 最适合全屏效果——若用在带透明区域的游戏对象上，ADD 混合的光晕无法与背景正确混合（源码注释已说明此限制）。

CaptureFrame：场景级效果

CaptureFrame在显示列表中的位置即捕获点：它之前渲染的对象会被捕获，之后的对象不会：

// 需要摄像机处于合成（composite）模式 this.cameras.main.setForceComposite(true); // 在 CaptureFrame 之前渲染的对象会被捕获 const bg = this.add.image(400, 300, 'background'); // 创建捕获点 const capture = this.add.captureFrame('myCapture'); // 用滤镜显示捕获到的纹理 const display = this.add.image(400, 300, 'myCapture'); display.enableFilters(); display.filters.internal.addBlur(0, 4, 4, 2);

全部内置滤镜一览

以下为FilterList提供的全部工厂方法（参数默认值与取值范围均依据 FilterList.js 源码）：

API 速查

开启与访问滤镜

// 游戏对象：必须先 enableFilters() gameObject.enableFilters(); gameObject.filters.internal.addBlur(); gameObject.filters.external.addGlow(); // 摄像机：立即可用 camera.filters.internal.addBlur(); camera.filters.external.addGlow();

FilterList 方法

const list = camera.filters.internal; list.addBlur(); // 工厂方法（每种滤镜一个） list.add(controllerInstance); // 添加预构建的控制器 list.add(controller, 2); // 插入到索引 2 list.remove(controller); // 移除并销毁 list.clear(); // 移除并销毁全部 list.getActive(); // 获取所有活动控制器 list.list; // 原始数组（可安全重排）

Controller 通用 API

controller.active = false; // 停用但不移除 controller.setActive(true); // 启用（链式返回 this） controller.setPaddingOverride(10, 10, 10, 10); // 覆盖 padding controller.setPaddingOverride(null); // 清除覆盖 controller.ignoreDestroy = true; // 在 FilterList.destroy() 时存活 controller.destroy(); // 手动清理

Mask 滤镜 API

const mask = list.addMask('texKey'); // 按纹理 key const mask = list.addMask(gameObject); // 按游戏对象 mask.invert = true; // 反转遮罩 mask.autoUpdate = false; // 停止自动更新 GO 遮罩 mask.needsUpdate = true; // 强制更新一次 mask.setTexture('newKey'); // 更换纹理源 mask.setGameObject(newGO); // 更换 GO 源 mask.viewCamera = otherCamera; // 渲染 GO 的摄像机 mask.viewTransform = 'local'; // 'local' 或 'world' mask.scaleFactor = 0.5; // 遮罩纹理缩放

源码细节：setTexture仅在纹理存在时替换glTexture并清除maskGameObject；setGameObject会置needsUpdate = true并清除纹理引用（测试 tests/filters/Mask.test.js 对不存在纹理、链式返回等边界均有覆盖）。

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();

易踩的坑（Gotchas）

1. 仅 WebGL：Canvas 渲染器下滤镜不可用，enableFilters()检测到无 WebGL 会提前返回（见 Filters.js）。
2. 游戏对象必须enableFilters()：摄像机默认可用；精灵、图片、容器等对象必须先开启才能访问filters。
3. 性能开销：每个带活动滤镜的对象都会产生额外绘制调用（基础渲染一次 + 每个活动滤镜一次）。源码注释明确提醒"可以很昂贵，请节制使用"（见 Filters.js 顶部 JSDoc）。应尽早做性能测试。
4. internal/external 选择很重要：internal 更便宜（对象区域大小），external 是全屏。需要随对象旋转的模糊必须用 internal；需要保持屏幕对齐的模糊必须用 external。
5. 滤镜顺序影响结果：滤镜按列表顺序依次执行，前一个的输出是后一个的输入。
6. Glow 的 quality 与 distance 不可变：创建后无法修改，只能销毁重建（源码中二者为@readonly，见 Glow.js）。
7. CaptureFrame 需要 forceComposite：摄像机必须setForceComposite(true)或以其他方式渲染到帧缓冲，CaptureFrame 才能工作。
8. 向外扩张效果的 padding：Blur、Glow、Shadow 等滤镜会自动计算 padding 以扩展渲染纹理；可用setPaddingOverride()覆盖，传null清除。用于摄像机时，用camera.getPaddingWrapper(x)渲染图像边缘之外的世界。
9. 控制器复用：默认控制器会随 FilterList 销毁而销毁；设置ignoreDestroy = true可跨对象复用，但生命周期需自行管理，且最好用于 external 滤镜（源码注释：一个 Controller 不要同时用于多个摄像机，否则销毁一个拥有者时控制器也会被销毁，见 Controller.js）。
10. 遮罩游戏对象的渲染：autoUpdate = true时遮罩对象每帧渲染到 DynamicTexture；静态遮罩建议autoUpdate = false+needsUpdate = true做一次性更新以提升性能。
11. v4 没有独立 Bloom 滤镜：使用 ParallelFilters（Threshold + Blur + ADD 混合）自行搭建，或直接用Phaser.Actions.AddEffectBloom自动化（源码见 src/actions/AddEffectBloom.js）。圆形遮罩可交给Phaser.Actions.AddMaskShape（实现见 src/actions/AddMaskShape.js，支持 circle/square/rectangle/ellipse 四种形状与可选模糊软边）。

从 v3 迁移：FX → Filters 的变化对照

源码地图

进一步的配套阅读可参考仓库内的 sprites-and-images 技能文档、cameras 技能文档 与 v4-new-features 技能文档。

【免费下载链接】phaserPhaser is a fun, free and fast 2D game framework for making HTML5 games for desktop and mobile web browsers, supporting Canvas and WebGL rendering.项目地址: https://gitcode.com/gh_mirrors/ph/phaser