API Reference

Class List

pc.GraphicsDevice

Extends: pc.EventHandler

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

canvas

The canvas DOM element that provides the underlying WebGL context used by the graphics device.

fullscreen

Fullscreen mode.

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]

maxPixelRatio

Maximum pixel ratio.

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]

scope

The scope namespace for shader attributes and variables.

supportsInstancing

True if hardware instancing is supported.[read only]

textureFloatHighPrecision

Check if high precision floating-point textures are supported.[read only]

textureFloatRenderable

Determines if 32-bit floating-point textures can be used as frame buffer.

textureHalfFloatRenderable

Determines if 16-bit floating-point textures can be used as frame buffer.

textureHalfFloatUpdatable

Check if texture with half float format can be updated with data.[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.

copyRenderTarget

Copies source render target into destination render target.

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.

Inherited

Methods

fire

Fire an event, all additional arguments are passed on to the event listener.

hasEvent

Test if there are any handlers bound to an event name.

off

Detach an event handler from an event.

on

Attach an event handler to an event.

once

Attach an event handler to an event.

Details

Constructor

GraphicsDevice(canvas, [options])

Creates a new graphics device.

Parameters

canvasHTMLCanvasElement

The canvas to which the graphics device will render.

optionsobject

Options passed when creating the WebGL context. More info here.

Properties

HTMLCanvasElementcanvas

The canvas DOM element that provides the underlying WebGL context used by the graphics device.

booleanfullscreen

Fullscreen mode.

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]

numbermaxPixelRatio

Maximum pixel ratio.

numbermaxTextureSize

The maximum supported dimension of a texture.

[read only]

numbermaxVolumeSize

The maximum supported dimension of a 3D texture (any axis).

[read only]

stringprecision

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

[read only]

pc.ScopeSpacescope

The scope namespace for shader attributes and variables. [read only].

booleansupportsInstancing

True if hardware instancing is supported.

[read only]

numbertextureFloatHighPrecision

Check if high precision floating-point textures are supported.

[read only]

booleantextureFloatRenderable

Determines if 32-bit floating-point textures can be used as frame buffer. [read only].

booleantextureHalfFloatRenderable

Determines if 16-bit floating-point textures can be used as frame buffer. [read only].

numbertextureHalfFloatUpdatable

Check if texture with half float format can be updated with data.

[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

optionsobject

Optional 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.depthnumber

The depth value to clear the depth buffer to in the range 0.0 to 1.0.

options.flagsnumber

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

clearShaderCache()

Frees memory from all shaders ever allocated with this device.

copyRenderTarget(source, [dest], [color], [depth])

Copies source render target into destination render target. Mostly used by post-effects.

Parameters

sourcepc.RenderTarget

The source render target.

destpc.RenderTarget

The destination render target. Defaults to frame buffer.

colorboolean

If true will copy the color buffer. Defaults to false.

depthboolean

If true will copy the depth buffer. Defaults to false.

Returns

boolean

True if the copy was successful, false otherwise.

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

primitiveobject

Primitive object describing how to submit current vertex/index buffers defined as follows:

primitive.typenumber

The type of primitive to render. Can be:

primitive.basenumber

The offset of the first index or vertex to dispatch in the draw call.

primitive.countnumber

The number of indices or vertices to dispatch in the draw call.

primitive.indexedboolean

True to interpret the primitive as indexed, thereby using the currently set index buffer and false otherwise.

numInstancesnumber

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

widthnumber

The new width of the canvas.

heightnumber

The new height of the canvas.

setBlendEquation(blendEquation)

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

Parameters

blendEquationnumber

The blend equation. Can be:

Note that MIN and MAX modes require either EXT_blend_minmax or WebGL2 to work (check device.extBlendMinmax).

setBlendEquationSeparate(blendEquation, blendAlphaEquation)

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

Parameters

blendEquationnumber

The blend equation. Can be:

Note that MIN and MAX modes require either EXT_blend_minmax or WebGL2 to work (check device.extBlendMinmax).

blendAlphaEquationnumber

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:

Parameters

blendSrcnumber

The source blend function.

blendDstnumber

The destination blend function.

setBlendFunctionSeparate(blendSrc, blendDst, blendSrcAlpha, blendDstAlpha)

Configures blending operations. Both source and destination blend modes can take the following values:

Parameters

blendSrcnumber

The source blend function.

blendDstnumber

The destination blend function.

blendSrcAlphanumber

The separate source blend function for the alpha channel.

blendDstAlphanumber

The separate destination blend function for the alpha channel.

setBlending(blending)

Enables or disables blending.

Parameters

blendingboolean

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

writeRedboolean

True to enable writing of the red channel and false otherwise.

writeGreenboolean

True to enable writing of the green channel and false otherwise.

writeBlueboolean

True to enable writing of the blue channel and false otherwise.

writeAlphaboolean

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

cullModenumber

The cull mode to set. Can be:

setDepthFunc(func)

Configures the depth test.

Parameters

funcnumber

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

depthTestboolean

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

writeDepthboolean

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

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

renderTargetpc.RenderTarget

The render target to activate.

setScissor(x, y, w, h)

Set the active scissor rectangle on the specified device.

Parameters

xnumber

The pixel space x-coordinate of the bottom left corner of the scissor rectangle.

ynumber

The pixel space y-coordinate of the bottom left corner of the scissor rectangle.

wnumber

The width of the scissor rectangle in pixels.

hnumber

The height of the scissor rectangle in pixels.

setShader(shader)

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

Parameters

shaderpc.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

funcnumber

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:

refnumber

Reference value used in comparison.

masknumber

Mask applied to stencil buffer value and reference value before comparison.

setStencilFuncBack(func, ref, mask)

Configures stencil test for back faces.

Parameters

funcnumber

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:

refnumber

Reference value used in comparison.

masknumber

Mask applied to stencil buffer value and reference value before comparison.

setStencilFuncFront(func, ref, mask)

Configures stencil test for front faces.

Parameters

funcnumber

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:

refnumber

Reference value used in comparison.

masknumber

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

failnumber

Action to take if stencil test is failed.

zfailnumber

Action to take if depth test is failed.

zpassnumber

Action to take if both depth and stencil test are passed All arguments can be:

writeMasknumber

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

failnumber

Action to take if stencil test is failed.

zfailnumber

Action to take if depth test is failed.

zpassnumber

Action to take if both depth and stencil test are passed All arguments can be:

writeMasknumber

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

failnumber

Action to take if stencil test is failed.

zfailnumber

Action to take if depth test is failed.

zpassnumber

Action to take if both depth and stencil test are passed All arguments can be:

writeMasknumber

A bit mask applied to the reference value, when written.

setStencilTest(enable)

Enables or disables stencil test.

Parameters

enableboolean

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

vertexBufferpc.VertexBuffer

The vertex buffer to assign to the device.

streamnumber

The stream index for the vertex buffer, indexed from 0 upwards.

vbOffsetnumber

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

xnumber

The pixel space x-coordinate of the bottom left corner of the viewport.

ynumber

The pixel space y-coordinate of the bottom left corner of the viewport.

wnumber

The width of the viewport in pixels.

hnumber

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.

Events

resizecanvas

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

Parameters

widthnumber

The new width of the canvas in pixels.

heightnumber

The new height of the canvas in pixels.

Inherited

Methods

fire(name, [arg1], [arg2], [arg3], [arg4], [arg5], [arg6], [arg7], [arg8])

Fire an event, all additional arguments are passed on to the event listener.

obj.fire('test', 'This is the message');

Parameters

nameobject

Name of event to fire.

arg1*

First argument that is passed to the event handler.

arg2*

Second argument that is passed to the event handler.

arg3*

Third argument that is passed to the event handler.

arg4*

Fourth argument that is passed to the event handler.

arg5*

Fifth argument that is passed to the event handler.

arg6*

Sixth argument that is passed to the event handler.

arg7*

Seventh argument that is passed to the event handler.

arg8*

Eighth argument that is passed to the event handler.

Returns

pc.EventHandler

Self for chaining.

hasEvent(name)

Test if there are any handlers bound to an event name.

obj.on('test', function () { }); // bind an event to 'test'
obj.hasEvent('test'); // returns true
obj.hasEvent('hello'); // returns false

Parameters

namestring

The name of the event to test.

Returns

boolean

True if the object has handlers bound to the specified event name.

off([name], [callback], [scope])

Detach an event handler from an event. If callback is not provided then all callbacks are unbound from the event, if scope is not provided then all events with the callback will be unbound.

var handler = function () {
};
obj.on('test', handler);

obj.off(); // Removes all events
obj.off('test'); // Removes all events called 'test'
obj.off('test', handler); // Removes all handler functions, called 'test'
obj.off('test', handler, this); // Removes all hander functions, called 'test' with scope this

Parameters

namestring

Name of the event to unbind.

callbackpc.callbacks.HandleEvent

Function to be unbound.

scopeobject

Scope that was used as the this when the event is fired.

Returns

pc.EventHandler

Self for chaining.

on(name, callback, [scope])

Attach an event handler to an event.

obj.on('test', function (a, b) {
    console.log(a + b);
});
obj.fire('test', 1, 2); // prints 3 to the console

Parameters

namestring

Name of the event to bind the callback to.

callbackpc.callbacks.HandleEvent

Function that is called when event is fired. Note the callback is limited to 8 arguments.

scopeobject

Object to use as 'this' when the event is fired, defaults to current this.

Returns

pc.EventHandler

Self for chaining.

once(name, callback, [scope])

Attach an event handler to an event. This handler will be removed after being fired once.

obj.once('test', function (a, b) {
    console.log(a + b);
});
obj.fire('test', 1, 2); // prints 3 to the console
obj.fire('test', 1, 2); // not going to get handled

Parameters

namestring

Name of the event to bind the callback to.

callbackpc.callbacks.HandleEvent

Function that is called when event is fired. Note the callback is limited to 8 arguments.

scopeobject

Object to use as 'this' when the event is fired, defaults to current this.

Returns

pc.EventHandler

Self for chaining.