Packagestarling.display
Classpublic class Sprite3D
InheritanceSprite3D Inheritance DisplayObjectContainer Inheritance DisplayObject Inheritance EventDispatcher Inheritance Object

A container that allows you to position objects in three-dimensional space.

Starling is, at its heart, a 2D engine. However, sometimes, simple 3D effects are useful for special effects, e.g. for screen transitions or to turn playing cards realistically. This class makes it possible to create such 3D effects.

Positioning objects in 3D

Just like a normal sprite, you can add and remove children to this container, which allows you to group several display objects together. In addition to that, Sprite3D adds some interesting properties:

With the help of these properties, you can move a sprite and all its children in the 3D space. By nesting several Sprite3D containers, it's even possible to construct simple volumetric objects (like a cube).

Note that Starling does not make any z-tests: visibility is solely established by the order of the children, just as with 2D objects.

Setting up the camera

The camera settings are found directly on the stage. Modify the 'focalLength' or 'fieldOfView' properties to change the distance between stage and camera; use the 'projectionOffset' to move it to a different position.

Limitations

On rendering, each Sprite3D requires its own draw call — except if the object does not contain any 3D transformations ('z', 'rotationX/Y' and 'pivotZ' are zero). Furthermore, it interrupts the render cache, i.e. the cache cannot contain objects within different 3D coordinate systems. Flat contents within the Sprite3D will be cached, though.



Public Properties
 PropertyDefined By
 Inheritedalpha : Number
The opacity of the object.
DisplayObject
 Inheritedbase : DisplayObject
[read-only] The topmost object in the display tree the object is part of.
DisplayObject
 InheritedblendMode : String
The blend mode determines how the object is blended with the objects underneath.
DisplayObject
 Inheritedbounds : Rectangle
[read-only] The bounds of the object relative to the local coordinates of the parent.
DisplayObject
 Inheritedfilter : FragmentFilter
The filter that is attached to the display object.
DisplayObject
 Inheritedheight : Number
The height of the object in pixels.
DisplayObject
 Inheritedis3D : Boolean
[read-only] Indicates if this object or any of its parents is a 'Sprite3D' object.
DisplayObject
  isFlat : Boolean
[read-only] If true, this 3D object contains only 2D content.
Sprite3D
 Inheritedmask : DisplayObject
The display object that acts as a mask for the current object.
DisplayObject
 InheritedmaskInverted : Boolean
Indicates if the masked region of this object is set to be inverted.
DisplayObject
 Inheritedname : String
The name of the display object (default: null).
DisplayObject
 InheritednumChildren : int
[read-only] The number of children of this container.
DisplayObjectContainer
 Inheritedparent : DisplayObjectContainer
[read-only] The display object container that contains this display object.
DisplayObject
 InheritedpivotX : Number
The x coordinate of the object's origin in its own coordinate space (default: 0).
DisplayObject
 InheritedpivotY : Number
The y coordinate of the object's origin in its own coordinate space (default: 0).
DisplayObject
  pivotZ : Number
The z coordinate of the object's origin in its own coordinate space (default: 0).
Sprite3D
 InheritedrequiresRedraw : Boolean
[read-only] Indicates if the object needs to be redrawn in the upcoming frame, i.e.
DisplayObject
 Inheritedroot : DisplayObject
[read-only] The root object the display object is connected to (i.e.
DisplayObject
 Inheritedrotation : Number
The rotation of the object in radians.
DisplayObject
  rotationX : Number
The rotation of the object about the x axis, in radians.
Sprite3D
  rotationY : Number
The rotation of the object about the y axis, in radians.
Sprite3D
  rotationZ : Number
The rotation of the object about the z axis, in radians.
Sprite3D
 Inheritedscale : Number
Sets both 'scaleX' and 'scaleY' to the same value.
DisplayObject
 InheritedscaleX : Number
The horizontal scale factor.
DisplayObject
 InheritedscaleY : Number
The vertical scale factor.
DisplayObject
  scaleZ : Number
The depth scale factor.
Sprite3D
 InheritedskewX : Number
The horizontal skew angle in radians.
DisplayObject
 InheritedskewY : Number
The vertical skew angle in radians.
DisplayObject
 Inheritedstage : Stage
[read-only] The stage the display object is connected to, or null if it is not connected to the stage.
DisplayObject
 Inheritedtouchable : Boolean
Indicates if this object (and its children) will receive touch events.
DisplayObject
 InheritedtouchGroup : Boolean
If a container is a 'touchGroup', it will act as a single touchable object.
DisplayObjectContainer
  transformationMatrix : Matrix
[override]
Sprite3D
 InheritedtransformationMatrix3D : Matrix3D
[read-only] The 3D transformation matrix of the object relative to its parent.
DisplayObject
 InheriteduseHandCursor : Boolean
Indicates if the mouse cursor should transform into a hand while it's over the sprite.
DisplayObject
 Inheritedvisible : Boolean
The visibility of the object.
DisplayObject
 Inheritedwidth : Number
The width of the object in pixels.
DisplayObject
 Inheritedx : Number
The x coordinate of the object relative to the local coordinates of the parent.
DisplayObject
 Inheritedy : Number
The y coordinate of the object relative to the local coordinates of the parent.
DisplayObject
  z : Number
The z coordinate of the object relative to the local coordinates of the parent.
Sprite3D
Public Methods
 MethodDefined By
  
Creates an empty Sprite3D.
Sprite3D
 Inherited
Adds a child to the container.
DisplayObjectContainer
 Inherited
Adds a child to the container at a certain index.
DisplayObjectContainer
 Inherited
addEventListener(type:String, listener:Function):void
[override] Registers an event listener at a certain object.
DisplayObject
 Inherited
alignPivot(horizontalAlign:String = center, verticalAlign:String = center):void
Moves the pivot point to a certain position within the local coordinate system of the object.
DisplayObject
 Inherited
broadcastEvent(event:Event):void
Dispatches an event on all children (recursively).
DisplayObjectContainer
 Inherited
broadcastEventWith(eventType:String, data:Object = null):void
Dispatches an event with the given parameters on all children (recursively).
DisplayObjectContainer
 Inherited
contains(child:DisplayObject):Boolean
Determines if a certain object is a child of the container (recursively).
DisplayObjectContainer
 Inherited
dispatchEvent(event:Event):void
Dispatches an event to all objects that have registered listeners for its type.
EventDispatcher
 Inherited
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
 Inherited
dispose():void
[override] Disposes the resources of all children.
DisplayObjectContainer
 Inherited
drawToBitmapData(out:BitmapData = null, color:uint = 0x0, alpha:Number = 0.0):BitmapData
Draws the object into a BitmapData object.
DisplayObject
 Inherited
getBounds(targetSpace:DisplayObject, out:Rectangle = null):Rectangle
[override] Returns a rectangle that completely encloses the object as it appears in another coordinate system.
DisplayObjectContainer
 Inherited
Returns a child object at a certain index.
DisplayObjectContainer
 Inherited
Returns a child object with a certain name (non-recursively).
DisplayObjectContainer
 Inherited
Returns the index of a child within the container, or "-1" if it is not found.
DisplayObjectContainer
 Inherited
getTransformationMatrix(targetSpace:DisplayObject, out:Matrix = null):Matrix
Creates a matrix that represents the transformation from the local coordinate system to another.
DisplayObject
 Inherited
getTransformationMatrix3D(targetSpace:DisplayObject, out:Matrix3D = null):Matrix3D
Creates a matrix that represents the transformation from the local coordinate system to another.
DisplayObject
 Inherited
globalToLocal(globalPoint:Point, out:Point = null):Point
Transforms a point from global (stage) coordinates to the local coordinate system.
DisplayObject
 Inherited
globalToLocal3D(globalPoint:Point, out:Vector3D = null):Vector3D
Transforms a point from global (stage) coordinates to the 3D local coordinate system.
DisplayObject
 Inherited
hasEventListener(type:String, listener:Function = null):Boolean
If called with one argument, figures out if there are any listeners registered for the given event type.
EventDispatcher
  
hitTest(localPoint:Point):DisplayObject
[override] Returns the object that is found topmost beneath a point in local coordinates, or nil if the test fails.
Sprite3D
 Inherited
hitTestMask(localPoint:Point):Boolean
Checks if a certain point is inside the display object's mask.
DisplayObject
 Inherited
local3DToGlobal(localPoint:Vector3D, out:Point = null):Point
Transforms a 3D point from the local coordinate system to global (stage) coordinates.
DisplayObject
 Inherited
localToGlobal(localPoint:Point, out:Point = null):Point
Transforms a point from the local coordinate system to global (stage) coordinates.
DisplayObject
 Inherited
removeChild(child:DisplayObject, dispose:Boolean = false):DisplayObject
Removes a child from the container.
DisplayObjectContainer
 Inherited
removeChildAt(index:int, dispose:Boolean = false):DisplayObject
Removes a child at a certain index.
DisplayObjectContainer
 Inherited
removeChildren(beginIndex:int = 0, endIndex:int = -1, dispose:Boolean = false):void
Removes a range of children from the container (endIndex included).
DisplayObjectContainer
 Inherited
removeEventListener(type:String, listener:Function):void
[override] Removes an event listener from the object.
DisplayObject
 Inherited
removeEventListeners(type:String = null):void
[override] Removes all event listeners with a certain type, or all of them if type is null.
DisplayObject
 Inherited
removeFromParent(dispose:Boolean = false):void
Removes the object from its parent, if it has one, and optionally disposes it.
DisplayObject
  
render(painter:Painter):void
[override] Renders the display object with the help of a painter object.
Sprite3D
 Inherited
setChildIndex(child:DisplayObject, index:int):void
Moves a child to a certain index.
DisplayObjectContainer
 Inherited
Forces the object to be redrawn in the next frame.
DisplayObject
 Inherited
sortChildren(compareFunction:Function):void
Sorts the children according to a given function (that works just like the sort function of the Vector class).
DisplayObjectContainer
 Inherited
Swaps the indexes of two children.
DisplayObjectContainer
 Inherited
swapChildrenAt(index1:int, index2:int):void
Swaps the indexes of two children.
DisplayObjectContainer
Events
 Event Summary Defined By
 InheritedDispatched when an object is added to a parent.DisplayObject
 InheritedDispatched when an object is connected to the stage (directly or indirectly).DisplayObject
 InheritedDispatched once every frame on every object that is connected to the stage.DisplayObject
 InheritedDispatched when a key on the keyboard is pressed.DisplayObject
 InheritedDispatched when a key on the keyboard is released.DisplayObject
 InheritedDispatched when an object is removed from its parent.DisplayObject
 InheritedDispatched when an object is removed from the stage and won't be rendered any longer.DisplayObject
 InheritedDispatched when an object is touched.DisplayObject
Property Detail
isFlatproperty
isFlat:Boolean  [read-only]

If true, this 3D object contains only 2D content. This means that rendering will be just as efficient as for a standard 2D object.


Implementation
    public function get isFlat():Boolean
pivotZproperty 
pivotZ:Number

The z coordinate of the object's origin in its own coordinate space (default: 0).


Implementation
    public function get pivotZ():Number
    public function set pivotZ(value:Number):void
rotationXproperty 
rotationX:Number

The rotation of the object about the x axis, in radians. (In Starling, all angles are measured in radians.)


Implementation
    public function get rotationX():Number
    public function set rotationX(value:Number):void
rotationYproperty 
rotationY:Number

The rotation of the object about the y axis, in radians. (In Starling, all angles are measured in radians.)


Implementation
    public function get rotationY():Number
    public function set rotationY(value:Number):void
rotationZproperty 
rotationZ:Number

The rotation of the object about the z axis, in radians. (In Starling, all angles are measured in radians.)


Implementation
    public function get rotationZ():Number
    public function set rotationZ(value:Number):void
scaleZproperty 
scaleZ:Number

The depth scale factor. '1' means no scale, negative values flip the object.


Implementation
    public function get scaleZ():Number
    public function set scaleZ(value:Number):void
transformationMatrixproperty 
transformationMatrix:Matrix[override]


Implementation
    public function get transformationMatrix():Matrix
    public function set transformationMatrix(value:Matrix):void
zproperty 
z:Number

The z coordinate of the object relative to the local coordinates of the parent. The z-axis points away from the camera, i.e. positive z-values will move the object further away from the viewer.


Implementation
    public function get z():Number
    public function set z(value:Number):void
Constructor Detail
Sprite3D()Constructor
public function Sprite3D()

Creates an empty Sprite3D.

Method Detail
hitTest()method
override public function hitTest(localPoint:Point):DisplayObject

Returns the object that is found topmost beneath a point in local coordinates, or nil if the test fails. Untouchable and invisible objects will cause the test to fail.

Parameters

localPoint:Point

Returns
DisplayObject
render()method 
override public function render(painter:Painter):void

Renders the display object with the help of a painter object. Never call this method directly, except from within another render method.

Parameters

painter:Painter — Captures the current render state and provides utility functions for rendering.

updateTransformationMatrices()method 
override starling_internal function updateTransformationMatrices(x:Number, y:Number, pivotX:Number, pivotY:Number, scaleX:Number, scaleY:Number, skewX:Number, skewY:Number, rotation:Number, out:Matrix, out3D:Matrix3D):void

Parameters

x:Number
 
y:Number
 
pivotX:Number
 
pivotY:Number
 
scaleX:Number
 
scaleY:Number
 
skewX:Number
 
skewY:Number
 
rotation:Number
 
out:Matrix
 
out3D:Matrix3D

updateTransformationMatrices3D()method 
starling_internal function updateTransformationMatrices3D(x:Number, y:Number, z:Number, pivotX:Number, pivotY:Number, pivotZ:Number, scaleX:Number, scaleY:Number, scaleZ:Number, rotationX:Number, rotationY:Number, rotationZ:Number, out:Matrix, out3D:Matrix3D):void

Parameters

x:Number
 
y:Number
 
z:Number
 
pivotX:Number
 
pivotY:Number
 
pivotZ:Number
 
scaleX:Number
 
scaleY:Number
 
scaleZ:Number
 
rotationX:Number
 
rotationY:Number
 
rotationZ:Number
 
out:Matrix
 
out3D:Matrix3D