Pixelmask

author:
Jonathan Hart
description:
Pixel-based masking support for Starling
lastupdate:
2012-11-23
compatible:
v2.2
tag:
mask, masking
download:
https://github.com/jonathanhart/pixelmask



IMPORTANT NOTE

This extension is used to achieve “soft” alpha-based masking and has non-trivial performance requirements, especially at larger sizes. It is recommended only for small UI elements such as button shimmers.

Stencil-masks may be a better route to take for your masking needs, and are much faster with lower memory footprint. However, they do not support soft alpha masking so the edges will be pixelated. It is up to you to decide which mask to use, but please know that for basic hard-edged masking, stencil-mask is a better solution.

More info on stencil-mask here: http://forum.starling-framework.org/topic/new-feature-stencil-masks

Overview

The following is a demonstration of Pixelmask in action. It is a particle system container being masked by an animated spritesheet of text that has a blur filter applied to it. Click inside the box to see the mask inverted:

Here is a demo of button sheens, the text inside is dynamic and shown to have an extra highlighting effect:

Pixelmask is a Starling extension to provide pixel level masking to any Starling display object. The goal is to achieve the same masking functionality provided in the classic flash display namespace, while taking advantage of the GPU accelerated Starling framework.

Using Pixelmask works similar to the classic way, a Starling display object called PixelMaskDisplayObject contains a public property called “pixelMask” that can be set to any Starling display object. As each frame progresses, custom blend filters will apply the mask's alpha channel to the contents of the PixelMaskDisplayObject. Both animated and static display objects are supported for both the source and the mask.

One can either create a custom class that extends PixelMaskDisplayObject, or simply use a stand-alone instance of the class as a container.

Example

// myCustomDisplayObject and myCustomMaskDisplayObject can be any Starling display object:
var myCustomDisplayObject:Sprite = new Sprite();
var myCustomMaskDisplayObject:Sprite = new Sprite();
 
// for masks with animation:
var maskedDisplayObject:PixelMaskDisplayObject = new PixelMaskDisplayObject();
maskedDisplayObject.addChild(myCustomDisplayObject);
 
// for masks with no animation (note, MUCH better performance!)
var maskedDisplayObject:PixelMaskDisplayObject = new PixelMaskDisplayObject(-1, false);
maskedDisplayObject.addChild(myCustomDisplayObject);
 
// Apply the masking as you would in classic flash.display style.
// Note: the mask display object should not be added to the display list.
 
maskedDisplayObject.pixelMask = myCustomMaskDisplayObject;
addChild(maskedDisplayObject);

Changelog

  • 2012/11/23: First public version
  • 2017/12/01: Updated for Starling 2.x

Source Code

Source code and demo projects are available here:

https://github.com/jonathanhart/pixelmask

To run the demo, the following are required as linked source paths:

User Comments

Feel free to edit this part of the page if you want to add information that's lacking in the above description.
Questions are better asked in the forum, though.

  extensions/pixelmask.txt · Last modified: 2021/01/07 16:38 by daniel
 
Powered by DokuWiki