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.

---