Creates a new Starling instance.
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.)
The Flash (2D) stage.
A rectangle describing the area into which the content will be rendered. Default: stage size
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.
The Context3D render mode that should be requested. Use this parameter if you want to force "software" rendering.
The Context3D profile that should be requested.
<ul>
<li>If you pass a profile String, this profile is enforced.</li>
<li>Pass an Array of profiles to make Starling pick the first
one that works (starting with the first array element).</li>
<li>Pass the String "auto" to make Starling pick the best available
profile automatically.</li>
</ul>
The antialiasing level. 0 - no antialasing, 16 - maximum antialiasing. @default 0
The ratio between viewPort width and stage width. Useful for choosing a different set of textures depending on the display resolution.
The render context of this instance.
Indicates if the Context3D object is currently valid (i.e. it hasn't been lost or disposed).
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 number of frames that have been rendered since this instance was created.
Indicates if this Starling instance is started.
The default juggler of this instance. Will be advanced once per frame.
A Flash Sprite placed directly on top of the Starling content. Use it to display native Flash components.
The Flash (2D) stage object Starling renders beneath.
The painter, which is used for all rendering. The same instance is passed to all
render
methods each frame.
The Context3D profile of the current render context, or null
if the context has not been created yet.
The instance of the root class provided in the constructor. Available as soon as the event 'ROOT_CREATED' has been dispatched.
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.
Indicates if another Starling instance (or another Stage3D framework altogether) uses the same render context. If enabled, Starling will not execute any destructive context operations (e.g. not call 'configureBackBuffer', 'clear', 'present', etc. This has to be done manually, then. @default false
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.
Indicates if multitouch simulation with "Shift" and "Ctrl"/"Cmd"-keys is enabled. @default false
When enabled, Starling will skip rendering the stage if it hasn't changed since the last frame. This is great for apps that remain static from time to time, since it will greatly reduce power consumption. You should activate this whenever possible!
The reason why it's disabled by default is just that it causes problems with Render-
and VideoTextures. When you use those, you either have to disable this property
temporarily, or call setRequiresRedraw()
(ideally on the stage) whenever
those textures are changing. Otherwise, the changes won't show up.
@default false
The Starling stage object, which is the root of the display tree that is rendered.
The Flash Stage3D object Starling renders into.
If enabled, the Stage3D back buffer will change its size according to the browser zoom value - similar to what's done when "supportHighResolutions" is enabled. The resolution is updated on the fly when the zoom factor changes. Only relevant for the browser plugin. @default false
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. @default false
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.
The viewport into which Starling contents will be rendered.
The version of the Starling framework.
All Starling instances.
CAUTION: not a copy, but the actual object! Do not modify!
The currently active Starling instance.
Indicates if multitouch input should be supported.
Registers an event listener at a certain object.
Dispatches ENTER_FRAME events on the display list, advances the Juggler and processes touches.
Dispatches an event to all objects that have registered listeners for its type. If an event with enabled 'bubble' property is dispatched to a display object, it will travel up along the line of parents, until it either hits the root object or someone stops its propagation manually.
Dispatches an event with the given parameters to all objects that have registered listeners for the given type. The method uses an internal pool of event objects to avoid allocations.
Disposes all children of the stage and the render context; removes all registered event listeners.
If called with one argument, figures out if there are any listeners registered for the given event type. If called with two arguments, also determines if a specific listener is registered.
Make this Starling instance the current
one.
Calls advanceTime()
(with the time that has passed since the last frame)
and render()
.
Removes an event listener from the object.
Removes all event listeners with a certain type, or all of them if type is null. Be careful when removing all event listeners: you never know who else was listening.
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.
Makes sure that the next frame is actually rendered.
When skipUnchangedFrames
is enabled, some situations require that you
manually force a redraw, e.g. when a RenderTexture is changed. This method is the
easiest way to do so; it's just a shortcut to stage.setRequiresRedraw()
.
Displays the statistics box at a certain position.
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.)
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.
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.
Generated using TypeDoc
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:
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:
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), but to 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.
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.Skipping Unchanged Frames
It happens surprisingly often in an app or game that a scene stays completely static for several frames. So why redraw the stage at all in those situations? That's exactly the point of the
skipUnchangedFrames
-property. If enabled, static scenes are recognized as such and the back buffer is simply left as it is. On a mobile device, the impact of this feature can't be overestimated! There's simply no better way to enhance battery life. Make it a habit to always activate it; look at the documentation of the corresponding property for details.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 will try to recover from a lost context automatically; to be able to do this, it will cache textures in RAM. This will take up quite a bit of extra memory, though, which might be problematic especially on mobile platforms. To avoid the higher memory footprint, it's recommended to load your textures with Starling's "AssetManager"; it is smart enough to recreate a texture directly from its origin.
In case you want to react to a context loss manually, Starling dispatches an event with the type "Event.CONTEXT3D_CREATE" when the context is restored, and textures will execute their
root.onRestore
callback, to which you can attach your own logic. Refer to the "Texture" class for more information.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:RenderUtil.requestContext3D
andcontext.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'snextFrame
as well as the equivalent method of the other Stage3D engine. Surround those calls withcontext.clear()
andcontext.present()
.The Starling wiki contains a tutorial with more information about this topic.
@see starling.utils.AssetManager @see starling.textures.Texture