@mathzetta/qblur 0.0.0-stage → 0.1.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/package.json CHANGED
@@ -1,6 +1,120 @@
1
1
  {
2
2
  "name": "@mathzetta/qblur",
3
- "version": "0.0.0-stage",
4
- "stub": true,
5
- "description": "Temporary package placeholder for staged publishing"
6
- }
3
+ "version": "0.1.2",
4
+ "description": "Shareable image filters written as maths: a JSON format with params, pictures and chains, compiled to WebGL shaders by MathZetta.",
5
+ "type": "module",
6
+ "main": "src/index.js",
7
+ "types": "./src/index.d.ts",
8
+ "exports": {
9
+ ".": {
10
+ "types": "./src/index.d.ts",
11
+ "default": "./src/index.js"
12
+ },
13
+ "./apply": {
14
+ "types": "./src/apply.d.ts",
15
+ "default": "./src/apply.js"
16
+ },
17
+ "./element": {
18
+ "types": "./src/element.d.ts",
19
+ "default": "./src/element.js"
20
+ },
21
+ "./dist/qblur.js": {
22
+ "types": "./src/index.d.ts",
23
+ "default": "./dist/qblur.js"
24
+ },
25
+ "./dist/qblur.external.js": {
26
+ "types": "./src/index.d.ts",
27
+ "default": "./dist/qblur.external.js"
28
+ },
29
+ "./dist/qblur-apply.js": {
30
+ "types": "./src/apply.d.ts",
31
+ "default": "./dist/qblur-apply.js"
32
+ },
33
+ "./dist/qblur-element.js": {
34
+ "types": "./src/element.d.ts",
35
+ "default": "./dist/qblur-element.js"
36
+ },
37
+ "./dist/*": "./dist/*",
38
+ "./package.json": "./package.json"
39
+ },
40
+ "sideEffects": [
41
+ "./src/cpu-worker.js",
42
+ "./src/element.js",
43
+ "./dist/*"
44
+ ],
45
+ "files": [
46
+ "src/",
47
+ "!src/*.tmp.js",
48
+ "dist/",
49
+ "docs/filters.md",
50
+ "docs/library.md",
51
+ "README.md",
52
+ "CHANGELOG.md",
53
+ "LICENSE"
54
+ ],
55
+ "scripts": {
56
+ "test": "node test/run.js",
57
+ "serve": "node tools/serve.js",
58
+ "build": "node tools/build.mjs",
59
+ "check:site": "node tools/build.mjs && node tools/check.mjs --site",
60
+ "check:ai": "node tools/check.mjs --ai",
61
+ "test:ai": "MZ_AI=1 node test/run.js",
62
+ "check": "node tools/check.mjs",
63
+ "check:cpu": "node tools/check.mjs --cpu",
64
+ "check:nowebgl": "node tools/check.mjs --no-webgl",
65
+ "prepublishOnly": "npm test && npm run build",
66
+ "check:apps": "node tools/check-apps.mjs",
67
+ "check:docs": "node tools/check-docs.mjs"
68
+ },
69
+ "peerDependencies": {
70
+ "mathzetta": "^1.2.0"
71
+ },
72
+ "devDependencies": {
73
+ "@mathzetta/inlinemath": "file:../mathzetta/packages/inlinemath",
74
+ "@mediapipe/tasks-vision": "^1.1.1",
75
+ "@rollup/plugin-terser": "^1.0.2",
76
+ "gifenc": "^1.0.3",
77
+ "mathzetta": "file:../mathzetta/packages/mathzetta",
78
+ "mathzetta-sites": "file:../mathzetta-sites",
79
+ "onnxruntime-node": "^1.30.0",
80
+ "onnxruntime-web": "^1.30.0",
81
+ "rollup": "^4.64.12"
82
+ },
83
+ "license": "MIT",
84
+ "author": {
85
+ "name": "Robert Wilcox",
86
+ "email": "rwilcox@mathzetta.com",
87
+ "url": "https://qblur.com"
88
+ },
89
+ "engines": {
90
+ "node": ">=18"
91
+ },
92
+ "homepage": "https://qblur.com",
93
+ "repository": {
94
+ "type": "git",
95
+ "url": "git+https://github.com/triplelog/qblur.git"
96
+ },
97
+ "bugs": {
98
+ "url": "https://github.com/triplelog/qblur/issues",
99
+ "email": "rwilcox@mathzetta.com"
100
+ },
101
+ "unpkg": "dist/qblur.global.min.js",
102
+ "jsdelivr": "dist/qblur.global.min.js",
103
+ "publishConfig": {
104
+ "access": "public"
105
+ },
106
+ "keywords": [
107
+ "image",
108
+ "image-processing",
109
+ "filter",
110
+ "photo-filter",
111
+ "webgl",
112
+ "shader",
113
+ "glsl",
114
+ "canvas",
115
+ "gif",
116
+ "web-component",
117
+ "maths",
118
+ "mathzetta"
119
+ ]
120
+ }
@@ -0,0 +1,245 @@
1
+ /**
2
+ * One call: a picture and a filter in, the filtered picture out.
3
+ *
4
+ * const canvas = await applyFilter(img, '1 - rgb'); // maths
5
+ * const canvas = await applyFilter(img, 'Sepia'); // a built-in filter, by name
6
+ * const canvas = await applyFilter(img, 'Threshold', { params: { cutoff: 0.3 } });
7
+ * const picture = await applyFilter(imageData, filterDoc); // in Node: { data, width, height }
8
+ *
9
+ * `filter` is maths, a filter document, JSON or a share link (readFilter), a
10
+ * compiled filter (compileFilter), or the name of a filter in LIBRARY. The
11
+ * result is the picture's size — up to a limit: a picture longer than
12
+ * `maxSize` on its long side (MAX_SIZE, 4096 px, on the GPU; MAX_SIZE_CPU,
13
+ * 2048 px, on the CPU, which is far slower and holds four floats a pixel) is
14
+ * scaled down to it first, keeping its shape, and so are the other pictures
15
+ * in `images`. A bigger `maxSize` keeps more, up to what the GPU can hold. In
16
+ * a page the result is a 2D canvas (`canvas`, or a new one); in a worker an
17
+ * OffscreenCanvas; in Node, where there is no canvas, a picture
18
+ * { data: Uint8ClampedArray, width, height }.
19
+ *
20
+ * The GPU draws when WebGL is there (engine 'auto'), the CPU otherwise — the
21
+ * same pixels either way. The GPU work happens on one hidden WebGL canvas the
22
+ * module keeps (browsers allow only a few contexts), and a filter's shaders
23
+ * are compiled once and kept for the next call with the same filter (the
24
+ * same maths or document — by what it says, so a changed document is a new
25
+ * filter — or the same compiled filter, whose knob values are read again on
26
+ * every call). Calls run one at a time, in the order they were made.
27
+ */
28
+
29
+ import { compileFilter, readFilter, filterToJSON } from './format.js';
30
+ import { createRunner } from './auto.js';
31
+ import { renderGraphics } from './graphics.js';
32
+ import { LIBRARY } from './library.js';
33
+
34
+ const hasCanvas = () => typeof document !== 'undefined' || typeof OffscreenCanvas !== 'undefined';
35
+ const newCanvas = (width, height) => (typeof document !== 'undefined'
36
+ ? Object.assign(document.createElement('canvas'), { width, height })
37
+ : new OffscreenCanvas(width, height));
38
+
39
+ /** A filter in any of its forms → the compiled filter (not yet copied). */
40
+ export function toCompiled(filter) {
41
+ if (filter && typeof filter === 'object' && Array.isArray(filter.passes)) return filter; // (isCompiled, below)
42
+ if (typeof filter === 'string') {
43
+ const named = LIBRARY.find((f) => f.name.toLowerCase() === filter.trim().toLowerCase());
44
+ return compileFilter(named ?? readFilter(filter));
45
+ }
46
+ return compileFilter(filter);
47
+ }
48
+
49
+ /** The longest side applyFilter draws on the GPU, and on the CPU; a bigger picture is scaled down to it (option `maxSize`). */
50
+ export const MAX_SIZE = 4096;
51
+ export const MAX_SIZE_CPU = 2048;
52
+
53
+ const isPlain = (image) => Boolean(image && image.data && image.width && image.height) && !(typeof ImageData !== 'undefined' && image instanceof ImageData);
54
+ const toImageData = (p) => (typeof ImageData !== 'undefined' && p instanceof ImageData ? p : new ImageData(
55
+ p.data instanceof Uint8ClampedArray ? p.data : Uint8ClampedArray.from(p.data, p.data instanceof Float32Array || p.data instanceof Float64Array ? (v) => v * 255 : undefined),
56
+ p.width, p.height));
57
+
58
+ /** The picture at most `limit` on its long side: itself when it fits, else a smaller copy (a canvas, or in Node a picture). */
59
+ function fit(image, width, height, limit) {
60
+ const k = Math.min(1, limit / Math.max(width, height));
61
+ if (k >= 1) return { image, width, height };
62
+ const W = Math.max(1, Math.round(width * k)), H = Math.max(1, Math.round(height * k));
63
+ if (hasCanvas()) {
64
+ let source = image;
65
+ if (isPlain(image) || (typeof ImageData !== 'undefined' && image instanceof ImageData)) {
66
+ source = newCanvas(width, height);
67
+ source.getContext('2d').putImageData(toImageData(image), 0, 0);
68
+ }
69
+ const out = newCanvas(W, H), ctx = out.getContext('2d');
70
+ ctx.imageSmoothingEnabled = true;
71
+ ctx.imageSmoothingQuality = 'high';
72
+ ctx.drawImage(source, 0, 0, W, H);
73
+ return { image: out, width: W, height: H };
74
+ }
75
+ // no canvas (Node): each new pixel is the average of the pixels it covers
76
+ const src = image.data, out = new src.constructor(W * H * 4);
77
+ for (let Y = 0; Y < H; Y++) {
78
+ const y0 = Math.floor((Y * height) / H), y1 = Math.max(y0 + 1, Math.floor(((Y + 1) * height) / H));
79
+ for (let X = 0; X < W; X++) {
80
+ const x0 = Math.floor((X * width) / W), x1 = Math.max(x0 + 1, Math.floor(((X + 1) * width) / W));
81
+ const sum = [0, 0, 0, 0];
82
+ for (let y = y0; y < y1; y++) for (let x = x0; x < x1; x++) for (let c = 0; c < 4; c++) sum[c] += src[(y * width + x) * 4 + c];
83
+ const n = (y1 - y0) * (x1 - x0);
84
+ for (let c = 0; c < 4; c++) out[(Y * W + X) * 4 + c] = sum[c] / n;
85
+ }
86
+ }
87
+ return { image: { data: out, width: W, height: H }, width: W, height: H };
88
+ }
89
+
90
+ const isImg = (image) => typeof HTMLImageElement !== 'undefined' && image instanceof HTMLImageElement;
91
+ const pictureSize = (image) => (isImg(image) && !(image.complete && image.naturalWidth) ? [0, 0] : [ // an <img>'s width attribute is not a picture
92
+ image.naturalWidth || image.videoWidth || image.displayWidth || image.width || 0,
93
+ image.naturalHeight || image.videoHeight || image.displayHeight || image.height || 0,
94
+ ]);
95
+ const isCompiled = (filter) => Boolean(filter) && typeof filter === 'object' && Array.isArray(filter.passes);
96
+ const isColor = (v) => (Array.isArray(v) || ArrayBuffer.isView(v)) && v.length === 3 && [...v].every((n) => Number.isFinite(Number(n)));
97
+
98
+ // ---- the shared WebGL canvas -------------------------------------------------------------
99
+
100
+ let shared = null; // { canvas, gl, runners: Map(key → { compiled, runner, engine }) }
101
+ const byObject = new WeakMap(); // compiled filter → its key
102
+
103
+ function sharedGl() {
104
+ if (shared && !shared.gl.isContextLost()) return shared;
105
+ if (!hasCanvas()) return null;
106
+ const canvas = newCanvas(1, 1);
107
+ const gl = canvas.getContext('webgl', { preserveDrawingBuffer: true, premultipliedAlpha: false });
108
+ shared = gl ? { canvas, gl, runners: new Map() } : null;
109
+ return shared;
110
+ }
111
+
112
+ let nextKey = 0;
113
+ /** What a kept runner is found by: the text, what a document says, or which compiled filter it is. */
114
+ function keyOf(filter) {
115
+ if (typeof filter === 'string') return `s:${filter}`;
116
+ if (isCompiled(filter)) {
117
+ if (!byObject.has(filter)) byObject.set(filter, `c:${nextKey++}`);
118
+ return byObject.get(filter);
119
+ }
120
+ if (filter && typeof filter === 'object') { try { return `d:${filterToJSON(filter)}`; } catch { return null; } }
121
+ return null;
122
+ }
123
+
124
+ /** A copy whose knob values can change without touching the caller's compiled filter. */
125
+ const copyOf = (compiled) => ({ ...compiled, passes: compiled.passes.map((p) => ({ ...p, values: { ...p.values } })) });
126
+
127
+ function runnerFor(filter, engine, gl) {
128
+ const key = keyOf(filter) && `${engine}|${keyOf(filter)}`;
129
+ const cache = shared?.runners;
130
+ if (gl && key && cache?.has(key)) {
131
+ const entry = cache.get(key);
132
+ cache.delete(key); // used again: the last to go
133
+ cache.set(key, entry);
134
+ return entry;
135
+ }
136
+ const source = toCompiled(filter);
137
+ const compiled = copyOf(source);
138
+ const made = createRunner(compiled, { gl, prefer: engine });
139
+ // a compiled filter is the caller's: its knob values and opacities are read on every call; anything else starts from its own
140
+ const entry = { compiled, source: isCompiled(filter) ? source : copyOf(source), ...made };
141
+ if (gl && key && made.engine === 'gpu') {
142
+ cache.set(key, entry);
143
+ if (cache.size > 16) { // the one unused longest goes
144
+ const [oldest, old] = cache.entries().next().value;
145
+ cache.delete(oldest);
146
+ old.runner.dispose();
147
+ }
148
+ }
149
+ return entry;
150
+ }
151
+
152
+ let queue = Promise.resolve(); // one drawing at a time: they share the canvas, and a filter's runner
153
+
154
+ /**
155
+ * @param {CanvasImageSource|ImageData|{ data, width, height }} image the picture (loaded)
156
+ * @param {string|object} filter maths, a filter document, JSON, a link, a compiled filter, or a LIBRARY name
157
+ * @param {object} [options]
158
+ * params { name: value } — knob values (a colour is [r, g, b], 0–1); the rest keep their defaults.
159
+ * In a chain, every step with a knob of that name takes it.
160
+ * t the frame, for filters that move (default 0)
161
+ * images { name: picture } — the other pictures the filter asks for (compiled.images)
162
+ * engine 'auto' (default) | 'gpu' | 'cpu'
163
+ * canvas a 2D canvas to draw on (resized to the picture); otherwise a new one
164
+ * maxSize the longest side drawn (default MAX_SIZE on the GPU, MAX_SIZE_CPU on the CPU); bigger pictures are scaled down
165
+ * @returns {Promise<HTMLCanvasElement|OffscreenCanvas|{ data: Uint8ClampedArray, width: number, height: number }>}
166
+ */
167
+ export function applyFilter(image, filter, options = {}) {
168
+ const run = queue.then(() => apply(image, filter, options));
169
+ queue = run.catch(() => {});
170
+ return run;
171
+ }
172
+
173
+ async function apply(picture, filter, { params = {}, t = 0, images = {}, engine = 'auto', canvas = null, maxSize = null } = {}) {
174
+ if (!picture) throw new Error('applyFilter: no picture');
175
+ const [fullWidth, fullHeight] = pictureSize(picture);
176
+ if (!fullWidth || !fullHeight) throw new Error('applyFilter: the picture has no size yet (not loaded?)');
177
+ if (maxSize !== null && !(Number(maxSize) >= 1)) throw new Error(`applyFilter: maxSize is a number of pixels, not ${JSON.stringify(maxSize)}`);
178
+ if (engine !== 'auto' && engine !== 'gpu' && engine !== 'cpu') throw new Error(`applyFilter: engine is 'auto', 'gpu' or 'cpu', not "${engine}"`);
179
+ const ctx = canvas ? canvas.getContext('2d') : null;
180
+ if (canvas && !ctx) throw new Error('applyFilter: `canvas` must be a 2D canvas (this one already has another kind of context)');
181
+ const gpu = engine !== 'cpu' ? sharedGl() : null;
182
+ if (engine === 'gpu' && !gpu) throw new Error('applyFilter: no WebGL here (use engine "auto" or "cpu")');
183
+ const entry = runnerFor(filter, engine === 'gpu' ? 'gpu' : gpu ? 'auto' : 'cpu', gpu?.gl);
184
+ const { compiled, source, runner } = entry;
185
+ const kept = entry.engine === 'gpu'; // a kept runner (the GPU's); the CPU's is this call's alone
186
+ // the size drawn: the picture's, up to the limit (and never more than the GPU can hold)
187
+ const limit = kept ? Math.min(Number(maxSize ?? MAX_SIZE), gpu.gl.getParameter(gpu.gl.MAX_TEXTURE_SIZE) || MAX_SIZE) : Number(maxSize ?? MAX_SIZE_CPU);
188
+ const { image, width, height } = fit(picture, fullWidth, fullHeight, limit);
189
+ try {
190
+ // knobs: back to the filter's own values, then the ones asked for
191
+ const known = new Map(compiled.passes.flatMap((p) => Object.entries(p.params ?? {})));
192
+ for (const [name, value] of Object.entries(params)) {
193
+ if (!known.has(name)) throw new Error(`applyFilter: the filter has no knob called "${name}" (it has ${[...known.keys()].join(', ') || 'none'})`);
194
+ if (known.get(name).type === 'color' ? !isColor(value) : !Number.isFinite(Number(value)) || typeof value === 'object' || value === '') {
195
+ throw new Error(`applyFilter: the knob "${name}" needs ${known.get(name).type === 'color' ? 'a colour, [r, g, b] with each 0–1' : 'a number'}, not ${JSON.stringify(value)}`);
196
+ }
197
+ }
198
+ // the filter's graphics (text, shapes, strokes) are drawn first: nothing below waits, so a kept runner is set and drawn in one go
199
+ const graphics = Object.entries(compiled.graphics ?? {});
200
+ let drawn = {};
201
+ if (graphics.length) {
202
+ const needCanvas = graphics.filter(([, g]) => g.type !== 'strokes').map(([key]) => key);
203
+ if (!hasCanvas() && needCanvas.length) throw new Error(`applyFilter: this filter draws ${needCanvas.join(', ')} (text or shapes), which needs a canvas — there is none here`);
204
+ drawn = await renderGraphics(compiled, width, height, { t: Number.isFinite(t) ? t : Infinity });
205
+ }
206
+ compiled.passes.forEach((pass, i) => {
207
+ pass.values = { ...source.passes[i].values };
208
+ pass.opacity = source.passes[i].opacity;
209
+ for (const [name, value] of Object.entries(params)) {
210
+ if (name in (pass.params ?? {})) pass.values[name] = pass.params[name].type === 'color' ? [...value].map(Number) : Number(value);
211
+ }
212
+ });
213
+ runner.setImage(image);
214
+ // a kept runner still holds the last call's pictures: one this call doesn't give goes back to "not given", as on the CPU
215
+ for (const name of entry.given ?? []) if (!(name in images)) runner.setImage(name, null);
216
+ entry.given = Object.keys(images);
217
+ for (const [name, other] of Object.entries(images)) {
218
+ const [w, h] = pictureSize(other);
219
+ runner.setImage(name, w && h ? fit(other, w, h, limit).image : other);
220
+ }
221
+ for (const [key, picture] of Object.entries(drawn)) runner.setImage(key, picture);
222
+
223
+ if (kept) {
224
+ gpu.canvas.width = width;
225
+ gpu.canvas.height = height;
226
+ runner.draw({ t });
227
+ const out = canvas ?? newCanvas(width, height);
228
+ out.width = width;
229
+ out.height = height;
230
+ const to = ctx ?? out.getContext('2d');
231
+ to.clearRect(0, 0, width, height);
232
+ to.drawImage(gpu.canvas, 0, 0);
233
+ return out;
234
+ }
235
+ const picture = await runner.drawAsync({ t }); // big pictures: rows spread over workers
236
+ if (!hasCanvas() && !canvas) return picture;
237
+ const out = canvas ?? newCanvas(width, height);
238
+ out.width = width;
239
+ out.height = height;
240
+ (ctx ?? out.getContext('2d')).putImageData(new ImageData(picture.data, width, height), 0, 0);
241
+ return out;
242
+ } finally {
243
+ if (!kept) runner.dispose(); // its workers too, whatever happened
244
+ }
245
+ }
package/src/apply.d.ts ADDED
@@ -0,0 +1,64 @@
1
+ /** `import { applyFilter, toBlob } from '@mathzetta/qblur/apply'` — one call to filter a picture, and the ways to save the result. */
2
+ import type { CompiledFilter, FilterInput, Picture, Picture8, PictureSource, Colour, Engine } from './index.js';
3
+
4
+ // ---- one call ------------------------------------------------------------------------------
5
+
6
+ export interface ApplyOptions {
7
+ /** Knob values; a colour is [r, g, b], 0–1. The rest keep their defaults. */
8
+ params?: Record<string, number | Colour>;
9
+ /** The frame, for filters that move. */
10
+ t?: number;
11
+ /** The other pictures the filter asks for (compiled.images). */
12
+ images?: Record<string, PictureSource>;
13
+ engine?: 'auto' | Engine;
14
+ /** A 2D canvas to draw on (resized to the picture); otherwise a new one. */
15
+ canvas?: HTMLCanvasElement | OffscreenCanvas | null;
16
+ /** The longest side drawn (default MAX_SIZE on the GPU, MAX_SIZE_CPU on the CPU, never more than the GPU holds);
17
+ * a bigger picture — and any of `images` — is scaled down to it first, keeping its shape. */
18
+ maxSize?: number;
19
+ }
20
+
21
+ /** The longest side applyFilter draws by default: on the GPU (4096) and on the CPU (2048). */
22
+ export const MAX_SIZE: number;
23
+ export const MAX_SIZE_CPU: number;
24
+
25
+ /**
26
+ * A picture and a filter in, the filtered picture out (the picture's size, up to `maxSize`): a 2D canvas in a page,
27
+ * an OffscreenCanvas in a worker, a picture { data, width, height } in Node.
28
+ * `filter`: maths, a document, JSON, a share link, a compiled filter, or a LIBRARY filter's name.
29
+ */
30
+ export function applyFilter(image: PictureSource, filter: FilterInput | CompiledFilter, options?: ApplyOptions): Promise<HTMLCanvasElement | OffscreenCanvas | Picture8>;
31
+ /** A filter in any of the forms applyFilter takes → compiled. */
32
+ export function toCompiled(filter: FilterInput | CompiledFilter): CompiledFilter;
33
+
34
+ // ---- saving --------------------------------------------------------------------------------
35
+
36
+ /** PNG anywhere (the package's own writer); JPEG and WebP in a browser. */
37
+ export function toBlob(what: HTMLCanvasElement | OffscreenCanvas | Picture, options?: {
38
+ type?: 'image/png' | 'image/jpeg' | 'image/webp' | string;
39
+ quality?: number;
40
+ /** PNG: 'auto' writes an indexed PNG when there are at most 256 colours. */
41
+ palette?: 'auto' | 'none';
42
+ }): Promise<Blob>;
43
+ /** An animated GIF; pass gifenc (`import * as gifenc from 'gifenc'`). */
44
+ export function encodeGif(frames: Iterable<HTMLCanvasElement | OffscreenCanvas | Picture> | AsyncIterable<HTMLCanvasElement | OffscreenCanvas | Picture>, options: {
45
+ gifenc: object;
46
+ /** ms per frame (33). */
47
+ delay?: number;
48
+ /** 0: loop for ever (the default); -1: play once. */
49
+ repeat?: number;
50
+ colours?: number;
51
+ }): Promise<Blob>;
52
+ /** The RGBA bytes of a 2D canvas or a picture. */
53
+ export function pictureData(what: HTMLCanvasElement | OffscreenCanvas | Picture): Picture8 | ImageData;
54
+ /** The PNG writer: indexed when few colours, RGB when opaque; null without CompressionStream. */
55
+ export function encodePng(options: {
56
+ width: number;
57
+ height: number;
58
+ data: Uint8ClampedArray | Uint8Array;
59
+ palette?: 'auto' | 'none' | 'force';
60
+ colours?: number;
61
+ dither?: boolean;
62
+ /** Needed for palette 'force' on a picture with more than `colours` colours. */
63
+ quantize?: (data: Uint8ClampedArray | Uint8Array, colours: number, options: { dither: boolean; width: number }) => { palette: number[][]; indices: Uint8Array };
64
+ }): Promise<{ blob: Blob; kind: 'palette' | 'rgb' | 'rgba'; colours: number; bits: number } | null>;
package/src/apply.js ADDED
@@ -0,0 +1,14 @@
1
+ /**
2
+ * @mathzetta/qblur/apply — one call to filter a picture, and the ways to save the result. Its own entry, so a page that
3
+ * only compiles and runs filters (the main entry, `@mathzetta/qblur`) doesn't carry it:
4
+ *
5
+ * import { applyFilter, toBlob } from '@mathzetta/qblur/apply';
6
+ * const canvas = await applyFilter(img, 'Sepia');
7
+ * const png = await toBlob(canvas);
8
+ *
9
+ * dist/qblur-apply.js is this entry bundled with MathZetta; the classic scripts (qblur.global.min.js,
10
+ * qblur.external.global.min.js) put it on window.QBlur with everything else.
11
+ */
12
+ export { applyFilter, toCompiled, MAX_SIZE, MAX_SIZE_CPU } from './apply-filter.js';
13
+ export { toBlob, encodeGif, pictureData } from './save.js';
14
+ export { encodePng } from './png.js';
package/src/auto.js ADDED
@@ -0,0 +1,41 @@
1
+ /**
2
+ * GPU or CPU? One call that picks, and says why.
3
+ *
4
+ * const { runner, engine, reason } = createRunner(compileFilter(def), { gl });
5
+ * runner.setImage(img); runner.draw({ t, canvas }); // canvas: where the CPU draws (the GPU draws on gl's)
6
+ *
7
+ * The GPU whenever WebGL is there: a filter's shaders are compiled once and
8
+ * then reused for every picture and every frame, so the compile is paid once
9
+ * per filter, and after that the GPU is the faster engine. The CPU when
10
+ * there is no WebGL (some browsers, Node, servers), when the GPU refuses the
11
+ * shader, or when asked for (prefer: 'cpu'). Both give the same pixels
12
+ * (tools/check.mjs --cpu compares them on every library filter).
13
+ */
14
+
15
+ import { createFilterRunner } from './runtime.js';
16
+ import { createCpuRunner } from './cpu-runner.js';
17
+
18
+ /** @returns {{ engine: 'gpu' | 'cpu', reason: string }} */
19
+ export function chooseEngine({ webgl = false, prefer = 'auto' } = {}) {
20
+ if (prefer === 'cpu') return { engine: 'cpu', reason: 'asked for the CPU' };
21
+ if (!webgl) return { engine: 'cpu', reason: 'no WebGL here' };
22
+ return { engine: 'gpu', reason: prefer === 'gpu' ? 'asked for the GPU' : 'WebGL is here' };
23
+ }
24
+
25
+ /**
26
+ * @param {object} compiled compileFilter() output
27
+ * @param {object} [o] { gl, prefer: 'auto' | 'gpu' | 'cpu', precision, workers }
28
+ * @returns {{ runner, engine: 'gpu' | 'cpu', reason: string }}
29
+ */
30
+ export function createRunner(compiled, o = {}) {
31
+ const choice = chooseEngine({ webgl: Boolean(o.gl), prefer: o.prefer });
32
+ if (choice.engine === 'gpu') {
33
+ try {
34
+ return { runner: createFilterRunner(o.gl, compiled, { precision: o.precision }), ...choice };
35
+ } catch (e) {
36
+ if (o.prefer === 'gpu') throw e;
37
+ return { runner: createCpuRunner(compiled, o), engine: 'cpu', reason: `the GPU refused the shader (${e.message.split('\n')[0]})` };
38
+ }
39
+ }
40
+ return { runner: createCpuRunner(compiled, o), ...choice };
41
+ }