q5 2.7.6 → 2.9.0

package/.prettierignore

@@ -0,0 +1 @@
+q5.d.ts

package/package.json

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

package/q5.d.ts

@@ -12,7 +12,8 @@ declare global {
 		 * Creates an instance of Q5.
 		 *
 		 * Running `new Q5()` enables the use of q5 functions and variables
-		 * anywhere in your code.
+		 * anywhere in your code. You can also start Q5 in global mode by 
+		 * running [`createCanvas`](https://q5js.org/learn/#canvas-createCanvas).
 		 * @param {string | Function} [scope] -
 		 *   - "global": (default) top-level global mode, adds q5 functions
 		 * and variables to the global scope
@@ -22,6 +23,7 @@ declare global {
 		 * @example
 		 * new Q5();
 		 * createCanvas(200, 100);
+		 * circle(100, 50, 80);
 		 */
 		constructor(scope?: string | Function, parent?: HTMLElement);
 
@@ -54,7 +56,7 @@ declare global {
 	 * @example
 function draw() {
   background('lightgray');
-	circle(frameCount % 200, 100, 50);
+	circle(frameCount % 200, 100, 80);
 }
 	 */
 	function draw(): void;
@@ -98,7 +100,7 @@ function draw() {
 	 * Stops the draw loop.
 	 * @example
 function draw() {
-  circle(frameCount * 5, 100, 50);
+  circle(frameCount * 5, 100, 80);
   noLoop();
 }
 	 */
@@ -109,11 +111,11 @@ function draw() {
 	 * it calls the draw function once.
 	 * @param {number} [n] - number of times to redraw the canvas, default is 1
 	 * @example
-new Q5();
+createCanvas(200, 200);
 noLoop();
 
 function draw() {
-  circle(frameCount * 5, 100, 50);
+  circle(frameCount * 5, 100, 80);
 }
 function mouseClicked() {
   redraw();
@@ -124,11 +126,11 @@ function mouseClicked() {
 	/** ⭐️
 	 * Starts the draw loop again if it was stopped.
 	 * @example
-new Q5();
+createCanvas(200, 200);
 noLoop();
 
 function draw() {
-  circle(frameCount * 5, 100, 50);
+  circle(frameCount * 5, 100, 80);
 }
 function mouseClicked() {
   loop();
@@ -147,7 +149,7 @@ function draw() {
 	if (mouseIsPressed) frameRate(10);
 	else frameRate(60);
 
-	circle(frameCount % 200, 100, 50);
+	circle(frameCount % 200, 100, 80);
 }
 	 * @example
 function draw() {
@@ -239,7 +241,7 @@ function draw() {
 	frameRate(random(30, 60));
 
 	x += deltaTime * 0.2;
-	circle(x % 200, 100, 50);
+	circle(x % 200, 100, 20);
 }
 	 */
 	var deltaTime: number;
@@ -249,15 +251,25 @@ function draw() {
 	/** ⬜️
 	 * Creates a canvas element. If no input parameters are provided, the
 	 * canvas will be the size of the window.
+	 * 
+	 * You can start q5 in top level global mode by running this function
+	 * before the rest of your code.
 	 *
 	 * If this function is not run by the user, a 200x200 canvas will be
 	 * created automatically.
 	 * @param {number} [w] - width of the canvas
 	 * @param {number} [h] - height of the canvas
 	 * @param {Object} [options] - options for the canvas
-	 * @param {boolean} [options.alpha] - whether the canvas should have an alpha channel, default is false
+	 * @param {boolean} [options.alpha] - whether the canvas should have an alpha channel that allows it to be seen through, default is false
 	 * @param {string} [options.colorSpace] - color space of the canvas, either "srgb" or "display-p3", default is "display-p3" for devices that support HDR colors
 	 * @returns {HTMLCanvasElement} created canvas element
+	 * @example
+createCanvas(200, 200, { alpha: true });
+
+function draw() {
+	clear();
+	circle(frameCount % 200, 100, 80);
+}
 	 */
 	function createCanvas(w?: number, h?: number, options?: CanvasRenderingContext2DSettings): HTMLCanvasElement;
 
@@ -268,87 +280,118 @@ function draw() {
 
 	/** ⬜️
 	 * The width of the canvas.
+	 * Can also be accessed via `canvas.w`/`canvas.width`.
 	 */
 	var width: number;
 
 	/** ⬜️
 	 * The height of the canvas.
+	 * Can also be accessed via `canvas.h`/`canvas.height`.
 	 */
 	var height: number;
 
 	/** ⬜️
-	 * Resizes the canvas to the specified width and height.
-	 * @param {number} w - width of the canvas
-	 * @param {number} h - height of the canvas
+	 * Clears the canvas, making every pixel completely transparent.
+	 *
+	 * The canvas can only be seen through if it has an alpha channel though.
 	 */
-	function resizeCanvas(w: number, h: number): void;
+	function clear(): void;
 
 	/** ⬜️
-	 * Sets the pixel density of the canvas.
-	 * @param {number} v - pixel density value
-	 * @returns {number} pixel density
-	 */
-	function pixelDensity(v: number): number;
+	 * Sets the fill color for shapes. The default is white.
+	 * 
+	 * Like the [`color`](https://q5js.org/learn/#color) function, this function can accept colors in a wide range of formats: CSS color string, hex string, grayscale value, and color component values.
+	 * @param {string | Color} color - fill color
+	 * @example
+function draw() {
+	background(200);
 
-	/** ⬜️
-	 * Returns the current display density.
-	 * @returns {number} display density
-	 */
-	function displayDensity(): number;
+  fill('red');
+  circle(80, 80, 80);
 
-	/** ⬜️
-	 * 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
+	fill('lime');
+  square(80, 80, 80);
+}
 	 */
-	function fullscreen(v?: boolean): void | boolean;
+	function fill(color: string | Color): void;
 
 	/** ⬜️
-	 * Any position coordinates or dimensions you use will be scaled based
-	 * on the unit provided to this function.
-	 * @param {number} unit - unit to scale by
+	 * Sets the stroke (outline) color for shapes. The default is black.
+	 * 
+	 * Like the [`color`](https://q5js.org/learn/#color) function, this function can accept colors in a wide range of formats: CSS color string, hex string, grayscale value, and color component values.
+	 * @param {string | Color} color - stroke color
 	 * @example
-new Q5();
-createCanvas(200, 200);
-flexibleCanvas(100);
-// rect will appear in the middle of the canvas
-rect(20, 20, 60, 60);
-	 */
-	function flexibleCanvas(unit: number): void;
-
-	/** ⬜️
-	 * Sets the fill color for shapes.
-	 * @param {string | number} color - fill color
-	 */
-	function fill(color: string | number): void;
+function draw() {
+  background(200);
+	fill(36);
 
-	/** ⬜️
-	 * Sets the stroke (outline) color for shapes.
-	 * @param {string | number} color - stroke color
+  stroke('red');
+  circle(80, 80, 80);
+	stroke('lime');
+  square(80, 80, 80);
+}
 	 */
-	function stroke(color: string | number): void;
+	function stroke(color: string | Color): void;
 
 	/** ⬜️
 	 * After calling this function, shapes will not be filled.
+	 * @example
+function draw() {
+  background(200);
+
+	noFill();
+  stroke('red');
+  circle(80, 80, 80);
+	stroke('lime');
+  square(80, 80, 80);
+}
 	 */
 	function noFill(): void;
 
 	/** ⬜️
 	 * After calling this function, shapes will not have a stroke (outline).
+	 * @example
+function draw() {
+  background(200);
+  fill(36);
+  stroke('red');
+  circle(80, 80, 80);
+
+	noStroke();
+  square(80, 80, 80);
+}
 	 */
 	function noStroke(): void;
 
 	/** ⬜️
 	 * Sets the size of the stroke used for lines and the border around shapes.
 	 * @param {number} weight - size of the stroke in pixels
+	 * @example
+function setup() {
+	createCanvas(200, 200);
+	background(200);
+	stroke('red');
+  circle(50, 100, 80);
+
+  strokeWeight(20);
+  circle(150, 100, 80)
+}
 	 */
 	function strokeWeight(weight: number): void;
 
 	/** ⬜️
-	 * Sets the global opacity, `ctx.globalAlpha`, which
-	 * affects all subsequent drawing operations.
-	 * 0 is completely transparent, 255 is completely opaque.
-	 * @param {number} alpha - opacity level
+	 * Sets the global opacity, which affects all subsequent drawing operations, except `background`. Default is 1, fully opaque.
+	 * @param {number} alpha - opacity level, ranging from 0 to 1
+	 * @example
+function draw() {
+	background(200);
+	
+	opacity(1);
+	circle(80, 80, 80);
+
+	opacity(0.2);
+	square(80, 80, 80);
+}
 	 */
 	function opacity(alpha: number): void;
 
@@ -434,11 +477,50 @@ rect(20, 20, 60, 60);
 	 */
 	function pop(): void;
 
+	/** ⬜️
+	 * Resizes the canvas to the specified width and height.
+	 * @param {number} w - width of the canvas
+	 * @param {number} h - height of the canvas
+	 */
+	function resizeCanvas(w: number, h: number): void;
+
+	/** ⬜️
+	 * Sets the pixel density of the canvas.
+	 * @param {number} v - pixel density value
+	 * @returns {number} pixel density
+	 */
+	function pixelDensity(v: number): number;
+
+	/** ⬜️
+	 * Returns the current display density.
+	 * @returns {number} display density
+	 */
+	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.
+	 * @param {number} unit - unit to scale by
+	 * @example
+createCanvas(200, 200);
+flexibleCanvas(100);
+// rect will appear in the middle of the canvas
+rect(20, 20, 60, 60);
+	 */
+	function flexibleCanvas(unit: number): void;
+
 	/** ⬜️
 	 * Creates a graphics buffer.
 	 * @param {number} w - width
 	 * @param {number} h - height
-	 * @param {CanvasRenderingContext2DSettings} [opt] - options
+	 * @param {Object} [opt] - options
 	 * @returns {Q5} a new Q5 graphics buffer
 	 */
 	function createGraphics(w: number, h: number, opt?: CanvasRenderingContext2DSettings): Q5;
@@ -458,12 +540,12 @@ rect(20, 20, 60, 60);
 	/** 💻
 	 * The `displayMode` function lets you customize how your canvas is presented.
 	 * @param {string} mode -
-	 *   - "normal": no styling to canvas or its parent element
+	 *   - "normal": (default) no styling to canvas or its parent element
 	 *   - "centered": canvas will be centered horizontally and vertically within its parent and if it's display size is bigger than its parent it will not clip
 	 *   - "maxed": canvas will fill the parent element, same as fullscreen for a global mode canvas inside a `main` element
 	 *   - "fullscreen": canvas will fill the screen with letterboxing if necessary to preserve its aspect ratio, like css object-fit contain
 	 * @param {string} renderQuality -
-	 *   - "default": pixelDensity set to displayDensity
+	 *   - "smooth": (default) no changes to the default render quality
 	 *   - "pixelated": pixelDensity set to 1 and various css styles are applied to the canvas to make it render without image smoothing
 	 * @param {number} scale - can be given as a string (for example "x2") or a number
 	 */
@@ -530,16 +612,7 @@ rect(20, 20, 60, 60);
 	 * @param {number} [mode] - drawing mode, can be `PIE`, `CHORD`, or `OPEN`
 	 * @param {number} [detail] - resolution of the arc
 	 */
-	function arc(
-		x: number,
-		y: number,
-		w: number,
-		h: number,
-		start: number,
-		stop: number,
-		mode?: number,
-		detail?: number
-	): void;
+	function arc(x: number, y: number, w: number, h: number, start: number, stop: number, mode?: number, detail?: number): void;
 
 	/** 🧑‍🎨
 	 * Draws a line on the canvas.
@@ -715,16 +788,74 @@ rect(20, 20, 60, 60);
 	// 🌆 image
 
 	/** 🌆
-	 * Applies a filter to the image.
-	 * @param {string} type - type of filter
-	 * @param {number} [value] - optional parameter, depending on filter type
+	 * Loads an image from a URL and optionally runs a callback function.
+	 * @param {string} url - url of the image to load
+	 * @param {(img: any) => void} [cb] - callback function after the image is loaded
+	 * @param {any} [opt] - optional parameters for loading the image
+	 * @example
+createCanvas(200, 200);
+
+let logo = loadImage('/q5js_logo.webp');
+
+function draw() {
+	image(logo, 0, 0, 200, 200);
+}
 	 */
-	function filter(type: string, value?: number): void;
+	function loadImage(url: string, cb?: (img: any) => void, opt?: any): void;
+
+	/** 🌆
+	 * Draws an image to the canvas.
+	 * @param {any} img - image to draw
+	 * @param {number} dx - x position to draw the image at
+	 * @param {number} dy - y position to draw the image at
+	 * @param {number} [dw] - width of the destination image
+	 * @param {number} [dh] - height of the destination image
+	 * @param {number} [sx] - x position in the source to start clipping a subsection from
+	 * @param {number} [sy] - y position in the source to start clipping a subsection from
+	 * @param {number} [sw] - width of the subsection of the source image
+	 * @param {number} [sh] - height of the subsection of the source image
+	 * @example
+createCanvas(200, 200);
+
+let logo = loadImage('/q5js_logo.webp');
+
+function draw() {
+  image(logo, 0, 0, 200, 200, 256, 256, 512, 512);
+}
+	 */
+	function image(img: any, dx: number, dy: number, dw?: number, dh?: number, sx?: number, sy?: number, sw?: number, sh?: number): void;
+
+	/** 🌆
+	 * Sets the image mode, which determines the position and alignment of images drawn on the canvas.
+	 * - `CORNER`: (default) images will be drawn from the top-left corner
+	 * - `CORNERS`: images will be drawn from the top-left to the bottom-right corner
+	 * - `CENTER`: images will be drawn centered at (dx, dy)
+	 * @param {string} mode
+	 * @example
+createCanvas(200, 200);
+
+let logo = loadImage('/q5js_logo.webp');
+
+function draw() {
+	imageMode(CENTER);
+	image(logo, 100, 100, 200, 200);
+}
+	 */
+	function imageMode(mode: string): void;
 
 	/** 🌆
 	 * Resizes the image.
 	 * @param {number} w - new width
 	 * @param {number} h - new height
+	 * @example
+createCanvas(200, 200);
+
+let logo = loadImage('/q5js_logo.webp');
+
+function setup() {
+	logo.resize(128, 128);
+	image(logo, 0, 0, 200, 200);
+}
 	 */
 	function resize(w: number, h: number): void;
 
@@ -734,6 +865,28 @@ rect(20, 20, 60, 60);
 	 */
 	function trim(): Image;
 
+	/** 🌆
+	 * Enables smooth image rendering.
+	 */
+	function smooth(): void;
+
+	/** 🌆
+	 * Disables smooth image rendering for a pixelated look.
+	 */
+	function noSmooth(): void;
+
+	/** 🌆
+	 * Applies a tint (color overlay) to the drawing.
+	 * Tinting affects all subsequent images drawn.
+	 * @param {string | number} color - tint color
+	 */
+	function tint(color: string | number): void;
+
+	/** 🌆
+	 * Images drawn after this function is run will not be tinted.
+	 */
+	function noTint(): void;
+
 	/** 🌆
 	 * Masks the image with another image.
 	 * @param {Image} img - image to use as a mask
@@ -751,25 +904,27 @@ rect(20, 20, 60, 60);
 	/** 🌆
 	 * Displays a region of the image on another region of the image.
 	 * Can be used to create a detail inset, aka a magnifying glass effect.
-	 * @param {number} srcX - x-coordinate of the source region
-	 * @param {number} srcY - y-coordinate of the source region
-	 * @param {number} srcW - width of the source region
-	 * @param {number} srcH - height of the source region
-	 * @param {number} dstX - x-coordinate of the destination region
-	 * @param {number} dstY - y-coordinate of the destination region
-	 * @param {number} dstW - width of the destination region
-	 * @param {number} dstH - height of the destination region
-	 */
-	function inset(
-		srcX: number,
-		srcY: number,
-		srcW: number,
-		srcH: number,
-		dstX: number,
-		dstY: number,
-		dstW: number,
-		dstH: number
-	): void;
+	 * @param {number} sx - x-coordinate of the source region
+	 * @param {number} sy - y-coordinate of the source region
+	 * @param {number} sw - width of the source region
+	 * @param {number} sh - height of the source region
+	 * @param {number} dx - x-coordinate of the destination region
+	 * @param {number} dy - y-coordinate of the destination region
+	 * @param {number} dw - width of the destination region
+	 * @param {number} dh - height of the destination region
+	 * @example
+let logo;
+function preload() {
+  logo = loadImage('/q5js_logo.webp');
+}
+function setup() {
+	logo.inset(256, 256, 512, 512, 0, 0, 200, 200);
+}
+function draw() {
+  
+}
+	 */
+	function inset(sx: number, sy: number, sw: number, sh: number, dx: number, dy: number, dw: number, dh: number): void;
 
 	/** 🌆
 	 * Returns a copy of the image.
@@ -814,76 +969,17 @@ rect(20, 20, 60, 60);
 	function updatePixels(): void;
 
 	/** 🌆
-	 * Enables smooth image rendering.
-	 */
-	function smooth(): void;
-
-	/** 🌆
-	 * Disables smooth image rendering for a pixelated look.
-	 */
-	function noSmooth(): void;
-
-	/** 🌆
-	 * Applies a tint (color overlay) to the drawing.
-	 * Tinting affects all subsequent images drawn.
-	 * @param {string | number} color - tint color
-	 */
-	function tint(color: string | number): void;
-
-	/** 🌆
-	 * Images drawn after this function is run will not be tinted.
-	 */
-	function noTint(): void;
-
-	/** 🌆
-	 * Creates a new image.
-	 * @param {number} w - width
-	 * @param {number} h - height
-	 * @param {any} [opt] - optional settings for the image
-	 * @returns {Image}
-	 */
-	function createImage(w: number, h: number, opt?: any): Image;
-
-	/** 🌆
-	 * Sets the image mode, which determines the position and alignment of images drawn on the canvas.
-	 * - 'CORNER': images will be drawn from the top-left corner (default).
-	 * - 'CORNERS': images will be drawn from the top-left to the bottom-right corner.
-	 * - 'CENTER': images will be drawn centered at (dx, dy).
-	 * @param {string} mode
+	 * Masks the image with another image.
+	 * @param {Image} img - image to use as a mask
 	 */
-	function imageMode(mode: string): void;
-
-	/** 🌆
-	 * Draws an image to the canvas.
-	 * @param {any} img - image to draw
-	 * @param {number} dx - x-coordinate of the destination corner
-	 * @param {number} dy - y-coordinate of the destination corner
-	 * @param {number} [dWidth] - width of the destination image
-	 * @param {number} [dHeight] - height of the destination image
-	 * @param {number} [sx] - x-coordinate of the source corner
-	 * @param {number} [sy] - y-coordinate of the source corner
-	 * @param {number} [sWidth] - width of the source image
-	 * @param {number} [sHeight] - height of the source image
-	 */
-	function image(
-		img: any,
-		dx: number,
-		dy: number,
-		dWidth?: number,
-		dHeight?: number,
-		sx?: number,
-		sy?: number,
-		sWidth?: number,
-		sHeight?: number
-	): void;
+	function mask(img: Image): void;
 
 	/** 🌆
-	 * Loads an image from a URL and optionally runs a callback function.
-	 * @param {string} url - uRL of the image to load
-	 * @param {(img: any) => void} [cb] - callback function after the image is loaded
-	 * @param {any} [opt] - optional parameters for loading the image
+	 * Applies a filter to the image.
+	 * @param {string} type - type of filter
+	 * @param {number} [value] - optional parameter, depending on filter type
 	 */
-	function loadImage(url: string, cb?: (img: any) => void, opt?: any): void;
+	function filter(type: string, value?: number): void;
 
 	/** 🌆
 	 * Converts the image to black and white pixels depending if they are above or below a certain threshold.
@@ -925,6 +1021,15 @@ rect(20, 20, 60, 60);
 	 */
 	const BLUR: 8;
 
+	/** 🌆
+	 * Creates a new image.
+	 * @param {number} w - width
+	 * @param {number} h - height
+	 * @param {any} [opt] - optional settings for the image
+	 * @returns {Image}
+	 */
+	function createImage(w: number, h: number, opt?: any): Image;
+
 	// ✍️ text
 
 	/** ✍️