Package | starling.display |
Class | public class Sprite |
Inheritance | Sprite DisplayObjectContainer DisplayObject EventDispatcher Object |
Use it as a simple means of grouping objects together in one coordinate system, or as the base class for custom display objects.
Flattened SpritesThe flatten
-method allows you to optimize the rendering of static parts of
your display list.
It analyzes the tree of children attached to the sprite and optimizes the rendering calls
in a way that makes rendering extremely fast. The speed-up comes at a price, though: you
will no longer see any changes in the properties of the children (position, rotation,
alpha, etc.). To update the object after changes have happened, simply call
flatten
again, or unflatten
the object.
The clipRect
property allows you to clip the visible area of the sprite
to a rectangular region. Only pixels inside the rectangle will be displayed. This is a very
fast way to mask objects. However, there is one limitation: the clipRect
only works with stage-aligned rectangles, i.e. you cannot rotate or skew the rectangle.
This limitation is inherited from the underlying "scissoring" technique that is used
internally.
See also
Property | Defined By | ||
---|---|---|---|
alpha : Number The opacity of the object. | DisplayObject | ||
base : DisplayObject [read-only] The topmost object in the display tree the object is part of. | DisplayObject | ||
blendMode : String The blend mode determines how the object is blended with the objects underneath. | DisplayObject | ||
bounds : Rectangle [read-only] The bounds of the object relative to the local coordinates of the parent. | DisplayObject | ||
clipRect : Rectangle The object's clipping rectangle in its local coordinate system. | Sprite | ||
filter : FragmentFilter The filter that is attached to the display object. | DisplayObject | ||
hasVisibleArea : Boolean [read-only] Indicates if an object occupies any visible area. | DisplayObject | ||
height : Number The height of the object in pixels. | DisplayObject | ||
isFlattened : Boolean [read-only] Indicates if the sprite was flattened. | Sprite | ||
name : String The name of the display object (default: null). | DisplayObject | ||
numChildren : int [read-only] The number of children of this container. | DisplayObjectContainer | ||
parent : DisplayObjectContainer [read-only] The display object container that contains this display object. | DisplayObject | ||
pivotX : Number The x coordinate of the object's origin in its own coordinate space (default: 0). | DisplayObject | ||
pivotY : Number The y coordinate of the object's origin in its own coordinate space (default: 0). | DisplayObject | ||
root : DisplayObject [read-only] The root object the display object is connected to (i.e. | DisplayObject | ||
rotation : Number The rotation of the object in radians. | DisplayObject | ||
scaleX : Number The horizontal scale factor. | DisplayObject | ||
scaleY : Number The vertical scale factor. | DisplayObject | ||
skewX : Number The horizontal skew angle in radians. | DisplayObject | ||
skewY : Number The vertical skew angle in radians. | DisplayObject | ||
stage : Stage [read-only] The stage the display object is connected to, or null if it is not connected
to the stage. | DisplayObject | ||
touchable : Boolean Indicates if this object (and its children) will receive touch events. | DisplayObject | ||
touchGroup : Boolean If a container is a 'touchGroup', it will act as a single touchable object. | DisplayObjectContainer | ||
transformationMatrix : Matrix The transformation matrix of the object relative to its parent. | DisplayObject | ||
useHandCursor : Boolean Indicates if the mouse cursor should transform into a hand while it's over the sprite. | DisplayObject | ||
visible : Boolean The visibility of the object. | DisplayObject | ||
width : Number The width of the object in pixels. | DisplayObject | ||
x : Number The x coordinate of the object relative to the local coordinates of the parent. | DisplayObject | ||
y : Number The y coordinate of the object relative to the local coordinates of the parent. | DisplayObject |
Method | Defined By | ||
---|---|---|---|
Sprite() Creates an empty sprite. | Sprite | ||
Adds a child to the container. | DisplayObjectContainer | ||
Adds a child to the container at a certain index. | DisplayObjectContainer | ||
addEventListener(type:String, listener:Function):void [override] | DisplayObject | ||
alignPivot(hAlign:String = center, vAlign:String = center):void Moves the pivot point to a certain position within the local coordinate system
of the object. | DisplayObject | ||
broadcastEvent(event:Event):void Dispatches an event on all children (recursively). | DisplayObjectContainer | ||
broadcastEventWith(type:String, data:Object = null):void Dispatches an event with the given parameters on all children (recursively). | DisplayObjectContainer | ||
contains(child:DisplayObject):Boolean Determines if a certain object is a child of the container (recursively). | DisplayObjectContainer | ||
dispatchEvent(event:Event):void [override] | DisplayObject | ||
dispatchEventWith(type:String, bubbles:Boolean = false, data:Object = null):void Dispatches an event with the given parameters to all objects that have registered
listeners for the given type. | EventDispatcher | ||
dispose():void [override] Disposes the resources of all children. | Sprite | ||
flatten():void Optimizes the sprite for optimal rendering performance. | Sprite | ||
getBounds(targetSpace:DisplayObject, resultRect:Rectangle = null):Rectangle [override] Returns a rectangle that completely encloses the object as it appears in another
coordinate system. | Sprite | ||
getChildAt(index:int):DisplayObject Returns a child object at a certain index. | DisplayObjectContainer | ||
getChildByName(name:String):DisplayObject Returns a child object with a certain name (non-recursively). | DisplayObjectContainer | ||
getChildIndex(child:DisplayObject):int Returns the index of a child within the container, or "-1" if it is not found. | DisplayObjectContainer | ||
getClipRect(targetSpace:DisplayObject, resultRect:Rectangle = null):Rectangle Returns the bounds of the container's clipRect in the given coordinate space, or
null if the sprite doens't have a clipRect. | Sprite | ||
getTransformationMatrix(targetSpace:DisplayObject, resultMatrix:Matrix = null):Matrix Creates a matrix that represents the transformation from the local coordinate system
to another. | DisplayObject | ||
globalToLocal(globalPoint:Point, resultPoint:Point = null):Point Transforms a point from global (stage) coordinates to the local coordinate system. | DisplayObject | ||
hasEventListener(type:String):Boolean Returns if there are listeners registered for a certain event type. | EventDispatcher | ||
hitTest(localPoint:Point, forTouch:Boolean = false):DisplayObject [override] Returns the object that is found topmost beneath a point in local coordinates, or nil if
the test fails. | Sprite | ||
localToGlobal(localPoint:Point, resultPoint:Point = null):Point Transforms a point from the local coordinate system to global (stage) coordinates. | DisplayObject | ||
Removes a child from the container. | DisplayObjectContainer | ||
removeChildAt(index:int, dispose:Boolean = false):DisplayObject Removes a child at a certain index. | DisplayObjectContainer | ||
removeChildren(beginIndex:int = 0, endIndex:int = -1, dispose:Boolean = false):void Removes a range of children from the container (endIndex included). | DisplayObjectContainer | ||
removeEventListener(type:String, listener:Function):void [override] | DisplayObject | ||
removeEventListeners(type:String = null):void [override] | DisplayObject | ||
removeFromParent(dispose:Boolean = false):void Removes the object from its parent, if it has one, and optionally disposes it. | DisplayObject | ||
render(support:RenderSupport, parentAlpha:Number):void [override] Renders the display object with the help of a support object. | Sprite | ||
setChildIndex(child:DisplayObject, index:int):void Moves a child to a certain index. | DisplayObjectContainer | ||
sortChildren(compareFunction:Function):void Sorts the children according to a given function (that works just like the sort function
of the Vector class). | DisplayObjectContainer | ||
Swaps the indexes of two children. | DisplayObjectContainer | ||
swapChildrenAt(index1:int, index2:int):void Swaps the indexes of two children. | DisplayObjectContainer | ||
unflatten():void Removes the rendering optimizations that were created when flattening the sprite. | Sprite |
Event | Summary | Defined By | ||
---|---|---|---|---|
Dispatched when an object is added to a parent. | DisplayObject | |||
Dispatched when an object is connected to the stage (directly or indirectly). | DisplayObject | |||
Dispatched once every frame on every object that is connected to the stage. | DisplayObject | |||
Dispatched on all children when the object is flattened. | Sprite | |||
Dispatched when a key on the keyboard is pressed. | DisplayObject | |||
Dispatched when a key on the keyboard is released. | DisplayObject | |||
Dispatched when an object is removed from its parent. | DisplayObject | |||
Dispatched when an object is removed from the stage and won't be rendered any longer. | DisplayObject | |||
Dispatched when an object is touched. | DisplayObject |
clipRect | property |
clipRect:Rectangle
The object's clipping rectangle in its local coordinate system. Only pixels within that rectangle will be drawn. Note: clip rects are axis aligned with the screen, so they will not be rotated or skewed if the Sprite is.
public function get clipRect():Rectangle
public function set clipRect(value:Rectangle):void
isFlattened | property |
isFlattened:Boolean
[read-only] Indicates if the sprite was flattened.
public function get isFlattened():Boolean
Sprite | () | Constructor |
public function Sprite()
Creates an empty sprite.
dispose | () | method |
override public function dispose():void
Disposes the resources of all children.
flatten | () | method |
public function flatten():void
Optimizes the sprite for optimal rendering performance. Changes in the
children of a flattened sprite will not be displayed any longer. For this to happen,
either call flatten
again, or unflatten
the sprite.
Beware that the actual flattening will not happen right away, but right before the
next rendering.
When you flatten a sprite, the result of all matrix operations that are otherwise executed during rendering are cached. For this reason, a flattened sprite can be rendered with much less strain on the CPU. However, a flattened sprite will always produce at least one draw call; if it were merged together with other objects, this would cause additional matrix operations, and the optimization would have been in vain. Thus, don't just blindly flatten all your sprites, but reserve flattening for sprites with a big number of children.
getBounds | () | method |
override public function getBounds(targetSpace:DisplayObject, resultRect:Rectangle = null):Rectangle
Returns a rectangle that completely encloses the object as it appears in another coordinate system. If you pass a 'resultRectangle', the result will be stored in this rectangle instead of creating a new object.
Parameters
targetSpace:DisplayObject | |
resultRect:Rectangle (default = null )
|
Rectangle |
getClipRect | () | method |
public function getClipRect(targetSpace:DisplayObject, resultRect:Rectangle = null):Rectangle
Returns the bounds of the container's clipRect in the given coordinate space, or null if the sprite doens't have a clipRect.
Parameters
targetSpace:DisplayObject | |
resultRect:Rectangle (default = null )
|
Rectangle |
hitTest | () | method |
override public function hitTest(localPoint:Point, forTouch:Boolean = false):DisplayObject
Returns the object that is found topmost beneath a point in local coordinates, or nil if the test fails. If "forTouch" is true, untouchable and invisible objects will cause the test to fail.
Parameters
localPoint:Point | |
forTouch:Boolean (default = false )
|
DisplayObject |
render | () | method |
override public function render(support:RenderSupport, parentAlpha:Number):void
Renders the display object with the help of a support object. Never call this method directly, except from within another render method.
Parameters
support:RenderSupport — Provides utility functions for rendering.
| |
parentAlpha:Number — The accumulated alpha value from the object's parent up to the stage. |
unflatten | () | method |
public function unflatten():void
Removes the rendering optimizations that were created when flattening the sprite. Changes to the sprite's children will immediately become visible again.
flatten | Event |