import { EventDispatcher } from "../../events/EventDispatcher"; import { Context3D } from "../../display3D/Context3D"; import { Stage } from "../display/Stage"; import { DisplayObject } from "../display/DisplayObject"; import { Rectangle } from "../../geom/Rectangle"; import { Sprite } from "../display/Sprite"; import { ByteArray } from "../../utils/ByteArray"; /** * 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).

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 three), but 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. 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. (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 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:

  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.

*/ export declare class Starling extends EventDispatcher { static VERSION: string; static readonly all: Starling[]; antiAliasing: number; /** * 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. */ readonly backBufferHeight: number; /** * 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'. */ readonly backBufferPixelsPerPoint: number; /** * 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. */ readonly backBufferWidth: number; /** * The ratio between viewPort width and stage width. Useful for choosing a different * set of textures depending on the display resolution. */ readonly contentScaleFactor: number; /** * The ratio between viewPort width and stage width. Useful for choosing a different * set of textures depending on the display resolution. */ static readonly contentScaleFactor: number; readonly context: Context3D; static readonly context: Context3D; /** * 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. */ readonly contextData: any; /** * Indicates if the Context3D object is currently valid (i.e. it hasn't been lost or * disposed). */ readonly contextValid: boolean; static readonly current: Starling; /** * Indicates if Stage3D render methods will report errors. Activate only when needed, * as this has a negative impact on performance. */ enableErrorChecking: 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. */ static handleLostContext: boolean; readonly isStarted: boolean; readonly juggler: any; static readonly juggler: any; static multitouchEnabled: boolean; /** * A Flash Sprite placed directly on top of the Starling content. Use it to display native * Flash components. */ readonly nativeOverlay: Sprite; readonly nativeStage: Stage; /** * 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. */ readonly profile: string; /** * The instance of the root class provided in the constructor. Available as soon as * the event 'ROOT_CREATED' has been dispatched. */ readonly root: DisplayObject; /** * 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. */ rootClass: any; /** * Indicates if the Context3D render calls are managed externally to Starling, * to allow other frameworks to share the Stage3D instance. */ shareContext: 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. */ showStats: boolean; simulateMultitouch: boolean; readonly stage: Stage; readonly stage3D: any; /** * 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. */ supportHighResolutions: boolean; /** * 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. */ touchProcessor: any; viewPort: Rectangle; /** * Dispatches ENTER_FRAME events on the display list, advances the Juggler * and processes touches. */ advanceTime(passedTime: number): void; deleteProgram(name: string): void; /** * Disposes all children of the stage and the render context; removes all registered * event listeners. */ dispose(): void; getProgram(name: string): any; hasProgram(name: string): boolean; makeCurrent(): void; /** * Calls advanceTime() (with the time that has passed since the last frame) * and render(). */ nextFrame(): void; /** * Registers a compiled shader-program under a certain name. * If the name was already used, the previous program is overwritten. */ registerProgram(name: string, vertexShader: ByteArray, fragmentShader: ByteArray): any; /** * Compiles a shader-program and registers it under a certain name. * If the name was already used, the previous program is overwritten. */ registerProgramFromSource(name: string, vertexShader: string, fragmentShader: string): any; /** * 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. */ render(): void; showStatsAt(hAlign?: string, vAlign?: string, scale?: number): void; /** * 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. 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.) * @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. * If you pass a profile String, this profile is enforced.Pass an Array of profiles to make Starling pick the first * one that works (starting with the first array element).Pass the String "auto" to make Starling pick the best available * profile automatically. */ constructor(rootClass: any, stage: Stage, viewPort?: Rectangle, stage3D?: any, renderMode?: string, profile?: any); /** * 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.) */ 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. */ stop(suspendRendering?: boolean): 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. */ stopWithFatalError(message: string): void; }