Packagestarling.core
Classpublic class Starling
InheritanceStarling Inheritance EventDispatcher Inheritance Object

The Starling class represents the core of the Starling framework.

The Starling framework makes it possible to create 2D applications and games that make use of the Stage3D architecture introduced in Flash Player 11. It implements a display tree system that is very similar to that of conventional Flash, while leveraging modern GPUs to speed up rendering.

The Starling class represents the link between the conventional Flash display tree and the Starling display tree. To create a Starling-powered application, you have to create an instance of the Starling class:

var starling:Starling = new Starling(Game, stage);

The first parameter has to be a Starling display object class, e.g. a subclass of starling.display.Sprite. In the sample above, the class "Game" is the application root. An instance of "Game" will be created as soon as Starling is initialized. The second parameter is the conventional (Flash) stage object. Per default, Starling will display its contents directly below the stage.

It is recommended to store the Starling instance as a member variable, to make sure that the Garbage Collector does not destroy it. After creating the Starling object, you have to start it up like this:

starling.start();

It will now render the contents of the "Game" class in the frame rate that is set up for the application (as defined in the Flash stage).

Context3D Profiles

Stage3D supports different rendering profiles, and Starling works with all of them. The last parameter of the Starling constructor allows you to choose which profile you want. The following profiles are available:

The recommendation is to deploy your app with the profile "auto" (which makes Starling pick the best available of those three), but test it in all available profiles.

Accessing the Starling object

From within your application, you can access the current Starling object anytime through the static method Starling.current. It will return the active Starling instance (most applications will only have one Starling object, anyway).

Viewport

The area the Starling content is rendered into is, per default, the complete size of the stage. You can, however, use the "viewPort" property to change it. This can be useful when you want to render only into a part of the screen, or if the player size changes. For the latter, you can listen to the RESIZE-event dispatched by the Starling stage.

Native overlay

Sometimes you will want to display native Flash content on top of Starling. That's what the nativeOverlay property is for. It returns a Flash Sprite lying directly on top of the Starling content. You can add conventional Flash objects to that overlay.

Beware, though, that conventional Flash content on top of 3D content can lead to performance penalties on some (mobile) platforms. For that reason, always remove all child objects from the overlay when you don't need them any longer. Starling will remove the overlay from the display list when it's empty.

Multitouch

Starling supports multitouch input on devices that provide it. During development, where most of us are working with a conventional mouse and keyboard, Starling can simulate multitouch events with the help of the "Shift" and "Ctrl" (Mac: "Cmd") keys. Activate this feature by enabling the simulateMultitouch property.

Handling a lost render context

On some operating systems and under certain conditions (e.g. returning from system sleep), Starling's stage3D render context may be lost. Starling can recover from a lost context if the class property "handleLostContext" is set to "true". Keep in mind, however, that this comes at the price of increased memory consumption; Starling will cache textures in RAM to be able to restore them when the context is lost. (Except if you use the 'AssetManager' for your textures. It is smart enough to recreate a texture directly from its origin.)

In case you want to react to a context loss, Starling dispatches an event with the type "Event.CONTEXT3D_CREATE" when the context is restored. You can recreate any invalid resources in a corresponding event listener.

Sharing a 3D Context

Per default, Starling handles the Stage3D context itself. If you want to combine Starling with another Stage3D engine, however, this may not be what you want. In this case, you can make use of the shareContext property:

  1. Manually create and configure a context3D object that both frameworks can work with (through stage3D.requestContext3D and context.configureBackBuffer).
  2. Initialize Starling with the stage3D instance that contains that configured context. This will automatically enable shareContext.
  3. Call start() on your Starling instance (as usual). This will make Starling queue input events (keyboard/mouse/touch).
  4. Create a game loop (e.g. using the native ENTER_FRAME event) and let it call Starling's nextFrame as well as the equivalent method of the other Stage3D engine. Surround those calls with context.clear() and context.present().

The Starling wiki contains a tutorial with more information about this topic.



Public Properties
 PropertyDefined By
  all : Vector.<Starling>
[static] [read-only] All Starling instances.
Starling
  antiAliasing : int
The antialiasing level.
Starling
  backBufferHeight : int
[read-only] Returns the actual height (in pixels) of the back buffer.
Starling
  backBufferWidth : int
[read-only] Returns the actual width (in pixels) of the back buffer.
Starling
  contentScaleFactor : Number
[read-only] The ratio between viewPort width and stage width.
Starling
  context : Context3D
[read-only] The render context of this instance.
Starling
  contextData : Dictionary
[read-only] A dictionary that can be used to save custom data related to the current context.
Starling
  contextValid : Boolean
[read-only] Indicates if the Context3D object is currently valid (i.e.
Starling
  current : Starling
[static] [read-only] The currently active Starling instance.
Starling
  enableErrorChecking : Boolean
Indicates if Stage3D render methods will report errors.
Starling
  handleLostContext : Boolean
[static] Indicates if Starling should automatically recover from a lost device context.
Starling
  isStarted : Boolean
[read-only] Indicates if this Starling instance is started.
Starling
  juggler : Juggler
[read-only] The default juggler of this instance.
Starling
  multitouchEnabled : Boolean
[static] Indicates if multitouch input should be supported.
Starling
  nativeOverlay : Sprite
[read-only] A Flash Sprite placed directly on top of the Starling content.
Starling
  nativeStage : Stage
[read-only] The Flash (2D) stage object Starling renders beneath.
Starling
  profile : String
[read-only] The Context3D profile as requested in the constructor.
Starling
  root : DisplayObject
[read-only] The instance of the root class provided in the constructor.
Starling
  shareContext : Boolean
Indicates if the Context3D render calls are managed externally to Starling, to allow other frameworks to share the Stage3D instance.
Starling
  showStats : Boolean
Indicates if a small statistics box (with FPS, memory usage and draw count) is displayed.
Starling
  simulateMultitouch : Boolean
Indicates if multitouch simulation with "Shift" and "Ctrl"/"Cmd"-keys is enabled.
Starling
  stage : Stage
[read-only] The Starling stage object, which is the root of the display tree that is rendered.
Starling
  stage3D : Stage3D
[read-only] The Flash Stage3D object Starling renders into.
Starling
  supportHighResolutions : Boolean
Indicates that if the device supports HiDPI screens Starling will attempt to allocate a larger back buffer than indicated via the viewPort size.
Starling
  touchProcessor : TouchProcessor
The TouchProcessor is passed all mouse and touch input and is responsible for dispatching TouchEvents to the Starling display tree.
Starling
  viewPort : Rectangle
The viewport into which Starling contents will be rendered.
Starling
Public Methods
 MethodDefined By
  
Starling(rootClass:Class, stage:Stage, viewPort:Rectangle = null, stage3D:Stage3D = null, renderMode:String = auto, profile:Object = baselineConstrained)
Creates a new Starling instance.
Starling
 Inherited
addEventListener(type:String, listener:Function):void
Registers an event listener at a certain object.
EventDispatcher
  
advanceTime(passedTime:Number):void
Dispatches ENTER_FRAME events on the display list, advances the Juggler and processes touches.
Starling
  
deleteProgram(name:String):void
Deletes the vertex- and fragment-programs of a certain name.
Starling
 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
  
dispose():void
Disposes all children of the stage and the render context; removes all registered event listeners.
Starling
  
getProgram(name:String):Program3D
Returns the vertex- and fragment-programs registered under a certain name.
Starling
 Inherited
hasEventListener(type:String):Boolean
Returns if there are listeners registered for a certain event type.
EventDispatcher
  
hasProgram(name:String):Boolean
Indicates if a set of vertex- and fragment-programs is registered under a certain name.
Starling
  
Make this Starling instance the current one.
Starling
  
nextFrame():void
Calls advanceTime() (with the time that has passed since the last frame) and render().
Starling
  
registerProgram(name:String, vertexShader:ByteArray, fragmentShader:ByteArray):Program3D
Registers a compiled shader-program under a certain name.
Starling
  
registerProgramFromSource(name:String, vertexShader:String, fragmentShader:String):Program3D
Compiles a shader-program and registers it under a certain name.
Starling
 Inherited
removeEventListener(type:String, listener:Function):void
Removes an event listener from the object.
EventDispatcher
 Inherited
removeEventListeners(type:String = null):void
Removes all event listeners with a certain type, or all of them if type is null.
EventDispatcher
  
render():void
Renders the complete display list.
Starling
  
showStatsAt(hAlign:String = left, vAlign:String = top, scale:Number = 1):void
Displays the statistics box at a certain position.
Starling
  
start():void
As soon as Starling is started, it will queue input events (keyboard/mouse/touch); furthermore, the method nextFrame will be called once per Flash Player frame.
Starling
  
stop(suspendRendering:Boolean = false):void
Stops all logic and input processing, effectively freezing the app in its current state.
Starling
Events
 Event Summary Defined By
  Dispatched when a new render context is created.Starling
  Dispatched when the root class has been created.Starling
Public Constants
 ConstantDefined By
  VERSION : String = 1.5
[static] The version of the Starling framework.
Starling
Property Detail
allproperty
all:Vector.<Starling>  [read-only]

All Starling instances.

CAUTION: not a copy, but the actual object! Do not modify!


Implementation
    public static function get all():Vector.<Starling>
antiAliasingproperty 
antiAliasing:int

The antialiasing level. 0 - no antialasing, 16 - maximum antialiasing.

The default value is 0.


Implementation
    public function get antiAliasing():int
    public function set antiAliasing(value:int):void
backBufferHeightproperty 
backBufferHeight:int  [read-only]

Returns the actual height (in pixels) of the back buffer. This can differ from the height of the viewPort rectangle if it is partly outside the native stage.


Implementation
    public function get backBufferHeight():int
backBufferWidthproperty 
backBufferWidth:int  [read-only]

Returns the actual width (in pixels) of the back buffer. This can differ from the width of the viewPort rectangle if it is partly outside the native stage.


Implementation
    public function get backBufferWidth():int
contentScaleFactorproperty 
contentScaleFactor:Number  [read-only]

The ratio between viewPort width and stage width. Useful for choosing a different set of textures depending on the display resolution.


Implementation
    public function get contentScaleFactor():Number
contextproperty 
context:Context3D  [read-only]

The render context of this instance.


Implementation
    public function get context():Context3D
contextDataproperty 
contextData:Dictionary  [read-only]

A dictionary that can be used to save custom data related to the current context. If you need to share data that is bound to a specific stage3D instance (e.g. textures), use this dictionary instead of creating a static class variable. The Dictionary is actually bound to the stage3D instance, thus it survives a context loss.


Implementation
    public function get contextData():Dictionary
contextValidproperty 
contextValid:Boolean  [read-only]

Indicates if the Context3D object is currently valid (i.e. it hasn't been lost or disposed). Beware that each call to this method causes a String allocation (due to internal code Starling can't avoid), so do not call this method too often.


Implementation
    public function get contextValid():Boolean
currentproperty 
current:Starling  [read-only]

The currently active Starling instance.


Implementation
    public static function get current():Starling
enableErrorCheckingproperty 
enableErrorChecking:Boolean

Indicates if Stage3D render methods will report errors. Activate only when needed, as this has a negative impact on performance.

The default value is false.


Implementation
    public function get enableErrorChecking():Boolean
    public function set enableErrorChecking(value:Boolean):void
handleLostContextproperty 
handleLostContext:Boolean

Indicates if Starling should automatically recover from a lost device context. On some systems, an upcoming screensaver or entering sleep mode may invalidate the render context. This setting indicates if Starling should recover from such incidents. Beware that this has a huge impact on memory consumption! It is recommended to enable this setting on Android and Windows, but to deactivate it on iOS and Mac OS X.

The default value is false.


Implementation
    public static function get handleLostContext():Boolean
    public static function set handleLostContext(value:Boolean):void
isStartedproperty 
isStarted:Boolean  [read-only]

Indicates if this Starling instance is started.


Implementation
    public function get isStarted():Boolean
jugglerproperty 
juggler:Juggler  [read-only]

The default juggler of this instance. Will be advanced once per frame.


Implementation
    public function get juggler():Juggler
multitouchEnabledproperty 
multitouchEnabled:Boolean

Indicates if multitouch input should be supported.


Implementation
    public static function get multitouchEnabled():Boolean
    public static function set multitouchEnabled(value:Boolean):void
nativeOverlayproperty 
nativeOverlay:Sprite  [read-only]

A Flash Sprite placed directly on top of the Starling content. Use it to display native Flash components.


Implementation
    public function get nativeOverlay():Sprite
nativeStageproperty 
nativeStage:Stage  [read-only]

The Flash (2D) stage object Starling renders beneath.


Implementation
    public function get nativeStage():Stage
profileproperty 
profile:String  [read-only]

The Context3D profile as requested in the constructor. Beware that if you are using a shared context, this is simply what you passed to the Starling constructor.


Implementation
    public function get profile():String
rootproperty 
root:DisplayObject  [read-only]

The instance of the root class provided in the constructor. Available as soon as the event 'ROOT_CREATED' has been dispatched.


Implementation
    public function get root():DisplayObject
shareContextproperty 
shareContext:Boolean

Indicates if the Context3D render calls are managed externally to Starling, to allow other frameworks to share the Stage3D instance.

The default value is false.


Implementation
    public function get shareContext():Boolean
    public function set shareContext(value:Boolean):void
showStatsproperty 
showStats:Boolean

Indicates if a small statistics box (with FPS, memory usage and draw count) is displayed.


Implementation
    public function get showStats():Boolean
    public function set showStats(value:Boolean):void
simulateMultitouchproperty 
simulateMultitouch:Boolean

Indicates if multitouch simulation with "Shift" and "Ctrl"/"Cmd"-keys is enabled.

The default value is false.


Implementation
    public function get simulateMultitouch():Boolean
    public function set simulateMultitouch(value:Boolean):void
stageproperty 
stage:Stage  [read-only]

The Starling stage object, which is the root of the display tree that is rendered.


Implementation
    public function get stage():Stage
stage3Dproperty 
stage3D:Stage3D  [read-only]

The Flash Stage3D object Starling renders into.


Implementation
    public function get stage3D():Stage3D
supportHighResolutionsproperty 
supportHighResolutions:Boolean

Indicates that if the device supports HiDPI screens Starling will attempt to allocate a larger back buffer than indicated via the viewPort size. Note that this is used on Desktop only; mobile AIR apps still use the "requestedDisplayResolution" parameter the application descriptor XML.


Implementation
    public function get supportHighResolutions():Boolean
    public function set supportHighResolutions(value:Boolean):void
touchProcessorproperty 
touchProcessor:TouchProcessor

The TouchProcessor is passed all mouse and touch input and is responsible for dispatching TouchEvents to the Starling display tree. If you want to handle these types of input manually, pass your own custom subclass to this property.


Implementation
    public function get touchProcessor():TouchProcessor
    public function set touchProcessor(value:TouchProcessor):void
viewPortproperty 
viewPort:Rectangle

The viewport into which Starling contents will be rendered.


Implementation
    public function get viewPort():Rectangle
    public function set viewPort(value:Rectangle):void
Constructor Detail
Starling()Constructor
public function Starling(rootClass:Class, stage:Stage, viewPort:Rectangle = null, stage3D:Stage3D = null, renderMode:String = auto, profile:Object = baselineConstrained)

Creates a new Starling instance.

Parameters
rootClass:Class — A subclass of a Starling display object. It will be created as soon as initialization is finished and will become the first child of the Starling stage.
 
stage:Stage — The Flash (2D) stage.
 
viewPort:Rectangle (default = null) — A rectangle describing the area into which the content will be rendered. Default: stage size
 
stage3D:Stage3D (default = null) — The Stage3D object into which the content will be rendered. If it already contains a context, sharedContext will be set to true. Default: the first available Stage3D.
 
renderMode:String (default = auto) — The Context3D render mode that should be requested. Use this parameter if you want to force "software" rendering.
 
profile:Object (default = baselineConstrained) — The Context3D profile that should be requested.
  • If you pass a profile String, this profile is enforced.
  • Pass an Array of profiles to make Starling pick the first one that works (starting with the first array element).
  • Pass the String "auto" to make Starling pick the best available profile automatically.
Method Detail
advanceTime()method
public function advanceTime(passedTime:Number):void

Dispatches ENTER_FRAME events on the display list, advances the Juggler and processes touches.

Parameters

passedTime:Number

deleteProgram()method 
public function deleteProgram(name:String):void

Deletes the vertex- and fragment-programs of a certain name.

Parameters

name:String

dispose()method 
public function dispose():void

Disposes all children of the stage and the render context; removes all registered event listeners.

getProgram()method 
public function getProgram(name:String):Program3D

Returns the vertex- and fragment-programs registered under a certain name.

Parameters

name:String

Returns
Program3D
hasProgram()method 
public function hasProgram(name:String):Boolean

Indicates if a set of vertex- and fragment-programs is registered under a certain name.

Parameters

name:String

Returns
Boolean
makeCurrent()method 
public function makeCurrent():void

Make this Starling instance the current one.

nextFrame()method 
public function nextFrame():void

Calls advanceTime() (with the time that has passed since the last frame) and render().

registerProgram()method 
public function registerProgram(name:String, vertexShader:ByteArray, fragmentShader:ByteArray):Program3D

Registers a compiled shader-program under a certain name. If the name was already used, the previous program is overwritten.

Parameters

name:String
 
vertexShader:ByteArray
 
fragmentShader:ByteArray

Returns
Program3D
registerProgramFromSource()method 
public function registerProgramFromSource(name:String, vertexShader:String, fragmentShader:String):Program3D

Compiles a shader-program and registers it under a certain name. If the name was already used, the previous program is overwritten.

Parameters

name:String
 
vertexShader:String
 
fragmentShader:String

Returns
Program3D
render()method 
public function render():void

Renders the complete display list. Before rendering, the context is cleared; afterwards, it is presented. This can be avoided by enabling shareContext.

showStatsAt()method 
public function showStatsAt(hAlign:String = left, vAlign:String = top, scale:Number = 1):void

Displays the statistics box at a certain position.

Parameters

hAlign:String (default = left)
 
vAlign:String (default = top)
 
scale:Number (default = 1)

start()method 
public function start():void

As soon as Starling is started, it will queue input events (keyboard/mouse/touch); furthermore, the method nextFrame will be called once per Flash Player frame. (Except when shareContext is enabled: in that case, you have to call that method manually.)

stop()method 
public function stop(suspendRendering:Boolean = false):void

Stops all logic and input processing, effectively freezing the app in its current state. Per default, rendering will continue: that's because the classic display list is only updated when stage3D is. (If Starling stopped rendering, conventional Flash contents would freeze, as well.)

However, if you don't need classic Flash contents, you can stop rendering, too. On some mobile systems (e.g. iOS), you are even required to do so if you have activated background code execution.

Parameters

suspendRendering:Boolean (default = false)

Event Detail
context3DCreate Event
Event Object Type: starling.events.Event

Dispatched when a new render context is created.

rootCreated Event  
Event Object Type: starling.events.Event

Dispatched when the root class has been created.

Constant Detail
VERSIONConstant
public static const VERSION:String = 1.5

The version of the Starling framework.