q5 2.24.4 → 2.25.1

package/README.md

@@ -6,7 +6,7 @@
 - performance optimized for interactive art 🚀
 - lightning fast [WebGPU renderer](https://github.com/q5js/q5.js/wiki/q5-WebGPU-renderer) ⚡️
 - beginner friendly [documentation](https://q5js.org/learn) 📚
-- compatible with popular addons, including [p5.sound][] and [p5play][] 🎮
+- compatible with popular addons, including [p5.sound][], [ml5.js][], and [p5play][] 🎮
 - no dependencies, ~100kb minified 📦
 - free to use under the LGPL (just like p5.js) 🆓
 
@@ -19,8 +19,6 @@ createCanvas(100, 100);
 circle(50, 50, 50);
 ```
 
-q5 doesn't replicate all of p5's functionality, but it's a superior alternative for many use cases. 🛠️
-
 ## Documentation
 
 Browse the [q5 reference pages](https://q5js.org/learn) to learn how to use q5.js.
@@ -34,7 +32,9 @@ Use the [q5.d.ts](q5.d.ts) file in Visual Studio Code to get autocompletion and
 	"compilerOptions": {
 		"target": "ESNext"
 	},
-	"include": ["*.js", "*/*.js", "node_modules/q5/q5.d.ts"]
+	"typeAcquisition": {
+		"include": ["node_modules/q5"]
+	}
 }
 ```
 
@@ -42,7 +42,7 @@ Use the [q5.d.ts](q5.d.ts) file in Visual Studio Code to get autocompletion and
 
 q5 is open source and anyone can use it for free under the terms of the LGPL (just like p5.js). 🎉
 
-We need your support though! If you enjoy using q5.js, please donate via [GitHub Sponsors](https://github.com/sponsors/quinton-ashley) or [Patreon](https://www.patreon.com/p5play).
+We need your support though! If you enjoy using q5.js, please donate via [GitHub Sponsors](https://github.com/sponsors/quinton-ashley), [ko-fi](https://ko-fi.com/q5play), or [Patreon](https://www.patreon.com/p5play).
 
 ## Contributing
 
@@ -91,4 +91,5 @@ https://github.com/processing/p5.js/blob/1.1.9/src/math/noise.js
 [p5.js]: https://p5js.org
 [Processing Java]: https://processing.org
 [p5.sound]: https://archive.p5js.org/reference/#/libraries/p5.sound
+[ml5.js]: https://ml5js.org
 [p5play]: https://p5play.org

package/deno.json

@@ -1,6 +1,6 @@
 {
 	"name": "@q5/q5",
-	"version": "2.24.1",
+	"version": "2.25.0",
 	"license": "LGPL-3.0",
 	"description": "Beginner friendly graphics powered by WebGPU and optimized for interactive art!",
 	"author": "quinton-ashley",

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "q5",
-	"version": "2.24.4",
+	"version": "2.25.1",
 	"description": "Beginner friendly graphics powered by WebGPU and optimized for interactive art!",
 	"author": "quinton-ashley",
 	"contributors": [

package/q5.d.ts

@@ -840,13 +840,6 @@ square(0, 0, 50);
 	 */
 	function displayDensity(): number;
 
-	/** ⬜️
-	 * Enables or disables fullscreen mode.
-	 * @param {boolean} [v] boolean indicating whether to enable or disable fullscreen mode
-	 * @returns {void | boolean} true if fullscreen mode is enabled, false otherwise
-	 */
-	function fullscreen(v?: boolean): void | boolean;
-
 	/** ⬜️
 	 * Any position coordinates or dimensions you use will be scaled based
 	 * on the unit provided to this function.
@@ -1178,23 +1171,51 @@ background(255, 0, 0);
 
 	/** 💻
 	 * Customize how your canvas is presented.
-	 * @param {string} mode
-	 *   - "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) smooth upscaling if the canvas is scaled
-	 *   - "pixelated": pixels rendered as sharp squares
+	 * @param {string} mode Display modes:
+	 *   - NORMAL: (default) canvas is not repositioned
+	 *   - CENTER: 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 Render quality settings:
+	 *   - 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);
 
-displayMode('centered', 'pixelated', 4);
+displayMode(CENTER, PIXELATED, 4);
 
 circle(25, 12.5, 16);
 	 */
 	function displayMode(mode: string, renderQuality: string, scale: string | number): void;
 
+	/** 💻
+	 * Enables or disables fullscreen mode.
+	 * @param {boolean} [v] boolean indicating whether to enable or disable fullscreen mode
+	 */
+	function fullscreen(v?: boolean): void;
+
+	/** 💻
+	 * A `displayMode` setting.
+	 * 
+	 * The canvas will be scaled to fill the parent element,
+	 * with letterboxing if necessary to preserve its aspect ratio.
+	 */
+	const MAXED: 'maxed';
+
+	/** 💻
+	 * A `displayMode` render quality.
+	 * 
+	 * Smooth upscaling is used if the canvas is scaled.
+	 */
+	const SMOOTH: 'smooth';
+
+	/** 💻
+	 * A `displayMode` render quality.
+	 * 
+	 * Pixels are rendered as sharp squares if the canvas is scaled.
+	 */
+	const PIXELATED: 'pixelated';
+
 	// 🧑‍🎨 shapes
 
 	/** 🧑‍🎨
@@ -2242,7 +2263,7 @@ function draw() {
 	 * 
 	 * Useful for playing sounds.
 	 * @example
-createCanvas(200, 100);
+createCanvas(200);
 
 let gray = 100;
 function mousePressed() {
@@ -2404,8 +2425,9 @@ function draw() {
 	/**
 	 * ___Experimental! May be renamed or removed in the future.___
 	 * 
-	 * Generates a random number within a symmetric 
-	 * [jitter](https://en.wikipedia.org/wiki/Jitter) range around zero.
+	 * Generates a random number within a symmetric range around zero.
+	 * 
+	 * Can be used to create a jitter effect (random displacement).
 	 * 
 	 * Equivalent to `random(-amount, amount)`.
 	 * @param {number} amount absolute maximum amount of jitter, default is 1
@@ -2424,6 +2446,58 @@ q.draw = () => {
 	 */
 	function jit(amount: number): number;
 
+	/** 🧮
+	 * Generates a noise value based on the x, y, and z inputs.
+	 * 
+	 * Uses [Perlin Noise](https://en.wikipedia.org/wiki/Perlin_noise) by default.
+	 * @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);
+	circle(100, 100, n * 200);
+}
+	 * @example
+function draw() {
+	background(200);
+	let t = (frameCount + mouseX) * 0.02;
+	for (let x = -5; x < 220; x += 10) {
+		let n = noise(t, x * 0.1);
+		circle(x, 100, n * 40);
+	}
+}
+	 * @example
+let q = await Q5.WebGPU();
+
+q.draw = () => {
+	noStroke();
+	let t = millis() * 0.002;
+	for (let x = -100; x < 100; x += 5) {
+		for (let y = -100; y < 100; y += 5) {
+			fill(noise(t, (mouseX + x) * .05, y * .05));
+			square(x, y, 4);
+		}
+	}
+};
+	 * @example
+let q = await Q5.WebGPU();
+
+q.draw = () => {
+	let zoom = mouseY / 2000;
+	let t = millis() * 0.002;
+	for (let x = -50; x < 50; x++) {
+		for (let y = -50; y < 50; y++) {
+			stroke(noise(t, x * zoom, y * zoom));
+			point(x, y, 1);
+		}
+	}
+};
+	 */
+	function noise(x?: number, y?: number, z?: number): number;
+
 	/** 🧮
 	 * Calculates the distance between two points.
 	 * 
@@ -2503,6 +2577,89 @@ function draw() {
 	 */
 	function norm(n: number, start: number, stop: number): number;
 
+	/** 🧮
+	 * Calculates the fractional part of a number.
+	 * @param {number} n a number
+	 * @returns {number} fractional part of the number
+	 */
+	function fract(n: number): number;
+
+	/** 🧮
+	 * Calculates the absolute value of a number.
+	 * @param {number} n a number
+	 * @returns {number} absolute value of the number
+	 */
+	function abs(n: number): number;
+
+	/** 🧮
+	 * Rounds a number.
+	 * @param {number} n number to round
+	 * @param {number} [d] number of decimal places to round to
+	 * @returns {number} rounded number
+	 * @example
+createCanvas(200, 100);
+background(200);
+textSize(32);
+text(round(PI, 5), 10, 60);
+	 */
+	function round(n: number, d: number): number;
+
+	/** 🧮
+	 * Rounds a number up.
+	 * @param {number} n a number
+	 * @returns {number} rounded number
+	 * @example
+createCanvas(200, 100);
+background(200);
+textSize(32);
+text(ceil(PI), 10, 60);
+	 */
+	function ceil(n: number): number;
+
+	/** 🧮
+	 * Rounds a number down.
+	 * @param {number} n a number
+	 * @returns {number} rounded number
+	 * @example
+createCanvas(200, 100);
+background(200);
+textSize(32);
+text(floor(-PI), 10, 60);
+	 */
+	function floor(n: number): number;
+
+	/** 🧮
+	 * Returns the smallest value in a sequence of numbers.
+	 * @param {...number} args numbers to compare
+	 * @returns {number} minimum
+	 * @example
+function draw() {
+	background(min(mouseX, 100));
+}
+	 */
+	function min(...args: number[]): number;
+
+	/** 🧮
+	 * Returns the largest value in a sequence of numbers.
+	 * @param {...number} args numbers to compare
+	 * @returns {number} maximum
+	 * @example
+function draw() {
+	background(max(mouseX, 100));
+}
+	 */
+	function max(...args: number[]): number;
+
+	/** 🧮
+	 * Calculates the value of a base raised to a power.
+	 * 
+	 * For example, `pow(2, 3)` calculates 2 * 2 * 2 which is 8.
+	 * @param {number} base base
+	 * @param {number} exponent exponent
+	 * @returns {number} base raised to the power of exponent
+	 */
+	function pow(base: number, exponent: number): number;
+
 	/** 🧮
 	 * Calculates the square of a number.
 	 * @param {number} n number to square
@@ -2511,11 +2668,25 @@ function draw() {
 	function sq(n: number): number;
 
 	/** 🧮
-	 * Calculates the fractional part of a number.
-	 * @param {number} n number whose fractional part is to be calculated
-	 * @returns {number} fractional part of the number
+	 * Calculates the square root of a number.
+	 * @param {number} n a number
+	 * @returns {number} square root of the number
 	 */
-	function fract(n: number): number;
+	function sqrt(n: number): number;
+
+	/** 🧮
+	 * Calculates the natural logarithm (base e) of a number.
+	 * @param {number} n a number
+	 * @returns {number} natural logarithm of the number
+	 */
+	function loge(n: number): number;
+
+	/** 🧮
+	 * Calculates e raised to the power of a number.
+	 * @param {number} exponent power to raise e to
+	 * @returns {number} e raised to the power of exponent
+	 */
+	function exp(exponent: number): number;
 
 	/** 🧮
 	 * Sets the seed for the random number generator.
@@ -2552,21 +2723,6 @@ function draw() {
 	 */
 	function noiseMode(mode: 'perlin' | 'simplex' | 'blocky'): 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(100, 100, n * 200);
-}
-	 */
-	function noise(x?: number, y?: number, z?: number): number;
-
 	/** 🧮
 	 * Sets the seed value for noise generation.
 	 * @param {number} seed seed value