phenomenon
Version:
A fast 2kB low-level WebGL API.
178 lines (120 loc) • 9.42 kB
Markdown
# Phenomenon
[](https://www.npmjs.com/package/phenomenon)
[](https://travis-ci.org/vaneenige/phenomenon)
[](https://unpkg.com/phenomenon)
[](https://github.com/vaneenige/phenomenon/blob/master/LICENSE)
[](https://github.com/vaneenige/phenomenon/blob/master/package.json)
[](https://www.typescriptlang.org/)
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 <a href="https://codepen.io/collection/AOpMrm/">here</a>!*
## Install
```
$ npm install --save phenomenon
```
## Usage
```js
// Import the library
import Phenomenon from 'phenomenon';
// Create a renderer
const phenomenon = new Phenomenon(options);
// Add an instance
phenomenon.add("particles", options);
```
> 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` <br/>
Default: `document.querySelector('canvas')` <br/>
The element where the scene, with all of its instances, will be rendered to. The provided element has to be `<canvas>` otherwise it won't work.
#### options.context
Type: `Object`<br/>
Default: `{}`<br/>
Overrides that are used when getting the WebGL context from the canvas. The library overrides two settings by default.
| Name | Default | Description |
| --------- | --------| --------------------------------------------------------------------------------------------------------------------------------------- |
| Alpha | `false` | Setting this property to `true` will result in the canvas having a transparent background. By default clearColor is used instead. |
| Antialias | `false` | Setting this property to `true` will make the edges sharper, but could negatively impact performance. See for yourself if it's worth it! |
> 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` <br/>
Default: `webgl`
The context identifier defining the drawing context associated to the canvas. For WebGL 2.0 use `webgl2`.
#### options.settings
Type: `Object`<br/>
Default: `{}`<br/>
Overrides that can be used to alter the behaviour of the experience.
| Name | Value | Default | Description |
| ---------------------------------------- | ---------- | --------------- | --------------------------------------------------------------------------- |
| devicePixelRatio | `number` | `1` | The resolution multiplier by which the scene is rendered relative to the canvas' resolution. Use `window.devicePixelRatio` for the highest possible quality, `1` for the best performance. |
| clearColor | `array` | `[1,1,1,1]` | The color in `rgba` that is used as the background of the scene. |
| clip | `array` | `[0.001, 100]` | The near and far clip plane in 3D space. |
| position | `number` | `{x:0,y:0,z:2}` | The distance in 3D space between the center of the scene and the camera. |
| shouldRender | `boolean` | `true` | A boolean indicating whether the scene should start rendering automatically. |
| uniforms | `object` | `{}` | Shared values between all instances that can be updated at any given moment. By default this feature is used to render all the instances with the same `uProjectionMatrix`, `uModelMatrix` and `uViewMatrix`. It's also useful for moving everything around with the same progress value; `uProgress`. |
| onSetup(gl) | `function` | `undefined` | A setup hook that is called before first render which can be used for gl context changes. |
| onRender(renderer) | `function` | `undefined` | A render hook that is invoked after every rendered frame. Use this to update `renderer.uniforms`. |
### .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` <br/>
Default: `undefined` <br/>
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`<br/>
Default: `undefined`<br/>
Every instance should have a unique name. This name can also be used to destroy the instance specifically later.
#### settings
Type: `Object`<br/>
Default: `{}`<br/>
An object containing overrides for parameters that are used when getting the WebGL context from the canvas.
| Name | Value | Default | Description |
| ----------- | ---------- | ------------ | --------------------------------------------------------------------------- |
| attributes | `array` | `[]` | Values used in the program that are stored once, directly on the GPU. |
| uniforms | `object` | `{}` | Values used in the program that can be updated on the fly. |
| vertex | `string` | - | The vertex shader is used to position the geometry in 3D space. |
| fragment | `string` | - | The fragment shader is used to provide the geometry with color or texture. |
| multiplier | `number` | `1` | The amount of duplicates that will be created for the same instance. |
| mode | `number` | `0` | The way the instance will be rendered. Particles = 0, triangles = 4. |
| geometry | `object` | `{}` | Vertices (and optional normals) of a model. |
| modifiers | `object` | `{}` | Modifiers to alter the attributes data on initialize. |
| onRender | `function` | `undefined` | A render hook that is invoked after every rendered frame. |
> 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. <a href="https://codepen.io/cvaneenige/full/odpVPW">Particles</a>
2. <a href="https://codepen.io/cvaneenige/full/GdGpaN">Types</a>
3. <a href="https://codepen.io/cvaneenige/full/Lmrzmd">Transition</a>
4. <a href="https://codepen.io/cvaneenige/full/zjaydg">Easing</a>
5. <a href="https://codepen.io/cvaneenige/full/wjXVgr">Shapes</a>
6. <a href="https://codepen.io/cvaneenige/full/MGBZpB">Instances</a>
7. <a href="https://codepen.io/cvaneenige/full/LmXWeM">Movement</a>
8. <a href="https://codepen.io/cvaneenige/full/QBwbEY">Particle cube</a>
9. <a href="https://codepen.io/cvaneenige/full/ajNjaN">Dynamic intances</a>
## Contribute
Are you excited about this library and have interesting ideas on how to improve it? Please tell me or contribute directly! 🙌
```
npm install > npm start > http://localhost:8080
```
## License
MIT © <a href="https://use-the-platform.com">Colin van Eenige</a>