q5 2.10.3 → 2.10.6

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "q5",
-	"version": "2.10.3",
+	"version": "2.10.6",
 	"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;
 
@@ -1441,14 +1454,14 @@ function setup() {
 	const BOLDITALIC: 'italic bold';
 
 	/** ✍️
-	 * Align text to the center.
+	 * Align text to the left.
 	 */
-	const CENTER: 'center';
+	const LEFT: 'left';
 
 	/** ✍️
-	 * Align text to the left.
+	 * Align text to the center.
 	 */
-	const LEFT: 'left';
+	const CENTER: 'center';
 
 	/** ✍️
 	 * Align text to the right.
@@ -1480,25 +1493,135 @@ 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`.
+	 * 
+	 * 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're not perceptually uniform, meaning colors at the same 
+	 * brightness values may appear lighter or darker depending on the hue.
+	 * 
+	 * The OKLCH format is similar to HSL/HSV but its perceptually
+	 * uniform and supports HDR colors. Use this oklch color picker to 
+	 * explore the color space: https://oklch.com
+	 * 
+	 * `lightness`: 0 to 1
+	 * 
+	 * `chroma`: 0 to 0.3
+	 * 
+	 * `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