ShaderPass class

Basic usage

Shader passes offers the possibility to add post-processing to your scene. Think of it as an additional plane that would have the size of your WebGL canvas and that would pack your whole scene into a texture and draw it. You'd then be able to manipulate that texture in your fragment shader.

Like the Plane class it 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.
ShaderPass extends the BasePlane class by handling the creation of a frame buffer object and the creation of a render texture.

Creation

To create a shader pass, you will have to use the addShaderPass method of your Curtains class object:

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

Parameters

The code above will create a basic shader pass but you won't be able to do much with it. The addShaderPass method has a 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 params = {
vertexShaderID: "my-shader-pass-vs", // ID of your vertex shader script tag
fragmentShaderID: "my-shader-pass-fs", // ID of your fragment shader script tag
uniforms: { // uniforms are what will allow you to interact with your shader pass
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
},
},
};
var shaderPass = curtains.addShaderPass(params);

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

Shaders

Shader passes uses slightly different vertex and fragment shaders than the Plane objects.

Vertex shader

Since shader passes does not have projection and model view matrices, the default vertex shader is extremly simple.
If you add a new texture to your shader pass, do not forget to handle its matrix in this vertex shader.

// those are the mandatory attributes that the lib sets
attribute vec3 aVertexPosition;
attribute vec2 aTextureCoord;
// pass your vertex and texture coords to the fragment shader
varying vec3 vVertexPosition;
varying vec2 vTextureCoord;
void main() {
gl_Position = vec4(aVertexPosition, 1.0);
// set the varyings
// use our aTextureCoord attributes as texture coords in our fragment shader
vvTextureCoord = aTextureCoord;
vVertexPosition = vertexPosition;
}

Fragment shader

The ShaderPass object automatically creates a texture holding your WebGL scene upon creation. You will have to display that texture to display your scene. If you want to apply any post processing effect, this will be by manipulating this texture.
This texture sampler name is uRenderTexture.

// get our varyings
varying vec3 vVertexPosition;
varying vec2 vTextureCoord;
// our render texture
uniform sampler2D uRenderTexture;
void main() {
// display our render texture, which contains out whole WebGL scene
gl_FragColor = texture2D(uRenderTexture, vTextureCoord);
}

Properties

  • canvases (array): v3.0

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

  • crossOrigin (string): v3.0

    The cross origin process used to load the medias.

  • htmlElement (HTML element): v3.0

    The HTML element used to create your shader pass: your Curtains wrapper container.

  • images (array): v3.0

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

  • index (integer): v3.0

    The index of your shader pass in the Curtains planes array.

  • textures (array): v3.0

    An array containing all the shader pass' Textures already created.

  • uniforms (object): v3.0

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

  • videos (array): v3.0

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

Methods

  • createTexture(samplerName): v3.0

    This function will create a new Texture and add it to our ShaderPass.
    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 shader pass.

    returns: the newly created Texture if successful.

  • 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 Curtains pixelRatio value.

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

  • loadCanvas(canvasElement): v3.0

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

    • canvasElement HTML canvas element a HTML canvas element to load into your shader pass.
  • loadCanvases(canvasElements): v3.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 shader pass.
  • loadImage(imageElement): v3.0

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

    • imageElement HTML image element a HTML image element to load into your shader pass.

    Examples: used in Post processing displacement effect example.

  • loadImages(imageElements): v3.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 shader pass.
  • loadSource(sourceElement): v3.0

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

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

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

    • 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 shader pass.
  • loadVideo(videoElement): v3.0

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

    • videoElement HTML video element a HTML video element to load into your shader pass.
  • loadVideos(videoElements): v3.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 shader pass.
  • mouseToPlaneCoords(xMousePosition, yMousePosition): v3.0

    Get the mouse coordinates relative to the shader pass clip space values. Use it to send to a uniform and interact with your shader pass. A shader pass 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.
  • playVideos(): v3.0

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

Events

  • onAfterResize(): v3.0

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

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

  • onLoading(): v3.0

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

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

    Examples: used in Post processing displacement effect example.

  • onReady(): v3.0

    This function will be called once our shader pass is all set up and ready to be drawn.

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

    Examples: used in Post processing displacement effect example.

  • onRender(): v3.0

    This function will be triggered for each shader pass at each requestAnimationFrame call. Useful to update a time uniform.

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

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