https://github.com/dmnsgn/raf-perf

RAF loop with an adaptive fps and performance ratio calculated from either a sample count or a sample duration. Typically used when doing intensive graphics computation in canvas.
https://github.com/dmnsgn/raf-perf

adaptive fps loop performance raf requestanimationframe throttle tick ticker

Last synced: 11 months ago
JSON representation

RAF loop with an adaptive fps and performance ratio calculated from either a sample count or a sample duration. Typically used when doing intensive graphics computation in canvas.

• Host: GitHub
• URL: https://github.com/dmnsgn/raf-perf
• Owner: dmnsgn
• License: mit
• Created: 2019-01-10T09:37:37.000Z (about 7 years ago)
• Default Branch: main
• Last Pushed: 2024-07-06T14:23:38.000Z (over 1 year ago)
• Last Synced: 2025-04-14T21:14:17.481Z (11 months ago)
• Topics: adaptive, fps, loop, performance, raf, requestanimationframe, throttle, tick, ticker
• Language: JavaScript
• Homepage: https://dmnsgn.github.io/raf-perf/
• Size: 2.72 MB
• Stars: 62
• Watchers: 3
• Forks: 0
• Open Issues: 0
• Metadata Files:
  • Readme: README.md
  • Changelog: CHANGELOG.md
  • License: LICENSE.md

Awesome Lists containing this project

README

          
# raf-perf

[![npm version](https://img.shields.io/npm/v/raf-perf)](https://www.npmjs.com/package/raf-perf)

[![stability-stable](https://img.shields.io/badge/stability-stable-green.svg)](https://www.npmjs.com/package/raf-perf)

[![npm minzipped size](https://img.shields.io/bundlephobia/minzip/raf-perf)](https://bundlephobia.com/package/raf-perf)

[![dependencies](https://img.shields.io/librariesio/release/npm/raf-perf)](https://github.com/dmnsgn/raf-perf/blob/main/package.json)

[![types](https://img.shields.io/npm/types/raf-perf)](https://github.com/microsoft/TypeScript)

[![Conventional Commits](https://img.shields.io/badge/Conventional%20Commits-1.0.0-fa6673.svg)](https://conventionalcommits.org)

[![styled with prettier](https://img.shields.io/badge/styled_with-Prettier-f8bc45.svg?logo=prettier)](https://github.com/prettier/prettier)

[![linted with eslint](https://img.shields.io/badge/linted_with-ES_Lint-4B32C3.svg?logo=eslint)](https://github.com/eslint/eslint)

[![license](https://img.shields.io/github/license/dmnsgn/raf-perf)](https://github.com/dmnsgn/raf-perf/blob/main/LICENSE.md)

RAF loop with an adaptive fps and performance ratio calculated from either a sample count or a sample duration. Typically used when doing intensive graphics computation in canvas.

[![paypal](https://img.shields.io/badge/donate-paypal-informational?logo=paypal)](https://paypal.me/dmnsgn)

[![coinbase](https://img.shields.io/badge/donate-coinbase-informational?logo=coinbase)](https://commerce.coinbase.com/checkout/56cbdf28-e323-48d8-9c98-7019e72c97f3)

[![twitter](https://img.shields.io/twitter/follow/dmnsgn?style=social)](https://twitter.com/dmnsgn)

![](https://raw.githubusercontent.com/dmnsgn/raf-perf/main/screenshot.gif)

## Installation

```bash

npm install raf-perf

```

## Usage

```js

import RafPerf from "raf-perf";

import createCanvasContext from "canvas-context";

const { context, canvas } = createCanvasContext("2d", {

  width: window.innerWidth,

  height: window.innerHeight,

  offscreen: true,

});

document.body.appendChild(canvas);

const engine = new RafPerf();

const offTick = engine.on("tick", (dt) => {

  // Clear

  context.clearRect(0, 0, canvas.width, canvas.height);

  // Draw

  // ...

});

const offPerf = engine.on("perf", (ratio) => {

  if (!ratio) return;

  console.log(`Performance ratio: ${ratio}`);

  if (ratio < 0.9) {

    console.log("Too many draws");

  } else if (ratio >= 0.9 && rectCount < maxRectCount) {

    console.log("Draw more");

  }

});

engine.start();

const destroy = () => {

  if (engine.isRunning) engine.stop();

  offTick();

  offPerf();

};

```

## API

## Classes



RafPerf





## Events



"perf"



Event triggered when performance ratio (this.frameDuration / averageDeltaTime) is updated. Understand a ratio of the fps, for instance for a fps value of 24, ratio < 0.5 means that the averaged fps < 12 and you should probably do something about it.



"tick"



Event triggered on tick, throttled by options.fps.





## Typedefs





Options : object







OptionsPerformances : object









## RafPerf

**Kind**: global class

- [RafPerf](#RafPerf)

  - [new RafPerf([options])](#new_RafPerf_new)

  - [.TickEvent](#RafPerf+TickEvent) : string

  - [.PerfEvent](#RafPerf+PerfEvent) : string

  - [.start()](#RafPerf+start)

  - [.tick()](#RafPerf+tick)

  - [.stop()](#RafPerf+stop)

  - [.on(type, cb)](#RafPerf+on) ⇒ function



### new RafPerf([options])

Creates an instance of RafPerf.

| Param     | Type                             | Default         | Description                                                                                                                                                         |

| --------- | -------------------------------- | --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

| [options] | [Options](#Options) | {} | `samplesCount` and `sampleDuration` are used concurrently. Set `sampleDuration` to a _falsy_ value if you only want to sample performances from a number of frames. |



### rafPerf.TickEvent : string

**Kind**: instance property of [RafPerf](#RafPerf)



### rafPerf.PerfEvent : string

**Kind**: instance property of [RafPerf](#RafPerf)



### rafPerf.start()

Run the `requestAnimationFrame` loop and start checking performances if `options.performances.enabled` is `true`.

**Kind**: instance method of [RafPerf](#RafPerf)



### rafPerf.tick()

The frame loop callback.

**Kind**: instance method of [RafPerf](#RafPerf)

**Emits**: RafPerf.event:PerfEvent, RafPerf.event:TickEvent



### rafPerf.stop()

Run `cancelAnimationFrame` if necessary and reset the engine.

**Kind**: instance method of [RafPerf](#RafPerf)



### rafPerf.on(type, cb) ⇒ function

Add "perf" and "tick" listeners.

**Kind**: instance method of [RafPerf](#RafPerf)

**Returns**: function - Call the return value to unsubscribe.

| Param | Type                  |

| ----- | --------------------- |

| type  | string   |

| cb    | function |



## "perf"

Event triggered when performance ratio (`this.frameDuration / averageDeltaTime`) is updated. Understand a ratio of the fps, for instance for a fps value of 24, `ratio < 0.5` means that the averaged `fps < 12` and you should probably do something about it.

**Kind**: event emitted



## "tick"

Event triggered on tick, throttled by `options.fps`.

**Kind**: event emitted



## Options : object

**Kind**: global typedef

**Properties**

| Name           | Type                                                     | Default                                                                 | Description           |

| -------------- | -------------------------------------------------------- | ----------------------------------------------------------------------- | --------------------- |

| [fps]          | number                                      | 60                                                         | Throttle fps.         |

| [performances] | [OptionsPerformances](#OptionsPerformances) | { enabled: true, samplesCount: 200, sampleDuration: 4000 } | Performances metrics. |



## OptionsPerformances : object

**Kind**: global typedef

**Properties**

| Name             | Type                 | Default           | Description                                  |

| ---------------- | -------------------- | ----------------- | -------------------------------------------- |

| [enabled]        | boolean | true | Evaluate performances.                       |

| [samplesCount]   | number  | 200  | Number of samples to evaluate performances.  |

| [sampleDuration] | number  | 4000 | Duration of sample to evaluate performances. |

## License

MIT. See [license file](https://github.com/dmnsgn/raf-perf/blob/main/LICENSE.md).