The Context3D class provides a context for rendering geometrically defined graphics. A rendering context includes a drawing surface and its associated resources and state. When possible, the rendering context uses the hardware graphics processing unit (GPU). Otherwise, the rendering context uses software. (If rendering through Context3D is not supported on a platform, the stage3Ds property of the Stage object contains an empty list.)

The Context3D rendering context is a programmable pipeline that is very similar to OpenGL ES 2, but is abstracted so that it is compatible with a range of hardware and GPU interfaces. Although designed for 3D graphics, the rendering pipeline does not mandate that the rendering is three dimensional. Thus, you can create a 2D renderer by supplying the appropriate vertex and pixel fragment programs. In both the 3D and 2D cases, the only geometric primitive supported is the triangle.

Get an instance of the Context3D class by calling the requestContext3D() method of a Stage3D object. A limited number of Context3D objects can exist per stage; one for each Stage3D in the Stage.stage3Ds list. When the context is created, the Stage3D object dispatches a context3DCreate event. A rendering context can be destroyed and recreated at any time, such as when another application that uses the GPU gains focus. Your code should anticipate receiving multiple context3DCreate events. Position the rendering area on the stage using the x and y properties of the associated Stage3D instance.

To render and display a scene (after getting a Context3D object), the following steps are typical:

  1. Configure the main display buffer attributes by calling configureBackBuffer().
  2. Create and initialize your rendering resources, including:
  3. Vertex and index buffers defining the scene geometry
  4. Vertex and pixel programs (shaders) for rendering the scene
  5. Textures
  6. Render a frame:
  7. Set the render state as appropriate for an object or collection of objects in the scene.
  8. Call the drawTriangles() method to render a set of triangles.
  9. Change the rendering state for the next group of objects.
  10. Call drawTriangles() to draw the triangles defining the objects.
  11. Repeat until the scene is entirely rendered.
  12. Call the present() method to display the rendered scene on the stage.

The following limits apply to rendering:

Resource limits:

ResourceNumber allowedTotal memory
Vertex buffers4096256 MB
Index buffers4096128 MB
Programs409616 MB
Textures4096128 MB
Cube textures4096256 MB

AGAL limits: 200 opcodes per program.

Draw call limits: 32,768 drawTriangles() calls for each present() call.

The following limits apply to textures:

Texture limits for AIR 32 bit:

TextureMaximum sizeTotal GPU memory
Normal Texture (below Baseline extended)2048x2048512 MB
Normal Texture (Baseline extended and above)4096x4096512 MB
Rectangular Texture (below Baseline extended)2048x2048512 MB
Rectangular Texture (Baseline extended and above)4096x4096512 MB
Cube Texture1024x1024256 MB

Texture limits for AIR 64 bit (Desktop):

TextureMaximum sizeTotal GPU memory
Normal Texture (below Baseline extended)2048x2048512 MB
Normal Texture (Baseline extended to Standard)4096x4096512 MB
Normal Texture (Standard extended and above)4096x40962048 MB
Rectangular Texture (below Baseline extended)2048x2048512 MB
Rectangular Texture (Baseline extended to Standard)4096x4096512 MB
Rectangular Texture (Standard extended and above)4096x40962048 MB
Cube Texture1024x1024256 MB

512 MB is the absolute limit for textures, including the texture memory required for mipmaps. However, for Cube Textures, the memory limit is 256 MB.

You cannot create Context3D objects with the Context3D constructor. It is constructed and available as a property of a Stage3D instance. The Context3D class can be used on both desktop and mobile platforms, both when running in Flash Player and AIR.

Variables

read onlybackBufferHeight:Int = 0

Specifies the height of the back buffer, which can be changed by a successful call to the configureBackBuffer() method. The height may be modified when the browser zoom factor changes if the wantsBestResolutionOnBrowserZoom parameter is set to true in the last successful call to the configureBackBuffer() method. The change in height can be detected by registering an event listener for the browser zoom change event.

read onlybackBufferWidth:Int = 0

Specifies the width of the back buffer, which can be changed by a successful call to the configureBackBuffer() method. The width may be modified when the browser zoom factor changes if the wantsBestResolutionOnBrowserZoom parameter is set to true in the last successful call to the configureBackBuffer() method. The change in width can be detected by registering an event listener for the browser zoom change event.

read onlydriverInfo:String = "OpenGL (Direct blitting)"

The type of graphics library driver used by this rendering context. Indicates whether the rendering is using software, a DirectX driver, or an OpenGL driver. Also indicates whether hardware rendering failed. If hardware rendering fails, Flash Player uses software rendering for Stage3D and driverInfo contains one of the following values:

  • "Software Hw_disabled=userDisabled" - The Enable hardware acceleration checkbox in the Adobe Flash Player Settings UI is not selected.
  • "Software Hw_disabled=oldDriver" - There are known problems with the hardware graphics driver. Updating the graphics driver may fix this problem.
  • "Software Hw_disabled=unavailable" - Known problems with the hardware graphics driver or hardware graphics initialization failure.
  • "Software Hw_disabled=explicit" - The content explicitly requested software rendering through requestContext3D.
  • "Software Hw_disabled=domainMemory" - The content uses domainMemory, which requires a license when used with Stage3D hardware rendering. Visit adobe.com/go/fpl.

enableErrorChecking:Bool

Specifies whether errors encountered by the renderer are reported to the application.

When enableErrorChecking is true, the clear(), and drawTriangles() methods are synchronous and can throw errors. When enableErrorChecking is false, the default, the clear(), and drawTriangles() methods are asynchronous and errors are not reported. Enabling error checking reduces rendering performance. You should only enable error checking when debugging.

read onlymaxBackBufferHeight:Int

Specifies the maximum height of the back buffer. The inital value is the system limit in the platform. The property can be set to a value smaller than or equal to, but not greater than, the system limit. The property can be set to a value greater than or equal to, but not smaller than, the minimum limit. The minimum limit is a constant value, 32, when the back buffer is not configured. The minimum limit will be the value of the height parameter in the last successful call to the configureBackBuffer() method after the back buffer is configured.

read onlymaxBackBufferWidth:Int

Specifies the maximum width of the back buffer. The inital value is the system limit in the platform. The property can be set to a value smaller than or equal to, but not greater than, the system limit. The property can be set to a value greater than or equal to, but not smaller than, the minimum limit. The minimum limit is a constant value, 32, when the back buffer is not configured. The minimum limit will be the value of the width parameter in the last successful call to the configureBackBuffer() method after the back buffer is configured.

read onlyprofile:Context3DProfile = STANDARD

The feature-support profile in use by this Context3D object.

read onlytotalGPUMemory:Int = 0

Returns the total GPU memory allocated by Stage3D data structures of an application.

Whenever a GPU resource object is created, memory utilized is stored in Context3D. This memory includes index buffers, vertex buffers, textures (excluding video texture), and programs that were created through this Context3D.

API totalGPUMemory returns the total memory consumed by the above resources to the user. Default value returned is 0.The total GPU memory returned is in bytes. The information is only provided in Direct mode on mobile, and in Direct and GPU modes on desktop. (On desktop, using <renderMode>gpu</renderMode> will fall back to <renderMode>direct</renderMode>)

This API can be used when the SWF version is 32 or later.

Methods

clear (red:Float = 0, green:Float = 0, blue:Float = 0, alpha:Float = 1, depth:Float = 1, stencil:UInt = 0, mask:UInt = Context3DClearMask.ALL):Void

Clears the color, depth, and stencil buffers associated with this Context3D object and fills them with the specified values.

Set the mask parameter to specify which buffers to clear. Use the constants defined in the Context3DClearMask class to set the mask parameter. Use the bitwise OR operator, "|", to add multiple buffers to the mask (or use Context3DClearMask.ALL). When rendering to the back buffer, the configureBackBuffer() method must be called before any clear() calls.

Note: If you specify a parameter value outside the allowed range, Numeric parameter values are silently clamped to the range zero to one. Likewise, if stencil is greater than 0xff it is set to 0xff.

Parameters:

red

the red component of the color with which to clear the color buffer, in the range zero to one.

green

the green component of the color with which to clear the color buffer, in the range zero to one.

blue

the blue component of the color with which to clear the color buffer, in the range zero to one.

alpha

the alpha component of the color with which to clear the color buffer, in the range zero to one. The alpha component is not used for blending. It is written to the buffer alpha directly.

depth

the value with which to clear the depth buffer, in the range zero to one.

stencil

the 8-bit value with which to clear the stencil buffer, in a range of 0x00 to 0xff.

mask

specifies which buffers to clear.

Throws:

Error

Object Disposed: If this Context3D object has been disposed by a calling dispose() or because the underlying rendering hardware has been lost.

Error

3768: The Stage3D API may not be used during background execution.

configureBackBuffer (width:Int, height:Int, antiAlias:Int, enableDepthAndStencil:Bool = true, wantsBestResolution:Bool = false, wantsBestResolutionOnBrowserZoom:Bool = false):Void

Sets the viewport dimensions and other attributes of the rendering buffer.

Rendering is double-buffered. The back buffer is swapped with the visible, front buffer when the present() method is called. The minimum size of the buffer is 32x32 pixels. The maximum size of the back buffer is limited by the device capabilities and can also be set by the user through the properties maxBackBufferWidth and maxBackBufferHeight. Configuring the buffer is a slow operation. Avoid changing the buffer size or attributes during normal rendering operations.

Parameters:

width

width in pixels of the buffer.

height

height in pixels of the buffer.

antiAlias

an integer value specifying the requested antialiasing quality. The value correlates to the number of subsamples used when antialiasing. Using more subsamples requires more calculations to be performed, although the relative performance impact depends on the specific rendering hardware. The type of antialiasing and whether antialiasing is performed at all is dependent on the device and rendering mode. Antialiasing is not supported at all by the software rendering context. | --- | --- | | 0 | No antialiasing | | 2 | Minimal antialiasing | | 4 | High-quality antialiasing | | 16 | Very high-quality antialiasing |

enableDepthAndStencil

false indicates no depth or stencil buffer is created, true creates a depth and a stencil buffer. For an AIR 3.2 or later application compiled with SWF version 15 or higher, if the renderMode element in the application descriptor file is direct, then the depthAndStencil element in the application descriptor file must have the same value as this argument. By default, the value of the depthAndStencil element is false.

wantsBestResolution

true indicates that if the device supports HiDPI screens it will attempt to allocate a larger back buffer than indicated with the width and height parameters. Since this add more pixels and potentially changes the result of shader operations this is turned off by default. Use Stage.contentsScaleFactor to determine by how much the native back buffer was scaled up.

wantsBestResolutionOnBrowserZoom

true indicates that the size of the back buffer should increase in proportion to the increase in the browser zoom factor. The setting of this value is persistent across multiple browser zooms. The default value of the parameter is false. Set maxBackBufferWidth and maxBackBufferHeight properties to limit the back buffer size increase. Use backBufferWidth and backBufferHeight to determine the current size of the back buffer.

Throws:

Error

Object Disposed: if this Context3D object has been disposed by a calling dispose() or because the underlying rendering hardware has been lost.

Error

Bad Input Size: The width or height parameter is either less than the minimum back buffer allowed size or greater than the maximum back buffer size allowed.

Error

3709: The depthAndStencil flag in the application descriptor must match the enableDepthAndStencil Boolean passed to configureBackBuffer() on the Context3D object.

createCubeTexture (size:Int, format:Context3DTextureFormat, optimizeForRenderToTexture:Bool, streamingLevels:Int = 0):CubeTexture

Creates a CubeTexture object.

Use a CubeTexture object to upload cube texture bitmaps to the rendering context and to reference a cube texture during rendering. A cube texture consists of six equal-sized, square textures arranged in a cubic topology and are useful for describing environment maps.

You cannot create CubeTexture objects with a CubeTexture constructor; use this method instead. After creating a CubeTexture object, upload the texture bitmap data using the CubeTexture uploadFromBitmapData(), uploadFromByteArray(), or uploadCompressedTextureFromByteArray() methods.

Parameters:

size

The texture edge length in texels.

format

The texel format, of the Context3DTextureFormat enumerated list. Texture compression lets you store texture images in compressed format directly on the GPU, which saves GPU memory and memory bandwidth. Typically, compressed textures are compressed offline and uploaded to the GPU in compressed form using the Texture.uploadCompressedTextureFromByteArray method. Flash Player 11.4 and AIR 3.4 on desktop platforms added support for runtime texture compression, which may be useful in certain situations, such as when rendering dynamic textures from vector art. Note that this feature is not currently available on mobile platforms and an ArgumentError (Texture Format Mismatch) will be thrown instead. To use runtime texture compression, perform the following steps: 1. Create the texture object by calling the Context3D.createCubeTexture() method, passing either openfl.display3D.Context3DTextureFormat.COMPRESSED or openfl.display3D.Context3DTextureFormat.COMPRESSED_ALPHA as the format parameter. 2. Using the openfl.display3D.textures.Texture instance returned by createCubeTexture(), call either openfl.display3D.textures.CubeTexture.uploadFromBitmapData() or openfl.display3D.textures.CubeTexture.uploadFromByteArray() to upload and compress the texture in one step.

optimizeForRenderToTexture

Set to true if the texture is likely to be used as a render target.

streamingLevels

The MIP map level that must be loaded before the image is rendered. Texture streaming offers the ability to load and display the smallest mip levels first, progressively displaying higher quality images as the textures are loaded. End users can view lower-quality images in an application while the higher quality images load. By default, streamingLevels is 0, meaning that the highest quality image in the MIP map must be loaded before the image is rendered. This parameter was added in Flash Player 11.3 and AIR 3.3. Using the default value maintains the behavior of the previous versions of Flash Player and AIR. Set streamingLevels to a value between 1 and the number of images in the MIP map to enable texture streaming. For example, you have a MIP map that includes at the highest quality a main image at 64x64 pixels. Lower quality images in the MIP map are 32x32, 16x16, 8x8, 4x4, 2x2, and 1x1 pixels, for 7 images in total, or 7 levels. Level 0 is the highest quality image. The maximum value of this property is log2(min(width,height)). Therefore, for a main image that is 64x64 pixels, the maximum value of streamingLevels is 7. Set this property to 3 to render the image after the 8x8 pixel image loads. Note: Setting this property to a value > 0 can impact memory usage and performance.

Throws:

Error

Object Disposed: if this Context3D object has been disposed by a calling dispose() or because the underlying rendering hardware has been lost.

Error

Resource Limit Exceeded: if too many Texture objects are created or the amount of memory allocated to textures is exceeded.

ArgumentError

Depth Texture Not Implemented: if you attempt to create a depth texture.

ArgumentError

Texture Size Is Zero: if the size parameter is not greater than zero.

ArgumentError

Texture Not Power Of Two: if the size parameter is not a power of two.

ArgumentError

Texture Too Big: if the size parameter is greater than 1024.

Error

Texture Creation Failed: if the CubeTexture object could not be created by the rendering context (but information about the reason is not available).

ArgumentError

Invalid streaming level: if streamingLevels is greater or equal to log2(size).

Returns:

A new CubeTexture object

createIndexBuffer (numIndices:Int, bufferUsage:Context3DBufferUsage = STATIC_DRAW):IndexBuffer3D

Creates an IndexBuffer3D object.

Use an IndexBuffer3D object to upload a set of triangle indices to the rendering context and to reference that set of indices for rendering. Each index in the index buffer references a corresponding vertex in a vertex buffer. Each set of three indices identifies a triangle. Pass the IndexBuffer3D object to the drawTriangles() method to render one or more triangles defined in the index buffer.

You cannot create IndexBuffer3D objects with the IndexBuffer3D class constructor; use this method instead. After creating a IndexBuffer3D object, upload the indices using the IndexBuffer3D uploadFromVector() or uploadFromByteArray() methods.

Parameters:

numIndices

the number of vertices to be stored in the buffer.

bufferUsage

the expected buffer usage. Use one of the constants defined in Context3DBufferUsage. The hardware driver can do appropriate optimization when you set it correctly. This parameter is only available after Flash 12/AIR 4.

Throws:

Error

Object Disposed: if this Context3D object has been disposed by a calling dispose() or because the underlying rendering hardware has been lost.

Error

Resource Limit Exceeded: if too many index buffers are created or the amount of memory allocated to index buffers is exceeded.

Error

3768: The Stage3D API may not be used during background execution.

ArgumentError

Buffer Too Big: when numIndices is greater than or equal to 0xf0000.

Returns:

A new IndexBuffer3D object

createProgram (format:Context3DProgramFormat = AGAL):Program3D

Creates a Program3D object.

Use a Program3D object to upload shader programs to the rendering context and to reference uploaded programs during rendering. A Program3D object stores two programs, a vertex program and a fragment program (also known as a pixel program). The programs are written in a binary shader assembly language.

You cannot create Program3D objects with a Program3D constructor; use this method instead. After creating a Program3D object, upload the programs using the Program3D upload() method.

Parameters:

format

(Experimental) Set the format of this Program3D instance to AGAL (default) or to GLSL for use on GL-based renderers

Throws:

Error

Object Disposed: if this Context3D object has been disposed by a calling dispose() or because the underlying rendering hardware has been lost.

Error

The number of programs exceeds 4096 or the total memory size exceeds 16MB (use dispose to free Program3D resources).

Returns:

A new Program3D object

createRectangleTexture (width:Int, height:Int, format:Context3DTextureFormat, optimizeForRenderToTexture:Bool):RectangleTexture

Creates a Rectangle Texture object.

Use a RectangleTexture object to upload texture bitmaps to the rendering context and to reference a texture during rendering.

You cannot create RectangleTexture objects with a RectangleTexture constructor; use this method instead. After creating a RectangleTexture object, upload the texture bitmaps using the Texture uploadFromBitmapData() or uploadFromByteArray() methods.

Note that 32-bit integer textures are stored in a packed BGRA format to match the OpenFL BitmapData format. Floating point textures use a conventional RGBA format.

Rectangle textures are different from regular 2D textures in that their width and height do not have to be powers of two. Also, they do not contain mip maps. They are most useful for use in render to texture cases. If a rectangle texture is used with a sampler that uses mip map filtering or repeat wrapping the drawTriangles call will fail. Rectangle texture also do not allow streaming. The only texture formats supported by Rectangle textures are BGRA, BGR_PACKED, BGRA_PACKED. The compressed texture formats are not supported by Rectangle Textures.

Parameters:

width

The texture width in texels.

height

The texture height in texels.

format

The texel format, of the Context3DTextureFormat enumerated list.

optimizeForRenderToTexture

Set to true if the texture is likely to be used as a render target.

Throws:

Error

Object Disposed: if this Context3D object has been disposed by a calling dispose() or because the underlying rendering hardware has been lost.

Error

Resource Limit Exceeded: if too many Texture objects are created or the amount of memory allocated to textures is exceeded.

ArgumentError

Texture Size Is Zero: if both the width or height parameters are not greater than zero.

ArgumentError

Texture Too Big: if either the width or the height parameter is greater than 2048.

Error

Texture Creation Failed: if the Texture object could not be created by the rendering context (but information about the reason is not available).

Error

Requires Baseline Profile Or Above: if rectangular texture is created with baseline constrained profile.

Returns:

A new RectangleTexture object

createTexture (width:Int, height:Int, format:Context3DTextureFormat, optimizeForRenderToTexture:Bool, streamingLevels:Int = 0):Texture

Creates a Texture object.

Use a Texture object to upload texture bitmaps to the rendering context and to reference a texture during rendering.

You cannot create Texture objects with a Texture constructor; use this method instead. After creating a Texture object, upload the texture bitmaps using the Texture uploadFromBitmapData(), uploadFromByteArray(), or uploadCompressedTextureFromByteArray() methods.

Note that 32-bit integer textures are stored in a packed BGRA format to match the OpenFL BitmapData format. Floating point textures use a conventional RGBA format.

Parameters:

width

The texture width in texels.

height

The texture height in texels.

format

The texel format, of the Context3DTextureFormat enumerated list. Texture compression lets you store texture images in compressed format directly on the GPU, which saves GPU memory and memory bandwidth. Typically, compressed textures are compressed offline and uploaded to the GPU in compressed form using the Texture.uploadCompressedTextureFromByteArray method. Flash Player 11.4 and AIR 3.4 on desktop platforms added support for runtime texture compression, which may be useful in certain situations, such as when rendering dynamic textures from vector art. Note that this feature is not currently available on mobile platforms and an ArgumentError (Texture Format Mismatch) will be thrown instead. To use runtime texture compression, perform the following steps: 1. Create the texture object by calling the Context3D.createTexture() method, passing either openfl.display3D.Context3DTextureFormat.COMPRESSED or openfl.display3D.Context3DTextureFormat.COMPRESSED_ALPHA as the format parameter. 2. Using the openfl.display3D.textures.Texture instance returned by createTexture(), call either openfl.display3D.textures.Texture.uploadFromBitmapData() or openfl.display3D.textures.Texture.uploadFromByteArray() to upload and compress the texture in one step.

optimizeForRenderToTexture

Set to true if the texture is likely to be used as a render target.

streamingLevels

The MIP map level that must be loaded before the image is rendered. Texture streaming offers the ability to load and display the smallest mip levels first, progressively displaying higher quality images as the textures are loaded. End users can view lower-quality images in an application while the higher quality images load. By default, streamingLevels is 0, meaning that the highest quality image in the MIP map must be loaded before the image is rendered. This parameter was added in Flash Player 11.3 and AIR 3.3. Using the default value maintains the behavior of the previous versions of Flash Player and AIR. Set streamingLevels to a value between 1 and the number of images in the MIP map to enable texture streaming. For example, you have a MIP map that includes at the highest quality a main image at 64x64 pixels. Lower quality images in the MIP map are 32x32, 16x16, 8x8, 4x4, 2x2, and 1x1 pixels, for 7 images in total, or 7 levels. Level 0 is the highest quality image. The maximum value of this property is log2(min(width,height)). Therefore, for a main image that is 64x64 pixels, the maximum value of streamingLevels is 7. Set this property to 3 to render the image after the 8x8 pixel image loads. Note: Setting this property to a value > 0 can impact memory usage and performance.

Throws:

Error

Object Disposed: if this Context3D object has been disposed by a calling dispose() or because the underlying rendering hardware has been lost.

Error

Resource Limit Exceeded: if too many Texture objects are created or the amount of memory allocated to textures is exceeded.

ArgumentError

Depth Texture Not Implemented: if you attempt to create a depth texture.

ArgumentError

Texture Size Is Zero: if both the width or height parameters are not greater than zero.

ArgumentError

Texture Not Power Of Two: if both the width and height parameters are not a power of two.

ArgumentError

Texture Too Big: if either the width or the height parameter is greater than 2048 for baseline and baseline constrained profile or if either the width or the height parameter is greater than 4096 for profile baseline extended and above.

Error

Texture Creation Failed: if the Texture object could not be created by the rendering context (but information about the reason is not available).

ArgumentError

Invalid streaming level: if streamingLevels is greater or equal to log2(min(width,height)).

Returns:

A new Texture object

createVertexBuffer (numVertices:Int, data32PerVertex:Int, bufferUsage:Context3DBufferUsage = STATIC_DRAW):VertexBuffer3D

Creates a VertexBuffer3D object.

Use a VertexBuffer3D object to upload a set of vertex data to the rendering context. A vertex buffer contains the data needed to render each point in the scene geometry. The data attributes associated with each vertex typically includes position, color, and texture coordinates and serve as the input to the vertex shader program. Identify the data values that correspond to one of the inputs of the vertex program using the setVertexBufferAt() method. You can specify up to sixty-four 32-bit values for each vertex.

You cannot create VertexBuffer3D objects with a VertexBuffer3D constructor; use this method instead. After creating a VertexBuffer3D object, upload the vertex data using the VertexBuffer3D uploadFromVector() or uploadFromByteArray() methods.

Parameters:

numVertices

the number of vertices to be stored in the buffer. The maximum number of vertices in a single buffer is 65535.

data32PerVertex

the number of 32-bit(4-byte) data values associated with each vertex. The maximum number of 32-bit data elements per vertex is 64 (or 256 bytes). Note that only eight attribute registers are accessible by a vertex shader program at any given time. Use setVertextBufferAt() to select attributes from within a vertex buffer.

bufferUsage

the expected buffer usage. Use one of the constants defined in Context3DBufferUsage. The hardware driver can do appropriate optimization when you set it correctly. This parameter is only available after Flash 12/AIR 4

Throws:

Error

Object Disposed: if this Context3D object has been disposed by a calling dispose() or because the underlying rendering hardware has been lost.

Error

Resource Limit Exceeded: if too many vertex buffer objects are created or the amount of memory alloted to vertex buffers is exceeded.

ArgumentError

Buffer Too Big: when numVertices is greater than 0x10000 or data32PerVertex is greater than 64.

ArgumentError

Buffer Has Zero Size: when numVertices is zero or data32PerVertex is zero.

ArgumentError

Buffer Creation Failed: if the VertexBuffer3D object could not be created by the rendering context (but additional information about the reason is not available).

Error

3768: The Stage3D API may not be used during background execution.

Returns:

A new VertexBuffer3D object

createVideoTexture ():VideoTexture

Creates a VideoTexture object.

Use a VideoTexture object to obtain video frames as texture from NetStream object or Camera object and to upload the video frames to the rendering context.

The VideoTexture object cannot be created with the VideoTexture constructor; use this method instead. After creating a VideoTexture object, attach NetStream object or Camera Object to get the video frames with the VideoTexture attachNetStream() or attachCamera() methods.

Note that this method returns null if the system doesn't support this feature.

VideoTexture does not contain mipmaps. If VideoTexture is used with a sampler that uses mip map filtering or repeat wrapping, the drawTriangles call will fail. VideoTexture can be treated as BGRA texture by the shaders. The attempt to instantiate the VideoTexture Object will fail if the Context3D was requested with sotfware rendering mode.

A maximum of 4 VideoTexture objects are available per Context3D instance. On mobile the actual number of supported VideoTexture objects may be less than 4 due to platform limitations.

Throws:

Error

Object Disposed: if this Context3D object has been disposed by a calling dispose() or because the underlying rendering hardware has been lost.

Error

Resource Limit Exceeded: if too many Texture objects are created or the amount of memory allocated to textures is exceeded.

Error

Texture Creation Failed: if the Texture object could not be created by the rendering context (but information about the reason is not available).

Returns:

A new VideoTexture object

dispose (recreate:Bool = true):Void

Frees all resources and internal storage associated with this Context3D.

All index buffers, vertex buffers, textures, and programs that were created through this Context3D are disposed just as if calling dispose() on each of them individually. In addition, the Context3D itself is disposed freeing all temporary buffers and the back buffer. If you call configureBackBuffer(), clear(), drawTriangles(), createCubeTexture(), createTexture(), createProgram(), createIndexBuffer(), createVertexBuffer(), or drawToBitmapData() after calling dispose(), the runtime throws an exception.

Warning: calling dispose() on a Context3D while there is still a event listener for Events.CONTEXT3D_CREATE set on the asociated Stage3D object the dispose() call will simulate a device loss. It will create a new Context3D on the Stage3D and issue the Events.CONTEXT3D_CREATE event again. If this is not desired remove the event listener from the Stage3D object before calling dispose() or set the recreate parameter to false.

Parameters:

recreate

Whether to allow this Stage3D object to create itself again

drawToBitmapData (destination:BitmapData, ?srcRect:Rectangle, ?destPoint:Point):Void

Draws the current render buffer to a bitmap.

The current contents of the back render buffer are copied to a BitmapData object. This is potentially a very slow operation that can take up to a second. Use with care. Note that this function does not copy the front render buffer (the one shown on stage), but the buffer being drawn to. To capture the rendered image as it appears on the stage, call drawToBitmapData() immediately before you calling present().

Beginning with AIR 25, two new parameters have been introduced in the API drawToBitmapData(). This API now takes three parameters. The first one is the existing parameter destination:BitmapData. The second parameter is srcRect:Rectangle, which is target rectangle on Stage3D. The third parameter is destPoint:Point, which is the coordinate on the destination bitmap. The parameters srcRect and destPoint are optional and default to (0,0,bitmapWidth,bitmapHeight) and (0,0), respectively.

When the image is drawn, it is not scaled to fit the bitmap. Instead, the contents are clipped to the size of the destination bitmap.

OpenFL BitmapData objects store colors already multiplied by the alpha component. For example, if the "pure" rgb color components of a pixel are (0x0A, 0x12, 0xBB) and the alpha component is 0x7F (.5), then the pixel is stored in the BitmapData object with the rgba values: (0x05, 0x09, 0x5D, 0x7F). You can set the blend factors so that the colors rendered to the buffer are multiplied by alpha or perform the operation in the fragment shader. The rendering context does not validate that the colors are stored in premultiplied format.

Parameters:

destination

The target BitmapData for this drawing operation

srcRect

The source rectangle in the current Stage3D context

destPoint

A destination point to write to in the target BitmapData

Throws:

Error

Object Disposed: if this Context3D object has been disposed by a calling dispose() or because the underlying rendering hardware has been lost.

Error

3768: The Stage3D API may not be used during background execution.

Error

3802: If either one of the parameters destPoint:Point or srcRect:Rectangle is outside the bitmap/stage3D coordinate bound, or if non-numeric(NaN) values are passed as input.

drawTriangles (indexBuffer:IndexBuffer3D, firstIndex:Int = 0, numTriangles:Int = -1):Void

Render the specified triangles using the current buffers and state of this Context3D object.

For each triangle, the triangle vertices are processed by the vertex shader program and the triangle surface is processed by the pixel shader program. The output color from the pixel program for each pixel is drawn to the render target depending on the stencil operations, depth test, source and destination alpha, and the current blend mode. The render destination can be the main render buffer or a texture.

If culling is enabled, (with the setCulling() method), then triangles can be discarded from the scene before the pixel program is run. If stencil and depth testing are enabled, then output pixels from the pixel program can be discarded without updating the render destination. In addition, the pixel program can decide not to output a color for a pixel.

The rendered triangles are not displayed in the viewport until you call the present() method. After each present() call, the clear() method must be called before the first drawTriangles() call or rendering fails.

When enableErrorChecking is false, this function returns immediately, does not wait for results, and throws exceptions only if this Context3D instance has been disposed or there are too many draw calls. If the rendering context state is invalid rendering fails silently. When the enableErrorChecking property is true, this function returns after the triangles are drawn and throws exceptions for any drawing errors or invalid context state.

Parameters:

indexBuffer:IndexBuffer3D

— a set of vertex indices referencing the vertices to render.

firstIndex:int

(default = 0) — the index of the first vertex index selected to render. Default 0.

numTriangles:int

(default = -1) — the number of triangles to render. Each triangle consumes three indices. Pass -1 to draw all triangles in the index buffer. Default -1.

Throws:

Error

— Object Disposed: if this Context3D object has been disposed by a calling dispose() or because the underlying rendering hardware has been lost.

Error

— If this method is called too many times between calls to present(). The maximum number of calls is 32,768. The following errors are only thrown when enableErrorChecking property is true:

Error

Need To Clear Before Draw: If the buffer has not been cleared since the last present() call.

Error

If a valid Program3D object is not set.

Error

No Valid Index Buffer Set: If an IndexBuffer3D object is not set.

Error

Sanity Check On Parameters Failed: when the number of triangles to be drawn or the firstIndex exceed allowed values.

RangeError

— Not Enough Indices In This Buffer: when there aren't enough indices in the buffer to define the number of triangles to be drawn.

Error

— Sample Binds Texture Also Bound To Render: when the render target is a texture and that texture assigned to a texture input of the current fragment program.

Error

— Sample Binds Invalid Texture: an invalid texture is specified as the input to the current fragment program.

Error

— Sampler Format Does Not Match Texture Format: when the texture assigned as the input to the current fragment program has a different format than that specified for the sampler register. For example, a 2D texture is assigned to a cube texture sampler.

Error

— Sample Binds Undefined Texture: The current fragment program accesses a texture register that has not been set (using setTextureAt()).

Error

— Same Texture Needs Same Sampler Params: If a texture is used for more than one sampler register, all of the samplers must have the same settings. For example, you cannot set one sampler to clamp and another to wrap.

Error

— Texture Bound But Not Used: A texture is set as a shader input, but it is not used.

Error

— Stream Is Not Used: A vertex buffer is assigned to a vertex attribute input, but the vertex program does not reference the corresponding register.

Error

— Stream Is Invalid: a VertexBuffer3D object assigned to a vertex program input is not a valid object.

RangeError

— Stream Does Not Have Enough Vertices: A vertex buffer supplying data for drawing the specified triangles does not have enough data.

RangeError

— Stream Vertex Offset Out Of Bounds: The offset specified in a setVertexBufferAt() call is negative or past the end of the buffer.

Error

— Stream Read But Not Set: A vertex attribute used by the current vertex program is not set (using setVertexBufferAt()).

present ():Void

Displays the back rendering buffer.

Calling the present() method makes the results of all rendering operations since the last present() call visible and starts a new rendering cycle. After calling present, you must call clear() before making another drawTriangles() call. Otherwise, this function will alternately clear the render buffer to yellow and green or, if enableErrorChecking has been set to true, an exception is thrown.

Calling present() also resets the render target, just like calling setRenderToBackBuffer().

Throws:

Error

Need To Clear Before Draw: If the clear() has not been called since the previous call to present(). (Two consecutive present() calls are not allowed without calling clear() in between.)

Error

3768: The Stage3D API may not be used during background execution.

setBlendFactors (sourceFactor:Context3DBlendFactor, destinationFactor:Context3DBlendFactor):Void

Specifies the factors used to blend the output color of a drawing operation with the existing color.

The output (source) color of the pixel shader program is combined with the existing (destination) color at that pixel according to the following formula:

result color = (source color * sourceFactor) + (destination color * destinationFactor)

The destination color is the current color in the render buffer for that pixel. Thus it is the result of the most recent clear() call and any intervening drawTriangles() calls.

Use setBlendFactors() to set the factors used to multiply the source and destination colors before they are added together. The default blend factors are, sourceFactor = Context3DBlendFactor.ONE, and destinationFactor = Context3DBlendFactor.ZERO, which results in the source color overwriting the destination color (in other words, no blending of the two colors occurs). For normal alpha blending, use sourceFactor = Context3DBlendFactor.SOURCE_ALPHA and destinationFactor = Context3DBlendFactor.ONE_MINUS_SOURCE_ALPHA.

Use the constants defined in the Context3DBlendFactor class to set the parameters of this function.

Parameters:

sourceFactor

The factor with which to multiply the source color. Defaults to Context3DBlendFactor.ONE.

destinationFactor

The factor with which to multiply the destination color. Defaults to Context3DBlendFactor.ZERO.

Throws:

Error

— Invalid Enum: when sourceFactor or destinationFactor is not one of the recognized values, which are defined in the Context3DBlendFactor class.

setColorMask (red:Bool, green:Bool, blue:Bool, alpha:Bool):Void

Sets the mask used when writing colors to the render buffer.

Only color components for which the corresponding color mask parameter is true are updated when a color is written to the render buffer. For example, if you call: setColorMask(true, false, false, false), only the red component of a color is written to the buffer until you change the color mask again. The color mask does not affect the behavior of the clear() method.

Parameters:

red

set false to block changes to the red channel.

green

set false to block changes to the green channel.

blue

set false to block changes to the blue channel.

alpha

set false to block changes to the alpha channel.

setCulling (triangleFaceToCull:Context3DTriangleFace):Void

Sets triangle culling mode.

Triangles may be excluded from the scene early in the rendering pipeline based on their orientation relative to the view plane. Specify vertex order consistently (clockwise or counter-clockwise) as seen from the outside of the model to cull correctly.

Parameters:

triangleFaceToCull

the culling mode. Use one of the constants defined in the Context3DTriangleFace class.

Throws:

Error

Invalid Enum Error: when triangleFaceToCull is not one of the values defined in the Context3DTriangleFace class.

setDepthTest (depthMask:Bool, passCompareMode:Context3DCompareMode):Void

Sets type of comparison used for depth testing.

The depth of the source pixel output from the pixel shader program is compared to the current value in the depth buffer. If the comparison evaluates as false, then the source pixel is discarded. If true, then the source pixel is processed by the next step in the rendering pipeline, the stencil test. In addition, the depth buffer is updated with the depth of the source pixel, as long as the depthMask parameter is set to true.

Sets the test used to compare depth values for source and destination pixels. The source pixel is composited with the destination pixel when the comparison is true. The comparison operator is applied as an infix operator between the source and destination pixel values, in that order.

Parameters:

depthMask

the destination depth value will be updated from the source pixel when true.

passCompareMode

the depth comparison test operation. One of the values of Context3DCompareMode.

setProgram (program:Program3D):Void

Sets vertex and fragment shader programs to use for subsequent rendering.

Parameters:

program

the Program3D object representing the vertex and fragment programs to use.

setProgramConstantsFromByteArray (programType:Context3DProgramType, firstRegister:Int, numRegisters:Int, data:ByteArray, byteArrayOffset:UInt):Void

Set constants for use by shader programs using values stored in a ByteArray.

Sets constants that can be accessed from the vertex or fragment program.

Parameters:

programType

one of Context3DProgramType.

firstRegister

the index of the first shader program constant to set.

numRegisters

the number of registers to set. Every register is read as four float values.

data

the source ByteArray object

byteArrayOffset

an offset into the ByteArray for reading

Throws:

TypeError

kNullPointerError when data is null.

RangeError

kConstantRegisterOutOfBounds when attempting to set more than the maximum number of shader constants.

RangeError

kBadInputSize if byteArrayOffset is greater than or equal to the length of data or no. of elements in data - byteArrayOffset is less than numRegisters*16

setProgramConstantsFromMatrix (programType:Context3DProgramType, firstRegister:Int, matrix:Matrix3D, transposedMatrix:Bool = false):Void

Sets constants for use by shader programs using values stored in a Matrix3D.

Use this function to pass a matrix to a shader program. The function sets 4 constant registers used by the vertex or fragment program. The matrix is assigned to registers row by row. The first constant register is assigned the top row of the matrix. You can set 128 registers for a vertex program and 28 for a fragment program.

Parameters:

programType

The type of shader program, either Context3DProgramType.VERTEX or Context3DProgramType.FRAGMENT.

firstRegister

the index of the first constant register to set. Since a Matrix3D has 16 values, four registers are set.

matrix

the matrix containing the constant values.

transposedMatrix

if true the matrix entries are copied to registers in transposed order. The default value is false.

Throws:

TypeError

Null Pointer Error: when matrix is null.

RangeError

Constant Register Out Of Bounds: when attempting to set more than the maximum number of shader constant registers.

setProgramConstantsFromVector (programType:Context3DProgramType, firstRegister:Int, data:Vector<Float>, numRegisters:Int = -1):Void

Sets the constant inputs for the shader programs.

Sets an array of constants to be accessed by a vertex or fragment shader program. Constants set in Program3D are accessed within the shader programs as constant registers. Each constant register is comprised of 4 floating point values (x, y, z, w). Therefore every register requires 4 entries in the data Vector. The number of registers that you can set for vertex program and fragment program depends on the Context3DProfile.

Parameters:

programType

The type of shader program, either Context3DProgramType.VERTEX or Context3DProgramType.FRAGMENT.

firstRegister

the index of the first constant register to set.

data

the floating point constant values. There must be at least numRegisters 4 elements in data.

numRegisters

the number of constants to set. Specify -1, the default value, to set enough registers to use all of the available data.

Throws:

TypeError

Null Pointer Error: when data is null.

RangeError

Constant Register Out Of Bounds: when attempting to set more than the maximum number of shader constant registers.

RangeError

Bad Input Size: When the number of elements in data is less than numRegisters*4

setRenderToBackBuffer ():Void

Sets the back rendering buffer as the render target. Subsequent calls to drawTriangles() and clear() methods result in updates to the back buffer. Use this method to resume normal rendering after using the setRenderToTexture() method.

setRenderToTexture (texture:TextureBase, enableDepthAndStencil:Bool = false, antiAlias:Int = 0, surfaceSelector:Int = 0):Void

Sets the specified texture as the rendering target.

Subsequent calls to drawTriangles() and clear() methods update the specified texture instead of the back buffer. Mip maps are created automatically. Use the setRenderToBackBuffer() to resume normal rendering to the back buffer.

No clear is needed before drawing. If there is no clear operation, the render content will be retained. depth buffer and stencil buffer will also not be cleared. But it is forced to clear when first drawing. Calling present() resets the target to the back buffer.

Parameters:

texture

the target texture to render into. Set to null to resume rendering to the back buffer (setRenderToBackBuffer() and present also reset the target to the back buffer).

enableDepthAndStencil

if true, depth and stencil testing are available. If false, all depth and stencil state is ignored for subsequent drawing operations.

antiAlias

the antialiasing quality. Use 0 to disable antialiasing; higher values improve antialiasing quality, but require more calculations. The value is currently ignored by mobile platform and software rendering context.

surfaceSelector

specifies which element of the texture to update. Texture objects have one surface, so you must specify 0, the default value. CubeTexture objects have six surfaces, so you can specify an integer from 0 through 5.

colorOutputIndex

The output color register. Must be 0 for constrained or baseline mode. Otherwise specifies the output color register.

Throws:

ArgumentError

for a mismatched surfaceSelector parameter. The value must be 0 for 2D textures and 0..5 for cube maps.

ArgumentError

texture is not derived from the TextureBase class (either Texture or CubeTexture classes).

ArgumentError

colorOutputIndex must be an integer is from 0 through 3.

ArgumentError

this call requires a Context3D that is created with the standard profile or above.

setSamplerStateAt (sampler:Int, wrap:Context3DWrapMode, filter:Context3DTextureFilter, mipfilter:Context3DMipFilter):Void

Manually override texture sampler state.

Texture sampling state is typically set at the time setProgram is called. However, you can override texture sampler state with this function. If you do not want the program to change sampler state, set the ignoresamnpler bit in AGAL and use this function.

Parameters:

sampler

sampler The sampler register to use. Maps to the sampler register in AGAL.

wrap

Wrapping mode. Defined in Context3DWrapMode. The default is repeat.

filter

Texture filtering mode. Defined in Context3DTextureFilter. The default is nearest.

mipfilter

Mip map filter. Defined in Context3DMipFilter. The default is none.

Throws:

Error

sampler out of range

Error

wrap, filter, mipfilter bad enum

Error

Object Disposed: if this Context3D object has been disposed by a calling dispose() or because the underlying rendering hardware has been lost.

setScissorRectangle (rectangle:Rectangle):Void

Sets a scissor rectangle, which is type of drawing mask. The renderer only draws to the area inside the scissor rectangle. Scissoring does not affect clear operations.

Pass null to turn off scissoring.

Parameters:

rectangle

The rectangle in which to draw. Specify the rectangle position and dimensions in pixels. The coordinate system origin is the top left corner of the viewport, with positive values increasing down and to the right (the same as the normal OpenFL display coordinate system).

setStencilActions (triangleFace:Context3DTriangleFace = FRONT_AND_BACK, compareMode:Context3DCompareMode = ALWAYS, actionOnBothPass:Context3DStencilAction = KEEP, actionOnDepthFail:Context3DStencilAction = KEEP, actionOnDepthPassStencilFail:Context3DStencilAction = KEEP):Void

Sets stencil mode and operation.

An 8-bit stencil reference value can be associated with each draw call. During rendering, the reference value can be tested against values stored previously in the frame buffer. The result of the test can control the draw action and whether or how the stored stencil value is updated. In addition, depth testing controls whether stencil testing is performed. A failed depth test can also be used to control the action taken on the stencil buffer.

In the pixel processing pipeline, depth testing is performed first. If the depth test fails, a stencil buffer update action can be taken, but no further evaluation of the stencil buffer value can be made. If the depth test passes, then the stencil test is performed. Alternate actions can be taken depending on the outcome of the stencil test.

The stencil reference value is set using setStencilReferenceValue().

Parameters:

triangleFace

the triangle orientations allowed to contribute to the stencil operation. One of Context3DTriangleFace.

compareMode

the test operator used to compare the current stencil reference value and the destination pixel stencil value. Destination pixel color and depth update is performed when the comparison is true. The stencil actions are performed as requested in the following action parameters. The comparison operator is applied as an infix operator between the current and destination reference values, in that order (in pseudocode: if stencilReference OPERATOR stencilBuffer then pass). Use one of the constants defined in the Context3DCompareMode class.

actionOnBothPass

action to be taken when both depth and stencil comparisons pass. Use one of the constants defined in the Context3DStencilAction class.

actionOnDepthFail

action to be taken when depth comparison fails. Use one of the constants defined in the Context3DStencilAction class.

actionOnDepthPassStencilFail

action to be taken when depth comparison passes and the stencil comparison fails. Use one of the constants defined in the Context3DStencilAction class.

Throws:

Error

Invalid Enum Error: when triangleFace is not one of the values defined in the Context3DTriangleFace class.

Error

Invalid Enum Error: when compareMode is not one of the values defined in the Context3DCompareMode class.

Error

Invalid Enum Error: when actionOnBothPass, actionOnDepthFail, or actionOnDepthPassStencilFail is not one of the values defined in the Context3DStencilAction class.

setStencilReferenceValue (referenceValue:UInt, readMask:UInt = 0xFF, writeMask:UInt = 0xFF):Void

Sets the stencil comparison value used for stencil tests.

Only the lower 8 bits of the reference value are used. The stencil buffer value is also 8 bits in length. Use the readMask and writeMask to use the stencil buffer as a bit field.

Parameters:

referenceValue

an 8-bit reference value used in reference value comparison tests.

readMask

an 8-bit mask for applied to both the current stencil buffer value and the reference value before the comparison.

writeMask

an 8-bit mask applied to the reference value before updating the stencil buffer.

setTextureAt (sampler:Int, texture:TextureBase):Void

Specifies the texture to use for a texture input register of a fragment program.

A fragment program can read information from up to eight texture objects. Use this function to assign a Texture or CubeTexture object to one of the sampler registers used by the fragment program.

Note: if you change the active fragment program (with setProgram) to a shader that uses fewer textures, set the unused registers to null:

haxe setTextureAt(7, null);


Parameters:

sampler

the sampler register index, a value from 0 through 7.

texture

the texture object to make available, either a Texture or a CubeTexture instance.

setVertexBufferAt (index:Int, buffer:VertexBuffer3D, bufferOffset:Int = 0, format:Context3DVertexBufferFormat = FLOAT_4):Void

Specifies which vertex data components correspond to a single vertex shader program input.

Use the setVertexBufferAt method to identify which components of the data defined for each vertex in a VertexBuffer3D buffer belong to which inputs to the vertex program. The developer of the vertex program determines how much data is needed per vertex. That data is mapped from 1 or more VertexBuffer3D stream(s) to the attribute registers of the vertex shader program.

The smallest unit of data consumed by the vertex shader is a 32-bit data. Offsets into the vertex stream are specified in multiples of 32-bits.

As an example, a programmer might define each vertex with the following data:

position:  x    float32
		   y    float32
		   z    float32
color:     r    unsigned byte
		   g    unsigned byte
		   b    unsigned byte
		   a    unsigned byte

Assuming the vertex was defined in a VertexBuffer3D object named buffer, it would be assigned to a vertex shader with the following code:

setVertexBufferAt(0, buffer, 0, Context3DVertexBufferFormat.FLOAT_3);   // attribute #0 will contain the position information
setVertexBufferAt(1, buffer, 3, Context3DVertexBufferFormat.BYTES_4);    // attribute #1 will contain the color information

Parameters:

index

the index of the attribute register in the vertex shader (0 through 7).

buffer

the buffer that contains the source vertex data to be fed to the vertex shader.

bufferOffset

an offset from the start of the data for a single vertex at which to start reading this attribute. In the example above, the position data has an offset of 0 because it is the first attribute; color has an offset of 3 because the color attribute follows the three 32-bit position values. The offset is specified in units of 32 bits.

format

a value from the Context3DVertexBufferFormat class specifying the data type of this attribute.

Throws:

Error

Invalid Enum: when format is not one of the values defined in the Context3DVertexBufferFormat class.

RangeError

Attribute Register Out Of Bounds: when the index parameter is outside the range from 0 through 7. (A maximum of eight vertex attribute registers can be used by a shader.)

Static variables

staticread onlysupportsVideoTexture:Bool = false

Indicates if Context3D supports video texture.

Inherited Variables

Inherited Methods

Defined by EventDispatcher

addEventListener (type:String, listener:Dynamic ‑> Void, useCapture:Bool = false, priority:Int = 0, useWeakReference:Bool = false):Void

Registers an event listener object with an EventDispatcher object so that the listener receives notification of an event. You can register event listeners on all nodes in the display list for a specific type of event, phase, and priority.

After you successfully register an event listener, you cannot change its priority through additional calls to addEventListener(). To change a listener's priority, you must first call removeListener(). Then you can register the listener again with the new priority level.

Keep in mind that after the listener is registered, subsequent calls to addEventListener() with a different type or useCapture value result in the creation of a separate listener registration. For example, if you first register a listener with useCapture set to true, it listens only during the capture phase. If you call addEventListener() again using the same listener object, but with useCapture set to false, you have two separate listeners: one that listens during the capture phase and another that listens during the target and bubbling phases.

You cannot register an event listener for only the target phase or the bubbling phase. Those phases are coupled during registration because bubbling applies only to the ancestors of the target node.

If you no longer need an event listener, remove it by calling removeEventListener(), or memory problems could result. Event listeners are not automatically removed from memory because the garbage collector does not remove the listener as long as the dispatching object exists(unless the useWeakReference parameter is set to true).

Copying an EventDispatcher instance does not copy the event listeners attached to it.(If your newly created node needs an event listener, you must attach the listener after creating the node.) However, if you move an EventDispatcher instance, the event listeners attached to it move along with it.

If the event listener is being registered on a node while an event is being processed on this node, the event listener is not triggered during the current phase but can be triggered during a later phase in the event flow, such as the bubbling phase.

If an event listener is removed from a node while an event is being processed on the node, it is still triggered by the current actions. After it is removed, the event listener is never invoked again(unless registered again for future processing).

Parameters:

type

The type of event.

useCapture

Determines whether the listener works in the capture phase or the target and bubbling phases. If useCapture is set to true, the listener processes the event only during the capture phase and not in the target or bubbling phase. If useCapture is false, the listener processes the event only during the target or bubbling phase. To listen for the event in all three phases, call addEventListener twice, once with useCapture set to true, then again with useCapture set to false.

priority

The priority level of the event listener. The priority is designated by a signed 32-bit integer. The higher the number, the higher the priority. All listeners with priority n are processed before listeners of priority n-1. If two or more listeners share the same priority, they are processed in the order in which they were added. The default priority is 0.

useWeakReference

Determines whether the reference to the listener is strong or weak. A strong reference(the default) prevents your listener from being garbage-collected. A weak reference does not.

Class-level member functions are not subject to garbage collection, so you can set useWeakReference to true for class-level member functions without subjecting them to garbage collection. If you set useWeakReference to true for a listener that is a nested inner function, the function will be garbage-collected and no longer persistent. If you create references to the inner function(save it in another variable) then it is not garbage-collected and stays persistent.

Throws:

ArgumentError

The listener specified is not a function.

dispatchEvent (event:Event):Bool

Dispatches an event into the event flow. The event target is the EventDispatcher object upon which the dispatchEvent() method is called.

Parameters:

event

The Event object that is dispatched into the event flow. If the event is being redispatched, a clone of the event is created automatically. After an event is dispatched, its target property cannot be changed, so you must create a new copy of the event for redispatching to work.

Throws:

Error

The event dispatch recursion limit has been reached.

Returns:

A value of true if the event was successfully dispatched. A value of false indicates failure or that preventDefault() was called on the event.

hasEventListener (type:String):Bool

Checks whether the EventDispatcher object has any listeners registered for a specific type of event. This allows you to determine where an EventDispatcher object has altered handling of an event type in the event flow hierarchy. To determine whether a specific event type actually triggers an event listener, use willTrigger().

The difference between hasEventListener() and willTrigger() is that hasEventListener() examines only the object to which it belongs, whereas willTrigger() examines the entire event flow for the event specified by the type parameter.

When hasEventListener() is called from a LoaderInfo object, only the listeners that the caller can access are considered.

Parameters:

type

The type of event.

Returns:

A value of true if a listener of the specified type is registered; false otherwise.

removeEventListener (type:String, listener:Dynamic ‑> Void, useCapture:Bool = false):Void

Removes a listener from the EventDispatcher object. If there is no matching listener registered with the EventDispatcher object, a call to this method has no effect.

Parameters:

type

The type of event.

useCapture

Specifies whether the listener was registered for the capture phase or the target and bubbling phases. If the listener was registered for both the capture phase and the target and bubbling phases, two calls to removeEventListener() are required to remove both, one call with useCapture() set to true, and another call with useCapture() set to false.

toString ():String

willTrigger (type:String):Bool

Checks whether an event listener is registered with this EventDispatcher object or any of its ancestors for the specified event type. This method returns true if an event listener is triggered during any phase of the event flow when an event of the specified type is dispatched to this EventDispatcher object or any of its descendants.

The difference between the hasEventListener() and the willTrigger() methods is that hasEventListener() examines only the object to which it belongs, whereas the willTrigger() method examines the entire event flow for the event specified by the type parameter.

When willTrigger() is called from a LoaderInfo object, only the listeners that the caller can access are considered.

Parameters:

type

The type of event.

Returns:

A value of true if a listener of the specified type will be triggered; false otherwise.