The Context3D object 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 object 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:


Configure the main display buffer attributes by calling configureBackBuffer().

Create and initialize your rendering resources, including:

Vertex and index buffers defining the scene geometry

Vertex and pixel programs (shaders) for rendering the scene

Textures

Render a frame:

Set the render state as appropriate for an object or collection of objects in the scene.

Call the drawTriangles() method to render a set of triangles.

Change the rendering state for the next group of objects.

Call drawTriangles() to draw the triangles defining the objects.

Repeat until the scene is entirely rendered.

Call the present() method to display the rendered scene on the stage.


Created Context3D object has properties:

driverInfo

The type of graphics library driver used by this rendering context.

read-only, String

enableErrorChecking

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

true/false


methods:

clear(red, green, blue, alpha, depth, stencil, mask) 

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

red - (default = 0.0) - the red component of the color with which to clear the color buffer, in the range zero to one.

green - (default = 0.0) - the green component of the color with which to clear the color buffer, in the range zero to one.

blue - (default = 0.0) - the blue component of the color with which to clear the color buffer, in the range zero to one.

alpha - (default = 1.0) - 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 - (default = 1.0) - the value with which to clear the depth buffer, in the range zero to one.

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

mask - (default = Lib.Media.Display3D.Context3DClearMask.ALL) - specifies which buffers to clear.

configureBackBuffer(width, height, antiAlias, enableDepthAndStencil)

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

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 - (default = true) - false indicates no depth or stencil buffer is created, true creates a depth and a stencil buffer. By default, the value of the depthAndStencil element is false.

createCubeTexture(size, format, optimizeForRenderToTexture, streamingLevels)

Creates a CubeTexture object.

Note: currently compressed textures not supported.

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. 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 Context3DTextureFormat.COMPRESSED or Context3DTextureFormat.COMPRESSED_ALPHA as the format parameter. 2. Using the Texture instance returned by createCubeTexture(), call either CubeTexture.uploadFromBitmapData() or 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 - (default = 0) - 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.

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.

createIndexBuffer(numIndices)

Creates an IndexBuffer3D object.

numIndices - the number of vertices to be stored in the buffer, int

createProgram()

Creates a Program3D object.

createRectangleTexture(width, height, format, optimizeForRenderToTexture)

Creates a Rectangle Texture object.

Note: currently compressed textures not supported.

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.

createTexture(width, height, format, optimizeForRenderToTexture, streamingLevels)

Creates a Texture object.

Note: currently compressed textures not supported.

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. 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 Context3DTextureFormat.COMPRESSED or Context3DTextureFormat.COMPRESSED_ALPHA as the format parameter. 2. Using the Texture instance returned by createTexture(), call either Texture.uploadFromBitmapData() or 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 - (default = 0) - 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.

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.

createVertexBuffer(numVertices, data32PerVertex)

Creates a VertexBuffer3D object.

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.

dispose()

Frees all resources and internal storage associated with this Context3D.

drawToBitmapData(destination)

Not supported

drawTriangles(indexBuffer, firstIndex, numTriangles)

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

indexBuffer - IndexBuffer3D object, a set of vertex indices referencing the vertices to render.

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

numTriangles - (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.

present()

Displays the back rendering buffer.

setBlendFactors(sourceFactor, destinationFactor)

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

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.

setColorMask(red, green, blue, alpha) 

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

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)

Sets triangle culling mode.

triangleFaceToCull - the culling mode. Use one of the constants defined in the Context3DTriangleFace object.

setDepthTest(depthMask, passCompareMode)

Sets type of comparison used for depth testing.

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)

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

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

setProgramConstantsFromByteArray(programType, firstRegister, numRegisters, data, byteArrayOffset)

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

programType - one of Context3DProgramType. 

firstRegister - the index of the first shader program constant to set, int.

numRegisters - the number of registers to set, int. Every register is read as four float values. 

data - the source ByteArray object 

byteArrayOffset - an offset into the ByteArray for reading, int.

setProgramConstantsFromMatrix(programType, firstRegister, matrix, transposedMatrix)

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

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, int.

matrix - the matrix containing the constant values, Matrix3D object.

transposedMatrix - (default = false) - if true the matrix entries are copied to registers in transposed order. The default value is false.

setProgramConstantsFromVector(programType, firstRegister, data, numRegisters)

Sets the constant inputs for the shader programs.

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, vector array of floats.

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

setGLSLProgramConstantsFromByteArray(locationName, data, byteArrayOffset)

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

locationName - uniform location name, string. 

data - the source ByteArray object 

byteArrayOffset - an offset into the ByteArray for reading, int.

setGLSLProgramConstantsFromMatrix(locationName, matrix, transposedMatrix)

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

locationName - uniform location name, string. 

matrix - the matrix containing the constant values, Matrix3D object.

transposedMatrix - (default = false) - if true the matrix entries are copied to registers in transposed order. The default value is false.

setGLSLProgramConstantsFromVector4(locationName, data, startIndex)

Sets the constant inputs for the GLSL shader programs.

locationName - uniform location name, string. 

data - the floating point constant values. There must be 4 elements in data, vector array of floats.

startIndex - (default = 0) - data start index,

data[startIndex], data[startIndex + 1], data[startIndex+2], data[startIndex+3]

setRenderToBackBuffer()

Sets the back rendering buffer as the render target.


setRenderToTexture(texture, enableDepthAndStencil, antiAlias, surfaceSelector)

Sets the specified texture as the rendering target.

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

enableDepthAndStencil - (default = false) - if true, depth and stencil testing are available. If false, all depth and stencil state is ignored for subsequent drawing operations.

antiAlias - (default = 0) - 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 - (default = 0) - 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.

setSamplerStateAt(sampler, wrap, filter, mipfilter)

Manually override texture sampler state.

sampler - sampler The sampler register to use. Maps to the sampler register in AGAL, int value.

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.

setScissorRectangle(rectangle)

Sets a scissor rectangle, which is type of drawing mask.

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 Flash display coordinate system).

setStencilActions(triangleFace,compareMode, actionOnBothPass, actionOnDepthFail, actionOnDepthPassStencilFail)

Not supported


setStencilReferenceValue(referenceValue, readMask, writeMask)

Not supported


setTextureAt(sampler, texture)

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

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.

setGLSLTextureAt(locationName, texture, textureIndex)

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

locationName - uniform location name, string.

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

textureIndex - texture index, int [0..7]

setVertexBufferAt(index, buffer, bufferOffset, format)

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

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

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

bufferOffset - (default = 0) - 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 - (default = "float4") - a value from the Context3DVertexBufferFormat object specifying the data type of this attribute.

setGLSLVertexBufferAt(locationName, buffer, bufferOffset, format)

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

locationName - uniform location name, string.

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

bufferOffset - (default = 0) - 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 - (default = "float4") - a value from the Context3DVertexBufferFormat object specifying the data type of this attribute.



Created with the Personal Edition of HelpNDoc: Full-featured Help generator