| Package | flash.display |
| Class | public class Stage3D |
| Inheritance | Stage3D  EventDispatcher Object |
| Language Version: | ActionScript 3.0 |
| Runtime Versions: | Flash Player 11, AIR 3 |
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
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 | ||
| 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 | |
|
Dispatches an event into the event flow. | EventDispatcher | |
|
Checks whether the EventDispatcher object has any listeners registered for a specific type
of event. | EventDispatcher | |
|
Indicates whether an object has a specified property defined. | Object | |
|
Indicates whether an instance of the Object class is in the prototype chain of the object specified
as the parameter. | Object | |
|
Indicates whether the specified property exists and is enumerable. | Object | |
|
Removes a listener from the EventDispatcher object. | EventDispatcher | |
Request the creation of a Context3D object for this Stage3D instance. | Stage3D | ||
Request the creation of a Context3D object for this Stage3D instance. | Stage3D | ||
|
Sets the availability of a dynamic property for loop operations. | Object | |
|
Returns the string representation of this object, formatted according to locale-specific conventions. | Object | |
|
Returns the string representation of the specified object. | Object | |
|
Returns the primitive value of the specified object. | Object | |
|
Checks whether an event listener is registered with this EventDispatcher object or any of
its ancestors for the specified event type. | EventDispatcher | |
| Event | Summary | Defined By | ||
|---|---|---|---|---|
| [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 | |||
| [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 | |||
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():Context3DRelated 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):voidx | 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):voidThrows
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):voidThrows
ArgumentError — if the position is not in the interval [-8191..8191].
|
Stage3D | () | Constructor |
public function Stage3D()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")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")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: — Dispatched when the requested rendering context is successfully
completed.
| |
error: — 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: — Dispatched when the requested rendering context is successfully
completed.
| |
error: — 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
context3DCreate | Event |
flash.events.Eventproperty 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.
TheEvent.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 |
flash.events.ErrorEventproperty 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 thetype 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
Mon Apr 10 2017, 12:28 PM -07:00