@@ -226,7 +226,7 @@ p5.prototype._ontouchmove = function(e) {
* to the end of the method.
*
* @method touchEnded
- * @param {Object} [event] optional TouchEvent callback argument.
+ * @param {TouchEvent} [event] optional TouchEvent callback argument.
* @example
*
*
diff --git a/src/image/filters.js b/src/image/filters.js
index d4707438e3..83c47a661a 100644
--- a/src/image/filters.js
+++ b/src/image/filters.js
@@ -308,7 +308,7 @@ const Filters = {
},
/**
- * reduces the bright areas in an image
+ * increases the bright areas in an image
* @private
* @param {Canvas} canvas
*/
@@ -395,7 +395,7 @@ const Filters = {
},
/**
- * increases the bright areas in an image
+ * reduces the bright areas in an image
* @private
* @param {Canvas} canvas
*/
diff --git a/src/image/image.js b/src/image/image.js
index b4d150df66..858e8b052c 100644
--- a/src/image/image.js
+++ b/src/image/image.js
@@ -13,38 +13,38 @@ import p5 from '../core/main';
import omggif from 'omggif';
/**
- * Creates a new p5.Image (the datatype for storing images). This provides a
- * fresh buffer of pixels to play with. Set the size of the buffer with the
- * width and height parameters.
+ * Creates a new p5.Image object. The new image is
+ * transparent by default.
*
- * .pixels gives access to an array containing the values for all the pixels
- * in the display window.
- * These values are numbers. This array is the size (including an appropriate
- * factor for the pixelDensity ) of the display window x4,
- * representing the R, G, B, A values in order for each pixel, moving from
- * left to right across each row, then down each column. See .pixels for
- * more info. It may also be simpler to use set() or get() .
- *
- * Before accessing the pixels of an image, the data must loaded with the
- * loadPixels() function. After the array data has been modified, the
- * updatePixels() function must be run to update the changes.
+ * `createImage()` uses the `width` and `height` paremeters to set the new
+ * p5.Image object's dimensions in pixels. The new
+ * p5.Image can be modified by updating its
+ * pixels array or by calling its
+ * get() and
+ * set() methods. The
+ * loadPixels() method must be called
+ * before reading or modifying pixel values. The
+ * updatePixels() method must be called
+ * for updates to take effect.
*
* @method createImage
- * @param {Integer} width width in pixels
- * @param {Integer} height height in pixels
- * @return {p5.Image} the p5.Image object
+ * @param {Integer} width width in pixels.
+ * @param {Integer} height height in pixels.
+ * @return {p5.Image} new p5.Image object.
* @example
*
*
* let img = createImage(66, 66);
* img.loadPixels();
- * for (let i = 0; i < img.width; i++) {
- * for (let j = 0; j < img.height; j++) {
- * img.set(i, j, color(0, 90, 102));
+ * for (let x = 0; x < img.width; x += 1) {
+ * for (let y = 0; y < img.height; y += 1) {
+ * img.set(x, y, 0);
* }
* }
* img.updatePixels();
* image(img, 17, 17);
+ *
+ * describe('A black square drawn in the middle of a gray square.');
*
*
*
@@ -52,39 +52,42 @@ import omggif from 'omggif';
*
* let img = createImage(66, 66);
* img.loadPixels();
- * for (let i = 0; i < img.width; i++) {
- * for (let j = 0; j < img.height; j++) {
- * img.set(i, j, color(0, 90, 102, (i % img.width) * 2));
+ * for (let x = 0; x < img.width; x += 1) {
+ * for (let y = 0; y < img.height; y += 1) {
+ * let a = map(x, 0, img.width, 0, 255);
+ * let c = color(0, a);
+ * img.set(x, y, c);
* }
* }
* img.updatePixels();
* image(img, 17, 17);
- * image(img, 34, 34);
+ *
+ * describe('A square with a horizontal color gradient that transitions from gray to black.');
*
*
*
- * let pink = color(255, 102, 204);
* let img = createImage(66, 66);
* img.loadPixels();
* let d = pixelDensity();
- * let halfImage = 4 * (img.width * d) * (img.height / 2 * d);
+ * let halfImage = 4 * (d * img.width) * (d * img.height / 2);
* for (let i = 0; i < halfImage; i += 4) {
- * img.pixels[i] = red(pink);
- * img.pixels[i + 1] = green(pink);
- * img.pixels[i + 2] = blue(pink);
- * img.pixels[i + 3] = alpha(pink);
+ * // Red.
+ * img.pixels[i] = 0;
+ * // Green.
+ * img.pixels[i + 1] = 0;
+ * // Blue.
+ * img.pixels[i + 2] = 0;
+ * // Alpha.
+ * img.pixels[i + 3] = 255;
* }
* img.updatePixels();
* image(img, 17, 17);
+ *
+ * describe('A black square drawn in the middle of a gray square.');
*
*
- *
- * @alt
- * 66×66 dark turquoise rect in center of canvas.
- * 2 gradated dark turquoise rects fade left. 1 center 1 bottom right of canvas
- * no image displayed
*/
p5.prototype.createImage = function(width, height) {
p5._validateParameters('createImage', arguments);
@@ -92,46 +95,75 @@ p5.prototype.createImage = function(width, height) {
};
/**
- * Save the current canvas as an image. The browser will either save the
- * file immediately, or prompt the user with a dialogue window.
+ * Saves the current canvas as an image. The browser will either save the
+ * file immediately or prompt the user with a dialogue window.
*
* @method saveCanvas
- * @param {p5.Element|HTMLCanvasElement} selectedCanvas a variable
- * representing a specific html5 canvas (optional)
- * @param {String} [filename]
- * @param {String} [extension] 'jpg' or 'png'
+ * @param {p5.Element|HTMLCanvasElement} selectedCanvas reference to a
+ * specific HTML5 canvas element.
+ * @param {String} [filename] file name. Defaults to 'untitled'.
+ * @param {String} [extension] file extension, either 'jpg' or 'png'. Defaults to 'png'.
*
* @example
- *
+ *
+ *
* function setup() {
- * let c = createCanvas(100, 100);
- * background(255, 0, 0);
- * saveCanvas(c, 'myCanvas', 'jpg');
+ * createCanvas(100, 100);
+ * background(255);
+ * saveCanvas();
* }
- *
- *
- * // note that this example has the same result as above
- * // if no canvas is specified, defaults to main canvas
+ *
+ *
+ *
+ *
+ *
* function setup() {
- * let c = createCanvas(100, 100);
- * background(255, 0, 0);
+ * createCanvas(100, 100);
+ * background(255);
+ * saveCanvas('myCanvas.jpg');
+ * }
+ *
+ *
+ *
+ *
+ *
+ * function setup() {
+ * createCanvas(100, 100);
+ * background(255);
* saveCanvas('myCanvas', 'jpg');
+ * }
+ *
+ *
*
- * // all of the following are valid
- * saveCanvas(c, 'myCanvas', 'jpg');
- * saveCanvas(c, 'myCanvas.jpg');
- * saveCanvas(c, 'myCanvas');
- * saveCanvas(c);
- * saveCanvas('myCanvas', 'png');
- * saveCanvas('myCanvas');
- * saveCanvas();
+ *
+ *
+ * function setup() {
+ * let cnv = createCanvas(100, 100);
+ * background(255);
+ * saveCanvas(cnv);
* }
- *
+ *
+ *
+ *
+ * function setup() {
+ * let cnv = createCanvas(100, 100);
+ * background(255);
+ * saveCanvas(cnv, 'myCanvas.jpg');
+ * }
+ *
+ *
+ *
+ *
+ *
+ * function setup() {
+ * let cnv = createCanvas(100, 100);
+ * background(255);
+ * saveCanvas(cnv, 'myCanvas', 'jpg');
+ * }
+ *
+ *
*/
/**
* @method saveCanvas
@@ -413,50 +445,78 @@ p5.prototype.encodeAndDownloadGif = function(pImg, filename) {
};
/**
- * Capture a sequence of frames that can be used to create a movie.
- * Accepts a callback. For example, you may wish to send the frames
- * to a server where they can be stored or converted into a movie.
- * If no callback is provided, the browser will pop up save dialogues in an
- * attempt to download all of the images that have just been created. With the
- * callback provided the image data isn't saved by default but instead passed
- * as an argument to the callback function as an array of objects, with the
- * size of array equal to the total number of frames.
+ * Captures a sequence of frames from the canvas that can be used to create a
+ * movie. Frames are downloaded as individual image files by default.
+ *
+ * The first parameter, `filename`, sets the prefix for the file names. For
+ * example, setting the prefix to `'frame'` would generate the image files
+ * `frame0.png`, `frame1.png`, and so on. The second parameter, `extension`,
+ * sets the file type to either `'png'` or `'jpg'`.
*
- * The arguments `duration` and `framerate` are constrained to be less or equal to 15 and 22, respectively, which means you
- * can only download a maximum of 15 seconds worth of frames at 22 frames per second, adding up to 330 frames.
- * This is done in order to avoid memory problems since a large enough canvas can fill up the memory in your computer
- * very easily and crash your program or even your browser.
+ * The third parameter, `duration`, sets the duration to record in seconds.
+ * The maximum duration is 15 seconds. The fourth parameter, `framerate`, sets
+ * the number of frames to record per second. The maximum frame rate value is
+ * 22. Limits are placed on `duration` and `framerate` to avoid using too much
+ * memory. Recording large canvases can easily crash sketches or even web
+ * browsers.
*
- * To export longer animations, you might look into a library like
- * ccapture.js .
+ * The fifth parameter, `callback`, is optional. If a function is passed,
+ * image files won't be saved by default. The callback function can be used
+ * to process an array containing the data for each captured frame. The array
+ * of image data contains a sequence of objects with three properties for each
+ * frame: `imageData`, `filename`, and `extension`.
*
- * @method saveFrames
- * @param {String} filename
- * @param {String} extension 'jpg' or 'png'
- * @param {Number} duration Duration in seconds to save the frames for. This parameter will be constrained to be less or equal to 15.
- * @param {Number} framerate Framerate to save the frames in. This parameter will be constrained to be less or equal to 22.
- * @param {function(Array)} [callback] A callback function that will be executed
+ * @method saveFrames
+ * @param {String} filename prefix of file name.
+ * @param {String} extension file extension, either 'jpg' or 'png'.
+ * @param {Number} duration duration in seconds to record. This parameter will be constrained to be less or equal to 15.
+ * @param {Number} framerate number of frames to save per second. This parameter will be constrained to be less or equal to 22.
+ * @param {function(Array)} [callback] callback function that will be executed
to handle the image data. This function
should accept an array as argument. The
array will contain the specified number of
frames of objects. Each object has three
- properties: imageData - an
- image/octet-stream, filename and extension.
- * @example
- *
+ properties: `imageData`, `filename`, and `extension`.
+ * @example
+ *
+ *
+ * function draw() {
+ * let r = frameCount % 255;
+ * let g = 50;
+ * let b = 100;
+ * background(r, g, b);
+ *
+ * describe('A square repeatedly changes color from blue to pink.');
+ * }
+ *
+ * function keyPressed() {
+ * if (key === 's') {
+ * saveFrames('frame', 'png', 1, 5);
+ * }
+ * }
+ *
+ *
+ *
+ *
+ *
* function draw() {
- * background(mouseX);
+ * let r = frameCount % 255;
+ * let g = 50;
+ * let b = 100;
+ * background(r, g, b);
+ *
+ * describe('A square repeatedly changes color from blue to pink.');
* }
*
* function mousePressed() {
- * saveFrames('out', 'png', 1, 25, data => {
+ * saveFrames('frame', 'png', 1, 5, data => {
+ * // Prints an array of objects containing raw image data,
+ * // filenames, and extensions.
* print(data);
* });
* }
-
- *
- * @alt
- * canvas background goes from light to dark with mouse x.
+ *
+ *
p5.Image from it.
+ * Loads an image to create a p5.Image object.
*
- * The image may not be immediately available for rendering.
- * If you want to ensure that the image is ready before doing
- * anything with it, place the loadImage() call in preload() .
- * You may also supply a callback function to handle the image when it's ready.
+ * `loadImage()` interprets the first parameter one of three ways. If the path
+ * to an image file is provided, `loadImage()` will load it. Paths to local
+ * files should be relative, such as `'assets/thundercat.jpg'`. URLs such as
+ * `'https://example.com/thundercat.jpg'` may be blocked due to browser
+ * security. Raw image data can also be passed as a base64 encoded image in
+ * the form `'data:image/png;base64,arandomsequenceofcharacters'`.
*
- * The path to the image should be relative to the HTML file
- * that links in your sketch. Loading an image from a URL or other
- * remote location may be blocked due to your browser's built-in
- * security.
-
- * You can also pass in a string of a base64 encoded image as an alternative to the file path.
- * Remember to add "data:image/png;base64," in front of the string.
+ * The second parameter is optional. If a function is passed, it will be
+ * called once the image has loaded. The callback function can optionally use
+ * the new p5.Image object.
+ *
+ * The third parameter is also optional. If a function is passed, it will be
+ * called if the image fails to load. The callback function can optionally use
+ * the event error.
+ *
+ * Images can take time to load. Calling `loadImage()` in
+ * preload() ensures images load before they're
+ * used in setup() or draw() .
*
* @method loadImage
- * @param {String} path Path of the image to be loaded
- * @param {function(p5.Image)} [successCallback] Function to be called once
- * the image is loaded. Will be passed the
- * p5.Image .
- * @param {function(Event)} [failureCallback] called with event error if
- * the image fails to load.
- * @return {p5.Image} the p5.Image object
+ * @param {String} path path of the image to be loaded or base64 encoded image.
+ * @param {function(p5.Image)} [successCallback] function called with
+ * p5.Image once it
+ * loads.
+ * @param {function(Event)} [failureCallback] function called with event
+ * error if the image fails to load.
+ * @return {p5.Image} the p5.Image object.
* @example
*
*
* let img;
+ *
* function preload() {
* img = loadImage('assets/laDefense.jpg');
* }
+ *
* function setup() {
* image(img, 0, 0);
+ * describe('Image of the underside of a white umbrella and a gridded ceiling.');
* }
*
*
+ *
*
*
* function setup() {
- * // here we use a callback to display the image after loading
* loadImage('assets/laDefense.jpg', img => {
* image(img, 0, 0);
* });
+ * describe('Image of the underside of a white umbrella and a gridded ceiling.');
* }
*
*
*
- * @alt
- * image of the underside of a white umbrella and grided ceililng above
- * image of the underside of a white umbrella and grided ceililng above
+ *
+ *
+ * function setup() {
+ * loadImage('assets/laDefense.jpg', success, failure);
+ * }
+ *
+ * function success(img) {
+ * image(img, 0, 0);
+ * describe('Image of the underside of a white umbrella and a gridded ceiling.');
+ * }
+ *
+ * function failure(event) {
+ * console.error('Oops!', event);
+ * }
+ *
+ *
*/
p5.prototype.loadImage = function(path, successCallback, failureCallback) {
p5._validateParameters('loadImage', arguments);
@@ -163,74 +186,48 @@ p5.prototype.loadImage = function(path, successCallback, failureCallback) {
};
/**
- * Generates a gif of your current animation and downloads it to your computer!
- *
- * The duration argument specifies how many seconds you want to record from your animation.
- * This value is then converted to the necessary number of frames to generate it, depending
- * on the value of units. More on that on the next paragraph.
- *
- * An optional object that can contain two more arguments: delay (number) and units (string).
+ * Generates a gif from a sketch and saves it to a file. `saveGif()` may be
+ * called in setup() or at any point while a sketch
+ * is running.
*
- * `delay`, specifying how much time we should wait before recording
+ * The first parameter, `fileName`, sets the gif's file name. The second
+ * parameter, `duration`, sets the gif's duration in seconds.
*
- * `units`, a string that can be either 'seconds' or 'frames'. By default it's 'seconds'.
- *
- * `units` specifies how the duration and delay arguments will behave.
- * If 'seconds', these arguments will correspond to seconds, meaning that 3 seconds worth of animation
- * will be created. If 'frames', the arguments now correspond to the number of frames you want your
- * animation to be, if you are very sure of this number.
- *
- * This may be called in setup, or, like in the example below, inside an event function,
- * like keyPressed or mousePressed.
+ * The third parameter, `options`, is optional. If an object is passed,
+ * `saveGif()` will use its properties to customize the gif. `saveGif()`
+ * recognizes the properties `delay`, `units`, `silent`,
+ * `notificationDuration`, and `notificationID`.
*
* @method saveGif
- * @param {String} filename File name of your gif
- * @param {Number} duration Duration in seconds that you wish to capture from your sketch
- * @param {Object} options An optional object that can contain five more arguments:
- * delay, specifying how much time we should wait before recording;
- * units, a string that can be either 'seconds' or 'frames'. By default it's 'seconds’;
- * silent, a boolean that defines presence of progress notifications. By default it’s false;
- * notificationDuration, a number that defines how long in seconds the final notification
- * will live. 0, the default value, means that the notification will never be removed;
- * notificationID, a string that specifies the notification DOM element id. By default it’s 'progressBar’.
+ * @param {String} filename file name of gif.
+ * @param {Number} duration duration in seconds to capture from the sketch.
+ * @param {Object} [options] an object that can contain five more properties:
+ * `delay`, a Number specifying how much time to wait before recording;
+ * `units`, a String that can be either 'seconds' or 'frames'. By default it's 'seconds’;
+ * `silent`, a Boolean that defines presence of progress notifications. By default it’s `false`;
+ * `notificationDuration`, a Number that defines how long in seconds the final notification
+ * will live. By default it's `0`, meaning the notification will never be removed;
+ * `notificationID`, a String that specifies the id of the notification's DOM element. By default it’s `'progressBar’`.
*
* @example
*
*
- * function setup() {
- * createCanvas(100, 100);
- * }
- *
* function draw() {
- * colorMode(RGB);
- * background(30);
- *
- * // create a bunch of circles that move in... circles!
- * for (let i = 0; i < 10; i++) {
- * let opacity = map(i, 0, 10, 0, 255);
- * noStroke();
- * fill(230, 250, 90, opacity);
- * circle(
- * 30 * sin(frameCount / (30 - i)) + width / 2,
- * 30 * cos(frameCount / (30 - i)) + height / 2,
- * 10
- * );
- * }
+ * background(200);
+ * let c = frameCount % 255;
+ * fill(c);
+ * circle(50, 50, 25);
+ *
+ * describe('A circle drawn in the middle of a gray square. The circle changes color from black to white, then repeats.');
* }
*
- * // you can put it in the mousePressed function,
- * // or keyPressed for example
* function keyPressed() {
- * // this will download the first 5 seconds of the animation!
* if (key === 's') {
* saveGif('mySketch', 5);
* }
* }
*
*
- *
- * @alt
- * animation of a group of yellow circles moving in circles over a dark background
*/
p5.prototype.saveGif = async function(
fileName,
@@ -833,130 +830,152 @@ function _sAssign(sVal, iVal) {
}
/**
- * Draw an image to the p5.js canvas.
- *
- * This function can be used with different numbers of parameters. The
- * simplest use requires only three parameters: img, x, and y—where (x, y) is
- * the position of the image. Two more parameters can optionally be added to
- * specify the width and height of the image.
- *
- * This function can also be used with eight Number parameters. To
- * differentiate between all these parameters, p5.js uses the language of
- * "destination rectangle" (which corresponds to "dx", "dy", etc.) and "source
- * image" (which corresponds to "sx", "sy", etc.) below. Specifying the
- * "source image" dimensions can be useful when you want to display a
- * subsection of the source image instead of the whole thing. Here's a diagram
- * to explain further:
+ * Draws a source image to the canvas.
+ *
+ * The first parameter, `img`, is the source image to be drawn. The second and
+ * third parameters, `dx` and `dy`, set the coordinates of the destination
+ * image's top left corner. See imageMode() for
+ * other ways to position images.
+ *
+ * Here's a diagram that explains how optional parameters work in `image()`:
+ *
*
*
* let img;
+ *
* function preload() {
* img = loadImage('assets/laDefense.jpg');
* }
+ *
* function setup() {
- * // Top-left corner of the img is at (0, 0)
- * // Width and height are the img's original width and height
+ * background(50);
* image(img, 0, 0);
+ *
+ * describe('An image of the underside of a white umbrella with a gridded ceiling above.');
* }
*
*
+ *
*
*
* let img;
+ *
* function preload() {
* img = loadImage('assets/laDefense.jpg');
* }
+ *
* function setup() {
* background(50);
- * // Top-left corner of the img is at (10, 10)
- * // Width and height are 50×50
- * image(img, 10, 10, 50, 50);
+ * image(img, 10, 10);
+ *
+ * describe('An image of the underside of a white umbrella with a gridded ceiling above. The image has dark gray borders on its left and top.');
* }
*
*
+ *
*
*
+ * let img;
+ *
+ * function preload() {
+ * img = loadImage('assets/laDefense.jpg');
+ * }
+ *
* function setup() {
- * // Here, we use a callback to display the image after loading
- * loadImage('assets/laDefense.jpg', img => {
- * image(img, 0, 0);
- * });
+ * background(50);
+ * image(img, 0, 0, 50, 50);
+ *
+ * describe('An image of the underside of a white umbrella with a gridded ceiling above. The image is drawn in the top left corner of a dark gray square.');
* }
*
*
+ *
*
*
* let img;
+ *
* function preload() {
- * img = loadImage('assets/gradient.png');
+ * img = loadImage('assets/laDefense.jpg');
* }
+ *
* function setup() {
- * // 1. Background image
- * // Top-left corner of the img is at (0, 0)
- * // Width and height are the img's original width and height, 100×100
- * image(img, 0, 0);
- * // 2. Top right image
- * // Top-left corner of destination rectangle is at (50, 0)
- * // Destination rectangle width and height are 40×20
- * // The next parameters are relative to the source image:
- * // - Starting at position (50, 50) on the source image, capture a 50×50
- * // subsection
- * // - Draw this subsection to fill the dimensions of the destination rectangle
- * image(img, 50, 0, 40, 20, 50, 50, 50, 50);
+ * background(50);
+ * image(img, 25, 25, 50, 50, 25, 25, 50, 50);
+ *
+ * describe('An image of a gridded ceiling drawn in the center of a dark gray square.');
* }
*
*
+ *
*
*
* let img;
+ *
* function preload() {
- * // dimensions of image are 780 x 440
- * // dimensions of canvas are 100 x 100
* img = loadImage('assets/moonwalk.jpg');
* }
+ *
* function setup() {
- * // CONTAIN the whole image without distorting the image's aspect ratio
- * // CONTAIN the image within the specified destination box and display at LEFT,CENTER position
- * background(color('green'));
- * image(img, 0, 0, width, height, 0, 0, img.width, img.height, CONTAIN, LEFT);
+ * background(50);
+ * image(img, 0, 0, width, height, 0, 0, img.width, img.height, CONTAIN);
+ *
+ * describe('An image of an astronaut on the moon. The top and bottom borders of the image are dark gray.');
* }
*
*
+ *
*
*
* let img;
+ *
* function preload() {
- * img = loadImage('assets/laDefense50.png'); // dimensions of image are 50 x 50
+ * // Image is 50 x 50 pixels.
+ * img = loadImage('assets/laDefense50.png');
* }
+ *
* function setup() {
- * // COVER the whole destination box without distorting the image's aspect ratio
- * // COVER the specified destination box which is of dimension 100 x 100
- * // Without specifying xAlign or yAlign, the image will be
- * // centered in the destination box in both axes
+ * background(50);
* image(img, 0, 0, width, height, 0, 0, img.width, img.height, COVER);
+ *
+ * describe('A pixelated image of the underside of a white umbrella with a gridded ceiling above.');
* }
*
*
- * @alt
- * image of the underside of a white umbrella and gridded ceiling above
- * image of the underside of a white umbrella and gridded ceiling above
*/
/**
* @method image
@@ -1003,10 +1022,14 @@ p5.prototype.image = function(
yAlign = yAlign || constants.CENTER;
xAlign = xAlign || constants.CENTER;
+ if (img.elt) {
+ defW = defW !== undefined ? defW : img.elt.width;
+ defH = defH !== undefined ? defH : img.elt.height;
+ }
if (img.elt && img.elt.videoWidth && !img.canvas) {
// video no canvas
- defW = img.elt.videoWidth;
- defH = img.elt.videoHeight;
+ defW = defW !== undefined ? defW : img.elt.videoWidth;
+ defH = defH !== undefined ? defH : img.elt.videoHeight;
}
let _dx = dx;
@@ -1015,8 +1038,8 @@ p5.prototype.image = function(
let _dh = dHeight || defH;
let _sx = sx || 0;
let _sy = sy || 0;
- let _sw = sWidth || defW;
- let _sh = sHeight || defH;
+ let _sw = sWidth !== undefined ? sWidth : defW;
+ let _sh = sHeight !== undefined ? sHeight : defH;
_sw = _sAssign(_sw, defW);
_sh = _sAssign(_sh, defH);
@@ -1073,38 +1096,45 @@ p5.prototype.image = function(
};
/**
- * Sets the fill value for displaying images. Images can be tinted to
- * specified colors or made transparent by including an alpha value.
+ * Tints images using a specified color.
*
- * To apply transparency to an image without affecting its color, use
- * white as the tint color and specify an alpha value. For instance,
- * tint(255, 128) will make an image 50% transparent (assuming the default
- * alpha range of 0-255, which can be changed with colorMode() ).
+ * The version of `tint()` with one parameter interprets it 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. An array of
+ * `[R, G, B, A]` values or a p5.Color object can
+ * also be used to set the tint color.
*
- * The value for the gray parameter must be less than or equal to the current
- * maximum value as specified by colorMode() . The default maximum value is
- * 255.
+ * The version of `tint()` with two parameters uses the first one as a
+ * grayscale value and the second as an alpha value. For example, calling
+ * `tint(255, 128)` will make an image 50% transparent.
+ *
+ * The version of `tint()` with three parameters interprets them as RGB or
+ * HSB values, depending on the current
+ * colorMode() . The optional fourth parameter
+ * sets the alpha value. For example, `tint(255, 0, 0, 100)` will give images
+ * a red tint and make them transparent.
*
* @method tint
- * @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 or hue value.
+ * @param {Number} v2 green or saturation value.
+ * @param {Number} v3 blue or brightness.
* @param {Number} [alpha]
*
* @example
*
*
* let img;
+ *
* function preload() {
* img = loadImage('assets/laDefense.jpg');
* }
+ *
* function setup() {
* image(img, 0, 0);
- * tint(0, 153, 204); // Tint blue
+ * tint('red');
* image(img, 50, 0);
+ *
+ * describe('Two images of an umbrella and a ceiling side-by-side. The image on the right has a red tint.');
* }
*
*
@@ -1112,13 +1142,17 @@ p5.prototype.image = function(
*
*
* let img;
+ *
* function preload() {
* img = loadImage('assets/laDefense.jpg');
* }
+ *
* function setup() {
* image(img, 0, 0);
- * tint(0, 153, 204, 126); // Tint blue and set transparency
+ * tint(255, 0, 0);
* image(img, 50, 0);
+ *
+ * describe('Two images of an umbrella and a ceiling side-by-side. The image on the right has a red tint.');
* }
*
*
@@ -1126,38 +1160,54 @@ p5.prototype.image = function(
*
*
* let img;
+ *
* function preload() {
* img = loadImage('assets/laDefense.jpg');
* }
+ *
* function setup() {
* image(img, 0, 0);
- * tint(255, 126); // Apply transparency without changing color
+ * tint(255, 0, 0, 100);
* image(img, 50, 0);
+ *
+ * describe('Two images of an umbrella and a ceiling side-by-side. The image on the right has a transparent red tint.');
* }
*
*
*
- * @alt
- * 2 side by side images of umbrella and ceiling, one image with blue tint
- * Images of umbrella and ceiling, one half of image with blue tint
- * 2 side by side images of umbrella and ceiling, one image translucent
+ *
+ *
+ * let img;
+ *
+ * function preload() {
+ * img = loadImage('assets/laDefense.jpg');
+ * }
+ *
+ * function setup() {
+ * image(img, 0, 0);
+ * tint(255, 180);
+ * image(img, 50, 0);
+ *
+ * describe('Two images of an umbrella and a ceiling side-by-side. The image on the right is transparent.');
+ * }
+ *
+ *
*/
-
/**
* @method tint
- * @param {String} value a color string
+ * @param {String} value CSS color string.
*/
/**
* @method tint
- * @param {Number} gray a gray value
+ * @param {Number} gray grayscale value.
* @param {Number} [alpha]
*/
/**
* @method tint
- * @param {Number[]} values an array containing the red,green,blue &
- * and alpha components of the color
+ * @param {Number[]} values array containing the red, green, blue &
+ * alpha components of the color.
*/
/**
@@ -1171,28 +1221,28 @@ p5.prototype.tint = function(...args) {
};
/**
- * Removes the current fill value for displaying images and reverts to
- * displaying images with their original hues.
+ * Removes the current tint set by tint() and restores
+ * images to their original colors.
*
* @method noTint
* @example
*
*
* let img;
+ *
* function preload() {
- * img = loadImage('assets/bricks.jpg');
+ * img = loadImage('assets/laDefense.jpg');
* }
* function setup() {
- * tint(0, 153, 204); // Tint blue
+ * tint('red');
* image(img, 0, 0);
- * noTint(); // Disable tint
+ * noTint();
* image(img, 50, 0);
+ *
+ * describe('Two images of an umbrella and a ceiling side-by-side. The image on the left has a red tint.');
* }
*
*
- *
- * @alt
- * 2 side by side images of bricks, left image with blue tint
*/
p5.prototype.noTint = function() {
this._renderer._tint = null;
@@ -1210,34 +1260,41 @@ p5.prototype._getTintedImageCanvas =
p5.Renderer2D.prototype._getTintedImageCanvas;
/**
- * Set image mode. Modifies the location from which images are drawn by
- * changing the way in which parameters given to image() are interpreted.
- * The default mode is imageMode(CORNER), which interprets the second and
- * third parameters of image() as the upper-left corner of the image. If
- * two additional parameters are specified, they are used to set the image's
- * width and height.
+ * Changes the location from which images are drawn when
+ * image() is called.
+ *
+ * By default, the first
+ * two parameters of image() are the x- and
+ * y-coordinates of the image's upper-left corner. The next parameters are
+ * its width and height. This is the same as calling `imageMode(CORNER)`.
*
- * imageMode(CORNERS) interprets the second and third parameters of image()
- * as the location of one corner, and the fourth and fifth parameters as the
- * opposite corner.
+ * `imageMode(CORNERS)` also uses the first two parameters of
+ * image() as the x- and y-coordinates of the image's
+ * top-left corner. The third and fourth parameters are the coordinates of its
+ * bottom-right corner.
*
- * imageMode(CENTER) interprets the second and third parameters of image()
- * as the image's center point. If two additional parameters are specified,
- * they are used to set the image's width and height.
+ * `imageMode(CENTER)` uses the first two parameters of
+ * image() as the x- and y-coordinates of the image's
+ * center. The next parameters are its width and height.
*
* @method imageMode
- * @param {Constant} mode either CORNER, CORNERS, or CENTER
+ * @param {Constant} mode either CORNER, CORNERS, or CENTER.
* @example
*
*
*
* let img;
+ *
* function preload() {
* img = loadImage('assets/bricks.jpg');
* }
+ *
* function setup() {
+ * background(200);
* imageMode(CORNER);
* image(img, 10, 10, 50, 50);
+ *
+ * describe('A square image of a brick wall is drawn at the top left of a gray square.');
* }
*
*
@@ -1245,12 +1302,17 @@ p5.prototype._getTintedImageCanvas =
*
*
* let img;
+ *
* function preload() {
* img = loadImage('assets/bricks.jpg');
* }
+ *
* function setup() {
+ * background(200);
* imageMode(CORNERS);
* image(img, 10, 10, 90, 40);
+ *
+ * describe('An image of a brick wall is drawn on a gray square. The image is squeezed into a small rectangular area.');
* }
*
*
@@ -1258,20 +1320,20 @@ p5.prototype._getTintedImageCanvas =
*
*
* let img;
+ *
* function preload() {
* img = loadImage('assets/bricks.jpg');
* }
+ *
* function setup() {
+ * background(200);
* imageMode(CENTER);
* image(img, 50, 50, 80, 80);
+ *
+ * describe('A square image of a brick wall is drawn on a gray square.');
* }
*
*
- *
- * @alt
- * small square image of bricks
- * horizontal rectangle image of bricks
- * large square image of bricks
*/
p5.prototype.imageMode = function(m) {
p5._validateParameters('imageMode', arguments);
diff --git a/src/image/p5.Image.js b/src/image/p5.Image.js
index 36a5a162f8..4bc3f100c8 100644
--- a/src/image/p5.Image.js
+++ b/src/image/p5.Image.js
@@ -19,65 +19,65 @@ import Filters from './filters';
*/
/**
- * Creates a new p5.Image . A p5.Image is a canvas backed representation of an
- * image.
+ * A class to describe an image. Images are rectangular grids of pixels that
+ * can be displayed and modified.
*
- * p5 can display .gif, .jpg and .png images. Images may be displayed
- * in 2D and 3D space. Before an image is used, it must be loaded with the
- * loadImage() function. The p5.Image class contains fields for the width and
- * height of the image, as well as an array called pixels[] that contains the
- * values for every pixel in the image.
+ * Existing images can be loaded by calling
+ * loadImage() . Blank images can be created by
+ * calling createImage() . `p5.Image` objects
+ * have methods for common tasks such as applying filters and modifying
+ * pixel values.
*
- * The methods described below allow easy access to the image's pixels and
- * alpha channel and simplify the process of compositing.
- *
- * Before using the pixels[] array, be sure to use the loadPixels() method on
- * the image to make sure that the pixel data is properly loaded.
* @example
- *
- * function setup() {
- * let img = createImage(100, 100); // same as new p5.Image(100, 100);
- * img.loadPixels();
- * createCanvas(100, 100);
- * background(0);
+ *
+ *
+ * let img;
*
- * // helper for writing color to array
- * function writeColor(image, x, y, red, green, blue, alpha) {
- * let index = (x + y * width) * 4;
- * image.pixels[index] = red;
- * image.pixels[index + 1] = green;
- * image.pixels[index + 2] = blue;
- * image.pixels[index + 3] = alpha;
- * }
+ * function preload() {
+ * img = loadImage('assets/bricks.jpg');
+ * }
*
- * let x, y;
- * // fill with random colors
- * for (y = 0; y < img.height; y++) {
- * for (x = 0; x < img.width; x++) {
- * let red = random(255);
- * let green = random(255);
- * let blue = random(255);
- * let alpha = 255;
- * writeColor(img, x, y, red, green, blue, alpha);
- * }
- * }
+ * function setup() {
+ * image(img, 0, 0);
*
- * // draw a red line
- * y = 0;
- * for (x = 0; x < img.width; x++) {
- * writeColor(img, x, y, 255, 0, 0, 255);
- * }
+ * describe('An image of a brick wall.');
+ * }
+ *
+ *
*
- * // draw a green line
- * y = img.height - 1;
- * for (x = 0; x < img.width; x++) {
- * writeColor(img, x, y, 0, 255, 0, 255);
- * }
+ *
+ *
+ * let img;
+ *
+ * function preload() {
+ * img = loadImage('assets/bricks.jpg');
+ * }
*
- * img.updatePixels();
+ * function setup() {
+ * img.filter(GRAY);
* image(img, 0, 0);
+ *
+ * describe('A grayscale image of a brick wall.');
+ * }
+ *
+ *
+ *
+ *
+ *
+ * background(200);
+ * let img = createImage(66, 66);
+ * img.loadPixels();
+ * for (let x = 0; x < img.width; x += 1) {
+ * for (let y = 0; y < img.height; y += 1) {
+ * img.set(x, y, 0);
+ * }
* }
- *
+ * img.updatePixels();
+ * image(img, 17, 17);
+ *
+ * describe('A black square drawn in the middle of a gray square.');
+ *
+ *
+ *
+ *
* let img;
+ *
* function preload() {
* img = loadImage('assets/rockies.jpg');
* }
*
* function setup() {
- * createCanvas(100, 100);
* image(img, 0, 0);
- * for (let i = 0; i < img.width; i++) {
- * let c = img.get(i, img.height / 2);
- * stroke(c);
- * line(i, height / 2, i, height);
- * }
- * }
- *
- *
- * @alt
- * rocky mountains in top and horizontal lines in corresponding colors in bottom.
+ * let x = img.width / 2;
+ * let y = img.height / 2;
+ * let d = 20;
+ * circle(x, y, d);
*
+ * describe('An image of a mountain landscape with a white circle drawn in the middle.');
+ * }
+ *
+ *
+ *
+ *
* let img;
+ *
* function preload() {
* img = loadImage('assets/rockies.jpg');
* }
*
* function setup() {
- * createCanvas(100, 100);
* image(img, 0, 0);
- * for (let i = 0; i < img.height; i++) {
- * let c = img.get(img.width / 2, i);
- * stroke(c);
- * line(0, i, width / 2, i);
- * }
- * }
- *
- *
- * @alt
- * rocky mountains on right and vertical lines in corresponding colors on left.
+ * let x = img.width / 2;
+ * let y = img.height / 2;
+ * let d = 20;
+ * circle(x, y, d);
*
+ * describe('An image of a mountain landscape with a white circle drawn in the middle.');
+ * }
+ *
+ *
p5.Image object. Colors are stored as numbers
+ * representing red, green, blue, and alpha (RGBA) values. `img.pixels` is a
+ * one-dimensional array for performance reasons.
+ *
+ * Each pixel occupies four elements in the pixels array, one for each
+ * RGBA value. For example, the pixel at coordinates (0, 0) stores its
+ * RGBA values at `img.pixels[0]`, `img.pixels[1]`, `img.pixels[2]`,
+ * and `img.pixels[3]`, respectively. The next pixel at coordinates (1, 0)
+ * stores its RGBA values at `img.pixels[4]`, `img.pixels[5]`,
+ * `img.pixels[6]`, and `img.pixels[7]`. And so on. The `img.pixels` array
+ * for a 100×100 p5.Image object has
+ * 100 × 100 × 4 = 40,000 elements.
+ *
+ * Accessing the RGBA values for a pixel in the
+ * p5.Image object requires a little math as
+ * shown below. The img.loadPixels()
+ * method must be called before accessing the `img.pixels` array. The
+ * img.updatePixels() method must be
+ * called after any changes are made.
*
- * Before accessing this array, the data must loaded with the loadPixels()
- * function. After the array data has been modified, the updatePixels()
- * function must be run to update the changes.
* @property {Number[]} pixels
* @example
*
*
* let img = createImage(66, 66);
* img.loadPixels();
- * for (let i = 0; i < img.width; i++) {
- * for (let j = 0; j < img.height; j++) {
- * img.set(i, j, color(0, 90, 102));
- * }
+ * let numPixels = 4 * img.width * img.height;
+ * for (let i = 0; i < numPixels; i += 4) {
+ * // Red.
+ * img.pixels[i] = 0;
+ * // Green.
+ * img.pixels[i + 1] = 0;
+ * // Blue.
+ * img.pixels[i + 2] = 0;
+ * // Alpha.
+ * img.pixels[i + 3] = 255;
* }
* img.updatePixels();
* image(img, 17, 17);
+ *
+ * describe('A black square drawn in the middle of a gray square.');
*
*
+ *
*
*
- * let pink = color(255, 102, 204);
* let img = createImage(66, 66);
* img.loadPixels();
- * for (let i = 0; i < 4 * (width * height / 2); i += 4) {
- * img.pixels[i] = red(pink);
- * img.pixels[i + 1] = green(pink);
- * img.pixels[i + 2] = blue(pink);
- * img.pixels[i + 3] = alpha(pink);
+ * let numPixels = 4 * img.width * img.height;
+ * for (let i = 0; i < numPixels; i += 4) {
+ * // Red.
+ * img.pixels[i] = 255;
+ * // Green.
+ * img.pixels[i + 1] = 0;
+ * // Blue.
+ * img.pixels[i + 2] = 0;
+ * // Alpha.
+ * img.pixels[i + 3] = 255;
* }
* img.updatePixels();
* image(img, 17, 17);
+ *
+ * describe('A red square drawn in the middle of a gray square.');
*
*
- *
- * @alt
- * 66×66 turquoise rect in center of canvas
- * 66×66 pink rect in center of canvas
- *
*/
this.pixels = [];
}
+ /**
+ * Gets or sets the pixel density for high pixel density displays. By default,
+ * the density will be set to 1.
+ *
+ * Call this method with no arguments to get the default density, or pass
+ * in a number to set the density. If a non-positive number is provided,
+ * it defaults to 1.
+ *
+ * @method pixelDensity
+ * @param {Number} [density] A scaling factor for the number of pixels per
+ * side
+ * @returns {Number} The current density if called without arguments, or the instance for chaining if setting density.
+ */
+ pixelDensity(density) {
+ if (typeof density !== 'undefined') {
+ // Setter: set the density and handle resize
+ if (density <= 0) {
+ const errorObj = {
+ type: 'INVALID_VALUE',
+ format: { types: ['Number'] },
+ position: 1
+ };
+
+ p5._friendlyParamError(errorObj, 'pixelDensity');
+
+ // Default to 1 in case of an invalid value
+ density = 1;
+ }
+
+ this._pixelDensity = density;
+
+ // Adjust canvas dimensions based on pixel density
+ this.width /= density;
+ this.height /= density;
+
+ return this; // Return the image instance for chaining if needed
+ } else {
+ // Getter: return the default density
+ return this._pixelDensity;
+ }
+ }
+
/**
* Helper function for animating GIF-based images with time
*/
@@ -260,34 +301,49 @@ p5.Image = class {
}
/**
- * Loads the pixels data for this image into the [pixels] attribute.
+ * Loads the current value of each pixel in the
+ * p5.Image object into the `img.pixels` array.
+ * This method must be called before reading or modifying pixel values.
*
* @method loadPixels
* @example
- *
- * let myImage;
- * let halfImage;
- *
- * function preload() {
- * myImage = loadImage('assets/rockies.jpg');
- * }
- *
- * function setup() {
- * myImage.loadPixels();
- * halfImage = 4 * myImage.width * myImage.height / 2;
- * for (let i = 0; i < halfImage; i++) {
- * myImage.pixels[i + halfImage] = myImage.pixels[i];
+ *
+ *
+ * let img = createImage(66, 66);
+ * img.loadPixels();
+ * for (let x = 0; x < img.width; x += 1) {
+ * for (let y = 0; y < img.height; y += 1) {
+ * img.set(x, y, 0);
* }
- * myImage.updatePixels();
* }
+ * img.updatePixels();
+ * image(img, 17, 17);
*
- * function draw() {
- * image(myImage, 0, 0, width, height);
- * }
- *
+ * describe('A black square drawn in the middle of a gray square.');
+ *
+ *
+ *
+ * let img = createImage(66, 66);
+ * img.loadPixels();
+ * let numPixels = 4 * img.width * img.height;
+ * for (let i = 0; i < numPixels; i += 4) {
+ * // Red.
+ * img.pixels[i] = 0;
+ * // Green.
+ * img.pixels[i + 1] = 0;
+ * // Blue.
+ * img.pixels[i + 2] = 0;
+ * // Alpha.
+ * img.pixels[i + 3] = 255;
+ * }
+ * img.updatePixels();
+ * image(img, 17, 17);
+ *
+ * describe('A black square drawn in the middle of a gray square.');
+ *
+ *
*/
loadPixels() {
p5.Renderer2D.prototype.loadPixels.call(this);
@@ -295,46 +351,68 @@ p5.Image = class {
}
/**
- * Updates the backing canvas for this image with the contents of
- * the [pixels] array.
+ * Updates the canvas with the RGBA values in the
+ * img.pixels array.
*
- * If this image is an animated GIF then the pixels will be updated
- * in the frame that is currently displayed.
+ * `img.updatePixels()` only needs to be called after changing values in
+ * the img.pixels array. Such changes can be
+ * made directly after calling
+ * img.loadPixels() or by calling
+ * img.set() .
*
- * @method updatePixels
- * @param {Integer} x x-offset of the target update area for the
- * underlying canvas
- * @param {Integer} y y-offset of the target update area for the
- * underlying canvas
- * @param {Integer} w width of the target update area for the
- * underlying canvas
- * @param {Integer} h height of the target update area for the
- * underlying canvas
- * @example
- *
- * let myImage;
- * let halfImage;
+ * The optional parameters `x`, `y`, `width`, and `height` define a
+ * subsection of the p5.Image object to update.
+ * Doing so can improve performance in some cases.
*
- * function preload() {
- * myImage = loadImage('assets/rockies.jpg');
- * }
+ * If the p5.Image object was loaded from a GIF,
+ * then calling `img.updatePixels()` will update the pixels in current
+ * frame.
*
- * function setup() {
- * myImage.loadPixels();
- * halfImage = 4 * myImage.width * myImage.height / 2;
- * for (let i = 0; i < halfImage; i++) {
- * myImage.pixels[i + halfImage] = myImage.pixels[i];
+ * @method updatePixels
+ * @param {Integer} x x-coordinate of the upper-left corner
+ * of the subsection to update.
+ * @param {Integer} y y-coordinate of the upper-left corner
+ * of the subsection to update.
+ * @param {Integer} w width of the subsection to update.
+ * @param {Integer} h height of the subsection to update.
+ * @example
+ *
+ *
+ * let img = createImage(66, 66);
+ * img.loadPixels();
+ * for (let x = 0; x < img.width; x += 1) {
+ * for (let y = 0; y < img.height; y += 1) {
+ * img.set(x, y, 0);
* }
- * myImage.updatePixels();
* }
+ * img.updatePixels();
+ * image(img, 17, 17);
*
- * function draw() {
- * image(myImage, 0, 0, width, height);
+ * describe('A black square drawn in the middle of a gray square.');
+ *
+ *
+ *
+ *
+ *
+ * let img = createImage(66, 66);
+ * img.loadPixels();
+ * let numPixels = 4 * img.width * img.height;
+ * for (let i = 0; i < numPixels; i += 4) {
+ * // Red.
+ * img.pixels[i] = 0;
+ * // Green.
+ * img.pixels[i + 1] = 0;
+ * // Blue.
+ * img.pixels[i + 2] = 0;
+ * // Alpha.
+ * img.pixels[i + 3] = 255;
* }
- *
+ * img.updatePixels();
+ * image(img, 17, 17);
*
- * @alt
- * 2 images of rocky mountains vertically stacked
+ * describe('A black square drawn in the middle of a gray square.');
+ *
+ *
p5.Image object.
+ *
+ * `img.get()` is easy to use but it's not as fast as
+ * img.pixels . Use
+ * img.pixels to read many pixel values.
+ *
+ * The version of `img.get()` with no parameters returns the entire image.
*
- * If no params are passed, the whole image is returned.
- * If x and y are the only params passed a single pixel is extracted.
- * If all params are passed a rectangle region is extracted and a p5.Image
- * is returned.
+ * The version of `img.get()` with two parameters interprets them as
+ * coordinates. It returns an array with the `[R, G, B, A]` values of the
+ * pixel at the given point.
+ *
+ * The version of `img.get()` with four parameters interprets them as
+ * coordinates and dimensions. It returns a subsection of the canvas as a
+ * p5.Image object. The first two parameters are
+ * the coordinates for the upper-left corner of the subsection. The last two
+ * parameters are the width and height of the subsection.
+ *
+ * Use img.get() to work directly with
+ * p5.Image objects.
*
* @method get
- * @param {Number} x x-coordinate of the pixel
- * @param {Number} y y-coordinate of the pixel
- * @param {Number} w width
- * @param {Number} h height
- * @return {p5.Image} the rectangle p5.Image
+ * @param {Number} x x-coordinate of the pixel.
+ * @param {Number} y y-coordinate of the pixel.
+ * @param {Number} w width of the subsection to be returned.
+ * @param {Number} h height of the subsection to be returned.
+ * @return {p5.Image} subsection as a p5.Image object.
* @example
- *
- * let myImage;
- * let c;
+ *
+ *
+ * let img;
*
* function preload() {
- * myImage = loadImage('assets/rockies.jpg');
+ * img = loadImage('assets/rockies.jpg');
* }
*
* function setup() {
- * background(myImage);
- * noStroke();
- * c = myImage.get(60, 90);
+ * image(img, 0, 0);
+ * let img2 = get();
+ * image(img2, width / 2, 0);
+ *
+ * describe('Two identical mountain landscapes shown side-by-side.');
+ * }
+ *
+ *
+ *
+ *
+ *
+ * let img;
+ *
+ * function preload() {
+ * img = loadImage('assets/rockies.jpg');
+ * }
+ *
+ * function setup() {
+ * image(img, 0, 0);
+ * let c = img.get(50, 90);
* fill(c);
- * rect(25, 25, 50, 50);
+ * noStroke();
+ * square(25, 25, 50);
+ *
+ * describe('A mountain landscape with an olive green square in its center.');
* }
+ *
+ *
*
- * //get() returns color here
- *
+ *
+ * let img;
*
- * @alt
- * image of rocky mountains with 50×50 green rect in front
+ * function preload() {
+ * img = loadImage('assets/rockies.jpg');
+ * }
+ *
+ * function setup() {
+ * image(img, 0, 0);
+ * let img2 = img.get(0, 0, img.width / 2, img.height / 2);
+ * image(img2, width / 2, height / 2);
+ *
+ * describe('A mountain landscape drawn on top of another mountain landscape.');
+ * }
+ *
+ *
*/
/**
* @method get
- * @return {p5.Image} the whole p5.Image
+ * @return {p5.Image} whole p5.Image
*/
/**
* @method get
* @param {Number} x
* @param {Number} y
- * @return {Number[]} color of pixel at x,y in array format [R, G, B, A]
+ * @return {Number[]} color of the pixel at (x, y) in array format `[R, G, B, A]`.
*/
get(x, y, w, h) {
p5._validateParameters('p5.Image.get', arguments);
@@ -401,36 +528,90 @@ p5.Image = class {
}
/**
- * Set the color of a single pixel or write an image into
- * this p5.Image .
+ * Sets the color of one or more pixels within a
+ * p5.Image object.
*
- * Note that for a large number of pixels this will
- * be slower than directly manipulating the pixels array
- * and then calling updatePixels() .
+ * `img.set()` is easy to use but it's not as fast as
+ * img.pixels . Use
+ * img.pixels to set many pixel values.
+ *
+ * `img.set()` interprets the first two parameters as x- and y-coordinates. It
+ * interprets the last parameter as a grayscale value, a `[R, G, B, A]` pixel
+ * array, a p5.Color object, or another
+ * p5.Image object.
+ *
+ * img.updatePixels() must be called
+ * after using `img.set()` for changes to appear.
*
* @method set
- * @param {Number} x x-coordinate of the pixel
- * @param {Number} y y-coordinate of the pixel
+ * @param {Number} x x-coordinate of the pixel.
+ * @param {Number} y y-coordinate of the pixel.
* @param {Number|Number[]|Object} a grayscale value | pixel array |
- * a p5.Color | image to copy
+ * p5.Color object |
+ * p5.Image to copy.
* @example
*
*
+ * let img = createImage(100, 100);
+ * img.set(30, 20, 0);
+ * img.set(85, 20, 0);
+ * img.set(85, 75, 0);
+ * img.set(30, 75, 0);
+ * img.updatePixels();
+ * image(img, 0, 0);
+ *
+ * describe('Four black dots arranged in a square drawn on a gray background.');
+ *
+ *
+ *
+ *
+ *
+ * let img = createImage(100, 100);
+ * let black = color(0);
+ * img.set(30, 20, black);
+ * img.set(85, 20, black);
+ * img.set(85, 75, black);
+ * img.set(30, 75, black);
+ * img.updatePixels();
+ * image(img, 0, 0);
+ *
+ * describe('Four black dots arranged in a square drawn on a gray background.');
+ *
+ *
+ *
+ *
+ *
* let img = createImage(66, 66);
- * img.loadPixels();
- * for (let i = 0; i < img.width; i++) {
- * for (let j = 0; j < img.height; j++) {
- * img.set(i, j, color(0, 90, 102, (i % img.width) * 2));
+ * for (let x = 0; x < img.width; x += 1) {
+ * for (let y = 0; y < img.height; y += 1) {
+ * let c = map(x, 0, img.width, 0, 255);
+ * img.set(x, y, c);
* }
* }
* img.updatePixels();
* image(img, 17, 17);
- * image(img, 34, 34);
+ *
+ * describe('A square with a horiztonal color gradient from black to white drawn on a gray background.');
*
*
*
- * @alt
- * 2 gradated dark turquoise rects fade left. 1 center 1 bottom right of canvas
+ *
+ *
+ * let img;
+ *
+ * function preload() {
+ * img = loadImage('assets/rockies.jpg');
+ * }
+ *
+ * function setup() {
+ * let img2 = createImage(100, 100);
+ * img2.set(0, 0, img);
+ * image(img2, 0, 0);
+ *
+ * describe('An image of a mountain landscape.');
+ * }
+ *
+ *
*/
set(x, y, imgOrCol) {
p5.Renderer2D.prototype.set.call(this, x, y, imgOrCol);
@@ -438,33 +619,69 @@ p5.Image = class {
}
/**
- * Resize the image to a new width and height. To make the image scale
- * proportionally, use 0 as the value for the wide or high parameter.
- * For instance, to make the width of an image 150 pixels, and change
- * the height using the same proportion, use resize(150, 0).
+ * Resizes the p5.Image object to a given `width`
+ * and `height`. The image's original aspect ratio can be kept by passing 0
+ * for either `width` or `height`. For example, calling `img.resize(50, 0)`
+ * on an image that was 500 × 300 pixels will resize it to
+ * 50 × 30 pixels.
*
* @method resize
- * @param {Number} width the resized image width
- * @param {Number} height the resized image height
+ * @param {Number} width resized image width.
+ * @param {Number} height resized image height.
* @example
- *
+ *
+ *
* let img;
*
* function preload() {
* img = loadImage('assets/rockies.jpg');
* }
- * function draw() {
+ * function setup() {
+ * image(img, 0, 0);
+ * img.resize(50, 100);
* image(img, 0, 0);
+ *
+ * describe('Two images of a mountain landscape. One copy of the image is squeezed horizontally.');
* }
+ *
+ *
*
- * function mousePressed() {
- * img.resize(50, 100);
+ *
+ *
+ * let img;
+ *
+ * function preload() {
+ * img = loadImage('assets/rockies.jpg');
+ * }
+
+ * function setup() {
+ * image(img, 0, 0);
+ * img.resize(0, 30);
+ * image(img, 0, 0);
+ *
+ * describe('Two images of a mountain landscape. The small copy of the image covers the top-left corner of the larger image.');
+ * }
+ *
+ *
+ *
+ *
+ *
+ * let img;
+ *
+ * function preload() {
+ * img = loadImage('assets/rockies.jpg');
* }
- *
+
+ * function setup() {
+ * image(img, 0, 0);
+ * img.resize(60, 0);
+ * image(img, 0, 0);
*
- * @alt
- * image of rocky mountains. zoomed in
+ * describe('Two images of a mountain landscape. The small copy of the image covers the top-left corner of the larger image.');
+ * }
+ *
+ *
p5.Image
+ * to this one. Calling `img.copy()` will scale pixels from the source
+ * region if it isn't the same size as the destination region.
*
* @method copy
- * @param {p5.Image|p5.Element} srcImage source image
- * @param {Integer} sx X coordinate of the source's upper left corner
- * @param {Integer} sy Y coordinate of the source's upper left corner
- * @param {Integer} sw source image width
- * @param {Integer} sh source image height
- * @param {Integer} dx X coordinate of the destination's upper left corner
- * @param {Integer} dy Y coordinate of the destination's upper left corner
- * @param {Integer} dw destination image width
- * @param {Integer} dh destination image height
+ * @param {p5.Image|p5.Element} srcImage source image.
+ * @param {Integer} sx x-coordinate of the source's upper-left corner.
+ * @param {Integer} sy y-coordinate of the source's upper-left corner.
+ * @param {Integer} sw source image width.
+ * @param {Integer} sh source image height.
+ * @param {Integer} dx x-coordinate of the destination's upper-left corner.
+ * @param {Integer} dy y-coordinate of the destination's upper-left corner.
+ * @param {Integer} dw destination image width.
+ * @param {Integer} dh destination image height.
+ *
* @example
- *
- * let photo;
+ *
+ *
+ * let img;
+ *
+ * function preload() {
+ * img = loadImage('assets/rockies.jpg');
+ * }
+ *
+ * function setup() {
+ * img.copy(7, 22, 10, 10, 35, 25, 50, 50);
+ * image(img, 0, 0);
+ * // Outline copied region.
+ * stroke(255);
+ * noFill();
+ * square(7, 22, 10);
+ *
+ * describe('An image of a mountain landscape. A square region is outlined in white. A larger square contains a pixelated view of the outlined region.');
+ * }
+ *
+ *
+ *
+ *
+ *
+ * let mountains;
* let bricks;
- * let x;
- * let y;
*
* function preload() {
- * photo = loadImage('assets/rockies.jpg');
+ * mountains = loadImage('assets/rockies.jpg');
* bricks = loadImage('assets/bricks.jpg');
* }
*
* function setup() {
- * x = bricks.width / 2;
- * y = bricks.height / 2;
- * photo.copy(bricks, 0, 0, x, y, 0, 0, x, y);
- * image(photo, 0, 0);
- * }
- *
+ * let x = bricks.width / 2;
+ * let y = bricks.height / 2;
+ * mountains.copy(bricks, 0, 0, x, y, 0, 0, x, y);
+ * image(mountains, 0, 0);
*
- * @alt
- * image of rocky mountains and smaller image on top of bricks at top left
+ * describe('An image of a brick wall drawn at the top-left of an image of a mountain landscape.');
+ * }
+ *
+ *
- * let photo, maskImage;
+ *
+ *
+ * let photo;
+ * let maskImage;
+ *
* function preload() {
* photo = loadImage('assets/rockies.jpg');
* maskImage = loadImage('assets/mask2.png');
* }
*
* function setup() {
- * createCanvas(100, 100);
* photo.mask(maskImage);
* image(photo, 0, 0);
- * }
- *
*
- * @alt
- * image of rocky mountains with white at right
- *
- * http://blogs.adobe.com/webplatform/2013/01/28/blending-features-in-canvas/
+ * describe('An image of a mountain landscape. The right side of the image has a faded patch of white.');
+ * }
+ *
+ *
p5.Image
+ * Applies an image filter to the p5.Image object.
+ * The preset options are:
*
- * THRESHOLD
- * Converts the image to black and white pixels depending if they are above or
- * below the threshold defined by the level parameter. The parameter must be
- * between 0.0 (black) and 1.0 (white). If no level is specified, 0.5 is used.
+ * `INVERT`
+ * Inverts the colors in the image. No parameter is used.
*
- * GRAY
- * Converts any colors in the image to grayscale equivalents. No parameter
- * is used.
+ * `GRAY`
+ * Converts the image to grayscale. No parameter is used.
*
- * OPAQUE
- * Sets the alpha channel to entirely opaque. No parameter is used.
+ * `THRESHOLD`
+ * Converts the image to black and white. Pixels with a grayscale value
+ * above a given threshold are converted to white. The rest are converted to
+ * black. The threshold must be between 0.0 (black) and 1.0 (white). If no
+ * value is specified, 0.5 is used.
*
- * INVERT
- * Sets each pixel to its inverse value. No parameter is used.
+ * `OPAQUE`
+ * Sets the alpha channel to be entirely opaque. No parameter is used.
*
- * POSTERIZE
- * Limits each channel of the image to the number of colors specified as the
- * parameter. The parameter can be set to values between 2 and 255, but
- * results are most noticeable in the lower ranges.
+ * `POSTERIZE`
+ * Limits the number of colors in the image. Each color channel is limited to
+ * the number of colors specified. Values between 2 and 255 are valid, but
+ * results are most noticeable with lower values. The default value is 4.
*
- * BLUR
- * Executes a Gaussian blur with the level parameter specifying the extent
- * of the blurring. If no parameter is used, the blur is equivalent to
- * Gaussian blur of radius 1. Larger values increase the blur.
+ * `BLUR`
+ * Blurs the image. The level of blurring is specified by a blur radius. Larger
+ * values increase the blur. The default value is 4. A gaussian blur is used
+ * in `P2D` mode. A box blur is used in `WEBGL` mode.
*
- * ERODE
+ * `ERODE`
* Reduces the light areas. No parameter is used.
*
- * DILATE
+ * `DILATE`
* Increases the light areas. No parameter is used.
*
- * filter() does not work in WEBGL mode.
- * A similar effect can be achieved in WEBGL mode using custom
- * shaders. Adam Ferriss has written
- * a selection of shader examples that contains many
- * of the effects present in the filter examples.
- *
* @method filter
* @param {Constant} filterType either THRESHOLD, GRAY, OPAQUE, INVERT,
* POSTERIZE, ERODE, DILATE or BLUR.
- * See Filters.js for docs on
- * each available filter
- * @param {Number} [filterParam] an optional parameter unique
- * to each filter, see above
+ * @param {Number} [filterParam] parameter unique to each filter.
* @example
- *
- * let photo1;
- * let photo2;
+ *
+ *
+ * let img;
*
* function preload() {
- * photo1 = loadImage('assets/rockies.jpg');
- * photo2 = loadImage('assets/rockies.jpg');
+ * img = loadImage('assets/bricks.jpg');
* }
*
* function setup() {
- * photo2.filter(GRAY);
- * image(photo1, 0, 0);
- * image(photo2, width / 2, 0);
+ * img.filter(INVERT);
+ * image(img, 0, 0);
+ *
+ * describe('A blue brick wall.');
+ * }
+ *
+ *
+ *
+ *
+ *
+ * let img;
+ *
+ * function preload() {
+ * img = loadImage('assets/bricks.jpg');
+ * }
+ *
+ * function setup() {
+ * img.filter(GRAY);
+ * image(img, 0, 0);
+ *
+ * describe('A brick wall drawn in grayscale.');
+ * }
+ *
+ *
+ *
+ *
+ *
+ * let img;
+ *
+ * function preload() {
+ * img = loadImage('assets/bricks.jpg');
+ * }
+ *
+ * function setup() {
+ * img.filter(THRESHOLD);
+ * image(img, 0, 0);
+ *
+ * describe('A brick wall drawn in black and white.');
+ * }
+ *
+ *
+ *
+ *
+ *
+ * let img;
+ *
+ * function preload() {
+ * img = loadImage('assets/bricks.jpg');
+ * }
+ *
+ * function setup() {
+ * img.filter(OPAQUE);
+ * image(img, 0, 0);
+ *
+ * describe('A red brick wall.');
+ * }
+ *
+ *
+ *
+ *
+ *
+ * let img;
+ *
+ * function preload() {
+ * img = loadImage('assets/bricks.jpg');
+ * }
+ *
+ * function setup() {
+ * img.filter(POSTERIZE, 3);
+ * image(img, 0, 0);
+ *
+ * describe('An image of a red brick wall drawn with a limited color palette.');
+ * }
+ *
+ *
+ *
+ *
+ *
+ * let img;
+ *
+ * function preload() {
+ * img = loadImage('assets/bricks.jpg');
+ * }
+ *
+ * function setup() {
+ * img.filter(BLUR, 3);
+ * image(img, 0, 0);
+ *
+ * describe('A blurry image of a red brick wall.');
+ * }
+ *
+ *
+ *
+ *
+ *
+ * let img;
+ *
+ * function preload() {
+ * img = loadImage('assets/bricks.jpg');
+ * }
+ *
+ * function setup() {
+ * img.filter(DILATE);
+ * image(img, 0, 0);
+ *
+ * describe('A red brick wall with bright lines between each brick.');
+ * }
+ *
+ *
+ *
+ *
+ *
+ * let img;
+ *
+ * function preload() {
+ * img = loadImage('assets/bricks.jpg');
* }
- *
*
- * @alt
- * 2 images of rocky mountains left one in color, right in black and white
+ * function setup() {
+ * img.filter(ERODE);
+ * image(img, 0, 0);
+ *
+ * describe('A red brick wall with faint lines between each brick.');
+ * }
+ *
+ *
p5.Image object into this one. The `blendMode`
+ * parameter blends the images' colors to create different effects.
*
* @method blend
* @param {p5.Image} srcImage source image
- * @param {Integer} sx X coordinate of the source's upper left corner
- * @param {Integer} sy Y coordinate of the source's upper left corner
- * @param {Integer} sw source image width
- * @param {Integer} sh source image height
- * @param {Integer} dx X coordinate of the destination's upper left corner
- * @param {Integer} dy Y coordinate of the destination's upper left corner
- * @param {Integer} dw destination image width
- * @param {Integer} dh destination image height
+ * @param {Integer} sx x-coordinate of the source's upper-left corner.
+ * @param {Integer} sy y-coordinate of the source's upper-left corner.
+ * @param {Integer} sw source image width.
+ * @param {Integer} sh source image height.
+ * @param {Integer} dx x-coordinate of the destination's upper-left corner.
+ * @param {Integer} dy y-coordinate of the destination's upper-left corner.
+ * @param {Integer} dw destination image width.
+ * @param {Integer} dh destination image height.
* @param {Constant} blendMode the blend mode. either
* BLEND, DARKEST, LIGHTEST, DIFFERENCE,
* MULTIPLY, EXCLUSION, SCREEN, REPLACE, OVERLAY, HARD_LIGHT,
@@ -779,7 +1126,8 @@ p5.Image = class {
*
* http://blogs.adobe.com/webplatform/2013/01/28/blending-features-in-canvas/
* @example
- *
+ *
+ *
* let mountains;
* let bricks;
*
@@ -792,9 +1140,14 @@ p5.Image = class {
* mountains.blend(bricks, 0, 0, 33, 100, 67, 0, 33, 100, ADD);
* image(mountains, 0, 0);
* image(bricks, 0, 0);
+ *
+ * describe('A wall of bricks in front of a mountain landscape. The same wall of bricks appears faded on the right of the image.');
* }
- *
- *
+ *
+ *
+ *
+ *
+ *
* let mountains;
* let bricks;
*
@@ -807,9 +1160,14 @@ p5.Image = class {
* mountains.blend(bricks, 0, 0, 33, 100, 67, 0, 33, 100, DARKEST);
* image(mountains, 0, 0);
* image(bricks, 0, 0);
+ *
+ * describe('A wall of bricks in front of a mountain landscape. The same wall of bricks appears transparent on the right of the image.');
* }
- *
- *
+ *
+ *
+ *
+ *
+ *
* let mountains;
* let bricks;
*
@@ -822,13 +1180,11 @@ p5.Image = class {
* mountains.blend(bricks, 0, 0, 33, 100, 67, 0, 33, 100, LIGHTEST);
* image(mountains, 0, 0);
* image(bricks, 0, 0);
- * }
- *
*
- * @alt
- * image of rocky mountains. Brick images on left and right. Right overexposed
- * image of rockies. Brickwall images on left and right. Right mortar transparent
- * image of rockies. Brickwall images on left and right. Right translucent
+ * describe('A wall of bricks in front of a mountain landscape. The same wall of bricks appears washed out on the right of the image.');
+ * }
+ *
+ *
p5.Image object to a file.
+ * The browser will either save the file immediately or prompt the user
+ * with a dialogue window.
+ *
+ * By default, calling `img.save()` will save the image as `untitled.png`.
+ *
+ * Calling `img.save()` with one argument, as in `img.save('photo.png')`,
+ * will set the image's filename and type together.
+ *
+ * Calling `img.save()` with two arguments, as in
+ * `image.save('photo', 'png')`, will set the image's filename and type
+ * separately.
+ *
+ * The image will only be downloaded as an animated GIF if the
+ * p5.Image object was loaded from a GIF file.
+ * See saveGif() to create new GIFs.
* @method save
- * @param {String} filename give your file a name
- * @param {String} extension 'png' or 'jpg'
+ * @param {String} filename filename. Defaults to 'untitled'.
+ * @param {String} [extension] file extension, either 'png' or 'jpg'.
+ * Defaults to 'png'.
* @example
- *
- * let photo;
+ *
+ *
+ * let img;
*
* function preload() {
- * photo = loadImage('assets/rockies.jpg');
+ * img = loadImage('assets/rockies.jpg');
* }
*
* function draw() {
- * image(photo, 0, 0);
+ * image(img, 0, 0);
+ *
+ * describe('An image of a mountain landscape.');
* }
*
- * function keyTyped() {
+ * function keyPressed() {
* if (key === 's') {
- * photo.save('photo', 'png');
+ * img.save();
+ * } else if (key === 'j') {
+ * img.save('rockies.jpg');
+ * } else if (key === 'p') {
+ * img.save('rockies', 'png');
* }
* }
- *
- *
- * @alt
- * image of rocky mountains.
+ *
+ *
+ *
+ *
* let gif;
*
* function preload() {
@@ -929,19 +1302,16 @@ p5.Image = class {
*
* function draw() {
* background(255);
- * // The GIF file that we loaded only loops once
- * // so it freezes on the last frame after playing through
* image(gif, 0, 0);
+ *
+ * describe('A cartoon face winks once and then freezes. Clicking resets the face and makes it wink again.');
* }
*
* function mousePressed() {
- * // Click to reset the GIF and begin playback from start
* gif.reset();
* }
- *
- * @alt
- * Animated image of a cartoon face that winks once and then freezes
- * When you click it animates again, winks once and freezes
+ *
+ *
+ *
+ *
* let gif;
*
* function preload() {
@@ -970,15 +1341,14 @@ p5.Image = class {
* }
*
* function draw() {
- * let frame = gif.getCurrentFrame();
+ * let index = gif.getCurrentFrame();
* image(gif, 0, 0);
- * text(frame, 10, 90);
+ * text(index, 10, 90);
+ *
+ * describe('A cartoon eye repeatedly looks around, then outwards. A number displayed in the bottom-left corner increases from 0 to 124, then repeats.');
* }
- *
- * @alt
- * Animated image of a cartoon eye looking around and then
- * looking outwards, in the lower-left hand corner a number counts
- * up quickly to 124 and then starts back over at 0
+ *
+ *
+ *
+ *
* let gif;
+ * let frameSlider;
*
* function preload() {
* gif = loadImage('assets/arnott-wallace-eye-loop-forever.gif');
* }
*
- * // Move your mouse up and down over canvas to see the GIF
- * // frames animate
+ * function setup() {
+ * let maxFrame = gif.numFrames() - 1;
+ * frameSlider = createSlider(0, maxFrame);
+ * frameSlider.position(10, 80);
+ * frameSlider.size(80);
+ * }
+ *
* function draw() {
- * gif.pause();
+ * let index = frameSlider.value();
+ * gif.setFrame(index);
* image(gif, 0, 0);
- * // Get the highest frame number which is the number of frames - 1
- * let maxFrame = gif.numFrames() - 1;
- * // Set the current frame that is mapped to be relative to mouse position
- * let frameNumber = floor(map(mouseY, 0, height, 0, maxFrame, true));
- * gif.setFrame(frameNumber);
- * }
- *
- * @alt
- * A still image of a cartoon eye that looks around when you move your mouse
- * up and down over the canvas
+ *
+ * describe('A cartoon eye looks around when a slider is moved.');
+ * }
+ *
+ *
+ * @return {Number} number of frames in the GIF.
+ *
+ * @example
+ *
+ *
* let gif;
*
* function preload() {
* gif = loadImage('assets/arnott-wallace-eye-loop-forever.gif');
* }
*
- * // Move your mouse up and down over canvas to see the GIF
- * // frames animate
* function draw() {
- * gif.pause();
* image(gif, 0, 0);
- * // Get the highest frame number which is the number of frames - 1
- * let maxFrame = gif.numFrames() - 1;
- * // Set the current frame that is mapped to be relative to mouse position
- * let frameNumber = floor(map(mouseY, 0, height, 0, maxFrame, true));
- * gif.setFrame(frameNumber);
- * }
- *
- * @alt
- * A still image of a cartoon eye that looks around when you move your mouse
- * up and down over the canvas
+ * let total = gif.numFrames();
+ * let index = gif.getCurrentFrame();
+ * text(`${index} / ${total}`, 30, 90);
+ *
+ * describe('A cartoon eye looks around. The text "n / 125" is shown at the bottom of the canvas.');
+ * }
+ *
+ *
pause()
+ * img.pause() .
*
* @method play
+ *
* @example
- *
+ *
+ *
* let gif;
*
* function preload() {
@@ -1083,6 +1455,8 @@ p5.Image = class {
* function draw() {
* background(255);
* image(gif, 0, 0);
+ *
+ * describe('A drawing of a child with hair blowing in the wind. The animation freezes when clicked and resumes when released.');
* }
*
* function mousePressed() {
@@ -1092,11 +1466,8 @@ p5.Image = class {
* function mouseReleased() {
* gif.play();
* }
- *
- * @alt
- * An animated GIF of a drawing of small child with
- * hair blowing in the wind, when you click the image
- * freezes when you release it animates again
+ *
+ *
img.play() .
*
* @method pause
+ *
* @example
- *
+ *
+ *
* let gif;
*
* function preload() {
@@ -1119,6 +1493,8 @@ p5.Image = class {
* function draw() {
* background(255);
* image(gif, 0, 0);
+ *
+ * describe('A drawing of a child with hair blowing in the wind. The animation freezes when clicked and resumes when released.');
* }
*
* function mousePressed() {
@@ -1128,11 +1504,8 @@ p5.Image = class {
* function mouseReleased() {
* gif.play();
* }
- *
- * @alt
- * An animated GIF of a drawing of small child with
- * hair blowing in the wind, when you click the image
- * freezes when you release it animates again
+ *
+ *
- * let gifFast, gifSlow;
+ *
+ *
+ * let gifFast;
+ * let gifSlow;
*
* function preload() {
* gifFast = loadImage('assets/arnott-wallace-eye-loop-forever.gif');
@@ -1158,24 +1536,40 @@ p5.Image = class {
* }
*
* function setup() {
- * gifFast.resize(width / 2, height / 2);
- * gifSlow.resize(width / 2, height / 2);
- *
- * //Change the delay here
+ * gifFast.resize(50, 50);
+ * gifSlow.resize(50, 50);
* gifFast.delay(10);
* gifSlow.delay(100);
* }
*
* function draw() {
- * background(255);
* image(gifFast, 0, 0);
- * image(gifSlow, width / 2, 0);
+ * image(gifSlow, 50, 0);
+ *
+ * describe('Two animated eyes looking around. The eye on the left moves faster than the eye on the right.');
* }
- *
- * @alt
- * Two animated gifs of cartoon eyes looking around
- * The gif on the left animates quickly, on the right
- * the animation is much slower
+ *
+ *
+ *
+ * let gif;
+ *
+ * function preload() {
+ * gif = loadImage('assets/arnott-wallace-eye-loop-forever.gif');
+ * }
+ *
+ * function setup() {
+ * gif.delay(3000, 67);
+ * }
+ *
+ * function draw() {
+ * image(gif, 0, 0);
+ *
+ * describe('An animated eye looking around. It pauses for three seconds while it looks down.');
+ * }
+ *
+ *
*/
delay(d, index) {
if (this.gifProperties) {
diff --git a/src/image/pixels.js b/src/image/pixels.js
index 858796f492..f5d5b9161b 100644
--- a/src/image/pixels.js
+++ b/src/image/pixels.js
@@ -8,60 +8,88 @@
import p5 from '../core/main';
import Filters from './filters';
import '../color/p5.Color';
+import * as constants from '../core/constants';
/**
- * Uint8ClampedArray
- * containing the values for all the pixels in the display window.
- * These values are numbers. This array is the size (include an appropriate
- * factor for pixelDensity ) of the display window x4,
- * representing the R, G, B, A values in order for each pixel, moving from
- * left to right across each row, then down each column. Retina and other
- * high density displays will have more pixels[] (by a factor of
- * pixelDensity^2).
- * For example, if the image is 100×100 pixels, there will be 40,000. On a
- * retina display, there will be 160,000.
- *
- * The first four values (indices 0-3) in the array will be the R, G, B, A
- * values of the pixel at (0, 0). The second four values (indices 4-7) will
- * contain the R, G, B, A values of the pixel at (1, 0). More generally, to
- * set values for a pixel at (x, y):
- * ```javascript
+ * An array containing the color of each pixel on the canvas. Colors are
+ * stored as numbers representing red, green, blue, and alpha (RGBA) values.
+ * `pixels` is a one-dimensional array for performance reasons.
+ *
+ * Each pixel occupies four elements in the `pixels` array, one for each RGBA
+ * value. For example, the pixel at coordinates (0, 0) stores its RGBA values
+ * at `pixels[0]`, `pixels[1]`, `pixels[2]`, and `pixels[3]`, respectively.
+ * The next pixel at coordinates (1, 0) stores its RGBA values at `pixels[4]`,
+ * `pixels[5]`, `pixels[6]`, and `pixels[7]`. And so on. The `pixels` array
+ * for a 100×100 canvas has 100 × 100 × 4 = 40,000 elements.
+ *
+ * Some displays use several smaller pixels to set the color at a single
+ * point. The pixelDensity() function returns
+ * the pixel density of the canvas. High density displays often have a
+ * pixelDensity() of 2. On such a display, the
+ * `pixels` array for a 100×100 canvas has 200 × 200 × 4 =
+ * 160,000 elements.
+ *
+ * Accessing the RGBA values for a point on the canvas requires a little math
+ * as shown below. The loadPixels() function
+ * must be called before accessing the `pixels` array. The
+ * updatePixels() function must be called
+ * after any changes are made.
+ *
+ * @property {Number[]} pixels
+ *
+ * @example
+ *
+ *
+ * loadPixels();
+ * let x = 50;
+ * let y = 50;
* let d = pixelDensity();
- * for (let i = 0; i < d; i++) {
- * for (let j = 0; j < d; j++) {
- * // loop over
- * index = 4 * ((y * d + j) * width * d + (x * d + i));
- * pixels[index] = r;
- * pixels[index+1] = g;
- * pixels[index+2] = b;
- * pixels[index+3] = a;
+ * for (let i = 0; i < d; i += 1) {
+ * for (let j = 0; j < d; j += 1) {
+ * let index = 4 * ((y * d + j) * width * d + (x * d + i));
+ * // Red.
+ * pixels[index] = 0;
+ * // Green.
+ * pixels[index + 1] = 0;
+ * // Blue.
+ * pixels[index + 2] = 0;
+ * // Alpha.
+ * pixels[index + 3] = 255;
* }
* }
- * ```
- * While the above method is complex, it is flexible enough to work with
- * any pixelDensity. Note that set() will automatically take care of
- * setting all the appropriate values in pixels[] for a given (x, y) at
- * any pixelDensity, but the performance may not be as fast when lots of
- * modifications are made to the pixel array.
+ * updatePixels();
+ *
+ * describe('A black dot in the middle of a gray rectangle.');
+ *
+ *
loadPixels()
- * function. After the array data has been modified, the updatePixels()
- * function must be run to update the changes.
+ *
+ *
+ * loadPixels();
+ * let d = pixelDensity();
+ * let halfImage = 4 * (d * width) * (d * height / 2);
+ * for (let i = 0; i < halfImage; i += 4) {
+ * // Red.
+ * pixels[i] = 255;
+ * // Green.
+ * pixels[i + 1] = 0;
+ * // Blue.
+ * pixels[i + 2] = 0;
+ * // Alpha.
+ * pixels[i + 3] = 255;
+ * }
+ * updatePixels();
*
- * Note that this is not a standard javascript array. This means that
- * standard javascript functions such as slice() or
- * arrayCopy() do not
- * work.
+ * describe('A red rectangle drawn above a gray rectangle.');
+ *
+ *
*
* let pink = color(255, 102, 204);
* loadPixels();
* let d = pixelDensity();
- * let halfImage = 4 * (width * d) * (height / 2 * d);
+ * let halfImage = 4 * (d * width) * (d * height / 2);
* for (let i = 0; i < halfImage; i += 4) {
* pixels[i] = red(pink);
* pixels[i + 1] = green(pink);
@@ -69,35 +97,35 @@ import '../color/p5.Color';
* pixels[i + 3] = alpha(pink);
* }
* updatePixels();
+ *
+ * describe('A pink rectangle drawn above a gray rectangle.');
*
*
- *
- * @alt
- * top half of canvas pink, bottom grey
*/
p5.prototype.pixels = [];
/**
- * Copies a region of pixels from one image to another, using a specified
- * blend mode to do the operation.
+ * Copies a region of pixels from one image to another. The `blendMode`
+ * parameter blends the images' colors to create different effects.
*
* @method blend
- * @param {p5.Image} srcImage source image
- * @param {Integer} sx X coordinate of the source's upper left corner
- * @param {Integer} sy Y coordinate of the source's upper left corner
- * @param {Integer} sw source image width
- * @param {Integer} sh source image height
- * @param {Integer} dx X coordinate of the destination's upper left corner
- * @param {Integer} dy Y coordinate of the destination's upper left corner
- * @param {Integer} dw destination image width
- * @param {Integer} dh destination image height
+ * @param {p5.Image} srcImage source image.
+ * @param {Integer} sx x-coordinate of the source's upper-left corner.
+ * @param {Integer} sy y-coordinate of the source's upper-left corner.
+ * @param {Integer} sw source image width.
+ * @param {Integer} sh source image height.
+ * @param {Integer} dx x-coordinate of the destination's upper-left corner.
+ * @param {Integer} dy y-coordinate of the destination's upper-left corner.
+ * @param {Integer} dw destination image width.
+ * @param {Integer} dh destination image height.
* @param {Constant} blendMode the blend mode. either
* BLEND, DARKEST, LIGHTEST, DIFFERENCE,
* MULTIPLY, EXCLUSION, SCREEN, REPLACE, OVERLAY, HARD_LIGHT,
* SOFT_LIGHT, DODGE, BURN, ADD or NORMAL.
*
* @example
- *
+ *
+ *
* let img0;
* let img1;
*
@@ -110,9 +138,14 @@ p5.prototype.pixels = [];
* background(img0);
* image(img1, 0, 0);
* blend(img1, 0, 0, 33, 100, 67, 0, 33, 100, LIGHTEST);
+ *
+ * describe('A wall of bricks in front of a mountain landscape. The same wall of bricks appears faded on the right of the image.');
* }
- *
- *
+ *
+ *
+ *
+ *
+ *
* let img0;
* let img1;
*
@@ -125,9 +158,14 @@ p5.prototype.pixels = [];
* background(img0);
* image(img1, 0, 0);
* blend(img1, 0, 0, 33, 100, 67, 0, 33, 100, DARKEST);
+ *
+ * describe('A wall of bricks in front of a mountain landscape. The same wall of bricks appears transparent on the right of the image.');
* }
- *
- *
+ *
+ *
+ *
+ *
+ *
* let img0;
* let img1;
*
@@ -140,14 +178,11 @@ p5.prototype.pixels = [];
* background(img0);
* image(img1, 0, 0);
* blend(img1, 0, 0, 33, 100, 67, 0, 33, 100, ADD);
- * }
- *
- *
- * @alt
- * image of rocky mountains. Brick images on left and right. Right overexposed
- * image of rockies. Brickwall images on left and right. Right mortar transparent
- * image of rockies. Brickwall images on left and right. Right translucent
*
+ * describe('A wall of bricks in front of a mountain landscape. The same wall of bricks appears washed out on the right of the image.');
+ * }
+ *
+ *
p5.Image
+ * object. `copy()` will scale pixels from the source region if it isn't the
+ * same size as the destination region.
*
* @method copy
- * @param {p5.Image|p5.Element} srcImage source image
- * @param {Integer} sx X coordinate of the source's upper left corner
- * @param {Integer} sy Y coordinate of the source's upper left corner
- * @param {Integer} sw source image width
- * @param {Integer} sh source image height
- * @param {Integer} dx X coordinate of the destination's upper left corner
- * @param {Integer} dy Y coordinate of the destination's upper left corner
- * @param {Integer} dw destination image width
- * @param {Integer} dh destination image height
+ * @param {p5.Image|p5.Element} srcImage source image.
+ * @param {Integer} sx x-coordinate of the source's upper-left corner.
+ * @param {Integer} sy y-coordinate of the source's upper-left corner.
+ * @param {Integer} sw source image width.
+ * @param {Integer} sh source image height.
+ * @param {Integer} dx x-coordinate of the destination's upper-left corner.
+ * @param {Integer} dy y-coordinate of the destination's upper-left corner.
+ * @param {Integer} dw destination image width.
+ * @param {Integer} dh destination image height.
*
* @example
- *
+ *
+ *
* let img;
*
* function preload() {
@@ -200,17 +234,15 @@ p5.prototype.blend = function(...args) {
* function setup() {
* background(img);
* copy(img, 7, 22, 10, 10, 35, 25, 50, 50);
+ * // Show copied region.
* stroke(255);
* noFill();
- * // Rectangle shows area being copied
- * rect(7, 22, 10, 10);
- * }
- *
+ * square(7, 22, 10);
*
- * @alt
- * image of rocky mountains. Brick images on left and right. Right overexposed
- * image of rockies. Brickwall images on left and right. Right mortar transparent
- * image of rockies. Brickwall images on left and right. Right translucent
+ * describe('An image of a mountain landscape. A square region is outlined in white. A larger square contains a pixelated view of the outlined region.');
+ * }
+ *
+ *
- * the introduction to shaders tutorial.
+ * In `WEBGL` mode, `filter()` can also use custom shaders. See
+ * createFilterShader() for more
+ * information.
*
- * See also a selection of shader examples by Adam Ferriss
- * that contains many similar filter effects.
*
* @method filter
* @param {Constant} filterType either THRESHOLD, GRAY, OPAQUE, INVERT,
* POSTERIZE, BLUR, ERODE, DILATE or BLUR.
- * See Filters.js for docs on
- * each available filter
- * @param {Number} [filterParam] an optional parameter unique
- * to each filter, see above
+ * @param {Number} [filterParam] parameter unique to each filter.
+ * @param {Boolean} [useWebGL] flag to control whether to use fast
+ * WebGL filters (GPU) or original image
+ * filters (CPU); defaults to `true`.
*
* @example
*
*
* let img;
+ *
* function preload() {
* img = loadImage('assets/bricks.jpg');
* }
+ *
* function setup() {
* image(img, 0, 0);
- * filter(THRESHOLD);
+ * filter(INVERT);
+ *
+ * describe('A blue brick wall.');
* }
*
*
@@ -375,12 +409,16 @@ p5.prototype._copyHelper = (
*
*
* let img;
+ *
* function preload() {
* img = loadImage('assets/bricks.jpg');
* }
+ *
* function setup() {
* image(img, 0, 0);
* filter(GRAY);
+ *
+ * describe('A brick wall drawn in grayscale.');
* }
*
*
@@ -388,12 +426,16 @@ p5.prototype._copyHelper = (
*
*
* let img;
+ *
* function preload() {
* img = loadImage('assets/bricks.jpg');
* }
+ *
* function setup() {
* image(img, 0, 0);
- * filter(OPAQUE);
+ * filter(THRESHOLD);
+ *
+ * describe('A brick wall drawn in black and white.');
* }
*
*
@@ -401,12 +443,16 @@ p5.prototype._copyHelper = (
*
*
* let img;
+ *
* function preload() {
* img = loadImage('assets/bricks.jpg');
* }
+ *
* function setup() {
* image(img, 0, 0);
- * filter(INVERT);
+ * filter(OPAQUE);
+ *
+ * describe('A red brick wall.');
* }
*
*
@@ -414,12 +460,16 @@ p5.prototype._copyHelper = (
*
*
* let img;
+ *
* function preload() {
* img = loadImage('assets/bricks.jpg');
* }
+ *
* function setup() {
* image(img, 0, 0);
* filter(POSTERIZE, 3);
+ *
+ * describe('An image of a red brick wall drawn with limited color palette.');
* }
*
*
@@ -427,12 +477,16 @@ p5.prototype._copyHelper = (
*
*
* let img;
+ *
* function preload() {
* img = loadImage('assets/bricks.jpg');
* }
+ *
* function setup() {
* image(img, 0, 0);
- * filter(DILATE);
+ * filter(BLUR, 3);
+ *
+ * describe('A blurry image of a red brick wall.');
* }
*
*
@@ -440,12 +494,16 @@ p5.prototype._copyHelper = (
*
*
* let img;
+ *
* function preload() {
* img = loadImage('assets/bricks.jpg');
* }
+ *
* function setup() {
* image(img, 0, 0);
- * filter(BLUR, 3);
+ * filter(DILATE);
+ *
+ * describe('A red brick wall with bright lines between each brick.');
* }
*
*
@@ -453,134 +511,193 @@ p5.prototype._copyHelper = (
*
*
* let img;
+ *
* function preload() {
* img = loadImage('assets/bricks.jpg');
* }
+ *
* function setup() {
* image(img, 0, 0);
* filter(ERODE);
+ *
+ * describe('A red brick wall with faint lines between each brick.');
* }
*
*
*
*
*
- * createCanvas(100, 100, WEBGL);
- * let myShader = createShader(
- * `attribute vec3 aPosition;
- * attribute vec2 aTexCoord;
- *
- * varying vec2 vTexCoord;
- *
- * void main() {
- * vTexCoord = aTexCoord;
- * vec4 positionVec4 = vec4(aPosition, 1.0);
- * positionVec4.xy = positionVec4.xy * 2.0 - 1.0;
- * gl_Position = positionVec4;
- * }`,
- * `precision mediump float;
- * varying mediump vec2 vTexCoord;
- *
- * uniform sampler2D tex0;
- *
- * float luma(vec3 color) {
- * return dot(color, vec3(0.299, 0.587, 0.114));
- * }
+ * let img;
*
- * void main() {
- * vec2 uv = vTexCoord;
- * uv.y = 1.0 - uv.y;
- * vec4 sampledColor = texture2D(tex0, uv);
- * float gray = luma(sampledColor.rgb);
- * gl_FragColor = vec4(gray, gray, gray, 1);
- * }`
- * );
- * background('RED');
- * filter(myShader);
- * describe('a canvas becomes gray after being filtered by shader');
+ * function preload() {
+ * img = loadImage('assets/bricks.jpg');
+ * }
+ *
+ * function setup() {
+ * image(img, 0, 0);
+ * // Don't use WebGL.
+ * filter(BLUR, 3, false);
+ *
+ * describe('A blurry image of a red brick wall.');
+ * }
*
*
- *
- * @alt
- * black and white image of a brick wall.
- * greyscale image of a brickwall
- * image of a brickwall
- * jade colored image of a brickwall
- * red and pink image of a brickwall
- * image of a brickwall
- * blurry image of a brickwall
- * image of a brickwall
- * image of a brickwall with less detail
- * gray square
*/
/**
* @method filter
- * @param {p5.Shader} shaderFilter A shader that's been loaded, with the
- * frag shader using a `tex0` uniform
+ * @param {Constant} filterType
+ * @param {Boolean} [useWebGL]
+ */
+/**
+ * @method filter
+ * @param {p5.Shader} shaderFilter shader that's been loaded, with the
+ * frag shader using a `tex0` uniform.
*/
-p5.prototype.filter = function(operation, value) {
+p5.prototype.filter = function(...args) {
p5._validateParameters('filter', arguments);
- // TODO: use shader filters always, and provide an opt out
- if (this._renderer.isP3D) {
- p5.RendererGL.prototype.filter.call(this._renderer, arguments);
+ let { shader, operation, value, useWebGL } = parseFilterArgs(...args);
+
+ // when passed a shader, use it directly
+ if (shader) {
+ p5.RendererGL.prototype.filter.call(this._renderer, shader);
return;
}
- if (this.canvas !== undefined) {
- Filters.apply(this.canvas, Filters[operation], value);
- } else {
- Filters.apply(this.elt, Filters[operation], value);
+ // when opting out of webgl, use old pixels method
+ if (!useWebGL && !this._renderer.isP3D) {
+ if (this.canvas !== undefined) {
+ Filters.apply(this.canvas, Filters[operation], value);
+ } else {
+ Filters.apply(this.elt, Filters[operation], value);
+ }
+ return;
+ }
+
+ if(!useWebGL && this._renderer.isP3D) {
+ console.warn('filter() with useWebGL=false is not supported in WEBGL');
+ }
+
+ // when this is a webgl renderer, apply constant shader filter
+ if (this._renderer.isP3D) {
+ p5.RendererGL.prototype.filter.call(this._renderer, operation, value);
+ }
+
+ // when this is P2D renderer, create/use hidden webgl renderer
+ else {
+ // create hidden webgl renderer if it doesn't exist
+ if (!this.filterGraphicsLayer) {
+ // the real _pInst is buried when this is a secondary p5.Graphics
+ const pInst =
+ this._renderer._pInst instanceof p5.Graphics ?
+ this._renderer._pInst._pInst :
+ this._renderer._pInst;
+
+ // create secondary layer
+ this.filterGraphicsLayer =
+ new p5.Graphics(
+ this.width,
+ this.height,
+ constants.WEBGL,
+ pInst
+ );
+ }
+
+ // copy p2d canvas contents to secondary webgl renderer
+ // dest
+ this.filterGraphicsLayer.copy(
+ // src
+ this._renderer,
+ // src coods
+ 0, 0, this.width, this.height,
+ // dest coords
+ -this.width/2, -this.height/2, this.width, this.height
+ );
+
+ // filter it with shaders
+ this.filterGraphicsLayer.filter(operation, value);
+
+ // copy secondary webgl renderer back to original p2d canvas
+ this._renderer._pInst.image(this.filterGraphicsLayer, 0, 0);
+ this.filterGraphicsLayer.clear(); // prevent feedback effects on p2d canvas
}
};
+function parseFilterArgs(...args) {
+ // args could be:
+ // - operation, value, [useWebGL]
+ // - operation, [useWebGL]
+ // - shader
+
+ let result = {
+ shader: undefined,
+ operation: undefined,
+ value: undefined,
+ useWebGL: true
+ };
+
+ if (args[0] instanceof p5.Shader) {
+ result.shader = args[0];
+ return result;
+ }
+ else {
+ result.operation = args[0];
+ }
+
+ if (args.length > 1 && typeof args[1] === 'number') {
+ result.value = args[1];
+ }
+
+ if (args[args.length-1] === false) {
+ result.useWebGL = false;
+ }
+ return result;
+}
+
/**
- * Get a region of pixels, or a single pixel, from the canvas.
- *
- * Returns an array of [R,G,B,A] values for any pixel or grabs a section of
- * an image. If no parameters are specified, the entire image is returned.
- * Use the x and y parameters to get the value of one pixel. Get a section of
- * the display window by specifying additional w and h parameters. When
- * getting an image, the x and y parameters define the coordinates for the
- * upper-left corner of the image, regardless of the current imageMode() .
- *
- * Getting the color of a single pixel with get(x, y) is easy, but not as fast
- * as grabbing the data directly from pixels[] . The equivalent statement to
- * get(x, y) using pixels[] with pixel density d is
- * ```javascript
- * let x, y, d; // set these to the coordinates
- * let off = (y * width + x) * d * 4;
- * let components = [
- * pixels[off],
- * pixels[off + 1],
- * pixels[off + 2],
- * pixels[off + 3]
- * ];
- * print(components);
- * ```
- * See the reference for pixels[] for more information.
- *
- * If you want to extract an array of colors or a subimage from an p5.Image object,
- * take a look at p5.Image.get()
+ * Gets a pixel or a region of pixels from the canvas.
+ *
+ * `get()` is easy to use but it's not as fast as
+ * pixels . Use pixels
+ * to read many pixel values.
+ *
+ * The version of `get()` with no parameters returns the entire canvas.
+ *
+ * The version of `get()` with two parameters interprets them as
+ * coordinates. It returns an array with the `[R, G, B, A]` values of the
+ * pixel at the given point.
+ *
+ * The version of `get()` with four parameters interprets them as coordinates
+ * and dimensions. It returns a subsection of the canvas as a
+ * p5.Image object. The first two parameters are the
+ * coordinates for the upper-left corner of the subsection. The last two
+ * parameters are the width and height of the subsection.
+ *
+ * Use p5.Image.get() to work directly with
+ * p5.Image objects.
*
* @method get
- * @param {Number} x x-coordinate of the pixel
- * @param {Number} y y-coordinate of the pixel
- * @param {Number} w width of the section to be returned
- * @param {Number} h height of the section to be returned
- * @return {p5.Image} the rectangle p5.Image
+ * @param {Number} x x-coordinate of the pixel.
+ * @param {Number} y y-coordinate of the pixel.
+ * @param {Number} w width of the subsection to be returned.
+ * @param {Number} h height of the subsection to be returned.
+ * @return {p5.Image} subsection as a p5.Image object.
* @example
*
*
* let img;
+ *
* function preload() {
* img = loadImage('assets/rockies.jpg');
* }
+ *
* function setup() {
* image(img, 0, 0);
* let c = get();
* image(c, width / 2, 0);
+ *
+ * describe('Two identical mountain landscapes shown side-by-side.');
* }
*
*
@@ -588,32 +705,50 @@ p5.prototype.filter = function(operation, value) {
*
*
* let img;
+ *
* function preload() {
* img = loadImage('assets/rockies.jpg');
* }
+ *
* function setup() {
* image(img, 0, 0);
* let c = get(50, 90);
* fill(c);
* noStroke();
- * rect(25, 25, 50, 50);
+ * square(25, 25, 50);
+ *
+ * describe('A mountain landscape with an olive green square in its center.');
* }
*
*
*
- * @alt
- * 2 images of the rocky mountains, side-by-side
- * Image of the rocky mountains with 50×50 green rect in center of canvas
+ *
+ *
+ * let img;
+ *
+ * function preload() {
+ * img = loadImage('assets/rockies.jpg');
+ * }
+ *
+ * function setup() {
+ * image(img, 0, 0);
+ * let c = get(0, 0, width / 2, height / 2);
+ * image(c, width / 2, height / 2);
+ *
+ * describe('A mountain landscape drawn on top of another mountain landscape.');
+ * }
+ *
+ *
*/
/**
* @method get
- * @return {p5.Image} the whole p5.Image
+ * @return {p5.Image} whole canvas as a p5.Image .
*/
/**
* @method get
* @param {Number} x
* @param {Number} y
- * @return {Number[]} color of pixel at x,y in array format [R, G, B, A]
+ * @return {Number[]} color of the pixel at (x, y) in array format `[R, G, B, A]`.
*/
p5.prototype.get = function(x, y, w, h) {
p5._validateParameters('get', arguments);
@@ -621,16 +756,17 @@ p5.prototype.get = function(x, y, w, h) {
};
/**
- * Loads the pixel data for the display window into the pixels[] array. This
- * function must always be called before reading from or writing to pixels[] .
- * Note that only changes made with set() or direct manipulation of pixels[]
- * will occur.
+ * Loads the current value of each pixel on the canvas into the
+ * pixels array. This
+ * function must be called before reading from or writing to
+ * pixels .
*
* @method loadPixels
* @example
*
*
* let img;
+ *
* function preload() {
* img = loadImage('assets/rockies.jpg');
* }
@@ -638,18 +774,17 @@ p5.prototype.get = function(x, y, w, h) {
* function setup() {
* image(img, 0, 0, width, height);
* let d = pixelDensity();
- * let halfImage = 4 * (width * d) * (height * d / 2);
+ * let halfImage = 4 * (d * width) * (d * height / 2);
* loadPixels();
- * for (let i = 0; i < halfImage; i++) {
+ * for (let i = 0; i < halfImage; i += 1) {
* pixels[i + halfImage] = pixels[i];
* }
* updatePixels();
+ *
+ * describe('Two identical images of mountain landscapes, one on top of the other.');
* }
*
*
- *
- * @alt
- * two images of the rocky mountains. one on top, one on bottom of canvas.
*/
p5.prototype.loadPixels = function(...args) {
p5._validateParameters('loadPixels', args);
@@ -657,56 +792,71 @@ p5.prototype.loadPixels = function(...args) {
};
/**
- * Changes the color of any pixel, or writes an image directly to the
- * display window.
- * The x and y parameters specify the pixel to change and the c parameter
- * specifies the color value. This can be a p5.Color object, or [R, G, B, A]
- * pixel array. It can also be a single grayscale value.
- * When setting an image, the x and y parameters define the coordinates for
- * the upper-left corner of the image, regardless of the current imageMode() .
- *
- * After using set() , you must call updatePixels() for your changes to appear.
- * This should be called once all pixels have been set, and must be called before
- * calling .get() or drawing the image.
- *
- * Setting the color of a single pixel with set(x, y) is easy, but not as
- * fast as putting the data directly into pixels[] . Setting the pixels[]
- * values directly may be complicated when working with a retina display,
- * but will perform better when lots of pixels need to be set directly on
- * every loop. See the reference for pixels[] for more information.
+ * Sets the color of a pixel or draws an image to the canvas.
+ *
+ * `set()` is easy to use but it's not as fast as
+ * pixels . Use pixels
+ * to set many pixel values.
+ *
+ * `set()` interprets the first two parameters as x- and y-coordinates. It
+ * interprets the last parameter as a grayscale value, a `[R, G, B, A]` pixel
+ * array, a p5.Color object, or a
+ * p5.Image object. If an image is passed, the first
+ * two parameters set the coordinates for the image's upper-left corner,
+ * regardless of the current imageMode() .
+ *
+ * updatePixels() must be called after using
+ * `set()` for changes to appear.
*
* @method set
- * @param {Number} x x-coordinate of the pixel
- * @param {Number} y y-coordinate of the pixel
- * @param {Number|Number[]|Object} c insert a grayscale value | a pixel array |
- * a p5.Color object | a p5.Image to copy
+ * @param {Number} x x-coordinate of the pixel.
+ * @param {Number} y y-coordinate of the pixel.
+ * @param {Number|Number[]|Object} c grayscale value | pixel array |
+ * p5.Color object | p5.Image to copy.
* @example
*
*
+ * set(30, 20, 0);
+ * set(85, 20, 0);
+ * set(85, 75, 0);
+ * set(30, 75, 0);
+ * updatePixels();
+ *
+ * describe('Four black dots arranged in a square drawn on a gray background.');
+ *
+ *
+ *
+ *
+ *
* let black = color(0);
* set(30, 20, black);
* set(85, 20, black);
* set(85, 75, black);
* set(30, 75, black);
* updatePixels();
+ *
+ * describe('Four black dots arranged in a square drawn on a gray background.');
*
*
*
*
*
- * for (let i = 30; i < width - 15; i++) {
- * for (let j = 20; j < height - 25; j++) {
- * let c = color(204 - j, 153 - i, 0);
- * set(i, j, c);
+ * for (let x = 0; x < width; x += 1) {
+ * for (let y = 0; y < height; y += 1) {
+ * let c = map(x, 0, width, 0, 255);
+ * set(x, y, c);
* }
* }
* updatePixels();
+ *
+ * describe('A horiztonal color gradient from black to white.');
*
*
*
*
*
* let img;
+ *
* function preload() {
* img = loadImage('assets/rockies.jpg');
* }
@@ -714,39 +864,37 @@ p5.prototype.loadPixels = function(...args) {
* function setup() {
* set(0, 0, img);
* updatePixels();
- * line(0, 0, width, height);
- * line(0, height, width, 0);
+ *
+ * describe('An image of a mountain landscape.');
* }
*
*
- *
- * @alt
- * 4 black points in the shape of a square middle-right of canvas.
- * square with orangey-brown gradient lightening at bottom right.
- * image of the rocky mountains. with lines like an 'x' through the center.
*/
p5.prototype.set = function(x, y, imgOrCol) {
this._renderer.set(x, y, imgOrCol);
};
+
/**
- * Updates the display window with the data in the pixels[] array.
- * Use in conjunction with loadPixels() . If you're only reading pixels from
- * the array, there's no need to call updatePixels() — updating is only
- * necessary to apply changes. updatePixels() should be called anytime the
- * pixels array is manipulated or set() is called, and only changes made with
- * set() or direct changes to pixels[] will occur.
+ * Updates the canvas with the RGBA values in the
+ * pixels array.
+ *
+ * `updatePixels()` only needs to be called after changing values in the
+ * pixels array. Such changes can be made directly
+ * after calling loadPixels() or by calling
+ * set() .
*
* @method updatePixels
* @param {Number} [x] x-coordinate of the upper-left corner of region
- * to update
+ * to update.
* @param {Number} [y] y-coordinate of the upper-left corner of region
- * to update
- * @param {Number} [w] width of region to update
- * @param {Number} [h] height of region to update
+ * to update.
+ * @param {Number} [w] width of region to update.
+ * @param {Number} [h] height of region to update.
* @example
*
*
* let img;
+ *
* function preload() {
* img = loadImage('assets/rockies.jpg');
* }
@@ -754,17 +902,17 @@ p5.prototype.set = function(x, y, imgOrCol) {
* function setup() {
* image(img, 0, 0, width, height);
* let d = pixelDensity();
- * let halfImage = 4 * (width * d) * (height * d / 2);
+ * let halfImage = 4 * (d * width) * (d * height / 2);
* loadPixels();
- * for (let i = 0; i < halfImage; i++) {
+ * for (let i = 0; i < halfImage; i += 1) {
* pixels[i + halfImage] = pixels[i];
* }
* updatePixels();
+ *
+ * describe('Two identical images of mountain landscapes, one on top of the other.');
* }
*
*
- * @alt
- * two images of the rocky mountains. one on top, one on bottom of canvas.
*/
p5.prototype.updatePixels = function(x, y, w, h) {
p5._validateParameters('updatePixels', arguments);
diff --git a/src/math/p5.Vector.js b/src/math/p5.Vector.js
index 1fd6576be3..8becd7076a 100644
--- a/src/math/p5.Vector.js
+++ b/src/math/p5.Vector.js
@@ -32,42 +32,63 @@ const calculateRemainder3D = function(xComponent, yComponent, zComponent) {
};
/**
- * A class to describe a two or three-dimensional vector, specifically
- * a Euclidean (also known as geometric) vector. A vector is an entity
- * that has both magnitude and direction. The datatype, however, stores
- * the components of the vector (`x`, `y` for 2D; or `x`, `y`, `z` for 3D). The magnitude
- * and direction can be accessed via the methods p5.Vector.mag() and heading() .
- *
- * In many of the p5.js examples, you will see p5.Vector used to describe a
- * position, velocity, or acceleration. For example, if you consider a rectangle
- * moving across the screen, at any given instant it has a position (a vector
- * that points from the origin to its location), a velocity (the rate at which
- * the object's position changes per time unit, expressed as a vector), and
- * acceleration (the rate at which the object's velocity changes per time
- * unit, expressed as a vector).
- *
- * Since vectors represent groupings of values, we cannot simply use
- * traditional addition/multiplication/etc. Instead, we'll need to do some
- * "vector" math, which is made easy by the methods inside the p5.Vector class.
+ * A class to describe a two or three-dimensional vector. A vector is like an
+ * arrow pointing in space. Vectors have both magnitude (length) and
+ * direction.
+ *
+ * `p5.Vector` objects are often used to program motion because they simplify
+ * the math. For example, a moving ball has a position and a velocity.
+ * Position describes where the ball is in space. The ball's position vector
+ * extends from the origin to the ball's center. Velocity describes the ball's
+ * speed and the direction it's moving. If the ball is moving straight up, its
+ * velocity vector points straight up. Adding the ball's velocity vector to
+ * its position vector moves it, as in `pos.add(vel)`. Vector math relies on
+ * methods inside the `p5.Vector` class.
*
* @class p5.Vector
* @constructor
- * @param {Number} [x] x component of the vector
- * @param {Number} [y] y component of the vector
- * @param {Number} [z] z component of the vector
+ * @param {Number} [x] x component of the vector.
+ * @param {Number} [y] y component of the vector.
+ * @param {Number} [z] z component of the vector.
* @example
*
*
- * let v1 = createVector(40, 50);
- * let v2 = createVector(40, 50);
+ * let p1 = createVector(25, 25);
+ * let p2 = createVector(75, 75);
*
- * ellipse(v1.x, v1.y, 50, 50);
- * ellipse(v2.x, v2.y, 50, 50);
- * v1.add(v2);
- * ellipse(v1.x, v1.y, 50, 50);
+ * strokeWeight(5);
+ * point(p1);
+ * point(p2.x, p2.y);
*
- * describe(`2 white ellipses. One center-left the other
- * bottom right and off canvas`);
+ * describe('Two black dots on a gray square, one at the top left and the other at the bottom right.');
+ *
+ *
+ *
+ *
+ *
+ * let pos;
+ * let vel;
+ *
+ * function setup() {
+ * createCanvas(100, 100);
+ * pos = createVector(width / 2, height);
+ * vel = createVector(0, -1);
+ * }
+ *
+ * function draw() {
+ * background(200);
+ *
+ * pos.add(vel);
+ *
+ * if (pos.y < 0) {
+ * pos.y = height;
+ * }
+ *
+ * strokeWeight(5);
+ * point(pos);
+ *
+ * describe('A black dot moves from bottom to top on a gray square. The dot reappears at the bottom when it reaches the top.');
+ * }
*
*
*/
@@ -107,47 +128,17 @@ p5.Vector = class {
}
/**
- * Returns a string representation of a vector `v` by calling `String(v)`
- * or `v.toString()`. This method is useful for logging vectors in the
- * console.
+ * Returns a string representation of a vector. This method is useful for
+ * printing vectors to the console while debugging.
* @method toString
- * @return {String}
+ * @return {String} string representation of the vector.
* @example
*
*
* function setup() {
* let v = createVector(20, 30);
- * print(String(v)); // prints "p5.Vector Object : [20, 30, 0]"
- * }
- *
- *
- *
- *
- *
- * function draw() {
- * background(240);
- *
- * let v0 = createVector(0, 0);
- * let v1 = createVector(mouseX, mouseY);
- * drawArrow(v0, v1, 'black');
- *
- * noStroke();
- * text(v1.toString(), 10, 25, 90, 75);
- * }
- *
- * // draw an arrow for a vector at a given base position
- * function drawArrow(base, vec, myColor) {
- * push();
- * stroke(myColor);
- * strokeWeight(3);
- * fill(myColor);
- * translate(base.x, base.y);
- * line(0, 0, vec.x, vec.y);
- * rotate(vec.heading());
- * let arrowSize = 7;
- * translate(vec.mag() - arrowSize, 0);
- * triangle(0, arrowSize / 2, 0, -arrowSize / 2, arrowSize, 0);
- * pop();
+ * // Prints 'p5.Vector Object : [20, 30, 0]'.
+ * print(v.toString());
* }
*
*
@@ -157,67 +148,45 @@ p5.Vector = class {
}
/**
- * Sets the `x`, `y`, and `z` components of the vector using two or three separate
- * variables, the data from a p5.Vector , or the values from a float array.
+ * Sets the `x`, `y`, and `z` components of the vector using separate numbers,
+ * a p5.Vector object, or an array of numbers.
+ * Calling `set()` with no arguments sets the vector's components to 0.
+ *
* @method set
- * @param {Number} [x] The x component of the vector
- * @param {Number} [y] The y component of the vector
- * @param {Number} [z] The z component of the vector
+ * @param {Number} [x] x component of the vector.
+ * @param {Number} [y] y component of the vector.
+ * @param {Number} [z] z component of the vector.
* @chainable
* @example
- *
- *
- * function setup() {
- * let v = createVector(1, 2, 3);
- * v.set(4, 5, 6); // Sets vector to [4, 5, 6]
- *
- * let v1 = createVector(0, 0, 0);
- * let arr = [1, 2, 3];
- * v1.set(arr); // Sets vector to [1, 2, 3]
- * }
- *
- *
- *
*
*
- * let v0, v1;
- * function setup() {
- * createCanvas(100, 100);
+ * strokeWeight(5);
*
- * v0 = createVector(0, 0);
- * v1 = createVector(50, 50);
- * }
+ * // Top left.
+ * let pos = createVector(25, 25);
+ * point(pos);
*
- * function draw() {
- * background(240);
+ * // Top right.
+ * pos.set(75, 25);
+ * point(pos);
*
- * drawArrow(v0, v1, 'black');
- * v1.set(v1.x + random(-1, 1), v1.y + random(-1, 1));
+ * // Bottom right.
+ * let p2 = createVector(75, 75);
+ * pos.set(p2);
+ * point(pos);
*
- * noStroke();
- * text('x: ' + round(v1.x) + ' y: ' + round(v1.y), 20, 90);
- * }
+ * // Bottom left.
+ * let arr = [25, 75];
+ * pos.set(arr);
+ * point(pos);
*
- * // draw an arrow for a vector at a given base position
- * function drawArrow(base, vec, myColor) {
- * push();
- * stroke(myColor);
- * strokeWeight(3);
- * fill(myColor);
- * translate(base.x, base.y);
- * line(0, 0, vec.x, vec.y);
- * rotate(vec.heading());
- * let arrowSize = 7;
- * translate(vec.mag() - arrowSize, 0);
- * triangle(0, arrowSize / 2, 0, -arrowSize / 2, arrowSize, 0);
- * pop();
- * }
+ * describe('Four black dots arranged in a square on a gray background.');
*
*
*/
/**
* @method set
- * @param {p5.Vector|Number[]} value The vector to set
+ * @param {p5.Vector|Number[]} value vector to set.
* @chainable
*/
set (x, y, z) {
@@ -240,17 +209,20 @@ p5.Vector = class {
}
/**
- * Gets a copy of the vector, returns a p5.Vector object.
+ * Returns a copy of the p5.Vector object.
*
* @method copy
- * @return {p5.Vector} A copy of the p5.Vector object
+ * @return {p5.Vector} copy of the p5.Vector object.
* @example
- *
+ *
*
- * let v1 = createVector(1, 2, 3);
- * let v2 = v1.copy();
- * print(v1.x === v2.x && v1.y === v2.y && v1.z === v2.z);
- * // Prints "true"
+ * let pos = createVector(50, 50);
+ * let pc = pos.copy();
+ *
+ * strokeWeight(5);
+ * point(pc);
+ *
+ * describe('A black point drawn in the middle of a gray square.');
*
*
*/
@@ -269,66 +241,84 @@ p5.Vector = class {
}
/**
- * Adds `x`, `y`, and `z` components to a vector, adds one vector to another, or
- * adds two independent vectors together. The version of the method that adds
- * two vectors together is a static method and returns a
p5.Vector , the others
- * act directly on the vector. Additionally, you may provide arguments to this method as an array.
- * See the examples for more context.
+ * Adds to a vector's `x`, `y`, and `z` components using separate numbers,
+ * another
p5.Vector object, or an array of numbers.
+ * Calling `add()` with no arguments has no effect.
+ *
+ * The static version of `add()`, as in `p5.Vector.add(v2, v1)`, returns a new
+ *
p5.Vector object and doesn't change the
+ * originals.
*
* @method add
- * @param {Number} x The x component of the vector to be added
- * @param {Number} [y] The y component of the vector to be added
- * @param {Number} [z] The z component of the vector to be added
+ * @param {Number} x x component of the vector to be added.
+ * @param {Number} [y] y component of the vector to be added.
+ * @param {Number} [z] z component of the vector to be added.
* @chainable
* @example
- *
+ *
*
- * let v = createVector(1, 2, 3);
- * v.add(4, 5, 6);
- * // v's components are set to [5, 7, 9]
- *
- *
+ * strokeWeight(5);
*
- *
- *
- * let v = createVector(1, 2, 3);
- * // Provide arguments as an array
- * let arr = [4, 5, 6];
- * v.add(arr);
- * // v's components are set to [5, 7, 9]
+ * // Top left.
+ * let pos = createVector(25, 25);
+ * point(pos);
+ *
+ * // Top right.
+ * pos.add(50, 0);
+ * point(pos);
+ *
+ * // Bottom right.
+ * let p2 = createVector(0, 50);
+ * pos.add(p2);
+ * point(pos);
+ *
+ * // Bottom left.
+ * let arr = [-50, 0];
+ * pos.add(arr);
+ * point(pos);
+ *
+ * describe('Four black dots arranged in a square on a gray background.');
*
*
*
- *
+ *
*
- * // Static method
- * let v1 = createVector(1, 2, 3);
- * let v2 = createVector(2, 3, 4);
+ * // Top left.
+ * let p1 = createVector(25, 25);
+ *
+ * // Center.
+ * let p2 = createVector(50, 50);
+ *
+ * // Bottom right.
+ * let p3 = p5.Vector.add(p1, p2);
+ *
+ * strokeWeight(5);
+ * point(p1);
+ * point(p2);
+ * point(p3);
*
- * let v3 = p5.Vector.add(v1, v2);
- * // v3 has components [3, 5, 7]
- * print(v3);
+ * describe('Three black dots in a diagonal line from top left to bottom right.');
*
*
*
*
*
- * // red vector + blue vector = purple vector
* function draw() {
- * background(240);
+ * background(200);
*
- * let v0 = createVector(0, 0);
- * let v1 = createVector(mouseX, mouseY);
- * drawArrow(v0, v1, 'red');
+ * let origin = createVector(0, 0);
+ * let v1 = createVector(50, 50);
+ * drawArrow(origin, v1, 'red');
*
* let v2 = createVector(-30, 20);
* drawArrow(v1, v2, 'blue');
*
* let v3 = p5.Vector.add(v1, v2);
- * drawArrow(v0, v3, 'purple');
+ * drawArrow(origin, v3, 'purple');
+ *
+ * describe('Three arrows drawn on a gray square. A red arrow extends from the top left corner to the center. A blue arrow extends from the tip of the red arrow. A purple arrow extends from the origin to the tip of the blue arrow.');
* }
*
- * // draw an arrow for a vector at a given base position
* function drawArrow(base, vec, myColor) {
* push();
* stroke(myColor);
@@ -370,37 +360,65 @@ p5.Vector = class {
}
/**
- * Gives the remainder of a vector when it is divided by another vector.
- * See examples for more context.
+ * Performs modulo (remainder) division with a vector's `x`, `y`, and `z`
+ * components using separate numbers, another
+ * p5.Vector object, or an array of numbers.
+ *
+ * The static version of `rem()` as in `p5.Vector.rem(v2, v1)`, returns a new
+ * p5.Vector object and doesn't change the
+ * originals.
*
* @method rem
- * @param {Number} x The x component of divisor vector
- * @param {Number} y The y component of divisor vector
- * @param {Number} z The z component of divisor vector
+ * @param {Number} x x component of divisor vector.
+ * @param {Number} y y component of divisor vector.
+ * @param {Number} z z component of divisor vector.
* @chainable
* @example
*
*
* let v = createVector(3, 4, 5);
* v.rem(2, 3, 4);
- * // v's components are set to [1, 1, 1]
+ * // Prints 'p5.Vector Object : [1, 1, 1]'.
+ * print(v.toString());
*
*
- *
+ *
+ *
*
- * // Static method
* let v1 = createVector(3, 4, 5);
* let v2 = createVector(2, 3, 4);
+ * v1.rem(v2);
+ *
+ * // Prints 'p5.Vector Object : [1, 1, 1]'.
+ * print(v1.toString());
+ *
+ *
*
+ *
+ *
+ * let v = createVector(3, 4, 5);
+ * let arr = [2, 3, 4];
+ * v.rem(arr);
+ *
+ * // Prints 'p5.Vector Object : [1, 1, 1]'.
+ * print(v.toString());
+ *
+ *
+ *
+ *
+ *
+ * let v1 = createVector(3, 4, 5);
+ * let v2 = createVector(2, 3, 4);
* let v3 = p5.Vector.rem(v1, v2);
- * // v3 has components [1, 1, 1]
- * print(v3);
+ *
+ * // Prints 'p5.Vector Object : [1, 1, 1]'.
+ * print(v3.toString());
*
*
*/
/**
* @method rem
- * @param {p5.Vector | Number[]} value The divisor vector
+ * @param {p5.Vector | Number[]} value divisor vector.
* @chainable
*/
rem (x, y, z) {
@@ -459,66 +477,84 @@ p5.Vector = class {
}
/**
- * Subtracts `x`, `y`, and `z` components from a vector, subtracts one vector from
- * another, or subtracts two independent vectors. The version of the method
- * that subtracts two vectors is a static method and returns a
p5.Vector , the
- * others act directly on the vector. Additionally, you may provide arguments to this method as an array.
- * See the examples for more context.
+ * Subtracts from a vector's `x`, `y`, and `z` components using separate
+ * numbers, another
p5.Vector object, or an array of
+ * numbers. Calling `sub()` with no arguments has no effect.
+ *
+ * The static version of `sub()`, as in `p5.Vector.sub(v2, v1)`, returns a new
+ *
p5.Vector object and doesn't change the
+ * originals.
*
* @method sub
- * @param {Number} x The x component of the vector to subtract
- * @param {Number} [y] The y component of the vector to subtract
- * @param {Number} [z] The z component of the vector to subtract
+ * @param {Number} x x component of the vector to subtract.
+ * @param {Number} [y] y component of the vector to subtract.
+ * @param {Number} [z] z component of the vector to subtract.
* @chainable
* @example
- *
+ *
*
- * let v = createVector(4, 5, 6);
- * v.sub(1, 1, 1);
- * // v's components are set to [3, 4, 5]
- *
- *
+ * strokeWeight(5);
*
- *
- *
- * let v = createVector(4, 5, 6);
- * // Provide arguments as an array
- * let arr = [1, 1, 1];
- * v.sub(arr);
- * // v's components are set to [3, 4, 5]
+ * // Bottom right.
+ * let pos = createVector(75, 75);
+ * point(pos);
+ *
+ * // Top right.
+ * pos.sub(0, 50);
+ * point(pos);
+ *
+ * // Top left.
+ * let p2 = createVector(50, 0);
+ * pos.sub(p2);
+ * point(pos);
+ *
+ * // Bottom left.
+ * let arr = [0, -50];
+ * pos.sub(arr);
+ * point(pos);
+ *
+ * describe('Four black dots arranged in a square on a gray background.');
*
*
*
- *
+ *
*
- * // Static method
- * let v1 = createVector(2, 3, 4);
- * let v2 = createVector(1, 2, 3);
+ * // Bottom right.
+ * let p1 = createVector(75, 75);
+ *
+ * // Center.
+ * let p2 = createVector(50, 50);
*
- * let v3 = p5.Vector.sub(v1, v2);
- * // v3 has components [1, 1, 1]
- * print(v3);
+ * // Top left.
+ * let p3 = p5.Vector.sub(p1, p2);
+ *
+ * strokeWeight(5);
+ * point(p1);
+ * point(p2);
+ * point(p3);
+ *
+ * describe('Three black dots in a diagonal line from top left to bottom right.');
*
*
*
*
*
- * // red vector - blue vector = purple vector
* function draw() {
- * background(240);
+ * background(200);
*
- * let v0 = createVector(0, 0);
- * let v1 = createVector(70, 50);
- * drawArrow(v0, v1, 'red');
+ * let origin = createVector(0, 0);
+ * let v1 = createVector(50, 50);
+ * drawArrow(origin, v1, 'red');
*
- * let v2 = createVector(mouseX, mouseY);
- * drawArrow(v0, v2, 'blue');
+ * let v2 = createVector(20, 70);
+ * drawArrow(origin, v2, 'blue');
+ *
+ * let v3 = p5.Vector.sub(v2, v1);
+ * drawArrow(v1, v3, 'purple');
*
- * let v3 = p5.Vector.sub(v1, v2);
- * drawArrow(v2, v3, 'purple');
+ * describe('Three arrows drawn on a gray square. A red and a blue arrow extend from the top left. A purple arrow extends from the tip of the red arrow to the tip of the blue arrow.');
* }
*
- * // draw an arrow for a vector at a given base position
* function drawArrow(base, vec, myColor) {
* push();
* stroke(myColor);
@@ -560,81 +596,107 @@ p5.Vector = class {
}
/**
- * Multiplies the vector by a scalar, multiplies the `x`, `y`, and `z` components from a vector, or multiplies
- * the `x`, `y`, and `z` components of two independent vectors. When multiplying a vector by a scalar, the `x`, `y`,
- * and `z` components of the vector are all multiplied by the scalar. When multiplying a vector by a vector,
- * the `x`, `y`, `z` components of both vectors are multiplied by each other
- * (for example, with two vectors `a` and `b`: `a.x * b.x`, `a.y * b.y`, `a.z * b.z`). The static version of this method
- * creates a new p5.Vector while the non-static version acts on the vector
- * directly. Additionally, you may provide arguments to this function as an array.
- * See the examples for more context.
+ * Multiplies a vector's `x`, `y`, and `z` components by the same number,
+ * separate numbers, the components of another
+ * p5.Vector object, or an array of numbers. Calling
+ * `mult()` with no arguments has no effect.
+ *
+ * The static version of `mult()`, as in `p5.Vector.mult(v, 2)`, returns a new
+ * p5.Vector object and doesn't change the
+ * originals.
*
* @method mult
* @param {Number} n The number to multiply with the vector
* @chainable
* @example
- *
+ *
*
- * let v = createVector(1, 2, 3);
- * v.mult(2);
- * // v's components are set to [2, 4, 6]
+ * strokeWeight(5);
+ *
+ * let p = createVector(25, 25);
+ * point(p);
+ *
+ * p.mult(2);
+ * point(p);
+ *
+ * describe('Two black dots drawn on a gray square. One dot is in the top left corner and the other is in the center.');
*
*
*
- *
+ *
*
- * let v0 = createVector(1, 2, 3);
- * let v1 = createVector(2, 3, 4);
- * v0.mult(v1); // v0's components are set to [2, 6, 12]
+ * strokeWeight(5);
+ *
+ * let p = createVector(25, 25);
+ * point(p);
+ *
+ * p.mult(2, 3);
+ * point(p);
+ *
+ * describe('Two black dots drawn on a gray square. One dot is in the top left corner and the other is in the bottom center.');
*
*
*
- *
+ *
*
- * let v0 = createVector(1, 2, 3);
- * // Provide arguments as an array
- * let arr = [2, 3, 4];
- * v0.mult(arr); // v0's components are set to [2, 6, 12]
+ * strokeWeight(5);
+ *
+ * let p = createVector(25, 25);
+ * point(p);
+ *
+ * let arr = [2, 3];
+ * p.mult(arr);
+ * point(p);
+ *
+ * describe('Two black dots drawn on a gray square. One dot is in the top left corner and the other is in the bottom center.');
*
*
*
- *
+ *
*
- * let v0 = createVector(1, 2, 3);
- * let v1 = createVector(2, 3, 4);
- * const result = p5.Vector.mult(v0, v1);
- * print(result); // result's components are set to [2, 6, 12]
+ * strokeWeight(5);
+ *
+ * let p = createVector(25, 25);
+ * point(p);
+ *
+ * let p2 = createVector(2, 3);
+ * p.mult(p2);
+ * point(p);
+ *
+ * describe('Two black dots drawn on a gray square. One dot is in the top left corner and the other is in the bottom center.');
*
*
*
- *
+ *
*
- * // Static method
- * let v1 = createVector(1, 2, 3);
- * let v2 = p5.Vector.mult(v1, 2);
- * // v2 has components [2, 4, 6]
- * print(v2);
+ * strokeWeight(5);
+ *
+ * let p = createVector(25, 25);
+ * point(p);
+ *
+ * let p2 = createVector(2, 3);
+ * let p3 = p5.Vector.mult(p, p2);
+ * point(p3);
+ *
+ * describe('Two black dots drawn on a gray square. One dot is in the top left corner and the other is in the bottom center.');
*
*
*
*
*
* function draw() {
- * background(240);
+ * background(200);
*
- * let v0 = createVector(50, 50);
- * let v1 = createVector(25, -25);
- * drawArrow(v0, v1, 'red');
+ * let origin = createVector(0, 0);
+ * let v1 = createVector(25, 25);
+ * drawArrow(origin, v1, 'red');
*
- * let num = map(mouseX, 0, width, -2, 2, true);
- * let v2 = p5.Vector.mult(v1, num);
- * drawArrow(v0, v2, 'blue');
+ * let v2 = p5.Vector.mult(v1, 2);
+ * drawArrow(origin, v2, 'blue');
*
- * noStroke();
- * text('multiplied by ' + num.toFixed(2), 5, 90);
+ * describe('Two arrows extending from the top left corner. The blue arrow is twice the length of the red arrow.');
* }
*
- * // draw an arrow for a vector at a given base position
* function drawArrow(base, vec, myColor) {
* push();
* stroke(myColor);
@@ -654,21 +716,21 @@ p5.Vector = class {
/**
* @method mult
- * @param {Number} x The number to multiply with the x component of the vector
- * @param {Number} y The number to multiply with the y component of the vector
- * @param {Number} [z] The number to multiply with the z component of the vector
+ * @param {Number} x number to multiply with the x component of the vector.
+ * @param {Number} y number to multiply with the y component of the vector.
+ * @param {Number} [z] number to multiply with the z component of the vector.
* @chainable
*/
/**
* @method mult
- * @param {Number[]} arr The array to multiply with the components of the vector
+ * @param {Number[]} arr array to multiply with the components of the vector.
* @chainable
*/
/**
* @method mult
- * @param {p5.Vector} v The vector to multiply with the components of the original vector
+ * @param {p5.Vector} v vector to multiply with the components of the original vector.
* @chainable
*/
@@ -752,84 +814,107 @@ p5.Vector = class {
}
/**
- * Divides the vector by a scalar, divides a vector by the `x`, `y`, and `z` arguments, or divides the `x`, `y`, and
- * `z` components of two vectors against each other. When dividing a vector by a scalar, the `x`, `y`,
- * and `z` components of the vector are all divided by the scalar. When dividing a vector by a vector,
- * the `x`, `y`, `z` components of the source vector are treated as the dividend, and the `x`, `y`, `z` components
- * of the argument is treated as the divisor. (For example, with two vectors
- * `a` and `b`: `a.x / b.x`, `a.y / b.y`, `a.z / b.z`.) If any component of the second vector is 0, a division by 0
- * error will be logged, unless both two vectors have 0 in their `z` components, in which case only the `x` and `y`
- * components will be divided.
- * The static version of this method creates a
- * new p5.Vector while the non-static version acts on the vector directly.
- * Additionally, you may provide arguments to this method as an array.
- * See the examples for more context.
+ * Divides a vector's `x`, `y`, and `z` components by the same number,
+ * separate numbers, the components of another
+ * p5.Vector object, or an array of numbers. Calling
+ * `div()` with no arguments has no effect.
+ *
+ * The static version of `div()`, as in `p5.Vector.div(v, 2)`, returns a new
+ * p5.Vector object and doesn't change the
+ * originals.
*
* @method div
* @param {number} n The number to divide the vector by
* @chainable
* @example
- *
+ *
*
- * let v = createVector(6, 4, 2);
- * v.div(2); //v's components are set to [3, 2, 1]
+ * strokeWeight(5);
+ *
+ * let p = createVector(50, 50);
+ * point(p);
+ *
+ * p.div(2);
+ * point(p);
+ *
+ * describe('Two black dots drawn on a gray square. One dot is in the top left corner and the other is in the center.');
*
*
*
- *
+ *
*
- * let v0 = createVector(9, 4, 2);
- * let v1 = createVector(3, 2, 4);
- * v0.div(v1); // v0's components are set to [3, 2, 0.5]
+ * strokeWeight(5);
+ *
+ * let p = createVector(50, 75);
+ * point(p);
+ *
+ * p.div(2, 3);
+ * point(p);
+ *
+ * describe('Two black dots drawn on a gray square. One dot is in the top left corner and the other is in the bottom center.');
*
*
*
- *
+ *
*
- * let v0 = createVector(9, 4, 2);
- * // Provide arguments as an array
- * let arr = [3, 2, 4];
- * v0.div(arr); // v0's components are set to [3, 2, 0.5]
+ * strokeWeight(5);
+ *
+ * let p = createVector(50, 75);
+ * point(p);
+ *
+ * let arr = [2, 3];
+ * p.div(arr);
+ * point(p);
+ *
+ * describe('Two black dots drawn on a gray square. One dot is in the top left corner and the other is in the bottom center.');
*
*
*
- *
+ *
*
- * let v0 = createVector(9, 4, 2);
- * let v1 = createVector(3, 2, 4);
- * let result = p5.Vector.div(v0, v1);
- * print(result); // result's components are set to [3, 2, 0.5]
+ * strokeWeight(5);
+ *
+ * let p = createVector(50, 75);
+ * point(p);
+ *
+ * let p2 = createVector(2, 3);
+ * p.div(p2);
+ * point(p);
+ *
+ * describe('Two black dots drawn on a gray square. One dot is in the top left corner and the other is in the bottom center.');
*
*
*
- *
+ *
*
- * // Static method
- * let v1 = createVector(6, 4, 2);
- * let v2 = p5.Vector.div(v1, 2);
- * // v2 has components [3, 2, 1]
- * print(v2);
+ * strokeWeight(5);
+ *
+ * let p = createVector(50, 75);
+ * point(p);
+ *
+ * let p2 = createVector(2, 3);
+ * let p3 = p5.Vector.div(p, p2);
+ * point(p3);
+ *
+ * describe('Two black dots drawn on a gray square. One dot is in the top left corner and the other is in the bottom center.');
*
*
*
*
*
* function draw() {
- * background(240);
+ * background(200);
*
- * let v0 = createVector(0, 100);
- * let v1 = createVector(50, -50);
- * drawArrow(v0, v1, 'red');
+ * let origin = createVector(0, 0);
+ * let v1 = createVector(50, 50);
+ * drawArrow(origin, v1, 'red');
*
- * let num = map(mouseX, 0, width, 10, 0.5, true);
- * let v2 = p5.Vector.div(v1, num);
- * drawArrow(v0, v2, 'blue');
+ * let v2 = p5.Vector.div(v1, 2);
+ * drawArrow(origin, v2, 'blue');
*
- * noStroke();
- * text('divided by ' + num.toFixed(2), 10, 90);
+ * describe('Two arrows extending from the top left corner. The blue arrow is half the length of the red arrow.');
* }
*
- * // draw an arrow for a vector at a given base position
* function drawArrow(base, vec, myColor) {
* push();
* stroke(myColor);
@@ -849,21 +934,21 @@ p5.Vector = class {
/**
* @method div
- * @param {Number} x The number to divide with the x component of the vector
- * @param {Number} y The number to divide with the y component of the vector
- * @param {Number} [z] The number to divide with the z component of the vector
+ * @param {Number} x number to divide with the x component of the vector.
+ * @param {Number} y number to divide with the y component of the vector.
+ * @param {Number} [z] number to divide with the z component of the vector.
* @chainable
*/
/**
* @method div
- * @param {Number[]} arr The array to divide the components of the vector by
+ * @param {Number[]} arr array to divide the components of the vector by.
* @chainable
*/
/**
* @method div
- * @param {p5.Vector} v The vector to divide the components of the original vector by
+ * @param {p5.Vector} v vector to divide the components of the original vector by.
* @chainable
*/
div(x, y, z) {
@@ -963,46 +1048,20 @@ p5.Vector = class {
return this;
}
/**
- * Calculates the magnitude (length) of the vector and returns the result as
- * a float. (This is simply the equation `sqrt(x*x + y*y + z*z)`.)
+ * Returns the magnitude (length) of the vector.
*
* @method mag
- * @return {Number} The magnitude of the vector
+ * @return {Number} magnitude of the vector.
* @example
*
*
- * function draw() {
- * background(240);
+ * let p = createVector(30, 40);
+ * line(0, 0, p.x, p.y);
*
- * let v0 = createVector(0, 0);
- * let v1 = createVector(mouseX, mouseY);
- * drawArrow(v0, v1, 'black');
+ * let m = p.mag();
+ * text(m, p.x, p.y);
*
- * noStroke();
- * text('vector length: ' + v1.mag().toFixed(2), 10, 70, 90, 30);
- * }
- *
- * // draw an arrow for a vector at a given base position
- * function drawArrow(base, vec, myColor) {
- * push();
- * stroke(myColor);
- * strokeWeight(3);
- * fill(myColor);
- * translate(base.x, base.y);
- * line(0, 0, vec.x, vec.y);
- * rotate(vec.heading());
- * let arrowSize = 7;
- * translate(vec.mag() - arrowSize, 0);
- * triangle(0, arrowSize / 2, 0, -arrowSize / 2, arrowSize, 0);
- * pop();
- * }
- *
- *
- *
- *
- * let v = createVector(20.0, 30.0, 40.0);
- * let m = v.mag();
- * print(m); // Prints "53.85164807134504"
+ * describe('A diagonal black line extends from the top left corner of a gray square. The number 50 is written at the end of the line.');
*
*
*/
@@ -1011,49 +1070,20 @@ p5.Vector = class {
}
/**
- * Calculates the squared magnitude of the vector and returns the result
- * as a float. (This is simply the equation `x*x + y*y + z*z`.)
- * Faster if the real length is not required in the
- * case of comparing vectors, etc.
+ * Returns the magnitude (length) of the vector squared.
*
* @method magSq
- * @return {number} The squared magnitude of the vector
+ * @return {number} squared magnitude of the vector.
* @example
- *
- *
- * // Static method
- * let v1 = createVector(6, 4, 2);
- * print(v1.magSq()); // Prints "56"
- *
- *
- *
*
*
- * function draw() {
- * background(240);
- *
- * let v0 = createVector(0, 0);
- * let v1 = createVector(mouseX, mouseY);
- * drawArrow(v0, v1, 'black');
+ * let p = createVector(30, 40);
+ * line(0, 0, p.x, p.y);
*
- * noStroke();
- * text('vector length squared: ' + v1.magSq().toFixed(2), 10, 45, 90, 55);
- * }
+ * let m = p.magSq();
+ * text(m, p.x, p.y);
*
- * // draw an arrow for a vector at a given base position
- * function drawArrow(base, vec, myColor) {
- * push();
- * stroke(myColor);
- * strokeWeight(3);
- * fill(myColor);
- * translate(base.x, base.y);
- * line(0, 0, vec.x, vec.y);
- * rotate(vec.heading());
- * let arrowSize = 7;
- * translate(vec.mag() - arrowSize, 0);
- * triangle(0, arrowSize / 2, 0, -arrowSize / 2, arrowSize, 0);
- * pop();
- * }
+ * describe('A diagonal black line extends from the top left corner of a gray square. The number 2500 is written at the end of the line.');
*
*
*/
@@ -1065,38 +1095,85 @@ p5.Vector = class {
}
/**
- * Calculates the dot product of two vectors. The version of the method
- * that computes the dot product of two independent vectors is a static
- * method. See the examples for more context.
+ * Returns the dot product of two vectors. The dot product is a number that
+ * describes the overlap between two vectors. Visually, the dot product can be
+ * thought of as the "shadow" one vector casts on another. The dot product's
+ * magnitude is largest when two vectors point in the same or opposite
+ * directions. Its magnitude is 0 when two vectors form a right angle.
+ *
+ * The version of `dot()` with one parameter interprets it as another
+ * p5.Vector object.
+ *
+ * The version of `dot()` with multiple parameters interprets them as the
+ * `x`, `y`, and `z` components of another vector.
+ *
+ * The static version of `dot()`, as in `p5.Vector.dot(v1, v2)`, is the same
+ * as calling `v1.dot(v2)`.
*
* @method dot
- * @param {Number} x The x component of the vector
- * @param {Number} [y] The y component of the vector
- * @param {Number} [z] The z component of the vector
- * @return {Number} The dot product
+ * @param {Number} x x component of the vector.
+ * @param {Number} [y] y component of the vector.
+ * @param {Number} [z] z component of the vector.
+ * @return {Number} dot product.
*
* @example
*
*
- * let v1 = createVector(1, 2, 3);
- * let v2 = createVector(2, 3, 4);
- *
- * print(v1.dot(v2)); // Prints "20"
+ * let v1 = createVector(3, 4);
+ * let v2 = createVector(3, 0);
+ * let dp = v1.dot(v2);
+ * // Prints "9" to the console.
+ * print(dp);
*
*
*
*
*
- * //Static method
- * let v1 = createVector(1, 2, 3);
- * let v2 = createVector(3, 2, 1);
- * print(p5.Vector.dot(v1, v2)); // Prints "10"
+ * let v1 = createVector(1, 0);
+ * let v2 = createVector(0, 1);
+ * let dp = p5.Vector.dot(v1, v2);
+ * // Prints "0" to the console.
+ * print(dp);
+ *
+ *
+ *
+ *
+ *
+ * function draw() {
+ * background(200);
+ *
+ * let v0 = createVector(width / 2, height / 2);
+ * let v1 = createVector(30, 0);
+ * drawArrow(v0, v1, 'black');
+ *
+ * let v2 = createVector(mouseX - width / 2, mouseY - height / 2);
+ * drawArrow(v0, v2, 'red');
+ *
+ * let dp = v2.dot(v1);
+ * text(`v2 • v1 = ${dp}`, 15, 20);
+ *
+ * describe('Two arrows drawn on a gray square. A black arrow points to the right and a red arrow follows the mouse. The text "v1 • v2 = something" changes as the mouse moves.');
+ * }
+ *
+ * function drawArrow(base, vec, myColor) {
+ * push();
+ * stroke(myColor);
+ * strokeWeight(3);
+ * fill(myColor);
+ * translate(base.x, base.y);
+ * line(0, 0, vec.x, vec.y);
+ * rotate(vec.heading());
+ * let arrowSize = 7;
+ * translate(vec.mag() - arrowSize, 0);
+ * triangle(0, arrowSize / 2, 0, -arrowSize / 2, arrowSize, 0);
+ * pop();
+ * }
*
*
*/
/**
* @method dot
- * @param {p5.Vector} value value component of the vector or a p5.Vector
+ * @param {p5.Vector} v p5.Vector to be dotted.
* @return {Number}
*/
dot(x, y, z) {
@@ -1107,33 +1184,35 @@ p5.Vector = class {
}
/**
- * Calculates and returns a vector composed of the cross product between
- * two vectors. Both the static and non-static methods return a new p5.Vector .
- * See the examples for more context.
+ * Returns the cross product of two vectors. The cross product is a vector
+ * that points straight out of the plane created by two vectors. The cross
+ * product's magnitude is the area of the parallelogram formed by the original
+ * two vectors.
+ *
+ * The static version of `cross()`, as in `p5.Vector.cross(v1, v2)`, is the same
+ * as calling `v1.cross(v2)`.
*
* @method cross
- * @param {p5.Vector} v p5.Vector to be crossed
- * @return {p5.Vector} p5.Vector composed of cross product
+ * @param {p5.Vector} v p5.Vector to be crossed.
+ * @return {p5.Vector} cross product as a p5.Vector .
* @example
*
*
- * let v1 = createVector(1, 2, 3);
- * let v2 = createVector(1, 2, 3);
- *
- * let v = v1.cross(v2); // v's components are [0, 0, 0]
- * print(v);
+ * let v1 = createVector(1, 0);
+ * let v2 = createVector(3, 4);
+ * let cp = v1.cross(v2);
+ * // Prints "p5.Vector Object : [0, 0, 4]" to the console.
+ * print(cp.toString());
*
*
*
*
*
- * // Static method
- * let v1 = createVector(1, 0, 0);
- * let v2 = createVector(0, 1, 0);
- *
- * let crossProduct = p5.Vector.cross(v1, v2);
- * // crossProduct has components [0, 0, 1]
- * print(crossProduct);
+ * let v1 = createVector(1, 0);
+ * let v2 = createVector(3, 4);
+ * let cp = p5.Vector.cross(v1, v2);
+ * // Prints "p5.Vector Object : [0, 0, 4]" to the console.
+ * print(cp.toString());
*
*
*/
@@ -1149,54 +1228,60 @@ p5.Vector = class {
}
/**
- * Calculates the Euclidean distance between two points (considering a
- * point as a vector object).
- * If you are looking to calculate distance between 2 points see dist()
+ * Returns the distance between two points represented by vectors. A point's
+ * coordinates can be thought of as a vector's components.
+ *
+ * The static version of `dist()`, as in `p5.Vector.dist(v1, v2)`, is the same
+ * as calling `v1.dist(v2)`.
+ *
+ * Use dist() to calculate the distance between points
+ * using coordinates as in `dist(x1, y1, x2, y2)`.
*
* @method dist
- * @param {p5.Vector} v The x, y, and z coordinates of a p5.Vector
- * @return {Number} The distance
+ * @param {p5.Vector} v x, y, and z coordinates of a p5.Vector .
+ * @return {Number} distance.
* @example
*
*
- * let v1 = createVector(1, 0, 0);
- * let v2 = createVector(0, 1, 0);
- *
- * let distance = v1.dist(v2); // distance is 1.4142...
- * print(distance);
+ * let v1 = createVector(1, 0);
+ * let v2 = createVector(0, 1);
+ * let d = v1.dist(v2);
+ * // Prints "1.414..." to the console.
+ * print(d);
*
*
*
*
*
- * // Static method
- * let v1 = createVector(1, 0, 0);
- * let v2 = createVector(0, 1, 0);
- *
- * let distance = p5.Vector.dist(v1, v2);
- * // distance is 1.4142...
- * print(distance);
+ * let v1 = createVector(1, 0);
+ * let v2 = createVector(0, 1);
+ * let d = p5.Vector.dist(v1, v2);
+ * // Prints "1.414..." to the console.
+ * print(d);
*
*
*
*
*
* function draw() {
- * background(240);
+ * background(200);
*
- * let v0 = createVector(0, 0);
+ * let origin = createVector(0, 0);
+ * let v1 = createVector(50, 50);
+ * drawArrow(origin, v1, 'red');
*
- * let v1 = createVector(70, 50);
- * drawArrow(v0, v1, 'red');
+ * let v2 = createVector(20, 70);
+ * drawArrow(origin, v2, 'blue');
*
- * let v2 = createVector(mouseX, mouseY);
- * drawArrow(v0, v2, 'blue');
+ * let v3 = p5.Vector.sub(v2, v1);
+ * drawArrow(v1, v3, 'purple');
*
- * noStroke();
- * text('distance between vectors: ' + v2.dist(v1).toFixed(2), 5, 50, 95, 50);
+ * let m = floor(v3.mag());
+ * text(m, 50, 75);
+ *
+ * describe('Three arrows drawn on a gray square. A red and a blue arrow extend from the top left. A purple arrow extends from the tip of the red arrow to the tip of the blue arrow. The number 36 is written in black near the purple arrow.');
* }
*
- * // draw an arrow for a vector at a given base position
* function drawArrow(base, vec, myColor) {
* push();
* stroke(myColor);
@@ -1221,31 +1306,33 @@ p5.Vector = class {
}
/**
- * Normalize the vector to length 1 (make it a unit vector).
+ * Scales the components of a p5.Vector object so
+ * that its magnitude is 1.
+ *
+ * The static version of `normalize()`, as in `p5.Vector.normalize(v)`,
+ * returns a new p5.Vector object and doesn't change
+ * the original.
*
* @method normalize
- * @return {p5.Vector} The normalized p5.Vector
+ * @return {p5.Vector} normalized p5.Vector .
* @example
*
*
* let v = createVector(10, 20, 2);
- * // v has components [10.0, 20.0, 2.0]
* v.normalize();
- * // v's components are set to
- * // [0.4454354, 0.8908708, 0.089087084]
+ * // Prints "p5.Vector Object : [0.445..., 0.890..., 0.089...]" to the console.
+ * print(v.toString());
*
*
*
*
*
- * // Static method
- * let v_initial = createVector(10, 20, 2);
- * // v_initial has components [10.0, 20.0, 2.0]
- * let v_normalized = p5.Vector.normalize(v_initial);
- * print(v_normalized);
- * // returns a new vector with components set to
- * // [0.4454354, 0.8908708, 0.089087084]
- * // v_initial remains unchanged
+ * let v0 = createVector(10, 20, 2);
+ * let v1 = p5.Vector.normalize(v0);
+ * // Prints "p5.Vector Object : [10, 20, 2]" to the console.
+ * print(v0.toString());
+ * // Prints "p5.Vector Object : [0.445..., 0.890..., 0.089...]" to the console.
+ * print(v1.toString());
*
*
*
@@ -1257,15 +1344,17 @@ p5.Vector = class {
* let v0 = createVector(50, 50);
* let v1 = createVector(mouseX - 50, mouseY - 50);
*
+ * let r = 25;
* drawArrow(v0, v1, 'red');
* v1.normalize();
- * drawArrow(v0, v1.mult(35), 'blue');
+ * drawArrow(v0, v1.mult(r), 'blue');
*
* noFill();
- * ellipse(50, 50, 35 * 2);
+ * circle(50, 50, r * 2);
+ *
+ * describe("A red and blue arrow extend from the center of a circle. Both arrows follow the mouse, but the blue arrow's length is fixed to the circle's radius.");
* }
*
- * // draw an arrow for a vector at a given base position
* function drawArrow(base, vec, myColor) {
* push();
* stroke(myColor);
@@ -1291,22 +1380,34 @@ p5.Vector = class {
}
/**
- * Limit the magnitude of this vector to the value used for the `max`
- * parameter.
+ * Limits a vector's magnitude to a maximum value.
+ *
+ * The static version of `limit()`, as in `p5.Vector.limit(v, 5)`, returns a
+ * new p5.Vector object and doesn't change the
+ * original.
*
* @method limit
- * @param {Number} max The maximum magnitude for the vector
+ * @param {Number} max maximum magnitude for the vector.
* @chainable
* @example
*
*
* let v = createVector(10, 20, 2);
- * // v has components [10.0, 20.0, 2.0]
* v.limit(5);
- * // v's components are set to
- * // [2.2271771, 4.4543543, 0.4454354]
+ * // Prints "p5.Vector Object : [2.227..., 4.454..., 0.445...]" to the console.
+ * print(v.toString());
+ *
+ *
+ *
+ *
+ *
+ * let v0 = createVector(10, 20, 2);
+ * let v1 = p5.Vector.limit(v0, 5);
+ * // Prints "p5.Vector Object : [2.227..., 4.454..., 0.445...]" to the console.
+ * print(v1.toString());
*
*
+ *
*
*
* function draw() {
@@ -1315,14 +1416,16 @@ p5.Vector = class {
* let v0 = createVector(50, 50);
* let v1 = createVector(mouseX - 50, mouseY - 50);
*
+ * let r = 25;
* drawArrow(v0, v1, 'red');
- * drawArrow(v0, v1.limit(35), 'blue');
+ * drawArrow(v0, v1.limit(r), 'blue');
*
* noFill();
- * ellipse(50, 50, 35 * 2);
+ * circle(50, 50, r * 2);
+ *
+ * describe("A red and blue arrow extend from the center of a circle. Both arrows follow the mouse, but the blue arrow never crosses the circle's edge.");
* }
*
- * // draw an arrow for a vector at a given base position
* function drawArrow(base, vec, myColor) {
* push();
* stroke(myColor);
@@ -1349,19 +1452,36 @@ p5.Vector = class {
}
/**
- * Set the magnitude of this vector to the value used for the `len`
- * parameter.
+ * Sets a vector's magnitude to a given value.
+ *
+ * The static version of `setMag()`, as in `p5.Vector.setMag(v, 10)`, returns
+ * a new p5.Vector object and doesn't change the
+ * original.
*
* @method setMag
- * @param {number} len The new length for this vector
+ * @param {number} len new length for this vector.
* @chainable
* @example
*
*
- * let v = createVector(3, 4, 0);
- * // v has components [3.0, 4.0, 0.0]
- * v.setMag(10);
- * // v's components are set to [6.0, 8.0, 0.0]
+ * let v = createVector(3, 4, 0);
+ * // Prints "5" to the console.
+ * print(v.mag());
+ *
+ * v.setMag(10);
+ * // Prints "p5.Vector Object : [6, 8, 0]" to the console.
+ * print(v.toString());
+ *
+ *
+ *
+ *
+ *
+ * let v0 = createVector(3, 4, 0);
+ * let v1 = p5.Vector.setMag(v0, 10);
+ * // Prints "5" to the console.
+ * print(v0.mag());
+ * // Prints "p5.Vector Object : [6, 8, 0]" to the console.
+ * print(v1.toString());
*
*
*
@@ -1370,20 +1490,17 @@ p5.Vector = class {
* function draw() {
* background(240);
*
- * let v0 = createVector(0, 0);
- * let v1 = createVector(50, 50);
+ * let origin = createVector(0, 0);
+ * let v = createVector(50, 50);
*
- * drawArrow(v0, v1, 'red');
+ * drawArrow(origin, v, 'red');
*
- * let length = map(mouseX, 0, width, 0, 141, true);
- * v1.setMag(length);
- * drawArrow(v0, v1, 'blue');
+ * v.setMag(30);
+ * drawArrow(origin, v, 'blue');
*
- * noStroke();
- * text('magnitude set to: ' + length.toFixed(2), 10, 70, 90, 30);
+ * describe('Two arrows extend from the top left corner of a square toward its center. The red arrow reaches the center and the blue arrow only extends part of the way.');
* }
*
- * // draw an arrow for a vector at a given base position
* function drawArrow(base, vec, myColor) {
* push();
* stroke(myColor);
@@ -1405,55 +1522,63 @@ p5.Vector = class {
}
/**
- * Calculate the angle of rotation for this vector (only 2D vectors).
- * p5.Vectors created using createVector()
- * will take the current angleMode() into
- * consideration, and give the angle in radians or degrees accordingly.
+ * Calculates the angle a 2D vector makes with the positive x-axis. Angles
+ * increase in the clockwise direction.
+ *
+ * If the vector was created with
+ * createVector() , `heading()` returns angles
+ * in the units of the current angleMode() .
+ *
+ * The static version of `heading()`, as in `p5.Vector.heading(v)`, works the
+ * same way.
*
* @method heading
- * @return {Number} The angle of rotation
+ * @return {Number} angle of rotation.
* @example
*
*
- * function setup() {
- * let v1 = createVector(30, 50);
- * print(v1.heading()); // 1.0303768265243125
+ * let v = createVector(1, 1);
+ * // Prints "0.785..." to the console.
+ * print(v.heading());
*
- * v1 = createVector(40, 50);
- * print(v1.heading()); // 0.8960553845713439
+ * angleMode(DEGREES);
+ * // Prints "45" to the console.
+ * print(v.heading());
+ *
+ *
*
- * v1 = createVector(30, 70);
- * print(v1.heading()); // 1.1659045405098132
- * }
+ *
+ *
+ * let v = createVector(1, 1);
+ * // Prints "0.785..." to the console.
+ * print(p5.Vector.heading(v));
+ *
+ * angleMode(DEGREES);
+ * // Prints "45" to the console.
+ * print(p5.Vector.heading(v));
*
*
*
*
*
* function draw() {
- * background(240);
+ * background(200);
*
- * let v0 = createVector(50, 50);
- * let v1 = createVector(mouseX - 50, mouseY - 50);
+ * let origin = createVector(0, 0);
+ * let v = createVector(50, 50);
*
- * drawArrow(v0, v1, 'black');
+ * drawArrow(origin, v, 'black');
*
- * let myHeading = v1.heading();
- * noStroke();
- * text(
- * 'vector heading: ' +
- * myHeading.toFixed(2) +
- * ' radians or ' +
- * degrees(myHeading).toFixed(2) +
- * ' degrees',
- * 10,
- * 50,
- * 90,
- * 50
- * );
+ * angleMode(RADIANS);
+ * let h = round(v.heading(), 2);
+ * text(`Radians: ${h}`, 20, 70);
+ * angleMode(DEGREES);
+ * h = v.heading();
+ * text(`Degrees: ${h}`, 20, 85);
+ *
+ * describe('A black arrow extends from the top left of a square to its center. The text "Radians: 0.79" and "Degrees: 45" is written near the tip of the arrow.');
* }
*
- * // draw an arrow for a vector at a given base position
* function drawArrow(base, vec, myColor) {
* push();
* stroke(myColor);
@@ -1477,19 +1602,72 @@ p5.Vector = class {
}
/**
- * Rotate the vector to a specific angle (only 2D vectors); magnitude remains the
- * same.
+ * Rotates a 2D vector to a specific angle without changing its magnitude.
+ * By convention, the positive x-axis has an angle of 0. Angles increase in
+ * the clockwise direction.
+ *
+ * If the vector was created with
+ * createVector() , `setHeading()` uses
+ * the units of the current angleMode() .
*
* @method setHeading
- * @param {number} angle The angle of rotation
+ * @param {number} angle angle of rotation.
* @chainable
* @example
*
*
- * let v = createVector(10.0, 20.0);
- * // result of v.heading() is 1.1071487177940904
- * v.setHeading(Math.PI);
- * // result of v.heading() is now 3.141592653589793
+ * let v = createVector(0, 1);
+ * // Prints "1.570..." to the console.
+ * print(v.heading());
+ *
+ * v.setHeading(PI);
+ * // Prints "3.141..." to the console.
+ * print(v.heading());
+ *
+ *
+ *
+ *
+ *
+ * angleMode(DEGREES);
+ * let v = createVector(0, 1);
+ * // Prints "90" to the console.
+ * print(v.heading());
+ *
+ * v.setHeading(180);
+ * // Prints "180" to the console.
+ * print(v.heading());
+ *
+ *
+ *
+ *
+ *
+ * function draw() {
+ * background(200);
+ *
+ * let v0 = createVector(50, 50);
+ * let v1 = createVector(30, 0);
+ *
+ * drawArrow(v0, v1, 'red');
+ *
+ * v1.setHeading(HALF_PI);
+ * drawArrow(v0, v1, 'blue');
+ *
+ * describe('Two arrows extend from the center of a gray square. The red arrow points to the right and the blue arrow points down.');
+ * }
+ *
+ * function drawArrow(base, vec, myColor) {
+ * push();
+ * stroke(myColor);
+ * strokeWeight(3);
+ * fill(myColor);
+ * translate(base.x, base.y);
+ * line(0, 0, vec.x, vec.y);
+ * rotate(vec.heading());
+ * let arrowSize = 7;
+ * translate(vec.mag() - arrowSize, 0);
+ * triangle(0, arrowSize / 2, 0, -arrowSize / 2, arrowSize, 0);
+ * pop();
+ * }
*
*
*/
@@ -1503,49 +1681,88 @@ p5.Vector = class {
}
/**
- * Rotate the vector by an angle (only 2D vectors); magnitude remains the
- * same.
+ * Rotates a 2D vector by an angle without changing its magnitude.
+ * By convention, the positive x-axis has an angle of 0. Angles increase in
+ * the clockwise direction.
+ *
+ * If the vector was created with
+ * createVector() , `rotate()` uses
+ * the units of the current angleMode() .
+ *
+ * The static version of `rotate()`, as in `p5.Vector.rotate(v, PI)`,
+ * returns a new p5.Vector object and doesn't change
+ * the original.
*
* @method rotate
- * @param {number} angle The angle of rotation
+ * @param {number} angle angle of rotation.
* @chainable
* @example
*
*
- * let v = createVector(10.0, 20.0);
- * // v has components [10.0, 20.0, 0.0]
+ * let v = createVector(1, 0);
+ * // Prints "p5.Vector Object : [1, 0, 0]" to the console.
+ * print(v.toString());
* v.rotate(HALF_PI);
- * // v's components are set to [-20.0, 9.999999, 0.0]
+ * // Prints "p5.Vector Object : [0, 1, 0]" to the console.
+ * print(v.toString());
+ *
+ *
+ *
+ *
+ *
+ * angleMode(DEGREES);
+ * let v = createVector(1, 0);
+ * // Prints "p5.Vector Object : [1, 0, 0]" to the console.
+ * print(v.toString());
+ * v.rotate(90);
+ * // Prints "p5.Vector Object : [0, 1, 0]" to the console.
+ * print(v.toString());
+ *
+ *
+ *
+ *
+ *
+ * let v0 = createVector(1, 0);
+ * let v1 = p5.Vector.rotate(v0, HALF_PI);
+ * // Prints "p5.Vector Object : [1, 0, 0]" to the console.
+ * print(v0.toString());
+ * // Prints "p5.Vector Object : [0, 1, 0]" to the console.
+ * print(v1.toString());
*
*
*
*
*
- * // static function implementation
- * let v = createVector(10.0, 20.0);
- * // v has components [10.0, 20.0, 0.0]
- * let rotated_v = p5.Vector.rotate(v, HALF_PI);
- * console.log(rotated_v);
- * // rotated_v's components are set to [-20.0, 9.999999, 0.0]
- * console.log(v);
- * // v's components remains the same (i.e, [10.0, 20.0, 0.0])
+ * angleMode(DEGREES);
+ * let v0 = createVector(1, 0);
+ * let v1 = p5.Vector.rotate(v0, 90);
+ * // Prints "p5.Vector Object : [1, 0, 0]" to the console.
+ * print(v0.toString());
+ * // Prints "p5.Vector Object : [0, 1, 0]" to the console.
+ * print(v1.toString());
*
*
*
*
*
- * let angle = 0;
+ * let v0;
+ * let v1;
+ *
+ * function setup() {
+ * v0 = createVector(50, 50);
+ * v1 = createVector(30, 0);
+ * }
+ *
* function draw() {
* background(240);
*
- * let v0 = createVector(50, 50);
- * let v1 = createVector(50, 0);
+ * v1.rotate(0.01);
*
- * drawArrow(v0, v1.rotate(angle), 'black');
- * angle += 0.01;
+ * drawArrow(v0, v1, 'black');
+ *
+ * describe('A black arrow extends from the center of a gray square. The arrow rotates counterclockwise.');
* }
*
- * // draw an arrow for a vector at a given base position
* function drawArrow(base, vec, myColor) {
* push();
* stroke(myColor);
@@ -1572,53 +1789,86 @@ p5.Vector = class {
}
/**
- * Calculates and returns the angle between two vectors. This method will take
- * the current angleMode into consideration, and
- * give the angle in radians or degrees accordingly.
+ * Returns the angle between two vectors. The angles returned are signed,
+ * which means that `v1.angleBetween(v2) === -v2.angleBetween(v1)`.
+ *
+ * If the vector was created with
+ * createVector() , `angleBetween()` returns
+ * angles in the units of the current
+ * angleMode() .
*
* @method angleBetween
- * @param {p5.Vector} value The x, y, and z components of a p5.Vector
- * @return {Number} The angle between
+ * @param {p5.Vector} value x, y, and z components of a p5.Vector .
+ * @return {Number} angle between the vectors.
* @example
*
*
- * let v1 = createVector(1, 0, 0);
- * let v2 = createVector(0, 1, 0);
+ * let v0 = createVector(1, 0);
+ * let v1 = createVector(0, 1);
+ * // Prints "1.570..." to the console.
+ * print(v0.angleBetween(v1));
+ * // Prints "-1.570..." to the console.
+ * print(v1.angleBetween(v0));
+ *
+ *
+ *
+ *
+ *
+ * angleMode(DEGREES);
+ * let v0 = createVector(1, 0);
+ * let v1 = createVector(0, 1);
+ * // Prints "90" to the console.
+ * print(v0.angleBetween(v1));
+ * // Prints "-90" to the console.
+ * print(v1.angleBetween(v0));
+ *
+ *
+ *
+ *
+ *
+ * let v0 = createVector(1, 0);
+ * let v1 = createVector(0, 1);
+ * // Prints "1.570..." to the console.
+ * print(p5.Vector.angleBetween(v0, v1));
+ * // Prints "-1.570..." to the console.
+ * print(p5.Vector.angleBetween(v1, v0));
+ *
+ *
*
- * let angle = v1.angleBetween(v2);
- * // angle is PI/2
- * print(angle);
+ *
+ *
+ * angleMode(DEGREES);
+ * let v0 = createVector(1, 0);
+ * let v1 = createVector(0, 1);
+ * // Prints "90" to the console.
+ * print(p5.Vector.angleBetween(v0, v1));
+ * // Prints "-90" to the console.
+ * print(p5.Vector.angleBetween(v1, v0));
*
*
*
*
*
* function draw() {
- * background(240);
+ * background(200);
+ *
* let v0 = createVector(50, 50);
+ * let v1 = createVector(30, 0);
+ * let v2 = createVector(0, 30);
*
- * let v1 = createVector(50, 0);
* drawArrow(v0, v1, 'red');
- *
- * let v2 = createVector(mouseX - 50, mouseY - 50);
* drawArrow(v0, v2, 'blue');
*
- * let angleBetween = v1.angleBetween(v2);
- * noStroke();
- * text(
- * 'angle between: ' +
- * angleBetween.toFixed(2) +
- * ' radians or ' +
- * degrees(angleBetween).toFixed(2) +
- * ' degrees',
- * 10,
- * 50,
- * 90,
- * 50
- * );
+ * angleMode(RADIANS);
+ * let angle = round(v1.angleBetween(v2), 2);
+ * text(`Radians: ${angle}`, 20, 20);
+ * angleMode(DEGREES);
+ * angle = round(v1.angleBetween(v2), 2);
+ * text(`Degrees: ${angle}`, 20, 35);
+ *
+ * describe('Two arrows extend from the center of a gray square. A red arrow points to the right and a blue arrow points down. The text "Radians: 1.57" and "Degrees: 90" is written above the arrows.');
* }
*
- * // draw an arrow for a vector at a given base position
* function drawArrow(base, vec, myColor) {
* push();
* stroke(myColor);
@@ -1635,7 +1885,6 @@ p5.Vector = class {
*
*
*/
-
angleBetween(v) {
const magSqMult = this.magSq() * v.magSq();
// Returns NaN if either vector is the zero vector.
@@ -1654,62 +1903,71 @@ p5.Vector = class {
}
/**
- * Linear interpolate the vector to another vector.
+ * Calculates new `x`, `y`, and `z` components that are proportionally the
+ * same distance between two vectors. The `amt` parameter is the amount to
+ * interpolate between the old vector and the new vector. 0.0 keeps all
+ * components equal to the old vector's, 0.5 is halfway between, and 1.0 sets
+ * all components equal to the new vector's.
+ *
+ * The static version of `lerp()`, as in `p5.Vector.lerp(v0, v1, 0.5)`,
+ * returns a new p5.Vector object and doesn't change
+ * the original.
*
* @method lerp
- * @param {Number} x The x component
- * @param {Number} y The y component
- * @param {Number} z The z component
- * @param {Number} amt The amount of interpolation; some value between 0.0
- * (old vector) and 1.0 (new vector). 0.9 is very near
- * the new vector. 0.5 is halfway in between.
+ * @param {Number} x x component.
+ * @param {Number} y y component.
+ * @param {Number} z z component.
+ * @param {Number} amt amount of interpolation between 0.0 (old vector)
+ * and 1.0 (new vector). 0.5 is halfway between.
* @chainable
*
* @example
*
*
- * let v = createVector(1, 1, 0);
- *
- * v.lerp(3, 3, 0, 0.5); // v now has components [2,2,0]
+ * let v0 = createVector(1, 1, 1);
+ * let v1 = createVector(3, 3, 3);
+ * v0.lerp(v1, 0.5);
+ * // Prints "p5.Vector Object : [2, 2, 2]" to the console.
+ * print(v0.toString());
*
*
*
*
*
- * let v1 = createVector(0, 0, 0);
- * let v2 = createVector(100, 100, 0);
+ * let v = createVector(1, 1, 1);
+ * v.lerp(3, 3, 3, 0.5);
+ * // Prints "p5.Vector Object : [2, 2, 2]" to the console.
+ * print(v.toString());
+ *
+ *
*
- * let v3 = p5.Vector.lerp(v1, v2, 0.5);
- * // v3 has components [50,50,0]
- * print(v3);
+ *
+ *
+ * let v0 = createVector(1, 1, 1);
+ * let v1 = createVector(3, 3, 3);
+ * let v2 = p5.Vector.lerp(v0, v1, 0.5);
+ * // Prints "p5.Vector Object : [2, 2, 2]" to the console.
+ * print(v2.toString());
*
*
*
*
*
- * let step = 0.01;
- * let amount = 0;
- *
* function draw() {
- * background(240);
- * let v0 = createVector(0, 0);
+ * background(200);
*
- * let v1 = createVector(mouseX, mouseY);
- * drawArrow(v0, v1, 'red');
+ * let v0 = createVector(50, 50);
+ * let v1 = createVector(30, 0);
+ * let v2 = createVector(0, 30);
+ * let v3 = p5.Vector.lerp(v1, v2, 0.5);
*
- * let v2 = createVector(90, 90);
+ * drawArrow(v0, v1, 'red');
* drawArrow(v0, v2, 'blue');
- *
- * if (amount > 1 || amount < 0) {
- * step *= -1;
- * }
- * amount += step;
- * let v3 = p5.Vector.lerp(v1, v2, amount);
- *
* drawArrow(v0, v3, 'purple');
+ *
+ * describe('Three arrows extend from the center of a gray square. A red arrow points to the right, a blue arrow points down, and a purple arrow points to the bottom right.');
* }
*
- * // draw an arrow for a vector at a given base position
* function drawArrow(base, vec, myColor) {
* push();
* stroke(myColor);
@@ -1728,7 +1986,7 @@ p5.Vector = class {
*/
/**
* @method lerp
- * @param {p5.Vector} v The p5.Vector to lerp to
+ * @param {p5.Vector} v p5.Vector to lerp toward.
* @param {Number} amt
* @chainable
*/
@@ -1743,83 +2001,101 @@ p5.Vector = class {
}
/**
- * Performs spherical linear interpolation with the other vector
- * and returns the resulting vector.
- * This works in both 3D and 2D. As for 2D, the result of slerping
- * between 2D vectors is always a 2D vector.
+ * Calculates a new heading and magnitude that are between two vectors. The
+ * `amt` parameter is the amount to interpolate between the old vector and
+ * the new vector. 0.0 keeps the heading and magnitude equal to the old
+ * vector's, 0.5 sets them halfway between, and 1.0 sets the heading and
+ * magnitude equal to the new vector's.
+ *
+ * `slerp()` differs from lerp() because
+ * it interpolates magnitude. Calling `v0.slerp(v1, 0.5)` sets `v0`'s
+ * magnitude to a value halfway between its original magnitude and `v1`'s.
+ * Calling `v0.lerp(v1, 0.5)` makes no such guarantee.
+ *
+ * The static version of `slerp()`, as in `p5.Vector.slerp(v0, v1, 0.5)`,
+ * returns a new p5.Vector object and doesn't change
+ * the original.
*
* @method slerp
- * @param {p5.Vector} v the p5.Vector to slerp to
- * @param {Number} amt The amount of interpolation. some value between 0.0
- * (old vector) and 1.0 (new vector). 0.9 is very near
- * the new vector. 0.5 is halfway in between.
+ * @param {p5.Vector} v p5.Vector to slerp toward.
+ * @param {Number} amt amount of interpolation between 0.0 (old vector)
+ * and 1.0 (new vector). 0.5 is halfway between.
* @return {p5.Vector}
*
* @example
*
*
+ * let v0 = createVector(3, 0);
+ * // Prints "3" to the console.
+ * print(v0.mag());
+ * // Prints "0" to the console.
+ * print(v0.heading());
*
- * const v1 = createVector(1, 0, 0);
- * const v2 = createVector(0, 1, 0);
+ * let v1 = createVector(0, 1);
+ * // Prints "1" to the console.
+ * print(v1.mag());
+ * // Prints "1.570..." to the console.
+ * print(v1.heading());
*
- * const v = v1.slerp(v2, 1/3);
- * print(v.toString());
- * // v's components are almost [cos(30°), sin(30°), 0]
+ * v0.slerp(v1, 0.5);
+ * // Prints "2" to the console.
+ * print(v0.mag());
+ * // Prints "0.785..." to the console.
+ * print(v0.heading());
*
*
*
- *
+ *
*
- * let needle;
- * function setup() {
- * createCanvas(100, 100);
- * stroke(0);
- * strokeWeight(4);
- *
- * needle = createVector(50, 0);
- * }
- *
- * function draw(){
- * background(255);
- * translate(50, 50);
+ * let v0 = createVector(3, 0);
+ * // Prints "3" to the console.
+ * print(v0.mag());
+ * // Prints "0" to the console.
+ * print(v0.heading());
*
- * const v = createVector(mouseX - 50, mouseY - 50).setMag(50);
- * // slerp between v and needle vector.
- * // needle vector is changed by slerp function.
- * needle.slerp(v, 0.05);
+ * let v1 = createVector(0, 1);
+ * // Prints "1" to the console.
+ * print(v1.mag());
+ * // Prints "1.570..." to the console.
+ * print(v1.heading());
*
- * line(0, 0, needle.x, needle.y);
- * }
+ * let v3 = p5.Vector.slerp(v0, v1, 0.5);
+ * // Prints "2" to the console.
+ * print(v3.mag());
+ * // Prints "0.785..." to the console.
+ * print(v3.heading());
*
*
*
*
*
- * function setup(){
- * createCanvas(100, 100, WEBGL);
+ * function draw() {
+ * background(200);
+ *
+ * let v0 = createVector(50, 50);
+ * let v1 = createVector(20, 0);
+ * let v2 = createVector(-40, 0);
+ * let v3 = p5.Vector.slerp(v1, v2, 0.5);
+ *
+ * drawArrow(v0, v1, 'red');
+ * drawArrow(v0, v2, 'blue');
+ * drawArrow(v0, v3, 'purple');
+ *
+ * describe('Three arrows extend from the center of a gray square. A red arrow points to the right, a blue arrow points to the left, and a purple arrow points down.');
* }
*
- * function draw(){
- * background(255);
- *
- * const vx = createVector(30, 0, 0);
- * const vy = createVector(0, 30, 0);
- * const vz = createVector(0, 0, 30);
- *
- * const t = map(sin(frameCount * TAU / 120), -1, 1, 0, 1);
- * // v1, v2, v3 is not changed by slerp function.
- * // because this function is static version.
- * const vSlerpXY = p5.Vector.slerp(vx, vy, t);
- * const vSlerpYZ = p5.Vector.slerp(vy, vz, t);
- * const vSlerpZX = p5.Vector.slerp(vz, vx, t);
- * strokeWeight(6);
- * strokeCap(SQUARE);
- * stroke('red');
- * line(0, 0, 0, vSlerpXY.x, vSlerpXY.y, vSlerpXY.z);
- * stroke('green');
- * line(0, 0, 0, vSlerpYZ.x, vSlerpYZ.y, vSlerpYZ.z);
- * stroke('blue');
- * line(0, 0, 0, vSlerpZX.x, vSlerpZX.y, vSlerpZX.z);
+ * function drawArrow(base, vec, myColor) {
+ * push();
+ * stroke(myColor);
+ * strokeWeight(3);
+ * fill(myColor);
+ * translate(base.x, base.y);
+ * line(0, 0, vec.x, vec.y);
+ * rotate(vec.heading());
+ * let arrowSize = 7;
+ * translate(vec.mag() - arrowSize, 0);
+ * triangle(0, arrowSize / 2, 0, -arrowSize / 2, arrowSize, 0);
+ * pop();
* }
*
*
@@ -1891,40 +2167,59 @@ p5.Vector = class {
}
/**
- * Reflect a vector about a normal to a line in 2D, or about a normal to a
- * plane in 3D.
+ * Reflects a vector about a line in 2D or a plane in 3D. The orientation of
+ * the line or plane is described by a normal vector that points away from the
+ * shape.
+ *
+ * The static version of `reflect()`, as in `p5.Vector.reflect(v, n)`,
+ * returns a new
p5.Vector object and doesn't change
+ * the original.
*
* @method reflect
- * @param {p5.Vector} surfaceNormal the
p5.Vector
+ * @param {p5.Vector} surfaceNormal
p5.Vector
* to reflect about.
* @chainable
* @example
*
*
- * let v = createVector(4, 6); // incoming vector, this example vector is heading to the right and downward
- * let n = createVector(0, -1); // surface normal to a plane (this example normal points directly upwards)
- * v.reflect(n); // v is reflected about the surface normal n. v's components are now set to [4, -6]
+ * let n = createVector(0, 1);
+ * let v = createVector(4, 6);
+ * v.reflect(n);
+ * // Prints "p5.Vector Object : [4, -6, 0]" to the console.
+ * print(v.toString());
+ *
+ *
+ *
+ *
+ *
+ * let n = createVector(0, 1);
+ * let v0 = createVector(4, 6);
+ * let v1 = p5.Vector.reflect(v0, n);
+ * // Prints "p5.Vector Object : [4, -6, 0]" to the console.
+ * print(v1.toString());
*
*
*
*
*
* function draw() {
- * background(240);
+ * background(200);
*
- * let v0 = createVector(0, 0);
- * let v1 = createVector(mouseX, mouseY);
- * drawArrow(v0, v1, 'red');
+ * line(50, 0, 50, 100);
+ * let n = createVector(1, 0);
+ *
+ * let v0 = createVector(50, 50);
+ * let v1 = createVector(30, 40);
+ * let v2 = p5.Vector.reflect(v1, n);
*
- * let n = createVector(0, -30);
- * drawArrow(v1, n, 'blue');
+ * n.setMag(30);
+ * drawArrow(v0, n, 'black');
+ * drawArrow(v0, v1, 'red');
+ * drawArrow(v0, v2, 'blue');
*
- * let r = v1.copy();
- * r.reflect(n);
- * drawArrow(v1, r, 'purple');
+ * describe('Three arrows extend from the center of a gray square with a vertical line down its middle. A black arrow points to the right, a blue arrow points to the bottom left, and a red arrow points to the bottom right.');
* }
*
- * // draw an arrow for a vector at a given base position
* function drawArrow(base, vec, myColor) {
* push();
* stroke(myColor);
@@ -1947,30 +2242,16 @@ p5.Vector = class {
}
/**
- * Return a representation of this vector as a float array. This is only
- * for temporary use. If used in any other fashion, the contents should be
- * copied by using the p5.Vector.copy()
- * method to copy into your own vector.
+ * Returns the vector's components as an array of numbers.
*
* @method array
- * @return {Number[]} An Array with the 3 values
+ * @return {Number[]} array with the vector's components.
* @example
*
*
- * function setup() {
- * let v = createVector(20, 30);
- * print(v.array()); // Prints : Array [20, 30, 0]
- * }
- *
- *
- *
- *
- *
- * let v = createVector(10.0, 20.0, 30.0);
- * let f = v.array();
- * print(f[0]); // Prints "10.0"
- * print(f[1]); // Prints "20.0"
- * print(f[2]); // Prints "30.0"
+ * let v = createVector(20, 30);
+ * // Prints "[20, 30, 0]" to the console.
+ * print(v.array());
*
*
*/
@@ -1979,38 +2260,67 @@ p5.Vector = class {
}
/**
- * Equality check against a p5.Vector .
+ * Returns `true` if the vector's components are all the same as another
+ * vector's and `false` if not.
+ *
+ * The version of `equals()` with one parameter interprets it as another
+ * p5.Vector object.
+ *
+ * The version of `equals()` with multiple parameters interprets them as the
+ * components of another vector. Any missing parameters are assigned the value
+ * 0.
+ *
+ * The static version of `equals()`, as in `p5.Vector.equals(v0, v1)`,
+ * interprets both parameters as p5.Vector objects.
*
* @method equals
- * @param {Number} [x] The x component of the vector
- * @param {Number} [y] The y component of the vector
- * @param {Number} [z] The z component of the vector
- * @return {Boolean} Whether the vectors are equal
+ * @param {Number} [x] x component of the vector.
+ * @param {Number} [y] y component of the vector.
+ * @param {Number} [z] z component of the vector.
+ * @return {Boolean} whether the vectors are equal.
* @example
+ *
+ *
+ * let v0 = createVector(10, 20, 30);
+ * let v1 = createVector(10, 20, 30);
+ * let v2 = createVector(0, 0, 0);
+ *
+ * // Prints "true" to the console.
+ * print(v0.equals(v1));
+ * // Prints "false" to the console.
+ * print(v0.equals(v2));
+ *
+ *
+ *
*
*
+ * let v0 = createVector(5, 10, 20);
* let v1 = createVector(5, 10, 20);
- * let v2 = createVector(5, 10, 20);
- * let v3 = createVector(13, 10, 19);
+ * let v2 = createVector(13, 10, 19);
*
- * print(v1.equals(v2.x, v2.y, v2.z)); // true
- * print(v1.equals(v3.x, v3.y, v3.z)); // false
+ * // Prints "true" to the console.
+ * print(v0.equals(v1.x, v1.y, v1.z));
+ * // Prints "false" to the console.
+ * print(v0.equals(v2.x, v2.y, v2.z));
*
*
*
*
*
- * let v1 = createVector(10.0, 20.0, 30.0);
- * let v2 = createVector(10.0, 20.0, 30.0);
- * let v3 = createVector(0.0, 0.0, 0.0);
- * print(v1.equals(v2)); // true
- * print(v1.equals(v3)); // false
+ * let v0 = createVector(10, 20, 30);
+ * let v1 = createVector(10, 20, 30);
+ * let v2 = createVector(0, 0, 0);
+ *
+ * // Prints "true" to the console.
+ * print(p5.Vector.equals(v0, v1));
+ * // Prints "false" to the console.
+ * print(p5.Vector.equals(v0, v2));
*
*
*/
/**
* @method equals
- * @param {p5.Vector|Array} value The vector to compare
+ * @param {p5.Vector|Array} value vector to compare.
* @return {Boolean}
*/
equals(x, y, z) {
@@ -2038,40 +2348,42 @@ p5.Vector = class {
*
* @method fromAngle
* @static
- * @param {Number} angle The desired angle, in radians (unaffected by angleMode )
- * @param {Number} [length] The length of the new vector (defaults to 1)
- * @return {p5.Vector} The new p5.Vector object
+ * @param {Number} angle desired angle, in radians. Unaffected by angleMode() .
+ * @param {Number} [length] length of the new vector (defaults to 1).
+ * @return {p5.Vector} new p5.Vector object.
* @example
+ *
+ *
+ * let v = p5.Vector.fromAngle(0);
+ * // Prints "p5.Vector Object : [1, 0, 0]" to the console.
+ * print(v.toString());
+ *
+ *
+ *
*
*
* function draw() {
* background(200);
*
- * // Create a variable, proportional to the mouseX,
- * // varying from 0-360, to represent an angle in degrees.
- * let myDegrees = map(mouseX, 0, width, 0, 360);
+ * let v0 = createVector(50, 50);
+ * let v1 = p5.Vector.fromAngle(0, 30);
*
- * // Display that variable in an onscreen text.
- * // (Note the nfc() function to truncate additional decimal places,
- * // and the "\xB0" character for the degree symbol.)
- * let readout = 'angle = ' + nfc(myDegrees, 1) + '\xB0';
- * noStroke();
- * fill(0);
- * text(readout, 5, 15);
+ * drawArrow(v0, v1, 'black');
*
- * // Create a p5.Vector using the fromAngle function,
- * // and extract its x and y components.
- * let v = p5.Vector.fromAngle(radians(myDegrees), 30);
- * let vx = v.x;
- * let vy = v.y;
+ * describe('A black arrow extends from the center of a gray square. It points to the right.');
+ * }
*
+ * function drawArrow(base, vec, myColor) {
* push();
- * translate(width / 2, height / 2);
- * noFill();
- * stroke(150);
- * line(0, 0, 30, 0);
- * stroke(0);
- * line(0, 0, vx, vy);
+ * stroke(myColor);
+ * strokeWeight(3);
+ * fill(myColor);
+ * translate(base.x, base.y);
+ * line(0, 0, vec.x, vec.y);
+ * rotate(vec.heading());
+ * let arrowSize = 7;
+ * translate(vec.mag() - arrowSize, 0);
+ * triangle(0, arrowSize / 2, 0, -arrowSize / 2, arrowSize, 0);
* pop();
* }
*
@@ -2089,30 +2401,41 @@ p5.Vector = class {
*
* @method fromAngles
* @static
- * @param {Number} theta The polar angle, in radians (zero is up)
- * @param {Number} phi The azimuthal angle, in radians
- * (zero is out of the screen)
- * @param {Number} [length] The length of the new vector (defaults to 1)
- * @return {p5.Vector} A new
p5.Vector object
+ * @param {Number} theta polar angle in radians (zero is up).
+ * @param {Number} phi azimuthal angle in radians
+ * (zero is out of the screen).
+ * @param {Number} [length] length of the new vector (defaults to 1).
+ * @return {p5.Vector} new
p5.Vector object.
* @example
- *
+ *
+ *
+ * let v = p5.Vector.fromAngles(0, 0);
+ * // Prints "p5.Vector Object : [0, -1, 0]" to the console.
+ * print(v.toString());
+ *
+ *
+ *
+ *
*
* function setup() {
* createCanvas(100, 100, WEBGL);
- * fill(255);
- * noStroke();
* }
+ *
* function draw() {
- * background(255);
+ * background(0);
*
- * let t = millis() / 1000;
+ * fill(255);
+ * noStroke();
*
- * // add three point lights
- * pointLight(color('#f00'), p5.Vector.fromAngles(t * 1.0, t * 1.3, 100));
- * pointLight(color('#0f0'), p5.Vector.fromAngles(t * 1.1, t * 1.2, 100));
- * pointLight(color('#00f'), p5.Vector.fromAngles(t * 1.2, t * 1.1, 100));
+ * let theta = frameCount * 0.05;
+ * let phi = 0;
+ * let v = p5.Vector.fromAngles(theta, phi, 100);
+ * let c = color('deeppink');
+ * pointLight(c, v);
*
* sphere(35);
+ *
+ * describe('A light shines on a pink sphere as it orbits.');
* }
*
*
@@ -2134,38 +2457,36 @@ p5.Vector = class {
}
/**
- * Make a new 2D unit vector from a random angle.
+ * Make a new 2D unit vector with a random heading.
*
* @method random2D
* @static
- * @return {p5.Vector} A new
p5.Vector object
+ * @return {p5.Vector} new
p5.Vector object.
* @example
*
*
* let v = p5.Vector.random2D();
- * // May make v's attributes something like:
- * // [0.61554617, -0.51195765, 0.0] or
- * // [-0.4695841, -0.14366731, 0.0] or
- * // [0.6091097, -0.22805278, 0.0]
- * print(v);
+ * // Prints "p5.Vector Object : [x, y, 0]" to the console
+ * // where x and y are small random numbers.
+ * print(v.toString());
*
*
*
*
*
- * function setup() {
- * frameRate(1);
- * }
- *
* function draw() {
- * background(240);
+ * background(200);
+ *
+ * frameRate(1);
*
* let v0 = createVector(50, 50);
* let v1 = p5.Vector.random2D();
- * drawArrow(v0, v1.mult(50), 'black');
+ * v1.mult(30);
+ * drawArrow(v0, v1, 'black');
+ *
+ * describe('A black arrow in extends from the center of a gray square. It changes direction once per second.');
* }
*
- * // draw an arrow for a vector at a given base position
* function drawArrow(base, vec, myColor) {
* push();
* stroke(myColor);
@@ -2187,20 +2508,18 @@ p5.Vector = class {
}
/**
- * Make a new random 3D unit vector.
+ * Make a new 3D unit vector with a random heading.
*
* @method random3D
* @static
- * @return {p5.Vector} A new p5.Vector object
+ * @return {p5.Vector} new p5.Vector object.
* @example
*
*
* let v = p5.Vector.random3D();
- * // May make v's attributes something like:
- * // [0.61554617, -0.51195765, 0.599168] or
- * // [-0.4695841, -0.14366731, -0.8711202] or
- * // [0.6091097, -0.22805278, -0.7595902]
- * print(v);
+ * // Prints "p5.Vector Object : [x, y, z]" to the console
+ * // where x, y, and z are small random numbers.
+ * print(v.toString());
*
*
*/
@@ -2231,8 +2550,8 @@ p5.Vector = class {
* @static
* @param {p5.Vector} v1 A p5.Vector to add
* @param {p5.Vector} v2 A p5.Vector to add
- * @param {p5.Vector} [target] The vector to receive the result
- * @return {p5.Vector} The resulting p5.Vector
+ * @param {p5.Vector} [target] vector to receive the result.
+ * @return {p5.Vector} resulting p5.Vector .
*/
static add(v1, v2, target) {
@@ -2282,7 +2601,7 @@ p5.Vector = class {
* @static
* @param {p5.Vector} v1 A p5.Vector to subtract from
* @param {p5.Vector} v2 A p5.Vector to subtract
- * @param {p5.Vector} [target] The vector to receive the result
+ * @param {p5.Vector} [target] vector to receive the result.
* @return {p5.Vector} The resulting p5.Vector
*/
@@ -2312,7 +2631,7 @@ p5.Vector = class {
* @param {Number} x
* @param {Number} y
* @param {Number} [z]
- * @return {p5.Vector} The resulting new p5.Vector
+ * @return {p5.Vector} resulting new p5.Vector .
*/
/**
@@ -2320,7 +2639,7 @@ p5.Vector = class {
* @static
* @param {p5.Vector} v
* @param {Number} n
- * @param {p5.Vector} [target] the vector to receive the result
+ * @param {p5.Vector} [target] vector to receive the result.
*/
/**
@@ -2440,9 +2759,9 @@ p5.Vector = class {
/**
* @method dot
* @static
- * @param {p5.Vector} v1 The first p5.Vector
- * @param {p5.Vector} v2 The second p5.Vector
- * @return {Number} The dot product
+ * @param {p5.Vector} v1 first p5.Vector .
+ * @param {p5.Vector} v2 second p5.Vector .
+ * @return {Number} dot product.
*/
static dot(v1, v2) {
return v1.dot(v2);
@@ -2454,9 +2773,9 @@ p5.Vector = class {
/**
* @method cross
* @static
- * @param {p5.Vector} v1 The first p5.Vector
- * @param {p5.Vector} v2 The second p5.Vector
- * @return {Number} The cross product
+ * @param {p5.Vector} v1 first p5.Vector .
+ * @param {p5.Vector} v2 second p5.Vector .
+ * @return {Number} cross product.
*/
static cross(v1, v2) {
return v1.cross(v2);
@@ -2515,10 +2834,10 @@ p5.Vector = class {
/**
* @method slerp
* @static
- * @param {p5.Vector} v1 old vector
- * @param {p5.Vector} v2 new vectpr
+ * @param {p5.Vector} v1 old vector.
+ * @param {p5.Vector} v2 new vector.
* @param {Number} amt
- * @param {p5.Vector} [target] The vector to receive the result
+ * @param {p5.Vector} [target] vector to receive the result.
* @return {p5.Vector} slerped vector between v1 and v2
*/
static slerp(v1, v2, amt, target) {
@@ -2670,9 +2989,9 @@ p5.Vector = class {
/**
* @method angleBetween
* @static
- * @param {p5.Vector} v1 the first vector
- * @param {p5.Vector} v2 the second vector
- * @return {Number} the angle between the two vectors
+ * @param {p5.Vector} v1 the first vector.
+ * @param {p5.Vector} v2 the second vector.
+ * @return {Number} angle between the two vectors.
*/
static angleBetween(v1, v2) {
return v1.angleBetween(v2);
@@ -2685,9 +3004,9 @@ p5.Vector = class {
/**
* @method reflect
* @static
- * @param {p5.Vector} incidentVector vector to be reflected
+ * @param {p5.Vector} incidentVector vector to be reflected.
* @param {p5.Vector} surfaceNormal
- * @param {p5.Vector} [target] the vector to receive the result (Optional)
+ * @param {p5.Vector} [target] vector to receive the result.
* @return {p5.Vector} the reflected vector
*/
static reflect(incidentVector, surfaceNormal, target) {
diff --git a/src/typography/loading_displaying.js b/src/typography/loading_displaying.js
index 5c046adf72..f625db3d99 100644
--- a/src/typography/loading_displaying.js
+++ b/src/typography/loading_displaying.js
@@ -14,75 +14,117 @@ import '../core/friendly_errors/file_errors';
import '../core/friendly_errors/fes_core';
/**
- * Loads an opentype font file (.otf, .ttf) from a file or a URL,
- * and returns a p5.Font object. This function
- * is asynchronous, meaning it may not finish before the next line in
- * your sketch is executed.
- *
- * The path to the font should be relative to the HTML file
- * that links in your sketch. Loading fonts from a URL or other
- * remote location may be blocked due to your browser's built-in
+ * Loads a font and creates a p5.Font object.
+ * `loadFont()` can load fonts in either .otf or .ttf format. Loaded fonts can
+ * be used to style text on the canvas and in HTML elements.
+ *
+ * The first parameter, `path`, is the path to a font file.
+ * Paths to local files should be relative. For example,
+ * `'assets/inconsolata.otf'`. The Inconsolata font used in the following
+ * examples can be downloaded for free
+ * here .
+ * Paths to remote files should be URLs. For example,
+ * `'https://example.com/inconsolata.otf'`. URLs may be blocked due to browser
* security.
*
+ * The second parameter, `successCallback`, is optional. If a function is
+ * passed, it will be called once the font has loaded. The callback function
+ * may use the new p5.Font object if needed.
+ *
+ * The third parameter, `failureCallback`, is also optional. If a function is
+ * passed, it will be called if the font fails to load. The callback function
+ * may use the error
+ * Event
+ * object if needed.
+ *
+ * Fonts can take time to load. Calling `loadFont()` in
+ * preload() ensures fonts load before they're
+ * used in setup() or
+ * draw() .
+ *
* @method loadFont
- * @param {String} path name of the file or url to load
- * @param {Function} [callback] function to be executed after
- * loadFont() completes
- * @param {Function} [onError] function to be executed if
- * an error occurs
- * @return {p5.Font} p5.Font object
+ * @param {String} path path of the font to be loaded.
+ * @param {Function} [successCallback] function called with the
+ * p5.Font object after it
+ * loads.
+ * @param {Function} [failureCallback] function called with the error
+ * Event
+ * object if the font fails to load.
+ * @return {p5.Font} p5.Font object.
* @example
*
- * Calling loadFont() inside preload() guarantees
- * that the load operation will have completed before setup()
- * and draw() are called.
+ *
+ *
+ * let font;
*
- *
- * let myFont;
* function preload() {
- * myFont = loadFont('assets/inconsolata.otf');
+ * font = loadFont('assets/inconsolata.otf');
* }
*
* function setup() {
- * fill('#ED225D');
- * textFont(myFont);
+ * fill('deeppink');
+ * textFont(font);
* textSize(36);
* text('p5*js', 10, 50);
+ *
+ * describe('The text "p5*js" written in pink on a white background.');
* }
- *
+ *
+ *
+ *
+ * function setup() {
+ * loadFont('assets/inconsolata.otf', font => {
+ * fill('deeppink');
+ * textFont(font);
+ * textSize(36);
+ * text('p5*js', 10, 50);
*
- * Outside of preload() , you may supply a
- * callback function to handle the object:
+ * describe('The text "p5*js" written in pink on a white background.');
+ * });
+ * }
+ *
+ *
+ *
+ *
* function setup() {
- * loadFont('assets/inconsolata.otf', drawText);
+ * loadFont('assets/inconsolata.otf', success, failure);
* }
*
- * function drawText(font) {
- * fill('#ED225D');
- * textFont(font, 36);
+ * function success(font) {
+ * fill('deeppink');
+ * textFont(font);
+ * textSize(36);
* text('p5*js', 10, 50);
+ *
+ * describe('The text "p5*js" written in pink on a white background.');
* }
- *
*
- * You can also use the font filename string (without the file extension) to
- * style other HTML elements.
+ * function failure(event) {
+ * console.error('Oops!', event);
+ * }
+ *
+ *
+ *
+ *
* function preload() {
* loadFont('assets/inconsolata.otf');
* }
*
* function setup() {
- * let myDiv = createDiv('hello there');
- * myDiv.style('font-family', 'Inconsolata');
- * }
- *
+ * let p = createP('p5*js');
+ * p.style('color', 'deeppink');
+ * p.style('font-family', 'Inconsolata');
+ * p.style('font-size', '36px');
+ * p.position(10, 50);
*
- * @alt
- * p5*js in p5's theme dark pink
- * p5*js in p5's theme dark pink
+ * describe('The text "p5*js" written in pink on a white background.');
+ * }
+ *
+ *
textFont() function and a default size will be
- * used unless a font is set with textSize() . Change
- * the color of the text with the fill() function. Change
- * the outline of the text with the stroke() and
- * strokeWeight() functions.
- *
- * The text displays in relation to the textAlign()
- * function, which gives the option to draw to the left, right, and center of the
- * coordinates.
- *
- * The x2 and y2 parameters define a rectangular area to display within and
- * may only be used with string data. When these parameters are specified,
- * they are interpreted based on the current rectMode()
- * setting. Text that does not fit completely within the rectangle specified will
- * not be drawn to the screen. If x2 and y2 are not specified, the baseline
- * alignment is the default, which means that the text will be drawn upwards
- * from x and y.
- *
- * WEBGL : Only opentype/truetype fonts are supported. You must load a font
- * using the loadFont() method (see the example above).
- * stroke() currently has no effect in webgl mode.
- * Learn more about working with text in webgl mode on the
- * wiki .
+ * Draws text to the canvas.
+ *
+ * The first parameter, `str`, is the text to be drawn. The second and third
+ * parameters, `x` and `y`, set the coordinates of the text's bottom-left
+ * corner. See textAlign() for other ways to
+ * align text.
+ *
+ * The fourth and fifth parameters, `maxWidth` and `maxHeight`, are optional.
+ * They set the dimensions of the invisible rectangle containing the text. By
+ * default, they set its maximum width and height. See
+ * rectMode() for other ways to define the
+ * rectangular text box. Text will wrap to fit within the text box. Text
+ * outside of the box won't be drawn.
+ *
+ * Text can be styled a few ways. Call the fill()
+ * function to set the text's fill color. Call
+ * stroke() and
+ * strokeWeight() to set the text's outline.
+ * Call textSize() and
+ * textFont() to set the text's size and font,
+ * respectively.
+ *
+ * Note: `WEBGL` mode only supports fonts loaded with
+ * loadFont() . Calling
+ * stroke() has no effect in `WEBGL` mode.
*
* @method text
- * @param {String|Object|Array|Number|Boolean} str the alphanumeric
- * symbols to be displayed
- * @param {Number} x x-coordinate of text
- * @param {Number} y y-coordinate of text
- * @param {Number} [x2] by default, the width of the text box,
- * see rectMode() for more info
- * @param {Number} [y2] by default, the height of the text box,
- * see rectMode() for more info
+ * @param {String|Object|Array|Number|Boolean} str text to be displayed.
+ * @param {Number} x x-coordinate of the text box.
+ * @param {Number} y y-coordinate of the text box.
+ * @param {Number} [maxWidth] maximum width of the text box. See
+ * rectMode() for
+ * other options.
+ * @param {Number} [maxHeight] maximum height of the text box. See
+ * rectMode() for
+ * other options.
+ *
* @chainable
* @example
*
*
- * textSize(32);
- * text('word', 10, 30);
- * fill(0, 102, 153);
- * text('word', 10, 60);
- * fill(0, 102, 153, 51);
- * text('word', 10, 90);
+ * function setup() {
+ * background(200);
+ * text('hi', 50, 50);
+ *
+ * describe('The text "hi" written in black in the middle of a gray square.');
+ * }
+ *
+ *
+ *
+ *
+ *
+ * function setup() {
+ * background('skyblue');
+ * textSize(100);
+ * text('🌈', 0, 100);
+ *
+ * describe('A rainbow in a blue sky.');
+ * }
+ *
+ *
+ *
+ *
+ *
+ * function setup() {
+ * textSize(32);
+ * fill(255);
+ * stroke(0);
+ * strokeWeight(4);
+ * text('hi', 50, 50);
+ *
+ * describe('The text "hi" written in white with a black outline.');
+ * }
+ *
+ *
+ *
+ *
+ *
+ * function setup() {
+ * background('black');
+ * textSize(22);
+ * fill('yellow');
+ * text('rainbows', 6, 20);
+ * fill('cornflowerblue');
+ * text('rainbows', 6, 45);
+ * fill('tomato');
+ * text('rainbows', 6, 70);
+ * fill('limegreen');
+ * text('rainbows', 6, 95);
+ *
+ * describe('The text "rainbows" written on several lines, each in a different color.');
+ * }
+ *
+ *
+ *
+ *
+ *
+ * function setup() {
+ * background(200);
+ * let s = 'The quick brown fox jumps over the lazy dog.';
+ * text(s, 10, 10, 70, 80);
+ *
+ * describe('The sample text "The quick brown fox..." written in black across several lines.');
+ * }
*
*
+ *
*
*
- * let s = 'The quick brown fox jumped over the lazy dog.';
- * fill(50);
- * text(s, 10, 10, 70, 80); // Text wraps within text box
+ * function setup() {
+ * background(200);
+ * rectMode(CENTER);
+ * let s = 'The quick brown fox jumps over the lazy dog.';
+ * text(s, 50, 50, 70, 80);
+ *
+ * describe('The sample text "The quick brown fox..." written in black across several lines.');
+ * }
*
*
*
*
*
- * let inconsolata;
+ * let font;
+ *
* function preload() {
- * inconsolata = loadFont('assets/inconsolata.otf');
+ * font = loadFont('assets/inconsolata.otf');
* }
+ *
* function setup() {
* createCanvas(100, 100, WEBGL);
- * textFont(inconsolata);
- * textSize(width / 3);
+ * textFont(font);
+ * textSize(32);
* textAlign(CENTER, CENTER);
* }
+ *
* function draw() {
* background(0);
- * let time = millis();
- * rotateX(time / 1000);
- * rotateZ(time / 1234);
- * text('p5.js', 0, 0);
+ * rotateY(frameCount / 30);
+ * text('p5*js', 0, 0);
+ *
+ * describe('The text "p5*js" written in white and spinning in 3D.');
* }
*
*
- *
- * @alt
- * 'word' displayed 3 times going from black, blue to translucent blue
- * The text 'The quick brown fox jumped over the lazy dog' displayed.
- * The text 'p5.js' spinning in 3d
*/
p5.prototype.text = function(str, x, y, maxWidth, maxHeight) {
p5._validateParameters('text', arguments);
@@ -229,60 +333,92 @@ p5.prototype.text = function(str, x, y, maxWidth, maxHeight) {
};
/**
- * Sets the current font that will be drawn with the text() function.
- * If textFont() is called without any argument, it will return the current font if one has
- * been set already. If not, it will return the name of the default font as a string.
- * If textFont() is called with a font to use, it will return the p5 object.
+ * Sets the font used by the text() function.
*
- * WEBGL : Only fonts loaded via loadFont() are supported.
+ * The first parameter, `font`, sets the font. `textFont()` recognizes either
+ * a p5.Font object or a string with the name of a
+ * system font. For example, `'Courier New'`.
+ *
+ * The second parameter, `size`, is optional. It sets the font size in pixels.
+ * This has the same effect as calling textSize() .
+ *
+ * Note: `WEBGL` mode only supports fonts loaded with
+ * loadFont() .
*
* @method textFont
- * @return {Object} the current font / p5 Object
+ * @return {Object} current font or p5 Object.
*
* @example
*
*
- * fill(0);
- * textSize(12);
- * textFont('Georgia');
- * text('Georgia', 12, 30);
- * textFont('Helvetica');
- * text('Helvetica', 12, 60);
+ * function setup() {
+ * background(200);
+ * textFont('Courier New');
+ * textSize(24);
+ * text('hi', 35, 55);
+ *
+ * describe('The text "hi" written in a black, monospace font on a gray background.');
+ * }
+ *
+ *
+ *
+ *
+ *
+ * function setup() {
+ * background('black');
+ * fill('palegreen');
+ * textFont('Courier New', 10);
+ * text('You turn to the left and see a door. Do you enter?', 5, 5, 90, 90);
+ * text('>', 5, 70);
+ *
+ * describe('A text prompt from a game is written in a green, monospace font on a black background.');
+ * }
+ *
+ *
+ *
+ *
+ *
+ * function setup() {
+ * background(200);
+ * textFont('Verdana');
+ * let currentFont = textFont();
+ * text(currentFont, 25, 50);
+ *
+ * describe('The text "Verdana" written in a black, sans-serif font on a gray background.');
+ * }
*
*
+ *
*
*
- * let fontRegular, fontItalic, fontBold;
+ * let fontRegular;
+ * let fontItalic;
+ * let fontBold;
+ *
* function preload() {
* fontRegular = loadFont('assets/Regular.otf');
* fontItalic = loadFont('assets/Italic.ttf');
* fontBold = loadFont('assets/Bold.ttf');
* }
+ *
* function setup() {
- * background(210);
- * fill(0)
- .strokeWeight(0)
- .textSize(10);
+ * background(200);
* textFont(fontRegular);
- * text('Font Style Normal', 10, 30);
+ * text('I am Normal', 10, 30);
* textFont(fontItalic);
- * text('Font Style Italic', 10, 50);
+ * text('I am Italic', 10, 50);
* textFont(fontBold);
- * text('Font Style Bold', 10, 70);
+ * text('I am Bold', 10, 70);
+ *
+ * describe('The statements "I am Normal", "I am Italic", and "I am Bold" written in black on separate lines. The statements have normal, italic, and bold fonts, respectively.');
* }
*
*
- *
- * @alt
- * word 'Georgia' displayed in font Georgia and 'Helvetica' in font Helvetica
- * words Font Style Normal displayed normally, Italic in italic and bold in bold
*/
/**
* @method textFont
- * @param {Object|String} font a font loaded via loadFont() ,
- * or a String representing a web safe font
- * (a font that is generally available across all systems)
- * @param {Number} [size] the font size to use
+ * @param {Object|String} font font as a p5.Font object or a string.
+ * @param {Number} [size] font size in pixels.
* @chainable
*/
p5.prototype.textFont = function(theFont, theSize) {
diff --git a/src/typography/p5.Font.js b/src/typography/p5.Font.js
index 21b5c64cd7..c827964a82 100644
--- a/src/typography/p5.Font.js
+++ b/src/typography/p5.Font.js
@@ -11,10 +11,30 @@ import p5 from '../core/main';
import * as constants from '../core/constants';
/**
- * Base class for font handling
+ * A class to describe fonts.
* @class p5.Font
* @constructor
- * @param {p5} [pInst] pointer to p5 instance
+ * @param {p5} [pInst] pointer to p5 instance.
+ * @example
+ *
+ *
+ * let font;
+ *
+ * function preload() {
+ * // Creates a p5.Font object.
+ * font = loadFont('assets/inconsolata.otf');
+ * }
+ *
+ * function setup() {
+ * fill('deeppink');
+ * textFont(font);
+ * textSize(36);
+ * text('p5*js', 10, 50);
+ *
+ * describe('The text "p5*js" written in pink on a white background.');
+ * }
+ *
+ *
*/
p5.Font = class {
constructor(p){
@@ -23,51 +43,103 @@ p5.Font = class {
this.cache = {};
/**
- * Underlying opentype font implementation
+ * Underlying
+ * opentype.js
+ * font object.
* @property font
*/
this.font = undefined;
}
/**
- * Returns a tight bounding box for the given text string using this
- * font
+ * Returns the bounding box for a string of text written using this
+ * p5.Font .
*
- * @method textBounds
- * @param {String} line a line of text
- * @param {Number} x x-position
- * @param {Number} y y-position
- * @param {Number} [fontSize] font size to use (optional) Default is 12.
- * @param {Object} [options] opentype options (optional)
- * opentype fonts contains alignment and baseline options.
- * Default is 'LEFT' and 'alphabetic'
+ * The first parameter, `str`, is a string of text. The second and third
+ * parameters, `x` and `y`, are the text's position. By default, they set the
+ * coordinates of the bounding box's bottom-left corner. See
+ * textAlign() for more ways to align text.
+ *
+ * The fourth parameter, `fontSize`, is optional. It sets the font size used to
+ * determine the bounding box. By default, `font.textBounds()` will use the
+ * current textSize() .
*
- * @return {Object} a rectangle object with properties: x, y, w, h
+ * @method textBounds
+ * @param {String} str string of text.
+ * @param {Number} x x-coordinate of the text.
+ * @param {Number} y y-coordinate of the text.
+ * @param {Number} [fontSize] font size. Defaults to the current
+ * textSize() .
+ * @return {Object} object describing the bounding box with
+ * properties x, y, w, and h.
*
* @example
*
*
* let font;
- * let textString = 'Lorem ipsum dolor sit amet.';
+ *
+ * function preload() {
+ * font = loadFont('assets/inconsolata.otf');
+ * }
+ *
+ * function setup() {
+ * background(200);
+ *
+ * let bbox = font.textBounds('p5*js', 35, 53);
+ * rect(bbox.x, bbox.y, bbox.w, bbox.h);
+ *
+ * textFont(font);
+ * text('p5*js', 35, 53);
+ *
+ * describe('The text "p5*js" written in black inside a white rectangle.');
+ * }
+ *
+ *
+ *
+ *
+ *
+ * let font;
+ *
* function preload() {
- * font = loadFont('./assets/Regular.otf');
+ * font = loadFont('assets/inconsolata.otf');
* }
+ *
* function setup() {
- * background(210);
+ * background(200);
+ *
+ * textFont(font);
+ * textSize(15);
+ * textAlign(CENTER, CENTER);
*
- * let bbox = font.textBounds(textString, 10, 30, 12);
- * fill(255);
- * stroke(0);
+ * let bbox = font.textBounds('p5*js', 50, 50);
+ * rect(bbox.x, bbox.y, bbox.w, bbox.h);
+ *
+ * text('p5*js', 50, 50);
+ *
+ * describe('The text "p5*js" written in black inside a white rectangle.');
+ * }
+ *
+ *
+ *
+ *
+ *
+ * let font;
+ *
+ * function preload() {
+ * font = loadFont('assets/inconsolata.otf');
+ * }
+ *
+ * function setup() {
+ * background(200);
+ *
+ * let bbox = font.textBounds('p5*js', 31, 53, 15);
* rect(bbox.x, bbox.y, bbox.w, bbox.h);
- * fill(0);
- * noStroke();
*
* textFont(font);
- * textSize(12);
- * text(textString, 10, 30);
+ * textSize(15);
+ * text('p5*js', 31, 53);
*
- * describe(`Words “Lorem ipsum dol” go off canvas and
- * contained by white bounding box`);
+ * describe('The text "p5*js" written in black inside a white rectangle.');
* }
*
*
@@ -174,59 +246,55 @@ p5.Font = class {
}
/**
- * Computes an array of points following the path for specified text
+ * Returns an array of points outlining a string of text written using this
+ * p5.Font .
*
- * @method textToPoints
- * @param {String} txt a line of text
- * @param {Number} x x-position
- * @param {Number} y y-position
- * @param {Number} fontSize font size to use (optional)
- * @param {Object} [options] an (optional) object that can contain:
+ * The first parameter, `str`, is a string of text. The second and third
+ * parameters, `x` and `y`, are the text's position. By default, they set the
+ * coordinates of the bounding box's bottom-left corner. See
+ * textAlign() for more ways to align text.
+ *
+ * The fourth parameter, `fontSize`, is optional. It sets the text's font
+ * size. By default, `font.textToPoints()` will use the current
+ * textSize() .
+ *
+ * The fifth parameter, `options`, is also optional. `font.textToPoints()`
+ * expects an object with the following properties:
*
- * textSize() .
+ * @param {Object} [options] object with sampleFactor and simplifyThreshold
+ * properties.
+ * @return {Array} array of point objects, each with x, y, and alpha (path angle) properties.
* @example
*
*
* let font;
+ *
* function preload() {
* font = loadFont('assets/inconsolata.otf');
* }
*
- * let points;
- * let bounds;
* function setup() {
- * createCanvas(100, 100);
- * stroke(0);
- * fill(255, 104, 204);
- *
- * points = font.textToPoints('p5', 0, 0, 10, {
- * sampleFactor: 5,
- * simplifyThreshold: 0
+ * background(200);
+ * let points = font.textToPoints('p5*js', 6, 60, 35, { sampleFactor: 0.5 });
+ * points.forEach(p => {
+ * point(p.x, p.y);
* });
- * bounds = font.textBounds(' p5 ', 0, 0, 10);
- * }
*
- * function draw() {
- * background(255);
- * beginShape();
- * translate(-bounds.x * width / bounds.w, -bounds.y * height / bounds.h);
- * for (let i = 0; i < points.length; i++) {
- * let p = points[i];
- * vertex(
- * p.x * width / bounds.w +
- * sin(20 * p.y / bounds.h + millis() / 1000) * width / 30,
- * p.y * height / bounds.h
- * );
- * }
- * endShape(CLOSE);
+ * describe('A set of black dots outlining the text "p5*js" on a gray background.');
* }
*
*
diff --git a/src/utilities/conversion.js b/src/utilities/conversion.js
index b640b4bd53..983d7ce61b 100644
--- a/src/utilities/conversion.js
+++ b/src/utilities/conversion.js
@@ -24,15 +24,13 @@ import p5 from '../core/main';
* let str = '20';
* let diameter = float(str);
* ellipse(width / 2, height / 2, diameter, diameter);
+ * describe('20-by-20 white ellipse in the center of the canvas');
*
*
* print(float('10.31')); // 10.31
* print(float('Infinity')); // Infinity
* print(float('-Infinity')); // -Infinity
*
- *
- * @alt
- * 20 by 20 white ellipse in the center of the canvas
*/
p5.prototype.float = function(str) {
if (str instanceof Array) {
diff --git a/src/utilities/string_functions.js b/src/utilities/string_functions.js
index 41fe142756..97285c88e6 100644
--- a/src/utilities/string_functions.js
+++ b/src/utilities/string_functions.js
@@ -29,11 +29,9 @@ import '../core/friendly_errors/fes_core';
* let separator = ' ';
* let message = join(array, separator);
* text(message, 5, 50);
+ * describe('“Hello world!” displayed middle left of canvas.');
*
*
- *
- * @alt
- * "hello world!" displayed middle left of canvas.
*/
p5.prototype.join = function(list, separator) {
p5._validateParameters('join', arguments);
@@ -69,11 +67,9 @@ p5.prototype.join = function(list, separator) {
* let regexp = 'p5js\\*';
* let m = match(string, regexp);
* text(m, 5, 50);
+ * describe('“p5js*” displayed middle left of canvas.');
*
*
*
- *
- * @alt
- * "0321.00" middle top, -1321.00" middle bottom canvas
*/
/**
* @method nf
@@ -249,12 +244,11 @@ function doNf(num, left, right) {
* // Draw dividing line
* stroke(120);
* line(0, 50, width, 50);
+ *
+ * describe('“11,253,106.115” top middle and “1.00,1.00,2.00” displayed bottom mid');
* }
*
*
*
*
*
* let string = trim(' No new lines\n ');
* text(string + ' here', 2, 50);
+ * describe('“No new lines here” displayed center canvas');
*
*
* let d = day();
* text('Current day: \n' + d, 5, 50);
+ * describe('Current day is displayed');
*
*
* let h = hour();
* text('Current hour:\n' + h, 5, 50);
+ * describe('Current hour is displayed');
*
*
- *
- * @alt
- * Current hour is displayed
*/
p5.prototype.hour = function() {
return new Date().getHours();
@@ -60,11 +56,9 @@ p5.prototype.hour = function() {
*
* let m = minute();
* text('Current minute: \n' + m, 5, 50);
+ * describe('Current minute is displayed');
*
*
- *
- * @alt
- * Current minute is displayed
*/
p5.prototype.minute = function() {
return new Date().getMinutes();
@@ -82,11 +76,9 @@ p5.prototype.minute = function() {
*
* let millisecond = millis();
* text('Milliseconds \nrunning: \n' + millisecond, 5, 40);
+ * describe('number of milliseconds since sketch has started displayed');
*
*
- *
- * @alt
- * number of milliseconds since sketch has started displayed
*/
p5.prototype.millis = function() {
if (this._millisStart === -1) {
@@ -108,11 +100,9 @@ p5.prototype.millis = function() {
*
* let m = month();
* text('Current month: \n' + m, 5, 50);
+ * describe('Current month is displayed');
*
*
- *
- * @alt
- * Current month is displayed
*/
p5.prototype.month = function() {
//January is 0!
@@ -130,11 +120,9 @@ p5.prototype.month = function() {
*
* let s = second();
* text('Current second: \n' + s, 5, 50);
+ * describe('Current second is displayed');
*
*
- *
- * @alt
- * Current second is displayed
*/
p5.prototype.second = function() {
return new Date().getSeconds();
@@ -151,11 +139,9 @@ p5.prototype.second = function() {
*
* let y = year();
* text('Current year: \n' + y, 5, 50);
+ * describe('Current year is displayed');
*
*
p5.Shader using only a fragment shader, as a convenience method for creating image effects.
* It's like createShader() but with a default vertex shader included.
*
- * createFilterShader() is intended to be used along with filter() for filtering the entire contents of a canvas in WebGL mode.
+ * createFilterShader() is intended to be used along with filter() for filtering the contents of a canvas in WebGL mode.
+ * A filter shader will not be applied to any geometries.
*
- * Note:
- * - The fragment shader is provided with a single texture input uniform called `tex0`.
- * This is created specificially for filter shaders to access the canvas contents.
- *
- * - A filter shader will not apply to a 3D geometry.
- *
- * - Shaders can only be used in `WEBGL` mode.
+ * The fragment shader receives some uniforms:
+ * - `sampler2D tex0`, which contains the canvas contents as a texture
+ * - `vec2 canvasSize`, which is the width and height of the canvas
+ * - `vec2 texelSize`, which is the size of a pixel (`1.0/width`, `1.0/height`)
*
* For more info about filters and shaders, see Adam Ferriss' repo of shader examples
* or the introduction to shaders page.
@@ -235,7 +233,10 @@ p5.prototype.createShader = function(vertSrc, fragSrc) {
*
* // the canvas contents, given from filter()
* uniform sampler2D tex0;
- * // a custom variable from the sketch
+ * // other useful information from the canvas
+ * uniform vec2 texelSize;
+ * uniform vec2 canvasSize;
+ * // a custom variable from this sketch
* uniform float darkness;
*
* void main() {
@@ -262,26 +263,50 @@ p5.prototype.createShader = function(vertSrc, fragSrc) {
p5.prototype.createFilterShader = function(fragSrc) {
this._assert3d('createFilterShader');
p5._validateParameters('createFilterShader', arguments);
- let defaultVertSrc = `
+ let defaultVertV1 = `
+ uniform mat4 uModelViewMatrix;
+ uniform mat4 uProjectionMatrix;
+
attribute vec3 aPosition;
// texcoords only come from p5 to vertex shader
// so pass texcoords on to the fragment shader in a varying variable
attribute vec2 aTexCoord;
varying vec2 vTexCoord;
-
+
void main() {
// transferring texcoords for the frag shader
vTexCoord = aTexCoord;
-
+
// copy position with a fourth coordinate for projection (1.0 is normal)
vec4 positionVec4 = vec4(aPosition, 1.0);
- // scale by two and center to achieve correct positioning
- positionVec4.xy = positionVec4.xy * 2.0 - 1.0;
-
- gl_Position = positionVec4;
+
+ // project to 3D space
+ gl_Position = uProjectionMatrix * uModelViewMatrix * positionVec4;
}
`;
- return new p5.Shader(this._renderer, defaultVertSrc, fragSrc);
+ let defaultVertV2 = `#version 300 es
+ uniform mat4 uModelViewMatrix;
+ uniform mat4 uProjectionMatrix;
+
+ in vec3 aPosition;
+ in vec2 aTexCoord;
+ out vec2 vTexCoord;
+
+ void main() {
+ // transferring texcoords for the frag shader
+ vTexCoord = aTexCoord;
+
+ // copy position with a fourth coordinate for projection (1.0 is normal)
+ vec4 positionVec4 = vec4(aPosition, 1.0);
+
+ // project to 3D space
+ gl_Position = uProjectionMatrix * uModelViewMatrix * positionVec4;
+ }
+ `;
+ let vertSrc = fragSrc.includes('#version 300 es') ? defaultVertV2 : defaultVertV1;
+ const shader = new p5.Shader(this._renderer, vertSrc, fragSrc);
+ shader.ensureCompiledOnContext(this._renderer.getFilterGraphicsLayer());
+ return shader;
};
/**
@@ -370,11 +395,7 @@ p5.prototype.shader = function(s) {
this._assert3d('shader');
p5._validateParameters('shader', arguments);
- if (s._renderer === undefined) {
- s._renderer = this._renderer;
- }
-
- s.init();
+ s.ensureCompiledOnContext(this);
if (s.isStrokeShader()) {
this._renderer.userStrokeShader = s;
diff --git a/src/webgl/p5.Camera.js b/src/webgl/p5.Camera.js
index f592732317..3ffa915876 100644
--- a/src/webgl/p5.Camera.js
+++ b/src/webgl/p5.Camera.js
@@ -1622,7 +1622,8 @@ p5.Camera = class Camera {
'eyeX', 'eyeY', 'eyeZ',
'centerX', 'centerY', 'centerZ',
'upX', 'upY', 'upZ',
- 'cameraFOV', 'aspectRatio', 'cameraNear', 'cameraFar', 'cameraType'
+ 'cameraFOV', 'aspectRatio', 'cameraNear', 'cameraFar', 'cameraType',
+ 'yScale'
];
for (const keyName of keyNamesOfThePropToCopy) {
this[keyName] = cam[keyName];
@@ -2019,6 +2020,7 @@ p5.Camera = class Camera {
_cam.cameraMatrix = this.cameraMatrix.copy();
_cam.projMatrix = this.projMatrix.copy();
+ _cam.yScale = this.yScale;
return _cam;
}
diff --git a/src/webgl/p5.DataArray.js b/src/webgl/p5.DataArray.js
new file mode 100644
index 0000000000..9ab0c2eaf2
--- /dev/null
+++ b/src/webgl/p5.DataArray.js
@@ -0,0 +1,110 @@
+import p5 from '../core/main';
+
+/**
+ * An internal class to store data that will be sent to a p5.RenderBuffer.
+ * Those need to eventually go into a Float32Array, so this class provides a
+ * variable-length array container backed by a Float32Array so that it can be
+ * sent to the GPU without allocating a new array each frame.
+ *
+ * Like a C++ vector, its fixed-length Float32Array backing its contents will
+ * double in size when it goes over its capacity.
+ *
+ * @example
+ *
+ *
+ * // Initialize storage with a capacity of 4
+ * const storage = new DataArray(4);
+ * console.log(storage.data.length); // 4
+ * console.log(storage.length); // 0
+ * console.log(storage.dataArray()); // Empty Float32Array
+ *
+ * storage.push(1, 2, 3, 4, 5, 6);
+ * console.log(storage.data.length); // 8
+ * console.log(storage.length); // 6
+ * console.log(storage.dataArray()); // Float32Array{1, 2, 3, 4, 5, 6}
+ *
+ *
+ */
+p5.DataArray = class DataArray {
+ constructor(initialLength = 128) {
+ this.length = 0;
+ this.data = new Float32Array(initialLength);
+ this.initialLength = initialLength;
+ }
+
+ /**
+ * Returns a Float32Array window sized to the exact length of the data
+ */
+ dataArray() {
+ return this.subArray(0, this.length);
+ }
+
+ /**
+ * A "soft" clear, which keeps the underlying storage size the same, but
+ * empties the contents of its dataArray()
+ */
+ clear() {
+ this.length = 0;
+ }
+
+ /**
+ * Can be used to scale a DataArray back down to fit its contents.
+ */
+ rescale() {
+ if (this.length < this.data.length / 2) {
+ // Find the power of 2 size that fits the data
+ const targetLength = 1 << Math.ceil(Math.log2(this.length));
+ const newData = new Float32Array(targetLength);
+ newData.set(this.data.subarray(0, this.length), 0);
+ this.data = newData;
+ }
+ }
+
+ /**
+ * A full reset, which allocates a new underlying Float32Array at its initial
+ * length
+ */
+ reset() {
+ this.clear();
+ this.data = new Float32Array(this.initialLength);
+ }
+
+ /**
+ * Adds values to the DataArray, expanding its internal storage to
+ * accommodate the new items.
+ */
+ push(...values) {
+ this.ensureLength(this.length + values.length);
+ this.data.set(values, this.length);
+ this.length += values.length;
+ }
+
+ /**
+ * Returns a copy of the data from the index `from`, inclusive, to the index
+ * `to`, exclusive
+ */
+ slice(from, to) {
+ return this.data.slice(from, Math.min(to, this.length));
+ }
+
+ /**
+ * Returns a mutable Float32Array window from the index `from`, inclusive, to
+ * the index `to`, exclusive
+ */
+ subArray(from, to) {
+ return this.data.subarray(from, Math.min(to, this.length));
+ }
+
+ /**
+ * Expand capacity of the internal storage until it can fit a target size
+ */
+ ensureLength(target) {
+ while (this.data.length < target) {
+ const newData = new Float32Array(this.data.length * 2);
+ newData.set(this.data, 0);
+ this.data = newData;
+ }
+ }
+};
+
+export default p5.DataArray;
diff --git a/src/webgl/p5.Framebuffer.js b/src/webgl/p5.Framebuffer.js
index a4c7aaabda..bbf1b8df23 100644
--- a/src/webgl/p5.Framebuffer.js
+++ b/src/webgl/p5.Framebuffer.js
@@ -110,6 +110,8 @@ class Framebuffer {
this.target = target;
this.target._renderer.framebuffers.add(this);
+ this._isClipApplied = false;
+
/**
* A Uint8ClampedArray
@@ -531,8 +533,8 @@ class Framebuffer {
this.target._renderer,
this.color,
{
- glMinFilter: filter,
- glMagFilter: filter
+ minFilter: filter,
+ magFilter: filter
}
);
this.target._renderer.textures.set(this.color, this.colorP5Texture);
@@ -911,9 +913,7 @@ class Framebuffer {
_beforeBegin() {
const gl = this.gl;
gl.bindFramebuffer(gl.FRAMEBUFFER, this._framebufferToBind());
- gl.viewport(
- 0,
- 0,
+ this.target._renderer.viewport(
this.width * this.density,
this.height * this.density
);
@@ -962,18 +962,22 @@ class Framebuffer {
*/
end() {
const gl = this.gl;
+ this.target.pop();
const fbo = this.target._renderer.activeFramebuffers.pop();
if (fbo !== this) {
throw new Error("It looks like you've called end() while another Framebuffer is active.");
}
this._beforeEnd();
- this.target.pop();
if (this.prevFramebuffer) {
this.prevFramebuffer._beforeBegin();
} else {
gl.bindFramebuffer(gl.FRAMEBUFFER, null);
- gl.viewport(...this.target._renderer._viewport);
+ this.target._renderer.viewport(
+ this.target._renderer._origViewport.width,
+ this.target._renderer._origViewport.height
+ );
}
+ this.target._renderer._applyStencilTestIfClipping();
}
/**
diff --git a/src/webgl/p5.Geometry.js b/src/webgl/p5.Geometry.js
index ef63ea5c96..768a4b2cf7 100644
--- a/src/webgl/p5.Geometry.js
+++ b/src/webgl/p5.Geometry.js
@@ -17,28 +17,28 @@ import p5 from '../core/main';
* @param {Integer} [detailY] number of vertices along the y-axis.
* @param {function} [callback] function to call upon object instantiation.
*/
-p5.Geometry = class {
+p5.Geometry = class Geometry {
constructor(detailX, detailY, callback){
//an array containing every vertex
//@type [p5.Vector]
this.vertices = [];
//an array containing every vertex for stroke drawing
- this.lineVertices = [];
+ this.lineVertices = new p5.DataArray();
// The tangents going into or out of a vertex on a line. Along a straight
// line segment, both should be equal. At an endpoint, one or the other
// will not exist and will be all 0. In joins between line segments, they
// may be different, as they will be the tangents on either side of the join.
- this.lineTangentsIn = [];
- this.lineTangentsOut = [];
+ this.lineTangentsIn = new p5.DataArray();
+ this.lineTangentsOut = new p5.DataArray();
// When drawing lines with thickness, entries in this buffer represent which
// side of the centerline the vertex will be placed. The sign of the number
// will represent the side of the centerline, and the absolute value will be
// used as an enum to determine which part of the cap or join each vertex
// represents. See the doc comments for _addCap and _addJoin for diagrams.
- this.lineSides = [];
+ this.lineSides = new p5.DataArray();
//an array containing 1 normal per vertex
//@type [p5.Vector]
@@ -60,7 +60,7 @@ p5.Geometry = class {
// One color per line vertex, generated automatically based on
// vertexStrokeColors in _edgesToVertices()
- this.lineVertexColors = [];
+ this.lineVertexColors = new p5.DataArray();
this.detailX = detailX !== undefined ? detailX : 1;
this.detailY = detailY !== undefined ? detailY : 1;
this.dirtyFlags = {};
@@ -72,16 +72,16 @@ p5.Geometry = class {
}
reset() {
- this.lineVertices.length = 0;
- this.lineTangentsIn.length = 0;
- this.lineTangentsOut.length = 0;
- this.lineSides.length = 0;
+ this.lineVertices.clear();
+ this.lineTangentsIn.clear();
+ this.lineTangentsOut.clear();
+ this.lineSides.clear();
this.vertices.length = 0;
this.edges.length = 0;
this.vertexColors.length = 0;
this.vertexStrokeColors.length = 0;
- this.lineVertexColors.length = 0;
+ this.lineVertexColors.clear();
this.vertexNormals.length = 0;
this.uvs.length = 0;
@@ -261,10 +261,10 @@ p5.Geometry = class {
* @chainable
*/
_edgesToVertices() {
- this.lineVertices.length = 0;
- this.lineTangentsIn.length = 0;
- this.lineTangentsOut.length = 0;
- this.lineSides.length = 0;
+ this.lineVertices.clear();
+ this.lineTangentsIn.clear();
+ this.lineTangentsOut.clear();
+ this.lineSides.clear();
const potentialCaps = new Map();
const connected = new Set();
@@ -409,18 +409,20 @@ p5.Geometry = class {
const a = begin.array();
const b = end.array();
const dirArr = dir.array();
- this.lineSides.push(1, -1, 1, 1, -1, -1);
+ this.lineSides.push(1, 1, -1, 1, -1, -1);
for (const tangents of [this.lineTangentsIn, this.lineTangentsOut]) {
- tangents.push(dirArr, dirArr, dirArr, dirArr, dirArr, dirArr);
+ for (let i = 0; i < 6; i++) {
+ tangents.push(...dirArr);
+ }
}
- this.lineVertices.push(a, a, b, b, a, b);
+ this.lineVertices.push(...a, ...b, ...a, ...b, ...b, ...a);
this.lineVertexColors.push(
- fromColor,
- fromColor,
- toColor,
- toColor,
- fromColor,
- toColor
+ ...fromColor,
+ ...toColor,
+ ...fromColor,
+ ...toColor,
+ ...toColor,
+ ...fromColor
);
return this;
}
@@ -446,12 +448,12 @@ p5.Geometry = class {
const tanInArray = tangent.array();
const tanOutArray = [0, 0, 0];
for (let i = 0; i < 6; i++) {
- this.lineVertices.push(ptArray);
- this.lineTangentsIn.push(tanInArray);
- this.lineTangentsOut.push(tanOutArray);
- this.lineVertexColors.push(color);
+ this.lineVertices.push(...ptArray);
+ this.lineTangentsIn.push(...tanInArray);
+ this.lineTangentsOut.push(...tanOutArray);
+ this.lineVertexColors.push(...color);
}
- this.lineSides.push(-1, -2, 2, 2, 1, -1);
+ this.lineSides.push(-1, 2, -2, 1, 2, -1);
return this;
}
@@ -488,14 +490,13 @@ p5.Geometry = class {
const tanInArray = fromTangent.array();
const tanOutArray = toTangent.array();
for (let i = 0; i < 12; i++) {
- this.lineVertices.push(ptArray);
- this.lineTangentsIn.push(tanInArray);
- this.lineTangentsOut.push(tanOutArray);
- this.lineVertexColors.push(color);
- }
- for (const side of [-1, 1]) {
- this.lineSides.push(side, 2 * side, 3 * side, side, 3 * side, 0);
+ this.lineVertices.push(...ptArray);
+ this.lineTangentsIn.push(...tanInArray);
+ this.lineTangentsOut.push(...tanOutArray);
+ this.lineVertexColors.push(...color);
}
+ this.lineSides.push(-1, -3, -2, -1, 0, -3);
+ this.lineSides.push(3, 1, 2, 3, 0, 1);
return this;
}
diff --git a/src/webgl/p5.RenderBuffer.js b/src/webgl/p5.RenderBuffer.js
index 246bc8fa29..79851e485f 100644
--- a/src/webgl/p5.RenderBuffer.js
+++ b/src/webgl/p5.RenderBuffer.js
@@ -61,11 +61,11 @@ p5.RenderBuffer = class {
shader.enableAttrib(attr, this.size);
} else {
const loc = attr.location;
- if (loc === -1 || !this._renderer.registerEnabled[loc]) { return; }
+ if (loc === -1 || !this._renderer.registerEnabled.has(loc)) { return; }
// Disable register corresponding to unused attribute
gl.disableVertexAttribArray(loc);
// Record register availability
- this._renderer.registerEnabled[loc] = false;
+ this._renderer.registerEnabled.delete(loc);
}
}
};
diff --git a/src/webgl/p5.RendererGL.Immediate.js b/src/webgl/p5.RendererGL.Immediate.js
index a3d771e549..2409dae3d6 100644
--- a/src/webgl/p5.RendererGL.Immediate.js
+++ b/src/webgl/p5.RendererGL.Immediate.js
@@ -128,14 +128,19 @@ p5.RendererGL.prototype.vertex = function(x, y) {
lineVertexColor[3]
);
- if (this.textureMode === constants.IMAGE) {
+ if (this.textureMode === constants.IMAGE && !this.isProcessingVertices) {
if (this._tex !== null) {
if (this._tex.width > 0 && this._tex.height > 0) {
u /= this._tex.width;
v /= this._tex.height;
}
} else if (
- !this.isProcessingVertices &&
+ this.userFillShader !== undefined ||
+ this.userStrokeShader !== undefined ||
+ this.userPointShader !== undefined
+ ) {
+ // Do nothing if user-defined shaders are present
+ } else if (
this._tex === null &&
arguments.length >= 4
) {
@@ -192,7 +197,8 @@ p5.RendererGL.prototype.endShape = function(
isBezier,
isQuadratic,
isContour,
- shapeKind
+ shapeKind,
+ count = 1
) {
if (this.immediateMode.shapeMode === constants.POINTS) {
this._drawPoints(
@@ -201,6 +207,15 @@ p5.RendererGL.prototype.endShape = function(
);
return this;
}
+ // When we are drawing a shape then the shape mode is TESS,
+ // but in case of triangle we can skip the breaking into small triangle
+ // this can optimize performance by skipping the step of breaking it into triangles
+ if (this.immediateMode.geometry.vertices.length === 3 &&
+ this.immediateMode.shapeMode === constants.TESS
+ ) {
+ this.immediateMode.shapeMode === constants.TRIANGLES;
+ }
+
this.isProcessingVertices = true;
this._processVertices(...arguments);
this.isProcessingVertices = false;
@@ -226,15 +241,15 @@ p5.RendererGL.prototype.endShape = function(
if (this._doFill) {
if (
!this.geometryBuilder &&
- this.immediateMode.geometry.vertices.length > 1
+ this.immediateMode.geometry.vertices.length >= 3
) {
- this._drawImmediateFill();
+ this._drawImmediateFill(count);
}
}
if (this._doStroke) {
if (
!this.geometryBuilder &&
- this.immediateMode.geometry.lineVertices.length > 1
+ this.immediateMode.geometry.lineVertices.length >= 1
) {
this._drawImmediateStroke();
}
@@ -447,12 +462,36 @@ p5.RendererGL.prototype._tesselateShape = function() {
this.immediateMode.geometry.edges.map(edge => edge.map(origIdx => {
if (!newIndex.has(origIdx)) {
const orig = originalVertices[origIdx];
- newIndex.set(origIdx, this.immediateMode.geometry.vertices.findIndex(
+ let newVertIndex = this.immediateMode.geometry.vertices.findIndex(
v =>
orig.x === v.x &&
orig.y === v.y &&
orig.z === v.z
- ));
+ );
+ if (newVertIndex === -1) {
+ // The tesselation process didn't output a vertex with the exact
+ // coordinate as before, potentially due to numerical issues. This
+ // doesn't happen often, but in this case, pick the closest point
+ let closestDist = Infinity;
+ let closestIndex = 0;
+ for (
+ let i = 0;
+ i < this.immediateMode.geometry.vertices.length;
+ i++
+ ) {
+ const vert = this.immediateMode.geometry.vertices[i];
+ const dX = orig.x - vert.x;
+ const dY = orig.y - vert.y;
+ const dZ = orig.z - vert.z;
+ const dist = dX*dX + dY*dY + dZ*dZ;
+ if (dist < closestDist) {
+ closestDist = dist;
+ closestIndex = i;
+ }
+ }
+ newVertIndex = closestIndex;
+ }
+ newIndex.set(origIdx, newVertIndex);
}
return newIndex.get(origIdx);
}));
@@ -465,7 +504,7 @@ p5.RendererGL.prototype._tesselateShape = function() {
* enabling all appropriate buffers, applying color blend, and drawing the fill geometry.
* @private
*/
-p5.RendererGL.prototype._drawImmediateFill = function() {
+p5.RendererGL.prototype._drawImmediateFill = function(count = 1) {
const gl = this.GL;
this._useVertexColor = (this.immediateMode.geometry.vertexColors.length > 0);
@@ -477,14 +516,30 @@ p5.RendererGL.prototype._drawImmediateFill = function() {
for (const buff of this.immediateMode.buffers.fill) {
buff._prepareBuffer(this.immediateMode.geometry, shader);
}
+ shader.disableRemainingAttributes();
this._applyColorBlend(this.curFillColor);
- gl.drawArrays(
- this.immediateMode.shapeMode,
- 0,
- this.immediateMode.geometry.vertices.length
- );
+ if (count === 1) {
+ gl.drawArrays(
+ this.immediateMode.shapeMode,
+ 0,
+ this.immediateMode.geometry.vertices.length
+ );
+ }
+ else {
+ try {
+ gl.drawArraysInstanced(
+ this.immediateMode.shapeMode,
+ 0,
+ this.immediateMode.geometry.vertices.length,
+ count
+ );
+ }
+ catch (e) {
+ console.log('🌸 p5.js says: Instancing is only supported in WebGL2 mode');
+ }
+ }
shader.unbindShader();
};
@@ -499,25 +554,19 @@ p5.RendererGL.prototype._drawImmediateStroke = function() {
this._useLineColor =
(this.immediateMode.geometry.vertexStrokeColors.length > 0);
- const faceCullingEnabled = gl.isEnabled(gl.CULL_FACE);
- // Prevent strokes from getting removed by culling
- gl.disable(gl.CULL_FACE);
-
const shader = this._getImmediateStrokeShader();
this._setStrokeUniforms(shader);
for (const buff of this.immediateMode.buffers.stroke) {
buff._prepareBuffer(this.immediateMode.geometry, shader);
}
+ shader.disableRemainingAttributes();
this._applyColorBlend(this.curStrokeColor);
gl.drawArrays(
gl.TRIANGLES,
0,
- this.immediateMode.geometry.lineVertices.length
+ this.immediateMode.geometry.lineVertices.length / 3
);
- if (faceCullingEnabled) {
- gl.enable(gl.CULL_FACE);
- }
shader.unbindShader();
};
diff --git a/src/webgl/p5.RendererGL.Retained.js b/src/webgl/p5.RendererGL.Retained.js
index 308b7310ce..d278d51428 100644
--- a/src/webgl/p5.RendererGL.Retained.js
+++ b/src/webgl/p5.RendererGL.Retained.js
@@ -5,8 +5,6 @@ import './p5.RendererGL';
import './p5.RenderBuffer';
import * as constants from '../core/constants';
-let hashCount = 0;
-
/**
* @param {p5.Geometry} geometry The model whose resources will be freed
*/
@@ -30,11 +28,9 @@ p5.RendererGL.prototype._initBufferDefaults = function(gId) {
this._freeBuffers(gId);
//@TODO remove this limit on hashes in retainedMode.geometry
- hashCount++;
- if (hashCount > 1000) {
+ if (Object.keys(this.retainedMode.geometry).length > 1000) {
const key = Object.keys(this.retainedMode.geometry)[0];
- delete this.retainedMode.geometry[key];
- hashCount--;
+ this._freeBuffers(key);
}
//create a new entry in our retainedMode.geometry
@@ -48,7 +44,6 @@ p5.RendererGL.prototype._freeBuffers = function(gId) {
}
delete this.retainedMode.geometry[gId];
- hashCount--;
const gl = this.GL;
if (buffers.indexBuffer) {
@@ -115,7 +110,9 @@ p5.RendererGL.prototype.createBuffers = function(gId, model) {
buffers.vertexCount = model.vertices ? model.vertices.length : 0;
}
- buffers.lineVertexCount = model.lineVertices ? model.lineVertices.length : 0;
+ buffers.lineVertexCount = model.lineVertices
+ ? model.lineVertices.length / 3
+ : 0;
return buffers;
};
@@ -130,13 +127,18 @@ p5.RendererGL.prototype.drawBuffers = function(gId) {
const gl = this.GL;
const geometry = this.retainedMode.geometry[gId];
- if (!this.geometryBuilder && this._doFill) {
+ if (
+ !this.geometryBuilder &&
+ this._doFill &&
+ this.retainedMode.geometry[gId].vertexCount > 0
+ ) {
this._useVertexColor = (geometry.model.vertexColors.length > 0);
const fillShader = this._getRetainedFillShader();
this._setFillUniforms(fillShader);
for (const buff of this.retainedMode.buffers.fill) {
buff._prepareBuffer(geometry, fillShader);
}
+ fillShader.disableRemainingAttributes();
if (geometry.indexBuffer) {
//vertex index buffer
this._bindBuffer(geometry.indexBuffer, gl.ELEMENT_ARRAY_BUFFER);
@@ -148,19 +150,14 @@ p5.RendererGL.prototype.drawBuffers = function(gId) {
if (!this.geometryBuilder && this._doStroke && geometry.lineVertexCount > 0) {
this._useLineColor = (geometry.model.vertexStrokeColors.length > 0);
- const faceCullingEnabled = gl.isEnabled(gl.CULL_FACE);
- // Prevent strokes from getting removed by culling
- gl.disable(gl.CULL_FACE);
const strokeShader = this._getRetainedStrokeShader();
this._setStrokeUniforms(strokeShader);
for (const buff of this.retainedMode.buffers.stroke) {
buff._prepareBuffer(geometry, strokeShader);
}
+ strokeShader.disableRemainingAttributes();
this._applyColorBlend(this.curStrokeColor);
this._drawArrays(gl.TRIANGLES, gId);
- if (faceCullingEnabled) {
- gl.enable(gl.CULL_FACE);
- }
strokeShader.unbindShader();
}
diff --git a/src/webgl/p5.RendererGL.js b/src/webgl/p5.RendererGL.js
index 35a809c33f..3542584674 100644
--- a/src/webgl/p5.RendererGL.js
+++ b/src/webgl/p5.RendererGL.js
@@ -79,6 +79,26 @@ const defaultShaders = {
pointFrag: readFileSync(join(__dirname, '/shaders/point.frag'), 'utf-8')
};
+const filterShaderFrags = {
+ [constants.GRAY]:
+ readFileSync(join(__dirname, '/shaders/filters/gray.frag'), 'utf-8'),
+ [constants.ERODE]:
+ readFileSync(join(__dirname, '/shaders/filters/erode.frag'), 'utf-8'),
+ [constants.DILATE]:
+ readFileSync(join(__dirname, '/shaders/filters/dilate.frag'), 'utf-8'),
+ [constants.BLUR]:
+ readFileSync(join(__dirname, '/shaders/filters/blur.frag'), 'utf-8'),
+ [constants.POSTERIZE]:
+ readFileSync(join(__dirname, '/shaders/filters/posterize.frag'), 'utf-8'),
+ [constants.OPAQUE]:
+ readFileSync(join(__dirname, '/shaders/filters/opaque.frag'), 'utf-8'),
+ [constants.INVERT]:
+ readFileSync(join(__dirname, '/shaders/filters/invert.frag'), 'utf-8'),
+ [constants.THRESHOLD]:
+ readFileSync(join(__dirname, '/shaders/filters/threshold.frag'), 'utf-8')
+};
+const filterShaderVert = readFileSync(join(__dirname, '/shaders/filters/default.vert'), 'utf-8');
+
/**
* @module Rendering
* @submodule Rendering
@@ -423,7 +443,9 @@ p5.RendererGL = class RendererGL extends p5.Renderer {
this._isErasing = false;
// clipping
- this._clipDepth = null;
+ this._clipDepths = [];
+ this._isClipApplied = false;
+ this._stencilTestOn = false;
// lights
this._enableLighting = false;
@@ -473,7 +495,7 @@ p5.RendererGL = class RendererGL extends p5.Renderer {
this._useLineColor = false;
this._useVertexColor = false;
- this.registerEnabled = [];
+ this.registerEnabled = new Set();
this._tint = [255, 255, 255, 255];
@@ -525,10 +547,10 @@ p5.RendererGL = class RendererGL extends p5.Renderer {
geometry: {},
buffers: {
stroke: [
- new p5.RenderBuffer(4, 'lineVertexColors', 'lineColorBuffer', 'aVertexColor', this, this._flatten),
- new p5.RenderBuffer(3, 'lineVertices', 'lineVerticesBuffer', 'aPosition', this, this._flatten),
- new p5.RenderBuffer(3, 'lineTangentsIn', 'lineTangentsInBuffer', 'aTangentIn', this, this._flatten),
- new p5.RenderBuffer(3, 'lineTangentsOut', 'lineTangentsOutBuffer', 'aTangentOut', this, this._flatten),
+ new p5.RenderBuffer(4, 'lineVertexColors', 'lineColorBuffer', 'aVertexColor', this),
+ new p5.RenderBuffer(3, 'lineVertices', 'lineVerticesBuffer', 'aPosition', this),
+ new p5.RenderBuffer(3, 'lineTangentsIn', 'lineTangentsInBuffer', 'aTangentIn', this),
+ new p5.RenderBuffer(3, 'lineTangentsOut', 'lineTangentsOutBuffer', 'aTangentOut', this),
new p5.RenderBuffer(1, 'lineSides', 'lineSidesBuffer', 'aSide', this)
],
fill: [
@@ -564,10 +586,10 @@ p5.RendererGL = class RendererGL extends p5.Renderer {
new p5.RenderBuffer(2, 'uvs', 'uvBuffer', 'aTexCoord', this, this._flatten)
],
stroke: [
- new p5.RenderBuffer(4, 'lineVertexColors', 'lineColorBuffer', 'aVertexColor', this, this._flatten),
- new p5.RenderBuffer(3, 'lineVertices', 'lineVerticesBuffer', 'aPosition', this, this._flatten),
- new p5.RenderBuffer(3, 'lineTangentsIn', 'lineTangentsInBuffer', 'aTangentIn', this, this._flatten),
- new p5.RenderBuffer(3, 'lineTangentsOut', 'lineTangentsOutBuffer', 'aTangentOut', this, this._flatten),
+ new p5.RenderBuffer(4, 'lineVertexColors', 'lineColorBuffer', 'aVertexColor', this),
+ new p5.RenderBuffer(3, 'lineVertices', 'lineVerticesBuffer', 'aPosition', this),
+ new p5.RenderBuffer(3, 'lineTangentsIn', 'lineTangentsInBuffer', 'aTangentIn', this),
+ new p5.RenderBuffer(3, 'lineTangentsOut', 'lineTangentsOutBuffer', 'aTangentOut', this),
new p5.RenderBuffer(1, 'lineSides', 'lineSidesBuffer', 'aSide', this)
],
point: this.GL.createBuffer()
@@ -590,6 +612,8 @@ p5.RendererGL = class RendererGL extends p5.Renderer {
// for post processing step
this.filterShader = undefined;
this.filterGraphicsLayer = undefined;
+ this.filterGraphicsLayerTemp = undefined;
+ this.defaultFilterShaders = {};
this.textureMode = constants.IMAGE;
// default wrap settings
@@ -951,14 +975,16 @@ p5.RendererGL = class RendererGL extends p5.Renderer {
this.curStrokeJoin = join;
}
- filter(args) {
- // Couldn't create graphics in RendererGL constructor
- // (led to infinite loop)
- // so it's just created here once on the initial filter call.
+ getFilterGraphicsLayer() {
+ // Lazily initialize the filter graphics layer. We only do this on demand
+ // because the graphics layer itself has a p5.RendererGL, which would then
+ // try to make its own filter layer, infinitely looping.
if (!this.filterGraphicsLayer) {
// the real _pInst is buried when this is a secondary p5.Graphics
+
const pInst =
this._pInst instanceof p5.Graphics ? this._pInst._pInst : this._pInst;
+
// create secondary layer
this.filterGraphicsLayer =
new p5.Graphics(
@@ -967,42 +993,143 @@ p5.RendererGL = class RendererGL extends p5.Renderer {
constants.WEBGL,
pInst
);
+ // geometries/borders on this layer should always be invisible
+ this.filterGraphicsLayer.noStroke();
+ }
+ if (
+ this.filterGraphicsLayer.width !== this.width ||
+ this.filterGraphicsLayer.height !== this.height
+ ) {
+ // Resize the graphics layer
+ this.filterGraphicsLayer.resizeCanvas(this.width, this.height);
+ }
+ if (
+ this.filterGraphicsLayer.pixelDensity() !== this._pInst.pixelDensity()
+ ) {
+ this.filterGraphicsLayer.pixelDensity(this._pInst.pixelDensity());
}
- let pg = this.filterGraphicsLayer;
+ return this.filterGraphicsLayer;
+ }
- if (typeof args[0] === 'string') {
- // TODO, handle filter constants:
- // this.filterShader = map(args[0], {GRAYSCALE: grayscaleShader, ...})
- // filterOperationParameter = undefined or args[1]
- p5._friendlyError('webgl filter implementation in progress');
- return;
+ getFilterGraphicsLayerTemp() {
+ // two-pass blur filter needs another graphics layer
+ if (!this.filterGraphicsLayerTemp) {
+ const pInst = this._pInst instanceof p5.Graphics ?
+ this._pInst._pInst : this._pInst;
+ // create secondary layer
+ this.filterGraphicsLayerTemp =
+ new p5.Graphics(
+ this.width,
+ this.height,
+ constants.WEBGL,
+ pInst
+ );
+ this.filterGraphicsLayerTemp.noStroke();
+ }
+ if (
+ this.filterGraphicsLayerTemp.width !== this.width ||
+ this.filterGraphicsLayerTemp.height !== this.height
+ ) {
+ // Resize the graphics layer
+ this.filterGraphicsLayerTemp.resizeCanvas(this.width, this.height);
+ }
+ if (
+ this.filterGraphicsLayerTemp.pixelDensity() !== this._pInst.pixelDensity()
+ ) {
+ this.filterGraphicsLayerTemp.pixelDensity(this._pInst.pixelDensity());
}
- let userShader = args[0];
+ return this.filterGraphicsLayerTemp;
+ }
- // Copy the user shader once on the initial filter call,
- // since it has to be bound to pg and not main
- let isSameUserShader = (
- this.filterShader !== undefined &&
- userShader._vertSrc === this.filterShader._vertSrc &&
- userShader._fragSrc === this.filterShader._fragSrc
- );
- if (!isSameUserShader) {
- this.filterShader =
- new p5.Shader(pg._renderer, userShader._vertSrc, userShader._fragSrc);
- this.filterShader.parentShader = userShader;
+ filter(...args) {
+ let pg = this.getFilterGraphicsLayer();
+
+ // use internal shader for filter constants BLUR, INVERT, etc
+ let filterParameter = undefined;
+ let operation = undefined;
+ if (typeof args[0] === 'string') {
+ operation = args[0];
+ let defaults = {
+ [constants.BLUR]: 3,
+ [constants.POSTERIZE]: 4,
+ [constants.THRESHOLD]: 0.5
+ };
+ let useDefaultParam = operation in defaults && args[1] === undefined;
+ filterParameter = useDefaultParam ? defaults[operation] : args[1];
+
+ // Create and store shader for constants once on initial filter call.
+ // Need to store multiple in case user calls different filters,
+ // eg. filter(BLUR) then filter(GRAY)
+ if ( !(operation in this.defaultFilterShaders) ) {
+ this.defaultFilterShaders[operation] = new p5.Shader(
+ pg._renderer,
+ filterShaderVert,
+ filterShaderFrags[operation]
+ );
+ }
+ this.filterShader = this.defaultFilterShaders[operation];
+
+ }
+ // use custom user-supplied shader
+ else {
+ this.filterShader = args[0];
}
- // apply shader to pg
- pg.shader(this.filterShader);
- this.filterShader.setUniform('tex0', this);
- pg.rect(0,0,this.width,this.height);
+ pg.clear(); // prevent undesirable feedback effects accumulating secretly
+
+ let pd = this._pInst.pixelDensity();
+ let texelSize = [1 / (this.width * pd), 1 / (this.height * pd)];
+
+ // apply blur shader with multiple passes
+ if (operation === constants.BLUR) {
+
+ const tmp = this.getFilterGraphicsLayerTemp();
+ tmp.clear(); // prevent feedback effects here too
+
+ // setup
+ this._pInst.push();
+ this._pInst.noStroke();
+
+ // draw main to temp buffer
+ tmp.image(this, -this.width/2, -this.height/2);
+
+ pg.shader(this.filterShader);
+ this.filterShader.setUniform('texelSize', texelSize);
+ this.filterShader.setUniform('canvasSize', [this.width, this.height]);
+ this.filterShader.setUniform('radius', Math.max(1, filterParameter));
+ // horiz pass
+ this.filterShader.setUniform('direction', [1, 0]);
+ this.filterShader.setUniform('tex0', tmp);
+ pg.rect(-this.width/2, -this.height/2, this.width, this.height);
+
+ // read back to temp buffer
+ tmp.image(pg, -this.width/2, -this.height/2);
+
+ // vert pass
+ this.filterShader.setUniform('direction', [0, 1]);
+ this.filterShader.setUniform('tex0', tmp);
+ pg.rect(-this.width/2, -this.height/2, this.width, this.height);
+
+ this._pInst.pop();
+ }
+ // every other non-blur shader uses single pass
+ else {
+ pg.shader(this.filterShader);
+ this.filterShader.setUniform('tex0', this);
+ this.filterShader.setUniform('texelSize', texelSize);
+ this.filterShader.setUniform('canvasSize', [this.width, this.height]);
+ // filterParameter uniform only used for POSTERIZE, and THRESHOLD
+ // but shouldn't hurt to always set
+ this.filterShader.setUniform('filterParameter', filterParameter);
+ pg.rect(-this.width/2, -this.height/2, this.width, this.height);
+
+ }
// draw pg contents onto main renderer
this._pInst.push();
- this._pInst.noStroke(); // don't draw triangles for plane() geometry
- this._pInst.scale(1, -1); // vertically flip output
- this._pInst.texture(pg);
- this._pInst.plane(this.width, this.height);
+ this._pInst.noStroke();
+ this._pInst.image(pg, -this.width/2, -this.height/2,
+ this.width, this.height);
this._pInst.pop();
}
@@ -1055,12 +1182,20 @@ p5.RendererGL = class RendererGL extends p5.Renderer {
}
}
+ drawTarget() {
+ return this.activeFramebuffers[this.activeFramebuffers.length - 1] || this;
+ }
+
beginClip(options = {}) {
super.beginClip(options);
+
+ this.drawTarget()._isClipApplied = true;
+
const gl = this.GL;
gl.clearStencil(0);
gl.clear(gl.STENCIL_BUFFER_BIT);
gl.enable(gl.STENCIL_TEST);
+ this._stencilTestOn = true;
gl.stencilFunc(
gl.ALWAYS, // the test
1, // reference value
@@ -1097,7 +1232,7 @@ p5.RendererGL = class RendererGL extends p5.Renderer {
// Mark the depth at which the clip has been applied so that we can clear it
// when we pop past this depth
- this._clipDepth = this._pushPopDepth;
+ this._clipDepths.push(this._pushPopDepth);
super.endClip();
}
@@ -1105,7 +1240,10 @@ p5.RendererGL = class RendererGL extends p5.Renderer {
_clearClip() {
this.GL.clearStencil(1);
this.GL.clear(this.GL.STENCIL_BUFFER_BIT);
- this._clipDepth = null;
+ if (this._clipDepths.length > 0) {
+ this._clipDepths.pop();
+ }
+ this.drawTarget()._isClipApplied = false;
}
/**
@@ -1250,6 +1388,11 @@ p5.RendererGL = class RendererGL extends p5.Renderer {
return this.retainedMode.geometry[gId] !== undefined;
}
+ viewport(w, h) {
+ this._viewport = [0, 0, w, h];
+ this.GL.viewport(0, 0, w, h);
+ }
+
/**
* [resize description]
* @private
@@ -1258,13 +1401,14 @@ p5.RendererGL = class RendererGL extends p5.Renderer {
*/
resize(w, h) {
p5.Renderer.prototype.resize.call(this, w, h);
- this.GL.viewport(
- 0,
- 0,
- this.GL.drawingBufferWidth,
- this.GL.drawingBufferHeight
+ this._origViewport = {
+ width: this.GL.drawingBufferWidth,
+ height: this.GL.drawingBufferHeight
+ };
+ this.viewport(
+ this._origViewport.width,
+ this._origViewport.height
);
- this._viewport = this.GL.getParameter(this.GL.VIEWPORT);
this._curCamera._resize();
@@ -1304,7 +1448,22 @@ p5.RendererGL = class RendererGL extends p5.Renderer {
const _r = args[0] || 0;
const _g = args[1] || 0;
const _b = args[2] || 0;
- const _a = args[3] || 0;
+ let _a = args[3] || 0;
+
+ const activeFramebuffer = this.activeFramebuffer();
+ if (
+ activeFramebuffer &&
+ activeFramebuffer.format === constants.UNSIGNED_BYTE &&
+ !activeFramebuffer.antialias &&
+ _a === 0
+ ) {
+ // Drivers on Intel Macs check for 0,0,0,0 exactly when drawing to a
+ // framebuffer and ignore the command if it's the only drawing command to
+ // the framebuffer. To work around it, we can set the alpha to a value so
+ // low that it still rounds down to 0, but that circumvents the buggy
+ // check in the driver.
+ _a = 1e-10;
+ }
this.GL.clearColor(_r * _a, _g * _a, _b * _a, _a);
this.GL.clearDepth(1);
@@ -1447,11 +1606,26 @@ p5.RendererGL = class RendererGL extends p5.Renderer {
return style;
}
pop(...args) {
- if (this._pushPopDepth === this._clipDepth) {
+ if (
+ this._clipDepths.length > 0 &&
+ this._pushPopDepth === this._clipDepths[this._clipDepths.length - 1]
+ ) {
this._clearClip();
- this.GL.disable(this.GL.STENCIL_TEST);
}
super.pop(...args);
+ this._applyStencilTestIfClipping();
+ }
+ _applyStencilTestIfClipping() {
+ const drawTarget = this.drawTarget();
+ if (drawTarget._isClipApplied !== this._stencilTestOn) {
+ if (drawTarget._isClipApplied) {
+ this.GL.enable(this.GL.STENCIL_TEST);
+ this._stencilTestOn = true;
+ } else {
+ this.GL.disable(this.GL.STENCIL_TEST);
+ this._stencilTestOn = false;
+ }
+ }
}
resetMatrix() {
this.uMVMatrix.set(
@@ -1823,7 +1997,12 @@ p5.RendererGL = class RendererGL extends p5.Renderer {
if (!target) target = this.GL.ARRAY_BUFFER;
this.GL.bindBuffer(target, buffer);
if (values !== undefined) {
- const data = new (type || Float32Array)(values);
+ let data = values;
+ if (values instanceof p5.DataArray) {
+ data = values.dataArray();
+ } else if (!(data instanceof (type || Float32Array))) {
+ data = new (type || Float32Array)(data);
+ }
this.GL.bufferData(target, data, usage || this.GL.STATIC_DRAW);
}
}
diff --git a/src/webgl/p5.Shader.js b/src/webgl/p5.Shader.js
index 33072e9616..587247cd1f 100644
--- a/src/webgl/p5.Shader.js
+++ b/src/webgl/p5.Shader.js
@@ -103,6 +103,42 @@ p5.Shader = class {
return this;
}
+ /**
+ * Shaders belong to the main canvas or a p5.Graphics. Once they are compiled,
+ * they can only be used in the context they were compiled on.
+ *
+ * Use this method to make a new copy of a shader that gets compiled on a
+ * different context.
+ *
+ * @method copyToContext
+ * @param {p5|p5.Graphics} context The graphic or instance to copy this shader to.
+ * Pass `window` if you need to copy to the main canvas.
+ * @returns {p5.Shader} A new shader on the target context.
+ */
+ copyToContext(context) {
+ const shader = new p5.Shader(
+ context._renderer,
+ this._vertSrc,
+ this._fragSrc
+ );
+ shader.ensureCompiledOnContext(context);
+ return shader;
+ }
+
+ /**
+ * @private
+ */
+ ensureCompiledOnContext(context) {
+ if (this._glProgram !== 0 && this._renderer !== context._renderer) {
+ throw new Error(
+ 'The shader being run is attached to a different context. Do you need to copy it to this context first with .copyToContext()?'
+ );
+ } else if (this._glProgram === 0) {
+ this._renderer = context._renderer;
+ this.init();
+ }
+ }
+
/**
* Queries the active attributes for this shader and loads
* their names and locations into the attributes array.
@@ -392,13 +428,6 @@ p5.Shader = class {
* canvas toggles between a circular gradient of orange and blue vertically. and a circular gradient of red and green moving horizontally when mouse is clicked/pressed.
*/
setUniform(uniformName, data) {
- // detect when to set uniforms on duplicate filter shader copy
- let other = this._renderer.filterShader;
- if (other !== undefined && other.parentShader === this) {
- other.setUniform(uniformName, data);
- return;
- }
-
const uniform = this.uniforms[uniformName];
if (!uniform) {
return;
@@ -582,10 +611,10 @@ p5.Shader = class {
if (loc !== -1) {
const gl = this._renderer.GL;
// Enable register even if it is disabled
- if (!this._renderer.registerEnabled[loc]) {
+ if (!this._renderer.registerEnabled.has(loc)) {
gl.enableVertexAttribArray(loc);
// Record register availability
- this._renderer.registerEnabled[loc] = true;
+ this._renderer.registerEnabled.add(loc);
}
this._renderer.GL.vertexAttribPointer(
loc,
@@ -599,6 +628,26 @@ p5.Shader = class {
}
return this;
}
+
+ /**
+ * Once all buffers have been bound, this checks to see if there are any
+ * remaining active attributes, likely left over from previous renders,
+ * and disables them so that they don't affect rendering.
+ * @method disableRemainingAttributes
+ * @private
+ */
+ disableRemainingAttributes() {
+ for (const location of this._renderer.registerEnabled.values()) {
+ if (
+ !Object.keys(this.attributes).some(
+ key => this.attributes[key].location === location
+ )
+ ) {
+ this._renderer.GL.disableVertexAttribArray(location);
+ this._renderer.registerEnabled.delete(location);
+ }
+ }
+ }
};
export default p5.Shader;
diff --git a/src/webgl/shaders/filters/blur.frag b/src/webgl/shaders/filters/blur.frag
new file mode 100644
index 0000000000..2823043b1f
--- /dev/null
+++ b/src/webgl/shaders/filters/blur.frag
@@ -0,0 +1,60 @@
+precision highp float;
+
+// Two-pass blur filter, unweighted kernel.
+// See also a similar blur at Adam Ferriss' repo of shader examples:
+// https://github.com/aferriss/p5jsShaderExamples/blob/gh-pages/4_image-effects/4-9_single-pass-blur/effect.frag
+
+
+uniform sampler2D tex0;
+varying vec2 vTexCoord;
+uniform vec2 direction;
+uniform vec2 canvasSize;
+uniform float radius;
+
+float random(vec2 p) {
+ vec3 p3 = fract(vec3(p.xyx) * .1031);
+ p3 += dot(p3, p3.yzx + 33.33);
+ return fract((p3.x + p3.y) * p3.z);
+}
+
+// This isn't a real Gaussian weight, it's a quadratic weight. It's what the
+// CPU mode's blur uses though, so we also use it here to match.
+float quadWeight(float x, float e) {
+ return pow(e-abs(x), 2.);
+}
+
+void main(){
+ vec2 uv = vTexCoord;
+
+ // A reasonable maximum number of samples
+ const float maxSamples = 64.0;
+
+ float numSamples = floor(7. * radius);
+ if (fract(numSamples / 2.) == 0.) {
+ numSamples++;
+ }
+ vec4 avg = vec4(0.0);
+ float total = 0.0;
+
+ // Calculate the spacing to avoid skewing if numSamples > maxSamples
+ float spacing = 1.0;
+ if (numSamples > maxSamples) {
+ spacing = numSamples / maxSamples;
+ numSamples = maxSamples;
+ }
+
+ float randomOffset = (spacing - 1.0) * mix(-0.5, 0.5, random(gl_FragCoord.xy));
+ for (float i = 0.0; i < maxSamples; i++) {
+ if (i >= numSamples) break;
+
+ float sample = i * spacing - (numSamples - 1.0) * 0.5 * spacing + randomOffset;
+ vec2 sampleCoord = uv + vec2(sample, sample) / canvasSize * direction;
+ float weight = quadWeight(sample, (numSamples - 1.0) * 0.5 * spacing);
+
+ avg += weight * texture2D(tex0, sampleCoord);
+ total += weight;
+ }
+
+ avg /= total;
+ gl_FragColor = avg;
+}
diff --git a/src/webgl/shaders/filters/default.vert b/src/webgl/shaders/filters/default.vert
new file mode 100644
index 0000000000..ee73804cec
--- /dev/null
+++ b/src/webgl/shaders/filters/default.vert
@@ -0,0 +1,18 @@
+uniform mat4 uModelViewMatrix;
+uniform mat4 uProjectionMatrix;
+
+attribute vec3 aPosition;
+// texcoords only come from p5 to vertex shader
+// so pass texcoords on to the fragment shader in a varying variable
+attribute vec2 aTexCoord;
+varying vec2 vTexCoord;
+
+void main() {
+ // transferring texcoords for the frag shader
+ vTexCoord = aTexCoord;
+
+ // copy position with a fourth coordinate for projection (1.0 is normal)
+ vec4 positionVec4 = vec4(aPosition, 1.0);
+
+ gl_Position = uProjectionMatrix * uModelViewMatrix * positionVec4;
+}
diff --git a/src/webgl/shaders/filters/dilate.frag b/src/webgl/shaders/filters/dilate.frag
new file mode 100644
index 0000000000..3209c4a7ef
--- /dev/null
+++ b/src/webgl/shaders/filters/dilate.frag
@@ -0,0 +1,39 @@
+// Increase the bright areas in an image
+
+precision highp float;
+
+varying vec2 vTexCoord;
+
+uniform sampler2D tex0;
+uniform vec2 texelSize;
+
+float luma(vec3 color) {
+ // weighted grayscale with luminance values
+ // weights 77, 151, 28 taken from src/image/filters.js
+ return dot(color, vec3(0.300781, 0.589844, 0.109375));
+}
+
+void main() {
+ vec4 color = texture2D(tex0, vTexCoord);
+ float lum = luma(color.rgb);
+
+ // set current color as the brightest neighbor color
+
+ vec4 neighbors[4];
+ neighbors[0] = texture2D(tex0, vTexCoord + vec2( texelSize.x, 0.0));
+ neighbors[1] = texture2D(tex0, vTexCoord + vec2(-texelSize.x, 0.0));
+ neighbors[2] = texture2D(tex0, vTexCoord + vec2(0.0, texelSize.y));
+ neighbors[3] = texture2D(tex0, vTexCoord + vec2(0.0, -texelSize.y));
+
+ for (int i = 0; i < 4; i++) {
+ vec4 neighborColor = neighbors[i];
+ float neighborLum = luma(neighborColor.rgb);
+
+ if (neighborLum > lum) {
+ color = neighborColor;
+ lum = neighborLum;
+ }
+ }
+
+ gl_FragColor = color;
+}
diff --git a/src/webgl/shaders/filters/erode.frag b/src/webgl/shaders/filters/erode.frag
new file mode 100644
index 0000000000..6be0e78525
--- /dev/null
+++ b/src/webgl/shaders/filters/erode.frag
@@ -0,0 +1,39 @@
+// Reduces the bright areas in an image
+
+precision highp float;
+
+varying vec2 vTexCoord;
+
+uniform sampler2D tex0;
+uniform vec2 texelSize;
+
+float luma(vec3 color) {
+ // weighted grayscale with luminance values
+ // weights 77, 151, 28 taken from src/image/filters.js
+ return dot(color, vec3(0.300781, 0.589844, 0.109375));
+}
+
+void main() {
+ vec4 color = texture2D(tex0, vTexCoord);
+ float lum = luma(color.rgb);
+
+ // set current color as the darkest neighbor color
+
+ vec4 neighbors[4];
+ neighbors[0] = texture2D(tex0, vTexCoord + vec2( texelSize.x, 0.0));
+ neighbors[1] = texture2D(tex0, vTexCoord + vec2(-texelSize.x, 0.0));
+ neighbors[2] = texture2D(tex0, vTexCoord + vec2(0.0, texelSize.y));
+ neighbors[3] = texture2D(tex0, vTexCoord + vec2(0.0, -texelSize.y));
+
+ for (int i = 0; i < 4; i++) {
+ vec4 neighborColor = neighbors[i];
+ float neighborLum = luma(neighborColor.rgb);
+
+ if (neighborLum < lum) {
+ color = neighborColor;
+ lum = neighborLum;
+ }
+ }
+
+ gl_FragColor = color;
+}
diff --git a/src/webgl/shaders/filters/gray.frag b/src/webgl/shaders/filters/gray.frag
new file mode 100644
index 0000000000..815388c746
--- /dev/null
+++ b/src/webgl/shaders/filters/gray.frag
@@ -0,0 +1,16 @@
+precision highp float;
+
+varying vec2 vTexCoord;
+
+uniform sampler2D tex0;
+
+float luma(vec3 color) {
+ // weighted grayscale with luminance values
+ return dot(color, vec3(0.2126, 0.7152, 0.0722));
+}
+
+void main() {
+ vec4 tex = texture2D(tex0, vTexCoord);
+ float gray = luma(tex.rgb);
+ gl_FragColor = vec4(gray, gray, gray, tex.a);
+}
diff --git a/src/webgl/shaders/filters/invert.frag b/src/webgl/shaders/filters/invert.frag
new file mode 100644
index 0000000000..ef841372ef
--- /dev/null
+++ b/src/webgl/shaders/filters/invert.frag
@@ -0,0 +1,14 @@
+// Set each pixel to inverse value
+// Note that original INVERT does not change the opacity, so this follows suit
+
+precision highp float;
+
+varying vec2 vTexCoord;
+
+uniform sampler2D tex0;
+
+void main() {
+ vec4 color = texture2D(tex0, vTexCoord);
+ vec3 invertedColor = 1.0 - color.rgb;
+ gl_FragColor = vec4(invertedColor, color.a);
+}
diff --git a/src/webgl/shaders/filters/opaque.frag b/src/webgl/shaders/filters/opaque.frag
new file mode 100644
index 0000000000..566d57c66e
--- /dev/null
+++ b/src/webgl/shaders/filters/opaque.frag
@@ -0,0 +1,12 @@
+// Set alpha channel to entirely opaque
+
+precision highp float;
+
+varying vec2 vTexCoord;
+
+uniform sampler2D tex0;
+
+void main() {
+ vec4 color = texture2D(tex0, vTexCoord);
+ gl_FragColor = vec4(color.rgb, 1.0);
+}
diff --git a/src/webgl/shaders/filters/posterize.frag b/src/webgl/shaders/filters/posterize.frag
new file mode 100644
index 0000000000..2375b8a700
--- /dev/null
+++ b/src/webgl/shaders/filters/posterize.frag
@@ -0,0 +1,29 @@
+// Limit color space for a stylized cartoon / poster effect
+
+precision highp float;
+
+varying vec2 vTexCoord;
+
+uniform sampler2D tex0;
+uniform float filterParameter;
+
+vec3 quantize(vec3 color, float n) {
+ // restrict values to N options/bins
+ // and floor each channel to nearest value
+ //
+ // eg. when N = 5, values = 0.0, 0.25, 0.50, 0.75, 1.0
+ // then quantize (0.1, 0.7, 0.9) -> (0.0, 0.5, 1.0)
+
+ color = color * n;
+ color = floor(color);
+ color = color / (n - 1.0);
+ return color;
+}
+
+void main() {
+ vec4 color = texture2D(tex0, vTexCoord);
+
+ vec3 restrictedColor = quantize(color.rgb, filterParameter);
+
+ gl_FragColor = vec4(restrictedColor.rgb, color.a);
+}
diff --git a/src/webgl/shaders/filters/threshold.frag b/src/webgl/shaders/filters/threshold.frag
new file mode 100644
index 0000000000..597f7e3012
--- /dev/null
+++ b/src/webgl/shaders/filters/threshold.frag
@@ -0,0 +1,23 @@
+// Convert pixels to either white or black,
+// depending on if their luma is above or below filterParameter
+
+precision highp float;
+
+varying vec2 vTexCoord;
+
+uniform sampler2D tex0;
+uniform float filterParameter;
+
+float luma(vec3 color) {
+ // weighted grayscale with luminance values
+ return dot(color, vec3(0.2126, 0.7152, 0.0722));
+}
+
+void main() {
+ vec4 color = texture2D(tex0, vTexCoord);
+ float gray = luma(color.rgb);
+ // floor() used to match src/image/filters.js
+ float threshold = floor(filterParameter * 255.0) / 255.0;
+ float blackOrWhite = step(threshold, gray);
+ gl_FragColor = vec4(vec3(blackOrWhite), color.a);
+}
diff --git a/test/manual-test-examples/webgl/filter/index.html b/test/manual-test-examples/webgl/filter/index.html
index 656e6c469d..f91fd65214 100644
--- a/test/manual-test-examples/webgl/filter/index.html
+++ b/test/manual-test-examples/webgl/filter/index.html
@@ -7,11 +7,11 @@
