Canvas-app NPM

canvas-app

deprecation warning

This module is bloated and a little too magical. Instead, some of the following are recommended:

The Easy Bake Oven of canvas rendering. Sets up a canvas for 2D or WebGL context, handling a few things like:

CSS scaling for retina displays with a devicePixelRatio of > 1.0
Boilerplate to safely grab 2D/webgl context
resizes the canvas to full-screen on resize & device orientation change (by default)
basic delta time calculation
start/stop handling
current FPS

Simplest use might look like this:

//a simple render loop
function render(context, width, height, dt) {
	context.clearRect(0, 0, width, height);
	context.fillRect(20, 50, 25, 25);

	context.fillText("FPS: "+this.fps, 20, 20);
}

//defaults to a full-screen canvas
var app = require('canvas-app')(render);

//append to DOM
document.body.appendChild( app.canvas );

//start render loop
app.start();

For simple use like the above, you may want to use canvas-testbed, which also handles DOM ready event, better body styling for full-screen canvas apps, and requestAnimationFrame polyfills.

Usage

Another example:

var app = require('canvas-app')(renderHandler, {
	width: 256,
	height: 256,
	once: true, //only render once
	retina: false, //don't try to scale for retina displays
});

//renders a single frame
app.renderOnce();

The constructor can take two forms:

canvasApp(renderHandler, options);
canvasApp(options);

options

width force a width of the canvas in pixels. If passed, resize events will be ignored
height force a height of the canvas in pixels. If passed, resize events will be ignored
ignoreResize if true, resize events will be ignored
retina default true, whether to scale the canvas style and context for device pixel ratio
once only renders a single frame, and then again on resize
canvas the canvas element to use, otherwise creates a new element
context the context to use, can be either 'webgl' or '2d', defaults to 2d
contextAttributes passed to the getContext call
onResize a function called on resize with arguments width, height
onRender a function called on render with arguments context, width, height, deltaTime (can instead be passed as first argument to the constructor)
resizeDebounce if we are using built-in resize handlers, they will be debounced by 50 ms unless you specify a value explicitly here

If context is a WebGLRenderingContext or CanvasRenderingContext, it will be used along with its associatedcanvas. This is useful to avoid consecutivegetContext('webgl')` calls which can interfere with WebGL inspectors.

methods

renderOnce() renders a single frame
start() starts the render loop
stop() stops the current render loop
resize(width, height) resizes the canvas to the given size. You should probably use ignoreResize if you want to manually handle resize events.

properties

canvas the canvas element
context the 2D or WebGL rendering context
width, height the current size, not scaled by devicePixelRatio
running whether the loop is currently running
deviceWidth, deviceHeight the actual device height (i.e. size * devicePixelRatio). This is needed for glViewport, glScissor, etc.

context scaling / viewport

For 2D contexts, scale() is called before rendering based on the deviePixelRatio. For WebGL contexts, gl.viewport() is called before rendering with the device size.

If retina is false, the device size will be assumed to be the same as the canvas size.