Class: MaskSystem

PIXI.MaskSystem

System plugin to the renderer to manage masks.

There are three built-in types of masking:

  • Scissor Masking: Scissor masking discards pixels that are outside of a rectangle called the scissor box. It is the most performant as the scissor test is inexpensive. However, it can only be used when the mask is rectangular.
  • Stencil Masking: Stencil masking discards pixels that don't overlap with the pixels rendered into the stencil buffer. It is the next fastest option as it does not require rendering into a separate framebuffer. However, it does cause the mask to be rendered twice for each masking operation; hence, minimize the rendering cost of your masks.
  • Sprite Mask Filtering: Sprite mask filtering discards pixels based on the red channel of the sprite-mask's texture. (Generally, the masking texture is grayscale). Using advanced techniques, you might be able to embed this type of masking in a custom shader - and hence, bypassing the masking system fully for performance wins.

The best type of masking is auto-detected when you push one. To use scissor masking, you must pass in a Graphics object with just a rectangle drawn.

Mask Stacks

In the scene graph, masks can be applied recursively, i.e. a mask can be applied during a masking operation. The mask stack stores the currently applied masks in order. Each PIXI.BaseRenderTexture holds its own mask stack, i.e. when you switch render-textures, the old masks only applied when you switch back to rendering to the old render-target.

new PIXI.MaskSystem (renderer) overrides

Name Type Description
renderer PIXI.Renderer

The renderer this System works for.

Extends

Implements

Members

alphaMaskIndex number readonly

Current index of alpha mask pool

Default Value:
  • 0

alphaMaskPool Array<PIXI.SpriteMaskFilter> readonly

Pool of used sprite mask filters

enableScissor boolean readonly

Enable scissor masking.

maskDataPool Array<PIXI.MaskData> readonly

Pool of mask data

Methods

detect (maskData) void

Sets type of MaskData based on its maskObject

Name Type Description
maskData PIXI.MaskData

pop (target) void

Removes the last mask from the mask stack and doesn't return it.

NOTE: The batch renderer should be flushed beforehand to render the masked contents before the mask is removed.

Name Type Description
target PIXI.DisplayObject

Display Object to pop the mask from

popSpriteMask () void

Removes the last filter from the filter stack and doesn't return it.

push (target, maskData) void

Enables the mask and appends it to the current mask stack.

NOTE: The batch renderer should be flushed beforehand to prevent pending renders from being masked.

Name Type Description
target PIXI.DisplayObject

Display Object to push the mask to

maskData PIXI.MaskData | PIXI.Sprite | PIXI.Graphics | PIXI.DisplayObject

The masking data.

pushSpriteMask (maskData) void

Applies the Mask and adds it to the current filter stack.

Name Type Description
maskData PIXI.MaskData

Sprite to be used as the mask

setMaskStack (maskStack) void

Changes the mask stack that is used by this System.

Name Type Description
maskStack Array<PIXI.MaskData>

The mask stack

Inherited Properties

From class PIXI.System

renderer Renderer inherited

Reference to the main renderer

Inherited Methods

From class PIXI.System

destroy () void inherited

Destroy and don't use after this.