Texture class

Basic usage

Creation

Textures are automatically created each time one of the plane loading methods is called.
If your plane autoloadSources initial parameter is set to true, they will be created on initialization for each image, canvas or video children of your plane.

To create a new texture, you should use the createTexture method of your Plane or ShaderPass class object.

// "canvas" is the ID of our HTML container element
var curtains = new Curtains({
container: "canvas"
});
var planeElement = document.getElementById("my-plane");
var plane = curtains.addPlane(planeElement);
// if our plane has been successfully created
if(plane) {
// "myTexture" will be used as a sampler name in your fragment shader
// a uniform mat4 "myTextureMatrix" handling your texture matrix will also be created
var myTexture = plane.createTexture("myTexture");
}

A newly created texture will just display black pixels until you've set it a source from one of the images, canvases or videos already loaded in your plane.

Using texture matrices

Shaders use texture coordinates (or UVs) to map a texture to the plane.
By default the library sets an arbitrary aTextureCoord attributes that you could use in your shaders:

<!-- vertex shader -->
<script id="plane-vs" type="x-shader/x-vertex">
#ifdef GL_ES
precision mediump float;
#endif
// those are the mandatory attributes that the lib sets
attribute vec3 aVertexPosition;
attribute vec2 aTextureCoord;
// those are mandatory uniforms that the lib sets and that contain our model view and projection matrix
uniform mat4 uMVMatrix;
uniform mat4 uPMatrix;
// pass your vertex and texture coords to the fragment shader
varying vec3 vVertexPosition;
varying vec2 vTextureCoord;
void main() {
vec3 vertexPosition = aVertexPosition;
gl_Position = uPMatrix * uMVMatrix * vec4(vertexPosition, 1.0);
// set the varyings
// use our aTextureCoord attributes as texture coords in our fragment shader
vvTextureCoord = aTextureCoord;
vVertexPosition = vertexPosition;
}
</script>
<!-- fragment shader -->
<script id="plane-fs" type="x-shader/x-fragment">
#ifdef GL_ES
precision mediump float;
#endif
// get our varyings
varying vec3 vVertexPosition;
varying vec2 vTextureCoord;
// our texture sampler (default sampler name)
uniform sampler2D uSampler0;
void main() {
// map our texture with the original texture coords
gl_FragColor = texture2D(uSampler0, vTextureCoord);
}
</script>

You may use it to map your texture to your plane, but if the plane and the media aspect ratio are different, you'll end up with a distorted texture.

Fortunately, there's a built-in solution to display your textures without them being distorted: texture matrices. Each time you set a source to a texture (or each time a plane is resized), its texture matrix is automatically computed and sent to your shader as a uniform. With the same example as above, here's how to use it:

<!-- vertex shader -->
<script id="plane-vs" type="x-shader/x-vertex">
#ifdef GL_ES
precision mediump float;
#endif
// those are the mandatory attributes that the lib sets
attribute vec3 aVertexPosition;
attribute vec2 aTextureCoord;
// those are mandatory uniforms that the lib sets and that contain our model view and projection matrix
uniform mat4 uMVMatrix;
uniform mat4 uPMatrix;
// our texture matrix that will handle image cover
uniform mat4 uTextureMatrix0;
// pass your vertex and texture coords to the fragment shader
varying vec3 vVertexPosition;
varying vec2 vTextureCoord;
void main() {
vec3 vertexPosition = aVertexPosition;
gl_Position = uPMatrix * uMVMatrix * vec4(vertexPosition, 1.0);
// set the varyings
// here we use our texture matrix to calculate the accurate texture coords
vvTextureCoord = (uTextureMatrix0 * vec4(aTextureCoord, 0.0, 1.0)).xy;
vVertexPosition = vertexPosition;
}
</script>
<!-- fragment shader -->
<script id="plane-fs" type="x-shader/x-fragment">
#ifdef GL_ES
precision mediump float;
#endif
// get our varyings
varying vec3 vVertexPosition;
varying vec2 vTextureCoord;
// our texture sampler (default sampler name)
uniform sampler2D uSampler0;
void main() {
// map our texture with the texture matrix coords
gl_FragColor = texture2D(uSampler0, vTextureCoord);
}
</script>

The texture matrix uniform name will follow the same rule as the sampler uniform name:
If you did not specify any name, it will be named "uTextureMatrix" + your texture index.
If you did specify a sampler name, it will be named samplerName + "Matrix".

Properties

  • index(integer): v2.0

    The index of your texture in the Plane or ShaderPass textures array.
    Since ShaderPass silently creates a texture on init, if you add a texture to it later, this texture will have an index of 1.

  • scale(object): v2.0

    An object containing the scale applied to your texture on x and y axis. Only applied if you are using the texture matrix to map your texture in your shaders.

  • shouldUpdate(boolean): v2.0

    Depends on your texture type.
    By default, a canvas texture will be updated at each requestAnimationFrame call, a video texture will be updated at 30FPS, and an image texture will never be updated.
    If you want to stop updating your canvas or video texture, set this flag to false for performance boost.

    Examples: used in Text planes using canvas example.

  • source(HTML element): v2.0

    The source used by your texture. Could be either an image, canvas or video HTML element. Use it to safely access any property or method of that element, like play() or pause() for videos.

  • type(string): v2.0

    The type or your texture. Could be either "image", "canvas", "video" or "texturePass".
    A "texturePass" is nothing more than a texture containing the whole scene you are currently drawing. It is created internally with each new ShaderPass.

Methods

  • setSource(sourceElement): v2.0

    Use this method to set a source to your texture. The source must be already loaded in your plane, otherwise use one of the load method of your Plane or ShaderPass classes.

    • sourceElement either an image, canvas or video HTML element a source to apply to your texture. It must be an element already loaded by your plane.

    Examples: used in Slideshow with a displacement shader example.

  • setScale(scaleX, scaleY): v2.0

    Set the texture new scale. Only applied if you are using the texture matrix to map your texture in your shaders.

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