diff --git a/src/webgl/material.js b/src/webgl/material.js index 4a4b332e7f..23bfaa0f93 100644 --- a/src/webgl/material.js +++ b/src/webgl/material.js @@ -584,11 +584,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 * example. + * * @method normalMaterial * @chainable * @example @@ -606,7 +612,7 @@ p5.prototype.textureWrap = function(wrapX, wrapY = wrapX) { * * * @alt - * Red, green and blue gradient. + * Sphere with normal material */ p5.prototype.normalMaterial = function(...args) { this._assert3d('normalMaterial'); @@ -622,14 +628,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 example containing all possible materials. - * @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 + * example. + * + * @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 *
@@ -640,12 +662,16 @@ p5.prototype.normalMaterial = function(...args) { * function draw() { * background(0); * noStroke(); - * ambientLight(200); + * ambientLight(255); * ambientMaterial(70, 130, 230); * sphere(40); * } * *
+ * @alt + * sphere reflecting red, blue, and green light + * + * @example *
* * // ambientLight is both red and blue (magenta), @@ -655,12 +681,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); * } * *
+ * @alt + * box reflecting only red and blue light + * + * @example *
* * // ambientLight is green. Since object does not contain @@ -671,19 +701,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); * } * *
* @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 p5.Color, + * as an array, or as a CSS string * @chainable */ p5.prototype.ambientMaterial = function(v1, v2, v3) { @@ -702,17 +740,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 + * example. + * * @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 *
@@ -731,11 +780,21 @@ p5.prototype.ambientMaterial = function(v1, v2, v3) { *
* * @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 p5.Color, + * as an array, or as a CSS string * @chainable */ p5.prototype.emissiveMaterial = function(v1, v2, v3, a) { @@ -754,11 +813,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 example containing all possible materials. + * 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 shininess() function. + * + * Like ambientMaterial(), + * the specularMaterial() color is the color the object will reflect + * under ambientLight(). + * However unlike ambientMaterial(), for all other types of lights + * (directionalLight(), + * pointLight(), + * spotLight()), + * 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 + * example. * * @method specularMaterial * @param {Number} gray number specifying value between white and black. @@ -808,7 +879,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 p5.Color, + * as an array, or as a CSS string * @chainable */ p5.prototype.specularMaterial = function(v1, v2, v3, alpha) { @@ -827,12 +900,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 + * specularMaterial(). + * + * 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 *
@@ -858,7 +932,7 @@ p5.prototype.specularMaterial = function(v1, v2, v3, alpha) { * *
* @alt - * Shininess on Camera changes position with mouse + * two spheres, one more shiny than the other */ p5.prototype.shininess = function(shine) { this._assert3d('shininess');