CurtainsJS

curtains.js is a lightweight vanilla WebGL javascript library that turns HT...

README

What is it ?

    Shaders are the new front-end web developpment big thing, with the ability to create very powerful 3D interactions and animations. A lot of very good javascript libraries already handle WebGL but with most of them it's kind of a headache to position your meshes relative to the DOM elements of your web page.

curtains.js was created with just that issue in mind. It is a small vanilla WebGL javascript library that converts HTML elements containing images and videos into 3D WebGL textured planes, allowing you to animate them via shaders.

    You can define each plane size and position via CSS, which makes it super easy to add WebGL responsive planes all over your pages.

curtains.js demo gif

Knowledge and technical requirements

    It is easy to use but you will of course have to possess good basics of HTML, CSS and javascript.

If you've never heard about shaders, you may want to learn a bit more about them on The Book of Shaders for example. You will have to understand what are the vertex and fragment shaders, the use of uniforms as well as the GLSL syntax basics.

Installation and usage

    You can directly download the files and start using the ES6 modules:
    
  1. ``` js
  2. import {Curtains, Plane} from 'path/to/src/index.mjs';

  3. const curtains = new Curtains({
  4.     container: "canvas"
  5. });

  6. const plane = new Plane(curtains, document.querySelector("#plane"));
  7. ```
    Or you can use npm:

  1. ```
  2. npm i curtainsjs
  3. ```

    Load ES6 modules:

  1. ``` js
  2. import {Curtains, Plane} from 'curtainsjs';
  3. ```

In a browser, you can use the UMD files located in the dist directory:
    
  1. ``` html
  2. <script src="dist/curtains.umd.min.js"></script>
  3. ```

  1. ``` js
  2. const curtains = new Curtains({
  3.     container: "canvas"
  4. });

  5. const plane = new Plane(curtains, document.querySelector("#plane"));

  6. // etc
  7. ```

Usage with React


Note that if you are using React, you might want to try react-curtains, curtains.js official React package.

Documentation


The library is split into classes modules. Most of them are used internally by the library but there are however a few classes meant to be used directly, exported in the src/index.mjs file.

Core

  •         Curtains: appends a canvas to your container and instanciates the WebGL context. Also handles a few helpers like scroll and resize events, request animation frame loop, etc.
  •         Plane: creates a new Plane object bound to a HTML element.
  •         Textures: creates a new Texture object.

Frame Buffer Objects

  •         RenderTarget: creates a frame buffer object.
  •         ShaderPass: creates a post processing pass using a RenderTarget object.

Loader

  •         TextureLoader: loads HTML media elements such as images, videos or canvases and creates Texture objects using those sources.

Math

  •         Vec2: creates a new Vector 2.
  •         Vec3: creates a new Vector 3.
  •         Mat4: creates a new Matrix 4.
  •         Quat: creates a new Quaternion.

Extras

  •         PingPongPlane: creates a plane that uses FBOs ping pong to read/write a texture.
  •         FXAAPass: creates an antialiasing FXAA pass using a ShaderPass object.

Full documentation

Getting started
API docs
Examples

Basic example

HTML


  1. ``` html
  2. <body>
  3.     
  4.     <div id="canvas"></div>
  5.     
  6.     
  7.     <div class="plane">
  8.     
  9.         
  10.         <img src="path/to/my-image.jpg" crossorigin="" />
  11.     </div>
  12.     
  13. </body>
  14. ```

CSS


  1. ```css
  2. body {
  3.     /* make the body fits our viewport */
  4.     position: relative;
  5.     width: 100%;
  6.     height: 100vh;
  7.     margin: 0;
  8.     overflow: hidden;
  9. }

  10. #canvas {
  11.     /* make the canvas wrapper fits the document */
  12.     position: absolute;
  13.     top: 0;
  14.     right: 0;
  15.     bottom: 0;
  16.     left: 0;
  17. }

  18. .plane {
  19.     /* define the size of your plane */
  20.     width: 80%;
  21.     height: 80vh;
  22.     margin: 10vh auto;
  23. }

  24. .plane img {
  25.     /* hide the img element */
  26.     display: none;
  27. }
  28. ```

Javascript


  1. ``` js
  2. import {Curtains, Plane} from 'curtainsjs';

  3. window.addEventListener("load", () => {
  4.     // set up our WebGL context and append the canvas to our wrapper
  5.     const curtains = new Curtains({
  6.         container: "canvas"
  7.     });
  8.     
  9.     // get our plane element
  10.     const planeElement = document.getElementsByClassName("plane")[0];
  11.     
  12.     // set our initial parameters (basic uniforms)
  13.     const params = {
  14.         vertexShaderID: "plane-vs", // our vertex shader ID
  15.         fragmentShaderID: "plane-fs", // our fragment shader ID
  16.         uniforms: {
  17.             time: {
  18.                 name: "uTime", // uniform name that will be passed to our shaders
  19.                 type: "1f", // this means our uniform is a float
  20.                 value: 0,
  21.             },
  22.         },
  23.     };
  24.     
  25.     // create our plane using our curtains object, the bound HTML element and the parameters
  26.     const plane = new Plane(curtains, planeElement, params);
  27.     
  28.     plane.onRender(() => {
  29.         // use the onRender method of our plane fired at each requestAnimationFrame call
  30.         plane.uniforms.time.value++; // update our time uniform value
  31.     });
  32.     
  33. });
  34. ```

Shaders

Vertex shader


  1. ```glsl
  2. <script id="plane-vs" type="x-shader/x-vertex">
  3.     #ifdef GL_ES
  4.     precision mediump float;
  5.     #endif
  6.     
  7.     // those are the mandatory attributes that the lib sets
  8.     attribute vec3 aVertexPosition;
  9.     attribute vec2 aTextureCoord;
  10.     
  11.     // those are mandatory uniforms that the lib sets and that contain our model view and projection matrix
  12.     uniform mat4 uMVMatrix;
  13.     uniform mat4 uPMatrix;
  14.     
  15.     // our texture matrix that will handle image cover
  16.     uniform mat4 uTextureMatrix0;
  17.     
  18.     // pass your vertex and texture coords to the fragment shader
  19.     varying vec3 vVertexPosition;
  20.     varying vec2 vTextureCoord;
  21.     
  22.     void main() {      
  23.         gl_Position = uPMatrix * uMVMatrix * vec4(aVertexPosition, 1.0);
  24.         
  25.         // set the varyings
  26.         // here we use our texture matrix to calculate the accurate texture coords
  27.         vTextureCoord = (uTextureMatrix0 * vec4(aTextureCoord, 0.0, 1.0)).xy;
  28.         vVertexPosition = aVertexPosition;
  29.     }
  30. </script>
  31. ```

Fragment shader


  1. ```glsl
  2. <script id="plane-fs" type="x-shader/x-fragment">
  3.     #ifdef GL_ES
  4.     precision mediump float;
  5.     #endif
  6.     
  7.     // get our varyings
  8.     varying vec3 vVertexPosition;
  9.     varying vec2 vTextureCoord;
  10.     
  11.     // the uniform we declared inside our javascript
  12.     uniform float uTime;
  13.     
  14.     // our texture sampler (default name, to use a different name please refer to the documentation)
  15.     uniform sampler2D uSampler0;
  16.     
  17.     void main() {
  18.         // get our texture coords from our varying
  19.         vec2 textureCoord = vTextureCoord;
  20.         
  21.         // displace our pixels along the X axis based on our time uniform
  22.         // textures coords are ranging from 0.0 to 1.0 on both axis
  23.         textureCoord.x += sin(textureCoord.y * 25.0) * cos(textureCoord.x * 25.0) * (cos(uTime / 50.0)) / 25.0;
  24.         
  25.         // map our texture with the texture matrix coords
  26.         gl_FragColor = texture2D(uSampler0, textureCoord);
  27.     }
  28. </script>
  29. ```

Changelog


Complete changelog starting from version 7.1.0