filters-and-postfx

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Phaser 4 Filters and Post-FX

Phaser 4 滤镜与后期特效

Quick Start

快速入门

Add a glow effect to a sprite:

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

Add a blur to the camera:

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

为精灵添加发光效果：

// 在你的场景的create()方法中：
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);

Core Concepts

核心概念

How Filters Work in v4

v4中滤镜的工作方式

Filters are GPU-based post-processing effects applied after an object or camera renders to a texture. Each filter runs a shader pass over that texture, producing the final visual output. Filters are WebGL only.

The rendering pipeline for a camera with filters:

Objects render to a texture the size of the camera.
Internal filters process that texture, applying effects in object/camera local space.
The texture is drawn to a context-sized texture, applying camera transformations (position, rotation, zoom).
External filters process that context texture, applying effects in screen space.
The final texture is composited into the output.

滤镜是基于GPU的后期处理效果，在对象或相机渲染到纹理后应用。每个滤镜会对该纹理执行一次着色器处理，生成最终的视觉输出。滤镜仅支持WebGL。

带滤镜的相机渲染流程：

对象渲染到与相机尺寸一致的纹理上。
内部滤镜处理该纹理，在对象/相机的局部空间中应用效果。
将纹理绘制到与上下文尺寸一致的纹理上，应用相机变换（位置、旋转、缩放）。
外部滤镜处理该上下文纹理，在屏幕空间中应用效果。
将最终纹理合成到输出画面中。

Internal vs External Filters

内部滤镜 vs 外部滤镜

Every

FilterList

exposes two sub-lists:

filters.internal

and

filters.external

. The distinction controls when the filter runs relative to the camera/object transform:

Internal -- applied before the camera transform. Effects operate in the object's local coordinate space. A horizontal blur on a rotated object appears rotated with the object. Internal filters only cover the object/camera region, so they are cheaper.
External -- applied after the camera transform. Effects operate in screen space. A horizontal blur on a rotated object always blurs horizontally on screen. External filters are full-screen and more expensive.

Use internal filters wherever possible for better performance.

每个

FilterList

都包含两个子列表：

filters.internal

和

filters.external

。两者的区别决定了滤镜相对于相机/对象变换的执行时机：

内部滤镜 -- 在相机变换前应用。效果在对象的局部坐标系中生效。对旋转对象应用水平模糊时，模糊效果会随对象一起旋转。内部滤镜仅覆盖对象/相机区域，因此性能开销更低。
外部滤镜 -- 在相机变换后应用。效果在屏幕空间中生效。对旋转对象应用水平模糊时，模糊效果始终沿屏幕水平方向。外部滤镜是全屏的，性能开销更高。

尽可能使用内部滤镜以获得更好的性能。

FilterList

FilterList

(

Phaser.GameObjects.Components.FilterList

) is the container that holds filter controllers. It provides:

```
add(filter, index)
```
-- add a Controller instance at an optional index
```
remove(filter, forceDestroy)
```
-- remove and destroy a filter
```
clear()
```
-- remove and destroy all filters
```
getActive()
```
-- return all filters where
```
active === true
```
```
list
```
-- the raw array of Controllers (safe to reorder)
Convenience factory methods:
```
addBlur()
```
,
```
addGlow()
```
,
```
addMask()
```
, etc.

FilterList

（

Phaser.GameObjects.Components.FilterList

）是存放滤镜控制器的容器，提供以下功能：

```
add(filter, index)
```
-- 在可选索引位置添加一个控制器实例
```
remove(filter, forceDestroy)
```
-- 移除并销毁滤镜
```
clear()
```
-- 移除并销毁所有滤镜
```
getActive()
```
-- 返回所有
```
active === true
```
的滤镜
```
list
```
-- 控制器的原始数组（可安全重新排序）
便捷工厂方法：
```
addBlur()
```
、
```
addGlow()
```
、
```
addMask()
```
等

Filter Controllers

滤镜控制器

Every filter is a

Phaser.Filters.Controller

subclass. Common Controller properties:

Property	Type	Description
`active`	boolean	Toggle the filter on/off without removing it
`camera`	Camera	The camera that owns this filter
`renderNode`	string	The render node ID for the shader
`paddingOverride`	Rectangle	Override automatic padding calculation
`ignoreDestroy`	boolean	If true, the filter survives when its FilterList is destroyed (for reuse)

Key methods:

setActive(bool)

setPaddingOverride(left, top, right, bottom)

getPadding()

destroy()

每个滤镜都是

Phaser.Filters.Controller

的子类。常见控制器属性：

属性	类型	描述
`active`	boolean	在不移除滤镜的情况下切换其开关状态
`camera`	Camera	拥有该滤镜的相机
`renderNode`	string	着色器的渲染节点ID
`paddingOverride`	Rectangle	覆盖自动内边距计算
`ignoreDestroy`	boolean	如果为true，当所属FilterList被销毁时，该滤镜会保留（用于复用）

关键方法：

setActive(bool)

、

setPaddingOverride(left, top, right, bottom)

、

getPadding()

、

destroy()

。

Enabling Filters on Game Objects

在游戏对象上启用滤镜

Cameras have filters available by default. Game objects do not -- you must call

enableFilters()

first:

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

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

enableFilters()

creates an internal

filterCamera

on the game object that handles rendering the object to a texture for filter processing. It returns

this

for chaining.

Related properties on game objects after enabling:

Property	Default	Description
`filterCamera`	null -> Camera	The internal camera used for filter rendering
`filters`	null -> {internal, external}	Access to the FilterList pair
`renderFilters`	true	Master toggle for all filter rendering
`filtersAutoFocus`	true	Auto-adjust camera to follow the object
`filtersFocusContext`	false	Focus on the rendering context instead of the object bounds
`filtersForceComposite`	false	Always draw to a framebuffer even with no active filters
`maxFilterSize`	null -> Vector2	Maximum texture size for filter framebuffers

Use

willRenderFilters()

to check if any active filters will actually render.

相机默认已启用滤镜，而游戏对象则需要先调用

enableFilters()

：

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

// 现在可以访问sprite.filters
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()

检查是否有激活的滤镜会实际渲染。

Common Patterns

常见用法

Adding Filters to Game Objects

为游戏对象添加滤镜

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

Camera Filters

相机滤镜

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 camera = this.cameras.main;

// 内部滤镜：在相机局部空间生效
const blur = camera.filters.internal.addBlur(0, 2, 2, 1);

// 外部滤镜：在屏幕空间生效
const vignette = camera.filters.external.addVignette(0.5, 0.5, 0.5, 0.5);

// 通过ColorMatrix进行颜色分级
const cm = camera.filters.internal.addColorMatrix();
cm.colorMatrix.sepia();

Chaining Multiple Filters

链式添加多个滤镜

Filters execute in list order. Each filter receives the output of the previous one:

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

滤镜按列表顺序执行，每个滤镜的输出作为下一个滤镜的输入：

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

Masks via Filters

通过滤镜实现遮罩

Masks in v4 are implemented as filters. They use the alpha channel of a texture or game object to control visibility:

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

Internal masks match the object being filtered. External masks match the camera context. Use a

viewCamera

parameter to control which camera renders the mask game object.

v4中的遮罩通过滤镜实现，使用纹理或游戏对象的Alpha通道控制可见性：

// 使用静态纹理作为遮罩
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);

内部遮罩与被过滤的对象匹配，外部遮罩与相机上下文匹配。使用

viewCamera

参数控制哪个相机渲染遮罩游戏对象。

Wipe / Reveal Transitions

擦除/显示过渡效果

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

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

// 通过补间动画实现
this.tweens.add({
    targets: wipe,
    progress: 1,
    duration: 2000,
    ease: 'Linear'
});

// 方向辅助方法
wipe.setLeftToRight();
wipe.setTopToBottom();
wipe.setRevealEffect();   // 显示模式
wipe.setWipeEffect();     // 擦除模式

// 擦除到另一张纹理（用于场景过渡）
wipe.setTexture('nextSceneCapture');

ParallelFilters (Custom Bloom and Compositing)

ParallelFilters（自定义Bloom与合成）

ParallelFilters splits the input into two paths, processes each independently, then blends the results. This replaces the dedicated Bloom filter from 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

ParallelFilters将输入分为两条路径，分别独立处理后再混合结果。它取代了v3中的专用Bloom滤镜：

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

// 上方路径：高亮区域阈值化，然后模糊
pf.top.addThreshold(0.5, 1);
pf.top.addBlur();

// 配置混合方式（上方路径如何与下方路径混合）
pf.blend.blendMode = Phaser.BlendModes.ADD;
pf.blend.amount = 0.5;

// 下方路径：留空则使用原始输入

CaptureFrame for Scene-Level Effects

CaptureFrame用于场景级效果

CaptureFrame

captures the current render state at the point it appears in the display list. Objects rendered before it are captured; objects after it are not:

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

CaptureFrame

会捕获其在显示列表中位置的当前渲染状态。在它之前渲染的对象会被捕获，之后的对象则不会：

// 需要相机启用合成模式
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);

All Built-in Filters

所有内置滤镜

Filter	Add Method	Description
Barrel	`addBarrel(amount)`	Pinch/expand distortion. `amount=1` is neutral.
Blend	`addBlend(texture, blendMode, amount, color)`	Blend another texture using a blend mode. Supports modes not available in standard WebGL.
Blocky	`addBlocky(config)`	Pixelation that preserves original colors (no blending). Best without anti-aliasing.
Blur	`addBlur(quality, x, y, strength, color, steps)`	Gaussian blur. Quality: 0=low, 1=medium, 2=high.
Bokeh	`addBokeh(radius, amount, contrast)`	Depth-of-field bokeh blur effect.
ColorMatrix	`addColorMatrix()`	Color manipulation via matrix. Access `.colorMatrix` for sepia, grayscale, brightness, hue, etc.
CombineColorMatrix	`addCombineColorMatrix(texture)`	Combine channels from two textures via color matrices. Useful for alpha transfer.
Displacement	`addDisplacement(texture, x, y)`	Pixel displacement using a displacement map texture. Values are very small floats (e.g. 0.005).
Glow	`addGlow(color, outerStrength, innerStrength, scale, knockout, quality, distance)`	Luminous halo around edges. Supports inner/outer glow and knockout mode.
GradientMap	`addGradientMap(config)`	Recolor image using a ColorRamp based on brightness.
ImageLight	`addImageLight(config)`	Image-based lighting using a panorama environment map and normal map.
Key	`addKey(config)`	Chroma key: remove or isolate a specific color. Config: `{ color, threshold, feather, isolate }` .
Mask	`addMask(mask, invert, viewCamera, viewTransform, scaleFactor)`	Alpha masking via texture or game object.
NormalTools	`addNormalTools(config)`	Manipulate normal maps: rotate, adjust facing power, output grayscale facing data.
PanoramaBlur	`addPanoramaBlur(config)`	Spherically-correct blur for panorama images. For use with ImageLight. Very slow.
ParallelFilters	`addParallelFilters()`	Split input into two filter paths, blend results. Use for custom bloom.
Pixelate	`addPixelate(amount)`	Mosaic/pixelation effect. Pixel size = 2 + amount. Blends colors (unlike Blocky).
Quantize	`addQuantize(config)`	Reduce color palette. Supports RGBA/HSVA modes, gamma, offset, dithering.
Sampler	`addSampler(callback, region)`	Extract pixel data from the render. Does not alter the image. Expensive.
Shadow	`addShadow(x, y, decay, power, color, samples, intensity)`	Drop shadow with offset, decay, and color.
Threshold	`addThreshold(edge1, edge2, invert)`	Binary threshold per channel. Edges can be arrays for per-channel control.
TiltShift	`addTiltShift(radius, amount, contrast, blurX, blurY, strength)`	Miniature/tilt-shift effect (uses Bokeh internally).
Vignette	`addVignette(x, y, radius, strength, color, blendMode)`	Edge darkening/coloring. Supports NORMAL, ADD, MULTIPLY, SCREEN blend modes.
Wipe	`addWipe(wipeWidth, direction, axis, reveal, wipeTexture)`	Wipe/reveal transition. Animate `progress` via tween.

滤镜	添加方法	描述
Barrel	`addBarrel(amount)`	挤压/扩张畸变效果。 `amount=1` 为中性状态。
Blend	`addBlend(texture, blendMode, amount, color)`	使用混合模式混合另一张纹理。支持标准WebGL不具备的混合模式。
Blocky	`addBlocky(config)`	保留原始颜色的像素化效果（无混合）。在禁用抗锯齿时效果最佳。
Blur	`addBlur(quality, x, y, strength, color, steps)`	高斯模糊。Quality：0=低质量，1=中等质量，2=高质量。
Bokeh	`addBokeh(radius, amount, contrast)`	景深散景模糊效果。
ColorMatrix	`addColorMatrix()`	通过矩阵进行颜色调整。访问 `.colorMatrix` 可实现棕褐色调、灰度、亮度、色相等效果。
CombineColorMatrix	`addCombineColorMatrix(texture)`	通过颜色矩阵合并两张纹理的通道。适用于Alpha通道传递。
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)`	通过纹理或游戏对象实现Alpha遮罩。
NormalTools	`addNormalTools(config)`	法线贴图处理：旋转、调整朝向强度、输出灰度朝向数据。
PanoramaBlur	`addPanoramaBlur(config)`	全景图像的球面校正模糊效果。配合ImageLight使用。性能开销极高。
ParallelFilters	`addParallelFilters()`	将输入分为两条滤镜路径，混合结果。用于自定义Bloom效果。
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)`	逐通道二元阈值处理。Edges可为数组以实现逐通道控制。
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 Quick Reference

API快速参考

Enabling and Accessing Filters

启用和访问滤镜

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

// 游戏对象：必须先启用
gameObject.enableFilters();
gameObject.filters.internal.addBlur();
gameObject.filters.external.addGlow();

// 相机：可直接访问滤镜
camera.filters.internal.addBlur();
camera.filters.external.addGlow();

FilterList Methods

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)

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 Common API

控制器通用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

controller.active = false;                  // 禁用滤镜但不移除
controller.setActive(true);                 // 启用滤镜（返回自身）
controller.setPaddingOverride(10, 10, 10, 10); // 覆盖内边距设置
controller.setPaddingOverride(null);        // 清除内边距覆盖
controller.ignoreDestroy = true;            // 在FilterList销毁时保留
controller.destroy();                       // 手动清理

Mask Filter API

遮罩滤镜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

const mask = list.addMask('texKey');       // 通过纹理键创建
const mask = list.addMask(gameObject);     // 通过游戏对象创建
mask.invert = true;                         // 反转遮罩
mask.autoUpdate = false;                    // 停止自动更新游戏对象遮罩
mask.needsUpdate = true;                    // 强制单次更新
mask.setTexture('newKey');                  // 更改纹理源
mask.setGameObject(newGO);                 // 更改游戏对象源
mask.viewCamera = otherCamera;             // 用于渲染游戏对象的相机
mask.viewTransform = 'local';              // 'local'或'world'
mask.scaleFactor = 0.5;                    // 遮罩纹理尺寸缩放因子

ColorMatrix Presets

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

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

注意事项

WebGL only -- Filters do not work in Canvas renderer.
```
enableFilters()
```
returns early if WebGL is not available.
enableFilters() required for game objects -- Cameras have filters by default. Sprites, images, containers, and other game objects require
```
enableFilters()
```
before accessing
```
filters
```
.
Performance cost -- Each object with active filters creates extra draw calls (one for the base render plus one per active filter). Use sparingly and performance test early.
Internal vs external matters -- Internal filters are cheaper (object-region sized). External filters are full-screen. A blur that should rotate with the object must be internal; a blur that should stay screen-aligned must be external.
Filter order matters -- Filters are applied sequentially in list order. The output of one feeds into the next.
Glow quality and distance are immutable --
```
quality
```
and
```
distance
```
on the Glow filter cannot be changed after creation. Destroy and recreate the filter to change them.
CaptureFrame requires forceComposite -- The camera must have
```
setForceComposite(true)
```
or otherwise render into a framebuffer for CaptureFrame to work.
Padding for expanding effects -- Filters like Blur, Glow, and Shadow can automatically calculate padding to expand the render texture. Override with
```
setPaddingOverride()
```
if needed. Pass
```
null
```
to clear the override. When used on a camera, use
```
camera.getPaddingWrapper(x)
```
to render more world outside the image edge.
Controller reuse -- By default, controllers are destroyed when their FilterList is destroyed. Set
```
ignoreDestroy = true
```
to reuse a controller across multiple objects, but you must manage its lifecycle manually. Works best with external filters.
Mask game object rendering -- When using a game object as a mask source, it is rendered to a DynamicTexture each frame (if
```
autoUpdate
```
is true). Set
```
autoUpdate = false
```
and use
```
needsUpdate = true
```
for one-shot updates to improve performance for static masks.
No Bloom filter -- v4 does not have a dedicated Bloom filter. Use ParallelFilters with Threshold + Blur + ADD blend instead (see Common Patterns), or use
```
Phaser.Actions.AddEffectBloom
```
to automate the process.

仅支持WebGL -- 滤镜在Canvas渲染器中无法工作。如果WebGL不可用，
```
enableFilters()
```
会提前返回。
游戏对象需调用enableFilters() -- 相机默认已启用滤镜。精灵、图像、容器及其他游戏对象在访问
```
filters
```
前必须调用
```
enableFilters()
```
。
性能开销 -- 每个带有激活滤镜的对象会增加额外的绘制调用（一次基础渲染加上每个激活滤镜一次调用）。请谨慎使用并尽早进行性能测试。
内部与外部滤镜的区别很重要 -- 内部滤镜开销更低（仅覆盖对象区域），外部滤镜是全屏的。需要随对象旋转的模糊效果必须使用内部滤镜；需要保持屏幕对齐的模糊效果必须使用外部滤镜。
滤镜顺序很重要 -- 滤镜按列表顺序依次应用，前一个滤镜的输出作为后一个的输入。
Glow的quality和distance不可变 -- Glow滤镜的
```
quality
```
和
```
distance
```
参数在创建后无法修改。如需更改，需销毁并重新创建滤镜。
CaptureFrame需要forceComposite -- 相机必须设置
```
setForceComposite(true)
```
或以其他方式渲染到帧缓冲区，CaptureFrame才能正常工作。
扩展效果的内边距 -- Blur、Glow和Shadow等滤镜会自动计算内边距以扩展渲染纹理。如有需要，可使用
```
setPaddingOverride()
```
覆盖。传入
```
null
```
可清除覆盖。在相机上使用时，可通过
```
camera.getPaddingWrapper(x)
```
渲染图像边缘外的更多世界内容。
控制器复用 -- 默认情况下，控制器会在所属FilterList销毁时被销毁。设置
```
ignoreDestroy = true
```
可在多个对象间复用控制器，但需手动管理其生命周期。该方式更适用于外部滤镜。
遮罩游戏对象的渲染 -- 使用游戏对象作为遮罩源时，如果
```
autoUpdate
```
为true，每帧都会将其渲染到DynamicTexture。对于静态遮罩，设置
```
autoUpdate = false
```
并使用
```
needsUpdate = true
```
进行单次更新可提升性能。
无专用Bloom滤镜 -- v4没有专用的Bloom滤镜。可使用ParallelFilters配合Threshold+Blur+ADD混合模式实现（见常见用法），或使用
```
Phaser.Actions.AddEffectBloom
```
自动完成该过程。

v4 Changes from v3

v4与v3的差异

v3 (FX)	v4 (Filters)	Notes
`gameObject.preFX` / `gameObject.postFX`	`gameObject.filters.internal` / `gameObject.filters.external`	`preFX` / `postFX` replaced by internal/external filter lists
`camera.postFX`	`camera.filters.internal` / `camera.filters.external`	Cameras now have both internal and external lists
`FX.addBloom()`	Use `ParallelFilters` + Threshold + Blur	No dedicated Bloom filter; build it with ParallelFilters or `Phaser.Actions.AddEffectBloom`
`FX.addCircle()`	Use Vignette or Mask	Circle effect removed; use Vignette with radius or a circular Mask, or automate with `Phaser.Actions.AddMaskShape`
`FX.addGradient()`	Use Gradient GameObject + Quantize	New Gradient GameObject renders gradients; Quantize adds steps if wanted
Glow `quality` was 0-1 fraction	Glow `quality` is an integer (default 10)	Stochastic sampling replaces line sampling; higher quality at lower values
`camera.setMask()`	`camera.filters.internal.addMask()`	Masks are now filters, not a separate system
`gameObject.setMask()`	`gameObject.filters.internal.addMask()`	Same unified filter system
FX controllers	`Phaser.Filters.Controller` subclasses	Same pattern: returned controller objects with mutable properties
--	`enableFilters()` required for game objects	New explicit opt-in step for game objects
--	Blocky, Quantize, Key, Blend, CombineColorMatrix, ImageLight, NormalTools, PanoramaBlur, ParallelFilters, Sampler	New filters added in 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	圆形效果已移除；使用带半径的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新增的滤镜

Source File Map

源文件映射

File	Description
`src/gameobjects/components/Filters.js`	Mixin that adds `enableFilters()` , `filterCamera` , `filters` to game objects
`src/gameobjects/components/FilterList.js`	FilterList class with all `add*()` factory methods
`src/filters/Controller.js`	Base Controller class for all filters
`src/filters/Barrel.js`	Barrel distortion filter
`src/filters/Blend.js`	Texture blend filter
`src/filters/Blocky.js`	Color-preserving pixelation filter
`src/filters/Blur.js`	Gaussian blur filter
`src/filters/Bokeh.js`	Bokeh / tilt shift filter
`src/filters/ColorMatrix.js`	Color matrix filter (sepia, grayscale, etc.)
`src/filters/CombineColorMatrix.js`	Dual-texture channel combining filter
`src/filters/Displacement.js`	Displacement map filter
`src/filters/Glow.js`	Glow/outline filter
`src/filters/GradientMap.js`	Gradient map recoloring filter
`src/filters/ImageLight.js`	Image-based lighting filter
`src/filters/Key.js`	Chroma key filter
`src/filters/Mask.js`	Alpha mask filter (texture or game object)
`src/filters/NormalTools.js`	Normal map manipulation filter
`src/filters/PanoramaBlur.js`	Spherical panorama blur filter
`src/filters/ParallelFilters.js`	Parallel filter paths with blend
`src/filters/Pixelate.js`	Pixelation filter
`src/filters/Quantize.js`	Color quantization filter
`src/filters/Sampler.js`	Pixel sampling/readback filter
`src/filters/Shadow.js`	Drop shadow filter
`src/filters/Threshold.js`	Threshold filter
`src/filters/Vignette.js`	Vignette filter
`src/filters/Wipe.js`	Wipe/reveal transition filter
`src/gameobjects/captureframe/CaptureFrame.js`	CaptureFrame game object for scene-level capture

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

文件	描述
`src/gameobjects/components/Filters.js`	混入类，为游戏对象添加 `enableFilters()` 、 `filterCamera` 、 `filters` 属性
`src/gameobjects/components/FilterList.js`	FilterList类，包含所有 `add*()` 工厂方法
`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`	Alpha遮罩滤镜（纹理或游戏对象）
`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