flash.display

# Stage3D - AS3

Package | flash.display
Class | public class Stage3D
Inheritance | Stage3D EventDispatcher Object

Language Version: | ActionScript 3.0

Runtime Versions: | Flash Player 11, AIR 3

The Stage3D class provides a display area and a programmable rendering context for drawing 2D and 3D graphics.

Stage3D provides a high-performance rendering surface for content rendered using the `Context3D` class. This surface uses the graphics processing unit (GPU) when possible. The runtime stage provides a fixed number of `Stage3D` objects. The number of instances varies by the type of device. Desktop computers typically provide four Stage3D instances.

Content drawn to the `Stage3D` viewport is composited with other visible graphics objects in a predefined order. The most distant are all `StageVideo` surfaces. `Stage3D` comes next, with traditional Flash display object content being rendered last, on top of all others. StageVideo and Stage3D layers are rendered with no transparency; thus a viewport completely obscures any other Stage3D or StageVideo viewports positioned underneath it. Display list content is rendered with transparency.

Note: You can use the `visible` property of a Stage3D object to remove it from the display temporarily, such as when playing a video using the StageVideo class.

A `Stage3D` object is retrieved from the Player stage using its `stage3Ds` member. Use the Stage3D instance to request an associated rendering context and to position the display on the runtime stage.

Related API Elements

Stage
flash.display3D.Context3D

Public Properties
Hide Inherited Public Properties
Show Inherited Public Properties

| Property | Defined By
--- | --- | ---
|  | constructor : Object A reference to the class object or constructor function for a given object instance. | Object
|  | context3D : Context3D [read-only] The Context3D object associated with this Stage3D instance. | Stage3D
|  | visible : Boolean Specifies whether this Stage3D object is visible. | Stage3D
|  | x : Number The horizontal coordinate of the Stage3D display on the stage, in pixels. | Stage3D
|  | y : Number The vertical coordinate of the Stage3D display on the stage, in pixels. | Stage3D

Public Methods
Hide Inherited Public Methods
Show Inherited Public Methods

| Method | Defined By
--- | --- | ---
|  | Stage3D() | Stage3D
|  | addEventListener(type:String, listener:Function, useCapture:Boolean = false, priority:int = 0, useWeakReference:Boolean = false):void Registers an event listener object with an EventDispatcher object so that the listener receives notification of an event. | EventDispatcher
|  | dispatchEvent(event:Event):Boolean Dispatches an event into the event flow. | EventDispatcher
|  | hasEventListener(type:String):Boolean Checks whether the EventDispatcher object has any listeners registered for a specific type of event. | EventDispatcher
|  | hasOwnProperty(name:String):Boolean Indicates whether an object has a specified property defined. | Object
|  | isPrototypeOf(theClass:Object):Boolean Indicates whether an instance of the Object class is in the prototype chain of the object specified as the parameter. | Object
|  | propertyIsEnumerable(name:String):Boolean Indicates whether the specified property exists and is enumerable. | Object
|  | removeEventListener(type:String, listener:Function, useCapture:Boolean = false):void Removes a listener from the EventDispatcher object. | EventDispatcher
|  | requestContext3D(context3DRenderMode:String = "auto", profile:String = "baseline"):void Request the creation of a Context3D object for this Stage3D instance. | Stage3D
|  | requestContext3DMatchingProfiles(profiles:Vector.<String>):void Request the creation of a Context3D object for this Stage3D instance. | Stage3D
|  | setPropertyIsEnumerable(name:String, isEnum:Boolean = true):void Sets the availability of a dynamic property for loop operations. | Object
|  | toLocaleString():String Returns the string representation of this object, formatted according to locale-specific conventions. | Object
|  | toString():String Returns the string representation of the specified object. | Object
|  | valueOf():Object Returns the primitive value of the specified object. | Object
|  | willTrigger(type:String):Boolean Checks whether an event listener is registered with this EventDispatcher object or any of its ancestors for the specified event type. | EventDispatcher

Events
Click for more information on events
Hide Inherited Events
Show Inherited Events

| Event | Summary | Defined By
--- | --- | --- | ---
|  | activate | [broadcast event] Dispatched when the Flash Player or AIR application gains operating system focus and becomes active. | EventDispatcher
|  | context3DCreate | Dispatched when a rendering context is created. | Stage3D
|  | deactivate | [broadcast event] Dispatched when the Flash Player or AIR application operating loses system focus and is becoming inactive. | EventDispatcher
|  | error | Dispatched when a request for a rendering context fails. | Stage3D

Property Detail

### context3D

property

`context3D:Context3D` [read-only]

Language Version: | ActionScript 3.0

Runtime Versions: | Flash Player 11, AIR 3

The Context3D object associated with this Stage3D instance.

This property is initially `null`. To create the Context3D instance for this Stage3D object, add an event listener for the `context3DCreate` event and then call the `requestContext3D` method. The listener is called once the Context3D object has been created.

Implementation
`public function get context3D():Context3D`

Related API Elements

requestContext3D()

### visible

property

`visible:Boolean`

Language Version: | ActionScript 3.0

Runtime Versions: | Flash Player 11, AIR 3

Specifies whether this Stage3D object is visible.

Use this property to temporarily hide a Stage3D object on the Stage. This property defaults to `true`.

Implementation
`public function get visible():Boolean`
`public function set visible(value:Boolean):void`

### x

property

`x:Number`

Language Version: | ActionScript 3.0

Runtime Versions: | Flash Player 11, AIR 3

The horizontal coordinate of the Stage3D display on the stage, in pixels.

This property defaults to zero.

Implementation
`public function get x():Number`
`public function set x(value:Number):void`
Throws

| `ArgumentError` — if the position is not in the interval [-8191..8191].

### y

property

`y:Number`

Language Version: | ActionScript 3.0

Runtime Versions: | Flash Player 11, AIR 3

The vertical coordinate of the Stage3D display on the stage, in pixels.

This property defaults to zero.

Implementation
`public function get y():Number`
`public function set y(value:Number):void`
Throws

| `ArgumentError` — if the position is not in the interval [-8191..8191].

Constructor Detail

### Stage3D

()
Constructor

`public function Stage3D()`

Method Detail

### requestContext3D

()
method

`public function requestContext3D(context3DRenderMode:String = "auto", profile:String = "baseline"):void`

Language Version: | ActionScript 3.0

Runtime Versions: | Flash Player 11, AIR 3

Request the creation of a Context3D object for this Stage3D instance.

Before calling this function, add an event listener for the `context3DCreate` event. If you do not, the runtime throws an exception.

Important note on device loss: GPU device loss occurs when the GPU hardware becomes unavailable to the application. The Context3D object is disposed when the GPU device is lost. GPU device loss can happen for various reasons, such as, when a mobile device runs out of battery power or a Windows device goes to a "lock screen." When the GPU becomes available again, the runtime creates a new Context3D instance and dispatches another `context3DCreate` event. Your application must reload all assets and reset the rendering context state whenever device loss occurs.

Design your application logic to handle the possibility of device loss and context regeneration. Do not remove the `context3DCreate` event listener. Do not perform actions in response to the event that should not be repeated in the application. For example, do not add anonymous functions to handle timer events because they would be duplicated after device loss. To test your application's handling of device loss, you can simulate device loss by calling the `dispose()` method of the Context3D object.

The following example illustrates how to request a Context3d rendering context:

Copy

            if( stage.stage3Ds.length > 0 )
            {
                var stage3D:Stage3D = stage.stage3Ds[0];
                stage3D.addEventListener( Event.CONTEXT3D_CREATE, myContext3DHandler );
                stage3D.requestContext3D( );
            }

            function myContext3DHandler ( event : Event ) : void
            {
                var targetStage3D : Stage3D = event.target as Stage3D;
                InitAll3DResources( targetStage3D.context3D );
                StartRendering( targetStage3D.context3D );
            }

Parameters

| `context3DRenderMode:String` (default = "`auto`")`` — The type of rendering context to request. The default is `Context3DRenderMode.AUTO` for which the runtime will create a hardware-accelerated context if possible and fall back to software otherwise. Use `Context3DRenderMode.SOFTWARE` to request a software rendering context. Software rendering is not available on mobile devices. Software rendering is available only for `Context3DProfile.BASELINE` and `Context3DProfile.BASELINE_CONSTRAINED`.
| `profile:String` (default = "`baseline`")`` — (AIR 3.4 and higher) Specifies the extent to which Flash Player supports lower-level GPUs. The default is `Context3DProfile.BASELINE`, which returns a `Context3D` instance similar to that used in previous releases. To get details of all available profiles, see `flash.display3D.Context3DProfile`.

Events

| `context3DCreate:`Event`` — Dispatched when the requested rendering context is successfully completed.
| `error:`ErrorEvent`` — Dispatched when the requested rendering context cannot be created.

Throws

| `Error` — if no listeners for the `context3DCreate` event have been added to this Stage3D object.
| `ArgumentError` — if this method is called again with a different `context3DRenderMode` before the previous call has completed.

Related API Elements

flash.display3D.Context3D
flash.display3D.Context3DRenderMode
flash.display3D.Context3DProfile

### requestContext3DMatchingProfiles

()
method

`public function requestContext3DMatchingProfiles(profiles:Vector.<String>):void`

Language Version: | ActionScript 3.0

Runtime Versions: | Flash Player 12, AIR 4

Request the creation of a Context3D object for this Stage3D instance.

Before calling this function, add an event listener for the `context3DCreate` event. If you do not, the runtime throws an exception.

Important note on device loss: GPU device loss occurs when the GPU hardware becomes unavailable to the application. The Context3D object is disposed when the GPU device is lost. GPU device loss can happen for various reasons, such as, when a mobile device runs out of battery power or a Windows device goes to a "lock screen." When the GPU becomes available again, the runtime creates a new Context3D instance and dispatches another `context3DCreate` event. Your application must reload all assets and reset the rendering context state whenever device loss occurs.

Design your application logic to handle the possibility of device loss and context regeneration. Do not remove the `context3DCreate` event listener. Do not perform actions in response to the event that should not be repeated in the application. For example, do not add anonymous functions to handle timer events because they would be duplicated after device loss. To test your application's handling of device loss, you can simulate device loss by calling the `dispose()` method of the Context3D object.

The following example illustrates how to request a Context3d rendering context:

Copy

            if( stage.stage3Ds.length > 0 )
            {
              var stage3D:Stage3D = stage.stage3Ds[0];
              stage3D.addEventListener( Event.CONTEXT3D_CREATE, myContext3DHandler );
              stage3D.requestContext3DMatchingProfiles(Vector.<string>([Context3DProfile.BASELINE, Context3DProfile.BASELINE_EXTENDED]));
            }

            function myContext3DHandler ( event : Event ) : void
            {
                   var targetStage3D : Stage3D = event.target as Stage3D;
                if(targetStage3D.context3D.profile.localeCompare(Context3DProfile.BASELINE) == 0)
                {
                      InitAll3DResources( targetStage3D.context3D );
                }
                StartRendering( targetStage3D.context3D );

Parameters

| `profiles:Vector.<String>` — (AIR 3.4 and higher) a profile arrays that developer want to use in their flash program. When developer pass profile array to Stage3D.requestContext3DMatchingProfiles, he will get a Context3D based on the high level profile in that array according to their hardware capability. The rendermode is setted to AUTO, so the param is omitted.

Events

| `context3DCreate:`Event`` — Dispatched when the requested rendering context is successfully completed.
| `error:`ErrorEvent`` — Dispatched when the requested rendering context cannot be created. If the hardware is not available, it will not create a software context3d.

Throws

| `Error` — if no listeners for the `context3DCreate` event have been added to this Stage3D object.
| `ArgumentError` — if this method is called before the previous call has completed.
| `ArgumentError` — if the item in array is not flash.display3D.Context3DProfile.

Related API Elements

flash.display3D.Context3D
flash.display3D.Context3DProfile
Event Detail

### context3DCreate

Event

Event Object Type: `flash.events.Event`
property Event.type = `flash.events.Event.CONTEXT3D_CREATE`

Language Version: | ActionScript 3.0

Runtime Versions: | Flash Player 11, AIR 3

Dispatched when a rendering context is created.

The `Event.CONTEXT3D_CREATE` constant defines the value of the `type` property of a `context3Dcreate` event object. This event is raised only by Stage3D objects in response to either a call to Stage3D.requestContext3D or in response to an OS triggered reset of the Context3D bound to the Stage3D object. Inspect the Stage3D.context3D property to get the newly created Context3D object.

Related API Elements

requestContext3D()

### error

Event

Event Object Type: `flash.events.ErrorEvent`
property ErrorEvent.type = `flash.events.ErrorEvent.ERROR`

Language Version: | ActionScript 3.0

Runtime Versions: | Flash Player 11, AIR 3

Dispatched when a request for a rendering context fails.

Defines the value of the `type` property of an `error` event object.

This event has the following properties:

Property | Value
--- | ---
`bubbles` | `false`
`cancelable` | `false`; there is no default behavior to cancel.
`currentTarget` | The object that is actively processing the Event object with an event listener.
`target` | The object experiencing a network operation failure.
`text` | Text to be displayed as an error message.

Related API Elements

requestContext3D()

© 2015 Adobe Systems Incorporated. All rights reserved.
Mon Apr 10 2017, 12:28 PM -07:00