@codincod/ornament 0.0.0-stage → 0.2.0

package/src/paint/bed.ts

@@ -0,0 +1,231 @@
+/**
+ * The ground, and everything rooted in it.
+ *
+ * The sand, the hills standing behind it, the reef's mound, the wall at the
+ * back, and every plant growing on any of them. It is the one part of the
+ * picture that does not move under its own steam: a plant leans on the current
+ * and nothing here goes anywhere.
+ *
+ * ## Why a renderer on a card does not use this
+ *
+ * Because it can do better. A plant is a short tree of limbs, so a renderer
+ * with a vertex shader takes the shape once at rest and bends it on the card,
+ * and a frame after that costs two numbers a plant. `flora.ts` hands out
+ * `madeOf` for exactly that, and the desktop's renderer reads it.
+ *
+ * This is the other bargain, and it is the right one for a processor: take the
+ * points the plant has already cut for itself and stroke them. `flora.ts` only
+ * cuts a plant when the water has moved it far enough to be worth redrawing, so
+ * the tolerance it was given is what decides how much of a frame this costs.
+ *
+ * Both draw the same bed. What differs is where the bending happens.
+ */
+import type { Caustics } from "../caustics.ts"
+import type { Flora } from "../flora.ts"
+import type { Reef } from "../reef.ts"
+import type { Seabed } from "../seabed.ts"
+import { type Pen, type Point, TONE } from "./pen.ts"
+import { far, floored } from "./rock.ts"
+import type { Box } from "./sky.ts"
+import { trace } from "./trace.ts"
+
+/** How dark each of these may be at the front of the picture. */
+const FLORA_INK = 0.33
+const SAND_INK = 0.19
+const STONE_INK = 0.25
+
+/** How thick a blade is against the strand it grows off. */
+const BLADE_GIRTH = 0.8
+
+/**
+ * How stout a strand has to be before its blades are drawn thinner than it.
+ *
+ * Under this the difference between the two widths is less than the width of a
+ * line, so the whole plant is drawn at one weight and nothing is lost. Over it
+ * the strand reads as the thing the blades hang off.
+ */
+const BLADE_SPLIT = 0.5
+
+/**
+ * Where each band of ground sorts.
+ *
+ * Ground is on a scale of its own, behind everything that swims, and the bands
+ * are kept a fifth of a lane apart so a hill never crosses the sand in front of
+ * it. The sand is flat rather than a function of distance because there is only
+ * one of it and it is the nearest thing in the picture that is not rock.
+ */
+const LANE = { cliff: -3.4, hill: -3, mound: -2.6, sand: -2 }
+
+/**
+ * The water itself, which everything else is drawn into.
+ *
+ * Behind every band of ground and behind the murk, so it is the one thing in
+ * the picture with nothing at all in front of it. Its tone is the wall, which
+ * is whatever the surface underneath the water happens to be showing: a
+ * desktop's own wallpaper, or a page's own background.
+ */
+export function paintWater(pen: Pen, box: Box): void {
+  pen.fill(
+    [
+      [
+        { x: 0, y: 0 },
+        { x: box.width, y: 0 },
+        { x: box.width, y: box.height },
+        { x: 0, y: box.height },
+      ],
+    ],
+    { lane: -9, tone: TONE.wall, weight: 0 },
+  )
+}
+
+/**
+ * The ground at every distance it has, each band shut under the box.
+ *
+ * Far first, near last, which is the order they are drawn in as well as the
+ * order they stand in: a band closed off downwards covers everything behind it
+ * from its own ridge to the bottom edge, so drawing the near sand first would
+ * leave every hill behind it painted over its face.
+ */
+export function paintGround(pen: Pen, seabed: Seabed, reef: Reef | null, box: Box): void {
+  for (const cliff of seabed.cliffs) {
+    pen.fill([floored(cliff.ridge, box)], {
+      lane: LANE.cliff + cliff.depth,
+      shade: box.height * 0.5,
+      weight: far(SAND_INK, cliff.depth),
+    })
+  }
+
+  for (const band of seabed.ranges) {
+    pen.fill([floored(band.ridge, box)], {
+      lane: LANE.hill + band.depth,
+      weight: far(SAND_INK, band.depth),
+    })
+  }
+
+  if (reef) {
+    pen.fill([floored(reef.crest, box)], {
+      lane: LANE.mound + reef.depth,
+      weight: far(STONE_INK, reef.depth),
+    })
+  }
+
+  pen.fill([floored(seabed.ridge, box)], { lane: LANE.sand, weight: SAND_INK })
+}
+
+/**
+ * Every plant, at the distance it grew at.
+ *
+ * A plant is a strand and whatever hangs off it, both handed over as points the
+ * plant cut for itself, and a coral is a stencil that never moves. Which of the
+ * two a plant is, is its own business and not read here beyond that: anything
+ * carrying twigs is drawn as twigs and anything else is drawn as lines.
+ */
+/**
+ * How bright the light on the ground gets, and the least of it at night.
+ *
+ * Faint. This palette is one colour and its shadow, so a bright web on the sand
+ * stops being water and starts being decoration at a threshold well under where
+ * instinct puts it. What it is worth is that the ground is no longer one flat
+ * tone: a ridge with light moving over it has a shape, and a ridge without has
+ * an outline.
+ */
+const CAUSTIC_LIGHT = 0.32
+
+const MOON_CAUSTIC = 0.22
+
+/**
+ * How wide one patch of it is against the box, how far apart they are put along
+ * a ridge, and how flat.
+ *
+ * Laid as a run of soft round lights rather than as a line, because a line has
+ * one strength for the whole of its length and the entire point of a caustic is
+ * that it does not. Overlapping blobs at their own strengths are what a bright
+ * band with a dark end is made of here.
+ */
+const CAUSTIC_REACH = 0.026
+
+const CAUSTIC_STEP = 0.011
+
+const CAUSTIC_FLAT = 0.42
+
+/** Under this there is nothing to see and a drawing would be a drawing wasted. */
+const CAUSTIC_SEEN = 0.06
+
+/**
+ * The light on the ground, ridge by ridge.
+ *
+ * Walked along the outlines the bed already has rather than laid over the box,
+ * since the only ground a reader can see is the top of each band and that is
+ * exactly what a ridge is. Each one is asked at its own distance, so the bands
+ * are lit differently and the bed keeps the depth it is drawn with.
+ */
+export function paintCaustics(
+  pen: Pen,
+  seabed: Seabed,
+  caustics: Caustics,
+  box: Box,
+  daylight: number,
+): void {
+  const overcast = MOON_CAUSTIC + (1 - MOON_CAUSTIC) * daylight
+  const reach = box.width * CAUSTIC_REACH
+  const apart = Math.max(1, box.width * CAUSTIC_STEP)
+
+  const along = (ridge: readonly Point[], depth: number, lane: number): void => {
+    if (ridge.length < 2) return
+
+    let last = Number.NEGATIVE_INFINITY
+    for (const point of ridge) {
+      if (point.x - last < apart) continue
+      last = point.x
+
+      const on = caustics.at(point.x / box.width, depth)
+      const lit = CAUSTIC_LIGHT * on * overcast * far(1, depth)
+      if (lit <= CAUSTIC_SEEN * CAUSTIC_LIGHT) continue
+
+      pen.light(point.x, point.y, {
+        alpha: lit,
+        fall: 1.7,
+        lane,
+        thin: CAUSTIC_FLAT,
+        tone: TONE.sun,
+        width: reach,
+      })
+    }
+  }
+
+  for (const cliff of seabed.cliffs) along(cliff.ridge, cliff.depth, LANE.cliff + cliff.depth)
+  for (const band of seabed.ranges) along(band.ridge, band.depth, LANE.hill + band.depth)
+  along(seabed.ridge, 1, LANE.sand)
+}
+
+export function paintFlora(pen: Pen, flora: Flora): void {
+  for (const plant of flora.plants) {
+    const weight = far(FLORA_INK, plant.depth)
+    const mark = { lane: plant.depth, shade: plant.y, weight }
+
+    if (plant.twigs.length > 0) {
+      const spot = { scale: plant.scale, x: plant.x, y: plant.y }
+      for (const twig of plant.twigs) {
+        pen.line(trace(twig.d), { ...mark, width: twig.width * plant.scale }, spot)
+      }
+      continue
+    }
+
+    if (plant.points.length < 2 && plant.blades.length === 0) continue
+
+    // The strand and its limbs at the plant's own weight, and the blades at a
+    // share of it where the plant is stout enough for the two to read apart.
+    const parted = plant.girth * (1 - BLADE_GIRTH) >= BLADE_SPLIT
+    const strand: Point[][] = plant.points.length > 1 ? [plant.points] : []
+
+    if (parted) {
+      if (strand.length) pen.line(strand, { ...mark, width: plant.girth })
+      if (plant.blades.length) {
+        pen.line(plant.blades, { ...mark, width: plant.girth * BLADE_GIRTH })
+      }
+      continue
+    }
+
+    pen.line([...strand, ...plant.blades], { ...mark, width: plant.girth })
+  }
+}

package/src/paint/colour.ts

@@ -0,0 +1,86 @@
+/**
+ * A theme's colour, as numbers a renderer can mix.
+ *
+ * A renderer is handed its two colours as whatever a page's stylesheet hands
+ * back, and needs them as sRGB in 0 to 1 to mix the water from them.
+ *
+ * ## Why the colours are parsed rather than measured
+ *
+ * The obvious way to turn a theme token into numbers is to fill a pixel with it
+ * and read the pixel back, which is the browser doing the colour conversion for
+ * you. It is also wrong here. A browser with fingerprinting protection on
+ * (Librewolf, Brave, Firefox with `resistFingerprinting`) perturbs canvas
+ * readback on purpose, so the same token comes back a slightly different colour
+ * on every load, and an ornament whose hue wanders between reloads is an
+ * ornament that looks broken.
+ *
+ * Parsing is therefore the only stable answer. Only what a computed style can
+ * actually hand back has to be understood, which is `rgb()` for anything the
+ * page states in sRGB and `oklch()` for the theme tokens, since a computed
+ * colour keeps the space it was authored in. Anything else returns null and the
+ * caller falls back to colours of its own.
+ */
+
+export type Rgb = readonly [number, number, number]
+
+const clamp01 = (value: number): number => Math.min(1, Math.max(0, value))
+
+/**
+ * Oklab to linear sRGB, then to sRGB. Ottosson's matrices, as published.
+ *
+ * Out-of-gamut values are clamped per channel, which is what a browser does
+ * when it paints one.
+ */
+function oklabToRgb(lightness: number, a: number, b: number): Rgb {
+  const l = (lightness + 0.3963377774 * a + 0.2158037573 * b) ** 3
+  const m = (lightness - 0.1055613458 * a - 0.0638541728 * b) ** 3
+  const s = (lightness - 0.0894841775 * a - 1.291485548 * b) ** 3
+
+  const linear = [
+    4.0767416621 * l - 3.3077115913 * m + 0.2309699292 * s,
+    -1.2684380046 * l + 2.6097574011 * m - 0.3413193965 * s,
+    -0.0041960863 * l - 0.7034186147 * m + 1.707614701 * s,
+  ]
+
+  return linear.map((channel) => {
+    const value = clamp01(channel)
+    return value <= 0.0031308 ? value * 12.92 : 1.055 * value ** (1 / 2.4) - 0.055
+  }) as unknown as Rgb
+}
+
+const numbers = (css: string): number[] =>
+  css
+    .slice(css.indexOf("(") + 1, css.lastIndexOf(")"))
+    .split(/[\s,/]+/)
+    .filter(Boolean)
+    .map((part) => (part.endsWith("%") ? Number.parseFloat(part) / 100 : Number.parseFloat(part)))
+
+/**
+ * A computed colour as sRGB in 0 to 1, or null for anything not understood,
+ * which includes the transparent an element with no background of its own
+ * reports.
+ */
+export function parseColour(css: string): Rgb | null {
+  const value = css.trim().toLowerCase()
+
+  if (value.startsWith("rgb")) {
+    const [r, g, b, alpha] = numbers(value)
+    if (r == null || g == null || b == null || alpha === 0) return null
+    return [clamp01(r / 255), clamp01(g / 255), clamp01(b / 255)]
+  }
+
+  if (value.startsWith("oklch")) {
+    const [lightness, chroma, hue, alpha] = numbers(value)
+    if (lightness == null || chroma == null || alpha === 0) return null
+    const angle = ((hue ?? 0) * Math.PI) / 180
+    return oklabToRgb(lightness, chroma * Math.cos(angle), chroma * Math.sin(angle))
+  }
+
+  if (value.startsWith("oklab")) {
+    const [lightness, a, b, alpha] = numbers(value)
+    if (lightness == null || a == null || b == null || alpha === 0) return null
+    return oklabToRgb(lightness, a, b)
+  }
+
+  return null
+}

package/src/paint/frame.ts

@@ -0,0 +1,204 @@
+/**
+ * A frame of the water, read back.
+ *
+ * `pen.ts` writes drawings into a block of numbers and this walks them out
+ * again. It exists because there is more than one renderer: a canvas walks the
+ * frame with a path, a graphics card cuts it into triangles, and both of them
+ * are reading the same block, so the one place that knows what the numbers mean
+ * should be a file rather than a habit.
+ *
+ * ## Nothing is allocated
+ *
+ * A busy sea is a few thousand drawings a frame at sixty frames a second, and
+ * an object per drawing is a few hundred thousand objects a second for the
+ * collector to take away again. So a reader is one object whose fields are
+ * rewritten as it walks, and points stay where they are: what a renderer is
+ * handed is where in the block a part starts and how many points it has.
+ *
+ * Read a field while the reader is standing on the drawing it belongs to. Keep
+ * it and it is the next drawing's answer.
+ */
+import { FORM, OWN, SPENT, TONE } from "./pen.ts"
+
+export { FORM, OWN, SPENT, TONE }
+
+/** How many numbers stand in front of the count. */
+const HEAD = 6
+
+/** How many numbers one drawing spends before its points. */
+const MARK = 12
+
+export interface Held {
+  /** How light it is above the water, 0 through 1. */
+  daylight: number
+  /** How much bigger than its box the scene is drawn. */
+  overscan: number
+  /** How far the frame has wandered, in px. */
+  swayX: number
+  swayY: number
+  /** How far it has rolled, in radians. */
+  tilt: number
+  /** Which frame of grain this is. */
+  turn: number
+}
+
+/**
+ * Where a box is pointed at the frame, for a window on a water bigger than it.
+ *
+ * A scene draws itself at its own size and is held with a hand's own wander,
+ * which is the header above. A plate is the other case: the water is larger
+ * than the box, the box is pointed at one animal in it, and the animal is
+ * magnified until it fills the frame. Both are the same drawing seen from a
+ * different place, which is why this is a camera rather than a second kind of
+ * frame.
+ */
+export interface View {
+  /** How far in, 1 being the water's own size. */
+  scale: number
+  /** The point of the water to put in the middle of the box. */
+  x: number
+  y: number
+}
+
+/** Where the camera is holding the frame, off the front of the block. */
+export function held(floats: Float32Array): Held {
+  return {
+    daylight: floats[5] ?? 1,
+    overscan: floats[3] ?? 1,
+    swayX: floats[0] ?? 0,
+    swayY: floats[1] ?? 0,
+    tilt: floats[2] ?? 0,
+    turn: floats[4] ?? 0,
+  }
+}
+
+/**
+ * One drawing at a time, in the order they were made.
+ *
+ * The order is the picture. Depth sorts anything solid, but two lights over one
+ * another are a painting rather than a stack of distances, so a renderer that
+ * shuffles this is a renderer drawing a different scene.
+ */
+export class Reader {
+  /** How many drawings are in this frame. */
+  readonly count: number
+
+  form = 0
+  alpha = 1
+  fall = 1
+  fadeSpan = 0
+  fadeTop = 0
+  lane = 0
+  shade = OWN
+  soft = 0
+  thin = 1
+  tone = 0
+  weight = 0
+  width = 0
+
+  /** How many pieces this drawing is in. */
+  parts = 0
+
+  /** The block being walked, for a renderer reading points straight out of it. */
+  readonly floats: Float32Array
+
+  private at = 0
+  private read = 0
+  private mark = 0
+
+  constructor(floats: Float32Array) {
+    this.floats = floats
+    this.count = floats[HEAD] ?? 0
+    this.at = HEAD + 1
+  }
+
+  /** Whether the drawing is a round light rather than a shape. */
+  get round(): boolean {
+    return this.form === FORM.light
+  }
+
+  /** Whether it ends on the light's own curve rather than on an exponent. */
+  get spent(): boolean {
+    return (this.tone & SPENT) !== 0
+  }
+
+  /** Which colour it is mixed from, with the flags taken off. */
+  get hue(): number {
+    return this.tone & 0xff
+  }
+
+  /**
+   * Stand on the next drawing, or say there is not one.
+   *
+   * The points are stepped over here rather than by the caller, so a renderer
+   * that skips a drawing it cannot use does not have to know how long it was.
+   */
+  next(): boolean {
+    if (this.read >= this.count) return false
+    this.read++
+    this.at = this.stand(this.at)
+    return true
+  }
+
+  /** Where the drawing being stood on begins, for a caller keeping the place. */
+  get offset(): number {
+    return this.mark
+  }
+
+  /**
+   * Stand on the drawing at a given place, and say where the next one begins.
+   *
+   * A renderer that has to put the frame in another order reads it twice: once
+   * to note where each drawing is and how far back it stands, and again in the
+   * order it decided on. Both passes are this.
+   */
+  stand(from: number): number {
+    const floats = this.floats
+    let at = from
+    this.mark = from
+
+    this.form = floats[at] ?? 0
+    this.tone = floats[at + 1] ?? 0
+    this.weight = floats[at + 2] ?? 0
+    this.shade = floats[at + 3] ?? OWN
+    this.alpha = floats[at + 4] ?? 1
+    this.lane = floats[at + 5] ?? 0
+    this.width = floats[at + 6] ?? 0
+    this.fall = floats[at + 7] ?? 1
+    this.fadeTop = floats[at + 8] ?? 0
+    this.fadeSpan = floats[at + 9] ?? 0
+    this.thin = floats[at + 10] ?? 1
+    this.soft = floats[at + 11] ?? 0
+
+    at += MARK
+    this.parts = floats[at++] ?? 0
+    this.first = at
+
+    for (let part = 0; part < this.parts; part++) {
+      at += 1 + 2 * (floats[at] ?? 0)
+    }
+    return at
+  }
+
+  /** Where this drawing's first part begins. */
+  first = 0
+
+  /**
+   * Every piece of this drawing, as where its points start and how many.
+   *
+   * Several pieces rather than one, because an animal is not one outline: a
+   * fish is a body, a tail swung off its joint and a fin rooted inside the
+   * back, and they are meant to overlap. Filled as one silhouette they are the
+   * animal; filled one after another, every overlap shows as a seam.
+   */
+  each(walk: (at: number, points: number) => void): void {
+    const floats = this.floats
+    let at = this.first
+
+    for (let part = 0; part < this.parts; part++) {
+      const points = floats[at] ?? 0
+      walk(at + 1, points)
+      at += 1 + 2 * points
+    }
+  }
+}

package/src/paint/ink.ts

@@ -0,0 +1,134 @@
+/**
+ * What colour a drawing comes out, and how much of it there is.
+ *
+ * Every colour in this scene is worked out from two: the theme's own ink and
+ * the surface it is standing on. That is what lets a theme switch recolour the
+ * whole sea without a single drawing knowing it happened, and it is why nothing
+ * in `paint/` names a colour. A drawing says how heavy it is and which of the
+ * two it is mixed from, and the answer is worked out here.
+ *
+ * The exceptions are the lights, which are the only colours in the picture that
+ * are not the theme's. A sun is the colour a sun is.
+ *
+ * ## Where it is read
+ *
+ * A card reads it per pixel, in the fragment shader, so a shape spanning half
+ * the box takes the water's own gradient across its whole height. A canvas
+ * cannot: a fill is one colour, or one gradient built before the fill. So the
+ * same arithmetic is here in TypeScript, and `flat.ts` decides how many times to
+ * ask it. The two agree on every number, which is the point of the file.
+ */
+
+import type { Rgb } from "./colour.ts"
+import { TONE } from "./pen.ts"
+
+/**
+ * How much ink is in the water at the surface.
+ *
+ * The water is not the page's background with things drawn on it. It is a
+ * column, lightest at the top where the light comes in and giving out with
+ * depth, and this is how far from the background the lit top of it stands.
+ */
+const LIT = 0.13
+
+/**
+ * How fast the light gives out going down.
+ *
+ * Over 1, so the top half of the box keeps most of it and the bottom goes
+ * quickly, which is what looking down a water column actually looks like. A
+ * straight line reads as a printed gradient.
+ */
+const SINKAGE = 2.1
+
+/** The three lights, which are the only colours here the theme does not own. */
+const SUNLIGHT: Rgb = [1, 0.93, 0.76]
+const MOONLIGHT: Rgb = [0.95, 0.92, 0.85]
+const DUSKLIGHT: Rgb = [0.91, 0.64, 0.3]
+
+export interface Palette {
+  /** The theme's own ink, which everything in the water is drawn towards. */
+  ink: Rgb
+  /** What the water is standing on, which everything fades into. */
+  surface: Rgb
+}
+
+const mix = (a: Rgb, b: Rgb, at: number): Rgb => [
+  a[0] + (b[0] - a[0]) * at,
+  a[1] + (b[1] - a[1]) * at,
+  a[2] + (b[2] - a[2]) * at,
+]
+
+/** The water at a height in the box, lit from above and giving up with depth. */
+export function waterAt(palette: Palette, y: number, height: number): Rgb {
+  const t = Math.min(1, Math.max(0, y / Math.max(1, height)))
+  return mix(palette.surface, mix(palette.surface, palette.ink, LIT), (1 - t) ** SINKAGE)
+}
+
+/**
+ * One drawing's colour: the water where it is, with its own weight mixed in.
+ *
+ * `weight` is how much of the thing stopped the light. A body is one weight,
+ * because a body at this distance is one shape the light did not come back
+ * through, and that is what a silhouette is.
+ */
+export function hueOf(
+  palette: Palette,
+  tone: number,
+  weight: number,
+  y: number,
+  height: number,
+): Rgb {
+  const base = waterAt(palette, y, height)
+  const w = Math.min(1, Math.max(0, weight))
+
+  switch (tone & 0xff) {
+    case TONE.shadow:
+      return mix(base, palette.surface, w)
+    case TONE.sun:
+      return SUNLIGHT
+    case TONE.moon:
+      return MOONLIGHT
+    case TONE.dusk:
+      return DUSKLIGHT
+    case TONE.surface:
+      return palette.surface
+    case TONE.ink:
+      return palette.ink
+    // The water column, which on a page is the page itself: whatever is behind
+    // the canvas is what you see through it, so nothing is painted at all.
+    case TONE.wall:
+      return base
+    default:
+      return mix(base, palette.ink, w)
+  }
+}
+
+export const css = (hue: Rgb, alpha: number): string =>
+  `rgba(${Math.round(hue[0] * 255)},${Math.round(hue[1] * 255)},${Math.round(hue[2] * 255)},${alpha})`
+
+/**
+ * What is left of a shape's own light at a height in the box.
+ *
+ * Two shapes of falling off and no others. Everything that fades down the box
+ * takes the same exponent, because a light in water does not thin in a straight
+ * line and a straight line is what two ends of a gradient draw. `spent` is the
+ * one that does not: it holds most of its strength for the first half of its
+ * length and then goes quickly, which is what a shaft of sunlight does and no
+ * single exponent draws.
+ */
+export function leftAt(
+  alpha: number,
+  fadeTop: number,
+  fadeSpan: number,
+  fall: number,
+  spent: boolean,
+  y: number,
+): number {
+  if (fadeSpan <= 0) return alpha
+  const down = Math.min(1, Math.max(0, (y - fadeTop) / fadeSpan))
+  if (spent) {
+    const held = 1 - down * down
+    return alpha * held * held
+  }
+  return alpha * (1 - down) ** fall
+}