Packageflash.display
Classpublic class Stage3D
InheritanceStage3D Inheritance EventDispatcher Inheritance Object

Language version: ActionScript 3.0
Runtime version: 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.

See also

Stage
flash.display3D.Context3D


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
 Inheritedprototype : Object
[static] A reference to the prototype object of a class or function object.
Object
  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
 EventSummaryDefined 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
context3Dproperty
context3D:Context3D  [read-only]

Language version: ActionScript 3.0
Runtime version: 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

See also

visibleproperty 
visible:Boolean  [read-write]

Language version: ActionScript 3.0
Runtime version: 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
xproperty 
x:Number  [read-write]

Language version: ActionScript 3.0
Runtime version: 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].
yproperty 
y:Number  [read-write]

Language version: ActionScript 3.0
Runtime version: 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 version: 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. 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.

See also

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

Language version: ActionScript 3.0
Runtime version: 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.

See also

Event detail
context3DCreateevent 
Event object type: flash.events.Event

Language version: ActionScript 3.0
Runtime version: AIR 3

Dispatched when a rendering context is created.

See also

errorevent  
Event object type: flash.events.ErrorEvent
ErrorEvent.type property = flash.events.ErrorEvent.ERROR

Language version: ActionScript 3.0
Runtime version: 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.

See also