From b1d117b7a1cc5a7f8e7c5b55263f367036c805ed Mon Sep 17 00:00:00 2001 From: Nick McIntyre Date: Thu, 14 Mar 2024 11:30:02 -0700 Subject: [PATCH 1/2] Update image references --- src/image/image.js | 242 ++++++++++++++++++++++++++++++++++----------- 1 file changed, 182 insertions(+), 60 deletions(-) diff --git a/src/image/image.js b/src/image/image.js index 3e82f6cbb4..2b4c028d75 100644 --- a/src/image/image.js +++ b/src/image/image.js @@ -13,10 +13,9 @@ import p5 from '../core/main'; import omggif from 'omggif'; /** - * Creates a new p5.Image object. The new image is - * transparent by default. + * Creates a new p5.Image object. * - * `createImage()` uses the `width` and `height` paremeters to set the new + * `createImage()` uses the `width` and `height` parameters 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 @@ -27,65 +26,122 @@ import omggif from 'omggif'; * updatePixels() method must be called * for updates to take effect. * + * Note: The new p5.Image object is transparent by + * default. + * * @method createImage * @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 x = 0; x < img.width; x += 1) { - * for (let y = 0; y < img.height; y += 1) { - * img.set(x, y, 0); + * function setup() { + * createCanvas(100, 100); + * + * background(200); + * + * // Create a p5.Image object. + * let img = createImage(66, 66); + * + * // Load the image's pixels into memory. + * img.loadPixels(); + * + * // Set all the image's pixels to black. + * 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.'); + * // Update the image's pixel values. + * img.updatePixels(); + * + * // Draw the image. + * image(img, 17, 17); + * + * describe('A black square drawn in the middle of a gray square.'); + * } * *
* *
* - * 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) { - * let a = map(x, 0, img.width, 0, 255); - * let c = color(0, a); - * img.set(x, y, c); + * function setup() { + * createCanvas(100, 100); + * + * background(200); + * + * // Create a p5.Image object. + * let img = createImage(66, 66); + * + * // Load the image's pixels into memory. + * img.loadPixels(); + * + * // Create a color gradient. + * for (let x = 0; x < img.width; x += 1) { + * for (let y = 0; y < img.height; y += 1) { + * // Calculate the transparency. + * let a = map(x, 0, img.width, 0, 255); + * + * // Create a p5.Color object. + * let c = color(0, a); + * + * // Set the pixel's color. + * img.set(x, y, c); + * } * } - * } - * img.updatePixels(); - * image(img, 17, 17); * - * describe('A square with a horizontal color gradient that transitions from gray to black.'); + * // Update the image's pixels. + * img.updatePixels(); + * + * // Display the image. + * image(img, 17, 17); + * + * describe('A square with a horizontal color gradient that transitions from gray to black.'); + * } * *
* *
* - * let img = createImage(66, 66); - * img.loadPixels(); - * let d = pixelDensity(); - * let halfImage = 4 * (d * img.width) * (d * img.height / 2); - * for (let i = 0; i < halfImage; 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); + * function setup() { + * createCanvas(100, 100); + * + * background(200); + * + * // Create a p5.Image object. + * let img = createImage(66, 66); + * + * // Load the pixels into memory. + * img.loadPixels(); + * // Get the current pixel density. + * let d = pixelDensity(); + * + * // Calculate the pixel that is halfway through the image's pixel array. + * let halfImage = 4 * (d * img.width) * (d * img.height / 2); * - * describe('A black square drawn in the middle of a gray square.'); + * // Set half of the image's pixels to black. + * for (let i = 0; i < halfImage; 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; + * } + * + * // Update the image's pixels. + * img.updatePixels(); + * + * // Display the image. + * image(img, 17, 17); + * + * describe('A black square drawn in the middle of a gray square.'); + * } * *
*/ @@ -95,8 +151,22 @@ p5.prototype.createImage = function(width, height) { }; /** - * Saves 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. + * + * By default, `saveCanvas()` saves the canvas as a PNG image called + * `untitled.png`. + * + * The first parameter, `filename`, is optional. It's a string that sets the + * file's name. If a file extension is included, as in + * `saveCanvas('drawing.png')`, then the image will be saved using that + * format. + * + * The second parameter, `extension`, is also optional. It sets the files format. + * Either `'png'` or `'jpg'` can be used. For example, `saveCanvas('drawing', 'jpg')` + * saves the canvas to a file called `drawing.jpg`. + * + * Note: The browser will either save the file immediately or prompt the user + * with a dialogue window. * * @method saveCanvas * @param {p5.Framebuffer|p5.Element|HTMLCanvasElement} selectedCanvas reference to a @@ -110,7 +180,11 @@ p5.prototype.createImage = function(width, height) { * function setup() { * createCanvas(100, 100); * background(255); + * + * // Save the canvas to 'untitled.png'. * saveCanvas(); + * + * describe('A white square.'); * } * * @@ -119,8 +193,13 @@ p5.prototype.createImage = function(width, height) { * * function setup() { * createCanvas(100, 100); + * * background(255); + * + * // Save the canvas to 'myCanvas.jpg'. * saveCanvas('myCanvas.jpg'); + * + * describe('A white square.'); * } * * @@ -129,8 +208,13 @@ p5.prototype.createImage = function(width, height) { * * function setup() { * createCanvas(100, 100); + * * background(255); + * + * // Save the canvas to 'myCanvas.jpg'. * saveCanvas('myCanvas', 'jpg'); + * + * describe('A white square.'); * } * * @@ -139,8 +223,13 @@ p5.prototype.createImage = function(width, height) { * * function setup() { * let cnv = createCanvas(100, 100); + * * background(255); + * + * // Save the canvas to 'untitled.png'. * saveCanvas(cnv); + * + * describe('A white square.'); * } * * @@ -149,8 +238,13 @@ p5.prototype.createImage = function(width, height) { * * function setup() { * let cnv = createCanvas(100, 100); + * * background(255); + * + * // Save the canvas to 'myCanvas.jpg'. * saveCanvas(cnv, 'myCanvas.jpg'); + * + * describe('A white square.'); * } * * @@ -159,8 +253,13 @@ p5.prototype.createImage = function(width, height) { * * function setup() { * let cnv = createCanvas(100, 100); + * * background(255); + * + * // Save the canvas to 'myCanvas.jpg'. * saveCanvas(cnv, 'myCanvas', 'jpg'); + * + * describe('A white square.'); * } * * @@ -457,20 +556,28 @@ p5.prototype.encodeAndDownloadGif = function(pImg, filename) { }; /** - * 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. + * Creates an array of frames from the canvas that can be saved as images. + * + * Each frame is stored as an object with its file type, file name, and image + * data as a string. For example, the first saved frame might + * have the following object: + * + * `{ ext: 'png', filenmame: 'frame0', imageData: 'data:image/octet-stream;base64, abc123' }`. * * 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'`. + * `frame0.png`, `frame1.png`, and so on. + * + * The second parameter, `extension`, sets the file type to either `'png'` or + * `'jpg'`. * * 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. + * 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. * * 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 @@ -478,6 +585,8 @@ p5.prototype.encodeAndDownloadGif = function(pImg, filename) { * of image data contains a sequence of objects with three properties for each * frame: `imageData`, `filename`, and `extension`. * + * Note: Frames are downloaded as individual image files by default. + * * @method saveFrames * @param {String} filename prefix of file name. * @param {String} extension file extension, either 'jpg' or 'png'. @@ -492,15 +601,20 @@ p5.prototype.encodeAndDownloadGif = function(pImg, filename) { * @example *
* + * function setup() { + * createCanvas(100, 100); + * + * describe('A square repeatedly changes color from blue to pink.'); + * } + * * 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.'); * } * + * // Save the frames when the user presses the 's' key. * function keyPressed() { * if (key === 's') { * saveFrames('frame', 'png', 1, 5); @@ -511,21 +625,29 @@ p5.prototype.encodeAndDownloadGif = function(pImg, filename) { * *
* + * function setup() { + * createCanvas(100, 100); + * + * describe('A square repeatedly changes color from blue to pink.'); + * } + * * 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.'); * } * + * // Print 5 frames when the user presses the mouse. * function mousePressed() { - * saveFrames('frame', 'png', 1, 5, data => { - * // Prints an array of objects containing raw image data, - * // filenames, and extensions. - * print(data); - * }); + * saveFrames('frame', 'png', 1, 5, printFrames); + * } + * + * // Prints an array of objects containing raw image data, filenames, and extensions. + * function printFrames(frames) { + * for (let frame of frames) { + * print(frame); + * } * } * *
From b7a6129854cb97427938e1f8a0eb4b515cffe5e1 Mon Sep 17 00:00:00 2001 From: Nick McIntyre Date: Fri, 15 Mar 2024 08:40:20 -0700 Subject: [PATCH 2/2] Revise saveFrames() reference --- src/image/image.js | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/src/image/image.js b/src/image/image.js index 2b4c028d75..9a1b44ad18 100644 --- a/src/image/image.js +++ b/src/image/image.js @@ -556,11 +556,11 @@ p5.prototype.encodeAndDownloadGif = function(pImg, filename) { }; /** - * Creates an array of frames from the canvas that can be saved as images. + * Captures a sequence of frames from the canvas that can be saved as images. * - * Each frame is stored as an object with its file type, file name, and image - * data as a string. For example, the first saved frame might - * have the following object: + * `saveFrames()` creates an array of frame objects. Each frame is stored as + * an object with its file type, file name, and image data as a string. For + * example, the first saved frame might have the following properties: * * `{ ext: 'png', filenmame: 'frame0', imageData: 'data:image/octet-stream;base64, abc123' }`. *