q5 2.21.5 → 2.22.0

package/README.md

@@ -68,6 +68,16 @@ https://webgpu.github.io/webgpu-samples/?sample=textRenderingMsdf
 WebGPU blendMode:
 https://webgpufundamentals.org/webgpu/lessons/webgpu-transparency.html
 
+HSLtoRGB:
+https://stackoverflow.com/a/64090995/3792062
+
+HSBtoHSL:
+https://stackoverflow.com/a/66469632/3792062
+
+OKLCHtoRGB:
+https://gist.github.com/dkaraush/65d19d61396f5f3cd8ba7d1b4b3c9432
+https://github.com/color-js/color.js/blob/main/src/spaces/oklch.js
+
 A JS Implementation of Ziggurat Algorithm:
 http://ziggurat.glitch.me/
 

package/deno.json

@@ -1,8 +1,8 @@
 {
 	"name": "@q5/q5",
-	"version": "2.21.0",
+	"version": "2.22.0",
 	"license": "LGPL-3.0",
-	"description": "A sequel to p5.js that's optimized for interactive art",
+	"description": "Beginner friendly graphics powered by WebGPU and optimized for interactive art!",
 	"author": "quinton-ashley",
 	"exports": "./q5-deno-server.js",
 	"types": "./q5-deno-server.d.ts",

package/package.json

@@ -1,7 +1,7 @@
 {
 	"name": "q5",
-	"version": "2.21.5",
-	"description": "Beginner friendly graphics framework that's powered by WebGPU and optimized for interactive art!",
+	"version": "2.22.0",
+	"description": "Beginner friendly graphics powered by WebGPU and optimized for interactive art!",
 	"author": "quinton-ashley",
 	"contributors": [
 		"Tezumie",

package/q5.d.ts

@@ -8,17 +8,12 @@ declare global {
 	// ⭐️ core
 
 	/** ⭐️
-	 * Welcome to q5's documentation! ☺️
+	 * Welcome to q5's documentation! 🤩
 	 * 
 	 * First time coding? Check out the [q5 Beginner's Brief](https://github.com/q5js/q5.js/wiki/q5-Beginner's-Brief).
 	 * 
-	 * On these Learn pages you'll find concise descriptions for
-	 * q5's functions and variables. Scroll through entire topics without
-	 * needing to click between separate pages.
-	 * 
-	 * Experiment with editing the code in the interactive mini examples,
-	 * which are often only 8 lines or less. They automatically
-	 * update as you type, so you can see results right away.
+	 * On these Learn pages, you can experiment with editing the 
+	 * interactive mini examples. Have fun! 😎
 	 */
 
 	/** ⭐️
@@ -905,15 +900,18 @@ function draw() {
 	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.
+	 * Sets the color mode for the sketch, which changes how colors are
+	 * interpreted and displayed.
 	 * 
-	 * In c2d, the default color mode is RGB in legacy integer format.
+	 * 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 is RGB in float format (best performance).
+	 * 
+	 * Color gamut is 'display-p3' by default, if the device supports HDR.
 	 * 
-	 * See the documentation for q5's color constants below for more info.
-	 * @param {'rgb' | 'srgb' | 'oklch'} mode color mode
+	 * @param {'rgb' | 'oklch' | 'hsl' | 'hsb'} mode color mode
 	 * @param {1 | 255} format color format (1 for float, 255 for integer)
+	 * @param {'srgb' | 'display-p3'} [gamut] color gamut
 	 * @example
 createCanvas(200);
 
@@ -935,82 +933,176 @@ 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;
+	function colorMode(mode: 'rgb' | 'oklch', format: 1 | 255, gamut: 'srgb' | 'display-p3'): void;
 
 	/** 🎨
 	 * RGB colors have components `r`/`red`, `g`/`green`, `b`/`blue`,
 	 * and `a`/`alpha`.
 	 * 
-	 * By default when a canvas is using the HDR `display-p3` color space,
+	 * By default when a canvas is using the HDR "display-p3" color space,
 	 * rgb colors are mapped to the full P3 gamut, even when they use the
 	 * legacy integer 0-255 format.
 	 * @example
 createCanvas(200, 100);
 
-colorMode(RGB, 255);
+colorMode(RGB);
 
 background(255, 0, 0);
 	 */
 	const RGB: 'rgb';
 
 	/** 🎨
-	 * This color mode limits the gamut of rgb colors to sRGB.
+	 * OKLCH colors have components `l`/`lightness`, `c`/`chroma`,
+	 * `h`/`hue`, and `a`/`alpha`. It's more intuitive for humans
+	 * to work with color in these terms than RGB.
+	 * 
+	 * OKLCH is perceptually uniform, meaning colors at the
+	 * same lightness and chroma (colorfulness) will appear to
+	 * have equal luminance, regardless of the hue.
+	 *
+	 * OKLCH can accurately represent all colors visible to the
+	 * human eye, unlike many other color spaces that are bounded
+	 * to a gamut. The maximum lightness and chroma values that
+	 * correspond to sRGB or P3 gamut limits vary depending on
+	 * the hue. Colors that are out of gamut will be clipped to
+	 * the nearest in-gamut color.
+	 * 
+	 * Use the [OKLCH color picker](https://oklch.com) to find
+	 * in-gamut colors.
 	 * 
-	 * 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.
+	 * - `lightness`: 0 to 1
+	 * - `chroma`: 0 to ~0.4
+	 * - `hue`: 0 to 360
+	 * - `alpha`: 0 to 1
 	 * @example
 createCanvas(200, 100);
 
-colorMode(SRGB, 255);
+colorMode(OKLCH);
 
-background(255, 0, 0);
+background(0.64, 0.3, 30);
+	 * @example
+createCanvas(200);
+colorMode(OKLCH);
+
+function draw() {
+	background(0.7, 0.16, frameCount % 360);
+}
 	 */
-	const SRGB: 'srgb';
+	const OKLCH: 'oklch';
 
 	/** 🎨
-	 * OKLCH colors have components `l`/`lightness`, `c`/`chroma`,
-	 * `h`/`hue`, and `a`/`alpha`.
+	 * HSL colors have components `h`/`hue`, `s`/`saturation`,
+	 * `l`/`lightness`, 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.
+	 * HSL was created in the 1970s to approximate human perception
+	 * of color, trading accuracy for simpler computations. It's
+	 * not perceptually uniform, so colors with the same lightness
+	 * can appear darker or lighter, depending on their hue
+	 * and saturation. Yet, the lightness and saturation values that
+	 * correspond to gamut limits are always 100, regardless of the
+	 * hue. This can make HSL easier to work with than OKLCH.
 	 * 
-	 * The OKLCH format is similar to HSL/HSV but it's perceptually
-	 * uniform and supports HDR colors. Use this oklch color picker to 
-	 * explore the color space: https://oklch.com
+	 * HSL colors are mapped to the full P3 gamut when
+	 * using the "display-p3" color space.
 	 * 
-	 * `lightness`: 0 to 1
+	 * - `hue`: 0 to 360
+	 * - `saturation`: 0 to 100
+	 * - `lightness`: 0 to 100
+	 * - `alpha`: 0 to 1
+	 * @example
+createCanvas(200, 100);
+
+colorMode(HSL);
+
+background(0, 100, 50);
+	 * @example
+createCanvas(200, 220);
+noStroke();
+
+colorMode(HSL);
+for (let h = 0; h < 360; h += 10) {
+  for (let l = 0; l <= 100; l += 10) {
+    fill(h, 100, l);
+    rect(h * (11/20), l * 2, 6, 20);
+  }
+}
+	 */
+	const HSL: 'hsl';
+
+	/** 🎨
+	 * HSB colors have components `h`/`hue`, `s`/`saturation`,
+	 * `b`/`brightness` (aka `v`/`value`), and `a`/`alpha`.
 	 * 
-	 * `chroma`: 0 to 0.3
+	 * HSB is similar to HSL, but instead of lightness
+	 * (black to white), it uses brightness (black to
+	 * full color). To produce white, set brightness
+	 * to 100 and saturation to 0.
 	 * 
-	 * `hue`: 0 to 360
+	 * - `hue`: 0 to 360
+	 * - `saturation`: 0 to 100
+	 * - `brightness`: 0 to 100
+	 * - `alpha`: 0 to 1
+	 * @example
+createCanvas(200, 100);
+
+colorMode(HSB);
+
+background(0, 100, 100);
+	 * @example
+createCanvas(200, 220);
+noStroke();
+
+colorMode(HSB);
+for (let h = 0; h < 360; h += 10) {
+  for (let b = 0; b <= 100; b += 10) {
+    fill(h, 100, b);
+    rect(h * (11/20), b * 2, 6, 20);
+  }
+}
+	 */
+	const HSB: 'hsb';
+
+	/** 🎨
+	 * Limits the color gamut to the sRGB color space.
 	 * 
-	 * `alpha`: 0 to 1
+	 * If your display is HDR capable, note that full red appears
+	 * less saturated and darker in this example, as it would on
+	 * an SDR display.
+	 * @example
+createCanvas(200, 100);
+
+colorMode(RGB, 255, SRGB);
+
+background(255, 0, 0);
+	 */
+	const SRGB: 'srgb';
+
+	/** 🎨
+	 * Expands the color gamut to the P3 color space.
+	 * 
+	 * This is the default color gamut on devices that support HDR.
 	 * 
-	 * Note how seamless the hue transitions are in the following example.
+	 * If your display is HDR capable, note that full red appears
+	 * fully saturated and bright in the following example.
 	 * @example
-createCanvas(200);
-colorMode(OKLCH);
+createCanvas(200, 100);
 
-function draw() {
-	background(0.7, 0.16, frameCount % 360);
-}
+colorMode(RGB, 255, DISPLAY_P3);
+
+background(255, 0, 0);
 	 */
-	const OKLCH: 'oklch';
+	const DISPLAY_P3: 'display-p3';
 
 	class Color {
 		/** 🎨
+		 * This constructor strictly accepts 4 numbers, which are the color 
+		 * components.
+		 * 
 		 * Use the `color` function for greater flexibility, it runs
 		 * this constructor internally.
 		 * 
-		 * This constructor only accepts 4 numbers, which are the color 
-		 * components.
-		 * 
 		 * `Color` is not actually a class itself, it's a reference to a
-		 * Q5 color class based on the color mode and format.
+		 * Q5 color class based on the color mode, format, and gamut.
 		 */
 		constructor(c0: number, c1: number, c2: number, c3: number);
 	}