Adds createFilterShader() and custom shader support to the webGL filter() function

src/image/pixels.js

@@ -307,43 +307,48 @@ p5.prototype._copyHelper = (
 /**
  * Applies a filter to the canvas. The presets options are:
  *
- * THRESHOLD
+ * `THRESHOLD`
  * Converts the image to black and white pixels depending if they are above or
  * below the threshold defined by the level parameter. The parameter must be
  * between 0.0 (black) and 1.0 (white). If no level is specified, 0.5 is used.
  *
- * GRAY
+ * `GRAY`
  * Converts any colors in the image to grayscale equivalents. No parameter
  * is used.
  *
- * OPAQUE
+ * `OPAQUE`
  * Sets the alpha channel to entirely opaque. No parameter is used.
  *
- * INVERT
+ * `INVERT`
  * Sets each pixel to its inverse value. No parameter is used.
  *
- * POSTERIZE
+ * `POSTERIZE`
  * Limits each channel of the image to the number of colors specified as the
  * parameter. The parameter can be set to values between 2 and 255, but
  * results are most noticeable in the lower ranges.
  *
- * BLUR
+ * `BLUR`
  * Executes a Gaussian blur with the level parameter specifying the extent
  * of the blurring. If no parameter is used, the blur is equivalent to
  * Gaussian blur of radius 1. Larger values increase the blur.
  *
- * ERODE
+ * `ERODE`
  * Reduces the light areas. No parameter is used.
  *
- * DILATE
+ * `DILATE`
  * Increases the light areas. No parameter is used.
  *
- * filter() does not work in WEBGL mode.
- * A similar effect can be achieved in WEBGL mode using custom
- * shaders. Adam Ferriss has written
- * a <a href="https://github.com/aferriss/p5jsShaderExamples"
- * target='_blank'>selection of shader examples</a> that contains many
- * of the effects present in the filter examples.
+ * ---
+ *
+ * In WEBGL mode, `filter()` can also accept a shader. The fragment shader
+ * is given a `uniform sampler2D` named `tex0` that contains the current
+ * state of the canvas. For more information on using shaders, check
+ * <a href="https://p5js.org/learn/getting-started-in-webgl-shaders.html">
+ * the introduction to shaders</a> tutorial.
+ *
+ * See also <a href="https://github.com/aferriss/p5jsShaderExamples"
+ * target='_blank'>a selection of shader examples</a> by Adam Ferriss
+ * that contains many similar filter effects.
  *
  * @method filter
  * @param  {Constant} filterType  either THRESHOLD, GRAY, OPAQUE, INVERT,
@@ -458,6 +463,44 @@ p5.prototype._copyHelper = (
  * </code>
  * </div>
  *
+ * <div>
+ * <code>
+ * createCanvas(100, 100, WEBGL);
+ * let myShader = createShader(
+ *   `attribute vec3 aPosition;
+ *   attribute vec2 aTexCoord;
+ *
+ *   varying vec2 vTexCoord;
+ *
+ *   void main() {
+ *     vTexCoord = aTexCoord;
+ *     vec4 positionVec4 = vec4(aPosition, 1.0);
+ *     positionVec4.xy = positionVec4.xy * 2.0 - 1.0;
+ *     gl_Position = positionVec4;
+ *   }`,
+ *   `precision mediump float;
+ *   varying mediump vec2 vTexCoord;
+ *
+ *   uniform sampler2D tex0;
+ *
+ *   float luma(vec3 color) {
+ *     return dot(color, vec3(0.299, 0.587, 0.114));
+ *   }
+ *
+ *   void main() {
+ *     vec2 uv = vTexCoord;
+ *     uv.y = 1.0 - uv.y;
+ *     vec4 sampledColor = texture2D(tex0, uv);
+ *     float gray = luma(sampledColor.rgb);
+ *     gl_FragColor = vec4(gray, gray, gray, 1);
+ *   }`
+ * );
+ * background('RED');
+ * filter(myShader);
+ * describe('a canvas becomes gray after being filtered by shader');
+ * </code>
+ * </div>
+ *
  * @alt
  * black and white image of a brick wall.
  * greyscale image of a brickwall
@@ -468,9 +511,23 @@ p5.prototype._copyHelper = (
  * blurry image of a brickwall
  * image of a brickwall
  * image of a brickwall with less detail
+ * gray square
+ */
+
+/**
+ * @method filter
+ * @param {p5.Shader}  shaderFilter  A shader that's been loaded, with the
+ *                                   frag shader using a `tex0` uniform
  */
 p5.prototype.filter = function(operation, value) {
   p5._validateParameters('filter', arguments);
+
+  // TODO: use shader filters always, and provide an opt out
+  if (this._renderer.isP3D) {
+    p5.RendererGL.prototype.filter.call(this._renderer, arguments);
+    return;
+  }
+
   if (this.canvas !== undefined) {
     Filters.apply(this.canvas, Filters[operation], value);
   } else {

src/webgl/material.js

@@ -183,6 +183,107 @@ p5.prototype.createShader = function(vertSrc, fragSrc) {
   return new p5.Shader(this._renderer, vertSrc, fragSrc);
 };
 
+/**
+ * Creates a new <a href="#/p5.Shader">p5.Shader</a> using only a fragment shader, as a convenience method for creating image effects.
+ * It's like <a href="#/createShader">createShader()</a> but with a default vertex shader included.
+ *
+ * <a href="#/createFilterShader">createFilterShader()</a> is intended to be used along with <a href="#/filter">filter()</a> for filtering the entire contents of a canvas in WebGL mode.
+ *
+ * Note:
+ * - The fragment shader is provided with a single texture input uniform called `tex0`.
+ * This is created specificially for filter shaders to access the canvas contents.
+ *
+ * - A filter shader will not apply to a 3D geometry.
+ *
+ * - Shaders can only be used in `WEBGL` mode.
+ *
+ * For more info about filters and shaders, see Adam Ferriss' <a href="https://github.com/aferriss/p5jsShaderExamples">repo of shader examples</a>
+ * or the <a href="https://p5js.org/learn/getting-started-in-webgl-shaders.html">introduction to shaders</a> page.
+ *
+ * @method createFilterShader
+ * @param {String} fragSrc source code for the fragment shader
+ * @returns {p5.Shader} a shader object created from the provided
+ *                      fragment shader.
+ * @example
+ * <div modernizr='webgl'>
+ * <code>
+ * function setup() {
+ *   let fragSrc = `precision highp float;
+ *   void main() {
+ *     gl_FragColor = vec4(1.0, 1.0, 0.0, 1.0);
+ *   }`;
+ *
+ *   createCanvas(100, 100, WEBGL);
+ *   let s = createFilterShader(fragSrc);
+ *   filter(s);
+ *   describe('a yellow canvas');
+ * }
+ * </code>
+ * </div>
+ *
+ * <div modernizr='webgl'>
+ * <code>
+ * let img, s;
+ * function preload() {
+ *   img = loadImage('assets/bricks.jpg');
+ * }
+ * function setup() {
+ *   let fragSrc = `precision highp float;
+ *
+ *   // x,y coordinates, given from the vertex shader
+ *   varying vec2 vTexCoord;
+ *
+ *   // the canvas contents, given from filter()
+ *   uniform sampler2D tex0;
+ *   // a custom variable from the sketch
+ *   uniform float darkness;
+ *
+ *   void main() {
+ *     // get the color at current pixel
+ *     vec4 color = texture2D(tex0, vTexCoord);
+ *     // set the output color
+ *     color.b = 1.0;
+ *     color *= darkness;
+ *     gl_FragColor = vec4(color.rgb, 1.0);
+ *   }`;
+ *
+ *   createCanvas(100, 100, WEBGL);
+ *   s = createFilterShader(fragSrc);
+ * }
+ * function draw() {
+ *   image(img, -50, -50);
+ *   s.setUniform('darkness', 0.5);
+ *   filter(s);
+ *   describe('a image of bricks tinted dark blue');
+ * }
+ * </code>
+ * </div>
+ */
+p5.prototype.createFilterShader = function(fragSrc) {
+  this._assert3d('createFilterShader');
+  p5._validateParameters('createFilterShader', arguments);
+  let defaultVertSrc = `
+    attribute vec3 aPosition;
+    // texcoords only come from p5 to vertex shader
+    // so pass texcoords on to the fragment shader in a varying variable
+    attribute vec2 aTexCoord;
+    varying vec2 vTexCoord;
+
+    void main() {
+      // transferring texcoords for the frag shader
+      vTexCoord = aTexCoord;
+
+      // copy position with a fourth coordinate for projection (1.0 is normal)
+      vec4 positionVec4 = vec4(aPosition, 1.0);
+      // scale by two and center to achieve correct positioning
+      positionVec4.xy = positionVec4.xy * 2.0 - 1.0;
+
+      gl_Position = positionVec4;
+    }
+  `;
+  return new p5.Shader(this._renderer, defaultVertSrc, fragSrc);
+};
+
 /**
  * Sets the <a href="#/p5.Shader">p5.Shader</a> object to
  * be used to render subsequent shapes.

src/webgl/p5.RendererGL.js

@@ -5,6 +5,7 @@ import './p5.Shader';
 import './p5.Camera';
 import '../core/p5.Renderer';
 import './p5.Matrix';
+import './p5.Framebuffer';
 import { readFileSync } from 'fs';
 import { join } from 'path';
 
@@ -577,6 +578,10 @@ p5.RendererGL = class RendererGL extends p5.Renderer {
     // set of framebuffers in use
     this.framebuffers = new Set();
 
+    // for post processing step
+    this.filterShader = undefined;
+    this.filterGraphicsLayer = undefined;
+
     this.textureMode = constants.IMAGE;
     // default wrap settings
     this.textureWrapX = constants.CLAMP;
@@ -873,12 +878,61 @@ p5.RendererGL = class RendererGL extends p5.Renderer {
     this.curStrokeJoin = join;
   }
 
-  filter(filterType) {
-    // filter can be achieved using custom shaders.
-    // https://github.com/aferriss/p5jsShaderExamples
-    // https://itp-xstory.github.io/p5js-shaders/#/
-    p5._friendlyError('filter() does not work in WEBGL mode');
+  filter(args) {
+    // Couldn't create graphics in RendererGL constructor
+    // (led to infinite loop)
+    // so it's just created here once on the initial filter call.
+    if (!this.filterGraphicsLayer) {
+      // the real _pInst is buried when this is a secondary p5.Graphics
+      const pInst =
+        this._pInst instanceof p5.Graphics ? this._pInst._pInst : this._pInst;
+      // create secondary layer
+      this.filterGraphicsLayer =
+        new p5.Graphics(
+          this.width,
+          this.height,
+          constants.WEBGL,
+          pInst
+        );
+    }
+    let pg = this.filterGraphicsLayer;
+
+    if (typeof args[0] === 'string') {
+      // TODO, handle filter constants:
+      //   this.filterShader = map(args[0], {GRAYSCALE: grayscaleShader, ...})
+      //   filterOperationParameter = undefined or args[1]
+      p5._friendlyError('webgl filter implementation in progress');
+      return;
+    }
+    let userShader = args[0];
+
+    // Copy the user shader once on the initial filter call,
+    // since it has to be bound to pg and not main
+    let isSameUserShader = (
+      this.filterShader !== undefined &&
+      userShader._vertSrc === this.filterShader._vertSrc &&
+      userShader._fragSrc === this.filterShader._fragSrc
+    );
+    if (!isSameUserShader) {
+      this.filterShader =
+        new p5.Shader(pg._renderer, userShader._vertSrc, userShader._fragSrc);
+      this.filterShader.parentShader = userShader;
+    }
+
+    // apply shader to pg
+    pg.shader(this.filterShader);
+    this.filterShader.setUniform('tex0', this);
+    pg.rect(0,0,this.width,this.height);
+
+    // draw pg contents onto main renderer
+    this._pInst.push();
+    this._pInst.noStroke(); // don't draw triangles for plane() geometry
+    this._pInst.scale(1, -1); // vertically flip output
+    this._pInst.texture(pg);
+    this._pInst.plane(this.width, this.height);
+    this._pInst.pop();
   }
+
   blendMode(mode) {
     if (
       mode === constants.DARKEST ||
@@ -1104,6 +1158,11 @@ p5.RendererGL = class RendererGL extends p5.Renderer {
       // can also update their size
       framebuffer._canvasSizeChanged();
     }
+
+    // resize filter graphics layer
+    if (this.filterGraphicsLayer) {
+      p5.Renderer.prototype.resize.call(this.filterGraphicsLayer, w, h);
+    }
   }
 
   /**

src/webgl/p5.Shader.js

@@ -319,6 +319,16 @@ p5.Shader = class {
    * (which run on the GPU) with values from a sketch
    * (which runs on the CPU).
    *
+   * Here are some examples of uniforms you can make:
+   * - booleans
+   *   - Example: `setUniform('x', true)` becomes `uniform float x` with the value `1.0`
+   * - numbers
+   *   - Example: `setUniform('x', -2)` becomes `uniform float x` with the value `-2.0`
+   * - arrays of numbers
+   *   - Example: `setUniform('x', [0, 0.5, 1])` becomes `uniform vec3 x` with the value `vec3(0.0, 0.5, 1.0)`
+   * - a p5.Image, p5.Graphics, p5.MediaElement, or p5.Texture
+   *   - Example: `setUniform('x', img)` becomes `uniform sampler2D x`
+   *
    * @method setUniform
    * @chainable
    * @param {String} uniformName the name of the uniform.
@@ -382,6 +392,13 @@ p5.Shader = class {
    * canvas toggles between a circular gradient of orange and blue vertically. and a circular gradient of red and green moving horizontally when mouse is clicked/pressed.
    */
   setUniform(uniformName, data) {
+    // detect when to set uniforms on duplicate filter shader copy
+    let other = this._renderer.filterShader;
+    if (other !== undefined && other.parentShader === this) {
+      other.setUniform(uniformName, data);
+      return;
+    }
+
     const uniform = this.uniforms[uniformName];
     if (!uniform) {
       return;

test/manual-test-examples/webgl/filter/index.html

@@ -0,0 +1,17 @@
+<!DOCTYPE html>
+<html>
+
+<head>
+  <meta charset="utf-8">
+  <meta http-equiv="X-UA-Compatible" content="IE=edge">
+  <title></title>
+  <link rel="stylesheet" href="../../styles.css">
+  <script language="javascript" type="text/javascript" src="../../../../lib/p5.js"></script>
+  <script language="javascript" type="text/javascript" src="sketch.js"></script>
+  <script src="../stats.js"></script>
+</head>
+
+<body>
+</body>
+
+</html>