Merge pull request #5314 from JetStarBlues/improveSpecularColorExample

Improve clarity of `specularColor()` example

Author: stalgiag

src/webgl/light.js

@@ -139,27 +139,45 @@ p5.prototype.ambientLight = function(v1, v2, v3, a) {
  * @example
  * <div>
  * <code>
+ * let setRedSpecularColor = true;
+ *
  * function setup() {
  *   createCanvas(100, 100, WEBGL);
  *   noStroke();
  * }
  *
  * function draw() {
  *   background(0);
- *   shininess(20);
- *   ambientLight(50);
- *   specularColor(255, 0, 0);
- *   pointLight(255, 0, 0, 0, -50, 50);
- *   specularColor(0, 255, 0);
- *   pointLight(0, 255, 0, 0, 50, 50);
- *   specularMaterial(255);
- *   sphere(40);
+ *
+ *   ambientLight(60);
+ *
+ *   // add a point light to showcase specular color
+ *   // -- use mouse location to position the light
+ *   let lightPosX = mouseX - width / 2;
+ *   let lightPosY = mouseY - height / 2;
+ *   // -- set the light's specular color
+ *   if (setRedSpecularColor) {
+ *     specularColor(255, 0, 0); // red specular highlight
+ *   }
+ *   // -- create the light
+ *   pointLight(200, 200, 200, lightPosX, lightPosY, 50); // white light
+ *
+ *   // use specular material with high shininess
+ *   specularMaterial(150);
+ *   shininess(50);
+ *
+ *   sphere(30, 64, 64);
+ * }
+ *
+ * function mouseClicked() {
+ *   setRedSpecularColor = !setRedSpecularColor;
  * }
  * </code>
  * </div>
  *
  * @alt
- * different specular light sources from top and bottom of canvas
+ * Sphere with specular highlight. Clicking the mouse toggles the
+ * specular highlight color between red and the default white.
  */
 
 /**