Documentation

Curtains object

Instanciate

You will have to create a Curtains object first that will handle the scene containing all your planes. It will also create the WebGL context, append the canvas and handle the requestAnimationFrame loop. You just have to pass the ID of the HTML element that will wrap the canvas :


var curtains = new Curtains("canvas"); // "canvas" is the ID of our HTML element

								

You can pass a boolean as a second parameter to indicate whether you want to use the library in production mode. If set to true it will remove all console warnings. Default to false.


var curtains = new Curtains("canvas", true); // use the library in "production" mode

							

Methods

  • addPlane(planeElement, params) :
    planeElement (HTML element) : a HTML element
    params (object) : an object containing the plane parameters (see the Plane object).

    This function will add a plane to our Curtains wrapper.

  • removePlane(plane) :
    plane (plane object) : the plane to remove

    This function will remove a plane from our Curtains object.

  • onError() :

    This function will be called if there's an error during the initialisation, or if the WebGL context could not be created.

  • disableDrawing() :

    This function will prevent the scene from being drawn again (putting it in a paused state). You won't be able to update uniforms while the drawing is disabled. Useful to improve performance if you got a static scene.

  • enableDrawing() :

    This function will reenable the scene drawing in case you paused it via disableDrawing(). Could be useful if you want to start drawing the scene again when a user gesture happens for example.

  • needRender() :

    This function will reenable the scene drawing for just one frame. Useful if you want to update uniforms if the drawing is disabled.

  • dispose() :

    This function will cancel the requestAnimationFrame loop, remove all planes and delete the WebGL context.

Plane object

Those are the planes we will be manipulating. They are instanciate internally each time you call the addPlane method on the parent Curtains object.

Properties

  • vertexShader (string) : Your vertex shader as a string. Be careful with the line-breaks as it may throw javascript errors. Will look for vertexShaderID param if not specified.
  • vertexShaderID (string) : the vertex shader ID. If ommited, will look for a data attribute data-vs-id on the plane HTML element. Will use a default vertex shader and throw a warning if nothing specified.
  • fragmentShader (string) : Your fragment shader as a string. Be careful with the line-breaks as it may throw javascript errors. Will look for fragmentShaderID param if not specified.
  • fragmentShaderID (string) : the fragment shader ID. If ommited, will look for a data attribute data-fs-id on the plane HTML element. Will use a default fragment shader that draws only black pixels and throw a warning if nothing specified.
  • widthSegments (integer, optionnal) : plane definition along the X axis (1 by default).
  • heightSegments (integer, optionnal) : plane definition along the Y axis (1 by default).
  • mimicCSS (bool, optionnal) : define if the plane should copy it's HTML element position (true by default).
  • imageCover (bool, optionnal) : define if the images must imitate css background-cover or just fit the plane (true by default).
  • crossOrigin (string, optionnal) : define the cross origin process to load images if any.
  • fov (integer, optionnal) : define the perspective field of view (default to 75).
  • uniforms (object, otpionnal): the uniforms that will be passed to the shaders (if no uniforms specified there won't be any interaction with the plane). Each uniform should have three properties : a name (string), a type (string, see here) and a value.

Parameters basic example


var params = {
    vertexShaderID: "plane-vs", // our vertex shader ID
    fragmentShaderID: "plane-fs", // our framgent shader ID
    uniforms: {
        time: {
            name: "uTime", // uniform name that will be passed to our shaders
            type: "1f", // this means our uniform is a float
            value: 0,
        },
    }
}

							

Methods

  • loadImages(imgElements) :
    imgElements (HTML image elements) : a collection of HTML image elements to load into your plane.

    This function is automatically called internally on a new Plane instanciation, but you can use it if you want to create an empty plane and then assign it some textures later. See asynchronous textures loading example.

  • loadVideos(videoElements) :
    videoElements (HTML video elements) : a collection of HTML video elements to load into your plane.

    This function is automatically called internally on a new Plane instanciation. It works exactly the same as the loadImages() method.

  • loadCanvases(canvasElements) :
    canvasElements (HTML canvas elements) : a collection of HTML canvas elements to load into your plane.

    This function is automatically called internally on a new Plane instanciation. It works exactly the same as the loadImages() method.

  • onLoading() :

    This function will be fired each time an image of the plane has been loaded. Useful to handle a loader.

  • onReady() :

    This function will be called once our plane is all set up and ready to be drawn. This is where you may want to add event listener to interact with it or update its uniforms.

  • onRender() :

    This function will be triggered at each requestAnimationFrame call. Useful to update a time uniform, change plane rotation, scale, etc.

  • playVideos() :

    This function will automatically start all of your plane videos playback. If you are not calling it after a user action it might not work on mobile.

  • planeResize() :

    This method is called internally each time the WebGL canvas is resized, but you should call it manually each time you're updating a plane size, either via CSS animations or directly in javascript. Updates position as well if the mimicCSS property is set to true.

  • updatePosition() :

    The planes positions are updated only when the canvas container is resized. But if you are updating your plane HTML element position without resizing the container (typically animating its CSS position or transform values), call this method in your animation loop at the same time.
    Only effective if the mimicCSS property is set to true.

  • setPerspective(fieldOfView, nearPlane, farPlane) :
    fieldOfView (integer) : the perspective field of view. Should be greater than 0 and lower than 180. Default to 75.
    nearPlane (float, optionnal) : closest point where a mesh vertex is displayed. Default to 0.1.
    farPlane (float, optionnal) : farthest point where a mesh vertex is displayed. Default to 150 (two times the field of view).

    Reset the perspective. The smaller the field of view, the more perspective.

  • setScale(scaleX, scaleY) :
    scaleX (float) : the scale to set along the X axis.
    scaleY (float) : the scale to set along the Y axis.

    Set the plane new scale.

  • setRotation(angleX, angleY, angleZ) :
    angleX (float) : the angle in radians to rotate around the X axis.
    angleY (float) : the angle in radians to rotate around the Y axis.
    angleZ (float) : the angle in radians to rotate around the Z axis.

    Set the plane rotation.

  • setRelativePosition(translationX, translationY) :
    translationX (float) : the translation value to apply on the X axis in pixel.
    translationY (float) : the translation value to apply on the Y axis in pixel.

    Set the plane translation based on pixel units.

  • mouseToPlaneCoords(xMousePosition, yMousePosition) :
    xMousePosition (float) : mouse event clientX value.
    yMousePosition (float) : mouse event clientY value.

    Get the mouse coordinates relative to the plane clip space values. Use it to send to a uniform and interact with your plane. A plane coordinates ranges from (-1, 1) in the top left corner to (1, -1) in the bottom right corner, which means the values along the Y axis are inverted.

  • enableDepthTest(shouldEnableDepthTest) :
    shouldEnableDepthTest (bool) : enable or disable the depth test for that plane.

    Switches on/off the depth test for that plane. You might want to disable the depth test if you got transparency issues.

  • moveToFront() :

    Let the plane overlay all other planes. Be careful as it is silently disabling depth test for that plane, you might want to switch it back on later.