q5 2.0.17 → 2.2.0

package/src/q5-webgpu-drawing.js

@@ -0,0 +1,369 @@
+Q5.renderers.webgpu.drawing = ($, q) => {
+	$.CLOSE = 1;
+
+	let verticesStack, drawStack, colorsStack;
+
+	$._hooks.postCanvas.push(() => {
+		let colorsLayout = Q5.device.createBindGroupLayout({
+			entries: [
+				{
+					binding: 0,
+					visibility: GPUShaderStage.FRAGMENT,
+					buffer: {
+						type: 'read-only-storage',
+						hasDynamicOffset: false
+					}
+				}
+			]
+		});
+
+		$.bindGroupLayouts.push(colorsLayout);
+
+		verticesStack = $.verticesStack;
+		drawStack = $.drawStack;
+		colorsStack = $.colorsStack;
+
+		let vertexBufferLayout = {
+			arrayStride: 16, // 2 coordinates + 1 color index + 1 transform index * 4 bytes each
+			attributes: [
+				{ format: 'float32x2', offset: 0, shaderLocation: 0 }, // position
+				{ format: 'float32', offset: 8, shaderLocation: 1 }, // colorIndex
+				{ format: 'float32', offset: 12, shaderLocation: 2 } // transformIndex
+			]
+		};
+
+		let vertexShader = Q5.device.createShaderModule({
+			code: `
+struct VertexOutput {
+	@builtin(position) position: vec4<f32>,
+	@location(1) colorIndex: f32
+};
+
+struct Uniforms {
+	halfWidth: f32,
+	halfHeight: f32
+};
+
+@group(0) @binding(0) var<uniform> uniforms: Uniforms;
+@group(1) @binding(0) var<storage, read> transforms: array<mat4x4<f32>>;
+
+@vertex
+fn vertexMain(@location(0) pos: vec2<f32>, @location(1) colorIndex: f32, @location(2) transformIndex: f32) -> VertexOutput {
+	var vert = vec4<f32>(pos, 0.0, 1.0);
+	vert *= transforms[i32(transformIndex)];
+	vert.x /= uniforms.halfWidth;
+	vert.y /= uniforms.halfHeight;
+
+	var output: VertexOutput;
+	output.position = vert;
+	output.colorIndex = colorIndex;
+	return output;
+}
+`
+		});
+
+		let fragmentShader = Q5.device.createShaderModule({
+			code: `
+@group(2) @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 pipelineLayout = Q5.device.createPipelineLayout({
+			bindGroupLayouts: $.bindGroupLayouts
+		});
+
+		$._createPipeline = (blendConfig) => {
+			return Q5.device.createRenderPipeline({
+				layout: pipelineLayout,
+				vertex: {
+					module: vertexShader,
+					entryPoint: 'vertexMain',
+					buffers: [vertexBufferLayout]
+				},
+				fragment: {
+					module: fragmentShader,
+					entryPoint: 'fragmentMain',
+					targets: [
+						{
+							format: 'bgra8unorm',
+							blend: blendConfig
+						}
+					]
+				},
+				primitive: {
+					topology: 'triangle-list'
+				}
+			});
+		};
+
+		$.pipelines[0] = $._createPipeline(blendConfigs.normal);
+	});
+
+	// prettier-ignore
+	let blendFactors = [
+			'zero',                // 0
+			'one',                 // 1
+			'src-alpha',           // 2
+			'one-minus-src-alpha', // 3
+			'dst',                 // 4
+			'dst-alpha',           // 5
+			'one-minus-dst-alpha', // 6
+			'one-minus-src'        // 7
+	];
+	let blendOps = [
+		'add', // 0
+		'subtract', // 1
+		'reverse-subtract', // 2
+		'min', // 3
+		'max' // 4
+	];
+
+	const blendModes = {
+		normal: [2, 3, 0, 2, 3, 0],
+		lighter: [2, 1, 0, 2, 1, 0],
+		subtract: [2, 1, 2, 2, 1, 2],
+		multiply: [4, 0, 0, 5, 0, 0],
+		screen: [1, 3, 0, 1, 3, 0],
+		darken: [1, 3, 3, 1, 3, 3],
+		lighten: [1, 3, 4, 1, 3, 4],
+		overlay: [2, 3, 0, 2, 3, 0],
+		hard_light: [2, 3, 0, 2, 3, 0],
+		soft_light: [2, 3, 0, 2, 3, 0],
+		difference: [2, 3, 2, 2, 3, 2],
+		exclusion: [2, 3, 0, 2, 3, 0],
+		color_dodge: [1, 7, 0, 1, 7, 0],
+		color_burn: [6, 1, 0, 6, 1, 0],
+		linear_dodge: [2, 1, 0, 2, 1, 0],
+		linear_burn: [2, 7, 1, 2, 7, 1],
+		vivid_light: [2, 7, 0, 2, 7, 0],
+		pin_light: [2, 7, 0, 2, 7, 0],
+		hard_mix: [2, 7, 0, 2, 7, 0]
+	};
+
+	$.blendConfigs = {};
+
+	Object.entries(blendModes).forEach(([name, mode]) => {
+		$.blendConfigs[name] = {
+			color: {
+				srcFactor: blendFactors[mode[0]],
+				dstFactor: blendFactors[mode[1]],
+				operation: blendOps[mode[2]]
+			},
+			alpha: {
+				srcFactor: blendFactors[mode[3]],
+				dstFactor: blendFactors[mode[4]],
+				operation: blendOps[mode[5]]
+			}
+		};
+	});
+
+	$._blendMode = 'normal';
+	$.blendMode = (mode) => {
+		if (mode == $._blendMode) return;
+		if (mode == 'source-over') mode = 'normal';
+		mode = mode.toLowerCase().replace(/[ -]/g, '_');
+		$._blendMode = mode;
+		$.pipelines[0] = $._createPipeline($.blendConfigs[mode]);
+	};
+
+	let shapeVertices;
+
+	$.beginShape = () => {
+		shapeVertices = [];
+	};
+
+	$.vertex = (x, y) => {
+		if ($._matrixDirty) $._saveMatrix();
+		shapeVertices.push(x, -y, $._colorIndex, $._transformIndex);
+	};
+
+	$.endShape = (close) => {
+		let v = shapeVertices;
+		if (v.length < 12) {
+			throw new Error('A shape must have at least 3 vertices.');
+		}
+		if (close) {
+			// Close the shape by adding the first vertex at the end
+			v.push(v[0], v[1], v[2], v[3]);
+		}
+		// Convert the shape to triangles
+		let triangles = [];
+		for (let i = 4; i < v.length; i += 4) {
+			triangles.push(
+				v[0], // First vertex
+				v[1],
+				v[2],
+				v[3],
+				v[i - 4], // Previous vertex
+				v[i - 3],
+				v[i - 2],
+				v[i - 1],
+				v[i], // Current vertex
+				v[i + 1],
+				v[i + 2],
+				v[i + 3]
+			);
+		}
+
+		verticesStack.push(...triangles);
+		drawStack.push(triangles.length / 4);
+		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;
+
+		let left = x - hw;
+		let right = x + hw;
+		let top = -(y - hh); // y is inverted in WebGPU
+		let bottom = -(y + hh);
+
+		let ci = $._colorIndex;
+		if ($._matrixDirty) $._saveMatrix();
+		let ti = $._transformIndex;
+		// two triangles make a rectangle
+		verticesStack.push(
+			left,
+			top,
+			ci,
+			ti,
+			right,
+			top,
+			ci,
+			ti,
+			left,
+			bottom,
+			ci,
+			ti,
+			right,
+			top,
+			ci,
+			ti,
+			left,
+			bottom,
+			ci,
+			ti,
+			right,
+			bottom,
+			ci,
+			ti
+		);
+		drawStack.push(6);
+	};
+
+	$.background = () => {};
+
+	/**
+	 * 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;
+
+		let t = 0; // theta
+		const angleIncrement = $.TAU / n;
+		const ci = $._colorIndex;
+		if ($._matrixDirty) $._saveMatrix();
+		const ti = $._transformIndex;
+		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, ti, vx1, vy1, ci, ti, vx2, vy2, ci, ti);
+		}
+
+		drawStack.push(n * 3);
+	};
+
+	$.circle = (x, y, d) => $.ellipse(x, y, d, d);
+
+	$._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 colorsBuffer = Q5.device.createBuffer({
+			size: colorsStack.length * 4,
+			usage: GPUBufferUsage.STORAGE | GPUBufferUsage.COPY_DST
+		});
+
+		Q5.device.queue.writeBuffer(colorsBuffer, 0, new Float32Array(colorsStack));
+
+		const colorsBindGroup = Q5.device.createBindGroup({
+			layout: $.bindGroupLayouts[2],
+			entries: [
+				{
+					binding: 0,
+					resource: {
+						buffer: colorsBuffer,
+						offset: 0,
+						size: colorsStack.length * 4
+					}
+				}
+			]
+		});
+
+		// set the bind group once before rendering
+		$.pass.setBindGroup(2, colorsBindGroup);
+	});
+};

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 renderer support to q5. Note that images, text, and strokes can not be rendered yet.
+
+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
+};
+```
+
+The sketches you create with the q5-webgpu renderer will still display properly if WebGPU is not supported on a viewer's browser.
+
+In that case, q5 will put a warning in the console and fall back to the q2d renderer. A compatibility layer is applied which sets the color mode to "rgba" in float format and translates the origin to the center of the canvas on every frame. For now, be sure to set `noStroke` in your setup code and `clear` the canvas at the start of your `draw` function to match current q5 webgpu limitations.
+
+Implemented functions:
+
+`createCanvas`, `resizeCanvas`, `fill`, `clear`, `push`, `pop`, `resetMatrix`, `translate`, `rotate`, `scale`
+
+## 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 immediately draw on 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 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 faster than Canvas2D.
+
+Implemented functions:
+
+`rect`, `circle`, `ellipse`, `triangle`, `beginShape`, `vertex`, `endShape`, `blendMode`
 
 ## 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.