{% extends "base.html" %} {% set baseurl = ".." %} {% block header %} {% endblock %} {% block content %}

Overview

This library provides realtime image effects using WebGL. There are three parts to glfx.js:

There are two caveats to glfx.js. First, WebGL is a new technology that is only available in the latest browsers and it will be quite a while before the majority of users have it. Second, due to the same origin policy, JavaScript is only allowed to read images that originate from the same domain as the script reading them, so you may have to host the images you modify.

Quick Start

This HTML fragment is all you need to use the API. Copy and paste it into an empty index.html document, make sure that directory also contains glfx.js and an image named image.jpg, and open index.html. You should see the image with the ink filter applied.

<script src="glfx.js"></script>
<script>

window.onload = function() {
    // try to create a WebGL canvas (will fail if WebGL isn't supported)
    try {
        var canvas = fx.canvas();
    } catch (e) {
        alert(e);
        return;
    }

    // convert the image to a texture
    var image = document.getElementById('image');
    var texture = canvas.texture(image);

    // apply the ink filter
    canvas.draw(texture).ink(0.25).update();

    // replace the image with the canvas
    image.parentNode.insertBefore(canvas, image);
    image.parentNode.removeChild(image);

    // Note: instead of swapping the <canvas> tag with the <img> tag
    // as done above, we could have just transferred the contents of
    // the image directly:
    //
    //     image.src = canvas.toDataURL('image/png');
    //
    // This has two disadvantages. First, it is much slower, so it
    // would be a bad idea to do this repeatedly. If you are going
    // to be repeatedly updating a filter it's much better to use
    // the <canvas> tag directly. Second, this requires that the
    // image is hosted on the same domain as the script because
    // JavaScript has direct access to the image contents. When the
    // two tags were swapped using the previous method, JavaScript
    // actually doesn't have access to the image contents and this
    // does not violate the same origin policy.
};

</script>
<img id="image" src="image.jpg">

Core API

Canvas Constructor

var canvas = fx.canvas();

Before you can apply any filters you will need a canvas, which stores the result of the filters you apply. Canvas creation is done through fx.canvas(), which creates and returns a new WebGL <canvas> tag with additional methods specific to glfx.js. This call will throw an error message if the browser doesn't support WebGL.

Draw Image

canvas.draw(texture);

This replaces the internal contents of the canvas with the image stored in texture. All filter operations take place in a chain that starts with canvas.draw() and ends with canvas.update().

texture Stores image data, the result of calling fx.texture().

Update Screen

canvas.update();

This replaces the visible contents of the canvas with the internal image result. For efficiency reasons, the internal image buffers are not rendered to the screen every time a filter is applied, so you will need to call update() on your canvas after you have finished applying the filters to be able to see the result. All filter operations take place in a chain that starts with canvas.draw() and ends with canvas.update().

Texture Constructor

var texture = canvas.texture(element);

Creates a texture that initially stores the image from an HTML element. Notice that texture() is a method on a canvas object, which means if you want to use the same image on two canvas objects you will need two different textures, one for each canvas.

element The HTML element to store in the texture, either an <img>, a <canvas>, or a <video>.

Update Texture

texture.loadContentsOf(element);

Loads the image from an HTML element into the texture. This is more efficient than repeatedly creating and destroying textures.

element The HTML element to store in the texture, either an <img>, a <canvas>, or a <video>.

Destroy Texture

texture.destroy();

Textures will be garbage collected eventually when they are no longer referenced, but this method will free GPU resources immediately.

Filters

All filters are methods on a canvas object and modify the image that is currently on the canvas. This means you will have to draw() a texture on the canvas before you can apply a filter to it. For efficiency reasons, the internal image buffers are not rendered to the screen every time a filter is applied, so you will need to call update() on your canvas after you have finished applying the filters to be able to see the result. For an example, please see the Quick Start section above.
{{ docs }} {% endblock %}