q5 2.4.10 → 2.5.1

package/README.md

@@ -339,13 +339,13 @@ Unminified:
 
 - p5.js **5112kb** ⚠️
 - p5.sound.js 488kb
-- q5.js 93kb
+- q5.js 110kb
 
 Minified:
 
 - p5.min.js 1034kb ⚠️
 - p5.sound.min.js 200kb
-- q5.min.js **61kb** 🎉
+- q5.min.js **70kb** 🎉
 
 ## Benchmarks
 
@@ -404,6 +404,9 @@ p5.js is licensed under the LGPLv2, the two small sections of p5' code directly
 
 ## Credits
 
+q5-webgpu msdf text rendering:
+https://webgpu.github.io/webgpu-samples/?sample=textRenderingMsdf
+
 q5-webgpu blendMode:
 https://webgpufundamentals.org/webgpu/lessons/webgpu-transparency.html
 

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "q5",
-	"version": "2.4.10",
+	"version": "2.5.1",
 	"description": "A sequel to p5.js that's smaller and faster",
 	"author": "quinton-ashley",
 	"contributors": [

package/q5.d.ts

@@ -86,6 +86,22 @@ declare global {
 	 */
 	var deviceOrientation: string | null;
 
+	/** ⭐️
+	 * Use preload to load assets before the sketch starts and the
+	 * setup function is run.
+	 */
+	function preload(): void;
+
+	/** ⭐️
+	 * The setup function is called once when the program starts.
+	 */
+	function setup(): void;
+
+	/** ⭐️
+	 * The draw function is run 60 times per second by default.
+	 */
+	function draw(): void;
+
 	/** ⭐️
 	 * Stops the draw loop.
 	 */
@@ -312,6 +328,8 @@ declare global {
 
 	/** ⬜️
 	 * Saves the current drawing style settings.
+	 *
+	 * This includes the fill, stroke, stroke weight, tint, image mode, rect mode, ellipse mode, text size, text align, and text baseline.
 	 */
 	function pushStyles(): void;
 
@@ -565,9 +583,11 @@ declare global {
 	function resize(w: number, h: number): void;
 
 	/** 🌆
-	 * Trims the image, cropping out transparent pixels from the edges.
+	 * Returns a trimmed image, cropping out transparent pixels
+	 * from the edges.
+	 * @returns {Image}
 	 */
-	function trim(): void;
+	function trim(): Image;
 
 	/** 🌆
 	 * Masks the image with another image
@@ -584,29 +604,61 @@ declare global {
 	function save(a: string, b: string, c?: number): void;
 
 	/** 🌆
-	 * Retrieves pixel data from an image.
+	 * 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 srcX - x-coordinate of the source region
+	 * @param srcY - y-coordinate of the source region
+	 * @param srcW - width of the source region
+	 * @param srcH - height of the source region
+	 * @param dstX - x-coordinate of the destination region
+	 * @param dstY - y-coordinate of the destination region
+	 * @param dstW - width of the destination region
+	 * @param dstH - height of the destination region
+	 */
+	function inset(srcX, srcY, srcW, srcH, dstX, dstY, dstW, dstH): void;
+
+	/** 🌆
+	 * Returns a copy of the image.
+	 * @returns {Image}
+	 */
+	function copy(): Image;
+
+	/** 🌆
+	 * Retrieves a subsection of an image or canvas, as a q5 Image.
+	 *
+	 * Or if width and height are both 1, returns the color of the pixel at
+	 * the given coordinates in `[R, G, B, A]` array format.
+	 * 
+	 * To edit the color value of multiple pixels, it's faster to use 
+	 * `loadPixels` and `updatePixels`.
 	 * @param x
 	 * @param y
 	 * @param w - width of the area
 	 * @param h - height of the area
+	 * @returns {Image}
 	 */
 	function get(x: number, y: number, w?: number, h?: number): any;
 
 	/** 🌆
-	 * Sets pixel data in the image.
+	 * Sets a pixel's color in the image or canvas.
+	 * 
+	 * Or if a canvas or image is provided, it's drawn on top of the 
+	 * destination image or canvas ignoring its tint setting.
 	 * @param x
 	 * @param y
-	 * @param c - color or pixel data
+	 * @param c - color, canvas, or image
 	 */
 	function set(x: number, y: number, c: any): void;
 
 	/** 🌆
-	 * Loads pixel data into the image's pixel array.
+	 * Loads pixel data into the image's `pixels` array.
 	 */
 	function loadPixels(): void;
 
 	/** 🌆
-	 * Updates the image's pixels array to the canvas.
+	 * Updates the image's `pixels` array to the canvas.
 	 */
 	function updatePixels(): void;
 
@@ -775,6 +827,11 @@ declare global {
 
 	/** ✍️
 	 * Loads a font from a URL and optionally runs a callback function with the font name once it's loaded
+	 *
+	 * WebGPU: Fonts must be in MSDF format with the file ending
+	 * "-msdf.json". If no font is loaded before `text` is run, then
+	 * the default font is loaded:
+	 * https://q5js.org/fonts/YaHei-msdf.json
 	 * @param url - URL of the font to load
 	 * @param cb - Optional callback function that receives the font name as an argument once the font is loaded
 	 * @returns name of the loaded font
@@ -782,7 +839,7 @@ declare global {
 	function loadFont(url: string, cb?: (fontName: string) => void): string;
 
 	/** ✍️
-	 * Sets the current font to be used for text elements
+	 * Sets the current font to be used for rendering text
 	 * @param fontName - name of the font
 	 */
 	function textFont(fontName: string): void;
@@ -812,7 +869,7 @@ declare global {
 	 * @param horiz - horizontal alignment ('left', 'center', 'right')
 	 * @param vert - vertical alignment ('top', 'middle', 'bottom', 'alphabetic')
 	 */
-	function textAlign(horiz: 'left' | 'center' | 'right', vert?: 'top' | 'middle' | 'bottom' | 'alphabetic'): void;
+	function textAlign(horiz: 'left' | 'center' | 'right', vert?: 'top' | 'center' | 'bottom' | 'alphabetic'): void;
 
 	/** ✍️
 	 * Calculates and returns the width of a given string of text
@@ -894,7 +951,7 @@ declare global {
 
 	/** 🎨
 	 * Sets the color mode for the sketch. Changes the type of color object created by color functions.
-	 * 
+	 *
 	 * In WebGPU, the default color mode is 'rgb' in float format.
 	 * @param mode - color mode ('rgb', 'srgb', or 'oklch')
 	 * @param format - color format (1 or 255) for floating point or legacy 8-bit integer representation
@@ -1145,7 +1202,7 @@ declare global {
 	 */
 	function noiseDetail(lod: number, falloff: number): void;
 
-	// 🔊 q5-sound
+	// 🔊 sound
 
 	/** 🔊
 	 * Represents a sound object, extending the native `Audio` to