Skip to content

Commit

Permalink
Merge pull request #6226 from zelf0/edit-color-inline
Browse files Browse the repository at this point in the history
Edit color setting docs. Addresses #6219
nickmcintyre authored Jul 5, 2023

Verified

This commit was created on GitHub.com and signed with GitHub’s verified signature. The key has expired.
2 parents ab81552 + 1bfab71 commit a74bc5c
Showing 1 changed file with 316 additions and 270 deletions.
586 changes: 316 additions & 270 deletions src/color/setting.js
Original file line number Diff line number Diff line change
@@ -11,25 +11,27 @@ import * as constants from '../core/constants';
import './p5.Color';

/**
* The <a href="#/p5/background">background()</a> function sets the color used
* for the background of the p5.js canvas. The default background is transparent.
* This function is typically used within <a href="#/p5/draw">draw()</a> to clear
* the display window at the beginning of each frame, but it can be used inside
* <a href="#/p5/setup">setup()</a> to set the background on the first frame of
* animation or if the background need only be set once.
*
* The color is either specified in terms of the RGB, HSB, or HSL color depending
* on the current <a href="#/p5/colorMode">colorMode</a>. (The default color space
* is RGB, with each value in the range from 0 to 255). The alpha range by default
* is also 0 to 255.<br><br>
*
* If a single string argument is provided, RGB, RGBA and Hex CSS color strings
* and all named color strings are supported. In this case, an alpha number
* value as a second argument is not supported, the RGBA form should be used.
*
* A <a href="#/p5.Color">p5.Color</a> object can also be provided to set the background color.
*
* A <a href="#/p5.Image">p5.Image</a> can also be provided to set the background image.
* Sets the color used for the background of the canvas. By default, the
* background is transparent. This function is typically used within
* <a href="#/p5/draw">draw()</a> to clear the display window at the beginning
* of each frame. It can also be used inside <a href="#/p5/setup">setup()</a> to
* set the background on the first frame of animation.
*
* The version of `background()` with one parameter interprets the value one of four
* ways. If the parameter is a number, it's interpreted as a grayscale value.
* If the parameter is a string, it's interpreted as a CSS color string. RGB, RGBA,
* HSL, HSLA, hex, and named color strings are supported. If the parameter is a
* <a href="#/p5.Color">p5.Color</a> object, it will be used as the background color.
* If the parameter is a <a href="#/p5.Image">p5.Image</a> object, it will be used as
* the background image.
*
* The version of `background()` with two parameters interprets the first one as a
* grayscale value. The second parameter sets the alpha (transparency) value.
*
* The version of `background()` with three parameters interprets them as RGB, HSB,
* or HSL colors, depending on the current <a href="#/p5/colorMode">colorMode()</a>.
* By default, colors are specified in RGB values. Calling background(255, 204, 0)
* sets the background a bright yellow color.
*
* @method background
* @param {p5.Color} color any value created by the <a href="#/p5/color">color()</a> function
@@ -38,90 +40,99 @@ import './p5.Color';
* @example
* <div>
* <code>
* // Grayscale integer value
* // A grayscale integer value.
* background(51);
* describe('canvas with darkest charcoal grey background');
* describe('A canvas with a dark charcoal gray background.');
* </code>
* </div>
*
* <div>
* <code>
* // A grayscale integer value and an alpha value.
* background(51, 0.4);
* describe('A canvas with a transparent gray background.');
* </code>
* </div>
*
* <div>
* <code>
* // R, G & B integer values
* // R, G & B integer values.
* background(255, 204, 0);
* describe('canvas with yellow background');
* describe('A canvas with a yellow background.');
* </code>
* </div>
*
* <div>
* <code>
* // H, S & B integer values
* // H, S & B integer values.
* colorMode(HSB);
* background(255, 204, 100);
* describe('canvas with royal blue background');
* describe('A canvas with a royal blue background.');
* </code>
* </div>
*
* <div>
* <code>
* // Named SVG/CSS color string
* // A CSS named color.
* background('red');
* describe('canvas with red background');
* describe('A canvas with a red background.');
* </code>
* </div>
*
* <div>
* <code>
* // three-digit hexadecimal RGB notation
* // Three-digit hex RGB notation.
* background('#fae');
* describe('canvas with pink background');
* describe('A canvas with a pink background.');
* </code>
* </div>
*
* <div>
* <code>
* // six-digit hexadecimal RGB notation
* // Six-digit hex RGB notation.
* background('#222222');
* describe('canvas with black background');
* describe('A canvas with a black background.');
* </code>
* </div>
*
* <div>
* <code>
* // integer RGB notation
* // Integer RGB notation.
* background('rgb(0,255,0)');
* describe('canvas with bright green background');
* describe('A canvas with a bright green background.');
* </code>
* </div>
*
* <div>
* <code>
* // integer RGBA notation
* // Integer RGBA notation.
* background('rgba(0,255,0, 0.25)');
* describe('canvas with soft green background');
* describe('A canvas with a transparent green background.');
* </code>
* </div>
*
* <div>
* <code>
* // percentage RGB notation
* // Percentage RGB notation.
* background('rgb(100%,0%,10%)');
* describe('canvas with red background');
* describe('A canvas with a red background.');
* </code>
* </div>
*
* <div>
* <code>
* // percentage RGBA notation
* // Percentage RGBA notation.
* background('rgba(100%,0%,100%,0.5)');
* describe('canvas with light purple background');
* describe('A canvas with a transparent purple background.');
* </code>
* </div>
*
* <div>
* <code>
* // p5 Color object
* background(color(0, 0, 255));
* describe('canvas with blue background');
* // A p5.Color object.
* let c = color(0, 0, 255);
* background(c);
* describe('A canvas with a blue background.');
* </code>
* </div>
*
@@ -131,43 +142,41 @@ import './p5.Color';
* @method background
* @param {String} colorstring color string, possible formats include: integer
* rgb() or rgba(), percentage rgb() or rgba(),
* 3-digit hex, 6-digit hex
* 3-digit hex, 6-digit hex.
* @param {Number} [a] opacity of the background relative to current
* color range (default is 0-255)
* color range (default is 0-255).
* @chainable
*/

/**
* @method background
* @param {Number} gray specifies a value between white and black
* @param {Number} gray specifies a value between white and black.
* @param {Number} [a]
* @chainable
*/

/**
* @method background
* @param {Number} v1 red or hue value (depending on the current color
* mode)
* @param {Number} v2 green or saturation value (depending on the current
* color mode)
* @param {Number} v3 blue or brightness value (depending on the current
* color mode)
* @param {Number} v1 red value if color mode is RGB, or hue value if color mode is HSB.
* @param {Number} v2 green value if color mode is RGB, or saturation value if color mode is HSB.
* @param {Number} v3 blue value if color mode is RGB, or brightness value if color mode is HSB.
* @param {Number} [a]
* @chainable
*/

/**
* @method background
* @param {Number[]} values an array containing the red, green, blue
* and alpha components of the color
* and alpha components of the color.
* @chainable
*/

/**
* @method background
* @param {p5.Image} image image created with <a href="#/p5/loadImage">loadImage()</a> or <a href="#/p5/createImage">createImage()</a>,
* to set as background
* (must be same size as the sketch window)
* @param {p5.Image} image image created with <a href="#/p5/loadImage">loadImage()</a>
* or <a href="#/p5/createImage">createImage()</a>,
* to set as background.
* (must be same size as the sketch window).
* @param {Number} [a]
* @chainable
*/
@@ -177,44 +186,63 @@ p5.prototype.background = function(...args) {
};

/**
* Clears the pixels within a buffer. This function only clears the canvas.
* It will not clear objects created by createX() methods such as
* <a href="#/p5/createVideo">createVideo()</a> or <a href="#/p5/createDiv">createDiv()</a>.
* Unlike the main graphics context, pixels in additional graphics areas created
* with <a href="#/p5/createGraphics">createGraphics()</a> can be entirely
* or partially transparent. This function clears everything to make all of
* the pixels 100% transparent.
*
* Note: In WebGL mode, this function can be passed normalized RGBA color values in
* order to clear the screen to a specific color. In addition to color, it will also
* clear the depth buffer. If you are not using the webGL renderer
* these color values will have no effect.
* Clears the pixels on the canvas. This function makes every pixel 100%
* transparent. Calling `clear()` doesn't clear objects created by `createX()`
* functions such as <a href="#/p5/createGraphics">createGraphics()</a>,
* <a href="#/p5/createVideo">createVideo()</a>, and
* <a href="#/p5/createImg">createImg()</a>. These objects will remain
* unchanged after calling clear() and can be redrawn.
*
* In WebGL mode, this function can clear the screen to a specific color. It
* interprets four numeric parameters as normalized RGBA color values. It also
* clears the depth buffer. If you are not using the WebGL renderer, these
* parameters will have no effect.
*
* @method clear
* @chainable
* @example
* <div>
* <code>
* // Clear the screen on mouse press.
* function draw() {
* ellipse(mouseX, mouseY, 20, 20);
* describe(`small white ellipses are continually drawn at mouse’s x and y
* coordinates.`);
* circle(mouseX, mouseY, 20);
* describe('A white circle is drawn at the mouse x- and y-coordinates.');
* }
*
* function mousePressed() {
* clear();
* background(128);
* describe(
* 'canvas is cleared, small white ellipse is drawn at mouse X and mouse Y'
* );
* describe('The canvas is cleared when the mouse is clicked.');
* }
* </code>
* </div>
*
* <div>
* <code>
* let pg;
*
* function setup() {
* createCanvas(100, 100);
* background(200);
*
* pg = createGraphics(60, 60);
* pg.background(200);
* pg.noStroke();
* pg.circle(pg.width / 2, pg.height / 2, 15);
* image(pg, 20, 20);
* describe('A white circle drawn on a gray square. The square gets smaller when the mouse is pressed.');
* }
*
* function mousePressed() {
* clear();
* image(pg, 20, 20);
* }
* </code>
* </div>
*
* @param {Number} r normalized red val.
* @param {Number} g normalized green val.
* @param {Number} b normalized blue val.
* @param {Number} a normalized alpha val.
* @param {Number} r normalized red value.
* @param {Number} g normalized green value.
* @param {Number} b normalized blue value.
* @param {Number} a normalized alpha value.
*/
p5.prototype.clear = function(...args) {
const _r = args[0] || 0;
@@ -227,37 +255,43 @@ p5.prototype.clear = function(...args) {
};

/**
* <a href="#/p5/colorMode">colorMode()</a> changes the way p5.js interprets
* color data. By default, the parameters for <a href="#/p5/fill">fill()</a>,
* <a href="#/p5/stroke">stroke()</a>, <a href="#/p5/background">background()</a>,
* and <a href="#/p5/color">color()</a> are defined by values between 0 and 255
* using the RGB color model. This is equivalent to setting colorMode(RGB, 255).
* Setting colorMode(HSB) lets you use the HSB system instead. By default, this
* is colorMode(HSB, 360, 100, 100, 1). You can also use HSL.
* Changes the way p5.js interprets color data. By default, the numeric
* parameters for <a href="#/p5/fill">fill()</a>,
* <a href="#/p5/stroke">stroke()</a>,
* <a href="#/p5/background">background()</a>, and
* <a href="#/p5/color">color()</a> are defined by values between 0 and 255
* using the RGB color model. This is equivalent to calling
* `colorMode(RGB, 255)`. Pure red is `color(255, 0, 0)` in this model.
*
* Note: existing color objects remember the mode that they were created in,
* so you can change modes as you like without affecting their appearance.
* Calling `colorMode(RGB, 100)` sets colors to be interpreted as RGB color
* values between 0 and 100. Pure red is `color(100, 0, 0)` in this model.
*
* Calling `colorMode(HSB)` or `colorMode(HSL)` changes to HSB or HSL system
* instead of RGB.
*
* <a href="#/p5.Color">p5.Color</a> objects remember the mode that they were
* created in. Changing modes doesn't affect their appearance.
*
* @method colorMode
* @param {Constant} mode either RGB, HSB or HSL, corresponding to
* Red/Green/Blue and Hue/Saturation/Brightness
* (or Lightness)
* @param {Number} [max] range for all values
* (or Lightness).
* @param {Number} [max] range for all values.
* @chainable
*
* @example
* <div>
* <code>
* noStroke();
* colorMode(RGB, 100);
* for (let i = 0; i < 100; i++) {
* for (let j = 0; j < 100; j++) {
* for (let i = 0; i < 100; i += 1) {
* for (let j = 0; j < 100; j += 1) {
* stroke(i, j, 0);
* point(i, j);
* }
* }
* describe(
* 'Green to red gradient from bottom left to top right with shading from top left'
* 'A diagonal green to red gradient from bottom-left to top-right with shading transitioning to black at top-left corner.'
* );
* </code>
* </div>
@@ -272,19 +306,23 @@ p5.prototype.clear = function(...args) {
* point(i, j);
* }
* }
* describe(`Rainbow gradient from left to right.
* Brightness increasing to white at top.`);
* describe('A rainbow gradient from left-to-right. Brightness transitions to white at the top.');
* </code>
* </div>
*
* <div>
* <code>
* colorMode(RGB, 255);
* let c = color(127, 255, 0);
* let myColor = color(180, 175, 230);
* background(myColor);
* colorMode(RGB, 1);
* let myColor = c._getRed();
* text(myColor, 10, 10, 80, 80);
* describe('value of color red 0.4980... written on canvas');
* let redValue = red(myColor);
* let greenValue = green(myColor);
* let blueValue = blue(myColor);
* text(`Red: ${redValue}`, 10, 10, 80, 80);
* text(`Green: ${greenValue}`, 10, 40, 80, 80);
* text(`Blue: ${blueValue}`, 10, 70, 80, 80);
* describe('A purple canvas with the red, green, and blue decimal values of the color written on it.');
* </code>
* </div>
*
@@ -295,9 +333,9 @@ p5.prototype.clear = function(...args) {
* background(255);
* strokeWeight(4);
* stroke(255, 0, 10, 0.3);
* ellipse(40, 40, 50, 50);
* ellipse(50, 50, 40, 40);
* describe('two translucent pink ellipse outlines at middle left and at center');
* circle(40, 40, 50);
* circle(50, 60, 50);
* describe('Two overlapping translucent pink circle outlines.');
* </code>
* </div>
*
@@ -307,12 +345,12 @@ p5.prototype.clear = function(...args) {
* @method colorMode
* @param {Constant} mode
* @param {Number} max1 range for the red or hue depending on the
* current color mode
* current color mode.
* @param {Number} max2 range for the green or saturation depending
* on the current color mode
* on the current color mode.
* @param {Number} max3 range for the blue or brightness/lightness
* depending on the current color mode
* @param {Number} [maxA] range for the alpha
* depending on the current color mode.
* @param {Number} [maxA] range for the alpha.
* @chainable
*/
p5.prototype.colorMode = function(mode, max1, max2, max3, maxA) {
@@ -348,153 +386,153 @@ p5.prototype.colorMode = function(mode, max1, max2, max3, maxA) {
};

/**
* Sets the color used to fill shapes. For example, if you run fill(204, 102, 0),
* all shapes drawn after the fill command will be filled with the color orange.
* This color is either specified in terms of the RGB or HSB color depending on
* the current <a href="#/p5/colorMode">colorMode()</a>. (The default color space
* is RGB, with each value in the range from 0 to 255). The alpha range by default
* is also 0 to 255.
* Sets the color used to fill shapes. Calling `fill(255, 165, 0)` or
* `fill('orange')` means all shapes drawn after the fill command will be
* filled with the color orange.
*
* If a single string argument is provided, RGB, RGBA and Hex CSS color strings
* and all named color strings are supported. In this case, an alpha number
* value as a second argument is not supported, the RGBA form should be used.
* The version of `fill()` with one parameter interprets the value one of
* three ways. If the parameter is a number, it's interpreted as a grayscale
* value. If the parameter is a string, it's interpreted as a CSS color
* string. A <a href="#/p5.Color">p5.Color</a> object can also be provided to
* set the fill color.
*
* A <a href="#/p5.Color">p5.Color</a> object can also be provided to set the fill color.
* The version of `fill()` with three parameters interprets them as RGB, HSB,
* or HSL colors, depending on the current
* <a href="#/p5/colorMode">colorMode()</a>. The default color space is RGB,
* with each value in the range from 0 to 255.
*
* @method fill
* @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} v1 red value if color mode is RGB or hue value if color mode is HSB.
* @param {Number} v2 green value if color mode is RGB or saturation value if color mode is HSB.
* @param {Number} v3 blue value if color mode is RGB or brightness value if color mode is HSB.
* @param {Number} [alpha]
* @chainable
* @example
* <div>
* <code>
* // Grayscale integer value
* // Grayscale integer value.
* fill(51);
* rect(20, 20, 60, 60);
* describe('dark charcoal grey rect with black outline in center of canvas');
* square(20, 20, 60);
* describe('A dark charcoal gray square with a black outline.');
* </code>
* </div>
*
* <div>
* <code>
* // R, G & B integer values
* // R, G & B integer values.
* fill(255, 204, 0);
* rect(20, 20, 60, 60);
* describe('yellow rect with black outline in center of canvas');
* square(20, 20, 60);
* describe('A yellow square with a black outline.');
* </code>
* </div>
*
* <div>
* <code>
* // H, S & B integer values
* // H, S & B integer values.
* colorMode(HSB);
* fill(255, 204, 100);
* rect(20, 20, 60, 60);
* describe('royal blue rect with black outline in center of canvas');
* square(20, 20, 60);
* describe('A royal blue square with a black outline.');
* </code>
* </div>
*
* <div>
* <code>
* // Named SVG/CSS color string
* // A CSS named color.
* fill('red');
* rect(20, 20, 60, 60);
* describe('red rect with black outline in center of canvas');
* square(20, 20, 60);
* describe('A red square with a black outline.');
* </code>
* </div>
*
* <div>
* <code>
* // three-digit hexadecimal RGB notation
* // Three-digit hex RGB notation.
* fill('#fae');
* rect(20, 20, 60, 60);
* describe('pink rect with black outline in center of canvas');
* square(20, 20, 60);
* describe('A pink square with a black outline.');
* </code>
* </div>
*
* <div>
* <code>
* // six-digit hexadecimal RGB notation
* fill('#222222');
* rect(20, 20, 60, 60);
* describe('black rect with black outline in center of canvas');
* // Six-digit hex RGB notation.
* fill('#A251FA');
* square(20, 20, 60);
* describe('A purple square with a black outline.');
* </code>
* </div>
*
* <div>
* <code>
* // integer RGB notation
* // Integer RGB notation.
* fill('rgb(0,255,0)');
* rect(20, 20, 60, 60);
* describe('bright green rect with black outline in center of canvas');
* square(20, 20, 60);
* describe('A bright green square with a black outline.');
* </code>
* </div>
*
* <div>
* <code>
* // integer RGBA notation
* // Integer RGBA notation.
* fill('rgba(0,255,0, 0.25)');
* rect(20, 20, 60, 60);
* describe('soft green rect with black outline in center of canvas');
* square(20, 20, 60);
* describe('A soft green rectange with a black outline.');
* </code>
* </div>
*
* <div>
* <code>
* // percentage RGB notation
* // Percentage RGB notation.
* fill('rgb(100%,0%,10%)');
* rect(20, 20, 60, 60);
* describe('red rect with black outline in center of canvas');
* square(20, 20, 60);
* describe('A red square with a black outline.');
* </code>
* </div>
*
* <div>
* <code>
* // percentage RGBA notation
* // Percentage RGBA notation.
* fill('rgba(100%,0%,100%,0.5)');
* rect(20, 20, 60, 60);
* describe('dark fuchsia rect with black outline in center of canvas');
* square(20, 20, 60);
* describe('A dark fuchsia square with a black outline.');
* </code>
* </div>
*
* <div>
* <code>
* // p5 Color object
* fill(color(0, 0, 255));
* rect(20, 20, 60, 60);
* describe('blue rect with black outline in center of canvas');
* // p5.Color object.
* let c = color(0, 0, 255);
* fill(c);
* square(20, 20, 60);
* describe('A blue square with a black outline.');
* </code>
* </div>
*/

/**
* @method fill
* @param {String} value a color string
* @param {String} value a color string.
* @chainable
*/

/**
* @method fill
* @param {Number} gray a gray value
* @param {Number} gray a grayscale value.
* @param {Number} [alpha]
* @chainable
*/

/**
* @method fill
* @param {Number[]} values an array containing the red,green,blue &
* and alpha components of the color
* @param {Number[]} values an array containing the red, green, blue &
* and alpha components of the color.
* @chainable
*/

/**
* @method fill
* @param {p5.Color} color the fill color
* @param {p5.Color} color the fill color.
* @chainable
*/
p5.prototype.fill = function(...args) {
@@ -505,19 +543,21 @@ p5.prototype.fill = function(...args) {
};

/**
* Disables filling geometry. If both <a href="#/p5/noStroke">noStroke()</a> and <a href="#/p5/noFill">noFill()</a> are called,
* nothing will be drawn to the screen.
* Disables setting the interior color of shapes. This is the same as making
* the fill completely transparent. If both
* <a href="#/p5/noStroke">noStroke()</a> and
* <a href="#/p5/noFill">noFill()</a> are called, nothing will be drawn to the
* screen.
*
* @method noFill
* @chainable
* @example
* <div>
* <code>
* rect(15, 10, 55, 55);
* square(32, 10, 35);
* noFill();
* rect(20, 20, 60, 60);
* describe(`White rect at top middle and noFill rect center,
* both with black outlines.`);
* square(32, 55, 35);
* describe('A white square on top of an empty square. Both squares have black outlines.');
* </code>
* </div>
*
@@ -534,7 +574,7 @@ p5.prototype.fill = function(...args) {
* rotateX(frameCount * 0.01);
* rotateY(frameCount * 0.01);
* box(45, 45, 45);
* describe('black canvas with purple cube wireframe spinning');
* describe('A purple cube wireframe spinning on a black canvas.');
* }
* </code>
* </div>
@@ -545,17 +585,19 @@ p5.prototype.noFill = function() {
};

/**
* Disables drawing the stroke (outline). If both <a href="#/p5/noStroke">noStroke()</a> and <a href="#/p5/noFill">noFill()</a>
* are called, nothing will be drawn to the screen.
* Disables drawing the stroke (outline). If both
* <a href="#/p5/noStroke">noStroke()</a> and
* <a href="#/p5/noFill">noFill()</a> are called, nothing will be drawn to the
* screen.
*
* @method noStroke
* @chainable
* @example
* <div>
* <code>
* noStroke();
* rect(20, 20, 60, 60);
* describe('White rect at center; no outline.');
* square(20, 20, 60);
* describe('A white square with no outline.');
* </code>
* </div>
*
@@ -572,7 +614,7 @@ p5.prototype.noFill = function() {
* rotateX(frameCount * 0.01);
* rotateY(frameCount * 0.01);
* box(45, 45, 45);
* describe('black canvas with pink cube spinning');
* describe('A pink cube with no edge outlines spinning on a black canvas.');
* }
* </code>
* </div>
@@ -583,165 +625,171 @@ p5.prototype.noStroke = function() {
};

/**
* Sets the color used to draw lines and borders around shapes. This color
* is either specified in terms of the RGB or HSB color depending on the
* current <a href="#/p5/colorMode">colorMode()</a> (the default color space
* is RGB, with each value in the range from 0 to 255). The alpha range by
* default is also 0 to 255.
* Sets the color used to draw lines and borders around shapes. Calling
* `stroke(255, 165, 0)` or `stroke('orange')` means all shapes drawn after
* the `stroke()` command will be filled with the color orange. The way these
* parameters are interpreted may be changed with the
* <a href="#/p5/colorMode">colorMode()</a> function.
*
* If a single string argument is provided, RGB, RGBA and Hex CSS color
* strings and all named color strings are supported. In this case, an alpha
* number value as a second argument is not supported, the RGBA form should be
* used.
* The version of `stroke()` with one parameter interprets the value one of
* three ways. If the parameter is a number, it's interpreted as a grayscale
* value. If the parameter is a string, it's interpreted as a CSS color
* string. A <a href="#/p5.Color">p5.Color</a> object can also be provided to
* set the stroke color.
*
* A <a href="#/p5.Color">p5.Color</a> object can also be provided to set the stroke color.
* The version of `stroke()` with two parameters interprets the first one as a
* grayscale value. The second parameter sets the alpha (transparency) value.
*
* The version of `stroke()` with three parameters interprets them as RGB, HSB,
* or HSL colors, depending on the current `colorMode()`.
*
* The version of `stroke()` with four parameters interprets them as RGBA, HSBA,
* or HSLA colors, depending on the current `colorMode()`. The last parameter
* sets the alpha (transparency) value.
*
* @method stroke
* @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} v1 red value if color mode is RGB or hue value if color mode is HSB.
* @param {Number} v2 green value if color mode is RGB or saturation value if color mode is HSB.
* @param {Number} v3 blue value if color mode is RGB or brightness value if color mode is HSB.
* @param {Number} [alpha]
* @chainable
*
* @example
* <div>
* <code>
* // Grayscale integer value
* // Grayscale integer value.
* strokeWeight(4);
* stroke(51);
* rect(20, 20, 60, 60);
* describe('White rect at center with dark charcoal grey outline.');
* describe('A white rectangle with a dark charcoal gray outline.');
* </code>
* </div>
*
* <div>
* <code>
* // R, G & B integer values
* // R, G & B integer values.
* stroke(255, 204, 0);
* strokeWeight(4);
* rect(20, 20, 60, 60);
* describe('White rect at center with yellow outline.');
* describe('A white rectangle with a yellow outline.');
* </code>
* </div>
*
* <div>
* <code>
* // H, S & B integer values
* // H, S & B integer values.
* colorMode(HSB);
* strokeWeight(4);
* stroke(255, 204, 100);
* rect(20, 20, 60, 60);
* describe('White rect at center with royal blue outline.');
* describe('A white rectangle with a royal blue outline.');
* </code>
* </div>
*
* <div>
* <code>
* // Named SVG/CSS color string
* // A CSS named color.
* stroke('red');
* strokeWeight(4);
* rect(20, 20, 60, 60);
* describe('White rect at center with red outline.');
* describe('A white rectangle with a red outline.');
* </code>
* </div>
*
* <div>
* <code>
* // three-digit hexadecimal RGB notation
* // Three-digit hex RGB notation.
* stroke('#fae');
* strokeWeight(4);
* rect(20, 20, 60, 60);
* describe('White rect at center with pink outline.');
* describe('A white rectangle with a pink outline.');
* </code>
* </div>
*
* <div>
* <code>
* // six-digit hexadecimal RGB notation
* // Six-digit hex RGB notation.
* stroke('#222222');
* strokeWeight(4);
* rect(20, 20, 60, 60);
* describe('White rect at center with black outline.');
* describe('A white rectangle with a black outline.');
* </code>
* </div>
*
* <div>
* <code>
* // integer RGB notation
* // Integer RGB notation.
* stroke('rgb(0,255,0)');
* strokeWeight(4);
* rect(20, 20, 60, 60);
* describe('White rect at center with bright green outline.');
* describe('A whiite rectangle with a bright green outline.');
* </code>
* </div>
*
* <div>
* <code>
* // integer RGBA notation
* // Integer RGBA notation.
* stroke('rgba(0,255,0,0.25)');
* strokeWeight(4);
* rect(20, 20, 60, 60);
* describe('White rect at center with soft green outline.');
* describe('A white rectangle with a soft green outline.');
* </code>
* </div>
*
* <div>
* <code>
* // percentage RGB notation
* // Percentage RGB notation.
* stroke('rgb(100%,0%,10%)');
* strokeWeight(4);
* rect(20, 20, 60, 60);
* describe('White rect at center with red outline.');
* describe('A white rectangle with a red outline.');
* </code>
* </div>
*
* <div>
* <code>
* // percentage RGBA notation
* // Percentage RGBA notation.
* stroke('rgba(100%,0%,100%,0.5)');
* strokeWeight(4);
* rect(20, 20, 60, 60);
* describe('White rect at center with dark fuchsia outline.');
* describe('A white rectangle with a dark fuchsia outline.');
* </code>
* </div>
*
* <div>
* <code>
* // p5 Color object
* // p5.Color object.
* stroke(color(0, 0, 255));
* strokeWeight(4);
* rect(20, 20, 60, 60);
* describe('White rect at center with blue outline.');
* describe('A white rectangle with a blue outline.');
* </code>
* </div>
*/

/**
* @method stroke
* @param {String} value a color string
* @param {String} value a color string.
* @chainable
*/

/**
* @method stroke
* @param {Number} gray a gray value
* @param {Number} gray a grayscale value.
* @param {Number} [alpha]
* @chainable
*/

/**
* @method stroke
* @param {Number[]} values an array containing the red,green,blue &
* and alpha components of the color
* @param {Number[]} values an array containing the red, green, blue,
* and alpha components of the color.
* @chainable
*/

/**
* @method stroke
* @param {p5.Color} color the stroke color
* @param {p5.Color} color the stroke color.
* @chainable
*/

@@ -753,77 +801,77 @@ p5.prototype.stroke = function(...args) {
};

/**
* All drawing that follows <a href="#/p5/erase">erase()</a> will subtract from
* the canvas. Erased areas will reveal the web page underneath the canvas. Erasing
* can be canceled with <a href="#/p5/noErase">noErase()</a>.
* All drawing that follows <a href="#/p5/erase">erase()</a> will subtract
* from the canvas, revealing the web page underneath. The erased areas will
* become transparent, allowing the content behind the canvas to show through.
* The <a href="#/p5/fill">fill()</a>, <a href="#/p5/stroke">stroke()</a>, and
* <a href="#/p5/blendMode">blendMode()</a> have no effect once `erase()` is
* called.
*
* The `erase()` function has two optional parameters. The first parameter
* sets the strength of erasing by the shape's interior. A value of 0 means
* that no erasing will occur. A value of 255 means that the shape's interior
* will fully erase the content underneath. The default value is 255
* (full strength).
*
* Drawing done with <a href="#/p5/image">image()</a> and <a href="#/p5/background">
* background()</a> in between <a href="#/p5/erase">erase()</a> and
* <a href="#/p5/noErase">noErase()</a> will not erase the canvas but works as usual.
* The second parameter sets the strength of erasing by the shape's edge. A
* value of 0 means that no erasing will occur. A value of 255 means that the
* shape's edge will fully erase the content underneath. The default value is
* 255 (full strength).
*
* To cancel the erasing effect, use the <a href="#/p5/noErase">noErase()</a>
* function.
*
* `erase()` has no effect on drawing done with the
* <a href="#/p5/image">image()</a> and
* <a href="#/p5/background">background()</a> functions.
*
* @method erase
* @param {Number} [strengthFill] A number (0-255) for the strength of erasing for a shape's fill.
* This will default to 255 when no argument is given, which
* is full strength.
* @param {Number} [strengthStroke] A number (0-255) for the strength of erasing for a shape's stroke.
* This will default to 255 when no argument is given, which
* is full strength.
* @param {Number} [strengthFill] a number (0-255) for the strength of erasing under a shape's interior.
* Defaults to 255, which is full strength.
* @param {Number} [strengthStroke] a number (0-255) for the strength of erasing under a shape's edge.
* Defaults to 255, which is full strength.
*
* @chainable
* @example
* <div>
* <code>
* background(100, 100, 250);
* fill(250, 100, 100);
* rect(20, 20, 60, 60);
* square(20, 20, 60);
* erase();
* ellipse(25, 30, 30);
* circle(25, 30, 30);
* noErase();
* describe(`60×60 centered pink rect, purple background.
* Elliptical area in top-left of rect is erased white.`);
* describe('A purple canvas with a pink square in the middle. A circle is erased from the top-left, leaving a white hole.');
* </code>
* </div>
*
* <div>
* <code>
* background(150, 250, 150);
* fill(100, 100, 250);
* rect(20, 20, 60, 60);
* strokeWeight(5);
* erase(150, 255);
* triangle(50, 10, 70, 50, 90, 10);
* let p = createP('I am a DOM element');
* p.style('font-size', '12px');
* p.style('width', '65px');
* p.style('text-align', 'center');
* p.position(18, 26);
*
* background(100, 170, 210);
* erase(200, 100);
* circle(50, 50, 77);
* noErase();
* describe(`60×60 centered purple rect, mint green background.
* Triangle in top-right is partially erased with fully erased outline.`);
* describe('A blue canvas with a circular hole in the center that reveals the message "I am a DOM element".');
* </code>
* </div>
*
* <div>
* <code>
* function setup() {
* smooth();
* createCanvas(100, 100, WEBGL);
* // Make a &lt;p&gt; element and put it behind the canvas
* let p = createP('I am a dom element');
* p.center();
* p.style('font-size', '20px');
* p.style('text-align', 'center');
* p.style('z-index', '-9999');
* }
*
* function draw() {
* background(250, 250, 150);
* fill(15, 195, 185);
* noStroke();
* sphere(30);
* erase();
* rotateY(frameCount * 0.02);
* translate(0, 0, 40);
* torus(15, 5);
* noErase();
* describe(`60×60 centered teal sphere, yellow background.
* Torus rotating around sphere erases to reveal black text underneath.`);
* }
* background(150, 250, 150);
* fill(100, 100, 250);
* square(20, 20, 60);
* strokeWeight(5);
* erase(150, 255);
* triangle(50, 10, 70, 50, 90, 10);
* noErase();
* describe('A mint green canvas with a purple square in the center. A triangle in the top-right corner partially erases its interior and a fully erases its outline.');
* </code>
* </div>
*/
@@ -836,8 +884,8 @@ p5.prototype.erase = function(opacityFill = 255, opacityStroke = 255) {
/**
* Ends erasing that was started with <a href="#/p5/erase">erase()</a>.
* The <a href="#/p5/fill">fill()</a>, <a href="#/p5/stroke">stroke()</a>, and
* <a href="#/p5/blendMode">blendMode()</a> settings will return to what they were
* prior to calling <a href="#/p5/erase">erase()</a>.
* <a href="#/p5/blendMode">blendMode()</a> settings will return to what they
* were prior to calling <a href="#/p5/erase">erase()</a>.
*
* @method noErase
* @chainable
@@ -849,15 +897,13 @@ p5.prototype.erase = function(opacityFill = 255, opacityStroke = 255) {
* fill(30, 45, 220);
* rect(30, 10, 10, 80);
* erase();
* ellipse(50, 50, 60);
* circle(50, 50, 60);
* noErase();
* rect(70, 10, 10, 80);
* describe(`Orange background, with two tall blue rectangles.
* A centered ellipse erased the first blue rect but not the second.`);
* describe('An orange canvas with two tall blue rectangles. A circular hole in the center erases the rectangle on the left but not the one on the right.');
* </code>
* </div>
*/

p5.prototype.noErase = function() {
this._renderer.noErase();
return this;

0 comments on commit a74bc5c

Please sign in to comment.