filters-and-postfx

# Phaser 4 Filters and Post-FX ## Quick Start Add a glow effect to a sprite: ```js // 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: ```js // Cameras have filters enabled by default - no enableFilters() needed const camera = this.cameras.main; camera.filters.internal.addBlur(0, 2, 2, 1); ``` --- ## Core Concepts ### How Filters Work in 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: 1. Objects render to a texture the size of the camera. 2. **Internal filters** process that texture, applying effects in object/camera local space. 3. The texture is drawn to a context-sized texture, applying camera transformations (position, rotation, zoom). 4. **External filters** process that context texture, applying effects in screen space. 5. The final texture is composited into the output. ### Internal vs External Filters 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 `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. ### 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()`. ### Enabling Filters on Game Objects Cameras have filters available by default. Game objects do not -- you must call `enableFilters()` first: ```js 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. --- ## Common Patterns ### Adding Filters to Game Objects ```js 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); ``` ### Camera Filters ```js 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(); ``` ### Chaining Multiple Filters Filters execute in list order. Each filter receives the output of the previous one: ```js 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); ``` ### Masks via Filters Masks in v4 are implemented as filters. They use the alpha channel of a texture or game object to control visibility: ```js // 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. ### Wipe / Reveal Transitions ```js 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 (Custom Bloom and Compositing) ParallelFilters splits the input into two paths, processes each independently, then blends the results. This replaces the dedicated Bloom filter from v3: ```js 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 for Scene-Level Effects `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: ```js // 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); ``` --- ## 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. | --- ## API Quick Reference ### Enabling and Accessing Filters ```js // 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 Methods ```js 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 Common API ```js 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 Filter API ```js 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 Presets ```js 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(); ```