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

Phaser.Filters.Controller

Source: src/filters/Mask.js#L11
Since: 4.0.0

Inherited Members

From Phaser.Filters.Controller:

• active
• allowBaseDraw
• camera
• currentPadding
• ignoreDestroy
• paddingOverride
• renderNode

---

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. A value less than 1 reduces the texture resolution to save memory at the cost of mask precision. A value greater than 1 increases resolution for sharper masking but uses more memory. When changing this value, you must also scale the mask GameObject or Container to match, so that its rendered output fills the texture correctly.

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:

• getPadding
• setActive
• setPaddingOverride

---

Public Methods

destroy

<instance> destroy()

Description:

Destroys this filter, releasing all references and resources.

If a dynamic texture was created for a mask GameObject, it will also be destroyed.

Overrides: Phaser.Filters.Controller#destroy

Source: src/filters/Mask.js#L294
Since: 4.0.0

---

setGameObject

<instance> setGameObject(gameObject)

Description:

Sets the GameObject used for the mask. The GameObject will be rendered to an internal DynamicTexture on the next render pass. Setting a new GameObject also sets needsUpdate to true, ensuring the texture is refreshed before the next frame is drawn.

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#L246
Since: 4.0.0

---

setTexture

<instance> setTexture([texture])

Description:

Sets a static texture to use as the mask, looked up by key from the Texture Manager. Any previously assigned mask GameObject is cleared. Unlike a GameObject mask, a static texture mask does not update automatically between frames.

Parameters:

name	type	optional	default	description
texture	string	Yes	"'__WHITE'"	The unique string-based key of the texture to use for the mask, which must exist in the Texture Manager.

Returns: Phaser.Filters.Mask - This Filter Controller.

Source: src/filters/Mask.js#L270
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#L195
Since: 4.0.0

---