# gizlang/graphics

Graphics: every drawing of Gizlang in one module, with no operating system call. A Canvas is XRGB8888 pixels at an address the host gives. Shapes (rounded rectangles, rings, shadows, gradients, polygons, strokes) and OpenType text share one coverage rule and one blend. A Scene is a display list of them in float pixels: an engine records it once (GizBrowser's paint, a desktop's shell) and replays it at any scale onto a canvas, a damaged region or a GPU later.

```gizlang
import * as Graphics from "gizlang/graphics";
```

## Types

### `Canvas`

```gizlang
type Canvas = { at: i64; width: i64; height: i64; stride: i64; }
```

WIDTH x HEIGHT pixels at AT, rows STRIDE pixels apart: a whole picture, or a view of a rectangle of one.

- `at`: `i64`
- `width`: `i64`
- `height`: `i64`
- `stride`: `i64`

### `Rect`

```gizlang
type Rect = { x: f64; y: f64; w: f64; h: f64; }
```

A rectangle in pixels; its edges may fall between pixels.

- `x`: `f64`
- `y`: `f64`
- `w`: `f64`
- `h`: `f64`

### `Bitmap`

```gizlang
type Bitmap = { width: i64; height: i64; pixels: bytes; }
```

A picture in memory: WIDTH x HEIGHT pixels of four bytes each, red, green, blue and straight alpha, row by row.

- `width`: `i64`
- `height`: `i64`
- `pixels`: `bytes`

### `Radii`

```gizlang
type Radii = { topLeft: f64; topRight: f64; bottomRight: f64; bottomLeft: f64; }
```

The radius of each corner.

- `topLeft`: `f64`
- `topRight`: `f64`
- `bottomRight`: `f64`
- `bottomLeft`: `f64`

### `Stop`

```gizlang
type Stop = { at: f64; argb: i64; }
```

A color stop: its place on the gradient line (0 to 1) and its ARGB.

- `at`: `f64`
- `argb`: `i64`

### `Insets`

```gizlang
type Insets = { top: f64; right: f64; bottom: f64; left: f64; }
```

The four sides of a box: border widths.

- `top`: `f64`
- `right`: `f64`
- `bottom`: `f64`
- `left`: `f64`

### `Shadow`

```gizlang
type Shadow = { dx: f64; dy: f64; blur: f64; spread: f64; argb: i64; }
```

A shadow: its offset, its blur (CSS box-shadow: twice the Gaussian's deviation), its spread and its color.

- `dx`: `f64`
- `dy`: `f64`
- `blur`: `f64`
- `spread`: `f64`
- `argb`: `i64`

### `Gradient`

```gizlang
type Gradient = { angle: f64; radial: bool; stops: Vec<Stop>; }
```

A gradient: its stops along ANGLE degrees (0 points up, 90 right, as CSS linear-gradient lays its line), or circles
from the centre to the farthest corner when RADIAL.

- `angle`: `f64`
- `radial`: `bool`
- `stops`: `Vec<gizlang_graphics.Stop>`

### `Font`

```gizlang
type Font = { at: i64; }
```

A loaded OpenType font: a record of words at an address, its caches beside it. A negative `at` is a face of a
terminal's grid (gridFont): -1 - STYLE, with CELL_BOLD and CELL_ITALIC in STYLE.

- `at`: `i64`

### `Scene`

```gizlang
class Scene { ops: Vec<Op> = []; bitmaps: Vec<Bitmap> = []; constructor() {} fill(rect: Rect, corners: Radii, color: i64): void { this.ops.push(op(OP_FILL, rect, corners, color)); } border(rect: Rect, corners: Radii, widths: Insets, color: i64): void { let o = op(OP_BORDER, rect, corners, color); o.numbers = [widths.top, widths.right, widths.bottom, widths.left]; this.ops.push(o); } shadow(rect: Rect, corners: Radii, s: Shadow): void { let o = op(OP_SHADOW, rect, corners, s.argb); o.shadow = s; this.ops.push(o); } gradient(rect: Rect, corners: Radii, g: Gradient): void { let o = op(OP_GRADIENT, rect, corners, 0); o.gradient = g; this.ops.push(o); } text(font: Font, size: f64, x: f64, baseline: f64, text: string, color: i64, spacing: f64, rtl: bool = false): void { let o = op(OP_TEXT, { x, y: baseline, w: 0.0, h: 0.0 }, SQUARE, color); o.font = font; o.text = text; o.numbers = [size, spacing, rtl ? 1.0: 0.0]; this.ops.push(o); } stroke(points: Vec<f64>, width: f64, color: i64): void { let o = op(OP_STROKE, NOWHERE, SQUARE, color); o.numbers = [width].concat(points); this.ops.push(o); } bitmap(b: Bitmap): i64 { this.bitmaps.push(b); return this.bitmaps.length - 1; } image(id: i64, src: Rect, dst: Rect, corners: Radii = SQUARE): void { let o = op(OP_IMAGE, dst, corners, id); o.numbers = [src.x, src.y, src.w, src.h]; this.ops.push(o); } scales(scale: f64): Vec<f64> { let out: Vec<f64> = new Array(this.bitmaps.length).fill(0.0); let ks: Vec<Vec<f64>> = [[scale, scale]]; for (const o of this.ops) { const t = ks[ks.length - 1]; if (o.kind === OP_TRANSFORM) { ks.push([t[0] * o.numbers[0], t[1] * o.numbers[1]]); continue; } if (o.kind === OP_UNTRANSFORM) { if (ks.length> 1) { ks.pop(); } continue; } const n = o.numbers; if (o.kind !== OP_IMAGE || n[2] <= 0.0 || n[3] <= 0.0) { continue; } const k = max(o.rect.w * (t[0] <0.0 ? -t[0]: t[0]) / n[2], o.rect.h * (t[1] <0.0 ? -t[1]: t[1]) / n[3]); if (k> out[o.color]) { out[o.color] = k; } } return out; } replaceBitmap(id: i64, b: Bitmap): void { const old = this.bitmaps[id]; const fx = old.width> 0 ? f64(b.width) / f64(old.width): 1.0; const fy = old.height> 0 ? f64(b.height) / f64(old.height): 1.0; for (let i = 0; i <this.ops.length; i + = 1) { let o = this.ops[i]; if (o.kind !== OP_IMAGE || o.color !== id) { continue; } const n = o.numbers; o.numbers = [n[0] * fx, n[1] * fy, n[2] * fx, n[3] * fy]; this.ops[i] = o; } this.bitmaps[id] = b; } polygon(xs: Vec<f64>, ys: Vec<f64>, ends: Vec<i64>, color: i64): void { let o = op(OP_POLYGON, NOWHERE, SQUARE, color); let n: Vec<f64> = [f64(ends.length)]; for (const e of ends) { n.push(f64(e)); } for (let i = 0; i <xs.length; i + = 1) { n.push(xs[i]); n.push(ys[i]); } o.numbers = n; this.ops.push(o); } transform(sx: f64, sy: f64, tx: f64, ty: f64): void { let o = op(OP_TRANSFORM, NOWHERE, SQUARE, 0); o.numbers = [sx, sy, tx, ty]; this.ops.push(o); } untransform(): void { this.ops.push(op(OP_UNTRANSFORM, NOWHERE, SQUARE, 0)); } clip(rect: Rect, corners: Radii = SQUARE): void { this.ops.push(op(OP_CLIP, rect, corners, 0)); } unclip(): void { this.ops.push(op(OP_UNCLIP, NOWHERE, SQUARE, 0)); } size(): i64 { return this.ops.length; } replay(canvas: Canvas, scale: f64, scratch: mut Arena, dx: f64 = 0.0, dy: f64 = 0.0): void { let clips: Vec<Rect> = [{ x: 0.0, y: 0.0, w: f64(canvas.width), h: f64(canvas.height) }]; let bends: Vec<Rect> = [NOWHERE]; let bent: Vec<Radii> = [SQUARE]; let ks: Vec<Vec<f64>> = [[scale, scale, dx, dy]]; for (const o of this.ops) { const clip = clips[clips.length - 1]; const t = ks[ks.length - 1]; const kx = t[0]; const ky = t[1]; const ox = t[2]; const oy = t[3]; if (o.kind === OP_TRANSFORM) { const n = o.numbers; ks.push([kx * n[0], ky * n[1], ox + kx * n[2], oy + ky * n[3]]); continue; } if (o.kind === OP_UNTRANSFORM) { if (ks.length> 1) { ks.pop(); } continue; } if (o.kind === OP_CLIP) { const ax = o.rect.x * kx + ox; const bx = (o.rect.x + o.rect.w) * kx + ox; const ay = o.rect.y * ky + oy; const by = (o.rect.y + o.rect.h) * ky + oy; const x0 = max(clip.x, floor(least(ax, bx))); const y0 = max(clip.y, floor(least(ay, by))); const x1 = least(clip.x + clip.w, ceil(max(ax, bx))); const y1 = least(clip.y + clip.h, ceil(max(ay, by))); clips.push({ x: x0, y: y0, w: max(x1 - x0, 0.0), h: max(y1 - y0, 0.0) }); const k = o.corners; const kr = least(kx, ky); const round = k.topLeft + k.topRight + k.bottomRight + k.bottomLeft> 0.0; bends.push(round ? { x: o.rect.x * kx + ox, y: o.rect.y * ky + oy, w: o.rect.w * kx, h: o.rect.h * ky }: bends[bends.length - 1]); bent.push(round ? { topLeft: k.topLeft * kr, topRight: k.topRight * kr, bottomRight: k.bottomRight * kr, bottomLeft: k.bottomLeft * kr }: bent[bent.length - 1]); continue; } if (o.kind === OP_UNCLIP) { if (clips.length> 1) { clips.pop(); bends.pop(); bent.pop(); } continue; } if (clip.w <= 0.0 || clip.h <= 0.0 || kx === 0.0 || ky === 0.0) { continue; } const target = view(canvas, i64(clip.x), i64(clip.y), i64(clip.w), i64(clip.h)); const fx = kx <0.0; const fy = ky <0.0; const sx = fx ? -kx: kx; const sy = fy ? -ky: ky; const r: Rect = { x: (o.rect.x + (fx ? o.rect.w: 0.0)) * kx + ox - clip.x, y: (o.rect.y + (fy ? o.rect.h: 0.0)) * ky + oy - clip.y, w: o.rect.w * sx, h: o.rect.h * sy }; const k0 = o.corners; const kr = least(sx, sy); const k = fx ? { topLeft: k0.topRight, topRight: k0.topLeft, bottomRight: k0.bottomLeft, bottomLeft: k0.bottomRight }: k0; const c: Radii = fy ? { topLeft: k.bottomLeft * kr, topRight: k.bottomRight * kr, bottomRight: k.topRight * kr, bottomLeft: k.topLeft * kr }: { topLeft: k.topLeft * kr, topRight: k.topRight * kr, bottomRight: k.bottomRight * kr, bottomLeft: k.bottomLeft * kr }; const n = o.numbers; if (outside(o, r, n, kr, sy, clip)) { continue; } if (o.kind === OP_POLYGON) { const count = i64(n[0]); if (n.length <count + 7) { continue; } let ends: Vec<i64> = []; for (let i = 1; i <= count; i + = 1) { ends.push(i64(n[i])); } let xs: Vec<f64> = []; let ys: Vec<f64> = []; let x0 = n[count + 1] * kx + ox - clip.x; let y0 = n[count + 2] * ky + oy - clip.y; let x1 = x0; let y1 = y0; for (let i = count + 1; i + 1 <n.length; i + = 2) { const x = n[i] * kx + ox - clip.x; const y = n[i + 1] * ky + oy - clip.y; xs.push(x); ys.push(y); x0 = least(x0, x); x1 = max(x1, x); y0 = least(y0, y); y1 = max(y1, y); } const need = (ceil(x1) - floor(x0) + 3.0) * (ceil(y1) - floor(y0) + 1.0) * 9.0 + 64.0; if (xs.length <3 || need> f64(scratch.size - scratch.used)) { continue; } polygon(target, xs, ys, ends, o.color & 0xffffff, (o.color>> 24) & 255, scratch); continue; } switch (o.kind) { case OP_FILL: { rounded(target, r, c, o.color); break; } case OP_BORDER: { ring(target, r, c, n[fy ? 2: 0] * sy, n[fx ? 3: 1] * sx, n[fy ? 0: 2] * sy, n[fx ? 1: 3] * sx, o.color); break; } case OP_SHADOW: { const s = o.shadow; boxShadow(target, r, c, s.dx * kx, s.dy * ky, s.blur * kr, s.spread * kr, s.argb); break; } case OP_GRADIENT: { gradient(target, r, c, o.gradient.angle, o.gradient.radial, o.gradient.stops); break; } case OP_TEXT: { textAt(target, o.font.at, n[0] * sy, r.x, r.y, o.text, n[1] * sx, o.color, n[2] !== 0.0); break; } case OP_IMAGE: { const own = c.topLeft + c.topRight + c.bottomRight + c.bottomLeft> 0.0; const b = bends[bends.length - 1]; const shape = own ? r: { x: b.x - clip.x, y: b.y - clip.y, w: b.w, h: b.h }; image(target, this.bitmaps[o.color], { x: fx ? n[0] + n[2]: n[0], y: fy ? n[1] + n[3]: n[1], w: fx ? -n[2]: n[2], h: fy ? -n[3]: n[3] }, r, own ? c: bent[bent.length - 1], shape); break; } case OP_STROKE: { let points: Vec<f64> = []; for (let i = 1; i + 1 <n.length; i + = 2) { points.push(n[i] * kx + ox - clip.x); points.push(n[i + 1] * ky + oy - clip.y); } stroke(target, points, n[0] * kr, o.color); break; } default: {} } } } replayCells(cells: Cells, dx: f64 = 0.0, dy: f64 = 0.0): void { let clips: Vec<Rect> = [{ x: 0.0, y: 0.0, w: f64(cells.columns) * GRID_W, h: f64(cells.rows) * GRID_H }]; let ks: Vec<Vec<f64>> = [[1.0, 1.0, dx, dy]]; for (const o of this.ops) { const clip = clips[clips.length - 1]; const t = ks[ks.length - 1]; const kx = t[0]; const ky = t[1]; const ox = t[2]; const oy = t[3]; if (o.kind === OP_TRANSFORM) { const n = o.numbers; ks.push([kx * n[0], ky * n[1], ox + kx * n[2], oy + ky * n[3]]); continue; } if (o.kind === OP_UNTRANSFORM) { if (ks.length> 1) { ks.pop(); } continue; } const ax = o.rect.x * kx + ox; const bx = (o.rect.x + o.rect.w) * kx + ox; const ay = o.rect.y * ky + oy; const by = (o.rect.y + o.rect.h) * ky + oy; const r: Rect = { x: least(ax, bx), y: least(ay, by), w: abs(bx - ax), h: abs(by - ay) }; if (o.kind === OP_CLIP) { const x0 = max(clip.x, r.x); const y0 = max(clip.y, r.y); const x1 = least(clip.x + clip.w, r.x + r.w); const y1 = least(clip.y + clip.h, r.y + r.h); clips.push({ x: x0, y: y0, w: max(x1 - x0, 0.0), h: max(y1 - y0, 0.0) }); continue; } if (o.kind === OP_UNCLIP) { if (clips.length> 1) { clips.pop(); } continue; } if (clip.w <= 0.0 || clip.h <= 0.0) { continue; } switch (o.kind) { case OP_FILL: { cells.area(r, clip, o.color); break; } case OP_GRADIENT: { cells.area(r, clip, meanOf(o.gradient.stops)); break; } case OP_BORDER: { cells.frame(r, clip, o.numbers, o.corners.topLeft> 0.0, o.color); break; } case OP_TEXT: { cells.write(r.x, r.y, clip, o.text, o.color, o.font.at <0 ? -1 - o.font.at: 0); break; } case OP_IMAGE: { cells.place(this.bitmaps[o.color], r, clip); break; } default: {} } } cells.join(); } }
```

A display list: what a Canvas draws, recorded in order with nested clips, in float pixels. Recording draws nothing;
replay() draws it at any scale. An engine records a frame once and replays it onto a screen, a region or a file.

- `ops`: `Vec<gizlang_graphics.Op>`
- `bitmaps`: `Vec<gizlang_graphics.Bitmap>`

### `Pictured`

```gizlang
type Pictured = { bitmap: Bitmap; column: i64; row: i64; columns: i64; rows: i64; }
```

A picture over the cells COLUMNS x ROWS from (COLUMN, ROW).

- `bitmap`: `gizlang_graphics.Bitmap`
- `column`: `i64`
- `row`: `i64`
- `columns`: `i64`
- `rows`: `i64`

### `Cells`

```gizlang
class Cells { columns: i64; rows: i64; text: Vec<string> = []; fg: Vec<i64> = []; bg: Vec<i64> = []; style: Vec<i64> = []; pictures: Vec<Pictured> = []; base: i64 = 0; cursor: Vec<i64> = []; constructor(columns: i64, rows: i64) { this.columns = columns; this.rows = rows; this.clear(); } clear(): void { const n = this.columns * this.rows; this.text = new Array(n).fill(" "); this.fg = new Array(n).fill(0); this.bg = new Array(n).fill(0); this.style = new Array(n).fill(0); this.pictures = []; this.base = 0; this.cursor = []; } put(c: i64, r: i64, text: string, fg: i64, bg: i64, style: i64): void { const w = graphemeWidth(text); if (r <0 || r> = this.rows || c <0 || c + (w> 1 ? w: 1)> this.columns) { return; } const i = r * this.columns + c; this.text[i] = text; this.fg[i] = fg; this.bg[i] = bg; this.style[i] = style; if (w === 2) { this.text[i + 1] = ""; this.fg[i + 1] = fg; this.bg[i + 1] = bg; this.style[i + 1] = style; } } line(c: i64, r: i64, text: string, fg: i64, bg: i64, style: i64): i64 { let at = c; for (const g of graphemes(text)) { const w = graphemeWidth(g); if (w === 0) { continue; } if (at + w> this.columns) { break; } this.put(at, r, g, fg, bg, style); at + = w; } return at; } area(rect: Rect, clip: Rect, color: i64): void { if (((color>> 24) & 255) === 0) { return; } const columns = this.columns; const rows = this.rows; const x0 = max(rect.x, clip.x); const y0 = max(rect.y, clip.y); const x1 = least(rect.x + rect.w, clip.x + clip.w); const y1 = least(rect.y + rect.h, clip.y + clip.h); if (x1 <= x0 || y1 <= y0) { return; } const flat = y1 - y0 <GRID_H * 0.5; const narrow = x1 - x0 <GRID_W * 0.5; if (flat && narrow) { return; } if (flat) { const row = i64(floor(y0 / GRID_H)); const part = (y0 - f64(row) * GRID_H) / GRID_H; for (let c = i64(floor(x0 / GRID_W)); c <i64(ceil(x1 / GRID_W)); c + = 1) { if (row <0 || row> = rows || c <0 || c> = columns) { continue; } const i = row * columns + c; if (this.text[i] !== " ") { if (this.text[i] !== ACROSS) { this.style[i] = this.style[i] | (part> 0.6 ? CELL_UNDERLINE: CELL_STRIKE); } } else { this.text[i] = ACROSS; this.fg[i] = color; } } return; } if (narrow) { if (y1 - y0 <GRID_H * 1.5) { return; } const c = i64(floor(x0 / GRID_W)); for (let row = i64(floor(y0 / GRID_H + 0.5)); row <i64(floor(y1 / GRID_H + 0.5)); row + = 1) { if (row <0 || row> = rows || c <0 || c> = columns) { continue; } const i = row * columns + c; if (this.text[i] === " ") { this.text[i] = DOWN; this.fg[i] = color; } } return; } const c0 = edge(x0, GRID_W); const c1 = edge(x1, GRID_W); const r0 = edge(y0, GRID_H); const r1 = edge(y1, GRID_H); const opaque = ((color>> 24) & 255) === 255; if (this.base === 0 && c0 <= 0 && r0 <= 0 && c1> = columns && opaque) { this.base = color; } const base = this.base; const left = c0> 0 ? c0: 0; const right = c1 <columns ? c1: columns; const top = r0> 0 ? r0: 0; const bottom = r1 <rows ? r1: rows; if (opaque) { fillCellRows(this.bg, columns, left, right, top, bottom, color); } else { blendCellRows(this.bg, columns, left, right, top, bottom, color, base); } fillCellRows(this.text, columns, left, right, top, bottom, " "); fillCellRows(this.style, columns, left, right, top, bottom, 0); } frame(rect: Rect, clip: Rect, widths: Vec<f64>, round: bool, color: i64): void { if (((color>> 24) & 255) === 0) { return; } const columns = this.columns; const rows = this.rows; const top = edge(rect.y, GRID_H); const bottom = edge(rect.y + rect.h, GRID_H) - 1; const left = edge(rect.x, GRID_W); const right = edge(rect.x + rect.w, GRID_W) - 1; const c0 = edge(clip.x, GRID_W); const c1 = edge(clip.x + clip.w, GRID_W); const r0 = edge(clip.y, GRID_H); const r1 = edge(clip.y + clip.h, GRID_H); const inside = (c: i64, r: i64): bool => c> = c0 && c <c1 && r> = r0 && r <r1; const mark = (c: i64, r: i64, g: string): void => { if (!inside(c, r) || r <0 || r> = rows || c <0 || c> = columns) { return; } const i = r * columns + c; this.text[i] = g; this.fg[i] = color; }; if (top === bottom) { if (widths[3]> 0.0) { mark(left, top, "["); } if (widths[1]> 0.0) { mark(right, top, "]"); } return; } for (let c = left + 1; c <right; c + = 1) { if (widths[0]> 0.0) { mark(c, top, ACROSS); } if (widths[2]> 0.0) { mark(c, bottom, ACROSS); } } for (let r = top + 1; r <bottom; r + = 1) { if (widths[3]> 0.0) { mark(left, r, DOWN); } if (widths[1]> 0.0) { mark(right, r, DOWN); } } const corner = (c: i64, r: i64, side: f64, end: f64, g: string): void => { if (side> 0.0 && end> 0.0) { mark(c, r, g); } else if (side> 0.0) { mark(c, r, DOWN); } else if (end> 0.0) { mark(c, r, ACROSS); } }; corner(left, top, widths[3], widths[0], round ? "╭": "┌"); corner(right, top, widths[1], widths[0], round ? "╮": "┐"); corner(left, bottom, widths[3], widths[2], round ? "╰": "└"); corner(right, bottom, widths[1], widths[2], round ? "╯": "┘"); } write(x: f64, baseline: f64, clip: Rect, text: string, color: i64, style: i64): void { if (((color>> 24) & 255) === 0) { return; } const row = edge(baseline - GRID_ASCENT, GRID_H); if (row <0 || row> = this.rows || row <edge(clip.y, GRID_H) || row> = edge(clip.y + clip.h, GRID_H)) { return; } const first = edge(clip.x, GRID_W); const last = edge(clip.x + clip.w, GRID_W); let c = edge(x, GRID_W); let previous = -1; for (const g of graphemes(text)) { const w = graphemeWidth(g); if (w === 0) { if (previous> = 0) { this.text[previous] = this.text[previous] + g; } continue; } if (c> = first && c + w <= last && c> = 0 && c + w <= this.columns) { const i = row * this.columns + c; const keep = this.bg[i]; this.put(c, row, g, color, keep, style); previous = i; } c + = w; } } place(bitmap: Bitmap, rect: Rect, clip: Rect): void { const columns = this.columns; const rows = this.rows; const x0 = max(rect.x, clip.x); const y0 = max(rect.y, clip.y); const x1 = least(rect.x + rect.w, clip.x + clip.w); const y1 = least(rect.y + rect.h, clip.y + clip.h); const c0 = edge(x0, GRID_W); const r0 = edge(y0, GRID_H); const c1 = edge(x1, GRID_W); const r1 = edge(y1, GRID_H); if (c1 <= c0 || r1 <= r0 || c0 <0 || r0 <0 || c1> columns || r1> rows) { return; } fillCellRows(this.text, columns, c0, c1, r0, r1, " "); this.pictures.push({ bitmap, column: c0, row: r0, columns: c1 - c0, rows: r1 - r0 }); } join(): void { const columns = this.columns; const rows = this.rows; joinCellRules(this.text, columns, rows); } }
```

A terminal's surface: COLUMNS x ROWS cells, each a grapheme ("" in the cell after a wide one), its foreground and
background (ARGB; 0 is the terminal's own) and its style bits (CELL_*), the pictures placed over cells, the
background of the page under all (BASE: the terminal shows its own there) and where the terminal's cursor stands
([column, row], or none). Scene.replayCells draws a scene on it; gizlang/terminal sends what changed.

- `columns`: `i64`
- `rows`: `i64`
- `text`: `Vec<string>`
- `fg`: `Vec<i64>`
- `bg`: `Vec<i64>`
- `style`: `Vec<i64>`
- `pictures`: `Vec<gizlang_graphics.Pictured>`
- `base`: `i64`
- `cursor`: `Vec<i64>`

### `Face`

```gizlang
type Face = { font: Font; family: string; weight: i64; italic: bool; }
```

One face: its font, its family (lower case), weight and slant.

- `font`: `gizlang_graphics.Font`
- `family`: `string`
- `weight`: `i64`
- `italic`: `bool`

### `Run`

```gizlang
type Run = { face: i64; text: string; count: i64; }
```

A run of text in one face (Fonts.runs): the face, the text and its code points.

- `face`: `i64`
- `text`: `string`
- `count`: `i64`

### `Fonts`

```gizlang
class Fonts { faces: Vec<Face> = []; aliases: Map<string, string> = new Map(); constructor() {} loaders: Map<i64, () => Font> = new Map(); covered: Map<i64, i64> = new Map(); private picked: Map<string, i64> = new Map(); add(font: Font, family: string, weight: i64, italic: bool): void { this.faces.push({ font, family: family.toLowerCase(), weight, italic }); this.picked = new Map(); } later(load: () => Font, family: string, weight: i64, italic: bool): void { this.loaders.set(this.faces.length, load); this.faces.push({ font: { at: 0 }, family: family.toLowerCase(), weight, italic }); this.picked = new Map(); } font(i: i64): Font { const load = this.loaders.get(i); if (load !== undefined) { this.loaders.delete(i); this.faces[i].font = load!(); } return this.faces[i].font; } holds(i: i64, code: i64): bool { const f = this.font(i); return f.at !== 0 && f.has(code); } alias(name: string, family: string): void { this.aliases.set(name.toLowerCase(), family.toLowerCase()); this.picked = new Map(); } pick(families: Vec<string>, weight: i64, italic: bool): i64 { const key = `${weight }${ italic ? "i": "n" }${ families.join("\n") }`; const known = this.picked.get(key); if (known !== undefined) { return known!; } const face = this.search(families, weight, italic); this.picked.set(key, face); return face; } private search(families: Vec<string>, weight: i64, italic: bool): i64 { for (const name of families) { let family = name.toLowerCase(); if (!this.has(family)) { family = this.aliases.get(family) ?? ""; } if (family === "" || !this.has(family)) { continue; } return this.nearest(family, weight, italic); } const fallback = this.aliases.get("sans-serif") ?? (this.faces.length> 0 ? this.faces[0].family: ""); return this.faces.length === 0 ? -1: this.nearest(fallback, weight, italic); } has(family: string): bool { for (const f of this.faces) { if (f.family === family) { return true; } } return false; } nearest(family: string, weight: i64, italic: bool): i64 { let best = -1; let bestScore = 1 <<40; for (let i = 0; i <this.faces.length; i + = 1) { const f = this.faces[i]; if (f.family !== family) { continue; } let score = f.weight> weight ? (f.weight - weight) * (weight> = 500 ? 1: 3): (weight - f.weight) * (weight> = 500 ? 3: 1); if (f.italic !== italic) { score + = 100000; } if (score <bestScore) { bestScore = score; best = i; } } return best; } covering(face: i64, code: i64): i64 { if (face <0 || code <0x80) { return face; } const key = (face <<21) | code; const known = this.covered.get(key); if (known !== undefined) { return known!; } let found = face; if (!this.holds(face, code)) { const weight = this.faces[face].weight; for (let i = 0; i <this.faces.length && found === face; i + = 1) { if (this.faces[i].weight === weight && this.holds(i, code)) { found = i; } } for (let i = 0; i <this.faces.length && found === face; i + = 1) { if (this.faces[i].weight === 400 && this.holds(i, code)) { found = i; } } } this.covered.set(key, found); return found; } advance(face: i64, code: i64, size: f64): f64 { const f = face <0 ? NO_FONT: this.font(face); if (f.at === 0) { return size * 0.5; } return f.advance(code, size); } measure(face: i64, text: string, size: f64, letter: f64): f64 { let width = 0.0; for (const run of this.runs(face, text)) { width + = (run.face <0 ? 0.0: this.font(run.face).measure(run.text, size)) + letter * f64(run.count); } return width; } runs(face: i64, text: string): Vec<Run> { let out: Vec<Run> = []; const data = utf8(text); let at = 0; let start = 0; let runFace = -1; let count = 0; while (at <data.length) { const cp = codePointAt(data, at); const own = this.covering(face, cp.value); if (own !== runFace && count> 0) { out.push({ face: runFace, text: string(data.slice(start, at)), count }); start = at; count = 0; } runFace = own; at = cp.next; count + = 1; } if (count> 0) { out.push({ face: runFace, text: string(data.slice(start, data.length)), count }); } return out; } ascent(face: i64, size: f64): f64 { const f = face <0 ? NO_FONT: this.font(face); return f.at === 0 ? size * 0.8: f.ascent(size); } descent(face: i64, size: f64): f64 { const f = face <0 ? NO_FONT: this.font(face); return f.at === 0 ? size * 0.2: f.descent(size); } normal(face: i64, size: f64): f64 { const f = face <0 ? NO_FONT: this.font(face); if (f.at === 0) { return size * 1.2; } return f.ascent(size) + f.descent(size) + f.gap(size); } }
```

The faces a program draws text with, and the generic families it maps onto them: the face of each character (the
style's families, the nearest weight, then any face that has the glyph) and exact advances. A program adds faces
loaded, or loaders that run at a face's first use (folderFonts).

- `faces`: `Vec<gizlang_graphics.Face>`
- `aliases`: `_gizlang_sdk_collections.Map<string, string>` — A generic or missing family name (sans-serif, Inter, system-ui) and the family it stands for.
- `loaders`: `_gizlang_sdk_collections.Map<i64, () => gizlang_graphics.Font>` — The loaders of the faces added by later that have not been used yet, by face.
- `covered`: `_gizlang_sdk_collections.Map<i64, i64>` — The face that draws each character in each face (covering), by face << 21 | code.
- `picked`: `_gizlang_sdk_collections.Map<string, i64>` — The face pick gave for each weight, slant and list of families: a layout asks for the same few for every run of
text, and a search of all the faces for each was a twentieth of a page's layout. A new face or alias empties it.

## Functions

### `argb`

```gizlang
function argb(color: i64, alpha: i64): i64
```

COLOR (0xRRGGBB) at ALPHA (0 to 255) as one 0xAARRGGBB value.

Effects: fail.

### `area`

```gizlang
function area(x: i64, y: i64, w: i64, h: i64): Rect
```

The rectangle of whole pixels at (X, Y) of W x H.

### `radii`

```gizlang
function radii(r: f64): Radii
```

One radius for every corner.

### `polygonMask`

```gizlang
function polygonMask(area: i64, mask: i64, w: i64, h: i64, xs: Vec<f64>, ys: Vec<f64>, dx: f64, dy: f64, ends: Vec<i64> = []): void
```

The coverage mask of the closed polygon through (XS[i], YS[i]), each point moved by (DX, DY), in the W x H MASK, through
AREA (of W + 2 by H f64 deltas, cleared here): the non-zero winding of its edges. ENDS splits the points into closed
contours, each the index after its last point (empty: one contour).

Effects: fail, read, write.

### `insets`

```gizlang
function insets(w: f64): Insets
```

The same width on every side.

### `rgb`

```gizlang
function rgb(r: i64, g: i64, b: i64): i64
```

An opaque color of red, green and blue (each clamped to 0 to 255).

Effects: fail.

### `over`

```gizlang
function over(to: i64, from: i64, count: i64): void
```

COUNT premultiplied ARGB pixels at FROM over the XRGB pixels at TO (Porter-Duff over): a client buffer onto a screen.

Effects: fail, read, write.

### `gridFont`

```gizlang
function gridFont(style: i64): Font
```

The face of a terminal's grid in STYLE (CELL_BOLD, CELL_ITALIC, and a text decoration's CELL_UNDERLINE or CELL_STRIKE):
it draws nothing on a Canvas, and each grapheme takes its cells (gizlang/unicode) times GRID_W at any size, one line GRID_H. Cells draws its text.

Effects: fail.

### `gridFonts`

```gizlang
function gridFonts(): Fonts
```

The faces of a terminal's grid, regular, bold and italic, as the family "monospace" that every family stands for:
a page laid out with them falls on the cells of Viewport.cells.

Effects: fail, read, write, alloc.

### `fontBudget`

```gizlang
function fontBudget(): i64
```

The arena bytes that loading one font takes: its record, tables and caches (the file is the caller's).

Effects: fail.

### `loadFont`

```gizlang
function loadFont(data: i64, size: i64, a: mut Arena): Font throws string
```

The font in the OpenType file of SIZE bytes at DATA (TrueType or CFF outlines; the first face of a collection), its
record and caches from A. DATA is the caller's and stays as it is while the font is used.

Effects: fail, read, write, alloc.

### `constructor`

```gizlang
constructor()
```

An empty scene.

Effects: fail, write, alloc.

### `constructor`

```gizlang
constructor(columns: i64, rows: i64)
```

COLUMNS x ROWS blank cells.

Effects: fail, read, write, alloc.

### `constructor`

```gizlang
constructor()
```

No faces and no aliases: add faces with add or later.

Effects: fail, write, alloc.

### `breakBetween`

```gizlang
function breakBetween(previous: i64, code: i64): bool
```

Whether a line may break before CODE when PREVIOUS precedes it, without a space between: CJK ideographs, kana and
Hangul break between any two, and a line may break after a hyphen or a slash (UAX #14, cut to the text of a UI).

### `wide`

```gizlang
function wide(code: i64): bool
```

CJK and Hangul: each character is a word of its own for line breaking.

### `fontFolders`

```gizlang
function fontFolders(): Vec<string>
```

The system's font folders, in order. On Linux and GizOS: Pretendard first (the faces of the UI), then Noto (CJK) and
DejaVu (Greek, Cyrillic, Hebrew, Arabic) of each XDG data folder; the others only draw what Pretendard lacks
(Fonts.covering). On macOS the system's and the user's Library folders; on Windows its Fonts folder.

Effects: fail, io, alloc.

### `folderFonts`

```gizlang
function folderFonts(folders: Vec<string>): Fonts throws string
```

Every OpenType face in the folders FOLDERS (one level, missing folders skipped), named Family-Style.ttf, .otf or .ttc
(its first face): the style gives the weight (WEIGHTS) and Italic the slant. A font the text does not name falls back
to the first family; a character its face lacks, to the first face that has it, in folder order.

Effects: fail, read, write, io, alloc.

### `rightToLeftCode`

```gizlang
function rightToLeftCode(code: i64): bool
```

Whether CODE is written right to left (Hebrew, Arabic, Syriac, Thaana, N'Ko and their presentation forms).

### `strongOf`

```gizlang
function strongOf(text: string): i64
```

The class of TEXT for bidi: its first strong letter's, else a number, else none.

Effects: fail.

## Methods

### `Canvas.view`

```gizlang
function Canvas.view(self: Canvas, x: i64, y: i64, w: i64, h: i64): Canvas
```

The rectangle at (X, Y) of W x H of CANVAS as a canvas of its own.

Effects: fail.

### `Canvas.fill`

```gizlang
function Canvas.fill(self: Canvas, rect: Rect, corners: Radii, color: i64): void
```

RECT with corners RADII filled with ARGB, its edges by exact coverage.

Effects: fail, read, write, alloc.

### `Canvas.border`

```gizlang
function Canvas.border(self: Canvas, rect: Rect, corners: Radii, widths: Insets, color: i64): void
```

The border of RECT (corners RADII) WIDTHS wide on each side, in ARGB; inner corners follow the outer ones.

Effects: fail, read, write, alloc.

### `Canvas.shadow`

```gizlang
function Canvas.shadow(self: Canvas, rect: Rect, corners: Radii, s: Shadow): void
```

The shadow that RECT (corners RADII) casts. Its inside is left alone: the shape that casts it covers it.

Effects: fail, read, write, alloc.

### `Canvas.gradient`

```gizlang
function Canvas.gradient(self: Canvas, rect: Rect, corners: Radii, g: Gradient): void
```

RECT (corners RADII) filled with G.

Effects: fail, read, write, alloc.

### `Canvas.stroke`

```gizlang
function Canvas.stroke(self: Canvas, points: Vec<f64>, width: f64, color: i64): void
```

The polyline through POINTS (x, y pairs) stroked WIDTH wide with round joins and caps.

Effects: fail, read, write.

### `Canvas.polygon`

```gizlang
function Canvas.polygon(self: Canvas, xs: Vec<f64>, ys: Vec<f64>, color: i64, scratch: mut Arena, ends: Vec<i64> = []): void
```

The closed polygon through (XS[i], YS[i]) by non-zero winding, in contours that ENDS splits (polygon); its masks come
from SCRATCH and go back to it.

Effects: fail, read, write.

### `Canvas.text`

```gizlang
function Canvas.text(self: Canvas, font: Font, size: f64, x: f64, baseline: f64, text: string, color: i64, spacing: f64 = 0.0, rtl: bool = false): f64
```

TEXT in FONT at SIZE pixels, the pen from X on BASELINE, SPACING added after each character; the pen's end.

Effects: fail, read, write, alloc.

### `Canvas.image`

```gizlang
function Canvas.image(self: Canvas, bitmap: Bitmap, src: Rect, dst: Rect): void
```

The part SRC of BITMAP drawn into DST, scaled to fit it.

Effects: fail, read, write, console, io, alloc.

### `Canvas.blur`

```gizlang
function Canvas.blur(self: Canvas, x: i64, y: i64, w: i64, h: i64, radius: i64, scratch: mut Arena): void
```

Blurs the rectangle at (X, Y) of W x H: three box passes of RADIUS, close to a Gaussian.

Effects: fail, read, write.

### `Canvas.darken`

```gizlang
function Canvas.darken(self: Canvas, keep: i64): void
```

Scales every pixel's red, green and blue by KEEP / 256: the backdrop under an overlay.

Effects: fail, read, write.

### `Canvas.saveCorners`

```gizlang
function Canvas.saveCorners(self: Canvas, x: i64, y: i64, w: i64, h: i64, radius: i64): Vec<i64>
```

The pixels under the corners of a window of RADIUS at (X, Y) of W x H, for restoreCorners after it is drawn square.

Effects: fail, read, alloc.

### `Canvas.restoreCorners`

```gizlang
function Canvas.restoreCorners(self: Canvas, saved: Vec<i64>, x: i64, y: i64, w: i64, h: i64, radius: i64): void
```

Puts back the pixels SAVED by saveCorners at the corners of the window of RADIUS at (X, Y) of W x H.

Effects: fail, read, write, alloc.

### `Font.grid`

```gizlang
function Font.grid(self: Font): bool
```

Whether FONT is a face of the terminal's grid (gridFont).

### `Font.has`

```gizlang
function Font.has(self: Font, code: i64): bool
```

Whether FONT has a glyph for CODE.

Effects: fail, read.

### `Font.advance`

```gizlang
function Font.advance(self: Font, code: i64, size: f64): f64
```

The advance of CODE at SIZE pixels.

Effects: fail, read, alloc.

### `Font.measure`

```gizlang
function Font.measure(self: Font, text: string, size: f64): f64
```

The width of TEXT at SIZE pixels.

Effects: fail, read, alloc.

### `Font.ascent`

```gizlang
function Font.ascent(self: Font, size: f64): f64
```

The ascent above the baseline, the descent below it and the line gap, at SIZE pixels (hhea).

Effects: fail, read.

### `Font.descent`

```gizlang
function Font.descent(self: Font, size: f64): f64
```

The descent below the baseline at SIZE pixels.

Effects: fail, read.

### `Font.gap`

```gizlang
function Font.gap(self: Font, size: f64): f64
```

The line gap at SIZE pixels.

Effects: fail, read.

### `Scene.fill`

```gizlang
fill(rect: Rect, corners: Radii, color: i64): void
```

Fills RECT with its CORNERS rounded in COLOR (ARGB).

Effects: fail, read, write, console, io, alloc.

### `Scene.border`

```gizlang
border(rect: Rect, corners: Radii, widths: Insets, color: i64): void
```

The border of RECT, WIDTHS wide on each side, in COLOR.

Effects: fail, read, write, console, io, alloc.

### `Scene.shadow`

```gizlang
shadow(rect: Rect, corners: Radii, s: Shadow): void
```

The shadow S of the box RECT.

Effects: fail, read, write, console, io, alloc.

### `Scene.gradient`

```gizlang
gradient(rect: Rect, corners: Radii, g: Gradient): void
```

Fills RECT with the gradient G.

Effects: fail, read, write, console, io, alloc.

### `Scene.text`

```gizlang
text(font: Font, size: f64, x: f64, baseline: f64, text: string, color: i64, spacing: f64, rtl: bool = false): void
```

TEXT in FONT at SIZE from X on BASELINE, in COLOR, with SPACING between its characters.

Effects: fail, read, write, console, io, alloc.

### `Scene.stroke`

```gizlang
stroke(points: Vec<f64>, width: f64, color: i64): void
```

A line WIDTH wide through POINTS (x, y pairs), in COLOR.

Effects: fail, read, write, console, io, alloc.

### `Scene.bitmap`

```gizlang
bitmap(b: Bitmap): i64
```

Keeps BITMAP for image() and answers its id: a picture drawn often (a sprite) is kept once.

Effects: fail, read, write, alloc.

### `Scene.image`

```gizlang
image(id: i64, src: Rect, dst: Rect, corners: Radii = SQUARE): void
```

The part SRC of the bitmap ID (bitmap()) drawn into DST.

Effects: fail, read, write, console, io, alloc.

### `Scene.scales`

```gizlang
scales(scale: f64): Vec<f64>
```

The most canvas pixels that one pixel of each bitmap covers where the scene draws it, replayed at SCALE (0 for one
it never draws): a host that decodes a picture only to draw it decodes it at that size (replaceBitmap).

Effects: fail, read, alloc.

### `Scene.replaceBitmap`

```gizlang
replaceBitmap(id: i64, b: Bitmap): void
```

Replaces the bitmap ID by B, the same picture at another size: the parts its operations draw scale with it.

Effects: fail, read, write, alloc.

### `Scene.polygon`

```gizlang
polygon(xs: Vec<f64>, ys: Vec<f64>, ends: Vec<i64>, color: i64): void
```

The closed polygon through (XS[i], YS[i]) by non-zero winding, in contours that ENDS splits (Canvas.polygon).

Effects: fail, read, write, console, io, alloc.

### `Scene.transform`

```gizlang
transform(sx: f64, sy: f64, tx: f64, ty: f64): void
```

Draws what follows with each point (x, y) at (x * SX + TX, y * SY + TY), within any transform already set, until
untransform(): CSS's translate and scale. A text's size scales by SY.

Effects: fail, read, write, console, io, alloc.

### `Scene.untransform`

```gizlang
untransform(): void
```

Ends the last transform().

Effects: fail, read, write, console, io, alloc.

### `Scene.clip`

```gizlang
clip(rect: Rect, corners: Radii = SQUARE): void
```

Clips what follows to RECT, within any clip already set, until unclip().

Effects: fail, read, write, console, io, alloc.

### `Scene.unclip`

```gizlang
unclip(): void
```

Ends the last clip().

Effects: fail, read, write, console, io, alloc.

### `Scene.size`

```gizlang
size(): i64
```

How many operations the scene holds.

Effects: fail, read.

### `Scene.replay`

```gizlang
replay(canvas: Canvas, scale: f64, scratch: mut Arena, dx: f64 = 0.0, dy: f64 = 0.0): void
```

Draws the scene onto CANVAS, one scene pixel as SCALE canvas pixels, moved by (DX, DY) canvas pixels (a scrolled
view draws its page at -scroll). An operation wholly outside the canvas draws nothing and costs only its test, so a
long page costs what its visible part holds. A polygon's masks come from SCRATCH; one whose masks do not fit in it
is skipped.

Effects: fail, read, write, console, io, alloc.

### `Scene.replayCells`

```gizlang
replayCells(cells: Cells, dx: f64 = 0.0, dy: f64 = 0.0): void
```

Draws the scene onto the terminal surface CELLS, moved by (DX, DY) CSS pixels, each cell GRID_W x GRID_H of
them (Viewport.cells): a fill gives its cells their background and covers their text, a thin one underlines or
strikes the text in its row or is a rule; a border is a frame of box-drawing characters; text takes a cell for
each cell of its graphemes, in the style of its grid face (gridFont); a picture is placed over its cells, which
the terminal draws its own way (gizlang/terminal). Shadows, strokes and polygons have no cells.

Effects: fail, read, write, alloc.

### `Cells.clear`

```gizlang
clear(): void
```

Every cell blank, no picture, no cursor.

Effects: fail, read, write, alloc.

### `Cells.put`

```gizlang
put(c: i64, r: i64, text: string, fg: i64, bg: i64, style: i64): void
```

Grapheme TEXT (one cell, or two for a wide one) at (C, R) in FG on BG with STYLE; nothing outside.

Effects: fail, read, write, alloc.

### `Cells.line`

```gizlang
line(c: i64, r: i64, text: string, fg: i64, bg: i64, style: i64): i64
```

TEXT from (C, R) on, a cell for each cell of its graphemes, as far as the row goes; the column after it.

Effects: fail, read, write, alloc.

### `Cells.area`

```gizlang
area(rect: Rect, clip: Rect, color: i64): void
```

The cells whose centres RECT (in CSS pixels, within CLIP) covers, filled with COLOR over their background and
cleared of text. A band thinner than half a cell is a line: under or through the text of its row, or a rule.

Effects: fail, read, write, alloc.

### `Cells.frame`

```gizlang
frame(rect: Rect, clip: Rect, widths: Vec<f64>, round: bool, color: i64): void
```

The frame of RECT within CLIP, WIDTHS wide on each side (top, right, bottom, left), in COLOR: rules on its rows
and columns, round corners when ROUND; a frame one row high is brackets, as a button's.

Effects: fail, read, write, alloc.

### `Cells.write`

```gizlang
write(x: f64, baseline: f64, clip: Rect, text: string, color: i64, style: i64): void
```

TEXT from X on BASELINE (CSS pixels) within CLIP, in COLOR and STYLE: its row is the one its line (GRID_ASCENT
above the baseline) falls on by edge, as its box's background does.

Effects: fail, read, write, alloc.

### `Cells.place`

```gizlang
place(bitmap: Bitmap, rect: Rect, clip: Rect): void
```

BITMAP over the cells RECT covers within CLIP: their text goes, the terminal draws the picture there.

Effects: fail, read, write, alloc.

### `Cells.join`

```gizlang
join(): void
```

Rules that meet join: a rule's end beside a crossing one takes its corner, tee or cross.

Effects: fail, read, write, alloc.

### `Canvas.pixel`

```gizlang
function Canvas.pixel(self: Canvas, x: i64, y: i64, color: i64): void
```

The pixel at (X, Y) in ARGB over what is there; nothing outside the canvas.

Effects: fail, read, write.

### `Fonts.add`

```gizlang
add(font: Font, family: string, weight: i64, italic: bool): void
```

Adds the loaded FONT as FAMILY at WEIGHT.

Effects: fail, read, write, alloc.

### `Fonts.later`

```gizlang
later(load: () => Font, family: string, weight: i64, italic: bool): void
```

Adds a face that LOAD gives at its first use (a font at 0 when it cannot be read: a face with no glyphs). A page
that shows none of its characters never reads its file: a Korean face on an English page was 14 MB.

Effects: fail, read, write, alloc.

### `Fonts.font`

```gizlang
font(i: i64): Font
```

The font of face I, loaded now if it is the first use.

Effects: fail, read, write, console, io, alloc.

### `Fonts.holds`

```gizlang
holds(i: i64, code: i64): bool
```

Whether face I has a font with the glyph of CODE.

Effects: fail, read, write, console, io, alloc.

### `Fonts.alias`

```gizlang
alias(name: string, family: string): void
```

Makes NAME (a generic family such as sans-serif, or a family the program lacks) stand for FAMILY.

Effects: fail, read, write, alloc.

### `Fonts.pick`

```gizlang
pick(families: Vec<string>, weight: i64, italic: bool): i64
```

The face for FAMILIES (in order of preference) at WEIGHT and slant ITALIC.

Effects: fail, read, write, alloc.

### `Fonts.search`

```gizlang
private search(families: Vec<string>, weight: i64, italic: bool): i64
```

The face of the first of FAMILIES that was added (by name or alias), nearest WEIGHT and slant; the sans-serif
face when none was, -1 with no face.

Effects: fail, read, alloc.

### `Fonts.has`

```gizlang
has(family: string): bool
```

Whether a face of FAMILY was added (lower case).

Effects: fail, read.

### `Fonts.nearest`

```gizlang
nearest(family: string, weight: i64, italic: bool): i64
```

CSS font matching cut short: the same slant first, then the nearest weight (heavier above 500).

Effects: fail, read.

### `Fonts.covering`

```gizlang
covering(face: i64, code: i64): i64
```

The face that draws CODE: FACE if it has the glyph, else the first face of its weight that does, else the first
regular one (FACE when none has it). Only faces of those two weights are read: a character no face has does not
load every file of a folder of fallbacks. The answer is kept.

Effects: fail, read, write, console, io, alloc.

### `Fonts.advance`

```gizlang
advance(face: i64, code: i64, size: f64): f64
```

The advance of CODE in FACE at SIZE CSS pixels.

Effects: fail, read, write, console, io, alloc.

### `Fonts.measure`

```gizlang
measure(face: i64, text: string, size: f64, letter: f64): f64
```

The width of TEXT in FACE at SIZE, with LETTER spacing after each character.

Effects: fail, read, write, console, io, alloc.

### `Fonts.runs`

```gizlang
runs(face: i64, text: string): Vec<Run>
```

TEXT in runs of one face each: a code point FACE lacks goes to a face that has it. Each run is measured and drawn
whole, so its letters shape together.

Effects: fail, read, write, console, io, alloc.

### `Fonts.ascent`

```gizlang
ascent(face: i64, size: f64): f64
```

The ascent and descent of FACE at SIZE: the content area of a line of its text.

Effects: fail, read, write, console, io, alloc.

### `Fonts.descent`

```gizlang
descent(face: i64, size: f64): f64
```

How far the font of FACE reaches below the baseline at SIZE pixels; a missing face reaches a fifth of SIZE.

Effects: fail, read, write, console, io, alloc.

### `Fonts.normal`

```gizlang
normal(face: i64, size: f64): f64
```

line-height: normal of FACE at SIZE.

Effects: fail, read, write, console, io, alloc.

## Constants

### `GRID_W`

```gizlang
const GRID_W: f64 = 8.0
```

The CSS pixels of one terminal cell: a page shown on a terminal is laid out on this grid (Viewport.cells).

### `GRID_H`

```gizlang
const GRID_H: f64 = 16.0
```

The CSS pixel height of one terminal cell (GRID_W is its width).

### `CELL_BOLD`

```gizlang
const CELL_BOLD = 1
```

The style bit bold; a cell's style is an OR of CELL_*.

### `CELL_ITALIC`

```gizlang
const CELL_ITALIC = 2
```

The style bit italic.

### `CELL_UNDERLINE`

```gizlang
const CELL_UNDERLINE = 4
```

The style bit underline.

### `CELL_STRIKE`

```gizlang
const CELL_STRIKE = 8
```

The style bit strike.

### `CELL_DIM`

```gizlang
const CELL_DIM = 16
```

The style bit dim.

### `CELL_INVERSE`

```gizlang
const CELL_INVERSE = 32
```

The style bit inverse.

### `STRONG_NONE`

```gizlang
const STRONG_NONE = 0
```

The bidi class of a run of text (strongOf): no strong letter, a left-to-right or right-to-left letter first, or a
number with no letter.

### `STRONG_L`

```gizlang
const STRONG_L = 1
```

A run whose first strong letter is written left to right (bidi class L).

### `STRONG_R`

```gizlang
const STRONG_R = 2
```

A run whose first strong letter is written right to left (bidi class R or AL).

### `STRONG_NUMBER`

```gizlang
const STRONG_NUMBER = 3
```

A run with digits and no strong letter (bidi class EN or AN).

