Package | starling.core |
Class | public class Starling |
Inheritance | Starling EventDispatcher Object |
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 ProfilesStage3D 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 objectFrom 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).
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 overlaySometimes 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.
MultitouchStarling 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.
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 ContextPer 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:
stage3D.requestContext3D
and
context.configureBackBuffer
).shareContext
.start()
on your Starling instance (as usual). This will make
Starling queue input events (keyboard/mouse/touch).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.
Property | Defined By | ||
---|---|---|---|
all : Vector.<Starling> [static] [read-only] All Starling instances. | Starling | ||
antiAliasing : int The antialiasing level. | Starling | ||
backBufferHeight : int [read-only] Returns the current height of the back buffer. | Starling | ||
backBufferPixelsPerPoint : int [read-only] The number of pixel per point returned by the 'backBufferWidth/Height' properties. | Starling | ||
backBufferWidth : int [read-only] Returns the current width of the back buffer. | Starling | ||
broadcastKeyboardEvents : Boolean Indicates if keyboard events are broadcast to all display objects, or dispatched
to the stage only. | 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 used for rendering. | Starling | ||
root : DisplayObject [read-only] The instance of the root class provided in the constructor. | Starling | ||
rootClass : Class The class that will be instantiated by Starling as the 'root' display object. | 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 |
Method | Defined By | ||
---|---|---|---|
Starling(rootClass:Class, stage:Stage, viewPort:Rectangle = null, stage3D:Stage3D = null, renderMode:String = auto, profile:Object = 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, 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 | ||
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 | ||
stopWithFatalError(message:String):void Stops Starling right away and displays an error message on the native overlay. | Starling |
Event | Summary | Defined By | ||
---|---|---|---|---|
Dispatched when a new render context is created. | Starling | |||
Dispatched when a fatal error is encountered. | Starling | |||
Dispatched when the display list is about to be rendered. | Starling | |||
Dispatched when the root class has been created. | Starling |
Constant | Defined By | ||
---|---|---|---|
VERSION : String = 1.8 [static] The version of the Starling framework. | Starling |
all | property |
all:Vector.<Starling>
[read-only] All Starling instances.
CAUTION: not a copy, but the actual object! Do not modify!
public static function get all():Vector.<Starling>
antiAliasing | property |
antiAliasing:int
The antialiasing level. 0 - no antialasing, 16 - maximum antialiasing.
The default value is 0
.
public function get antiAliasing():int
public function set antiAliasing(value:int):void
backBufferHeight | property |
backBufferHeight:int
[read-only] Returns the current height of the back buffer. In most cases, this value is in pixels; however, if the app is running on an HiDPI display with an activated 'supportHighResolutions' setting, you have to multiply with 'backBufferPixelsPerPoint' for the actual pixel count.
public function get backBufferHeight():int
backBufferPixelsPerPoint | property |
backBufferPixelsPerPoint:int
[read-only] The number of pixel per point returned by the 'backBufferWidth/Height' properties. Except for desktop HiDPI displays with an activated 'supportHighResolutions' setting, this will always return '1'.
public function get backBufferPixelsPerPoint():int
backBufferWidth | property |
backBufferWidth:int
[read-only] Returns the current width of the back buffer. In most cases, this value is in pixels; however, if the app is running on an HiDPI display with an activated 'supportHighResolutions' setting, you have to multiply with 'backBufferPixelsPerPoint' for the actual pixel count.
public function get backBufferWidth():int
broadcastKeyboardEvents | property |
broadcastKeyboardEvents:Boolean
Indicates if keyboard events are broadcast to all display objects, or dispatched to the stage only. In some situations, it makes sense to deactivate this setting for performance reasons.
The default value is true
.
public function get broadcastKeyboardEvents():Boolean
public function set broadcastKeyboardEvents(value:Boolean):void
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.
public function get contentScaleFactor():Number
context | property |
context:Context3D
[read-only] The render context of this instance.
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.
public function get contextData():Dictionary
contextValid | property |
contextValid:Boolean
[read-only] Indicates if the Context3D object is currently valid (i.e. it hasn't been lost or disposed).
public function get contextValid():Boolean
current | property |
current:Starling
[read-only] The currently active Starling instance.
public static function get current():Starling
enableErrorChecking | property |
enableErrorChecking:Boolean
Indicates if Stage3D render methods will report errors. It's recommended to activate this when writing custom rendering code (shaders, etc.), since you'll get more detailed error messages. However, it has a very negative impact on performance, and it prevents ATF textures from being restored on a context loss. Never activate for release builds!
The default value is false
.
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: if used carelessly, this property may have a huge impact on memory consumption. That's because, by default, it will make Starling keep a copy of each texture in memory.
However, this downside can be avoided by using the "AssetManager" to load textures. The AssetManager is smart enough to restore them directly from their sources. You can also do this by setting up "root.onRestore" on your manually loaded textures.
A context loss can happen on almost every platform. It's very common on Windows and Android, but rare on OS X and iOS (e.g. it may occur when opening up the camera roll). It's recommended to always enable this property, while using the AssetManager for texture loading.
The default value is true
.
public static function get handleLostContext():Boolean
public static function set handleLostContext(value:Boolean):void
See also
isStarted | property |
isStarted:Boolean
[read-only] Indicates if this Starling instance is started.
public function get isStarted():Boolean
juggler | property |
juggler:Juggler
[read-only] The default juggler of this instance. Will be advanced once per frame.
public function get juggler():Juggler
multitouchEnabled | property |
multitouchEnabled:Boolean
Indicates if multitouch input should be supported.
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.
public function get nativeOverlay():Sprite
nativeStage | property |
nativeStage:Stage
[read-only] The Flash (2D) stage object Starling renders beneath.
public function get nativeStage():Stage
profile | property |
profile:String
[read-only] The Context3D profile used for rendering. Beware that if you are using a shared context in AIR 3.9 / Flash Player 11 or below, this is simply what you passed to the Starling constructor.
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.
public function get root():DisplayObject
rootClass | property |
rootClass:Class
The class that will be instantiated by Starling as the 'root' display object. Must be a subclass of 'starling.display.DisplayObject'.
If you passed null
as first parameter to the Starling constructor,
you can use this property to set the root class at a later time. As soon as the class
is instantiated, Starling will dispatch a ROOT_CREATED
event.
Beware: you cannot change the root class once the root object has been instantiated.
public function get rootClass():Class
public function set rootClass(value:Class):void
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
.
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.
Beware that the memory usage should be taken with a grain of salt. The value is
determined via System.totalMemory
and does not take texture memory
into account. It is recommended to use Adobe Scout for reliable and comprehensive
memory analysis.
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
.
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.
public function get stage():Stage
stage3D | property |
stage3D:Stage3D
[read-only] The Flash Stage3D object Starling renders into.
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.
The default value is false
.
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.
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.
public function get viewPort():Rectangle
public function set viewPort(value:Rectangle):void
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.
ParametersrootClass:Class — A subclass of 'starling.display.DisplayObject'. It will be created
as soon as initialization is finished and will become the first child
of the Starling stage. Pass null if you don't want to
create a root object right away. (You can use the
rootClass property later to make that happen.)
| |
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.
|
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 |
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 |
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 |
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 |
Program3D |
render | () | method |
public function render():void
Renders the complete display list. Before rendering, the context is cleared; afterwards,
it is presented (to avoid this, enable shareContext
).
This method also dispatches an Event.RENDER
-event on the Starling
instance. That's the last opportunity to make changes before the display list is
rendered.
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 )
|
stopWithFatalError | () | method |
public function stopWithFatalError(message:String):void
Stops Starling right away and displays an error message on the native overlay. This method will also cause Starling to dispatch a FATAL_ERROR event.
Parameters
message:String |
context3DCreate | Event |
starling.events.Event
Dispatched when a new render context is created. The 'data' property references the context.
fatalError | Event |
starling.events.Event
Dispatched when a fatal error is encountered. The 'data' property contains an error string.
render | Event |
starling.events.Event
Dispatched when the display list is about to be rendered. This event provides the last opportunity to make changes before the display list is rendered.
rootCreated | Event |
starling.events.Event
Dispatched when the root class has been created. The 'data' property references that object.
VERSION | Constant |
public static const VERSION:String = 1.8
The version of the Starling framework.