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

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

canvas	HTMLCanvasElement	The canvas to which the graphics device will render.
options	Object	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]

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]

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

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: pc.CLEARFLAG_COLOR pc.CLEARFLAG_DEPTH pc.CLEARFLAG_STENCIL

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: pc.PRIMITIVE_POINTS pc.PRIMITIVE_LINES pc.PRIMITIVE_LINELOOP pc.PRIMITIVE_LINESTRIP pc.PRIMITIVE_TRIANGLES pc.PRIMITIVE_TRISTRIP pc.PRIMITIVE_TRIFAN
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:

pc.BLENDEQUATION_ADD
pc.BLENDEQUATION_SUBTRACT
pc.BLENDEQUATION_REVERSE_SUBTRACT
pc.BLENDEQUATION_MIN
pc.BLENDEQUATION_MAX

setBlendEquationSeparate(blendEquation, blendAlphaEquation) 

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

Parameters

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.

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:

pc.CULLFACE_NONE
pc.CULLFACE_BACK
pc.CULLFACE_FRONT
pc.CULLFACE_FRONTANDBACK

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:

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

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

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

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

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

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

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

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.

Events

resizecanvas 

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

Parameters

width	Number	The new width of the canvas in pixels
height	Number	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

name	Object	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

name

String

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

name	String	Name of the event to unbind
callback	pc.callbacks.HandleEvent	Function to be unbound.
scope	Object	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

name	String	Name of the event to bind the callback to
callback	pc.callbacks.HandleEvent	Function that is called when event is fired. Note the callback is limited to 8 arguments.
scope	Object	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

name	String	Name of the event to bind the callback to
callback	pc.callbacks.HandleEvent	Function that is called when event is fired. Note the callback is limited to 8 arguments.
scope	Object	Object to use as 'this' when the event is fired, defaults to current this

Returns

pc.EventHandler Self for chaining.