Skip to content

A fast 2D and 3D game engine — TypeScript SDK, C++/WebAssembly core, visual editor. Ship one project to web, desktop, WeChat MiniGames, playable ads, and native Android / iOS.

feat(assets): a texture can ship as its recipe - an .esimage named where a texture goes is carried as its source and drawn on the device when it loads, to the pixels its png has; the raster that draws it moved from the pipeline into the SDK as esengine/image, which an export adds when a recipe ships

yhhe53b659e2a4f
diff --git a/CHANGELOG.md b/CHANGELOG.md
index b7789aead..95a6fef19 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -16,6 +16,7 @@ published separately; it ships inside the editor.
### Added
+- **A texture can ship as its recipe.** A package shipped every pixel of every picture. An `.esimage` (the layered source the image tools write, which until now was only ever baked to a `.png` beside it) can be named where a texture goes, and the package then carries the source: the texture is drawn on the device when it is first loaded. In a headless game a 512 pixel plate drawn from its 691 byte recipe matched its 351 KB PNG at every one of 921,600 pixels. The raster moved from the pipeline into the SDK as `esengine/image` (about 86 KB of a web package before compression), which an export adds when a recipe ships and no other package carries; the pipeline and the editor draw with the same code. It is drawn on the main thread at load and is not kept between runs, and a picture with a `figure` layer or text is still baked.
- **A scale map.** `Foliage.densityMap` says how many of a field's plants stand where, and every one that stood was its full size: grass that thinned toward a beach ended in tufts as tall as the meadow's. `Foliage.scaleMap` is an image over the same area whose red is how large the plants stand: full size at white, smaller toward black, none at black. It is read as numbers, as the density map is, and on the workers with it. With both, a sward thins and shortens as it runs out and has a soft edge.
- **The grade has a gain and an offset, and the vignette a radius and a roundness.** Color Grade could add to the blacks (Lift) and never take from them, and its contrast in a linear project is a power curve about 0.18, which leaves black where it was. A look graded elsewhere with a contrast that is a line through 0.5 sinks its blacks: without that, a meadow that measures 0.77 saturation there measured 0.50 here, with a film of blue over every dark green. **Gain** (`u_gain`) multiplies every tone and **Offset** (`u_offset`, which may be under zero) is added after it, as a grade's slope and offset are; `(c - 0.5) * k + 0.5` is a gain of `k` and an offset of `0.5 - 0.5 * k`. The Vignette was full at the middle of every edge whatever its numbers: **Radius** (`u_radius`) is where it is full, and **Roundness** (`u_roundness`) takes it from the frame's own ellipse to a circle whose 1 is the corner, the usual lens vignette. Every default is the picture as it was.
- **A blade's lean, its turn to the eye, and what a leaf lets through and mirrors are yours to set.** Four numbers of a field of grass were the engine's own. `Foliage.bladeLean` is how far a blade's tip is thrown over (it was 0.12 of its height, written into the builder). On the Foliage material, `u_specular` is how much a plant mirrors the sun and the sky (it was 0.5, written into the shader), `u_translucencyColor` the colour of the light that comes through a leaf, which was the leaf's own and is yellower in a real one, and `u_bladeFaceEye` turns the flat of each blade toward the eye so that a blade seen edge on is not a line. Every default is what it was.
diff --git a/docs/astro/src/content/docs/assets/textures.mdx b/docs/astro/src/content/docs/assets/textures.mdx
index 2053d19d3..af27ab8b9 100644
--- a/docs/astro/src/content/docs/assets/textures.mdx
+++ b/docs/astro/src/content/docs/assets/textures.mdx
@@ -193,6 +193,25 @@ For sheet animation, author a flipbook instead of computing these by hand — se
[Animation](/docs/animation/overview/). For tile art, see
[Tilemaps](/docs/world/tilemaps/).
+## Texture recipes
+
+A texture can be shipped as how it is drawn and not as its pixels. An **`.esimage`** is a picture's source: layers of shapes, gradients,
+noise and grids, the file the image tools write and draw a `.png` from. Name the `.esimage` itself where a texture goes (a sprite, a
+material) and the package carries the source; the picture is drawn on the device when the texture is first loaded, to the very pixels
+its `.png` has.
+
+```json
+{ "type": "Sprite", "data": { "texture": "assets/tex/plate.esimage", "size": { "x": 512, "y": 512 } } }
+```
+
+A 512 pixel plate of noise, rust, a stripe and rivets is 691 bytes as a recipe and 351 KB as a PNG. What draws recipes is the
+`esengine/image` module, about 86 KB of a web package before compression: an export adds it when a recipe ships, and a script that
+loads one by code imports it where the game starts. A package with no recipe does not carry it.
+
+What a recipe costs is time: it is drawn on the main thread when it loads, every run. Draw large ones behind a loading screen. A
+picture with a `figure` layer or text needs the authoring tools to draw and is baked to its `.png` instead; so is a source's surface
+(its normal and roughness maps).
+
## Memory & residency
Textures are the largest thing most 2D games hold, and they are reference-counted and
diff --git a/docs/astro/src/content/docs/zh-cn/assets/textures.mdx b/docs/astro/src/content/docs/zh-cn/assets/textures.mdx
index e5e699235..6c4a06146 100644
--- a/docs/astro/src/content/docs/zh-cn/assets/textures.mdx
+++ b/docs/astro/src/content/docs/zh-cn/assets/textures.mdx
@@ -168,6 +168,22 @@ sprite.uvScale = { x: 32 / 256, y: 32 / 256 };
做序列帧动画不要手算这些,去授权一个 flipbook——见[动画](/docs/zh-cn/animation/overview/)。
瓦片美术见[瓦片地图](/docs/zh-cn/world/tilemaps/)。
+## 贴图配方
+
+贴图可以按"怎么画"发布,而不是按像素发布。**`.esimage`** 是一张图的源文件:由形状、渐变、噪声和网格组成的图层,也就是图像工具写出并据此
+画出 `.png` 的那个文件。在需要贴图的地方(精灵、材质)直接写 `.esimage`,包里带的就是源文件;贴图第一次加载时在设备上画出来,和它的
+`.png` 逐像素一致。
+
+```json
+{ "type": "Sprite", "data": { "texture": "assets/tex/plate.esimage", "size": { "x": 512, "y": 512 } } }
+```
+
+一块 512 像素、带噪声、锈迹、色带和铆钉的钢板,作为配方是 691 字节,作为 PNG 是 351 KB。负责画配方的是 `esengine/image` 模块,压缩前约占
+web 包 86 KB:导出时只要包里有配方就会自动带上,用脚本按代码加载配方的话,在游戏启动处导入它。没有配方的包不会带它。
+
+配方的代价是时间:它在加载时于主线程绘制,每次运行都要画。大的配方放在加载画面后面画。带 `figure` 图层或文字的图需要创作工具才能画,仍然
+烘焙成 `.png`;源文件的表面贴图(法线和粗糙度)也是。
+
## 内存与驻留
纹理通常是 2D 游戏里最大的一块,它们是引用计数 + 可驱逐的,不会永远常驻。预算、LRU、以及怎么读
diff --git a/docs/astro/src/data/apiStability.generated.json b/docs/astro/src/data/apiStability.generated.json
index dfb785223..701f5ebb2 100644
--- a/docs/astro/src/data/apiStability.generated.json
+++ b/docs/astro/src/data/apiStability.generated.json
@@ -405,6 +405,18 @@
"SplineCurve"
]
},
+ {
+ "id": "image",
+ "title": "Texture recipes",
+ "titleZh": "贴图配方",
+ "tier": "experimental",
+ "why": "a recipe draws on the device to the very pixels its baked picture has, checked in a headless game, but it is drawn on the main thread at load, is not kept between runs, and has not been timed on a phone",
+ "whyZh": "配方在设备上画出来的像素与烘焙好的图片逐像素一致,已在无头游戏里检查过;但它在加载时于主线程绘制,不跨次运行缓存,也没有在手机上计过时",
+ "entry": [
+ "renderImage",
+ "validateImageSource"
+ ]
+ },
{
"id": "rig2d",
"title": "2D rigs",
diff --git a/pipeline/src/bundle/engineInstalls.ts b/pipeline/src/bundle/engineInstalls.ts
index 60145e448..64e64e48e 100644
--- a/pipeline/src/bundle/engineInstalls.ts
+++ b/pipeline/src/bundle/engineInstalls.ts
@@ -24,6 +24,8 @@ import { ESENGINE_SUBPATHS } from './engineSubpaths';
* scene says "script graph", the `.esgraph` it references does. */
const ASSET_SUBPATH: Readonly<Record<string, string>> = {
'.esgraph': 'esengine/logic',
+ // A picture's source that ships is a texture drawn on the device (sdk asset/textureRecipe.ts).
+ '.esimage': 'esengine/image',
'.esanimator': 'esengine/skeletal-animation',
'.esavatar': 'esengine/skeletal-animation',
'.estimeline': 'esengine/timeline',
diff --git a/pipeline/src/bundle/engineSubpaths.ts b/pipeline/src/bundle/engineSubpaths.ts
index 089f45238..aaaadf02e 100644
--- a/pipeline/src/bundle/engineSubpaths.ts
+++ b/pipeline/src/bundle/engineSubpaths.ts
@@ -22,6 +22,7 @@ export const ESENGINE_SUBPATHS: Readonly<Record<string, string>> = {
'esengine/worldgen': 'worldgen/index.js',
'esengine/water': 'water/index.js',
'esengine/spline': 'spline/index.js',
+ 'esengine/image': 'image/index.js',
'esengine/voxel': 'voxel/index.js',
'esengine/rig2d': 'rig2d/index.js',
'esengine/imported-scene': 'imported-scene/index.js',
diff --git a/pipeline/src/image/imageAdjust.ts b/pipeline/src/image/imageAdjust.ts
index 210e12de6..9b74aca41 100644
--- a/pipeline/src/image/imageAdjust.ts
+++ b/pipeline/src/image/imageAdjust.ts
@@ -1,518 +1,4 @@
// SPDX-License-Identifier: Apache-2.0
// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
-/**
- * @file imageAdjust.ts
- * @brief What a photo editor offers over a picture so far: adjustments of its colour, and filters over its pixels.
- *
- * Each is one operation with numbers to turn, and the layer it sits on says where it applies and how much. Which to use, and how far, is the model's.
- * Pixels here are stored as the canvas stores them, colour already times alpha.
- */
-import { blurMask, fractalNoise, parseColor } from './imageNoise';
-import type { ImageAdjust, ImageFilterName } from './imageSource';
-
-const clamp01 = (v: number): number => Math.max(0, Math.min(1, v));
-const smooth = (t: number): number => t * t * (3 - 2 * t);
-export const lightnessOf = (r: number, g: number, b: number): number => r * 0.2126 + g * 0.7152 + b * 0.0722;
-
-// ---- Colour ----------------------------------------------------------------------
-
-function rgbToHsl(r: number, g: number, b: number): [number, number, number] {
- const [hi, lo] = [Math.max(r, g, b), Math.min(r, g, b)];
- const l = (hi + lo) / 2;
- if (hi === lo) return [0, 0, l];
- const d = hi - lo;
- const s = l > 0.5 ? d / (2 - hi - lo) : d / (hi + lo);
- const h = hi === r ? (g - b) / d + (g < b ? 6 : 0) : hi === g ? (b - r) / d + 2 : (r - g) / d + 4;
- return [h / 6, s, l];
-}
-
-function hslToRgb(h: number, s: number, l: number): [number, number, number] {
- if (s === 0) return [l, l, l];
- const q = l < 0.5 ? l * (1 + s) : l + s - l * s;
- const p = 2 * l - q;
- const channel = (t0: number): number => {
- const t = t0 < 0 ? t0 + 1 : t0 > 1 ? t0 - 1 : t0;
- if (t < 1 / 6) return p + (q - p) * 6 * t;
- if (t < 1 / 2) return q;
- if (t < 2 / 3) return p + (q - p) * (2 / 3 - t) * 6;
- return p;
- };
- return [channel(h + 1 / 3), channel(h), channel(h - 1 / 3)];
-}
-
-/** Through its points without overshooting them, as a curves dialog draws it: a table for 0..1. */
-function curveTable(points: readonly (readonly number[])[]): Float32Array {
- const sorted = [...points].sort((a, b) => a[0]! - b[0]!);
- const xs = sorted.map((p) => p[0]!), ys = sorted.map((p) => p[1]!);
- const n = xs.length;
- const slopes = xs.slice(0, -1).map((x, i) => (ys[i + 1]! - ys[i]!) / Math.max(1e-6, xs[i + 1]! - x));
- const tangents = xs.map((_, i) => {
- if (i === 0) return slopes[0] ?? 0;
- if (i === n - 1) return slopes[n - 2] ?? 0;
- return slopes[i - 1]! * slopes[i]! <= 0 ? 0 : (slopes[i - 1]! + slopes[i]!) / 2;
- });
- const table = new Float32Array(1024);
- for (let k = 0; k < table.length; k++) {
- const x = k / (table.length - 1);
- if (x <= xs[0]!) { table[k] = ys[0]!; continue; }
- if (x >= xs[n - 1]!) { table[k] = ys[n - 1]!; continue; }
- let i = 0;
- while (x > xs[i + 1]!) i++;
- const h = xs[i + 1]! - xs[i]!;
- const t = (x - xs[i]!) / h;
- const [t2, t3] = [t * t, t * t * t];
- table[k] = clamp01((2 * t3 - 3 * t2 + 1) * ys[i]! + (t3 - 2 * t2 + t) * h * tangents[i]! + (3 * t2 - 2 * t3) * ys[i + 1]! + (t3 - t2) * h * tangents[i + 1]!);
- }
- return table;
-}
-const look = (table: Float32Array, v: number): number => table[Math.round(clamp01(v) * (table.length - 1))]!;
-
-/** Colour along stops, for a gradient map. */
-function stopsTable(stops: readonly (readonly [number, string])[]): Float32Array {
- const sorted = [...stops].sort((a, b) => a[0] - b[0]).map(([t, c]) => [t, parseColor(c)] as const);
- const out = new Float32Array(256 * 3);
- for (let k = 0; k < 256; k++) {
- const v = k / 255;
- let i = 0;
- while (i + 2 < sorted.length && v > sorted[i + 1]![0]) i++;
- const [a, b] = [sorted[i]!, sorted[Math.min(sorted.length - 1, i + 1)]!];
- const t = clamp01((v - a[0]) / Math.max(1e-6, b[0] - a[0]));
- for (let n = 0; n < 3; n++) out[k * 3 + n] = a[1][n]! + (b[1][n]! - a[1][n]!) * t;
- }
- return out;
-}
-
-/** The picture with its colour changed, in the order a stack of adjustment layers would most often take. */
-export function applyAdjust(px: Float32Array, w: number, h: number, a: ImageAdjust): Float32Array {
- const out = new Float32Array(px.length);
- const levels = a.levels;
- const [inLow, inHigh] = levels?.input ?? [0, 1];
- const [outLow, outHigh] = levels?.output ?? [0, 1];
- const gamma = levels?.gamma ?? 1;
- const curves = a.curves ? (Array.isArray(a.curves) ? { all: curveTable(a.curves as readonly (readonly number[])[]) } : Object.fromEntries(Object.entries(a.curves).map(([k, v]) => [k, curveTable(v as readonly (readonly number[])[])]))) as Record<string, Float32Array> : null;
- const exposure = a.exposure !== undefined ? 2 ** a.exposure : 1;
- const [brightness, contrast] = [a.brightness ?? 0, a.contrast ?? 0];
- const contrastGain = contrast >= 0 ? 1 / Math.max(0.01, 1 - contrast * 0.98) : 1 + contrast;
- const [warm, tint] = [a.temperature ?? 0, a.tint ?? 0];
- const [hue, saturation, lightness] = [(a.hue ?? 0) / 360, a.saturation ?? 0, a.lightness ?? 0];
- const vibrance = a.vibrance ?? 0;
- const map = a.gradientMap ? stopsTable(a.gradientMap) : null;
- const levelsStep = a.posterize !== undefined ? Math.max(2, Math.round(a.posterize)) : 0;
- const balance = a.balance;
- for (let i = 0; i < w * h; i++) {
- const at = i * 4, alpha = px[at + 3]!;
- if (alpha <= 0) continue;
- let [r, g, b] = [px[at]! / alpha, px[at + 1]! / alpha, px[at + 2]! / alpha];
- if (exposure !== 1) { r *= exposure; g *= exposure; b *= exposure; }
- if (levels) {
- const f = (v: number): number => outLow + (outHigh - outLow) * clamp01((v - inLow) / Math.max(1e-6, inHigh - inLow)) ** (1 / gamma);
- r = f(r); g = f(g); b = f(b);
- }
- if (curves) {
- if (curves.all) { r = look(curves.all, r); g = look(curves.all, g); b = look(curves.all, b); }
- if (curves.r) r = look(curves.r, r);
- if (curves.g) g = look(curves.g, g);
- if (curves.b) b = look(curves.b, b);
- }
- if (brightness || contrast) {
- const f = (v: number): number => (v + brightness - 0.5) * contrastGain + 0.5;
- r = f(r); g = f(g); b = f(b);
- }
- if (warm || tint) { r += warm * 0.2 + tint * 0.1; g -= tint * 0.2; b += -warm * 0.2 + tint * 0.1; }
- if (balance) {
- const l = clamp01(lightnessOf(r, g, b));
- const [dark, mid, bright] = [smooth(clamp01(1 - l * 2.5)), 1 - Math.abs(l - 0.5) * 2, smooth(clamp01((l - 0.6) * 2.5))];
- for (const [weight, shift] of [[dark, balance.shadows], [mid, balance.midtones], [bright, balance.highlights]] as const) {
- if (!shift) continue;
- r += shift[0]! * weight * 0.5; g += shift[1]! * weight * 0.5; b += shift[2]! * weight * 0.5;
- }
- }
- if (hue || saturation || lightness) {
- const [hh, ss, ll] = rgbToHsl(clamp01(r), clamp01(g), clamp01(b));
- const s2 = saturation >= 0 ? ss + (1 - ss) * saturation * (ss > 0 ? 1 : 0) : ss * (1 + saturation);
- const l2 = lightness >= 0 ? ll + (1 - ll) * lightness : ll * (1 + lightness);
- [r, g, b] = hslToRgb((hh + hue + 1) % 1, clamp01(s2), clamp01(l2));
- }
- if (vibrance) {
- // More for what is dull than for what is already vivid, so skin and neon are not pushed over.
- const [hi, lo] = [Math.max(r, g, b), Math.min(r, g, b)];
- const amount = vibrance * (1 - clamp01(hi - lo));
- const l = lightnessOf(r, g, b);
- r = l + (r - l) * (1 + amount); g = l + (g - l) * (1 + amount); b = l + (b - l) * (1 + amount);
- }
- if (a.blackWhite) {
- const [cr, cg, cb] = Array.isArray(a.blackWhite) ? a.blackWhite as readonly number[] : [0.2126, 0.7152, 0.0722];
- r = g = b = r * cr! + g * cg! + b * cb!;
- }
- if (map) {
- const k = Math.round(clamp01(lightnessOf(r, g, b)) * 255) * 3;
- [r, g, b] = [map[k]!, map[k + 1]!, map[k + 2]!];
- }
- if (a.invert) { r = 1 - r; g = 1 - g; b = 1 - b; }
- if (levelsStep) {
- const f = (v: number): number => Math.round(clamp01(v) * (levelsStep - 1)) / (levelsStep - 1);
- r = f(r); g = f(g); b = f(b);
- }
- if (a.threshold !== undefined) r = g = b = lightnessOf(r, g, b) >= a.threshold ? 1 : 0;
- out[at] = clamp01(r) * alpha; out[at + 1] = clamp01(g) * alpha; out[at + 2] = clamp01(b) * alpha; out[at + 3] = alpha;
- }
- return out;
-}
-
-// ---- Filters ---------------------------------------------------------------------
-
-const bilinear = (px: Float32Array, w: number, h: number, x: number, y: number, out: Float32Array, to: number): void => {
- const [fx, fy] = [Math.max(0, Math.min(w - 1.001, x - 0.5)), Math.max(0, Math.min(h - 1.001, y - 0.5))];
- const [ix, iy] = [Math.floor(fx), Math.floor(fy)];
- const [tx, ty] = [fx - ix, fy - iy];
- const [a, b, c, d] = [(iy * w + ix) * 4, (iy * w + ix + 1) * 4, ((iy + 1) * w + ix) * 4, ((iy + 1) * w + ix + 1) * 4];
- for (let n = 0; n < 4; n++) {
- out[to + n] = (px[a + n]! * (1 - tx) + px[b + n]! * tx) * (1 - ty) + (px[c + n]! * (1 - tx) + px[d + n]! * tx) * ty;
- }
-};
-
-const blurAll = (px: Float32Array, w: number, h: number, sigma: number): Float32Array => {
- const out = new Float32Array(px.length);
- for (let n = 0; n < 4; n++) {
- const channel = new Float32Array(w * h);
- for (let i = 0; i < channel.length; i++) channel[i] = px[i * 4 + n]!;
- const soft = blurMask(channel, w, h, sigma);
- for (let i = 0; i < channel.length; i++) out[i * 4 + n] = soft[i]!;
- }
- return out;
-};
-
-/** Every pixel from somewhere else in the picture. */
-function warped(px: Float32Array, w: number, h: number, from: (x: number, y: number) => readonly [number, number]): Float32Array {
- const out = new Float32Array(px.length);
- for (let y = 0; y < h; y++) {
- for (let x = 0; x < w; x++) {
- const [sx, sy] = from(x + 0.5, y + 0.5);
- bilinear(px, w, h, sx, sy, out, (y * w + x) * 4);
- }
- }
- return out;
-}
-
-/** Every pixel the mean of several places, each given by how far along 0..1 it is. */
-function averaged(px: Float32Array, w: number, h: number, samples: number, from: (x: number, y: number, t: number) => readonly [number, number]): Float32Array {
- const out = new Float32Array(px.length);
- const one = new Float32Array(4);
- for (let y = 0; y < h; y++) {
- for (let x = 0; x < w; x++) {
- const to = (y * w + x) * 4;
- for (let s = 0; s < samples; s++) {
- const [sx, sy] = from(x + 0.5, y + 0.5, samples === 1 ? 0 : s / (samples - 1));
- bilinear(px, w, h, sx, sy, one, 0);
- for (let n = 0; n < 4; n++) out[to + n]! += one[n]!;
- }
- for (let n = 0; n < 4; n++) out[to + n]! /= samples;
- }
- }
- return out;
-}
-
-/** Light over a pixel without covering it: `add` 0..1 in each colour on top of what is there. */
-function screened(px: Float32Array, w: number, h: number, light: (x: number, y: number, into: Float32Array) => void): Float32Array {
- const out = new Float32Array(px);
- const add = new Float32Array(3);
- for (let y = 0; y < h; y++) {
- for (let x = 0; x < w; x++) {
- add.fill(0);
- light(x + 0.5, y + 0.5, add);
- const at = (y * w + x) * 4;
- let most = out[at + 3]!;
- for (let n = 0; n < 3; n++) {
- out[at + n] = out[at + n]! + (1 - out[at + n]!) * clamp01(add[n]!);
- most = Math.max(most, out[at + n]!);
- }
- out[at + 3] = most;
- }
- }
- return out;
-}
-
-type P = Readonly<Record<string, unknown>>;
-const num = (p: P, key: string, fallback: number): number => (p[key] as number | undefined) ?? fallback;
-const pointOf = (p: P, key: string, fallback: readonly [number, number]): readonly [number, number] => (p[key] as readonly [number, number] | undefined) ?? fallback;
-
-/** The picture with a filter over it: what it would be everywhere, which the layer then lays down where and as much as it says. @p k is the size of a pixel in the source's terms. */
-export function applyFilter(name: ImageFilterName, p: P, px: Float32Array, w: number, h: number, k: number): Float32Array {
- const middle = [w / (2 * k), h / (2 * k)] as const;
- const centre = (key = 'at'): readonly [number, number] => { const c = pointOf(p, key, middle); return [c[0] * k, c[1] * k]; };
- switch (name) {
- case 'gaussian':
- return blurAll(px, w, h, num(p, 'radius', 4) * k);
- case 'motion': {
- const a = (num(p, 'angle', 0) * Math.PI) / 180, d = num(p, 'distance', 16) * k;
- const [dx, dy] = [Math.cos(a) * d, Math.sin(a) * d];
- return averaged(px, w, h, Math.max(2, Math.min(64, Math.ceil(d))), (x, y, t) => [x + dx * (t - 0.5), y + dy * (t - 0.5)]);
- }
- case 'spin': {
- const [cx, cy] = centre();
- const amount = (num(p, 'angle', 10) * Math.PI) / 180;
- return averaged(px, w, h, 24, (x, y, t) => {
- const r = amount * (t - 0.5);
- const [dx, dy] = [x - cx, y - cy];
- return [cx + dx * Math.cos(r) - dy * Math.sin(r), cy + dx * Math.sin(r) + dy * Math.cos(r)];
- });
- }
- case 'zoom': {
- const [cx, cy] = centre();
- const amount = num(p, 'amount', 0.1);
- return averaged(px, w, h, 24, (x, y, t) => { const s = 1 + amount * (t - 0.5); return [cx + (x - cx) * s, cy + (y - cy) * s]; });
- }
- case 'lens': {
- // A disc and not a bell, so highlights open into the round lights of a real lens.
- const radius = num(p, 'radius', 6) * k;
- const bright = num(p, 'highlights', 1);
- const rings = Math.max(2, Math.min(6, Math.ceil(radius / 2)));
- const offsets: [number, number][] = [[0, 0]];
- for (let ring = 1; ring <= rings; ring++) {
- const count = ring * 7;
- for (let s = 0; s < count; s++) {
- const a = (s / count) * Math.PI * 2 + ring;
- offsets.push([Math.cos(a) * (radius * ring) / rings, Math.sin(a) * (radius * ring) / rings]);
- }
- }
- const out = new Float32Array(px.length);
- const one = new Float32Array(4);
- for (let y = 0; y < h; y++) {
- for (let x = 0; x < w; x++) {
- const to = (y * w + x) * 4;
- let weight = 0;
- for (const [ox, oy] of offsets) {
- bilinear(px, w, h, x + 0.5 + ox, y + 0.5 + oy, one, 0);
- const l = lightnessOf(one[0]!, one[1]!, one[2]!);
- const q = 1 + bright * 2 * l * l * l * l;
- for (let n = 0; n < 4; n++) out[to + n]! += one[n]! * q;
- weight += q;
- }
- for (let n = 0; n < 4; n++) out[to + n]! /= weight;
- }
- }
- return out;
- }
- case 'sharpen': {
- const soft = blurAll(px, w, h, num(p, 'radius', 1.5) * k);
- const [amount, threshold] = [num(p, 'amount', 0.8), num(p, 'threshold', 0)];
- const out = new Float32Array(px);
- for (let i = 0; i < w * h; i++) {
- const at = i * 4, a = px[at + 3]!;
- for (let n = 0; n < 3; n++) {
- const diff = px[at + n]! - soft[at + n]!;
- if (Math.abs(diff) >= threshold) out[at + n] = Math.max(0, Math.min(a, px[at + n]! + diff * amount));
- }
- }
- return out;
- }
- case 'highPass': {
- const soft = blurAll(px, w, h, num(p, 'radius', 6) * k);
- const out = new Float32Array(px.length);
- for (let i = 0; i < w * h; i++) {
- const at = i * 4, a = px[at + 3]!;
- out[at + 3] = a;
- for (let n = 0; n < 3; n++) out[at + n] = clamp01(0.5 + px[at + n]! - soft[at + n]!) * a;
- }
- return out;
- }
- case 'noise': {
- const [amount, scale, seed, mono] = [num(p, 'amount', 0.08), num(p, 'scale', 1) * k, num(p, 'seed', 1), p.mono !== false];
- const out = new Float32Array(px);
- for (let y = 0; y < h; y++) {
- for (let x = 0; x < w; x++) {
- const at = (y * w + x) * 4, a = px[at + 3]!;
- for (let n = 0; n < 3; n++) {
- const v = fractalNoise(x / scale, y / scale, 1, mono ? seed : seed + n * 13) - 0.5;
- out[at + n] = Math.max(0, Math.min(a, px[at + n]! + v * amount * 2 * a));
- }
- }
- }
- return out;
- }
- case 'median': {
- const r = Math.max(1, Math.min(6, Math.round(num(p, 'radius', 1) * k)));
- const out = new Float32Array(px.length);
- const lights: [number, number][] = [];
- for (let y = 0; y < h; y++) {
- for (let x = 0; x < w; x++) {
- lights.length = 0;
- for (let dy = -r; dy <= r; dy++) {
- for (let dx = -r; dx <= r; dx++) {
- const at = (Math.max(0, Math.min(h - 1, y + dy)) * w + Math.max(0, Math.min(w - 1, x + dx))) * 4;
- lights.push([lightnessOf(px[at]!, px[at + 1]!, px[at + 2]!), at]);
- }
- }
- lights.sort((a, b) => a[0] - b[0]);
- const from = lights[lights.length >> 1]![1], to = (y * w + x) * 4;
- for (let n = 0; n < 4; n++) out[to + n] = px[from + n]!;
- }
- }
- return out;
- }
- case 'emboss': {
- const a = (num(p, 'angle', 135) * Math.PI) / 180, d = num(p, 'height', 2) * k, amount = num(p, 'amount', 2);
- const [dx, dy] = [Math.round(Math.cos(a) * d), Math.round(Math.sin(a) * d)];
- const out = new Float32Array(px.length);
- for (let y = 0; y < h; y++) {
- for (let x = 0; x < w; x++) {
- const at = (y * w + x) * 4;
- const there = (Math.max(0, Math.min(h - 1, y + dy)) * w + Math.max(0, Math.min(w - 1, x + dx))) * 4;
- const diff = lightnessOf(px[at]!, px[at + 1]!, px[at + 2]!) - lightnessOf(px[there]!, px[there + 1]!, px[there + 2]!);
- const v = clamp01(0.5 + diff * amount);
- const alpha = px[at + 3]!;
- out[at] = out[at + 1] = out[at + 2] = v * alpha;
- out[at + 3] = alpha;
- }
- }
- return out;
- }
- case 'ripple': {
- const [amount, size, seed] = [num(p, 'amount', 4) * k, num(p, 'size', 24) * k, num(p, 'seed', 1)];
- return warped(px, w, h, (x, y) => [x + Math.sin((y / size) * Math.PI * 2 + seed) * amount, y + Math.sin((x / size) * Math.PI * 2 + seed * 1.7) * amount]);
- }
- case 'displace': {
- const [amount, size, seed] = [num(p, 'amount', 8) * k, num(p, 'size', 40) * k, num(p, 'seed', 1)];
- return warped(px, w, h, (x, y) => [x + (fractalNoise(x / size, y / size, 3, seed) - 0.5) * amount * 2, y + (fractalNoise(x / size, y / size, 3, seed + 7) - 0.5) * amount * 2]);
- }
- case 'twirl': {
- const [cx, cy] = centre();
- const [radius, angle] = [num(p, 'radius', Math.min(w, h) / (2 * k)) * k, (num(p, 'angle', 45) * Math.PI) / 180];
- return warped(px, w, h, (x, y) => {
- const [dx, dy] = [x - cx, y - cy];
- const d = Math.hypot(dx, dy);
- if (d >= radius) return [x, y];
- const a = angle * (1 - d / radius) ** 2;
- return [cx + dx * Math.cos(a) - dy * Math.sin(a), cy + dx * Math.sin(a) + dy * Math.cos(a)];
- });
- }
- case 'pixelate': {
- const cell = Math.max(2, Math.round(num(p, 'cell', 8) * k));
- const out = new Float32Array(px.length);
- for (let gy = 0; gy < h; gy += cell) {
- for (let gx = 0; gx < w; gx += cell) {
- const sum = [0, 0, 0, 0];
- let n = 0;
- for (let y = gy; y < Math.min(h, gy + cell); y++) for (let x = gx; x < Math.min(w, gx + cell); x++) { const at = (y * w + x) * 4; for (let c = 0; c < 4; c++) sum[c]! += px[at + c]!; n++; }
- for (let y = gy; y < Math.min(h, gy + cell); y++) for (let x = gx; x < Math.min(w, gx + cell); x++) { const at = (y * w + x) * 4; for (let c = 0; c < 4; c++) out[at + c] = sum[c]! / n; }
- }
- }
- return out;
- }
- case 'chromatic': {
- const [cx, cy] = centre();
- const amount = num(p, 'amount', 2) * k / Math.max(w, h);
- const out = new Float32Array(px);
- const one = new Float32Array(4);
- for (let y = 0; y < h; y++) {
- for (let x = 0; x < w; x++) {
- const at = (y * w + x) * 4;
- const [dx, dy] = [x + 0.5 - cx, y + 0.5 - cy];
- bilinear(px, w, h, cx + dx * (1 + amount), cy + dy * (1 + amount), one, 0);
- out[at] = one[0]!;
- bilinear(px, w, h, cx + dx * (1 - amount), cy + dy * (1 - amount), one, 0);
- out[at + 2] = one[2]!;
- }
- }
- return out;
- }
- case 'vignette': {
- const [cx, cy] = centre();
- const [amount, inner, outer] = [num(p, 'amount', 0.6), num(p, 'radius', 0.55), num(p, 'outer', 1.05)];
- const col = parseColor((p.color as string | undefined) ?? '#000000');
- const reach = Math.hypot(w, h) / 2;
- const out = new Float32Array(px);
- for (let y = 0; y < h; y++) {
- for (let x = 0; x < w; x++) {
- const at = (y * w + x) * 4;
- const t = amount * smooth(clamp01((Math.hypot(x + 0.5 - cx, y + 0.5 - cy) / reach - inner) / Math.max(0.01, outer - inner)));
- for (let n = 0; n < 3; n++) out[at + n] = px[at + n]! + (col[n]! * px[at + 3]! - px[at + n]!) * t;
- }
- }
- return out;
- }
- case 'fog': {
- // Thick at `to`, clear at `from`, in drifting patches: air between things, over and not behind them.
- const col = parseColor((p.color as string | undefined) ?? '#c8d0e0');
- const [fx, fy] = [pointOf(p, 'from', [0, 0])[0] * k, pointOf(p, 'from', [0, 0])[1] * k];
- const [tx, ty] = [pointOf(p, 'to', [0, h / k])[0] * k, pointOf(p, 'to', [0, h / k])[1] * k];
- const [dx, dy] = [tx - fx, ty - fy];
- const len = dx * dx + dy * dy || 1;
- const [density, patch, size, seed] = [num(p, 'density', 0.6), num(p, 'patchiness', 0.5), num(p, 'size', 120) * k, num(p, 'seed', 1)];
- const out = new Float32Array(px);
- for (let y = 0; y < h; y++) {
- for (let x = 0; x < w; x++) {
- const at = (y * w + x) * 4;
- const along = clamp01(((x + 0.5 - fx) * dx + (y + 0.5 - fy) * dy) / len);
- const cloud = patch > 0 ? 1 - patch + patch * 2 * fractalNoise(x / (size * 2), y / size, 4, seed) : 1;
- const t = clamp01(smooth(along) * density * cloud) * col[3];
- for (let n = 0; n < 3; n++) out[at + n] = px[at + n]! * (1 - t) + col[n]! * t;
- out[at + 3] = px[at + 3]! * (1 - t) + t;
- }
- }
- return out;
- }
- case 'rays': {
- // What is bright, drawn out from a point: light through air, in the colour of what shines.
- const [cx, cy] = centre();
- const [threshold, length, strength, decay] = [num(p, 'threshold', 0.6), num(p, 'length', 0.6), num(p, 'strength', 0.8), num(p, 'decay', 0.96)];
- const bright = new Float32Array(px.length);
- for (let i = 0; i < w * h; i++) {
- const at = i * 4;
- const over = clamp01((Math.max(px[at]!, px[at + 1]!, px[at + 2]!) - threshold) / Math.max(0.01, 1 - threshold));
- for (let n = 0; n < 3; n++) bright[at + n] = px[at + n]! * over;
- bright[at + 3] = 1;
- }
- const STEPS = 48;
- const one = new Float32Array(4);
- return screened(px, w, h, (x, y, into) => {
- let weight = 1;
- for (let s = 0; s < STEPS; s++) {
- const t = 1 - (s / STEPS) * length;
- bilinear(bright, w, h, cx + (x - cx) * t, cy + (y - cy) * t, one, 0);
- for (let n = 0; n < 3; n++) into[n]! += one[n]! * weight * strength / STEPS;
- weight *= decay;
- }
- });
- }
- case 'flare': {
- const [cx, cy] = centre();
- const col = parseColor((p.color as string | undefined) ?? '#ffe0b0');
- const [size, strength] = [num(p, 'size', 60) * k, num(p, 'strength', 1)];
- const [mx, my] = [w / 2, h / 2];
- const ghosts = [[-0.4, 0.22, 0.14], [-0.8, 0.12, 0.2], [-1.3, 0.34, 0.09], [-1.7, 0.17, 0.13]] as const;
- return screened(px, w, h, (x, y, into) => {
- const d = Math.hypot(x - cx, y - cy);
- let v = 0.9 * Math.exp(-((d / size) ** 2)) + 0.25 * Math.exp(-d / (size * 2.5));
- // A streak along the sensor, and ghosts in a line through the middle of the frame.
- v += 0.5 * Math.exp(-Math.abs(y - cy) / (size * 0.05)) * Math.exp(-Math.abs(x - cx) / (size * 3.5));
- for (const [t, r, a] of ghosts) {
- const [gx, gy] = [cx + (mx - cx) * (1 - t), cy + (my - cy) * (1 - t)];
- const gd = Math.hypot(x - gx, y - gy) / (size * r * 2.2);
- if (gd < 1) v += a * (1 - gd * gd * gd * gd);
- }
- for (let n = 0; n < 3; n++) into[n]! += col[n]! * v * strength;
- });
- }
- case 'texture': {
- // A relief lit from one side and not a stain: canvas, paper, plaster.
- const [scale, amount, seed] = [num(p, 'scale', 3) * k, num(p, 'amount', 0.3), num(p, 'seed', 1)];
- const a = (num(p, 'angle', 135) * Math.PI) / 180;
- const [lx, ly] = [Math.cos(a), Math.sin(a)];
- const out = new Float32Array(px);
- for (let y = 0; y < h; y++) {
- for (let x = 0; x < w; x++) {
- const at = (y * w + x) * 4;
- const v = fractalNoise(x / scale, y / scale, 3, seed);
- const slope = v - fractalNoise((x + lx) / scale, (y + ly) / scale, 3, seed);
- const shade = 1 + slope * amount * 3;
- const alpha = px[at + 3]!;
- for (let n = 0; n < 3; n++) out[at + n] = Math.max(0, Math.min(alpha, px[at + n]! * shade));
- }
- }
- return out;
- }
- default:
- throw new Error(`no filter "${String(name)}"`);
- }
-}
+// The picture code is the SDK's (sdk/src/image), so a game can evaluate a picture as the pipeline does; this is where the pipeline reaches it.
+export * from '../../../sdk/src/image/imageAdjust';
diff --git a/pipeline/src/image/imageFigure.ts b/pipeline/src/image/imageFigure.ts
index 279f3140d..37cbc4a32 100644
--- a/pipeline/src/image/imageFigure.ts
+++ b/pipeline/src/image/imageFigure.ts
@@ -10,6 +10,9 @@
import type { HumanoidBuild } from '../modeling/humanoid';
import { poseFrames, poseJoints, type PoseParams } from '../modeling/pose';
import type { ImageLayer } from './imageSource';
+import type { FlatFigure, ImageFigureDrawer } from './imageRaster';
+
+export type { FlatFigure } from './imageRaster';
/** The bones' own height: they are built at it, and sized in the picture. */
const BODY_HEIGHT = 1.6;
@@ -107,19 +110,6 @@ function volumesOf(frames: ReturnType<typeof poseFrames>, build: HumanoidBuild):
return volumes;
}
-export interface FlatFigure {
- /** Coverage of the whole body in picture pixels, then of each kind of block as it shows. */
- mask: Float32Array;
- parts: Record<string, Float32Array>;
- /** Which way the surface faces at each pixel, x right, y up, z toward the viewer; zero off the body. */
- normals: Float32Array;
- /** Dark where one block passes in front of another. */
- contour: Float32Array;
- /** In the picture: where each joint landed, and the bones and the head's cross as lines. */
- joints: Record<string, readonly [number, number]>;
- lines: readonly (readonly (readonly [number, number])[])[];
- light: readonly [number, number, number];
-}
const normalized = (v: readonly number[]): [number, number, number] => {
const len = Math.hypot(v[0]!, v[1]!, v[2]!) || 1;
@@ -273,3 +263,6 @@ export function flattenFigure(layer: ImageLayer, w: number, h: number, project:
}
export const figureLight = normalized;
+
+/** The drawer of figures the pipeline hands every picture it renders. */
+export const FIGURE_DRAWER: ImageFigureDrawer = { flatten: flattenFigure };
diff --git a/pipeline/src/image/imageMaterial.ts b/pipeline/src/image/imageMaterial.ts
index 8582603ba..cd980607f 100644
--- a/pipeline/src/image/imageMaterial.ts
+++ b/pipeline/src/image/imageMaterial.ts
@@ -1,221 +1,16 @@
// SPDX-License-Identifier: Apache-2.0
// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
/**
- * @file imageMaterial.ts — a picture as a surface: the maps a lit material reads beside its colour.
- *
- * A wall is not only its colour. Light catches the edges of its bricks and slides off its glaze, and a picture
- * alone draws flat however well it is painted. So a source may say what its surface is as well as what it looks
- * like: its relief, how rough it is, and where it is metal. Each is drawn with the same layers the colour is, as
- * a grey picture of its own (light is high, light is rough, light is metal), and what a material needs is made
- * from them: a normal map from the relief, and one map holding roughness and metal.
- *
- * With nothing drawn for the relief, the colour's own lightness stands in for it: dark is low. That is the
- * cheap guess every texture tool makes, and it is right for mortar and wrong for a painted stripe, which is why
- * a relief can be drawn instead.
+ * @file imageMaterial.ts: the SDK's surface maps (sdk/src/image), drawn with the pipeline's drawer of figures.
*/
-import { renderImage, type RenderedImage, type RgbaBitmap, type ImageTextDrawer } from './imageRaster';
-import type { ImageLayer, ImageMaterial, ImageSource } from './imageSource';
+import { renderMaterialMaps as render, type MaterialMaps } from '../../../sdk/src/image/imageMaterial';
+import type { RgbaBitmap } from '../../../sdk/src/image/imageRaster';
+import type { ImageSource } from '../../../sdk/src/image/imageSource';
+import { FIGURE_DRAWER } from './imageFigure';
-export type { ImageMaterial } from './imageSource';
+export * from '../../../sdk/src/image/imageMaterial';
-export interface MaterialMaps {
- /** Tangent space, +z out of the surface, as the engine's lit materials read it. */
- normal: RgbaBitmap;
- /** Roughness in green and metal in blue, glTF's layout; null when both are one value everywhere. */
- surface: RgbaBitmap | null;
- /** The one value, where it is one. */
- roughness: number;
- metal: number;
- /** The grey pictures the maps were made from, for looking at. */
- height: RgbaBitmap;
- notes: string[];
-}
-
-type DrawOptions = { pictures?: Readonly<Record<string, RgbaBitmap>>; text?: ImageTextDrawer };
-
-const lightness = (p: Uint8Array, i: number): number => (p[i * 4]! * 0.2126 + p[i * 4 + 1]! * 0.7152 + p[i * 4 + 2]! * 0.0722) / 255;
-
-/** The layers as a grey picture the size of the source, on black: what is not drawn is low, smooth, not metal. */
-function greyOf(source: ImageSource, layers: readonly ImageLayer[], options: DrawOptions): { values: Float32Array; picture: RenderedImage } {
- const picture = renderImage({ size: source.size, background: '#000000', ...(source.tile ? { tile: true } : {}), layers }, options);
- const values = new Float32Array(picture.width * picture.height);
- for (let i = 0; i < values.length; i++) values[i] = lightness(picture.rgba, i);
- return { values, picture };
-}
-
-/**
- * A normal map from heights 0..1. The slope at a pixel is read across its neighbours (a Sobel), going round the edges of
- * a picture that repeats and stopping at them otherwise. Green is up the picture, which is +v as the engine lays a
- * texture, so a ridge lit from above is bright on its upper side.
- */
-export function normalFromHeight(height: Float32Array, w: number, h: number, relief: number, wrap: boolean): RgbaBitmap {
- const at = (x: number, y: number): number => {
- const [cx, cy] = wrap ? [((x % w) + w) % w, ((y % h) + h) % h] : [Math.max(0, Math.min(w - 1, x)), Math.max(0, Math.min(h - 1, y))];
- return height[cy * w + cx]!;
- };
- const rgba = new Uint8Array(w * h * 4);
- for (let y = 0; y < h; y++) {
- for (let x = 0; x < w; x++) {
- const dx = ((at(x + 1, y - 1) + 2 * at(x + 1, y) + at(x + 1, y + 1)) - (at(x - 1, y - 1) + 2 * at(x - 1, y) + at(x - 1, y + 1))) / 8;
- // Down the picture is down the surface: a height rising toward the top of the picture slopes toward +v.
- const dy = ((at(x - 1, y - 1) + 2 * at(x, y - 1) + at(x + 1, y - 1)) - (at(x - 1, y + 1) + 2 * at(x, y + 1) + at(x + 1, y + 1))) / 8;
- const [nx, ny] = [-dx * relief, -dy * relief];
- const l = Math.hypot(nx, ny, 1);
- const o = (y * w + x) * 4;
- rgba[o] = Math.round((nx / l * 0.5 + 0.5) * 255);
- rgba[o + 1] = Math.round((ny / l * 0.5 + 0.5) * 255);
- rgba[o + 2] = Math.round((1 / l * 0.5 + 0.5) * 255);
- rgba[o + 3] = 255;
- }
- }
- return { width: w, height: h, rgba };
-}
-
-/**
- * How much the join shows when a picture is laid beside itself, as a share of how much one row or column of it differs
- * from the next anyway: about 1 is a picture that repeats, well above it is a seam.
- */
-export function seamOf(image: RgbaBitmap): number {
- const { width: w, height: h, rgba } = image;
- if (w < 4 || h < 4) return 1;
- const step = (a: number, b: number): number => {
- let d = 0;
- for (let k = 0; k < 4; k++) d += Math.abs(rgba[a * 4 + k]! - rgba[b * 4 + k]!);
- return d;
- };
- let [across, inside, insideCount] = [0, 0, 0];
- for (let y = 0; y < h; y++) across += step(y * w + w - 1, y * w);
- for (let x = 0; x < w; x++) across += step((h - 1) * w + x, x);
- for (let y = 0; y < h; y++) for (let x = 0; x + 1 < w; x += Math.max(1, Math.floor(w / 16))) { inside += step(y * w + x, y * w + x + 1); insideCount++; }
- for (let x = 0; x < w; x++) for (let y = 0; y + 1 < h; y += Math.max(1, Math.floor(h / 16))) { inside += step(y * w + x, (y + 1) * w + x); insideCount++; }
- const usual = inside / Math.max(1, insideCount);
- const join = across / (w + h);
- // A flat picture has no usual step to measure against: its join shows only if there is one at all.
- return usual < 0.25 ? (join < 0.5 ? 1 : join / 0.25) : join / usual;
-}
-
-/** The maps a source's `material` asks for, drawn beside its colour @p color. */
-export function renderMaterialMaps(source: ImageSource, color: RgbaBitmap, options: DrawOptions = {}): MaterialMaps {
- const material = source.material ?? {};
- const [w, h] = [color.width, color.height];
- const notes: string[] = [];
- let height: Float32Array;
- let heightPicture: RgbaBitmap;
- if (material.height) {
- const drawn = greyOf(source, material.height, options);
- [height, heightPicture] = [drawn.values, drawn.picture];
- notes.push(...drawn.picture.notes.map((n) => `height: ${n}`));
- } else {
- height = new Float32Array(w * h);
- const rgba = new Uint8Array(w * h * 4);
- for (let i = 0; i < w * h; i++) {
- height[i] = lightness(color.rgba, i);
- const v = Math.round(height[i]! * 255);
- rgba.set([v, v, v, 255], i * 4);
- }
- heightPicture = { width: w, height: h, rgba };
- }
- let [low, high] = [1, 0];
- for (const v of height) { if (v < low) low = v; if (v > high) high = v; }
- if (high - low < 1 / 255) notes.push('the relief is flat: its height is one value everywhere, so the normal map says nothing');
-
- const constant = (v: ImageMaterial['roughness'], fallback: number): number => (typeof v === 'number' ? v : fallback);
- const drawnMap = (v: ImageMaterial['roughness'], name: string): Float32Array | null => {
- if (!Array.isArray(v)) return null;
- const drawn = greyOf(source, v, options);
- notes.push(...drawn.picture.notes.map((n) => `${name}: ${n}`));
- return drawn.values;
- };
- const [rough, metal] = [drawnMap(material.roughness, 'roughness'), drawnMap(material.metal, 'metal')];
- let surface: RgbaBitmap | null = null;
- if (rough || metal) {
- const rgba = new Uint8Array(w * h * 4);
- const [r0, m0] = [Math.round(constant(material.roughness, 0.8) * 255), Math.round(constant(material.metal, 0) * 255)];
- for (let i = 0; i < w * h; i++) {
- rgba[i * 4] = 255;
- rgba[i * 4 + 1] = rough ? Math.round(rough[i]! * 255) : r0;
- rgba[i * 4 + 2] = metal ? Math.round(metal[i]! * 255) : m0;
- rgba[i * 4 + 3] = 255;
- }
- surface = { width: w, height: h, rgba };
- }
- return {
- normal: normalFromHeight(height, w, h, material.relief ?? 4, source.tile === true),
- surface,
- roughness: constant(material.roughness, 0.8),
- metal: constant(material.metal, 0),
- height: heightPicture,
- notes,
- };
-}
-
-/** The `.esmaterial` that reads the maps, by the names they were saved under beside it. */
-export function imageMaterialDoc(maps: MaterialMaps, files: { normal: string; surface: string | null }, constants: { version: string | number; blendNone: number; cullBack: number }): Record<string, unknown> {
- return {
- version: constants.version,
- type: 'material',
- shader: 'builtin:model',
- blendMode: constants.blendNone,
- depthTest: true,
- depthWrite: true,
- cull: constants.cullBack,
- properties: {
- u_normalMap: files.normal,
- // A map holds the values and the factors multiply it, so where there is a map they stand aside.
- ...(files.surface
- ? { u_metallicRoughnessMap: files.surface, u_roughness: 1, u_metallic: 1 }
- : { u_roughness: maps.roughness, u_metallic: maps.metal }),
- },
- };
-}
-
-/** A picture laid beside itself, two by two: the joins run down and across its middle, where a seam shows if there is one. */
-export function laidTwice(image: RgbaBitmap): RgbaBitmap {
- const { width: w, height: h, rgba } = image;
- const out = new Uint8Array(w * 2 * h * 2 * 4);
- for (let y = 0; y < h * 2; y++) {
- for (let x = 0; x < w * 2; x++) {
- const from = ((y % h) * w + (x % w)) * 4;
- out.set(rgba.subarray(from, from + 4), (y * w * 2 + x) * 4);
- }
- }
- return { width: w * 2, height: h * 2, rgba: out };
-}
-
-/**
- * The surface under a low light from the upper left, as a flat wall of it would take one: what the relief and the
- * roughness do, which neither the colour nor the normal map's own colours show. For looking at; the engine's own
- * shading is what a scene gets.
- */
-export function litPreview(color: RgbaBitmap, maps: MaterialMaps): RgbaBitmap {
- const { width: w, height: h } = color;
- const out = new Uint8Array(w * h * 4);
- const light = [-0.55, 0.55, 0.63];
- const half = (() => { const v = [light[0]!, light[1]!, light[2]! + 1]; const l = Math.hypot(...v); return v.map((c) => c / l); })();
- const srgb = (v: number): number => Math.round(Math.pow(Math.max(0, Math.min(1, v)), 1 / 2.2) * 255);
- for (let i = 0; i < w * h; i++) {
- const n = [maps.normal.rgba[i * 4]! / 127.5 - 1, maps.normal.rgba[i * 4 + 1]! / 127.5 - 1, maps.normal.rgba[i * 4 + 2]! / 127.5 - 1];
- const rough = maps.surface ? maps.surface.rgba[i * 4 + 1]! / 255 : maps.roughness;
- const metal = maps.surface ? maps.surface.rgba[i * 4 + 2]! / 255 : maps.metal;
- const diffuse = Math.max(0, n[0]! * light[0]! + n[1]! * light[1]! + n[2]! * light[2]!);
- const shine = Math.pow(Math.max(0, n[0]! * half[0]! + n[1]! * half[1]! + n[2]! * half[2]!), 2 / Math.max(0.02, rough * rough) - 1) * (1 - rough) * 1.6;
- for (let k = 0; k < 3; k++) {
- const base = Math.pow(color.rgba[i * 4 + k]! / 255, 2.2);
- out[i * 4 + k] = srgb(base * (1 - metal) * (0.18 + 0.95 * diffuse) + (0.04 + (base - 0.04) * metal) * (shine + metal * 0.25 * (0.3 + diffuse)));
- }
- out[i * 4 + 3] = 255;
- }
- return { width: w, height: h, rgba: out };
-}
-
-/** Two pictures side by side, the second scaled to the first's height. */
-export function sideBySide(a: RgbaBitmap, b: RgbaBitmap): RgbaBitmap {
- const out = new Uint8Array((a.width + b.width + 8) * a.height * 4).fill(60);
- for (let y = 0; y < a.height; y++) {
- out.set(a.rgba.subarray(y * a.width * 4, (y + 1) * a.width * 4), y * (a.width + b.width + 8) * 4);
- const by = Math.min(b.height - 1, Math.floor((y / a.height) * b.height));
- out.set(b.rgba.subarray(by * b.width * 4, (by + 1) * b.width * 4), (y * (a.width + b.width + 8) + a.width + 8) * 4);
- }
- for (let i = 3; i < out.length; i += 4) out[i] = 255;
- return { width: a.width + b.width + 8, height: a.height, rgba: out };
+/** The maps a source's surface draws, figures and all. */
+export function renderMaterialMaps(source: ImageSource, color: RgbaBitmap, options: Parameters<typeof render>[2] = {}): MaterialMaps {
+ return render(source, color, { figure: FIGURE_DRAWER, ...options });
}
diff --git a/pipeline/src/image/imageNoise.ts b/pipeline/src/image/imageNoise.ts
index 9374b83d4..16216b325 100644
--- a/pipeline/src/image/imageNoise.ts
+++ b/pipeline/src/image/imageNoise.ts
@@ -1,117 +1,4 @@
// SPDX-License-Identifier: Apache-2.0
// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
-export type Rgba = readonly [number, number, number, number];
-
-export function parseColor(text: string): Rgba {
- const h = /^#([0-9a-fA-F]+)$/.exec(text)?.[1];
- if (!h || ![3, 4, 6, 8].includes(h.length)) throw new Error(`color ${JSON.stringify(text)} must be #rgb, #rgba, #rrggbb or #rrggbbaa`);
- const full = h.length <= 4 ? [...h].map((c) => c + c).join('') : h;
- const at = (i: number): number => parseInt(full.slice(i, i + 2), 16) / 255;
- return [at(0), at(2), at(4), full.length === 8 ? at(6) : 1];
-}
-
-/**
- * Whether the picture being drawn repeats: what leaves one edge comes in at the opposite one. Set for the length of one
- * draw (renderImage), and read by everything that looks past an edge, so a tile's blur, shadow and noise all go round.
- */
-let wrapping = false;
-export const setWrapping = (on: boolean): void => { wrapping = on; };
-export const isWrapping = (): boolean => wrapping;
-
-function blurRound(src: Float32Array, w: number, h: number, sigma: number): Float32Array {
- const r = Math.max(1, Math.round(sigma * 1.2));
- let cur = src;
- for (let pass = 0; pass < 3; pass++) {
- const a = new Float32Array(w * h);
- for (let y = 0; y < h; y++) {
- let sum = 0;
- for (let x = -r; x <= r; x++) sum += cur[y * w + (((x % w) + w) % w)]!;
- for (let x = 0; x < w; x++) {
- a[y * w + x] = sum / (2 * r + 1);
- sum += cur[y * w + ((x + r + 1) % w)]! - cur[y * w + ((((x - r) % w) + w) % w)]!;
- }
- }
- const b = new Float32Array(w * h);
- for (let x = 0; x < w; x++) {
- let sum = 0;
- for (let y = -r; y <= r; y++) sum += a[(((y % h) + h) % h) * w + x]!;
- for (let y = 0; y < h; y++) {
- b[y * w + x] = sum / (2 * r + 1);
- sum += a[((y + r + 1) % h) * w + x]! - a[((((y - r) % h) + h) % h) * w + x]!;
- }
- }
- cur = b;
- }
- return cur;
-}
-
-export function blurMask(src: Float32Array, w: number, h: number, sigma: number): Float32Array {
- if (sigma <= 0) return src;
- if (wrapping) return blurRound(src, w, h, sigma);
- const r = Math.max(1, Math.round(sigma * 1.2));
- let cur = src;
- for (let pass = 0; pass < 3; pass++) {
- const a = new Float32Array(w * h);
- for (let y = 0; y < h; y++) {
- let sum = 0;
- for (let x = -r; x <= r; x++) sum += cur[y * w + Math.max(0, Math.min(w - 1, x))]!;
- for (let x = 0; x < w; x++) {
- a[y * w + x] = sum / (2 * r + 1);
- sum += cur[y * w + Math.min(w - 1, x + r + 1)]! - cur[y * w + Math.max(0, x - r)]!;
- }
- }
- const b = new Float32Array(w * h);
- for (let x = 0; x < w; x++) {
- let sum = 0;
- for (let y = -r; y <= r; y++) sum += a[Math.max(0, Math.min(h - 1, y)) * w + x]!;
- for (let y = 0; y < h; y++) {
- b[y * w + x] = sum / (2 * r + 1);
- sum += a[Math.min(h - 1, y + r + 1) * w + x]! - a[Math.max(0, y - r) * w + x]!;
- }
- }
- cur = b;
- }
- return cur;
-}
-
-export const NOISE_DIRECTIONS: readonly (readonly [number, number])[] = [
- [1, 0], [0.9239, 0.3827], [0.7071, 0.7071], [0.3827, 0.9239], [0, 1], [-0.3827, 0.9239], [-0.7071, 0.7071], [-0.9239, 0.3827],
- [-1, 0], [-0.9239, -0.3827], [-0.7071, -0.7071], [-0.3827, -0.9239], [0, -1], [0.3827, -0.9239], [0.7071, -0.7071], [0.9239, -0.3827],
-];
-
-export function cornerLift(ix: number, iy: number, seed: number, dx: number, dy: number): number {
- let h = Math.imul(ix, 374761393) + Math.imul(iy, 668265263) + Math.imul(seed, 1442968193);
- h = Math.imul(h ^ (h >>> 13), 1274126177);
- h = Math.imul(h ^ (h >>> 16), 2246822519);
- const d = NOISE_DIRECTIONS[((h ^ (h >>> 16)) >>> 0) % NOISE_DIRECTIONS.length]!;
- return d[0] * dx + d[1] * dy;
-}
-
-export const fade = (t: number): number => t * t * t * (t * (t * 6 - 15) + 10);
-
-/** @p px, @p py: how many lattice cells before the noise repeats each way; 0 for never. */
-export function gradientNoise(x: number, y: number, seed: number, px = 0, py = 0): number {
- const [ix, iy] = [Math.floor(x), Math.floor(y)];
- const [fx, fy] = [x - ix, y - iy];
- const [sx, sy] = [fade(fx), fade(fy)];
- const wx = (i: number): number => (px > 0 ? ((i % px) + px) % px : i);
- const wy = (i: number): number => (py > 0 ? ((i % py) + py) % py : i);
- const top = cornerLift(wx(ix), wy(iy), seed, fx, fy) * (1 - sx) + cornerLift(wx(ix + 1), wy(iy), seed, fx - 1, fy) * sx;
- const bottom = cornerLift(wx(ix), wy(iy + 1), seed, fx, fy - 1) * (1 - sx) + cornerLift(wx(ix + 1), wy(iy + 1), seed, fx - 1, fy - 1) * sx;
- return top * (1 - sy) + bottom * sy;
-}
-
-export const NOISE_CONTRAST = [1.15, 1.3, 1.4, 1.45, 1.45, 1.45, 1.45, 1.45];
-
-/** @p px, @p py: cells of the first octave before the noise repeats; each finer octave repeats with it. 0 for never. */
-export function fractalNoise(x: number, y: number, octaves: number, seed: number, px = 0, py = 0): number {
- let [sum, weight, amplitude, frequency] = [0, 0, 1, 1];
- for (let i = 0; i < octaves; i++) {
- // Off the lattice, where this noise is always nothing.
- sum += gradientNoise(x * frequency + 0.37, y * frequency + 0.61, seed + i * 101, px * frequency, py * frequency) * amplitude;
- weight += amplitude;
- amplitude *= 0.5;
- frequency *= 2;
- }
- return Math.max(0, Math.min(1, 0.5 + (sum / weight) * NOISE_CONTRAST[octaves - 1]!));
-}
+// The picture code is the SDK's (sdk/src/image), so a game can evaluate a picture as the pipeline does; this is where the pipeline reaches it.
+export * from '../../../sdk/src/image/imageNoise';
diff --git a/pipeline/src/image/imagePath.ts b/pipeline/src/image/imagePath.ts
index 0750b54da..a7305aefd 100644
--- a/pipeline/src/image/imagePath.ts
+++ b/pipeline/src/image/imagePath.ts
@@ -1,75 +1,4 @@
// SPDX-License-Identifier: Apache-2.0
// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
-export type Pt = readonly [number, number];
-
-export const CURVE_STEPS = 20;
-
-export function parsePath(d: string): { points: Pt[]; closed: boolean }[] {
- const tokens = d.match(/[a-zA-Z]|-?(?:\d+\.?\d*|\.\d+)(?:[eE][-+]?\d+)?/g) ?? [];
- const runs: { points: Pt[]; closed: boolean }[] = [];
- let run: Pt[] | null = null;
- let [x, y, sx, sy, lastCx, lastCy] = [0, 0, 0, 0, 0, 0];
- let cmd = '', prev = '', i = 0;
- const num = (): number => {
- const t = tokens[i++];
- if (t === undefined || /[a-zA-Z]/.test(t)) throw new Error(`path ${JSON.stringify(d.slice(0, 60))}: command ${cmd} is short of numbers`);
- return Number(t);
- };
- const start = (): void => {
- if (!run) { run = [[x, y]]; runs.push({ points: run, closed: false }); }
- };
- const curve = (f: (t: number) => Pt): void => {
- start();
- for (let s = 1; s <= CURVE_STEPS; s++) run!.push(f(s / CURVE_STEPS));
- };
- while (i < tokens.length) {
- if (/[a-zA-Z]/.test(tokens[i]!)) cmd = tokens[i++]!;
- else if (!cmd) throw new Error(`path ${JSON.stringify(d.slice(0, 60))} must start with a command`);
- const rel = cmd === cmd.toLowerCase();
- const [ox, oy] = rel ? [x, y] : [0, 0];
- switch (cmd.toUpperCase()) {
- case 'M':
- x = ox + num(); y = oy + num(); sx = x; sy = y;
- run = [[x, y]];
- runs.push({ points: run, closed: false });
- cmd = rel ? 'l' : 'L';
- break;
- case 'L': x = ox + num(); y = oy + num(); start(); run!.push([x, y]); break;
- case 'H': x = ox + num(); start(); run!.push([x, y]); break;
- case 'V': y = oy + num(); start(); run!.push([x, y]); break;
- case 'C': case 'S': {
- const smooth = cmd.toUpperCase() === 'S';
- const [c1x, c1y] = smooth ? (prev === 'C' || prev === 'S' ? [2 * x - lastCx, 2 * y - lastCy] : [x, y]) : [ox + num(), oy + num()];
- const [c2x, c2y, ex, ey] = [ox + num(), oy + num(), ox + num(), oy + num()];
- const [x0, y0] = [x, y];
- curve((t) => {
- const u = 1 - t;
- return [u * u * u * x0 + 3 * u * u * t * c1x + 3 * u * t * t * c2x + t * t * t * ex, u * u * u * y0 + 3 * u * u * t * c1y + 3 * u * t * t * c2y + t * t * t * ey];
- });
- [x, y, lastCx, lastCy] = [ex, ey, c2x, c2y];
- break;
- }
- case 'Q': case 'T': {
- const smooth = cmd.toUpperCase() === 'T';
- const [cx, cy] = smooth ? (prev === 'Q' || prev === 'T' ? [2 * x - lastCx, 2 * y - lastCy] : [x, y]) : [ox + num(), oy + num()];
- const [ex, ey] = [ox + num(), oy + num()];
- const [x0, y0] = [x, y];
- curve((t) => {
- const u = 1 - t;
- return [u * u * x0 + 2 * u * t * cx + t * t * ex, u * u * y0 + 2 * u * t * cy + t * t * ey];
- });
- [x, y, lastCx, lastCy] = [ex, ey, cx, cy];
- break;
- }
- case 'Z':
- if (runs.length) runs[runs.length - 1]!.closed = true;
- x = sx; y = sy; run = null;
- cmd = '';
- break;
- default:
- throw new Error(`path command ${cmd} is not one this draws; there are M L H V C S Q T Z`);
- }
- prev = cmd.toUpperCase() === 'L' && prev === 'M' ? 'L' : cmd.toUpperCase();
- }
- return runs;
-}
+// The picture code is the SDK's (sdk/src/image), so a game can evaluate a picture as the pipeline does; this is where the pipeline reaches it.
+export * from '../../../sdk/src/image/imagePath';
diff --git a/pipeline/src/image/imageRaster.ts b/pipeline/src/image/imageRaster.ts
index 5c60612a2..64dc886a3 100644
--- a/pipeline/src/image/imageRaster.ts
+++ b/pipeline/src/image/imageRaster.ts
@@ -1,2175 +1,15 @@
// SPDX-License-Identifier: Apache-2.0
// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
/**
- * @file imageRaster.ts — a picture from a list of layers, on the CPU.
- *
- * A model describes structure well and cannot write a hundred thousand colours. So it states shapes, fills and
- * effects, and this owns everything that has to be exact: antialiased edges, gradients, soft shadows.
- * On the CPU rather than through a canvas, so the same source makes the same bytes on any machine and a test can read them.
+ * @file imageRaster.ts: the SDK's raster (sdk/src/image), with the pipeline's own drawer of figures handed to every picture it renders.
*/
-import { applyAdjust, applyFilter, lightnessOf } from './imageAdjust';
-import { figureLight, flattenFigure, type FlatFigure } from './imageFigure';
-import { IMAGE_BRUSHES, isGuideLayer, MAX_MARK_STROKES } from './imageSource';
-import type { ImageFill, ImageLayer, ImageSource, ImageAlong, ImageBrushSettings, ImageEffect, ImageField, ImageMark, ImageStroke, ImageSweep, ImageTransform } from './imageSource';
-import { type Pt, parsePath } from './imagePath';
-import { type Rgba, blurMask, fractalNoise, gradientNoise, isWrapping, parseColor, setWrapping } from './imageNoise';
+import { renderImage as render, type RenderedImage } from '../../../sdk/src/image/imageRaster';
+import type { ImageSource } from '../../../sdk/src/image/imageSource';
+import { FIGURE_DRAWER } from './imageFigure';
-export interface RgbaBitmap { width: number; height: number; rgba: Uint8Array }
-type Matrix = readonly [number, number, number, number, number, number];
+export * from '../../../sdk/src/image/imageRaster';
-const IDENTITY: Matrix = [1, 0, 0, 1, 0, 0];
-const SUBSCANS = 8;
-/** The size of the picture being drawn, for what has to repeat with it (see setWrapping). */
-let tileWidth = 0, tileHeight = 0;
-
-const times = (a: Matrix, b: Matrix): Matrix => [
- a[0] * b[0] + a[2] * b[1], a[1] * b[0] + a[3] * b[1],
- a[0] * b[2] + a[2] * b[3], a[1] * b[2] + a[3] * b[3],
- a[0] * b[4] + a[2] * b[5] + a[4], a[1] * b[4] + a[3] * b[5] + a[5],
-];
-const apply = (m: Matrix, [x, y]: Pt): Pt => [m[0] * x + m[2] * y + m[4], m[1] * x + m[3] * y + m[5]];
-function invert(m: Matrix): Matrix {
- const det = m[0] * m[3] - m[1] * m[2] || 1e-12;
- return [m[3] / det, -m[1] / det, -m[2] / det, m[0] / det, (m[2] * m[5] - m[3] * m[4]) / det, (m[1] * m[4] - m[0] * m[5]) / det];
-}
-
-function transformOf(t: ImageTransform | undefined, origin: Pt): Matrix {
- if (!t) return IDENTITY;
- const [ox, oy] = t.origin ?? origin;
- const r = ((t.rotate ?? 0) * Math.PI) / 180;
- const [sx, sy] = typeof t.scale === 'number' ? [t.scale, t.scale] : t.scale ?? [1, 1];
- const [tx, ty] = t.translate ?? [0, 0];
- let m: Matrix = [1, 0, 0, 1, tx + ox, ty + oy];
- m = times(m, [Math.cos(r), Math.sin(r), -Math.sin(r), Math.cos(r), 0, 0]);
- m = times(m, [sx, 0, 0, sy, 0, 0]);
- return times(m, [1, 0, 0, 1, -ox, -oy]);
-}
-
-// ---- Outlines -------------------------------------------------------------------
-
-function ellipsePoints(cx: number, cy: number, rx: number, ry: number): Pt[] {
- const n = Math.max(48, Math.ceil(Math.max(rx, ry) * 2));
- return Array.from({ length: n }, (_, i): Pt => [cx + rx * Math.cos((i / n) * Math.PI * 2), cy + ry * Math.sin((i / n) * Math.PI * 2)]);
-}
-
-function roundedRect(x: number, y: number, w: number, h: number, radius: number | readonly number[]): Pt[] {
- const rs = typeof radius === 'number' ? [radius, radius, radius, radius] : radius;
- const limit = Math.min(w, h) / 2;
- const [tl, tr, br, bl] = [0, 1, 2, 3].map((i) => Math.max(0, Math.min(limit, rs[i] ?? 0))) as [number, number, number, number];
- const out: Pt[] = [];
- const corner = (cx: number, cy: number, r: number, from: number): void => {
- if (r <= 0) { out.push([cx, cy]); return; }
- const n = Math.max(4, Math.ceil(r));
- for (let i = 0; i <= n; i++) {
- const a = from + (i / n) * (Math.PI / 2);
- out.push([cx + r * Math.cos(a), cy + r * Math.sin(a)]);
- }
- };
- corner(x + tl, y + tl, tl, Math.PI);
- corner(x + w - tr, y + tr, tr, -Math.PI / 2);
- corner(x + w - br, y + h - br, br, 0);
- corner(x + bl, y + h - bl, bl, Math.PI / 2);
- return out;
-}
-
-/** A layer's outlines in its own coordinates. */
-function outlinesOf(layer: ImageLayer): { runs: { points: Pt[]; closed: boolean }[]; middle: Pt } {
- const closed = (points: Pt[]): { points: Pt[]; closed: boolean }[] => [{ points, closed: true }];
- switch (layer.shape) {
- case 'rect': {
- const [x, y] = layer.at!, [w, h] = layer.size!;
- return { runs: closed(roundedRect(x, y, w, h, layer.radius ?? 0)), middle: [x + w / 2, y + h / 2] };
- }
- case 'circle': {
- const [cx, cy] = layer.at!;
- return { runs: closed(ellipsePoints(cx, cy, layer.radius as number, layer.radius as number)), middle: [cx, cy] };
- }
- case 'ellipse': {
- const [cx, cy] = layer.at!, [rx, ry] = layer.radii!;
- return { runs: closed(ellipsePoints(cx, cy, rx, ry)), middle: [cx, cy] };
- }
- case 'ring': {
- const [cx, cy] = layer.at!;
- const inner = ellipsePoints(cx, cy, layer.inner!, layer.inner!).reverse();
- return { runs: [...closed(ellipsePoints(cx, cy, layer.radius as number, layer.radius as number)), ...closed(inner)], middle: [cx, cy] };
- }
- case 'polygon': case 'line': {
- const pts = layer.points as Pt[];
- const c = pts.reduce<[number, number]>((s, p) => [s[0] + p[0] / pts.length, s[1] + p[1] / pts.length], [0, 0]);
- return { runs: [{ points: pts, closed: layer.shape === 'polygon' }], middle: c };
- }
- case 'star': case 'gear': {
- const [cx, cy] = layer.at!;
- const n = layer.count!, outer = layer.radius as number, inner = layer.inner!;
- const out: Pt[] = [];
- const start = ((layer.turn ?? -90) * Math.PI) / 180;
- if (layer.shape === 'star') {
- for (let i = 0; i < n * 2; i++) {
- const r = i % 2 === 0 ? outer : inner;
- const a = start + (i / (n * 2)) * Math.PI * 2;
- out.push([cx + r * Math.cos(a), cy + r * Math.sin(a)]);
- }
- } else {
- // A tooth is flat on top, narrower than its root, with the same gap between.
- const step = (Math.PI * 2) / n, tip = (layer.tooth ?? 0.3) * step, root = tip * 1.5;
- for (let i = 0; i < n; i++) {
- const a = start + i * step;
- for (const [r, d] of [[inner, -root], [outer, -tip], [outer, tip], [inner, root]] as const) out.push([cx + r * Math.cos(a + d), cy + r * Math.sin(a + d)]);
- }
- }
- return { runs: closed(out), middle: [cx, cy] };
- }
- case 'path': {
- const runs = parsePath(layer.d!);
- const all = runs.flatMap((r) => r.points);
- if (all.length === 0) throw new Error('path draws nothing');
- const c = all.reduce<[number, number]>((s, p) => [s[0] + p[0] / all.length, s[1] + p[1] / all.length], [0, 0]);
- return { runs, middle: c };
- }
- default:
- return { runs: [], middle: [0, 0] };
- }
-}
-
-// ---- Masks ----------------------------------------------------------------------
-
-/** What each pixel has of a filled outline, non-zero: a span's ends count for what they cover, so an edge has no stairs. */
-/** The nine places a thing drawn in a repeating picture shows: where it is, and one picture away each way. */
-const ROUND: readonly Pt[] = [[0, 0], [-1, 0], [1, 0], [0, -1], [0, 1], [-1, -1], [1, -1], [-1, 1], [1, 1]];
-
-/** Whether points moved by (@p dx, @p dy), grown by @p reach, touch the picture at all. */
-function touches(points: Iterable<readonly number[]>, dx: number, dy: number, reach: number, w: number, h: number): boolean {
- let [x0, y0, x1, y1] = [Infinity, Infinity, -Infinity, -Infinity];
- for (const p of points) {
- if (p[0]! < x0) x0 = p[0]!;
- if (p[0]! > x1) x1 = p[0]!;
- if (p[1]! < y0) y0 = p[1]!;
- if (p[1]! > y1) y1 = p[1]!;
- }
- return x1 + dx + reach > 0 && x0 + dx - reach < w && y1 + dy + reach > 0 && y0 + dy - reach < h;
-}
-
-/** A mask drawn once, or in a repeating picture once for each place it shows, the most of them kept. */
-function goingRound(points: () => Iterable<readonly number[]>, reach: number, w: number, h: number, draw: (dx: number, dy: number) => Float32Array): Float32Array {
- if (!isWrapping()) return draw(0, 0);
- let out: Float32Array | null = null;
- for (const [ox, oy] of ROUND) {
- const [dx, dy] = [ox * w, oy * h];
- if ((ox !== 0 || oy !== 0) && !touches(points(), dx, dy, reach, w, h)) continue;
- const part = draw(dx, dy);
- if (!out) { out = part; continue; }
- for (let i = 0; i < out.length; i++) if (part[i]! > out[i]!) out[i] = part[i]!;
- }
- return out ?? new Float32Array(w * h);
-}
-
-function fillMask(runs: readonly (readonly Pt[])[], w: number, h: number): Float32Array {
- return goingRound(() => runs.flat(), 1, w, h, (dx, dy) => fillMaskOnce(dx === 0 && dy === 0 ? runs : runs.map((run) => run.map(([x, y]) => [x + dx, y + dy] as Pt)), w, h));
-}
-
-function fillMaskOnce(runs: readonly (readonly Pt[])[], w: number, h: number): Float32Array {
- const mask = new Float32Array(w * h);
- const edges: { x0: number; y0: number; x1: number; y1: number; dir: number }[] = [];
- let top = Infinity, bottom = -Infinity;
- for (const run of runs) {
- for (let i = 0; i < run.length; i++) {
- const [a, b] = [run[i]!, run[(i + 1) % run.length]!];
- if (a[1] === b[1]) continue;
- const down = a[1] < b[1];
- edges.push(down ? { x0: a[0], y0: a[1], x1: b[0], y1: b[1], dir: 1 } : { x0: b[0], y0: b[1], x1: a[0], y1: a[1], dir: -1 });
- top = Math.min(top, a[1], b[1]); bottom = Math.max(bottom, a[1], b[1]);
- }
- }
- if (edges.length === 0) return mask;
- const share = 1 / SUBSCANS;
- const from = Math.max(0, Math.floor(top)), to = Math.min(h - 1, Math.ceil(bottom));
- const hits: { x: number; dir: number }[] = [];
- for (let y = from; y <= to; y++) {
- for (let s = 0; s < SUBSCANS; s++) {
- const sy = y + (s + 0.5) * share;
- hits.length = 0;
- for (const e of edges) {
- if (sy < e.y0 || sy >= e.y1) continue;
- hits.push({ x: e.x0 + ((sy - e.y0) / (e.y1 - e.y0)) * (e.x1 - e.x0), dir: e.dir });
- }
- if (hits.length < 2) continue;
- hits.sort((a, b) => a.x - b.x);
- let winding = 0;
- for (let i = 0; i + 1 < hits.length; i++) {
- winding += hits[i]!.dir;
- if (winding === 0) continue;
- const [l, r] = [Math.max(0, hits[i]!.x), Math.min(w, hits[i + 1]!.x)];
- if (r <= l) continue;
- const [il, ir] = [Math.floor(l), Math.min(w - 1, Math.floor(r))];
- const row = y * w;
- if (il === ir) { mask[row + il]! += (r - l) * share; continue; }
- mask[row + il]! += (il + 1 - l) * share;
- for (let x = il + 1; x < ir; x++) mask[row + x]! += share;
- mask[row + ir]! += (r - ir) * share;
- }
- }
- }
- for (let i = 0; i < mask.length; i++) if (mask[i]! > 1) mask[i] = 1;
- return mask;
-}
-
-/** Past this a mitre is bevelled: a point of about 11 degrees still comes out sharp, and a thinner one does not throw a long spike. */
-const MITER_LIMIT = 10;
-const STROKE_SAMPLES = 6;
-
-/** What each pixel has of a stroke. Round joins and ends come from the distance to the line; the others are built of convex pieces, sampled where a pixel crosses an edge: a distance from the edges would trail a faint tail off a sharp point. */
-function strokeMask(runs: readonly { points: readonly Pt[]; closed: boolean }[], width: number, w: number, h: number, join: 'round' | 'miter' | 'bevel' = 'round', cap: 'round' | 'butt' | 'square' = 'round'): Float32Array {
- // A mitre can reach a good way past its line, so the reach is generous: a copy drawn for nothing costs little.
- return goingRound(() => runs.flatMap((r) => r.points), width * (join === 'miter' ? MITER_LIMIT : 1) + 2, w, h, (dx, dy) => strokeMaskOnce(
- dx === 0 && dy === 0 ? runs : runs.map((r) => ({ closed: r.closed, points: r.points.map(([x, y]) => [x + dx, y + dy] as Pt) })), width, w, h, join, cap));
-}
-
-function strokeMaskOnce(runs: readonly { points: readonly Pt[]; closed: boolean }[], width: number, w: number, h: number, join: 'round' | 'miter' | 'bevel' = 'round', cap: 'round' | 'butt' | 'square' = 'round'): Float32Array {
- const mask = new Float32Array(w * h);
- const half = width / 2;
- const capsule = (a: Pt, b: Pt): void => {
- const [x0, x1] = [Math.max(0, Math.floor(Math.min(a[0], b[0]) - half - 1)), Math.min(w - 1, Math.ceil(Math.max(a[0], b[0]) + half + 1))];
- const [y0, y1] = [Math.max(0, Math.floor(Math.min(a[1], b[1]) - half - 1)), Math.min(h - 1, Math.ceil(Math.max(a[1], b[1]) + half + 1))];
- const [ex, ey] = [b[0] - a[0], b[1] - a[1]];
- const len = ex * ex + ey * ey;
- for (let y = y0; y <= y1; y++) {
- for (let x = x0; x <= x1; x++) {
- const [px, py] = [x + 0.5 - a[0], y + 0.5 - a[1]];
- const t = len > 0 ? Math.max(0, Math.min(1, (px * ex + py * ey) / len)) : 0;
- const v = Math.max(0, Math.min(1, half - Math.hypot(px - ex * t, py - ey * t) + 0.5));
- if (v > mask[y * w + x]!) mask[y * w + x] = v;
- }
- }
- };
- const convex = (poly: readonly Pt[]): void => {
- let area = 0;
- for (let i = 0; i < poly.length; i++) {
- const [a, b] = [poly[i]!, poly[(i + 1) % poly.length]!];
- area += a[0] * b[1] - b[0] * a[1];
- }
- if (area === 0) return;
- const edges = poly.map((a, i) => {
- const b = poly[(i + 1) % poly.length]!;
- const len = Math.hypot(b[0] - a[0], b[1] - a[1]) || 1;
- return { x: a[0], y: a[1], nx: (-(b[1] - a[1]) / len) * Math.sign(area), ny: ((b[0] - a[0]) / len) * Math.sign(area) };
- });
- const [xs, ys] = [poly.map((p) => p[0]), poly.map((p) => p[1])];
- const [x0, x1] = [Math.max(0, Math.floor(Math.min(...xs) - 1)), Math.min(w - 1, Math.ceil(Math.max(...xs) + 1))];
- const [y0, y1] = [Math.max(0, Math.floor(Math.min(...ys) - 1)), Math.min(h - 1, Math.ceil(Math.max(...ys) + 1))];
- for (let y = y0; y <= y1; y++) {
- for (let x = x0; x <= x1; x++) {
- let inside = Infinity;
- for (const e of edges) inside = Math.min(inside, (x + 0.5 - e.x) * e.nx + (y + 0.5 - e.y) * e.ny);
- if (inside <= -0.75) continue;
- let v = 1;
- if (inside < 0.75) {
- let hits = 0;
- for (let sy = 0; sy < STROKE_SAMPLES; sy++) {
- for (let sx = 0; sx < STROKE_SAMPLES; sx++) {
- const [px, py] = [x + (sx + 0.5) / STROKE_SAMPLES, y + (sy + 0.5) / STROKE_SAMPLES];
- if (edges.every((e) => (px - e.x) * e.nx + (py - e.y) * e.ny >= 0)) hits++;
- }
- }
- v = hits / (STROKE_SAMPLES * STROKE_SAMPLES);
- }
- if (v > mask[y * w + x]!) mask[y * w + x] = v;
- }
- }
- };
- for (const run of runs) {
- if (join === 'round' && cap === 'round') {
- const count = run.closed ? run.points.length : run.points.length - 1;
- for (let i = 0; i < count; i++) capsule(run.points[i]!, run.points[(i + 1) % run.points.length]!);
- continue;
- }
- // A point repeated has no direction to join from.
- const pts = run.points.filter((p, i, all) => i === 0 || Math.hypot(p[0] - all[i - 1]![0], p[1] - all[i - 1]![1]) > 1e-6);
- if (run.closed && pts.length > 1 && Math.hypot(pts[0]![0] - pts[pts.length - 1]![0], pts[0]![1] - pts[pts.length - 1]![1]) <= 1e-6) pts.pop();
- if (pts.length < 2) {
- if (pts[0] && cap !== 'butt') capsule(pts[0], pts[0]);
- continue;
- }
- const count = run.closed ? pts.length : pts.length - 1;
- const direction = (i: number): Pt => {
- const [a, b] = [pts[i]!, pts[(i + 1) % pts.length]!];
- const len = Math.hypot(b[0] - a[0], b[1] - a[1]);
- return [(b[0] - a[0]) / len, (b[1] - a[1]) / len];
- };
- for (let i = 0; i < count; i++) {
- const [a, b] = [pts[i]!, pts[(i + 1) % pts.length]!];
- const u = direction(i);
- const [nx, ny] = [-u[1] * half, u[0] * half];
- // A joined end runs on by a pixel's half diagonal, or two pieces half covering a pixel leave a notch across the line.
- const end = (open: boolean): number => (open ? (cap === 'square' ? half : 0) : 0.75);
- const [s, e] = [end(!run.closed && i === 0), end(!run.closed && i === count - 1)];
- const [ax, ay, bx, by] = [a[0] - u[0] * s, a[1] - u[1] * s, b[0] + u[0] * e, b[1] + u[1] * e];
- convex([[ax + nx, ay + ny], [bx + nx, by + ny], [bx - nx, by - ny], [ax - nx, ay - ny]]);
- }
- if (!run.closed && cap === 'round') {
- capsule(pts[0]!, pts[0]!);
- capsule(pts[pts.length - 1]!, pts[pts.length - 1]!);
- }
- for (let i = run.closed ? 0 : 1; i < (run.closed ? pts.length : pts.length - 1); i++) {
- const p = pts[i]!;
- const [u0, u1] = [direction((i - 1 + pts.length) % pts.length), direction(i)];
- const cross = u0[0] * u1[1] - u0[1] * u1[0];
- if (join === 'round') {
- capsule(p, p);
- continue;
- }
- if (Math.abs(cross) < 1e-6) continue;
- // Turning toward +normal, the outside of the corner is the other side.
- const side = cross > 0 ? -1 : 1;
- const [n0, n1]: [Pt, Pt] = [[-u0[1] * side, u0[0] * side], [-u1[1] * side, u1[0] * side]];
- const [A, B]: [Pt, Pt] = [[p[0] + n0[0] * half, p[1] + n0[1] * half], [p[0] + n1[0] * half, p[1] + n1[1] * half]];
- const [mx, my] = [n0[0] + n1[0], n0[1] + n1[1]];
- const length = Math.hypot(mx, my);
- const ratio = length > 0 ? 2 / length : Infinity;
- if (join === 'miter' && ratio <= MITER_LIMIT) convex([p, A, [p[0] + (mx / length) * half * ratio, p[1] + (my / length) * half * ratio], B]);
- else convex([p, A, B]);
- }
- }
- return mask;
-}
-
-function shifted(src: Float32Array, w: number, h: number, dx: number, dy: number): Float32Array {
- const [ix, iy] = [Math.round(dx), Math.round(dy)];
- if (ix === 0 && iy === 0) return src;
- const out = new Float32Array(w * h);
- if (isWrapping()) {
- for (let y = 0; y < h; y++) {
- const fy = (((y - iy) % h) + h) % h;
- for (let x = 0; x < w; x++) out[y * w + x] = src[fy * w + ((((x - ix) % w) + w) % w)]!;
- }
- return out;
- }
- for (let y = 0; y < h; y++) {
- const fy = y - iy;
- if (fy < 0 || fy >= h) continue;
- for (let x = 0; x < w; x++) {
- const fx = x - ix;
- if (fx >= 0 && fx < w) out[y * w + x] = src[fy * w + fx]!;
- }
- }
- return out;
-}
-
-/** From a place in the picture to where it lies on four corners, 0..1 each way; null when the corners cannot be solved. */
-function quadToUnit(q: readonly (readonly number[])[]): ((x: number, y: number) => readonly [number, number]) | null {
- const [[x0, y0], [x1, y1], [x2, y2], [x3, y3]] = q as unknown as [[number, number], [number, number], [number, number], [number, number]];
- // The square onto the corners, as a projective map.
- const [dx1, dx2, sx, dy1, dy2, sy] = [x1 - x2, x3 - x2, x0 - x1 + x2 - x3, y1 - y2, y3 - y2, y0 - y1 + y2 - y3];
- const det = dx1 * dy2 - dx2 * dy1;
- if (Math.abs(det) < 1e-9) return null;
- const g = (sx * dy2 - dx2 * sy) / det, h = (dx1 * sy - sx * dy1) / det;
- const [a, b, c, d, e, f] = [x1 - x0 + g * x1, x3 - x0 + h * x3, x0, y1 - y0 + g * y1, y3 - y0 + h * y3, y0];
- // Its inverse, by cofactors.
- const [A, B, C, D, E, F, G, H, I] = [e - f * h, c * h - b, b * f - c * e, f * g - d, a - c * g, c * d - a * f, d * h - e * g, b * g - a * h, a * e - b * d];
- return (x, y) => {
- const z = G * x + H * y + I;
- return [(A * x + B * y + C) / z, (D * x + E * y + F) / z];
- };
-}
-
-/** The other way: from 0..1 each way on four corners to the place in the picture. */
-function unitToQuad(q: readonly (readonly number[])[]): (u: number, v: number) => Pt {
- const [[x0, y0], [x1, y1], [x2, y2], [x3, y3]] = q as unknown as [[number, number], [number, number], [number, number], [number, number]];
- const [dx1, dx2, sx, dy1, dy2, sy] = [x1 - x2, x3 - x2, x0 - x1 + x2 - x3, y1 - y2, y3 - y2, y0 - y1 + y2 - y3];
- const det = dx1 * dy2 - dx2 * dy1 || 1e-9;
- const g = (sx * dy2 - dx2 * sy) / det, h = (dx1 * sy - sx * dy1) / det;
- const [a, b, c, d, e, f] = [x1 - x0 + g * x1, x3 - x0 + h * x3, x0, y1 - y0 + g * y1, y3 - y0 + h * y3, y0];
- return (u, v) => {
- const z = g * u + h * v + 1;
- return [(a * u + b * v + c) / z, (d * u + e * v + f) / z];
- };
-}
-
-/** A block's face, named as "id.a", and the part of it asked for. A name that is not there says so. */
-function faceCorners(layer: ImageLayer, drawn: Drawn): readonly (readonly number[])[] | null {
- const [id, key] = (layer.face as string).replace(/^@/, '').split('.') as [string, string | undefined];
- const quad = key ? drawn.blocks.get(id)?.[key] : undefined;
- if (!quad) {
- drawn.notes.push(`layer ${layer.id ?? layer.shape}: face "${layer.face}" names no face of a block drawn before it, so it drew nothing`);
- return null;
- }
- if (!layer.within) return quad;
- const to = unitToQuad(quad);
- const [l, t, r, b] = layer.within as [number, number, number, number];
- return [to(l, t), to(r, t), to(r, b), to(l, b)];
-}
-
-/** Marks in rows and columns, each with its own colour and whether it is on, sampled within the pixel so distant rows blend and do not shimmer. */
-function gridPaint(fill: Extract<ImageFill, { type: 'grid' }>, m: Matrix): (x: number, y: number) => Rgba {
- const colors = fill.colors.map(parseColor);
- const ground = fill.ground ? parseColor(fill.ground) : ([0, 0, 0, 0] as Rgba);
- const off = fill.off ? parseColor(fill.off) : ground;
- const [mw, mh] = fill.mark ?? [0.6, 0.6];
- const [lit, seed] = [fill.lit ?? 1, fill.seed ?? 1];
- const inverse = invert(m);
- const toUnit = fill.quad ? quadToUnit(fill.quad) : null;
- const [cols, rows] = fill.cells ?? [1, 1];
- const [cw, ch] = fill.cell ?? [1, 1];
- const at = (x: number, y: number): Rgba => {
- let u: number, v: number;
- if (toUnit) {
- const p = toUnit(x, y);
- if (p[0] < 0 || p[1] < 0 || p[0] > 1 || p[1] > 1) return ground;
- [u, v] = [p[0] * cols, p[1] * rows];
- } else {
- const p = apply(inverse, [x, y]);
- [u, v] = [p[0] / cw, p[1] / ch];
- }
- const [i, j] = [Math.floor(u), Math.floor(v)];
- if (Math.abs(u - i - 0.5) > mw / 2 || Math.abs(v - j - 0.5) > mh / 2) return ground;
- if (hash01(seed * 41 + i, j) >= lit) return off;
- return colors[Math.floor(hash01(seed * 43 + j, i) * colors.length) % colors.length]!;
- };
- const SAMPLES = 3;
- return (x, y) => {
- const sum = [0, 0, 0, 0];
- for (let sy = 0; sy < SAMPLES; sy++) {
- for (let sx = 0; sx < SAMPLES; sx++) {
- const c = at(x - 0.5 + (sx + 0.5) / SAMPLES, y - 0.5 + (sy + 0.5) / SAMPLES);
- sum[0]! += c[0] * c[3]; sum[1]! += c[1] * c[3]; sum[2]! += c[2] * c[3]; sum[3]! += c[3];
- }
- }
- const a = sum[3]!;
- return a > 0 ? [sum[0]! / a, sum[1]! / a, sum[2]! / a, a / (SAMPLES * SAMPLES)] : [0, 0, 0, 0];
- };
-}
-
-/** Draws text to coverage in the picture's pixels. Lives in whoever has fonts: this file has none. */
-export type ImageTextDrawer = (layer: ImageLayer, m: readonly number[], w: number, h: number) => { fill: Float32Array; line: Float32Array | null };
-
-function paintOf(fill: ImageFill, m: Matrix, drawn?: Drawn, w = 0): (x: number, y: number) => Rgba {
- if (typeof fill === 'string') {
- const c = parseColor(fill);
- return () => c;
- }
- const stops = [...(fill.type === 'image' || fill.type === 'grid' ? [] : fill.stops)].map(([t, c]) => [t, parseColor(c)] as const).sort((a, b) => a[0] - b[0]);
- const inverse = invert(m);
- const at = (t: number): Rgba => {
- if (t <= stops[0]![0]) return stops[0]![1];
- for (let i = 1; i < stops.length; i++) {
- if (t <= stops[i]![0]) {
- const [t0, a] = stops[i - 1]!, [t1, b] = stops[i]!;
- const s = (t - t0) / Math.max(1e-6, t1 - t0);
- return [a[0] + (b[0] - a[0]) * s, a[1] + (b[1] - a[1]) * s, a[2] + (b[2] - a[2]) * s, a[3] + (b[3] - a[3]) * s];
- }
- }
- return stops[stops.length - 1]![1];
- };
- if (fill.type === 'image') {
- const image = drawn?.images.get(fill.image);
- if (!image) {
- drawn?.notes.push(`a fill names image "${fill.image}", which was not drawn before it`);
- return () => [0, 0, 0, 0];
- }
- return (x, y) => {
- const i = (Math.floor(y) * w + Math.floor(x)) * 4;
- return [image[i] ?? 0, image[i + 1] ?? 0, image[i + 2] ?? 0, image[i + 3] ?? 0];
- };
- }
- if (fill.type === 'grid') return gridPaint(fill, m);
- if (fill.type === 'form') {
- const figure = drawn?.figures.get(fill.figure);
- if (!figure) {
- drawn?.notes.push(`a form names figure "${fill.figure}", which was not drawn before it`);
- return () => at(0);
- }
- const light = fill.light ? figureLight(fill.light) : figure.light;
- return (x, y) => {
- const i = Math.floor(y) * w + Math.floor(x);
- const [nx, ny, nz] = [figure.normals[i * 3] ?? 0, figure.normals[i * 3 + 1] ?? 0, figure.normals[i * 3 + 2] ?? 0];
- return at(0.5 + 0.5 * (nx * light[0] + ny * light[1] + nz * light[2]));
- };
- }
- if (fill.type === 'noise') {
- const [scale, octaves, seed] = [fill.scale ?? 32, fill.octaves ?? 4, fill.seed ?? 0];
- if (isWrapping() && tileWidth > 0) {
- // A whole number of cells across the picture, so the last meets the first; the scale gives a little to make it so.
- // In the picture's own pixels and not the layer's: a noise turned or scaled with its layer would not come round.
- const [cx, cy] = [Math.max(1, Math.round(tileWidth / scale)), Math.max(1, Math.round(tileHeight / scale))];
- return (x, y) => at(fractalNoise(((x - 0.5) / tileWidth) * cx, ((y - 0.5) / tileHeight) * cy, octaves, seed, cx, cy));
- }
- return (x, y) => {
- const p = apply(inverse, [x - 0.5, y - 0.5]);
- return at(fractalNoise(p[0] / scale, p[1] / scale, octaves, seed));
- };
- }
- if (fill.type === 'linear') {
- const [a, b] = [fill.from, fill.to];
- const [ex, ey] = [b[0] - a[0], b[1] - a[1]];
- const len = ex * ex + ey * ey || 1;
- return (x, y) => {
- const p = apply(inverse, [x, y]);
- return at(((p[0] - a[0]) * ex + (p[1] - a[1]) * ey) / len);
- };
- }
- const [cx, cy] = fill.at;
- const r = fill.radius;
- return (x, y) => {
- const p = apply(inverse, [x, y]);
- return at(Math.hypot(p[0] - cx, p[1] - cy) / r);
- };
-}
-
-/** Premultiplied: what blending wants, and what a blur of an edge wants. */
-class Canvas {
- readonly px: Float32Array;
- constructor(readonly w: number, readonly h: number) { this.px = new Float32Array(w * h * 4); }
-}
-
-type Blend = NonNullable<ImageLayer['blend']>;
-const softLight = (b: number, s: number): number => {
- if (s <= 0.5) return b - (1 - 2 * s) * b * (1 - b);
- const d = b <= 0.25 ? ((16 * b - 12) * b + 4) * b : Math.sqrt(b);
- return b + (2 * s - 1) * (d - b);
-};
-const dodge = (b: number, s: number): number => (b <= 0 ? 0 : s >= 1 ? 1 : Math.min(1, b / (1 - s)));
-const burn = (b: number, s: number): number => (b >= 1 ? 1 : s <= 0 ? 0 : 1 - Math.min(1, (1 - b) / s));
-const hard = (b: number, s: number): number => (s < 0.5 ? 2 * b * s : 1 - 2 * (1 - b) * (1 - s));
-const blendChannel = (mode: Blend, b: number, s: number): number => {
- switch (mode) {
- case 'multiply': return b * s;
- case 'screen': return b + s - b * s;
- case 'overlay': return hard(s, b);
- case 'add': return Math.min(1, b + s);
- case 'softLight': return softLight(b, s);
- case 'hardLight': return hard(b, s);
- case 'vividLight': return s < 0.5 ? burn(b, 2 * s) : dodge(b, 2 * s - 1);
- case 'linearLight': return Math.max(0, Math.min(1, b + 2 * s - 1));
- case 'pinLight': return s < 0.5 ? Math.min(b, 2 * s) : Math.max(b, 2 * s - 1);
- case 'colorDodge': return dodge(b, s);
- case 'colorBurn': return burn(b, s);
- case 'linearBurn': return Math.max(0, b + s - 1);
- case 'darken': return Math.min(b, s);
- case 'lighten': return Math.max(b, s);
- case 'difference': return Math.abs(b - s);
- case 'exclusion': return b + s - 2 * b * s;
- case 'subtract': return Math.max(0, b - s);
- case 'divide': return s <= 0 ? 1 : Math.min(1, b / s);
- default: return s;
- }
-};
-
-/** Keeping a colour's hue and saturation in range when its lightness is set, as the colour blend modes need. */
-function withLight(c: readonly [number, number, number], light: number): [number, number, number] {
- const d = light - lightnessOf(c[0], c[1], c[2]);
- const out: [number, number, number] = [c[0] + d, c[1] + d, c[2] + d];
- const l = lightnessOf(out[0], out[1], out[2]);
- const [lo, hi] = [Math.min(...out), Math.max(...out)];
- if (lo < 0) for (let i = 0; i < 3; i++) out[i] = l + ((out[i]! - l) * l) / (l - lo);
- if (hi > 1) for (let i = 0; i < 3; i++) out[i] = l + ((out[i]! - l) * (1 - l)) / (hi - l);
- return out;
-}
-const colourfulness = (c: readonly [number, number, number]): number => Math.max(...c) - Math.min(...c);
-function withColourfulness(c: readonly [number, number, number], sat: number): [number, number, number] {
- const [lo, hi] = [Math.min(...c), Math.max(...c)];
- if (hi === lo) return [0, 0, 0];
- return [((c[0] - lo) * sat) / (hi - lo), ((c[1] - lo) * sat) / (hi - lo), ((c[2] - lo) * sat) / (hi - lo)];
-}
-/** The modes that work on a colour whole: this hue on that lightness, and so on. */
-function blendWhole(mode: Blend, d: readonly [number, number, number], s: readonly [number, number, number]): [number, number, number] {
- switch (mode) {
- case 'hue': return withLight(withColourfulness(s, colourfulness(d)), lightnessOf(d[0], d[1], d[2]));
- case 'saturation': return withLight(withColourfulness(d, colourfulness(s)), lightnessOf(d[0], d[1], d[2]));
- case 'color': return withLight(s, lightnessOf(d[0], d[1], d[2]));
- default: return withLight(d, lightnessOf(s[0], s[1], s[2]));
- }
-}
-const WHOLE_MODES: ReadonlySet<Blend> = new Set<Blend>(['hue', 'saturation', 'color', 'luminosity']);
-
-/** @p color straight, at coverage @p m, over what is there. */
-function put(c: Canvas, i: number, r: number, g: number, b: number, a: number, mode: Blend): void {
- if (a <= 0) return;
- const p = c.px, at = i * 4;
- const da = p[at + 3]!;
- if (mode === 'normal' || da <= 0) {
- p[at] = p[at]! * (1 - a) + r * a; p[at + 1] = p[at + 1]! * (1 - a) + g * a; p[at + 2] = p[at + 2]! * (1 - a) + b * a;
- } else {
- const [dr, dg, db] = [p[at]! / da, p[at + 1]! / da, p[at + 2]! / da];
- if (WHOLE_MODES.has(mode)) {
- const whole = blendWhole(mode, [dr, dg, db], [r, g, b]);
- const [mr, mg, mb] = [(1 - da) * r + da * whole[0], (1 - da) * g + da * whole[1], (1 - da) * b + da * whole[2]];
- p[at] = p[at]! * (1 - a) + mr * a; p[at + 1] = p[at + 1]! * (1 - a) + mg * a; p[at + 2] = p[at + 2]! * (1 - a) + mb * a;
- p[at + 3] = da + a - da * a;
- return;
- }
- const mix = (d: number, s: number): number => (1 - da) * s + da * blendChannel(mode, d, s);
- p[at] = p[at]! * (1 - a) + mix(dr, r) * a; p[at + 1] = p[at + 1]! * (1 - a) + mix(dg, g) * a; p[at + 2] = p[at + 2]! * (1 - a) + mix(db, b) * a;
- }
- p[at + 3] = da + a - da * a;
-}
-
-/** Raised edges from how the shape's edge slopes: lit on the side toward the light, and shaded away from it. */
-function bevelEffect(e: ImageEffect, c: Canvas, mask: Float32Array): void {
- const { w, h } = c;
- const soft = blurMask(mask, w, h, Math.max(0.5, (e.size ?? 4) / 2));
- const a = ((e.angle ?? 225) * Math.PI) / 180;
- const [lx, ly] = [Math.cos(a), Math.sin(a)];
- const [hr, hg, hb, ha] = parseColor(e.color ?? '#ffffff');
- const [sr, sg, sb, sa] = parseColor(e.shade ?? '#000000');
- const gain = (e.depth ?? 1) * (e.size ?? 4) * 2;
- const op = e.opacity ?? 0.8;
- for (let y = 1; y < h - 1; y++) {
- for (let x = 1; x < w - 1; x++) {
- const i = y * w + x;
- if (mask[i]! <= 0) continue;
- // The edge rises inward, so it faces against its slope.
- const facing = -((soft[i + 1]! - soft[i - 1]!) * lx + (soft[i + w]! - soft[i - w]!) * ly) * gain;
- if (facing > 0) put(c, i, hr, hg, hb, Math.min(1, facing) * op * ha * mask[i]!, 'screen');
- else if (facing < 0) put(c, i, sr, sg, sb, Math.min(1, -facing) * op * sa * mask[i]!, 'multiply');
- }
- }
-}
-
-function effectLayers(effects: readonly ImageEffect[] | undefined, under: boolean, c: Canvas, mask: Float32Array): void {
- const { w, h } = c;
- for (const e of effects ?? []) {
- const isUnder = e.type === 'shadow' || e.type === 'glow';
- if (isUnder !== under) continue;
- if (e.type === 'bevel') { bevelEffect(e, c, mask); continue; }
- if (e.type === 'overlay') {
- const paint = paintOf(e.fill!, IDENTITY);
- for (let y = 0; y < h; y++) {
- for (let x = 0; x < w; x++) {
- const i = y * w + x;
- if (mask[i]! <= 0) continue;
- const col = paint(x + 0.5, y + 0.5);
- put(c, i, col[0], col[1], col[2], col[3] * mask[i]! * (e.opacity ?? 1), e.blend ?? 'normal');
- }
- }
- continue;
- }
- const [r, g, b, ca] = parseColor(e.color ?? (e.type === 'glow' || e.type === 'innerGlow' ? '#ffffff' : '#000000'));
- const op = (e.opacity ?? 1) * ca;
- const sigma = e.blur ?? (e.type === 'glow' ? 8 : 4);
- if (isUnder) {
- let src = shifted(mask, w, h, e.x ?? 0, e.y ?? 0);
- // Spread first, so a glow is bright at the edge and not merely soft.
- if (e.type === 'glow') src = src.map((v) => Math.min(1, v * 1.6));
- const soft = blurMask(src, w, h, sigma);
- for (let i = 0; i < soft.length; i++) put(c, i, r, g, b, Math.min(1, soft[i]! * op), e.type === 'glow' ? 'screen' : 'normal');
- } else {
- // Inside: what the shape leaves out, softened and moved, and kept within the shape.
- const inv = mask.map((v) => 1 - v);
- const soft = blurMask(shifted(inv, w, h, e.x ?? 0, e.y ?? 0), w, h, sigma);
- const mode: Blend = e.type === 'innerGlow' ? 'screen' : 'normal';
- for (let i = 0; i < soft.length; i++) put(c, i, r, g, b, Math.min(1, soft[i]! * mask[i]! * op), mode);
- }
- }
-}
-
-interface Drawn { masks: Map<string, Float32Array>; notes: string[]; bounds: Map<string, ImageBox>; painted: Map<string, { entries: number; strokes: number }>; figures: Map<string, FlatFigure>; figureJoints: Map<string, Record<string, readonly [number, number]>>; showGuides: boolean; pictures: Readonly<Record<string, RgbaBitmap>>; images: Map<string, Float32Array>; text: ImageTextDrawer | undefined; blocks: Map<string, Record<string, readonly (readonly number[])[]>> }
-
-/** x, y, width and height in the picture's pixels. */
-export type ImageBox = readonly [number, number, number, number];
-
-/** The box of whatever covers at least half a pixel: where a shape's edge is, and not the last faint pixel of a glow. */
-function boxOf(w: number, h: number, covers: (i: number) => boolean): ImageBox | null {
- let [x0, y0, x1, y1] = [w, h, -1, -1];
- for (let y = 0; y < h; y++) {
- for (let x = 0; x < w; x++) {
- if (!covers(y * w + x)) continue;
- if (x < x0) x0 = x;
- if (x > x1) x1 = x;
- if (y < y0) y0 = y;
- y1 = y;
- }
- }
- return x1 < 0 ? null : [x0, y0, x1 - x0 + 1, y1 - y0 + 1];
-}
-
-function noteBox(drawn: Drawn, id: string | undefined, mask: Float32Array, w: number, h: number): void {
- if (!id) return;
- // Half of what it reaches: a faint layer is still somewhere, and half of full coverage would miss it.
- let peak = 0;
- for (let i = 0; i < mask.length; i++) if (mask[i]! > peak) peak = mask[i]!;
- if (peak <= 0.004) return;
- const box = boxOf(w, h, (i) => mask[i]! >= Math.min(0.5, peak / 2));
- if (box) drawn.bounds.set(id, box);
-}
-
-function drawLayer(c: Canvas, layer: ImageLayer, parent: Matrix, drawn: Drawn): void {
- const { w, h } = c;
- if (layer.visible === false) {
- // A guide hidden from sight is still what others are clipped to and lit by. Anything else hidden is simply not there.
- if (isGuideLayer(layer)) {
- const { visible: _v, ...shown } = layer;
- drawLayer(new Canvas(w, h), { ...shown, guide: false }, parent, drawn);
- }
- return;
- }
- // What a guide masks is still wanted when it is not seen, so it draws somewhere that is thrown away.
- if (!drawn.showGuides && isGuideLayer(layer)) {
- drawLayer(new Canvas(w, h), { ...layer, guide: false }, parent, drawn);
- return;
- }
- if (layer.mirror) {
- const { mirror, ...rest } = layer;
- const axis = mirror === 'x' ? { x: -1, y: 1 } : { x: 1, y: -1 };
- // Across the middle of the picture.
- const flip: Matrix = axis.x < 0 ? [-1, 0, 0, 1, w / drawnScale(parent), 0] : [1, 0, 0, -1, 0, h / drawnScale(parent)];
- drawLayer(c, rest, parent, drawn);
- drawLayer(c, { ...rest, ...(layer.id ? { id: `${layer.id}.mirrored` } : {}) }, times(parent, flip), drawn);
- return;
- }
- const opacity = layer.opacity ?? 1;
- const blend: Blend = layer.blend ?? 'normal';
- const named = (id: string): Float32Array | undefined => drawn.masks.get(id.replace(/^@/, ''));
- let clip = layer.clip ? named(layer.clip) : undefined;
- const softened = (mask: Float32Array): Float32Array => {
- let out = mask;
- if (layer.clipGrow) out = grownMask(out, layer.clipGrow * drawnScale(parent), w, h);
- if (layer.clipFeather) out = blurMask(out, w, h, layer.clipFeather * drawnScale(parent));
- return layer.clipInvert ? out.map((v) => 1 - v) : out;
- };
- if (clip) clip = softened(clip);
- // Nothing, and not everything: a clip that failed would otherwise cover the picture in what it was meant to hold in.
- if (layer.clip && !clip) {
- drawn.notes.push(`layer ${layer.id ?? layer.shape}: clip "${layer.clip}" names no layer drawn before it, so it drew nothing`);
- return;
- }
- if (layer.except) {
- const out = named(layer.except);
- if (!out) drawn.notes.push(`layer ${layer.id ?? layer.shape}: except "${layer.except}" names no layer drawn before it`);
- else clip = out.map((v, i) => (1 - v) * (clip ? clip[i]! : 1));
- }
-
- if (layer.blendIf) {
- // Reads the picture as it stands now, so a highlight is chosen by being one.
- const [low, high, soft = 0.1] = layer.blendIf as [number, number, number?];
- const chosen = new Float32Array(w * h);
- for (let i = 0; i < chosen.length; i++) {
- const a = c.px[i * 4 + 3]!;
- const l = a > 0 ? lightnessOf(c.px[i * 4]! / a, c.px[i * 4 + 1]! / a, c.px[i * 4 + 2]! / a) : 0;
- const v = Math.min(soft > 0 ? (l - low) / soft + 1 : l >= low ? 1 : 0, soft > 0 ? (high - l) / soft + 1 : l <= high ? 1 : 0);
- chosen[i] = Math.max(0, Math.min(1, v)) * (clip ? clip[i]! : 1);
- }
- clip = chosen;
- }
-
- if (layer.feather) {
- const { feather, opacity: _o, blend: _b, clip: _c, except: _e, blendIf: _f, clipFeather: _g, clipGrow: _h, clipInvert: _i, ...sharp } = layer;
- const inner = new Canvas(w, h);
- drawLayer(inner, sharp, parent, drawn);
- const alpha = new Float32Array(w * h);
- for (let i = 0; i < alpha.length; i++) alpha[i] = inner.px[i * 4 + 3]!;
- const soft = blurMask(alpha, w, h, feather * drawnScale(parent));
- const mask = new Float32Array(w * h);
- for (let i = 0; i < alpha.length; i++) {
- const a = alpha[i]!;
- if (a <= 0) continue;
- // Fading in from the edge: half way down its blur is the edge, and all of the colour there is the layer's own.
- const kept = a * smoothed(Math.max(0, Math.min(1, (soft[i]! / a - 0.5) * 2.5)));
- mask[i] = kept * (clip ? clip[i]! : 1);
- put(c, i, inner.px[i * 4]! / a, inner.px[i * 4 + 1]! / a, inner.px[i * 4 + 2]! / a, mask[i]! * opacity, blend);
- }
- if (layer.id) drawn.masks.set(layer.id, mask);
- return;
- }
-
- if (layer.shape === 'adjust' || layer.shape === 'filter') {
- const k = drawnScale(parent);
- const next = layer.shape === 'adjust' ? applyAdjust(c.px, w, h, layer.adjust!) : applyFilter(layer.filter!, layer.params ?? {}, c.px, w, h, k);
- for (let i = 0; i < w * h; i++) {
- const keep = opacity * (clip ? clip[i]! : 1);
- if (keep <= 0) continue;
- const at = i * 4;
- if (blend !== 'normal') {
- const a = next[at + 3]!;
- if (a > 0) put(c, i, next[at]! / a, next[at + 1]! / a, next[at + 2]! / a, a * keep, blend);
- continue;
- }
- for (let n = 0; n < 4; n++) c.px[at + n] = c.px[at + n]! + (next[at + n]! - c.px[at + n]!) * keep;
- }
- return;
- }
-
- if (layer.blur) {
- const { blur, opacity: _o, blend: _b, clip: _c, except: _e, blendIf: _f, clipFeather: _g, clipGrow: _h, clipInvert: _i, ...sharp } = layer;
- const inner = new Canvas(w, h);
- drawLayer(inner, sharp, parent, drawn);
- // Blurred as stored, colour already times alpha: blurring straight colour would bring the black of empty pixels in round the edge.
- const [r, g, b, a] = [0, 1, 2, 3].map((k) => {
- const channel = new Float32Array(w * h);
- for (let i = 0; i < channel.length; i++) channel[i] = inner.px[i * 4 + k]!;
- return blurMask(channel, w, h, blur * drawnScale(parent));
- }) as [Float32Array, Float32Array, Float32Array, Float32Array];
- if (layer.id) drawn.masks.set(layer.id, clip ? a.map((v, i) => v * clip![i]!) : a);
- for (let i = 0; i < a.length; i++) {
- const alpha = a[i]!;
- if (alpha <= 0) continue;
- put(c, i, r[i]! / alpha, g[i]! / alpha, b[i]! / alpha, alpha * opacity * (clip ? clip[i]! : 1), blend);
- }
- return;
- }
-
- if (layer.shape === 'group') {
- const inner = new Canvas(w, h);
- const m = times(parent, transformOf(layer.transform, [w / 2, h / 2]));
- for (const child of layer.layers ?? []) drawLayer(inner, child, m, drawn);
- const alpha = new Float32Array(w * h);
- for (let i = 0; i < alpha.length; i++) alpha[i] = inner.px[i * 4 + 3]!;
- if (layer.id) drawn.masks.set(layer.id, alpha);
- noteBox(drawn, layer.id, alpha, w, h);
- effectLayers(layer.effects, true, c, alpha);
- for (let i = 0; i < alpha.length; i++) {
- const a = alpha[i]! * opacity * (clip ? clip[i]! : 1);
- if (a <= 0) continue;
- const s = inner.px[i * 4 + 3]! || 1;
- put(c, i, inner.px[i * 4]! / s, inner.px[i * 4 + 1]! / s, inner.px[i * 4 + 2]! / s, a, blend);
- }
- effectLayers(layer.effects, false, c, alpha);
- return;
- }
-
- if (layer.shape === 'pixels') {
- drawPixels(c, layer, parent, drawn, opacity, blend, clip);
- return;
- }
-
- if (layer.shape === 'paint') {
- drawPaint(c, layer, parent, drawn, opacity, blend, clip);
- return;
- }
-
- if (layer.shape === 'figure') {
- drawFigure(c, layer, parent, drawn, opacity, blend, clip);
- return;
- }
-
- if (layer.shape === 'image') {
- drawPicture(c, layer, parent, drawn, opacity, blend, clip);
- return;
- }
-
- if (layer.shape === 'text') {
- drawText(c, layer, parent, drawn, opacity, blend, clip);
- return;
- }
-
- if (layer.shape === 'block') {
- drawBlock(c, layer, parent, drawn);
- return;
- }
-
- if (layer.shape === 'perspective') {
- drawPerspective(c, layer, parent, opacity);
- return;
- }
-
- if (layer.shape === 'reflect') {
- drawReflection(c, layer, parent, drawn, opacity, clip);
- return;
- }
-
- if (layer.shape === 'bloom') {
- drawBloom(c, layer, parent, opacity, clip);
- return;
- }
-
- if (layer.face && layer.shape === 'rect') {
- const corners = faceCorners(layer, drawn);
- if (!corners) return;
- const { face: _f, within: _w, at: _a, size: _s, radius: _r, ...rest } = layer;
- const fill = rest.fill && typeof rest.fill !== 'string' && rest.fill.type === 'grid' && !rest.fill.quad ? { ...rest.fill, quad: corners } : rest.fill;
- drawLayer(c, { ...rest, ...(fill ? { fill } : {}), shape: 'polygon', points: corners as [number, number][] }, parent, drawn);
- return;
- }
-
- const { runs, middle } = outlinesOf(layer);
- const m = times(parent, transformOf(layer.transform, middle));
- const placed = runs.map((run) => ({ closed: run.closed, points: run.points.map((p) => apply(m, p)) }));
- const scale = Math.sqrt(Math.abs(m[0] * m[3] - m[1] * m[2]));
- const hasFill = layer.fill !== undefined && layer.shape !== 'line';
- const body = layer.shape === 'line' ? new Float32Array(w * h) : fillMask(placed.map((r) => r.points), w, h);
- const align = layer.stroke?.align ?? 'center';
- // An outside stroke is as wide again and goes under the fill. Cut to meet the fill's edge, each would cover part of the same edge pixel and the ground would show between them.
- const line = layer.stroke ? strokeMask(placed, layer.stroke.width * scale * (align === 'outside' ? 2 : 1), w, h, layer.stroke.join, layer.stroke.cap) : null;
- if (line && align === 'inside') for (let i = 0; i < line.length; i++) line[i]! *= body[i]!;
- // Under a see-through fill it must not show, so only the edge pixels keep it.
- if (line && align === 'outside') for (let i = 0; i < line.length; i++) if (body[i]! >= 0.999) line[i] = 0;
- const whole = new Float32Array(w * h);
- let any = 0;
- for (let i = 0; i < whole.length; i++) {
- const v = Math.max(hasFill ? body[i]! : 0, line ? line[i]! : 0) * (clip ? clip[i]! : 1);
- whole[i] = v;
- any += v;
- }
- noteBox(drawn, layer.id, whole, w, h);
- // What clips to this stays inside its stroke: liquid in a flask must not paint over the flask's outline.
- if (layer.id) {
- // A line has no inside but itself.
- const covering = align === 'outside' ? null : line;
- drawn.masks.set(layer.id, layer.shape === 'line' ? whole : body.map((v, i) => v * (covering ? 1 - covering[i]! : 1) * (clip ? clip[i]! : 1)));
- }
- if (any === 0) drawn.notes.push(`layer ${layer.id ?? layer.shape} draws nothing inside the picture${clip ? ', or nothing inside its clip' : ''}`);
- if (layer.erase) {
- for (let i = 0; i < whole.length; i++) {
- const keep = 1 - whole[i]! * opacity;
- for (let k = 0; k < 4; k++) c.px[i * 4 + k]! *= keep;
- }
- return;
- }
- effectLayers(layer.effects, true, c, whole);
- const paintLine = (): void => {
- const paint = paintOf(layer.stroke!.color, m, drawn, w);
- for (let y = 0; y < h; y++) {
- for (let x = 0; x < w; x++) {
- const i = y * w + x;
- const v = line![i]! * (clip ? clip[i]! : 1);
- if (v <= 0) continue;
- const col = paint(x + 0.5, y + 0.5);
- put(c, i, col[0], col[1], col[2], v * col[3] * opacity, blend);
- }
- }
- };
- if (line && align === 'outside') paintLine();
- if (hasFill) {
- const paint = paintOf(layer.fill!, m, drawn, w);
- for (let y = 0; y < h; y++) {
- for (let x = 0; x < w; x++) {
- const i = y * w + x;
- const v = body[i]! * (clip ? clip[i]! : 1);
- if (v <= 0) continue;
- const col = paint(x + 0.5, y + 0.5);
- put(c, i, col[0], col[1], col[2], v * col[3] * opacity, blend);
- }
- }
- }
- effectLayers(layer.effects, false, c, whole);
- if (line && align !== 'outside') paintLine();
-}
-
-const drawnScale = (m: Matrix): number => Math.sqrt(Math.abs(m[0] * m[3] - m[1] * m[2])) || 1;
-
-/** Rows of characters, each a palette's colour, drawn as hard squares. */
-// ---- Brushes ---------------------------------------------------------------------
-
-const hash01 = (a: number, b: number): number => {
- let h = Math.imul(a, 374761393) + Math.imul(b, 668265263);
- h = Math.imul(h ^ (h >>> 13), 1274126177);
- h = Math.imul(h ^ (h >>> 16), 2246822519);
- return ((h ^ (h >>> 16)) >>> 0) / 4294967295;
-};
-
-const smoothed = (t: number): number => t * t * (3 - 2 * t);
-
-interface PathPoint { x: number; y: number; pressure: number; along: number }
-
-/** The tooth of the paper, worked out once: every stroke with grain asks it at every pixel it touches. */
-let paper: { key: string; values: Float32Array } | null = null;
-function paperAt(w: number, h: number, scale: number): Float32Array {
- const key = `${w}x${h}:${scale}`;
- if (paper?.key === key) return paper.values;
- const values = new Float32Array(w * h);
- for (let y = 0; y < h; y++) for (let x = 0; x < w; x++) values[y * w + x] = fractalNoise((x + 0.5) / scale, (y + 0.5) / scale, 3, 77);
- paper = { key, values };
- return values;
-}
-
-/** A stroke's points as a smooth line about a pixel apart, Catmull-Rom so it passes through each. */
-function brushPath(points: readonly (readonly number[])[], m: Matrix): PathPoint[] {
- const placed = points.map((p) => {
- const q = apply(m, [p[0]!, p[1]!]);
- return [q[0], q[1], p[2] ?? 1] as const;
- });
- const out: PathPoint[] = [{ x: placed[0]![0], y: placed[0]![1], pressure: placed[0]![2], along: 0 }];
- for (let i = 0; i + 1 < placed.length; i++) {
- const [p0, p1, p2, p3] = [placed[Math.max(0, i - 1)]!, placed[i]!, placed[i + 1]!, placed[Math.min(placed.length - 1, i + 2)]!];
- const steps = Math.max(1, Math.ceil(Math.hypot(p2[0] - p1[0], p2[1] - p1[1])));
- for (let s = 1; s <= steps; s++) {
- const t = s / steps, t2 = t * t, t3 = t2 * t;
- const curve = (k: 0 | 1): number => 0.5 * (2 * p1[k] + (p2[k] - p0[k]) * t + (2 * p0[k] - 5 * p1[k] + 4 * p2[k] - p3[k]) * t2 + (3 * p1[k] - p0[k] - 3 * p2[k] + p3[k]) * t3);
- const [x, y] = [curve(0), curve(1)];
- const last = out[out.length - 1]!;
- out.push({ x, y, pressure: p1[2] + (p2[2] - p1[2]) * t, along: last.along + Math.hypot(x - last.x, y - last.y) });
- }
- }
- return out;
-}
-
-/** One stroke's coverage before it meets the canvas, so a stroke overlapping itself does not build up into beads. */
-interface StrokeBuffer { mask: Float32Array; rgb: Float32Array; touched: number[] }
-
-function paintStrand(c: Canvas, s: ImageStroke, path: readonly PathPoint[], strand: { offset: number; radius: number | null; from: number; to: number; shade: number; strength: number; seed: number }, scale: number, buffer: StrokeBuffer): void {
- const { w, h } = c;
- const total = path[path.length - 1]!.along;
- const [startColor, endColor] = [parseColor(s.color ?? '#000000'), parseColor(s.to ?? s.color ?? '#000000')];
- const [taperIn, taperOut] = s.taper ?? [0, 0];
- const [fadeIn, fadeOut] = s.fade ?? [0, 0];
- const roundness = s.roundness ?? 1;
- const held = s.angle !== undefined ? [Math.cos((s.angle * Math.PI) / 180), Math.sin((s.angle * Math.PI) / 180)] as const : null;
- const [grain, grainScale, dry, wet, edge, flow] = [s.grain ?? 0, (s.grainScale ?? 2) * scale, s.dry ?? 0, s.wet ?? 0, s.edge ?? 0, s.flow ?? 0];
- const [scatter, dab, spacing] = [s.scatter ?? 0, s.dab ?? 1, s.spacing];
- let loaded: [number, number, number] | null = null;
- let stamp = 0;
- const hardness = s.hardness ?? 0.5;
- const size = s.size * scale;
- const smudge = s.smudge ?? 0;
- const wobble = (s.wobble ?? 0) * scale;
-
- const sample = (x: number, y: number): [number, number, number, number] => {
- const [px, py] = [Math.max(0, Math.min(w - 1, Math.floor(x))), Math.max(0, Math.min(h - 1, Math.floor(y)))];
- const at = (py * w + px) * 4;
- return [c.px[at]!, c.px[at + 1]!, c.px[at + 2]!, c.px[at + 3]!];
- };
- let carried: [number, number, number, number] | null = null;
-
- let index = 0;
- let distance = total * strand.from;
- const end = total * strand.to;
- for (;;) {
- while (index + 1 < path.length - 1 && path[index + 1]!.along < distance) index++;
- const [a, b] = [path[index]!, path[Math.min(path.length - 1, index + 1)]!];
- const span = b.along - a.along;
- const t = span > 0 ? Math.max(0, Math.min(1, (distance - a.along) / span)) : 0;
- const position = total > 0 ? distance / total : 0;
- let narrowing = 1;
- if (total > 0 && taperIn > 0 && position < taperIn) narrowing *= smoothed(position / taperIn);
- if (total > 0 && taperOut > 0 && position > 1 - taperOut) narrowing *= smoothed((1 - position) / taperOut);
- const width = size * (a.pressure + (b.pressure - a.pressure) * t) * narrowing;
- const reach = strand.radius === null ? width / 2 : Math.min(strand.radius, Math.max(width, strand.radius * 0.4));
- const radius = reach * dab;
- const [nx, ny] = span > 0 ? [-(b.y - a.y) / span, (b.x - a.x) / span] : [0, 0];
- const drift = wobble > 0 ? gradientNoise(distance / (size * 3 + 8), strand.seed * 0.37 + 0.5, strand.seed) * 2 * wobble : 0;
- const away = strand.offset * width + drift;
- stamp++;
- const [off1, off2] = scatter > 0 ? [(hash01(strand.seed * 3 + 1, stamp) - 0.5) * 2, (hash01(strand.seed * 3 + 2, stamp) - 0.5) * 2] : [0, 0];
- const [cx, cy] = [a.x + (b.x - a.x) * t + nx * away + off1 * scatter * reach, a.y + (b.y - a.y) * t + ny * away + off2 * scatter * reach];
- let fading = 1;
- if (total > 0 && fadeIn > 0 && position < fadeIn) fading *= position / fadeIn;
- if (total > 0 && fadeOut > 0 && position > 1 - fadeOut) fading *= (1 - position) / fadeOut;
-
- if (radius >= 0.12) {
- const soft = Math.max(1, radius * (1 - hardness));
- const thin = Math.min(1, radius * 2);
- // Flat at the top: stamps of a pointed falloff, overlapped, ripple along the stroke.
- const cover = (d: number): number => {
- const v = Math.max(0, Math.min(1, (radius + 0.5 - d) / soft));
- return soft > 1 ? smoothed(v) : v;
- };
- // Across is the wide way of the brush, as it travels or as it is held.
- const [ax2, ay2] = held ?? [nx, ny];
- const shaped = (dx: number, dy: number): number => (roundness >= 1 ? Math.hypot(dx, dy) : Math.hypot(dx * ax2 + dy * ay2, (dx * ay2 - dy * ax2) / roundness));
- const toothOf = (x: number, y: number): number => {
- if (grain <= 0 && dry <= 0) return 1;
- let kept = 1;
- // A wide band and not a threshold: paper takes more or less pigment at each place, and specks of all or nothing read as static.
- // A wide band and not a threshold: paper takes more or less pigment at each place, and specks of all or nothing read as static.
- if (grain > 0) kept *= Math.max(0, Math.min(1, (paperAt(w, h, grainScale)[Math.floor(y) * w + Math.floor(x)]! - (0.12 + grain * 0.62)) / 0.34 + 0.5));
- if (dry > 0) {
- // Hairs of the brush: fine across its width and long along its travel.
- const across = (x - cx) * nx + (y - cy) * ny + away;
- // Hairs gather in clumps, some wide and some fine, so the gaps are not ruled lines.
- const hairs = gradientNoise(across / Math.max(0.8, size * 0.045), distance / (size * 3 + 8), strand.seed + 5);
- const clumps = gradientNoise(across / Math.max(1.5, size * 0.17), distance / (size * 5 + 12), strand.seed + 9);
- const streak = 0.5 + 0.8 * hairs + 1.1 * clumps;
- kept *= Math.max(0, Math.min(1, (streak - (0.12 + dry * 0.68)) / 0.22 + 0.5));
- }
- return kept;
- };
- const [x0, x1] = [Math.max(0, Math.floor(cx - radius - 1)), Math.min(w - 1, Math.ceil(cx + radius + 1))];
- const [y0, y1] = [Math.max(0, Math.floor(cy - radius - 1)), Math.min(h - 1, Math.ceil(cy + radius + 1))];
- if (smudge > 0) {
- carried ??= sample(cx, cy);
- for (let y = y0; y <= y1; y++) {
- for (let x = x0; x <= x1; x++) {
- const v = cover(shaped(x + 0.5 - cx, y + 0.5 - cy)) * thin * smudge * (s.opacity ?? 1) * toothOf(x + 0.5, y + 0.5);
- if (v <= 0) continue;
- const at = (y * w + x) * 4;
- for (let k = 0; k < 4; k++) c.px[at + k] = c.px[at + k]! + (carried[k]! - c.px[at + k]!) * v * 0.5;
- }
- }
- const here = sample(cx, cy);
- for (let k = 0; k < 4; k++) carried[k] = carried[k]! + (here[k]! - carried[k]!) * (1 - smudge) * 0.5;
- } else {
- const along = total > 0 ? distance / total : 0;
- const mix = (k: number): number => Math.max(0, Math.min(1, (startColor[k]! + (endColor[k]! - startColor[k]!) * along) * strand.shade));
- let [r, g, bl] = [mix(0), mix(1), mix(2)];
- if (wet > 0) {
- const under = sample(cx, cy);
- const here: [number, number, number] | null = under[3] > 0.02 ? [under[0] / under[3], under[1] / under[3], under[2] / under[3]] : null;
- // It takes up a good share where it first touches, then a little with every dab, and its own paint slowly clears what it carries.
- const pick = here ? (loaded ? wet * 0.09 : wet * 0.45) : 0;
- const base: [number, number, number] = loaded ?? [r, g, bl];
- const own = [r, g, bl];
- loaded = [0, 1, 2].map((k) => {
- const fed = base[k]! + (own[k]! - base[k]!) * 0.012;
- return fed + ((here ? here[k]! : fed) - fed) * pick;
- }) as [number, number, number];
- [r, g, bl] = loaded;
- }
- const alpha = (startColor[3] + (endColor[3] - startColor[3]) * along) * (s.opacity ?? 1) * strand.strength * fading;
- for (let y = y0; y <= y1; y++) {
- for (let x = x0; x <= x1; x++) {
- const v = cover(shaped(x + 0.5 - cx, y + 0.5 - cy)) * thin * alpha * toothOf(x + 0.5, y + 0.5);
- const i = y * w + x;
- const was = buffer.mask[i]!;
- const next = flow > 0 ? was + v * flow * (1 - was) : v;
- if (next <= was) continue;
- if (was === 0) buffer.touched.push(i);
- buffer.mask[i] = next;
- buffer.rgb[i * 3] = r; buffer.rgb[i * 3 + 1] = g; buffer.rgb[i * 3 + 2] = bl;
- }
- }
- }
- }
- if (distance >= end || total === 0) break;
- // Narrow along its travel, a flat brush needs its dabs closer or they show.
- distance = Math.min(end, distance + (spacing !== undefined ? Math.max(0.3, radius * 2 * spacing) : Math.max(0.4, radius * 0.1 * roundness)));
- }
- // Laid down all at once, so opacity is the stroke's and not the sum of its stamps.
- const mode: Blend = s.blend ?? 'normal';
- for (const i of buffer.touched) {
- const covered = buffer.mask[i]!;
- // Where a stroke thins out at its edge, the pigment that gathered there: darker at the rim and paler inside.
- const v = edge > 0 ? Math.min(1, covered * (1 - edge * 0.45 * smoothed(Math.min(1, covered / (s.opacity ?? 1))) + edge * 1.1 * Math.max(0, 1 - Math.abs(covered / (s.opacity ?? 1) - 0.4) * 3))) : covered;
- if (s.erase) for (let k = 0; k < 4; k++) c.px[i * 4 + k]! *= 1 - v;
- else put(c, i, buffer.rgb[i * 3]!, buffer.rgb[i * 3 + 1]!, buffer.rgb[i * 3 + 2]!, v, mode);
- buffer.mask[i] = 0;
- }
- buffer.touched.length = 0;
-}
-
-function paintStroke(c: Canvas, given: ImageStroke, m: Matrix, scale: number, n: number, buffer: StrokeBuffer): void {
- if (!isWrapping()) { paintStrokeOnce(c, given, m, scale, n, buffer); return; }
- const placed = given.points.map((p) => apply(m, [p[0]!, p[1]!]));
- const reach = (given.size ?? 24) * scale * 2 + 4;
- for (const [ox, oy] of ROUND) {
- const [dx, dy] = [ox * c.w, oy * c.h];
- if ((ox !== 0 || oy !== 0) && !touches(placed, dx, dy, reach, c.w, c.h)) continue;
- // The same stroke, the same hairs: its number seeds it, so each copy is the one stroke seen again.
- paintStrokeOnce(c, given, times([1, 0, 0, 1, dx, dy], m), scale, n, buffer);
- }
-}
-
-function paintStrokeOnce(c: Canvas, given: ImageStroke, m: Matrix, scale: number, n: number, buffer: StrokeBuffer): void {
- const s: ImageStroke = given.brush ? { ...IMAGE_BRUSHES[given.brush], ...given } : given;
- const path = brushPath(s.points, m);
- const seed = s.seed ?? n + 1;
- const count = s.bristles ?? 1;
- if (count === 1) {
- paintStrand(c, s, path, { offset: 0, radius: null, from: 0, to: 1, shade: 1, strength: 1, seed }, scale, buffer);
- return;
- }
- const spread = s.spread ?? 1;
- const vary = s.vary ?? 0.15;
- const radius = ((s.strand ?? Math.max(0.8, (s.size / count) * 2.2)) * scale) / 2;
- for (let j = 0; j < count; j++) {
- const pick = (k: number): number => hash01(seed * 131 + j, k);
- paintStrand(c, s, path, {
- // Even across the width and then shaken, so bristles neither clump nor stand in rows.
- offset: (((j + pick(1)) / count) - 0.5) * spread,
- radius,
- from: pick(2) * 0.06,
- to: 1 - pick(3) * 0.1,
- shade: 1 + (pick(4) - 0.5) * 2 * vary,
- strength: 1 - pick(5) * vary * 1.5,
- seed: seed * 31 + j,
- }, scale, buffer);
- }
-}
-
-const channelHex = (v: number): string => Math.max(0, Math.min(255, Math.round(v * 255))).toString(16).padStart(2, '0');
-const toHex = (c: Rgba, shade = 1): string => `#${channelHex(c[0] * shade)}${channelHex(c[1] * shade)}${channelHex(c[2] * shade)}${channelHex(c[3])}`;
-
-/** A guide at evenly spaced places along its length, smooth through its points. */
-function resampled(guide: readonly (readonly number[])[], samples: number): { x: number; y: number; pressure: number }[] {
- const path = brushPath(guide, IDENTITY);
- const total = path[path.length - 1]!.along;
- let index = 0;
- return Array.from({ length: samples }, (_, i) => {
- const at = (total * i) / (samples - 1);
- while (index + 1 < path.length - 1 && path[index + 1]!.along < at) index++;
- const [a, b] = [path[index]!, path[index + 1] ?? path[index]!];
- const t = b.along > a.along ? Math.min(1, (at - a.along) / (b.along - a.along)) : 0;
- return { x: a.x + (b.x - a.x) * t, y: a.y + (b.y - a.y) * t, pressure: a.pressure + (b.pressure - a.pressure) * t };
- });
-}
-
-const SWEEP_SAMPLES = 14;
-
-/** Hairs between the guides. Each belongs to a lock and draws into it toward the tip, and a lock shares a shade, which is what makes a mass read as locks and not as combed lines. */
-const brushSettings = (s: ImageBrushSettings & { brush?: string }): Partial<ImageStroke> => {
- const out: Record<string, unknown> = {};
- for (const key of ['brush', 'roundness', 'angle', 'grain', 'grainScale', 'dry', 'wet', 'edge', 'scatter', 'dab', 'spacing', 'flow', 'fade'] as const) if (s[key as keyof typeof s] !== undefined) out[key] = s[key as keyof typeof s];
- return out as Partial<ImageStroke>;
-};
-
-function sweepStrokes(s: ImageSweep): ImageStroke[] {
- const guides = s.guides.map((g) => resampled(g, SWEEP_SAMPLES));
- const seed = s.seed ?? 1;
- const colors = s.colors.map(parseColor);
- const tip = s.tip ? parseColor(s.tip) : null;
- const clumps = s.clumps ?? Math.max(2, Math.round(s.count / 14));
- const [gather, flyaway, vary, wobble] = [s.gather ?? 0.6, s.flyaway ?? 0.02, s.vary ?? 0.12, s.wobble ?? 1.5];
- const colorAt = (u: number): Rgba => {
- const at = Math.max(0, Math.min(0.9999, u)) * (colors.length - 1);
- const [i, t] = [Math.floor(at), at - Math.floor(at)];
- const [a, b] = [colors[i]!, colors[Math.min(colors.length - 1, i + 1)]!];
- return [a[0] + (b[0] - a[0]) * t, a[1] + (b[1] - a[1]) * t, a[2] + (b[2] - a[2]) * t, a[3] + (b[3] - a[3]) * t];
- };
- const lockCentre = Array.from({ length: clumps }, (_, k) => (k + 0.2 + hash01(seed * 7 + k, 1) * 0.6) / clumps);
- const lockShade = Array.from({ length: clumps }, (_, k) => 1 + (hash01(seed * 7 + k, 2) - 0.5) * vary * 2.5);
- const out: ImageStroke[] = [];
- for (let j = 0; j < s.count; j++) {
- const pick = (k: number): number => hash01(seed * 131 + j, k);
- const u = (j + pick(1)) / s.count;
- const lock = Math.min(clumps - 1, Math.floor(u * clumps));
- const strays = pick(2) < flyaway;
- const [side, reach] = [pick(3) < 0.5 ? -1 : 1, 0.6 + pick(4) * 1.4];
- const length = 1 - pick(5) * (strays ? 0.05 : 0.16);
- const points: number[][] = [];
- for (let i = 0; i < SWEEP_SAMPLES; i++) {
- const t = (i / (SWEEP_SAMPLES - 1)) * length;
- const draw = strays ? 0 : gather * t * t;
- const where = (u + (lockCentre[lock]! - u) * draw) * (guides.length - 1);
- const [g, f] = [Math.min(guides.length - 2, Math.floor(where)), where - Math.min(guides.length - 2, Math.floor(where))];
- const at = (line: readonly { x: number; y: number }[]): [number, number] => {
- const place = t * (SWEEP_SAMPLES - 1);
- const [low, frac] = [Math.min(SWEEP_SAMPLES - 2, Math.floor(place)), place - Math.min(SWEEP_SAMPLES - 2, Math.floor(place))];
- return [line[low]!.x + (line[low + 1]!.x - line[low]!.x) * frac, line[low]!.y + (line[low + 1]!.y - line[low]!.y) * frac];
- };
- const [ax, ay] = at(guides[g]!);
- const [bx, by] = at(guides[g + 1]!);
- const [x, y] = [ax + (bx - ax) * f, ay + (by - ay) * f];
- const [cx, cy] = [bx - ax, by - ay];
- const across = Math.hypot(cx, cy) || 1;
- const shake = gradientNoise(t * 3.1, j * 0.73 + 0.5, seed) * wobble * 2 * t;
- const stray = strays ? side * reach * t * t * (across * 0.5 + (s.size ?? 1.2) * 14) : 0;
- points.push([Math.round((x + (cx / across) * (shake + stray)) * 100) / 100, Math.round((y + (cy / across) * (shake + stray)) * 100) / 100]);
- }
- const shade = lockShade[lock]! * (1 + (pick(6) - 0.5) * vary);
- const root = colorAt(u + (pick(7) - 0.5) * 0.08);
- const size = (s.size ?? 1.2) * (0.7 + pick(8) * 0.6);
- out.push({
- ...brushSettings(s),
- points, size, ...(s.brush && s.hardness === undefined ? {} : { hardness: s.hardness ?? 0.7 }), color: toHex(root, shade),
- ...(tip ? { to: toHex([root[0] + (tip[0] - root[0]) * 0.8, root[1] + (tip[1] - root[1]) * 0.8, root[2] + (tip[2] - root[2]) * 0.8, root[3]], shade) } : {}),
- opacity: (s.opacity ?? (s.brush ? IMAGE_BRUSHES[s.brush]!.opacity ?? 1 : 1)) * (strays ? 0.55 : 0.75 + pick(9) * 0.25),
- taper: s.taper ?? [0.04, 0.45],
- });
- }
- return out;
-}
-
-/** Strokes across a region, following the guides or an angle. Each takes its colour from `tone` where it starts. */
-function fieldStrokes(s: ImageField, w: number, h: number, m: Matrix, drawn: Drawn, where: string): ImageStroke[] {
- const seed = s.seed ?? 1;
- const named = s.region?.startsWith('@') ? s.region.slice(1) : null;
- const mask = named ? drawn.masks.get(named) : undefined;
- if (named && !mask) {
- drawn.notes.push(`${where}: a field's region "@${named}" names no layer drawn before it, so it drew nothing`);
- return [];
- }
- const box = mask ? boxOf(w, h, (i) => mask[i]! >= 0.5) : null;
- if (mask && !box) return [];
- const regionRuns = s.region && !named ? parsePath(s.region).map((r) => r.points) : null;
- const inside = (x: number, y: number): boolean => {
- if (mask) {
- const p = apply(m, [x, y]);
- const [px, py] = [Math.floor(p[0]), Math.floor(p[1])];
- return px >= 0 && py >= 0 && px < w && py < h && mask[py * w + px]! >= 0.5;
- }
- if (!regionRuns) return true;
- let winding = 0;
- for (const run of regionRuns) {
- for (let i = 0; i < run.length; i++) {
- const [a, b] = [run[i]!, run[(i + 1) % run.length]!];
- if ((a[1] <= y) === (b[1] <= y)) continue;
- const cross = (b[0] - a[0]) * (y - a[1]) - (x - a[0]) * (b[1] - a[1]);
- if (b[1] > a[1] ? cross > 0 : cross < 0) winding += b[1] > a[1] ? 1 : -1;
- }
- }
- return winding !== 0;
- };
- const back = invert(m);
- const all = box
- ? ([[box[0], box[1]], [box[0] + box[2], box[1]], [box[0], box[1] + box[3]], [box[0] + box[2], box[1] + box[3]]] as Pt[]).map((p) => apply(back, p))
- : regionRuns ? regionRuns.flat() : [[0, 0], [w, h]] as Pt[];
- const [x0, x1] = [Math.min(...all.map((p) => p[0])), Math.max(...all.map((p) => p[0]))];
- const [y0, y1] = [Math.min(...all.map((p) => p[1])), Math.max(...all.map((p) => p[1]))];
- const flow = (s.guides ?? []).flatMap((g) => {
- const line = resampled(g, 24);
- return line.slice(0, -1).map((p, i) => {
- const q = line[i + 1]!;
- const len = Math.hypot(q.x - p.x, q.y - p.y) || 1;
- return { x: p.x, y: p.y, dx: (q.x - p.x) / len, dy: (q.y - p.y) / len };
- });
- });
- const direction = (x: number, y: number): [number, number] => {
- if (flow.length === 0) {
- const r = ((s.angle ?? 0) * Math.PI) / 180;
- return [Math.cos(r), Math.sin(r)];
- }
- let [dx, dy] = [0, 0];
- for (const f of flow) {
- const weight = 1 / (1 + ((x - f.x) ** 2 + (y - f.y) ** 2) ** 1.5);
- dx += f.dx * weight; dy += f.dy * weight;
- }
- const len = Math.hypot(dx, dy) || 1;
- return [dx / len, dy / len];
- };
- const toned = s.tone !== undefined && typeof s.tone !== 'string' && (s.tone.type === 'form' || s.tone.type === 'image') ? paintOf(s.tone, IDENTITY, drawn, w) : null;
- const paint = toned ? (x: number, y: number): Rgba => { const p = apply(m, [x, y]); return toned(p[0], p[1]); } : s.tone !== undefined ? paintOf(s.tone, IDENTITY) : null;
- const length = s.length ?? s.size * 3;
- const count = Math.min(MAX_MARK_STROKES, Math.ceil(((s.coverage ?? 4) * Math.max(1, (x1 - x0) * (y1 - y0))) / (s.size * length)));
- const spread = ((s.spread ?? 12) * Math.PI) / 180;
- const vary = s.vary ?? 0.05;
- const steps = 5;
- const out: ImageStroke[] = [];
- // One start in each cell of a grid, in shuffled order: wholly random starts leave holes, and starts in rows lay strokes over each other in rows.
- const across = Math.max(1, Math.round(Math.sqrt((count * (x1 - x0 || 1)) / (y1 - y0 || 1))));
- const down = Math.max(1, Math.ceil(count / across));
- const order = Array.from({ length: across * down }, (_, i) => i).sort((a, b) => hash01(seed * 53 + a, 9) - hash01(seed * 53 + b, 9));
- for (const j of order) {
- const pick = (k: number): number => hash01(seed * 197 + j, k);
- const [sx, sy] = [x0 + (((j % across) + pick(1)) / across) * (x1 - x0), y0 + ((Math.floor(j / across) + pick(2)) / down) * (y1 - y0)];
- if (!inside(sx, sy)) continue;
- const turn = (pick(3) - 0.5) * 2 * spread;
- const points: number[][] = [];
- const [back, forward] = [-length / 2, length / steps];
- let [x, y] = [sx, sy];
- const [d0x, d0y] = direction(sx, sy);
- x += d0x * back; y += d0y * back;
- for (let k = 0; k <= steps; k++) {
- points.push([Math.round(x * 100) / 100, Math.round(y * 100) / 100]);
- const [dx, dy] = direction(x, y);
- const [rx, ry] = [dx * Math.cos(turn) - dy * Math.sin(turn), dx * Math.sin(turn) + dy * Math.cos(turn)];
- x += rx * forward; y += ry * forward;
- }
- out.push({
- ...brushSettings(s),
- points, size: s.size * (0.75 + pick(4) * 0.5),
- // A named brush keeps what it is, and only a field without one takes the soft defaults.
- ...(s.brush ? {} : { hardness: s.hardness ?? 0.25, opacity: s.opacity ?? 0.6 }),
- ...(s.brush && s.hardness !== undefined ? { hardness: s.hardness } : {}),
- ...(s.brush && s.opacity !== undefined ? { opacity: s.opacity } : {}),
- ...(s.smudge ? { smudge: s.smudge } : { color: toHex(paint!(sx, sy), 1 + (pick(5) - 0.5) * 2 * vary) }), taper: s.taper ?? [0.12, 0.3],
- });
- }
- return out;
-}
-
-/** The strokes again along a line, each turned to the line's direction there and sized along it. */
-function alongStrokes(s: ImageAlong): ImageStroke[] {
- const seed = s.seed ?? 1;
- const line = resampled(s.line, Math.max(2, s.count));
- const [from, to] = typeof s.scale === 'number' ? [s.scale, s.scale] : s.scale ?? [1, 1];
- const jitter = s.jitter ?? 0;
- const out: ImageStroke[] = [];
- for (let i = 0; i < s.count; i++) {
- const t = s.count === 1 ? 0 : i / (s.count - 1);
- const p = line[i]!;
- // Its direction from the next place along, and at the last from the one before.
- const [from0, to0] = i + 1 < line.length ? [p, line[i + 1]!] : [line[i - 1]!, p];
- const pick = (k: number): number => (hash01(seed * 89 + i, k) - 0.5) * 2 * jitter;
- const scale = from + (to - from) * t;
- const base = Math.atan2(to0.y - from0.y, to0.x - from0.x);
- for (const side of s.both ? [1, -1] : [1]) {
- const angle = base + (((s.turn ?? 0) * side + pick(1) * 0.1) * Math.PI) / 180;
- const [cos, sin] = [Math.cos(angle), Math.sin(angle)];
- const [ox, oy] = [p.x + pick(2), p.y + pick(3)];
- for (const stroke of s.strokes) {
- out.push({
- ...stroke,
- size: stroke.size * scale,
- points: stroke.points.map((v) => {
- const [x, y] = [v[0]! * scale, v[1]! * scale * side];
- return [ox + x * cos - y * sin, oy + x * sin + y * cos, ...(v[2] !== undefined ? [v[2]] : [])];
- }),
- });
- }
- }
- }
- return out;
-}
-
-/** Hairs laid between lines closer than a few hairs' width do not read as hairs, and nothing else says so. */
-function sweepNote(s: ImageSweep, drawn: Drawn, where: string): void {
- const size = s.size ?? 1.2;
- const lines = s.guides.map((g) => resampled(g, 3)[1]!);
- let span = 0;
- for (let i = 0; i + 1 < lines.length; i++) span += Math.hypot(lines[i + 1]!.x - lines[i]!.x, lines[i + 1]!.y - lines[i]!.y);
- if (span < size * 4 || s.count * size > span * 8 * Math.max(1, s.guides.length)) {
- drawn.notes.push(`${where}: a sweep lays ${s.count} hairs of size ${size} across ${Math.round(span)} pixels, which fills it as a flat band; use fewer, thinner hairs or set the guides further apart`);
- }
-}
-
-const expandMark = (mark: ImageMark, w: number, h: number, m: Matrix, drawn: Drawn, where: string): readonly ImageStroke[] => {
- if (!('type' in mark)) return [mark];
- if (mark.type === 'sweep') {
- sweepNote(mark, drawn, where);
- return sweepStrokes(mark);
- }
- return mark.type === 'along' ? alongStrokes(mark) : fieldStrokes(mark, w, h, m, drawn, where);
-};
-
-function drawPaint(c: Canvas, layer: ImageLayer, parent: Matrix, drawn: Drawn, opacity: number, blend: Blend, clip: Float32Array | undefined): void {
- const { w, h } = c;
- const m = times(parent, transformOf(layer.transform, [w / 2, h / 2]));
- const inner = new Canvas(w, h);
- if (layer.from === 'below') inner.px.set(c.px);
- if (layer.fill !== undefined) {
- const paint = paintOf(layer.fill, m, drawn, w);
- for (let y = 0; y < h; y++) {
- for (let x = 0; x < w; x++) {
- const col = paint(x + 0.5, y + 0.5);
- put(inner, y * w + x, col[0], col[1], col[2], col[3], 'normal');
- }
- }
- }
- const buffer: StrokeBuffer = { mask: new Float32Array(w * h), rgb: new Float32Array(w * h * 3), touched: [] };
- let drawnStrokes = 0;
- const onFace = layer.face ? faceCorners(layer, drawn) : null;
- if (layer.face && !onFace) return;
- const place = onFace ? unitToQuad(onFace) : null;
- const lay = (points: readonly (readonly number[])[]): number[][] => points.map((p) => [...place!(p[0]!, p[1]!), ...p.slice(2)]);
- const placed = (mark: ImageMark): ImageMark => {
- if (!place) return mark;
- if (!('type' in mark)) return { ...mark, points: lay(mark.points) };
- if (mark.type === 'sweep') return { ...mark, guides: mark.guides.map(lay) };
- if (mark.type === 'along') return { ...mark, line: lay(mark.line) };
- return mark;
- };
- (layer.strokes ?? []).map(placed).forEach((mark) => {
- for (const s of expandMark(mark, w, h, m, drawn, `layer ${layer.id ?? 'paint'}`)) paintStroke(inner, s, m, drawnScale(m), drawnStrokes++, buffer);
- });
- if (layer.id) drawn.painted.set(layer.id, { entries: (layer.strokes ?? []).length, strokes: drawnStrokes });
- const alpha = new Float32Array(w * h);
- for (let i = 0; i < alpha.length; i++) alpha[i] = inner.px[i * 4 + 3]!;
- // What it holds is what its clip let through: what clips to it must not get out past that.
- const held = clip ? alpha.map((v, i) => v * clip[i]!) : alpha;
- if (layer.id) drawn.masks.set(layer.id, held);
- noteBox(drawn, layer.id, held, w, h);
- if (layer.from === 'below') {
- // It already holds the picture, so it takes that picture's place and does not go over it.
- for (let i = 0; i < alpha.length * 4; i++) {
- const keep = opacity * (clip ? clip[Math.floor(i / 4)]! : 1);
- c.px[i] = c.px[i]! + (inner.px[i]! - c.px[i]!) * keep;
- }
- return;
- }
- effectLayers(layer.effects, true, c, alpha);
- for (let i = 0; i < alpha.length; i++) {
- const a = alpha[i]!;
- if (a <= 0) continue;
- put(c, i, inner.px[i * 4]! / a, inner.px[i * 4 + 1]! / a, inner.px[i * 4 + 2]! / a, a * opacity * (clip ? clip[i]! : 1), blend);
- }
- effectLayers(layer.effects, false, c, alpha);
-}
-
-/** The blocks in plain grey, with the bones and a mark on each joint: enough to draw over, and nothing to be mistaken for the drawing. */
-function drawFigure(c: Canvas, layer: ImageLayer, parent: Matrix, drawn: Drawn, opacity: number, blend: Blend, clip: Float32Array | undefined): void {
- const { w, h } = c;
- const figure = flattenFigure(layer, w, h, (p) => apply(parent, p), drawnScale(parent));
- // Past the blocks a little way, so cloth that hangs off them is lit as what it hangs from.
- const reach = Math.max(2, (layer.height as number) * 0.03);
- const spread = blurMask(figure.mask, w, h, reach);
- const extended = new Float32Array(figure.normals);
- for (let k = 0; k < 3; k++) {
- const channel = new Float32Array(w * h);
- for (let i = 0; i < channel.length; i++) channel[i] = figure.normals[i * 3 + k]! * figure.mask[i]!;
- const soft = blurMask(channel, w, h, reach);
- for (let i = 0; i < channel.length; i++) if (figure.mask[i]! < 0.5 && spread[i]! > 0.01) extended[i * 3 + k] = soft[i]! / spread[i]!;
- }
- if (layer.id) {
- drawn.figures.set(layer.id, { ...figure, normals: extended });
- const held = (mask: Float32Array): Float32Array => (clip ? mask.map((v, i) => v * clip[i]!) : mask);
- drawn.masks.set(layer.id, held(figure.mask));
- noteBox(drawn, layer.id, held(figure.mask), w, h);
- for (const [tag, mask] of Object.entries(figure.parts)) {
- drawn.masks.set(`${layer.id}.${tag}`, held(mask));
- noteBox(drawn, `${layer.id}.${tag}`, held(mask), w, h);
- }
- }
- const [lx, ly, lz] = figure.light;
- for (let i = 0; i < figure.mask.length; i++) {
- const a = figure.mask[i]!;
- if (a <= 0) continue;
- const lit = 0.25 + 0.7 * Math.max(0, 0.5 + 0.5 * (figure.normals[i * 3]! * lx + figure.normals[i * 3 + 1]! * ly + figure.normals[i * 3 + 2]! * lz));
- const line = 1 - figure.contour[i]! * 0.85;
- put(c, i, lit * line * 0.92, lit * line * 0.94, lit * line, a * opacity * (clip ? clip[i]! : 1), blend);
- }
- const bones = strokeMask(figure.lines.map((points) => ({ closed: false, points })), 1.5, w, h);
- for (let i = 0; i < bones.length; i++) put(c, i, 0.95, 0.35, 0.3, bones[i]! * 0.8 * opacity, 'normal');
- for (const [x, y] of Object.values(figure.joints)) {
- for (let dy = -2; dy <= 2; dy++) {
- for (let dx = -2; dx <= 2; dx++) {
- if (x + dx < 0 || y + dy < 0 || x + dx >= w || y + dy >= h || dx * dx + dy * dy > 5) continue;
- put(c, (y + dy) * w + x + dx, 0.95, 0.2, 0.25, 0.85 * opacity, 'normal');
- }
- }
- }
- if (layer.id) drawn.figureJoints.set(layer.id, figure.joints);
-}
-
-/** Pixels a text is drawn at before it is laid on its corners: a font hinted small would not survive being stretched. */
-const QUAD_TEXT_SIZE = 96;
-
-/** The words drawn large and flat, cut to where they are, and looked up from each pixel of the corners they are laid on. */
-function textOnQuad(layer: ImageLayer, m: Matrix, w: number, h: number, draw: ImageTextDrawer): { fill: Float32Array; line: Float32Array | null } {
- const count = [...(layer.text as string)].length;
- const k = QUAD_TEXT_SIZE / (layer.fontSize ?? QUAD_TEXT_SIZE);
- const long = Math.ceil(QUAD_TEXT_SIZE * 1.4 * (count + 1) + Math.abs(layer.tracking ?? 0) * k * count);
- const across = QUAD_TEXT_SIZE * 2;
- const [W, H] = layer.vertical ? [across, long] : [long, across];
- const flat = draw({
- ...layer, fontSize: QUAD_TEXT_SIZE, align: 'left', at: layer.vertical ? [across / 2, QUAD_TEXT_SIZE * 0.2] : [QUAD_TEXT_SIZE * 0.2, QUAD_TEXT_SIZE * 1.3],
- ...(layer.tracking ? { tracking: layer.tracking * k } : {}), ...(layer.stroke ? { stroke: { ...layer.stroke, width: layer.stroke.width * k } } : {}),
- }, IDENTITY, W, H);
- const box = boxOf(W, H, (i) => flat.fill[i]! >= 0.5 || (flat.line ? flat.line[i]! >= 0.5 : false));
- const out = { fill: new Float32Array(w * h), line: flat.line ? new Float32Array(w * h) : null };
- const corners = layer.quad!.map((p) => apply(m, p as unknown as Pt));
- const toUnit = quadToUnit(corners);
- if (!box || !toUnit) return out;
- const [x0, x1] = [Math.max(0, Math.floor(Math.min(...corners.map((p) => p[0])))), Math.min(w - 1, Math.ceil(Math.max(...corners.map((p) => p[0]))))];
- const [y0, y1] = [Math.max(0, Math.floor(Math.min(...corners.map((p) => p[1])))), Math.min(h - 1, Math.ceil(Math.max(...corners.map((p) => p[1]))))];
- const SAMPLES = 3;
- for (let y = y0; y <= y1; y++) {
- for (let x = x0; x <= x1; x++) {
- let [f, l] = [0, 0];
- for (let sy = 0; sy < SAMPLES; sy++) {
- for (let sx = 0; sx < SAMPLES; sx++) {
- const [u, v] = toUnit(x + (sx + 0.5) / SAMPLES, y + (sy + 0.5) / SAMPLES);
- if (u < 0 || v < 0 || u >= 1 || v >= 1) continue;
- const at = Math.floor(box[1] + v * box[3]) * W + Math.floor(box[0] + u * box[2]);
- f += flat.fill[at]!;
- if (flat.line) l += flat.line[at]!;
- }
- }
- out.fill[y * w + x] = f / (SAMPLES * SAMPLES);
- if (out.line) out.line[y * w + x] = l / (SAMPLES * SAMPLES);
- }
- }
- return out;
-}
-
-/** What is bright in the picture so far, spilling over what is round it: a tight glow and a wide one, as a lens and the air both give. */
-function drawBloom(c: Canvas, layer: ImageLayer, parent: Matrix, opacity: number, clip: Float32Array | undefined): void {
- const { w, h } = c;
- const threshold = layer.threshold ?? 0.6;
- const strength = (layer.strength ?? 1) * opacity;
- const radius = ((layer.radius as number | undefined) ?? 10) * drawnScale(parent);
- const bright = [new Float32Array(w * h), new Float32Array(w * h), new Float32Array(w * h)] as const;
- const span = Math.max(0.001, 1 - threshold);
- for (let i = 0; i < w * h; i++) {
- const [r, g, b] = [c.px[i * 4]!, c.px[i * 4 + 1]!, c.px[i * 4 + 2]!];
- const peak = Math.max(r, g, b);
- if (peak <= threshold) continue;
- // Its own colour, in proportion to how far over it is: only the brightest of a soft edge shines.
- const over = smoothed(Math.min(1, (peak - threshold) / span));
- bright[0][i] = r * over; bright[1][i] = g * over; bright[2][i] = b * over;
- }
- for (let k = 0; k < 3; k++) {
- const [tight, wide] = [blurMask(bright[k]!, w, h, radius * 0.5), blurMask(bright[k]!, w, h, radius * 2.5)];
- for (let i = 0; i < w * h; i++) {
- const shine = Math.min(1, (tight[i]! * 0.7 + wide[i]! * 0.9) * strength) * (clip ? clip[i]! : 1);
- if (shine <= 0) continue;
- const at = i * 4;
- c.px[at + k] = c.px[at + k]! + (1 - c.px[at + k]!) * shine;
- if (shine > c.px[at + 3]!) c.px[at + 3] = shine;
- }
- }
-}
-
-/** Coverage with this many pixels taken off every edge: the lowest within reach, across and then down. */
-function thinned(mask: Float32Array, pixels: number, w: number, h: number): Float32Array {
- const r = Math.round(pixels);
- if (r <= 0) return mask;
- const across = new Float32Array(w * h);
- for (let y = 0; y < h; y++) {
- for (let x = 0; x < w; x++) {
- let low = 1;
- for (let d = -r; d <= r; d++) {
- const at = x + d;
- const v = at < 0 || at >= w ? 0 : mask[y * w + at]!;
- if (v < low) low = v;
- }
- across[y * w + x] = low;
- }
- }
- const out = new Float32Array(w * h);
- for (let x = 0; x < w; x++) {
- for (let y = 0; y < h; y++) {
- let low = 1;
- for (let d = -r; d <= r; d++) {
- const at = y + d;
- const v = at < 0 || at >= h ? 0 : across[at * w + x]!;
- if (v < low) low = v;
- }
- out[y * w + x] = low;
- }
- }
- return out;
-}
-
-/** Letters worn as a brush wears a stroke, by the same paper and in streaks across them. */
-function wornText(mask: Float32Array, layer: ImageLayer, w: number): Float32Array {
- const [grain, dry] = [layer.grain ?? 0, layer.dry ?? 0];
- if (grain <= 0 && dry <= 0) return mask;
- const scale = layer.grainScale ?? 2;
- return mask.map((v, i) => {
- if (v <= 0) return 0;
- const [x, y] = [(i % w) + 0.5, Math.floor(i / w) + 0.5];
- let kept = v;
- if (grain > 0) kept *= Math.max(0, Math.min(1, (fractalNoise(x / scale, y / scale, 3, 77) - (0.12 + grain * 0.62)) / 0.34 + 0.5));
- if (dry > 0) kept *= Math.max(0, Math.min(1, (0.5 + 1.3 * gradientNoise(x / 40, y / 1.8, 9) - (0.12 + dry * 0.68)) / 0.22 + 0.5));
- return kept;
- });
-}
-
-/** A mask made wider by @p pixels, or narrower if they are less than none: the highest or lowest within reach, across and then down. */
-function grownMask(mask: Float32Array, pixels: number, w: number, h: number): Float32Array {
- const r = Math.round(Math.abs(pixels));
- if (r === 0) return mask;
- const pick = pixels > 0 ? Math.max : Math.min;
- const across = new Float32Array(w * h);
- for (let y = 0; y < h; y++) {
- for (let x = 0; x < w; x++) {
- let v = mask[y * w + x]!;
- for (let d = -r; d <= r; d++) { const at = x + d; v = pick(v, at < 0 || at >= w ? (pixels > 0 ? 0 : v) : mask[y * w + at]!); }
- across[y * w + x] = v;
- }
- }
- const out = new Float32Array(w * h);
- for (let x = 0; x < w; x++) {
- for (let y = 0; y < h; y++) {
- let v = across[y * w + x]!;
- for (let d = -r; d <= r; d++) { const at = y + d; v = pick(v, at < 0 || at >= h ? (pixels > 0 ? 0 : v) : across[at * w + x]!); }
- out[y * w + x] = v;
- }
- }
- return out;
-}
-
-function drawText(c: Canvas, layer: ImageLayer, parent: Matrix, drawn: Drawn, opacity: number, blend: Blend, clip: Float32Array | undefined): void {
- const { w, h } = c;
- if (!drawn.text) throw new Error(`layer ${layer.id ?? 'text'}: text needs the editor's fonts, and this render has none`);
- const m = times(parent, transformOf(layer.transform, (layer.at ?? [0, 0]) as Pt));
- const corners = layer.face ? faceCorners(layer, drawn) : layer.quad;
- if (layer.face && !corners) return;
- const drawnText = corners ? textOnQuad({ ...layer, quad: corners }, m, w, h, drawn.text) : drawn.text(layer, m, w, h);
- const line = drawnText.line;
- const fill = wornText(thinned(drawnText.fill, (layer.thin ?? 0) * drawnScale(m), w, h), layer, w);
- const whole = new Float32Array(w * h);
- for (let i = 0; i < whole.length; i++) whole[i] = Math.max(layer.fill !== undefined ? fill[i]! : 0, line ? line[i]! : 0) * (clip ? clip[i]! : 1);
- if (layer.id) drawn.masks.set(layer.id, whole);
- noteBox(drawn, layer.id, whole, w, h);
- effectLayers(layer.effects, true, c, whole);
- const lay = (mask: Float32Array, paint: (x: number, y: number) => Rgba): void => {
- for (let y = 0; y < h; y++) {
- for (let x = 0; x < w; x++) {
- const i = y * w + x;
- const v = mask[i]! * (clip ? clip[i]! : 1);
- if (v <= 0) continue;
- const col = paint(x + 0.5, y + 0.5);
- put(c, i, col[0], col[1], col[2], v * col[3] * opacity, blend);
- }
- }
- };
- if (line && layer.stroke) lay(line, paintOf(layer.stroke.color, m, drawn, w));
- if (layer.fill !== undefined) lay(fill, paintOf(layer.fill, m, drawn, w));
- effectLayers(layer.effects, false, c, whole);
-}
-
-/** A building's visible faces, from the corner nearest the viewer toward the vanishing points. Each is a layer of its own to clip to. */
-function drawBlock(c: Canvas, layer: ImageLayer, parent: Matrix, drawn: Drawn): void {
- const [bx, by] = layer.at as Pt;
- const top = by - (layer.height as number);
- const toward = (x: number, y: number, v: readonly number[], t: number): number[] => [x + (v[0]! - x) * t, y + (v[1]! - y) * t];
- const quads: Record<string, readonly (readonly number[])[]> = {};
- const names = ['a', 'b'];
- const common: Partial<ImageLayer> = { ...(layer.opacity !== undefined ? { opacity: layer.opacity } : {}), ...(layer.blend ? { blend: layer.blend } : {}), ...(layer.clip ? { clip: layer.clip } : {}), ...(layer.except ? { except: layer.except } : {}), ...(layer.stroke ? { stroke: layer.stroke } : {}) };
- const faces: ImageLayer[] = (layer.vanish ?? []).map((v, n) => {
- const t = layer.depth![n]!;
- const [tx, ty] = toward(bx, top, v, t);
- const [fx, fy] = toward(bx, by, v, t);
- // Top left, top right, bottom right, bottom left, as seen: the far edge is on whichever side it recedes to.
- const quad = v[0]! < bx ? [[tx, ty], [bx, top], [bx, by], [fx, fy]] : [[bx, top], [tx, ty], [fx, fy], [bx, by]];
- quads[names[n]!] = quad;
- const given = layer.faces![n]!;
- const fill = typeof given !== 'string' && given.type === 'grid' && !given.quad ? { ...given, quad } : given;
- return { ...common, ...(layer.id ? { id: `${layer.id}.${names[n]}` } : {}), shape: 'polygon', points: quad as [number, number][], fill } as ImageLayer;
- });
- // A roof shows only from above, which is when the top is below the line the vanishing points are on.
- const vanish = layer.vanish ?? [];
- if (layer.roof !== undefined && vanish[0]![1]! < top) {
- const near: number[] = [bx, top];
- const [p, q] = [toward(bx, top, vanish[0]!, layer.depth![0]!), vanish[1] ? toward(bx, top, vanish[1], layer.depth![1]!) : null];
- const roof = q && vanish[1]
- ? [near, p, (() => {
- // Where the lines from each far corner to the other vanishing point meet.
- const [a, b, cc, d] = [p, vanish[1]!, q, vanish[0]!];
- const den = (a[0]! - b[0]!) * (cc[1]! - d[1]!) - (a[1]! - b[1]!) * (cc[0]! - d[0]!);
- if (Math.abs(den) < 1e-6) return a;
- const k = ((a[0]! - cc[0]!) * (cc[1]! - d[1]!) - (a[1]! - cc[1]!) * (cc[0]! - d[0]!)) / den;
- return [a[0]! + k * (b[0]! - a[0]!), a[1]! + k * (b[1]! - a[1]!)];
- })(), q]
- : null;
- if (roof) {
- quads.top = roof;
- faces.unshift({ ...common, ...(layer.id ? { id: `${layer.id}.top` } : {}), shape: 'polygon', points: roof as [number, number][], fill: layer.roof } as ImageLayer);
- }
- }
- for (const face of faces) drawLayer(c, face, parent, drawn);
- if (layer.id) {
- drawn.blocks.set(layer.id, Object.fromEntries(Object.entries(quads).map(([k, q]) => [k, q.map((p) => { const a = apply(parent, p as unknown as Pt); return [Math.round(a[0]), Math.round(a[1])]; })])));
- const whole = new Float32Array(c.w * c.h);
- for (const key of Object.keys(quads)) {
- const mask = drawn.masks.get(`${layer.id}.${key}`);
- if (mask) for (let i = 0; i < whole.length; i++) whole[i] = Math.max(whole[i]!, mask[i]!);
- }
- drawn.masks.set(layer.id, whole);
- noteBox(drawn, layer.id, whole, c.w, c.h);
- }
-}
-
-/** Lines running out from each vanishing point, to build along. A guide. */
-function drawPerspective(c: Canvas, layer: ImageLayer, parent: Matrix, opacity: number): void {
- const { w, h } = c;
- const reach = Math.hypot(w, h);
- const lines = (layer.vanish ?? []).flatMap((v) => Array.from({ length: 24 }, (_, i) => {
- const a = (i / 24) * Math.PI * 2;
- const from = apply(parent, [v[0]!, v[1]!]);
- return { closed: false, points: [from, [from[0] + Math.cos(a) * reach, from[1] + Math.sin(a) * reach]] as Pt[] };
- }));
- const horizon = (layer.vanish ?? [])[0];
- if (horizon) lines.push({ closed: false, points: [apply(parent, [-w, horizon[1]!]), apply(parent, [w * 2, horizon[1]!])] });
- const mask = strokeMask(lines, 1, w, h);
- for (let i = 0; i < mask.length; i++) put(c, i, 0.3, 0.9, 1, mask[i]! * 0.55 * opacity, 'normal');
-}
-
-/** What is above a line, turned over below it: a wet street or still water. It wavers side to side, longer toward the viewer, and fades as it reaches. */
-function drawReflection(c: Canvas, layer: ImageLayer, parent: Matrix, drawn: Drawn, opacity: number, clip: Float32Array | undefined): void {
- const { w, h } = c;
- const k = drawnScale(parent);
- // Where each column turns over: things in perspective stand on a slanting line, and a level one would not meet their feet.
- const lineAt = new Float32Array(w);
- const edge = layer.edge?.map((p) => apply(parent, p as unknown as Pt)).sort((a, b) => a[0] - b[0]);
- for (let x = 0; x < w; x++) {
- if (!edge) { lineAt[x] = apply(parent, [0, layer.y as number])[1]; continue; }
- let i = 0;
- while (i + 2 < edge.length && edge[i + 1]![0] < x + 0.5) i++;
- const [a, b] = [edge[i]!, edge[i + 1]!];
- const t = b[0] === a[0] ? 0 : Math.max(0, Math.min(1, (x + 0.5 - a[0]) / (b[0] - a[0])));
- lineAt[x] = a[1] + (b[1] - a[1]) * t;
- }
- const reach = (layer.reach ?? h) * k;
- const ripple = (layer.ripple ?? 3) * k;
- const seed = 11;
- const out = new Float32Array(w * h * 4);
- for (let y = 0; y < h; y++) {
- for (let x = 0; x < w; x++) {
- const depth = y + 0.5 - lineAt[x]!;
- if (depth < 0 || depth >= reach) continue;
- const from = Math.floor(lineAt[x]! - depth);
- if (from < 0) continue;
- const swing = ripple * (depth / reach + 0.2);
- const shift = gradientNoise(x / 90, y / 3.5, seed) * swing * 2.4 + gradientNoise(x / 22, y / 1.6, seed + 1) * swing;
- const sx = Math.max(0, Math.min(w - 1, Math.round(x + shift)));
- const [to, at] = [(y * w + x) * 4, (from * w + sx) * 4];
- for (let n = 0; n < 4; n++) out[to + n] = c.px[at + n]!;
- }
- }
- const smear = (layer.smear ?? 2) * k;
- const channels = [0, 1, 2, 3].map((n) => {
- const channel = new Float32Array(w * h);
- for (let i = 0; i < channel.length; i++) channel[i] = out[i * 4 + n]!;
- return smear > 0 ? blurMask(channel, w, h, smear) : channel;
- }) as [Float32Array, Float32Array, Float32Array, Float32Array];
- const mask = new Float32Array(w * h);
- for (let y = 0; y < h; y++) {
- for (let x = 0; x < w; x++) {
- const depth = y + 0.5 - lineAt[x]!;
- if (depth < 0) continue;
- const fading = Math.max(0, 1 - depth / reach);
- const i = y * w + x;
- const a = channels[3][i]!;
- mask[i] = a * fading * (clip ? clip[i]! : 1);
- if (a <= 0 || mask[i]! <= 0) continue;
- put(c, i, channels[0][i]! / a, channels[1][i]! / a, channels[2][i]! / a, mask[i]! * opacity, layer.blend ?? 'normal');
- }
- }
- if (layer.id) drawn.masks.set(layer.id, mask);
- noteBox(drawn, layer.id, mask, w, h);
-}
-
-/** A picture from the project, smoothly scaled to where it goes. */
-function drawPicture(c: Canvas, layer: ImageLayer, parent: Matrix, drawn: Drawn, opacity: number, blend: Blend, clip: Float32Array | undefined): void {
- const { w, h } = c;
- const picture = drawn.pictures[layer.src!];
- if (!picture) throw new Error(`there is no picture at ${layer.src}`);
- const [ox, oy] = apply(parent, layer.at ?? [0, 0]);
- const k = drawnScale(parent);
- const [dw, dh] = (layer.size ?? [picture.width, picture.height]).map((v) => v * k) as [number, number];
- const out = new Float32Array(w * h * 4);
- const mask = new Float32Array(w * h);
- for (let y = Math.max(0, Math.floor(oy)); y < Math.min(h, Math.ceil(oy + dh)); y++) {
- for (let x = Math.max(0, Math.floor(ox)); x < Math.min(w, Math.ceil(ox + dw)); x++) {
- const [u, v] = [((x + 0.5 - ox) / dw) * picture.width - 0.5, ((y + 0.5 - oy) / dh) * picture.height - 0.5];
- if (u < -0.5 || v < -0.5 || u > picture.width - 0.5 || v > picture.height - 0.5) continue;
- const [x0, y0] = [Math.max(0, Math.floor(u)), Math.max(0, Math.floor(v))];
- const [x1, y1] = [Math.min(picture.width - 1, x0 + 1), Math.min(picture.height - 1, y0 + 1)];
- const [fx, fy] = [Math.max(0, u - x0), Math.max(0, v - y0)];
- const i = y * w + x;
- for (let n = 0; n < 4; n++) {
- const at = (px: number, py: number): number => picture.rgba[(py * picture.width + px) * 4 + n]! / 255;
- out[i * 4 + n] = (at(x0, y0) * (1 - fx) + at(x1, y0) * fx) * (1 - fy) + (at(x0, y1) * (1 - fx) + at(x1, y1) * fx) * fy;
- }
- mask[i] = out[i * 4 + 3]!;
- }
- }
- if (layer.id) {
- drawn.images.set(layer.id, out);
- const held = clip ? mask.map((v, i) => v * clip[i]!) : mask;
- drawn.masks.set(layer.id, held);
- noteBox(drawn, layer.id, held, w, h);
- }
- for (let i = 0; i < mask.length; i++) {
- if (mask[i]! > 0) put(c, i, out[i * 4]!, out[i * 4 + 1]!, out[i * 4 + 2]!, mask[i]! * opacity * (clip ? clip[i]! : 1), blend);
- }
-}
-
-function drawPixels(c: Canvas, layer: ImageLayer, parent: Matrix, drawn: Drawn, opacity: number, blend: Blend, clip: Float32Array | undefined): void {
- const { w, h } = c;
- const rows = layer.rows!;
- const columns = Math.max(...rows.map((r) => r.length));
- const scale = (layer.scale ?? Math.max(1, Math.floor(Math.min(w / columns, h / rows.length)))) * drawnScale(parent);
- const [ax, ay] = layer.at ? apply(parent, layer.at) : [(w - columns * scale) / 2, (h - rows.length * scale) / 2];
- const palette = new Map(Object.entries(layer.palette ?? {}).map(([k, v]) => [k, parseColor(v)]));
- const whole = new Float32Array(w * h);
- const colors = new Float32Array(w * h * 3);
- rows.forEach((row, ry) => {
- [...row].forEach((ch, rx) => {
- const col = palette.get(ch);
- if (!col) return;
- for (let y = Math.max(0, Math.round(ay + ry * scale)); y < Math.min(h, Math.round(ay + (ry + 1) * scale)); y++) {
- for (let x = Math.max(0, Math.round(ax + rx * scale)); x < Math.min(w, Math.round(ax + (rx + 1) * scale)); x++) {
- whole[y * w + x] = col[3] * (clip ? clip[y * w + x]! : 1);
- colors[(y * w + x) * 3] = col[0]; colors[(y * w + x) * 3 + 1] = col[1]; colors[(y * w + x) * 3 + 2] = col[2];
- }
- }
- });
- });
- if (layer.id) drawn.masks.set(layer.id, whole);
- noteBox(drawn, layer.id, whole, w, h);
- effectLayers(layer.effects, true, c, whole);
- for (let i = 0; i < whole.length; i++) put(c, i, colors[i * 3]!, colors[i * 3 + 1]!, colors[i * 3 + 2]!, whole[i]! * opacity, blend);
- effectLayers(layer.effects, false, c, whole);
-}
-
-/** A picture part-way through: what it costs to draw is what a small edit should not pay again. */
-interface Snapshot { px: Float32Array; drawn: Omit<Drawn, 'showGuides' | 'pictures' | 'text'> }
-const snapshots = new Map<string, Snapshot>();
-const SNAPSHOT_AFTER_MS = 150;
-const SNAPSHOT_BYTES = 512 * 1024 * 1024;
-const cacheCounters = { drawn: 0, reused: 0 };
-
-/** How many layers were drawn and how many were picked up already drawn; `clear` forgets what is kept. */
-export function imageCacheStats(clear = false): { drawn: number; reused: number; kept: number } {
- const out = { ...cacheCounters, kept: snapshots.size };
- if (clear) { snapshots.clear(); cacheCounters.drawn = 0; cacheCounters.reused = 0; }
- return out;
-}
-
-function textHash(text: string): string {
- let [a, b] = [0xdeadbeef, 0x41c6ce57];
- for (let i = 0; i < text.length; i++) {
- const ch = text.charCodeAt(i);
- a = Math.imul(a ^ ch, 2654435761);
- b = Math.imul(b ^ ch, 1597334677);
- }
- return (((a ^ (a >>> 16)) >>> 0).toString(36)) + ((b ^ (b >>> 13)) >>> 0).toString(36) + text.length.toString(36);
-}
-
-/** Pictures come from files that change under the same name, so what is in them is part of the key. */
-function picturesDigest(pictures: Readonly<Record<string, RgbaBitmap>> | undefined): string {
- if (!pictures) return '';
- return Object.entries(pictures).map(([name, p]) => {
- let sum = 0;
- for (let i = 0; i < p.rgba.length; i += 97) sum = (Math.imul(sum, 31) + p.rgba[i]!) | 0;
- return `${name}:${p.width}x${p.height}:${sum}`;
- }).join('|');
-}
-
-/** Masks and the rest are never written once set, so a snapshot can hold them as they are. */
-function keepSnapshot(key: string, canvas: Canvas, drawn: Drawn): void {
- snapshots.set(key, {
- px: canvas.px.slice(),
- drawn: {
- masks: new Map(drawn.masks), notes: [...drawn.notes], bounds: new Map(drawn.bounds), painted: new Map(drawn.painted), figures: new Map(drawn.figures),
- figureJoints: new Map(drawn.figureJoints), images: new Map(drawn.images), blocks: new Map(drawn.blocks),
- },
- });
- let bytes = 0;
- for (const s of snapshots.values()) bytes += s.px.byteLength;
- for (const [k, s] of snapshots) {
- if (bytes <= SNAPSHOT_BYTES) break;
- snapshots.delete(k);
- bytes -= s.px.byteLength;
- }
-}
-
-function restoreSnapshot(kept: Snapshot, canvas: Canvas, drawn: Drawn): void {
- canvas.px.set(kept.px);
- drawn.masks = new Map(kept.drawn.masks); drawn.notes = [...kept.drawn.notes]; drawn.bounds = new Map(kept.drawn.bounds); drawn.painted = new Map(kept.drawn.painted);
- drawn.figures = new Map(kept.drawn.figures); drawn.figureJoints = new Map(kept.drawn.figureJoints); drawn.images = new Map(kept.drawn.images); drawn.blocks = new Map(kept.drawn.blocks);
-}
-
-export interface RenderedImage extends RgbaBitmap {
- notes: string[];
- /** Where the picture is solid, null if nowhere, and how much of its area that is, 0..1: how large it looks beside others. */
- bounds: ImageBox | null;
- covers: number;
- /** The same box for each layer with an id, after every transform, without its effects. */
- layerBounds: Record<string, ImageBox>;
- /** For each paint layer with an id: its entries, which `drop` counts, and the strokes they came to. */
- painted: Record<string, { entries: number; strokes: number }>;
- /** For each figure with an id: where its joints landed in the picture. */
- figures: Record<string, Record<string, readonly [number, number]>>;
- /** For each block with an id: its faces' corners in the picture, to place things on. */
- blocks: Record<string, Record<string, readonly (readonly number[])[]>>;
-}
-
-/** Draws a source that has been validated. */
-export function renderImage(source: ImageSource, options: { guides?: boolean; pictures?: Readonly<Record<string, RgbaBitmap>>; text?: ImageTextDrawer } = {}): RenderedImage {
- const [w, h] = typeof source.size === 'number' ? [source.size, source.size] : source.size;
- const canvas = new Canvas(w, h);
- const drawn: Drawn = { masks: new Map(), notes: [], bounds: new Map(), painted: new Map(), figures: new Map(), figureJoints: new Map(), showGuides: options.guides === true, pictures: options.pictures ?? {}, images: new Map(), text: options.text, blocks: new Map() };
- // What every layer so far amounts to, chained: a layer changed leaves the keys before it as they were.
- let key = textHash(JSON.stringify([w, h, source.background ?? null, options.guides === true, picturesDigest(options.pictures), source.tile === true]));
- const keys = source.layers.map((layer) => (key = textHash(key + JSON.stringify(layer))));
- let from = 0;
- for (let i = keys.length - 1; i >= 0; i--) {
- const kept = snapshots.get(keys[i]!);
- if (!kept) continue;
- restoreSnapshot(kept, canvas, drawn);
- // Used last, kept longest.
- snapshots.delete(keys[i]!);
- snapshots.set(keys[i]!, kept);
- from = i + 1;
- cacheCounters.reused += from;
- break;
- }
- if (from === 0 && source.background) {
- const [r, g, b, a] = parseColor(source.background);
- for (let i = 0; i < w * h; i++) put(canvas, i, r, g, b, a, 'normal');
- }
- let since = Date.now();
- // Set for this draw only, and taken off whatever happens: the next picture drawn may not repeat.
- setWrapping(source.tile === true);
- [tileWidth, tileHeight] = [w, h];
- try {
- for (let i = from; i < source.layers.length; i++) {
- drawLayer(canvas, source.layers[i]!, IDENTITY, drawn);
- cacheCounters.drawn++;
- if (i === source.layers.length - 1 || Date.now() - since >= SNAPSHOT_AFTER_MS) {
- keepSnapshot(keys[i]!, canvas, drawn);
- since = Date.now();
- }
- }
- } finally {
- setWrapping(false);
- }
- const rgba = new Uint8Array(w * h * 4);
- for (let i = 0; i < w * h; i++) {
- const a = canvas.px[i * 4 + 3]!;
- const d = a > 1e-5 ? 1 / a : 0;
- rgba[i * 4] = Math.round(Math.min(1, canvas.px[i * 4]! * d) * 255);
- rgba[i * 4 + 1] = Math.round(Math.min(1, canvas.px[i * 4 + 1]! * d) * 255);
- rgba[i * 4 + 2] = Math.round(Math.min(1, canvas.px[i * 4 + 2]! * d) * 255);
- rgba[i * 4 + 3] = Math.round(Math.min(1, a) * 255);
- }
- let solid = 0;
- for (let i = 0; i < w * h; i++) if (rgba[i * 4 + 3]! >= 128) solid++;
- return {
- width: w, height: h, rgba, notes: drawn.notes,
- bounds: boxOf(w, h, (i) => rgba[i * 4 + 3]! >= 128),
- covers: Math.round((solid / (w * h)) * 1000) / 1000,
- layerBounds: Object.fromEntries(drawn.bounds),
- painted: Object.fromEntries(drawn.painted),
- figures: Object.fromEntries(drawn.figureJoints),
- blocks: Object.fromEntries(drawn.blocks),
- };
-}
-
-function shrink(src: RgbaBitmap, width: number, height: number): RgbaBitmap {
- // Averaged by alpha: a transparent pixel's colour must not bleed into the edge beside it.
- const rgba = new Uint8Array(width * height * 4);
- for (let y = 0; y < height; y++) {
- const [y0, y1] = [Math.floor((y * src.height) / height), Math.max(Math.floor((y * src.height) / height) + 1, Math.floor(((y + 1) * src.height) / height))];
- for (let x = 0; x < width; x++) {
- const [x0, x1] = [Math.floor((x * src.width) / width), Math.max(Math.floor((x * src.width) / width) + 1, Math.floor(((x + 1) * src.width) / width))];
- let [r, g, b, a, n] = [0, 0, 0, 0, 0];
- for (let sy = y0; sy < y1; sy++) {
- for (let sx = x0; sx < x1; sx++) {
- const at = (sy * src.width + sx) * 4;
- const al = src.rgba[at + 3]!;
- r += src.rgba[at]! * al; g += src.rgba[at + 1]! * al; b += src.rgba[at + 2]! * al; a += al; n++;
- }
- }
- const to = (y * width + x) * 4;
- if (a > 0) { rgba[to] = r / a; rgba[to + 1] = g / a; rgba[to + 2] = b / a; }
- rgba[to + 3] = a / n;
- }
- }
- return { width, height, rgba };
-}
-
-type Ground = (x: number, y: number) => readonly [number, number, number];
-/** Between dark and light, so a dark outline and a pale highlight both show. On a near-black ground the outline a small icon wants disappears. */
-const midGround: Ground = () => [104, 112, 128];
-const checkGround: Ground = (x, y) => ((Math.floor(x / 12) + Math.floor(y / 12)) % 2 ? [226, 226, 230] : [250, 250, 252]);
-
-function layOn(rgba: Uint8Array, W: number, pic: RgbaBitmap, ox: number, oy: number, ground: Ground): void {
- for (let y = 0; y < pic.height; y++) {
- for (let x = 0; x < pic.width; x++) {
- const from = (y * pic.width + x) * 4;
- const a = pic.rgba[from + 3]! / 255;
- const g = ground(x, y);
- const to = ((oy + y) * W + ox + x) * 4;
- rgba[to] = pic.rgba[from]! * a + g[0] * (1 - a);
- rgba[to + 1] = pic.rgba[from + 1]! * a + g[1] * (1 - a);
- rgba[to + 2] = pic.rgba[from + 2]! * a + g[2] * (1 - a);
- rgba[to + 3] = 255;
- }
- }
-}
-
-const SHEET_GROUND = [64, 64, 68, 255] as const;
-
-function solidSheet(W: number, H: number): Uint8Array {
- const rgba = new Uint8Array(W * H * 4);
- for (let i = 0; i < W * H; i++) rgba.set(SHEET_GROUND, i * 4);
- return rgba;
-}
-
-const fitted = (image: RgbaBitmap, size: number): RgbaBitmap => {
- const k = size / Math.max(image.width, image.height);
- const [w, h] = [Math.max(1, Math.round(image.width * k)), Math.max(1, Math.round(image.height * k))];
- return k >= 1 ? nearestScale(image, w, h) : shrink(image, w, h);
-};
-
-/** Several pictures on one sheet, to be judged as a set: each on the mid ground and the check, then at 64 and 32, column by column. */
-export function setSheet(images: readonly RgbaBitmap[], cell = 128): RgbaBitmap {
- if (images.length === 0) throw new Error('a set needs at least one picture');
- const gap = 8;
- const columns = Math.min(8, images.length);
- const rows = Math.ceil(images.length / columns);
- const tall = cell * 2 + 64 + 32 + gap * 5;
- const W = columns * (cell + gap) + gap, H = rows * tall;
- const rgba = solidSheet(W, H);
- images.forEach((image, n) => {
- const [ox, oy] = [gap + (n % columns) * (cell + gap), Math.floor(n / columns) * tall + gap];
- const big = fitted(image, cell);
- layOn(rgba, W, big, ox, oy, midGround);
- layOn(rgba, W, big, ox, oy + cell + gap, checkGround);
- layOn(rgba, W, fitted(image, 64), ox, oy + cell * 2 + gap * 2, midGround);
- layOn(rgba, W, fitted(image, 32), ox, oy + cell * 2 + 64 + gap * 3, midGround);
- });
- return { width: W, height: H, rgba };
-}
-
-/** A part of a picture enlarged with hard pixels on the check, to see what the whole hides: a seam one pixel wide. */
-export function zoomImage(image: RgbaBitmap, region: { x: number; y: number; w: number; h: number }, longest = 1024): RgbaBitmap {
- const [x0, y0] = [Math.max(0, Math.floor(region.x)), Math.max(0, Math.floor(region.y))];
- const [w, h] = [Math.min(image.width - x0, Math.round(region.w)), Math.min(image.height - y0, Math.round(region.h))];
- if (!(w > 0 && h > 0)) throw new Error(`region ${JSON.stringify(region)} is outside the picture, ${image.width} by ${image.height}`);
- const cut = new Uint8Array(w * h * 4);
- for (let y = 0; y < h; y++) cut.set(image.rgba.subarray(((y0 + y) * image.width + x0) * 4, ((y0 + y) * image.width + x0 + w) * 4), y * w * 4);
- const k = Math.max(1, Math.floor(longest / Math.max(w, h)));
- const big = nearestScale({ width: w, height: h, rgba: cut }, w * k, h * k);
- const rgba = solidSheet(big.width, big.height);
- layOn(rgba, big.width, big, 0, 0, checkGround);
- return { width: big.width, height: big.height, rgba };
-}
-
-/** Something to look at: the picture on a mid ground and on a light check, as a transparent image needs both, and at the sizes an icon is really seen. */
-export function imageSheet(image: RgbaBitmap, sizes: readonly number[] = [96, 64, 48, 32]): RgbaBitmap {
- const big = Math.max(image.width, image.height);
- if (big >= LARGE_PICTURE && isOpaque(image)) return largeSheet(image);
- const k = big < 384 ? Math.max(1, Math.floor(384 / big)) : Math.min(1, 512 / big);
- const [pw, ph] = [Math.round(image.width * k), Math.round(image.height * k)];
- const gap = 8;
- const smallest = sizes.length ? Math.max(...sizes) : 0;
- const W = pw * 2 + gap * 3 + (smallest ? smallest + gap : 0);
- const H = Math.max(ph + gap * 2, sizes.reduce((s, v) => s + v + gap, gap) * 1);
- const rgba = new Uint8Array(W * H * 4);
- for (let i = 0; i < W * H; i++) rgba.set([64, 64, 68, 255], i * 4);
- const scaled = k >= 1 ? nearestScale(image, pw, ph) : shrink(image, pw, ph);
- const lay = (pic: RgbaBitmap, ox: number, oy: number, ground: Ground): void => layOn(rgba, W, pic, ox, oy, ground);
- lay(scaled, gap, gap, midGround);
- lay(scaled, gap * 2 + pw, gap, checkGround);
- let oy = gap;
- for (const s of sizes) {
- const small = shrink(image, s, Math.max(1, Math.round((s * image.height) / image.width)));
- lay(small, gap * 3 + pw * 2, oy, midGround);
- oy += small.height + gap;
- }
- return { width: W, height: H, rgba };
-}
-
-const LARGE_PICTURE = 512;
-
-export function isOpaque(image: RgbaBitmap): boolean {
- for (let i = 3; i < image.rgba.length; i += 4) if (image.rgba[i] !== 255) return false;
- return true;
-}
-
-/** What a full painting wants to be seen at: large, with nothing to judge against a ground, and small to check it still reads. */
-function largeSheet(image: RgbaBitmap): RgbaBitmap {
- const k = Math.min(1, 1024 / Math.max(image.width, image.height));
- const [pw, ph] = [Math.round(image.width * k), Math.round(image.height * k)];
- const gap = 8;
- const [W, H] = [pw + gap * 3 + 192, ph + gap * 2];
- const rgba = solidSheet(W, H);
- layOn(rgba, W, k < 1 ? shrink(image, pw, ph) : image, gap, gap, midGround);
- let oy = gap;
- for (const s of [192, 96]) {
- const small = shrink(image, s, Math.max(1, Math.round((s * image.height) / image.width)));
- if (oy + small.height > H) break;
- layOn(rgba, W, small, gap * 2 + pw, oy, midGround);
- oy += small.height + gap;
- }
- return { width: W, height: H, rgba };
-}
-
-/** The picture in lightness alone: whether it holds together in light and dark, before colour flatters it. */
-export function valuesImage(image: RgbaBitmap): RgbaBitmap {
- const rgba = new Uint8Array(image.rgba.length);
- for (let i = 0; i < rgba.length; i += 4) {
- const v = Math.round(lightness(image.rgba[i]!, image.rgba[i + 1]!, image.rgba[i + 2]!) * 255);
- rgba[i] = v; rgba[i + 1] = v; rgba[i + 2] = v; rgba[i + 3] = image.rgba[i + 3]!;
- }
- return { width: image.width, height: image.height, rgba };
-}
-
-const lightness = (r: number, g: number, b: number): number => (r * 0.2126 + g * 0.7152 + b * 0.0722) / 255;
-
-/** What is at each point: the colour, and how light it is 0..1. */
-export function pickColors(image: RgbaBitmap, points: readonly (readonly number[])[]): { at: readonly number[]; color: string; value: number }[] {
- return points.map((at) => {
- const [x, y] = [Math.floor(at[0]!), Math.floor(at[1]!)];
- if (!(x >= 0 && y >= 0 && x < image.width && y < image.height)) throw new Error(`[${at.join(', ')}] is outside the picture, ${image.width} by ${image.height}`);
- const i = (y * image.width + x) * 4;
- const [r, g, b, a] = [image.rgba[i]!, image.rgba[i + 1]!, image.rgba[i + 2]!, image.rgba[i + 3]!];
- const hex = (v: number): string => v.toString(16).padStart(2, '0');
- return { at, color: `#${hex(r)}${hex(g)}${hex(b)}${a === 255 ? '' : hex(a)}`, value: Math.round(lightness(r, g, b) * 100) / 100 };
- });
-}
-
-function nearestScale(src: RgbaBitmap, width: number, height: number): RgbaBitmap {
- const rgba = new Uint8Array(width * height * 4);
- for (let y = 0; y < height; y++) {
- const sy = Math.floor((y * src.height) / height);
- for (let x = 0; x < width; x++) {
- const from = (sy * src.width + Math.floor((x * src.width) / width)) * 4;
- rgba.set(src.rgba.subarray(from, from + 4), (y * width + x) * 4);
- }
- }
- return { width, height, rgba };
+/** The picture a source draws, figures and all. */
+export function renderImage(source: ImageSource, options: Parameters<typeof render>[1] = {}): RenderedImage {
+ return render(source, { figure: FIGURE_DRAWER, ...options });
}
diff --git a/pipeline/src/image/imageSource.ts b/pipeline/src/image/imageSource.ts
index 4c3c112e2..03d80e267 100644
--- a/pipeline/src/image/imageSource.ts
+++ b/pipeline/src/image/imageSource.ts
@@ -1,1013 +1,4 @@
// SPDX-License-Identifier: Apache-2.0
// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
-/**
- * @file imageSource.ts — `.esimage`: a picture as a list of layers, what a model writes and edits, and what is wrong with one.
- */
-import { parsePath } from './imagePath';
-
-export const IMAGE_BLENDS = [
- 'normal', 'multiply', 'screen', 'overlay', 'add', 'softLight', 'hardLight', 'vividLight', 'linearLight', 'pinLight', 'colorDodge', 'colorBurn', 'linearBurn',
- 'darken', 'lighten', 'difference', 'exclusion', 'subtract', 'divide', 'hue', 'saturation', 'color', 'luminosity',
-] as const;
-export type ImageBlend = (typeof IMAGE_BLENDS)[number];
-
-/** Adjustments of the picture so far. Any of them together, applied in this order. */
-export interface ImageAdjust {
- /** Stops, as a photo's: 1 is twice as bright. */
- exposure?: number;
- levels?: { input?: readonly [number, number]; gamma?: number; output?: readonly [number, number] };
- /** [[in, out]...] 0..1 for all channels, or { r, g, b } for each. */
- curves?: readonly (readonly number[])[] | { r?: readonly (readonly number[])[]; g?: readonly (readonly number[])[]; b?: readonly (readonly number[])[] };
- brightness?: number;
- contrast?: number;
- temperature?: number;
- tint?: number;
- /** Each [r, g, b], -1..1, pushing that part of the tonal range. */
- balance?: { shadows?: readonly number[]; midtones?: readonly number[]; highlights?: readonly number[] };
- /** Degrees round the wheel, and -1..1 each. */
- hue?: number;
- saturation?: number;
- lightness?: number;
- vibrance?: number;
- /** true, or how much of [r, g, b] each makes the grey. */
- blackWhite?: boolean | readonly number[];
- gradientMap?: readonly (readonly [number, string])[];
- invert?: boolean;
- posterize?: number;
- threshold?: number;
-}
-
-const ADJUST_RANGES: Readonly<Record<string, readonly [number, number]>> = { exposure: [-8, 8], brightness: [-1, 1], contrast: [-1, 1], temperature: [-1, 1], tint: [-1, 1], hue: [-360, 360], saturation: [-1, 1], lightness: [-1, 1], vibrance: [-1, 1], posterize: [2, 256], threshold: [0, 1] };
-
-function adjustProblem(a: unknown): string | null {
- if (typeof a !== 'object' || a === null) return 'must be an object of what to change';
- const o = a as Record<string, unknown>;
- const known = [...Object.keys(ADJUST_RANGES), 'levels', 'curves', 'balance', 'blackWhite', 'gradientMap', 'invert'];
- for (const key of Object.keys(o)) if (!known.includes(key)) return `has unknown "${key}"; there are ${known.join(', ')}`;
- if (Object.keys(o).length === 0) return 'changes nothing';
- for (const [key, [lo, hi]] of Object.entries(ADJUST_RANGES)) if (o[key] !== undefined && !(isNum(o[key]) && (o[key] as number) >= lo && (o[key] as number) <= hi)) return `${key} must be ${lo}..${hi}`;
- const unitPair = (v: unknown): boolean => isPair(v) && (v as number[]).every((n) => n >= 0 && n <= 1);
- const curve = (v: unknown): boolean => Array.isArray(v) && v.length >= 2 && v.every(unitPair);
- if (o.levels !== undefined) {
- const l = o.levels as Record<string, unknown>;
- if (typeof l !== 'object' || l === null) return 'levels must be { input?, gamma?, output? }';
- for (const key of Object.keys(l)) if (!['input', 'gamma', 'output'].includes(key)) return `levels has unknown "${key}"; there are input, gamma, output`;
- for (const key of ['input', 'output']) if (l[key] !== undefined && !unitPair(l[key])) return `levels ${key} must be [low, high], each 0..1`;
- if (l.gamma !== undefined && !(isNum(l.gamma) && (l.gamma as number) > 0)) return 'levels gamma must be positive';
- }
- if (o.curves !== undefined) {
- if (Array.isArray(o.curves)) { if (!curve(o.curves)) return 'curves must be two or more [in, out], each 0..1'; }
- else {
- const c = o.curves as Record<string, unknown>;
- if (typeof c !== 'object' || c === null) return 'curves must be [[in, out]...] or { r, g, b }';
- for (const [key, v] of Object.entries(c)) { if (!['r', 'g', 'b'].includes(key)) return `curves has unknown "${key}"; there are r, g, b`; if (!curve(v)) return `curves ${key} must be two or more [in, out], each 0..1`; }
- }
- }
- if (o.balance !== undefined) {
- for (const [key, v] of Object.entries(o.balance as Record<string, unknown>)) {
- if (!['shadows', 'midtones', 'highlights'].includes(key)) return `balance has unknown "${key}"; there are shadows, midtones, highlights`;
- if (!(Array.isArray(v) && v.length === 3 && v.every(isNum))) return `balance ${key} must be [r, g, b]`;
- }
- }
- if (o.blackWhite !== undefined && typeof o.blackWhite !== 'boolean' && !(Array.isArray(o.blackWhite) && o.blackWhite.length === 3 && o.blackWhite.every(isNum))) return 'blackWhite must be true or [r, g, b]';
- if (o.invert !== undefined && typeof o.invert !== 'boolean') return 'invert must be true or false';
- if (o.gradientMap !== undefined && !(Array.isArray(o.gradientMap) && o.gradientMap.length >= 2 && o.gradientMap.every((s) => Array.isArray(s) && s.length === 2 && isNum(s[0]) && isColor(s[1])))) return 'gradientMap must be two or more [0..1, colour]';
- return null;
-}
-
-/** Every filter and what it takes. A number but for: `at`, `from`, `to` a place; `color` a colour; `mono` true or false. */
-export const IMAGE_FILTERS = {
- gaussian: ['radius'], motion: ['angle', 'distance'], spin: ['at', 'angle'], zoom: ['at', 'amount'], lens: ['radius', 'highlights'],
- sharpen: ['amount', 'radius', 'threshold'], highPass: ['radius'], noise: ['amount', 'scale', 'mono', 'seed'], median: ['radius'], emboss: ['angle', 'height', 'amount'],
- ripple: ['amount', 'size', 'seed'], displace: ['amount', 'size', 'seed'], twirl: ['at', 'radius', 'angle'], pixelate: ['cell'], chromatic: ['at', 'amount'],
- vignette: ['at', 'amount', 'radius', 'outer', 'color'], fog: ['color', 'density', 'from', 'to', 'patchiness', 'size', 'seed'], rays: ['at', 'threshold', 'length', 'strength', 'decay'],
- flare: ['at', 'size', 'color', 'strength'], texture: ['scale', 'amount', 'angle', 'seed'],
-} as const;
-export type ImageFilterName = keyof typeof IMAGE_FILTERS;
-
-function filterProblem(name: unknown, params: unknown): string | null {
- if (typeof name !== 'string' || !Object.hasOwn(IMAGE_FILTERS, name)) return `filter ${JSON.stringify(name)} must be one of ${Object.keys(IMAGE_FILTERS).join(', ')}`;
- if (params === undefined) return null;
- if (typeof params !== 'object' || params === null) return 'params must be an object';
- const known = IMAGE_FILTERS[name as ImageFilterName] as readonly string[];
- for (const [key, v] of Object.entries(params)) {
- if (!known.includes(key)) return `filter ${name} has unknown "${key}"; it takes ${known.join(', ')}`;
- if (key === 'color') { if (!isColor(v)) return `filter ${name}: color must be #rgb..#rrggbbaa`; }
- else if (key === 'at' || key === 'from' || key === 'to') { if (!isPair(v)) return `filter ${name}: ${key} must be [x, y]`; }
- else if (key === 'mono') { if (typeof v !== 'boolean') return `filter ${name}: mono must be true or false`; }
- else if (!isNum(v)) return `filter ${name}: ${key} must be a number`;
- }
- return null;
-}
-
-export const IMAGE_SOURCE_EXT = '.esimage';
-export const IMAGE_SOURCE_VERSION = 1;
-export const MAX_IMAGE_SIZE = 2048;
-
-export type ImageFill = string
- | { type: 'linear'; from: readonly [number, number]; to: readonly [number, number]; stops: readonly (readonly [number, string])[] }
- | { type: 'radial'; at: readonly [number, number]; radius: number; stops: readonly (readonly [number, string])[] }
- /** The same picture on every machine: it comes from `seed` and never from a random number. */
- | { type: 'noise'; scale?: number; octaves?: number; seed?: number; stops: readonly (readonly [number, string])[] }
- /** By which way a figure's surface faces: 1 toward the light, 0.5 side on, 0 away. So light turns the form and does not sit on its edge. */
- | { type: 'form'; figure: string; light?: readonly number[]; stops: readonly (readonly [number, string])[] }
- /** The colour of an `image` layer at each place. */
- | { type: 'image'; image: string }
- /** Marks in rows and columns: windows, tiles, grilles. On four corners it lies in perspective. */
- | {
- type: 'grid';
- /** A cell's size in pixels, or with `quad` how many columns and rows there are. */
- cell?: readonly [number, number];
- cells?: readonly [number, number];
- /** Corners in order round: top left, top right, bottom right, bottom left. */
- quad?: readonly (readonly number[])[];
- /** The mark as a share of its cell, each 0..1. */
- mark?: readonly [number, number];
- colors: readonly string[];
- /** Between the marks; clear without it. */
- ground?: string;
- /** The share of marks that are on, 0..1, and what the rest show. */
- lit?: number;
- off?: string;
- seed?: number;
- };
-
-export interface ImageEffect {
- type: 'shadow' | 'glow' | 'innerShadow' | 'innerGlow' | 'bevel' | 'overlay';
- /** A bevel: how wide, the light's direction in degrees, how strong, and the colour on its dark side. */
- size?: number;
- angle?: number;
- depth?: number;
- shade?: string;
- /** An overlay: what covers the shape. */
- fill?: ImageFill;
- blend?: ImageBlend;
- color?: string;
- x?: number;
- y?: number;
- blur?: number;
- opacity?: number;
-}
-
-export interface ImageTransform {
- translate?: readonly [number, number];
- /** Degrees, clockwise on screen, about `origin`. */
- rotate?: number;
- scale?: number | readonly [number, number];
- /** Default the layer's middle. */
- origin?: readonly [number, number];
-}
-
-export type ImageShape = 'rect' | 'circle' | 'ellipse' | 'ring' | 'polygon' | 'line' | 'star' | 'gear' | 'path' | 'pixels' | 'paint' | 'figure' | 'image' | 'text' | 'block' | 'perspective' | 'reflect' | 'bloom' | 'adjust' | 'filter' | 'group';
-
-/** How a brush lays colour. Any of these on a stroke, a sweep or a field, over what its `brush` starts from. */
-export interface ImageBrushSettings {
- hardness?: number;
- opacity?: number;
- taper?: readonly [number, number];
- /** 1 round; lower is a flat brush, thin along its travel and wide across it. */
- roundness?: number;
- /** Degrees the flat of the brush is held at, which gives thick and thin as a pen does. Without it the brush turns with the stroke. */
- angle?: number;
- /** 0..1: how much the tooth of the paper breaks it up, in a texture fixed to the picture. */
- grain?: number;
- grainScale?: number;
- /** 0..1: how much the brush runs dry, in streaks along its travel. */
- dry?: number;
- /** 0..1: how much it picks up what is under it as it goes. */
- wet?: number;
- /** 0..1: pigment gathered at the edge, as watercolour dries. */
- edge?: number;
- /** Each dab this many brush radii off the line. */
- scatter?: number;
- /** The dabs as a share of the brush's size: small, and scattered, they are a spray. */
- dab?: number;
- /** Between dabs, as a share of a dab's width. */
- spacing?: number;
- /** 0..1: each dab adds this much, so paint builds where it passes, as an airbrush does, and opacity no longer caps it. */
- flow?: number;
- /** How much of the length at each end fades out, each 0..1. */
- fade?: readonly [number, number];
-}
-
-/** Named starting points, in the words a painter uses. */
-export const IMAGE_BRUSHES: Readonly<Record<string, ImageBrushSettings>> = {
- ink: { hardness: 1, taper: [0.12, 0.3] },
- pen: { hardness: 1, roundness: 0.25, angle: -45 },
- pencil: { hardness: 0.6, grain: 0.35, grainScale: 1.2, opacity: 0.75 },
- charcoal: { hardness: 0.35, grain: 0.5, grainScale: 2.2, dry: 0.12, opacity: 0.95 },
- chalk: { hardness: 0.7, grain: 0.55, grainScale: 6, opacity: 0.95 },
- flat: { hardness: 0.85, roundness: 0.3, dry: 0.3 },
- oil: { hardness: 0.65, roundness: 0.55, dry: 0.22, wet: 0.55, opacity: 0.95 },
- gouache: { hardness: 0.8, roundness: 0.5, wet: 0.2, dry: 0.08, opacity: 0.95 },
- watercolor: { hardness: 0.2, wet: 0.45, edge: 0.5, opacity: 0.45, grain: 0.05, grainScale: 5 },
- marker: { hardness: 0.9, roundness: 0.45, angle: -30, opacity: 0.72 },
- airbrush: { hardness: 0, flow: 0.05 },
- spray: { hardness: 0.7, dab: 0.07, scatter: 1, spacing: 0.5, opacity: 0.9 },
- dry: { hardness: 0.75, roundness: 0.35, dry: 0.65, opacity: 0.95 },
-};
-const BRUSH_FIELDS = ['brush', 'roundness', 'angle', 'grain', 'grainScale', 'dry', 'wet', 'edge', 'scatter', 'dab', 'spacing', 'flow', 'fade'];
-
-/** One movement of a brush. Replayed in order on a `paint` layer, so the same list is the same picture. */
-export interface ImageStroke extends ImageBrushSettings {
- /** A named brush from IMAGE_BRUSHES, which what else is given here overrides. */
- brush?: string;
- /** Through these, smoothly; a third number is pressure, 1 by default. One point is a dab. */
- points: readonly (readonly number[])[];
- color?: string;
- /** The colour it has become by the end. */
- to?: string;
- size: number;
- /** 1 is a hard edge, 0 fades from the middle. */
- hardness?: number;
- opacity?: number;
- /** How much of the length at each end narrows to a point, each 0..1. */
- taper?: readonly [number, number];
- /** Separate hairs across its width, which meet where it narrows. */
- bristles?: number;
- /** The width of a bristle; by default what spreads them across the stroke. */
- strand?: number;
- spread?: number;
- /** How far each bristle's lightness and strength differ, 0..1. */
- vary?: number;
- /** How far a bristle wanders from its line, in pixels. */
- wobble?: number;
- seed?: number;
- /** 0..1: drags what is already on this layer along, instead of laying colour. */
- smudge?: number;
- erase?: boolean;
- blend?: ImageBlend;
-}
-
-/** Many hairs between guide lines, gathered into locks. A few words of intent, and hundreds of strokes when drawn. */
-export interface ImageSweep extends ImageBrushSettings {
- type: 'sweep';
- brush?: string;
- /** Two or more lines, side by side and in order, each root to tip. */
- guides: readonly (readonly (readonly number[])[])[];
- /** Across the guides, first to last. */
- colors: readonly string[];
- count: number;
- /** What the colours have turned to by the tips. */
- tip?: string;
- /** The width of one hair. */
- size?: number;
- clumps?: number;
- /** How far hairs draw into their lock by the tips, 0..1. */
- gather?: number;
- /** The share of hairs that stray from the mass, 0..1. */
- flyaway?: number;
- vary?: number;
- wobble?: number;
- opacity?: number;
- taper?: readonly [number, number];
- seed?: number;
-}
-
-/** A region covered in strokes that follow a flow, each its colour from `tone` where it starts. */
-export interface ImageField extends ImageBrushSettings {
- type: 'field';
- brush?: string;
- /** An SVG path to start strokes in, or "@id" for where an earlier layer drew; the whole picture without it. Strokes may run over its edge. */
- region?: string;
- /** Lines the strokes follow, nearest the most, or a direction in degrees clockwise from right. */
- guides?: readonly (readonly (readonly number[])[])[];
- angle?: number;
- /** Where each stroke takes its colour; left out when it smudges. */
- tone?: ImageFill;
- /** 0..1: the strokes drag what is there along the flow, and lay no colour. */
- smudge?: number;
- size: number;
- length?: number;
- /** How many times over the strokes cover the region. */
- coverage?: number;
- /** Degrees either side of the flow. */
- spread?: number;
- vary?: number;
- opacity?: number;
- hardness?: number;
- seed?: number;
-}
-
-/** The same strokes again and again along a line: feathers, scales, leaves, beads. */
-export interface ImageAlong {
- type: 'along';
- line: readonly (readonly number[])[];
- count: number;
- /** Drawn with x along the line and y across it, about the point [0, 0]. */
- strokes: readonly ImageStroke[];
- /** How large they are at the start of the line and at the end. */
- scale?: number | readonly [number, number];
- /** Degrees, added to the line's direction. */
- turn?: number;
- /** Each one again, reflected across the line. */
- both?: boolean;
- /** Up to this far off their place, in pixels and a tenth as many degrees. */
- jitter?: number;
- seed?: number;
-}
-
-export type ImageMark = ImageStroke | ImageSweep | ImageField | ImageAlong;
-
-export interface ImageLayer {
- id?: string;
- shape: ImageShape;
- at?: readonly [number, number];
- size?: readonly [number, number];
- radius?: number | readonly number[];
- radii?: readonly [number, number];
- inner?: number;
- count?: number;
- tooth?: number;
- turn?: number;
- points?: readonly (readonly [number, number])[];
- d?: string;
- rows?: readonly string[];
- palette?: Readonly<Record<string, string>>;
- scale?: number;
- layers?: readonly ImageLayer[];
- strokes?: readonly ImageMark[];
- /** "below": a paint layer's canvas starts as the picture so far, so its strokes and smudges work across everything under it. */
- from?: 'below';
- /** Seen when looking and left out of the .png, while what it masks still works. A figure is one unless told otherwise. */
- guide?: boolean;
- /** A figure: pixels from floor to crown, standing straight. */
- height?: number;
- /** A figure: degrees turned about the body, 0 facing the viewer, 90 facing picture right, 180 away. */
- yaw?: number;
- /** A figure: degrees seen from above. */
- pitch?: number;
- build?: { head?: number; shoulders?: number; chest?: number; waist?: number; hips?: number; limbs?: number };
- pose?: {
- rotate?: Readonly<Record<string, readonly number[]>>;
- move?: Readonly<Record<string, readonly number[]>>;
- /** A joint and where it must be: [x, y] in the picture, or [x, y, z] on the body's own axes. */
- reach?: Readonly<Record<string, { at: readonly number[]; pole?: readonly number[] }>>;
- };
- /** Text: what it says. */
- text?: string;
- fontSize?: number;
- /** A family the machine has, or a font file in the project. */
- font?: string;
- weight?: number | string;
- align?: 'left' | 'center' | 'right';
- /** Characters one under the other, as a sign down a building. */
- vertical?: boolean;
- /** Extra between characters, in pixels. */
- tracking?: number;
- /** Text: pixels taken off each stroke of the letters, for the white-hot core of a neon tube. */
- thin?: number;
- /** Text: 0..1 how much the surface shows through, as worn paint, and how much it is rubbed away in streaks. */
- grain?: number;
- grainScale?: number;
- dry?: number;
- /** Text or paint: a face of a block already drawn, "id.a", to lie on: text within `within`, and strokes with their points counted 0..1 across it and 0..1 down. */
- face?: string;
- /** On a face, the part it takes: left, top, right, bottom, each 0..1. */
- within?: readonly number[];
- /** Text: four corners in the picture it is laid on, in order round from the top left, so it lies on a wall in perspective. */
- quad?: readonly (readonly number[])[];
- /** Pixels of soft edge on the layer, fading inward, keeping its colour where a blur would smear it. */
- feather?: number;
- /** What it clips to, softened, grown or shrunk, or turned inside out. */
- clipFeather?: number;
- clipGrow?: number;
- clipInvert?: boolean;
- /** Only where the picture so far is this light, [low, high, softness?] each 0..1: a highlight or shadow selected by what it is. */
- blendIf?: readonly number[];
- adjust?: ImageAdjust;
- filter?: ImageFilterName;
- params?: Readonly<Record<string, unknown>>;
- /** A bloom: how bright a pixel must be to shine, 0..1, and how much it does. */
- threshold?: number;
- strength?: number;
- /** A block or a perspective: the points lines recede to. */
- vanish?: readonly (readonly number[])[];
- /** A block: how far each face runs toward its vanishing point, 0..1. */
- depth?: readonly number[];
- /** A block: the fill of each face, and of the roof if it can be seen. */
- faces?: readonly ImageFill[];
- roof?: ImageFill;
- /** A reflect: the line it mirrors about, level or as points along where things meet the ground, how far down it reaches, and how far it wavers and smears in pixels. */
- y?: number;
- edge?: readonly (readonly number[])[];
- reach?: number;
- ripple?: number;
- smear?: number;
- /** An image: a picture in the project. */
- src?: string;
- /** Drawn everywhere but inside this earlier layer. */
- except?: string;
- /** A figure: where the light is, x right, y up, z toward the viewer. */
- light?: readonly number[];
- fill?: ImageFill;
- stroke?: { color: ImageFill; width: number; align?: 'center' | 'inside' | 'outside'; join?: 'round' | 'miter' | 'bevel'; cap?: 'round' | 'butt' | 'square' };
- opacity?: number;
- blend?: ImageBlend;
- transform?: ImageTransform;
- mirror?: 'x' | 'y';
- effects?: readonly ImageEffect[];
- clip?: string;
- erase?: boolean;
- visible?: boolean;
- /** Softens the layer as drawn, with its effects, in the picture's pixels. On a group it softens the group as one thing. */
- blur?: number;
-}
-
-export interface ImageSource {
- version?: number;
- size: number | readonly [number, number];
- background?: string;
- /**
- * The picture repeats: laid edge to edge with itself it shows no seam. What is drawn past one edge comes in at the
- * opposite one, a blur or a shadow goes round with it, and a noise fill repeats with the picture. For a wall, a floor,
- * a cloth: anything a surface is covered with.
- */
- tile?: boolean;
- /** What the surface is, beside what it looks like: see {@link ImageMaterial}. With it, a normal map and a material are written beside the picture. */
- material?: ImageMaterial;
- layers: readonly ImageLayer[];
-}
-
-/**
- * A picture as a surface. Each part is a number for the whole of it, or layers drawn as a grey picture of their own:
- * light is high, light is rough, light is metal.
- */
-export interface ImageMaterial {
- /** How far white stands above black, in pixels of the picture. Default 4. */
- relief?: number;
- /** The relief, drawn: light is high. Default: the colour picture's own lightness, dark being low. */
- height?: readonly ImageLayer[];
- /** How rough, 0..1 everywhere, or drawn: light is rough. Default 0.8. */
- roughness?: number | readonly ImageLayer[];
- /** How much metal, 0..1 everywhere, or drawn: light is metal. Default 0. */
- metal?: number | readonly ImageLayer[];
-}
-
-const isNum = (v: unknown): v is number => typeof v === 'number' && Number.isFinite(v);
-const isPair = (v: unknown): boolean => Array.isArray(v) && v.length === 2 && v.every(isNum);
-const isColor = (v: unknown): boolean => typeof v === 'string' && /^#(?:[0-9a-fA-F]{3,4}|[0-9a-fA-F]{6}|[0-9a-fA-F]{8})$/.test(v);
-
-function checkFill(v: unknown): string | null {
- if (typeof v === 'string') return isColor(v) ? null : `${JSON.stringify(v)} must be #rgb, #rgba, #rrggbb or #rrggbbaa`;
- const f = v as Record<string, unknown> | null;
- if (typeof f !== 'object' || f === null) return 'must be a colour or a gradient';
- if (f.type !== 'linear' && f.type !== 'radial' && f.type !== 'noise' && f.type !== 'form' && f.type !== 'image' && f.type !== 'grid') return 'a gradient has type linear, radial, noise, form, image or grid';
- if (f.type === 'grid') {
- if (!Array.isArray(f.colors) || f.colors.length === 0 || !f.colors.every(isColor)) return 'a grid needs colors: one or more';
- for (const key of ['ground', 'off']) if (f[key] !== undefined && !isColor(f[key])) return `a grid's ${key} must be a colour`;
- const quad = f.quad as unknown[] | undefined;
- if (quad !== undefined && !(Array.isArray(quad) && quad.length === 4 && quad.every(isPair))) return 'a grid\'s quad must be four [x, y], in order round from the top left';
- if (f.cell === undefined && f.cells === undefined) return 'a grid needs cell: [w, h] in pixels, or cells: [columns, rows]';
- for (const key of ['cell', 'cells']) if (f[key] !== undefined && !(isPair(f[key]) && (f[key] as number[]).every((v) => v > 0))) return `a grid's ${key} must be two positive numbers`;
- if (f.cell !== undefined && quad !== undefined) return 'a grid on a quad is counted in cells: [columns, rows]';
- if (f.mark !== undefined && !(isPair(f.mark) && (f.mark as number[]).every((v) => v > 0 && v <= 1))) return 'a grid\'s mark must be [w, h], each above 0 and up to 1';
- if (f.lit !== undefined && !(isNum(f.lit) && (f.lit as number) >= 0 && (f.lit as number) <= 1)) return 'a grid\'s lit must be 0..1';
- if (f.seed !== undefined && !Number.isInteger(f.seed)) return 'a grid\'s seed must be a whole number';
- return null;
- }
- if (f.type === 'image') return typeof f.image === 'string' && f.image ? null : 'an image fill needs image, the id of an image layer drawn before it';
- if (f.type === 'form') {
- if (typeof f.figure !== 'string' || !f.figure) return 'a form needs figure, the id of a figure drawn before it';
- if (f.light !== undefined && !(Array.isArray(f.light) && f.light.length === 3 && f.light.every(isNum))) return 'a form\'s light must be [x, y, z], x right, y up, z toward the viewer';
- }
- if (f.type === 'noise') {
- if (f.scale !== undefined && !(isNum(f.scale) && (f.scale as number) > 0)) return 'noise scale must be a positive number of pixels';
- if (f.octaves !== undefined && !(Number.isInteger(f.octaves) && (f.octaves as number) >= 1 && (f.octaves as number) <= 8)) return 'noise octaves must be a whole number from 1 to 8';
- if (f.seed !== undefined && !Number.isInteger(f.seed)) return 'noise seed must be a whole number';
- }
- if (f.type === 'linear' && !(isPair(f.from) && isPair(f.to))) return 'a linear gradient needs from and to, each [x, y]';
- if (f.type === 'linear' && (f.from as number[])[0] === (f.to as number[])[0] && (f.from as number[])[1] === (f.to as number[])[1]) return 'a linear gradient needs from and to apart: at one point it draws a single flat colour';
- if (f.type === 'radial' && !(isPair(f.at) && isNum(f.radius) && (f.radius as number) > 0)) return 'a radial gradient needs at: [x, y] and a positive radius';
- if (!Array.isArray(f.stops) || f.stops.length < 2) return 'a gradient needs two stops or more, each [0..1, colour]';
- for (const s of f.stops as unknown[]) {
- if (!Array.isArray(s) || s.length !== 2 || !isNum(s[0]) || !isColor(s[1])) return `a stop ${JSON.stringify(s)} must be [0..1, colour]`;
- }
- return null;
-}
-
-const FIELDS = ['id', 'shape', 'at', 'size', 'radius', 'radii', 'inner', 'count', 'tooth', 'turn', 'points', 'd', 'rows', 'palette', 'scale', 'layers', 'fill', 'stroke', 'opacity', 'blend', 'transform', 'mirror', 'effects', 'clip', 'erase', 'visible', 'blur', 'strokes', 'from', 'guide', 'height', 'yaw', 'pitch', 'build', 'pose', 'light', 'src', 'except', 'text', 'fontSize', 'font', 'weight', 'align', 'vertical', 'tracking', 'vanish', 'depth', 'faces', 'roof', 'y', 'edge', 'reach', 'ripple', 'smear', 'quad', 'threshold', 'strength', 'thin', 'grain', 'grainScale', 'dry', 'face', 'within', 'feather', 'clipFeather', 'clipGrow', 'clipInvert', 'blendIf', 'adjust', 'filter', 'params'];
-
-/** Layers that are aids to drawing unless told otherwise: seen when looking, and not in the .png. */
-export const isGuideLayer = (l: ImageLayer): boolean => l.guide ?? (l.shape === 'figure' || l.shape === 'image' || l.shape === 'perspective');
-const SHAPES: readonly ImageShape[] = ['rect', 'circle', 'ellipse', 'ring', 'polygon', 'line', 'star', 'gear', 'path', 'pixels', 'paint', 'figure', 'image', 'text', 'block', 'perspective', 'reflect', 'bloom', 'adjust', 'filter', 'group'];
-const STROKE_FIELDS = ['points', 'color', 'to', 'size', 'hardness', 'opacity', 'taper', 'bristles', 'strand', 'spread', 'vary', 'wobble', 'seed', 'smudge', 'erase', 'blend', ...BRUSH_FIELDS];
-
-/** What a brush's own settings must be, on whatever carries them. */
-function brushProblem(s: Record<string, unknown>): string | null {
- if (s.brush !== undefined && !(typeof s.brush === 'string' && Object.hasOwn(IMAGE_BRUSHES, s.brush))) return `brush ${JSON.stringify(s.brush)} must be one of ${Object.keys(IMAGE_BRUSHES).join(', ')}`;
- for (const key of ['roundness', 'grain', 'dry', 'wet', 'edge', 'dab', 'flow']) {
- if (s[key] !== undefined && !(isNum(s[key]) && (s[key] as number) >= 0 && (s[key] as number) <= 1)) return `${key} must be 0..1`;
- }
- if (s.roundness === 0 || s.dab === 0) return `${s.roundness === 0 ? 'roundness' : 'dab'} must be above 0`;
- for (const key of ['grainScale', 'spacing']) if (s[key] !== undefined && !(isNum(s[key]) && (s[key] as number) > 0)) return `${key} must be positive`;
- if (s.scatter !== undefined && !(isNum(s.scatter) && (s.scatter as number) >= 0)) return 'scatter must be 0 or more';
- if (s.angle !== undefined && !isNum(s.angle)) return 'angle must be degrees';
- if (s.fade !== undefined && !(Array.isArray(s.fade) && s.fade.length === 2 && s.fade.every((t) => isNum(t) && t >= 0 && t <= 1))) return 'fade must be [start, end], each 0..1';
- return null;
-}
-
-const SWEEP_FIELDS = ['type', 'guides', 'colors', 'count', 'tip', 'size', 'clumps', 'gather', 'flyaway', 'vary', 'wobble', 'opacity', 'taper', 'seed', 'hardness', ...BRUSH_FIELDS];
-const ALONG_FIELDS = ['type', 'line', 'count', 'strokes', 'scale', 'turn', 'both', 'jitter', 'seed'];
-const FIELD_FIELDS = ['type', 'region', 'guides', 'angle', 'tone', 'smudge', 'size', 'length', 'coverage', 'spread', 'vary', 'opacity', 'hardness', 'seed', 'taper', ...BRUSH_FIELDS];
-const isGuide = (g: unknown): boolean => Array.isArray(g) && g.length >= 2 && g.every((p) => Array.isArray(p) && (p.length === 2 || p.length === 3) && p.every(isNum));
-export const MAX_MARK_STROKES = 30000;
-
-function markProblem(s: Record<string, unknown>): string | null {
- const zeroToOne = (keys: readonly string[]): string | null => {
- for (const key of keys) if (s[key] !== undefined && !(isNum(s[key]) && (s[key] as number) >= 0 && (s[key] as number) <= 1)) return `${key} must be 0..1`;
- return null;
- };
- const fields = s.type === 'sweep' ? SWEEP_FIELDS : s.type === 'along' ? ALONG_FIELDS : FIELD_FIELDS;
- for (const key of Object.keys(s)) if (!fields.includes(key)) return `has unknown field "${key}"; a ${String(s.type)} takes ${fields.join(', ')}`;
- if (s.seed !== undefined && !Number.isInteger(s.seed)) return 'seed must be a whole number';
- if (s.type !== 'along') {
- const bad = brushProblem(s);
- if (bad) return bad;
- }
- if (s.type === 'sweep') {
- if (!Array.isArray(s.guides) || s.guides.length < 2 || !s.guides.every(isGuide)) return 'needs guides: two or more lines, each two or more [x, y]';
- if (!Array.isArray(s.colors) || s.colors.length === 0 || !s.colors.every(isColor)) return 'needs colors: one or more, across the guides';
- if (s.tip !== undefined && !isColor(s.tip)) return 'tip must be a colour';
- if (!(Number.isInteger(s.count) && (s.count as number) >= 1 && (s.count as number) <= MAX_MARK_STROKES)) return `count must be a whole number from 1 to ${MAX_MARK_STROKES}`;
- if (s.clumps !== undefined && !(Number.isInteger(s.clumps) && (s.clumps as number) >= 1)) return 'clumps must be a whole number of 1 or more';
- for (const key of ['size', 'wobble']) if (s[key] !== undefined && !(isNum(s[key]) && (s[key] as number) >= 0)) return `${key} must be 0 or more`;
- if (s.taper !== undefined && !(Array.isArray(s.taper) && s.taper.length === 2 && s.taper.every((t) => isNum(t) && t >= 0 && t <= 1))) return 'taper must be [start, end], each 0..1';
- return zeroToOne(['gather', 'flyaway', 'vary', 'opacity']);
- }
- if (s.type === 'along') {
- if (!isGuide(s.line)) return 'needs a line: two or more [x, y]';
- if (!(Number.isInteger(s.count) && (s.count as number) >= 1 && (s.count as number) <= 2000)) return 'count must be a whole number from 1 to 2000';
- if (!Array.isArray(s.strokes) || s.strokes.length === 0) return 'needs strokes, drawn about [0, 0]';
- for (const [n, inner] of (s.strokes as Record<string, unknown>[]).entries()) {
- if (inner?.type !== undefined) return `strokes[${n}] must be a plain stroke`;
- const bad = strokeProblem(inner);
- if (bad) return `strokes[${n}] ${bad}`;
- }
- const scale = s.scale;
- if (scale !== undefined && !(isNum(scale) && scale > 0) && !(isPair(scale) && (scale as number[]).every((v) => v > 0))) return 'scale must be a positive number, or [start, end]';
- for (const key of ['turn', 'jitter']) if (s[key] !== undefined && !isNum(s[key])) return `${key} must be a number`;
- return null;
- }
- if (s.region !== undefined) {
- if (typeof s.region !== 'string') return 'region must be an SVG path or "@id"';
- if (!s.region.startsWith('@')) {
- try { parsePath(s.region); } catch (e) { return `region: ${(e as Error).message}`; }
- }
- }
- if (s.guides !== undefined && !(Array.isArray(s.guides) && s.guides.length > 0 && s.guides.every(isGuide))) return 'guides must be one or more lines, each two or more [x, y]';
- if (s.angle !== undefined && !isNum(s.angle)) return 'angle must be degrees';
- if (s.tone === undefined && !s.smudge) return 'needs a tone, unless it smudges';
- if (s.tone !== undefined) {
- const bad = checkFill(s.tone);
- if (bad) return `tone ${bad}`;
- }
- for (const key of ['size', 'length', 'coverage']) {
- if (s[key] !== undefined && !(isNum(s[key]) && (s[key] as number) > 0)) return `${key} must be positive`;
- }
- if (s.size === undefined) return 'needs a positive size';
- if (s.spread !== undefined && !(isNum(s.spread) && (s.spread as number) >= 0)) return 'spread must be 0 or more degrees';
- return zeroToOne(['vary', 'opacity', 'hardness', 'smudge']);
-}
-
-function strokeProblem(s: Record<string, unknown>): string | null {
- if (typeof s !== 'object' || s === null) return 'must be an object';
- if (s.type === undefined) {
- const bad = brushProblem(s);
- if (bad) return bad;
- }
- if (s.type === 'sweep' || s.type === 'field' || s.type === 'along') return markProblem(s);
- if (s.type !== undefined) return `has type "${String(s.type)}"; there are sweep, field and along, or none for one stroke`;
- for (const key of Object.keys(s)) if (!STROKE_FIELDS.includes(key)) return `has unknown field "${key}"; a stroke takes ${STROKE_FIELDS.join(', ')}`;
- if (!Array.isArray(s.points) || s.points.length === 0 || !s.points.every((p) => Array.isArray(p) && (p.length === 2 || p.length === 3) && p.every(isNum))) return 'needs points, each [x, y] or [x, y, pressure]';
- if (!(isNum(s.size) && (s.size as number) > 0)) return 'needs a positive size';
- const paints = !s.erase && !s.smudge;
- if (paints && s.color === undefined) return 'needs a color, unless it erases or smudges';
- for (const key of ['color', 'to']) if (s[key] !== undefined && !isColor(s[key])) return `${key} must be #rgb, #rgba, #rrggbb or #rrggbbaa`;
- for (const key of ['hardness', 'opacity', 'vary', 'smudge']) if (s[key] !== undefined && !(isNum(s[key]) && (s[key] as number) >= 0 && (s[key] as number) <= 1)) return `${key} must be 0..1`;
- for (const key of ['strand', 'spread', 'wobble']) if (s[key] !== undefined && !(isNum(s[key]) && (s[key] as number) >= 0)) return `${key} must be 0 or more`;
- if (s.bristles !== undefined && !(Number.isInteger(s.bristles) && (s.bristles as number) >= 1 && (s.bristles as number) <= 200)) return 'bristles must be a whole number from 1 to 200';
- if (s.seed !== undefined && !Number.isInteger(s.seed)) return 'seed must be a whole number';
- if (s.taper !== undefined && !(Array.isArray(s.taper) && s.taper.length === 2 && s.taper.every((t) => isNum(t) && t >= 0 && t <= 1))) return 'taper must be [start, end], each 0..1';
- if (s.blend !== undefined && !IMAGE_BLENDS.includes(s.blend as ImageBlend)) return `blend must be one of ${IMAGE_BLENDS.join(', ')}`;
- return null;
-}
-
-function checkLayer(l: Record<string, unknown>, where: string, ids: Set<string>): void {
- const fail = (what: string): never => { throw new Error(`${where}: ${what}`); };
- if (typeof l !== 'object' || l === null) fail('must be an object');
- for (const key of Object.keys(l)) if (!FIELDS.includes(key)) fail(`unknown field "${key}"; a layer takes ${FIELDS.join(', ')}`);
- if (!SHAPES.includes(l.shape as ImageShape)) fail(`shape ${JSON.stringify(l.shape)} must be one of ${SHAPES.join(', ')}`);
- if (l.id !== undefined) {
- if (typeof l.id !== 'string' || !l.id) fail('id must be a string');
- if (ids.has(l.id as string)) fail(`the id "${String(l.id)}" is already used`);
- ids.add(l.id as string);
- }
- const num = (k: string, ok: (n: number) => boolean = () => true): void => { if (!isNum(l[k]) || !ok(l[k] as number)) fail(`${k} must be a number${ok === positive ? ' above 0' : ''}`); };
- const pair = (k: string): void => { if (!isPair(l[k])) fail(`${k} must be [a, b]`); };
- const positive = (n: number): boolean => n > 0;
- switch (l.shape) {
- case 'rect': if (l.face === undefined) { pair('at'); pair('size'); } if (l.radius !== undefined && !isNum(l.radius) && !(Array.isArray(l.radius) && l.radius.length === 4 && l.radius.every(isNum))) fail('radius must be a number or four corners'); break;
- case 'circle': pair('at'); num('radius', positive); break;
- case 'ellipse': pair('at'); pair('radii'); break;
- case 'ring': pair('at'); num('radius', positive); num('inner', positive); if ((l.inner as number) >= (l.radius as number)) fail('inner must be less than radius'); break;
- case 'polygon': case 'line':
- if (!Array.isArray(l.points) || l.points.length < (l.shape === 'line' ? 2 : 3) || !l.points.every(isPair)) fail(`points must be ${l.shape === 'line' ? 'two' : 'three'} or more [x, y]`);
- if (l.shape === 'line' && !l.stroke) fail('a line needs a stroke: { color, width }');
- break;
- case 'star': case 'gear': pair('at'); num('radius', positive); num('inner', positive); if (!Number.isInteger(l.count) || (l.count as number) < 3) fail('count must be 3 or more'); break;
- case 'path':
- if (typeof l.d !== 'string' || !l.d.trim()) fail('d must be an SVG path: M L H V C S Q T Z');
- // Here and not when it is drawn: a hidden layer is not drawn, and an error waits until it is shown.
- try {
- if (parsePath(l.d as string).every((run) => run.points.length === 0)) fail('d draws nothing');
- } catch (e) {
- fail((e as Error).message);
- }
- break;
- case 'figure': {
- if (!isPair(l.at)) fail('at must be [x, y]: the place on the floor under her');
- if (!(isNum(l.height) && (l.height as number) > 0)) fail('height must be pixels from floor to crown');
- for (const key of ['yaw', 'pitch']) if (l[key] !== undefined && !isNum(l[key])) fail(`${key} must be degrees`);
- if (l.light !== undefined && !(Array.isArray(l.light) && l.light.length === 3 && l.light.every(isNum))) fail('light must be [x, y, z], x right, y up, z toward the viewer');
- const build = l.build as Record<string, unknown> | undefined;
- for (const [key, value] of Object.entries(build ?? {})) {
- if (!['head', 'shoulders', 'chest', 'waist', 'hips', 'limbs'].includes(key)) fail(`build has unknown "${key}"; it takes head, shoulders, chest, waist, hips, limbs`);
- if (!(isNum(value) && (value as number) > 0)) fail(`build ${key} must be positive`);
- }
- const pose = l.pose as Record<string, Record<string, unknown>> | undefined;
- for (const key of Object.keys(pose ?? {})) if (!['rotate', 'move', 'reach'].includes(key)) fail(`pose has unknown "${key}"; it takes rotate, move, reach`);
- for (const [key, list] of Object.entries(pose ?? {})) {
- for (const [joint, value] of Object.entries(list)) {
- const numbers = key === 'reach' ? (value as { at?: unknown }).at : value;
- const lengths = key === 'reach' ? [2, 3] : [3];
- if (!(Array.isArray(numbers) && lengths.includes(numbers.length) && numbers.every(isNum))) fail(`pose ${key} "${joint}" must be ${key === 'reach' ? '{ at: [x, y] or [x, y, z] }' : '[x, y, z]'}`);
- }
- }
- break;
- }
- case 'text':
- if (typeof l.text !== 'string' || !l.text) fail('text must say something');
- if (l.within !== undefined && !(Array.isArray(l.within) && l.within.length === 4 && l.within.every((v) => isNum(v) && v >= 0 && v <= 1))) fail('within must be [left, top, right, bottom], each 0..1');
- if (l.face !== undefined) {
- if (typeof l.face !== 'string') fail('face must name a face of a block, as "id.a"');
- } else if (l.quad !== undefined) {
- if (!(Array.isArray(l.quad) && l.quad.length === 4 && l.quad.every(isPair))) fail('quad must be four [x, y], in order round from the top left');
- } else {
- pair('at');
- if (!(isNum(l.fontSize) && (l.fontSize as number) > 0)) fail('fontSize must be positive, in pixels');
- }
- if (l.font !== undefined && typeof l.font !== 'string') fail('font must be a family name or a font file in the project');
- if (l.align !== undefined && !['left', 'center', 'right'].includes(l.align as string)) fail('align must be left, center or right');
- if (l.tracking !== undefined && !isNum(l.tracking)) fail('tracking must be pixels');
- if (l.thin !== undefined && !(isNum(l.thin) && (l.thin as number) >= 0)) fail('thin must be 0 or more pixels');
- for (const key of ['grain', 'dry']) if (l[key] !== undefined && !(isNum(l[key]) && (l[key] as number) >= 0 && (l[key] as number) <= 1)) fail(`${key} must be 0..1`);
- if (l.grainScale !== undefined && !(isNum(l.grainScale) && (l.grainScale as number) > 0)) fail('grainScale must be positive');
- if (l.fill === undefined && l.stroke === undefined) fail('it needs a fill or a stroke, or it draws nothing');
- break;
- case 'adjust': {
- const bad = adjustProblem(l.adjust);
- if (bad) fail(`adjust ${bad}`);
- break;
- }
- case 'filter': {
- const bad = filterProblem(l.filter, l.params);
- if (bad) fail(bad);
- break;
- }
- case 'bloom':
- for (const key of ['threshold', 'strength']) if (l[key] !== undefined && !(isNum(l[key]) && (l[key] as number) >= 0)) fail(`${key} must be 0 or more`);
- if (l.threshold !== undefined && (l.threshold as number) > 1) fail('threshold must be 0..1');
- if (l.radius !== undefined && !(isNum(l.radius) && (l.radius as number) > 0)) fail('radius must be positive, in pixels');
- break;
- case 'perspective':
- if (!Array.isArray(l.vanish) || l.vanish.length === 0 || !l.vanish.every(isPair)) fail('vanish must be one or more [x, y]');
- break;
- case 'block': {
- pair('at');
- if (!(isNum(l.height) && (l.height as number) > 0)) fail('height must be pixels, from the corner at its foot up to its top');
- if (!Array.isArray(l.vanish) || l.vanish.length < 1 || l.vanish.length > 2 || !l.vanish.every(isPair)) fail('vanish must be one or two [x, y], where its faces recede to');
- if (!Array.isArray(l.depth) || l.depth.length !== (l.vanish as unknown[]).length || !l.depth.every((d) => isNum(d) && d > 0 && d <= 1)) fail('depth must give each vanishing point how far the face runs toward it, each above 0 and up to 1');
- if (!Array.isArray(l.faces) || l.faces.length !== (l.vanish as unknown[]).length) fail('faces must give one fill for each vanishing point');
- for (const face of l.faces as unknown[]) { const bad = checkFill(face); if (bad) fail(`face ${bad}`); }
- if (l.roof !== undefined) { const bad = checkFill(l.roof); if (bad) fail(`roof ${bad}`); }
- break;
- }
- case 'reflect':
- if (!isNum(l.y) && !(Array.isArray(l.edge) && l.edge.length >= 2 && l.edge.every(isPair))) fail('y must be the line it mirrors about, or edge two or more [x, y] along where things meet the ground');
- for (const key of ['reach', 'ripple', 'smear']) if (l[key] !== undefined && !(isNum(l[key]) && (l[key] as number) >= 0)) fail(`${key} must be 0 or more pixels`);
- break;
- case 'image':
- if (typeof l.src !== 'string' || !l.src) fail('src must be the path of a picture in the project');
- if (l.at !== undefined && !isPair(l.at)) fail('at must be [x, y]');
- if (l.size !== undefined && !isPair(l.size)) fail('size must be [w, h]');
- break;
- case 'paint': {
- if (!Array.isArray(l.strokes)) fail('strokes must be an array, which may start empty');
- if (l.face !== undefined && typeof l.face !== 'string') fail('face must name a face of a block, as "id.a"');
- if (l.from !== undefined && l.from !== 'below') fail('from must be "below"');
- if (l.from !== undefined && (l.fill !== undefined || l.effects !== undefined || l.blend !== undefined)) fail('from "below" works on the picture itself, and takes no fill, effects or blend');
- (l.strokes as Record<string, unknown>[]).forEach((s, n) => {
- const bad = strokeProblem(s);
- if (bad) fail(`stroke ${n} ${bad}`);
- });
- break;
- }
- case 'pixels': {
- if (!Array.isArray(l.rows) || l.rows.length === 0 || !l.rows.every((r) => typeof r === 'string')) fail('rows must be strings, one character a pixel');
- const pal = l.palette as Record<string, unknown> | undefined;
- if (typeof pal !== 'object' || pal === null) fail('palette must be { character: colour }');
- for (const [k, v] of Object.entries(pal!)) {
- if ([...k].length !== 1) fail(`palette key ${JSON.stringify(k)} must be one character`);
- if (!isColor(v)) fail(`palette "${k}" ${JSON.stringify(v)} must be a colour`);
- }
- const known = new Set(Object.keys(pal!));
- const width = (l.rows as string[])[0]!.length;
- (l.rows as string[]).forEach((row, i) => {
- if ([...row].length !== width) fail(`row ${i} is ${[...row].length} wide and row 0 is ${width}: a slip here shifts everything after it`);
- for (const ch of row) if (ch !== '.' && ch !== ' ' && !known.has(ch)) fail(`row ${i} has "${ch}", which is not in the palette; "." and " " are nothing`);
- });
- if (l.scale !== undefined) num('scale', positive);
- if (l.at !== undefined) pair('at');
- break;
- }
- case 'group':
- if (!Array.isArray(l.layers)) fail('a group needs layers');
- (l.layers as Record<string, unknown>[]).forEach((c, i) => checkLayer(c, `${where}.layers[${i}]`, ids));
- break;
- default:
- }
- if (l.fill !== undefined) { const bad = checkFill(l.fill); if (bad) fail(`fill ${bad}`); }
- if (l.stroke !== undefined) {
- const s = l.stroke as Record<string, unknown>;
- if (typeof s !== 'object' || s === null || !isNum(s.width) || (s.width as number) <= 0) fail('stroke must be { color, width, align? }');
- const bad = checkFill(s.color);
- if (bad) fail(`stroke color ${bad}`);
- if (s.align !== undefined && !['center', 'inside', 'outside'].includes(s.align as string)) fail('stroke align must be center, inside or outside');
- if (s.join !== undefined && !['round', 'miter', 'bevel'].includes(s.join as string)) fail('stroke join must be round, miter or bevel');
- if (s.cap !== undefined && !['round', 'butt', 'square'].includes(s.cap as string)) fail('stroke cap must be round, butt or square');
- }
- if (!['group', 'pixels', 'paint', 'figure', 'image', 'text', 'block', 'perspective', 'reflect', 'bloom', 'adjust', 'filter', 'line'].includes(l.shape as string) && l.fill === undefined && l.stroke === undefined && !l.erase) fail('it needs a fill or a stroke, or it draws nothing');
- if (l.from !== undefined && l.shape !== 'paint') fail('from is for a paint layer');
- if (l.guide !== undefined && typeof l.guide !== 'boolean') fail('guide must be true or false');
- if (l.blur !== undefined && !(isNum(l.blur) && (l.blur as number) >= 0)) fail('blur must be 0 or more, in pixels');
- if (l.blur && l.erase) fail('blur does not go with erase; put what cuts in a group with what it cuts, and blur the group');
- if (l.opacity !== undefined && !(isNum(l.opacity) && l.opacity >= 0 && l.opacity <= 1)) fail('opacity must be 0..1');
- if (l.blend !== undefined && !IMAGE_BLENDS.includes(l.blend as ImageBlend)) fail(`blend must be one of ${IMAGE_BLENDS.join(', ')}`);
- for (const key of ['feather', 'clipFeather']) if (l[key] !== undefined && !(isNum(l[key]) && (l[key] as number) >= 0)) fail(`${key} must be 0 or more pixels`);
- if (l.clipGrow !== undefined && !isNum(l.clipGrow)) fail('clipGrow must be pixels, more to grow what it clips to and less to shrink it');
- if (l.clipInvert !== undefined && typeof l.clipInvert !== 'boolean') fail('clipInvert must be true or false');
- if (l.blendIf !== undefined && !(Array.isArray(l.blendIf) && (l.blendIf.length === 2 || l.blendIf.length === 3) && l.blendIf.every((v) => isNum(v) && v >= 0 && v <= 1))) fail('blendIf must be [low, high] or [low, high, softness], each 0..1');
- if (l.mirror !== undefined && l.mirror !== 'x' && l.mirror !== 'y') fail('mirror must be x or y');
- if (l.clip !== undefined && typeof l.clip !== 'string') fail('clip must be a layer id');
- if (l.transform !== undefined) {
- const t = l.transform as Record<string, unknown>;
- for (const key of Object.keys(t)) if (!['translate', 'rotate', 'scale', 'origin'].includes(key)) fail(`transform has an unknown field "${key}"`);
- if (t.translate !== undefined && !isPair(t.translate)) fail('transform.translate must be [x, y]');
- if (t.origin !== undefined && !isPair(t.origin)) fail('transform.origin must be [x, y]');
- if (t.rotate !== undefined && !isNum(t.rotate)) fail('transform.rotate must be degrees');
- if (t.scale !== undefined && !isNum(t.scale) && !isPair(t.scale)) fail('transform.scale must be a number or [x, y]');
- }
- if (l.effects !== undefined) {
- if (!Array.isArray(l.effects)) fail('effects must be an array');
- for (const e of l.effects as Record<string, unknown>[]) {
- if (!['shadow', 'glow', 'innerShadow', 'innerGlow', 'bevel', 'overlay'].includes(e?.type as string)) fail(`an effect has type ${JSON.stringify(e?.type)}; there are shadow, glow, innerShadow, innerGlow, bevel, overlay`);
- if (e.type === 'overlay') { const bad = checkFill(e.fill); if (bad) fail(`effect overlay: fill ${bad}`); }
- if (e.blend !== undefined && !IMAGE_BLENDS.includes(e.blend as ImageBlend)) fail(`effect ${String(e.type)}: blend must be one of ${IMAGE_BLENDS.join(', ')}`);
- if (e.shade !== undefined && !isColor(e.shade)) fail(`effect ${String(e.type)}: shade must be #rgb..#rrggbbaa`);
- for (const key of Object.keys(e)) if (!['type', 'color', 'x', 'y', 'blur', 'opacity', 'size', 'angle', 'depth', 'shade', 'fill', 'blend'].includes(key)) fail(`effect ${String(e.type)} has an unknown field "${key}"`);
- if (e.color !== undefined && !isColor(e.color)) fail(`effect ${String(e.type)}: color must be #rgb..#rrggbbaa`);
- for (const k of ['x', 'y', 'blur', 'opacity', 'size', 'angle', 'depth']) if (e[k] !== undefined && !isNum(e[k])) fail(`effect ${String(e.type)}: ${k} must be a number`);
- }
- }
-}
-
-/** The source if it is well formed; otherwise throws, naming the layer and the field. */
-export function validateImageSource(raw: unknown): ImageSource {
- if (typeof raw !== 'object' || raw === null || Array.isArray(raw)) throw new Error('an image source must be { size, layers }');
- const s = raw as Record<string, unknown>;
- for (const key of Object.keys(s)) if (!['version', 'size', 'background', 'tile', 'material', 'layers'].includes(key)) throw new Error(`unknown field "${key}"; an image has version, size, background, tile, material, layers`);
- if (s.tile !== undefined && typeof s.tile !== 'boolean') throw new Error('tile must be true or false');
- if (s.version !== undefined && s.version !== IMAGE_SOURCE_VERSION) throw new Error(`version ${String(s.version)} is not one this editor reads (${IMAGE_SOURCE_VERSION})`);
- const [w, h] = typeof s.size === 'number' ? [s.size, s.size] : isPair(s.size) ? (s.size as number[]) : [NaN, NaN];
- if (!Number.isInteger(w) || !Number.isInteger(h) || w! < 1 || h! < 1 || w! > MAX_IMAGE_SIZE || h! > MAX_IMAGE_SIZE) throw new Error(`size must be a whole number or [width, height], 1..${MAX_IMAGE_SIZE}`);
- if (s.background !== undefined && !isColor(s.background)) throw new Error('background must be a colour; leave it out for a transparent picture');
- if (!Array.isArray(s.layers)) throw new Error('layers must be an array');
- const ids = new Set<string>();
- (s.layers as Record<string, unknown>[]).forEach((l, i) => checkLayer(l, `layer ${i}${l?.id ? ` "${String(l.id)}"` : ''}`, ids));
- if (s.material !== undefined) {
- const m = s.material as Record<string, unknown> | null;
- if (typeof m !== 'object' || m === null || Array.isArray(m)) throw new Error('material must be { relief?, height?, roughness?, metal? }');
- for (const key of Object.keys(m)) if (!['relief', 'height', 'roughness', 'metal'].includes(key)) throw new Error(`material has unknown "${key}"; it takes relief, height, roughness, metal`);
- if (m.relief !== undefined && !(isNum(m.relief) && (m.relief as number) >= 0 && (m.relief as number) <= 64)) throw new Error('material.relief must be 0..64, in pixels');
- const drawn = (key: string, v: unknown): void => {
- if (!Array.isArray(v) || v.length === 0) throw new Error(`material.${key} must be layers, one or more`);
- (v as Record<string, unknown>[]).forEach((l, i) => checkLayer(l, `material.${key} layer ${i}${l?.id ? ` "${String(l.id)}"` : ''}`, ids));
- };
- if (m.height !== undefined) drawn('height', m.height);
- for (const key of ['roughness', 'metal']) {
- const v = m[key];
- if (v === undefined) continue;
- if (isNum(v)) { if (v < 0 || v > 1) throw new Error(`material.${key} must be 0..1, or layers`); }
- else drawn(key, v);
- }
- }
- return { version: IMAGE_SOURCE_VERSION, ...(s as unknown as ImageSource) };
-}
-
-export type ImageEdit =
- | { op: 'set'; layer: string; fields: Record<string, unknown> }
- | { op: 'insert'; layer: ImageLayer; before?: string; after?: string; into?: string }
- | { op: 'remove'; layer: string }
- | { op: 'move'; layer: string; before?: string; after?: string; into?: string }
- | { op: 'paint'; layer: string; strokes?: readonly ImageMark[]; drop?: number; at?: number; remove?: number }
- | { op: 'wrap'; layers: readonly string[]; group: Partial<ImageLayer> }
- | { op: 'unwrap'; layer: string }
- | {
- op: 'pixels';
- layer: string;
- set?: readonly { row: number; at?: number; text: string }[];
- rect?: readonly { x: number; y: number; w?: number; h?: number; text: string }[];
- palette?: Readonly<Record<string, string | null>>;
- }
- | { op: 'settings'; fields: { size?: ImageSource['size']; background?: string | null; tile?: boolean | null; material?: ImageMaterial | null } };
-
-/** Every stroke width a source draws with, and how many layers use each: what drifts first across a set of icons. */
-export function strokeWidths(source: ImageSource): Record<string, number> {
- const out: Record<string, number> = {};
- const walk = (layers: readonly ImageLayer[]): void => {
- for (const l of layers) {
- if (l.stroke) out[String(l.stroke.width)] = (out[String(l.stroke.width)] ?? 0) + 1;
- if (l.layers) walk(l.layers);
- }
- };
- walk(source.layers);
- return out;
-}
-
-/** A source with @p edits applied in order, where layers are named by id at any depth. Throws, naming what it could not find. */
-export function applyImageEdits(source: ImageSource, edits: readonly ImageEdit[]): ImageSource {
- const clone = JSON.parse(JSON.stringify(source)) as { size: ImageSource['size']; background?: string; version?: number; layers: (ImageLayer & Record<string, unknown>)[] };
- type Row = ImageLayer & Record<string, unknown>;
- const allIds: string[] = [];
- const find = (id: string, list: Row[] = clone.layers): { list: Row[]; index: number } | null => {
- for (let i = 0; i < list.length; i++) {
- if (list[i]!.id === id) return { list, index: i };
- if (list[i]!.layers) {
- const hit = find(id, list[i]!.layers as Row[]);
- if (hit) return hit;
- }
- }
- return null;
- };
- const need = (id: string): { list: Row[]; index: number } => {
- const hit = find(id);
- if (hit) return hit;
- allIds.length = 0;
- const walk = (list: Row[]): void => { for (const l of list) { if (l.id) allIds.push(l.id); if (l.layers) walk(l.layers as Row[]); } };
- walk(clone.layers);
- throw new Error(`no layer "${id}"; ids: ${allIds.join(', ') || '(none: give layers an id to edit them)'}`);
- };
- for (const edit of edits) {
- switch (edit?.op) {
- case 'set': {
- const { list, index } = need(edit.layer);
- for (const [k, v] of Object.entries(edit.fields ?? {})) {
- if (v === null) delete list[index]![k];
- else list[index]![k] = v;
- }
- break;
- }
- case 'insert': {
- if (edit.into !== undefined) {
- const { list, index } = need(edit.into);
- const group = list[index]!;
- if (group.shape !== 'group') throw new Error(`layer "${edit.into}" is not a group`);
- (group.layers as Row[]).push(edit.layer as Row);
- } else if (edit.before !== undefined) {
- const { list, index } = need(edit.before);
- list.splice(index, 0, edit.layer as Row);
- } else if (edit.after !== undefined) {
- const { list, index } = need(edit.after);
- list.splice(index + 1, 0, edit.layer as Row);
- } else clone.layers.push(edit.layer as Row);
- break;
- }
- case 'remove': {
- const { list, index } = need(edit.layer);
- list.splice(index, 1);
- break;
- }
- case 'move': {
- const given = [edit.before, edit.after, edit.into].filter((v) => v !== undefined);
- if (given.length > 1) throw new Error('move takes one of before, after and into');
- const { list, index } = need(edit.layer);
- const [row] = list.splice(index, 1);
- const within = (l: Row): boolean => l.id === given[0] || ((l.layers as Row[] | undefined) ?? []).some(within);
- if (given.length && within(row!)) {
- list.splice(index, 0, row!);
- throw new Error(`layer "${edit.layer}" cannot move next to or into "${String(given[0])}", which is itself or inside it`);
- }
- if (edit.into !== undefined) {
- const target = need(edit.into);
- const group = target.list[target.index]!;
- if (group.shape !== 'group') throw new Error(`layer "${edit.into}" is not a group`);
- (group.layers as Row[]).push(row!);
- } else if (edit.before !== undefined) {
- const target = need(edit.before);
- target.list.splice(target.index, 0, row!);
- } else if (edit.after !== undefined) {
- const target = need(edit.after);
- target.list.splice(target.index + 1, 0, row!);
- } else clone.layers.push(row!);
- break;
- }
- case 'paint': {
- const { list, index } = need(edit.layer);
- const layer = list[index]!;
- if (layer.shape !== 'paint') throw new Error(`layer "${edit.layer}" is not paint`);
- const had = layer.strokes as readonly ImageMark[];
- const drop = edit.drop ?? 0;
- if (!Number.isInteger(drop) || drop < 0 || drop > had.length) throw new Error(`layer "${edit.layer}" has ${had.length} strokes: cannot drop ${String(edit.drop)}`);
- const kept = had.slice(0, had.length - drop);
- const at = edit.at ?? kept.length;
- const remove = edit.remove ?? 0;
- if (!Number.isInteger(at) || at < 0 || at > kept.length || !Number.isInteger(remove) || remove < 0 || at + remove > kept.length) throw new Error(`layer "${edit.layer}" has ${kept.length} strokes: cannot replace ${remove} at ${at}`);
- kept.splice(at, remove, ...(edit.strokes ?? []));
- layer.strokes = kept;
- break;
- }
- case 'wrap': {
- if (!Array.isArray(edit.layers) || edit.layers.length === 0) throw new Error('wrap needs layers, the ids to put in the group');
- const found = edit.layers.map((id) => ({ id, ...need(id) }));
- if (found.some((f) => f.list !== found[0]!.list)) throw new Error(`wrap takes layers side by side, and ${edit.layers.join(', ')} are not all in one list`);
- const list = found[0]!.list;
- // Kept in the order they draw, whatever order they were named in: wrapping must not change what is over what.
- const indices = found.map((f) => f.index).sort((a, b) => a - b);
- const children = indices.map((i) => list[i]!);
- for (const i of [...indices].reverse()) list.splice(i, 1);
- list.splice(indices[0]!, 0, { ...edit.group, shape: 'group', layers: children } as Row);
- break;
- }
- case 'unwrap': {
- const { list, index } = need(edit.layer);
- const group = list[index]!;
- if (group.shape !== 'group') throw new Error(`layer "${edit.layer}" is not a group`);
- const kept = ['transform', 'effects', 'opacity', 'blend', 'clip', 'mirror', 'visible'].filter((k) => group[k] !== undefined);
- if (kept.length) throw new Error(`group "${edit.layer}" has ${kept.join(', ')}, which its layers would lose; set them to null first`);
- list.splice(index, 1, ...(group.layers as Row[]));
- break;
- }
- case 'pixels': {
- const { list, index } = need(edit.layer);
- const layer = list[index]!;
- if (layer.shape !== 'pixels') throw new Error(`layer "${edit.layer}" is not pixels`);
- const rows = [...(layer.rows as string[])];
- if (edit.palette) {
- const palette = { ...(layer.palette as Record<string, string>) };
- for (const [key, value] of Object.entries(edit.palette)) {
- if (value === null) delete palette[key];
- else palette[key] = value;
- }
- layer.palette = palette;
- }
- for (const area of edit.rect ?? []) {
- const [w, h, char] = [area.w ?? 1, area.h ?? 1, [...(area.text ?? '')]];
- if (char.length !== 1) throw new Error(`a rect in "${edit.layer}" paints one character, not "${area.text}"`);
- const width = [...rows[0]!].length;
- if (!(Number.isInteger(area.x) && Number.isInteger(area.y) && Number.isInteger(w) && Number.isInteger(h) && area.x >= 0 && area.y >= 0 && w > 0 && h > 0 && area.x + w <= width && area.y + h <= rows.length)) {
- throw new Error(`layer "${edit.layer}" is ${width} by ${rows.length}: a rect of ${w} by ${h} at ${area.x}, ${area.y} does not fit`);
- }
- for (let y = area.y; y < area.y + h; y++) {
- const chars = [...rows[y]!];
- chars.fill(char[0]!, area.x, area.x + w);
- rows[y] = chars.join('');
- }
- }
- for (const change of edit.set ?? []) {
- const row = rows[change.row];
- if (row === undefined) throw new Error(`layer "${edit.layer}" has rows 0..${rows.length - 1}, not ${change.row}`);
- const chars = [...row], text = [...change.text], at = change.at ?? 0;
- if (at < 0 || at + text.length > chars.length) throw new Error(`row ${change.row} of "${edit.layer}" is ${chars.length} wide: ${text.length} at ${at} does not fit`);
- chars.splice(at, text.length, ...text);
- rows[change.row] = chars.join('');
- }
- layer.rows = rows;
- break;
- }
- case 'settings':
- if (edit.fields?.size !== undefined) clone.size = edit.fields.size;
- if (edit.fields?.background === null) delete clone.background;
- else if (edit.fields?.background !== undefined) clone.background = edit.fields.background;
- // The whole of each, or none: a relief is replaced with the layers that draw it.
- for (const key of ['tile', 'material'] as const) {
- if (edit.fields?.[key] === null) delete (clone as Record<string, unknown>)[key];
- else if (edit.fields?.[key] !== undefined) (clone as Record<string, unknown>)[key] = edit.fields[key];
- }
- break;
- default:
- throw new Error(`an edit has op ${JSON.stringify((edit as { op?: unknown })?.op)}; there are set, insert, remove, move, paint, wrap, unwrap, pixels, settings`);
- }
- }
- return validateImageSource(clone);
-}
+// The picture code is the SDK's (sdk/src/image), so a game can evaluate a picture as the pipeline does; this is where the pipeline reaches it.
+export * from '../../../sdk/src/image/imageSource';
diff --git a/pipeline/src/project/targetSupport.ts b/pipeline/src/project/targetSupport.ts
index d9f4c79e6..b1b08c005 100644
--- a/pipeline/src/project/targetSupport.ts
+++ b/pipeline/src/project/targetSupport.ts
@@ -28,7 +28,7 @@ import { NATIVE_PLATFORMS, type ExportPlatform } from './platforms';
/** An engine subsystem a build target may lack. */
export type Subsystem =
| 'text' | 'tilemap' | 'terrain' | 'foliage' | 'worldgen' | 'water' | 'spline' | 'voxel' | 'rig2d' | 'importedScene' | 'skeletalAnimation' | 'characterShaders' | 'timeline' | 'fxBasic' | 'fxAtmosphere' | 'fxLighting' | 'fxAgx' | 'particles' | 'postprocess' | 'physics' | 'physics3d'
- | 'spine' | 'dragonbones' | 'video' | 'ai' | 'logic' | 'replication' | 'gameplay';
+ | 'spine' | 'dragonbones' | 'video' | 'ai' | 'logic' | 'replication' | 'gameplay' | 'textureRecipe';
/**
* The authored vocabulary that puts a subsystem in use: a scene or prefab
@@ -38,6 +38,8 @@ export type Subsystem =
*/
export const SUBSYSTEM_COMPONENTS: Readonly<Record<Subsystem, readonly string[]>> = {
text: ['Text', 'BitmapText'],
+ // No component: a package reaches it by shipping a texture that is a recipe (an .esimage), which the walk of what ships sees.
+ textureRecipe: [],
tilemap: ['Tilemap', 'TilemapLayer'],
terrain: ['Terrain'],
timeline: ['TimelinePlayer'],
@@ -110,6 +112,7 @@ export const SHADER_SUBSYSTEM: Readonly<Record<string, Subsystem>> = {
/** Human name, for a message someone packaging a game has to act on. */
export const SUBSYSTEM_LABEL: Readonly<Record<Subsystem, string>> = {
text: 'Text',
+ textureRecipe: 'Texture recipes (pictures drawn on the device)',
tilemap: 'Tilemaps',
terrain: 'Terrain',
timeline: 'Timelines',
@@ -147,6 +150,7 @@ export const SUBSYSTEM_LABEL: Readonly<Record<Subsystem, string>> = {
*/
export const SUBSYSTEM_INSTALL: Readonly<Record<Subsystem, string>> = {
text: 'base',
+ textureRecipe: 'esengine/image',
particles: 'base',
postprocess: 'base',
tilemap: 'esengine/tilemap',
diff --git a/pipeline/tests/engine-installs.test.ts b/pipeline/tests/engine-installs.test.ts
index 5c2efe826..b0d1a1864 100644
--- a/pipeline/tests/engine-installs.test.ts
+++ b/pipeline/tests/engine-installs.test.ts
@@ -137,7 +137,7 @@ describe('every subpath the SDK publishes', () => {
}
// The two tables engineInstalls keeps for evidence content does not carry
// as a component — asked through it, so this cannot read a stale copy.
- for (const ext of ['.esgraph', '.esfsm', '.esbt']) {
+ for (const ext of ['.esgraph', '.esfsm', '.esbt', '.esimage']) {
for (const s of engineInstalls({ assetPaths: [`x${ext}`] }).subpaths) installable.add(s);
}
for (const id of ['physics', 'physics3d', 'dragonbones', 'spine:4.2']) {
@@ -259,7 +259,7 @@ describe('every module a project can refuse', () => {
);
// Detection also reads asset extensions, which is how a script graph is
// found; asked through engineInstalls so this cannot read a stale copy.
- for (const ext of ['.esgraph', '.esfsm', '.esbt']) {
+ for (const ext of ['.esgraph', '.esfsm', '.esbt', '.esimage']) {
for (const s of engineInstalls({ assetPaths: [`x${ext}`] }).subpaths) byComponent.add(s);
}
// …and a post-process effect group is found by the effects a volume names.
diff --git a/sdk/etc/image.api.md b/sdk/etc/image.api.md
new file mode 100644
index 000000000..bce4597f0
--- /dev/null
+++ b/sdk/etc/image.api.md
@@ -0,0 +1,180 @@
+# API surface — esengine/image
+
+<!-- Generated by tools/api-surface.mjs — do not edit. Run --update to accept changes. -->
+Symbols: 0 public · 0 beta · 15 experimental · 0 deprecated
+
+## FlatFigure — interface @experimental
+```
+contour: Float32Array<ArrayBufferLike>
+joints: Record<string, readonly [number, number]>
+light: readonly [number, number, number]
+lines: readonly (readonly (readonly [number, number])[])[]
+mask: Float32Array<ArrayBufferLike>
+normals: Float32Array<ArrayBufferLike>
+parts: Record<string, Float32Array<ArrayBufferLike>>
+```
+
+## IMAGE_SOURCE_EXT — const @experimental
+```
+".esimage"
+```
+
+## IMAGE_SOURCE_VERSION — const @experimental
+```
+1
+```
+
+## ImageFigureDrawer — interface @experimental
+```
+flatten: (layer: ImageLayer, w: number, h: number, project: (p: readonly [number, number]) => readonly [number, number], scale: number) => FlatFigure
+```
+
+## ImageLayer — interface @experimental
+```
+adjust: ImageAdjust | undefined
+align: "right" | "left" | "center" | undefined
+at: readonly [number, number] | undefined
+blend: "color" | "normal" | "multiply" | "add" | "hue" | "subtract" | "screen" | "overlay" | "softLight" | "hardLight" | "vividLight" | "linearLight" | "pinLight" | "colorDodge" | "colorBurn" | "linearBurn" | "darken" | "lighten" | "difference" | "exclusion" | "divide" | "saturation" | "luminosity" | undefined
+blendIf: readonly number[] | undefined
+blur: number | undefined
+build: { head?: number; shoulders?: number; chest?: number; waist?: number; hips?: number; limbs?: number; } | undefined
+clip: string | undefined
+clipFeather: number | undefined
+clipGrow: number | undefined
+clipInvert: boolean | undefined
+count: number | undefined
+d: string | undefined
+depth: readonly number[] | undefined
+dry: number | undefined
+edge: readonly (readonly number[])[] | undefined
+effects: readonly ImageEffect[] | undefined
+erase: boolean | undefined
+except: string | undefined
+face: string | undefined
+faces: readonly ImageFill[] | undefined
+feather: number | undefined
+fill: ImageFill | undefined
+filter: "texture" | "motion" | "lens" | "rays" | "noise" | "gaussian" | "spin" | "zoom" | "sharpen" | "highPass" | "median" | "emboss" | "ripple" | "displace" | "twirl" | "pixelate" | "chromatic" | "vignette" | "fog" | "flare" | undefined
+font: string | undefined
+fontSize: number | undefined
+from: "below" | undefined
+grain: number | undefined
+grainScale: number | undefined
+guide: boolean | undefined
+height: number | undefined
+id: string | undefined
+inner: number | undefined
+layers: readonly ImageLayer[] | undefined
+light: readonly number[] | undefined
+mirror: "x" | "y" | undefined
+opacity: number | undefined
+palette: Readonly<Record<string, string>> | undefined
+params: Readonly<Record<string, unknown>> | undefined
+pitch: number | undefined
+points: readonly (readonly [number, number])[] | undefined
+pose: { rotate?: Readonly<Record<string, readonly number[]>>; move?: Readonly<Record<string, readonly number[]>>; reach?: Readonly<Record<string, { at: readonly number[]; pole?: readonly number[]; }>>; } | undefined
+quad: readonly (readonly number[])[] | undefined
+radii: readonly [number, number] | undefined
+radius: number | readonly number[] | undefined
+reach: number | undefined
+ripple: number | undefined
+roof: ImageFill | undefined
+rows: readonly string[] | undefined
+scale: number | undefined
+shape: ImageShape
+size: readonly [number, number] | undefined
+smear: number | undefined
+src: string | undefined
+strength: number | undefined
+stroke: { color: ImageFill; width: number; align?: "center" | "inside" | "outside"; join?: "round" | "miter" | "bevel"; cap?: "round" | "butt" | "square"; } | undefined
+strokes: readonly ImageMark[] | undefined
+text: string | undefined
+thin: number | undefined
+threshold: number | undefined
+tooth: number | undefined
+tracking: number | undefined
+transform: ImageTransform | undefined
+turn: number | undefined
+vanish: readonly (readonly number[])[] | undefined
+vertical: boolean | undefined
+visible: boolean | undefined
+weight: string | number | undefined
+within: readonly number[] | undefined
+y: number | undefined
+yaw: number | undefined
+```
+
+## ImageMaterial — interface @experimental
+```
+height: readonly ImageLayer[] | undefined
+metal: number | readonly ImageLayer[] | undefined
+relief: number | undefined
+roughness: number | readonly ImageLayer[] | undefined
+```
+
+## ImageSource — interface @experimental
+```
+background: string | undefined
+layers: readonly ImageLayer[]
+material: ImageMaterial | undefined
+size: number | readonly [number, number]
+tile: boolean | undefined
+version: number | undefined
+```
+
+## ImageTextDrawer — type @experimental
+```
+(layer: ImageLayer, m: readonly number[], w: number, h: number) => { fill: Float32Array; line: Float32Array | null }
+```
+
+## MAX_IMAGE_SIZE — const @experimental
+```
+2048
+```
+
+## MaterialMaps — interface @experimental
+```
+height: RgbaBitmap
+metal: number
+normal: RgbaBitmap
+notes: string[]
+roughness: number
+surface: RgbaBitmap | null
+```
+
+## RenderedImage — interface @experimental
+```
+blocks: Record<string, Record<string, readonly (readonly number[])[]>>
+bounds: ImageBox | null
+covers: number
+figures: Record<string, Record<string, readonly [number, number]>>
+height: number
+layerBounds: Record<string, ImageBox>
+notes: string[]
+painted: Record<string, { entries: number; strokes: number; }>
+rgba: Uint8Array<ArrayBufferLike>
+width: number
+```
+
+## RgbaBitmap — interface @experimental
+```
+height: number
+rgba: Uint8Array<ArrayBufferLike>
+width: number
+```
+
+## renderImage — function @experimental
+```
+(source: ImageSource, options?: { guides?: boolean; pictures?: Readonly<Record<string, RgbaBitmap>>; text?: ImageTextDrawer; figure?: ImageFigureDrawer; }): RenderedImage
+```
+
+## renderMaterialMaps — function @experimental
+```
+(source: ImageSource, color: RgbaBitmap, options?: DrawOptions): MaterialMaps
+```
+
+## validateImageSource — function @experimental
+```
+(raw: unknown): ImageSource
+```
+
diff --git a/sdk/package.json b/sdk/package.json
index cf71d0c98..684b444ff 100644
--- a/sdk/package.json
+++ b/sdk/package.json
@@ -27,6 +27,7 @@
"./dist/worldgen/index.js",
"./dist/water/index.js",
"./dist/spline/index.js",
+ "./dist/image/index.js",
"./dist/voxel/index.js",
"./dist/rig2d/index.js",
"./dist/imported-scene/index.js",
@@ -128,6 +129,10 @@
"import": "./dist/spline/index.js",
"types": "./dist/spline/index.d.ts"
},
+ "./image": {
+ "import": "./dist/image/index.js",
+ "types": "./dist/image/index.d.ts"
+ },
"./voxel": {
"import": "./dist/voxel/index.js",
"types": "./dist/voxel/index.d.ts"
diff --git a/sdk/rolldown.config.js b/sdk/rolldown.config.js
index c50a4dd5d..d38ec2917 100644
--- a/sdk/rolldown.config.js
+++ b/sdk/rolldown.config.js
@@ -113,6 +113,7 @@ export default defineConfig([
'worldgen/index': 'src/worldgen/entry.ts',
'water/index': 'src/water/index.ts',
'spline/index': 'src/spline/index.ts',
+ 'image/index': 'src/image/index.ts',
'voxel/index': 'src/voxel/index.ts',
'rig2d/index': 'src/rig2d/entry.ts',
'imported-scene/index': 'src/imported-scene/index.ts',
diff --git a/sdk/rollup.config.js b/sdk/rollup.config.js
index f67443d92..1aec791e8 100644
--- a/sdk/rollup.config.js
+++ b/sdk/rollup.config.js
@@ -35,6 +35,7 @@ export default [
'worldgen/index': 'src/worldgen/entry.ts',
'water/index': 'src/water/index.ts',
'spline/index': 'src/spline/index.ts',
+ 'image/index': 'src/image/index.ts',
'voxel/index': 'src/voxel/index.ts',
'rig2d/index': 'src/rig2d/entry.ts',
'imported-scene/index': 'src/imported-scene/index.ts',
diff --git a/sdk/src/asset/loaders/TextureLoader.ts b/sdk/src/asset/loaders/TextureLoader.ts
index ff27e7ea9..680fcc36a 100644
--- a/sdk/src/asset/loaders/TextureLoader.ts
+++ b/sdk/src/asset/loaders/TextureLoader.ts
@@ -20,6 +20,7 @@ import {
uploadBoundTextureImage, applyBoundTextureSampling, handOverNewTexture, findWebGL2Context,
} from '../glTextureUpload';
import { createTextureFromPixels, type TextureParams } from '../../runtime/runtimeAssets';
+import { isTextureRecipePath, renderTextureRecipe } from '../textureRecipe';
/**
* Decode a texture ref to raw RGBA pixels on the current platform. Set by a
@@ -303,6 +304,12 @@ export class TextureLoader implements AssetLoader<TextureResult> {
copy: boolean,
): Promise<TextureResult> {
this.lastDecision_ = RAW_PAYLOAD_UPLOAD;
+ // A recipe is drawn here, from its source, and is then a texture like any decoded one.
+ if (isTextureRecipePath(buildPath)) {
+ const drawn = await renderTextureRecipe(await ctx.backend.fetchText(buildPath), path);
+ const handle = createTextureFromPixels(this.module_, drawn, TextureContent.Asset, flip, pixelParams(settings));
+ return { handle, width: drawn.width, height: drawn.height };
+ }
if (isKtx2Path(buildPath)) {
const buf = await ctx.backend.fetchBinary(buildPath);
return this.uploadKtx2_(path, new Uint8Array(buf), settings, maxEdge);
diff --git a/sdk/src/asset/textureRecipe.ts b/sdk/src/asset/textureRecipe.ts
new file mode 100644
index 000000000..e0cf6c648
--- /dev/null
+++ b/sdk/src/asset/textureRecipe.ts
@@ -0,0 +1,40 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
+/**
+ * @file textureRecipe.ts
+ * @brief A texture that is a recipe: a picture's source (an `.esimage`) shipped in place of its pixels and drawn where it is loaded.
+ *
+ * @details A package that ships a picture ships every pixel of it; one that ships how the picture is drawn ships a few hundred bytes
+ * and pays for the drawing once, on the device. The texture loader asks here for any path that is a recipe. What draws
+ * one is not in the core: importing `esengine/image` installs it, so a game with no recipe does not carry the raster.
+ */
+
+/** The pixels a recipe draws: top row first, RGBA, as a decoded image is. */
+export interface RecipePixels { width: number; height: number; pixels: Uint8Array }
+
+/** Draws a recipe from its source text. */
+export type TextureRecipeRenderer = (source: string, path: string) => RecipePixels | Promise<RecipePixels>;
+
+const RECIPE_EXTENSION = '.esimage';
+let renderer: TextureRecipeRenderer | null = null;
+
+/** Whether a texture's path names a recipe and not an image. */
+export function isTextureRecipePath(path: string): boolean {
+ const end = path.indexOf('?');
+ return (end < 0 ? path : path.slice(0, end)).toLowerCase().endsWith(RECIPE_EXTENSION);
+}
+
+/** Installs what draws recipes (null takes it out again). `esengine/image` does this on import. */
+export function setTextureRecipeRenderer(next: TextureRecipeRenderer | null): void {
+ renderer = next;
+}
+
+export function hasTextureRecipeRenderer(): boolean {
+ return renderer !== null;
+}
+
+/** The pixels of the recipe at `path`, whose source is `source`. */
+export async function renderTextureRecipe(source: string, path: string): Promise<RecipePixels> {
+ if (!renderer) throw new Error(`texture "${path}" is a recipe, and nothing here draws recipes: import 'esengine/image' where the game starts`);
+ return renderer(source, path);
+}
diff --git a/sdk/src/assetTypes.ts b/sdk/src/assetTypes.ts
index 223fccd3d..3e5072611 100644
--- a/sdk/src/assetTypes.ts
+++ b/sdk/src/assetTypes.ts
@@ -37,6 +37,8 @@ const ASSET_TYPE_REGISTRY: readonly AssetTypeEntry[] = [
// wechatPackInclude: WeChat's fs denies package reads of unlisted custom
// extensions — KTX2 textures are fs-read (transcoded), not image-decoded.
{ extensions: ['ktx2'], contentType: 'binary', editorType: 'texture', addressableType: 'texture', wechatPackInclude: true, hasTransitiveDeps: false },
+ // A picture's source, drawn into a texture where it is loaded (asset/textureRecipe.ts).
+ { extensions: ['esimage'], contentType: 'json', editorType: 'texture', addressableType: 'texture', wechatPackInclude: true, hasTransitiveDeps: false },
{ extensions: ['mp3', 'wav', 'ogg', 'aac', 'flac', 'm4a', 'webm'], contentType: 'audio', editorType: 'audio', addressableType: 'audio', wechatPackInclude: false, hasTransitiveDeps: false },
// Video container, streamed + decoded by the video system (HTMLVideoElement
// on web). `webm` stays with audio above to avoid the ambiguity; a .webm
diff --git a/sdk/src/image/imageAdjust.ts b/sdk/src/image/imageAdjust.ts
new file mode 100644
index 000000000..210e12de6
--- /dev/null
+++ b/sdk/src/image/imageAdjust.ts
@@ -0,0 +1,518 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
+/**
+ * @file imageAdjust.ts
+ * @brief What a photo editor offers over a picture so far: adjustments of its colour, and filters over its pixels.
+ *
+ * Each is one operation with numbers to turn, and the layer it sits on says where it applies and how much. Which to use, and how far, is the model's.
+ * Pixels here are stored as the canvas stores them, colour already times alpha.
+ */
+import { blurMask, fractalNoise, parseColor } from './imageNoise';
+import type { ImageAdjust, ImageFilterName } from './imageSource';
+
+const clamp01 = (v: number): number => Math.max(0, Math.min(1, v));
+const smooth = (t: number): number => t * t * (3 - 2 * t);
+export const lightnessOf = (r: number, g: number, b: number): number => r * 0.2126 + g * 0.7152 + b * 0.0722;
+
+// ---- Colour ----------------------------------------------------------------------
+
+function rgbToHsl(r: number, g: number, b: number): [number, number, number] {
+ const [hi, lo] = [Math.max(r, g, b), Math.min(r, g, b)];
+ const l = (hi + lo) / 2;
+ if (hi === lo) return [0, 0, l];
+ const d = hi - lo;
+ const s = l > 0.5 ? d / (2 - hi - lo) : d / (hi + lo);
+ const h = hi === r ? (g - b) / d + (g < b ? 6 : 0) : hi === g ? (b - r) / d + 2 : (r - g) / d + 4;
+ return [h / 6, s, l];
+}
+
+function hslToRgb(h: number, s: number, l: number): [number, number, number] {
+ if (s === 0) return [l, l, l];
+ const q = l < 0.5 ? l * (1 + s) : l + s - l * s;
+ const p = 2 * l - q;
+ const channel = (t0: number): number => {
+ const t = t0 < 0 ? t0 + 1 : t0 > 1 ? t0 - 1 : t0;
+ if (t < 1 / 6) return p + (q - p) * 6 * t;
+ if (t < 1 / 2) return q;
+ if (t < 2 / 3) return p + (q - p) * (2 / 3 - t) * 6;
+ return p;
+ };
+ return [channel(h + 1 / 3), channel(h), channel(h - 1 / 3)];
+}
+
+/** Through its points without overshooting them, as a curves dialog draws it: a table for 0..1. */
+function curveTable(points: readonly (readonly number[])[]): Float32Array {
+ const sorted = [...points].sort((a, b) => a[0]! - b[0]!);
+ const xs = sorted.map((p) => p[0]!), ys = sorted.map((p) => p[1]!);
+ const n = xs.length;
+ const slopes = xs.slice(0, -1).map((x, i) => (ys[i + 1]! - ys[i]!) / Math.max(1e-6, xs[i + 1]! - x));
+ const tangents = xs.map((_, i) => {
+ if (i === 0) return slopes[0] ?? 0;
+ if (i === n - 1) return slopes[n - 2] ?? 0;
+ return slopes[i - 1]! * slopes[i]! <= 0 ? 0 : (slopes[i - 1]! + slopes[i]!) / 2;
+ });
+ const table = new Float32Array(1024);
+ for (let k = 0; k < table.length; k++) {
+ const x = k / (table.length - 1);
+ if (x <= xs[0]!) { table[k] = ys[0]!; continue; }
+ if (x >= xs[n - 1]!) { table[k] = ys[n - 1]!; continue; }
+ let i = 0;
+ while (x > xs[i + 1]!) i++;
+ const h = xs[i + 1]! - xs[i]!;
+ const t = (x - xs[i]!) / h;
+ const [t2, t3] = [t * t, t * t * t];
+ table[k] = clamp01((2 * t3 - 3 * t2 + 1) * ys[i]! + (t3 - 2 * t2 + t) * h * tangents[i]! + (3 * t2 - 2 * t3) * ys[i + 1]! + (t3 - t2) * h * tangents[i + 1]!);
+ }
+ return table;
+}
+const look = (table: Float32Array, v: number): number => table[Math.round(clamp01(v) * (table.length - 1))]!;
+
+/** Colour along stops, for a gradient map. */
+function stopsTable(stops: readonly (readonly [number, string])[]): Float32Array {
+ const sorted = [...stops].sort((a, b) => a[0] - b[0]).map(([t, c]) => [t, parseColor(c)] as const);
+ const out = new Float32Array(256 * 3);
+ for (let k = 0; k < 256; k++) {
+ const v = k / 255;
+ let i = 0;
+ while (i + 2 < sorted.length && v > sorted[i + 1]![0]) i++;
+ const [a, b] = [sorted[i]!, sorted[Math.min(sorted.length - 1, i + 1)]!];
+ const t = clamp01((v - a[0]) / Math.max(1e-6, b[0] - a[0]));
+ for (let n = 0; n < 3; n++) out[k * 3 + n] = a[1][n]! + (b[1][n]! - a[1][n]!) * t;
+ }
+ return out;
+}
+
+/** The picture with its colour changed, in the order a stack of adjustment layers would most often take. */
+export function applyAdjust(px: Float32Array, w: number, h: number, a: ImageAdjust): Float32Array {
+ const out = new Float32Array(px.length);
+ const levels = a.levels;
+ const [inLow, inHigh] = levels?.input ?? [0, 1];
+ const [outLow, outHigh] = levels?.output ?? [0, 1];
+ const gamma = levels?.gamma ?? 1;
+ const curves = a.curves ? (Array.isArray(a.curves) ? { all: curveTable(a.curves as readonly (readonly number[])[]) } : Object.fromEntries(Object.entries(a.curves).map(([k, v]) => [k, curveTable(v as readonly (readonly number[])[])]))) as Record<string, Float32Array> : null;
+ const exposure = a.exposure !== undefined ? 2 ** a.exposure : 1;
+ const [brightness, contrast] = [a.brightness ?? 0, a.contrast ?? 0];
+ const contrastGain = contrast >= 0 ? 1 / Math.max(0.01, 1 - contrast * 0.98) : 1 + contrast;
+ const [warm, tint] = [a.temperature ?? 0, a.tint ?? 0];
+ const [hue, saturation, lightness] = [(a.hue ?? 0) / 360, a.saturation ?? 0, a.lightness ?? 0];
+ const vibrance = a.vibrance ?? 0;
+ const map = a.gradientMap ? stopsTable(a.gradientMap) : null;
+ const levelsStep = a.posterize !== undefined ? Math.max(2, Math.round(a.posterize)) : 0;
+ const balance = a.balance;
+ for (let i = 0; i < w * h; i++) {
+ const at = i * 4, alpha = px[at + 3]!;
+ if (alpha <= 0) continue;
+ let [r, g, b] = [px[at]! / alpha, px[at + 1]! / alpha, px[at + 2]! / alpha];
+ if (exposure !== 1) { r *= exposure; g *= exposure; b *= exposure; }
+ if (levels) {
+ const f = (v: number): number => outLow + (outHigh - outLow) * clamp01((v - inLow) / Math.max(1e-6, inHigh - inLow)) ** (1 / gamma);
+ r = f(r); g = f(g); b = f(b);
+ }
+ if (curves) {
+ if (curves.all) { r = look(curves.all, r); g = look(curves.all, g); b = look(curves.all, b); }
+ if (curves.r) r = look(curves.r, r);
+ if (curves.g) g = look(curves.g, g);
+ if (curves.b) b = look(curves.b, b);
+ }
+ if (brightness || contrast) {
+ const f = (v: number): number => (v + brightness - 0.5) * contrastGain + 0.5;
+ r = f(r); g = f(g); b = f(b);
+ }
+ if (warm || tint) { r += warm * 0.2 + tint * 0.1; g -= tint * 0.2; b += -warm * 0.2 + tint * 0.1; }
+ if (balance) {
+ const l = clamp01(lightnessOf(r, g, b));
+ const [dark, mid, bright] = [smooth(clamp01(1 - l * 2.5)), 1 - Math.abs(l - 0.5) * 2, smooth(clamp01((l - 0.6) * 2.5))];
+ for (const [weight, shift] of [[dark, balance.shadows], [mid, balance.midtones], [bright, balance.highlights]] as const) {
+ if (!shift) continue;
+ r += shift[0]! * weight * 0.5; g += shift[1]! * weight * 0.5; b += shift[2]! * weight * 0.5;
+ }
+ }
+ if (hue || saturation || lightness) {
+ const [hh, ss, ll] = rgbToHsl(clamp01(r), clamp01(g), clamp01(b));
+ const s2 = saturation >= 0 ? ss + (1 - ss) * saturation * (ss > 0 ? 1 : 0) : ss * (1 + saturation);
+ const l2 = lightness >= 0 ? ll + (1 - ll) * lightness : ll * (1 + lightness);
+ [r, g, b] = hslToRgb((hh + hue + 1) % 1, clamp01(s2), clamp01(l2));
+ }
+ if (vibrance) {
+ // More for what is dull than for what is already vivid, so skin and neon are not pushed over.
+ const [hi, lo] = [Math.max(r, g, b), Math.min(r, g, b)];
+ const amount = vibrance * (1 - clamp01(hi - lo));
+ const l = lightnessOf(r, g, b);
+ r = l + (r - l) * (1 + amount); g = l + (g - l) * (1 + amount); b = l + (b - l) * (1 + amount);
+ }
+ if (a.blackWhite) {
+ const [cr, cg, cb] = Array.isArray(a.blackWhite) ? a.blackWhite as readonly number[] : [0.2126, 0.7152, 0.0722];
+ r = g = b = r * cr! + g * cg! + b * cb!;
+ }
+ if (map) {
+ const k = Math.round(clamp01(lightnessOf(r, g, b)) * 255) * 3;
+ [r, g, b] = [map[k]!, map[k + 1]!, map[k + 2]!];
+ }
+ if (a.invert) { r = 1 - r; g = 1 - g; b = 1 - b; }
+ if (levelsStep) {
+ const f = (v: number): number => Math.round(clamp01(v) * (levelsStep - 1)) / (levelsStep - 1);
+ r = f(r); g = f(g); b = f(b);
+ }
+ if (a.threshold !== undefined) r = g = b = lightnessOf(r, g, b) >= a.threshold ? 1 : 0;
+ out[at] = clamp01(r) * alpha; out[at + 1] = clamp01(g) * alpha; out[at + 2] = clamp01(b) * alpha; out[at + 3] = alpha;
+ }
+ return out;
+}
+
+// ---- Filters ---------------------------------------------------------------------
+
+const bilinear = (px: Float32Array, w: number, h: number, x: number, y: number, out: Float32Array, to: number): void => {
+ const [fx, fy] = [Math.max(0, Math.min(w - 1.001, x - 0.5)), Math.max(0, Math.min(h - 1.001, y - 0.5))];
+ const [ix, iy] = [Math.floor(fx), Math.floor(fy)];
+ const [tx, ty] = [fx - ix, fy - iy];
+ const [a, b, c, d] = [(iy * w + ix) * 4, (iy * w + ix + 1) * 4, ((iy + 1) * w + ix) * 4, ((iy + 1) * w + ix + 1) * 4];
+ for (let n = 0; n < 4; n++) {
+ out[to + n] = (px[a + n]! * (1 - tx) + px[b + n]! * tx) * (1 - ty) + (px[c + n]! * (1 - tx) + px[d + n]! * tx) * ty;
+ }
+};
+
+const blurAll = (px: Float32Array, w: number, h: number, sigma: number): Float32Array => {
+ const out = new Float32Array(px.length);
+ for (let n = 0; n < 4; n++) {
+ const channel = new Float32Array(w * h);
+ for (let i = 0; i < channel.length; i++) channel[i] = px[i * 4 + n]!;
+ const soft = blurMask(channel, w, h, sigma);
+ for (let i = 0; i < channel.length; i++) out[i * 4 + n] = soft[i]!;
+ }
+ return out;
+};
+
+/** Every pixel from somewhere else in the picture. */
+function warped(px: Float32Array, w: number, h: number, from: (x: number, y: number) => readonly [number, number]): Float32Array {
+ const out = new Float32Array(px.length);
+ for (let y = 0; y < h; y++) {
+ for (let x = 0; x < w; x++) {
+ const [sx, sy] = from(x + 0.5, y + 0.5);
+ bilinear(px, w, h, sx, sy, out, (y * w + x) * 4);
+ }
+ }
+ return out;
+}
+
+/** Every pixel the mean of several places, each given by how far along 0..1 it is. */
+function averaged(px: Float32Array, w: number, h: number, samples: number, from: (x: number, y: number, t: number) => readonly [number, number]): Float32Array {
+ const out = new Float32Array(px.length);
+ const one = new Float32Array(4);
+ for (let y = 0; y < h; y++) {
+ for (let x = 0; x < w; x++) {
+ const to = (y * w + x) * 4;
+ for (let s = 0; s < samples; s++) {
+ const [sx, sy] = from(x + 0.5, y + 0.5, samples === 1 ? 0 : s / (samples - 1));
+ bilinear(px, w, h, sx, sy, one, 0);
+ for (let n = 0; n < 4; n++) out[to + n]! += one[n]!;
+ }
+ for (let n = 0; n < 4; n++) out[to + n]! /= samples;
+ }
+ }
+ return out;
+}
+
+/** Light over a pixel without covering it: `add` 0..1 in each colour on top of what is there. */
+function screened(px: Float32Array, w: number, h: number, light: (x: number, y: number, into: Float32Array) => void): Float32Array {
+ const out = new Float32Array(px);
+ const add = new Float32Array(3);
+ for (let y = 0; y < h; y++) {
+ for (let x = 0; x < w; x++) {
+ add.fill(0);
+ light(x + 0.5, y + 0.5, add);
+ const at = (y * w + x) * 4;
+ let most = out[at + 3]!;
+ for (let n = 0; n < 3; n++) {
+ out[at + n] = out[at + n]! + (1 - out[at + n]!) * clamp01(add[n]!);
+ most = Math.max(most, out[at + n]!);
+ }
+ out[at + 3] = most;
+ }
+ }
+ return out;
+}
+
+type P = Readonly<Record<string, unknown>>;
+const num = (p: P, key: string, fallback: number): number => (p[key] as number | undefined) ?? fallback;
+const pointOf = (p: P, key: string, fallback: readonly [number, number]): readonly [number, number] => (p[key] as readonly [number, number] | undefined) ?? fallback;
+
+/** The picture with a filter over it: what it would be everywhere, which the layer then lays down where and as much as it says. @p k is the size of a pixel in the source's terms. */
+export function applyFilter(name: ImageFilterName, p: P, px: Float32Array, w: number, h: number, k: number): Float32Array {
+ const middle = [w / (2 * k), h / (2 * k)] as const;
+ const centre = (key = 'at'): readonly [number, number] => { const c = pointOf(p, key, middle); return [c[0] * k, c[1] * k]; };
+ switch (name) {
+ case 'gaussian':
+ return blurAll(px, w, h, num(p, 'radius', 4) * k);
+ case 'motion': {
+ const a = (num(p, 'angle', 0) * Math.PI) / 180, d = num(p, 'distance', 16) * k;
+ const [dx, dy] = [Math.cos(a) * d, Math.sin(a) * d];
+ return averaged(px, w, h, Math.max(2, Math.min(64, Math.ceil(d))), (x, y, t) => [x + dx * (t - 0.5), y + dy * (t - 0.5)]);
+ }
+ case 'spin': {
+ const [cx, cy] = centre();
+ const amount = (num(p, 'angle', 10) * Math.PI) / 180;
+ return averaged(px, w, h, 24, (x, y, t) => {
+ const r = amount * (t - 0.5);
+ const [dx, dy] = [x - cx, y - cy];
+ return [cx + dx * Math.cos(r) - dy * Math.sin(r), cy + dx * Math.sin(r) + dy * Math.cos(r)];
+ });
+ }
+ case 'zoom': {
+ const [cx, cy] = centre();
+ const amount = num(p, 'amount', 0.1);
+ return averaged(px, w, h, 24, (x, y, t) => { const s = 1 + amount * (t - 0.5); return [cx + (x - cx) * s, cy + (y - cy) * s]; });
+ }
+ case 'lens': {
+ // A disc and not a bell, so highlights open into the round lights of a real lens.
+ const radius = num(p, 'radius', 6) * k;
+ const bright = num(p, 'highlights', 1);
+ const rings = Math.max(2, Math.min(6, Math.ceil(radius / 2)));
+ const offsets: [number, number][] = [[0, 0]];
+ for (let ring = 1; ring <= rings; ring++) {
+ const count = ring * 7;
+ for (let s = 0; s < count; s++) {
+ const a = (s / count) * Math.PI * 2 + ring;
+ offsets.push([Math.cos(a) * (radius * ring) / rings, Math.sin(a) * (radius * ring) / rings]);
+ }
+ }
+ const out = new Float32Array(px.length);
+ const one = new Float32Array(4);
+ for (let y = 0; y < h; y++) {
+ for (let x = 0; x < w; x++) {
+ const to = (y * w + x) * 4;
+ let weight = 0;
+ for (const [ox, oy] of offsets) {
+ bilinear(px, w, h, x + 0.5 + ox, y + 0.5 + oy, one, 0);
+ const l = lightnessOf(one[0]!, one[1]!, one[2]!);
+ const q = 1 + bright * 2 * l * l * l * l;
+ for (let n = 0; n < 4; n++) out[to + n]! += one[n]! * q;
+ weight += q;
+ }
+ for (let n = 0; n < 4; n++) out[to + n]! /= weight;
+ }
+ }
+ return out;
+ }
+ case 'sharpen': {
+ const soft = blurAll(px, w, h, num(p, 'radius', 1.5) * k);
+ const [amount, threshold] = [num(p, 'amount', 0.8), num(p, 'threshold', 0)];
+ const out = new Float32Array(px);
+ for (let i = 0; i < w * h; i++) {
+ const at = i * 4, a = px[at + 3]!;
+ for (let n = 0; n < 3; n++) {
+ const diff = px[at + n]! - soft[at + n]!;
+ if (Math.abs(diff) >= threshold) out[at + n] = Math.max(0, Math.min(a, px[at + n]! + diff * amount));
+ }
+ }
+ return out;
+ }
+ case 'highPass': {
+ const soft = blurAll(px, w, h, num(p, 'radius', 6) * k);
+ const out = new Float32Array(px.length);
+ for (let i = 0; i < w * h; i++) {
+ const at = i * 4, a = px[at + 3]!;
+ out[at + 3] = a;
+ for (let n = 0; n < 3; n++) out[at + n] = clamp01(0.5 + px[at + n]! - soft[at + n]!) * a;
+ }
+ return out;
+ }
+ case 'noise': {
+ const [amount, scale, seed, mono] = [num(p, 'amount', 0.08), num(p, 'scale', 1) * k, num(p, 'seed', 1), p.mono !== false];
+ const out = new Float32Array(px);
+ for (let y = 0; y < h; y++) {
+ for (let x = 0; x < w; x++) {
+ const at = (y * w + x) * 4, a = px[at + 3]!;
+ for (let n = 0; n < 3; n++) {
+ const v = fractalNoise(x / scale, y / scale, 1, mono ? seed : seed + n * 13) - 0.5;
+ out[at + n] = Math.max(0, Math.min(a, px[at + n]! + v * amount * 2 * a));
+ }
+ }
+ }
+ return out;
+ }
+ case 'median': {
+ const r = Math.max(1, Math.min(6, Math.round(num(p, 'radius', 1) * k)));
+ const out = new Float32Array(px.length);
+ const lights: [number, number][] = [];
+ for (let y = 0; y < h; y++) {
+ for (let x = 0; x < w; x++) {
+ lights.length = 0;
+ for (let dy = -r; dy <= r; dy++) {
+ for (let dx = -r; dx <= r; dx++) {
+ const at = (Math.max(0, Math.min(h - 1, y + dy)) * w + Math.max(0, Math.min(w - 1, x + dx))) * 4;
+ lights.push([lightnessOf(px[at]!, px[at + 1]!, px[at + 2]!), at]);
+ }
+ }
+ lights.sort((a, b) => a[0] - b[0]);
+ const from = lights[lights.length >> 1]![1], to = (y * w + x) * 4;
+ for (let n = 0; n < 4; n++) out[to + n] = px[from + n]!;
+ }
+ }
+ return out;
+ }
+ case 'emboss': {
+ const a = (num(p, 'angle', 135) * Math.PI) / 180, d = num(p, 'height', 2) * k, amount = num(p, 'amount', 2);
+ const [dx, dy] = [Math.round(Math.cos(a) * d), Math.round(Math.sin(a) * d)];
+ const out = new Float32Array(px.length);
+ for (let y = 0; y < h; y++) {
+ for (let x = 0; x < w; x++) {
+ const at = (y * w + x) * 4;
+ const there = (Math.max(0, Math.min(h - 1, y + dy)) * w + Math.max(0, Math.min(w - 1, x + dx))) * 4;
+ const diff = lightnessOf(px[at]!, px[at + 1]!, px[at + 2]!) - lightnessOf(px[there]!, px[there + 1]!, px[there + 2]!);
+ const v = clamp01(0.5 + diff * amount);
+ const alpha = px[at + 3]!;
+ out[at] = out[at + 1] = out[at + 2] = v * alpha;
+ out[at + 3] = alpha;
+ }
+ }
+ return out;
+ }
+ case 'ripple': {
+ const [amount, size, seed] = [num(p, 'amount', 4) * k, num(p, 'size', 24) * k, num(p, 'seed', 1)];
+ return warped(px, w, h, (x, y) => [x + Math.sin((y / size) * Math.PI * 2 + seed) * amount, y + Math.sin((x / size) * Math.PI * 2 + seed * 1.7) * amount]);
+ }
+ case 'displace': {
+ const [amount, size, seed] = [num(p, 'amount', 8) * k, num(p, 'size', 40) * k, num(p, 'seed', 1)];
+ return warped(px, w, h, (x, y) => [x + (fractalNoise(x / size, y / size, 3, seed) - 0.5) * amount * 2, y + (fractalNoise(x / size, y / size, 3, seed + 7) - 0.5) * amount * 2]);
+ }
+ case 'twirl': {
+ const [cx, cy] = centre();
+ const [radius, angle] = [num(p, 'radius', Math.min(w, h) / (2 * k)) * k, (num(p, 'angle', 45) * Math.PI) / 180];
+ return warped(px, w, h, (x, y) => {
+ const [dx, dy] = [x - cx, y - cy];
+ const d = Math.hypot(dx, dy);
+ if (d >= radius) return [x, y];
+ const a = angle * (1 - d / radius) ** 2;
+ return [cx + dx * Math.cos(a) - dy * Math.sin(a), cy + dx * Math.sin(a) + dy * Math.cos(a)];
+ });
+ }
+ case 'pixelate': {
+ const cell = Math.max(2, Math.round(num(p, 'cell', 8) * k));
+ const out = new Float32Array(px.length);
+ for (let gy = 0; gy < h; gy += cell) {
+ for (let gx = 0; gx < w; gx += cell) {
+ const sum = [0, 0, 0, 0];
+ let n = 0;
+ for (let y = gy; y < Math.min(h, gy + cell); y++) for (let x = gx; x < Math.min(w, gx + cell); x++) { const at = (y * w + x) * 4; for (let c = 0; c < 4; c++) sum[c]! += px[at + c]!; n++; }
+ for (let y = gy; y < Math.min(h, gy + cell); y++) for (let x = gx; x < Math.min(w, gx + cell); x++) { const at = (y * w + x) * 4; for (let c = 0; c < 4; c++) out[at + c] = sum[c]! / n; }
+ }
+ }
+ return out;
+ }
+ case 'chromatic': {
+ const [cx, cy] = centre();
+ const amount = num(p, 'amount', 2) * k / Math.max(w, h);
+ const out = new Float32Array(px);
+ const one = new Float32Array(4);
+ for (let y = 0; y < h; y++) {
+ for (let x = 0; x < w; x++) {
+ const at = (y * w + x) * 4;
+ const [dx, dy] = [x + 0.5 - cx, y + 0.5 - cy];
+ bilinear(px, w, h, cx + dx * (1 + amount), cy + dy * (1 + amount), one, 0);
+ out[at] = one[0]!;
+ bilinear(px, w, h, cx + dx * (1 - amount), cy + dy * (1 - amount), one, 0);
+ out[at + 2] = one[2]!;
+ }
+ }
+ return out;
+ }
+ case 'vignette': {
+ const [cx, cy] = centre();
+ const [amount, inner, outer] = [num(p, 'amount', 0.6), num(p, 'radius', 0.55), num(p, 'outer', 1.05)];
+ const col = parseColor((p.color as string | undefined) ?? '#000000');
+ const reach = Math.hypot(w, h) / 2;
+ const out = new Float32Array(px);
+ for (let y = 0; y < h; y++) {
+ for (let x = 0; x < w; x++) {
+ const at = (y * w + x) * 4;
+ const t = amount * smooth(clamp01((Math.hypot(x + 0.5 - cx, y + 0.5 - cy) / reach - inner) / Math.max(0.01, outer - inner)));
+ for (let n = 0; n < 3; n++) out[at + n] = px[at + n]! + (col[n]! * px[at + 3]! - px[at + n]!) * t;
+ }
+ }
+ return out;
+ }
+ case 'fog': {
+ // Thick at `to`, clear at `from`, in drifting patches: air between things, over and not behind them.
+ const col = parseColor((p.color as string | undefined) ?? '#c8d0e0');
+ const [fx, fy] = [pointOf(p, 'from', [0, 0])[0] * k, pointOf(p, 'from', [0, 0])[1] * k];
+ const [tx, ty] = [pointOf(p, 'to', [0, h / k])[0] * k, pointOf(p, 'to', [0, h / k])[1] * k];
+ const [dx, dy] = [tx - fx, ty - fy];
+ const len = dx * dx + dy * dy || 1;
+ const [density, patch, size, seed] = [num(p, 'density', 0.6), num(p, 'patchiness', 0.5), num(p, 'size', 120) * k, num(p, 'seed', 1)];
+ const out = new Float32Array(px);
+ for (let y = 0; y < h; y++) {
+ for (let x = 0; x < w; x++) {
+ const at = (y * w + x) * 4;
+ const along = clamp01(((x + 0.5 - fx) * dx + (y + 0.5 - fy) * dy) / len);
+ const cloud = patch > 0 ? 1 - patch + patch * 2 * fractalNoise(x / (size * 2), y / size, 4, seed) : 1;
+ const t = clamp01(smooth(along) * density * cloud) * col[3];
+ for (let n = 0; n < 3; n++) out[at + n] = px[at + n]! * (1 - t) + col[n]! * t;
+ out[at + 3] = px[at + 3]! * (1 - t) + t;
+ }
+ }
+ return out;
+ }
+ case 'rays': {
+ // What is bright, drawn out from a point: light through air, in the colour of what shines.
+ const [cx, cy] = centre();
+ const [threshold, length, strength, decay] = [num(p, 'threshold', 0.6), num(p, 'length', 0.6), num(p, 'strength', 0.8), num(p, 'decay', 0.96)];
+ const bright = new Float32Array(px.length);
+ for (let i = 0; i < w * h; i++) {
+ const at = i * 4;
+ const over = clamp01((Math.max(px[at]!, px[at + 1]!, px[at + 2]!) - threshold) / Math.max(0.01, 1 - threshold));
+ for (let n = 0; n < 3; n++) bright[at + n] = px[at + n]! * over;
+ bright[at + 3] = 1;
+ }
+ const STEPS = 48;
+ const one = new Float32Array(4);
+ return screened(px, w, h, (x, y, into) => {
+ let weight = 1;
+ for (let s = 0; s < STEPS; s++) {
+ const t = 1 - (s / STEPS) * length;
+ bilinear(bright, w, h, cx + (x - cx) * t, cy + (y - cy) * t, one, 0);
+ for (let n = 0; n < 3; n++) into[n]! += one[n]! * weight * strength / STEPS;
+ weight *= decay;
+ }
+ });
+ }
+ case 'flare': {
+ const [cx, cy] = centre();
+ const col = parseColor((p.color as string | undefined) ?? '#ffe0b0');
+ const [size, strength] = [num(p, 'size', 60) * k, num(p, 'strength', 1)];
+ const [mx, my] = [w / 2, h / 2];
+ const ghosts = [[-0.4, 0.22, 0.14], [-0.8, 0.12, 0.2], [-1.3, 0.34, 0.09], [-1.7, 0.17, 0.13]] as const;
+ return screened(px, w, h, (x, y, into) => {
+ const d = Math.hypot(x - cx, y - cy);
+ let v = 0.9 * Math.exp(-((d / size) ** 2)) + 0.25 * Math.exp(-d / (size * 2.5));
+ // A streak along the sensor, and ghosts in a line through the middle of the frame.
+ v += 0.5 * Math.exp(-Math.abs(y - cy) / (size * 0.05)) * Math.exp(-Math.abs(x - cx) / (size * 3.5));
+ for (const [t, r, a] of ghosts) {
+ const [gx, gy] = [cx + (mx - cx) * (1 - t), cy + (my - cy) * (1 - t)];
+ const gd = Math.hypot(x - gx, y - gy) / (size * r * 2.2);
+ if (gd < 1) v += a * (1 - gd * gd * gd * gd);
+ }
+ for (let n = 0; n < 3; n++) into[n]! += col[n]! * v * strength;
+ });
+ }
+ case 'texture': {
+ // A relief lit from one side and not a stain: canvas, paper, plaster.
+ const [scale, amount, seed] = [num(p, 'scale', 3) * k, num(p, 'amount', 0.3), num(p, 'seed', 1)];
+ const a = (num(p, 'angle', 135) * Math.PI) / 180;
+ const [lx, ly] = [Math.cos(a), Math.sin(a)];
+ const out = new Float32Array(px);
+ for (let y = 0; y < h; y++) {
+ for (let x = 0; x < w; x++) {
+ const at = (y * w + x) * 4;
+ const v = fractalNoise(x / scale, y / scale, 3, seed);
+ const slope = v - fractalNoise((x + lx) / scale, (y + ly) / scale, 3, seed);
+ const shade = 1 + slope * amount * 3;
+ const alpha = px[at + 3]!;
+ for (let n = 0; n < 3; n++) out[at + n] = Math.max(0, Math.min(alpha, px[at + n]! * shade));
+ }
+ }
+ return out;
+ }
+ default:
+ throw new Error(`no filter "${String(name)}"`);
+ }
+}
diff --git a/sdk/src/image/imageMaterial.ts b/sdk/src/image/imageMaterial.ts
new file mode 100644
index 000000000..ab32cd54f
--- /dev/null
+++ b/sdk/src/image/imageMaterial.ts
@@ -0,0 +1,221 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
+/**
+ * @file imageMaterial.ts — a picture as a surface: the maps a lit material reads beside its colour.
+ *
+ * A wall is not only its colour. Light catches the edges of its bricks and slides off its glaze, and a picture
+ * alone draws flat however well it is painted. So a source may say what its surface is as well as what it looks
+ * like: its relief, how rough it is, and where it is metal. Each is drawn with the same layers the colour is, as
+ * a grey picture of its own (light is high, light is rough, light is metal), and what a material needs is made
+ * from them: a normal map from the relief, and one map holding roughness and metal.
+ *
+ * With nothing drawn for the relief, the colour's own lightness stands in for it: dark is low. That is the
+ * cheap guess every texture tool makes, and it is right for mortar and wrong for a painted stripe, which is why
+ * a relief can be drawn instead.
+ */
+import { renderImage, type RenderedImage, type RgbaBitmap, type ImageFigureDrawer, type ImageTextDrawer } from './imageRaster';
+import type { ImageLayer, ImageMaterial, ImageSource } from './imageSource';
+
+export type { ImageMaterial } from './imageSource';
+
+export interface MaterialMaps {
+ /** Tangent space, +z out of the surface, as the engine's lit materials read it. */
+ normal: RgbaBitmap;
+ /** Roughness in green and metal in blue, glTF's layout; null when both are one value everywhere. */
+ surface: RgbaBitmap | null;
+ /** The one value, where it is one. */
+ roughness: number;
+ metal: number;
+ /** The grey pictures the maps were made from, for looking at. */
+ height: RgbaBitmap;
+ notes: string[];
+}
+
+type DrawOptions = { pictures?: Readonly<Record<string, RgbaBitmap>>; text?: ImageTextDrawer; figure?: ImageFigureDrawer };
+
+const lightness = (p: Uint8Array, i: number): number => (p[i * 4]! * 0.2126 + p[i * 4 + 1]! * 0.7152 + p[i * 4 + 2]! * 0.0722) / 255;
+
+/** The layers as a grey picture the size of the source, on black: what is not drawn is low, smooth, not metal. */
+function greyOf(source: ImageSource, layers: readonly ImageLayer[], options: DrawOptions): { values: Float32Array; picture: RenderedImage } {
+ const picture = renderImage({ size: source.size, background: '#000000', ...(source.tile ? { tile: true } : {}), layers }, options);
+ const values = new Float32Array(picture.width * picture.height);
+ for (let i = 0; i < values.length; i++) values[i] = lightness(picture.rgba, i);
+ return { values, picture };
+}
+
+/**
+ * A normal map from heights 0..1. The slope at a pixel is read across its neighbours (a Sobel), going round the edges of
+ * a picture that repeats and stopping at them otherwise. Green is up the picture, which is +v as the engine lays a
+ * texture, so a ridge lit from above is bright on its upper side.
+ */
+export function normalFromHeight(height: Float32Array, w: number, h: number, relief: number, wrap: boolean): RgbaBitmap {
+ const at = (x: number, y: number): number => {
+ const [cx, cy] = wrap ? [((x % w) + w) % w, ((y % h) + h) % h] : [Math.max(0, Math.min(w - 1, x)), Math.max(0, Math.min(h - 1, y))];
+ return height[cy * w + cx]!;
+ };
+ const rgba = new Uint8Array(w * h * 4);
+ for (let y = 0; y < h; y++) {
+ for (let x = 0; x < w; x++) {
+ const dx = ((at(x + 1, y - 1) + 2 * at(x + 1, y) + at(x + 1, y + 1)) - (at(x - 1, y - 1) + 2 * at(x - 1, y) + at(x - 1, y + 1))) / 8;
+ // Down the picture is down the surface: a height rising toward the top of the picture slopes toward +v.
+ const dy = ((at(x - 1, y - 1) + 2 * at(x, y - 1) + at(x + 1, y - 1)) - (at(x - 1, y + 1) + 2 * at(x, y + 1) + at(x + 1, y + 1))) / 8;
+ const [nx, ny] = [-dx * relief, -dy * relief];
+ const l = Math.hypot(nx, ny, 1);
+ const o = (y * w + x) * 4;
+ rgba[o] = Math.round((nx / l * 0.5 + 0.5) * 255);
+ rgba[o + 1] = Math.round((ny / l * 0.5 + 0.5) * 255);
+ rgba[o + 2] = Math.round((1 / l * 0.5 + 0.5) * 255);
+ rgba[o + 3] = 255;
+ }
+ }
+ return { width: w, height: h, rgba };
+}
+
+/**
+ * How much the join shows when a picture is laid beside itself, as a share of how much one row or column of it differs
+ * from the next anyway: about 1 is a picture that repeats, well above it is a seam.
+ */
+export function seamOf(image: RgbaBitmap): number {
+ const { width: w, height: h, rgba } = image;
+ if (w < 4 || h < 4) return 1;
+ const step = (a: number, b: number): number => {
+ let d = 0;
+ for (let k = 0; k < 4; k++) d += Math.abs(rgba[a * 4 + k]! - rgba[b * 4 + k]!);
+ return d;
+ };
+ let [across, inside, insideCount] = [0, 0, 0];
+ for (let y = 0; y < h; y++) across += step(y * w + w - 1, y * w);
+ for (let x = 0; x < w; x++) across += step((h - 1) * w + x, x);
+ for (let y = 0; y < h; y++) for (let x = 0; x + 1 < w; x += Math.max(1, Math.floor(w / 16))) { inside += step(y * w + x, y * w + x + 1); insideCount++; }
+ for (let x = 0; x < w; x++) for (let y = 0; y + 1 < h; y += Math.max(1, Math.floor(h / 16))) { inside += step(y * w + x, (y + 1) * w + x); insideCount++; }
+ const usual = inside / Math.max(1, insideCount);
+ const join = across / (w + h);
+ // A flat picture has no usual step to measure against: its join shows only if there is one at all.
+ return usual < 0.25 ? (join < 0.5 ? 1 : join / 0.25) : join / usual;
+}
+
+/** The maps a source's `material` asks for, drawn beside its colour @p color. */
+export function renderMaterialMaps(source: ImageSource, color: RgbaBitmap, options: DrawOptions = {}): MaterialMaps {
+ const material = source.material ?? {};
+ const [w, h] = [color.width, color.height];
+ const notes: string[] = [];
+ let height: Float32Array;
+ let heightPicture: RgbaBitmap;
+ if (material.height) {
+ const drawn = greyOf(source, material.height, options);
+ [height, heightPicture] = [drawn.values, drawn.picture];
+ notes.push(...drawn.picture.notes.map((n) => `height: ${n}`));
+ } else {
+ height = new Float32Array(w * h);
+ const rgba = new Uint8Array(w * h * 4);
+ for (let i = 0; i < w * h; i++) {
+ height[i] = lightness(color.rgba, i);
+ const v = Math.round(height[i]! * 255);
+ rgba.set([v, v, v, 255], i * 4);
+ }
+ heightPicture = { width: w, height: h, rgba };
+ }
+ let [low, high] = [1, 0];
+ for (const v of height) { if (v < low) low = v; if (v > high) high = v; }
+ if (high - low < 1 / 255) notes.push('the relief is flat: its height is one value everywhere, so the normal map says nothing');
+
+ const constant = (v: ImageMaterial['roughness'], fallback: number): number => (typeof v === 'number' ? v : fallback);
+ const drawnMap = (v: ImageMaterial['roughness'], name: string): Float32Array | null => {
+ if (!Array.isArray(v)) return null;
+ const drawn = greyOf(source, v, options);
+ notes.push(...drawn.picture.notes.map((n) => `${name}: ${n}`));
+ return drawn.values;
+ };
+ const [rough, metal] = [drawnMap(material.roughness, 'roughness'), drawnMap(material.metal, 'metal')];
+ let surface: RgbaBitmap | null = null;
+ if (rough || metal) {
+ const rgba = new Uint8Array(w * h * 4);
+ const [r0, m0] = [Math.round(constant(material.roughness, 0.8) * 255), Math.round(constant(material.metal, 0) * 255)];
+ for (let i = 0; i < w * h; i++) {
+ rgba[i * 4] = 255;
+ rgba[i * 4 + 1] = rough ? Math.round(rough[i]! * 255) : r0;
+ rgba[i * 4 + 2] = metal ? Math.round(metal[i]! * 255) : m0;
+ rgba[i * 4 + 3] = 255;
+ }
+ surface = { width: w, height: h, rgba };
+ }
+ return {
+ normal: normalFromHeight(height, w, h, material.relief ?? 4, source.tile === true),
+ surface,
+ roughness: constant(material.roughness, 0.8),
+ metal: constant(material.metal, 0),
+ height: heightPicture,
+ notes,
+ };
+}
+
+/** The `.esmaterial` that reads the maps, by the names they were saved under beside it. */
+export function imageMaterialDoc(maps: MaterialMaps, files: { normal: string; surface: string | null }, constants: { version: string | number; blendNone: number; cullBack: number }): Record<string, unknown> {
+ return {
+ version: constants.version,
+ type: 'material',
+ shader: 'builtin:model',
+ blendMode: constants.blendNone,
+ depthTest: true,
+ depthWrite: true,
+ cull: constants.cullBack,
+ properties: {
+ u_normalMap: files.normal,
+ // A map holds the values and the factors multiply it, so where there is a map they stand aside.
+ ...(files.surface
+ ? { u_metallicRoughnessMap: files.surface, u_roughness: 1, u_metallic: 1 }
+ : { u_roughness: maps.roughness, u_metallic: maps.metal }),
+ },
+ };
+}
+
+/** A picture laid beside itself, two by two: the joins run down and across its middle, where a seam shows if there is one. */
+export function laidTwice(image: RgbaBitmap): RgbaBitmap {
+ const { width: w, height: h, rgba } = image;
+ const out = new Uint8Array(w * 2 * h * 2 * 4);
+ for (let y = 0; y < h * 2; y++) {
+ for (let x = 0; x < w * 2; x++) {
+ const from = ((y % h) * w + (x % w)) * 4;
+ out.set(rgba.subarray(from, from + 4), (y * w * 2 + x) * 4);
+ }
+ }
+ return { width: w * 2, height: h * 2, rgba: out };
+}
+
+/**
+ * The surface under a low light from the upper left, as a flat wall of it would take one: what the relief and the
+ * roughness do, which neither the colour nor the normal map's own colours show. For looking at; the engine's own
+ * shading is what a scene gets.
+ */
+export function litPreview(color: RgbaBitmap, maps: MaterialMaps): RgbaBitmap {
+ const { width: w, height: h } = color;
+ const out = new Uint8Array(w * h * 4);
+ const light = [-0.55, 0.55, 0.63];
+ const half = (() => { const v = [light[0]!, light[1]!, light[2]! + 1]; const l = Math.hypot(...v); return v.map((c) => c / l); })();
+ const srgb = (v: number): number => Math.round(Math.pow(Math.max(0, Math.min(1, v)), 1 / 2.2) * 255);
+ for (let i = 0; i < w * h; i++) {
+ const n = [maps.normal.rgba[i * 4]! / 127.5 - 1, maps.normal.rgba[i * 4 + 1]! / 127.5 - 1, maps.normal.rgba[i * 4 + 2]! / 127.5 - 1];
+ const rough = maps.surface ? maps.surface.rgba[i * 4 + 1]! / 255 : maps.roughness;
+ const metal = maps.surface ? maps.surface.rgba[i * 4 + 2]! / 255 : maps.metal;
+ const diffuse = Math.max(0, n[0]! * light[0]! + n[1]! * light[1]! + n[2]! * light[2]!);
+ const shine = Math.pow(Math.max(0, n[0]! * half[0]! + n[1]! * half[1]! + n[2]! * half[2]!), 2 / Math.max(0.02, rough * rough) - 1) * (1 - rough) * 1.6;
+ for (let k = 0; k < 3; k++) {
+ const base = Math.pow(color.rgba[i * 4 + k]! / 255, 2.2);
+ out[i * 4 + k] = srgb(base * (1 - metal) * (0.18 + 0.95 * diffuse) + (0.04 + (base - 0.04) * metal) * (shine + metal * 0.25 * (0.3 + diffuse)));
+ }
+ out[i * 4 + 3] = 255;
+ }
+ return { width: w, height: h, rgba: out };
+}
+
+/** Two pictures side by side, the second scaled to the first's height. */
+export function sideBySide(a: RgbaBitmap, b: RgbaBitmap): RgbaBitmap {
+ const out = new Uint8Array((a.width + b.width + 8) * a.height * 4).fill(60);
+ for (let y = 0; y < a.height; y++) {
+ out.set(a.rgba.subarray(y * a.width * 4, (y + 1) * a.width * 4), y * (a.width + b.width + 8) * 4);
+ const by = Math.min(b.height - 1, Math.floor((y / a.height) * b.height));
+ out.set(b.rgba.subarray(by * b.width * 4, (by + 1) * b.width * 4), (y * (a.width + b.width + 8) + a.width + 8) * 4);
+ }
+ for (let i = 3; i < out.length; i += 4) out[i] = 255;
+ return { width: a.width + b.width + 8, height: a.height, rgba: out };
+}
diff --git a/sdk/src/image/imageNoise.ts b/sdk/src/image/imageNoise.ts
new file mode 100644
index 000000000..9374b83d4
--- /dev/null
+++ b/sdk/src/image/imageNoise.ts
@@ -0,0 +1,117 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
+export type Rgba = readonly [number, number, number, number];
+
+export function parseColor(text: string): Rgba {
+ const h = /^#([0-9a-fA-F]+)$/.exec(text)?.[1];
+ if (!h || ![3, 4, 6, 8].includes(h.length)) throw new Error(`color ${JSON.stringify(text)} must be #rgb, #rgba, #rrggbb or #rrggbbaa`);
+ const full = h.length <= 4 ? [...h].map((c) => c + c).join('') : h;
+ const at = (i: number): number => parseInt(full.slice(i, i + 2), 16) / 255;
+ return [at(0), at(2), at(4), full.length === 8 ? at(6) : 1];
+}
+
+/**
+ * Whether the picture being drawn repeats: what leaves one edge comes in at the opposite one. Set for the length of one
+ * draw (renderImage), and read by everything that looks past an edge, so a tile's blur, shadow and noise all go round.
+ */
+let wrapping = false;
+export const setWrapping = (on: boolean): void => { wrapping = on; };
+export const isWrapping = (): boolean => wrapping;
+
+function blurRound(src: Float32Array, w: number, h: number, sigma: number): Float32Array {
+ const r = Math.max(1, Math.round(sigma * 1.2));
+ let cur = src;
+ for (let pass = 0; pass < 3; pass++) {
+ const a = new Float32Array(w * h);
+ for (let y = 0; y < h; y++) {
+ let sum = 0;
+ for (let x = -r; x <= r; x++) sum += cur[y * w + (((x % w) + w) % w)]!;
+ for (let x = 0; x < w; x++) {
+ a[y * w + x] = sum / (2 * r + 1);
+ sum += cur[y * w + ((x + r + 1) % w)]! - cur[y * w + ((((x - r) % w) + w) % w)]!;
+ }
+ }
+ const b = new Float32Array(w * h);
+ for (let x = 0; x < w; x++) {
+ let sum = 0;
+ for (let y = -r; y <= r; y++) sum += a[(((y % h) + h) % h) * w + x]!;
+ for (let y = 0; y < h; y++) {
+ b[y * w + x] = sum / (2 * r + 1);
+ sum += a[((y + r + 1) % h) * w + x]! - a[((((y - r) % h) + h) % h) * w + x]!;
+ }
+ }
+ cur = b;
+ }
+ return cur;
+}
+
+export function blurMask(src: Float32Array, w: number, h: number, sigma: number): Float32Array {
+ if (sigma <= 0) return src;
+ if (wrapping) return blurRound(src, w, h, sigma);
+ const r = Math.max(1, Math.round(sigma * 1.2));
+ let cur = src;
+ for (let pass = 0; pass < 3; pass++) {
+ const a = new Float32Array(w * h);
+ for (let y = 0; y < h; y++) {
+ let sum = 0;
+ for (let x = -r; x <= r; x++) sum += cur[y * w + Math.max(0, Math.min(w - 1, x))]!;
+ for (let x = 0; x < w; x++) {
+ a[y * w + x] = sum / (2 * r + 1);
+ sum += cur[y * w + Math.min(w - 1, x + r + 1)]! - cur[y * w + Math.max(0, x - r)]!;
+ }
+ }
+ const b = new Float32Array(w * h);
+ for (let x = 0; x < w; x++) {
+ let sum = 0;
+ for (let y = -r; y <= r; y++) sum += a[Math.max(0, Math.min(h - 1, y)) * w + x]!;
+ for (let y = 0; y < h; y++) {
+ b[y * w + x] = sum / (2 * r + 1);
+ sum += a[Math.min(h - 1, y + r + 1) * w + x]! - a[Math.max(0, y - r) * w + x]!;
+ }
+ }
+ cur = b;
+ }
+ return cur;
+}
+
+export const NOISE_DIRECTIONS: readonly (readonly [number, number])[] = [
+ [1, 0], [0.9239, 0.3827], [0.7071, 0.7071], [0.3827, 0.9239], [0, 1], [-0.3827, 0.9239], [-0.7071, 0.7071], [-0.9239, 0.3827],
+ [-1, 0], [-0.9239, -0.3827], [-0.7071, -0.7071], [-0.3827, -0.9239], [0, -1], [0.3827, -0.9239], [0.7071, -0.7071], [0.9239, -0.3827],
+];
+
+export function cornerLift(ix: number, iy: number, seed: number, dx: number, dy: number): number {
+ let h = Math.imul(ix, 374761393) + Math.imul(iy, 668265263) + Math.imul(seed, 1442968193);
+ h = Math.imul(h ^ (h >>> 13), 1274126177);
+ h = Math.imul(h ^ (h >>> 16), 2246822519);
+ const d = NOISE_DIRECTIONS[((h ^ (h >>> 16)) >>> 0) % NOISE_DIRECTIONS.length]!;
+ return d[0] * dx + d[1] * dy;
+}
+
+export const fade = (t: number): number => t * t * t * (t * (t * 6 - 15) + 10);
+
+/** @p px, @p py: how many lattice cells before the noise repeats each way; 0 for never. */
+export function gradientNoise(x: number, y: number, seed: number, px = 0, py = 0): number {
+ const [ix, iy] = [Math.floor(x), Math.floor(y)];
+ const [fx, fy] = [x - ix, y - iy];
+ const [sx, sy] = [fade(fx), fade(fy)];
+ const wx = (i: number): number => (px > 0 ? ((i % px) + px) % px : i);
+ const wy = (i: number): number => (py > 0 ? ((i % py) + py) % py : i);
+ const top = cornerLift(wx(ix), wy(iy), seed, fx, fy) * (1 - sx) + cornerLift(wx(ix + 1), wy(iy), seed, fx - 1, fy) * sx;
+ const bottom = cornerLift(wx(ix), wy(iy + 1), seed, fx, fy - 1) * (1 - sx) + cornerLift(wx(ix + 1), wy(iy + 1), seed, fx - 1, fy - 1) * sx;
+ return top * (1 - sy) + bottom * sy;
+}
+
+export const NOISE_CONTRAST = [1.15, 1.3, 1.4, 1.45, 1.45, 1.45, 1.45, 1.45];
+
+/** @p px, @p py: cells of the first octave before the noise repeats; each finer octave repeats with it. 0 for never. */
+export function fractalNoise(x: number, y: number, octaves: number, seed: number, px = 0, py = 0): number {
+ let [sum, weight, amplitude, frequency] = [0, 0, 1, 1];
+ for (let i = 0; i < octaves; i++) {
+ // Off the lattice, where this noise is always nothing.
+ sum += gradientNoise(x * frequency + 0.37, y * frequency + 0.61, seed + i * 101, px * frequency, py * frequency) * amplitude;
+ weight += amplitude;
+ amplitude *= 0.5;
+ frequency *= 2;
+ }
+ return Math.max(0, Math.min(1, 0.5 + (sum / weight) * NOISE_CONTRAST[octaves - 1]!));
+}
diff --git a/sdk/src/image/imagePath.ts b/sdk/src/image/imagePath.ts
new file mode 100644
index 000000000..0750b54da
--- /dev/null
+++ b/sdk/src/image/imagePath.ts
@@ -0,0 +1,75 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
+export type Pt = readonly [number, number];
+
+export const CURVE_STEPS = 20;
+
+export function parsePath(d: string): { points: Pt[]; closed: boolean }[] {
+ const tokens = d.match(/[a-zA-Z]|-?(?:\d+\.?\d*|\.\d+)(?:[eE][-+]?\d+)?/g) ?? [];
+ const runs: { points: Pt[]; closed: boolean }[] = [];
+ let run: Pt[] | null = null;
+ let [x, y, sx, sy, lastCx, lastCy] = [0, 0, 0, 0, 0, 0];
+ let cmd = '', prev = '', i = 0;
+ const num = (): number => {
+ const t = tokens[i++];
+ if (t === undefined || /[a-zA-Z]/.test(t)) throw new Error(`path ${JSON.stringify(d.slice(0, 60))}: command ${cmd} is short of numbers`);
+ return Number(t);
+ };
+ const start = (): void => {
+ if (!run) { run = [[x, y]]; runs.push({ points: run, closed: false }); }
+ };
+ const curve = (f: (t: number) => Pt): void => {
+ start();
+ for (let s = 1; s <= CURVE_STEPS; s++) run!.push(f(s / CURVE_STEPS));
+ };
+ while (i < tokens.length) {
+ if (/[a-zA-Z]/.test(tokens[i]!)) cmd = tokens[i++]!;
+ else if (!cmd) throw new Error(`path ${JSON.stringify(d.slice(0, 60))} must start with a command`);
+ const rel = cmd === cmd.toLowerCase();
+ const [ox, oy] = rel ? [x, y] : [0, 0];
+ switch (cmd.toUpperCase()) {
+ case 'M':
+ x = ox + num(); y = oy + num(); sx = x; sy = y;
+ run = [[x, y]];
+ runs.push({ points: run, closed: false });
+ cmd = rel ? 'l' : 'L';
+ break;
+ case 'L': x = ox + num(); y = oy + num(); start(); run!.push([x, y]); break;
+ case 'H': x = ox + num(); start(); run!.push([x, y]); break;
+ case 'V': y = oy + num(); start(); run!.push([x, y]); break;
+ case 'C': case 'S': {
+ const smooth = cmd.toUpperCase() === 'S';
+ const [c1x, c1y] = smooth ? (prev === 'C' || prev === 'S' ? [2 * x - lastCx, 2 * y - lastCy] : [x, y]) : [ox + num(), oy + num()];
+ const [c2x, c2y, ex, ey] = [ox + num(), oy + num(), ox + num(), oy + num()];
+ const [x0, y0] = [x, y];
+ curve((t) => {
+ const u = 1 - t;
+ return [u * u * u * x0 + 3 * u * u * t * c1x + 3 * u * t * t * c2x + t * t * t * ex, u * u * u * y0 + 3 * u * u * t * c1y + 3 * u * t * t * c2y + t * t * t * ey];
+ });
+ [x, y, lastCx, lastCy] = [ex, ey, c2x, c2y];
+ break;
+ }
+ case 'Q': case 'T': {
+ const smooth = cmd.toUpperCase() === 'T';
+ const [cx, cy] = smooth ? (prev === 'Q' || prev === 'T' ? [2 * x - lastCx, 2 * y - lastCy] : [x, y]) : [ox + num(), oy + num()];
+ const [ex, ey] = [ox + num(), oy + num()];
+ const [x0, y0] = [x, y];
+ curve((t) => {
+ const u = 1 - t;
+ return [u * u * x0 + 2 * u * t * cx + t * t * ex, u * u * y0 + 2 * u * t * cy + t * t * ey];
+ });
+ [x, y, lastCx, lastCy] = [ex, ey, cx, cy];
+ break;
+ }
+ case 'Z':
+ if (runs.length) runs[runs.length - 1]!.closed = true;
+ x = sx; y = sy; run = null;
+ cmd = '';
+ break;
+ default:
+ throw new Error(`path command ${cmd} is not one this draws; there are M L H V C S Q T Z`);
+ }
+ prev = cmd.toUpperCase() === 'L' && prev === 'M' ? 'L' : cmd.toUpperCase();
+ }
+ return runs;
+}
diff --git a/sdk/src/image/imageRaster.ts b/sdk/src/image/imageRaster.ts
new file mode 100644
index 000000000..e9a2d1906
--- /dev/null
+++ b/sdk/src/image/imageRaster.ts
@@ -0,0 +1,2204 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
+/**
+ * @file imageRaster.ts — a picture from a list of layers, on the CPU.
+ *
+ * A model describes structure well and cannot write a hundred thousand colours. So it states shapes, fills and
+ * effects, and this owns everything that has to be exact: antialiased edges, gradients, soft shadows.
+ * On the CPU rather than through a canvas, so the same source makes the same bytes on any machine and a test can read them.
+ */
+import { applyAdjust, applyFilter, lightnessOf } from './imageAdjust';
+import { IMAGE_BRUSHES, isGuideLayer, MAX_MARK_STROKES } from './imageSource';
+import type { ImageFill, ImageLayer, ImageSource, ImageAlong, ImageBrushSettings, ImageEffect, ImageField, ImageMark, ImageStroke, ImageSweep, ImageTransform } from './imageSource';
+import { type Pt, parsePath } from './imagePath';
+import { type Rgba, blurMask, fractalNoise, gradientNoise, isWrapping, parseColor, setWrapping } from './imageNoise';
+
+export interface RgbaBitmap { width: number; height: number; rgba: Uint8Array }
+
+/** A `figure` layer flattened into the picture: what the drawer of figures hands the raster. */
+export interface FlatFigure {
+ /** Coverage of the whole body in picture pixels, then of each kind of block as it shows. */
+ mask: Float32Array;
+ parts: Record<string, Float32Array>;
+ /** Which way the surface faces at each pixel, x right, y up, z toward the viewer; zero off the body. */
+ normals: Float32Array;
+ /** Dark where one block passes in front of another. */
+ contour: Float32Array;
+ /** In the picture: where each joint landed, and the bones and the head's cross as lines. */
+ joints: Record<string, readonly [number, number]>;
+ lines: readonly (readonly (readonly [number, number])[])[];
+ light: readonly [number, number, number];
+}
+
+/**
+ * What draws a `figure` layer, handed to renderImage by whoever has a body to pose (the authoring pipeline). A game that evaluates a
+ * picture has none, and a picture with a figure in it is one to bake before it ships.
+ */
+export interface ImageFigureDrawer {
+ flatten(layer: ImageLayer, w: number, h: number, project: (p: readonly [number, number]) => readonly [number, number], scale: number): FlatFigure;
+}
+
+const unit3 = (v: readonly number[]): [number, number, number] => {
+ const len = Math.hypot(v[0]!, v[1]!, v[2]!) || 1;
+ return [v[0]! / len, v[1]! / len, v[2]! / len];
+};
+
+type Matrix = readonly [number, number, number, number, number, number];
+
+const IDENTITY: Matrix = [1, 0, 0, 1, 0, 0];
+const SUBSCANS = 8;
+/** The size of the picture being drawn, for what has to repeat with it (see setWrapping). */
+let tileWidth = 0, tileHeight = 0;
+
+const times = (a: Matrix, b: Matrix): Matrix => [
+ a[0] * b[0] + a[2] * b[1], a[1] * b[0] + a[3] * b[1],
+ a[0] * b[2] + a[2] * b[3], a[1] * b[2] + a[3] * b[3],
+ a[0] * b[4] + a[2] * b[5] + a[4], a[1] * b[4] + a[3] * b[5] + a[5],
+];
+const apply = (m: Matrix, [x, y]: Pt): Pt => [m[0] * x + m[2] * y + m[4], m[1] * x + m[3] * y + m[5]];
+function invert(m: Matrix): Matrix {
+ const det = m[0] * m[3] - m[1] * m[2] || 1e-12;
+ return [m[3] / det, -m[1] / det, -m[2] / det, m[0] / det, (m[2] * m[5] - m[3] * m[4]) / det, (m[1] * m[4] - m[0] * m[5]) / det];
+}
+
+function transformOf(t: ImageTransform | undefined, origin: Pt): Matrix {
+ if (!t) return IDENTITY;
+ const [ox, oy] = t.origin ?? origin;
+ const r = ((t.rotate ?? 0) * Math.PI) / 180;
+ const [sx, sy] = typeof t.scale === 'number' ? [t.scale, t.scale] : t.scale ?? [1, 1];
+ const [tx, ty] = t.translate ?? [0, 0];
+ let m: Matrix = [1, 0, 0, 1, tx + ox, ty + oy];
+ m = times(m, [Math.cos(r), Math.sin(r), -Math.sin(r), Math.cos(r), 0, 0]);
+ m = times(m, [sx, 0, 0, sy, 0, 0]);
+ return times(m, [1, 0, 0, 1, -ox, -oy]);
+}
+
+// ---- Outlines -------------------------------------------------------------------
+
+function ellipsePoints(cx: number, cy: number, rx: number, ry: number): Pt[] {
+ const n = Math.max(48, Math.ceil(Math.max(rx, ry) * 2));
+ return Array.from({ length: n }, (_, i): Pt => [cx + rx * Math.cos((i / n) * Math.PI * 2), cy + ry * Math.sin((i / n) * Math.PI * 2)]);
+}
+
+function roundedRect(x: number, y: number, w: number, h: number, radius: number | readonly number[]): Pt[] {
+ const rs = typeof radius === 'number' ? [radius, radius, radius, radius] : radius;
+ const limit = Math.min(w, h) / 2;
+ const [tl, tr, br, bl] = [0, 1, 2, 3].map((i) => Math.max(0, Math.min(limit, rs[i] ?? 0))) as [number, number, number, number];
+ const out: Pt[] = [];
+ const corner = (cx: number, cy: number, r: number, from: number): void => {
+ if (r <= 0) { out.push([cx, cy]); return; }
+ const n = Math.max(4, Math.ceil(r));
+ for (let i = 0; i <= n; i++) {
+ const a = from + (i / n) * (Math.PI / 2);
+ out.push([cx + r * Math.cos(a), cy + r * Math.sin(a)]);
+ }
+ };
+ corner(x + tl, y + tl, tl, Math.PI);
+ corner(x + w - tr, y + tr, tr, -Math.PI / 2);
+ corner(x + w - br, y + h - br, br, 0);
+ corner(x + bl, y + h - bl, bl, Math.PI / 2);
+ return out;
+}
+
+/** A layer's outlines in its own coordinates. */
+function outlinesOf(layer: ImageLayer): { runs: { points: Pt[]; closed: boolean }[]; middle: Pt } {
+ const closed = (points: Pt[]): { points: Pt[]; closed: boolean }[] => [{ points, closed: true }];
+ switch (layer.shape) {
+ case 'rect': {
+ const [x, y] = layer.at!, [w, h] = layer.size!;
+ return { runs: closed(roundedRect(x, y, w, h, layer.radius ?? 0)), middle: [x + w / 2, y + h / 2] };
+ }
+ case 'circle': {
+ const [cx, cy] = layer.at!;
+ return { runs: closed(ellipsePoints(cx, cy, layer.radius as number, layer.radius as number)), middle: [cx, cy] };
+ }
+ case 'ellipse': {
+ const [cx, cy] = layer.at!, [rx, ry] = layer.radii!;
+ return { runs: closed(ellipsePoints(cx, cy, rx, ry)), middle: [cx, cy] };
+ }
+ case 'ring': {
+ const [cx, cy] = layer.at!;
+ const inner = ellipsePoints(cx, cy, layer.inner!, layer.inner!).reverse();
+ return { runs: [...closed(ellipsePoints(cx, cy, layer.radius as number, layer.radius as number)), ...closed(inner)], middle: [cx, cy] };
+ }
+ case 'polygon': case 'line': {
+ const pts = layer.points as Pt[];
+ const c = pts.reduce<[number, number]>((s, p) => [s[0] + p[0] / pts.length, s[1] + p[1] / pts.length], [0, 0]);
+ return { runs: [{ points: pts, closed: layer.shape === 'polygon' }], middle: c };
+ }
+ case 'star': case 'gear': {
+ const [cx, cy] = layer.at!;
+ const n = layer.count!, outer = layer.radius as number, inner = layer.inner!;
+ const out: Pt[] = [];
+ const start = ((layer.turn ?? -90) * Math.PI) / 180;
+ if (layer.shape === 'star') {
+ for (let i = 0; i < n * 2; i++) {
+ const r = i % 2 === 0 ? outer : inner;
+ const a = start + (i / (n * 2)) * Math.PI * 2;
+ out.push([cx + r * Math.cos(a), cy + r * Math.sin(a)]);
+ }
+ } else {
+ // A tooth is flat on top, narrower than its root, with the same gap between.
+ const step = (Math.PI * 2) / n, tip = (layer.tooth ?? 0.3) * step, root = tip * 1.5;
+ for (let i = 0; i < n; i++) {
+ const a = start + i * step;
+ for (const [r, d] of [[inner, -root], [outer, -tip], [outer, tip], [inner, root]] as const) out.push([cx + r * Math.cos(a + d), cy + r * Math.sin(a + d)]);
+ }
+ }
+ return { runs: closed(out), middle: [cx, cy] };
+ }
+ case 'path': {
+ const runs = parsePath(layer.d!);
+ const all = runs.flatMap((r) => r.points);
+ if (all.length === 0) throw new Error('path draws nothing');
+ const c = all.reduce<[number, number]>((s, p) => [s[0] + p[0] / all.length, s[1] + p[1] / all.length], [0, 0]);
+ return { runs, middle: c };
+ }
+ default:
+ return { runs: [], middle: [0, 0] };
+ }
+}
+
+// ---- Masks ----------------------------------------------------------------------
+
+/** What each pixel has of a filled outline, non-zero: a span's ends count for what they cover, so an edge has no stairs. */
+/** The nine places a thing drawn in a repeating picture shows: where it is, and one picture away each way. */
+const ROUND: readonly Pt[] = [[0, 0], [-1, 0], [1, 0], [0, -1], [0, 1], [-1, -1], [1, -1], [-1, 1], [1, 1]];
+
+/** Whether points moved by (@p dx, @p dy), grown by @p reach, touch the picture at all. */
+function touches(points: Iterable<readonly number[]>, dx: number, dy: number, reach: number, w: number, h: number): boolean {
+ let [x0, y0, x1, y1] = [Infinity, Infinity, -Infinity, -Infinity];
+ for (const p of points) {
+ if (p[0]! < x0) x0 = p[0]!;
+ if (p[0]! > x1) x1 = p[0]!;
+ if (p[1]! < y0) y0 = p[1]!;
+ if (p[1]! > y1) y1 = p[1]!;
+ }
+ return x1 + dx + reach > 0 && x0 + dx - reach < w && y1 + dy + reach > 0 && y0 + dy - reach < h;
+}
+
+/** A mask drawn once, or in a repeating picture once for each place it shows, the most of them kept. */
+function goingRound(points: () => Iterable<readonly number[]>, reach: number, w: number, h: number, draw: (dx: number, dy: number) => Float32Array): Float32Array {
+ if (!isWrapping()) return draw(0, 0);
+ let out: Float32Array | null = null;
+ for (const [ox, oy] of ROUND) {
+ const [dx, dy] = [ox * w, oy * h];
+ if ((ox !== 0 || oy !== 0) && !touches(points(), dx, dy, reach, w, h)) continue;
+ const part = draw(dx, dy);
+ if (!out) { out = part; continue; }
+ for (let i = 0; i < out.length; i++) if (part[i]! > out[i]!) out[i] = part[i]!;
+ }
+ return out ?? new Float32Array(w * h);
+}
+
+function fillMask(runs: readonly (readonly Pt[])[], w: number, h: number): Float32Array {
+ return goingRound(() => runs.flat(), 1, w, h, (dx, dy) => fillMaskOnce(dx === 0 && dy === 0 ? runs : runs.map((run) => run.map(([x, y]) => [x + dx, y + dy] as Pt)), w, h));
+}
+
+function fillMaskOnce(runs: readonly (readonly Pt[])[], w: number, h: number): Float32Array {
+ const mask = new Float32Array(w * h);
+ const edges: { x0: number; y0: number; x1: number; y1: number; dir: number }[] = [];
+ let top = Infinity, bottom = -Infinity;
+ for (const run of runs) {
+ for (let i = 0; i < run.length; i++) {
+ const [a, b] = [run[i]!, run[(i + 1) % run.length]!];
+ if (a[1] === b[1]) continue;
+ const down = a[1] < b[1];
+ edges.push(down ? { x0: a[0], y0: a[1], x1: b[0], y1: b[1], dir: 1 } : { x0: b[0], y0: b[1], x1: a[0], y1: a[1], dir: -1 });
+ top = Math.min(top, a[1], b[1]); bottom = Math.max(bottom, a[1], b[1]);
+ }
+ }
+ if (edges.length === 0) return mask;
+ const share = 1 / SUBSCANS;
+ const from = Math.max(0, Math.floor(top)), to = Math.min(h - 1, Math.ceil(bottom));
+ const hits: { x: number; dir: number }[] = [];
+ for (let y = from; y <= to; y++) {
+ for (let s = 0; s < SUBSCANS; s++) {
+ const sy = y + (s + 0.5) * share;
+ hits.length = 0;
+ for (const e of edges) {
+ if (sy < e.y0 || sy >= e.y1) continue;
+ hits.push({ x: e.x0 + ((sy - e.y0) / (e.y1 - e.y0)) * (e.x1 - e.x0), dir: e.dir });
+ }
+ if (hits.length < 2) continue;
+ hits.sort((a, b) => a.x - b.x);
+ let winding = 0;
+ for (let i = 0; i + 1 < hits.length; i++) {
+ winding += hits[i]!.dir;
+ if (winding === 0) continue;
+ const [l, r] = [Math.max(0, hits[i]!.x), Math.min(w, hits[i + 1]!.x)];
+ if (r <= l) continue;
+ const [il, ir] = [Math.floor(l), Math.min(w - 1, Math.floor(r))];
+ const row = y * w;
+ if (il === ir) { mask[row + il]! += (r - l) * share; continue; }
+ mask[row + il]! += (il + 1 - l) * share;
+ for (let x = il + 1; x < ir; x++) mask[row + x]! += share;
+ mask[row + ir]! += (r - ir) * share;
+ }
+ }
+ }
+ for (let i = 0; i < mask.length; i++) if (mask[i]! > 1) mask[i] = 1;
+ return mask;
+}
+
+/** Past this a mitre is bevelled: a point of about 11 degrees still comes out sharp, and a thinner one does not throw a long spike. */
+const MITER_LIMIT = 10;
+const STROKE_SAMPLES = 6;
+
+/** What each pixel has of a stroke. Round joins and ends come from the distance to the line; the others are built of convex pieces, sampled where a pixel crosses an edge: a distance from the edges would trail a faint tail off a sharp point. */
+function strokeMask(runs: readonly { points: readonly Pt[]; closed: boolean }[], width: number, w: number, h: number, join: 'round' | 'miter' | 'bevel' = 'round', cap: 'round' | 'butt' | 'square' = 'round'): Float32Array {
+ // A mitre can reach a good way past its line, so the reach is generous: a copy drawn for nothing costs little.
+ return goingRound(() => runs.flatMap((r) => r.points), width * (join === 'miter' ? MITER_LIMIT : 1) + 2, w, h, (dx, dy) => strokeMaskOnce(
+ dx === 0 && dy === 0 ? runs : runs.map((r) => ({ closed: r.closed, points: r.points.map(([x, y]) => [x + dx, y + dy] as Pt) })), width, w, h, join, cap));
+}
+
+function strokeMaskOnce(runs: readonly { points: readonly Pt[]; closed: boolean }[], width: number, w: number, h: number, join: 'round' | 'miter' | 'bevel' = 'round', cap: 'round' | 'butt' | 'square' = 'round'): Float32Array {
+ const mask = new Float32Array(w * h);
+ const half = width / 2;
+ const capsule = (a: Pt, b: Pt): void => {
+ const [x0, x1] = [Math.max(0, Math.floor(Math.min(a[0], b[0]) - half - 1)), Math.min(w - 1, Math.ceil(Math.max(a[0], b[0]) + half + 1))];
+ const [y0, y1] = [Math.max(0, Math.floor(Math.min(a[1], b[1]) - half - 1)), Math.min(h - 1, Math.ceil(Math.max(a[1], b[1]) + half + 1))];
+ const [ex, ey] = [b[0] - a[0], b[1] - a[1]];
+ const len = ex * ex + ey * ey;
+ for (let y = y0; y <= y1; y++) {
+ for (let x = x0; x <= x1; x++) {
+ const [px, py] = [x + 0.5 - a[0], y + 0.5 - a[1]];
+ const t = len > 0 ? Math.max(0, Math.min(1, (px * ex + py * ey) / len)) : 0;
+ const v = Math.max(0, Math.min(1, half - Math.hypot(px - ex * t, py - ey * t) + 0.5));
+ if (v > mask[y * w + x]!) mask[y * w + x] = v;
+ }
+ }
+ };
+ const convex = (poly: readonly Pt[]): void => {
+ let area = 0;
+ for (let i = 0; i < poly.length; i++) {
+ const [a, b] = [poly[i]!, poly[(i + 1) % poly.length]!];
+ area += a[0] * b[1] - b[0] * a[1];
+ }
+ if (area === 0) return;
+ const edges = poly.map((a, i) => {
+ const b = poly[(i + 1) % poly.length]!;
+ const len = Math.hypot(b[0] - a[0], b[1] - a[1]) || 1;
+ return { x: a[0], y: a[1], nx: (-(b[1] - a[1]) / len) * Math.sign(area), ny: ((b[0] - a[0]) / len) * Math.sign(area) };
+ });
+ const [xs, ys] = [poly.map((p) => p[0]), poly.map((p) => p[1])];
+ const [x0, x1] = [Math.max(0, Math.floor(Math.min(...xs) - 1)), Math.min(w - 1, Math.ceil(Math.max(...xs) + 1))];
+ const [y0, y1] = [Math.max(0, Math.floor(Math.min(...ys) - 1)), Math.min(h - 1, Math.ceil(Math.max(...ys) + 1))];
+ for (let y = y0; y <= y1; y++) {
+ for (let x = x0; x <= x1; x++) {
+ let inside = Infinity;
+ for (const e of edges) inside = Math.min(inside, (x + 0.5 - e.x) * e.nx + (y + 0.5 - e.y) * e.ny);
+ if (inside <= -0.75) continue;
+ let v = 1;
+ if (inside < 0.75) {
+ let hits = 0;
+ for (let sy = 0; sy < STROKE_SAMPLES; sy++) {
+ for (let sx = 0; sx < STROKE_SAMPLES; sx++) {
+ const [px, py] = [x + (sx + 0.5) / STROKE_SAMPLES, y + (sy + 0.5) / STROKE_SAMPLES];
+ if (edges.every((e) => (px - e.x) * e.nx + (py - e.y) * e.ny >= 0)) hits++;
+ }
+ }
+ v = hits / (STROKE_SAMPLES * STROKE_SAMPLES);
+ }
+ if (v > mask[y * w + x]!) mask[y * w + x] = v;
+ }
+ }
+ };
+ for (const run of runs) {
+ if (join === 'round' && cap === 'round') {
+ const count = run.closed ? run.points.length : run.points.length - 1;
+ for (let i = 0; i < count; i++) capsule(run.points[i]!, run.points[(i + 1) % run.points.length]!);
+ continue;
+ }
+ // A point repeated has no direction to join from.
+ const pts = run.points.filter((p, i, all) => i === 0 || Math.hypot(p[0] - all[i - 1]![0], p[1] - all[i - 1]![1]) > 1e-6);
+ if (run.closed && pts.length > 1 && Math.hypot(pts[0]![0] - pts[pts.length - 1]![0], pts[0]![1] - pts[pts.length - 1]![1]) <= 1e-6) pts.pop();
+ if (pts.length < 2) {
+ if (pts[0] && cap !== 'butt') capsule(pts[0], pts[0]);
+ continue;
+ }
+ const count = run.closed ? pts.length : pts.length - 1;
+ const direction = (i: number): Pt => {
+ const [a, b] = [pts[i]!, pts[(i + 1) % pts.length]!];
+ const len = Math.hypot(b[0] - a[0], b[1] - a[1]);
+ return [(b[0] - a[0]) / len, (b[1] - a[1]) / len];
+ };
+ for (let i = 0; i < count; i++) {
+ const [a, b] = [pts[i]!, pts[(i + 1) % pts.length]!];
+ const u = direction(i);
+ const [nx, ny] = [-u[1] * half, u[0] * half];
+ // A joined end runs on by a pixel's half diagonal, or two pieces half covering a pixel leave a notch across the line.
+ const end = (open: boolean): number => (open ? (cap === 'square' ? half : 0) : 0.75);
+ const [s, e] = [end(!run.closed && i === 0), end(!run.closed && i === count - 1)];
+ const [ax, ay, bx, by] = [a[0] - u[0] * s, a[1] - u[1] * s, b[0] + u[0] * e, b[1] + u[1] * e];
+ convex([[ax + nx, ay + ny], [bx + nx, by + ny], [bx - nx, by - ny], [ax - nx, ay - ny]]);
+ }
+ if (!run.closed && cap === 'round') {
+ capsule(pts[0]!, pts[0]!);
+ capsule(pts[pts.length - 1]!, pts[pts.length - 1]!);
+ }
+ for (let i = run.closed ? 0 : 1; i < (run.closed ? pts.length : pts.length - 1); i++) {
+ const p = pts[i]!;
+ const [u0, u1] = [direction((i - 1 + pts.length) % pts.length), direction(i)];
+ const cross = u0[0] * u1[1] - u0[1] * u1[0];
+ if (join === 'round') {
+ capsule(p, p);
+ continue;
+ }
+ if (Math.abs(cross) < 1e-6) continue;
+ // Turning toward +normal, the outside of the corner is the other side.
+ const side = cross > 0 ? -1 : 1;
+ const [n0, n1]: [Pt, Pt] = [[-u0[1] * side, u0[0] * side], [-u1[1] * side, u1[0] * side]];
+ const [A, B]: [Pt, Pt] = [[p[0] + n0[0] * half, p[1] + n0[1] * half], [p[0] + n1[0] * half, p[1] + n1[1] * half]];
+ const [mx, my] = [n0[0] + n1[0], n0[1] + n1[1]];
+ const length = Math.hypot(mx, my);
+ const ratio = length > 0 ? 2 / length : Infinity;
+ if (join === 'miter' && ratio <= MITER_LIMIT) convex([p, A, [p[0] + (mx / length) * half * ratio, p[1] + (my / length) * half * ratio], B]);
+ else convex([p, A, B]);
+ }
+ }
+ return mask;
+}
+
+function shifted(src: Float32Array, w: number, h: number, dx: number, dy: number): Float32Array {
+ const [ix, iy] = [Math.round(dx), Math.round(dy)];
+ if (ix === 0 && iy === 0) return src;
+ const out = new Float32Array(w * h);
+ if (isWrapping()) {
+ for (let y = 0; y < h; y++) {
+ const fy = (((y - iy) % h) + h) % h;
+ for (let x = 0; x < w; x++) out[y * w + x] = src[fy * w + ((((x - ix) % w) + w) % w)]!;
+ }
+ return out;
+ }
+ for (let y = 0; y < h; y++) {
+ const fy = y - iy;
+ if (fy < 0 || fy >= h) continue;
+ for (let x = 0; x < w; x++) {
+ const fx = x - ix;
+ if (fx >= 0 && fx < w) out[y * w + x] = src[fy * w + fx]!;
+ }
+ }
+ return out;
+}
+
+/** From a place in the picture to where it lies on four corners, 0..1 each way; null when the corners cannot be solved. */
+function quadToUnit(q: readonly (readonly number[])[]): ((x: number, y: number) => readonly [number, number]) | null {
+ const [[x0, y0], [x1, y1], [x2, y2], [x3, y3]] = q as unknown as [[number, number], [number, number], [number, number], [number, number]];
+ // The square onto the corners, as a projective map.
+ const [dx1, dx2, sx, dy1, dy2, sy] = [x1 - x2, x3 - x2, x0 - x1 + x2 - x3, y1 - y2, y3 - y2, y0 - y1 + y2 - y3];
+ const det = dx1 * dy2 - dx2 * dy1;
+ if (Math.abs(det) < 1e-9) return null;
+ const g = (sx * dy2 - dx2 * sy) / det, h = (dx1 * sy - sx * dy1) / det;
+ const [a, b, c, d, e, f] = [x1 - x0 + g * x1, x3 - x0 + h * x3, x0, y1 - y0 + g * y1, y3 - y0 + h * y3, y0];
+ // Its inverse, by cofactors.
+ const [A, B, C, D, E, F, G, H, I] = [e - f * h, c * h - b, b * f - c * e, f * g - d, a - c * g, c * d - a * f, d * h - e * g, b * g - a * h, a * e - b * d];
+ return (x, y) => {
+ const z = G * x + H * y + I;
+ return [(A * x + B * y + C) / z, (D * x + E * y + F) / z];
+ };
+}
+
+/** The other way: from 0..1 each way on four corners to the place in the picture. */
+function unitToQuad(q: readonly (readonly number[])[]): (u: number, v: number) => Pt {
+ const [[x0, y0], [x1, y1], [x2, y2], [x3, y3]] = q as unknown as [[number, number], [number, number], [number, number], [number, number]];
+ const [dx1, dx2, sx, dy1, dy2, sy] = [x1 - x2, x3 - x2, x0 - x1 + x2 - x3, y1 - y2, y3 - y2, y0 - y1 + y2 - y3];
+ const det = dx1 * dy2 - dx2 * dy1 || 1e-9;
+ const g = (sx * dy2 - dx2 * sy) / det, h = (dx1 * sy - sx * dy1) / det;
+ const [a, b, c, d, e, f] = [x1 - x0 + g * x1, x3 - x0 + h * x3, x0, y1 - y0 + g * y1, y3 - y0 + h * y3, y0];
+ return (u, v) => {
+ const z = g * u + h * v + 1;
+ return [(a * u + b * v + c) / z, (d * u + e * v + f) / z];
+ };
+}
+
+/** A block's face, named as "id.a", and the part of it asked for. A name that is not there says so. */
+function faceCorners(layer: ImageLayer, drawn: Drawn): readonly (readonly number[])[] | null {
+ const [id, key] = (layer.face as string).replace(/^@/, '').split('.') as [string, string | undefined];
+ const quad = key ? drawn.blocks.get(id)?.[key] : undefined;
+ if (!quad) {
+ drawn.notes.push(`layer ${layer.id ?? layer.shape}: face "${layer.face}" names no face of a block drawn before it, so it drew nothing`);
+ return null;
+ }
+ if (!layer.within) return quad;
+ const to = unitToQuad(quad);
+ const [l, t, r, b] = layer.within as [number, number, number, number];
+ return [to(l, t), to(r, t), to(r, b), to(l, b)];
+}
+
+/** Marks in rows and columns, each with its own colour and whether it is on, sampled within the pixel so distant rows blend and do not shimmer. */
+function gridPaint(fill: Extract<ImageFill, { type: 'grid' }>, m: Matrix): (x: number, y: number) => Rgba {
+ const colors = fill.colors.map(parseColor);
+ const ground = fill.ground ? parseColor(fill.ground) : ([0, 0, 0, 0] as Rgba);
+ const off = fill.off ? parseColor(fill.off) : ground;
+ const [mw, mh] = fill.mark ?? [0.6, 0.6];
+ const [lit, seed] = [fill.lit ?? 1, fill.seed ?? 1];
+ const inverse = invert(m);
+ const toUnit = fill.quad ? quadToUnit(fill.quad) : null;
+ const [cols, rows] = fill.cells ?? [1, 1];
+ const [cw, ch] = fill.cell ?? [1, 1];
+ const at = (x: number, y: number): Rgba => {
+ let u: number, v: number;
+ if (toUnit) {
+ const p = toUnit(x, y);
+ if (p[0] < 0 || p[1] < 0 || p[0] > 1 || p[1] > 1) return ground;
+ [u, v] = [p[0] * cols, p[1] * rows];
+ } else {
+ const p = apply(inverse, [x, y]);
+ [u, v] = [p[0] / cw, p[1] / ch];
+ }
+ const [i, j] = [Math.floor(u), Math.floor(v)];
+ if (Math.abs(u - i - 0.5) > mw / 2 || Math.abs(v - j - 0.5) > mh / 2) return ground;
+ if (hash01(seed * 41 + i, j) >= lit) return off;
+ return colors[Math.floor(hash01(seed * 43 + j, i) * colors.length) % colors.length]!;
+ };
+ const SAMPLES = 3;
+ return (x, y) => {
+ const sum = [0, 0, 0, 0];
+ for (let sy = 0; sy < SAMPLES; sy++) {
+ for (let sx = 0; sx < SAMPLES; sx++) {
+ const c = at(x - 0.5 + (sx + 0.5) / SAMPLES, y - 0.5 + (sy + 0.5) / SAMPLES);
+ sum[0]! += c[0] * c[3]; sum[1]! += c[1] * c[3]; sum[2]! += c[2] * c[3]; sum[3]! += c[3];
+ }
+ }
+ const a = sum[3]!;
+ return a > 0 ? [sum[0]! / a, sum[1]! / a, sum[2]! / a, a / (SAMPLES * SAMPLES)] : [0, 0, 0, 0];
+ };
+}
+
+/** Draws text to coverage in the picture's pixels. Lives in whoever has fonts: this file has none. */
+export type ImageTextDrawer = (layer: ImageLayer, m: readonly number[], w: number, h: number) => { fill: Float32Array; line: Float32Array | null };
+
+function paintOf(fill: ImageFill, m: Matrix, drawn?: Drawn, w = 0): (x: number, y: number) => Rgba {
+ if (typeof fill === 'string') {
+ const c = parseColor(fill);
+ return () => c;
+ }
+ const stops = [...(fill.type === 'image' || fill.type === 'grid' ? [] : fill.stops)].map(([t, c]) => [t, parseColor(c)] as const).sort((a, b) => a[0] - b[0]);
+ const inverse = invert(m);
+ const at = (t: number): Rgba => {
+ if (t <= stops[0]![0]) return stops[0]![1];
+ for (let i = 1; i < stops.length; i++) {
+ if (t <= stops[i]![0]) {
+ const [t0, a] = stops[i - 1]!, [t1, b] = stops[i]!;
+ const s = (t - t0) / Math.max(1e-6, t1 - t0);
+ return [a[0] + (b[0] - a[0]) * s, a[1] + (b[1] - a[1]) * s, a[2] + (b[2] - a[2]) * s, a[3] + (b[3] - a[3]) * s];
+ }
+ }
+ return stops[stops.length - 1]![1];
+ };
+ if (fill.type === 'image') {
+ const image = drawn?.images.get(fill.image);
+ if (!image) {
+ drawn?.notes.push(`a fill names image "${fill.image}", which was not drawn before it`);
+ return () => [0, 0, 0, 0];
+ }
+ return (x, y) => {
+ const i = (Math.floor(y) * w + Math.floor(x)) * 4;
+ return [image[i] ?? 0, image[i + 1] ?? 0, image[i + 2] ?? 0, image[i + 3] ?? 0];
+ };
+ }
+ if (fill.type === 'grid') return gridPaint(fill, m);
+ if (fill.type === 'form') {
+ const figure = drawn?.figures.get(fill.figure);
+ if (!figure) {
+ drawn?.notes.push(`a form names figure "${fill.figure}", which was not drawn before it`);
+ return () => at(0);
+ }
+ const light = fill.light ? unit3(fill.light) : figure.light;
+ return (x, y) => {
+ const i = Math.floor(y) * w + Math.floor(x);
+ const [nx, ny, nz] = [figure.normals[i * 3] ?? 0, figure.normals[i * 3 + 1] ?? 0, figure.normals[i * 3 + 2] ?? 0];
+ return at(0.5 + 0.5 * (nx * light[0] + ny * light[1] + nz * light[2]));
+ };
+ }
+ if (fill.type === 'noise') {
+ const [scale, octaves, seed] = [fill.scale ?? 32, fill.octaves ?? 4, fill.seed ?? 0];
+ if (isWrapping() && tileWidth > 0) {
+ // A whole number of cells across the picture, so the last meets the first; the scale gives a little to make it so.
+ // In the picture's own pixels and not the layer's: a noise turned or scaled with its layer would not come round.
+ const [cx, cy] = [Math.max(1, Math.round(tileWidth / scale)), Math.max(1, Math.round(tileHeight / scale))];
+ return (x, y) => at(fractalNoise(((x - 0.5) / tileWidth) * cx, ((y - 0.5) / tileHeight) * cy, octaves, seed, cx, cy));
+ }
+ return (x, y) => {
+ const p = apply(inverse, [x - 0.5, y - 0.5]);
+ return at(fractalNoise(p[0] / scale, p[1] / scale, octaves, seed));
+ };
+ }
+ if (fill.type === 'linear') {
+ const [a, b] = [fill.from, fill.to];
+ const [ex, ey] = [b[0] - a[0], b[1] - a[1]];
+ const len = ex * ex + ey * ey || 1;
+ return (x, y) => {
+ const p = apply(inverse, [x, y]);
+ return at(((p[0] - a[0]) * ex + (p[1] - a[1]) * ey) / len);
+ };
+ }
+ const [cx, cy] = fill.at;
+ const r = fill.radius;
+ return (x, y) => {
+ const p = apply(inverse, [x, y]);
+ return at(Math.hypot(p[0] - cx, p[1] - cy) / r);
+ };
+}
+
+/** Premultiplied: what blending wants, and what a blur of an edge wants. */
+class Canvas {
+ readonly px: Float32Array;
+ constructor(readonly w: number, readonly h: number) { this.px = new Float32Array(w * h * 4); }
+}
+
+type Blend = NonNullable<ImageLayer['blend']>;
+const softLight = (b: number, s: number): number => {
+ if (s <= 0.5) return b - (1 - 2 * s) * b * (1 - b);
+ const d = b <= 0.25 ? ((16 * b - 12) * b + 4) * b : Math.sqrt(b);
+ return b + (2 * s - 1) * (d - b);
+};
+const dodge = (b: number, s: number): number => (b <= 0 ? 0 : s >= 1 ? 1 : Math.min(1, b / (1 - s)));
+const burn = (b: number, s: number): number => (b >= 1 ? 1 : s <= 0 ? 0 : 1 - Math.min(1, (1 - b) / s));
+const hard = (b: number, s: number): number => (s < 0.5 ? 2 * b * s : 1 - 2 * (1 - b) * (1 - s));
+const blendChannel = (mode: Blend, b: number, s: number): number => {
+ switch (mode) {
+ case 'multiply': return b * s;
+ case 'screen': return b + s - b * s;
+ case 'overlay': return hard(s, b);
+ case 'add': return Math.min(1, b + s);
+ case 'softLight': return softLight(b, s);
+ case 'hardLight': return hard(b, s);
+ case 'vividLight': return s < 0.5 ? burn(b, 2 * s) : dodge(b, 2 * s - 1);
+ case 'linearLight': return Math.max(0, Math.min(1, b + 2 * s - 1));
+ case 'pinLight': return s < 0.5 ? Math.min(b, 2 * s) : Math.max(b, 2 * s - 1);
+ case 'colorDodge': return dodge(b, s);
+ case 'colorBurn': return burn(b, s);
+ case 'linearBurn': return Math.max(0, b + s - 1);
+ case 'darken': return Math.min(b, s);
+ case 'lighten': return Math.max(b, s);
+ case 'difference': return Math.abs(b - s);
+ case 'exclusion': return b + s - 2 * b * s;
+ case 'subtract': return Math.max(0, b - s);
+ case 'divide': return s <= 0 ? 1 : Math.min(1, b / s);
+ default: return s;
+ }
+};
+
+/** Keeping a colour's hue and saturation in range when its lightness is set, as the colour blend modes need. */
+function withLight(c: readonly [number, number, number], light: number): [number, number, number] {
+ const d = light - lightnessOf(c[0], c[1], c[2]);
+ const out: [number, number, number] = [c[0] + d, c[1] + d, c[2] + d];
+ const l = lightnessOf(out[0], out[1], out[2]);
+ const [lo, hi] = [Math.min(...out), Math.max(...out)];
+ if (lo < 0) for (let i = 0; i < 3; i++) out[i] = l + ((out[i]! - l) * l) / (l - lo);
+ if (hi > 1) for (let i = 0; i < 3; i++) out[i] = l + ((out[i]! - l) * (1 - l)) / (hi - l);
+ return out;
+}
+const colourfulness = (c: readonly [number, number, number]): number => Math.max(...c) - Math.min(...c);
+function withColourfulness(c: readonly [number, number, number], sat: number): [number, number, number] {
+ const [lo, hi] = [Math.min(...c), Math.max(...c)];
+ if (hi === lo) return [0, 0, 0];
+ return [((c[0] - lo) * sat) / (hi - lo), ((c[1] - lo) * sat) / (hi - lo), ((c[2] - lo) * sat) / (hi - lo)];
+}
+/** The modes that work on a colour whole: this hue on that lightness, and so on. */
+function blendWhole(mode: Blend, d: readonly [number, number, number], s: readonly [number, number, number]): [number, number, number] {
+ switch (mode) {
+ case 'hue': return withLight(withColourfulness(s, colourfulness(d)), lightnessOf(d[0], d[1], d[2]));
+ case 'saturation': return withLight(withColourfulness(d, colourfulness(s)), lightnessOf(d[0], d[1], d[2]));
+ case 'color': return withLight(s, lightnessOf(d[0], d[1], d[2]));
+ default: return withLight(d, lightnessOf(s[0], s[1], s[2]));
+ }
+}
+const WHOLE_MODES: ReadonlySet<Blend> = new Set<Blend>(['hue', 'saturation', 'color', 'luminosity']);
+
+/** @p color straight, at coverage @p m, over what is there. */
+function put(c: Canvas, i: number, r: number, g: number, b: number, a: number, mode: Blend): void {
+ if (a <= 0) return;
+ const p = c.px, at = i * 4;
+ const da = p[at + 3]!;
+ if (mode === 'normal' || da <= 0) {
+ p[at] = p[at]! * (1 - a) + r * a; p[at + 1] = p[at + 1]! * (1 - a) + g * a; p[at + 2] = p[at + 2]! * (1 - a) + b * a;
+ } else {
+ const [dr, dg, db] = [p[at]! / da, p[at + 1]! / da, p[at + 2]! / da];
+ if (WHOLE_MODES.has(mode)) {
+ const whole = blendWhole(mode, [dr, dg, db], [r, g, b]);
+ const [mr, mg, mb] = [(1 - da) * r + da * whole[0], (1 - da) * g + da * whole[1], (1 - da) * b + da * whole[2]];
+ p[at] = p[at]! * (1 - a) + mr * a; p[at + 1] = p[at + 1]! * (1 - a) + mg * a; p[at + 2] = p[at + 2]! * (1 - a) + mb * a;
+ p[at + 3] = da + a - da * a;
+ return;
+ }
+ const mix = (d: number, s: number): number => (1 - da) * s + da * blendChannel(mode, d, s);
+ p[at] = p[at]! * (1 - a) + mix(dr, r) * a; p[at + 1] = p[at + 1]! * (1 - a) + mix(dg, g) * a; p[at + 2] = p[at + 2]! * (1 - a) + mix(db, b) * a;
+ }
+ p[at + 3] = da + a - da * a;
+}
+
+/** Raised edges from how the shape's edge slopes: lit on the side toward the light, and shaded away from it. */
+function bevelEffect(e: ImageEffect, c: Canvas, mask: Float32Array): void {
+ const { w, h } = c;
+ const soft = blurMask(mask, w, h, Math.max(0.5, (e.size ?? 4) / 2));
+ const a = ((e.angle ?? 225) * Math.PI) / 180;
+ const [lx, ly] = [Math.cos(a), Math.sin(a)];
+ const [hr, hg, hb, ha] = parseColor(e.color ?? '#ffffff');
+ const [sr, sg, sb, sa] = parseColor(e.shade ?? '#000000');
+ const gain = (e.depth ?? 1) * (e.size ?? 4) * 2;
+ const op = e.opacity ?? 0.8;
+ for (let y = 1; y < h - 1; y++) {
+ for (let x = 1; x < w - 1; x++) {
+ const i = y * w + x;
+ if (mask[i]! <= 0) continue;
+ // The edge rises inward, so it faces against its slope.
+ const facing = -((soft[i + 1]! - soft[i - 1]!) * lx + (soft[i + w]! - soft[i - w]!) * ly) * gain;
+ if (facing > 0) put(c, i, hr, hg, hb, Math.min(1, facing) * op * ha * mask[i]!, 'screen');
+ else if (facing < 0) put(c, i, sr, sg, sb, Math.min(1, -facing) * op * sa * mask[i]!, 'multiply');
+ }
+ }
+}
+
+function effectLayers(effects: readonly ImageEffect[] | undefined, under: boolean, c: Canvas, mask: Float32Array): void {
+ const { w, h } = c;
+ for (const e of effects ?? []) {
+ const isUnder = e.type === 'shadow' || e.type === 'glow';
+ if (isUnder !== under) continue;
+ if (e.type === 'bevel') { bevelEffect(e, c, mask); continue; }
+ if (e.type === 'overlay') {
+ const paint = paintOf(e.fill!, IDENTITY);
+ for (let y = 0; y < h; y++) {
+ for (let x = 0; x < w; x++) {
+ const i = y * w + x;
+ if (mask[i]! <= 0) continue;
+ const col = paint(x + 0.5, y + 0.5);
+ put(c, i, col[0], col[1], col[2], col[3] * mask[i]! * (e.opacity ?? 1), e.blend ?? 'normal');
+ }
+ }
+ continue;
+ }
+ const [r, g, b, ca] = parseColor(e.color ?? (e.type === 'glow' || e.type === 'innerGlow' ? '#ffffff' : '#000000'));
+ const op = (e.opacity ?? 1) * ca;
+ const sigma = e.blur ?? (e.type === 'glow' ? 8 : 4);
+ if (isUnder) {
+ let src = shifted(mask, w, h, e.x ?? 0, e.y ?? 0);
+ // Spread first, so a glow is bright at the edge and not merely soft.
+ if (e.type === 'glow') src = src.map((v) => Math.min(1, v * 1.6));
+ const soft = blurMask(src, w, h, sigma);
+ for (let i = 0; i < soft.length; i++) put(c, i, r, g, b, Math.min(1, soft[i]! * op), e.type === 'glow' ? 'screen' : 'normal');
+ } else {
+ // Inside: what the shape leaves out, softened and moved, and kept within the shape.
+ const inv = mask.map((v) => 1 - v);
+ const soft = blurMask(shifted(inv, w, h, e.x ?? 0, e.y ?? 0), w, h, sigma);
+ const mode: Blend = e.type === 'innerGlow' ? 'screen' : 'normal';
+ for (let i = 0; i < soft.length; i++) put(c, i, r, g, b, Math.min(1, soft[i]! * mask[i]! * op), mode);
+ }
+ }
+}
+
+interface Drawn { figure?: ImageFigureDrawer; masks: Map<string, Float32Array>; notes: string[]; bounds: Map<string, ImageBox>; painted: Map<string, { entries: number; strokes: number }>; figures: Map<string, FlatFigure>; figureJoints: Map<string, Record<string, readonly [number, number]>>; showGuides: boolean; pictures: Readonly<Record<string, RgbaBitmap>>; images: Map<string, Float32Array>; text: ImageTextDrawer | undefined; blocks: Map<string, Record<string, readonly (readonly number[])[]>> }
+
+/** x, y, width and height in the picture's pixels. */
+export type ImageBox = readonly [number, number, number, number];
+
+/** The box of whatever covers at least half a pixel: where a shape's edge is, and not the last faint pixel of a glow. */
+function boxOf(w: number, h: number, covers: (i: number) => boolean): ImageBox | null {
+ let [x0, y0, x1, y1] = [w, h, -1, -1];
+ for (let y = 0; y < h; y++) {
+ for (let x = 0; x < w; x++) {
+ if (!covers(y * w + x)) continue;
+ if (x < x0) x0 = x;
+ if (x > x1) x1 = x;
+ if (y < y0) y0 = y;
+ y1 = y;
+ }
+ }
+ return x1 < 0 ? null : [x0, y0, x1 - x0 + 1, y1 - y0 + 1];
+}
+
+function noteBox(drawn: Drawn, id: string | undefined, mask: Float32Array, w: number, h: number): void {
+ if (!id) return;
+ // Half of what it reaches: a faint layer is still somewhere, and half of full coverage would miss it.
+ let peak = 0;
+ for (let i = 0; i < mask.length; i++) if (mask[i]! > peak) peak = mask[i]!;
+ if (peak <= 0.004) return;
+ const box = boxOf(w, h, (i) => mask[i]! >= Math.min(0.5, peak / 2));
+ if (box) drawn.bounds.set(id, box);
+}
+
+function drawLayer(c: Canvas, layer: ImageLayer, parent: Matrix, drawn: Drawn): void {
+ const { w, h } = c;
+ if (layer.visible === false) {
+ // A guide hidden from sight is still what others are clipped to and lit by. Anything else hidden is simply not there.
+ if (isGuideLayer(layer)) {
+ const { visible: _v, ...shown } = layer;
+ drawLayer(new Canvas(w, h), { ...shown, guide: false }, parent, drawn);
+ }
+ return;
+ }
+ // What a guide masks is still wanted when it is not seen, so it draws somewhere that is thrown away.
+ if (!drawn.showGuides && isGuideLayer(layer)) {
+ drawLayer(new Canvas(w, h), { ...layer, guide: false }, parent, drawn);
+ return;
+ }
+ if (layer.mirror) {
+ const { mirror, ...rest } = layer;
+ const axis = mirror === 'x' ? { x: -1, y: 1 } : { x: 1, y: -1 };
+ // Across the middle of the picture.
+ const flip: Matrix = axis.x < 0 ? [-1, 0, 0, 1, w / drawnScale(parent), 0] : [1, 0, 0, -1, 0, h / drawnScale(parent)];
+ drawLayer(c, rest, parent, drawn);
+ drawLayer(c, { ...rest, ...(layer.id ? { id: `${layer.id}.mirrored` } : {}) }, times(parent, flip), drawn);
+ return;
+ }
+ const opacity = layer.opacity ?? 1;
+ const blend: Blend = layer.blend ?? 'normal';
+ const named = (id: string): Float32Array | undefined => drawn.masks.get(id.replace(/^@/, ''));
+ let clip = layer.clip ? named(layer.clip) : undefined;
+ const softened = (mask: Float32Array): Float32Array => {
+ let out = mask;
+ if (layer.clipGrow) out = grownMask(out, layer.clipGrow * drawnScale(parent), w, h);
+ if (layer.clipFeather) out = blurMask(out, w, h, layer.clipFeather * drawnScale(parent));
+ return layer.clipInvert ? out.map((v) => 1 - v) : out;
+ };
+ if (clip) clip = softened(clip);
+ // Nothing, and not everything: a clip that failed would otherwise cover the picture in what it was meant to hold in.
+ if (layer.clip && !clip) {
+ drawn.notes.push(`layer ${layer.id ?? layer.shape}: clip "${layer.clip}" names no layer drawn before it, so it drew nothing`);
+ return;
+ }
+ if (layer.except) {
+ const out = named(layer.except);
+ if (!out) drawn.notes.push(`layer ${layer.id ?? layer.shape}: except "${layer.except}" names no layer drawn before it`);
+ else clip = out.map((v, i) => (1 - v) * (clip ? clip[i]! : 1));
+ }
+
+ if (layer.blendIf) {
+ // Reads the picture as it stands now, so a highlight is chosen by being one.
+ const [low, high, soft = 0.1] = layer.blendIf as [number, number, number?];
+ const chosen = new Float32Array(w * h);
+ for (let i = 0; i < chosen.length; i++) {
+ const a = c.px[i * 4 + 3]!;
+ const l = a > 0 ? lightnessOf(c.px[i * 4]! / a, c.px[i * 4 + 1]! / a, c.px[i * 4 + 2]! / a) : 0;
+ const v = Math.min(soft > 0 ? (l - low) / soft + 1 : l >= low ? 1 : 0, soft > 0 ? (high - l) / soft + 1 : l <= high ? 1 : 0);
+ chosen[i] = Math.max(0, Math.min(1, v)) * (clip ? clip[i]! : 1);
+ }
+ clip = chosen;
+ }
+
+ if (layer.feather) {
+ const { feather, opacity: _o, blend: _b, clip: _c, except: _e, blendIf: _f, clipFeather: _g, clipGrow: _h, clipInvert: _i, ...sharp } = layer;
+ const inner = new Canvas(w, h);
+ drawLayer(inner, sharp, parent, drawn);
+ const alpha = new Float32Array(w * h);
+ for (let i = 0; i < alpha.length; i++) alpha[i] = inner.px[i * 4 + 3]!;
+ const soft = blurMask(alpha, w, h, feather * drawnScale(parent));
+ const mask = new Float32Array(w * h);
+ for (let i = 0; i < alpha.length; i++) {
+ const a = alpha[i]!;
+ if (a <= 0) continue;
+ // Fading in from the edge: half way down its blur is the edge, and all of the colour there is the layer's own.
+ const kept = a * smoothed(Math.max(0, Math.min(1, (soft[i]! / a - 0.5) * 2.5)));
+ mask[i] = kept * (clip ? clip[i]! : 1);
+ put(c, i, inner.px[i * 4]! / a, inner.px[i * 4 + 1]! / a, inner.px[i * 4 + 2]! / a, mask[i]! * opacity, blend);
+ }
+ if (layer.id) drawn.masks.set(layer.id, mask);
+ return;
+ }
+
+ if (layer.shape === 'adjust' || layer.shape === 'filter') {
+ const k = drawnScale(parent);
+ const next = layer.shape === 'adjust' ? applyAdjust(c.px, w, h, layer.adjust!) : applyFilter(layer.filter!, layer.params ?? {}, c.px, w, h, k);
+ for (let i = 0; i < w * h; i++) {
+ const keep = opacity * (clip ? clip[i]! : 1);
+ if (keep <= 0) continue;
+ const at = i * 4;
+ if (blend !== 'normal') {
+ const a = next[at + 3]!;
+ if (a > 0) put(c, i, next[at]! / a, next[at + 1]! / a, next[at + 2]! / a, a * keep, blend);
+ continue;
+ }
+ for (let n = 0; n < 4; n++) c.px[at + n] = c.px[at + n]! + (next[at + n]! - c.px[at + n]!) * keep;
+ }
+ return;
+ }
+
+ if (layer.blur) {
+ const { blur, opacity: _o, blend: _b, clip: _c, except: _e, blendIf: _f, clipFeather: _g, clipGrow: _h, clipInvert: _i, ...sharp } = layer;
+ const inner = new Canvas(w, h);
+ drawLayer(inner, sharp, parent, drawn);
+ // Blurred as stored, colour already times alpha: blurring straight colour would bring the black of empty pixels in round the edge.
+ const [r, g, b, a] = [0, 1, 2, 3].map((k) => {
+ const channel = new Float32Array(w * h);
+ for (let i = 0; i < channel.length; i++) channel[i] = inner.px[i * 4 + k]!;
+ return blurMask(channel, w, h, blur * drawnScale(parent));
+ }) as [Float32Array, Float32Array, Float32Array, Float32Array];
+ if (layer.id) drawn.masks.set(layer.id, clip ? a.map((v, i) => v * clip![i]!) : a);
+ for (let i = 0; i < a.length; i++) {
+ const alpha = a[i]!;
+ if (alpha <= 0) continue;
+ put(c, i, r[i]! / alpha, g[i]! / alpha, b[i]! / alpha, alpha * opacity * (clip ? clip[i]! : 1), blend);
+ }
+ return;
+ }
+
+ if (layer.shape === 'group') {
+ const inner = new Canvas(w, h);
+ const m = times(parent, transformOf(layer.transform, [w / 2, h / 2]));
+ for (const child of layer.layers ?? []) drawLayer(inner, child, m, drawn);
+ const alpha = new Float32Array(w * h);
+ for (let i = 0; i < alpha.length; i++) alpha[i] = inner.px[i * 4 + 3]!;
+ if (layer.id) drawn.masks.set(layer.id, alpha);
+ noteBox(drawn, layer.id, alpha, w, h);
+ effectLayers(layer.effects, true, c, alpha);
+ for (let i = 0; i < alpha.length; i++) {
+ const a = alpha[i]! * opacity * (clip ? clip[i]! : 1);
+ if (a <= 0) continue;
+ const s = inner.px[i * 4 + 3]! || 1;
+ put(c, i, inner.px[i * 4]! / s, inner.px[i * 4 + 1]! / s, inner.px[i * 4 + 2]! / s, a, blend);
+ }
+ effectLayers(layer.effects, false, c, alpha);
+ return;
+ }
+
+ if (layer.shape === 'pixels') {
+ drawPixels(c, layer, parent, drawn, opacity, blend, clip);
+ return;
+ }
+
+ if (layer.shape === 'paint') {
+ drawPaint(c, layer, parent, drawn, opacity, blend, clip);
+ return;
+ }
+
+ if (layer.shape === 'figure') {
+ drawFigure(c, layer, parent, drawn, opacity, blend, clip);
+ return;
+ }
+
+ if (layer.shape === 'image') {
+ drawPicture(c, layer, parent, drawn, opacity, blend, clip);
+ return;
+ }
+
+ if (layer.shape === 'text') {
+ drawText(c, layer, parent, drawn, opacity, blend, clip);
+ return;
+ }
+
+ if (layer.shape === 'block') {
+ drawBlock(c, layer, parent, drawn);
+ return;
+ }
+
+ if (layer.shape === 'perspective') {
+ drawPerspective(c, layer, parent, opacity);
+ return;
+ }
+
+ if (layer.shape === 'reflect') {
+ drawReflection(c, layer, parent, drawn, opacity, clip);
+ return;
+ }
+
+ if (layer.shape === 'bloom') {
+ drawBloom(c, layer, parent, opacity, clip);
+ return;
+ }
+
+ if (layer.face && layer.shape === 'rect') {
+ const corners = faceCorners(layer, drawn);
+ if (!corners) return;
+ const { face: _f, within: _w, at: _a, size: _s, radius: _r, ...rest } = layer;
+ const fill = rest.fill && typeof rest.fill !== 'string' && rest.fill.type === 'grid' && !rest.fill.quad ? { ...rest.fill, quad: corners } : rest.fill;
+ drawLayer(c, { ...rest, ...(fill ? { fill } : {}), shape: 'polygon', points: corners as [number, number][] }, parent, drawn);
+ return;
+ }
+
+ const { runs, middle } = outlinesOf(layer);
+ const m = times(parent, transformOf(layer.transform, middle));
+ const placed = runs.map((run) => ({ closed: run.closed, points: run.points.map((p) => apply(m, p)) }));
+ const scale = Math.sqrt(Math.abs(m[0] * m[3] - m[1] * m[2]));
+ const hasFill = layer.fill !== undefined && layer.shape !== 'line';
+ const body = layer.shape === 'line' ? new Float32Array(w * h) : fillMask(placed.map((r) => r.points), w, h);
+ const align = layer.stroke?.align ?? 'center';
+ // An outside stroke is as wide again and goes under the fill. Cut to meet the fill's edge, each would cover part of the same edge pixel and the ground would show between them.
+ const line = layer.stroke ? strokeMask(placed, layer.stroke.width * scale * (align === 'outside' ? 2 : 1), w, h, layer.stroke.join, layer.stroke.cap) : null;
+ if (line && align === 'inside') for (let i = 0; i < line.length; i++) line[i]! *= body[i]!;
+ // Under a see-through fill it must not show, so only the edge pixels keep it.
+ if (line && align === 'outside') for (let i = 0; i < line.length; i++) if (body[i]! >= 0.999) line[i] = 0;
+ const whole = new Float32Array(w * h);
+ let any = 0;
+ for (let i = 0; i < whole.length; i++) {
+ const v = Math.max(hasFill ? body[i]! : 0, line ? line[i]! : 0) * (clip ? clip[i]! : 1);
+ whole[i] = v;
+ any += v;
+ }
+ noteBox(drawn, layer.id, whole, w, h);
+ // What clips to this stays inside its stroke: liquid in a flask must not paint over the flask's outline.
+ if (layer.id) {
+ // A line has no inside but itself.
+ const covering = align === 'outside' ? null : line;
+ drawn.masks.set(layer.id, layer.shape === 'line' ? whole : body.map((v, i) => v * (covering ? 1 - covering[i]! : 1) * (clip ? clip[i]! : 1)));
+ }
+ if (any === 0) drawn.notes.push(`layer ${layer.id ?? layer.shape} draws nothing inside the picture${clip ? ', or nothing inside its clip' : ''}`);
+ if (layer.erase) {
+ for (let i = 0; i < whole.length; i++) {
+ const keep = 1 - whole[i]! * opacity;
+ for (let k = 0; k < 4; k++) c.px[i * 4 + k]! *= keep;
+ }
+ return;
+ }
+ effectLayers(layer.effects, true, c, whole);
+ const paintLine = (): void => {
+ const paint = paintOf(layer.stroke!.color, m, drawn, w);
+ for (let y = 0; y < h; y++) {
+ for (let x = 0; x < w; x++) {
+ const i = y * w + x;
+ const v = line![i]! * (clip ? clip[i]! : 1);
+ if (v <= 0) continue;
+ const col = paint(x + 0.5, y + 0.5);
+ put(c, i, col[0], col[1], col[2], v * col[3] * opacity, blend);
+ }
+ }
+ };
+ if (line && align === 'outside') paintLine();
+ if (hasFill) {
+ const paint = paintOf(layer.fill!, m, drawn, w);
+ for (let y = 0; y < h; y++) {
+ for (let x = 0; x < w; x++) {
+ const i = y * w + x;
+ const v = body[i]! * (clip ? clip[i]! : 1);
+ if (v <= 0) continue;
+ const col = paint(x + 0.5, y + 0.5);
+ put(c, i, col[0], col[1], col[2], v * col[3] * opacity, blend);
+ }
+ }
+ }
+ effectLayers(layer.effects, false, c, whole);
+ if (line && align !== 'outside') paintLine();
+}
+
+const drawnScale = (m: Matrix): number => Math.sqrt(Math.abs(m[0] * m[3] - m[1] * m[2])) || 1;
+
+/** Rows of characters, each a palette's colour, drawn as hard squares. */
+// ---- Brushes ---------------------------------------------------------------------
+
+const hash01 = (a: number, b: number): number => {
+ let h = Math.imul(a, 374761393) + Math.imul(b, 668265263);
+ h = Math.imul(h ^ (h >>> 13), 1274126177);
+ h = Math.imul(h ^ (h >>> 16), 2246822519);
+ return ((h ^ (h >>> 16)) >>> 0) / 4294967295;
+};
+
+const smoothed = (t: number): number => t * t * (3 - 2 * t);
+
+interface PathPoint { x: number; y: number; pressure: number; along: number }
+
+/** The tooth of the paper, worked out once: every stroke with grain asks it at every pixel it touches. */
+let paper: { key: string; values: Float32Array } | null = null;
+function paperAt(w: number, h: number, scale: number): Float32Array {
+ const key = `${w}x${h}:${scale}`;
+ if (paper?.key === key) return paper.values;
+ const values = new Float32Array(w * h);
+ for (let y = 0; y < h; y++) for (let x = 0; x < w; x++) values[y * w + x] = fractalNoise((x + 0.5) / scale, (y + 0.5) / scale, 3, 77);
+ paper = { key, values };
+ return values;
+}
+
+/** A stroke's points as a smooth line about a pixel apart, Catmull-Rom so it passes through each. */
+function brushPath(points: readonly (readonly number[])[], m: Matrix): PathPoint[] {
+ const placed = points.map((p) => {
+ const q = apply(m, [p[0]!, p[1]!]);
+ return [q[0], q[1], p[2] ?? 1] as const;
+ });
+ const out: PathPoint[] = [{ x: placed[0]![0], y: placed[0]![1], pressure: placed[0]![2], along: 0 }];
+ for (let i = 0; i + 1 < placed.length; i++) {
+ const [p0, p1, p2, p3] = [placed[Math.max(0, i - 1)]!, placed[i]!, placed[i + 1]!, placed[Math.min(placed.length - 1, i + 2)]!];
+ const steps = Math.max(1, Math.ceil(Math.hypot(p2[0] - p1[0], p2[1] - p1[1])));
+ for (let s = 1; s <= steps; s++) {
+ const t = s / steps, t2 = t * t, t3 = t2 * t;
+ const curve = (k: 0 | 1): number => 0.5 * (2 * p1[k] + (p2[k] - p0[k]) * t + (2 * p0[k] - 5 * p1[k] + 4 * p2[k] - p3[k]) * t2 + (3 * p1[k] - p0[k] - 3 * p2[k] + p3[k]) * t3);
+ const [x, y] = [curve(0), curve(1)];
+ const last = out[out.length - 1]!;
+ out.push({ x, y, pressure: p1[2] + (p2[2] - p1[2]) * t, along: last.along + Math.hypot(x - last.x, y - last.y) });
+ }
+ }
+ return out;
+}
+
+/** One stroke's coverage before it meets the canvas, so a stroke overlapping itself does not build up into beads. */
+interface StrokeBuffer { mask: Float32Array; rgb: Float32Array; touched: number[] }
+
+function paintStrand(c: Canvas, s: ImageStroke, path: readonly PathPoint[], strand: { offset: number; radius: number | null; from: number; to: number; shade: number; strength: number; seed: number }, scale: number, buffer: StrokeBuffer): void {
+ const { w, h } = c;
+ const total = path[path.length - 1]!.along;
+ const [startColor, endColor] = [parseColor(s.color ?? '#000000'), parseColor(s.to ?? s.color ?? '#000000')];
+ const [taperIn, taperOut] = s.taper ?? [0, 0];
+ const [fadeIn, fadeOut] = s.fade ?? [0, 0];
+ const roundness = s.roundness ?? 1;
+ const held = s.angle !== undefined ? [Math.cos((s.angle * Math.PI) / 180), Math.sin((s.angle * Math.PI) / 180)] as const : null;
+ const [grain, grainScale, dry, wet, edge, flow] = [s.grain ?? 0, (s.grainScale ?? 2) * scale, s.dry ?? 0, s.wet ?? 0, s.edge ?? 0, s.flow ?? 0];
+ const [scatter, dab, spacing] = [s.scatter ?? 0, s.dab ?? 1, s.spacing];
+ let loaded: [number, number, number] | null = null;
+ let stamp = 0;
+ const hardness = s.hardness ?? 0.5;
+ const size = s.size * scale;
+ const smudge = s.smudge ?? 0;
+ const wobble = (s.wobble ?? 0) * scale;
+
+ const sample = (x: number, y: number): [number, number, number, number] => {
+ const [px, py] = [Math.max(0, Math.min(w - 1, Math.floor(x))), Math.max(0, Math.min(h - 1, Math.floor(y)))];
+ const at = (py * w + px) * 4;
+ return [c.px[at]!, c.px[at + 1]!, c.px[at + 2]!, c.px[at + 3]!];
+ };
+ let carried: [number, number, number, number] | null = null;
+
+ let index = 0;
+ let distance = total * strand.from;
+ const end = total * strand.to;
+ for (;;) {
+ while (index + 1 < path.length - 1 && path[index + 1]!.along < distance) index++;
+ const [a, b] = [path[index]!, path[Math.min(path.length - 1, index + 1)]!];
+ const span = b.along - a.along;
+ const t = span > 0 ? Math.max(0, Math.min(1, (distance - a.along) / span)) : 0;
+ const position = total > 0 ? distance / total : 0;
+ let narrowing = 1;
+ if (total > 0 && taperIn > 0 && position < taperIn) narrowing *= smoothed(position / taperIn);
+ if (total > 0 && taperOut > 0 && position > 1 - taperOut) narrowing *= smoothed((1 - position) / taperOut);
+ const width = size * (a.pressure + (b.pressure - a.pressure) * t) * narrowing;
+ const reach = strand.radius === null ? width / 2 : Math.min(strand.radius, Math.max(width, strand.radius * 0.4));
+ const radius = reach * dab;
+ const [nx, ny] = span > 0 ? [-(b.y - a.y) / span, (b.x - a.x) / span] : [0, 0];
+ const drift = wobble > 0 ? gradientNoise(distance / (size * 3 + 8), strand.seed * 0.37 + 0.5, strand.seed) * 2 * wobble : 0;
+ const away = strand.offset * width + drift;
+ stamp++;
+ const [off1, off2] = scatter > 0 ? [(hash01(strand.seed * 3 + 1, stamp) - 0.5) * 2, (hash01(strand.seed * 3 + 2, stamp) - 0.5) * 2] : [0, 0];
+ const [cx, cy] = [a.x + (b.x - a.x) * t + nx * away + off1 * scatter * reach, a.y + (b.y - a.y) * t + ny * away + off2 * scatter * reach];
+ let fading = 1;
+ if (total > 0 && fadeIn > 0 && position < fadeIn) fading *= position / fadeIn;
+ if (total > 0 && fadeOut > 0 && position > 1 - fadeOut) fading *= (1 - position) / fadeOut;
+
+ if (radius >= 0.12) {
+ const soft = Math.max(1, radius * (1 - hardness));
+ const thin = Math.min(1, radius * 2);
+ // Flat at the top: stamps of a pointed falloff, overlapped, ripple along the stroke.
+ const cover = (d: number): number => {
+ const v = Math.max(0, Math.min(1, (radius + 0.5 - d) / soft));
+ return soft > 1 ? smoothed(v) : v;
+ };
+ // Across is the wide way of the brush, as it travels or as it is held.
+ const [ax2, ay2] = held ?? [nx, ny];
+ const shaped = (dx: number, dy: number): number => (roundness >= 1 ? Math.hypot(dx, dy) : Math.hypot(dx * ax2 + dy * ay2, (dx * ay2 - dy * ax2) / roundness));
+ const toothOf = (x: number, y: number): number => {
+ if (grain <= 0 && dry <= 0) return 1;
+ let kept = 1;
+ // A wide band and not a threshold: paper takes more or less pigment at each place, and specks of all or nothing read as static.
+ // A wide band and not a threshold: paper takes more or less pigment at each place, and specks of all or nothing read as static.
+ if (grain > 0) kept *= Math.max(0, Math.min(1, (paperAt(w, h, grainScale)[Math.floor(y) * w + Math.floor(x)]! - (0.12 + grain * 0.62)) / 0.34 + 0.5));
+ if (dry > 0) {
+ // Hairs of the brush: fine across its width and long along its travel.
+ const across = (x - cx) * nx + (y - cy) * ny + away;
+ // Hairs gather in clumps, some wide and some fine, so the gaps are not ruled lines.
+ const hairs = gradientNoise(across / Math.max(0.8, size * 0.045), distance / (size * 3 + 8), strand.seed + 5);
+ const clumps = gradientNoise(across / Math.max(1.5, size * 0.17), distance / (size * 5 + 12), strand.seed + 9);
+ const streak = 0.5 + 0.8 * hairs + 1.1 * clumps;
+ kept *= Math.max(0, Math.min(1, (streak - (0.12 + dry * 0.68)) / 0.22 + 0.5));
+ }
+ return kept;
+ };
+ const [x0, x1] = [Math.max(0, Math.floor(cx - radius - 1)), Math.min(w - 1, Math.ceil(cx + radius + 1))];
+ const [y0, y1] = [Math.max(0, Math.floor(cy - radius - 1)), Math.min(h - 1, Math.ceil(cy + radius + 1))];
+ if (smudge > 0) {
+ carried ??= sample(cx, cy);
+ for (let y = y0; y <= y1; y++) {
+ for (let x = x0; x <= x1; x++) {
+ const v = cover(shaped(x + 0.5 - cx, y + 0.5 - cy)) * thin * smudge * (s.opacity ?? 1) * toothOf(x + 0.5, y + 0.5);
+ if (v <= 0) continue;
+ const at = (y * w + x) * 4;
+ for (let k = 0; k < 4; k++) c.px[at + k] = c.px[at + k]! + (carried[k]! - c.px[at + k]!) * v * 0.5;
+ }
+ }
+ const here = sample(cx, cy);
+ for (let k = 0; k < 4; k++) carried[k] = carried[k]! + (here[k]! - carried[k]!) * (1 - smudge) * 0.5;
+ } else {
+ const along = total > 0 ? distance / total : 0;
+ const mix = (k: number): number => Math.max(0, Math.min(1, (startColor[k]! + (endColor[k]! - startColor[k]!) * along) * strand.shade));
+ let [r, g, bl] = [mix(0), mix(1), mix(2)];
+ if (wet > 0) {
+ const under = sample(cx, cy);
+ const here: [number, number, number] | null = under[3] > 0.02 ? [under[0] / under[3], under[1] / under[3], under[2] / under[3]] : null;
+ // It takes up a good share where it first touches, then a little with every dab, and its own paint slowly clears what it carries.
+ const pick = here ? (loaded ? wet * 0.09 : wet * 0.45) : 0;
+ const base: [number, number, number] = loaded ?? [r, g, bl];
+ const own = [r, g, bl];
+ loaded = [0, 1, 2].map((k) => {
+ const fed = base[k]! + (own[k]! - base[k]!) * 0.012;
+ return fed + ((here ? here[k]! : fed) - fed) * pick;
+ }) as [number, number, number];
+ [r, g, bl] = loaded;
+ }
+ const alpha = (startColor[3] + (endColor[3] - startColor[3]) * along) * (s.opacity ?? 1) * strand.strength * fading;
+ for (let y = y0; y <= y1; y++) {
+ for (let x = x0; x <= x1; x++) {
+ const v = cover(shaped(x + 0.5 - cx, y + 0.5 - cy)) * thin * alpha * toothOf(x + 0.5, y + 0.5);
+ const i = y * w + x;
+ const was = buffer.mask[i]!;
+ const next = flow > 0 ? was + v * flow * (1 - was) : v;
+ if (next <= was) continue;
+ if (was === 0) buffer.touched.push(i);
+ buffer.mask[i] = next;
+ buffer.rgb[i * 3] = r; buffer.rgb[i * 3 + 1] = g; buffer.rgb[i * 3 + 2] = bl;
+ }
+ }
+ }
+ }
+ if (distance >= end || total === 0) break;
+ // Narrow along its travel, a flat brush needs its dabs closer or they show.
+ distance = Math.min(end, distance + (spacing !== undefined ? Math.max(0.3, radius * 2 * spacing) : Math.max(0.4, radius * 0.1 * roundness)));
+ }
+ // Laid down all at once, so opacity is the stroke's and not the sum of its stamps.
+ const mode: Blend = s.blend ?? 'normal';
+ for (const i of buffer.touched) {
+ const covered = buffer.mask[i]!;
+ // Where a stroke thins out at its edge, the pigment that gathered there: darker at the rim and paler inside.
+ const v = edge > 0 ? Math.min(1, covered * (1 - edge * 0.45 * smoothed(Math.min(1, covered / (s.opacity ?? 1))) + edge * 1.1 * Math.max(0, 1 - Math.abs(covered / (s.opacity ?? 1) - 0.4) * 3))) : covered;
+ if (s.erase) for (let k = 0; k < 4; k++) c.px[i * 4 + k]! *= 1 - v;
+ else put(c, i, buffer.rgb[i * 3]!, buffer.rgb[i * 3 + 1]!, buffer.rgb[i * 3 + 2]!, v, mode);
+ buffer.mask[i] = 0;
+ }
+ buffer.touched.length = 0;
+}
+
+function paintStroke(c: Canvas, given: ImageStroke, m: Matrix, scale: number, n: number, buffer: StrokeBuffer): void {
+ if (!isWrapping()) { paintStrokeOnce(c, given, m, scale, n, buffer); return; }
+ const placed = given.points.map((p) => apply(m, [p[0]!, p[1]!]));
+ const reach = (given.size ?? 24) * scale * 2 + 4;
+ for (const [ox, oy] of ROUND) {
+ const [dx, dy] = [ox * c.w, oy * c.h];
+ if ((ox !== 0 || oy !== 0) && !touches(placed, dx, dy, reach, c.w, c.h)) continue;
+ // The same stroke, the same hairs: its number seeds it, so each copy is the one stroke seen again.
+ paintStrokeOnce(c, given, times([1, 0, 0, 1, dx, dy], m), scale, n, buffer);
+ }
+}
+
+function paintStrokeOnce(c: Canvas, given: ImageStroke, m: Matrix, scale: number, n: number, buffer: StrokeBuffer): void {
+ const s: ImageStroke = given.brush ? { ...IMAGE_BRUSHES[given.brush], ...given } : given;
+ const path = brushPath(s.points, m);
+ const seed = s.seed ?? n + 1;
+ const count = s.bristles ?? 1;
+ if (count === 1) {
+ paintStrand(c, s, path, { offset: 0, radius: null, from: 0, to: 1, shade: 1, strength: 1, seed }, scale, buffer);
+ return;
+ }
+ const spread = s.spread ?? 1;
+ const vary = s.vary ?? 0.15;
+ const radius = ((s.strand ?? Math.max(0.8, (s.size / count) * 2.2)) * scale) / 2;
+ for (let j = 0; j < count; j++) {
+ const pick = (k: number): number => hash01(seed * 131 + j, k);
+ paintStrand(c, s, path, {
+ // Even across the width and then shaken, so bristles neither clump nor stand in rows.
+ offset: (((j + pick(1)) / count) - 0.5) * spread,
+ radius,
+ from: pick(2) * 0.06,
+ to: 1 - pick(3) * 0.1,
+ shade: 1 + (pick(4) - 0.5) * 2 * vary,
+ strength: 1 - pick(5) * vary * 1.5,
+ seed: seed * 31 + j,
+ }, scale, buffer);
+ }
+}
+
+const channelHex = (v: number): string => Math.max(0, Math.min(255, Math.round(v * 255))).toString(16).padStart(2, '0');
+const toHex = (c: Rgba, shade = 1): string => `#${channelHex(c[0] * shade)}${channelHex(c[1] * shade)}${channelHex(c[2] * shade)}${channelHex(c[3])}`;
+
+/** A guide at evenly spaced places along its length, smooth through its points. */
+function resampled(guide: readonly (readonly number[])[], samples: number): { x: number; y: number; pressure: number }[] {
+ const path = brushPath(guide, IDENTITY);
+ const total = path[path.length - 1]!.along;
+ let index = 0;
+ return Array.from({ length: samples }, (_, i) => {
+ const at = (total * i) / (samples - 1);
+ while (index + 1 < path.length - 1 && path[index + 1]!.along < at) index++;
+ const [a, b] = [path[index]!, path[index + 1] ?? path[index]!];
+ const t = b.along > a.along ? Math.min(1, (at - a.along) / (b.along - a.along)) : 0;
+ return { x: a.x + (b.x - a.x) * t, y: a.y + (b.y - a.y) * t, pressure: a.pressure + (b.pressure - a.pressure) * t };
+ });
+}
+
+const SWEEP_SAMPLES = 14;
+
+/** Hairs between the guides. Each belongs to a lock and draws into it toward the tip, and a lock shares a shade, which is what makes a mass read as locks and not as combed lines. */
+const brushSettings = (s: ImageBrushSettings & { brush?: string }): Partial<ImageStroke> => {
+ const out: Record<string, unknown> = {};
+ for (const key of ['brush', 'roundness', 'angle', 'grain', 'grainScale', 'dry', 'wet', 'edge', 'scatter', 'dab', 'spacing', 'flow', 'fade'] as const) if (s[key as keyof typeof s] !== undefined) out[key] = s[key as keyof typeof s];
+ return out as Partial<ImageStroke>;
+};
+
+function sweepStrokes(s: ImageSweep): ImageStroke[] {
+ const guides = s.guides.map((g) => resampled(g, SWEEP_SAMPLES));
+ const seed = s.seed ?? 1;
+ const colors = s.colors.map(parseColor);
+ const tip = s.tip ? parseColor(s.tip) : null;
+ const clumps = s.clumps ?? Math.max(2, Math.round(s.count / 14));
+ const [gather, flyaway, vary, wobble] = [s.gather ?? 0.6, s.flyaway ?? 0.02, s.vary ?? 0.12, s.wobble ?? 1.5];
+ const colorAt = (u: number): Rgba => {
+ const at = Math.max(0, Math.min(0.9999, u)) * (colors.length - 1);
+ const [i, t] = [Math.floor(at), at - Math.floor(at)];
+ const [a, b] = [colors[i]!, colors[Math.min(colors.length - 1, i + 1)]!];
+ return [a[0] + (b[0] - a[0]) * t, a[1] + (b[1] - a[1]) * t, a[2] + (b[2] - a[2]) * t, a[3] + (b[3] - a[3]) * t];
+ };
+ const lockCentre = Array.from({ length: clumps }, (_, k) => (k + 0.2 + hash01(seed * 7 + k, 1) * 0.6) / clumps);
+ const lockShade = Array.from({ length: clumps }, (_, k) => 1 + (hash01(seed * 7 + k, 2) - 0.5) * vary * 2.5);
+ const out: ImageStroke[] = [];
+ for (let j = 0; j < s.count; j++) {
+ const pick = (k: number): number => hash01(seed * 131 + j, k);
+ const u = (j + pick(1)) / s.count;
+ const lock = Math.min(clumps - 1, Math.floor(u * clumps));
+ const strays = pick(2) < flyaway;
+ const [side, reach] = [pick(3) < 0.5 ? -1 : 1, 0.6 + pick(4) * 1.4];
+ const length = 1 - pick(5) * (strays ? 0.05 : 0.16);
+ const points: number[][] = [];
+ for (let i = 0; i < SWEEP_SAMPLES; i++) {
+ const t = (i / (SWEEP_SAMPLES - 1)) * length;
+ const draw = strays ? 0 : gather * t * t;
+ const where = (u + (lockCentre[lock]! - u) * draw) * (guides.length - 1);
+ const [g, f] = [Math.min(guides.length - 2, Math.floor(where)), where - Math.min(guides.length - 2, Math.floor(where))];
+ const at = (line: readonly { x: number; y: number }[]): [number, number] => {
+ const place = t * (SWEEP_SAMPLES - 1);
+ const [low, frac] = [Math.min(SWEEP_SAMPLES - 2, Math.floor(place)), place - Math.min(SWEEP_SAMPLES - 2, Math.floor(place))];
+ return [line[low]!.x + (line[low + 1]!.x - line[low]!.x) * frac, line[low]!.y + (line[low + 1]!.y - line[low]!.y) * frac];
+ };
+ const [ax, ay] = at(guides[g]!);
+ const [bx, by] = at(guides[g + 1]!);
+ const [x, y] = [ax + (bx - ax) * f, ay + (by - ay) * f];
+ const [cx, cy] = [bx - ax, by - ay];
+ const across = Math.hypot(cx, cy) || 1;
+ const shake = gradientNoise(t * 3.1, j * 0.73 + 0.5, seed) * wobble * 2 * t;
+ const stray = strays ? side * reach * t * t * (across * 0.5 + (s.size ?? 1.2) * 14) : 0;
+ points.push([Math.round((x + (cx / across) * (shake + stray)) * 100) / 100, Math.round((y + (cy / across) * (shake + stray)) * 100) / 100]);
+ }
+ const shade = lockShade[lock]! * (1 + (pick(6) - 0.5) * vary);
+ const root = colorAt(u + (pick(7) - 0.5) * 0.08);
+ const size = (s.size ?? 1.2) * (0.7 + pick(8) * 0.6);
+ out.push({
+ ...brushSettings(s),
+ points, size, ...(s.brush && s.hardness === undefined ? {} : { hardness: s.hardness ?? 0.7 }), color: toHex(root, shade),
+ ...(tip ? { to: toHex([root[0] + (tip[0] - root[0]) * 0.8, root[1] + (tip[1] - root[1]) * 0.8, root[2] + (tip[2] - root[2]) * 0.8, root[3]], shade) } : {}),
+ opacity: (s.opacity ?? (s.brush ? IMAGE_BRUSHES[s.brush]!.opacity ?? 1 : 1)) * (strays ? 0.55 : 0.75 + pick(9) * 0.25),
+ taper: s.taper ?? [0.04, 0.45],
+ });
+ }
+ return out;
+}
+
+/** Strokes across a region, following the guides or an angle. Each takes its colour from `tone` where it starts. */
+function fieldStrokes(s: ImageField, w: number, h: number, m: Matrix, drawn: Drawn, where: string): ImageStroke[] {
+ const seed = s.seed ?? 1;
+ const named = s.region?.startsWith('@') ? s.region.slice(1) : null;
+ const mask = named ? drawn.masks.get(named) : undefined;
+ if (named && !mask) {
+ drawn.notes.push(`${where}: a field's region "@${named}" names no layer drawn before it, so it drew nothing`);
+ return [];
+ }
+ const box = mask ? boxOf(w, h, (i) => mask[i]! >= 0.5) : null;
+ if (mask && !box) return [];
+ const regionRuns = s.region && !named ? parsePath(s.region).map((r) => r.points) : null;
+ const inside = (x: number, y: number): boolean => {
+ if (mask) {
+ const p = apply(m, [x, y]);
+ const [px, py] = [Math.floor(p[0]), Math.floor(p[1])];
+ return px >= 0 && py >= 0 && px < w && py < h && mask[py * w + px]! >= 0.5;
+ }
+ if (!regionRuns) return true;
+ let winding = 0;
+ for (const run of regionRuns) {
+ for (let i = 0; i < run.length; i++) {
+ const [a, b] = [run[i]!, run[(i + 1) % run.length]!];
+ if ((a[1] <= y) === (b[1] <= y)) continue;
+ const cross = (b[0] - a[0]) * (y - a[1]) - (x - a[0]) * (b[1] - a[1]);
+ if (b[1] > a[1] ? cross > 0 : cross < 0) winding += b[1] > a[1] ? 1 : -1;
+ }
+ }
+ return winding !== 0;
+ };
+ const back = invert(m);
+ const all = box
+ ? ([[box[0], box[1]], [box[0] + box[2], box[1]], [box[0], box[1] + box[3]], [box[0] + box[2], box[1] + box[3]]] as Pt[]).map((p) => apply(back, p))
+ : regionRuns ? regionRuns.flat() : [[0, 0], [w, h]] as Pt[];
+ const [x0, x1] = [Math.min(...all.map((p) => p[0])), Math.max(...all.map((p) => p[0]))];
+ const [y0, y1] = [Math.min(...all.map((p) => p[1])), Math.max(...all.map((p) => p[1]))];
+ const flow = (s.guides ?? []).flatMap((g) => {
+ const line = resampled(g, 24);
+ return line.slice(0, -1).map((p, i) => {
+ const q = line[i + 1]!;
+ const len = Math.hypot(q.x - p.x, q.y - p.y) || 1;
+ return { x: p.x, y: p.y, dx: (q.x - p.x) / len, dy: (q.y - p.y) / len };
+ });
+ });
+ const direction = (x: number, y: number): [number, number] => {
+ if (flow.length === 0) {
+ const r = ((s.angle ?? 0) * Math.PI) / 180;
+ return [Math.cos(r), Math.sin(r)];
+ }
+ let [dx, dy] = [0, 0];
+ for (const f of flow) {
+ const weight = 1 / (1 + ((x - f.x) ** 2 + (y - f.y) ** 2) ** 1.5);
+ dx += f.dx * weight; dy += f.dy * weight;
+ }
+ const len = Math.hypot(dx, dy) || 1;
+ return [dx / len, dy / len];
+ };
+ const toned = s.tone !== undefined && typeof s.tone !== 'string' && (s.tone.type === 'form' || s.tone.type === 'image') ? paintOf(s.tone, IDENTITY, drawn, w) : null;
+ const paint = toned ? (x: number, y: number): Rgba => { const p = apply(m, [x, y]); return toned(p[0], p[1]); } : s.tone !== undefined ? paintOf(s.tone, IDENTITY) : null;
+ const length = s.length ?? s.size * 3;
+ const count = Math.min(MAX_MARK_STROKES, Math.ceil(((s.coverage ?? 4) * Math.max(1, (x1 - x0) * (y1 - y0))) / (s.size * length)));
+ const spread = ((s.spread ?? 12) * Math.PI) / 180;
+ const vary = s.vary ?? 0.05;
+ const steps = 5;
+ const out: ImageStroke[] = [];
+ // One start in each cell of a grid, in shuffled order: wholly random starts leave holes, and starts in rows lay strokes over each other in rows.
+ const across = Math.max(1, Math.round(Math.sqrt((count * (x1 - x0 || 1)) / (y1 - y0 || 1))));
+ const down = Math.max(1, Math.ceil(count / across));
+ const order = Array.from({ length: across * down }, (_, i) => i).sort((a, b) => hash01(seed * 53 + a, 9) - hash01(seed * 53 + b, 9));
+ for (const j of order) {
+ const pick = (k: number): number => hash01(seed * 197 + j, k);
+ const [sx, sy] = [x0 + (((j % across) + pick(1)) / across) * (x1 - x0), y0 + ((Math.floor(j / across) + pick(2)) / down) * (y1 - y0)];
+ if (!inside(sx, sy)) continue;
+ const turn = (pick(3) - 0.5) * 2 * spread;
+ const points: number[][] = [];
+ const [back, forward] = [-length / 2, length / steps];
+ let [x, y] = [sx, sy];
+ const [d0x, d0y] = direction(sx, sy);
+ x += d0x * back; y += d0y * back;
+ for (let k = 0; k <= steps; k++) {
+ points.push([Math.round(x * 100) / 100, Math.round(y * 100) / 100]);
+ const [dx, dy] = direction(x, y);
+ const [rx, ry] = [dx * Math.cos(turn) - dy * Math.sin(turn), dx * Math.sin(turn) + dy * Math.cos(turn)];
+ x += rx * forward; y += ry * forward;
+ }
+ out.push({
+ ...brushSettings(s),
+ points, size: s.size * (0.75 + pick(4) * 0.5),
+ // A named brush keeps what it is, and only a field without one takes the soft defaults.
+ ...(s.brush ? {} : { hardness: s.hardness ?? 0.25, opacity: s.opacity ?? 0.6 }),
+ ...(s.brush && s.hardness !== undefined ? { hardness: s.hardness } : {}),
+ ...(s.brush && s.opacity !== undefined ? { opacity: s.opacity } : {}),
+ ...(s.smudge ? { smudge: s.smudge } : { color: toHex(paint!(sx, sy), 1 + (pick(5) - 0.5) * 2 * vary) }), taper: s.taper ?? [0.12, 0.3],
+ });
+ }
+ return out;
+}
+
+/** The strokes again along a line, each turned to the line's direction there and sized along it. */
+function alongStrokes(s: ImageAlong): ImageStroke[] {
+ const seed = s.seed ?? 1;
+ const line = resampled(s.line, Math.max(2, s.count));
+ const [from, to] = typeof s.scale === 'number' ? [s.scale, s.scale] : s.scale ?? [1, 1];
+ const jitter = s.jitter ?? 0;
+ const out: ImageStroke[] = [];
+ for (let i = 0; i < s.count; i++) {
+ const t = s.count === 1 ? 0 : i / (s.count - 1);
+ const p = line[i]!;
+ // Its direction from the next place along, and at the last from the one before.
+ const [from0, to0] = i + 1 < line.length ? [p, line[i + 1]!] : [line[i - 1]!, p];
+ const pick = (k: number): number => (hash01(seed * 89 + i, k) - 0.5) * 2 * jitter;
+ const scale = from + (to - from) * t;
+ const base = Math.atan2(to0.y - from0.y, to0.x - from0.x);
+ for (const side of s.both ? [1, -1] : [1]) {
+ const angle = base + (((s.turn ?? 0) * side + pick(1) * 0.1) * Math.PI) / 180;
+ const [cos, sin] = [Math.cos(angle), Math.sin(angle)];
+ const [ox, oy] = [p.x + pick(2), p.y + pick(3)];
+ for (const stroke of s.strokes) {
+ out.push({
+ ...stroke,
+ size: stroke.size * scale,
+ points: stroke.points.map((v) => {
+ const [x, y] = [v[0]! * scale, v[1]! * scale * side];
+ return [ox + x * cos - y * sin, oy + x * sin + y * cos, ...(v[2] !== undefined ? [v[2]] : [])];
+ }),
+ });
+ }
+ }
+ }
+ return out;
+}
+
+/** Hairs laid between lines closer than a few hairs' width do not read as hairs, and nothing else says so. */
+function sweepNote(s: ImageSweep, drawn: Drawn, where: string): void {
+ const size = s.size ?? 1.2;
+ const lines = s.guides.map((g) => resampled(g, 3)[1]!);
+ let span = 0;
+ for (let i = 0; i + 1 < lines.length; i++) span += Math.hypot(lines[i + 1]!.x - lines[i]!.x, lines[i + 1]!.y - lines[i]!.y);
+ if (span < size * 4 || s.count * size > span * 8 * Math.max(1, s.guides.length)) {
+ drawn.notes.push(`${where}: a sweep lays ${s.count} hairs of size ${size} across ${Math.round(span)} pixels, which fills it as a flat band; use fewer, thinner hairs or set the guides further apart`);
+ }
+}
+
+const expandMark = (mark: ImageMark, w: number, h: number, m: Matrix, drawn: Drawn, where: string): readonly ImageStroke[] => {
+ if (!('type' in mark)) return [mark];
+ if (mark.type === 'sweep') {
+ sweepNote(mark, drawn, where);
+ return sweepStrokes(mark);
+ }
+ return mark.type === 'along' ? alongStrokes(mark) : fieldStrokes(mark, w, h, m, drawn, where);
+};
+
+function drawPaint(c: Canvas, layer: ImageLayer, parent: Matrix, drawn: Drawn, opacity: number, blend: Blend, clip: Float32Array | undefined): void {
+ const { w, h } = c;
+ const m = times(parent, transformOf(layer.transform, [w / 2, h / 2]));
+ const inner = new Canvas(w, h);
+ if (layer.from === 'below') inner.px.set(c.px);
+ if (layer.fill !== undefined) {
+ const paint = paintOf(layer.fill, m, drawn, w);
+ for (let y = 0; y < h; y++) {
+ for (let x = 0; x < w; x++) {
+ const col = paint(x + 0.5, y + 0.5);
+ put(inner, y * w + x, col[0], col[1], col[2], col[3], 'normal');
+ }
+ }
+ }
+ const buffer: StrokeBuffer = { mask: new Float32Array(w * h), rgb: new Float32Array(w * h * 3), touched: [] };
+ let drawnStrokes = 0;
+ const onFace = layer.face ? faceCorners(layer, drawn) : null;
+ if (layer.face && !onFace) return;
+ const place = onFace ? unitToQuad(onFace) : null;
+ const lay = (points: readonly (readonly number[])[]): number[][] => points.map((p) => [...place!(p[0]!, p[1]!), ...p.slice(2)]);
+ const placed = (mark: ImageMark): ImageMark => {
+ if (!place) return mark;
+ if (!('type' in mark)) return { ...mark, points: lay(mark.points) };
+ if (mark.type === 'sweep') return { ...mark, guides: mark.guides.map(lay) };
+ if (mark.type === 'along') return { ...mark, line: lay(mark.line) };
+ return mark;
+ };
+ (layer.strokes ?? []).map(placed).forEach((mark) => {
+ for (const s of expandMark(mark, w, h, m, drawn, `layer ${layer.id ?? 'paint'}`)) paintStroke(inner, s, m, drawnScale(m), drawnStrokes++, buffer);
+ });
+ if (layer.id) drawn.painted.set(layer.id, { entries: (layer.strokes ?? []).length, strokes: drawnStrokes });
+ const alpha = new Float32Array(w * h);
+ for (let i = 0; i < alpha.length; i++) alpha[i] = inner.px[i * 4 + 3]!;
+ // What it holds is what its clip let through: what clips to it must not get out past that.
+ const held = clip ? alpha.map((v, i) => v * clip[i]!) : alpha;
+ if (layer.id) drawn.masks.set(layer.id, held);
+ noteBox(drawn, layer.id, held, w, h);
+ if (layer.from === 'below') {
+ // It already holds the picture, so it takes that picture's place and does not go over it.
+ for (let i = 0; i < alpha.length * 4; i++) {
+ const keep = opacity * (clip ? clip[Math.floor(i / 4)]! : 1);
+ c.px[i] = c.px[i]! + (inner.px[i]! - c.px[i]!) * keep;
+ }
+ return;
+ }
+ effectLayers(layer.effects, true, c, alpha);
+ for (let i = 0; i < alpha.length; i++) {
+ const a = alpha[i]!;
+ if (a <= 0) continue;
+ put(c, i, inner.px[i * 4]! / a, inner.px[i * 4 + 1]! / a, inner.px[i * 4 + 2]! / a, a * opacity * (clip ? clip[i]! : 1), blend);
+ }
+ effectLayers(layer.effects, false, c, alpha);
+}
+
+/** The blocks in plain grey, with the bones and a mark on each joint: enough to draw over, and nothing to be mistaken for the drawing. */
+function drawFigure(c: Canvas, layer: ImageLayer, parent: Matrix, drawn: Drawn, opacity: number, blend: Blend, clip: Float32Array | undefined): void {
+ const { w, h } = c;
+ if (!drawn.figure) throw new Error('this picture has a figure layer, and nothing here draws figures: it is baked where it is authored');
+ const figure = drawn.figure.flatten(layer, w, h, (p) => apply(parent, p), drawnScale(parent));
+ // Past the blocks a little way, so cloth that hangs off them is lit as what it hangs from.
+ const reach = Math.max(2, (layer.height as number) * 0.03);
+ const spread = blurMask(figure.mask, w, h, reach);
+ const extended = new Float32Array(figure.normals);
+ for (let k = 0; k < 3; k++) {
+ const channel = new Float32Array(w * h);
+ for (let i = 0; i < channel.length; i++) channel[i] = figure.normals[i * 3 + k]! * figure.mask[i]!;
+ const soft = blurMask(channel, w, h, reach);
+ for (let i = 0; i < channel.length; i++) if (figure.mask[i]! < 0.5 && spread[i]! > 0.01) extended[i * 3 + k] = soft[i]! / spread[i]!;
+ }
+ if (layer.id) {
+ drawn.figures.set(layer.id, { ...figure, normals: extended });
+ const held = (mask: Float32Array): Float32Array => (clip ? mask.map((v, i) => v * clip[i]!) : mask);
+ drawn.masks.set(layer.id, held(figure.mask));
+ noteBox(drawn, layer.id, held(figure.mask), w, h);
+ for (const [tag, mask] of Object.entries(figure.parts)) {
+ drawn.masks.set(`${layer.id}.${tag}`, held(mask));
+ noteBox(drawn, `${layer.id}.${tag}`, held(mask), w, h);
+ }
+ }
+ const [lx, ly, lz] = figure.light;
+ for (let i = 0; i < figure.mask.length; i++) {
+ const a = figure.mask[i]!;
+ if (a <= 0) continue;
+ const lit = 0.25 + 0.7 * Math.max(0, 0.5 + 0.5 * (figure.normals[i * 3]! * lx + figure.normals[i * 3 + 1]! * ly + figure.normals[i * 3 + 2]! * lz));
+ const line = 1 - figure.contour[i]! * 0.85;
+ put(c, i, lit * line * 0.92, lit * line * 0.94, lit * line, a * opacity * (clip ? clip[i]! : 1), blend);
+ }
+ const bones = strokeMask(figure.lines.map((points) => ({ closed: false, points })), 1.5, w, h);
+ for (let i = 0; i < bones.length; i++) put(c, i, 0.95, 0.35, 0.3, bones[i]! * 0.8 * opacity, 'normal');
+ for (const [x, y] of Object.values(figure.joints)) {
+ for (let dy = -2; dy <= 2; dy++) {
+ for (let dx = -2; dx <= 2; dx++) {
+ if (x + dx < 0 || y + dy < 0 || x + dx >= w || y + dy >= h || dx * dx + dy * dy > 5) continue;
+ put(c, (y + dy) * w + x + dx, 0.95, 0.2, 0.25, 0.85 * opacity, 'normal');
+ }
+ }
+ }
+ if (layer.id) drawn.figureJoints.set(layer.id, figure.joints);
+}
+
+/** Pixels a text is drawn at before it is laid on its corners: a font hinted small would not survive being stretched. */
+const QUAD_TEXT_SIZE = 96;
+
+/** The words drawn large and flat, cut to where they are, and looked up from each pixel of the corners they are laid on. */
+function textOnQuad(layer: ImageLayer, m: Matrix, w: number, h: number, draw: ImageTextDrawer): { fill: Float32Array; line: Float32Array | null } {
+ const count = [...(layer.text as string)].length;
+ const k = QUAD_TEXT_SIZE / (layer.fontSize ?? QUAD_TEXT_SIZE);
+ const long = Math.ceil(QUAD_TEXT_SIZE * 1.4 * (count + 1) + Math.abs(layer.tracking ?? 0) * k * count);
+ const across = QUAD_TEXT_SIZE * 2;
+ const [W, H] = layer.vertical ? [across, long] : [long, across];
+ const flat = draw({
+ ...layer, fontSize: QUAD_TEXT_SIZE, align: 'left', at: layer.vertical ? [across / 2, QUAD_TEXT_SIZE * 0.2] : [QUAD_TEXT_SIZE * 0.2, QUAD_TEXT_SIZE * 1.3],
+ ...(layer.tracking ? { tracking: layer.tracking * k } : {}), ...(layer.stroke ? { stroke: { ...layer.stroke, width: layer.stroke.width * k } } : {}),
+ }, IDENTITY, W, H);
+ const box = boxOf(W, H, (i) => flat.fill[i]! >= 0.5 || (flat.line ? flat.line[i]! >= 0.5 : false));
+ const out = { fill: new Float32Array(w * h), line: flat.line ? new Float32Array(w * h) : null };
+ const corners = layer.quad!.map((p) => apply(m, p as unknown as Pt));
+ const toUnit = quadToUnit(corners);
+ if (!box || !toUnit) return out;
+ const [x0, x1] = [Math.max(0, Math.floor(Math.min(...corners.map((p) => p[0])))), Math.min(w - 1, Math.ceil(Math.max(...corners.map((p) => p[0]))))];
+ const [y0, y1] = [Math.max(0, Math.floor(Math.min(...corners.map((p) => p[1])))), Math.min(h - 1, Math.ceil(Math.max(...corners.map((p) => p[1]))))];
+ const SAMPLES = 3;
+ for (let y = y0; y <= y1; y++) {
+ for (let x = x0; x <= x1; x++) {
+ let [f, l] = [0, 0];
+ for (let sy = 0; sy < SAMPLES; sy++) {
+ for (let sx = 0; sx < SAMPLES; sx++) {
+ const [u, v] = toUnit(x + (sx + 0.5) / SAMPLES, y + (sy + 0.5) / SAMPLES);
+ if (u < 0 || v < 0 || u >= 1 || v >= 1) continue;
+ const at = Math.floor(box[1] + v * box[3]) * W + Math.floor(box[0] + u * box[2]);
+ f += flat.fill[at]!;
+ if (flat.line) l += flat.line[at]!;
+ }
+ }
+ out.fill[y * w + x] = f / (SAMPLES * SAMPLES);
+ if (out.line) out.line[y * w + x] = l / (SAMPLES * SAMPLES);
+ }
+ }
+ return out;
+}
+
+/** What is bright in the picture so far, spilling over what is round it: a tight glow and a wide one, as a lens and the air both give. */
+function drawBloom(c: Canvas, layer: ImageLayer, parent: Matrix, opacity: number, clip: Float32Array | undefined): void {
+ const { w, h } = c;
+ const threshold = layer.threshold ?? 0.6;
+ const strength = (layer.strength ?? 1) * opacity;
+ const radius = ((layer.radius as number | undefined) ?? 10) * drawnScale(parent);
+ const bright = [new Float32Array(w * h), new Float32Array(w * h), new Float32Array(w * h)] as const;
+ const span = Math.max(0.001, 1 - threshold);
+ for (let i = 0; i < w * h; i++) {
+ const [r, g, b] = [c.px[i * 4]!, c.px[i * 4 + 1]!, c.px[i * 4 + 2]!];
+ const peak = Math.max(r, g, b);
+ if (peak <= threshold) continue;
+ // Its own colour, in proportion to how far over it is: only the brightest of a soft edge shines.
+ const over = smoothed(Math.min(1, (peak - threshold) / span));
+ bright[0][i] = r * over; bright[1][i] = g * over; bright[2][i] = b * over;
+ }
+ for (let k = 0; k < 3; k++) {
+ const [tight, wide] = [blurMask(bright[k]!, w, h, radius * 0.5), blurMask(bright[k]!, w, h, radius * 2.5)];
+ for (let i = 0; i < w * h; i++) {
+ const shine = Math.min(1, (tight[i]! * 0.7 + wide[i]! * 0.9) * strength) * (clip ? clip[i]! : 1);
+ if (shine <= 0) continue;
+ const at = i * 4;
+ c.px[at + k] = c.px[at + k]! + (1 - c.px[at + k]!) * shine;
+ if (shine > c.px[at + 3]!) c.px[at + 3] = shine;
+ }
+ }
+}
+
+/** Coverage with this many pixels taken off every edge: the lowest within reach, across and then down. */
+function thinned(mask: Float32Array, pixels: number, w: number, h: number): Float32Array {
+ const r = Math.round(pixels);
+ if (r <= 0) return mask;
+ const across = new Float32Array(w * h);
+ for (let y = 0; y < h; y++) {
+ for (let x = 0; x < w; x++) {
+ let low = 1;
+ for (let d = -r; d <= r; d++) {
+ const at = x + d;
+ const v = at < 0 || at >= w ? 0 : mask[y * w + at]!;
+ if (v < low) low = v;
+ }
+ across[y * w + x] = low;
+ }
+ }
+ const out = new Float32Array(w * h);
+ for (let x = 0; x < w; x++) {
+ for (let y = 0; y < h; y++) {
+ let low = 1;
+ for (let d = -r; d <= r; d++) {
+ const at = y + d;
+ const v = at < 0 || at >= h ? 0 : across[at * w + x]!;
+ if (v < low) low = v;
+ }
+ out[y * w + x] = low;
+ }
+ }
+ return out;
+}
+
+/** Letters worn as a brush wears a stroke, by the same paper and in streaks across them. */
+function wornText(mask: Float32Array, layer: ImageLayer, w: number): Float32Array {
+ const [grain, dry] = [layer.grain ?? 0, layer.dry ?? 0];
+ if (grain <= 0 && dry <= 0) return mask;
+ const scale = layer.grainScale ?? 2;
+ return mask.map((v, i) => {
+ if (v <= 0) return 0;
+ const [x, y] = [(i % w) + 0.5, Math.floor(i / w) + 0.5];
+ let kept = v;
+ if (grain > 0) kept *= Math.max(0, Math.min(1, (fractalNoise(x / scale, y / scale, 3, 77) - (0.12 + grain * 0.62)) / 0.34 + 0.5));
+ if (dry > 0) kept *= Math.max(0, Math.min(1, (0.5 + 1.3 * gradientNoise(x / 40, y / 1.8, 9) - (0.12 + dry * 0.68)) / 0.22 + 0.5));
+ return kept;
+ });
+}
+
+/** A mask made wider by @p pixels, or narrower if they are less than none: the highest or lowest within reach, across and then down. */
+function grownMask(mask: Float32Array, pixels: number, w: number, h: number): Float32Array {
+ const r = Math.round(Math.abs(pixels));
+ if (r === 0) return mask;
+ const pick = pixels > 0 ? Math.max : Math.min;
+ const across = new Float32Array(w * h);
+ for (let y = 0; y < h; y++) {
+ for (let x = 0; x < w; x++) {
+ let v = mask[y * w + x]!;
+ for (let d = -r; d <= r; d++) { const at = x + d; v = pick(v, at < 0 || at >= w ? (pixels > 0 ? 0 : v) : mask[y * w + at]!); }
+ across[y * w + x] = v;
+ }
+ }
+ const out = new Float32Array(w * h);
+ for (let x = 0; x < w; x++) {
+ for (let y = 0; y < h; y++) {
+ let v = across[y * w + x]!;
+ for (let d = -r; d <= r; d++) { const at = y + d; v = pick(v, at < 0 || at >= h ? (pixels > 0 ? 0 : v) : across[at * w + x]!); }
+ out[y * w + x] = v;
+ }
+ }
+ return out;
+}
+
+function drawText(c: Canvas, layer: ImageLayer, parent: Matrix, drawn: Drawn, opacity: number, blend: Blend, clip: Float32Array | undefined): void {
+ const { w, h } = c;
+ if (!drawn.text) throw new Error(`layer ${layer.id ?? 'text'}: text needs the editor's fonts, and this render has none`);
+ const m = times(parent, transformOf(layer.transform, (layer.at ?? [0, 0]) as Pt));
+ const corners = layer.face ? faceCorners(layer, drawn) : layer.quad;
+ if (layer.face && !corners) return;
+ const drawnText = corners ? textOnQuad({ ...layer, quad: corners }, m, w, h, drawn.text) : drawn.text(layer, m, w, h);
+ const line = drawnText.line;
+ const fill = wornText(thinned(drawnText.fill, (layer.thin ?? 0) * drawnScale(m), w, h), layer, w);
+ const whole = new Float32Array(w * h);
+ for (let i = 0; i < whole.length; i++) whole[i] = Math.max(layer.fill !== undefined ? fill[i]! : 0, line ? line[i]! : 0) * (clip ? clip[i]! : 1);
+ if (layer.id) drawn.masks.set(layer.id, whole);
+ noteBox(drawn, layer.id, whole, w, h);
+ effectLayers(layer.effects, true, c, whole);
+ const lay = (mask: Float32Array, paint: (x: number, y: number) => Rgba): void => {
+ for (let y = 0; y < h; y++) {
+ for (let x = 0; x < w; x++) {
+ const i = y * w + x;
+ const v = mask[i]! * (clip ? clip[i]! : 1);
+ if (v <= 0) continue;
+ const col = paint(x + 0.5, y + 0.5);
+ put(c, i, col[0], col[1], col[2], v * col[3] * opacity, blend);
+ }
+ }
+ };
+ if (line && layer.stroke) lay(line, paintOf(layer.stroke.color, m, drawn, w));
+ if (layer.fill !== undefined) lay(fill, paintOf(layer.fill, m, drawn, w));
+ effectLayers(layer.effects, false, c, whole);
+}
+
+/** A building's visible faces, from the corner nearest the viewer toward the vanishing points. Each is a layer of its own to clip to. */
+function drawBlock(c: Canvas, layer: ImageLayer, parent: Matrix, drawn: Drawn): void {
+ const [bx, by] = layer.at as Pt;
+ const top = by - (layer.height as number);
+ const toward = (x: number, y: number, v: readonly number[], t: number): number[] => [x + (v[0]! - x) * t, y + (v[1]! - y) * t];
+ const quads: Record<string, readonly (readonly number[])[]> = {};
+ const names = ['a', 'b'];
+ const common: Partial<ImageLayer> = { ...(layer.opacity !== undefined ? { opacity: layer.opacity } : {}), ...(layer.blend ? { blend: layer.blend } : {}), ...(layer.clip ? { clip: layer.clip } : {}), ...(layer.except ? { except: layer.except } : {}), ...(layer.stroke ? { stroke: layer.stroke } : {}) };
+ const faces: ImageLayer[] = (layer.vanish ?? []).map((v, n) => {
+ const t = layer.depth![n]!;
+ const [tx, ty] = toward(bx, top, v, t);
+ const [fx, fy] = toward(bx, by, v, t);
+ // Top left, top right, bottom right, bottom left, as seen: the far edge is on whichever side it recedes to.
+ const quad = v[0]! < bx ? [[tx, ty], [bx, top], [bx, by], [fx, fy]] : [[bx, top], [tx, ty], [fx, fy], [bx, by]];
+ quads[names[n]!] = quad;
+ const given = layer.faces![n]!;
+ const fill = typeof given !== 'string' && given.type === 'grid' && !given.quad ? { ...given, quad } : given;
+ return { ...common, ...(layer.id ? { id: `${layer.id}.${names[n]}` } : {}), shape: 'polygon', points: quad as [number, number][], fill } as ImageLayer;
+ });
+ // A roof shows only from above, which is when the top is below the line the vanishing points are on.
+ const vanish = layer.vanish ?? [];
+ if (layer.roof !== undefined && vanish[0]![1]! < top) {
+ const near: number[] = [bx, top];
+ const [p, q] = [toward(bx, top, vanish[0]!, layer.depth![0]!), vanish[1] ? toward(bx, top, vanish[1], layer.depth![1]!) : null];
+ const roof = q && vanish[1]
+ ? [near, p, (() => {
+ // Where the lines from each far corner to the other vanishing point meet.
+ const [a, b, cc, d] = [p, vanish[1]!, q, vanish[0]!];
+ const den = (a[0]! - b[0]!) * (cc[1]! - d[1]!) - (a[1]! - b[1]!) * (cc[0]! - d[0]!);
+ if (Math.abs(den) < 1e-6) return a;
+ const k = ((a[0]! - cc[0]!) * (cc[1]! - d[1]!) - (a[1]! - cc[1]!) * (cc[0]! - d[0]!)) / den;
+ return [a[0]! + k * (b[0]! - a[0]!), a[1]! + k * (b[1]! - a[1]!)];
+ })(), q]
+ : null;
+ if (roof) {
+ quads.top = roof;
+ faces.unshift({ ...common, ...(layer.id ? { id: `${layer.id}.top` } : {}), shape: 'polygon', points: roof as [number, number][], fill: layer.roof } as ImageLayer);
+ }
+ }
+ for (const face of faces) drawLayer(c, face, parent, drawn);
+ if (layer.id) {
+ drawn.blocks.set(layer.id, Object.fromEntries(Object.entries(quads).map(([k, q]) => [k, q.map((p) => { const a = apply(parent, p as unknown as Pt); return [Math.round(a[0]), Math.round(a[1])]; })])));
+ const whole = new Float32Array(c.w * c.h);
+ for (const key of Object.keys(quads)) {
+ const mask = drawn.masks.get(`${layer.id}.${key}`);
+ if (mask) for (let i = 0; i < whole.length; i++) whole[i] = Math.max(whole[i]!, mask[i]!);
+ }
+ drawn.masks.set(layer.id, whole);
+ noteBox(drawn, layer.id, whole, c.w, c.h);
+ }
+}
+
+/** Lines running out from each vanishing point, to build along. A guide. */
+function drawPerspective(c: Canvas, layer: ImageLayer, parent: Matrix, opacity: number): void {
+ const { w, h } = c;
+ const reach = Math.hypot(w, h);
+ const lines = (layer.vanish ?? []).flatMap((v) => Array.from({ length: 24 }, (_, i) => {
+ const a = (i / 24) * Math.PI * 2;
+ const from = apply(parent, [v[0]!, v[1]!]);
+ return { closed: false, points: [from, [from[0] + Math.cos(a) * reach, from[1] + Math.sin(a) * reach]] as Pt[] };
+ }));
+ const horizon = (layer.vanish ?? [])[0];
+ if (horizon) lines.push({ closed: false, points: [apply(parent, [-w, horizon[1]!]), apply(parent, [w * 2, horizon[1]!])] });
+ const mask = strokeMask(lines, 1, w, h);
+ for (let i = 0; i < mask.length; i++) put(c, i, 0.3, 0.9, 1, mask[i]! * 0.55 * opacity, 'normal');
+}
+
+/** What is above a line, turned over below it: a wet street or still water. It wavers side to side, longer toward the viewer, and fades as it reaches. */
+function drawReflection(c: Canvas, layer: ImageLayer, parent: Matrix, drawn: Drawn, opacity: number, clip: Float32Array | undefined): void {
+ const { w, h } = c;
+ const k = drawnScale(parent);
+ // Where each column turns over: things in perspective stand on a slanting line, and a level one would not meet their feet.
+ const lineAt = new Float32Array(w);
+ const edge = layer.edge?.map((p) => apply(parent, p as unknown as Pt)).sort((a, b) => a[0] - b[0]);
+ for (let x = 0; x < w; x++) {
+ if (!edge) { lineAt[x] = apply(parent, [0, layer.y as number])[1]; continue; }
+ let i = 0;
+ while (i + 2 < edge.length && edge[i + 1]![0] < x + 0.5) i++;
+ const [a, b] = [edge[i]!, edge[i + 1]!];
+ const t = b[0] === a[0] ? 0 : Math.max(0, Math.min(1, (x + 0.5 - a[0]) / (b[0] - a[0])));
+ lineAt[x] = a[1] + (b[1] - a[1]) * t;
+ }
+ const reach = (layer.reach ?? h) * k;
+ const ripple = (layer.ripple ?? 3) * k;
+ const seed = 11;
+ const out = new Float32Array(w * h * 4);
+ for (let y = 0; y < h; y++) {
+ for (let x = 0; x < w; x++) {
+ const depth = y + 0.5 - lineAt[x]!;
+ if (depth < 0 || depth >= reach) continue;
+ const from = Math.floor(lineAt[x]! - depth);
+ if (from < 0) continue;
+ const swing = ripple * (depth / reach + 0.2);
+ const shift = gradientNoise(x / 90, y / 3.5, seed) * swing * 2.4 + gradientNoise(x / 22, y / 1.6, seed + 1) * swing;
+ const sx = Math.max(0, Math.min(w - 1, Math.round(x + shift)));
+ const [to, at] = [(y * w + x) * 4, (from * w + sx) * 4];
+ for (let n = 0; n < 4; n++) out[to + n] = c.px[at + n]!;
+ }
+ }
+ const smear = (layer.smear ?? 2) * k;
+ const channels = [0, 1, 2, 3].map((n) => {
+ const channel = new Float32Array(w * h);
+ for (let i = 0; i < channel.length; i++) channel[i] = out[i * 4 + n]!;
+ return smear > 0 ? blurMask(channel, w, h, smear) : channel;
+ }) as [Float32Array, Float32Array, Float32Array, Float32Array];
+ const mask = new Float32Array(w * h);
+ for (let y = 0; y < h; y++) {
+ for (let x = 0; x < w; x++) {
+ const depth = y + 0.5 - lineAt[x]!;
+ if (depth < 0) continue;
+ const fading = Math.max(0, 1 - depth / reach);
+ const i = y * w + x;
+ const a = channels[3][i]!;
+ mask[i] = a * fading * (clip ? clip[i]! : 1);
+ if (a <= 0 || mask[i]! <= 0) continue;
+ put(c, i, channels[0][i]! / a, channels[1][i]! / a, channels[2][i]! / a, mask[i]! * opacity, layer.blend ?? 'normal');
+ }
+ }
+ if (layer.id) drawn.masks.set(layer.id, mask);
+ noteBox(drawn, layer.id, mask, w, h);
+}
+
+/** A picture from the project, smoothly scaled to where it goes. */
+function drawPicture(c: Canvas, layer: ImageLayer, parent: Matrix, drawn: Drawn, opacity: number, blend: Blend, clip: Float32Array | undefined): void {
+ const { w, h } = c;
+ const picture = drawn.pictures[layer.src!];
+ if (!picture) throw new Error(`there is no picture at ${layer.src}`);
+ const [ox, oy] = apply(parent, layer.at ?? [0, 0]);
+ const k = drawnScale(parent);
+ const [dw, dh] = (layer.size ?? [picture.width, picture.height]).map((v) => v * k) as [number, number];
+ const out = new Float32Array(w * h * 4);
+ const mask = new Float32Array(w * h);
+ for (let y = Math.max(0, Math.floor(oy)); y < Math.min(h, Math.ceil(oy + dh)); y++) {
+ for (let x = Math.max(0, Math.floor(ox)); x < Math.min(w, Math.ceil(ox + dw)); x++) {
+ const [u, v] = [((x + 0.5 - ox) / dw) * picture.width - 0.5, ((y + 0.5 - oy) / dh) * picture.height - 0.5];
+ if (u < -0.5 || v < -0.5 || u > picture.width - 0.5 || v > picture.height - 0.5) continue;
+ const [x0, y0] = [Math.max(0, Math.floor(u)), Math.max(0, Math.floor(v))];
+ const [x1, y1] = [Math.min(picture.width - 1, x0 + 1), Math.min(picture.height - 1, y0 + 1)];
+ const [fx, fy] = [Math.max(0, u - x0), Math.max(0, v - y0)];
+ const i = y * w + x;
+ for (let n = 0; n < 4; n++) {
+ const at = (px: number, py: number): number => picture.rgba[(py * picture.width + px) * 4 + n]! / 255;
+ out[i * 4 + n] = (at(x0, y0) * (1 - fx) + at(x1, y0) * fx) * (1 - fy) + (at(x0, y1) * (1 - fx) + at(x1, y1) * fx) * fy;
+ }
+ mask[i] = out[i * 4 + 3]!;
+ }
+ }
+ if (layer.id) {
+ drawn.images.set(layer.id, out);
+ const held = clip ? mask.map((v, i) => v * clip[i]!) : mask;
+ drawn.masks.set(layer.id, held);
+ noteBox(drawn, layer.id, held, w, h);
+ }
+ for (let i = 0; i < mask.length; i++) {
+ if (mask[i]! > 0) put(c, i, out[i * 4]!, out[i * 4 + 1]!, out[i * 4 + 2]!, mask[i]! * opacity * (clip ? clip[i]! : 1), blend);
+ }
+}
+
+function drawPixels(c: Canvas, layer: ImageLayer, parent: Matrix, drawn: Drawn, opacity: number, blend: Blend, clip: Float32Array | undefined): void {
+ const { w, h } = c;
+ const rows = layer.rows!;
+ const columns = Math.max(...rows.map((r) => r.length));
+ const scale = (layer.scale ?? Math.max(1, Math.floor(Math.min(w / columns, h / rows.length)))) * drawnScale(parent);
+ const [ax, ay] = layer.at ? apply(parent, layer.at) : [(w - columns * scale) / 2, (h - rows.length * scale) / 2];
+ const palette = new Map(Object.entries(layer.palette ?? {}).map(([k, v]) => [k, parseColor(v)]));
+ const whole = new Float32Array(w * h);
+ const colors = new Float32Array(w * h * 3);
+ rows.forEach((row, ry) => {
+ [...row].forEach((ch, rx) => {
+ const col = palette.get(ch);
+ if (!col) return;
+ for (let y = Math.max(0, Math.round(ay + ry * scale)); y < Math.min(h, Math.round(ay + (ry + 1) * scale)); y++) {
+ for (let x = Math.max(0, Math.round(ax + rx * scale)); x < Math.min(w, Math.round(ax + (rx + 1) * scale)); x++) {
+ whole[y * w + x] = col[3] * (clip ? clip[y * w + x]! : 1);
+ colors[(y * w + x) * 3] = col[0]; colors[(y * w + x) * 3 + 1] = col[1]; colors[(y * w + x) * 3 + 2] = col[2];
+ }
+ }
+ });
+ });
+ if (layer.id) drawn.masks.set(layer.id, whole);
+ noteBox(drawn, layer.id, whole, w, h);
+ effectLayers(layer.effects, true, c, whole);
+ for (let i = 0; i < whole.length; i++) put(c, i, colors[i * 3]!, colors[i * 3 + 1]!, colors[i * 3 + 2]!, whole[i]! * opacity, blend);
+ effectLayers(layer.effects, false, c, whole);
+}
+
+/** A picture part-way through: what it costs to draw is what a small edit should not pay again. */
+interface Snapshot { px: Float32Array; drawn: Omit<Drawn, 'showGuides' | 'pictures' | 'text'> }
+const snapshots = new Map<string, Snapshot>();
+const SNAPSHOT_AFTER_MS = 150;
+const SNAPSHOT_BYTES = 512 * 1024 * 1024;
+const cacheCounters = { drawn: 0, reused: 0 };
+
+/** How many layers were drawn and how many were picked up already drawn; `clear` forgets what is kept. */
+export function imageCacheStats(clear = false): { drawn: number; reused: number; kept: number } {
+ const out = { ...cacheCounters, kept: snapshots.size };
+ if (clear) { snapshots.clear(); cacheCounters.drawn = 0; cacheCounters.reused = 0; }
+ return out;
+}
+
+function textHash(text: string): string {
+ let [a, b] = [0xdeadbeef, 0x41c6ce57];
+ for (let i = 0; i < text.length; i++) {
+ const ch = text.charCodeAt(i);
+ a = Math.imul(a ^ ch, 2654435761);
+ b = Math.imul(b ^ ch, 1597334677);
+ }
+ return (((a ^ (a >>> 16)) >>> 0).toString(36)) + ((b ^ (b >>> 13)) >>> 0).toString(36) + text.length.toString(36);
+}
+
+/** Pictures come from files that change under the same name, so what is in them is part of the key. */
+function picturesDigest(pictures: Readonly<Record<string, RgbaBitmap>> | undefined): string {
+ if (!pictures) return '';
+ return Object.entries(pictures).map(([name, p]) => {
+ let sum = 0;
+ for (let i = 0; i < p.rgba.length; i += 97) sum = (Math.imul(sum, 31) + p.rgba[i]!) | 0;
+ return `${name}:${p.width}x${p.height}:${sum}`;
+ }).join('|');
+}
+
+/** Masks and the rest are never written once set, so a snapshot can hold them as they are. */
+function keepSnapshot(key: string, canvas: Canvas, drawn: Drawn): void {
+ snapshots.set(key, {
+ px: canvas.px.slice(),
+ drawn: {
+ masks: new Map(drawn.masks), notes: [...drawn.notes], bounds: new Map(drawn.bounds), painted: new Map(drawn.painted), figures: new Map(drawn.figures),
+ figureJoints: new Map(drawn.figureJoints), images: new Map(drawn.images), blocks: new Map(drawn.blocks),
+ },
+ });
+ let bytes = 0;
+ for (const s of snapshots.values()) bytes += s.px.byteLength;
+ for (const [k, s] of snapshots) {
+ if (bytes <= SNAPSHOT_BYTES) break;
+ snapshots.delete(k);
+ bytes -= s.px.byteLength;
+ }
+}
+
+function restoreSnapshot(kept: Snapshot, canvas: Canvas, drawn: Drawn): void {
+ canvas.px.set(kept.px);
+ drawn.masks = new Map(kept.drawn.masks); drawn.notes = [...kept.drawn.notes]; drawn.bounds = new Map(kept.drawn.bounds); drawn.painted = new Map(kept.drawn.painted);
+ drawn.figures = new Map(kept.drawn.figures); drawn.figureJoints = new Map(kept.drawn.figureJoints); drawn.images = new Map(kept.drawn.images); drawn.blocks = new Map(kept.drawn.blocks);
+}
+
+export interface RenderedImage extends RgbaBitmap {
+ notes: string[];
+ /** Where the picture is solid, null if nowhere, and how much of its area that is, 0..1: how large it looks beside others. */
+ bounds: ImageBox | null;
+ covers: number;
+ /** The same box for each layer with an id, after every transform, without its effects. */
+ layerBounds: Record<string, ImageBox>;
+ /** For each paint layer with an id: its entries, which `drop` counts, and the strokes they came to. */
+ painted: Record<string, { entries: number; strokes: number }>;
+ /** For each figure with an id: where its joints landed in the picture. */
+ figures: Record<string, Record<string, readonly [number, number]>>;
+ /** For each block with an id: its faces' corners in the picture, to place things on. */
+ blocks: Record<string, Record<string, readonly (readonly number[])[]>>;
+}
+
+/** Draws a source that has been validated. */
+export function renderImage(source: ImageSource, options: { guides?: boolean; pictures?: Readonly<Record<string, RgbaBitmap>>; text?: ImageTextDrawer; figure?: ImageFigureDrawer } = {}): RenderedImage {
+ const [w, h] = typeof source.size === 'number' ? [source.size, source.size] : source.size;
+ const canvas = new Canvas(w, h);
+ const drawn: Drawn = { figure: options.figure, masks: new Map(), notes: [], bounds: new Map(), painted: new Map(), figures: new Map(), figureJoints: new Map(), showGuides: options.guides === true, pictures: options.pictures ?? {}, images: new Map(), text: options.text, blocks: new Map() };
+ // What every layer so far amounts to, chained: a layer changed leaves the keys before it as they were.
+ let key = textHash(JSON.stringify([w, h, source.background ?? null, options.guides === true, picturesDigest(options.pictures), source.tile === true]));
+ const keys = source.layers.map((layer) => (key = textHash(key + JSON.stringify(layer))));
+ let from = 0;
+ for (let i = keys.length - 1; i >= 0; i--) {
+ const kept = snapshots.get(keys[i]!);
+ if (!kept) continue;
+ restoreSnapshot(kept, canvas, drawn);
+ // Used last, kept longest.
+ snapshots.delete(keys[i]!);
+ snapshots.set(keys[i]!, kept);
+ from = i + 1;
+ cacheCounters.reused += from;
+ break;
+ }
+ if (from === 0 && source.background) {
+ const [r, g, b, a] = parseColor(source.background);
+ for (let i = 0; i < w * h; i++) put(canvas, i, r, g, b, a, 'normal');
+ }
+ let since = Date.now();
+ // Set for this draw only, and taken off whatever happens: the next picture drawn may not repeat.
+ setWrapping(source.tile === true);
+ [tileWidth, tileHeight] = [w, h];
+ try {
+ for (let i = from; i < source.layers.length; i++) {
+ drawLayer(canvas, source.layers[i]!, IDENTITY, drawn);
+ cacheCounters.drawn++;
+ if (i === source.layers.length - 1 || Date.now() - since >= SNAPSHOT_AFTER_MS) {
+ keepSnapshot(keys[i]!, canvas, drawn);
+ since = Date.now();
+ }
+ }
+ } finally {
+ setWrapping(false);
+ }
+ const rgba = new Uint8Array(w * h * 4);
+ for (let i = 0; i < w * h; i++) {
+ const a = canvas.px[i * 4 + 3]!;
+ const d = a > 1e-5 ? 1 / a : 0;
+ rgba[i * 4] = Math.round(Math.min(1, canvas.px[i * 4]! * d) * 255);
+ rgba[i * 4 + 1] = Math.round(Math.min(1, canvas.px[i * 4 + 1]! * d) * 255);
+ rgba[i * 4 + 2] = Math.round(Math.min(1, canvas.px[i * 4 + 2]! * d) * 255);
+ rgba[i * 4 + 3] = Math.round(Math.min(1, a) * 255);
+ }
+ let solid = 0;
+ for (let i = 0; i < w * h; i++) if (rgba[i * 4 + 3]! >= 128) solid++;
+ return {
+ width: w, height: h, rgba, notes: drawn.notes,
+ bounds: boxOf(w, h, (i) => rgba[i * 4 + 3]! >= 128),
+ covers: Math.round((solid / (w * h)) * 1000) / 1000,
+ layerBounds: Object.fromEntries(drawn.bounds),
+ painted: Object.fromEntries(drawn.painted),
+ figures: Object.fromEntries(drawn.figureJoints),
+ blocks: Object.fromEntries(drawn.blocks),
+ };
+}
+
+function shrink(src: RgbaBitmap, width: number, height: number): RgbaBitmap {
+ // Averaged by alpha: a transparent pixel's colour must not bleed into the edge beside it.
+ const rgba = new Uint8Array(width * height * 4);
+ for (let y = 0; y < height; y++) {
+ const [y0, y1] = [Math.floor((y * src.height) / height), Math.max(Math.floor((y * src.height) / height) + 1, Math.floor(((y + 1) * src.height) / height))];
+ for (let x = 0; x < width; x++) {
+ const [x0, x1] = [Math.floor((x * src.width) / width), Math.max(Math.floor((x * src.width) / width) + 1, Math.floor(((x + 1) * src.width) / width))];
+ let [r, g, b, a, n] = [0, 0, 0, 0, 0];
+ for (let sy = y0; sy < y1; sy++) {
+ for (let sx = x0; sx < x1; sx++) {
+ const at = (sy * src.width + sx) * 4;
+ const al = src.rgba[at + 3]!;
+ r += src.rgba[at]! * al; g += src.rgba[at + 1]! * al; b += src.rgba[at + 2]! * al; a += al; n++;
+ }
+ }
+ const to = (y * width + x) * 4;
+ if (a > 0) { rgba[to] = r / a; rgba[to + 1] = g / a; rgba[to + 2] = b / a; }
+ rgba[to + 3] = a / n;
+ }
+ }
+ return { width, height, rgba };
+}
+
+type Ground = (x: number, y: number) => readonly [number, number, number];
+/** Between dark and light, so a dark outline and a pale highlight both show. On a near-black ground the outline a small icon wants disappears. */
+const midGround: Ground = () => [104, 112, 128];
+const checkGround: Ground = (x, y) => ((Math.floor(x / 12) + Math.floor(y / 12)) % 2 ? [226, 226, 230] : [250, 250, 252]);
+
+function layOn(rgba: Uint8Array, W: number, pic: RgbaBitmap, ox: number, oy: number, ground: Ground): void {
+ for (let y = 0; y < pic.height; y++) {
+ for (let x = 0; x < pic.width; x++) {
+ const from = (y * pic.width + x) * 4;
+ const a = pic.rgba[from + 3]! / 255;
+ const g = ground(x, y);
+ const to = ((oy + y) * W + ox + x) * 4;
+ rgba[to] = pic.rgba[from]! * a + g[0] * (1 - a);
+ rgba[to + 1] = pic.rgba[from + 1]! * a + g[1] * (1 - a);
+ rgba[to + 2] = pic.rgba[from + 2]! * a + g[2] * (1 - a);
+ rgba[to + 3] = 255;
+ }
+ }
+}
+
+const SHEET_GROUND = [64, 64, 68, 255] as const;
+
+function solidSheet(W: number, H: number): Uint8Array {
+ const rgba = new Uint8Array(W * H * 4);
+ for (let i = 0; i < W * H; i++) rgba.set(SHEET_GROUND, i * 4);
+ return rgba;
+}
+
+const fitted = (image: RgbaBitmap, size: number): RgbaBitmap => {
+ const k = size / Math.max(image.width, image.height);
+ const [w, h] = [Math.max(1, Math.round(image.width * k)), Math.max(1, Math.round(image.height * k))];
+ return k >= 1 ? nearestScale(image, w, h) : shrink(image, w, h);
+};
+
+/** Several pictures on one sheet, to be judged as a set: each on the mid ground and the check, then at 64 and 32, column by column. */
+export function setSheet(images: readonly RgbaBitmap[], cell = 128): RgbaBitmap {
+ if (images.length === 0) throw new Error('a set needs at least one picture');
+ const gap = 8;
+ const columns = Math.min(8, images.length);
+ const rows = Math.ceil(images.length / columns);
+ const tall = cell * 2 + 64 + 32 + gap * 5;
+ const W = columns * (cell + gap) + gap, H = rows * tall;
+ const rgba = solidSheet(W, H);
+ images.forEach((image, n) => {
+ const [ox, oy] = [gap + (n % columns) * (cell + gap), Math.floor(n / columns) * tall + gap];
+ const big = fitted(image, cell);
+ layOn(rgba, W, big, ox, oy, midGround);
+ layOn(rgba, W, big, ox, oy + cell + gap, checkGround);
+ layOn(rgba, W, fitted(image, 64), ox, oy + cell * 2 + gap * 2, midGround);
+ layOn(rgba, W, fitted(image, 32), ox, oy + cell * 2 + 64 + gap * 3, midGround);
+ });
+ return { width: W, height: H, rgba };
+}
+
+/** A part of a picture enlarged with hard pixels on the check, to see what the whole hides: a seam one pixel wide. */
+export function zoomImage(image: RgbaBitmap, region: { x: number; y: number; w: number; h: number }, longest = 1024): RgbaBitmap {
+ const [x0, y0] = [Math.max(0, Math.floor(region.x)), Math.max(0, Math.floor(region.y))];
+ const [w, h] = [Math.min(image.width - x0, Math.round(region.w)), Math.min(image.height - y0, Math.round(region.h))];
+ if (!(w > 0 && h > 0)) throw new Error(`region ${JSON.stringify(region)} is outside the picture, ${image.width} by ${image.height}`);
+ const cut = new Uint8Array(w * h * 4);
+ for (let y = 0; y < h; y++) cut.set(image.rgba.subarray(((y0 + y) * image.width + x0) * 4, ((y0 + y) * image.width + x0 + w) * 4), y * w * 4);
+ const k = Math.max(1, Math.floor(longest / Math.max(w, h)));
+ const big = nearestScale({ width: w, height: h, rgba: cut }, w * k, h * k);
+ const rgba = solidSheet(big.width, big.height);
+ layOn(rgba, big.width, big, 0, 0, checkGround);
+ return { width: big.width, height: big.height, rgba };
+}
+
+/** Something to look at: the picture on a mid ground and on a light check, as a transparent image needs both, and at the sizes an icon is really seen. */
+export function imageSheet(image: RgbaBitmap, sizes: readonly number[] = [96, 64, 48, 32]): RgbaBitmap {
+ const big = Math.max(image.width, image.height);
+ if (big >= LARGE_PICTURE && isOpaque(image)) return largeSheet(image);
+ const k = big < 384 ? Math.max(1, Math.floor(384 / big)) : Math.min(1, 512 / big);
+ const [pw, ph] = [Math.round(image.width * k), Math.round(image.height * k)];
+ const gap = 8;
+ const smallest = sizes.length ? Math.max(...sizes) : 0;
+ const W = pw * 2 + gap * 3 + (smallest ? smallest + gap : 0);
+ const H = Math.max(ph + gap * 2, sizes.reduce((s, v) => s + v + gap, gap) * 1);
+ const rgba = new Uint8Array(W * H * 4);
+ for (let i = 0; i < W * H; i++) rgba.set([64, 64, 68, 255], i * 4);
+ const scaled = k >= 1 ? nearestScale(image, pw, ph) : shrink(image, pw, ph);
+ const lay = (pic: RgbaBitmap, ox: number, oy: number, ground: Ground): void => layOn(rgba, W, pic, ox, oy, ground);
+ lay(scaled, gap, gap, midGround);
+ lay(scaled, gap * 2 + pw, gap, checkGround);
+ let oy = gap;
+ for (const s of sizes) {
+ const small = shrink(image, s, Math.max(1, Math.round((s * image.height) / image.width)));
+ lay(small, gap * 3 + pw * 2, oy, midGround);
+ oy += small.height + gap;
+ }
+ return { width: W, height: H, rgba };
+}
+
+const LARGE_PICTURE = 512;
+
+export function isOpaque(image: RgbaBitmap): boolean {
+ for (let i = 3; i < image.rgba.length; i += 4) if (image.rgba[i] !== 255) return false;
+ return true;
+}
+
+/** What a full painting wants to be seen at: large, with nothing to judge against a ground, and small to check it still reads. */
+function largeSheet(image: RgbaBitmap): RgbaBitmap {
+ const k = Math.min(1, 1024 / Math.max(image.width, image.height));
+ const [pw, ph] = [Math.round(image.width * k), Math.round(image.height * k)];
+ const gap = 8;
+ const [W, H] = [pw + gap * 3 + 192, ph + gap * 2];
+ const rgba = solidSheet(W, H);
+ layOn(rgba, W, k < 1 ? shrink(image, pw, ph) : image, gap, gap, midGround);
+ let oy = gap;
+ for (const s of [192, 96]) {
+ const small = shrink(image, s, Math.max(1, Math.round((s * image.height) / image.width)));
+ if (oy + small.height > H) break;
+ layOn(rgba, W, small, gap * 2 + pw, oy, midGround);
+ oy += small.height + gap;
+ }
+ return { width: W, height: H, rgba };
+}
+
+/** The picture in lightness alone: whether it holds together in light and dark, before colour flatters it. */
+export function valuesImage(image: RgbaBitmap): RgbaBitmap {
+ const rgba = new Uint8Array(image.rgba.length);
+ for (let i = 0; i < rgba.length; i += 4) {
+ const v = Math.round(lightness(image.rgba[i]!, image.rgba[i + 1]!, image.rgba[i + 2]!) * 255);
+ rgba[i] = v; rgba[i + 1] = v; rgba[i + 2] = v; rgba[i + 3] = image.rgba[i + 3]!;
+ }
+ return { width: image.width, height: image.height, rgba };
+}
+
+const lightness = (r: number, g: number, b: number): number => (r * 0.2126 + g * 0.7152 + b * 0.0722) / 255;
+
+/** What is at each point: the colour, and how light it is 0..1. */
+export function pickColors(image: RgbaBitmap, points: readonly (readonly number[])[]): { at: readonly number[]; color: string; value: number }[] {
+ return points.map((at) => {
+ const [x, y] = [Math.floor(at[0]!), Math.floor(at[1]!)];
+ if (!(x >= 0 && y >= 0 && x < image.width && y < image.height)) throw new Error(`[${at.join(', ')}] is outside the picture, ${image.width} by ${image.height}`);
+ const i = (y * image.width + x) * 4;
+ const [r, g, b, a] = [image.rgba[i]!, image.rgba[i + 1]!, image.rgba[i + 2]!, image.rgba[i + 3]!];
+ const hex = (v: number): string => v.toString(16).padStart(2, '0');
+ return { at, color: `#${hex(r)}${hex(g)}${hex(b)}${a === 255 ? '' : hex(a)}`, value: Math.round(lightness(r, g, b) * 100) / 100 };
+ });
+}
+
+function nearestScale(src: RgbaBitmap, width: number, height: number): RgbaBitmap {
+ const rgba = new Uint8Array(width * height * 4);
+ for (let y = 0; y < height; y++) {
+ const sy = Math.floor((y * src.height) / height);
+ for (let x = 0; x < width; x++) {
+ const from = (sy * src.width + Math.floor((x * src.width) / width)) * 4;
+ rgba.set(src.rgba.subarray(from, from + 4), (y * width + x) * 4);
+ }
+ }
+ return { width, height, rgba };
+}
diff --git a/sdk/src/image/imageSource.ts b/sdk/src/image/imageSource.ts
new file mode 100644
index 000000000..25b423646
--- /dev/null
+++ b/sdk/src/image/imageSource.ts
@@ -0,0 +1,1013 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
+/**
+ * @file imageSource.ts — `.esimage`: a picture as a list of layers, what a model writes and edits, and what is wrong with one.
+ */
+import { parsePath } from './imagePath';
+
+export const IMAGE_BLENDS = [
+ 'normal', 'multiply', 'screen', 'overlay', 'add', 'softLight', 'hardLight', 'vividLight', 'linearLight', 'pinLight', 'colorDodge', 'colorBurn', 'linearBurn',
+ 'darken', 'lighten', 'difference', 'exclusion', 'subtract', 'divide', 'hue', 'saturation', 'color', 'luminosity',
+] as const;
+export type ImageBlend = (typeof IMAGE_BLENDS)[number];
+
+/** Adjustments of the picture so far. Any of them together, applied in this order. */
+export interface ImageAdjust {
+ /** Stops, as a photo's: 1 is twice as bright. */
+ exposure?: number;
+ levels?: { input?: readonly [number, number]; gamma?: number; output?: readonly [number, number] };
+ /** [[in, out]...] 0..1 for all channels, or { r, g, b } for each. */
+ curves?: readonly (readonly number[])[] | { r?: readonly (readonly number[])[]; g?: readonly (readonly number[])[]; b?: readonly (readonly number[])[] };
+ brightness?: number;
+ contrast?: number;
+ temperature?: number;
+ tint?: number;
+ /** Each [r, g, b], -1..1, pushing that part of the tonal range. */
+ balance?: { shadows?: readonly number[]; midtones?: readonly number[]; highlights?: readonly number[] };
+ /** Degrees round the wheel, and -1..1 each. */
+ hue?: number;
+ saturation?: number;
+ lightness?: number;
+ vibrance?: number;
+ /** true, or how much of [r, g, b] each makes the grey. */
+ blackWhite?: boolean | readonly number[];
+ gradientMap?: readonly (readonly [number, string])[];
+ invert?: boolean;
+ posterize?: number;
+ threshold?: number;
+}
+
+const ADJUST_RANGES: Readonly<Record<string, readonly [number, number]>> = { exposure: [-8, 8], brightness: [-1, 1], contrast: [-1, 1], temperature: [-1, 1], tint: [-1, 1], hue: [-360, 360], saturation: [-1, 1], lightness: [-1, 1], vibrance: [-1, 1], posterize: [2, 256], threshold: [0, 1] };
+
+function adjustProblem(a: unknown): string | null {
+ if (typeof a !== 'object' || a === null) return 'must be an object of what to change';
+ const o = a as Record<string, unknown>;
+ const known = [...Object.keys(ADJUST_RANGES), 'levels', 'curves', 'balance', 'blackWhite', 'gradientMap', 'invert'];
+ for (const key of Object.keys(o)) if (!known.includes(key)) return `has unknown "${key}"; there are ${known.join(', ')}`;
+ if (Object.keys(o).length === 0) return 'changes nothing';
+ for (const [key, [lo, hi]] of Object.entries(ADJUST_RANGES)) if (o[key] !== undefined && !(isNum(o[key]) && (o[key] as number) >= lo && (o[key] as number) <= hi)) return `${key} must be ${lo}..${hi}`;
+ const unitPair = (v: unknown): boolean => isPair(v) && (v as number[]).every((n) => n >= 0 && n <= 1);
+ const curve = (v: unknown): boolean => Array.isArray(v) && v.length >= 2 && v.every(unitPair);
+ if (o.levels !== undefined) {
+ const l = o.levels as Record<string, unknown>;
+ if (typeof l !== 'object' || l === null) return 'levels must be { input?, gamma?, output? }';
+ for (const key of Object.keys(l)) if (!['input', 'gamma', 'output'].includes(key)) return `levels has unknown "${key}"; there are input, gamma, output`;
+ for (const key of ['input', 'output']) if (l[key] !== undefined && !unitPair(l[key])) return `levels ${key} must be [low, high], each 0..1`;
+ if (l.gamma !== undefined && !(isNum(l.gamma) && (l.gamma as number) > 0)) return 'levels gamma must be positive';
+ }
+ if (o.curves !== undefined) {
+ if (Array.isArray(o.curves)) { if (!curve(o.curves)) return 'curves must be two or more [in, out], each 0..1'; }
+ else {
+ const c = o.curves as Record<string, unknown>;
+ if (typeof c !== 'object' || c === null) return 'curves must be [[in, out]...] or { r, g, b }';
+ for (const [key, v] of Object.entries(c)) { if (!['r', 'g', 'b'].includes(key)) return `curves has unknown "${key}"; there are r, g, b`; if (!curve(v)) return `curves ${key} must be two or more [in, out], each 0..1`; }
+ }
+ }
+ if (o.balance !== undefined) {
+ for (const [key, v] of Object.entries(o.balance as Record<string, unknown>)) {
+ if (!['shadows', 'midtones', 'highlights'].includes(key)) return `balance has unknown "${key}"; there are shadows, midtones, highlights`;
+ if (!(Array.isArray(v) && v.length === 3 && v.every(isNum))) return `balance ${key} must be [r, g, b]`;
+ }
+ }
+ if (o.blackWhite !== undefined && typeof o.blackWhite !== 'boolean' && !(Array.isArray(o.blackWhite) && o.blackWhite.length === 3 && o.blackWhite.every(isNum))) return 'blackWhite must be true or [r, g, b]';
+ if (o.invert !== undefined && typeof o.invert !== 'boolean') return 'invert must be true or false';
+ if (o.gradientMap !== undefined && !(Array.isArray(o.gradientMap) && o.gradientMap.length >= 2 && o.gradientMap.every((s) => Array.isArray(s) && s.length === 2 && isNum(s[0]) && isColor(s[1])))) return 'gradientMap must be two or more [0..1, colour]';
+ return null;
+}
+
+/** Every filter and what it takes. A number but for: `at`, `from`, `to` a place; `color` a colour; `mono` true or false. */
+export const IMAGE_FILTERS = {
+ gaussian: ['radius'], motion: ['angle', 'distance'], spin: ['at', 'angle'], zoom: ['at', 'amount'], lens: ['radius', 'highlights'],
+ sharpen: ['amount', 'radius', 'threshold'], highPass: ['radius'], noise: ['amount', 'scale', 'mono', 'seed'], median: ['radius'], emboss: ['angle', 'height', 'amount'],
+ ripple: ['amount', 'size', 'seed'], displace: ['amount', 'size', 'seed'], twirl: ['at', 'radius', 'angle'], pixelate: ['cell'], chromatic: ['at', 'amount'],
+ vignette: ['at', 'amount', 'radius', 'outer', 'color'], fog: ['color', 'density', 'from', 'to', 'patchiness', 'size', 'seed'], rays: ['at', 'threshold', 'length', 'strength', 'decay'],
+ flare: ['at', 'size', 'color', 'strength'], texture: ['scale', 'amount', 'angle', 'seed'],
+} as const;
+export type ImageFilterName = keyof typeof IMAGE_FILTERS;
+
+function filterProblem(name: unknown, params: unknown): string | null {
+ if (typeof name !== 'string' || !Object.prototype.hasOwnProperty.call(IMAGE_FILTERS, name)) return `filter ${JSON.stringify(name)} must be one of ${Object.keys(IMAGE_FILTERS).join(', ')}`;
+ if (params === undefined) return null;
+ if (typeof params !== 'object' || params === null) return 'params must be an object';
+ const known = IMAGE_FILTERS[name as ImageFilterName] as readonly string[];
+ for (const [key, v] of Object.entries(params)) {
+ if (!known.includes(key)) return `filter ${name} has unknown "${key}"; it takes ${known.join(', ')}`;
+ if (key === 'color') { if (!isColor(v)) return `filter ${name}: color must be #rgb..#rrggbbaa`; }
+ else if (key === 'at' || key === 'from' || key === 'to') { if (!isPair(v)) return `filter ${name}: ${key} must be [x, y]`; }
+ else if (key === 'mono') { if (typeof v !== 'boolean') return `filter ${name}: mono must be true or false`; }
+ else if (!isNum(v)) return `filter ${name}: ${key} must be a number`;
+ }
+ return null;
+}
+
+export const IMAGE_SOURCE_EXT = '.esimage';
+export const IMAGE_SOURCE_VERSION = 1;
+export const MAX_IMAGE_SIZE = 2048;
+
+export type ImageFill = string
+ | { type: 'linear'; from: readonly [number, number]; to: readonly [number, number]; stops: readonly (readonly [number, string])[] }
+ | { type: 'radial'; at: readonly [number, number]; radius: number; stops: readonly (readonly [number, string])[] }
+ /** The same picture on every machine: it comes from `seed` and never from a random number. */
+ | { type: 'noise'; scale?: number; octaves?: number; seed?: number; stops: readonly (readonly [number, string])[] }
+ /** By which way a figure's surface faces: 1 toward the light, 0.5 side on, 0 away. So light turns the form and does not sit on its edge. */
+ | { type: 'form'; figure: string; light?: readonly number[]; stops: readonly (readonly [number, string])[] }
+ /** The colour of an `image` layer at each place. */
+ | { type: 'image'; image: string }
+ /** Marks in rows and columns: windows, tiles, grilles. On four corners it lies in perspective. */
+ | {
+ type: 'grid';
+ /** A cell's size in pixels, or with `quad` how many columns and rows there are. */
+ cell?: readonly [number, number];
+ cells?: readonly [number, number];
+ /** Corners in order round: top left, top right, bottom right, bottom left. */
+ quad?: readonly (readonly number[])[];
+ /** The mark as a share of its cell, each 0..1. */
+ mark?: readonly [number, number];
+ colors: readonly string[];
+ /** Between the marks; clear without it. */
+ ground?: string;
+ /** The share of marks that are on, 0..1, and what the rest show. */
+ lit?: number;
+ off?: string;
+ seed?: number;
+ };
+
+export interface ImageEffect {
+ type: 'shadow' | 'glow' | 'innerShadow' | 'innerGlow' | 'bevel' | 'overlay';
+ /** A bevel: how wide, the light's direction in degrees, how strong, and the colour on its dark side. */
+ size?: number;
+ angle?: number;
+ depth?: number;
+ shade?: string;
+ /** An overlay: what covers the shape. */
+ fill?: ImageFill;
+ blend?: ImageBlend;
+ color?: string;
+ x?: number;
+ y?: number;
+ blur?: number;
+ opacity?: number;
+}
+
+export interface ImageTransform {
+ translate?: readonly [number, number];
+ /** Degrees, clockwise on screen, about `origin`. */
+ rotate?: number;
+ scale?: number | readonly [number, number];
+ /** Default the layer's middle. */
+ origin?: readonly [number, number];
+}
+
+export type ImageShape = 'rect' | 'circle' | 'ellipse' | 'ring' | 'polygon' | 'line' | 'star' | 'gear' | 'path' | 'pixels' | 'paint' | 'figure' | 'image' | 'text' | 'block' | 'perspective' | 'reflect' | 'bloom' | 'adjust' | 'filter' | 'group';
+
+/** How a brush lays colour. Any of these on a stroke, a sweep or a field, over what its `brush` starts from. */
+export interface ImageBrushSettings {
+ hardness?: number;
+ opacity?: number;
+ taper?: readonly [number, number];
+ /** 1 round; lower is a flat brush, thin along its travel and wide across it. */
+ roundness?: number;
+ /** Degrees the flat of the brush is held at, which gives thick and thin as a pen does. Without it the brush turns with the stroke. */
+ angle?: number;
+ /** 0..1: how much the tooth of the paper breaks it up, in a texture fixed to the picture. */
+ grain?: number;
+ grainScale?: number;
+ /** 0..1: how much the brush runs dry, in streaks along its travel. */
+ dry?: number;
+ /** 0..1: how much it picks up what is under it as it goes. */
+ wet?: number;
+ /** 0..1: pigment gathered at the edge, as watercolour dries. */
+ edge?: number;
+ /** Each dab this many brush radii off the line. */
+ scatter?: number;
+ /** The dabs as a share of the brush's size: small, and scattered, they are a spray. */
+ dab?: number;
+ /** Between dabs, as a share of a dab's width. */
+ spacing?: number;
+ /** 0..1: each dab adds this much, so paint builds where it passes, as an airbrush does, and opacity no longer caps it. */
+ flow?: number;
+ /** How much of the length at each end fades out, each 0..1. */
+ fade?: readonly [number, number];
+}
+
+/** Named starting points, in the words a painter uses. */
+export const IMAGE_BRUSHES: Readonly<Record<string, ImageBrushSettings>> = {
+ ink: { hardness: 1, taper: [0.12, 0.3] },
+ pen: { hardness: 1, roundness: 0.25, angle: -45 },
+ pencil: { hardness: 0.6, grain: 0.35, grainScale: 1.2, opacity: 0.75 },
+ charcoal: { hardness: 0.35, grain: 0.5, grainScale: 2.2, dry: 0.12, opacity: 0.95 },
+ chalk: { hardness: 0.7, grain: 0.55, grainScale: 6, opacity: 0.95 },
+ flat: { hardness: 0.85, roundness: 0.3, dry: 0.3 },
+ oil: { hardness: 0.65, roundness: 0.55, dry: 0.22, wet: 0.55, opacity: 0.95 },
+ gouache: { hardness: 0.8, roundness: 0.5, wet: 0.2, dry: 0.08, opacity: 0.95 },
+ watercolor: { hardness: 0.2, wet: 0.45, edge: 0.5, opacity: 0.45, grain: 0.05, grainScale: 5 },
+ marker: { hardness: 0.9, roundness: 0.45, angle: -30, opacity: 0.72 },
+ airbrush: { hardness: 0, flow: 0.05 },
+ spray: { hardness: 0.7, dab: 0.07, scatter: 1, spacing: 0.5, opacity: 0.9 },
+ dry: { hardness: 0.75, roundness: 0.35, dry: 0.65, opacity: 0.95 },
+};
+const BRUSH_FIELDS = ['brush', 'roundness', 'angle', 'grain', 'grainScale', 'dry', 'wet', 'edge', 'scatter', 'dab', 'spacing', 'flow', 'fade'];
+
+/** One movement of a brush. Replayed in order on a `paint` layer, so the same list is the same picture. */
+export interface ImageStroke extends ImageBrushSettings {
+ /** A named brush from IMAGE_BRUSHES, which what else is given here overrides. */
+ brush?: string;
+ /** Through these, smoothly; a third number is pressure, 1 by default. One point is a dab. */
+ points: readonly (readonly number[])[];
+ color?: string;
+ /** The colour it has become by the end. */
+ to?: string;
+ size: number;
+ /** 1 is a hard edge, 0 fades from the middle. */
+ hardness?: number;
+ opacity?: number;
+ /** How much of the length at each end narrows to a point, each 0..1. */
+ taper?: readonly [number, number];
+ /** Separate hairs across its width, which meet where it narrows. */
+ bristles?: number;
+ /** The width of a bristle; by default what spreads them across the stroke. */
+ strand?: number;
+ spread?: number;
+ /** How far each bristle's lightness and strength differ, 0..1. */
+ vary?: number;
+ /** How far a bristle wanders from its line, in pixels. */
+ wobble?: number;
+ seed?: number;
+ /** 0..1: drags what is already on this layer along, instead of laying colour. */
+ smudge?: number;
+ erase?: boolean;
+ blend?: ImageBlend;
+}
+
+/** Many hairs between guide lines, gathered into locks. A few words of intent, and hundreds of strokes when drawn. */
+export interface ImageSweep extends ImageBrushSettings {
+ type: 'sweep';
+ brush?: string;
+ /** Two or more lines, side by side and in order, each root to tip. */
+ guides: readonly (readonly (readonly number[])[])[];
+ /** Across the guides, first to last. */
+ colors: readonly string[];
+ count: number;
+ /** What the colours have turned to by the tips. */
+ tip?: string;
+ /** The width of one hair. */
+ size?: number;
+ clumps?: number;
+ /** How far hairs draw into their lock by the tips, 0..1. */
+ gather?: number;
+ /** The share of hairs that stray from the mass, 0..1. */
+ flyaway?: number;
+ vary?: number;
+ wobble?: number;
+ opacity?: number;
+ taper?: readonly [number, number];
+ seed?: number;
+}
+
+/** A region covered in strokes that follow a flow, each its colour from `tone` where it starts. */
+export interface ImageField extends ImageBrushSettings {
+ type: 'field';
+ brush?: string;
+ /** An SVG path to start strokes in, or "@id" for where an earlier layer drew; the whole picture without it. Strokes may run over its edge. */
+ region?: string;
+ /** Lines the strokes follow, nearest the most, or a direction in degrees clockwise from right. */
+ guides?: readonly (readonly (readonly number[])[])[];
+ angle?: number;
+ /** Where each stroke takes its colour; left out when it smudges. */
+ tone?: ImageFill;
+ /** 0..1: the strokes drag what is there along the flow, and lay no colour. */
+ smudge?: number;
+ size: number;
+ length?: number;
+ /** How many times over the strokes cover the region. */
+ coverage?: number;
+ /** Degrees either side of the flow. */
+ spread?: number;
+ vary?: number;
+ opacity?: number;
+ hardness?: number;
+ seed?: number;
+}
+
+/** The same strokes again and again along a line: feathers, scales, leaves, beads. */
+export interface ImageAlong {
+ type: 'along';
+ line: readonly (readonly number[])[];
+ count: number;
+ /** Drawn with x along the line and y across it, about the point [0, 0]. */
+ strokes: readonly ImageStroke[];
+ /** How large they are at the start of the line and at the end. */
+ scale?: number | readonly [number, number];
+ /** Degrees, added to the line's direction. */
+ turn?: number;
+ /** Each one again, reflected across the line. */
+ both?: boolean;
+ /** Up to this far off their place, in pixels and a tenth as many degrees. */
+ jitter?: number;
+ seed?: number;
+}
+
+export type ImageMark = ImageStroke | ImageSweep | ImageField | ImageAlong;
+
+export interface ImageLayer {
+ id?: string;
+ shape: ImageShape;
+ at?: readonly [number, number];
+ size?: readonly [number, number];
+ radius?: number | readonly number[];
+ radii?: readonly [number, number];
+ inner?: number;
+ count?: number;
+ tooth?: number;
+ turn?: number;
+ points?: readonly (readonly [number, number])[];
+ d?: string;
+ rows?: readonly string[];
+ palette?: Readonly<Record<string, string>>;
+ scale?: number;
+ layers?: readonly ImageLayer[];
+ strokes?: readonly ImageMark[];
+ /** "below": a paint layer's canvas starts as the picture so far, so its strokes and smudges work across everything under it. */
+ from?: 'below';
+ /** Seen when looking and left out of the .png, while what it masks still works. A figure is one unless told otherwise. */
+ guide?: boolean;
+ /** A figure: pixels from floor to crown, standing straight. */
+ height?: number;
+ /** A figure: degrees turned about the body, 0 facing the viewer, 90 facing picture right, 180 away. */
+ yaw?: number;
+ /** A figure: degrees seen from above. */
+ pitch?: number;
+ build?: { head?: number; shoulders?: number; chest?: number; waist?: number; hips?: number; limbs?: number };
+ pose?: {
+ rotate?: Readonly<Record<string, readonly number[]>>;
+ move?: Readonly<Record<string, readonly number[]>>;
+ /** A joint and where it must be: [x, y] in the picture, or [x, y, z] on the body's own axes. */
+ reach?: Readonly<Record<string, { at: readonly number[]; pole?: readonly number[] }>>;
+ };
+ /** Text: what it says. */
+ text?: string;
+ fontSize?: number;
+ /** A family the machine has, or a font file in the project. */
+ font?: string;
+ weight?: number | string;
+ align?: 'left' | 'center' | 'right';
+ /** Characters one under the other, as a sign down a building. */
+ vertical?: boolean;
+ /** Extra between characters, in pixels. */
+ tracking?: number;
+ /** Text: pixels taken off each stroke of the letters, for the white-hot core of a neon tube. */
+ thin?: number;
+ /** Text: 0..1 how much the surface shows through, as worn paint, and how much it is rubbed away in streaks. */
+ grain?: number;
+ grainScale?: number;
+ dry?: number;
+ /** Text or paint: a face of a block already drawn, "id.a", to lie on: text within `within`, and strokes with their points counted 0..1 across it and 0..1 down. */
+ face?: string;
+ /** On a face, the part it takes: left, top, right, bottom, each 0..1. */
+ within?: readonly number[];
+ /** Text: four corners in the picture it is laid on, in order round from the top left, so it lies on a wall in perspective. */
+ quad?: readonly (readonly number[])[];
+ /** Pixels of soft edge on the layer, fading inward, keeping its colour where a blur would smear it. */
+ feather?: number;
+ /** What it clips to, softened, grown or shrunk, or turned inside out. */
+ clipFeather?: number;
+ clipGrow?: number;
+ clipInvert?: boolean;
+ /** Only where the picture so far is this light, [low, high, softness?] each 0..1: a highlight or shadow selected by what it is. */
+ blendIf?: readonly number[];
+ adjust?: ImageAdjust;
+ filter?: ImageFilterName;
+ params?: Readonly<Record<string, unknown>>;
+ /** A bloom: how bright a pixel must be to shine, 0..1, and how much it does. */
+ threshold?: number;
+ strength?: number;
+ /** A block or a perspective: the points lines recede to. */
+ vanish?: readonly (readonly number[])[];
+ /** A block: how far each face runs toward its vanishing point, 0..1. */
+ depth?: readonly number[];
+ /** A block: the fill of each face, and of the roof if it can be seen. */
+ faces?: readonly ImageFill[];
+ roof?: ImageFill;
+ /** A reflect: the line it mirrors about, level or as points along where things meet the ground, how far down it reaches, and how far it wavers and smears in pixels. */
+ y?: number;
+ edge?: readonly (readonly number[])[];
+ reach?: number;
+ ripple?: number;
+ smear?: number;
+ /** An image: a picture in the project. */
+ src?: string;
+ /** Drawn everywhere but inside this earlier layer. */
+ except?: string;
+ /** A figure: where the light is, x right, y up, z toward the viewer. */
+ light?: readonly number[];
+ fill?: ImageFill;
+ stroke?: { color: ImageFill; width: number; align?: 'center' | 'inside' | 'outside'; join?: 'round' | 'miter' | 'bevel'; cap?: 'round' | 'butt' | 'square' };
+ opacity?: number;
+ blend?: ImageBlend;
+ transform?: ImageTransform;
+ mirror?: 'x' | 'y';
+ effects?: readonly ImageEffect[];
+ clip?: string;
+ erase?: boolean;
+ visible?: boolean;
+ /** Softens the layer as drawn, with its effects, in the picture's pixels. On a group it softens the group as one thing. */
+ blur?: number;
+}
+
+export interface ImageSource {
+ version?: number;
+ size: number | readonly [number, number];
+ background?: string;
+ /**
+ * The picture repeats: laid edge to edge with itself it shows no seam. What is drawn past one edge comes in at the
+ * opposite one, a blur or a shadow goes round with it, and a noise fill repeats with the picture. For a wall, a floor,
+ * a cloth: anything a surface is covered with.
+ */
+ tile?: boolean;
+ /** What the surface is, beside what it looks like: see {@link ImageMaterial}. With it, a normal map and a material are written beside the picture. */
+ material?: ImageMaterial;
+ layers: readonly ImageLayer[];
+}
+
+/**
+ * A picture as a surface. Each part is a number for the whole of it, or layers drawn as a grey picture of their own:
+ * light is high, light is rough, light is metal.
+ */
+export interface ImageMaterial {
+ /** How far white stands above black, in pixels of the picture. Default 4. */
+ relief?: number;
+ /** The relief, drawn: light is high. Default: the colour picture's own lightness, dark being low. */
+ height?: readonly ImageLayer[];
+ /** How rough, 0..1 everywhere, or drawn: light is rough. Default 0.8. */
+ roughness?: number | readonly ImageLayer[];
+ /** How much metal, 0..1 everywhere, or drawn: light is metal. Default 0. */
+ metal?: number | readonly ImageLayer[];
+}
+
+const isNum = (v: unknown): v is number => typeof v === 'number' && Number.isFinite(v);
+const isPair = (v: unknown): boolean => Array.isArray(v) && v.length === 2 && v.every(isNum);
+const isColor = (v: unknown): boolean => typeof v === 'string' && /^#(?:[0-9a-fA-F]{3,4}|[0-9a-fA-F]{6}|[0-9a-fA-F]{8})$/.test(v);
+
+function checkFill(v: unknown): string | null {
+ if (typeof v === 'string') return isColor(v) ? null : `${JSON.stringify(v)} must be #rgb, #rgba, #rrggbb or #rrggbbaa`;
+ const f = v as Record<string, unknown> | null;
+ if (typeof f !== 'object' || f === null) return 'must be a colour or a gradient';
+ if (f.type !== 'linear' && f.type !== 'radial' && f.type !== 'noise' && f.type !== 'form' && f.type !== 'image' && f.type !== 'grid') return 'a gradient has type linear, radial, noise, form, image or grid';
+ if (f.type === 'grid') {
+ if (!Array.isArray(f.colors) || f.colors.length === 0 || !f.colors.every(isColor)) return 'a grid needs colors: one or more';
+ for (const key of ['ground', 'off']) if (f[key] !== undefined && !isColor(f[key])) return `a grid's ${key} must be a colour`;
+ const quad = f.quad as unknown[] | undefined;
+ if (quad !== undefined && !(Array.isArray(quad) && quad.length === 4 && quad.every(isPair))) return 'a grid\'s quad must be four [x, y], in order round from the top left';
+ if (f.cell === undefined && f.cells === undefined) return 'a grid needs cell: [w, h] in pixels, or cells: [columns, rows]';
+ for (const key of ['cell', 'cells']) if (f[key] !== undefined && !(isPair(f[key]) && (f[key] as number[]).every((v) => v > 0))) return `a grid's ${key} must be two positive numbers`;
+ if (f.cell !== undefined && quad !== undefined) return 'a grid on a quad is counted in cells: [columns, rows]';
+ if (f.mark !== undefined && !(isPair(f.mark) && (f.mark as number[]).every((v) => v > 0 && v <= 1))) return 'a grid\'s mark must be [w, h], each above 0 and up to 1';
+ if (f.lit !== undefined && !(isNum(f.lit) && (f.lit as number) >= 0 && (f.lit as number) <= 1)) return 'a grid\'s lit must be 0..1';
+ if (f.seed !== undefined && !Number.isInteger(f.seed)) return 'a grid\'s seed must be a whole number';
+ return null;
+ }
+ if (f.type === 'image') return typeof f.image === 'string' && f.image ? null : 'an image fill needs image, the id of an image layer drawn before it';
+ if (f.type === 'form') {
+ if (typeof f.figure !== 'string' || !f.figure) return 'a form needs figure, the id of a figure drawn before it';
+ if (f.light !== undefined && !(Array.isArray(f.light) && f.light.length === 3 && f.light.every(isNum))) return 'a form\'s light must be [x, y, z], x right, y up, z toward the viewer';
+ }
+ if (f.type === 'noise') {
+ if (f.scale !== undefined && !(isNum(f.scale) && (f.scale as number) > 0)) return 'noise scale must be a positive number of pixels';
+ if (f.octaves !== undefined && !(Number.isInteger(f.octaves) && (f.octaves as number) >= 1 && (f.octaves as number) <= 8)) return 'noise octaves must be a whole number from 1 to 8';
+ if (f.seed !== undefined && !Number.isInteger(f.seed)) return 'noise seed must be a whole number';
+ }
+ if (f.type === 'linear' && !(isPair(f.from) && isPair(f.to))) return 'a linear gradient needs from and to, each [x, y]';
+ if (f.type === 'linear' && (f.from as number[])[0] === (f.to as number[])[0] && (f.from as number[])[1] === (f.to as number[])[1]) return 'a linear gradient needs from and to apart: at one point it draws a single flat colour';
+ if (f.type === 'radial' && !(isPair(f.at) && isNum(f.radius) && (f.radius as number) > 0)) return 'a radial gradient needs at: [x, y] and a positive radius';
+ if (!Array.isArray(f.stops) || f.stops.length < 2) return 'a gradient needs two stops or more, each [0..1, colour]';
+ for (const s of f.stops as unknown[]) {
+ if (!Array.isArray(s) || s.length !== 2 || !isNum(s[0]) || !isColor(s[1])) return `a stop ${JSON.stringify(s)} must be [0..1, colour]`;
+ }
+ return null;
+}
+
+const FIELDS = ['id', 'shape', 'at', 'size', 'radius', 'radii', 'inner', 'count', 'tooth', 'turn', 'points', 'd', 'rows', 'palette', 'scale', 'layers', 'fill', 'stroke', 'opacity', 'blend', 'transform', 'mirror', 'effects', 'clip', 'erase', 'visible', 'blur', 'strokes', 'from', 'guide', 'height', 'yaw', 'pitch', 'build', 'pose', 'light', 'src', 'except', 'text', 'fontSize', 'font', 'weight', 'align', 'vertical', 'tracking', 'vanish', 'depth', 'faces', 'roof', 'y', 'edge', 'reach', 'ripple', 'smear', 'quad', 'threshold', 'strength', 'thin', 'grain', 'grainScale', 'dry', 'face', 'within', 'feather', 'clipFeather', 'clipGrow', 'clipInvert', 'blendIf', 'adjust', 'filter', 'params'];
+
+/** Layers that are aids to drawing unless told otherwise: seen when looking, and not in the .png. */
+export const isGuideLayer = (l: ImageLayer): boolean => l.guide ?? (l.shape === 'figure' || l.shape === 'image' || l.shape === 'perspective');
+const SHAPES: readonly ImageShape[] = ['rect', 'circle', 'ellipse', 'ring', 'polygon', 'line', 'star', 'gear', 'path', 'pixels', 'paint', 'figure', 'image', 'text', 'block', 'perspective', 'reflect', 'bloom', 'adjust', 'filter', 'group'];
+const STROKE_FIELDS = ['points', 'color', 'to', 'size', 'hardness', 'opacity', 'taper', 'bristles', 'strand', 'spread', 'vary', 'wobble', 'seed', 'smudge', 'erase', 'blend', ...BRUSH_FIELDS];
+
+/** What a brush's own settings must be, on whatever carries them. */
+function brushProblem(s: Record<string, unknown>): string | null {
+ if (s.brush !== undefined && !(typeof s.brush === 'string' && Object.prototype.hasOwnProperty.call(IMAGE_BRUSHES, s.brush))) return `brush ${JSON.stringify(s.brush)} must be one of ${Object.keys(IMAGE_BRUSHES).join(', ')}`;
+ for (const key of ['roundness', 'grain', 'dry', 'wet', 'edge', 'dab', 'flow']) {
+ if (s[key] !== undefined && !(isNum(s[key]) && (s[key] as number) >= 0 && (s[key] as number) <= 1)) return `${key} must be 0..1`;
+ }
+ if (s.roundness === 0 || s.dab === 0) return `${s.roundness === 0 ? 'roundness' : 'dab'} must be above 0`;
+ for (const key of ['grainScale', 'spacing']) if (s[key] !== undefined && !(isNum(s[key]) && (s[key] as number) > 0)) return `${key} must be positive`;
+ if (s.scatter !== undefined && !(isNum(s.scatter) && (s.scatter as number) >= 0)) return 'scatter must be 0 or more';
+ if (s.angle !== undefined && !isNum(s.angle)) return 'angle must be degrees';
+ if (s.fade !== undefined && !(Array.isArray(s.fade) && s.fade.length === 2 && s.fade.every((t) => isNum(t) && t >= 0 && t <= 1))) return 'fade must be [start, end], each 0..1';
+ return null;
+}
+
+const SWEEP_FIELDS = ['type', 'guides', 'colors', 'count', 'tip', 'size', 'clumps', 'gather', 'flyaway', 'vary', 'wobble', 'opacity', 'taper', 'seed', 'hardness', ...BRUSH_FIELDS];
+const ALONG_FIELDS = ['type', 'line', 'count', 'strokes', 'scale', 'turn', 'both', 'jitter', 'seed'];
+const FIELD_FIELDS = ['type', 'region', 'guides', 'angle', 'tone', 'smudge', 'size', 'length', 'coverage', 'spread', 'vary', 'opacity', 'hardness', 'seed', 'taper', ...BRUSH_FIELDS];
+const isGuide = (g: unknown): boolean => Array.isArray(g) && g.length >= 2 && g.every((p) => Array.isArray(p) && (p.length === 2 || p.length === 3) && p.every(isNum));
+export const MAX_MARK_STROKES = 30000;
+
+function markProblem(s: Record<string, unknown>): string | null {
+ const zeroToOne = (keys: readonly string[]): string | null => {
+ for (const key of keys) if (s[key] !== undefined && !(isNum(s[key]) && (s[key] as number) >= 0 && (s[key] as number) <= 1)) return `${key} must be 0..1`;
+ return null;
+ };
+ const fields = s.type === 'sweep' ? SWEEP_FIELDS : s.type === 'along' ? ALONG_FIELDS : FIELD_FIELDS;
+ for (const key of Object.keys(s)) if (!fields.includes(key)) return `has unknown field "${key}"; a ${String(s.type)} takes ${fields.join(', ')}`;
+ if (s.seed !== undefined && !Number.isInteger(s.seed)) return 'seed must be a whole number';
+ if (s.type !== 'along') {
+ const bad = brushProblem(s);
+ if (bad) return bad;
+ }
+ if (s.type === 'sweep') {
+ if (!Array.isArray(s.guides) || s.guides.length < 2 || !s.guides.every(isGuide)) return 'needs guides: two or more lines, each two or more [x, y]';
+ if (!Array.isArray(s.colors) || s.colors.length === 0 || !s.colors.every(isColor)) return 'needs colors: one or more, across the guides';
+ if (s.tip !== undefined && !isColor(s.tip)) return 'tip must be a colour';
+ if (!(Number.isInteger(s.count) && (s.count as number) >= 1 && (s.count as number) <= MAX_MARK_STROKES)) return `count must be a whole number from 1 to ${MAX_MARK_STROKES}`;
+ if (s.clumps !== undefined && !(Number.isInteger(s.clumps) && (s.clumps as number) >= 1)) return 'clumps must be a whole number of 1 or more';
+ for (const key of ['size', 'wobble']) if (s[key] !== undefined && !(isNum(s[key]) && (s[key] as number) >= 0)) return `${key} must be 0 or more`;
+ if (s.taper !== undefined && !(Array.isArray(s.taper) && s.taper.length === 2 && s.taper.every((t) => isNum(t) && t >= 0 && t <= 1))) return 'taper must be [start, end], each 0..1';
+ return zeroToOne(['gather', 'flyaway', 'vary', 'opacity']);
+ }
+ if (s.type === 'along') {
+ if (!isGuide(s.line)) return 'needs a line: two or more [x, y]';
+ if (!(Number.isInteger(s.count) && (s.count as number) >= 1 && (s.count as number) <= 2000)) return 'count must be a whole number from 1 to 2000';
+ if (!Array.isArray(s.strokes) || s.strokes.length === 0) return 'needs strokes, drawn about [0, 0]';
+ for (const [n, inner] of (s.strokes as Record<string, unknown>[]).entries()) {
+ if (inner?.type !== undefined) return `strokes[${n}] must be a plain stroke`;
+ const bad = strokeProblem(inner);
+ if (bad) return `strokes[${n}] ${bad}`;
+ }
+ const scale = s.scale;
+ if (scale !== undefined && !(isNum(scale) && scale > 0) && !(isPair(scale) && (scale as number[]).every((v) => v > 0))) return 'scale must be a positive number, or [start, end]';
+ for (const key of ['turn', 'jitter']) if (s[key] !== undefined && !isNum(s[key])) return `${key} must be a number`;
+ return null;
+ }
+ if (s.region !== undefined) {
+ if (typeof s.region !== 'string') return 'region must be an SVG path or "@id"';
+ if (!s.region.startsWith('@')) {
+ try { parsePath(s.region); } catch (e) { return `region: ${(e as Error).message}`; }
+ }
+ }
+ if (s.guides !== undefined && !(Array.isArray(s.guides) && s.guides.length > 0 && s.guides.every(isGuide))) return 'guides must be one or more lines, each two or more [x, y]';
+ if (s.angle !== undefined && !isNum(s.angle)) return 'angle must be degrees';
+ if (s.tone === undefined && !s.smudge) return 'needs a tone, unless it smudges';
+ if (s.tone !== undefined) {
+ const bad = checkFill(s.tone);
+ if (bad) return `tone ${bad}`;
+ }
+ for (const key of ['size', 'length', 'coverage']) {
+ if (s[key] !== undefined && !(isNum(s[key]) && (s[key] as number) > 0)) return `${key} must be positive`;
+ }
+ if (s.size === undefined) return 'needs a positive size';
+ if (s.spread !== undefined && !(isNum(s.spread) && (s.spread as number) >= 0)) return 'spread must be 0 or more degrees';
+ return zeroToOne(['vary', 'opacity', 'hardness', 'smudge']);
+}
+
+function strokeProblem(s: Record<string, unknown>): string | null {
+ if (typeof s !== 'object' || s === null) return 'must be an object';
+ if (s.type === undefined) {
+ const bad = brushProblem(s);
+ if (bad) return bad;
+ }
+ if (s.type === 'sweep' || s.type === 'field' || s.type === 'along') return markProblem(s);
+ if (s.type !== undefined) return `has type "${String(s.type)}"; there are sweep, field and along, or none for one stroke`;
+ for (const key of Object.keys(s)) if (!STROKE_FIELDS.includes(key)) return `has unknown field "${key}"; a stroke takes ${STROKE_FIELDS.join(', ')}`;
+ if (!Array.isArray(s.points) || s.points.length === 0 || !s.points.every((p) => Array.isArray(p) && (p.length === 2 || p.length === 3) && p.every(isNum))) return 'needs points, each [x, y] or [x, y, pressure]';
+ if (!(isNum(s.size) && (s.size as number) > 0)) return 'needs a positive size';
+ const paints = !s.erase && !s.smudge;
+ if (paints && s.color === undefined) return 'needs a color, unless it erases or smudges';
+ for (const key of ['color', 'to']) if (s[key] !== undefined && !isColor(s[key])) return `${key} must be #rgb, #rgba, #rrggbb or #rrggbbaa`;
+ for (const key of ['hardness', 'opacity', 'vary', 'smudge']) if (s[key] !== undefined && !(isNum(s[key]) && (s[key] as number) >= 0 && (s[key] as number) <= 1)) return `${key} must be 0..1`;
+ for (const key of ['strand', 'spread', 'wobble']) if (s[key] !== undefined && !(isNum(s[key]) && (s[key] as number) >= 0)) return `${key} must be 0 or more`;
+ if (s.bristles !== undefined && !(Number.isInteger(s.bristles) && (s.bristles as number) >= 1 && (s.bristles as number) <= 200)) return 'bristles must be a whole number from 1 to 200';
+ if (s.seed !== undefined && !Number.isInteger(s.seed)) return 'seed must be a whole number';
+ if (s.taper !== undefined && !(Array.isArray(s.taper) && s.taper.length === 2 && s.taper.every((t) => isNum(t) && t >= 0 && t <= 1))) return 'taper must be [start, end], each 0..1';
+ if (s.blend !== undefined && !IMAGE_BLENDS.includes(s.blend as ImageBlend)) return `blend must be one of ${IMAGE_BLENDS.join(', ')}`;
+ return null;
+}
+
+function checkLayer(l: Record<string, unknown>, where: string, ids: Set<string>): void {
+ const fail = (what: string): never => { throw new Error(`${where}: ${what}`); };
+ if (typeof l !== 'object' || l === null) fail('must be an object');
+ for (const key of Object.keys(l)) if (!FIELDS.includes(key)) fail(`unknown field "${key}"; a layer takes ${FIELDS.join(', ')}`);
+ if (!SHAPES.includes(l.shape as ImageShape)) fail(`shape ${JSON.stringify(l.shape)} must be one of ${SHAPES.join(', ')}`);
+ if (l.id !== undefined) {
+ if (typeof l.id !== 'string' || !l.id) fail('id must be a string');
+ if (ids.has(l.id as string)) fail(`the id "${String(l.id)}" is already used`);
+ ids.add(l.id as string);
+ }
+ const num = (k: string, ok: (n: number) => boolean = () => true): void => { if (!isNum(l[k]) || !ok(l[k] as number)) fail(`${k} must be a number${ok === positive ? ' above 0' : ''}`); };
+ const pair = (k: string): void => { if (!isPair(l[k])) fail(`${k} must be [a, b]`); };
+ const positive = (n: number): boolean => n > 0;
+ switch (l.shape) {
+ case 'rect': if (l.face === undefined) { pair('at'); pair('size'); } if (l.radius !== undefined && !isNum(l.radius) && !(Array.isArray(l.radius) && l.radius.length === 4 && l.radius.every(isNum))) fail('radius must be a number or four corners'); break;
+ case 'circle': pair('at'); num('radius', positive); break;
+ case 'ellipse': pair('at'); pair('radii'); break;
+ case 'ring': pair('at'); num('radius', positive); num('inner', positive); if ((l.inner as number) >= (l.radius as number)) fail('inner must be less than radius'); break;
+ case 'polygon': case 'line':
+ if (!Array.isArray(l.points) || l.points.length < (l.shape === 'line' ? 2 : 3) || !l.points.every(isPair)) fail(`points must be ${l.shape === 'line' ? 'two' : 'three'} or more [x, y]`);
+ if (l.shape === 'line' && !l.stroke) fail('a line needs a stroke: { color, width }');
+ break;
+ case 'star': case 'gear': pair('at'); num('radius', positive); num('inner', positive); if (!Number.isInteger(l.count) || (l.count as number) < 3) fail('count must be 3 or more'); break;
+ case 'path':
+ if (typeof l.d !== 'string' || !l.d.trim()) fail('d must be an SVG path: M L H V C S Q T Z');
+ // Here and not when it is drawn: a hidden layer is not drawn, and an error waits until it is shown.
+ try {
+ if (parsePath(l.d as string).every((run) => run.points.length === 0)) fail('d draws nothing');
+ } catch (e) {
+ fail((e as Error).message);
+ }
+ break;
+ case 'figure': {
+ if (!isPair(l.at)) fail('at must be [x, y]: the place on the floor under her');
+ if (!(isNum(l.height) && (l.height as number) > 0)) fail('height must be pixels from floor to crown');
+ for (const key of ['yaw', 'pitch']) if (l[key] !== undefined && !isNum(l[key])) fail(`${key} must be degrees`);
+ if (l.light !== undefined && !(Array.isArray(l.light) && l.light.length === 3 && l.light.every(isNum))) fail('light must be [x, y, z], x right, y up, z toward the viewer');
+ const build = l.build as Record<string, unknown> | undefined;
+ for (const [key, value] of Object.entries(build ?? {})) {
+ if (!['head', 'shoulders', 'chest', 'waist', 'hips', 'limbs'].includes(key)) fail(`build has unknown "${key}"; it takes head, shoulders, chest, waist, hips, limbs`);
+ if (!(isNum(value) && (value as number) > 0)) fail(`build ${key} must be positive`);
+ }
+ const pose = l.pose as Record<string, Record<string, unknown>> | undefined;
+ for (const key of Object.keys(pose ?? {})) if (!['rotate', 'move', 'reach'].includes(key)) fail(`pose has unknown "${key}"; it takes rotate, move, reach`);
+ for (const [key, list] of Object.entries(pose ?? {})) {
+ for (const [joint, value] of Object.entries(list)) {
+ const numbers = key === 'reach' ? (value as { at?: unknown }).at : value;
+ const lengths = key === 'reach' ? [2, 3] : [3];
+ if (!(Array.isArray(numbers) && lengths.includes(numbers.length) && numbers.every(isNum))) fail(`pose ${key} "${joint}" must be ${key === 'reach' ? '{ at: [x, y] or [x, y, z] }' : '[x, y, z]'}`);
+ }
+ }
+ break;
+ }
+ case 'text':
+ if (typeof l.text !== 'string' || !l.text) fail('text must say something');
+ if (l.within !== undefined && !(Array.isArray(l.within) && l.within.length === 4 && l.within.every((v) => isNum(v) && v >= 0 && v <= 1))) fail('within must be [left, top, right, bottom], each 0..1');
+ if (l.face !== undefined) {
+ if (typeof l.face !== 'string') fail('face must name a face of a block, as "id.a"');
+ } else if (l.quad !== undefined) {
+ if (!(Array.isArray(l.quad) && l.quad.length === 4 && l.quad.every(isPair))) fail('quad must be four [x, y], in order round from the top left');
+ } else {
+ pair('at');
+ if (!(isNum(l.fontSize) && (l.fontSize as number) > 0)) fail('fontSize must be positive, in pixels');
+ }
+ if (l.font !== undefined && typeof l.font !== 'string') fail('font must be a family name or a font file in the project');
+ if (l.align !== undefined && !['left', 'center', 'right'].includes(l.align as string)) fail('align must be left, center or right');
+ if (l.tracking !== undefined && !isNum(l.tracking)) fail('tracking must be pixels');
+ if (l.thin !== undefined && !(isNum(l.thin) && (l.thin as number) >= 0)) fail('thin must be 0 or more pixels');
+ for (const key of ['grain', 'dry']) if (l[key] !== undefined && !(isNum(l[key]) && (l[key] as number) >= 0 && (l[key] as number) <= 1)) fail(`${key} must be 0..1`);
+ if (l.grainScale !== undefined && !(isNum(l.grainScale) && (l.grainScale as number) > 0)) fail('grainScale must be positive');
+ if (l.fill === undefined && l.stroke === undefined) fail('it needs a fill or a stroke, or it draws nothing');
+ break;
+ case 'adjust': {
+ const bad = adjustProblem(l.adjust);
+ if (bad) fail(`adjust ${bad}`);
+ break;
+ }
+ case 'filter': {
+ const bad = filterProblem(l.filter, l.params);
+ if (bad) fail(bad);
+ break;
+ }
+ case 'bloom':
+ for (const key of ['threshold', 'strength']) if (l[key] !== undefined && !(isNum(l[key]) && (l[key] as number) >= 0)) fail(`${key} must be 0 or more`);
+ if (l.threshold !== undefined && (l.threshold as number) > 1) fail('threshold must be 0..1');
+ if (l.radius !== undefined && !(isNum(l.radius) && (l.radius as number) > 0)) fail('radius must be positive, in pixels');
+ break;
+ case 'perspective':
+ if (!Array.isArray(l.vanish) || l.vanish.length === 0 || !l.vanish.every(isPair)) fail('vanish must be one or more [x, y]');
+ break;
+ case 'block': {
+ pair('at');
+ if (!(isNum(l.height) && (l.height as number) > 0)) fail('height must be pixels, from the corner at its foot up to its top');
+ if (!Array.isArray(l.vanish) || l.vanish.length < 1 || l.vanish.length > 2 || !l.vanish.every(isPair)) fail('vanish must be one or two [x, y], where its faces recede to');
+ if (!Array.isArray(l.depth) || l.depth.length !== (l.vanish as unknown[]).length || !l.depth.every((d) => isNum(d) && d > 0 && d <= 1)) fail('depth must give each vanishing point how far the face runs toward it, each above 0 and up to 1');
+ if (!Array.isArray(l.faces) || l.faces.length !== (l.vanish as unknown[]).length) fail('faces must give one fill for each vanishing point');
+ for (const face of l.faces as unknown[]) { const bad = checkFill(face); if (bad) fail(`face ${bad}`); }
+ if (l.roof !== undefined) { const bad = checkFill(l.roof); if (bad) fail(`roof ${bad}`); }
+ break;
+ }
+ case 'reflect':
+ if (!isNum(l.y) && !(Array.isArray(l.edge) && l.edge.length >= 2 && l.edge.every(isPair))) fail('y must be the line it mirrors about, or edge two or more [x, y] along where things meet the ground');
+ for (const key of ['reach', 'ripple', 'smear']) if (l[key] !== undefined && !(isNum(l[key]) && (l[key] as number) >= 0)) fail(`${key} must be 0 or more pixels`);
+ break;
+ case 'image':
+ if (typeof l.src !== 'string' || !l.src) fail('src must be the path of a picture in the project');
+ if (l.at !== undefined && !isPair(l.at)) fail('at must be [x, y]');
+ if (l.size !== undefined && !isPair(l.size)) fail('size must be [w, h]');
+ break;
+ case 'paint': {
+ if (!Array.isArray(l.strokes)) fail('strokes must be an array, which may start empty');
+ if (l.face !== undefined && typeof l.face !== 'string') fail('face must name a face of a block, as "id.a"');
+ if (l.from !== undefined && l.from !== 'below') fail('from must be "below"');
+ if (l.from !== undefined && (l.fill !== undefined || l.effects !== undefined || l.blend !== undefined)) fail('from "below" works on the picture itself, and takes no fill, effects or blend');
+ (l.strokes as Record<string, unknown>[]).forEach((s, n) => {
+ const bad = strokeProblem(s);
+ if (bad) fail(`stroke ${n} ${bad}`);
+ });
+ break;
+ }
+ case 'pixels': {
+ if (!Array.isArray(l.rows) || l.rows.length === 0 || !l.rows.every((r) => typeof r === 'string')) fail('rows must be strings, one character a pixel');
+ const pal = l.palette as Record<string, unknown> | undefined;
+ if (typeof pal !== 'object' || pal === null) fail('palette must be { character: colour }');
+ for (const [k, v] of Object.entries(pal!)) {
+ if ([...k].length !== 1) fail(`palette key ${JSON.stringify(k)} must be one character`);
+ if (!isColor(v)) fail(`palette "${k}" ${JSON.stringify(v)} must be a colour`);
+ }
+ const known = new Set(Object.keys(pal!));
+ const width = (l.rows as string[])[0]!.length;
+ (l.rows as string[]).forEach((row, i) => {
+ if ([...row].length !== width) fail(`row ${i} is ${[...row].length} wide and row 0 is ${width}: a slip here shifts everything after it`);
+ for (const ch of row) if (ch !== '.' && ch !== ' ' && !known.has(ch)) fail(`row ${i} has "${ch}", which is not in the palette; "." and " " are nothing`);
+ });
+ if (l.scale !== undefined) num('scale', positive);
+ if (l.at !== undefined) pair('at');
+ break;
+ }
+ case 'group':
+ if (!Array.isArray(l.layers)) fail('a group needs layers');
+ (l.layers as Record<string, unknown>[]).forEach((c, i) => checkLayer(c, `${where}.layers[${i}]`, ids));
+ break;
+ default:
+ }
+ if (l.fill !== undefined) { const bad = checkFill(l.fill); if (bad) fail(`fill ${bad}`); }
+ if (l.stroke !== undefined) {
+ const s = l.stroke as Record<string, unknown>;
+ if (typeof s !== 'object' || s === null || !isNum(s.width) || (s.width as number) <= 0) fail('stroke must be { color, width, align? }');
+ const bad = checkFill(s.color);
+ if (bad) fail(`stroke color ${bad}`);
+ if (s.align !== undefined && !['center', 'inside', 'outside'].includes(s.align as string)) fail('stroke align must be center, inside or outside');
+ if (s.join !== undefined && !['round', 'miter', 'bevel'].includes(s.join as string)) fail('stroke join must be round, miter or bevel');
+ if (s.cap !== undefined && !['round', 'butt', 'square'].includes(s.cap as string)) fail('stroke cap must be round, butt or square');
+ }
+ if (!['group', 'pixels', 'paint', 'figure', 'image', 'text', 'block', 'perspective', 'reflect', 'bloom', 'adjust', 'filter', 'line'].includes(l.shape as string) && l.fill === undefined && l.stroke === undefined && !l.erase) fail('it needs a fill or a stroke, or it draws nothing');
+ if (l.from !== undefined && l.shape !== 'paint') fail('from is for a paint layer');
+ if (l.guide !== undefined && typeof l.guide !== 'boolean') fail('guide must be true or false');
+ if (l.blur !== undefined && !(isNum(l.blur) && (l.blur as number) >= 0)) fail('blur must be 0 or more, in pixels');
+ if (l.blur && l.erase) fail('blur does not go with erase; put what cuts in a group with what it cuts, and blur the group');
+ if (l.opacity !== undefined && !(isNum(l.opacity) && l.opacity >= 0 && l.opacity <= 1)) fail('opacity must be 0..1');
+ if (l.blend !== undefined && !IMAGE_BLENDS.includes(l.blend as ImageBlend)) fail(`blend must be one of ${IMAGE_BLENDS.join(', ')}`);
+ for (const key of ['feather', 'clipFeather']) if (l[key] !== undefined && !(isNum(l[key]) && (l[key] as number) >= 0)) fail(`${key} must be 0 or more pixels`);
+ if (l.clipGrow !== undefined && !isNum(l.clipGrow)) fail('clipGrow must be pixels, more to grow what it clips to and less to shrink it');
+ if (l.clipInvert !== undefined && typeof l.clipInvert !== 'boolean') fail('clipInvert must be true or false');
+ if (l.blendIf !== undefined && !(Array.isArray(l.blendIf) && (l.blendIf.length === 2 || l.blendIf.length === 3) && l.blendIf.every((v) => isNum(v) && v >= 0 && v <= 1))) fail('blendIf must be [low, high] or [low, high, softness], each 0..1');
+ if (l.mirror !== undefined && l.mirror !== 'x' && l.mirror !== 'y') fail('mirror must be x or y');
+ if (l.clip !== undefined && typeof l.clip !== 'string') fail('clip must be a layer id');
+ if (l.transform !== undefined) {
+ const t = l.transform as Record<string, unknown>;
+ for (const key of Object.keys(t)) if (!['translate', 'rotate', 'scale', 'origin'].includes(key)) fail(`transform has an unknown field "${key}"`);
+ if (t.translate !== undefined && !isPair(t.translate)) fail('transform.translate must be [x, y]');
+ if (t.origin !== undefined && !isPair(t.origin)) fail('transform.origin must be [x, y]');
+ if (t.rotate !== undefined && !isNum(t.rotate)) fail('transform.rotate must be degrees');
+ if (t.scale !== undefined && !isNum(t.scale) && !isPair(t.scale)) fail('transform.scale must be a number or [x, y]');
+ }
+ if (l.effects !== undefined) {
+ if (!Array.isArray(l.effects)) fail('effects must be an array');
+ for (const e of l.effects as Record<string, unknown>[]) {
+ if (!['shadow', 'glow', 'innerShadow', 'innerGlow', 'bevel', 'overlay'].includes(e?.type as string)) fail(`an effect has type ${JSON.stringify(e?.type)}; there are shadow, glow, innerShadow, innerGlow, bevel, overlay`);
+ if (e.type === 'overlay') { const bad = checkFill(e.fill); if (bad) fail(`effect overlay: fill ${bad}`); }
+ if (e.blend !== undefined && !IMAGE_BLENDS.includes(e.blend as ImageBlend)) fail(`effect ${String(e.type)}: blend must be one of ${IMAGE_BLENDS.join(', ')}`);
+ if (e.shade !== undefined && !isColor(e.shade)) fail(`effect ${String(e.type)}: shade must be #rgb..#rrggbbaa`);
+ for (const key of Object.keys(e)) if (!['type', 'color', 'x', 'y', 'blur', 'opacity', 'size', 'angle', 'depth', 'shade', 'fill', 'blend'].includes(key)) fail(`effect ${String(e.type)} has an unknown field "${key}"`);
+ if (e.color !== undefined && !isColor(e.color)) fail(`effect ${String(e.type)}: color must be #rgb..#rrggbbaa`);
+ for (const k of ['x', 'y', 'blur', 'opacity', 'size', 'angle', 'depth']) if (e[k] !== undefined && !isNum(e[k])) fail(`effect ${String(e.type)}: ${k} must be a number`);
+ }
+ }
+}
+
+/** The source if it is well formed; otherwise throws, naming the layer and the field. */
+export function validateImageSource(raw: unknown): ImageSource {
+ if (typeof raw !== 'object' || raw === null || Array.isArray(raw)) throw new Error('an image source must be { size, layers }');
+ const s = raw as Record<string, unknown>;
+ for (const key of Object.keys(s)) if (!['version', 'size', 'background', 'tile', 'material', 'layers'].includes(key)) throw new Error(`unknown field "${key}"; an image has version, size, background, tile, material, layers`);
+ if (s.tile !== undefined && typeof s.tile !== 'boolean') throw new Error('tile must be true or false');
+ if (s.version !== undefined && s.version !== IMAGE_SOURCE_VERSION) throw new Error(`version ${String(s.version)} is not one this editor reads (${IMAGE_SOURCE_VERSION})`);
+ const [w, h] = typeof s.size === 'number' ? [s.size, s.size] : isPair(s.size) ? (s.size as number[]) : [NaN, NaN];
+ if (!Number.isInteger(w) || !Number.isInteger(h) || w! < 1 || h! < 1 || w! > MAX_IMAGE_SIZE || h! > MAX_IMAGE_SIZE) throw new Error(`size must be a whole number or [width, height], 1..${MAX_IMAGE_SIZE}`);
+ if (s.background !== undefined && !isColor(s.background)) throw new Error('background must be a colour; leave it out for a transparent picture');
+ if (!Array.isArray(s.layers)) throw new Error('layers must be an array');
+ const ids = new Set<string>();
+ (s.layers as Record<string, unknown>[]).forEach((l, i) => checkLayer(l, `layer ${i}${l?.id ? ` "${String(l.id)}"` : ''}`, ids));
+ if (s.material !== undefined) {
+ const m = s.material as Record<string, unknown> | null;
+ if (typeof m !== 'object' || m === null || Array.isArray(m)) throw new Error('material must be { relief?, height?, roughness?, metal? }');
+ for (const key of Object.keys(m)) if (!['relief', 'height', 'roughness', 'metal'].includes(key)) throw new Error(`material has unknown "${key}"; it takes relief, height, roughness, metal`);
+ if (m.relief !== undefined && !(isNum(m.relief) && (m.relief as number) >= 0 && (m.relief as number) <= 64)) throw new Error('material.relief must be 0..64, in pixels');
+ const drawn = (key: string, v: unknown): void => {
+ if (!Array.isArray(v) || v.length === 0) throw new Error(`material.${key} must be layers, one or more`);
+ (v as Record<string, unknown>[]).forEach((l, i) => checkLayer(l, `material.${key} layer ${i}${l?.id ? ` "${String(l.id)}"` : ''}`, ids));
+ };
+ if (m.height !== undefined) drawn('height', m.height);
+ for (const key of ['roughness', 'metal']) {
+ const v = m[key];
+ if (v === undefined) continue;
+ if (isNum(v)) { if (v < 0 || v > 1) throw new Error(`material.${key} must be 0..1, or layers`); }
+ else drawn(key, v);
+ }
+ }
+ return { version: IMAGE_SOURCE_VERSION, ...(s as unknown as ImageSource) };
+}
+
+export type ImageEdit =
+ | { op: 'set'; layer: string; fields: Record<string, unknown> }
+ | { op: 'insert'; layer: ImageLayer; before?: string; after?: string; into?: string }
+ | { op: 'remove'; layer: string }
+ | { op: 'move'; layer: string; before?: string; after?: string; into?: string }
+ | { op: 'paint'; layer: string; strokes?: readonly ImageMark[]; drop?: number; at?: number; remove?: number }
+ | { op: 'wrap'; layers: readonly string[]; group: Partial<ImageLayer> }
+ | { op: 'unwrap'; layer: string }
+ | {
+ op: 'pixels';
+ layer: string;
+ set?: readonly { row: number; at?: number; text: string }[];
+ rect?: readonly { x: number; y: number; w?: number; h?: number; text: string }[];
+ palette?: Readonly<Record<string, string | null>>;
+ }
+ | { op: 'settings'; fields: { size?: ImageSource['size']; background?: string | null; tile?: boolean | null; material?: ImageMaterial | null } };
+
+/** Every stroke width a source draws with, and how many layers use each: what drifts first across a set of icons. */
+export function strokeWidths(source: ImageSource): Record<string, number> {
+ const out: Record<string, number> = {};
+ const walk = (layers: readonly ImageLayer[]): void => {
+ for (const l of layers) {
+ if (l.stroke) out[String(l.stroke.width)] = (out[String(l.stroke.width)] ?? 0) + 1;
+ if (l.layers) walk(l.layers);
+ }
+ };
+ walk(source.layers);
+ return out;
+}
+
+/** A source with @p edits applied in order, where layers are named by id at any depth. Throws, naming what it could not find. */
+export function applyImageEdits(source: ImageSource, edits: readonly ImageEdit[]): ImageSource {
+ const clone = JSON.parse(JSON.stringify(source)) as { size: ImageSource['size']; background?: string; version?: number; layers: (ImageLayer & Record<string, unknown>)[] };
+ type Row = ImageLayer & Record<string, unknown>;
+ const allIds: string[] = [];
+ const find = (id: string, list: Row[] = clone.layers): { list: Row[]; index: number } | null => {
+ for (let i = 0; i < list.length; i++) {
+ if (list[i]!.id === id) return { list, index: i };
+ if (list[i]!.layers) {
+ const hit = find(id, list[i]!.layers as Row[]);
+ if (hit) return hit;
+ }
+ }
+ return null;
+ };
+ const need = (id: string): { list: Row[]; index: number } => {
+ const hit = find(id);
+ if (hit) return hit;
+ allIds.length = 0;
+ const walk = (list: Row[]): void => { for (const l of list) { if (l.id) allIds.push(l.id); if (l.layers) walk(l.layers as Row[]); } };
+ walk(clone.layers);
+ throw new Error(`no layer "${id}"; ids: ${allIds.join(', ') || '(none: give layers an id to edit them)'}`);
+ };
+ for (const edit of edits) {
+ switch (edit?.op) {
+ case 'set': {
+ const { list, index } = need(edit.layer);
+ for (const [k, v] of Object.entries(edit.fields ?? {})) {
+ if (v === null) delete list[index]![k];
+ else list[index]![k] = v;
+ }
+ break;
+ }
+ case 'insert': {
+ if (edit.into !== undefined) {
+ const { list, index } = need(edit.into);
+ const group = list[index]!;
+ if (group.shape !== 'group') throw new Error(`layer "${edit.into}" is not a group`);
+ (group.layers as Row[]).push(edit.layer as Row);
+ } else if (edit.before !== undefined) {
+ const { list, index } = need(edit.before);
+ list.splice(index, 0, edit.layer as Row);
+ } else if (edit.after !== undefined) {
+ const { list, index } = need(edit.after);
+ list.splice(index + 1, 0, edit.layer as Row);
+ } else clone.layers.push(edit.layer as Row);
+ break;
+ }
+ case 'remove': {
+ const { list, index } = need(edit.layer);
+ list.splice(index, 1);
+ break;
+ }
+ case 'move': {
+ const given = [edit.before, edit.after, edit.into].filter((v) => v !== undefined);
+ if (given.length > 1) throw new Error('move takes one of before, after and into');
+ const { list, index } = need(edit.layer);
+ const [row] = list.splice(index, 1);
+ const within = (l: Row): boolean => l.id === given[0] || ((l.layers as Row[] | undefined) ?? []).some(within);
+ if (given.length && within(row!)) {
+ list.splice(index, 0, row!);
+ throw new Error(`layer "${edit.layer}" cannot move next to or into "${String(given[0])}", which is itself or inside it`);
+ }
+ if (edit.into !== undefined) {
+ const target = need(edit.into);
+ const group = target.list[target.index]!;
+ if (group.shape !== 'group') throw new Error(`layer "${edit.into}" is not a group`);
+ (group.layers as Row[]).push(row!);
+ } else if (edit.before !== undefined) {
+ const target = need(edit.before);
+ target.list.splice(target.index, 0, row!);
+ } else if (edit.after !== undefined) {
+ const target = need(edit.after);
+ target.list.splice(target.index + 1, 0, row!);
+ } else clone.layers.push(row!);
+ break;
+ }
+ case 'paint': {
+ const { list, index } = need(edit.layer);
+ const layer = list[index]!;
+ if (layer.shape !== 'paint') throw new Error(`layer "${edit.layer}" is not paint`);
+ const had = layer.strokes as readonly ImageMark[];
+ const drop = edit.drop ?? 0;
+ if (!Number.isInteger(drop) || drop < 0 || drop > had.length) throw new Error(`layer "${edit.layer}" has ${had.length} strokes: cannot drop ${String(edit.drop)}`);
+ const kept = had.slice(0, had.length - drop);
+ const at = edit.at ?? kept.length;
+ const remove = edit.remove ?? 0;
+ if (!Number.isInteger(at) || at < 0 || at > kept.length || !Number.isInteger(remove) || remove < 0 || at + remove > kept.length) throw new Error(`layer "${edit.layer}" has ${kept.length} strokes: cannot replace ${remove} at ${at}`);
+ kept.splice(at, remove, ...(edit.strokes ?? []));
+ layer.strokes = kept;
+ break;
+ }
+ case 'wrap': {
+ if (!Array.isArray(edit.layers) || edit.layers.length === 0) throw new Error('wrap needs layers, the ids to put in the group');
+ const found = edit.layers.map((id) => ({ id, ...need(id) }));
+ if (found.some((f) => f.list !== found[0]!.list)) throw new Error(`wrap takes layers side by side, and ${edit.layers.join(', ')} are not all in one list`);
+ const list = found[0]!.list;
+ // Kept in the order they draw, whatever order they were named in: wrapping must not change what is over what.
+ const indices = found.map((f) => f.index).sort((a, b) => a - b);
+ const children = indices.map((i) => list[i]!);
+ for (const i of [...indices].reverse()) list.splice(i, 1);
+ list.splice(indices[0]!, 0, { ...edit.group, shape: 'group', layers: children } as Row);
+ break;
+ }
+ case 'unwrap': {
+ const { list, index } = need(edit.layer);
+ const group = list[index]!;
+ if (group.shape !== 'group') throw new Error(`layer "${edit.layer}" is not a group`);
+ const kept = ['transform', 'effects', 'opacity', 'blend', 'clip', 'mirror', 'visible'].filter((k) => group[k] !== undefined);
+ if (kept.length) throw new Error(`group "${edit.layer}" has ${kept.join(', ')}, which its layers would lose; set them to null first`);
+ list.splice(index, 1, ...(group.layers as Row[]));
+ break;
+ }
+ case 'pixels': {
+ const { list, index } = need(edit.layer);
+ const layer = list[index]!;
+ if (layer.shape !== 'pixels') throw new Error(`layer "${edit.layer}" is not pixels`);
+ const rows = [...(layer.rows as string[])];
+ if (edit.palette) {
+ const palette = { ...(layer.palette as Record<string, string>) };
+ for (const [key, value] of Object.entries(edit.palette)) {
+ if (value === null) delete palette[key];
+ else palette[key] = value;
+ }
+ layer.palette = palette;
+ }
+ for (const area of edit.rect ?? []) {
+ const [w, h, char] = [area.w ?? 1, area.h ?? 1, [...(area.text ?? '')]];
+ if (char.length !== 1) throw new Error(`a rect in "${edit.layer}" paints one character, not "${area.text}"`);
+ const width = [...rows[0]!].length;
+ if (!(Number.isInteger(area.x) && Number.isInteger(area.y) && Number.isInteger(w) && Number.isInteger(h) && area.x >= 0 && area.y >= 0 && w > 0 && h > 0 && area.x + w <= width && area.y + h <= rows.length)) {
+ throw new Error(`layer "${edit.layer}" is ${width} by ${rows.length}: a rect of ${w} by ${h} at ${area.x}, ${area.y} does not fit`);
+ }
+ for (let y = area.y; y < area.y + h; y++) {
+ const chars = [...rows[y]!];
+ chars.fill(char[0]!, area.x, area.x + w);
+ rows[y] = chars.join('');
+ }
+ }
+ for (const change of edit.set ?? []) {
+ const row = rows[change.row];
+ if (row === undefined) throw new Error(`layer "${edit.layer}" has rows 0..${rows.length - 1}, not ${change.row}`);
+ const chars = [...row], text = [...change.text], at = change.at ?? 0;
+ if (at < 0 || at + text.length > chars.length) throw new Error(`row ${change.row} of "${edit.layer}" is ${chars.length} wide: ${text.length} at ${at} does not fit`);
+ chars.splice(at, text.length, ...text);
+ rows[change.row] = chars.join('');
+ }
+ layer.rows = rows;
+ break;
+ }
+ case 'settings':
+ if (edit.fields?.size !== undefined) clone.size = edit.fields.size;
+ if (edit.fields?.background === null) delete clone.background;
+ else if (edit.fields?.background !== undefined) clone.background = edit.fields.background;
+ // The whole of each, or none: a relief is replaced with the layers that draw it.
+ for (const key of ['tile', 'material'] as const) {
+ if (edit.fields?.[key] === null) delete (clone as Record<string, unknown>)[key];
+ else if (edit.fields?.[key] !== undefined) (clone as Record<string, unknown>)[key] = edit.fields[key];
+ }
+ break;
+ default:
+ throw new Error(`an edit has op ${JSON.stringify((edit as { op?: unknown })?.op)}; there are set, insert, remove, move, paint, wrap, unwrap, pixels, settings`);
+ }
+ }
+ return validateImageSource(clone);
+}
diff --git a/sdk/src/image/index.ts b/sdk/src/image/index.ts
new file mode 100644
index 000000000..bf9d5f6df
--- /dev/null
+++ b/sdk/src/image/index.ts
@@ -0,0 +1,19 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
+/**
+ * @file index.ts
+ * @brief Pictures drawn from their source: the raster an `.esimage` is drawn by, for a game that ships recipes in place of pixels.
+ */
+export { renderImage, type RenderedImage, type RgbaBitmap, type ImageFigureDrawer, type ImageTextDrawer, type FlatFigure } from './imageRaster';
+export { validateImageSource, IMAGE_SOURCE_EXT, IMAGE_SOURCE_VERSION, MAX_IMAGE_SIZE, type ImageSource, type ImageLayer, type ImageMaterial } from './imageSource';
+export { renderMaterialMaps, type MaterialMaps } from './imageMaterial';
+
+// Importing this subpath INSTALLS the drawer of texture recipes — see tilemap/index.ts.
+import { renderImage } from './imageRaster';
+import { validateImageSource } from './imageSource';
+import { setTextureRecipeRenderer } from '../asset/textureRecipe';
+
+setTextureRecipeRenderer((source) => {
+ const picture = renderImage(validateImageSource(JSON.parse(source)));
+ return { width: picture.width, height: picture.height, pixels: picture.rgba };
+});
diff --git a/sdk/tests/texture-recipe.test.ts b/sdk/tests/texture-recipe.test.ts
new file mode 100644
index 000000000..8685e4034
--- /dev/null
+++ b/sdk/tests/texture-recipe.test.ts
@@ -0,0 +1,48 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
+/**
+ * @file texture-recipe.test.ts
+ * @brief A texture that is a recipe: which paths are one, what draws them, and that what is drawn is the picture its source says.
+ */
+import { afterEach, describe, expect, it } from 'vitest';
+import { hasTextureRecipeRenderer, isTextureRecipePath, renderTextureRecipe, setTextureRecipeRenderer } from '../src/asset/textureRecipe';
+import { getAddressableType } from '../src/assetTypes';
+
+afterEach(() => setTextureRecipeRenderer(null));
+
+describe('a texture recipe', () => {
+ it('is a path that ends in .esimage, whatever its case or its query', () => {
+ expect(isTextureRecipePath('assets/wall.esimage')).toBe(true);
+ expect(isTextureRecipePath('assets/Wall.ESIMAGE?v=3')).toBe(true);
+ expect(isTextureRecipePath('assets/wall.png')).toBe(false);
+ expect(isTextureRecipePath('assets/wall.esimage.png')).toBe(false);
+ });
+
+ it('is a texture to whatever asks what an asset is', () => {
+ expect(getAddressableType('assets/wall.esimage')).toBe('texture');
+ });
+
+ it('is refused by name where nothing draws recipes, and says what to import', async () => {
+ expect(hasTextureRecipeRenderer()).toBe(false);
+ await expect(renderTextureRecipe('{}', 'assets/wall.esimage')).rejects.toThrow(/assets\/wall\.esimage.*esengine\/image/);
+ });
+
+ it('is drawn by the raster once esengine/image is imported: the pixels are the picture its source says', async () => {
+ await import('../src/image/index');
+ expect(hasTextureRecipeRenderer()).toBe(true);
+ const source = JSON.stringify({ size: [8, 4], background: '#0000ff', layers: [{ shape: 'rect', at: [0, 0], size: [4, 4], fill: '#ff0000' }] });
+ const drawn = await renderTextureRecipe(source, 'assets/flag.esimage');
+ expect([drawn.width, drawn.height, drawn.pixels.length]).toEqual([8, 4, 8 * 4 * 4]);
+ const at = (x: number, y: number): number[] => Array.from(drawn.pixels.subarray((y * 8 + x) * 4, (y * 8 + x) * 4 + 4));
+ expect(at(1, 1)).toEqual([255, 0, 0, 255]);
+ expect(at(6, 2)).toEqual([0, 0, 255, 255]);
+ });
+
+ it('refuses a source that is not a picture, and a picture that needs a body to pose', async () => {
+ const { renderImage, validateImageSource } = await import('../src/image/index');
+ setTextureRecipeRenderer((source) => { const p = renderImage(validateImageSource(JSON.parse(source))); return { width: p.width, height: p.height, pixels: p.rgba }; });
+ await expect(renderTextureRecipe('{"size":8}', 'a.esimage')).rejects.toThrow();
+ const figure = JSON.stringify({ size: 64, layers: [{ id: 'f', shape: 'figure', at: [32, 60], height: 50 }] });
+ await expect(renderTextureRecipe(figure, 'a.esimage')).rejects.toThrow(/figure/);
+ });
+});
diff --git a/tools/apiSubsystems.mjs b/tools/apiSubsystems.mjs
index 17dd7a1fd..8df82ebdf 100644
--- a/tools/apiSubsystems.mjs
+++ b/tools/apiSubsystems.mjs
@@ -346,6 +346,16 @@ export const SUBSYSTEMS = [
whyZh: '曲线和按距离度量已经有检查,但目前只有河流会沿着它走,编辑器里也还没有绘制它的工具',
entry: ['Spline', 'SplineCurve'],
},
+ {
+ id: 'image',
+ title: 'Texture recipes',
+ titleZh: '贴图配方',
+ source: ['image'],
+ tier: 'experimental',
+ why: 'a recipe draws on the device to the very pixels its baked picture has, checked in a headless game, but it is drawn on the main thread at load, is not kept between runs, and has not been timed on a phone',
+ whyZh: '配方在设备上画出来的像素与烘焙好的图片逐像素一致,已在无头游戏里检查过;但它在加载时于主线程绘制,不跨次运行缓存,也没有在手机上计过时',
+ entry: ['renderImage', 'validateImageSource'],
+ },
{
id: 'rig2d',
title: '2D rigs',
diff --git a/tools/assetMetaTable.js b/tools/assetMetaTable.js
index 338c056af..f11601df3 100644
--- a/tools/assetMetaTable.js
+++ b/tools/assetMetaTable.js
@@ -33,6 +33,8 @@ export const EXT_TO_TYPE = Object.freeze({
'.gif': 'texture',
'.svg': 'texture',
'.ktx2': 'texture',
+ // A picture's source, drawn into a texture where it is loaded (sdk asset/textureRecipe.ts).
+ '.esimage': 'texture',
// Audio
'.wav': 'audio',
'.mp3': 'audio',
diff --git a/tools/lib/sdkProgram.mjs b/tools/lib/sdkProgram.mjs
index 91f6d8367..d36c6fdd4 100644
--- a/tools/lib/sdkProgram.mjs
+++ b/tools/lib/sdkProgram.mjs
@@ -69,6 +69,7 @@ export const ENTRIES = {
'worldgen': 'src/worldgen/entry.ts',
'water': 'src/water/index.ts',
'spline': 'src/spline/index.ts',
+ 'image': 'src/image/index.ts',
'voxel': 'src/voxel/index.ts',
'rig2d': 'src/rig2d/entry.ts',
'imported-scene': 'src/imported-scene/index.ts',
diff --git a/tools/releaseNotes.mjs b/tools/releaseNotes.mjs
index c237db50c..561afb12d 100644
--- a/tools/releaseNotes.mjs
+++ b/tools/releaseNotes.mjs
@@ -4666,6 +4666,8 @@ export const NOTED = {
{"note": "A scale map."},
"fix(terrain): a splatmap is read between its pixels - the ground took the nearest pixel of its splatmap, and a page near the eye samples finer than the paint, so every pixel of a splatmap was a flat square on the ground and a soft edge between two layers was a staircase":
{"note": "A splatmap is read between its pixels."},
+ "feat(assets): a texture can ship as its recipe - an .esimage named where a texture goes is carried as its source and drawn on the device when it loads, to the pixels its png has; the raster that draws it moved from the pipeline into the SDK as esengine/image, which an export adds when a recipe ships":
+ {"note": "A texture can ship as its recipe."},
"fix(terrain): a detail the pages cannot hold no longer cracks the ground - a tree that wanted more nodes than the atlas has pages was drawn in part by coarser pages standing in, which do not meet their finer neighbours' edges, and the pages were fought over every frame; the ground is now drawn at the share of its detail's range that fits, and says so once":
{"note": "A detail the pages cannot hold no longer cracks the ground."},
"fix(foliage): a far plant grows across the ground, not taller - a mesh plant kept in a far version was grown the same every way to cover the ground of those left out, so a flower that stood for ten stood ten times as high and a far meadow was a field of poles; it now grows across the ground only, and Foliage.farGrowUp gives its height a share of the growth back":