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.
+ *
+ *