Curtains class

Basic usage

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 HTML element (or its ID) that will wrap the canvas :

// "canvas" is the ID of our HTML container element
var curtains = new Curtains({
container: document.getElementById("canvas") // we could have just pass "canvas" instead
});

There are other options that you can pass as parameters. For example, you can specify whether you want to use the library in production mode:

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

Parameters

Here is a complete list of all the parameters:

  • container HTML Element or string the HTML Element or ID of the HTML Element that will wrap the canvas. If not specified, will append a div with a "curtains-canvas" ID just before the body closing tag.
  • production bool, optionnal Whether the library should throw useful console warnings or not. Default to false.
  • pixelRatio float, optionnal Defines the pixel ratio value. Use it to limit it on init to increase performance. Default to window.devicePixelRatio.
  • autoRender bool, optionnal Whether the library should create a request animation frame loop to render the scene. Set it to false if you want to handle this by yourself using the render() method. Default to true.
  • autoResize bool, optionnal Whether the library should listen to the window resize event and actually resize the scene. Set it to false if you want to handle this by yourself using the resize() method. Default to true.
  • watchScroll bool, optionnal Whether the library should listen to the window scroll event. Set it to false if you want to handle this by yourself. Default to true.

Properties

  • container (HTML element) v1.0

    The container that will hold our WebGL canvas. The canvas will be sized according to this container. For performance reason, the smaller your container the better. Most of the time you'll set it to cover the window.

  • glCanvas (HTML canvas element) v1.0

    The WebGL canvas being created and that contains our scene.

  • glContext (WebGL context) v1.0

    Our WebGL context.

  • pixelRatio (float) v1.0

    The current device pixel ratio.

  • planes (array) v1.0

    An array containing all your current Plane elements.

  • productionMode (bool) v1.6

    If set to true, will remove all helpful warnings displayed by the library.

  • shaderPasses (array) v3.0

    An array containing all your current ShaderPass elements.

Methods

    addPlane(planeElement, params): v1.0

    This function will create a new Plane and add it to our Curtains wrapper.
    The newly created plane will be returned.

    planeElement (HTML element): a HTML element
    params (object, optionnal): an object containing the plane parameters:

    • planeElement HTML element a HTML element.
    • params object, optionnal an object containing the plane parameters:
      • vertexShader string, optionnal 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, optionnal 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, optionnal 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, optionnal 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 the plane's definition along the X axis (1 by default).
      • heightSegments integer, optionnal the plane's definition along the Y axis (1 by default).
      • alwaysDraw bool, optionnal Whether to use frustum culling: defines if the plane should always be drawn or if it should not be drawn if it lies completely outside of the scene (false by default).
      • drawCheckMargins object, optionnal Additional margins to add in the draw check calculations, in pixels.
        Positive value means the plane will be drawn even if outside the canvas by less than the value, negative value means the plane will be hidden if inside the canvas by more than the value.
        Useful if you're messing with the vertices positions in your vertex shader.
        • top float margin to apply when comparing the top side of the plane and the bottom side of the canvas (0 by default).
        • right float margin to apply when comparing the right side of the plane and the left side of the canvas (0 by default).
        • bottom float margin to apply when comparing the bottom side of the plane and the top side of the canvas (0 by default).
        • left float margin to apply when comparing the left side of the plane and the right side of the canvas (0 by default).
      • watchScroll bool, optionnal Whether the plane should auto update its position when the user scrolls (false by default).
      • autoloadSources bool, optionnal defines if the sources should be load on init automatically (true by default).
      • crossOrigin string, optionnal defines the crossOrigin process to load images if any (default to "anonymous").
      • fov integer, optionnal defines the perspective field of view (default to 75).
      • uniforms object, optionnal the uniforms that will be passed to the shaders (if no uniforms specified there won't be any interaction with the plane).
        • name string The name of the uniform to use in your shaders
        • type string The type of your uniform (see here).
        • value float, integer or array of floats or integers depending on your uniform type The value of the uniform.

    returns: the newly created Plane if successful, false othterwise.

    Parameters basic example

    var params = {
    vertexShaderID: "plane-vs", // our vertex shader ID
    fragmentShaderID: "plane-fs", // our fragment 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, // initial value of the uniform
    },
    },
    };

    Examples: used in all examples.

  • addShaderPass(params): v3.0

    This function will create a new ShaderPass and add it to our Curtains wrapper.
    The newly created shader pass will be returned.

    params (object, optionnal): an object containing the plane parameters:

    • params object, optionnal an object containing the plane parameters:
      • vertexShader string, optionnal 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, optionnal 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, optionnal 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, optionnal 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 the scene without modifications if nothing specified.
      • crossOrigin string, optionnal defines the crossOrigin process to load images if any (default to "anonymous").
      • uniforms object, optionnal the uniforms that will be passed to the shaders (if no uniforms specified there won't be any interaction with the plane).
        • name string The name of the uniform to use in your shaders
        • type string The type of your uniform (see here).
        • value float, integer or array of floats or integers depending on your uniform type The value of the uniform.

    returns: the newly created ShaderPass if successful, false othterwise.

    Parameters basic example

    See addPlane basic parameters example.

    Examples: used in Post processing displacement effect and Post processing multiple passes examples.

  • disableDrawing(): v1.8

    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.

    Examples: used in Slideshow with a displacement shader and Asynchronous textures loading examples.

  • dispose(): v1.0

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

  • enableDrawing(): v1.8

    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.

    Examples: used in Slideshow with a displacement shader and Asynchronous textures loading examples.

  • getBoundingRect(): v3.0

    Useful to get our container HTML element bounding rectangle without causing a reflow/layout repaint. Be careful as the values are relative to your pixelRatio value.

    returns: an object containing the container HTML element width, height, top and left positions.

    Examples: used in Multiple planes scroll effect and Post processing multiple passes examples.

  • getScrollDeltas(): v4.0

    Get the last scroll delta values along X and Y axis. Call it after having called updateScrollValues() or inside the onScroll() event if scroll watching is active.

    returns: an object containing the last scroll delta values along X and Y axis.

    Examples: used in Multiple planes, Multiple planes scroll effect : rotation, scale and parallax, Post processing displacement effect and Post processing multiple passes examples.

  • getScrollValues(): v4.0

    Get the current scroll values along X and Y axis. Call it after having called updateScrollValues() or inside the onScroll() event if scroll watching is active.

    returns: an object containing the current scroll values along X and Y axis.

    Examples: used in Multiple planes, Multiple planes scroll effect : rotation, scale and parallax, Post processing displacement effect and Post processing multiple passes examples.

  • needRender(): v1.8

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

    Examples: used in Slideshow with a displacement shader and Asynchronous textures loading examples.

  • removePlane(plane): v1.5

    This function will remove a plane from our Curtains object and delete all of its textures.

    • plane Plane object the plane to remove.

    Examples: used in AJAX navigation with plane removal example.

  • removeShaderPass(shaderPass): v3.0

    This function will remove a shader pass from our Curtains object and delete all of its textures.

    • shaderPass ShaderPass object the shader pass to remove.
  • render(): v4.0

    This function renders your scene if drawing is enabled. Useful if you're using your own request animation frame loop.

  • resize(): v2.0 triggers reflow

    This function will resize your scene and all your planes. Called internally at each window resize event. You should call it if you're changing your container size dynamically without changing the window size.

  • restoreContext(): v2.0

    This function will try to restore the WebGL context. Use it after having previously lost the context.

  • setPixelRatio(pixelRatio, triggerCallback): v2.0 triggers reflow

    This function will set a new pixel ratio and resize everything accordingly.
    The default pixel ratio value being initialized is the actual device pixel ratio. Use this method if you want to limit the pixel ratio to improve performance.

    • pixelRatio float new pixel ratio to set.
    • triggerCallback bool, optionnal whether onAfterResize callback should be triggered, false by default.
  • updateScrollValues(xOffset, yOffset): v4.0

    Updates the scroll values. Use it before updating your planes positions with updateScrollPosition() while scrolling.
    Called internally if scroll watching is active.

    • xOffset float scroll value along X axis.
    • yOffset float scroll value along Y axis.

    Examples: used in Multiple planes scroll effect with Locomotive scroll example.

Events

  • onAfterResize(): v3.0

    This function will be called each time the window has been resized, after everything has been updated.

    returns: your Curtains object, allowing it to be chainable.

  • onContextLost(): v2.0

    This function will be called each time the WebGL context has been lost.

    returns: your Curtains object, allowing it to be chainable.

  • onContextRestored(): v2.0

    This function will be called each time the WebGL context has been successfully restored.

    returns: your Curtains object, allowing it to be chainable.

  • onError(): v1.7

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

    returns: your Curtains object, allowing it to be chainable.

    Examples: used in all examples.

  • onRender(): v2.0

    This function is called once at each request animation frame call. Useful if you need to update stats or tweening engine.

    returns: your Curtains object, allowing it to be chainable.

    Examples: used in Multiple planes, Multiple planes scroll effect : rotation, scale and parallax examples.

  • onScroll(): v4.0

    This function is called each time a window scroll event is fired and scroll watching is active.

    returns: your Curtains object, allowing it to be chainable.

    Examples: used in Multiple planes, Multiple planes scroll effect : rotation, scale and parallax, Post processing displacement effect and Post processing multiple passes examples.