API Reference

Class List

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

heightHeight of the back buffer in pixels.[read only]
maxAnisotropyThe maximum supported texture anisotropy setting.[read only]
maxCubeMapSizeThe maximum supported dimension of a cube map.[read only]
maxTextureSizeThe maximum supported dimension of a texture.[read only]
precisionThe highest shader precision supported by this graphics device.[read only]
widthWidth of the back buffer in pixels.[read only]

Methods

clearClears the frame buffer of the currently set render target.
clearShaderCacheFrees memory from all shaders ever allocated with this device
drawSubmits a graphical primitive to the hardware for immediate rendering.
getBlendingQueries whether blending is enabled.
getDepthTestQueries whether depth testing is enabled.
getDepthWriteQueries whether writes to the depth buffer are enabled.
getRenderTargetQueries the currently set render target on the device.
resizeCanvasSets the width and height of the canvas, then fires the 'resizecanvas' event.
setBlendEquationConfigures the blending equation.
setBlendFunctionConfigures blending operations.
setBlendingEnables or disables blending.
setColorWriteEnables or disables writes to the color buffer.
setCullModeControls how triangles are culled based on their face direction.
setDepthTestEnables or disables depth testing of fragments.
setDepthWriteEnables or disables writes to the depth buffer.
setIndexBufferSets the current index buffer on the graphics device.
setRenderTargetSets the specified render target on the device.
setScissorSet the active scissor rectangle on the specified device.
setShaderSets the active shader to be used during subsequent draw calls.
setStencilFuncConfigures stencil test for both front and back faces.
setStencilFuncBackSame as pc.
setStencilFuncFrontSame as pc.
setStencilOperationConfigures how stencil buffer values should be modified based on the result of depth/stencil tests.
setStencilOperationBackSame as pc.
setStencilOperationFrontSame as pc.
setStencilTestEnables or disables stencil test.
setVertexBufferSets the current vertex buffer for a specific stream index on the graphics device.
setViewportSet the active rectangle for rendering on the specified device.
updateBeginMarks the beginning of a block of rendering.
updateEndMarks the end of a block of rendering.

Events

resizecanvasThe 'resizecanvas' event is fired when the canvas is resized

Details

Constructor

GraphicsDevice(canvas, [options])

Creates a new graphics device.

Parameters

canvasObjectThe canvas to which the graphics device is tied.
optionsObjectOptions passed when creating the WebGL context. More info here https://developer.mozilla.org/en-US/docs/Web/API/HTMLCanvasElement/getContext

Properties

Numberheight

Height of the back buffer in pixels.[read only]

NumbermaxAnisotropy

The maximum supported texture anisotropy setting.[read only]

NumbermaxCubeMapSize

The maximum supported dimension of a cube map.[read only]

NumbermaxTextureSize

The maximum supported dimension of a texture.[read only]

Stringprecision

The highest shader precision supported by this graphics device. Can be 'hiphp', 'mediump' or 'lowp'.[read only]

Numberwidth

Width of the back buffer in pixels.[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

optionsObjectOptional options object that controls the behavior of the clear operation defined as follows:
options.colorNumber[]The color to clear the color buffer to in the range 0.0 to 1.0 for each component.
options.depthNumberThe depth value to clear the depth buffer to in the range 0.0 to 1.0.
options.flagsNumberThe 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

clearShaderCache()

Frees memory from all shaders ever allocated with this device

draw(primitive)

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

primitiveObjectPrimitive object describing how to submit current vertex/index buffers defined as follows:
primitive.typeNumberThe 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
primitive.baseNumberThe offset of the first index or vertex to dispatch in the draw call.
primitive.countNumberThe number of indices or vertices to dispatch in the draw call.
primitive.indexedBooleanTrue to interpret the primitive as indexed, thereby using the currently set index buffer and false otherwise.

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

Sets the width and height of the canvas, then fires the 'resizecanvas' event.

setBlendEquation(blendEquation)

Configures the blending equation. The default blend equation is pc.BLENDEQUATION_ADD.

Parameters

blendEquationNumberThe blend equation. Can be:
  • pc.BLENDEQUATION_ADD
  • pc.BLENDEQUATION_SUBTRACT
  • pc.BLENDEQUATION_REVERSE_SUBTRACT

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

blendSrcNumberThe source blend function.
blendDstNumberThe destination blend function.

setBlending(blending)

Enables or disables blending.

Parameters

blendingBooleanTrue 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

writeRedBooleantrue to enable writing of the red channel and false otherwise.
writeGreenBooleantrue to enable writing of the green channel and false otherwise.
writeBlueBooleantrue to enable writing of the blue channel and false otherwise.
writeAlphaBooleantrue 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

cullModeNumberThe cull mode to set. Can be:
  • pc.CULLFACE_NONE
  • pc.CULLFACE_BACK
  • pc.CULLFACE_FRONT
  • pc.CULLFACE_FRONTANDBACK

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

depthTestBooleantrue 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

writeDepthBooleantrue 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

indexBufferpc.IndexBufferThe 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

renderTargetpc.RenderTargetThe render target to activate.

setScissor(x, y, w, h)

Set the active scissor rectangle on the specified device.

Parameters

xNumberThe pixel space x-coordinate of the bottom left corner of the scissor rectangle.
yNumberThe pixel space y-coordinate of the bottom left corner of the scissor rectangle.
wNumberThe width of the scissor rectangle in pixels.
hNumberThe height of the scissor rectangle in pixels.

setShader(shader)

Sets the active shader to be used during subsequent draw calls.

Parameters

shaderpc.ShaderThe shader to set to assign to the device.

setStencilFunc(func, ref, mask)

Configures stencil test for both front and back faces.

Parameters

funcNumberA 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
refNumberReference value used in comparison.
maskNumberMask applied to stencil buffer value and reference value before comparison.

setStencilFuncBack()

Same as pc.GraphicsDevice#setStencilFunc, but only for back faces.

setStencilFuncFront()

Same as pc.GraphicsDevice#setStencilFunc, but only for front faces.

setStencilOperation(fail, zfail, zpass)

Configures how stencil buffer values should be modified based on the result of depth/stencil tests. Works for both front and back faces.

Parameters

failNumberAction to take if stencil test is failed
zfailNumberAction to take if depth test is failed
zpassNumberAction 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

setStencilOperationBack()

Same as pc.GraphicsDevice#setStencilOperation, but only for back faces.

setStencilOperationFront()

Same as pc.GraphicsDevice#setStencilOperation, but only for front faces.

setStencilTest(enable)

Enables or disables stencil test.

Parameters

enableBooleanTrue to enable stencil test and false to disable it.

setVertexBuffer(vertexBuffer, stream)

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

vertexBufferpc.VertexBufferThe vertex buffer to assign to the device.
streamNumberThe stream index for the vertex buffer, indexed from 0 upwards.

setViewport(x, y, w, h)

Set the active rectangle for rendering on the specified device.

Parameters

xNumberThe pixel space x-coordinate of the bottom left corner of the viewport.
yNumberThe pixel space y-coordinate of the bottom left corner of the viewport.
wNumberThe width of the viewport in pixels.
hNumberThe 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.

Events

resizecanvas

The 'resizecanvas' event is fired when the canvas is resized

Parameters

widthNumberThe new width of the canvas in pixels
heightNumberThe new height of the canvas in pixels