Phenomenon

A fast 2kB low-level WebGL API.

vaneenige/phenomenonphenomenon

README


Phenomenon

npm version travis build gzip size license dependencies TypeScript

Phenomenon is a very small, low-level WebGL library that provides the essentials to deliver a high performance experience. Its core functionality is built around the idea of moving millions of particles around using the power of the GPU.

Features:


- Small in size, no dependencies
- GPU based for high performance
- Low-level & highly configurable
- Helper functions with options
- Add & destroy instances dynamically
- Dynamic attribute switching

*Want to see some magic right away? Have a look here!*

Install


  1. ```
  2. $ npm install --save phenomenon
  3. ```

Usage


  1. ``` js
  2. // Import the library
  3. import Phenomenon from 'phenomenon';

  5. // Create a renderer
  6. const phenomenon = new Phenomenon(options);

  8. // Add an instance
  9. phenomenon.add("particles", options);
  10. ```

For a better understanding of how to use the library, read along or have a look at the demo!


API


Phenomenon(options)


Returns an instance of Phenomenon.

Throughout this documentation we'll refer to an instance of this as renderer.


options.canvas

Type: `HTMLElement`
Default: `document.querySelector('canvas')`

The element where the scene, with all of its instances, will be rendered to. The provided element has to be `` otherwise it won't work.

options.context

Type: `Object`
Default: `{}`

Overrides that are used when getting the WebGL context from the canvas. The library overrides two settings by default.

NameDefaultDescription
-----------------|
Alpha`false`Setting
Antialias`false`Setting

Read more about all the possible overrides on <a href="https://developer.mozilla.org/en-US/docs/Web/API/HTMLCanvasElement/getContext">MDN</a>.


options.contextType

Type: `String`
Default: webgl

The context identifier defining the drawing context associated to the canvas. For WebGL 2.0 use webgl2.

options.settings

Type: `Object`
Default: `{}`

Overrides that can be used to alter the behaviour of the experience.

NameValueDefaultDescription
--------------------------------------------------------------------------------------------------------------------------------------------
devicePixelRatio`number``1`The
clearColor`array``[1,1,1,1]`The
clip`array``[0.001,The
position`number``{x:0,y:0,z:2}`The
shouldRender`boolean``true`A
uniforms`object``{}`Shared
onSetup(gl)`function``undefined`A
onRender(renderer)`function``undefined`A
debug`boolean``false`Whether


.resize()


Update all values that are based on the dimensions of the canvas to make it look good on all screen sizes.

.toggle(shouldRender)


Toggle the rendering state of the scene. When shouldRender is false requestAnimationFrame is disabled so no resources are used.

shouldRender

Type: `Boolean`
Default: `undefined`

An optional boolean to set the rendering state to a specific value. Leaving this value empty will result in a regular boolean switch.

.add(key, settings)


This function is used to add instances to the renderer. These instances can be as simple or complex as you'd like them to be. There's no limit to how many of these you can add. Make sure they all have a different key!

key

Type: `String`
Default: `undefined`

Every instance should have a unique name. This name can also be used to destroy the instance specifically later.

settings

Type: `Object`
Default: `{}`

An object containing overrides for parameters that are used when getting the WebGL context from the canvas.

NameValueDefaultDescription
------------------------------------------------------------------------------------------------------------
attributes`array``[]`Values
uniforms`object``{}`Values
vertex`string`-The
fragment`string`-The
multiplier`number``1`The
mode`number``0`The
geometry`object``{}`Vertices
modifiers`object``{}`Modifiers
onRender`function``undefined`A

Note: Less instances with a higher multiplier will be faster than more instances with a lower multiplier!


.remove(key)


Remove an instance from the scene (and from memory) by its key.

.destroy()


Remove all instances and the renderer itself. The canvas element will remain in the DOM.

.prepareAttribute(attribute)


Dynamically override an attribute with the same logic that is used during initial creation of the instance. The function requires an object with a name, size and data attribute.

Note: The calculation of the data function is done on the CPU. Be sure to check for dropped frames with a lot of particles.


Attributes can also be switched. In the demo this is used to continue with a new start position identical to the end position. This can be achieved with .prepareBuffer(attribute) in which the data function is replaced with the final array.

Examples


1. Particles2. Types3. Transition4. Easing5. Shapes6. Instances7. Movement8. Particle cube9. Dynamic intances

Contribute


Are you excited about this library and have interesting ideas on how to improve it? Please tell me or contribute directly! 🙌

  1. ```
  2. npm install > npm start > http://localhost:8080
  3. ```

License


MIT © Colin van Eenige