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 ID of the HTML element that will wrap the canvas :

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

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.

// use the library in "production" mode
var curtains = new Curtains("canvas", 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 defines if the plane should always be drawn or if it should be drawn only if its within the canvas (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 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, // 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.

  • 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.
  • 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.

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.