pc.GraphicsDevice
The graphics device manages the underlying graphics context. It is responsible for submitting render state changes and graphics primitives to the hardware. A graphics device is tied to a specific canvas HTML element. It is valid to have more than one canvas element per page and create a new graphics device against each.
Summary
Properties
| height | Height of the back buffer in pixels.[read only] |
| maxAnisotropy | The maximum supported texture anisotropy setting.[read only] |
| maxCubeMapSize | The maximum supported dimension of a cube map.[read only] |
| maxTextureSize | The maximum supported dimension of a texture.[read only] |
| maxVolumeSize | The maximum supported dimension of a 3D texture (any axis).[read only] |
| precision | The highest shader precision supported by this graphics device.[read only] |
| width | Width of the back buffer in pixels.[read only] |
Methods
| clear | Clears the frame buffer of the currently set render target. |
| clearShaderCache | Frees memory from all shaders ever allocated with this device |
| draw | Submits a graphical primitive to the hardware for immediate rendering. |
| getBlending | Queries whether blending is enabled. |
| getDepthTest | Queries whether depth testing is enabled. |
| getDepthWrite | Queries whether writes to the depth buffer are enabled. |
| getRenderTarget | Queries the currently set render target on the device. |
| resizeCanvas | Sets the width and height of the canvas, then fires the 'resizecanvas' event. |
| setBlendEquation | Configures the blending equation. |
| setBlendEquationSeparate | Configures the blending equation. |
| setBlendFunction | Configures blending operations. |
| setBlendFunctionSeparate | Configures blending operations. |
| setBlending | Enables or disables blending. |
| setColorWrite | Enables or disables writes to the color buffer. |
| setCullMode | Controls how triangles are culled based on their face direction. |
| setDepthFunc | Configures the depth test. |
| setDepthTest | Enables or disables depth testing of fragments. |
| setDepthWrite | Enables or disables writes to the depth buffer. |
| setIndexBuffer | Sets the current index buffer on the graphics device. |
| setRenderTarget | Sets the specified render target on the device. |
| setScissor | Set the active scissor rectangle on the specified device. |
| setShader | Sets the active shader to be used during subsequent draw calls. |
| setStencilFunc | Configures stencil test for both front and back faces. |
| setStencilFuncBack | Configures stencil test for back faces. |
| setStencilFuncFront | Configures stencil test for front faces. |
| setStencilOperation | Configures how stencil buffer values should be modified based on the result of depth/stencil tests. |
| setStencilOperationBack | Configures how stencil buffer values should be modified based on the result of depth/stencil tests. |
| setStencilOperationFront | Configures how stencil buffer values should be modified based on the result of depth/stencil tests. |
| setStencilTest | Enables or disables stencil test. |
| setVertexBuffer | Sets the current vertex buffer for a specific stream index on the graphics device. |
| setViewport | Set the active rectangle for rendering on the specified device. |
| updateBegin | Marks the beginning of a block of rendering. |
| updateEnd | Marks the end of a block of rendering. |
Events
| resizecanvas | The 'resizecanvas' event is fired when the canvas is resized |
Details
Constructor
GraphicsDevice(canvas, [options])
Creates a new graphics device.
Parameters
| canvas | Object | The canvas to which the graphics device is tied. |
| options | Object | Options passed when creating the WebGL context. More info here https://developer.mozilla.org/en-US/docs/Web/API/HTMLCanvasElement/getContext |
Properties
Stringprecision
The highest shader precision supported by this graphics device. Can be 'hiphp', 'mediump' or 'lowp'.[read only]
Methods
clear(options)
Clears the frame buffer of the currently set render target.
// Clear color buffer to black and depth buffer to 1.0
device.clear();
// Clear just the color buffer to red
device.clear({
color: [1, 0, 0, 1],
flags: pc.CLEARFLAG_COLOR
});
// Clear color buffer to yellow and depth to 1.0
device.clear({
color: [1, 1, 0, 1],
depth: 1.0,
flags: pc.CLEARFLAG_COLOR | pc.CLEARFLAG_DEPTH
});Parameters
| options | Object | Optional options object that controls the behavior of the clear operation defined as follows: |
| options.color | Number[] | The color to clear the color buffer to in the range 0.0 to 1.0 for each component. |
| options.depth | Number | The depth value to clear the depth buffer to in the range 0.0 to 1.0. |
| options.flags | Number | The buffers to clear (the types being color, depth and stencil). Can be any bitwise
combination of:
|
clearShaderCache()
Frees memory from all shaders ever allocated with this device
draw(primitive, [numInstances])
Submits a graphical primitive to the hardware for immediate rendering.
// Render a single, unindexed triangle
device.draw({
type: pc.PRIMITIVE_TRIANGLES,
base: 0,
count: 3,
indexed: false
)};Parameters
| primitive | Object | Primitive object describing how to submit current vertex/index buffers defined as follows: |
| primitive.type | Number | The type of primitive to render. Can be:
|
| primitive.base | Number | The offset of the first index or vertex to dispatch in the draw call. |
| primitive.count | Number | The number of indices or vertices to dispatch in the draw call. |
| primitive.indexed | Boolean | True to interpret the primitive as indexed, thereby using the currently set index buffer and false otherwise. |
| numInstances | Number | The number of instances to render when using ANGLE_instanced_arrays. Defaults to 1. |
getBlending()
Queries whether blending is enabled.
Returns
Boolean True if blending is enabled and false otherwise.getDepthTest()
Queries whether depth testing is enabled.
var depthTest = device.getDepthTest();
console.log('Depth testing is ' + depthTest ? 'enabled' : 'disabled');Returns
Boolean true if depth testing is enabled and false otherwise.getDepthWrite()
Queries whether writes to the depth buffer are enabled.
var depthWrite = device.getDepthWrite();
console.log('Depth writing is ' + depthWrite ? 'enabled' : 'disabled');Returns
Boolean true if depth writing is enabled and false otherwise.getRenderTarget()
Queries the currently set render target on the device.
// Get the current render target
var renderTarget = device.getRenderTarget();Returns
pc.RenderTarget The current render target.resizeCanvas(width, height)
Sets the width and height of the canvas, then fires the 'resizecanvas' event. Note that the specified width and height values will be multiplied by the value of pc.GraphicsDevice#maxPixelRatio to give the final resultant width and height for the canvas.
Parameters
| width | Number | The new width of the canvas. |
| height | Number | The new height of the canvas. |
setBlendEquation(blendEquation)
Configures the blending equation. The default blend equation is pc.BLENDEQUATION_ADD.
Parameters
| blendEquation | Number | The blend equation. Can be:
|
setBlendEquationSeparate(blendEquation, blendAlphaEquation)
Configures the blending equation. The default blend equation is pc.BLENDEQUATION_ADD.
Parameters
| blendEquation | Number | The blend equation. Can be:
|
| blendAlphaEquation | Number | A separate blend equation for the alpha channel. Accepts same values as blendEquation. |
setBlendFunction(blendSrc, blendDst)
Configures blending operations. Both source and destination blend modes can take the following values:
- pc.BLENDMODE_ZERO
- pc.BLENDMODE_ONE
- pc.BLENDMODE_SRC_COLOR
- pc.BLENDMODE_ONE_MINUS_SRC_COLOR
- pc.BLENDMODE_DST_COLOR
- pc.BLENDMODE_ONE_MINUS_DST_COLOR
- pc.BLENDMODE_SRC_ALPHA
- pc.BLENDMODE_SRC_ALPHA_SATURATE
- pc.BLENDMODE_ONE_MINUS_SRC_ALPHA
- pc.BLENDMODE_DST_ALPHA
- pc.BLENDMODE_ONE_MINUS_DST_ALPHA
Parameters
| blendSrc | Number | The source blend function. |
| blendDst | Number | The destination blend function. |
setBlendFunctionSeparate(blendSrc, blendDst, blendSrcAlpha, blendDstAlpha)
Configures blending operations. Both source and destination blend modes can take the following values:
- pc.BLENDMODE_ZERO
- pc.BLENDMODE_ONE
- pc.BLENDMODE_SRC_COLOR
- pc.BLENDMODE_ONE_MINUS_SRC_COLOR
- pc.BLENDMODE_DST_COLOR
- pc.BLENDMODE_ONE_MINUS_DST_COLOR
- pc.BLENDMODE_SRC_ALPHA
- pc.BLENDMODE_SRC_ALPHA_SATURATE
- pc.BLENDMODE_ONE_MINUS_SRC_ALPHA
- pc.BLENDMODE_DST_ALPHA
- pc.BLENDMODE_ONE_MINUS_DST_ALPHA
Parameters
| blendSrc | Number | The source blend function. |
| blendDst | Number | The destination blend function. |
| blendSrcAlpha | Number | The separate source blend function for the alpha channel. |
| blendDstAlpha | Number | The separate destination blend function for the alpha channel. |
setBlending(blending)
Enables or disables blending.
Parameters
| blending | Boolean | True to enable blending and false to disable it. |
setColorWrite(writeRed, writeGreen, writeBlue, writeAlpha)
Enables or disables writes to the color buffer. Once this state is set, it persists until it is changed. By default, color writes are enabled for all color channels.
// Just write alpha into the frame buffer
device.setColorWrite(false, false, false, true);Parameters
| writeRed | Boolean | true to enable writing of the red channel and false otherwise. |
| writeGreen | Boolean | true to enable writing of the green channel and false otherwise. |
| writeBlue | Boolean | true to enable writing of the blue channel and false otherwise. |
| writeAlpha | Boolean | true to enable writing of the alpha channel and false otherwise. |
setCullMode(cullMode)
Controls how triangles are culled based on their face direction. The default cull mode is pc.CULLFACE_BACK.
Parameters
| cullMode | Number | The cull mode to set. Can be:
|
setDepthFunc(func)
Configures the depth test.
Parameters
| func | Number | A function to compare a new depth value with an existing z-buffer value and decide if to write a pixel. Can be:
|
setDepthTest(depthTest)
Enables or disables depth testing of fragments. Once this state is set, it persists until it is changed. By default, depth testing is enabled.
device.setDepthTest(true);Parameters
| depthTest | Boolean | true to enable depth testing and false otherwise. |
setDepthWrite(writeDepth)
Enables or disables writes to the depth buffer. Once this state is set, it persists until it is changed. By default, depth writes are enabled.
device.setDepthWrite(true);Parameters
| writeDepth | Boolean | true to enable depth writing and false otherwise. |
setIndexBuffer(indexBuffer)
Sets the current index buffer on the graphics device. On subsequent calls to pc.GraphicsDevice#draw, the specified index buffer will be used to provide index data for any indexed primitives.
Parameters
| indexBuffer | pc.IndexBuffer | The index buffer to assign to the device. |
setRenderTarget(renderTarget)
Sets the specified render target on the device. If null is passed as a parameter, the back buffer becomes the current target for all rendering operations.
// Set a render target to receive all rendering output
device.setRenderTarget(renderTarget);
// Set the back buffer to receive all rendering output
device.setRenderTarget(null);Parameters
| renderTarget | pc.RenderTarget | The render target to activate. |
setScissor(x, y, w, h)
Set the active scissor rectangle on the specified device.
Parameters
| x | Number | The pixel space x-coordinate of the bottom left corner of the scissor rectangle. |
| y | Number | The pixel space y-coordinate of the bottom left corner of the scissor rectangle. |
| w | Number | The width of the scissor rectangle in pixels. |
| h | Number | The height of the scissor rectangle in pixels. |
setShader(shader)
Sets the active shader to be used during subsequent draw calls.
Parameters
| shader | pc.Shader | The shader to set to assign to the device. |
Returns
Boolean true if the shader was successfully set, false otherwise.setStencilFunc(func, ref, mask)
Configures stencil test for both front and back faces.
Parameters
| func | Number | A comparison function that decides if the pixel should be written, based on the current stencil buffer value,
reference value, and mask value. Can be:
|
| ref | Number | Reference value used in comparison. |
| mask | Number | Mask applied to stencil buffer value and reference value before comparison. |
setStencilFuncBack(func, ref, mask)
Configures stencil test for back faces.
Parameters
| func | Number | A comparison function that decides if the pixel should be written,
based on the current stencil buffer value, reference value, and mask value. Can be:
|
| ref | Number | Reference value used in comparison. |
| mask | Number | Mask applied to stencil buffer value and reference value before comparison. |
setStencilFuncFront(func, ref, mask)
Configures stencil test for front faces.
Parameters
| func | Number | A comparison function that decides if the pixel should be written,
based on the current stencil buffer value, reference value, and mask value. Can be:
|
| ref | Number | Reference value used in comparison. |
| mask | Number | Mask applied to stencil buffer value and reference value before comparison. |
setStencilOperation(fail, zfail, zpass, writeMask)
Configures how stencil buffer values should be modified based on the result of depth/stencil tests. Works for both front and back faces.
Parameters
| fail | Number | Action to take if stencil test is failed |
| zfail | Number | Action to take if depth test is failed |
| zpass | Number | Action to take if both depth and stencil test are passed
All arguments can be:
|
| writeMask | Number | A bit mask applied to the reference value, when written. |
setStencilOperationBack(fail, zfail, zpass, writeMask)
Configures how stencil buffer values should be modified based on the result of depth/stencil tests. Works for back faces.
Parameters
| fail | Number | Action to take if stencil test is failed |
| zfail | Number | Action to take if depth test is failed |
| zpass | Number | Action to take if both depth and stencil test are passed
All arguments can be:
|
| writeMask | Number | A bit mask applied to the reference value, when written. |
setStencilOperationFront(fail, zfail, zpass, writeMask)
Configures how stencil buffer values should be modified based on the result of depth/stencil tests. Works for front faces.
Parameters
| fail | Number | Action to take if stencil test is failed |
| zfail | Number | Action to take if depth test is failed |
| zpass | Number | Action to take if both depth and stencil test are passed
All arguments can be:
|
| writeMask | Number | A bit mask applied to the reference value, when written. |
setStencilTest(enable)
Enables or disables stencil test.
Parameters
| enable | Boolean | True to enable stencil test and false to disable it. |
setVertexBuffer(vertexBuffer, stream, [vbOffset])
Sets the current vertex buffer for a specific stream index on the graphics device. On subsequent calls to pc.GraphicsDevice#draw, the specified vertex buffer will be used to provide vertex data for any primitives.
Parameters
| vertexBuffer | pc.VertexBuffer | The vertex buffer to assign to the device. |
| stream | Number | The stream index for the vertex buffer, indexed from 0 upwards. |
| vbOffset | Number | The byte offset into the vertex buffer data. Defaults to 0. |
setViewport(x, y, w, h)
Set the active rectangle for rendering on the specified device.
Parameters
| x | Number | The pixel space x-coordinate of the bottom left corner of the viewport. |
| y | Number | The pixel space y-coordinate of the bottom left corner of the viewport. |
| w | Number | The width of the viewport in pixels. |
| h | Number | The height of the viewport in pixels. |
updateBegin()
Marks the beginning of a block of rendering. Internally, this function binds the render target currently set on the device. This function should be matched with a call to pc.GraphicsDevice#updateEnd. Calls to pc.GraphicsDevice#updateBegin and pc.GraphicsDevice#updateEnd must not be nested.
updateEnd()
Marks the end of a block of rendering. This function should be called after a matching call to pc.GraphicsDevice#updateBegin. Calls to pc.GraphicsDevice#updateBegin and pc.GraphicsDevice#updateEnd must not be nested.