q5 2.17.0 → 2.18.3

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.17.0",
+	"version": "2.18.1",
 	"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.17.0",
+	"version": "2.18.3",
 	"description": "A sequel to p5.js that's optimized for interactive art",
 	"author": "quinton-ashley",
 	"contributors": [
@@ -11,7 +11,7 @@
 	"homepage": "https://q5js.org/home",
 	"main": "q5-server.js",
 	"scripts": {
-		"bundle": "cat src/q5-core.js src/q5-canvas.js src/q5-c2d-canvas.js src/q5-c2d-drawing.js src/q5-c2d-image.js src/q5-c2d-soft-filters.js src/q5-c2d-text.js src/q5-ai.js src/q5-color.js src/q5-display.js src/q5-dom.js src/q5-input.js src/q5-math.js src/q5-sound.js src/q5-util.js src/q5-vector.js src/q5-webgpu-canvas.js src/q5-webgpu-drawing.js src/q5-webgpu-image.js src/q5-webgpu-text.js > q5.js",
+		"bundle": "cat src/q5-core.js src/q5-canvas.js src/q5-c2d-canvas.js src/q5-c2d-drawing.js src/q5-c2d-image.js src/q5-c2d-soft-filters.js src/q5-c2d-text.js src/q5-ai.js src/q5-color.js src/q5-display.js src/q5-dom.js src/q5-input.js src/q5-math.js src/q5-record.js src/q5-sound.js src/q5-util.js src/q5-vector.js src/q5-webgpu-canvas.js src/q5-webgpu-drawing.js src/q5-webgpu-image.js src/q5-webgpu-text.js > q5.js",
 		"min": "terser q5.js --compress ecma=2024 --mangle > q5.min.js",
 		"dist": "bun bundle && bun min",
 		"dist-p5play": "bun dist && cp q5.js ../../web/p5play-web/v3/q5.js && cp q5.min.js ../../web/p5play-web/v3/q5.min.js",

package/q5.d.ts

@@ -7,6 +7,20 @@
 declare global {
 	// ⭐️ core
 
+	/** ⭐️
+	 * Welcome to q5's documentation! ☺️
+	 * 
+	 * First time coding? Check out the [q5 Beginner's Guide to JavaScript](https://github.com/q5js/q5.js/wiki/q5-Beginner's-Guide-to-JavaScript).
+	 * 
+	 * On these Learn pages you'll find concise descriptions for
+	 * q5's functions and variables. Scroll through entire topics without
+	 * needing to click between separate pages.
+	 * 
+	 * Experiment with editing the code in the interactive mini examples,
+	 * which are often only 8 lines of code or less. They automatically
+	 * update as you type, so you can see results right away.
+	 */
+
 	/** ⭐️
 	 * The draw function is run 60 times per second by default.
 	 * @example
@@ -480,6 +494,8 @@ square(80, 80, 80);
 	 * Like the [`color`](https://q5js.org/learn/#color) function, this function
 	 * can accept colors in a wide range of formats: as a CSS color string,
 	 * a `Color` object, grayscale value, or color component values.
+	 * 
+	 * Not available in q5 WebGPU.
 	 * @param {Color} color shadow color
 	 * @example
 createCanvas(200);
@@ -524,12 +540,14 @@ rect(104, 104, 80, 80);
 	 * @param {number} blur blur radius of the shadow, defaults to 0
 	 * @example
 createCanvas(200);
-background(200);
 noStroke();
-shadow('red');
+shadow(50);
 
-shadowBox(-20, -8, 50);
-circle(100, 100, 80, 80);
+function draw() {
+  background(200);
+	shadowBox(-20, mouseY, 10);
+	circle(100, 100, 80, 80);
+}
 	 * @example
 createCanvas(200);
 background(200);
@@ -767,6 +785,8 @@ square(0, 0, 50);
 	/** ⬜️
 	 * Any position coordinates or dimensions you use will be scaled based
 	 * on the unit provided to this function.
+	 * 
+	 * Not available in q5 WebGPU.
 	 * @param {number} unit unit to scale by
 	 * @example
 createCanvas(200);
@@ -778,6 +798,8 @@ rect(20, 20, 60, 60);
 
 	/** ⬜️
 	 * Creates a graphics buffer.
+	 * 
+	 * Not available in q5 WebGPU.
 	 * @param {number} w width
 	 * @param {number} h height
 	 * @param {Object} [opt] options
@@ -786,7 +808,8 @@ rect(20, 20, 60, 60);
 	function createGraphics(w: number, h: number, opt?: any): Q5;
 
 	/** ⬜️
-	 * The 2D rendering context for the canvas.
+	 * The 2D rendering context for the canvas, if using the Canvas2D
+	 * renderer.
 	 */
 	var ctx: CanvasRenderingContext2D;
 
@@ -798,14 +821,14 @@ rect(20, 20, 60, 60);
 	// 💻 display
 
 	/** 💻
-	 * The `displayMode` function lets you customize how your canvas is presented.
+	 * 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);
@@ -830,7 +853,7 @@ createCanvas(200, 100);
 background('crimson');
 	 * @example
 function draw() {
-	background(128, 20);
+	background(128, 100);
 	circle(mouseX, mouseY, 20);
 }
 	 */
@@ -1109,22 +1132,36 @@ point(125, 50);
 	// 📑 dom
 
 	/** 📑
-	 * Creates a new HTML element.
-	 * 
-	 * q5 adds functions like `position` and `size` to the element
-	 * that make it easy to position elements above the canvas.
+	 * 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.
 	 * 
 	 * Modify the element's CSS [`style`](https://developer.mozilla.org/docs/Web/API/HTMLElement/style) to change its appearance.
 	 * 
-	 * `createEl` is an alias for this function.
+	 * Use [`addEventListener`](https://developer.mozilla.org/docs/Web/API/EventTarget/addEventListener) to respond to events such as:
+	 * - "click": when the element is clicked
+	 * - "mouseover": when the mouse hovers over the element
+	 * - "mouseout": when the mouse stops hovering over the element
+	 * - "input": when a form element's value changes
+	 * 
+	 * q5 adds some extra functionality to the elements it creates:
+	 * 
+	 * - the `position` function makes it easy to place the element
+	 * relative to the canvas
+	 * - the `size` function sets the width and height of the element
+	 * - alternatively, use the element's `x`, `y`, `width`, and `height` properties
 	 * @param {string} tag tag name of the element
 	 * @param {string} [content] content of the element
-	 * @returns {HTMLElement} created DOM element
+	 * @returns {HTMLElement} element
 	 * @example
 createCanvas(200);
 
 let el = createEl('div', '*');
-el.position(0, 0);
+el.position(50, 50);
 el.size(100, 100);
 el.style.fontSize = '136px';
 el.style.textAlign = 'center';
@@ -1139,18 +1176,20 @@ el.style.color = 'white';
 	 * @param {string} [text] text content
 	 * @param {boolean} [newTab] whether to open the link in a new tab
 	 * @example
-createCanvas(200, 100);
+createCanvas(200);
 
 let link = createA('https://q5js.org', 'q5.js');
-link.position(0, 0);
+link.position(16, 42);
 link.style.fontSize = '80px';
+
+link.addEventListener('mouseover', () => {
+	background('blue');
+});
 	 */
 	function createA(href: string, text?: string): HTMLAnchorElement;
 
 	/** 📑
 	 * Creates a button element.
-	 * 
-	 * Use [`addEventListener`](https://developer.mozilla.org/docs/Web/API/EventTarget/addEventListener) to respond to button click events.
 	 * @param {string} [content] text content
 	 * @example
 createCanvas(200, 100);
@@ -1177,7 +1216,7 @@ createCanvas(200, 100);
 let box = createCheckbox('Check me!');
 box.label.style.color = 'lime';
 
-box.addEventListener('change', () => {
+box.addEventListener('input', () => {
 	if (box.checked) background('lime');
 	else background('black');
 });
@@ -1202,7 +1241,7 @@ function draw() {
 	function createColorPicker(value?: string): HTMLInputElement;
 
 	/** 📑
-	 * Creates an img element.
+	 * Creates an image element.
 	 * @param {string} src url of the image
 	 * @example
 createCanvas(200, 100);
@@ -1218,6 +1257,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'
@@ -1280,10 +1322,12 @@ function draw() {
 	 * 
 	 * Set `multiple` to `true` to allow multiple options to be selected.
 	 * 
-	 * Use the `value` property to get or set the selected option.
+	 * Use the `value` property to get or set the selected option value.
 	 * 
-	 * Use the `selected` property to get the selected option or options.
-	 * @param {boolean} [placeholder] optional placeholder text that appears when no option is selected
+	 * Use the `selected` property get the labels of the selected 
+	 * options or set the selected options by label. Can be a single 
+	 * string or an array of strings.
+	 * @param {string} [placeholder] optional placeholder text that appears before an option is selected
 	 * @example
 createCanvas(200, 100);
 
@@ -1326,12 +1370,27 @@ function draw() {
 	 * @example
 createCanvas(200, 100);
 
+// example coming soon
 // let vid = createVideo('/assets/q5js_video.mp4');
 // vid.controls = true;
 // vid.loop = true;
 	 */
 	function createVideo(src: string): HTMLVideoElement;
 
+	/** 📑
+	 * Finds the first element in the DOM that matches the given [CSS selector](https://developer.mozilla.org/docs/Learn_web_development/Core/Styling_basics/Basic_selectors).
+	 * @param {string} selector
+	 * @returns {HTMLElement} element
+	 */
+	function findElement(selector: string): HTMLElement;
+
+	/** 📑
+	 * Finds all elements in the DOM that match the given [CSS selector](https://developer.mozilla.org/docs/Learn_web_development/Core/Styling_basics/Basic_selectors).
+	 * @param {string} selector
+	 * @returns {HTMLElement[]} elements
+	 */
+	function findElements(selector: string): HTMLElement[];
+
 	// 🌆 image
 
 	/** 🌆
@@ -1679,8 +1738,8 @@ function setup() {
 
 	/** 🌆
 	 * Creates a new image.
-	 * @param {number} [w] character limit per line
-	 * @param {number} [h] line limit
+	 * @param {number} w width
+	 * @param {number} h height
 	 * @param {any} [opt] optional settings for the image
 	 * @returns {Image}
 	 */
@@ -1710,6 +1769,7 @@ textSize(20);
 let info = "q5.js is a JavaScript library for creative coding. It's a sequel to p5.js that's optimized for interactive art.";
 
 text(info, 12, 30, 20, 6);
+//
 //
 	 */
 	function text(str: string, x: number, y: number, wrapWidth?: number, lineLimit?: number): void;
@@ -1726,9 +1786,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
@@ -1991,20 +2051,22 @@ createCanvas(200);
 	 * @returns {Color} a new `Color` object
 	 * @example
 createCanvas(200);
-//                (gray, alpha)
-let darkGray = color(55, 100);
-background(darkGray);
-//	                  (r, g,   b,  a)
-let blueBottle = color(0, 0, 200, 20);
-fill(blueBottle);
-circle(100, 50, 50);
+rect(0, 0, 100, 200);
+
+//                ( r,   g,   b,   a)
+let bottle = color(90, 100, 255, 100);
+fill(bottle);
+stroke(bottle);
+strokeWeight(30);
+circle(100, 100, 155);
 	 * @example
 createCanvas(200);
-
-let c = color('gray');
+//          (gray, alpha)
+let c = color(200, 50);
 
 function draw() {
 	background(c);
+	circle(mouseX, mouseY, 50);
 	c.g = (c.g + 1) % 255;
 }
 	 */
@@ -2037,6 +2099,7 @@ colorMode(OKLCH);
 
 fill(0.25, 0.15, 0);
 rect(0, 0, 100, 200);
+
 fill(0.75, 0.15, 0)
 rect(100, 0, 100, 200);
 	 */
@@ -2238,6 +2301,53 @@ 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);
+background(200);
+
+function draw() {
+	circle(randomX(), 100, 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));
+}
+	 */
+	function randomY(margin?: number): number;
+
 	/** 🧮
 	 * Calculates the distance between two points.
 	 * 
@@ -2328,17 +2438,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
@@ -2361,16 +2460,13 @@ 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
@@ -2380,6 +2476,12 @@ noCursor();
 	 */
 	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)
@@ -2405,11 +2507,94 @@ noCursor();
 	 */
 	const TAU: number;
 
+	// 🎞️ record
+
+	/** 🎞️
+	 * q5.js has a built-in canvas recorder powered by
+	 * [`MediaRecorder`](https://developer.mozilla.org/docs/Web/API/MediaRecorder/MediaRecorder). It's 5-10x faster than p5.capture.
+	 * 
+	 * 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.
+	 * 
+	 * 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 recording features, consider using
+	 * a screen capture tool like [OBS Studio](https://obsproject.com).
+	 */
+
+	/** 🎞️
+	 * Creates a recorder. Simply hit record to start recording!
+	 * 
+	 * `format` and `quality` properties are set 
+	 * automatically based on the height of the canvas. They can be
+	 * changed via the UI or programmatically.
+	 * 
+	 * @returns {HTMLElement} a recorder, q5 DOM element
+	 * @example
+createCanvas(200);
+
+createRecorder();
+
+function draw() {
+	circle(mouseX, random(height), 10);
+}
+	 */
+	function createRecorder(): HTMLElement;
+
+	/** 🎞️
+	 * Starts recording the canvas or resumes recording if it was paused.
+	 * 
+	 * If no recorder exists, one is created but not displayed.
+	 */
+	function record(): void;
+
+	/** 🎞️
+	 * Pauses the canvas recording, if one is in progress.
+	 */
+	function pauseRecording(): void;
+
+	/** 🎞️
+	 * Discards the current recording.
+	 */
+	function deleteRecording(): void;
+
+	/** 🎞️
+	 * Saves the current recording as a video file.
+	 * @param {string} fileName
+	 * @example
+function draw() {
+	square(mouseX, random(height), 10);
+}
+
+function mousePressed() {
+	if (!recording) record();
+	else saveRecording('squares');
+}
+	 */
+	function saveRecording(fileName): void;
+
+	/** 🎞️
+	 * True if the canvas is currently being recorded.
+	 */
+	var recording: boolean;
+
 	// 🔊 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