q5 4.0.1 → 4.2.0

package/README.md

@@ -2,17 +2,13 @@
 
 ## Visit [q5js.org](https://q5js.org)! 💫
 
-- inspired by [p5.js][] and [Processing][] ⭐️
-- performance optimized for interactive art 🚀
-- lightning fast [WebGPU renderer](https://github.com/q5js/q5.js/wiki/q5-WebGPU-renderer) ⚡️
+q5 was designed to make creative coding fun and accessible for educators, artists, designers, and beginners. 🤝
+
+- 100x faster than [p5.js][] ⚡️
 - beginner friendly [documentation](https://q5js.org/learn) 📚
 - compatible with popular addons, including [p5.sound][], [ml5.js][], and [p5play][] 🎮
 - no dependencies, ~140kb minified 📦
-- free to use under the LGPL 🆓
-
-q5 was designed to make creative coding fun and accessible for educators, artists, designers, and beginners. 🤝
-
-Familiar with p5? You'll be right at home with q5. It's like getting a free computer upgrade! 🖥️
+- free and open source 🆓
 
 ```js
 await Canvas(200);
@@ -21,23 +17,10 @@ circle(0, 0, 80);
 
 ## Documentation
 
-Browse the [q5 reference pages](https://q5js.org/learn) to learn how to use q5.js.
+The [q5 learn pages](https://q5js.org/learn) are organized into sections with interactive mini-examples.
 
 See the [wiki](https://github.com/q5js/q5.js/wiki) for extended documentation.
 
-Use the [q5.d.ts](q5.d.ts) file in Visual Studio Code to get autocompletion and inline hover-over documentation. Simply add this `jsconfig.json` file to your project folder:
-
-```json
-{
-	"compilerOptions": {
-		"target": "ESNext"
-	},
-	"typeAcquisition": {
-		"include": ["node_modules/q5"]
-	}
-}
-```
-
 ## Support q5 💙
 
 q5 is open source and anyone can use it for free under the terms of the LGPL. 🎉
@@ -54,7 +37,7 @@ All contributors must agree to the [code of conduct](CODE_OF_CONDUCT.md).
 
 ## Licensing
 
-q5.js was created by [Quinton Ashley](https://github.com/quinton-ashley) and [contributors](https://github.com/q5js/q5.js/graphs/contributors). It is open source licensed under the LGPLv3.
+q5.js was created by [Quinton Ashley](https://github.com/quinton-ashley) and [contributors](https://github.com/q5js/q5.js/graphs/contributors). It is free to use and open source licensed under the LGPLv3.
 
 @LingDong- created the original q5xjs library which is Unlicense (public domain) licensed.
 

package/deno.json

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

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "q5",
-	"version": "4.0.1",
+	"version": "4.2.0",
 	"description": "Beginner friendly graphics powered by WebGPU, optimized for interactive art!",
 	"author": "quinton-ashley",
 	"contributors": [
@@ -32,7 +32,6 @@
 		"bundle": "cat src/q5-core.js src/q5-canvas.js src/q5-c2d-canvas.js src/q5-c2d-shapes.js src/q5-c2d-image.js src/q5-c2d-soft-filters.js src/q5-c2d-text.js src/q5-color.js src/q5-display.js src/q5-dom.js src/q5-fes.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.js src/q5-lang.js > q5.js",
 		"min": "terser q5.js --compress ecma=2025 --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",
 		"tests": "jest test",
 		"bld": "node lang/build.js",
 		"dts": "node lang/types.js",

package/q5.d.ts

@@ -540,7 +540,7 @@ declare global {
 	 * and the bottom right pixel's data is at the end, going from
 	 * left to right and top to bottom.
 	 */
-	var pixels: number[];
+	let pixels: number[];
 
 	/** 🌆
 	 * Loads pixel data into `pixels` from the canvas or image.
@@ -1329,25 +1329,25 @@ declare global {
 	function touchMoved(): void;
 
 	/** 🖲
-	 * Object containing all current pointers within the
+	 * Array containing all current pointers within the
 	 * browser window.
 	 * 
-	 * This includes mouse, touch, and pen pointers.
+	 * This includes mouse, pen, and touch interactions.
 	 * 
 	 * Each pointer is an object with
 	 * `event`, `x`, and `y` properties.
-	 * The `event` property contains the original
-	 * [PointerEvent](https://developer.mozilla.org/docs/Web/API/PointerEvent).
+	 * 
+	 * The `event` property contains the most recent
+	 * [PointerEvent](https://developer.mozilla.org/docs/Web/API/PointerEvent) associated with the pointer, which includes additional information such as the pointer type.
 	 * @example
 	 * q5.draw = function () {
 	 * 	background(0.8);
-	 * 	for (let pointerID in pointers) {
-	 * 		let pointer = pointers[pointerID];
+	 * 	for (let pointer of pointers) {
 	 * 		circle(pointer.x, pointer.y, 100);
 	 * 	}
 	 * };
 	 */
-	let pointers: {};
+	let pointers: [];
 
 	/** 🖲
 	 * Sets the cursor to a [CSS cursor type](https://developer.mozilla.org/docs/Web/CSS/cursor) or image.
@@ -1378,7 +1378,8 @@ declare global {
 	 * 
 	 * Return true to allow the default behavior of scrolling the page.
 	 * @example
-	 * let x = (y = 0);
+	 * let x = 0;
+	 * let y = 0;
 	 * q5.draw = function () {
 	 * 	circle(x, y, 10);
 	 * };
@@ -1390,6 +1391,28 @@ declare global {
 	 */
 	function mouseWheel(event: any): void;
 
+	/** 🖲
+	 * Distance the mouse has moved since the last frame in the horizontal direction.
+	 * @example
+	 * q5.draw = function () {
+	 * 	background(0.8);
+	 * 	if (movedX > 0) text('>>', 0, 0);
+	 * 	if (movedX < 0) text('<<', 0, 0);
+	 * };
+	 */
+	let movedX: number;
+
+	/** 🖲
+	 * Distance the mouse has moved since the last frame in the vertical direction.
+	 * @example
+	 * q5.draw = function () {
+	 * 	background(0.8);
+	 * 	if (movedY > 0) text('vv', 0, 0);
+	 * 	if (movedY < 0) text('^^', 0, 0);
+	 * };
+	 */
+	let movedY: number;
+
 	/** 🖲
 	 * Requests that the pointer be locked to the document body, hiding
 	 * the cursor and allowing for unlimited movement.
@@ -1949,7 +1972,7 @@ declare global {
 	 * 
 	 * Not available in q5 WebGPU.
 	 */
-	var ctx: CanvasRenderingContext2D;
+	let ctx: CanvasRenderingContext2D;
 
 	/** 💅
 	 * Checks if a given point is within the current path's fill area.
@@ -2202,7 +2225,7 @@ declare global {
 	 * 	text(windowWidth, 0, 0);
 	 * };
 	 */
-	var windowWidth: number;
+	let windowWidth: number;
 
 	/** 💻
 	 * The height of the window.
@@ -2214,7 +2237,7 @@ declare global {
 	 * 	text(windowHeight, 0, 0);
 	 * };
 	 */
-	var windowHeight: number;
+	let windowHeight: number;
 
 	/** 💻
 	 * The width of the canvas.
@@ -2222,7 +2245,7 @@ declare global {
 	 * await Canvas(200, 120);
 	 * circle(0, 0, width);
 	 */
-	var width: number;
+	let width: number;
 
 	/** 💻
 	 * The height of the canvas.
@@ -2230,7 +2253,7 @@ declare global {
 	 * await Canvas(200, 80);
 	 * circle(0, 0, height);
 	 */
-	var height: number;
+	let height: number;
 
 	/** 💻
 	 * Half the width of the canvas.
@@ -2238,7 +2261,7 @@ declare global {
 	 * await Canvas(200, 80);
 	 * circle(0, 0, halfWidth);
 	 */
-	var halfWidth: number;
+	let halfWidth: number;
 
 	/** 💻
 	 * Half the height of the canvas.
@@ -2246,12 +2269,12 @@ declare global {
 	 * await Canvas(200, 80);
 	 * circle(0, 0, halfHeight);
 	 */
-	var halfHeight: number;
+	let halfHeight: number;
 
 	/** 💻
 	 * The canvas element associated with the Q5 instance.
 	 */
-	var canvas: HTMLCanvasElement;
+	let canvas: HTMLCanvasElement;
 
 	/** 💻
 	 * Resizes the canvas to the specified width and height.
@@ -2279,7 +2302,7 @@ declare global {
 	 * 	text(frameCount, -92, 20);
 	 * };
 	 */
-	var frameCount: number;
+	let frameCount: number;
 
 	/** 💻
 	 * Stops the draw loop.
@@ -2445,7 +2468,7 @@ declare global {
 	 * 	circle(x, 0, 20);
 	 * };
 	 */
-	var deltaTime: number;
+	let deltaTime: number;
 
 	// 🧮 math
 
@@ -3070,7 +3093,7 @@ declare global {
 	 * @example
 	 * await Canvas(200, 100);
 	 * 
-	 * let img = createImg('/assets/p5play_logo.webp');
+	 * let img = createImg('/assets/q5play_logo.avif');
 	 * img.position(0, 0).size(100, 100);
 	 */
 	function createImg(src: string): HTMLImageElement;
@@ -3348,7 +3371,7 @@ declare global {
 	/** 🎞
 	 * True if the canvas is currently being recorded.
 	 */
-	var recording: boolean;
+	let recording: boolean;
 
 	// 🛠 utilities
 
@@ -3874,22 +3897,22 @@ declare global {
 	 */
 
 	/** ⚡
-	 * Creates a shader that q5 can use to draw shapes.
+	 * Creates a shader that q5's WebGPU renderer can use.
+	 * 
+	 * If `type` is not specified, this function customizes a copy of the [default shapes shader](https://github.com/q5js/q5.js/blob/main/src/shaders/shapes.wgsl), which affects the following functions:
 	 * 
-	 * Affects the following functions:
 	 * `triangle`, `quad`, `plane`,
 	 * `curve`, `bezier`, `beginShape`/`endShape`,
 	 * and `background` (unless an image is used).
 	 * 
-	 * Use this function to customize a copy of the
-	 * [default shapes shader](https://github.com/q5js/q5.js/blob/main/src/shaders/shapes.wgsl).
-	 * 
 	 * For more information on the vertex and fragment function
 	 * input parameters, data, and helper functions made available for use
 	 * in your custom shader code, read the
 	 * ["Custom Shaders in q5 WebGPU"](https://github.com/q5js/q5.js/wiki/Custom-Shaders-in-q5-WebGPU)
 	 * wiki page.
 	 * @param {string} code WGSL shader code excerpt
+	 * @param {string} [type] defaults to "shapes"
+	 * @param {Float32Array} [data] only for use with [fully custom shaders](https://github.com/q5js/q5.js/wiki/Custom-Shaders-in-q5-WebGPU#fully-custom-shaders)
 	 * @returns {GPUShaderModule} a shader program
 	 * @example
 	 * await Canvas(200);
@@ -3928,7 +3951,7 @@ declare global {
 	 * 	triangle(-50, -50, 0, 50, 50, -50);
 	 * };
 	 */
-	function createShader(code: string): GPUShaderModule;
+	function createShader(code: string, type?: string, data?: Float32Array | {}): GPUShaderModule;
 
 	/** ⚡
 	 * A plane is a centered rectangle with no stroke.
@@ -4049,6 +4072,7 @@ declare global {
 	 * 	shader(grate);
 	 * 	image(logo, 0, 0, 180, 180);
 	 * };
+	 * //
 	 */
 	function createImageShader(code: string): GPUShaderModule;
 
@@ -4206,7 +4230,7 @@ declare global {
 		 * A WebGPU memory allocation limit.
 		 * 
 		 * The maximum number of transformation matrixes
-		 * that can be used in a single draw call.
+		 * that can be used per frame.
 		 */
 		static MAX_TRANSFORMS: number;
 
@@ -4215,7 +4239,7 @@ declare global {
 		 * 
 		 * The maximum number of rectangles
 		 * (calls to `rect`, `square`, `capsule`)
-		 * that can be drawn in a single draw call.
+		 * that can be drawn per frame.
 		 */
 		static MAX_RECTS: number;
 
@@ -4224,7 +4248,7 @@ declare global {
 		 * 
 		 * The maximum number of ellipses
 		 * (calls to `ellipse`, `circle`, and `arc`)
-		 * that can be drawn in a single draw call.
+		 * that can be drawn per frame.
 		 */
 		static MAX_ELLIPSES: number;
 
@@ -4232,7 +4256,7 @@ declare global {
 		 * A WebGPU memory allocation limit.
 		 * 
 		 * The maximum number of text characters
-		 * that can be drawn in a single draw call.
+		 * that can be drawn per frame.
 		 */
 		static MAX_CHARS: number;
 
@@ -4240,7 +4264,7 @@ declare global {
 		 * A WebGPU memory allocation limit.
 		 * 
 		 * The maximum number of separate calls to `text`
-		 * that can be drawn in a single draw call.
+		 * that can be drawn per frame.
 		 */
 		static MAX_TEXTS: number;
 
@@ -4264,14 +4288,6 @@ declare global {
 		 * Inside the function, `this` refers to the Q5 instance.
 		 * @param {string} lifecycle 'init', 'presetup', 'postsetup', 'predraw', 'postdraw', or 'remove'
 		 * @param {Function} fn The function to be run at the specified lifecycle phase.
-		 * @example
-		 * Q5.addHook('predraw', function () {
-		 * 	this.background('cyan');
-		 * });
-		 * 
-		 * q5.draw = function () {
-		 * 	circle(mouseX, mouseY, 80);
-		 * };
 		 */
 		static addHook(lifecycle: string, fn: Function): void;
 
@@ -4294,7 +4310,7 @@ declare global {
 		/** ⚙
 		 * The q5 draw function is run 60 times per second by default.
 		 */
-		draw(): void;
+		static draw(): void;
 
 		/** ⚙
 		 * Runs after each `draw` function call and post-draw q5 addon processes, if any.
@@ -4304,13 +4320,199 @@ declare global {
 		 * addons like p5play that auto-draw to the canvas after the `draw`
 		 * function is run.
 		 */
-		postProcess(): void;
-		update(): void; //-
-
-		drawFrame(): void; //-
-
-		static Image: {
-			new (w: number, h: number, opt?: any): Q5.Image;
+		static postProcess(): void;
+		//-
+			static update(): void;
+			update(): void;
+			draw(): void;
+			postProcess(): void;
+			Canvas: typeof Canvas;
+			log: typeof log;
+			circle: typeof circle;
+			ellipse: typeof ellipse;
+			rect: typeof rect;
+			square: typeof square;
+			point: typeof point;
+			line: typeof line;
+			capsule: typeof capsule;
+			rectMode: typeof rectMode;
+			ellipseMode: typeof ellipseMode;
+			loadImage: typeof loadImage;
+			image: typeof image;
+			imageMode: typeof imageMode;
+			defaultImageScale: typeof defaultImageScale;
+			resize: typeof resize;
+			trim: typeof trim;
+			smooth: typeof smooth;
+			noSmooth: typeof noSmooth;
+			tint: typeof tint;
+			noTint: typeof noTint;
+			mask: typeof mask;
+			copy: typeof copy;
+			inset: typeof inset;
+			get: typeof get;
+			set: typeof set;
+			loadPixels: typeof loadPixels;
+			updatePixels: typeof updatePixels;
+			filter: typeof filter;
+			createImage: typeof createImage;
+			createGraphics: typeof createGraphics;
+			text: typeof text;
+			loadFont: typeof loadFont;
+			textFont: typeof textFont;
+			textSize: typeof textSize;
+			textLeading: typeof textLeading;
+			textStyle: typeof textStyle;
+			textAlign: typeof textAlign;
+			textWeight: typeof textWeight;
+			textWidth: typeof textWidth;
+			textAscent: typeof textAscent;
+			textDescent: typeof textDescent;
+			createTextImage: typeof createTextImage;
+			textImage: typeof textImage;
+			textToPoints: typeof textToPoints;
+			nf: typeof nf;
+			mousePressed: typeof mousePressed;
+			mouseReleased: typeof mouseReleased;
+			mouseMoved: typeof mouseMoved;
+			mouseDragged: typeof mouseDragged;
+			doubleClicked: typeof doubleClicked;
+			keyIsDown: typeof keyIsDown;
+			keyPressed: typeof keyPressed;
+			keyReleased: typeof keyReleased;
+			touchStarted: typeof touchStarted;
+			touchEnded: typeof touchEnded;
+			touchMoved: typeof touchMoved;
+			cursor: typeof cursor;
+			noCursor: typeof noCursor;
+			mouseWheel: typeof mouseWheel;
+			pointerLock: typeof pointerLock;
+			color: typeof color;
+			colorMode: typeof colorMode;
+			background: typeof background;
+			fill: typeof fill;
+			stroke: typeof stroke;
+			noFill: typeof noFill;
+			noStroke: typeof noStroke;
+			strokeWeight: typeof strokeWeight;
+			opacity: typeof opacity;
+			shadow: typeof shadow;
+			noShadow: typeof noShadow;
+			shadowBox: typeof shadowBox;
+			blendMode: typeof blendMode;
+			strokeCap: typeof strokeCap;
+			strokeJoin: typeof strokeJoin;
+			erase: typeof erase;
+			noErase: typeof noErase;
+			pushStyles: typeof pushStyles;
+			popStyles: typeof popStyles;
+			clear: typeof clear;
+			inFill: typeof inFill;
+			inStroke: typeof inStroke;
+			translate: typeof translate;
+			rotate: typeof rotate;
+			scale: typeof scale;
+			shearX: typeof shearX;
+			shearY: typeof shearY;
+			applyMatrix: typeof applyMatrix;
+			resetMatrix: typeof resetMatrix;
+			pushMatrix: typeof pushMatrix;
+			popMatrix: typeof popMatrix;
+			push: typeof push;
+			pop: typeof pop;
+			displayMode: typeof displayMode;
+			fullscreen: typeof fullscreen;
+			resizeCanvas: typeof resizeCanvas;
+			noLoop: typeof noLoop;
+			redraw: typeof redraw;
+			loop: typeof loop;
+			frameRate: typeof frameRate;
+			getTargetFrameRate: typeof getTargetFrameRate;
+			getFPS: typeof getFPS;
+			pixelDensity: typeof pixelDensity;
+			displayDensity: typeof displayDensity;
+			random: typeof random;
+			jit: typeof jit;
+			noise: typeof noise;
+			dist: typeof dist;
+			map: typeof map;
+			angleMode: typeof angleMode;
+			radians: typeof radians;
+			degrees: typeof degrees;
+			lerp: typeof lerp;
+			constrain: typeof constrain;
+			norm: typeof norm;
+			abs: typeof abs;
+			round: typeof round;
+			ceil: typeof ceil;
+			floor: typeof floor;
+			min: typeof min;
+			max: typeof max;
+			sin: typeof sin;
+			cos: typeof cos;
+			tan: typeof tan;
+			mag: typeof mag;
+			asin: typeof asin;
+			acos: typeof acos;
+			atan: typeof atan;
+			atan2: typeof atan2;
+			pow: typeof pow;
+			fract: typeof fract;
+			sq: typeof sq;
+			sqrt: typeof sqrt;
+			loge: typeof loge;
+			exp: typeof exp;
+			randomSeed: typeof randomSeed;
+			randomGenerator: typeof randomGenerator;
+			randomGaussian: typeof randomGaussian;
+			randomExponential: typeof randomExponential;
+			noiseMode: typeof noiseMode;
+			noiseSeed: typeof noiseSeed;
+			noiseDetail: typeof noiseDetail;
+			loadSound: typeof loadSound;
+			loadAudio: typeof loadAudio;
+			getAudioContext: typeof getAudioContext;
+			userStartAudio: typeof userStartAudio;
+			createEl: typeof createEl;
+			createA: typeof createA;
+			createButton: typeof createButton;
+			createCheckbox: typeof createCheckbox;
+			createColorPicker: typeof createColorPicker;
+			createImg: typeof createImg;
+			createInput: typeof createInput;
+			createP: typeof createP;
+			createRadio: typeof createRadio;
+			createSelect: typeof createSelect;
+			createSlider: typeof createSlider;
+			createVideo: typeof createVideo;
+			createCapture: typeof createCapture;
+			findEl: typeof findEl;
+			findEls: typeof findEls;
+			createRecorder: typeof createRecorder;
+			record: typeof record;
+			pauseRecording: typeof pauseRecording;
+			deleteRecording: typeof deleteRecording;
+			saveRecording: typeof saveRecording;
+			load: typeof load;
+			save: typeof save;
+			loadText: typeof loadText;
+			loadJSON: typeof loadJSON;
+			loadCSV: typeof loadCSV;
+			loadXML: typeof loadXML;
+			loadAll: typeof loadAll;
+			disablePreload: typeof disablePreload;
+			shuffle: typeof shuffle;
+			storeItem: typeof storeItem;
+			getItem: typeof getItem;
+			removeItem: typeof removeItem;
+			clearStorage: typeof clearStorage;
+			year: typeof year;
+			day: typeof day;
+			hour: typeof hour;
+			minute: typeof minute;
+			second: typeof second;
+			static Image: {
+				new (w: number, h: number, opt?: any): Q5.Image;
 			};
 
 	}
@@ -4319,7 +4521,20 @@ declare global {
 		interface Image {
 			width: number;
 			height: number;
+			copy(): Q5.Image;
+			get(x: number, y: number, w?: number, h?: number): Q5.Image | number[];
+			set(x: number, y: number, val: any): void;
+			resize(w: number, h: number): void;
+			mask(img: Q5.Image): void;
+			trim(): Q5.Image;
+			filter(type: string, value?: number): void;
+			loadPixels(): void;
+			updatePixels(): void;
+			save(fileName?: string): void;
 		}
+
+		export import Color = globalThis.Color;
+		export import Vector = globalThis.Vector;
 	}
 
 }