Add more examples, document shader version

Author: davepagurek

src/webgl/material.js

@@ -211,12 +211,21 @@ p5.prototype.loadShader = function (
  * ```
  *
  * Then, in your vertex shader source, you can run a hook by calling a function
- * with the same name prefixed by `HOOK_`:
+ * with the same name prefixed by `HOOK_`. If you want to check if the default
+ * hook has been replaced, maybe to avoid extra overhead, you can check if the
+ * same name prefixed by `AUGMENTED_HOOK_` has been defined:
  *
  * ```glsl
  * void main() {
+ *   // In most cases, just calling the hook is fine:
  *   HOOK_beforeVertex();
- *   // Add the rest ofy our shader code here!
+ *
+ *   // Alternatively, for more efficiency:
+ *   #ifdef AUGMENTED_HOOK_beforeVertex
+ *   HOOK_beforeVertex();
+ *   #endif
+ *
+ *   // Add the rest of your shader code here!
  * }
  * ```
  *
@@ -453,6 +462,75 @@ p5.prototype.loadShader = function (
  * }
  * </code>
  * </div>
+ *
+ * <div>
+ * <code>
+ * // A shader with hooks.
+ * let myShader;
+ *
+ * // A shader with modified hooks.
+ * let modifiedShader;
+ *
+ * // Create a string with the vertex shader program.
+ * // The vertex shader is called for each vertex.
+ * let vertSrc = `
+ * precision highp float;
+ * uniform mat4 uModelViewMatrix;
+ * uniform mat4 uProjectionMatrix;
+ *
+ * attribute vec3 aPosition;
+ * attribute vec2 aTexCoord;
+ *
+ * void main() {
+ *   vec4 positionVec4 = vec4(aPosition, 1.0);
+ *   gl_Position = uProjectionMatrix * uModelViewMatrix * positionVec4;
+ * }
+ * `;
+ *
+ * // Create a fragment shader that uses a hook.
+ * let fragSrc = `
+ * precision highp float;
+ * void main() {
+ *   // Let users override the color
+ *   gl_FragColor = HOOK_getColor(vec4(1., 0., 0., 1.));
+ * }
+ * `;
+ *
+ * function setup() {
+ *   createCanvas(50, 50, WEBGL);
+ *
+ *   // Create a shader with hooks
+ *   myShader = createShader(vertSrc, fragSrc, {
+ *     fragment: {
+ *       'vec4 getColor': '(vec4 color) { return color; }'
+ *     }
+ *   });
+ *
+ *   // Make a version of the shader with a hook overridden
+ *   modifiedShader = myShader.modify({
+ *     'vec4 getColor': `(vec4 color) {
+ *       return vec4(0., 0., 1., 1.);
+ *     }`
+ *   });
+ * }
+ *
+ * function draw() {
+ *   noStroke();
+ *
+ *   push();
+ *   shader(myShader);
+ *   translate(-width/3, 0);
+ *   sphere(10);
+ *   pop();
+ *
+ *   push();
+ *   shader(modifiedShader);
+ *   translate(width/3, 0);
+ *   sphere(10);
+ *   pop();
+ * }
+ * </code>
+ * </div>
  */
 p5.prototype.createShader = function (vertSrc, fragSrc, options) {
   p5._validateParameters('createShader', arguments);
@@ -841,6 +919,9 @@ p5.prototype.shader = function (s) {
  * - `vec4 getFinalColor`: Update the final color after mixing. It takes in a `vec4 color` and must return a modified version.
  * - `void afterFragment`: Called at the end of the fragment shader.
  *
+ * Most of the time, you will need to write your hooks in GLSL ES version 300. If you
+ * are using WebGL 1 instead of 2, write your hooks in GLSL ES 100 instead.
+ *
  * Call `materialShader().inspectHooks()` to see all the possible hooks and
  * their default implementations.
  *
@@ -883,6 +964,41 @@ p5.prototype.shader = function (s) {
  * function setup() {
  *   createCanvas(200, 200, WEBGL);
  *   myShader = materialShader().modify({
+ *     declarations: 'vec3 myNormal;',
+ *     'Inputs getPixelInputs': `(Inputs inputs) {
+ *       myNormal = inputs.normal;
+ *       return inputs;
+ *     }`,
+ *     'vec4 getFinalColor': `(vec4 color) {
+ *       return mix(
+ *         vec4(1.0, 1.0, 1.0, 1.0),
+ *         color,
+ *         abs(dot(myNormal, vec3(0.0, 0.0, 1.0)))
+ *       );
+ *     }`
+ *   });
+ * }
+ *
+ * function draw() {
+ *   background(255);
+ *   rotateY(millis() * 0.001);
+ *   shader(myShader);
+ *   lights();
+ *   noStroke();
+ *   fill('red');
+ *   torus(30);
+ * }
+ * </code>
+ * </div>
+ *
+ * @example
+ * <div modernizr='webgl'>
+ * <code>
+ * let myShader;
+ *
+ * function setup() {
+ *   createCanvas(200, 200, WEBGL);
+ *   myShader = materialShader().modify({
  *     'Inputs getPixelInputs': `(Inputs inputs) {
  *       vec3 newNormal = inputs.normal;
  *       // Simple bump mapping: adjust the normal based on position
@@ -943,6 +1059,9 @@ p5.prototype.materialShader = function() {
  * - `vec4 getFinalColor`: Update the final color after mixing. It takes in a `vec4 color` and must return a modified version.
  * - `void afterFragment`: Called at the end of the fragment shader.
  *
+ * Most of the time, you will need to write your hooks in GLSL ES version 300. If you
+ * are using WebGL 1 instead of 2, write your hooks in GLSL ES 100 instead.
+ *
  * Call `normalShader().inspectHooks()` to see all the possible hooks and
  * their default implementations.
  *
@@ -1030,6 +1149,9 @@ p5.prototype.normalShader = function() {
  * - `vec4 getFinalColor`: Update the final color after mixing. It takes in a `vec4 color` and must return a modified version.
  * - `void afterFragment`: Called at the end of the fragment shader.
  *
+ * Most of the time, you will need to write your hooks in GLSL ES version 300. If you
+ * are using WebGL 1 instead of 2, write your hooks in GLSL ES 100 instead.
+ *
  * Call `colorShader().inspectHooks()` to see all the possible hooks and
  * their default implementations.
  *
@@ -1092,6 +1214,9 @@ p5.prototype.colorShader = function() {
  * - `vec4 getFinalColor`: Update the final color after mixing. It takes in a `vec4 color` and must return a modified version.
  * - `void afterFragment`: Called at the end of the fragment shader.
  *
+ * Most of the time, you will need to write your hooks in GLSL ES version 300. If you
+ * are using WebGL 1 instead of 2, write your hooks in GLSL ES 100 instead.
+ *
  * Call `strokeShader().inspectHooks()` to see all the possible hooks and
  * their default implementations.
  *

src/webgl/p5.Shader.js

@@ -216,6 +216,24 @@ p5.Shader = class {
     return preMain + hooks + main + postMain;
   }
 
+  /**
+   * Shaders are written in <a href="https://developer.mozilla.org/en-US/docs/Games/Techniques/3D_on_the_web/GLSL_Shaders">GLSL</a>, but
+   * there are different versions of GLSL that it might be written in.
+   *
+   * Calling this method on a `p5.Shader` will return the GLSL version it uses, either `100 es` or `300 es`.
+   * WebGL 1 shaders will only use `100 es`, and WebGL 2 shaders may use either.
+   *
+   * @returns {String} The GLSL version used by the shader.
+   */
+  version() {
+    const match = /#version (.+)$/.exec(this.vertSrc());
+    if (match) {
+      return match[1];
+    } else {
+      return '100 es';
+    }
+  }
+
   vertSrc() {
     return this.shaderSrc(this._vertSrc, 'vertex');
   }