q5 2.10.3 → 2.10.5

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "q5",
-	"version": "2.10.3",
+	"version": "2.10.5",
 	"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-2d-canvas.js src/q5-2d-drawing.js src/q5-2d-image.js src/q5-2d-text.js src/q5-ai.js src/q5-color.js src/q5-display.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-2d-canvas.js src/q5-2d-drawing.js src/q5-2d-image.js src/q5-2d-soft-filters.js src/q5-2d-text.js src/q5-ai.js src/q5-color.js src/q5-display.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",
 		"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

@@ -1254,8 +1254,21 @@ function setup() {
 
 	/** 🌆
 	 * Applies a filter to the image.
-	 * @param {string} type - type of filter
+	 * 
+	 * See the documentation for q5's filter constants below for more info.
+	 * 
+	 * If a CSS filter string is provided, it will be applied to the image.
+	 * https://developer.mozilla.org/en-US/docs/Web/CSS/filter
+	 * @param {string} type - type of filter or a CSS filter string
 	 * @param {number} [value] - optional parameter, depending on filter type
+	 * @example
+createCanvas(200, 200);
+let logo = loadImage('/q5js_logo.webp');
+
+function setup() {
+	logo.filter(INVERT);
+	image(logo, 0, 0, 200, 200);
+}
 	 */
 	function filter(type: string, value?: number): void;
 
@@ -1480,25 +1493,132 @@ function setup() {
 
 	// 🎨 color
 
+	/** 🎨
+	 * Creates a new `Color` object. This function can parse different
+	 * color representations depending on the current color mode.
+	 * 
+	 * RGB colors have components `r`/`red`, `g`/`green`, `b`/`blue`,
+	 * and `a`/`alpha`.
+	 * 
+	 * In rgb mode when only one numeric input is provided, it'll
+	 * be interpreted as a grayscale value. If only two numeric inputs
+	 * are provided, they will be used as grayscale and alpha values.
+	 * 
+	 * `fill`, `stroke`, and `background` functions can accept the same
+	 * wide range of inputs as this function.
+	 * @param {string | number | Color | number[]} c0 - first color component, a CSS color string, a `Color` object (to make copy), or an array of components
+	 * @param {number} [c1] - second color component
+	 * @param {number} [c2] - third color component
+	 * @param {number} [c3] - fourth color component (alpha)
+	 * @returns {Color} a new `Color` object
+	 * @example
+createCanvas(200, 200);
+
+let c = color(128);
+
+function draw() {
+	background(c);
+	c.g = (c.g + 1) % 255;
+}
+	 */
+	function color(c0: string | number | Color | number[], c1?: number, c2?: number, c3?: number): Color;
+
 	/** 🎨
 	 * Sets the color mode for the sketch. Changes the type of color object created by color functions.
+	 * 
+	 * In q2d, the default color mode is RGB in legacy integer format.
 	 *
-	 * In WebGPU, the default color mode is 'rgb' in float format.
+	 * In WebGPU, the default color mode is RGB in float format.
+	 * 
+	 * See the documentation for q5's color constants below for more info.
 	 * @param {'rgb' | 'srgb' | 'oklch'} mode - color mode
 	 * @param {1 | 255} format - color format (1 for float, 255 for integer)
+	 * @example
+createCanvas(200, 200);
+
+colorMode(RGB, 1);
+fill(1, 0, 0);
+rect(0, 0, 66, 200);
+fill(0, 1, 0);
+rect(66, 0, 67, 200);
+fill(0, 0, 1);
+rect(133, 0, 67, 200);
+	 * @example
+createCanvas(200, 200);
+
+colorMode(OKLCH);
+
+fill(0.25, 0.15, 0);
+rect(0, 0, 100, 200);
+fill(0.75, 0.15, 0)
+rect(100, 0, 100, 200);
 	 */
 	function colorMode(mode: 'rgb' | 'srgb' | 'oklch', format: 1 | 255): void;
 
 	/** 🎨
-	 * Creates a new `Color` object. It can parse different
-	 * color representations depending on the current `colorMode`.
-	 * @param {string | number | Color | number[]} c0 - first color component, or a string representing the color, or a `Color` object, or an array of components
-	 * @param {number} [c1] - second color component
-	 * @param {number} [c2] - third color component
-	 * @param {number} [c3] - fourth color component (alpha)
-	 * @returns {Color} a new `Color` object
+	 * 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,
+	 * rgb colors are mapped to the full P3 gamut, even when they use the
+	 * legacy integer format.
+	 * @example
+createCanvas(200, 200);
+
+function setup() {
+	background(255, 0, 0);
+}
 	 */
-	function color(c0: string | number | Color | number[], c1?: number, c2?: number, c3?: number): Color;
+	const RGB: 'rgb';
+
+	/** 🎨
+	 * This color mode limits the gamut of rgb colors to sRGB.
+	 * 
+	 * If your display is HDR capable, take a look at the following
+	 * example, note that full red appears less saturated, as it would
+	 * on an SDR display.
+	 * @example
+createCanvas(200, 200);
+
+colorMode(SRGB, 255);
+
+function setup() {
+	background(255, 0, 0);
+}
+	 */
+	const SRGB: 'srgb';
+
+	/** 🎨
+	 * OKLCH colors have components `l`/`lightness`, `c`/`chroma`,
+	 * `h`/`hue`, and `a`/`alpha`.
+	 * 
+	 * You may be familiar with the outdated HSL/HSV color formats,
+	 * which were created in the 1970s to be more intuitive for humans
+	 * to work with than RGB. But due to technical limitations of that
+	 * time, they are not perceptually uniform, meaning the same 
+	 * brightness values may appear lighter or darker depending on the hue.
+	 * 
+	 * The OKLCH format is similar to HSL/HSV but it is perceptually
+	 * uniform and supports a wider gamut (range of colors) than srgb. 
+	 * Every display-p3 color can be represented in OKLCH.
+	 * 
+	 * `lightness`: 0 to 1
+	 * `chroma`: 0 to 0.4
+	 * `hue`: 0 to 360
+	 * `alpha`: 0 to 1
+	 * 
+	 * Note how seamless the hue transitions are in the following example.
+	 * @example
+createCanvas(200, 200);
+colorMode(OKLCH);
+
+function draw() {
+	background(0.7, 0.16, frameCount % 360);
+}
+	 */
+	const OKLCH: 'oklch';
 
 	// 🖲️ input
 

package/q5.js

@@ -143,15 +143,16 @@ function Q5(scope, parent, renderer) {
 	$.getTargetFrameRate = () => $._targetFrameRate || 60;
 	$.getFPS = () => $._fps;
 
+	// shims for compatibility with p5.js libraries
 	$.Element = function (a) {
 		this.elt = a;
 	};
 	$._elements = [];
+	$.describe = () => {};
 
 	$.TWO_PI = $.TAU = Math.PI * 2;
 
 	$.log = $.print = console.log;
-	$.describe = () => {};
 
 	for (let m in Q5.modules) {
 		Q5.modules[m]($, q);
@@ -1270,6 +1271,9 @@ Q5.renderers.q2d.image = ($, q) => {
 
 	Q5.Image ??= Q5Image;
 
+	$._tint = null;
+	let imgData = null;
+
 	$.createImage = (w, h, opt) => {
 		opt ??= {};
 		opt.alpha ??= true;
@@ -1364,7 +1368,7 @@ Q5.renderers.q2d.image = ($, q) => {
 		} else sh *= pd;
 
 		if ($._tint) {
-			if (img._tint != $._tint || img._retint) {
+			if (img._retint || img._tint != $._tint) {
 				img._tintImg ??= $.createImage(img.w, img.h, { pixelDensity: pd });
 
 				if (img._tintImg.width != img.width || img._tintImg.height != img.height) {
@@ -1394,30 +1398,43 @@ Q5.renderers.q2d.image = ($, q) => {
 		$.ctx.drawImage(drawable, sx * pd, sy * pd, sw, sh, dx, dy, dw, dh);
 	};
 
-	$._tint = null;
-	let imgData = null;
-
-	$._softFilter = () => {
-		throw new Error('Load q5-2d-soft-filters.js to use software filters.');
-	};
-
-	$.filter = (type, x) => {
-		if (!$.ctx.filter) return $._softFilter(type, x);
-
-		if (typeof type == 'string') f = type;
-		else if (type == Q5.GRAY) f = `saturate(0%)`;
-		else if (type == Q5.INVERT) f = `invert(100%)`;
-		else if (type == Q5.BLUR) {
-			let r = Math.ceil(x * $._pixelDensity) || 1;
-			f = `blur(${r}px)`;
-		} else if (type == Q5.THRESHOLD) {
-			x ??= 0.5;
-			let b = Math.floor((0.5 / Math.max(x, 0.00001)) * 100);
-			f = `saturate(0%) brightness(${b}%) contrast(1000000%)`;
-		} else return $._softFilter(type, x);
+	$.filter = (type, value) => {
+		if (!$.ctx.filter) return $._softFilter(type, value);
+		let f = '';
+		if (typeof type === 'string') {
+			f = type;
+		} else if (type === Q5.GRAY) {
+			f = `saturate(0%)`;
+		} else if (type === Q5.INVERT) {
+			f = `invert(100%)`;
+		} else if (type === Q5.BLUR) {
+			const radius = Math.ceil(value * $._pixelDensity) || 1;
+			f = `blur(${radius}px)`;
+		} else if (type === Q5.THRESHOLD) {
+			value ??= 0.5;
+			const brightness = Math.floor((0.5 / Math.max(value, 0.00001)) * 100);
+			f = `saturate(0%) brightness(${brightness}%) contrast(1000000%)`;
+		} else if (type === Q5.SEPIA) {
+			f = `sepia(${value ?? 1})`;
+		} else if (type === Q5.BRIGHTNESS) {
+			f = `brightness(${value ?? 1})`;
+		} else if (type === Q5.SATURATION) {
+			f = `saturate(${value ?? 1})`;
+		} else if (type === Q5.CONTRAST) {
+			f = `contrast(${value ?? 1})`;
+		} else if (type === Q5.HUE_ROTATE) {
+			const unit = $._angleMode === 0 ? 'rad' : 'deg';
+			f = `hue-rotate(${value}${unit})`;
+		} else {
+			$._softFilter(type, value);
+			return;
+		}
 
 		$.ctx.filter = f;
-		$.ctx.drawImage($.canvas, 0, 0, $.canvas.w, $.canvas.h);
+		if ($.ctx.filter == 'none') {
+			throw new Error(`Invalid filter format: ${type}`);
+		}
+		$.ctx.drawImage($.canvas, 0, 0, $.canvas.width, $.canvas.height);
 		$.ctx.filter = 'none';
 		$._retint = true;
 	};
@@ -1570,6 +1587,156 @@ Q5.POSTERIZE = 5;
 Q5.DILATE = 6;
 Q5.ERODE = 7;
 Q5.BLUR = 8;
+Q5.SEPIA = 9;
+Q5.BRIGHTNESS = 10;
+Q5.SATURATION = 11;
+Q5.CONTRAST = 12;
+Q5.HUE_ROTATE = 13;
+/* software implementation of image filters */
+Q5.renderers.q2d.soft_filters = ($) => {
+	let u = null; // uint8 temporary buffer
+
+	function ensureBuf() {
+		let l = $.canvas.width * $.canvas.height * 4;
+		if (!u || u.length != l) u = new Uint8ClampedArray(l);
+	}
+
+	function initSoftFilters() {
+		$._filters = [];
+		$._filters[Q5.THRESHOLD] = (d, thresh) => {
+			if (thresh === undefined) thresh = 127.5;
+			else thresh *= 255;
+			for (let i = 0; i < d.length; i += 4) {
+				const gray = 0.2126 * d[i] + 0.7152 * d[i + 1] + 0.0722 * d[i + 2];
+				d[i] = d[i + 1] = d[i + 2] = gray >= thresh ? 255 : 0;
+			}
+		};
+		$._filters[Q5.GRAY] = (d) => {
+			for (let i = 0; i < d.length; i += 4) {
+				const gray = 0.2126 * d[i] + 0.7152 * d[i + 1] + 0.0722 * d[i + 2];
+				d[i] = d[i + 1] = d[i + 2] = gray;
+			}
+		};
+		$._filters[Q5.OPAQUE] = (d) => {
+			for (let i = 0; i < d.length; i += 4) {
+				d[i + 3] = 255;
+			}
+		};
+		$._filters[Q5.INVERT] = (d) => {
+			for (let i = 0; i < d.length; i += 4) {
+				d[i] = 255 - d[i];
+				d[i + 1] = 255 - d[i + 1];
+				d[i + 2] = 255 - d[i + 2];
+			}
+		};
+		$._filters[Q5.POSTERIZE] = (d, lvl = 4) => {
+			let lvl1 = lvl - 1;
+			for (let i = 0; i < d.length; i += 4) {
+				d[i] = (((d[i] * lvl) >> 8) * 255) / lvl1;
+				d[i + 1] = (((d[i + 1] * lvl) >> 8) * 255) / lvl1;
+				d[i + 2] = (((d[i + 2] * lvl) >> 8) * 255) / lvl1;
+			}
+		};
+		$._filters[Q5.DILATE] = (d, func) => {
+			func ??= Math.max;
+			ensureBuf();
+			u.set(d);
+			let [w, h] = [$.canvas.width, $.canvas.height];
+			for (let i = 0; i < h; i++) {
+				for (let j = 0; j < w; j++) {
+					let l = 4 * Math.max(j - 1, 0);
+					let r = 4 * Math.min(j + 1, w - 1);
+					let t = 4 * Math.max(i - 1, 0) * w;
+					let b = 4 * Math.min(i + 1, h - 1) * w;
+					let oi = 4 * i * w;
+					let oj = 4 * j;
+					for (let k = 0; k < 4; k++) {
+						let kt = k + t;
+						let kb = k + b;
+						let ko = k + oi;
+						d[oi + oj + k] = func(u[kt + oj], u[ko + l], u[ko + oj], u[ko + r], u[kb + oj]);
+					}
+				}
+			}
+		};
+		$._filters[Q5.ERODE] = (d) => {
+			$._filters[Q5.DILATE](d, Math.min);
+		};
+		$._filters[Q5.BLUR] = (d, r) => {
+			r = r || 1;
+			r = Math.floor(r * $._pixelDensity);
+			ensureBuf();
+			u.set(d);
+
+			let ksize = r * 2 + 1;
+
+			function gauss(ksize) {
+				let im = new Float32Array(ksize);
+				let sigma = 0.3 * r + 0.8;
+				let ss2 = sigma * sigma * 2;
+				for (let i = 0; i < ksize; i++) {
+					let x = i - ksize / 2;
+					let z = Math.exp(-(x * x) / ss2) / (2.5066282746 * sigma);
+					im[i] = z;
+				}
+				return im;
+			}
+
+			let kern = gauss(ksize);
+			let [w, h] = [$.canvas.width, $.canvas.height];
+			for (let i = 0; i < h; i++) {
+				for (let j = 0; j < w; j++) {
+					let s0 = 0,
+						s1 = 0,
+						s2 = 0,
+						s3 = 0;
+					for (let k = 0; k < ksize; k++) {
+						let jk = Math.min(Math.max(j - r + k, 0), w - 1);
+						let idx = 4 * (i * w + jk);
+						s0 += u[idx] * kern[k];
+						s1 += u[idx + 1] * kern[k];
+						s2 += u[idx + 2] * kern[k];
+						s3 += u[idx + 3] * kern[k];
+					}
+					let idx = 4 * (i * w + j);
+					d[idx] = s0;
+					d[idx + 1] = s1;
+					d[idx + 2] = s2;
+					d[idx + 3] = s3;
+				}
+			}
+			u.set(d);
+			for (let i = 0; i < h; i++) {
+				for (let j = 0; j < w; j++) {
+					let s0 = 0,
+						s1 = 0,
+						s2 = 0,
+						s3 = 0;
+					for (let k = 0; k < ksize; k++) {
+						let ik = Math.min(Math.max(i - r + k, 0), h - 1);
+						let idx = 4 * (ik * w + j);
+						s0 += u[idx] * kern[k];
+						s1 += u[idx + 1] * kern[k];
+						s2 += u[idx + 2] * kern[k];
+						s3 += u[idx + 3] * kern[k];
+					}
+					let idx = 4 * (i * w + j);
+					d[idx] = s0;
+					d[idx + 1] = s1;
+					d[idx + 2] = s2;
+					d[idx + 3] = s3;
+				}
+			}
+		};
+	}
+
+	$._softFilter = (typ, x) => {
+		if (!$._filters) initSoftFilters();
+		let imgData = $.ctx._getImageData(0, 0, $.canvas.width, $.canvas.height);
+		$._filters[typ](imgData.data, x);
+		$.ctx.putImageData(imgData, 0, 0);
+	};
+};
 Q5.renderers.q2d.text = ($, q) => {
 	$._textAlign = 'left';
 	$._textBaseline = 'alphabetic';
@@ -1899,6 +2066,7 @@ Q5.modules.ai = ($) => {
 };
 Q5.modules.color = ($, q) => {
 	$.RGB = $.RGBA = $._colorMode = 'rgb';
+	$.SRGB = 'srgb';
 	$.OKLCH = 'oklch';
 
 	$.colorMode = (mode, format) => {
@@ -1909,7 +2077,6 @@ Q5.modules.color = ($, q) => {
 		if (mode == 'oklch') {
 			q.Color = Q5.ColorOKLCH;
 		} else {
-			let srgb = $.canvas.colorSpace == 'srgb';
 			if ($._colorFormat == 255) {
 				q.Color = srgb ? Q5.ColorRGBA_8 : Q5.ColorRGBA_P3_8;
 			} else {
@@ -1993,10 +2160,12 @@ Q5.modules.color = ($, q) => {
 		return new C(c0, c1, c2, c3);
 	};
 
+	// deprecated
 	$.red = (c) => c.r;
 	$.green = (c) => c.g;
 	$.blue = (c) => c.b;
 	$.alpha = (c) => c.a;
+
 	$.lightness = (c) => {
 		if (c.l) return c.l;
 		return ((0.2126 * c.r + 0.7152 * c.g + 0.0722 * c.b) * 100) / 255;
@@ -2054,9 +2223,43 @@ Q5.ColorOKLCH = class extends Q5.Color {
 		this.h = h;
 		this.a = a ?? 1;
 	}
+	get levels() {
+		return [this.l, this.c, this.h, this.a];
+	}
+	equals(c) {
+		return c && this.l == c.l && this.c == c.c && this.h == c.h && this.a == c.a;
+	}
+	isSameColor(c) {
+		return c && this.l == c.l && this.c == c.c && this.h == c.h;
+	}
 	toString() {
 		return `oklch(${this.l} ${this.c} ${this.h} / ${this.a})`;
 	}
+
+	get lightness() {
+		return this.l;
+	}
+	set lightness(v) {
+		this.l = v;
+	}
+	get chroma() {
+		return this.c;
+	}
+	set chroma(v) {
+		this.c = v;
+	}
+	get hue() {
+		return this.h;
+	}
+	set hue(v) {
+		this.h = v;
+	}
+	get alpha() {
+		return this.a;
+	}
+	set alpha(v) {
+		this.a = v;
+	}
 };
 
 Q5.ColorRGBA = class extends Q5.Color {
@@ -2070,9 +2273,39 @@ Q5.ColorRGBA = class extends Q5.Color {
 	get levels() {
 		return [this.r, this.g, this.b, this.a];
 	}
+	equals(c) {
+		return c && this.r == c.r && this.g == c.g && this.b == c.b && this.a == c.a;
+	}
+	isSameColor(c) {
+		return c && this.r == c.r && this.g == c.g && this.b == c.b;
+	}
 	toString() {
 		return `color(srgb ${this.r} ${this.g} ${this.b} / ${this.a})`;
 	}
+	get red() {
+		return this.r;
+	}
+	set red(v) {
+		this.r = v;
+	}
+	get green() {
+		return this.g;
+	}
+	set green(v) {
+		this.g = v;
+	}
+	get blue() {
+		return this.b;
+	}
+	set blue(v) {
+		this.b = v;
+	}
+	get alpha() {
+		return this.a;
+	}
+	set alpha(v) {
+		this.a = v;
+	}
 };
 
 Q5.ColorRGBA_P3 = class extends Q5.ColorRGBA {
@@ -2086,6 +2319,7 @@ Q5.ColorRGBA_8 = class extends Q5.ColorRGBA {
 	constructor(r, g, b, a) {
 		super(r, g, b, a ?? 255);
 	}
+	// deprecated set functions for backwards compatibility
 	setRed(v) {
 		this.r = v;
 	}
@@ -2098,9 +2332,6 @@ Q5.ColorRGBA_8 = class extends Q5.ColorRGBA {
 	setAlpha(v) {
 		this.a = v;
 	}
-	get levels() {
-		return [this.r, this.g, this.b, this.a];
-	}
 	toString() {
 		return `rgb(${this.r} ${this.g} ${this.b} / ${this.a / 255})`;
 	}