Mask
The Mask Filter Controller.
This filter controller manages a mask effect.
A mask uses a texture to hide parts of an input.
It multiplies the color and alpha of the input
by the alpha of the mask in the corresponding texel.
Masks can be inverted, which switches what they hide and what they show.
Masks can use either a texture or a GameObject.
If a GameObject is used, the mask will render the GameObject
to a DynamicTexture and use that.
The mask will automatically update when the GameObject changes,
unless the autoUpdate flag is set to false.
When the mask filter is used as an internal filter,
the mask will match the object/view being filtered.
This is useful for creating effects that follow the object,
such as effects intended to match an animated sprite.
When the mask filter is used as an external filter,
the mask will match the context of the camera.
This is useful for creating effects that cover the entire view.
An optional viewCamera can be specified when creating the mask.
If not used, mask objects will be viewed through the current camera,
or through a default camera if no other option is set.
For example, when rendering to a DynamicTexture outside the normal rendering
flow.
A Mask effect is added to a Camera via the FilterList component:
const camera = this.cameras.main;
const texture = 'MyMask';
camera.filters.internal.addMask(texture);
camera.filters.external.addMask(texture, true, myCamera);
Constructor
new Mask(camera, [mask], [invert], [viewCamera], [viewTransform], [scaleFactor])
Parameters
| name | type | optional | default | description |
|---|---|---|---|---|
| camera | Phaser.Cameras.Scene2D.Camera | No | The Camera that owns this filter. | |
| mask | string | Phaser.GameObjects.GameObject | Yes | "'__WHITE'" | The source of the mask. This can be a unique string-based key of the texture to use for the mask, which must exist in the Texture Manager. Or it can be a GameObject, in which case the mask will render the GameObject to a DynamicTexture and use that. |
| invert | boolean | Yes | false | Whether to invert the mask. |
| viewCamera | Phaser.Cameras.Scene2D.Camera | Yes | The Camera to use when rendering the mask with a GameObject. If not specified, uses the scene's main camera. | |
| viewTransform | 'local' | 'world' | Yes | "'world'" | The transform to use when rendering the mask with a GameObject. 'local' uses the GameObject's own properties. 'world' uses the GameObject's parentContainer value to compute a world position. |
| scaleFactor | number | Yes | 1 | The scale factor to apply to the underlying mask texture. Can be used to balance memory usage and needed mask precision. This just adjusts the size of the texture; you must also adjust mask size to match, e.g. if scaleFactor is 0.5, your mask might be a Container with scale 0.5. It's easy to make things complicated when combining scale factor, object transform, and camera transform, so try to be precise when using this option. |
Scope: static
Extends
Source: src/filters/Mask.js#L11
Since: 4.0.0
Inherited Members
From Phaser.Filters.Controller:
Public Members
autoUpdate
autoUpdate: boolean
Description:
Whether the mask should automatically update.
This only applies when the mask is a GameObject.
If false, the mask will not change even if the GameObject changes.
Source: src/filters/Mask.js#L120
Since: 4.0.0
glTexture
glTexture: Phaser.Renderer.WebGL.Wrappers.WebGLTextureWrapper
Description:
The underlying texture used for the mask.
Source: src/filters/Mask.js#L77
Since: 4.0.0
invert
invert: boolean
Description:
Whether to invert the mask.
An inverted mask switches what it hides and what it shows.
Source: src/filters/Mask.js#L109
Since: 4.0.0
maskGameObject
maskGameObject: Phaser.GameObjects.GameObject
Description:
The GameObject used for the mask.
This is only set if the mask is a GameObject.
Source: src/filters/Mask.js#L98
Since: 4.0.0
needsUpdate
needsUpdate: boolean
Description:
Whether the mask needs updating, once.
This only applies when the mask is a GameObject.
If true, the mask will be updated before the next render.
This is automatically set to true when the mask is a GameObject,
but it turns off after the mask is updated.
Source: src/filters/Mask.js#L132
Since: 4.0.0
scaleFactor
scaleFactor: number
Description:
The scale factor to apply to the underlying mask texture.
Source: src/filters/Mask.js#L170
Since: 4.0.0
viewCamera
viewCamera: Phaser.Cameras.Scene2D.Camera
Description:
The Camera to use when rendering the mask.
If not specified, uses the currently rendering camera,
or failing that, an internal Camera.
Source: src/filters/Mask.js#L159
Since: 4.0.0
viewTransform
viewTransform: 'local', 'world'
Description:
The transform type to use when rendering the mask with a GameObject.
'local' uses the GameObject's own properties.
'world' uses the GameObject's parentContainer value to compute a world position.
This only applies when the mask is a GameObject.
Source: src/filters/Mask.js#L146
Since: 4.0.0
Inherited Methods
From Phaser.Filters.Controller:
Public Methods
setGameObject
<instance> setGameObject(gameObject)
Description:
Sets the GameObject used for the mask.
Parameters:
| name | type | optional | description |
|---|---|---|---|
| gameObject | Phaser.GameObjects.GameObject | No | The GameObject to use for the mask. |
Returns: Phaser.Filters.Mask - This Filter Controller.
Source: src/filters/Mask.js#L241
Since: 4.0.0
setTexture
<instance> setTexture([texture])
Description:
Sets the texture used for the mask.
Parameters:
| name | type | optional | default | description |
|---|---|---|---|---|
| texture | string | Yes | "'__WHITE'" | The unique string-based key of the texture to use for displacement, which must exist in the Texture Manager. |
Returns: Phaser.Filters.Mask - This Filter Controller.
Source: src/filters/Mask.js#L262
Since: 4.0.0
updateDynamicTexture
<instance> updateDynamicTexture(width, height)
Description:
Updates the DynamicTexture for the mask.
The DynamicTexture is created or resized if necessary.
This is called automatically during rendering
when the mask is a GameObject
and the needsUpdate or autoUpdate flags are set.
It should not be called directly.
Parameters:
| name | type | optional | description |
|---|---|---|---|
| width | number | No | The width of the DynamicTexture. |
| height | number | No | The height of the DynamicTexture |
Source: src/filters/Mask.js#L190
Since: 4.0.0