q5 2.0.17 → 2.1.0

package/src/q5-math.js

@@ -1,4 +1,4 @@
-Q5.modules.math = ($, p) => {
+Q5.modules.math = ($, q) => {
 	$.DEGREES = 'degrees';
 	$.RADIANS = 'radians';
 
@@ -27,7 +27,7 @@ Q5.modules.math = ($, p) => {
 	$.degrees = (x) => x * $._RADTODEG;
 	$.radians = (x) => x * $._DEGTORAD;
 
-	$.map = (value, istart, istop, ostart, ostop, clamp) => {
+	$.map = Q5.prototype.map = (value, istart, istop, ostart, ostop, clamp) => {
 		let val = ostart + (ostop - ostart) * (((value - istart) * 1.0) / (istop - istart));
 		if (!clamp) {
 			return val;
@@ -285,7 +285,7 @@ Q5.modules.math = ($, p) => {
 	let _noise;
 
 	$.noiseMode = (mode) => {
-		p.Noise = Q5[mode[0].toUpperCase() + mode.slice(1) + 'Noise'];
+		q.Noise = Q5[mode[0].toUpperCase() + mode.slice(1) + 'Noise'];
 		_noise = null;
 	};
 	$.noiseSeed = (seed) => {

package/src/q5-sound.js

@@ -1,11 +1,12 @@
-Q5.modules.sound = ($, p) => {
+Q5.modules.sound = ($, q) => {
 	$.Sound = Q5.Sound;
 	$.loadSound = (path, cb) => {
-		p._preloadCount++;
+		q._preloadCount++;
 		Q5.aud ??= new window.AudioContext();
 		let a = new Q5.Sound(path, cb);
 		a.addEventListener('canplaythrough', () => {
-			p._preloadCount--;
+			q._preloadCount--;
+			a.loaded = true;
 			if (cb) cb(a);
 		});
 		return a;
@@ -37,4 +38,10 @@ Q5.Sound = class extends Audio {
 	setPan(value) {
 		this.pan = value;
 	}
+	isLoaded() {
+		return this.loaded;
+	}
+	isPlaying() {
+		return !this.paused;
+	}
 };

package/src/q5-util.js

@@ -1,6 +1,6 @@
-Q5.modules.util = ($, p) => {
+Q5.modules.util = ($, q) => {
 	$._loadFile = (path, cb, type) => {
-		p._preloadCount++;
+		q._preloadCount++;
 		let ret = {};
 		fetch(path)
 			.then((r) => {
@@ -8,7 +8,7 @@ Q5.modules.util = ($, p) => {
 				if (type == 'text') return r.text();
 			})
 			.then((r) => {
-				p._preloadCount--;
+				q._preloadCount--;
 				Object.assign(ret, r);
 				if (cb) cb(r);
 			});

package/src/q5-vector.js

@@ -20,7 +20,7 @@ Q5.Vector = class {
 		return new Q5.Vector(this.x, this.y, this.z);
 	}
 	_arg2v(x, y, z) {
-		if (x.x !== undefined) return x;
+		if (x?.x !== undefined) return x;
 		if (y !== undefined) {
 			return { x, y, z: z || 0 };
 		}

package/src/q5-webgpu-canvas.js

@@ -0,0 +1,119 @@
+/**
+ * q5-webgpu
+ *
+ * EXPERIMENTAL, for developer testing only!
+ */
+Q5.renderers.webgpu = {};
+
+Q5.renderers.webgpu.canvas = ($, q) => {
+	let c = $.canvas;
+
+	c.width = $.width = 500;
+	c.height = $.height = 500;
+
+	if ($.colorMode) $.colorMode('rgb', 'float');
+
+	let colorsStack;
+
+	$._createCanvas = (w, h, opt) => {
+		q.ctx = q.drawingContext = c.getContext('webgpu');
+
+		$._canvasFormat = navigator.gpu.getPreferredCanvasFormat();
+		opt.format = $._canvasFormat;
+		opt.device = Q5.device;
+
+		$.ctx.configure(opt);
+
+		$.pipelines = [];
+
+		// pipeline changes for each draw call
+		$.pipelinesStack = [];
+
+		// vertices for each draw call
+		$.verticesStack = [];
+
+		// number of vertices for each draw call
+		$.drawStack = [];
+
+		// colors used for each draw call
+		colorsStack = $.colorsStack = [];
+
+		// current color index, used to associate a vertex with a color
+		$._colorIndex = -1;
+	};
+
+	$._resizeCanvas = (w, h) => {
+		$._setCanvasSize(w, h);
+	};
+
+	$.resetMatrix = () => {};
+	$.translate = () => {};
+
+	$._beginRender = () => {
+		$.encoder = Q5.device.createCommandEncoder();
+
+		q.pass = $.encoder.beginRenderPass({
+			colorAttachments: [
+				{
+					view: ctx.getCurrentTexture().createView(),
+					loadOp: 'clear',
+					storeOp: 'store'
+				}
+			]
+		});
+	};
+
+	$._render = () => {
+		// run pre-render methods
+		for (let m of $._hooks.preRender) m();
+
+		$.pass.setPipeline($.pipelines[0]);
+
+		let drawStack = $.drawStack; // local variables used for performance
+		let o = 0; // vertex offset
+		for (let i = 0; i < drawStack.length; i++) {
+			$.pass.draw(drawStack[i], 1, o, 0);
+			o += drawStack[i];
+		}
+	};
+
+	$._finishRender = () => {
+		$.pass.end();
+		const commandBuffer = $.encoder.finish();
+		Q5.device.queue.submit([commandBuffer]);
+		q.pass = $.encoder = null;
+
+		// clear the stacks for the next frame
+		$.verticesStack.length = 0;
+		$.drawStack.length = 0;
+		$.colorsStack.length = 0;
+		$.pipelinesStack.length = 0;
+		$._colorIndex = -1;
+	};
+
+	$.fill = (r, g, b, a = 1) => {
+		// grayscale mode `fill(1, 0.5)`
+		if (b == undefined) {
+			a = g;
+			g = b = r;
+		}
+		let levels;
+		if (r._q5Color) levels = r.levels;
+		else levels = [r, g, b, a];
+
+		colorsStack.push(...levels);
+		$._colorIndex++;
+	};
+};
+
+Q5.webgpu = async function (scope, parent) {
+	if (!navigator.gpu) {
+		console.error('q5 WebGPU not supported on this browser!');
+		return new Q5(scope, parent);
+	}
+	let adapter = await navigator.gpu.requestAdapter();
+	if (!adapter) throw new Error('No appropriate GPUAdapter found.');
+	Q5.device = await adapter.requestDevice();
+
+	return new Q5(scope, parent, 'webgpu');
+};

package/src/q5-webgpu-drawing.js

@@ -0,0 +1,281 @@
+Q5.renderers.webgpu.drawing = ($, q) => {
+	$.CLOSE = 1;
+
+	let verticesStack, drawStack, colorsStack;
+
+	$._hooks.postCanvas.push(() => {
+		verticesStack = $.verticesStack;
+		drawStack = $.drawStack;
+		colorsStack = $.colorsStack;
+
+		let vertexBufferLayout = {
+			arrayStride: 12, // 2 coordinates + 1 color index * 4 bytes each
+			attributes: [
+				{
+					format: 'float32x2',
+					offset: 0,
+					shaderLocation: 0 // position
+				},
+				{
+					format: 'float32',
+					offset: 8,
+					shaderLocation: 1 // colorIndex
+				}
+			]
+		};
+
+		let vertexShader = Q5.device.createShaderModule({
+			code: `
+struct VertexOutput {
+	@builtin(position) position: vec4<f32>,
+	@location(1) colorIndex: f32
+};
+
+@vertex
+fn vertexMain(@location(0) pos: vec2<f32>, @location(1) colorIndex: f32) -> VertexOutput {
+	var output: VertexOutput;
+	output.position = vec4<f32>(pos, 0.0, 1.0);
+	output.colorIndex = colorIndex;
+	return output;
+}
+`
+		});
+
+		let fragmentShader = Q5.device.createShaderModule({
+			code: `
+@group(0) @binding(0) var<storage, read> uColors : array<vec4<f32>>;
+
+@fragment
+fn fragmentMain(@location(1) colorIndex: f32) -> @location(0) vec4<f32> {
+	let index = u32(colorIndex);
+	return mix(uColors[index], uColors[index + 1u], fract(colorIndex));
+}
+`
+		});
+
+		let bindGroupLayout = Q5.device.createBindGroupLayout({
+			entries: [
+				{
+					binding: 0,
+					visibility: GPUShaderStage.FRAGMENT,
+					buffer: {
+						type: 'read-only-storage',
+						hasDynamicOffset: false
+					}
+				}
+			]
+		});
+
+		let pipelineLayout = Q5.device.createPipelineLayout({
+			bindGroupLayouts: [bindGroupLayout]
+		});
+
+		$.pipelines[0] = Q5.device.createRenderPipeline({
+			layout: pipelineLayout,
+			vertex: {
+				module: vertexShader,
+				entryPoint: 'vertexMain',
+				buffers: [vertexBufferLayout]
+			},
+			fragment: {
+				module: fragmentShader,
+				entryPoint: 'fragmentMain',
+				targets: [
+					{
+						format: $._canvasFormat
+					}
+				]
+			},
+			primitive: {
+				topology: 'triangle-list'
+			}
+		});
+	});
+
+	let shapeVertices;
+
+	$.beginShape = () => {
+		shapeVertices = [];
+	};
+
+	$.vertex = (x, y) => {
+		shapeVertices.push(x / $.canvas.hw, -y / $.canvas.hh, $._colorIndex);
+	};
+
+	$.endShape = (close) => {
+		if (shapeVertices.length < 6) {
+			throw new Error('A shape must have at least 3 vertices.');
+		}
+		if (close) {
+			// Close the shape by adding the first vertex at the end
+			shapeVertices.push(shapeVertices[0], shapeVertices[1], shapeVertices[2]);
+		}
+		// Convert the shape to triangles
+		let triangles = [];
+		for (let i = 3; i < shapeVertices.length; i += 3) {
+			triangles.push(
+				shapeVertices[0],
+				shapeVertices[1],
+				shapeVertices[2], // First vertex
+				shapeVertices[i - 3],
+				shapeVertices[i - 2],
+				shapeVertices[i - 1], // Previous vertex
+				shapeVertices[i],
+				shapeVertices[i + 1],
+				shapeVertices[i + 2] // Current vertex
+			);
+		}
+
+		verticesStack.push(...triangles);
+		drawStack.push(triangles.length / 3);
+		shapeVertices = [];
+	};
+
+	$.triangle = (x1, y1, x2, y2, x3, y3) => {
+		$.beginShape();
+		$.vertex(x1, y1);
+		$.vertex(x2, y2);
+		$.vertex(x3, y3);
+		$.endShape(1);
+	};
+
+	$.rect = (x, y, w, h) => {
+		let hw = w / 2;
+		let hh = h / 2;
+		// convert the coordinates from pixel space to NDC space
+		let left = (x - hw) / $.canvas.hw;
+		let right = (x + hw) / $.canvas.hw;
+		let top = -(y - hh) / $.canvas.hh; // y is inverted in WebGPU
+		let bottom = -(y + hh) / $.canvas.hh; // y is inverted in WebGPU
+
+		let ci = $._colorIndex;
+		// two triangles make a rectangle
+		verticesStack.push(
+			left,
+			top,
+			ci,
+			right,
+			top,
+			ci,
+			left,
+			bottom,
+			ci,
+			right,
+			top,
+			ci,
+			left,
+			bottom,
+			ci,
+			right,
+			bottom,
+			ci
+		);
+		drawStack.push(6);
+	};
+
+	/**
+	 * Derived from: ceil(Math.log(d) * 7) * 2 - ceil(28)
+	 * This lookup table is used for better performance.
+	 * @param {Number} d diameter of the circle
+	 * @returns n number of segments
+	 */
+	// prettier-ignore
+	const getArcSegments = (d) => 
+    d < 14 ? 8 :
+    d < 16 ? 10 :
+    d < 18 ? 12 :
+    d < 20 ? 14 :
+    d < 22 ? 16 :
+    d < 24 ? 18 :
+    d < 28 ? 20 :
+    d < 34 ? 22 :
+    d < 42 ? 24 :
+    d < 48 ? 26 :
+    d < 56 ? 28 :
+    d < 64 ? 30 :
+    d < 72 ? 32 :
+    d < 84 ? 34 :
+    d < 96 ? 36 :
+    d < 98 ? 38 :
+    d < 113 ? 40 :
+    d < 149 ? 44 :
+    d < 199 ? 48 :
+    d < 261 ? 52 :
+    d < 353 ? 56 :
+    d < 461 ? 60 :
+    d < 585 ? 64 :
+    d < 1200 ? 70 :
+		d < 1800 ? 80 :
+		d < 2400 ? 90 :
+		100;
+
+	$.ellipse = (x, y, w, h) => {
+		const n = getArcSegments(w == h ? w : Math.max(w, h));
+
+		let a = Math.max(w, 1) / 2;
+		let b = w == h ? a : Math.max(h, 1) / 2;
+
+		x /= $.canvas.hw;
+		y /= -$.canvas.hh;
+		a /= $.canvas.hw;
+		b /= -$.canvas.hh;
+
+		let t = 0; // theta
+		const angleIncrement = $.TAU / n;
+		const ci = $._colorIndex;
+		let vx1, vy1, vx2, vy2;
+		for (let i = 0; i <= n; i++) {
+			vx1 = vx2;
+			vy1 = vy2;
+			vx2 = x + a * Math.cos(t);
+			vy2 = y + b * Math.sin(t);
+			t += angleIncrement;
+
+			if (i == 0) continue;
+
+			verticesStack.push(x, y, ci, vx1, vy1, ci, vx2, vy2, ci);
+		}
+
+		drawStack.push(n * 3);
+	};
+
+	$.circle = (x, y, d) => $.ellipse(x, y, d, d);
+
+	$.noStroke = () => {};
+
+	$.background = () => {};
+
+	$._hooks.preRender.push(() => {
+		const vertexBuffer = Q5.device.createBuffer({
+			size: verticesStack.length * 6,
+			usage: GPUBufferUsage.VERTEX | GPUBufferUsage.COPY_DST
+		});
+
+		Q5.device.queue.writeBuffer(vertexBuffer, 0, new Float32Array(verticesStack));
+		$.pass.setVertexBuffer(0, vertexBuffer);
+
+		const colorBuffer = Q5.device.createBuffer({
+			size: colorsStack.length * 4,
+			usage: GPUBufferUsage.STORAGE | GPUBufferUsage.COPY_DST
+		});
+
+		Q5.device.queue.writeBuffer(colorBuffer, 0, new Float32Array(colorsStack));
+
+		const bindGroup = Q5.device.createBindGroup({
+			layout: $.pipelines[0].getBindGroupLayout(0),
+			entries: [
+				{
+					binding: 0,
+					resource: {
+						buffer: colorBuffer,
+						offset: 0,
+						size: colorsStack.length * 4
+					}
+				}
+			]
+		});
+
+		// set the bind group once before rendering
+		$.pass.setBindGroup(0, bindGroup);
+	});
+};

package/src/q5-webgpu-image.js

@@ -0,0 +1 @@
+Q5.renderers.webgpu.image = ($, q) => {};

package/src/q5-webgpu-text.js

@@ -0,0 +1 @@
+Q5.renderers.webgpu.text = ($, q) => {};

package/src/readme.md

@@ -32,12 +32,39 @@ Additional modules:
 <script src="https://q5js.org/src/q5-sensors.js"></script>
 ```
 
+WebGPU rendering modules are in development:
+
+```html
+<script src="https://q5js.org/src/q5-webgpu-canvas.js"></script>
+<script src="https://q5js.org/src/q5-webgpu-drawing.js"></script>
+```
+
 # Module Info
 
+- [Modular Use](#modular-use)
+- [Module Info](#module-info)
+	- [core](#core)
+	- [canvas](#canvas)
+	- [q2d-canvas](#q2d-canvas)
+	- [q2d-drawing](#q2d-drawing)
+	- [q2d-image](#q2d-image)
+	- [q2d-soft-filters](#q2d-soft-filters)
+	- [q2d-text](#q2d-text)
+	- [webgpu-canvas](#webgpu-canvas)
+	- [webgpu-drawing](#webgpu-drawing)
+	- [math](#math)
+	- [noisier](#noisier)
+
 ## core
 
 The core module provides the absolute basic functionality necessary to run q5.
 
+It loads other modules by passing `$` (alias for `this`) and `q` (which in global mode is a proxy for `this` and `window` or `global`).
+
+## canvas
+
+The canvas module provides shared functionality for all canvas renderers, such as adding the canvas to the DOM, resizing the canvas, setting pixel density,
+
 ## q2d-canvas
 
 Adds canvas 2D rendering support to q5.
@@ -60,27 +87,77 @@ The filters in q5-image use the [CanvasRenderingContext2D.filter](https://develo
 
 Software implementation of image filters.
 
-This module includes additional filters not implemented in q5-image and legacy filter support for Safari which lacks ctx.filter.
+This module includes additional filters not implemented in q5-image and legacy filter support for Safari which lacks `ctx.filter`.
 
-These filters are slow, real-time use of them is not recommended.
+These filters are slow. Real-time use of them is not recommended.
 
-As of April 2024, Safari Technology Preview supports ctx.filter under a flag. Hopefully in the near future mainline Safari will support ctx.filter and this module can be omitted from the default bundle.
+As of April 2024, Safari Technology Preview supports `ctx.filter` under a flag. Hopefully in the near future this module can be omitted from the default bundle.
 
 ## q2d-text
 
 Adds canvas 2D text rendering support to q5.
 
+Image based features in this module require the q5-2d-image module.
+
 `createTextImage(str, w, h)` provides a simple way for users to create images from text.
 
 `textImage(img, x, y)` displays text images, complying with the user's text position settings instead of their image position settings. The idea is that text will appear in the same place as it would if it were drawn with the `text` function.
 
 `textCache(bool, maxSize)` enables or disables text caching. As of June 2024, drawing rotated text is super slow in all browsers, so q5 creates and stores images of text and rotates that instead. Can improve rendering performance 90x but uses more memory. `maxSize` param determines the maximum number of text images to cache, default is 500 since these images will typically be quite small. The text image cache (tic) is a timed cache, so the oldest images are removed first.
 
-Of course, use of these image based features requires the q5-2d-image module.
+## webgpu-canvas
+
+> ⚠️ Experimental features! ⚠️
+
+This module adds WebGPU rendering support to q5.
+
+Instead of `new Q5()`, run the async function `Q5.webgpu()`. Explicit use of `createCanvas` is required.
+
+```js
+let q = await Q5.webgpu();
+
+createCanvas(500, 500);
+```
+
+Set the script type of your sketch to "module" to use `await` on the top level.
+
+```html
+<script type="module" src="sketch.js"></script>
+```
+
+Using q5 with the webgpu renderer requires a different approach to setting up sketches. That's because variables and functions declared in a module are not added to the global `window` object.
+
+Add functions like `setup` and `draw` as properties of `q`, the instance of Q5.
+
+```js
+q.draw = function () {
+	// draw stuff
+};
+```
+
+Implemented functions:
+
+`createCanvas`, `resizeCanvas`
+
+## webgpu-drawing
+
+> Uses `colorMode('rgb', 'float')` by default. Changing it to 'oklch' is not supported yet for the webgpu renderer.
+
+> All basic shapes are drawn from their center. Strokes are not implemented yet.
+
+q5's WebGPU renderer drawing functions like `rect` don't actually draw anything to the canvas. Instead, they prepare vertex and color data to be sent to the GPU in bulk, which occurs after the user's `draw` function and any post-draw addon functions are run. This approach better utilizes the GPU, so it doesn't have to repeatedly wait for the CPU to send small chunks of data that describe each individual shape. It's why webgpu is typically 2-3x faster than canvas 2d.
+
+Hooks into the q5-core `draw` loop were added to support webgpu rendering: `_beginRender`, `_render`, `_finishRender`.
+
+The current implementation is provided to give developers a taste of what q5 programming will be like with webgpu. Significant changes need to be made to support transformations such as rotation and scaling.
+
+Implemented functions:
+
+`fill`, `rect`, `circle`, `ellipse`, `triangle`, `beginShape`, `vertex`, `endShape`
 
 ## math
 
-`PerlinNoise` is q5's default noise algorithm. Kevin Perlin won an Academy Award for his work on the original algorithm for the 1982 movie Tron. q5's JavaScript implementation was authored by Tezumie.
+`PerlinNoise` is q5's default noise algorithm. Kevin Perlin won an Academy Award for his work on the original algorithm for the 1982 movie Tron. The JavaScript implementation of it in q5 was authored by Tezumie.
 
 `noiseMode` enables users to switch between noise algorithms, although only "perlin" is included in q5-math.
 
@@ -90,4 +167,4 @@ Adds additional noise functions to q5.
 
 `SimplexNoise` is a simplex noise implementation in JavaScript by Tezumie. Kevin Perlin's patent on simplex noise expired in 2022. Simplex noise is slightly faster but arguably less visually appealing than perlin noise.
 
-`BlockyNoise` is similar to p5's default `noise` function, which is a bit notorious in the gen art community for not actually being perlin noise, despite its claims to be. It looks closer to value noise but is not a standard implementation of that either. It's a bit blocky at 1 octave, hence the name.
+`BlockyNoise` is similar to p5's default `noise` function, which is a bit notorious in the gen art community for not actually being perlin noise, despite its claims to be. It looks closer to value noise but is not a standard implementation of that either. When visualized in 2d it's a bit blocky at 1 octave, hence the name.