~~NOTOC~~

====== Pixelmask ======

---- dataentry extension ----
author_mail   : jonathan.hart@gmail.com Jonathan Hart
description   : Pixel-based masking support for Starling           # enter a short description of the extension
lastupdate_dt : 2012-11-23 # the date you created the extension
compatible    : v2.2       # the Starling version you tested the extension with
tags          : mask, masking # enter a few tags, separated by commas
homepage_url  :            # if the ext. has an URL (e.g. a Gist-page), add it here
download_url  : 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:

{{ :extensions:pixel-mask.mp4?738x198 |}}

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

{{ :extensions:pixelmask-shimmer.mp4?298x200 |}}

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 =====

<code as3>

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

===== 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:

  * Pixelmask (found in the /src directory of this repository)
  * Starling (found here: [[https://github.com/Gamua/Starling-Framework]])
  * Starling Particles Extension (found here: [[https://github.com/Gamua/Starling-Extension-Particle-System]])
  * [[http://www.tecnicocaldera.com/916125277/reparacion-calderas|reparacion de calderas madrid]]


===== 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.//