q5 2.4.5 → 2.5.0

package/src/readme.md

@@ -54,6 +54,11 @@ WebGPU rendering modules are in development:
   - [webgpu-drawing](#webgpu-drawing)
   - [webgpu-image](#webgpu-image)
   - [webgpu-text](#webgpu-text)
+    - [Default Font](#default-font)
+    - [Loading Custom Fonts](#loading-custom-fonts)
+    - [Displaying Emojis](#displaying-emojis)
+    - [Lightweight Use](#lightweight-use)
+    - [Implemented functions](#implemented-functions)
   - [math](#math)
   - [noisier](#noisier)
 
@@ -105,7 +110,7 @@ Image based features in this module require the q5-2d-image module.
 
 `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.
+`textCache(bool, maxSize)` enables or disables text caching.
 
 ## webgpu-canvas
 
@@ -179,21 +184,83 @@ Implemented functions:
 
 ## webgpu-text
 
-> Use `textFill` and `textStroke` to set text colors.
+The q5 WebGPU text renderer uses the multi-channel signed distance fields (MSDF) technique for high performance and high quality real-time text rendering. Text can be rapidly recolored, rotated, and scaled without any loss in quality or performance.
 
-WebGPU (and WebGL) don't have fast HTML5 based text rasterization functionality, like Canvas2D does.
+MSDF, introduced by Chlumsky Viktor in his master's thesis ["Shape Decomposition for Multi-channel Distance Fields" (2015)](https://dspace.cvut.cz/bitstream/handle/10467/62770/F8-DP-2015-Chlumsky-Viktor-thesis.pdf), improves upon the signed distance field (SDF) technique, popularized by Chris Green and [Valve Software](https://www.valvesoftware.com/en/) in ["Improved Alpha-Tested Magnification for Vector Textures and Special Effects" (2007)](https://steamcdn-a.akamaihd.net/apps/valve/2007/SIGGRAPH2007_AlphaTestedMagnification.pdf).
 
-In p5.js WebGL mode, text is drawn directly to the canvas. This is a complex task, since letters have intricate geometry: thus many triangles must be used to render text at high resolution. Unless a user wants to render a lot of text, the performance cost is actually negligible. Yet since p5.js depends on opentype.js for this, which is 528kb (171kb minified), a different approach was needed to keep q5 lightweight.
+| SDF                                                                                                                  | MSDF                                                                                                                  |
+| -------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------- |
+| ![demo-sdf16](https://user-images.githubusercontent.com/18639794/106391905-e679af00-63ef-11eb-96c3-993176330911.png) | ![demo-msdf16](https://user-images.githubusercontent.com/18639794/106391899-e37ebe80-63ef-11eb-988b-4764004bb196.png) |
 
-Internally, q5's WebGPU renderer uses a q5 graphics object to draw text to a Canvas2D canvas via `createTextImage`, then converts that canvas to a WebGPU texture. Each texture is cached, so it doesn't have to be recreated every frame that users want to display the same text.
+### Default Font
 
-Creating a text image is slower than rendering text if it's only displayed for one frame, but displaying static text multiple frames from a cached image is way faster than re-rendering the text. So just try not to have long strings of text that change every frame.
+For convenience, if no font is loaded before `text` is run, then q5's default MSDF font is loaded: https://q5js.org/fonts/YaHei-msdf.json
 
-For typical use cases, this is a great trade-off!
+![YaHei msdf texture](https://q5js.org/fonts/YaHei.png)
 
-Complete implementation of text rendering in WebGPU.
+This 512x512 msdf texture (207kb) was made with the [Microsoft YaHei](https://learn.microsoft.com/en-us/typography/font-list/microsoft-yahei) font and stores every character visible on a standard English keyboard, letters with diacritics (accents) used in European languages, and mathematical symbols.
 
-`loadFont`,`textFont`, `textSize`, `textLeading`, `textStyle`, `textAlign`, `textWidth`, `textAscent`, `textDescent`, `textFill`, `textStroke`, `text`
+```
+!"#$%&'()\*+,-./0123456789:;<=>?@ABCDEFGHIJKLMNOPQRSTUVWXYZ[\]^\_`abcdefghijklmnopqrstuvwxyz{|}~€¡¢£¥©®°²³´·¹º¿ÀÁÂÃÄÅÆÇÈÉÊËÌÍÎÏÐÑÒÓÔÕÖ×ØÙÚÛÜÝÞßàáâãäåæçèéêëìíîïðñòóôõö÷øùúûüýþÿ‘’“”π
+```
+
+> Do you think any other characters ought to be included in the default set? Let us know! https://github.com/q5js/q5.js/issues
+
+### Loading Custom Fonts
+
+You can choose a custom set of characters and convert fonts to MSDF format by using the [msdf-bmfont-xml](https://msdf-bmfont.donmccurdy.com/) website, created by Don McCurdy.
+
+Here's how to load an MSDF font:
+
+```js
+function preload() {
+	loadFont('arial-msdf.json');
+}
+
+function setup() {
+	createCanvas(200, 200);
+}
+
+function draw() {
+	fill(0.71, 0.92, 1);
+	text('Hello, World!', mouseX, mouseY);
+}
+
+Q5.webgpu();
+```
+
+### Displaying Emojis
+
+Full color emoji characters can't be rendered using the MSDF technique, so use `createTextImage` and display them with `textImage`:
+
+```js
+let puppy;
+
+function setup() {
+	createCanvas(200, 200);
+	textSize(100);
+	puppy = createTextImage('🐶');
+}
+
+function draw() {
+	textAlign(CENTER, CENTER);
+	textImage(puppy, 0, 0);
+}
+
+Q5.webgpu();
+```
+
+### Lightweight Use
+
+For super lightweight use load <https://q5js.org/fonts/YaHei-256-msdf.json>, which has a limited character set of english letters and some common punctuation symbols that completely fill in a 256x256 texture (73kb).
+
+```
+!@'",-.0123456789:ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz
+```
+
+### Implemented functions
+
+`loadFont`, `text`, `textSize`, `textAlign`, `textWidth`, `createTextImage`, `textImage`
 
 ## math