ActionScript® 3.0 Reference for the Adobe® Flash® Platform
Home  |  Show Packages and Classes List |  Packages  |  Classes  |  What's New  |  Index  |  Appendixes
flash.display 

Stage3D  - AS3

Packageflash.display
Classpublic class Stage3D
InheritanceStage3D Inheritance EventDispatcher Inheritance 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



Public Properties
 PropertyDefined By
 Inheritedconstructor : 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
 MethodDefined By
  
Stage3D
 Inherited
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
 Inherited
Dispatches an event into the event flow.
EventDispatcher
 Inherited
Checks whether the EventDispatcher object has any listeners registered for a specific type of event.
EventDispatcher
 Inherited
Indicates whether an object has a specified property defined.
Object
 Inherited
Indicates whether an instance of the Object class is in the prototype chain of the object specified as the parameter.
Object
 Inherited
Indicates whether the specified property exists and is enumerable.
Object
 Inherited
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
  
Request the creation of a Context3D object for this Stage3D instance.
Stage3D
 Inherited
Sets the availability of a dynamic property for loop operations.
Object
 Inherited
Returns the string representation of this object, formatted according to locale-specific conventions.
Object
 Inherited
Returns the string representation of the specified object.
Object
 Inherited
Returns the primitive value of the specified object.
Object
 Inherited
Checks whether an event listener is registered with this EventDispatcher object or any of its ancestors for the specified event type.
EventDispatcher
Events
 Event Summary Defined By
 Inherited[broadcast event] Dispatched when the Flash Player or AIR application gains operating system focus and becomes active.EventDispatcher
  Dispatched when a rendering context is created.Stage3D
 Inherited[broadcast event] Dispatched when the Flash Player or AIR application operating loses system focus and is becoming inactive.EventDispatcher
  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

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:

        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.
 
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 that used in previous releases. You can also specify Context3DProfile.BASELINE_CONSTRAINED, which runs a limited set of Stage3D capabilities on lower-end GPUs or Context3DProfile.BASELINE_EXTENDED, which allows a slightly extended set of Stage3D capabilities suitable for more modern mobile hardware

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

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:

        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

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

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:

PropertyValue
bubblesfalse
cancelablefalse; there is no default behavior to cancel.
currentTargetThe object that is actively processing the Event object with an event listener.
targetThe object experiencing a network operation failure.
textText to be displayed as an error message.

Related API Elements