Class: GraphicsDevice

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.

Constructor

new GraphicsDevice(canvas, optionsopt)

Creates a new graphics device.
Parameters:
Name Type Attributes Description
canvas HTMLCanvasElement The canvas to which the graphics device will render.
options Object <optional>
Options passed when creating the WebGL context. More info here.
Properties:
Name Type Description
canvas HTMLCanvasElement The canvas DOM element that provides the underlying WebGL context used by the graphics device.
Source:

Members

(readonly) height :Number

Height of the back buffer in pixels.
Type:
  • Number
Source:

(readonly) maxAnisotropy :Number

The maximum supported texture anisotropy setting.
Type:
  • Number
Source:

(readonly) maxCubeMapSize :Number

The maximum supported dimension of a cube map.
Type:
  • Number
Source:

(readonly) maxTextureSize :Number

The maximum supported dimension of a texture.
Type:
  • Number
Source:

(readonly) maxVolumeSize :Number

The maximum supported dimension of a 3D texture (any axis).
Type:
  • Number
Source:

(readonly) precision :String

The highest shader precision supported by this graphics device. Can be 'hiphp', 'mediump' or 'lowp'.
Type:
  • String
Source:

(readonly) width :Number

Width of the back buffer in pixels.
Type:
  • Number
Source:

Methods

clear(options)

Clears the frame buffer of the currently set render target.
Parameters:
Name Type Description
options Object Optional options object that controls the behavior of the clear operation defined as follows:
Properties
Name Type Description
color Array.<Number> The color to clear the color buffer to in the range 0.0 to 1.0 for each component.
depth Number The depth value to clear the depth buffer to in the range 0.0 to 1.0.
flags Number The buffers to clear (the types being color, depth and stencil). Can be any bitwise combination of:
  • pc.CLEARFLAG_COLOR
  • pc.CLEARFLAG_DEPTH
  • pc.CLEARFLAG_STENCIL
Source:
Example
// 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
});

clearShaderCache()

Frees memory from all shaders ever allocated with this device
Source:

draw(primitive, numInstancesopt)

Submits a graphical primitive to the hardware for immediate rendering.
Parameters:
Name Type Attributes Default Description
primitive Object Primitive object describing how to submit current vertex/index buffers defined as follows:
Properties
Name Type Description
type Number The type of primitive to render. Can be:
  • pc.PRIMITIVE_POINTS
  • pc.PRIMITIVE_LINES
  • pc.PRIMITIVE_LINELOOP
  • pc.PRIMITIVE_LINESTRIP
  • pc.PRIMITIVE_TRIANGLES
  • pc.PRIMITIVE_TRISTRIP
  • pc.PRIMITIVE_TRIFAN
base Number The offset of the first index or vertex to dispatch in the draw call.
count Number The number of indices or vertices to dispatch in the draw call.
indexed Boolean True to interpret the primitive as indexed, thereby using the currently set index buffer and false otherwise.
numInstances Number <optional>
1 The number of instances to render when using ANGLE_instanced_arrays. Defaults to 1.
Source:
Example
// Render a single, unindexed triangle
device.draw({
    type: pc.PRIMITIVE_TRIANGLES,
    base: 0,
    count: 3,
    indexed: false
)};

getBlending() → {Boolean}

Queries whether blending is enabled.
Source:
Returns:
True if blending is enabled and false otherwise.
Type
Boolean

(private) getBoneLimit() → {Number}

Queries the maximum number of bones that can be referenced by a shader. The shader generators (pc.programlib) use this number to specify the matrix array size of the uniform 'matrix_pose[0]'. The value is calculated based on the number of available uniform vectors available after subtracting the number taken by a typical heavyweight shader. If a different number is required, it can be tuned via pc.GraphicsDevice#setBoneLimit.
Source:
Returns:
The maximum number of bones that can be supported by the host hardware.
Type
Number

getDepthTest() → {Boolean}

Queries whether depth testing is enabled.
Source:
Returns:
true if depth testing is enabled and false otherwise.
Type
Boolean
Example
var depthTest = device.getDepthTest();
console.log('Depth testing is ' + depthTest ? 'enabled' : 'disabled');

getDepthWrite() → {Boolean}

Queries whether writes to the depth buffer are enabled.
Source:
Returns:
true if depth writing is enabled and false otherwise.
Type
Boolean
Example
var depthWrite = device.getDepthWrite();
console.log('Depth writing is ' + depthWrite ? 'enabled' : 'disabled');

(private) getProgramLibrary() → {pc.ProgramLibrary}

Retrieves the program library assigned to the specified graphics device.
Source:
Returns:
The program library assigned to the device.
Type
pc.ProgramLibrary

getRenderTarget() → {pc.RenderTarget}

Queries the currently set render target on the device.
Source:
Returns:
The current render target.
Type
pc.RenderTarget
Example
// Get the current render target
var renderTarget = device.getRenderTarget();

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:
Name Type Description
width Number The new width of the canvas.
height Number The new height of the canvas.
Source:

(private) setAlphaToCoverage(state)

Enables or disables alpha to coverage (WebGL2 only).
Parameters:
Name Type Description
state Boolean True to enable alpha to coverage and false to disable it.
Source:

setBlendEquation(blendEquation)

Configures the blending equation. The default blend equation is pc.BLENDEQUATION_ADD.
Parameters:
Name Type Description
blendEquation Number The blend equation. Can be:
  • pc.BLENDEQUATION_ADD
  • pc.BLENDEQUATION_SUBTRACT
  • pc.BLENDEQUATION_REVERSE_SUBTRACT
  • pc.BLENDEQUATION_MIN
  • pc.BLENDEQUATION_MAX
  • Note that MIN and MAX modes require either EXT_blend_minmax or WebGL2 to work (check device.extBlendMinmax).
Source:

setBlendEquationSeparate(blendEquation, blendAlphaEquation)

Configures the blending equation. The default blend equation is pc.BLENDEQUATION_ADD.
Parameters:
Name Type Description
blendEquation Number The blend equation. Can be:
  • pc.BLENDEQUATION_ADD
  • pc.BLENDEQUATION_SUBTRACT
  • pc.BLENDEQUATION_REVERSE_SUBTRACT
  • pc.BLENDEQUATION_MIN
  • pc.BLENDEQUATION_MAX
  • Note that MIN and MAX modes require either EXT_blend_minmax or WebGL2 to work (check device.extBlendMinmax).
blendAlphaEquation Number A separate blend equation for the alpha channel. Accepts same values as blendEquation.
Source:

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:
Name Type Description
blendSrc Number The source blend function.
blendDst Number The destination blend function.
Source:

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:
Name Type Description
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.
Source:

setBlending(blending)

Enables or disables blending.
Parameters:
Name Type Description
blending Boolean True to enable blending and false to disable it.
Source:

(private) setBoneLimit(maxBones)

Specifies the maximum number of bones that the device can support on the current hardware. This function allows the default calculated value based on available vector uniforms to be overridden.
Parameters:
Name Type Description
maxBones Number The maximum number of bones supported by the host hardware.
Source:

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.
Parameters:
Name Type Description
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.
Source:
Example
// Just write alpha into the frame buffer
device.setColorWrite(false, false, false, true);

setCullMode(cullMode)

Controls how triangles are culled based on their face direction. The default cull mode is pc.CULLFACE_BACK.
Parameters:
Name Type Description
cullMode Number The cull mode to set. Can be:
  • pc.CULLFACE_NONE
  • pc.CULLFACE_BACK
  • pc.CULLFACE_FRONT
  • pc.CULLFACE_FRONTANDBACK
Source:

setDepthFunc(func)

Configures the depth test.
Parameters:
Name Type Description
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:
  • pc.FUNC_NEVER: don't draw
  • pc.FUNC_LESS: draw if new depth < depth buffer
  • pc.FUNC_EQUAL: draw if new depth == depth buffer
  • pc.FUNC_LESSEQUAL: draw if new depth <= depth buffer
  • pc.FUNC_GREATER: draw if new depth > depth buffer
  • pc.FUNC_NOTEQUAL: draw if new depth != depth buffer
  • pc.FUNC_GREATEREQUAL: draw if new depth >= depth buffer
  • pc.FUNC_ALWAYS: always draw
Source:

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.
Parameters:
Name Type Description
depthTest Boolean true to enable depth testing and false otherwise.
Source:
Example
device.setDepthTest(true);

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.
Parameters:
Name Type Description
writeDepth Boolean true to enable depth writing and false otherwise.
Source:
Example
device.setDepthWrite(true);

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:
Name Type Description
indexBuffer pc.IndexBuffer The index buffer to assign to the device.
Source:

(private) setProgramLibrary(programLib)

Assigns a program library to the specified device. By default, a graphics device is created with a program library that manages all of the programs that are used to render any graphical primitives. However, this function allows the user to replace the existing program library with a new one.
Parameters:
Name Type Description
programLib pc.ProgramLibrary The program library to assign to the device.
Source:

(private) setRaster(on)

Enables or disables rasterization. Useful with transform feedback, when you only need to process the data without drawing.
Parameters:
Name Type Description
on Boolean True to enable rasterization and false to disable it.
Source:

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.
Parameters:
Name Type Description
renderTarget pc.RenderTarget The render target to activate.
Source:
Example
// Set a render target to receive all rendering output
device.setRenderTarget(renderTarget);

// Set the back buffer to receive all rendering output
device.setRenderTarget(null);

setScissor(x, y, w, h)

Set the active scissor rectangle on the specified device.
Parameters:
Name Type Description
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.
Source:

setShader(shader) → {Boolean}

Sets the active shader to be used during subsequent draw calls.
Parameters:
Name Type Description
shader pc.Shader The shader to set to assign to the device.
Source:
Returns:
true if the shader was successfully set, false otherwise.
Type
Boolean

setStencilFunc(func, ref, mask)

Configures stencil test for both front and back faces.
Parameters:
Name Type Description
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:
  • pc.FUNC_NEVER: never pass
  • pc.FUNC_LESS: pass if (ref & mask) < (stencil & mask)
  • pc.FUNC_EQUAL: pass if (ref & mask) == (stencil & mask)
  • pc.FUNC_LESSEQUAL: pass if (ref & mask) <= (stencil & mask)
  • pc.FUNC_GREATER: pass if (ref & mask) > (stencil & mask)
  • pc.FUNC_NOTEQUAL: pass if (ref & mask) != (stencil & mask)
  • pc.FUNC_GREATEREQUAL: pass if (ref & mask) >= (stencil & mask)
  • pc.FUNC_ALWAYS: always pass
ref Number Reference value used in comparison.
mask Number Mask applied to stencil buffer value and reference value before comparison.
Source:

setStencilFuncBack(func, ref, mask)

Configures stencil test for back faces.
Parameters:
Name Type Description
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:
  • pc.FUNC_NEVER: never pass
  • pc.FUNC_LESS: pass if (ref & mask) < (stencil & mask)
  • pc.FUNC_EQUAL: pass if (ref & mask) == (stencil & mask)
  • pc.FUNC_LESSEQUAL: pass if (ref & mask) <= (stencil & mask)
  • pc.FUNC_GREATER: pass if (ref & mask) > (stencil & mask)
  • pc.FUNC_NOTEQUAL: pass if (ref & mask) != (stencil & mask)
  • pc.FUNC_GREATEREQUAL: pass if (ref & mask) >= (stencil & mask)
  • pc.FUNC_ALWAYS: always pass
ref Number Reference value used in comparison.
mask Number Mask applied to stencil buffer value and reference value before comparison.
Source:

setStencilFuncFront(func, ref, mask)

Configures stencil test for front faces.
Parameters:
Name Type Description
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:
  • pc.FUNC_NEVER: never pass
  • pc.FUNC_LESS: pass if (ref & mask) < (stencil & mask)
  • pc.FUNC_EQUAL: pass if (ref & mask) == (stencil & mask)
  • pc.FUNC_LESSEQUAL: pass if (ref & mask) <= (stencil & mask)
  • pc.FUNC_GREATER: pass if (ref & mask) > (stencil & mask)
  • pc.FUNC_NOTEQUAL: pass if (ref & mask) != (stencil & mask)
  • pc.FUNC_GREATEREQUAL: pass if (ref & mask) >= (stencil & mask)
  • pc.FUNC_ALWAYS: always pass
ref Number Reference value used in comparison.
mask Number Mask applied to stencil buffer value and reference value before comparison.
Source:

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:
Name Type Description
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:
  • pc.STENCILOP_KEEP: don't change the stencil buffer value
  • pc.STENCILOP_ZERO: set value to zero
  • pc.STENCILOP_REPLACE: replace value with the reference value (see pc.GraphicsDevice#setStencilFunc)
  • pc.STENCILOP_INCREMENT: increment the value
  • pc.STENCILOP_INCREMENTWRAP: increment the value, but wrap it to zero when it's larger than a maximum representable value
  • pc.STENCILOP_DECREMENT: decrement the value
  • pc.STENCILOP_DECREMENTWRAP: decrement the value, but wrap it to a maximum representable value, if the current value is 0
  • pc.STENCILOP_INVERT: invert the value bitwise
writeMask Number A bit mask applied to the reference value, when written.
Source:

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:
Name Type Description
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:
  • pc.STENCILOP_KEEP: don't change the stencil buffer value
  • pc.STENCILOP_ZERO: set value to zero
  • pc.STENCILOP_REPLACE: replace value with the reference value (see pc.GraphicsDevice#setStencilFunc)
  • pc.STENCILOP_INCREMENT: increment the value
  • pc.STENCILOP_INCREMENTWRAP: increment the value, but wrap it to zero when it's larger than a maximum representable value
  • pc.STENCILOP_DECREMENT: decrement the value
  • pc.STENCILOP_DECREMENTWRAP: decrement the value, but wrap it to a maximum representable value, if the current value is 0
  • pc.STENCILOP_INVERT: invert the value bitwise
writeMask Number A bit mask applied to the reference value, when written.
Source:

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:
Name Type Description
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:
  • pc.STENCILOP_KEEP: don't change the stencil buffer value
  • pc.STENCILOP_ZERO: set value to zero
  • pc.STENCILOP_REPLACE: replace value with the reference value (see pc.GraphicsDevice#setStencilFunc)
  • pc.STENCILOP_INCREMENT: increment the value
  • pc.STENCILOP_INCREMENTWRAP: increment the value, but wrap it to zero when it's larger than a maximum representable value
  • pc.STENCILOP_DECREMENT: decrement the value
  • pc.STENCILOP_DECREMENTWRAP: decrement the value, but wrap it to a maximum representable value, if the current value is 0
  • pc.STENCILOP_INVERT: invert the value bitwise
writeMask Number A bit mask applied to the reference value, when written.
Source:

setStencilTest(enable)

Enables or disables stencil test.
Parameters:
Name Type Description
enable Boolean True to enable stencil test and false to disable it.
Source:

(private) setTransformFeedbackBuffer(tf)

Sets the output vertex buffer. It will be written to by a shader with transform feedback varyings.
Parameters:
Name Type Description
tf pc.VertexBuffer The output vertex buffer
Source:

setVertexBuffer(vertexBuffer, stream, vbOffsetopt)

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:
Name Type Attributes Default Description
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 <optional>
0 The byte offset into the vertex buffer data. Defaults to 0.
Source:

setViewport(x, y, w, h)

Set the active rectangle for rendering on the specified device.
Parameters:
Name Type Description
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.
Source:

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.
Source:

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.
Source:

Events

resizecanvas

The 'resizecanvas' event is fired when the canvas is resized
Parameters:
Name Type Description
width Number The new width of the canvas in pixels
height Number The new height of the canvas in pixels
Source: