q5 2.18.1 → 2.19.0

package/README.md

@@ -2,14 +2,14 @@
 
 ## Visit [q5js.org](https://q5js.org)! 🌟
 
-[q5.js](https://q5js.org) is a spiritual successor to the [p5.js][] and [Processing Java][] graphics libraries.
+[q5.js](https://q5js.org) is a sequel to the [p5.js][] and [Processing Java][] graphics libraries.
 
 - performance optimized for interactive art 🚀
 - includes a brand new renderer powered by WebGPU 💪
 - up to 32x faster than p5.js 🏎️
-- HDR color support 🌈
+- beginner friendly API and documentation 📚
 - compatible with popular addons, including [p5.sound][] and [p5play][] 🎮
-- no dependencies, less than 100kb minified 📦
+- no dependencies, ~100kb minified 📦
 - LGPL licensed (just like p5.js) 🆓
 
 q5.js was designed to make creative coding fun and accessible for a new generation of artists, designers, educators, and beginners. 🤝

package/deno.json

@@ -1,6 +1,6 @@
 {
 	"name": "@q5/q5",
-	"version": "2.18.1",
+	"version": "2.19.0",
 	"license": "LGPL-3.0",
 	"description": "A sequel to p5.js that's optimized for interactive art",
 	"author": "quinton-ashley",

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "q5",
-	"version": "2.18.1",
+	"version": "2.19.0",
 	"description": "A sequel to p5.js that's optimized for interactive art",
 	"author": "quinton-ashley",
 	"contributors": [

package/q5.d.ts

@@ -293,18 +293,19 @@ function draw() {
 		/** ⭐️
 		 * Creates an instance of Q5.
 		 *
-		 * Running `new Q5()` enables the use of q5 functions and variables
-		 * anywhere in your code. You can also start Q5 in global mode by 
-		 * running [`createCanvas`](https://q5js.org/learn/#createCanvas).
+		 * Running `new Q5()` enables use of q5 functions and variables
+		 * anywhere in your sketch. You can also start Q5 in global 
+		 * mode by running [`createCanvas`](https://q5js.org/learn/#createCanvas).
 		 * 
-		 * By default q5 uses the CanvasRenderingContext2D based c2d renderer.
+		 * By default q5 uses the CanvasRenderingContext2D (aka Canvas2D)
+		 * based c2d renderer.
 		 * 
-		 * To use the q5 WebGPU renderer, run `Q5.webgpu()` after the creation of file level variables. For more information read the [q5-webgpu modules documentation](https://github.com/q5js/q5.js/blob/main/src/readme.md#webgpu-canvas).
+		 * To use the [q5 WebGPU renderer](https://github.com/q5js/q5.js/wiki/q5-WebGPU-renderer), run `Q5.webgpu()` after the creation of file level variables.
 		 * @param {string | Function} [scope]
 		 *   - "global": (default) top-level global mode, adds q5 functions
 		 * and variables to the global scope
 		 *   - "auto": if users don't create a new instance of Q5 themselves, an instance will be created automatically with this scope, which replicates p5's global mode
-		 *   - "instance": enables users to [assign a Q5 instance to a variable](https://github.com/q5js/q5.js/wiki/Instance-Mode), not to the global scope
+		 *   - "instance": enables users to [assign a Q5 instance to a variable](https://github.com/q5js/q5.js/wiki/Instance-Mode)
 		 * @param {HTMLElement} [parent] element that the canvas will be placed inside
 		 * @example
 new Q5();
@@ -823,12 +824,12 @@ rect(20, 20, 60, 60);
 	/** 💻
 	 * Customize how your canvas is presented.
 	 * @param {string} mode
-	 *   - "normal": (default) no styling to canvas or its parent element
-	 *   - "centered": canvas will be centered horizontally and vertically within its parent and if the window is smaller than the canvas, the canvas will be resized to avoid clipping
-	 *   - "maxed": canvas will fill the parent element, with letterboxing if necessary to preserve its aspect ratio
+	 *   - "normal": (default) canvas is not repositioned
+	 *   - "centered": canvas is moved to the center of its parent
+	 *   - "maxed": canvas will be scaled to fill the parent element, with letterboxing if necessary to preserve its aspect ratio
 	 * @param {string} renderQuality
-	 *   - "smooth": (default) no change to the default render quality
-	 *   - "pixelated": runs `pixelDensity(1)` and `noSmooth()` then sets the canvas CSS styles `image-rendering: pixelated` and `font-smooth: never`
+	 *   - "smooth": (default) smooth upscaling if the canvas is scaled
+	 *   - "pixelated": pixels rendered as sharp squares
 	 * @param {number} scale can also be given as a string (for example "x2")
 	 * @example
 createCanvas(50, 25);
@@ -1019,17 +1020,22 @@ point(125, 50);
 	function curveTightness(val: number): void;
 
 	/** 🧑‍🎨
-	 * Starts recording vertices for a shape.
+	 * Starts storing vertices for a convex shape.
 	 */
 	function beginShape(): void;
 
 	/** 🧑‍🎨
-	 * Starts recording vertices for a shape to be used as a contour.
+	 * Ends storing vertices for a convex shape.
+	 */
+	function endShape(): void;
+
+	/** 🧑‍🎨
+	 * Starts storing vertices for a contour.
 	 */
 	function beginContour(): void;
 
 	/** 🧑‍🎨
-	 * Ends recording vertices for a shape.
+	 * Ends storing vertices for a contour.
 	 */
 	function endContour(): void;
 
@@ -1131,13 +1137,15 @@ point(125, 50);
 
 	// 📑 dom
 
+	/** 📑
+	 * The Document Object Model (DOM) is an interface for
+	 * creating and editing web pages with JavaScript.
+	 */
+
 	/** 📑
 	 * Creates a new HTML element and adds it to the page. `createEl` is
 	 * an alias.
 	 * 
-	 * The element is part of the DOM (Document Object Model), an interface for
-	 * creating and editing web pages with JavaScript.
-	 * 
 	 * Modify the element's CSS [`style`](https://developer.mozilla.org/docs/Web/API/HTMLElement/style) to change its appearance.
 	 * 
 	 * Use [`addEventListener`](https://developer.mozilla.org/docs/Web/API/EventTarget/addEventListener) to respond to events such as:
@@ -1255,6 +1263,9 @@ let img = createImg('/assets/p5play_logo.webp')
 	 * 
 	 * Use the `value` property to get or set the input's value.
 	 * 
+	 * Use the `placeholder` property to set label text that appears
+	 * inside the input when it's empty.
+	 * 
 	 * See MDN's [input documentation](https://developer.mozilla.org/docs/Web/HTML/Element/input#input_types) for the full list of input types.
 	 * @param {string} [value] initial value
 	 * @param {string} [type] text input type, can be 'text', 'password', 'email', 'number', 'range', 'search', 'tel', 'url'
@@ -1552,14 +1563,6 @@ function setup() {
 	 */
 	function mask(img: Image): void;
 
-	/** 🌆
-	 * Saves the image.
-	 * @param {string} filename filename or url
-	 * @param {string} extension file extension
-	 * @param {number} [quality] quality of the saved image
-	 */
-	function save(filename: string, extension: string, quality?: number): void;
-
 	/** 🌆
 	 * Retrieves a subsection of an image or canvas, as a q5 Image.
 	 * Or if width and height are both 1, returns the color of the pixel at the given coordinates in `[R, G, B, A]` array format.
@@ -1595,7 +1598,7 @@ createCanvas(200);
 let c = color('lime');
 
 function draw() {
-	set(random(width), random(height), c);
+	set(randomX(), randomY(), c);
 	updatePixels();
 }
 	 */
@@ -1781,9 +1784,9 @@ text(info, 12, 30, 20, 6);
 	 *
 	 * In q5 WebGPU, fonts must be in MSDF format with the file ending
 	 * "-msdf.json". If no font is loaded before `text` is run, then
-	 * the default font, Microsoft YaHei, is loaded:
-	 * https://q5js.org/fonts/YaHei-msdf.json
-	 * https://q5js.org/fonts/YaHei.png
+	 * the default sans serif font, Microsoft YaHei, is loaded:
+	 * https://q5js.org/fonts/sans-serif-msdf.json
+	 * https://q5js.org/fonts/sans-serif.png
 	 * @param {string} url uRL of the font to load
 	 * @param {(font: FontFace) => void} [cb] optional callback function that receives the font name as an argument once the font is loaded
 	 * @returns {FontFace} font
@@ -1929,16 +1932,40 @@ createCanvas(200);
 	 * @param {number} [wrapWidth] maximum line width in characters
 	 * @param {number} [lineLimit] maximum number of lines
 	 * @returns {Q5.Image} an image object representing the rendered text
+	 * @example
+createCanvas(200, 200);
+textSize(80);
+let img = createTextImage('🐶');
+img.filter(INVERT);
+
+function draw() {
+	background(200);
+	text('🐶', 10, 75);
+	image(img, 110, 75);
+}
 	 */
 	function createTextImage(str: string, wrapWidth: number, lineLimit: number): Q5.Image;
 
 	/** ✍️
-	 * Renders an image generated from text onto the canvas. The
-	 * positioning of the image is affected by the current text
+	 * Renders an image generated from text onto the canvas.
+	 * 
+	 * The positioning of the image is affected by the current text
 	 * alignment and baseline settings.
-	 * @param {HTMLImageElement} img image object to render, typically generated from text
+	 * 
+	 * If the first parameter is a string, an image of the text is
+	 * created automatically, then drawn.
+	 * @param {Q5.Image} img image object or text
 	 * @param {number} x x-coordinate where the image should be placed
 	 * @param {number} y y-coordinate where the image should be placed
+	 * @example
+createCanvas(200, 200);
+textSize(80);
+textAlign(CENTER, CENTER);
+
+function draw() {
+	background(200);
+	textImage('🐶', 100, 100);
+}
 	 */
 	function textImage(img: HTMLImageElement, x: number, y: number): void;
 
@@ -1950,6 +1977,12 @@ createCanvas(200);
 	 * @param {number} l minimum number of digits to appear before the decimal point; the number is padded with zeros if necessary
 	 * @param {number} r number of digits to appear after the decimal point
 	 * @returns {string} a string representation of the number, formatted accordingly
+	 * @example
+createCanvas(200, 100);
+background(200);
+
+textSize(32);
+text(nf(PI, 4, 2), 10, 60);
 	 */
 	function nf(n: number, l: number, r: number): string;
 
@@ -2104,17 +2137,15 @@ rect(100, 0, 100, 200);
 	 * RGB colors have components `r`/`red`, `g`/`green`, `b`/`blue`,
 	 * and `a`/`alpha`.
 	 * 
-	 * RGB is the default color mode.
-	 * 
-	 * By default when a canvas is using the `display-p3` color space,
+	 * By default when a canvas is using the HDR `display-p3` color space,
 	 * rgb colors are mapped to the full P3 gamut, even when they use the
-	 * legacy integer format.
+	 * legacy integer 0-255 format.
 	 * @example
-createCanvas(200);
+createCanvas(200, 100);
 
-function setup() {
-	background(255, 0, 0);
-}
+colorMode(RGB, 255);
+
+background(255, 0, 0);
 	 */
 	const RGB: 'rgb';
 
@@ -2125,13 +2156,11 @@ function setup() {
 	 * example, note that full red appears less saturated, as it would
 	 * on an SDR display.
 	 * @example
-createCanvas(200);
+createCanvas(200, 100);
 
 colorMode(SRGB, 255);
 
-function setup() {
-	background(255, 0, 0);
-}
+background(255, 0, 0);
 	 */
 	const SRGB: 'srgb';
 
@@ -2224,6 +2253,24 @@ function draw() {
 	 */
 	let mouseIsPressed: boolean;
 
+	/** 🖲️
+	 * Define this function to respond to mouse events immediately.
+	 * 
+	 * There can be a delay of up to one frame between a mouse event
+	 * and the next time the `draw` function is run.
+	 * 
+	 * Useful for playing sounds.
+	 * @example
+createCanvas(200, 100);
+
+let gray = 100;
+function mousePressed() {
+	background(gray);
+	gray += 10;
+}
+	 */
+	function mousePressed(): void;
+
 	/** 🖲️
 	 * The name of the last key pressed.
 	 * @example
@@ -2260,6 +2307,24 @@ function draw() {
 	 */
 	function keyIsDown(key: string): boolean;
 
+	/** 🖲️
+	 * Define this function to respond to key press events immediately.
+	 * 
+	 * There can be a delay of up to one frame between a key press event
+	 * and the next time the `draw` function is run.
+	 * 
+	 * Useful for playing sounds.
+	 * @example
+createCanvas(200, 100);
+
+let gray = 100;
+function keyPressed() {
+	background(gray);
+	gray += 10;
+}
+	 */
+	function keyPressed(): void;
+
 	/** 🖲️
 	 * Array of current touches, each touch being an object with
 	 * id, x, and y properties.
@@ -2271,19 +2336,53 @@ function draw() {
 	 * If an image is provided, optional x and y coordinates can
 	 * specify the active point of the cursor.
 	 * @param {string} name name of the cursor or the url to an image
-	 * @param {number} [x] x-coordinate of the cursor's hot spot
-	 * @param {number} [y] y-coordinate of the cursor's hot spot
+	 * @param {number} [x] x-coordinate of the cursor's point
+	 * @param {number} [y] y-coordinate of the cursor's point
+	 * @example
+createCanvas(200, 100);
+cursor('pointer');
 	 */
 	function cursor(name: string, x?: number, y?: number): void;
 
 	/** 🖲️
 	 * Hides the cursor within the bounds of the canvas.
 	 * @example
-createCanvas(200);
+createCanvas(200, 100);
 noCursor();
 	 */
 	function noCursor(): void;
 
+	/** 🖲️
+	 * Prevents mouse wheel events from propagating and causing
+	 * the page to scroll when the mouse is inside the canvas.
+	 * 
+	 * Useful for games and interactive art that fill the screen.
+	 * @example
+createCanvas(200, 100);
+noScroll();
+	 */
+	function noScroll(): void;
+
+	/** 🖲️
+	 * Define this function to respond to mouse wheel events.
+	 * 
+	 * `event.deltaX` and `event.deltaY` are the horizontal and vertical
+	 * scroll amounts, respectively.
+	 * 
+	 * Return false to prevent the default behavior of scrolling the page.
+	 * @example
+let x = y = 100;
+function draw() {
+	circle(x, y, 10);
+}
+function mouseWheel(e) {
+	x += e.deltaX;
+	y += e.deltaY;
+	return false;
+}
+	 */
+	function mouseWheel(event: any): void;
+
 	/** 🖲️
 	 * Requests that the pointer be locked to the document body, hiding the cursor and allowing for unlimited movement.
 	 */
@@ -2296,6 +2395,60 @@ noCursor();
 
 	// 🧮 math
 
+		/** 🧮
+	 * Generates random numbers. If no arguments are provided, returns a random number between 0 and 1.
+	 * If one number argument is provided, returns a random number between 0 and the provided value.
+	 * If two number arguments are provided, returns a random number between the two values.
+	 * If an array is provided, returns a random element from the array.
+	 * @param {number | any[]} [low] lower bound (inclusive) or an array
+	 * @param {number} [high] upper bound (exclusive)
+	 * @returns {number | any} a random number or element
+	 * @example
+createCanvas(200);
+background(200);
+frameRate(5);
+
+function draw() {
+	circle(100, 100, random(200));
+}
+	 */
+	function random(low?: number | any[], high?: number): number | any;
+
+	/** 🧮
+	 * Generates a random number within the range of the canvas width.
+	 * @param {number} [margin] distance to extend (positive) or contract (negative) the range from canvas edges
+	 * @returns {number} random x value
+	 * @example
+createCanvas(200, 100);
+background(200);
+
+function draw() {
+	circle(randomX(), 50, random(50));
+}
+	 */
+	function randomX(margin?: number): number;
+
+	/** 🧮
+	 * Generates a random number within the range of the canvas height.
+	 * @param {number} [margin] distance to extend (positive) or contract (negative) the range from canvas edges
+	 * @returns {number} random y value
+	 * @example
+createCanvas(200);
+background(200);
+
+function draw() {
+	circle(100, randomY(), random(50));
+}
+	 * @example
+createCanvas(200);
+background(200);
+
+function draw() {
+	circle(randomX(), randomY(-60), 10);
+}
+	 */
+	function randomY(margin?: number): number;
+
 	/** 🧮
 	 * Calculates the distance between two points.
 	 * 
@@ -2305,6 +2458,15 @@ noCursor();
 	 * @param {number} x2 x-coordinate of the second point
 	 * @param {number} y2 y-coordinate of the second point
 	 * @returns {number} distance between the points
+	 * @example
+function draw() {
+	background(200);
+	circle(100, 100, 20);
+	circle(mouseX, mouseY, 20);
+
+	let d = dist(100, 100, mouseX, mouseY);
+	text(round(d), 20, 20);
+}
 	 */
 	function dist(x1: number, y1: number, x2: number, y2: number): number;
 
@@ -2386,17 +2548,6 @@ noCursor();
 	 */
 	function randomSeed(seed: number): void;
 
-	/** 🧮
-	 * Generates random numbers. If no arguments are provided, returns a random number between 0 and 1.
-	 * If one number argument is provided, returns a random number between 0 and the provided value.
-	 * If two number arguments are provided, returns a random number between the two values.
-	 * If an array is provided, returns a random element from the array.
-	 * @param {number | any[]} [a] lower bound (inclusive) or an array
-	 * @param {number} [b] upper bound (exclusive)
-	 * @returns {number | any} a random number or element
-	 */
-	function random(a?: number | any[], b?: number): number | any;
-
 	/** 🧮
 	 * Sets the random number generation method.
 	 * @param {any} method method to use for random number generation
@@ -2419,25 +2570,34 @@ noCursor();
 
 	/** 🧮
 	 * Sets the noise generation mode.
+	 * 
+	 * Only the default mode, "perlin", is included in q5.js. Use of the 
+	 * other modes requires the q5-noiser module.
 	 * @param {'perlin' | 'simplex' | 'blocky'} mode noise generation mode
 	 */
 	function noiseMode(mode: 'perlin' | 'simplex' | 'blocky'): void;
 
-	/** 🧮
-	 * Sets the seed value for noise generation.
-	 * @param {number} seed seed value
-	 */
-	function noiseSeed(seed: number): void;
-
 	/** 🧮
 	 * Generates a noise value based on the x, y, and z inputs.
 	 * @param {number} [x] x-coordinate input
 	 * @param {number} [y] y-coordinate input
 	 * @param {number} [z] z-coordinate input
 	 * @returns {number} a noise value
+	 * @example
+function draw() {
+	background(200);
+	let n = noise(frameCount * 0.01);
+	square(n * 200, n * 200, 10);
+}
 	 */
 	function noise(x?: number, y?: number, z?: number): number;
 
+	/** 🧮
+	 * Sets the seed value for noise generation.
+	 * @param {number} seed seed value
+	 */
+	function noiseSeed(seed: number): void;
+
 	/** 🧮
 	 * Sets the level of detail for noise generation.
 	 * @param {number} lod level of detail (number of octaves)
@@ -2466,23 +2626,29 @@ noCursor();
 	// 🎞️ record
 
 	/** 🎞️
-	 * Creates a recorder. Simply hit record to start recording!
+	 * q5.js has a built-in canvas recorder powered by
+	 * [`MediaRecorder`](https://developer.mozilla.org/docs/Web/API/MediaRecorder/MediaRecorder). It provides a good balance between 
+	 * video encoding speed, quality, and file size.
 	 * 
 	 * Recording large canvases is an intensive process, so your
 	 * computer may not be able to do it in real time. That's okay,
 	 * the resulting video will playback at your sketch's target 
-	 * frame rate.
+	 * frame rate. But if real time interaction while recording is a 
+	 * priority, consider reducing the canvas' size, frame rate, and/or 
+	 * recording quality.
+	 * 
+	 * HDR video encoding is not yet supported by any web browser.
+	 * For that and other advanced features, consider using
+	 * a screen capture tool like [OBS Studio](https://obsproject.com).
+	 */
+
+	/** 🎞️
+	 * Creates a recorder. Simply hit record to start recording!
 	 * 
-	 * In cases where real time interaction is a priority, consider 
-	 * reducing the canvas' size, frame rate, and/or recording
-	 * quality.
+	 * `quality` is set to "high" by default.
 	 * 
-	 * `format` and `quality` properties are set 
-	 * automatically based on the height of the canvas. They can be
-	 * changed via the UI or programmatically.
+	 * `format` is set automatically based on the height of the canvas.
 	 * 
-	 * The recorder uses the [`MediaRecorder`](https://developer.mozilla.org/docs/Web/API/MediaRecorder/MediaRecorder) API, which 
-	 * unfortunately can't encode HDR video.
 	 * @returns {HTMLElement} a recorder, q5 DOM element
 	 * @example
 createCanvas(200);
@@ -2490,7 +2656,7 @@ createCanvas(200);
 createRecorder();
 
 function draw() {
-	circle(mouseX, random(canvas.h), 10);
+	circle(mouseX, randomY(), 10);
 }
 	 */
 	function createRecorder(): HTMLElement;
@@ -2517,7 +2683,7 @@ function draw() {
 	 * @param {string} fileName
 	 * @example
 function draw() {
-	square(mouseX, random(canvas.h), 10);
+	square(mouseX, randomY(), 10);
 }
 
 function mousePressed() {
@@ -2535,8 +2701,15 @@ function mousePressed() {
 	// 🔊 sound
 
 	/** 🔊
-	 * Loads audio data from a file and returns a `Q5.Sound` object that 
-	 * provides low latency sound mixing powered by WebAudio.
+	 * q5.js includes low latency sound playback and basic mixing powered
+	 * by WebAudio.
+	 * 
+	 * For audio filtering, synthesis, and analysis, consider using
+	 * [p5.sound](https://p5js.org/reference/p5.sound/).
+	 */
+
+	/** 🔊
+	 * Loads audio data from a file and returns a `Q5.Sound` object.
 	 * 
 	 * Use functions like `play`, `pause`, and `stop` to 
 	 * control playback. Note that sounds can only be played after the 
@@ -2705,6 +2878,37 @@ q.mousePressed = () => {
 	 */
 	function load(...urls: string[]): Promise<any[]>;
 
+	/** 🛠️
+	 * Saves data to a file.
+	 * 
+	 * If data is not specified, the canvas will be saved.
+	 * 
+	 * If no arguments are provided, the canvas will be saved as
+	 * an image file named "untitled.png".
+	 * @param {object} [data] canvas, image, or JS object
+	 * @param {string} [filename] filename or url
+	 * @param {string} [extension] file extension
+	 * @example
+createCanvas(200);
+background(200);
+circle(100, 100, 50);
+
+function mousePressed() {
+	save('circle.png');
+}
+	 * @example
+createCanvas(200);
+
+textSize(180);
+let bolt = createTextImage('⚡️');
+image(bolt, 16, -56);
+
+function mousePressed() {
+	save(bolt, 'bolt.png');
+}
+	 */
+	function save(data: object, filename?: string, extension?: string): void;
+
 	/** 🛠️
 	 * Loads a text file from the specified url. Result is one string.
 	 * @param {string} url text file