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.

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.

See also

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

See also

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 50x50 pixels. Configuring the buffer is a slow operation. Avoid changing the buffer size or attributes during normal rendering operations.

Parameters

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

See also

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

See also

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.

See also

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.

Parameters

See also

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. (A shader program can use up to eight inputs.)

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

See also

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 object while the associated Stage3D object still has a listener for the context3DCreate event, simulates a device loss. The runtime creates a new Context3D instance for the Stage3D object and dispatches another context3DCreate event. If this is not desired, remove the event listener from the Stage3D object before calling dispose().

See also

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

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.

Flash 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

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

See also

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

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

See also

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

See also

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

See also

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

Parameters

See also

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

See also

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. You can set 128 registers for a vertex program and 28 for a fragment program.

Parameters

See also

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.

The texture must be cleared before drawing and the clear() method is called automatically if needed. Calling present() resets the target to the back buffer.

Parameters

See also

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

See also

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

See also

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:

         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.

position:  x    float32

           y    float32

           z    float32

color:     r    unsigned byte

           g    unsigned byte

           b    unsigned byte

           a    unsigned byte

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

See also

The example uses an ActionScript library, 3Dutils.swf, that contains the AGALMiniAssembler class for compiling AGAL assembly to bytecode and the PerspectiveMatrix3D class for creating a prespective projection.

<html>
    <head>
        <title>Spinning cube</title>
        <script src="AIRAliases.js" type="text/javascript"></script>
        <script src="3Dutils.swf" type="application/x-shockwave-flash"></script>
        <script type="text/javascript">
         const viewWidth = 320;
         const viewHeight = 200;
         const zNear = 1;
         const zFar = 500;
        
         const fov = 45;
        
         var stage3D;
         var renderContext;
         var indexList;
         var vertexes;
        
         var projection = new window.runtime.com.adobe.utils.PerspectiveMatrix3D();
         var model = new air.Matrix3D();
         var view = new air.Matrix3D();
         var finalTransform = new air.Matrix3D();
        
        //For rotating the cube
         var pivot = new air.Vector3D();
        
         const VERTEX_SHADER =
            "m44 op, va0, vc0    \n" +    // 4x4 matrix transform 
            "mov v0, va1"; //copy color to varying variable v0
        
         const FRAGMENT_SHADER = 
            "mov oc, v0"; //Set the output color to the value interpolated from the three triangle vertices 

         var vertexAssembly = new window.runtime.com.adobe.utils.AGALMiniAssembler();
         var fragmentAssembly = new window.runtime.com.adobe.utils.AGALMiniAssembler();
         var programPair;
        
         function Context3DExample()
        {
                    window.htmlLoader.paintsDefaultBackground = false;
            window.nativeWindow.activate();
                         
            stage3D = window.nativeWindow.stage.stage3Ds[0];
            stage3D.x = 10;
            stage3D.y = 10;

            //Add event listener before requesting the context
            stage3D.addEventListener( air.Event.CONTEXT3D_CREATE, contextCreated );
            stage3D.addEventListener( air.ErrorEvent.ERROR, contextCreationError );
            stage3D.requestContext3D( air.Context3DRenderMode.AUTO );
            
            //Compile shaders
            vertexAssembly.assemble( air.Context3DProgramType.VERTEX, VERTEX_SHADER, false );
            fragmentAssembly.assemble( air.Context3DProgramType.FRAGMENT, FRAGMENT_SHADER, false );            
        }
        
        //Note, context3DCreate event can happen at any time, such as when the hardware resources are taken by another process
         function contextCreated( event )
        {
                renderContext = event.target.context3D;
                air.trace( "3D driver: " + renderContext.driverInfo );
                setupScene();
        }
        
         function setupScene()
        {
            renderContext.enableErrorChecking = true; //Can slow rendering - only turn on when developing/testing
            renderContext.configureBackBuffer( viewWidth, viewHeight, 2, false );
            renderContext.setCulling( air.Context3DTriangleFace.BACK );

            //Create vertex index list for the triangles forming a cube
            var triangles = air.Vector["<uint>"]([ 
                2,1,0, //front face
                3,2,0,
                4,7,5, //bottom face
                7,6,5,
                8,11,9, //back face
                9,11,10,
                12,15,13, //top face
                13,15,14,
                16,19,17, //left face
                17,19,18,
                20,23,21, //right face
                21,23,22
            ] );
            
            indexList = renderContext.createIndexBuffer( triangles.length );
            indexList.uploadFromVector( triangles, 0, triangles.length );
            
            //Create vertexes - cube faces do not share vertexes
            const dataPerVertex = 6;
            var vertexData = air.Vector["<Number>"]([
                    // x,y,z r,g,b format
                    0,0,0, 1,0,0, //front face
                    0,1,0, 1,0,0,
                    1,1,0, 1,0,0,
                    1,0,0, 1,0,0,
                    
                    0,0,0, 0,1,0, //bottom face
                    1,0,0, 0,1,0,
                    1,0,1, 0,1,0,
                    0,0,1, 0,1,0,
                    
                    0,0,1, 1,0,0, //back face
                    1,0,1, 1,0,0,
                    1,1,1, 1,0,0,
                    0,1,1, 1,0,0,
                    
                    0,1,1, 0,1,0, //top face
                    1,1,1, 0,1,0,
                    1,1,0, 0,1,0,
                    0,1,0, 0,1,0,
                    
                    0,1,1, 0,0,1, //left face
                    0,1,0, 0,0,1,
                    0,0,0, 0,0,1,
                    0,0,1, 0,0,1,
                    
                    1,1,0, 0,0,1, //right face
                    1,1,1, 0,0,1,
                    1,0,1, 0,0,1,
                    1,0,0, 0,0,1
                ]);

            vertexes = renderContext.createVertexBuffer( vertexData.length/dataPerVertex, dataPerVertex );
            vertexes.uploadFromVector( vertexData, 0, vertexData.length/dataPerVertex );
            
            //Identify vertex data inputs for vertex program
            renderContext.setVertexBufferAt( 0, vertexes, 0, air.Context3DVertexBufferFormat.FLOAT_3 ); //va0 is position
            renderContext.setVertexBufferAt( 1, vertexes, 3, air.Context3DVertexBufferFormat.FLOAT_3 ); //va1 is color
            
            //Upload programs to render context
            programPair = renderContext.createProgram();
            programPair.upload( vertexAssembly.agalcode, fragmentAssembly.agalcode );
            renderContext.setProgram( programPair );
            
            //Set up 3D transforms
            projection.perspectiveFieldOfViewRH( fov, viewWidth/viewHeight, zNear, zFar );            
            view.appendTranslation( 0, 0, -2 );    //Move view back
            model.appendTranslation( -.5, -.5, -.5 ); //center cube on origin
            window.nativeWindow.stage.addEventListener( air.Event.ENTER_FRAME, render );
        }
        
         function render( event )
        {
            //Rotate model on each frame
            model.appendRotation( .5, air.Vector3D.Z_AXIS, pivot );
            model.appendRotation( .5, air.Vector3D.Y_AXIS, pivot );
            model.appendRotation( .5, air.Vector3D.X_AXIS, pivot );
            
            //Combine transforms
            finalTransform.identity();
            finalTransform.append( model );
            finalTransform.append( view );
            finalTransform.append( projection );
            
            //Pass the final transform to the vertex shader as program constant, vc0
            renderContext.setProgramConstantsFromMatrix( air.Context3DProgramType.VERTEX, 0, finalTransform, true );
            
            //Clear is required before drawTriangles on each frame
            renderContext.clear( .3,.3,.3 );
            
            //Draw the 12 triangles that make up the cube
            renderContext.drawTriangles( indexList, 0, 12 );
            
            //Show the frame
            renderContext.present();
        }
        
         function contextCreationError( error )
        {
            air.trace( error.errorID + ": " + error.text );
        }
        </script>
    </head>
    <body onLoad="Context3DExample()">
        <p style="background-color:#FFF; width:100px">3D Example<example</p>
    </body>
</html>