Minimal shape docs

src/shape/custom_shapes.js

@@ -825,12 +825,67 @@ class Shape {
     return name + 'Src';
   }
 
-  /*
-  Note: Internally, #bezierOrder is stored as an array, in order to accommodate
-  primitives including Bezier segments, Bezier triangles, and Bezier quads. For example,
-  a segment may have #bezierOrder [m], whereas a quad may have #bezierOrder [m, n].
-   */
 
+  /**
+   * Influences the shape of the Bézier curve segment in a custom shape.
+   * By default, this is 3; the other possible parameter is 2. This
+   * results in quadratic Bézier curves.
+   *
+   * `bezierVertex()` adds a curved segment to custom shapes. The Bézier curves
+   * it creates are defined like those made by the
+   * <a href="#/p5/bezier">bezier()</a> function. `bezierVertex()` must be
+   * called between the
+   * <a href="#/p5/beginShape">beginShape()</a> and
+   * <a href="#/p5/endShape">endShape()</a> functions. There must be at least
+   * one call to <a href="#/p5/vertex">bezierVertex()</a>, before
+   * a number of `bezierVertex()` calls that is a multiple of the parameter
+   * set by <a href="#/p5/bezierOrder">bezierOrder(...)</a> (default 3).
+   * 
+   * Each curve of order 3 requires three calls to `bezierVertex`, so
+   * 2 curves would need 7 calls to `bezierVertex()`:
+   * (1 one initial anchor point, two sets of 3 curves describing the curves)
+   * With `bezierOrder(2)`, two curves would need 5 calls: 1 + 2 + 2. 
+   *
+   * Bézier curves can also be drawn in 3D using WebGL mode.
+   *
+   * Note: `bezierVertex()` won’t work when an argument is passed to
+   * <a href="#/p5/beginShape">beginShape()</a>.
+   *
+   * @method bezierOrder
+   * @param  {Number} order can be either 2 or 3, by default 3
+   * 
+   * @example
+   * <div>
+   * <code>
+   * function setup() {
+   *   createCanvas(100, 100);
+   *
+   *   background(200);
+   *
+   *   // Style the shape.
+   *   noFill();
+   *
+   *   // Start drawing the shape.
+   *   beginShape();
+   * 
+   *   // set the order to 2 for a quadratic Bézier curve
+   *   bezierOrder(2);
+   *
+   *   // Add the first anchor point.
+   *   bezierVertex(30, 20);
+   *
+   *   // Add the Bézier vertex.
+   *   bezierVertex(80, 20);
+   *   bezierVertex(50, 50);
+   *
+   *   // Stop drawing the shape.
+   *   endShape();
+   *
+   *   describe('A black curve drawn on a gray square. The curve starts at the top-left corner and ends at the center.');
+   * }
+   * </code>
+   * </div>
+   */
   bezierOrder(...order) {
     this.#bezierOrder = order;
   }

src/shape/vertex.js

@@ -1,6 +1,6 @@
 /**
  * @module Shape
- * @submodule Vertex
+ * @submodule Custom Shapes
  * @for p5
  * @requires core
  * @requires constants
@@ -30,7 +30,6 @@ function vertex(p5, fn){
    *
    * After calling `beginShape()`, shapes can be built by calling
    * <a href="#/p5/vertex">vertex()</a>,
-   * <a href="#/p5/bezierVertex">bezierVertex()</a>,
    * <a href="#/p5/bezierVertex">bezierVertex()</a>, and/or
    * <a href="#/p5/splineVertex">splineVertex()</a>. Calling
    * <a href="#/p5/endShape">endShape()</a> will stop adding vertices to the
@@ -410,20 +409,23 @@ function vertex(p5, fn){
    * <a href="#/p5/bezier">bezier()</a> function. `bezierVertex()` must be
    * called between the
    * <a href="#/p5/beginShape">beginShape()</a> and
-   * <a href="#/p5/endShape">endShape()</a> functions. The curved segment uses
-   * the previous vertex as the first anchor point, so there must be at least
-   * one call to <a href="#/p5/vertex">vertex()</a> before `bezierVertex()` can
-   * be used.
-   *
-   * The first four parameters, `x2`, `y2`, `x3`, and `y3`, set the curve’s two
-   * control points. The control points "pull" the curve towards them.
-   *
-   * The fifth and sixth parameters, `x4`, and `y4`, set the last anchor point.
-   * The last anchor point is where the curve ends.
-   *
-   * Bézier curves can also be drawn in 3D using WebGL mode. The 3D version of
-   * `bezierVertex()` has eight arguments because each point has x-, y-, and
-   * z-coordinates.
+   * <a href="#/p5/endShape">endShape()</a> functions.
+   * Bézier need a starting point. Building a shape
+   * only wiht Bézier curves needs one initial
+   * call to <a href="#/p5/vertex">bezierVertex()</a>, before
+   * a number of `bezierVertex()` calls that is a multiple of the parameter
+   * set by <a href="#/p5/bezierOrder">bezierOrder(...)</a> (default 3).
+   * But shapes can mix different types of vertices, so if there
+   * are some previous vertizes, then the initial anchor is not needed, 
+   * only the multiples of 3 (or the Bézier order) calls to 
+   *  `bezierVertext` for each curve.
+   * 
+   * Each curve of order 3 requires three calls to `bezierVertext`, so
+   * 2 curves would need 7 calls to `bezierVertex()`:
+   * (1 one initial anchor point, two sets of 3 curves describing the curves)
+   * With `bezierOrder(2)`, two curves would need 5 calls: 1 + 2 + 2. 
+   *
+   * Bézier curves can also be drawn in 3D using WebGL mode.
    *
    * Note: `bezierVertex()` won’t work when an argument is passed to
    * <a href="#/p5/beginShape">beginShape()</a>.
@@ -449,10 +451,12 @@ function vertex(p5, fn){
    *   beginShape();
    *
    *   // Add the first anchor point.
-   *   vertex(30, 20);
+   *   bezierVertex(30, 20);
    *
    *   // Add the Bézier vertex.
-   *   bezierVertex(80, 0, 80, 75, 30, 75);
+   *   bezierVertex(80, 0);
+   *   bezierVertex(80, 75);
+   *   bezierVertex(30, 75);
    *
    *   // Stop drawing the shape.
    *   endShape();
@@ -489,10 +493,12 @@ function vertex(p5, fn){
    *   beginShape();
    *
    *   // Add the first anchor point.
-   *   vertex(30, 20);
+   *   bezierVertex(30, 20);
    *
    *   // Add the Bézier vertex.
-   *   bezierVertex(80, 0, 80, 75, 30, 75);
+   *   bezierVertex(80, 0);
+   *   bezierVertex(80, 75);
+   *   bezierVertex(30, 75);
    *
    *   // Stop drawing the shape.
    *   endShape();
@@ -549,10 +555,12 @@ function vertex(p5, fn){
    *   beginShape();
    *
    *   // Add the first anchor point.
-   *   vertex(30, 20);
+   *   bezierVertex(30, 20);
    *
    *   // Add the Bézier vertex.
-   *   bezierVertex(x2, y2, 80, 75, 30, 75);
+   *   bezierVertex(x2, y2);
+   *   bezierVertex(80, 75);
+   *   bezierVertex(30, 75);
    *
    *   // Stop drawing the shape.
    *   endShape();
@@ -596,11 +604,16 @@ function vertex(p5, fn){
    *   beginShape();
    *
    *   // Add the first anchor point.
-   *   vertex(30, 20);
+   *   bezierVertex(30, 20);
    *
    *   // Add the Bézier vertices.
-   *   bezierVertex(80, 0, 80, 75, 30, 75);
-   *   bezierVertex(50, 80, 60, 25, 30, 20);
+   *   bezierVertex(80, 0);
+   *   bezierVertex(80, 75);
+   *   bezierVertex(30, 75);
+   * 
+   *   bezierVertex(50, 80);
+   *   bezierVertex(60, 25);
+   *   bezierVertex(30, 20);
    *
    *   // Stop drawing the shape.
    *   endShape();
@@ -632,16 +645,30 @@ function vertex(p5, fn){
    *
    *   // Draw the first moon.
    *   beginShape();
-   *   vertex(-20, -30, 0);
-   *   bezierVertex(30, -50, 0, 30, 25, 0, -20, 25, 0);
-   *   bezierVertex(0, 30, 0, 10, -25, 0, -20, -30, 0);
+   *   bezierVertex(-20, -30, 0);
+   * 
+   *   bezierVertex(30, -50, 0);
+   *   bezierVertex(30, 25, 0);
+   *   bezierVertex(-20, 25, 0);
+   * 
+   *   bezierVertex(0, 30, 0);
+   *   bezierVertex(10, -25, 0);
+   *   bezierVertex(-20, -30, 0);
    *   endShape();
    *
    *   // Draw the second moon.
    *   beginShape();
-   *   vertex(-20, -30, -20);
-   *   bezierVertex(30, -50, -20, 30, 25, -20, -20, 25, -20);
-   *   bezierVertex(0, 30, -20, 10, -25, -20, -20, -30, -20);
+   * 
+   *   bezierVertex(-20, -30, -20);
+   * 
+   *   bezierVertex(30, -50, -20);
+   *   bezierVertex(30, 25, -20);
+   *   bezierVertex(-20, 25, -20);
+   * 
+   *   bezierVertex(0, 30, -20);
+   *   bezierVertex(10, -25, -20);
+   *   bezierVertex(-20, -30, -20);
+   * 
    *   endShape();
    * }
    * </code>
@@ -728,7 +755,7 @@ function vertex(p5, fn){
    * Note: `splineVertex()` won’t work when an argument is passed to
    * <a href="#/p5/beginShape">beginShape()</a>.
    *
-   * @method curveVertex
+   * @method splineVertex
    * @param {Number} x x-coordinate of the vertex
    * @param {Number} y y-coordinate of the vertex
    * @chainable
@@ -989,7 +1016,7 @@ function vertex(p5, fn){
    */
 
   /**
-   * @method curveVertex
+   * @method splineVertex
    * @param {Number} x
    * @param {Number} y
    * @param {Number} [z] z-coordinate of the vertex.
@@ -1041,8 +1068,8 @@ function vertex(p5, fn){
    * </code>
    * </div>
    */
-  fn.curveVertex = function(...args) {
-    // p5._validateParameters('curveVertex', args);
+  fn.splineVertex = function(...args) {
+    // p5._validateParameters('splineVertex', args);
     this._renderer.splineVertex(...args);
     return this;
   };
@@ -1069,9 +1096,8 @@ function vertex(p5, fn){
    *
    * After calling <a href="#/p5/beginShape">beginShape()</a>, shapes can be
    * built by calling <a href="#/p5/vertex">vertex()</a>,
-   * <a href="#/p5/bezierVertex">bezierVertex()</a>,
-   * <a href="#/p5/quadraticVertex">quadraticVertex()</a>, and/or
-   * <a href="#/p5/curveVertex">splineVertex()</a>. Calling
+   * <a href="#/p5/bezierVertex">bezierVertex()</a> and/or
+   * <a href="#/p5/splineVertex">splineVertex()</a>. Calling
    * `endShape()` will stop adding vertices to the
    * shape. Each shape will be outlined with the current stroke color and filled
    * with the current fill color.

test/unit/core/vertex.js

@@ -33,10 +33,10 @@ suite('Vertex', function() {
     });
   });
 
-  suite('p5.prototype.curveVertex', function() {
+  suite('p5.prototype.splineVertex', function() {
     test('should be a function', function() {
-      assert.ok(myp5.curveVertex);
-      assert.typeOf(myp5.curveVertex, 'function');
+      assert.ok(myp5.splineVertex);
+      assert.typeOf(myp5.splineVertex, 'function');
     });
   });