Skip to content

Improve documetation clarity of material methods #5310

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 3 commits into from
Feb 15, 2022
Merged

Improve documetation clarity of material methods #5310

Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
15e16c6
Improve documetation of material functions
JetStarBlues Jun 14, 2021
beeda4b
Merge branch 'main' into improveMaterialDocumentation
JetStarBlues Oct 17, 2021
f08bf2c
Improve documentation of material functions.
JetStarBlues Oct 17, 2021
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
166 changes: 120 additions & 46 deletions src/webgl/material.js
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
* <a href="https://p5js.org/examples/3d-materials.html">example</a>.
*
* @method normalMaterial
* @chainable
* @example
Expand All @@ -606,7 +612,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');
Expand All @@ -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 <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>
Expand All @@ -640,12 +662,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),
Expand All @@ -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);
* }
* </code>
* </div>
* @alt
* box reflecting only red and blue light
*
* @example
* <div>
* <code>
* // ambientLight is green. Since object does not contain
Expand All @@ -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);
* }
* </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) {
Expand All @@ -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
* <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>
Expand All @@ -731,11 +780,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) {
Expand All @@ -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 <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.
Expand Down Expand Up @@ -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 <a href="#/p5.Color">p5.Color</a>,
* as an array, or as a CSS string
* @chainable
*/
p5.prototype.specularMaterial = function(v1, v2, v3, alpha) {
Expand All @@ -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
* <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>
Expand All @@ -858,7 +932,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');
Expand Down