From fec0509006bb1f5d7527c96acdfae7aa2c5af27e Mon Sep 17 00:00:00 2001 From: Nick McIntyre Date: Tue, 7 May 2024 13:53:02 -0500 Subject: [PATCH] Update structure references --- src/core/structure.js | 1205 +++++++++++++++++++++++++++++++---------- 1 file changed, 905 insertions(+), 300 deletions(-) diff --git a/src/core/structure.js b/src/core/structure.js index 539a9c1192..309f4380c5 100644 --- a/src/core/structure.js +++ b/src/core/structure.js @@ -7,119 +7,210 @@ import p5 from './main'; /** - * Stops p5.js from continuously executing the code within draw(). - * If loop() is called, the code in draw() - * begins to run continuously again. If using noLoop() - * in setup(), it should be the last line inside the block. - * - * When noLoop() is used, it's not possible to manipulate - * or access the screen inside event handling functions such as - * mousePressed() or - * keyPressed(). Instead, use those functions to - * call redraw() or loop(), - * which will run draw(), which can update the screen - * properly. This means that when noLoop() has been - * called, no drawing can happen, and functions like saveFrames() - * or loadPixels() may not be used. - * - * Note that if the sketch is resized, redraw() will - * be called to update the sketch, even after noLoop() - * has been specified. Otherwise, the sketch would enter an odd state until - * loop() was called. - * - * Use isLooping() to check the current state of loop(). + * Stops the code in draw() from running repeatedly. + * + * By default, draw() tries to run 60 times per + * second. Calling `noLoop()` stops draw() from + * repeating. The draw loop can be restarted by calling + * loop(). draw() can be run + * once by calling redraw(). + * + * The isLooping() function can be used to check + * whether a sketch is looping, as in `isLooping() === true`. * * @method noLoop + * * @example *
* * function setup() { * createCanvas(100, 100); - * background(200); + * + * // Turn off the draw loop. * noLoop(); + * + * describe('A white half-circle on the left edge of a gray square.'); * } - + * * function draw() { - * line(10, 10, 90, 90); + * background(200); + * + * // Calculate the circle's x-coordinate. + * let x = frameCount; + * + * // Draw the circle. + * // Normally, the circle would move from left to right. + * circle(x, 50, 20); * } * *
* *
* - * let x = 0; + * // Double-click to stop the draw loop. + * * function setup() { * createCanvas(100, 100); + * + * // Slow the frame rate. + * frameRate(5); + * + * describe('A white circle moves randomly on a gray background. It stops moving when the user double-clicks.'); * } * * function draw() { - * background(204); - * x = x + 0.1; - * if (x > width) { - * x = 0; - * } - * line(x, 0, x, height); + * background(200); + * + * // Calculate the circle's coordinates. + * let x = random(0, 100); + * let y = random(0, 100); + * + * // Draw the circle. + * // Normally, the circle would move from left to right. + * circle(x, y, 20); * } * - * function mousePressed() { + * // Stop the draw loop when the user double-clicks. + * function doubleClicked() { * noLoop(); * } + * + *
* - * function mouseReleased() { - * loop(); + *
+ * + * let startButton; + * let stopButton; + * + * function setup() { + * createCanvas(100, 100); + * + * // Create the button elements and place them + * // beneath the canvas. + * startButton = createButton('▶'); + * startButton.position(0, 100); + * startButton.size(50, 20); + * stopButton = createButton('◾'); + * stopButton.position(50, 100); + * stopButton.size(50, 20); + * + * // Set functions to call when the buttons are pressed. + * startButton.mousePressed(loop); + * stopButton.mousePressed(noLoop); + * + * // Slow the frame rate. + * frameRate(5); + * + * describe( + * 'A white circle moves randomly on a gray background. Play and stop buttons are shown beneath the canvas. The circle stops or starts moving when the user presses a button.' + * ); + * } + * + * function draw() { + * background(200); + * + * // Calculate the circle's coordinates. + * let x = random(0, 100); + * let y = random(0, 100); + * + * // Draw the circle. + * // Normally, the circle would move from left to right. + * circle(x, y, 20); * } * *
- * - * @alt - * 113 pixel long line extending from top-left to bottom right of canvas. - * horizontal line moves slowly from left. Loops but stops on mouse press. */ p5.prototype.noLoop = function() { this._loop = false; }; /** - * By default, p5.js loops through draw() continuously, executing the code within - * it. However, the draw() loop may be stopped by calling - * noLoop(). In that case, the draw() - * loop can be resumed with loop(). + * Resumes the draw loop after noLoop() has been + * called. * - * Avoid calling loop() from inside setup(). + * By default, draw() tries to run 60 times per + * second. Calling noLoop() stops + * draw() from repeating. The draw loop can be + * restarted by calling `loop()`. * - * Use isLooping() to check the current state of loop(). + * The isLooping() function can be used to check + * whether a sketch is looping, as in `isLooping() === true`. * * @method loop + * * @example *
* - * let x = 0; * function setup() { * createCanvas(100, 100); + * + * // Turn off the draw loop. * noLoop(); + * + * describe( + * 'A white half-circle on the left edge of a gray square. The circle starts moving to the right when the user double-clicks.' + * ); * } * * function draw() { - * background(204); - * x = x + 0.1; - * if (x > width) { - * x = 0; - * } - * line(x, 0, x, height); + * background(200); + * + * // Calculate the circle's x-coordinate. + * let x = frameCount; + * + * // Draw the circle. + * circle(x, 50, 20); * } * - * function mousePressed() { + * // Resume the draw loop when the user double-clicks. + * function doubleClicked() { * loop(); * } + * + *
* - * function mouseReleased() { - * noLoop(); + *
+ * + * let startButton; + * let stopButton; + * + * function setup() { + * createCanvas(100, 100); + * + * // Create the button elements and place them + * // beneath the canvas. + * startButton = createButton('▶'); + * startButton.position(0, 100); + * startButton.size(50, 20); + * stopButton = createButton('◾'); + * stopButton.position(50, 100); + * stopButton.size(50, 20); + * + * // Set functions to call when the buttons are pressed. + * startButton.mousePressed(loop); + * stopButton.mousePressed(noLoop); + * + * // Slow the frame rate. + * frameRate(5); + * + * describe( + * 'A white circle moves randomly on a gray background. Play and stop buttons are shown beneath the canvas. The circle stops or starts moving when the user presses a button.' + * ); + * } + * + * function draw() { + * background(200); + * + * // Calculate the circle's coordinates. + * let x = random(0, 100); + * let y = random(0, 100); + * + * // Draw the circle. + * // Normally, the circle would move from left to right. + * circle(x, y, 20); * } * *
- * - * @alt - * horizontal line moves slowly from left. Loops but stops on mouse press. */ p5.prototype.loop = function() { if (!this._loop) { @@ -131,152 +222,324 @@ p5.prototype.loop = function() { }; /** - * By default, p5.js loops through draw() continuously, - * executing the code within it. If the sketch is stopped with - * noLoop() or resumed with loop(), - * isLooping() returns the current state for use within custom event handlers. + * Returns `true` if the draw loop is running and `false` if not. + * + * By default, draw() tries to run 60 times per + * second. Calling noLoop() stops + * draw() from repeating. The draw loop can be + * restarted by calling loop(). + * + * The `isLooping()` function can be used to check whether a sketch is + * looping, as in `isLooping() === true`. * * @method isLooping * @returns {boolean} + * * @example *
* - * let checkbox, button, colBG, colFill; - * * function setup() { * createCanvas(100, 100); * - * button = createButton('Colorize if loop()'); - * button.position(0, 120); - * button.mousePressed(changeBG); - * - * checkbox = createCheckbox('loop()', true); - * checkbox.changed(checkLoop); - * - * colBG = color(0); - * colFill = color(255); + * describe('A white circle drawn against a gray background. When the user double-clicks, the circle stops or resumes following the mouse.'); * } * - * function changeBG() { - * if (isLooping()) { - * colBG = color(random(255), random(255), random(255)); - * colFill = color(random(255), random(255), random(255)); - * } + * function draw() { + * background(200); + * + * // Draw the circle at the mouse's position. + * circle(mouseX, mouseY, 20); * } * - * function checkLoop() { - * if (this.checked()) { - * loop(); - * } else { + * // Toggle the draw loop when the user double-clicks. + * function doubleClicked() { + * if (isLooping() === true) { * noLoop(); + * } else { + * loop(); * } * } - * - * function draw() { - * background(colBG); - * fill(colFill); - * ellipse(frameCount % width, height / 2, 50); - * } * *
- * - * @alt - * Ellipse moves slowly from left. Checkbox toggles loop()/noLoop(). - * Button colorizes sketch if isLooping(). - * */ p5.prototype.isLooping = function() { return this._loop; }; /** - * The push() function saves the current drawing style - * settings and transformations, while pop() restores these - * settings. Note that these functions are always used together. They allow you to - * change the style and transformation settings and later return to what you had. - * When a new state is started with push(), it builds on - * the current style and transform information. The push() - * and pop() functions can be embedded to provide more - * control. (See the second example for a demonstration.) - * - * push() stores information related to the current transformation state - * and style settings controlled by the following functions: - * fill(), - * noFill(), - * noStroke(), - * stroke(), - * tint(), - * noTint(), - * strokeWeight(), - * strokeCap(), - * strokeJoin(), - * imageMode(), - * rectMode(), - * ellipseMode(), - * colorMode(), - * textAlign(), - * textFont(), - * textSize(), - * textLeading(), - * applyMatrix(), - * resetMatrix(), - * rotate(), - * scale(), - * shearX(), - * shearY(), - * translate(), - * noiseSeed(). - * - * In WEBGL mode additional style settings are stored. These are controlled by the - * following functions: setCamera(), - * ambientLight(), - * directionalLight(), - * pointLight(), texture(), - * specularMaterial(), - * shininess(), - * normalMaterial() - * and shader(). + * Begins a drawing group that contains its own styles and transformations. + * + * By default, styles such as fill() and + * transformations such as rotate() are applied to + * all drawing that follows. The `push()` and pop() + * functions can limit the effect of styles and transformations to a specific + * group of shapes, images, and text. For example, a group of shapes could be + * translated to follow the mouse without affecting the rest of the sketch: + * + * ```js + * // Begin the drawing group. + * push(); + * + * // Translate the origin to the mouse's position. + * translate(mouseX, mouseY); + * + * // Style the face. + * noStroke(); + * fill('green'); + * + * // Draw the face. + * circle(0, 0, 60); + * + * // Style the eyes. + * fill('white'); + * + * // Draw the left eye. + * ellipse(-20, -20, 30, 20); + * + * // Draw the right eye. + * ellipse(20, -20, 30, 20); + * + * // End the drawing group. + * pop(); + * + * // Draw a bug. + * let x = random(0, 100); + * let y = random(0, 100); + * text('🦟', x, y); + * ``` + * + * In the code snippet above, the bug's position isn't affected by + * `translate(mouseX, mouseY)` because that transformation is contained + * between `push()` and pop(). The bug moves around + * the entire canvas as expected. + * + * Note: `push()` and pop() are always called as a + * pair. Both functions are required to begin and end a drawing group. + * + * `push()` and pop() can also be nested to create + * subgroups. For example, the code snippet above could be changed to give + * more detail to the frog’s eyes: + * + * ```js + * // Begin the drawing group. + * push(); + * + * // Translate the origin to the mouse's position. + * translate(mouseX, mouseY); + * + * // Style the face. + * noStroke(); + * fill('green'); + * + * // Draw a face. + * circle(0, 0, 60); + * + * // Style the eyes. + * fill('white'); + * + * // Draw the left eye. + * push(); + * translate(-20, -20); + * ellipse(0, 0, 30, 20); + * fill('black'); + * circle(0, 0, 8); + * pop(); + * + * // Draw the right eye. + * push(); + * translate(20, -20); + * ellipse(0, 0, 30, 20); + * fill('black'); + * circle(0, 0, 8); + * pop(); + * + * // End the drawing group. + * pop(); + * + * // Draw a bug. + * let x = random(0, 100); + * let y = random(0, 100); + * text('🦟', x, y); + * ``` + * + * In this version, the code to draw each eye is contained between its own + * `push()` and pop() functions. Doing so makes it + * easier to add details in the correct part of a drawing. + * + * `push()` and pop() contain the effects of the + * following functions: + * + * - fill() + * - noFill() + * - noStroke() + * - stroke() + * - tint() + * - noTint() + * - strokeWeight() + * - strokeCap() + * - strokeJoin() + * - imageMode() + * - rectMode() + * - ellipseMode() + * - colorMode() + * - textAlign() + * - textFont() + * - textSize() + * - textLeading() + * - applyMatrix() + * - resetMatrix() + * - rotate() + * - scale() + * - shearX() + * - shearY() + * - translate() + * + * In WebGL mode, `push()` and pop() contain the + * effects of a few additional styles: + * + * - setCamera() + * - ambientLight() + * - directionalLight() + * - pointLight() texture() + * - specularMaterial() + * - shininess() + * - normalMaterial() + * - shader() * * @method push + * * @example *
* - * ellipse(0, 50, 33, 33); // Left circle + * function setup() { + * createCanvas(100, 100); * - * push(); // Start a new drawing state - * strokeWeight(10); - * fill(204, 153, 0); - * translate(50, 0); - * ellipse(0, 50, 33, 33); // Middle circle - * pop(); // Restore original state + * background(200); + * + * // Draw the left circle. + * circle(25, 50, 20); + * + * // Begin the drawing group. + * push(); + * + * // Translate the origin to the center. + * translate(50, 50); + * + * // Style the circle. + * strokeWeight(5); + * stroke('royalblue'); + * fill('orange'); + * + * // Draw the circle. + * circle(0, 0, 20); + * + * // End the drawing group. + * pop(); * - * ellipse(100, 50, 33, 33); // Right circle + * // Draw the right circle. + * circle(75, 50, 20); + * + * describe( + * 'Three circles drawn in a row on a gray background. The left and right circles are white with thin, black borders. The middle circle is orange with a thick, blue border.' + * ); + * } * *
* *
* - * ellipse(0, 50, 33, 33); // Left circle + * function setup() { + * createCanvas(100, 100); * - * push(); // Start a new drawing state - * strokeWeight(10); - * fill(204, 153, 0); - * ellipse(33, 50, 33, 33); // Left-middle circle + * // Slow the frame rate. + * frameRate(24); * - * push(); // Start another new drawing state - * stroke(0, 102, 153); - * ellipse(66, 50, 33, 33); // Right-middle circle - * pop(); // Restore previous state + * describe('A mosquito buzzes in front of a green frog. The frog follows the mouse as the user moves.'); + * } * - * pop(); // Restore original state + * function draw() { + * background(200); * - * ellipse(100, 50, 33, 33); // Right circle + * // Begin the drawing group. + * push(); + * + * // Translate the origin to the mouse's position. + * translate(mouseX, mouseY); + * + * // Style the face. + * noStroke(); + * fill('green'); + * + * // Draw a face. + * circle(0, 0, 60); + * + * // Style the eyes. + * fill('white'); + * + * // Draw the left eye. + * push(); + * translate(-20, -20); + * ellipse(0, 0, 30, 20); + * fill('black'); + * circle(0, 0, 8); + * pop(); + * + * // Draw the right eye. + * push(); + * translate(20, -20); + * ellipse(0, 0, 30, 20); + * fill('black'); + * circle(0, 0, 8); + * pop(); + * + * // End the drawing group. + * pop(); + * + * // Draw a bug. + * let x = random(0, 100); + * let y = random(0, 100); + * text('🦟', x, y); + * } * *
* - * @alt - * Gold ellipse + thick black outline @center 2 white ellipses on left and right. - * 2 Gold ellipses left black right blue stroke. 2 white ellipses on left+right. + *
+ * + * // Click and drag the mouse to view the scene from different angles. + * + * function setup() { + * createCanvas(100, 100, WEBGL); + * + * describe( + * 'Two spheres drawn on a gray background. The sphere on the left is red and lit from the front. The sphere on the right is a blue wireframe.' + * ); + * } + * + * function draw() { + * background(200); + * + * // Enable orbiting with the mouse. + * orbitControl(); + * + * // Draw the red sphere. + * push(); + * translate(-25, 0, 0); + * noStroke(); + * directionalLight(255, 0, 0, 0, 0, -1); + * sphere(20); + * pop(); + * + * // Draw the blue sphere. + * push(); + * translate(25, 0, 0); + * strokeWeight(0.3); + * stroke(0, 0, 255); + * noFill(); + * sphere(20); + * pop(); + * } + * + *
*/ p5.prototype.push = function() { this._styles.push({ @@ -288,95 +551,279 @@ p5.prototype.push = function() { }; /** - * The push() function saves the current drawing style - * settings and transformations, while pop() restores - * these settings. Note that these functions are always used together. They allow - * you to change the style and transformation settings and later return to what - * you had. When a new state is started with push(), it - * builds on the current style and transform information. The push() - * and pop() functions can be embedded to provide more - * control. (See the second example for a demonstration.) - * - * push() stores information related to the current transformation state - * and style settings controlled by the following functions: - * fill(), - * noFill(), - * noStroke(), - * stroke(), - * tint(), - * noTint(), - * strokeWeight(), - * strokeCap(), - * strokeJoin(), - * imageMode(), - * rectMode(), - * ellipseMode(), - * colorMode(), - * textAlign(), - * textFont(), - * textSize(), - * textLeading(), - * applyMatrix(), - * resetMatrix(), - * rotate(), - * scale(), - * shearX(), - * shearY(), - * translate(), - * noiseSeed(). - * - * In WEBGL mode additional style settings are stored. These are controlled by - * the following functions: - * setCamera(), - * ambientLight(), - * directionalLight(), - * pointLight(), - * texture(), - * specularMaterial(), - * shininess(), - * normalMaterial() and - * shader(). + * Ends a drawing group that contains its own styles and transformations. + * + * By default, styles such as fill() and + * transformations such as rotate() are applied to + * all drawing that follows. The push() and `pop()` + * functions can limit the effect of styles and transformations to a specific + * group of shapes, images, and text. For example, a group of shapes could be + * translated to follow the mouse without affecting the rest of the sketch: + * + * ```js + * // Begin the drawing group. + * push(); + * + * // Translate the origin to the mouse's position. + * translate(mouseX, mouseY); + * + * // Style the face. + * noStroke(); + * fill('green'); + * + * // Draw the face. + * circle(0, 0, 60); + * + * // Style the eyes. + * fill('white'); + * + * // Draw the left eye. + * ellipse(-20, -20, 30, 20); + * + * // Draw the right eye. + * ellipse(20, -20, 30, 20); + * + * // End the drawing group. + * pop(); + * + * // Draw a bug. + * let x = random(0, 100); + * let y = random(0, 100); + * text('🦟', x, y); + * ``` + * + * In the code snippet above, the bug's position isn't affected by + * `translate(mouseX, mouseY)` because that transformation is contained + * between push() and `pop()`. The bug moves around + * the entire canvas as expected. + * + * Note: push() and `pop()` are always called as a + * pair. Both functions are required to begin and end a drawing group. + * + * push() and `pop()` can also be nested to create + * subgroups. For example, the code snippet above could be changed to give + * more detail to the frog’s eyes: + * + * ```js + * // Begin the drawing group. + * push(); + * + * // Translate the origin to the mouse's position. + * translate(mouseX, mouseY); + * + * // Style the face. + * noStroke(); + * fill('green'); + * + * // Draw a face. + * circle(0, 0, 60); + * + * // Style the eyes. + * fill('white'); + * + * // Draw the left eye. + * push(); + * translate(-20, -20); + * ellipse(0, 0, 30, 20); + * fill('black'); + * circle(0, 0, 8); + * pop(); + * + * // Draw the right eye. + * push(); + * translate(20, -20); + * ellipse(0, 0, 30, 20); + * fill('black'); + * circle(0, 0, 8); + * pop(); + * + * // End the drawing group. + * pop(); + * + * // Draw a bug. + * let x = random(0, 100); + * let y = random(0, 100); + * text('🦟', x, y); + * ``` + * + * In this version, the code to draw each eye is contained between its own + * push() and `pop()` functions. Doing so makes it + * easier to add details in the correct part of a drawing. + * + * push() and `pop()` contain the effects of the + * following functions: + * + * - fill() + * - noFill() + * - noStroke() + * - stroke() + * - tint() + * - noTint() + * - strokeWeight() + * - strokeCap() + * - strokeJoin() + * - imageMode() + * - rectMode() + * - ellipseMode() + * - colorMode() + * - textAlign() + * - textFont() + * - textSize() + * - textLeading() + * - applyMatrix() + * - resetMatrix() + * - rotate() + * - scale() + * - shearX() + * - shearY() + * - translate() + * + * In WebGL mode, push() and `pop()` contain the + * effects of a few additional styles: + * + * - setCamera() + * - ambientLight() + * - directionalLight() + * - pointLight() texture() + * - specularMaterial() + * - shininess() + * - normalMaterial() + * - shader() * * @method pop + * * @example *
* - * ellipse(0, 50, 33, 33); // Left circle + * function setup() { + * createCanvas(100, 100); + * + * background(200); * - * push(); // Start a new drawing state - * translate(50, 0); - * strokeWeight(10); - * fill(204, 153, 0); - * ellipse(0, 50, 33, 33); // Middle circle - * pop(); // Restore original state + * // Draw the left circle. + * circle(25, 50, 20); * - * ellipse(100, 50, 33, 33); // Right circle + * // Begin the drawing group. + * push(); + * + * // Translate the origin to the center. + * translate(50, 50); + * + * // Style the circle. + * strokeWeight(5); + * stroke('royalblue'); + * fill('orange'); + * + * // Draw the circle. + * circle(0, 0, 20); + * + * // End the drawing group. + * pop(); + * + * // Draw the right circle. + * circle(75, 50, 20); + * + * describe( + * 'Three circles drawn in a row on a gray background. The left and right circles are white with thin, black borders. The middle circle is orange with a thick, blue border.' + * ); + * } * *
* *
* - * ellipse(0, 50, 33, 33); // Left circle + * function setup() { + * createCanvas(100, 100); * - * push(); // Start a new drawing state - * strokeWeight(10); - * fill(204, 153, 0); - * ellipse(33, 50, 33, 33); // Left-middle circle + * // Slow the frame rate. + * frameRate(24); * - * push(); // Start another new drawing state - * stroke(0, 102, 153); - * ellipse(66, 50, 33, 33); // Right-middle circle - * pop(); // Restore previous state + * describe('A mosquito buzzes in front of a green frog. The frog follows the mouse as the user moves.'); + * } * - * pop(); // Restore original state + * function draw() { + * background(200); * - * ellipse(100, 50, 33, 33); // Right circle + * // Begin the drawing group. + * push(); + * + * // Translate the origin to the mouse's position. + * translate(mouseX, mouseY); + * + * // Style the face. + * noStroke(); + * fill('green'); + * + * // Draw a face. + * circle(0, 0, 60); + * + * // Style the eyes. + * fill('white'); + * + * // Draw the left eye. + * push(); + * translate(-20, -20); + * ellipse(0, 0, 30, 20); + * fill('black'); + * circle(0, 0, 8); + * pop(); + * + * // Draw the right eye. + * push(); + * translate(20, -20); + * ellipse(0, 0, 30, 20); + * fill('black'); + * circle(0, 0, 8); + * pop(); + * + * // End the drawing group. + * pop(); + * + * // Draw a bug. + * let x = random(0, 100); + * let y = random(0, 100); + * text('🦟', x, y); + * } * *
* - * @alt - * Gold ellipse + thick black outline @center 2 white ellipses on left and right. - * 2 Gold ellipses left black right blue stroke. 2 white ellipses on left+right. + *
+ * + * // Click and drag the mouse to view the scene from different angles. + * + * function setup() { + * createCanvas(100, 100, WEBGL); + * + * describe( + * 'Two spheres drawn on a gray background. The sphere on the left is red and lit from the front. The sphere on the right is a blue wireframe.' + * ); + * } + * + * function draw() { + * background(200); + * + * // Enable orbiting with the mouse. + * orbitControl(); + * + * // Draw the red sphere. + * push(); + * translate(-25, 0, 0); + * noStroke(); + * directionalLight(255, 0, 0, 0, 0, -1); + * sphere(20); + * pop(); + * + * // Draw the blue sphere. + * push(); + * translate(25, 0, 0); + * strokeWeight(0.3); + * stroke(0, 0, 255); + * noFill(); + * sphere(20); + * pop(); + * } + * + *
*/ p5.prototype.pop = function() { const style = this._styles.pop(); @@ -389,71 +836,89 @@ p5.prototype.pop = function() { }; /** - * Executes the code within draw() one time. This - * function allows the program to update the display window only when necessary, - * for example when an event registered by mousePressed() - * or keyPressed() occurs. - * - * In structuring a program, it only makes sense to call redraw() - * within events such as mousePressed(). This - * is because redraw() does not run - * draw() immediately (it only sets a flag that indicates - * an update is needed). + * Runs the code in draw() once. * - * The redraw() function does not work properly when - * called inside draw().To enable/disable animations, - * use loop() and noLoop(). + * By default, draw() tries to run 60 times per + * second. Calling noLoop() stops + * draw() from repeating. Calling `redraw()` will + * execute the code in the draw() function a set + * number of times. * - * In addition you can set the number of redraws per method call. Just - * add an integer as single parameter for the number of redraws. + * The parameter, `n`, is optional. If a number is passed, as in `redraw(5)`, + * then the draw loop will run the given number of times. By default, `n` is + * 1. * * @method redraw - * @param {Integer} [n] Redraw for n-times. The default value is 1. + * @param {Integer} [n] number of times to run draw(). Defaults to 1. + * * @example - *
+ *
+ * + * // Double-click the canvas to move the circle. + * * let x = 0; * * function setup() { * createCanvas(100, 100); + * + * // Turn off the draw loop. * noLoop(); + * + * describe( + * 'A white half-circle on the left edge of a gray square. The circle moves a little to the right when the user double-clicks.' + * ); * } * * function draw() { - * background(204); - * line(x, 0, x, height); + * background(200); + * + * // Draw the circle. + * circle(x, 50, 20); + * + * // Increment x. + * x += 5; * } * - * function mousePressed() { - * x += 1; + * // Run the draw loop when the user double-clicks. + * function doubleClicked() { * redraw(); * } * *
* - *
+ *
* + * // Double-click the canvas to move the circle. + * * let x = 0; * * function setup() { * createCanvas(100, 100); + * + * // Turn off the draw loop. * noLoop(); + * + * describe( + * 'A white half-circle on the left edge of a gray square. The circle hops to the right when the user double-clicks.' + * ); * } * * function draw() { - * background(204); - * x += 1; - * line(x, 0, x, height); + * background(200); + * + * // Draw the circle. + * circle(x, 50, 20); + * + * // Increment x. + * x += 5; * } * - * function mousePressed() { - * redraw(5); + * // Run the draw loop three times when the user double-clicks. + * function doubleClicked() { + * redraw(3); * } * *
- * - * @alt - * black line on far left of canvas - * black line on far left of canvas */ p5.prototype.redraw = function(n) { if (this._inUserDraw || !this._setupDone) { @@ -492,53 +957,193 @@ p5.prototype.redraw = function(n) { }; /** - * The `p5()` constructor enables you to activate "instance mode" instead of normal - * "global mode". This is an advanced topic. A short description and example is - * included below. Please see - * - * Dan Shiffman's Coding Train video tutorial or this - * tutorial page - * for more info. - * - * By default, all p5.js functions are in the global namespace (i.e. bound to the window - * object), meaning you can call them simply `ellipse()`, `fill()`, etc. However, this - * might be inconvenient if you are mixing with other JS libraries (synchronously or - * asynchronously) or writing long programs of your own. p5.js currently supports a - * way around this problem called "instance mode". In instance mode, all p5 functions - * are bound up in a single variable instead of polluting your global namespace. - * - * Optionally, you can specify a default container for the canvas and any other elements - * to append to with a second argument. You can give the ID of an element in your html, - * or an html node itself. - * - * Note that creating instances like this also allows you to have more than one p5 sketch on - * a single web page, as they will each be wrapped up with their own set up variables. Of - * course, you could also use iframes to have multiple sketches in global mode. + * Creates a new sketch in "instance" mode. + * + * All p5.js sketches are instances of the `p5` class. Put another way, all + * p5.js sketches are objects with methods including `pInst.setup()`, + * `pInst.draw()`, `pInst.circle()`, and `pInst.fill()`. By default, sketches + * run in "global mode" to hide some of this complexity. + * + * In global mode, a default instance of the `p5` class is created + * automatically. The default `p5` instance searches the web page's source + * code for declarations of system functions such as `setup()`, `draw()`, + * and `mousePressed()`, then attaches those functions to itself as methods. + * Calling a function such as `circle()` in global mode actually calls the + * default `p5` object's `pInst.circle()` method. + * + * It's often helpful to isolate the code within sketches from the rest of the + * code on a web page. Two common use cases are web pages that use other + * JavaScript libraries and web pages with multiple sketches. "Instance mode" + * makes it easy to support both of these scenarios. + * + * Instance mode sketches support the same API as global mode sketches. They + * use a function to bundle, or encapsulate, an entire sketch. The function + * containing the sketch is then passed to the `p5()` constructor. + * + * The first parameter, `sketch`, is a function that contains the sketch. For + * example, the statement `new p5(mySketch)` would create a new instance mode + * sketch from a function named `mySketch`. The function should have one + * parameter, `p`, that's a `p5` object. + * + * The second parameter, `node`, is optional. If a string is passed, as in + * `new p5(mySketch, 'sketch-one')` the new instance mode sketch will become a + * child of the HTML element with the id `sketch-one`. If an HTML element is + * passed, as in `new p5(mySketch, myElement)`, then the new instance mode + * sketch will become a child of the `Element` object called `myElement`. * * @method p5 - * @param {Object} sketch a function containing a p5.js sketch - * @param {String|Object} node ID or pointer to HTML DOM node to contain sketch in + * @param {Object} sketch function containing the sketch. + * @param {String|HTMLElement} node ID or reference to the HTML element that will contain the sketch. + * * @example - *
- * const s = p => { - * let x = 100; - * let y = 100; + *
+ * + * // Declare the function containing the sketch. + * function sketch(p) { + * + * // Declare the setup() method. + * p.setup = function () { + * p.createCanvas(100, 100); * - * p.setup = function() { - * p.createCanvas(700, 410); + * p.describe('A white circle drawn on a gray background.'); * }; * - * p.draw = function() { - * p.background(0); - * p.fill(255); - * p.rect(x, y, 50, 50); + * // Declare the draw() method. + * p.draw = function () { + * p.background(200); + * + * // Draw the circle. + * p.circle(50, 50, 20); * }; - * }; + * } + * + * // Initialize the sketch. + * new p5(sketch); + * + *
+ * + *
+ * + * // Declare the function containing the sketch. + * function sketch(p) { + * // Create the sketch's variables within its scope. + * let x = 50; + * let y = 50; + * + * // Declare the setup() method. + * p.setup = function () { + * p.createCanvas(100, 100); + * + * p.describe('A white circle moves randomly on a gray background.'); + * }; + * + * // Declare the draw() method. + * p.draw = function () { + * p.background(200); + * + * // Update x and y. + * x += p.random(-1, 1); + * y += p.random(-1, 1); + * + * // Draw the circle. + * p.circle(x, y, 20); + * }; + * } + * + * // Initialize the sketch. + * new p5(sketch); + * + *
+ * + *
+ * + * // Declare the function containing the sketch. + * function sketch(p) { + * + * // Declare the setup() method. + * p.setup = function () { + * p.createCanvas(100, 100); + * + * p.describe('A white circle drawn on a gray background.'); + * }; + * + * // Declare the draw() method. + * p.draw = function () { + * p.background(200); + * + * // Draw the circle. + * p.circle(50, 50, 20); + * }; + * } + * + * // Select the web page's body element. + * let body = document.querySelector('body'); * - * new p5(s); // invoke p5 - *
+ * // Initialize the sketch and attach it to the web page's body. + * new p5(sketch, body); + * + *
+ * + *
+ * + * // Declare the function containing the sketch. + * function sketch(p) { + * + * // Declare the setup() method. + * p.setup = function () { + * p.createCanvas(100, 100); + * + * p.describe( + * 'A white circle drawn on a gray background. The circle follows the mouse as the user moves.' + * ); + * }; + * + * // Declare the draw() method. + * p.draw = function () { + * p.background(200); + * + * // Draw the circle. + * p.circle(p.mouseX, p.mouseY, 20); + * }; + * } + * + * // Initialize the sketch. + * new p5(sketch); + * + *
* - * @alt - * white rectangle on black background + *
+ * + * // Declare the function containing the sketch. + * function sketch(p) { + * + * // Declare the setup() method. + * p.setup = function () { + * p.createCanvas(100, 100); + * + * p.describe( + * 'A white circle drawn on a gray background. The circle follows the mouse as the user moves. The circle becomes black when the user double-clicks.' + * ); + * }; + * + * // Declare the draw() method. + * p.draw = function () { + * p.background(200); + * + * // Draw the circle. + * p.circle(p.mouseX, p.mouseY, 20); + * }; + * + * // Declare the doubleClicked() method. + * p.doubleClicked = function () { + * // Change the fill color when the user double-clicks. + * p.fill(0); + * }; + * } + * + * // Initialize the sketch. + * new p5(sketch); + * + *
*/ export default p5;