From 274dac2f470248abb6932b342f078f184b61e7c8 Mon Sep 17 00:00:00 2001 From: Nick McIntyre Date: Fri, 16 Jun 2023 23:28:48 -0500 Subject: [PATCH 1/5] Edit docs for 2D primitives --- src/core/shape/2d_primitives.js | 316 +++++++++++++++++--------------- 1 file changed, 170 insertions(+), 146 deletions(-) diff --git a/src/core/shape/2d_primitives.js b/src/core/shape/2d_primitives.js index 979b0adb4b..28b5eeced7 100644 --- a/src/core/shape/2d_primitives.js +++ b/src/core/shape/2d_primitives.js @@ -100,28 +100,25 @@ p5.prototype._normalizeArcAngles = ( }; /** - * Draw an arc to the screen. If called with only x, y, w, h, start and stop, - * the arc will be drawn and filled as an open pie segment. If a mode parameter - * is provided, the arc will be filled like an open semi-circle (OPEN), a closed - * semi-circle (CHORD), or as a closed pie segment (PIE). The origin may be changed - * with the ellipseMode() function. - * - * The arc is always drawn clockwise from wherever start falls to wherever stop - * falls on the ellipse. Adding or subtracting TWO_PI to either angle does not - * change where they fall. If both start and stop fall at the same place, a full - * ellipse will be drawn. Be aware that the y-axis increases in the downward - * direction, therefore angles are measured clockwise from the positive - * x-direction ("3 o'clock"). + * Draws an arc to the canvas. Arcs are drawn along the outer edge of an ellipse + * (oval) defined by the x, y, w, and h parameters. Use the start and stop + * parameters to specify the angles (in radians) at which to draw the arc. Arcs are + * always drawn clockwise from start to stop. The origin of the arc's ellipse may + * be changed with the ellipseMode() function. + * + * The optional mode parameter determines the arc's fill style. The modes are a + * semi-circle (OPEN), a closed semi-circle (CHORD), or a closed pie segment + * (PIE). * * @method arc - * @param {Number} x x-coordinate of the arc's ellipse - * @param {Number} y y-coordinate of the arc's ellipse - * @param {Number} w width of the arc's ellipse by default - * @param {Number} h height of the arc's ellipse by default - * @param {Number} start angle to start the arc, specified in radians - * @param {Number} stop angle to stop the arc, specified in radians + * @param {Number} x x-coordinate of the arc's ellipse. + * @param {Number} y y-coordinate of the arc's ellipse. + * @param {Number} w width of the arc's ellipse by default. + * @param {Number} h height of the arc's ellipse by default. + * @param {Number} start angle to start the arc, specified in radians. + * @param {Number} stop angle to stop the arc, specified in radians. * @param {Constant} [mode] optional parameter to determine the way of drawing - * the arc. either CHORD, PIE or OPEN + * the arc. either CHORD, PIE, or OPEN. * @param {Integer} [detail] optional parameter for WebGL mode only. This is to * specify the number of vertices that makes up the * perimeter of the arc. Default value is 25. Won't @@ -137,7 +134,7 @@ p5.prototype._normalizeArcAngles = ( * arc(50, 55, 70, 70, PI, PI + QUARTER_PI); * arc(50, 55, 80, 80, PI + QUARTER_PI, TWO_PI); * describe( - * 'shattered outline of ellipse with a quarter of a white circle bottom-right' + * 'A shattered outline of an ellipse with a quarter of a white circle at the bottom-right.' * ); * * @@ -145,30 +142,30 @@ p5.prototype._normalizeArcAngles = ( *
* * arc(50, 50, 80, 80, 0, PI + QUARTER_PI); - * describe('white ellipse with top right quarter missing'); + * describe('A white ellipse with the top-right third missing. The bottom is outlined in black.'); * *
* *
* * arc(50, 50, 80, 80, 0, PI + QUARTER_PI, OPEN); - * describe('white ellipse with black outline with top right missing'); + * describe( + * 'A white ellipse missing a section from the top-right. The bottom is outlined in black.' + * ); * *
* *
* * arc(50, 50, 80, 80, 0, PI + QUARTER_PI, CHORD); - * describe('white open arc with black outline with top right missing'); + * describe('A white ellipse with a black outline missing a section from the top-right.'); * *
* *
* * arc(50, 50, 80, 80, 0, PI + QUARTER_PI, PIE); - * describe( - * 'white ellipse with top right quarter missing with black outline around the shape' - * ); + * describe('A white ellipse with a black outline. The top-right third is missing.'); * *
* @@ -233,14 +230,15 @@ p5.prototype.arc = function(x, y, w, h, start, stop, mode, detail) { }; /** - * Draws an ellipse (oval) to the screen. By default, the first two parameters - * set the location of the center of the ellipse, and the third and fourth - * parameters set the shape's width and height. If no height is specified, the - * value of width is used for both the width and height. If a negative height or - * width is specified, the absolute value is taken. + * Draws an ellipse (oval) to the canvas. An ellipse with equal width and height + * is a circle. By default, the first two parameters set the location of the + * center of the ellipse. The third and fourth parameters set the shape's width + * and height, respectively. The origin may be changed with the + * ellipseMode() function. * - * An ellipse with equal width and height is a circle. The origin may be changed - * with the ellipseMode() function. + * If no height is specified, the value of width is used for both the width and + * height. If a negative height or width is specified, the absolute value is + * taken. * * @method ellipse * @param {Number} x x-coordinate of the center of the ellipse. @@ -252,7 +250,7 @@ p5.prototype.arc = function(x, y, w, h, start, stop, mode, detail) { *
* * ellipse(56, 46, 55, 55); - * describe('white ellipse with black outline in middle of a gray canvas'); + * describe('A white ellipse with black outline in middle of a gray canvas.'); * *
* @@ -264,7 +262,7 @@ p5.prototype.arc = function(x, y, w, h, start, stop, mode, detail) { * @param {Number} y * @param {Number} w * @param {Number} h - * @param {Integer} [detail] optional parameter for WEBGL mode only. This is to + * @param {Integer} [detail] optional parameter for WebGL mode only. This is to * specify the number of vertices that makes up the * perimeter of the ellipse. Default value is 25. Won't * draw a stroke for a detail of more than 50. @@ -275,14 +273,10 @@ p5.prototype.ellipse = function(x, y, w, h, detailX) { }; /** - * Draws a circle to the screen. A circle is a simple closed shape. It is the set - * of all points in a plane that are at a given distance from a given point, - * the center. This function is a special case of the - * ellipse() function, where the width and height - * of the ellipse are the same. Height and width of the ellipse correspond to - * the diameter of the circle. By default, the first two parameters set the - * location of the center of the circle, the third sets the diameter of the - * circle. + * Draws a circle to the canvas. By default, the first two parameters set the + * location of the center of the circle. The third parameter sets the shape's + * width and height (diameter). The origin may be changed with the + * ellipseMode() function. * * @method circle * @param {Number} x x-coordinate of the center of the circle. @@ -292,9 +286,8 @@ p5.prototype.ellipse = function(x, y, w, h, detailX) { * @example *
* - * // Draw a circle at location (30, 30) with a diameter of 20. * circle(30, 30, 20); - * describe('white circle with black outline in mid of gray canvas'); + * describe('A white circle with black outline in the middle of a gray canvas.'); * *
* @@ -339,25 +332,29 @@ p5.prototype._renderEllipse = function(x, y, w, h, detailX) { }; /** - * Draws a line (a direct path between two points) to the screen. If called with - * only 4 parameters, it will draw a line in 2D with a default width of 1 pixel. - * This width can be modified by using the - * strokeWeight() function. A line cannot be filled, therefore the fill() function will not affect the color of a line. So to - * color a line, use the stroke() function. + * Draws a line (a direct path between two points) to the canvas. The version + * of line() with four parameters draws the line in 2D. To color a line, use the + * stroke() function. To change its width, use the + * strokeWeight() function. A line + * can't be filled, so the fill() function won't affect + * the color of a line. + * + * The version of line() with six parameters allows the line to be drawn in 3D + * space. Doing so requires adding the WEBGL argument to + * createCanvas(). * * @method line - * @param {Number} x1 the x-coordinate of the first point - * @param {Number} y1 the y-coordinate of the first point - * @param {Number} x2 the x-coordinate of the second point - * @param {Number} y2 the y-coordinate of the second point + * @param {Number} x1 the x-coordinate of the first point. + * @param {Number} y1 the y-coordinate of the first point. + * @param {Number} x2 the x-coordinate of the second point. + * @param {Number} y2 the y-coordinate of the second point. * @chainable * @example *
* * line(30, 20, 85, 75); * describe( - * 'a 78 pixels long line running from mid-top to bottom-right of canvas' + * 'A black line on a gray canvas running from top-center to bottom-right.' * ); * *
@@ -370,21 +367,35 @@ p5.prototype._renderEllipse = function(x, y, w, h, detailX) { * stroke(255); * line(85, 75, 30, 75); * describe( - * '3 lines of various stroke colors. Form top, bottom and right sides of a square' + * 'Three lines drawn in grayscale on a gray canvas. They form the top, right, and bottom sides of a square.' * ); * * * + *
+ * + * function setup() { + * createCanvas(100, 100, WEBGL); + * describe('A black line drawn on a gray canvas.'); + * } + * + * function draw() { + * background(220); + * line(0, 0, 0, 10, 10, 0); + * } + * + *
+ * */ /** * @method line * @param {Number} x1 * @param {Number} y1 - * @param {Number} z1 the z-coordinate of the first point + * @param {Number} z1 the z-coordinate of the first point. * @param {Number} x2 * @param {Number} y2 - * @param {Number} z2 the z-coordinate of the second point + * @param {Number} z2 the z-coordinate of the second point. * @chainable */ p5.prototype.line = function(...args) { @@ -403,16 +414,22 @@ p5.prototype.line = function(...args) { }; /** - * Draws a point, a coordinate in space at the dimension of one pixel. - * The first parameter is the horizontal value for the point, the second - * param is the vertical value for the point. The color of the point is - * changed with the stroke() function. The size of the point - * can be changed with the strokeWeight() function. + * Draws a point, a coordinate in space at the dimension of one pixel. The first two + * parameters are the point's x- and y-coordinates, respectively. To color a point, use + * the stroke() function. To change its size, use the + * strokeWeight() function. + * + * The version of point() with three parameters allows the point to be drawn in 3D + * space. Doing so requires adding the WEBGL argument to + * createCanvas(). + * + * The version of point() with one parameter allows the point's location to be set with + * a p5.Vector object. * * @method point - * @param {Number} x the x-coordinate - * @param {Number} y the y-coordinate - * @param {Number} [z] the z-coordinate (for WebGL mode) + * @param {Number} x the x-coordinate. + * @param {Number} y the y-coordinate. + * @param {Number} [z] the z-coordinate (for WebGL mode). * @chainable * @example *
@@ -421,7 +438,9 @@ p5.prototype.line = function(...args) { * point(85, 20); * point(85, 75); * point(30, 75); - * describe('4 points create the corners of a square'); + * describe( + * 'Four small, black points drawn on a gray canvas. The points form the corners of a square.' + * ); * *
* @@ -429,24 +448,28 @@ p5.prototype.line = function(...args) { * * point(30, 20); * point(85, 20); - * stroke('purple'); // Change the color - * strokeWeight(10); // Make the points 10 pixels in size + * stroke('purple'); + * strokeWeight(10); * point(85, 75); * point(30, 75); - * describe('2 points and 2 large purple points in middle-right of canvas'); + * describe( + * 'Four points drawn on a gray canvas. Two are black and two are purple. The points form the corners of a square.' + * ); * * * *
* - * let a = createVector(10, 10); + * const a = createVector(10, 10); * point(a); - * let b = createVector(10, 20); + * const b = createVector(10, 20); * point(b); - * point(createVector(20, 10)); - * point(createVector(20, 20)); + * const c = createVector(20, 10); + * point(c); + * const d = createVector(20, 20); + * point(d); * describe( - * 'four points create vertices of 10x10 pixel square on top-left of canvas' + * 'Four small, black points drawn on a gray canvas. The points form the corners of a square.' * ); * *
@@ -455,7 +478,7 @@ p5.prototype.line = function(...args) { /** * @method point - * @param {p5.Vector} coordinate_vector the coordinate vector + * @param {p5.Vector} coordinateVector the coordinate vector. * @chainable */ p5.prototype.point = function(...args) { @@ -482,30 +505,33 @@ p5.prototype.point = function(...args) { }; /** - * Draws a quad on the canvas. A quad is a quadrilateral, a four-sided polygon. It is - * similar to a rectangle, but the angles between its edges are not - * constrained to ninety degrees. The first pair of parameters (x1,y1) - * sets the first vertex and the subsequent pairs should proceed - * clockwise or counter-clockwise around the defined shape. - * z-arguments only work when quad() is used in WEBGL mode. + * Draws a quad to the canvas. A quad is a quadrilateral, a four-sided polygon. + * It is a general shape that includes rectangles, squares, rhombuses, trapezoids, + * and so on. The first pair of parameters (x1,y1) sets the first point. The + * following pairs should proceed clockwise or counter-clockwise around the defined + * shape. + * + * The version of quad() with twelve arguments allows the quad to be drawn in 3D + * space. Doing so requires adding the WEBGL argument to + * createCanvas(). * * @method quad - * @param {Number} x1 the x-coordinate of the first point - * @param {Number} y1 the y-coordinate of the first point - * @param {Number} x2 the x-coordinate of the second point - * @param {Number} y2 the y-coordinate of the second point - * @param {Number} x3 the x-coordinate of the third point - * @param {Number} y3 the y-coordinate of the third point - * @param {Number} x4 the x-coordinate of the fourth point - * @param {Number} y4 the y-coordinate of the fourth point - * @param {Integer} [detailX] number of segments in the x-direction - * @param {Integer} [detailY] number of segments in the y-direction + * @param {Number} x1 the x-coordinate of the first point. + * @param {Number} y1 the y-coordinate of the first point. + * @param {Number} x2 the x-coordinate of the second point. + * @param {Number} y2 the y-coordinate of the second point. + * @param {Number} x3 the x-coordinate of the third point. + * @param {Number} y3 the y-coordinate of the third point. + * @param {Number} x4 the x-coordinate of the fourth point. + * @param {Number} y4 the y-coordinate of the fourth point. + * @param {Integer} [detailX] number of segments in the x-direction. + * @param {Integer} [detailY] number of segments in the y-direction. * @chainable * @example *
* * quad(38, 31, 86, 20, 69, 63, 30, 76); - * describe('irregular white quadrilateral with black outline'); + * describe('An irregular white quadrilateral with a black outline.'); * *
* @@ -514,16 +540,16 @@ p5.prototype.point = function(...args) { * @method quad * @param {Number} x1 * @param {Number} y1 - * @param {Number} z1 the z-coordinate of the first point + * @param {Number} z1 the z-coordinate of the first point. * @param {Number} x2 * @param {Number} y2 - * @param {Number} z2 the z-coordinate of the second point + * @param {Number} z2 the z-coordinate of the second point. * @param {Number} x3 * @param {Number} y3 - * @param {Number} z3 the z-coordinate of the third point + * @param {Number} z3 the z-coordinate of the third point. * @param {Number} x4 * @param {Number} y4 - * @param {Number} z4 the z-coordinate of the fourth point + * @param {Number} z4 the z-coordinate of the fourth point. * @param {Integer} [detailX] * @param {Integer} [detailY] * @chainable @@ -554,16 +580,20 @@ p5.prototype.quad = function(...args) { }; /** - * Draws a rectangle on the canvas. A rectangle is a four-sided closed shape with - * every angle at ninety degrees. By default, the first two parameters set - * the location of the upper-left corner, the third sets the width, and the - * fourth sets the height. The way these parameters are interpreted may be - * changed with the rectMode() function. + * Draws a rectangle to the canvas. A rectangle is a four-sided polygon with + * every angle at ninety degrees. By default, the first two parameters set the + * location of the upper-left corner. The third and fourth set the shape's the + * width and height, respectively. The way these parameters are interpreted may + * be changed with the rectMode() function. + * + * The version of rect() with five parameters creates a rounded rectangle. The + * fifth parameter is used as the radius value for all four corners. * - * The fifth, sixth, seventh and eighth parameters, if specified, - * determine corner radius for the top-left, top-right, lower-right and - * lower-left corners, respectively. An omitted corner radius parameter is set - * to the value of the previously specified radius value in the parameter list. + * The version of rect() with eight parameters also creates a rounded rectangle. + * When using eight parameters, the latter four set the radius of the arc at + * each corner separately. The radii start with the top-left corner and move + * clockwise around the rectangle. If any of these parameters are omitted, they + * are set to the value of the last specified corner radius. * * @method rect * @param {Number} x x-coordinate of the rectangle. @@ -578,28 +608,24 @@ p5.prototype.quad = function(...args) { * @example *
* - * // Draw a rectangle at location (30, 20) with a width and height of 55. * rect(30, 20, 55, 55); - * describe('white rect with black outline in mid-right of canvas'); + * describe('A white rectangle with a black outline on a gray canvas.'); * *
* *
* - * // Draw a rectangle with rounded corners, each having a radius of 20. * rect(30, 20, 55, 55, 20); * describe( - * 'white rect with black outline and round edges in mid-right of canvas' + * 'A white rectangle with a black outline and round edges on a gray canvas.' * ); * *
* *
* - * // Draw a rectangle with rounded corners having the following radii: - * // top-left = 20, top-right = 15, bottom-right = 10, bottom-left = 5. * rect(30, 20, 55, 55, 20, 15, 10, 5); - * describe('white rect with black outline and round edges of different radii'); + * describe('A white rectangle with a black outline and round edges of different radii.'); * *
* @@ -611,8 +637,8 @@ p5.prototype.quad = function(...args) { * @param {Number} y * @param {Number} w * @param {Number} h - * @param {Integer} [detailX] number of segments in the x-direction (for WebGL mode) - * @param {Integer} [detailY] number of segments in the y-direction (for WebGL mode) + * @param {Integer} [detailX] number of segments in the x-direction (for WebGL mode). + * @param {Integer} [detailY] number of segments in the y-direction (for WebGL mode). * @chainable */ p5.prototype.rect = function(...args) { @@ -621,18 +647,20 @@ p5.prototype.rect = function(...args) { }; /** - * Draws a square to the screen. A square is a four-sided shape with every angle - * at ninety degrees, and equal side size. This function is a special case of the - * rect() function, where the width and height are the same, and the parameter - * is called "s" for side size. By default, the first two parameters set the - * location of the upper-left corner, the third sets the side size of the square. - * The way these parameters are interpreted, may be changed with the rectMode() function. - * - * The fourth, fifth, sixth and seventh parameters, if specified, - * determine corner radius for the top-left, top-right, lower-right and - * lower-left corners, respectively. An omitted corner radius parameter is set - * to the value of the previously specified radius value in the parameter list. + * Draws a square to the canvas. A square is a four-sided polygon with every + * angle at ninety degrees and equal side lengths. By default, the first two + * parameters set the location of the square's upper-left corner. The third + * parameter sets its side size. The way these parameters are interpreted may + * be changed with the rectMode() function. + * + * The version of square() with four parameters creates a rounded square. The + * fourth parameter is used as the radius value for all four corners. + * + * The version of square() with seven parameters also creates a rounded square. + * When using seven parameters, the latter four set the radius of the arc at + * each corner separately. The radii start with the top-left corner and move + * clockwise around the square. If any of these parameters are omitted, they + * are set to the value of the last specified corner radius. * * @method square * @param {Number} x x-coordinate of the square. @@ -646,28 +674,24 @@ p5.prototype.rect = function(...args) { * @example *
* - * // Draw a square at location (30, 20) with a side size of 55. * square(30, 20, 55); - * describe('white square with black outline in mid-right of canvas'); + * describe('A white square with a black outline in on a gray canvas.'); * *
* *
* - * // Draw a square with rounded corners, each having a radius of 20. * square(30, 20, 55, 20); * describe( - * 'white square with black outline and round edges in mid-right of canvas' + * 'A white square with black outline and round edges on a gray canvas.' * ); * *
* *
* - * // Draw a square with rounded corners having the following radii: - * // top-left = 20, top-right = 15, bottom-right = 10, bottom-left = 5. * square(30, 20, 55, 20, 15, 10, 5); - * describe('white square with black outline and round edges of different radii'); + * describe('A white square with a black outline and round edges of different radii.'); * *
* @@ -711,24 +735,24 @@ p5.prototype._renderRect = function() { }; /** - * Draws a triangle to the canvas. A triangle is a plane created by connecting - * three points. The first two arguments specify the first point, the middle two - * arguments specify the second point, and the last two arguments specify the - * third point. + * Draws a triangle to the canvas. A triangle is a three-sided polygon. The + * first two parameters specify the first point (x1,y1). The middle two + * parameters specify the second point (x2,y2). And the last two parameters + * specify the third point (x3, y3). * * @method triangle - * @param {Number} x1 x-coordinate of the first point - * @param {Number} y1 y-coordinate of the first point - * @param {Number} x2 x-coordinate of the second point - * @param {Number} y2 y-coordinate of the second point - * @param {Number} x3 x-coordinate of the third point - * @param {Number} y3 y-coordinate of the third point + * @param {Number} x1 x-coordinate of the first point. + * @param {Number} y1 y-coordinate of the first point. + * @param {Number} x2 x-coordinate of the second point. + * @param {Number} y2 y-coordinate of the second point. + * @param {Number} x3 x-coordinate of the third point. + * @param {Number} y3 y-coordinate of the third point. * @chainable * @example *
* * triangle(30, 75, 58, 20, 86, 75); - * describe('white triangle with black outline in mid-right of canvas'); + * describe('A white triangle with a black outline on a gray canvas.'); * *
* From 55147b5da5d48e5f966892cc197981deaceb6bcb Mon Sep 17 00:00:00 2001 From: Nick McIntyre Date: Sat, 17 Jun 2023 09:45:07 -0500 Subject: [PATCH 2/5] More edits for 2D primitives --- src/core/shape/2d_primitives.js | 28 ++++++++++++++-------------- 1 file changed, 14 insertions(+), 14 deletions(-) diff --git a/src/core/shape/2d_primitives.js b/src/core/shape/2d_primitives.js index 28b5eeced7..ed1e0cf619 100644 --- a/src/core/shape/2d_primitives.js +++ b/src/core/shape/2d_primitives.js @@ -106,9 +106,8 @@ p5.prototype._normalizeArcAngles = ( * always drawn clockwise from start to stop. The origin of the arc's ellipse may * be changed with the ellipseMode() function. * - * The optional mode parameter determines the arc's fill style. The modes are a - * semi-circle (OPEN), a closed semi-circle (CHORD), or a closed pie segment - * (PIE). + * The optional mode parameter determines the arc's fill style. The fill modes are + * a semi-circle (OPEN), a closed semi-circle (CHORD), or a closed pie segment (PIE). * * @method arc * @param {Number} x x-coordinate of the arc's ellipse. @@ -332,9 +331,9 @@ p5.prototype._renderEllipse = function(x, y, w, h, detailX) { }; /** - * Draws a line (a direct path between two points) to the canvas. The version - * of line() with four parameters draws the line in 2D. To color a line, use the - * stroke() function. To change its width, use the + * Draws a line, a straight path between two points. Its default width is one pixel. + * The version of line() with four parameters draws the line in 2D. To color a line, + * use the stroke() function. To change its width, use the * strokeWeight() function. A line * can't be filled, so the fill() function won't affect * the color of a line. @@ -414,7 +413,7 @@ p5.prototype.line = function(...args) { }; /** - * Draws a point, a coordinate in space at the dimension of one pixel. The first two + * Draws a point, a single coordinate in space. Its default size is one pixel. The first two * parameters are the point's x- and y-coordinates, respectively. To color a point, use * the stroke() function. To change its size, use the * strokeWeight() function. @@ -506,7 +505,7 @@ p5.prototype.point = function(...args) { /** * Draws a quad to the canvas. A quad is a quadrilateral, a four-sided polygon. - * It is a general shape that includes rectangles, squares, rhombuses, trapezoids, + * Some examples of quads include rectangles, squares, rhombuses, trapezoids, * and so on. The first pair of parameters (x1,y1) sets the first point. The * following pairs should proceed clockwise or counter-clockwise around the defined * shape. @@ -582,9 +581,10 @@ p5.prototype.quad = function(...args) { /** * Draws a rectangle to the canvas. A rectangle is a four-sided polygon with * every angle at ninety degrees. By default, the first two parameters set the - * location of the upper-left corner. The third and fourth set the shape's the - * width and height, respectively. The way these parameters are interpreted may - * be changed with the rectMode() function. + * location of the rectangle's upper-left corner. The third and fourth set the + * shape's the width and height, respectively. The way these parameters are + * interpreted may be changed with the rectMode() + * function. * * The version of rect() with five parameters creates a rounded rectangle. The * fifth parameter is used as the radius value for all four corners. @@ -736,9 +736,9 @@ p5.prototype._renderRect = function() { /** * Draws a triangle to the canvas. A triangle is a three-sided polygon. The - * first two parameters specify the first point (x1,y1). The middle two - * parameters specify the second point (x2,y2). And the last two parameters - * specify the third point (x3, y3). + * first two parameters specify the triangle's first point (x1,y1). The middle + * two parameters specify its second point (x2,y2). And the last two parameters + * specify its third point (x3, y3). * * @method triangle * @param {Number} x1 x-coordinate of the first point. From 45a8c7912fd1dbee0606959a9e4dc06e52bbf28d Mon Sep 17 00:00:00 2001 From: Nick McIntyre Date: Sat, 17 Jun 2023 12:28:19 -0500 Subject: [PATCH 3/5] Edit docs for shape attributes --- src/core/shape/2d_primitives.js | 38 +++---- src/core/shape/attributes.js | 194 ++++++++++++++------------------ 2 files changed, 102 insertions(+), 130 deletions(-) diff --git a/src/core/shape/2d_primitives.js b/src/core/shape/2d_primitives.js index ed1e0cf619..4eb86d14b0 100644 --- a/src/core/shape/2d_primitives.js +++ b/src/core/shape/2d_primitives.js @@ -101,13 +101,13 @@ p5.prototype._normalizeArcAngles = ( /** * Draws an arc to the canvas. Arcs are drawn along the outer edge of an ellipse - * (oval) defined by the x, y, w, and h parameters. Use the start and stop + * (oval) defined by the `x`, `y`, `w`, and `h` parameters. Use the `start` and `stop` * parameters to specify the angles (in radians) at which to draw the arc. Arcs are - * always drawn clockwise from start to stop. The origin of the arc's ellipse may + * always drawn clockwise from `start` to `stop`. The origin of the arc's ellipse may * be changed with the ellipseMode() function. * - * The optional mode parameter determines the arc's fill style. The fill modes are - * a semi-circle (OPEN), a closed semi-circle (CHORD), or a closed pie segment (PIE). + * The optional `mode` parameter determines the arc's fill style. The fill modes are + * a semi-circle (`OPEN`), a closed semi-circle (`CHORD`), or a closed pie segment (`PIE`). * * @method arc * @param {Number} x x-coordinate of the arc's ellipse. @@ -332,14 +332,14 @@ p5.prototype._renderEllipse = function(x, y, w, h, detailX) { /** * Draws a line, a straight path between two points. Its default width is one pixel. - * The version of line() with four parameters draws the line in 2D. To color a line, + * The version of `line()` with four parameters draws the line in 2D. To color a line, * use the stroke() function. To change its width, use the * strokeWeight() function. A line * can't be filled, so the fill() function won't affect * the color of a line. * - * The version of line() with six parameters allows the line to be drawn in 3D - * space. Doing so requires adding the WEBGL argument to + * The version of `line()` with six parameters allows the line to be drawn in 3D + * space. Doing so requires adding the `WEBGL` argument to * createCanvas(). * * @method line @@ -418,8 +418,8 @@ p5.prototype.line = function(...args) { * the stroke() function. To change its size, use the * strokeWeight() function. * - * The version of point() with three parameters allows the point to be drawn in 3D - * space. Doing so requires adding the WEBGL argument to + * The version of `point()` with three parameters allows the point to be drawn in 3D + * space. Doing so requires adding the `WEBGL` argument to * createCanvas(). * * The version of point() with one parameter allows the point's location to be set with @@ -506,12 +506,12 @@ p5.prototype.point = function(...args) { /** * Draws a quad to the canvas. A quad is a quadrilateral, a four-sided polygon. * Some examples of quads include rectangles, squares, rhombuses, trapezoids, - * and so on. The first pair of parameters (x1,y1) sets the first point. The + * and so on. The first pair of parameters `(x1,y1)` sets the first point. The * following pairs should proceed clockwise or counter-clockwise around the defined * shape. * - * The version of quad() with twelve arguments allows the quad to be drawn in 3D - * space. Doing so requires adding the WEBGL argument to + * The version of `quad()` with twelve parameters allows the quad to be drawn in 3D + * space. Doing so requires adding the `WEBGL` argument to * createCanvas(). * * @method quad @@ -586,10 +586,10 @@ p5.prototype.quad = function(...args) { * interpreted may be changed with the rectMode() * function. * - * The version of rect() with five parameters creates a rounded rectangle. The + * The version of `rect()` with five parameters creates a rounded rectangle. The * fifth parameter is used as the radius value for all four corners. * - * The version of rect() with eight parameters also creates a rounded rectangle. + * The version of `rect()` with eight parameters also creates a rounded rectangle. * When using eight parameters, the latter four set the radius of the arc at * each corner separately. The radii start with the top-left corner and move * clockwise around the rectangle. If any of these parameters are omitted, they @@ -653,10 +653,10 @@ p5.prototype.rect = function(...args) { * parameter sets its side size. The way these parameters are interpreted may * be changed with the rectMode() function. * - * The version of square() with four parameters creates a rounded square. The + * The version of `square()` with four parameters creates a rounded square. The * fourth parameter is used as the radius value for all four corners. * - * The version of square() with seven parameters also creates a rounded square. + * The version of `square()` with seven parameters also creates a rounded square. * When using seven parameters, the latter four set the radius of the arc at * each corner separately. The radii start with the top-left corner and move * clockwise around the square. If any of these parameters are omitted, they @@ -736,9 +736,9 @@ p5.prototype._renderRect = function() { /** * Draws a triangle to the canvas. A triangle is a three-sided polygon. The - * first two parameters specify the triangle's first point (x1,y1). The middle - * two parameters specify its second point (x2,y2). And the last two parameters - * specify its third point (x3, y3). + * first two parameters specify the triangle's first point `(x1,y1)`. The middle + * two parameters specify its second point `(x2,y2)`. And the last two parameters + * specify its third point `(x3, y3)`. * * @method triangle * @param {Number} x1 x-coordinate of the first point. diff --git a/src/core/shape/attributes.js b/src/core/shape/attributes.js index 71fd48a44b..e50b17c577 100644 --- a/src/core/shape/attributes.js +++ b/src/core/shape/attributes.js @@ -10,28 +10,24 @@ import p5 from '../main'; import * as constants from '../constants'; /** - * Modifies the location from which ellipses are drawn by changing the way in - * which parameters given to ellipse(), - * circle() and arc() are interpreted. + * Modifies the location from which ellipses, circles, and arcs are drawn. By default, the + * first two parameters are the x- and y-coordinates of the shape's center. The next + * parameters are its width and height. This is equivalent to calling `ellipseMode(CENTER)`. * - * The default mode is `CENTER`, in which the first two parameters are interpreted - * as the shape's center point's x and y coordinates respectively, while the third - * and fourth parameters are its width and height. + * `ellipseMode(RADIUS)` also uses the first two parameters to set the x- and y-coordinates + * of the shape's center. The next parameters are half of the shapes's width and height. + * Calling `ellipse(0, 0, 10, 15)` draws a shape with a width of 20 and height of 30. * - * `ellipseMode(RADIUS)` also uses the first two parameters as the shape's center - * point's x and y coordinates, but uses the third and fourth parameters to - * specify half of the shapes's width and height. + * `ellipseMode(CORNER)` uses the first two parameters as the upper-left corner of the + * shape. The next parameters are its width and height. * - * `ellipseMode(CORNER)` interprets the first two parameters as the upper-left - * corner of the shape, while the third and fourth parameters are its width - * and height. + * `ellipseMode(CORNERS)` uses the first two parameters as the location of one corner + * of the ellipse's bounding box. The third and fourth parameters are the location of the + * opposite corner. * - * `ellipseMode(CORNERS)` interprets the first two parameters as the location of - * one corner of the ellipse's bounding box, and the third and fourth parameters - * as the location of the opposite corner. - * - * The parameter to this method must be written in ALL CAPS because they are - * predefined as constants in ALL CAPS and Javascript is a case-sensitive language. + * The argument passed to `ellipseMode()` must be written in ALL CAPS because the constants + * `CENTER`, `RADIUS`, `CORNER`, and `CORNERS` are defined this way. JavaScript is a + * case-sensitive language. * * @method ellipseMode * @param {Constant} mode either CENTER, RADIUS, CORNER, or CORNERS @@ -39,31 +35,27 @@ import * as constants from '../constants'; * @example *
* - * // Example showing RADIUS and CENTER ellipsemode with 2 overlaying ellipses * ellipseMode(RADIUS); * fill(255); - * ellipse(50, 50, 30, 30); // Outer white ellipse + * ellipse(50, 50, 30, 30); * ellipseMode(CENTER); * fill(100); - * ellipse(50, 50, 30, 30); // Inner gray ellipse + * ellipse(50, 50, 30, 30); + * describe('A white circle with a gray circle at its center. Both circles have black outlines.'); * *
* *
* - * // Example showing CORNER and CORNERS ellipseMode with 2 overlaying ellipses * ellipseMode(CORNER); * fill(255); - * ellipse(25, 25, 50, 50); // Outer white ellipse + * ellipse(25, 25, 50, 50); * ellipseMode(CORNERS); * fill(100); - * ellipse(25, 25, 50, 50); // Inner gray ellipse + * ellipse(25, 25, 50, 50); + * describe('A white circle with a gray circle at its top-left corner. Both circles have black outlines.'); * *
- * - * @alt - * 60×60 white ellipse and 30×30 grey ellipse with black outlines at center. - * 60×60 white ellipse and 30×30 grey ellipse top-right with black outlines. */ p5.prototype.ellipseMode = function(m) { p5._validateParameters('ellipseMode', arguments); @@ -81,13 +73,11 @@ p5.prototype.ellipseMode = function(m) { /** * Draws all geometry with jagged (aliased) edges. * - * Note that smooth() is active by default in 2D mode, so it is - * necessary to call noSmooth() to disable smoothing of geometry, - * images, and fonts. + * smooth() is active by default in 2D mode. It's necessary to call + * noSmooth() to disable smoothing of geometry, images, and fonts. * - * In 3D mode, noSmooth() is enabled by default, so it is necessary - * to call smooth() if you would like smooth (antialiased) edges on your - * geometry. + * In WebGL mode, noSmooth() is active by default. It's necessary + * to call smooth() to draw smooth (antialiased) edges. * * @method noSmooth * @chainable @@ -100,11 +90,9 @@ p5.prototype.ellipseMode = function(m) { * ellipse(30, 48, 36, 36); * noSmooth(); * ellipse(70, 48, 36, 36); + * describe('Two pixelated white circles on a black background.'); * * - * - * @alt - * 2 pixelated 36×36 white ellipses to left & right of center, black background */ p5.prototype.noSmooth = function() { if (!this._renderer.isP3D) { @@ -118,28 +106,25 @@ p5.prototype.noSmooth = function() { }; /** - * Modifies the location from which rectangles are drawn by changing the way - * in which parameters given to rect() are interpreted. + * Modifies the location from which rectangles and squares are drawn. By default, + * the first two parameters are the x- and y-coordinates of the shape's upper-left + * corner. The next parameters are its width and height. This is equivalent to + * calling `rectMode(CORNER)`. * - * The default mode is `CORNER`, which interprets the first two parameters as the - * upper-left corner of the shape, while the third and fourth parameters are its - * width and height. - * - * `rectMode(CORNERS)` interprets the first two parameters as the location of - * one of the corners, and the third and fourth parameters as the location of - * the diagonally opposite corner. Note, the rectangle is drawn between the - * coordinates, so it is not necessary that the first corner be the upper left + * `rectMode(CORNERS)` also uses the first two parameters as the location of one of + * the corners. The third and fourth parameters are the location of the opposite * corner. * - * `rectMode(CENTER)` interprets the first two parameters as the shape's center - * point, while the third and fourth parameters are its width and height. + * `rectMode(CENTER)` uses the first two parameters as the x- and y-coordinates of + * the shape's center. The next parameters are its width and height. * - * `rectMode(RADIUS)` also uses the first two parameters as the shape's center - * point, but uses the third and fourth parameters to specify half of the shape's - * width and height respectively. + * `rectMode(RADIUS)` also uses the first two parameters as the x- and y-coordinates + * of the shape's center. The next parameters are half of the shape's width and + * height. * - * The parameter to this method must be written in ALL CAPS because they are - * predefined as constants in ALL CAPS and Javascript is a case-sensitive language. + * The argument passed to `rectMode()` must be written in ALL CAPS because the + * constants `CENTER`, `RADIUS`, `CORNER`, and `CORNERS` are defined this way. + * JavaScript is a case-sensitive language. * * @method rectMode * @param {Constant} mode either CORNER, CORNERS, CENTER, or RADIUS @@ -149,11 +134,13 @@ p5.prototype.noSmooth = function() { * * rectMode(CORNER); * fill(255); - * rect(25, 25, 50, 50); // Draw white rectangle using CORNER mode + * rect(25, 25, 50, 50); * * rectMode(CORNERS); * fill(100); - * rect(25, 25, 50, 50); // Draw gray rectangle using CORNERS mode + * rect(25, 25, 50, 50); + * + * describe('A small gray square drawn at the top-left corner of a white square.'); * * * @@ -161,17 +148,15 @@ p5.prototype.noSmooth = function() { * * rectMode(RADIUS); * fill(255); - * rect(50, 50, 30, 30); // Draw white rectangle using RADIUS mode + * rect(50, 50, 30, 30); * * rectMode(CENTER); * fill(100); - * rect(50, 50, 30, 30); // Draw gray rectangle using CENTER mode + * rect(50, 50, 30, 30); + * + * describe('A small gray square drawn at the center of a white square.'); * * - * - * @alt - * 50×50 white rect at center and 25×25 grey rect in the top left of the other. - * 50×50 white rect at center and 25×25 grey rect in the center of the other. */ p5.prototype.rectMode = function(m) { p5._validateParameters('rectMode', arguments); @@ -190,13 +175,11 @@ p5.prototype.rectMode = function(m) { * Draws all geometry with smooth (anti-aliased) edges. smooth() will also * improve image quality of resized images. * - * Note that smooth() is active by default in 2D mode; - * noSmooth() can be used to disable smoothing of geometry, - * images, and fonts. + * smooth() is active by default in 2D mode. It's necessary to call + * noSmooth() to disable smoothing of geometry, images, and fonts. * - * In 3D mode, noSmooth() is enabled by default, so it is - * necessary to call smooth() if you would like smooth (antialiased) - * edges on your geometry. + * In WebGL mode, noSmooth() is active by default. It's necessary + * to call smooth() to draw smooth (antialiased) edges. * * @method smooth * @chainable @@ -209,11 +192,9 @@ p5.prototype.rectMode = function(m) { * ellipse(30, 48, 36, 36); * noSmooth(); * ellipse(70, 48, 36, 36); + * describe('Two pixelated white circles on a black background.'); * * - * - * @alt - * 2 pixelated 36×36 white ellipses one left one right of center. On black. */ p5.prototype.smooth = function() { this.setAttributes('antialias', true); @@ -226,12 +207,13 @@ p5.prototype.smooth = function() { }; /** - * Sets the style for rendering line endings. These ends are either rounded, - * squared, or extended, each of which specified with the corresponding - * parameters: `ROUND`, `SQUARE`, or `PROJECT`. The default cap is `ROUND`. + * Sets the style for rendering line endings. These ends are either rounded + * (`ROUND`), squared (`SQUARE`), or extended (`PROJECT`). The default cap is + * `ROUND`. * - * The parameter to this method must be written in ALL CAPS because they are - * predefined as constants in ALL CAPS and Javascript is a case-sensitive language. + * The argument passed to `strokeCap()` must be written in ALL CAPS because + * the constants `ROUND`, `SQUARE`, and `PROJECT` are defined this way. + * JavaScript is a case-sensitive language. * * @method strokeCap * @param {Constant} cap either ROUND, SQUARE, or PROJECT @@ -239,7 +221,6 @@ p5.prototype.smooth = function() { * @example *
* - * // Example of different strokeCaps * strokeWeight(12.0); * strokeCap(ROUND); * line(20, 30, 80, 30); @@ -247,11 +228,9 @@ p5.prototype.smooth = function() { * line(20, 50, 80, 50); * strokeCap(PROJECT); * line(20, 70, 80, 70); + * describe('Three horizontal lines. The top line has rounded ends, the middle line has squared ends, and the bottom line has longer, squared ends.'); * *
- * - * @alt - * 3 lines. Top line: rounded ends, mid: squared, bottom:longer squared ends. */ p5.prototype.strokeCap = function(cap) { p5._validateParameters('strokeCap', arguments); @@ -266,13 +245,13 @@ p5.prototype.strokeCap = function(cap) { }; /** - * Sets the style of the joints which connect line segments. These joints - * are either mitered, beveled, or rounded and specified with the - * corresponding parameters: `MITER`, `BEVEL`, or `ROUND`. The default joint is - * `MITER` in 2D mode and `ROUND` in WebGL mode. + * Sets the style of the joints which connect line segments. These joints are + * either mitered (`MITER`), beveled (`BEVEL`), or rounded (`ROUND`). The default + * joint is `MITER` in 2D mode and `ROUND` in WebGL mode. * - * The parameter to this method must be written in ALL CAPS because they are - * predefined as constants in ALL CAPS and Javascript is a case-sensitive language. + * The argument passed to `strokeJoin()` must be written in ALL CAPS because + * the constants `MITER`, `BEVEL`, and `ROUND` are defined this way. + * JavaScript is a case-sensitive language. * * @method strokeJoin * @param {Constant} join either MITER, BEVEL, or ROUND @@ -280,7 +259,6 @@ p5.prototype.strokeCap = function(cap) { * @example *
* - * // Example of MITER type of joints * noFill(); * strokeWeight(10.0); * strokeJoin(MITER); @@ -289,12 +267,12 @@ p5.prototype.strokeCap = function(cap) { * vertex(65, 50); * vertex(35, 80); * endShape(); + * describe('A right-facing arrowhead shape with a pointed tip in center of canvas.'); * *
* *
* - * // Example of BEVEL type of joints * noFill(); * strokeWeight(10.0); * strokeJoin(BEVEL); @@ -303,12 +281,12 @@ p5.prototype.strokeCap = function(cap) { * vertex(65, 50); * vertex(35, 80); * endShape(); + * describe('A right-facing arrowhead shape with a flat tip in center of canvas.'); * *
* *
* - * // Example of ROUND type of joints * noFill(); * strokeWeight(10.0); * strokeJoin(ROUND); @@ -317,13 +295,9 @@ p5.prototype.strokeCap = function(cap) { * vertex(65, 50); * vertex(35, 80); * endShape(); + * describe('A right-facing arrowhead shape with a rounded tip in center of canvas.'); * *
- * - * @alt - * Right-facing arrowhead shape with pointed tip in center of canvas. - * Right-facing arrowhead shape with flat tip in center of canvas. - * Right-facing arrowhead shape with rounded tip in center of canvas. */ p5.prototype.strokeJoin = function(join) { p5._validateParameters('strokeJoin', arguments); @@ -341,40 +315,38 @@ p5.prototype.strokeJoin = function(join) { * Sets the width of the stroke used for lines, points, and the border around * shapes. All widths are set in units of pixels. * - * Note that it is affected by any transformation or scaling that has - * been applied previously. + * Note that `strokeWeight()` is affected by any transformation or scaling that + * has been applied previously. * * @method strokeWeight - * @param {Number} weight the weight of the stroke (in pixels) + * @param {Number} weight the weight of the stroke (in pixels). * @chainable * @example *
* - * // Example of different stroke weights - * strokeWeight(1); // Default + * // Default. * line(20, 20, 80, 20); - * strokeWeight(4); // Thicker + * // Thicker. + * strokeWeight(4); * line(20, 40, 80, 40); - * strokeWeight(10); // Beastly + * // Beastly. + * strokeWeight(10); * line(20, 70, 80, 70); + * describe('Three horizontal black lines. The top line is thin, the middle is medium, and the bottom is thick.'); * *
* *
* - * //Example of stroke weights - * //after transformations - * strokeWeight(1); // Default + * // Default. * line(20, 20, 80, 20); - * scale(5); // Adding scale transformation - * strokeWeight(1); // Resulting strokeweight is 5 - * line(4, 8, 16, 8); // Coordinates adjusted for scaling + * // Adding scale transformation. + * scale(5); + * // Coordinates adjusted for scaling. + * line(4, 8, 16, 8); + * describe('Two horizontal black lines. The top line is thin and the bottom is five times thicker than the top.'); * *
- * - * @alt - * 3 horizontal black lines. Top line: thin, mid: medium, bottom:thick. - * 2 horizontal black line. Top line: thin, botton line: 5 times thicker than top */ p5.prototype.strokeWeight = function(w) { p5._validateParameters('strokeWeight', arguments); From c825d4716bbd38d62e63a3a324a48eebb9a03acc Mon Sep 17 00:00:00 2001 From: Nick McIntyre Date: Sat, 17 Jun 2023 16:16:39 -0500 Subject: [PATCH 4/5] Add more detail to circle docs --- src/core/shape/2d_primitives.js | 9 +++++---- 1 file changed, 5 insertions(+), 4 deletions(-) diff --git a/src/core/shape/2d_primitives.js b/src/core/shape/2d_primitives.js index 4eb86d14b0..c416027e78 100644 --- a/src/core/shape/2d_primitives.js +++ b/src/core/shape/2d_primitives.js @@ -272,10 +272,11 @@ p5.prototype.ellipse = function(x, y, w, h, detailX) { }; /** - * Draws a circle to the canvas. By default, the first two parameters set the - * location of the center of the circle. The third parameter sets the shape's - * width and height (diameter). The origin may be changed with the - * ellipseMode() function. + * Draws a circle to the canvas. A circle is a round shape. Every point on the + * edge of a circle is the same distance from its center. By default, the first + * two parameters set the location of the center of the circle. The third + * parameter sets the shape's width and height (diameter). The origin may be + * changed with the ellipseMode() function. * * @method circle * @param {Number} x x-coordinate of the center of the circle. From 28e5b7d60261d00e86a9650d4347ca10efc5a853 Mon Sep 17 00:00:00 2001 From: Nick McIntyre Date: Sun, 18 Jun 2023 12:49:45 -0500 Subject: [PATCH 5/5] Add code samples for quad() --- src/core/shape/2d_primitives.js | 43 ++++++++++++++++++++++++--------- 1 file changed, 32 insertions(+), 11 deletions(-) diff --git a/src/core/shape/2d_primitives.js b/src/core/shape/2d_primitives.js index c416027e78..4083867027 100644 --- a/src/core/shape/2d_primitives.js +++ b/src/core/shape/2d_primitives.js @@ -505,14 +505,15 @@ p5.prototype.point = function(...args) { }; /** - * Draws a quad to the canvas. A quad is a quadrilateral, a four-sided polygon. - * Some examples of quads include rectangles, squares, rhombuses, trapezoids, - * and so on. The first pair of parameters `(x1,y1)` sets the first point. The - * following pairs should proceed clockwise or counter-clockwise around the defined - * shape. - * - * The version of `quad()` with twelve parameters allows the quad to be drawn in 3D - * space. Doing so requires adding the `WEBGL` argument to + * Draws a quad to the canvas. A quad is a quadrilateral, a four-sided + * polygon. Some examples of quads include rectangles, squares, rhombuses, + * and trapezoids. The first pair of parameters (`x1`,`y1`) sets the quad's + * first point. The following pairs of parameters set the coordinates for + * its next three points. Parameters should proceed clockwise or + * counter-clockwise around the shape. + * + * The version of `quad()` with twelve parameters allows the quad to be drawn + * in 3D space. Doing so requires adding the `WEBGL` argument to * createCanvas(). * * @method quad @@ -530,11 +531,31 @@ p5.prototype.point = function(...args) { * @example *
* - * quad(38, 31, 86, 20, 69, 63, 30, 76); - * describe('An irregular white quadrilateral with a black outline.'); + * quad(20, 20, 80, 20, 80, 80, 20, 80); + * describe('A white square with a black outline drawn on a gray canvas.'); + * + *
+ * + *
+ * + * quad(20, 30, 80, 30, 80, 70, 20, 70); + * describe('A white rectangle with a black outline drawn on a gray canvas.'); + * + *
+ * + *
+ * + * quad(50, 62, 86, 50, 50, 38, 14, 50); + * describe('A white rhombus with a black outline drawn on a gray canvas.'); * *
* + *
+ * + * quad(20, 50, 80, 30, 80, 70, 20, 70); + * describe('A white trapezoid with a black outline drawn on a gray canvas.'); + * + *
*/ /** * @method quad @@ -684,7 +705,7 @@ p5.prototype.rect = function(...args) { * * square(30, 20, 55, 20); * describe( - * 'A white square with black outline and round edges on a gray canvas.' + * 'A white square with a black outline and round edges on a gray canvas.' * ); * *