Starling 1.7 added support for stencil masks via a new property on display objects (“mask”). One way to create such a mask is to use the new “Canvas” class for drawing a vector shape.

However, for complex shapes, it's easier to simply use the pixels of a certain texture as a mask. That's what this class is for.

The version for Starling 2 is implemented as a mesh style. This allows you to assign it to any mesh object (like Quad, Image, or even MovieClip). Any pixels with an alpha value below a certain threshold will be discarded. You can display such an object anywhere in the display tree, but it is especially useful as a stencil mask.

// get a sprite with some content
var sprite:Sprite = createMySprite();
addChild(sprite);
 
// create the image that will act as a mask, and assign the "TextureMaskStyle"
var mask:Image = new Image(assets.getTexture("shape"));
var style:TextureMaskStyle = new TextureMaskStyle();
mask.style = style;
sprite.mask = mask;
 
// change threshold to fine-tune the result
style.threshold = 0.3;

To use this extension with Starling 1.7, use the TextureMask class instead.

A “TextureMask” is actually a conventional display object, very similar to the “Image” class. The main difference to an image is that any pixels with an alpha value below a certain threshold will be discarded.

// get a sprite with some content
var sprite:Sprite = createMySprite();
addChild(sprite);
 
// create a "TextureMask" and assign it to the "mask" property
var textureMask:TextureMask = new TextureMask(assets.getTexture("shape"));
sprite.mask = textureMask;
 
// change threshold to fine-tune the result
textureMask.threshold = 0.3;

• 2015/05/07: First public version
• 2016/02/18: Created Starling 2 version

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.