Merge pull request #5316 from JetStarBlues/improveTextureDocumention

Improve documentation clarity of texture methods

src/webgl/material.js

@@ -293,11 +293,21 @@ p5.prototype.resetShader = function() {
 };
 
 /**
- * Texture for geometry.  You can view other possible materials in this
+ * Sets the texture that will be used to render subsequent shapes.
+ *
+ * A texture is like a "skin" that wraps around a 3D geometry. Currently
+ * supported textures are images, video, and offscreen renders.
+ *
+ * To texture a geometry created with <a href="#/p5/beginShape">beginShape()</a>,
+ * you will need to specify uv coordinates in <a href="#/p5/vertex">vertex()</a>.
+ *
+ * Note, texture() can only be used in WEBGL mode.
+ *
+ * You can view more materials in this
  * <a href="https://p5js.org/examples/3d-materials.html">example</a>.
+ *
  * @method texture
- * @param {p5.Image|p5.MediaElement|p5.Graphics} tex 2-dimensional graphics
- *                    to render as texture
+ * @param {p5.Image|p5.MediaElement|p5.Graphics} tex  image to use as texture
  * @chainable
  * @example
  * <div>
@@ -322,7 +332,10 @@ p5.prototype.resetShader = function() {
  * }
  * </code>
  * </div>
+ * @alt
+ * spinning cube with a texture from an image
  *
+ * @example
  * <div>
  * <code>
  * let pg;
@@ -345,7 +358,10 @@ p5.prototype.resetShader = function() {
  * }
  * </code>
  * </div>
+ * @alt
+ * plane with a texture from an image created by createGraphics()
  *
+ * @example
  * <div>
  * <code>
  * let vid;
@@ -371,9 +387,36 @@ p5.prototype.resetShader = function() {
  * </div>
  *
  * @alt
- * Rotating view of many images umbrella and grid roof on a 3d plane
- * black canvas
- * black canvas
+ * rectangle with video as texture
+ *
+ * @example
+ * <div>
+ * <code>
+ * let img;
+ *
+ * function preload() {
+ *   img = loadImage('assets/laDefense.jpg');
+ * }
+ *
+ * function setup() {
+ *   createCanvas(100, 100, WEBGL);
+ * }
+ *
+ * function draw() {
+ *   background(0);
+ *   texture(img);
+ *   textureMode(NORMAL);
+ *   beginShape();
+ *   vertex(-40, -40, 0, 0);
+ *   vertex(40, -40, 1, 0);
+ *   vertex(40, 40, 1, 1);
+ *   vertex(-40, 40, 0, 1);
+ *   endShape();
+ * }
+ * </code>
+ * </div>
+ * @alt
+ * quad with a texture, mapped using normalized coordinates
  */
 p5.prototype.texture = function(tex) {
   this._assert3d('texture');
@@ -396,7 +439,6 @@ p5.prototype.texture = function(tex) {
  * Sets the coordinate space for texture mapping. The default mode is IMAGE
  * which refers to the actual coordinates of the image.
  * NORMAL refers to a normalized space of values ranging from 0 to 1.
- * This function only works in WEBGL mode.
  *
  * With IMAGE, if an image is 100 x 200 pixels, mapping the image onto the entire
  * size of a quad would require the points (0,0) (100, 0) (100,200) (0,200).
@@ -428,10 +470,10 @@ p5.prototype.texture = function(tex) {
  * }
  * </code>
  * </div>
- *
  * @alt
- * the underside of a white umbrella and gridded ceiling above
+ * quad with a texture, mapped using normalized coordinates
  *
+ * @example
  * <div>
  * <code>
  * let img;
@@ -446,7 +488,7 @@ p5.prototype.texture = function(tex) {
  *
  * function draw() {
  *   texture(img);
- *   textureMode(NORMAL);
+ *   textureMode(IMAGE);
  *   beginShape();
  *   vertex(-50, -50, 0, 0);
  *   vertex(50, -50, img.width, 0);
@@ -456,9 +498,8 @@ p5.prototype.texture = function(tex) {
  * }
  * </code>
  * </div>
- *
  * @alt
- * the underside of a white umbrella and gridded ceiling above
+ * quad with a texture, mapped using image coordinates
  */
 p5.prototype.textureMode = function(mode) {
   if (mode !== constants.IMAGE && mode !== constants.NORMAL) {
@@ -472,18 +513,18 @@ p5.prototype.textureMode = function(mode) {
 
 /**
  * Sets the global texture wrapping mode. This controls how textures behave
- * when their uv's go outside of the 0 - 1 range. There are three options:
+ * when their uv's go outside of the 0 to 1 range. There are three options:
  * CLAMP, REPEAT, and MIRROR.
  *
- * CLAMP causes the pixels at the edge of the texture to extend to the bounds
- * REPEAT causes the texture to tile repeatedly until reaching the bounds
- * MIRROR works similarly to REPEAT but it flips the texture with every new tile
+ * CLAMP causes the pixels at the edge of the texture to extend to the bounds.
+ * REPEAT causes the texture to tile repeatedly until reaching the bounds.
+ * MIRROR works similarly to REPEAT but it flips the texture with every new tile.
  *
  * REPEAT & MIRROR are only available if the texture
  * is a power of two size (128, 256, 512, 1024, etc.).
  *
  * This method will affect all textures in your sketch until a subsequent
- * textureWrap call is made.
+ * textureWrap() call is made.
  *
  * If only one argument is provided, it will be applied to both the
  * horizontal and vertical axes.