final class Context3D

Indicates if Context3D supports video texture.

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.

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.

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.

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.

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.

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.

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

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.

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:

Throws:

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:

Throws:

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:

Returns:

Throws:

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:

Returns:

Throws:

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:

Returns:

Throws:

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:

Returns:

Throws:

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:

Returns:

Throws:

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:

Returns:

Throws:

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.

Returns:

Throws:

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:

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:

Throws:

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:

Throws:

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:

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:

Throws:

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:

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:

Throws:

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:

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

Parameters:

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:

Throws:

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:

Throws:

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:

Throws:

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.

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:

Throws:

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:

Throws:

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:

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:

Throws:

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:

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:

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:

Throws: