starling.display.Sprite3D

Package	starling.display
Class	public class Sprite3D
Inheritance	Sprite3D DisplayObjectContainer DisplayObject EventDispatcher 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:

z - Moves the sprite closer to / further away from the camera.
rotationX — Rotates the sprite around the x-axis.
rotationY — Rotates the sprite around the y-axis.
scaleZ - Scales the sprite along the z-axis.
pivotZ - Moves the pivot point along the z-axis.

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

Hide Inherited Public Properties

Show Inherited Public Properties

	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
		filter : FragmentFilter The filter that is attached to the display object.	DisplayObject
		height : Number The height of the object in pixels.	DisplayObject
		is3D : Boolean [read-only] Indicates if this object or any of its parents is a 'Sprite3D' object.	DisplayObject
		mask : DisplayObject The display object that acts as a mask for the current object.	DisplayObject
		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 [override] The x coordinate of the object's origin in its own coordinate space (default: 0).	Sprite3D
		pivotY : Number [override] The y coordinate of the object's origin in its own coordinate space (default: 0).	Sprite3D
		pivotZ : Number The z coordinate of the object's origin in its own coordinate space (default: 0).	Sprite3D
		requiresRedraw : Boolean [read-only] Indicates if the object needs to be redrawn in the upcoming frame, i.e.	DisplayObject
		root : DisplayObject [read-only] The root object the display object is connected to (i.e.	DisplayObject
		rotation : Number [override] The rotation of the object about the z axis, in radians.	Sprite3D
		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
		scale : Number Sets both 'scaleX' and 'scaleY' to the same value.	DisplayObject
		scaleX : Number [override] The horizontal scale factor.	Sprite3D
		scaleY : Number [override] The vertical scale factor.	Sprite3D
		scaleZ : Number The depth scale factor.	Sprite3D
		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 [override] The 2D transformation matrix of the object relative to its parent — if it can be represented in such a matrix (the values of 'z', 'rotationX/Y', and 'pivotZ' are zero).	Sprite3D
		transformationMatrix3D : Matrix3D [override] [read-only] The 3D transformation matrix of the object relative to its parent.	Sprite3D
		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 [override] The x coordinate of the object relative to the local coordinates of the parent.	Sprite3D
		y : Number [override] The y coordinate of the object relative to the local coordinates of the parent.	Sprite3D
		z : Number The z coordinate of the object relative to the local coordinates of the parent.	Sprite3D

Public Methods

Hide Inherited Public Methods

Show Inherited Public Methods

	Method		Defined By
		Sprite3D() Creates an empty Sprite3D.	Sprite3D
		addChild(child:DisplayObject):DisplayObject Adds a child to the container.	DisplayObjectContainer
		addChildAt(child:DisplayObject, index:int):DisplayObject Adds a child to the container at a certain index.	DisplayObjectContainer
		addEventListener(type:String, listener:Function):void [override] Registers an event listener at a certain object.	DisplayObject
		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
		broadcastEvent(event:Event):void Dispatches an event on all children (recursively).	DisplayObjectContainer
		broadcastEventWith(eventType: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 Dispatches an event to all objects that have registered listeners for its type.	EventDispatcher
		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.	DisplayObjectContainer
		getBounds(targetSpace:DisplayObject, out:Rectangle = null):Rectangle [override] Returns a rectangle that completely encloses the object as it appears in another coordinate system.	DisplayObjectContainer
		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
		getTransformationMatrix(targetSpace:DisplayObject, out:Matrix = null):Matrix Creates a matrix that represents the transformation from the local coordinate system to another.	DisplayObject
		getTransformationMatrix3D(targetSpace:DisplayObject, out:Matrix3D = null):Matrix3D Creates a matrix that represents the transformation from the local coordinate system to another.	DisplayObject
		globalToLocal(globalPoint:Point, out:Point = null):Point Transforms a point from global (stage) coordinates to the local coordinate system.	DisplayObject
		globalToLocal3D(globalPoint:Point, out:Vector3D = null):Vector3D Transforms a point from global (stage) coordinates to the 3D local coordinate system.	DisplayObject
		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
		hitTestMask(localPoint:Point):Boolean Checks if a certain point is inside the display object's mask.	DisplayObject
		local3DToGlobal(localPoint:Vector3D, out:Point = null):Point Transforms a 3D point from the local coordinate system to global (stage) coordinates.	DisplayObject
		localToGlobal(localPoint:Point, out:Point = null):Point Transforms a point from the local coordinate system to global (stage) coordinates.	DisplayObject
		removeChild(child:DisplayObject, dispose:Boolean = false):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] Removes an event listener from the object.	DisplayObject
		removeEventListeners(type:String = null):void [override] Removes all event listeners with a certain type, or all of them if type is null.	DisplayObject
		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
		setChildIndex(child:DisplayObject, index:int):void Moves a child to a certain index.	DisplayObjectContainer
		setRequiresRedraw():void Forces the object to be redrawn in the next frame.	DisplayObject
		sortChildren(compareFunction:Function):void Sorts the children according to a given function (that works just like the sort function of the Vector class).	DisplayObjectContainer
		swapChildren(child1:DisplayObject, child2:DisplayObject):void Swaps the indexes of two children.	DisplayObjectContainer
		swapChildrenAt(index1:int, index2:int):void Swaps the indexes of two children.	DisplayObjectContainer

Summary	Defined By
added	Dispatched when an object is added to a parent.	DisplayObject
addedToStage	Dispatched when an object is connected to the stage (directly or indirectly).	DisplayObject
enterFrame	Dispatched once every frame on every object that is connected to the stage.	DisplayObject
keyDown	Dispatched when a key on the keyboard is pressed.	DisplayObject
keyUp	Dispatched when a key on the keyboard is released.	DisplayObject
removed	Dispatched when an object is removed from its parent.	DisplayObject
removedFromStage	Dispatched when an object is removed from the stage and won't be rendered any longer.	DisplayObject
touch	Dispatched when an object is touched.	DisplayObject

Property Detail

pivotX

property

pivotX:Number[override]

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

Implementation
public function get pivotX():Number
public function set pivotX(value:Number):void

pivotY

property

pivotY:Number[override]

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

Implementation
public function get pivotY():Number
public function set pivotY(value:Number):void

pivotZ

property

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

rotation

property

rotation:Number[override]

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

Implementation
public function get rotation():Number
public function set rotation(value:Number):void

rotationX

property

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

rotationY

property

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

rotationZ

property

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

scaleX

property

scaleX:Number[override]

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

Implementation
public function get scaleX():Number
public function set scaleX(value:Number):void

scaleY

property

scaleY:Number[override]

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

Implementation
public function get scaleY():Number
public function set scaleY(value:Number):void

scaleZ

property

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

transformationMatrix

property

transformationMatrix:Matrix[override]

The 2D transformation matrix of the object relative to its parent — if it can be represented in such a matrix (the values of 'z', 'rotationX/Y', and 'pivotZ' are zero). Otherwise, the identity matrix. CAUTION: not a copy, but the actual object!

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

transformationMatrix3D

property

transformationMatrix3D:Matrix3D [read-only] [override]

The 3D transformation matrix of the object relative to its parent. CAUTION: not a copy, but the actual object!

Implementation
public function get transformationMatrix3D():Matrix3D

property

x:Number[override]

The x coordinate of the object relative to the local coordinates of the parent.

Implementation
public function get x():Number
public function set x(value:Number):void

property

y:Number[override]

The y coordinate of the object relative to the local coordinates of the parent.

Implementation
public function get y():Number
public function set y(value:Number):void

property

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.

Mon Apr 18 2016, 08:17 PM +02:00

Starling Framework Reference (v2.0)	All Packages \| All Classes \| Index \| Frames No Frames
Sprite3D	Properties \| Methods \| Events