Plane class

Basic usage

Plane class inherits from the BasePlane class, which is a class that just sets up the WebGL (buffers and attributes) and sources loading parts of a plane.
Plane extends the BasePlane class by adding various properties and methods to keep your WebGL plane in sync with its associated HTML element. All sizes and positions are handled by two matrices that you will have to use inside your vertex shader: the model view matrix and the projection matrix.

Creation

To create a plane, you will need to pass a mandatory HTML element. It will be used to calculate the size and position of your plane.
You will have to use the addPlane method of your Curtains class object:

// "canvas" is the ID of our HTML container element
var curtains = new Curtains("canvas");
var planeElement = document.getElementById("my-plane");
var plane = curtains.addPlane(planeElement);

Parameters

The code above will create a basic plane but you won't be able to do much with it. The addPlane method has a second parameter in which you can pass all the options you need:

// "canvas" is the ID of our HTML container element
var curtains = new Curtains("canvas");
var planeElement = document.getElementById("my-plane");
var params = {
vertexShaderID: "my-plane-vs", // ID of your vertex shader script tag
fragmentShaderID: "my-plane-fs", // ID of your fragment shader script tag
uniforms: { // uniforms are what will allow you to interact with your plane
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
},
},
};
// create our plane with the above parameters
var plane = curtains.addPlane(planeElement, params);

See the list of all the addPlane possible parameters to know more.

Passing shaders via data attributes

You can also pass the IDs of the vertex and fragment shaders using respectively data-vs-id and data-fs-id attributes of your plane HTML element:

<!-- div used to create our plane -->
<div id="my-plane" data-vs-id="my-plane-vs" data-fs-id="my-plane-fs">
<!-- image that will be used as texture by our plane -->
<img src="path/to/my-image.jpg" />
</div>

Properties

  • alwaysDraw (boolean): v2.0

    Whether the WebGL renderer should always draw the plane or if it should draw it only when the plane is contained in the canvas viewport. Used for performance optimizations.
    If you're messing with the Z position of your vertices in your shader, or if you use rotations, you should set this option to true when you create your plane.

  • autoloadSources (boolean): v2.0

    Whether the sources (images, videos and canvases HTML children elements of your plane) should be loaded, and according textures created on init.

  • canvases (array): v1.4

    An array containing all the canvases loaded via the load methods into the plane.

  • crossOrigin (string): v1.4

    The cross origin process used to load the medias.

  • htmlElement (HTML element): v1.0

    The HTML element used to create your plane. Useful if you want to add event listeners to it.

  • images (array): v1.0

    An array containing all the images loaded via the load methods into the plane.

  • index (integer): v1.0

    The index of your plane in the Curtains planes array.

  • relativeTranslation (object): v1.0

    An object containing the additional translation applied to your plane on x and y axis.

  • rotation (object): v1.0

    An object containing the rotation applied to your plane on x, y and z axis.

  • scale (object): v1.0

    An object containing the scale applied to your plane on x and y axis.

  • textures (array): v2.0

    An array containing all the plane's Textures already created.

  • uniforms (object): v1.0

    An object containing all the uniforms you passed as parameters.
    You can update your uniform by modifying its value property.

  • videos (array): v1.2

    An array containing all the videos loaded via the load methods into the plane.

Methods

  • createTexture(samplerName): v2.0

    This function will create a new Texture and add it to our Plane.
    The newly created texture will be returned.

    • samplerName string, optionnal a string to set the name of your sampler uniform in your shader. Will also impact the texture matrix uniform name. If not specified, will name your sampler "uSampler" + index of this texture in your plane.

    returns: the newly created Texture if successful.

    Examples: used in Slideshow with a displacement shader example.

  • enableDepthTest(shouldEnableDepthTest): v1.3

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

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

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

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

    Examples: used in Simple canvas plane, Text planes using canvas, Multiple planes scroll effect and Post processing multiple passes examples.

  • loadCanvas(canvasElement): v2.0

    This function takes a canvas HTML element, creates a Texture using it and loads it into your plane.

    • canvasElement HTML canvas element a HTML canvas element to load into your plane.

    Examples: used in Text planes using canvas example.

  • loadCanvases(canvasElements): v2.0

    This function takes an array of canvas HTML elements and creates a Texture for each of them.

    • canvasElements array or collection of HTML canvas elements an array or collection of HTML canvas elements to load into your plane.
  • loadImage(imageElement): v2.0

    This function takes an image HTML element, creates a Texture using it and loads it into your plane.

    • imageElement HTML image element a HTML image element to load into your plane.
  • loadImages(imageElements): v2.0

    This function takes an array of image HTML elements and creates a Texture for each of them.

    • imageElements array or collection of HTML image elements an array or collection of HTML image elements to load into your plane.

    Examples: used in Asynchronous textures loading example.

  • loadSource(sourceElement): v2.0

    This function takes a source element, creates a Texture using it and loads it into your plane.

    • sourceElement either image, canvas or video HTML element an image, canvas or video HTML element to load into your plane.
  • loadSources(sourceElements): v2.0

    This function takes an array of source elements, creates Textures using them and loads them into your plane.

    • sourceElements array or collection of either images, canvased or videos HTML elements an array of image, canvas or video HTML elements to load into your plane.
  • loadVideo(videoElement): v2.0

    This function takes a video HTML element, creates a Texture using it and loads it into your plane.

    • videoElement HTML video element a HTML video element to load into your plane.
  • loadVideos(videoElements): v2.0

    This function takes an array of video HTML elements and creates a Texture for each of them.

    • videoElements array or collection of HTML video elements an array or collection of HTML video elements to load into your plane.
  • mouseToPlaneCoords(xMousePosition, yMousePosition): v1.0

    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.

    • xMousePosition float mouse event clientX value.
    • yMousePosition float mouse event clientX value.

    Examples: used in Vertex coordinates helper, Simple plane, Simple video plane, Simple canvas plane examples.

  • moveToFront(): v1.3

    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.

  • planeResize(): v1.0 triggers reflow

    This method is called internally by the Curtains resize() method each time the window is resized, but you should call it manually each time you're updating a plane size, either via CSS animations or directly in javascript. It will updates its position as well.

  • playVideos(): v1.2

    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.

    Examples: used in Simple video plane, Multiple video textures with a displacement shader examples.

  • setPerspective(fieldOfView, nearPlane, farPlane): v1.0

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

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

    Examples: used in Simple plane, Simple video plane, Simple canvas plane examples.

  • setRelativePosition(translationX, translationY): v1.0

    Set the plane translation based on pixel units. Please note that this will not be applied to your plane HTML element, so it's more like an additional translation.
    Note that if you are using a virtual scroll library, you can also use it to update your plane position without causing a reflow and improve performance.

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

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

  • setRotation(angleX, angleY, angleZ): v1.0

    Set the plane rotation.

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

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

  • setScale(scaleX, scaleY): v1.0

    Set the plane new scale.

    • scaleX float the scale to set along the X axis.
    • scaleY float the scale to set along the Y axis.

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

  • updatePosition(): v1.6 triggers reflow

    Internally, the planes positions are updated only when the window is resized. But if you are updating your plane HTML element position without resizing the window (typically while scrolling, animating its CSS position or transform values), call this method in your animation loop at the same time.
    This method calls getBoundingClientRect() therefore causing a reflow/layout repaint of the page. See setRelativePosition to update your plane position without any reflow.

    Examples: used in Multiple planes, Multiple planes scroll effect : rotation, scale and parallax, AJAX navigation with plane removal, Text planes using canvas examples.

Events

  • onAfterResize(): v3.0

    This function will be called each time your plane has been resized, after everything has been updated.

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

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

  • onLeaveView(): v2.0

    This function will be triggered each time a plane leaves the Curtains container viewport area, unless alwaysDraw property is set to true.
    If alwaysDraw property is set to false, an out-of-view plane is not drawn anymore and its textures are no longer updated, but its uniforms are still updated and its onRender callback is still called.
    You might want to pause its videos as well if it contains any.

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

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

  • onLoading(): v1.0

    This function will be fired each time a source element (either an image, a canvas or a video) of the plane has been loaded and is ready to display. Useful to handle a loader.

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

    Examples: used in Asynchronous textures loading example.

  • onReady(): v1.0

    This function will be called once our plane is all set up and ready to be drawn.
    If autoloadSources is set to true, il will be called after the images, canvas and videos are loaded. Otherwise it will be called almost right away.
    This is where you may want to add event listener to interact with your plane or update its uniforms.

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

    Examples: used in most examples.

  • onReEnterView(): v2.0

    This function will be triggered each time a plane reenters the Curtains container viewport area, unless alwaysDraw property is set to true.

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

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

  • onRender(): v1.0

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

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

    Examples: used in most examples.