~~NOTOC~~

====== ClippedSprite ======

---- dataentry extension ----
author_mail   : daniel@gamua.com Daniel Sperl
description   : Simple Sprite subclass with a rectangular mask in stage coordinates
lastupdate_dt : 2012-04-190
compatible    : v1.1
depends       :
tags          : mask, clipping, scissor
homepage_url  : https://gist.github.com/2422317
download_url  : https://gist.github.com/gists/2422317/download
----

===== Overview =====

<note>
With Starling 1.4, you don't need this extension any longer! The "clipRect" property is now built right into the Sprite class. It does almost exactly the same as this extension, with the notable difference that it uses local coordinates, not stage coordinates.
</note>

{{ :extensions:masked-sprite-sample.png?nolink|}}

This class, a subclass of Sprite, allows you to clip the Sprite's content in a rectangular area. The mask is always given in **stage coordinates** and cannot be rotated.

Beware that the clipping rectangle does not affect the bounds of the sprite, i.e. the "width" and "height" properties won't reflect the clipping area. Touches outside the clipping rectangle are ignored, though.

To use the mask, assign a value to the "clipRect" property:

<code as3>
var sprite:ClippedSprite = new ClippedSprite();
addChild(sprite);

// the sprite works like you're used to
sprite.addChild(anObject);
sprite.addChild(anotherObject);

// set the mask rectangle in stage coordinates
sprite.clipRect = new Rectangle(10, 10, 380, 280);
</code>

**Note:** //Resistcorp// created a version of this extension that allows nested clipping regions. Find it [[https://gist.github.com/3099899|here]]!
===== Changelog =====

  * //2012/04/19//: First public version
  * //2012/04/21//: Added overridden ''hitTest()'' method
  * //2012/06/10//: Checking for ''mClipRect'' to be null in ''hitTest()'' method
  * //2012/07/16//: Corrected behavior when aspect ratio of Starling viewport differs from that of the stage
  * //2012/11/20//: Added support for filters. Class requires Starling 1.3 or development version.

===== Source Code =====

%gist(2422317)%

===== User Comments =====

I believe this is now a default part of the Starling framework.