Minor changes to the wording used in the following material methods, with the goal of improving clarity.

normalMaterial()

1) Reword

Current:

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 example.

Change:

Creates 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.

ambientMaterial()

1) Reword

Current:

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.

Change:

Creates an ambient material with 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.

2) Add variant to improve clarity

Use same parameter descriptions as color() reference.

Current:

ambientMaterial(v1, [v2], [v3])

v1
gray value, red or hue value (depending on the current color mode),

v2
green or saturation value (Optional)

v3
blue or brightness value (Optional)

Change:

ambientMaterial(gray)

ambientMaterial(v1, v2, v3)

gray
Number: number specifying value between white and black

v1
red or hue value relative to the current color range

v2
green or saturation value relative to the current color range

v3
blue or brightness value relative to the current color range

3) Improve clarity

Current:

Number[]|String|p5.Color:
color, color Array, or CSS color string

Change:

p5.Color|Number[]|String:
color as a p5.Color, as an array, or as a CSS string

4) Improve examples

Changes:

example 1:

• Use white (255) as ambientLight color so that output matches expectations. I.e. isolate color effect to just ambientMaterial.

example 2:

• color values currently swapped. Un-swapped to match explanation in comments.

emissiveMaterial()

1) Reword

Current:

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.

Change:

Creates an emissive material with 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.

2) Add link that appears in other materials

You can view more materials in this example.

3) Add variant to improve clarity (and rename a param to alpha)

Use same parameter descriptions as color() reference.

Current:

emissiveMaterial(v1, [v2], [v3], [a])

v1
gray value, red or hue value (depending on the current color mode),

v2
green or saturation value (Optional)

v3
blue or brightness value (Optional)

a
opacity (Optional)

Change:

emissiveMaterial(gray, [alpha])

emissiveMaterial(v1, v2, v3, [alpha])

gray
Number: number specifying value between white and black

v1
red or hue value relative to the current color range

v2
green or saturation value relative to the current color range

v3
blue or brightness value relative to the current color range

alpha
alpha value relative to current color range (default is 0-255) (Optional)

4) Improve clarity

Current:

Number[]|String|p5.Color:
color, color Array, or CSS color string

Change:

p5.Color|Number[]|String:
color as a p5.Color, as an array, or as a CSS string

specularMaterial()

1) Reword

Current:

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.

Change:

Creates a specular material with 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.

2) Improve clarity

Current:

Number[]|String|p5.Color:
color, color Array, or CSS color string

Change:

p5.Color|Number[]|String:
color as a p5.Color, as an array, or as a CSS string

3) Add an example

Change:

Separate PR over here.

shininess()

1) Reword

Current:

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.

Change:

Sets the amount of gloss ("shininess") of a specularMaterial().

The default and minimum value is 1.

Screenshots of the change

normalMaterial

ambientMaterial

emissiveMaterial

specularMaterial

shininess