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), 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).
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.
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.
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.
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 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.
* * @see starling.utils.AssetManager * @see starling.textures.Texture * */ @:jsRequire("starling/core/Starling", "default") extern class Starling extends EventDispatcher { /** The version of the Starling framework. */ public static var VERSION:String; // construction /** Creates a new Starling instance. * @param rootClass 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. Passnull if you don't want to
* create a root object right away. (You can use the
* rootClass property later to make that happen.)
* @param stage The Flash (2D) stage.
* @param viewPort A rectangle describing the area into which the content will be
* rendered. Default: stage size
* @param stage3D 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.
* @param renderMode The Context3D render mode that should be requested.
* Use this parameter if you want to force "software" rendering.
* @param profile The Context3D profile that should be requested.
*
* advanceTime() (with the time that has passed since the last frame)
* and render(). */
public function nextFrame():Void;
/** Dispatches ENTER_FRAME events on the display list, advances the Juggler
* and processes touches. */
public function advanceTime(passedTime:Float):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.
current one. */
public function makeCurrent():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.) */
public function start():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.
*/ public function stop(suspendRendering:Bool=false):Void; /** 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().
*
rendermethods each frame. */
public var painter(get, never):Painter;
private function get_painter():Painter;
/** The render context of this instance. */
public var context(get, never):Context3D;
private function get_context():Context3D;
/** Indicates if multitouch simulation with "Shift" and "Ctrl"/"Cmd"-keys is enabled.
* @default false */
public var simulateMultitouch(get, set):Bool;
private function get_simulateMultitouch():Bool;
private function set_simulateMultitouch(value:Bool):Bool;
/** 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!
*
* @default false */
public var enableErrorChecking(get, set):Bool;
private function get_enableErrorChecking():Bool;
private function set_enableErrorChecking(value:Bool):Bool;
/** The antialiasing level. 0 - no antialasing, 16 - maximum antialiasing. @default 0 */
public var antiAliasing(get, set):Int;
private function get_antiAliasing():Int;
private function set_antiAliasing(value:Int):Int;
/** The viewport into which Starling contents will be rendered. */
public var viewPort(get, set):Rectangle;
private function get_viewPort():Rectangle;
private function set_viewPort(value:Rectangle):Rectangle;
/** The ratio between viewPort width and stage width. Useful for choosing a different
* set of textures depending on the display resolution. */
public var contentScaleFactor(get, never):Float;
private function get_contentScaleFactor():Float;
/** A Flash Sprite placed directly on top of the Starling content. Use it to display native
* Flash components. */
public var nativeOverlay(get, never):Sprite;
private function get_nativeOverlay():Sprite;
/** 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.
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 var rootClass(get, set):Classnull
* if the context has not been created yet. */
public var profile(get, never):Context3DProfile;
private function get_profile():Context3DProfile;
/** 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 */
public var supportHighResolutions(get, set):Bool;
private function get_supportHighResolutions():Bool;
private function set_supportHighResolutions(value:Bool):Bool;
/** 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 */
public var supportBrowserZoom(get, set):Bool;
private function get_supportBrowserZoom():Bool;
private function set_supportBrowserZoom(value:Bool):Bool;
/** 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.
CAUTION: not a copy, but the actual object! Do not modify!
*/ public static var all(get, never):Vector