flash.display.Stage3D - Adobe® AIR® API Reference for HTML Developers

window.runtime property	window.runtime.flash.display.Stage3D

Inheritance	Stage3D EventDispatcher Object

Runtime Versions:

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

Properties

Hide Inherited Public Properties

Show Inherited 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
		prototype : 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

Hide Inherited Public Methods

Show Inherited 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"):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

Hide Inherited Events

Show Inherited Events

	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]

Runtime Versions:

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.

See also

requestContext3D()

visible

property

visible:Boolean

Runtime Versions:

Specifies whether this Stage3D object is visible.

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

x

property

x:Number

Runtime Versions:

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

This property defaults to zero.

Throws

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

y

property

y:Number

Runtime Versions:

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

This property defaults to zero.

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"):void

Runtime Versions:

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:

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.

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

Context3D
Context3DRenderMode

Event Detail

context3DCreate

Event

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

Runtime Versions:

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 dispatched by Stage3D objects in response to either a call to Stage3D.requestContext3D() or in response to an OS-triggered reset of the rendering context of the Stage3D object. Use the context3D property of the Stage3D object to access the newly created Context3D instance.

See also

requestContext3D()

error

Event

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

Runtime Versions:

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.

See also

requestContext3D()

[an error occurred while processing this directive][an error occurred while processing this directive]

Legal Notices | Online Privacy Policy