# canvas-loop-engine

> A basic loop engine for canvas animation

Latest version **1.1.2** (published 2020-06-18) · MIT license · 0 weekly downloads

## Install

```sh
npm install canvas-loop-engine
pnpm add canvas-loop-engine
yarn add canvas-loop-engine
bun add canvas-loop-engine
```

## 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 | 1.1.2 |
| Published | 2020-06-18 |
| First published | 2019-12-02 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | none |
| Module format | CommonJS |
| Dependencies | 1 |
| Unpacked size | 43.4 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 1 |
| Author | Julien Amblard |
| Maintainers | oory |
| Keywords | canvas, timer, loop, animation, engine, requestAnimationFrame, graphic |

## Links

- npm: https://www.npmjs.com/package/canvas-loop-engine
- Repository: https://github.com/sl-julienamblard/canvas-loop-engine
- Homepage: https://github.com/sl-julienamblard/canvas-loop-engine#readme
- Issues: https://github.com/sl-julienamblard/canvas-loop-engine/issues
- npm.io page: https://npm.io/package/canvas-loop-engine

## Dependencies (1)

- [clone-deep](https://npm.io/package/clone-deep.md) ^4.0.1

## Alternatives

- [exif-parser](https://npm.io/package/exif-parser.md) — 3.8M weekly downloads
- [vite-plugin-compression](https://npm.io/package/vite-plugin-compression.md) — 569.5K weekly downloads
- [pica](https://npm.io/package/pica.md) — 442.4K weekly downloads
- [@reportportal/client-javascript](https://npm.io/package/@reportportal/client-javascript.md) — 408.8K weekly downloads
- [@tldraw/state](https://npm.io/package/@tldraw/state.md) — 316.0K weekly downloads

## Recent versions

- 1.1.2 (latest) — 2020-06-18
- 1.1.1 — 2019-12-13
- 1.1.0 — 2019-12-13
- 1.0.0-alpha.1 — 2019-12-13
- 0.1.1 — 2019-12-02
- 0.1.0 — 2019-12-02
- 0.1.0-alpha.3 — 2019-12-02
- 0.1.0-alpha.2 — 2019-12-02
- 0.1.0-alpha.1 — 2019-12-02
- 0.1.0-alpha.0 — 2019-12-02

## README

# canvas-loop-engine

[![CircleCI Status](https://circleci.com/gh/sl-julienamblard/canvas-loop-engine.svg?style=shield&circle-token=:circle-token)](https://circleci.com/gh/sl-julienamblard/canvas-loop-engine)
[![codecov](https://codecov.io/gh/sl-julienamblard/canvas-loop-engine/branch/master/graph/badge.svg)](https://codecov.io/gh/sl-julienamblard/canvas-loop-engine)
[![npm](https://img.shields.io/npm/dt/canvas-loop-engine.svg?style=flat-square)](https://www.npmjs.com/package/canvas-loop-engine)
[![npm](https://img.shields.io/npm/v/canvas-loop-engine.svg?style=flat-square)](https://www.npmjs.com/package/canvas-loop-engine)
[![npm](https://img.shields.io/npm/l/canvas-loop-engine.svg?style=flat-square)](https://github.com/sl-julienamblard/canvas-loop-engine/blob/master/LICENSE)
  
> A basic loop engine for canvas animation

## [Live example](https://codepen.io/Capse/pen/gObOKGo)

- [Install](#install)
- [Importing](#importing)

- [Options](#options)
  - [$canvas](#canvas)
  - [contextType](#contextType)
  - [contextAttributes](#contextAttributes)
  - [autoStart](#autoStart)
  - [clearOnUpdate](#clearOnUpdate)
  - [data](#data)
  - [onInit](#onInit)
  - [onStart](#onStart)
  - [onStop](#onStop)
  - [onUpdate](#onUpdate)
  - [onDraw](#onDraw)
- [Methods](#methods)
  - [start()](#start)
  - [stop()](#stop)
  - [toggle()](#toggle)
  - [update()](#update)
  - [draw()](#draw)
  - [isRunning](#isRunning)

## Install <a id="install"></a>

`npm i canvas-loop-engine --save`  
or  
`yarn add canvas-loop-engine`  

---

### Importing <a id="importing"></a>

```js
import Engine from "canvas-loop-engine"

const MyLoop = new Engine({ ...options })
MyLoop.start()
```

---

## Options <a id="options"></a>  

### $canvas <a id="canvas"></a>  

| Type | Default | required | Description |
|:----|:----|:----|:----|
| `HTMLCanvasElement` | `null` | `true` | The canvas html element you want to draw on. |

```js
import Engine from "canvas-loop-engine"

const MyLoop = new Engine({
  $canvas: document.querySelector("canvas")
})
```

### contextType <a id="contextType"></a>  

| Type | Default | required | Description |
|:----|:----|:----|:----|
| `string` | `"2d"` | `false` | The canvas context type giving in the getContext. See [getContext documentation](https://developer.mozilla.org/en-US/docs/Web/API/HTMLCanvasElement/getContext)  |

```js
import Engine from "canvas-loop-engine"

const MyLoop = new Engine({
  $canvas: document.querySelector("canvas"),
  contextType: "webgl"
})
```

---
### contextAttributes <a id="contextAttributes"></a>  

| Type | Default | required | Description |
|:----|:----|:----|:----|
| `object` | `null` | `false` | The canvas context attributes giving in the getContext. See [getContext documentation](https://developer.mozilla.org/en-US/docs/Web/API/HTMLCanvasElement/getContext)  |

```js
import Engine from "canvas-loop-engine"

const MyLoop = new Engine({
  $canvas: document.querySelector("canvas"),
  contextType: "webgl",
  contextAttribute: {
    antialias: false,
    depth: false
  }
})
```

---

### autoStart <a id="autoStart"></a>  
| Type | Default | required | Description |
|:----|:----|:----|:----|
| `boolean` | `true` | `false` | Define if the loop engine should start automaticaly. |

```js
import Engine from "canvas-loop-engine"

const MyLoop = new Engine({
  $canvas: document.querySelector("canvas"),
  autoStart: false //default true
})
```

---

### clearOnUpdate <a id="clearOnUpdate"></a>  

| Type | Default | required | Description |
|:----|:----|:----|:----|
| `boolean` | `true` | `false` | Automaticaly clear the canvas before each draw |

> Will trigger just before the onDraw functions

```js
import Engine from "canvas-loop-engine"

const MyLoop = new Engine({
  $canvas: document.querySelector("canvas"),
  autoStart: false //default true
})
```

---

#### data <a id="data"></a>  
| Type | Default | required | Description |
|:----|:----|:----|:----|
| `any` | `{}` | `false` | You can give a data object. it will be return as argument in every props function (onInit, onUpdate, onDraw, onStar, onStop) for a future usage. |

> Usually, you can use it to stock your drawing settings (*particles etc...*)  

> ⚠️ The data object will be deeply clone. It will break every references

```js
import Engine from "canvas-loop-engine"

const MyLoop = new Engine({
  $canvas: document.querySelector("canvas"),
  data: [{
    //...particle data
  }]
})
```

---

### onInit <a id="onInit"></a>  

| Type | Default | required | Description |
|:----|:----|:----|:----|
| `function` \| `array of function` | `null` | `false` | function or array of function that will trigger at the loop init |

| name | type | Description |
|:----|:----|:----|
| $canvas | `HTMLCanvasElement` | the html convas element |
| ctx | `HTMLElement` | the html convas element |
| data | `any` | the data object you send at the init |

```js
import Engine from "canvas-loop-engine"

const MyLoop = new Engine({
  $canvas: document.querySelector("canvas"),
  onInit: function ({ $canvas, ctx, data }) {
    //do things
  }
})
```

***or***  

```js
import Engine from "canvas-loop-engine"

const foo = function ({ $canvas, ctx, data }) {
  //do things
}
const bar = function ({ $canvas, ctx, data }) {
  //do things
}

const MyLoop = new Engine({
  $canvas: document.querySelector("canvas"),
  onInit: [foo, bar]
})
```

---

### onStart <a id="onStart"></a>  

| Type | Default | required | Description |
|:----|:----|:----|:----|
| `function` \| `array of function` | `null` | `false` | Function or array of function that will trigger when you start the loop |

| name | type | Description |
|:----|:----|:----|
| $canvas | `HTMLCanvasElement` | the html convas element |
| ctx | `HTMLElement` | the html convas element |
| data | `any` | the data object you send at the init |

```js
import Engine from "canvas-loop-engine"

const MyLoop = new Engine({
  $canvas: document.querySelector("canvas"),
  onStart: function ({ $canvas, ctx, data }) {
    //do things
  }
})
```

***or***  

```js
import Engine from "canvas-loop-engine"

const foo = function ({ $canvas, ctx, data }) {
  //do things
}
const bar = function ({ $canvas, ctx, data }) {
  //do things
}

const MyLoop = new Engine({
  $canvas: document.querySelector("canvas"),
  onStart: [foo, bar]
})
```

---

### onStop <a id="onStop"></a>  

| Type | Default | required | Description |
|:----|:----|:----|:----|
| `function` \| `array of function` | `null` | `false` | Function or array of function that will trigger when you stop the loop |

| name | type | Description |
|:----|:----|:----|
| $canvas | `HTMLCanvasElement` | the html convas element |
| ctx | `HTMLElement` | the html convas element |
| data | `any` | the data object you send at the init |

```js
import Engine from "canvas-loop-engine"

const MyLoop = new Engine({
  $canvas: document.querySelector("canvas"),
  onStop: function ({ $canvas, ctx, data }) {
    //do things
  }
})
```

***or***  

```js
import Engine from "canvas-loop-engine"

const foo = function ({ $canvas, ctx, data }) {
  //do things
}
const bar = function ({ $canvas, ctx, data }) {
  //do things
}

const MyLoop = new Engine({
  $canvas: document.querySelector("canvas"),
  onStop: [foo, bar]
})
```

---

### onUpdate <a id="onUpdate"></a>  

| Type | Default | required | Description |
|:----|:----|:----|:----|
| `function` \| `array of function` | `null` | `false` | Function or array of function that will trigger on each loop update |

| name | type | Description |
|:----|:----|:----|
| $canvas | `HTMLCanvasElement` | the html convas element |
| ctx | `HTMLElement` | the html convas element |
| data | `any` | the data object you send at the init |

```js
import Engine from "canvas-loop-engine"

const MyLoop = new Engine({
  $canvas: document.querySelector("canvas"),
  onUpdate: function ({ $canvas, ctx, data }) {
    //do things
  }
})
```

***or***  

```js
import Engine from "canvas-loop-engine"

const foo = function ({ $canvas, ctx, data }) {
  //do things
}
const bar = function ({ $canvas, ctx, data }) {
  //do things
}

const MyLoop = new Engine({
  $canvas: document.querySelector("canvas"),
  onUpdate: [foo, bar]
})
```

---

### onDraw <a id="onDraw"></a>  

| Type | Default | required | Description |
|:----|:----|:----|:----|
| `function` \| `array of function` | `null` | `false` | Function or array of function that will trigger on each draw, usually, it's here you draw on canvas |

| name | type | Description |
|:----|:----|:----|
| $canvas | `HTMLCanvasElement` | the html convas element |
| ctx | `HTMLElement` | the html convas element |
| data | `any` | the data object you send at the init |

```js
import Engine from "canvas-loop-engine"

const MyLoop = new Engine({
  $canvas: document.querySelector("canvas"),
  onDraw: function ({ $canvas, ctx, data }) {
    //draw things
  }
})
```

***or***  

```js
import Engine from "canvas-loop-engine"

const foo = function ({ $canvas, ctx, data }) {
  //draw things
}
const bar = function ({ $canvas, ctx, data }) {
  //draw things
}

const MyLoop = new Engine({
  $canvas: document.querySelector("canvas"),
  onDraw: [foo, bar]
})
```

---

## Methods <a id="methods"></a>  

### .start() <a id="start"></a>  

| Type | Description |
|:----|:----|
| `function` | Start the loop, if it was'nt already start |
> Will trigger the `onStart` functions

---

### .stop() <a id="stop"></a>  

| Type | Description |
|:----|:----|
| `function` | Stop the loop, if it was'nt already stop |
> Will trigger the `onStop` functions

---

### .toggle() <a id="toggle"></a>  

| Type | Description |
|:----|:----|
| `function` | Toogle the loop (stop or start) |
> Will trigger the `onStop` or `onStart` functions

---

### .update() <a id="update"></a>  

| Type | Description |
|:----|:----|
| `function` | trigger the `onUpdate` functions |

---

### .draw() <a id="draw"></a>  

| Type | Description |
|:----|:----|
| `function` | trigger the `onDraw` functions |

---

### .isRunning <a id="isRunning"></a>  

| Type | Description |
|:----|:----|
| `boolean` | the current loop status (if he's running or not) |

---

---

## TODO  

- [x] Doc
- [ ] TU
- [ ] TS

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