GODPAPER | All Packages | All Classes | Index | Frames No Frames |
Starling

Package | starling.core
Class | public class Starling
Inheritance | Starling EventDispatcher 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).

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.

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 independently. 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

| Property | Defined By
--- | --- | ---
|  | 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
|  | 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
Hide Inherited Public Methods
Show Inherited Public Methods

| Method | Defined By
--- | --- | ---
|  | Starling(rootClass:Class, stage:Stage, viewPort:Rectangle = null, stage3D:Stage3D = null, renderMode:String = auto, profile:String = baselineConstrained) Creates a new Starling instance. | Starling
|  | 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
|  | 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 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
|  | 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
|  | makeCurrent():void 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, vertexProgram:ByteArray, fragmentProgram:ByteArray):Program3D Registers a vertex- and fragment-program under a certain name. | Starling
|  | removeEventListener(type:String, listener:Function):void Removes an event listener from the object. | EventDispatcher
|  | 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
--- | --- | --- | ---
|  | context3DCreate | Dispatched when a new render context is created. | Starling
|  | rootCreated | Dispatched when the root class has been created. | Starling

Public Constants

| Constant | Defined By
--- | --- | ---
|  | VERSION : String = 1.4 [static] The version of the Starling framework. | Starling

Property Detail

antiAliasing | property

`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`

backBufferHeight | property |

`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`

backBufferWidth | property |

`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`

contentScaleFactor | property |

`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`

context | property |

`context:Context3D` [read-only]

The render context of this instance.

Implementation
`public function get context():Context3D`

contextData | property |

`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`

current | property |

`current:Starling` [read-only]

The currently active Starling instance.

Implementation
`public static function get current():Starling`

enableErrorChecking | property |

`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`

handleLostContext | property |

`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`

isStarted | property |

`isStarted:Boolean` [read-only]

Indicates if this Starling instance is started.

Implementation
`public function get isStarted():Boolean`

juggler | property |

`juggler:Juggler` [read-only]

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

Implementation
`public function get juggler():Juggler`

multitouchEnabled | property |

`multitouchEnabled:Boolean`

Indicates if multitouch input should be supported.

Implementation
`public static function get multitouchEnabled():Boolean`
`public static function set multitouchEnabled(value:Boolean):void`

nativeOverlay | property |

`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`

nativeStage | property |

`nativeStage:Stage` [read-only]

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

Implementation
`public function get nativeStage():Stage`

profile | property |

`profile:String` [read-only]

The Context3D profile as requested in the constructor. Beware that if you are using a shared context, this might not be accurate.

Implementation
`public function get profile():String`

root | property |

`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`

shareContext | property |

`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`

showStats | property |

`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`

simulateMultitouch | property |

`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`

stage | property |

`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`

stage3D | property |

`stage3D:Stage3D` [read-only]

The Flash Stage3D object Starling renders into.

Implementation
`public function get stage3D():Stage3D`

supportHighResolutions | property |

`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`

touchProcessor | property |

`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`

viewPort | property |

`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:String = 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.
| `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`.
| `renderMode:String` (default = `auto`)`` — Use this parameter to force "software" rendering.
| `profile:String` (default = `baselineConstrained`)`` — The Context3DProfile that should be requested.

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, vertexProgram:ByteArray, fragmentProgram:ByteArray):Program3D`

Registers a vertex- and fragment-program under a certain name. If the name was already used, the previous program is overwritten.

Parameters

| `name:String`
| `vertexProgram:ByteArray`
| `fragmentProgram:ByteArray`

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

VERSION | Constant

`public static const VERSION:String = 1.4`

The version of the Starling framework.

Thu Jan 16 2014, 01:11 PM +08:00