# canvas-app

> sets up a retina-scaled canvas with render loop

Latest version **2.4.1** (published 2015-05-09) · MIT license · 0 weekly downloads

## Install

```sh
npm install canvas-app
pnpm add canvas-app
yarn add canvas-app
bun add canvas-app
```

## Health

**Score 15/100 (F)** — status: abandoned.

Positive: no vulnerabilities.

Warnings: low downloads; no types; no esm support.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 2.4.1 |
| Published | 2015-05-09 |
| First published | 2014-07-06 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | none |
| Module format | CommonJS |
| Dependencies | 4 |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 9 |
| Author | Matt DesLauriers |
| Maintainers | mattdesl |
| Keywords | canvas, 2d, webgl, gl, context, context2d, render, renderer, loop, frame, game, shell, animation |

## Links

- npm: https://www.npmjs.com/package/canvas-app
- Repository: https://github.com/mattdesl/canvas-app
- Issues: https://github.com/mattdesl/canvas-app/issues
- npm.io page: https://npm.io/package/canvas-app

## Dependencies (4)

- [debounce](https://npm.io/package/debounce.md) ^1.0.0
- [webgl-context](https://npm.io/package/webgl-context.md) ^1.2.1
- [is-webgl-context](https://npm.io/package/is-webgl-context.md) ^1.0.0
- [add-event-listener](https://npm.io/package/add-event-listener.md) 0.0.1

## Alternatives

- [@luma.gl/experimental](https://npm.io/package/@luma.gl/experimental.md) — 77.1K weekly downloads
- [persona-harness](https://npm.io/package/persona-harness.md) — 4.7K weekly downloads
- [@tsparticles/effect-bubble](https://npm.io/package/@tsparticles/effect-bubble.md) — 4.6K weekly downloads
- [f3d](https://npm.io/package/f3d.md) — 730 weekly downloads
- [spark-html-motion](https://npm.io/package/spark-html-motion.md) — 298 weekly downloads

## Recent versions

- 2.4.1 (latest) — 2015-05-09
- 2.4.0 — 2014-11-15
- 2.3.0 — 2014-10-14
- 2.2.0 — 2014-10-05
- 2.1.1 — 2014-10-01
- 2.1.0 — 2014-10-01
- 2.0.0 — 2014-09-27
- 1.1.0 — 2014-07-09
- 1.0.0 — 2014-07-06

## README

# canvas-app

[![stable](http://badges.github.io/stability-badges/dist/stable.svg)](http://github.com/badges/stability-badges)

#### deprecation warning

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

- [canvas-fit-loop](https://www.npmjs.com/package/canvas-fit-loop)
- [2d-context](https://www.npmjs.com/package/2d-context)
- [webgl-context](https://www.npmjs.com/package/webgl-context)

---

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:

```js
//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](https://github.com/mattdesl/canvas-testbed), which also handles DOM ready event, better body styling for full-screen canvas apps, and requestAnimationFrame polyfills.

## Usage

[![NPM](https://nodei.co/npm/canvas-app.png)](https://nodei.co/npm/canvas-app/)

Another example:

```js
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:

```js
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 associated `canvas`. This is useful to avoid consecutive `getContext('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. 

## License

MIT, see [LICENSE.md](http://github.com/mattdesl/canvas-app/blob/master/LICENSE.md) for details.

---
_Source: https://npm.io/package/canvas-app · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._