Merge pull request #5310 from JetStarBlues/improveMaterialDocumentation

Improve documetation clarity of material methods

Author: stalgiag

src/webgl/material.js

@@ -657,11 +657,17 @@ p5.prototype.textureWrap = function(wrapX, wrapY = wrapX) {
 };
 
 /**
- * Normal material for geometry is a material that is not affected by light.
- * It is not reflective and is a placeholder material often used for debugging.
- * Surfaces facing the X-axis, become red, those facing the Y-axis, become green and those facing the Z-axis, become blue.
- * You can view all possible materials in this
+ * Sets the current material as a normal material.
+ *
+ * A normal material is not affected by light. It is often used as
+ * a placeholder material when debugging.
+ *
+ * Surfaces facing the X-axis become red, those facing the Y-axis
+ * become green, and those facing the Z-axis become blue.
+ *
+ * You can view more materials in this
  * <a href="https://p5js.org/examples/3d-materials.html">example</a>.
+ *
  * @method normalMaterial
  * @chainable
  * @example
@@ -679,7 +685,7 @@ p5.prototype.textureWrap = function(wrapX, wrapY = wrapX) {
  * </code>
  * </div>
  * @alt
- * Red, green and blue gradient.
+ * Sphere with normal material
  */
 p5.prototype.normalMaterial = function(...args) {
   this._assert3d('normalMaterial');
@@ -695,14 +701,30 @@ p5.prototype.normalMaterial = function(...args) {
 };
 
 /**
- * Ambient material for geometry with a given color. Ambient material defines the color the object reflects under any lighting.
- * For example, if the ambient material of an object is pure red, but the ambient lighting only contains green, the object will not reflect any light.
- * Here's an <a href="https://p5js.org/examples/3d-materials.html">example containing all possible materials</a>.
- * @method  ambientMaterial
- * @param  {Number} v1  gray value, red or hue value
- *                         (depending on the current color mode),
- * @param  {Number} [v2] green or saturation value
- * @param  {Number} [v3] blue or brightness value
+ * Sets the current material as an ambient material of the given color.
+ *
+ * The ambientMaterial() color is the color the object will reflect
+ * under **any** lighting.
+ *
+ * Consider an ambientMaterial() with the color yellow (255, 255, 0).
+ * If the light emits the color white (255, 255, 255), then the object
+ * will appear yellow as it will reflect the red and green components
+ * of the light. If the light emits the color red (255, 0, 0), then
+ * the object will appear red as it will reflect the red component
+ * of the light. If the light emits the color blue (0, 0, 255),
+ * then the object will appear black, as there is no component of
+ * the light that it can reflect.
+ *
+ * You can view more materials in this
+ * <a href="https://p5js.org/examples/3d-materials.html">example</a>.
+ *
+ * @method ambientMaterial
+ * @param  {Number} v1  red or hue value relative to the current
+ *                       color range
+ * @param  {Number} v2  green or saturation value relative to the
+ *                       current color range
+ * @param  {Number} v3  blue or brightness value relative to the
+ *                       current color range
  * @chainable
  * @example
  * <div>
@@ -713,12 +735,16 @@ p5.prototype.normalMaterial = function(...args) {
  * function draw() {
  *   background(0);
  *   noStroke();
- *   ambientLight(200);
+ *   ambientLight(255);
  *   ambientMaterial(70, 130, 230);
  *   sphere(40);
  * }
  * </code>
  * </div>
+ * @alt
+ * sphere reflecting red, blue, and green light
+ *
+ * @example
  * <div>
  * <code>
  * // ambientLight is both red and blue (magenta),
@@ -728,12 +754,16 @@ p5.prototype.normalMaterial = function(...args) {
  * }
  * function draw() {
  *   background(70);
- *   ambientLight(100); // white light
- *   ambientMaterial(255, 0, 255); // pink material
+ *   ambientLight(255, 0, 255); // magenta light
+ *   ambientMaterial(255); // white material
  *   box(30);
  * }
  * </code>
  * </div>
+ * @alt
+ * box reflecting only red and blue light
+ *
+ * @example
  * <div>
  * <code>
  * // ambientLight is green. Since object does not contain
@@ -744,19 +774,27 @@ p5.prototype.normalMaterial = function(...args) {
  * function draw() {
  *   background(70);
  *   ambientLight(0, 255, 0); // green light
- *   ambientMaterial(255, 0, 255); // pink material
+ *   ambientMaterial(255, 0, 255); // magenta material
  *   box(30);
  * }
  * </code>
  * </div>
  * @alt
- * radiating light source from top right of canvas
- * box reflecting only red and blue light
  * box reflecting no light
  */
+
+/**
+ * @method ambientMaterial
+ * @param  {Number} gray  number specifying value between
+ *                         white and black
+ * @chainable
+ */
+
 /**
- * @method  ambientMaterial
- * @param  {Number[]|String|p5.Color} color  color, color Array, or CSS color string
+ * @method ambientMaterial
+ * @param  {p5.Color|Number[]|String} color
+ *           color as a <a href="#/p5.Color">p5.Color</a>,
+ *            as an array, or as a CSS string
  * @chainable
  */
 p5.prototype.ambientMaterial = function(v1, v2, v3) {
@@ -775,17 +813,28 @@ p5.prototype.ambientMaterial = function(v1, v2, v3) {
 };
 
 /**
- * Sets the emissive color of the material used for geometry drawn to
- * the screen. This is a misnomer in the sense that the material does not
- * actually emit light that effects surrounding polygons. Instead,
- * it gives the appearance that the object is glowing. An emissive material
- * will display at full strength even if there is no light for it to reflect.
+ * Sets the current material as an emissive material of
+ * the given color.
+ *
+ * An emissive material will display the emissive color at
+ * full strength regardless of lighting. This can give the
+ * appearance that the object is glowing.
+ *
+ * Note, "emissive" is a misnomer in the sense that the material
+ * does not actually emit light that will affect surrounding objects.
+ *
+ * You can view more materials in this
+ * <a href="https://p5js.org/examples/3d-materials.html">example</a>.
+ *
  * @method emissiveMaterial
- * @param  {Number} v1  gray value, red or hue value
- *                         (depending on the current color mode),
- * @param  {Number} [v2] green or saturation value
- * @param  {Number} [v3] blue or brightness value
- * @param  {Number} [a]  opacity
+ * @param  {Number} v1       red or hue value relative to the current
+ *                            color range
+ * @param  {Number} v2       green or saturation value relative to the
+ *                            current color range
+ * @param  {Number} v3       blue or brightness value relative to the
+ *                            current color range
+ * @param  {Number} [alpha]  alpha value relative to current color
+ *                            range (default is 0-255)
  * @chainable
  * @example
  * <div>
@@ -804,11 +853,21 @@ p5.prototype.ambientMaterial = function(v1, v2, v3) {
  * </div>
  *
  * @alt
- * radiating light source from top right of canvas
+ * sphere with green emissive material
+ */
+
+/**
+ * @method emissiveMaterial
+ * @param  {Number} gray  number specifying value between
+ *                         white and black
+ * @chainable
  */
+
 /**
- * @method  emissiveMaterial
- * @param  {Number[]|String|p5.Color} color  color, color Array, or CSS color string
+ * @method emissiveMaterial
+ * @param  {p5.Color|Number[]|String} color
+ *           color as a <a href="#/p5.Color">p5.Color</a>,
+ *            as an array, or as a CSS string
  * @chainable
  */
 p5.prototype.emissiveMaterial = function(v1, v2, v3, a) {
@@ -827,11 +886,23 @@ p5.prototype.emissiveMaterial = function(v1, v2, v3, a) {
 };
 
 /**
- * Specular material for geometry with a given color. Specular material is a shiny reflective material.
- * Like ambient material it also defines the color the object reflects under ambient lighting.
- * For example, if the specular material of an object is pure red, but the ambient lighting only contains green, the object will not reflect any light.
- * For all other types of light like point and directional light, a specular material will reflect the color of the light source to the viewer.
- * Here's an <a href="https://p5js.org/examples/3d-materials.html">example containing all possible materials</a>.
+ * Sets the current material as a specular material of the given color.
+ *
+ * A specular material is reflective (shiny). The shininess can be
+ * controlled by the <a href="#/p5/shininess">shininess()</a> function.
+ *
+ * Like <a href="#/p5/ambientMaterial">ambientMaterial()</a>,
+ * the specularMaterial() color is the color the object will reflect
+ * under <a href="#/p5/ambientLight">ambientLight()</a>.
+ * However unlike ambientMaterial(), for all other types of lights
+ * (<a href="#/p5/directionalLight">directionalLight()</a>,
+ * <a href="#/p5/pointLight">pointLight()</a>,
+ * <a href="#/p5/spotLight">spotLight()</a>),
+ * a specular material will reflect the **color of the light source**.
+ * This is what gives it its "shiny" appearance.
+ *
+ * You can view more materials in this
+ * <a href="https://p5js.org/examples/3d-materials.html">example</a>.
  *
  * @method specularMaterial
  * @param  {Number} gray number specifying value between white and black.
@@ -881,7 +952,9 @@ p5.prototype.emissiveMaterial = function(v1, v2, v3, a) {
 
 /**
  * @method specularMaterial
- * @param  {Number[]|String|p5.Color} color color Array, or CSS color string
+ * @param  {p5.Color|Number[]|String} color
+ *           color as a <a href="#/p5.Color">p5.Color</a>,
+ *            as an array, or as a CSS string
  * @chainable
  */
 p5.prototype.specularMaterial = function(v1, v2, v3, alpha) {
@@ -900,12 +973,13 @@ p5.prototype.specularMaterial = function(v1, v2, v3, alpha) {
 };
 
 /**
- * Sets the amount of gloss in the surface of shapes.
- * Used in combination with specularMaterial() in setting
- * the material properties of shapes. The default and minimum value is 1.
+ * Sets the amount of gloss ("shininess") of a
+ * <a href="#/p5/specularMaterial">specularMaterial()</a>.
+ *
+ * The default and minimum value is 1.
+ *
  * @method shininess
- * @param {Number} shine Degree of Shininess.
- *                       Defaults to 1.
+ * @param {Number} shine  degree of shininess
  * @chainable
  * @example
  * <div>
@@ -931,7 +1005,7 @@ p5.prototype.specularMaterial = function(v1, v2, v3, alpha) {
  * </code>
  * </div>
  * @alt
- * Shininess on Camera changes position with mouse
+ * two spheres, one more shiny than the other
  */
 p5.prototype.shininess = function(shine) {
   this._assert3d('shininess');