~~NOTOC~~

====== Texture Mask ======

---- dataentry extension ----
author_mail   : daniel@gamua.com Daniel Sperl
description   : A mesh style that discards alpha values below a certain threshold; useful for masks.
compatible    : v2.0
tags          : mask, stencil, alpha
homepage_url  : https://gist.github.com/PrimaryFeather/d13b8d14d329a364c7cb
----

===== Overview =====

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.

{{ :extensions:texture-mask.mp4?296x296 |}}
==== Starling 2 ====

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.

<code as3>
// 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;
</code>

==== Starling 1.7 ====

To use this extension with Starling 1.7, use [[https://gist.github.com/PrimaryFeather/4d5b194783f3df296093|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.

<code as3>
// 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;
</code>

===== Changelog =====

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

===== 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 [[http://forum.starling-framework.org|forum]], though.//