@codincod/ornament 0.0.0-stage → 0.1.0

package/src/cloud.ts

@@ -0,0 +1,308 @@
+/**
+ * Weather over the water, for the light to come through.
+ *
+ * The simulation behind the clouds in a seascape, kept free of the DOM the way
+ * `rays.ts` and `drift.ts` are.
+ *
+ * ## What a cloud is for here
+ *
+ * Not scenery. A reader looking up through the column sees the sun or the moon
+ * and the light it throws down, and a sky that is the same brightness every
+ * hour of every night is a lamp rather than weather. A cloud is the thing that
+ * takes some of that away for a while and gives it back: the moon dims as one
+ * crosses it, the shaft under it thins, and both come back once it has passed.
+ *
+ * So it is drawn in the water's own colour rather than a colour of its own.
+ * What a renderer paints is the absence of light, which is the only thing a
+ * cloud is from under here; a white shape over a night sky would be a cloud
+ * seen from a field.
+ *
+ * ## How they move
+ *
+ * Every one of them differently, and none of them quickly. A cloud carries a
+ * heading of its own and a swell of its own, so what crosses the picture is
+ * anything from a mass tracking flat across it to one that barely moves
+ * sideways and rises and falls in place, with most of them somewhere between
+ * and so going diagonally. Wind is one direction and clouds in it are not, and
+ * a sky where everything slides the same way at the same rate is a sky on a
+ * conveyor.
+ *
+ * The sideways drift wraps, since a cloud that has left the picture has nothing
+ * to say and the water it left is as good a place as any to come back at. The
+ * rise and fall does not: it is a swell about a seat, so nothing ever jumps
+ * from one edge to the other where somebody can see it happen.
+ *
+ * ## What it is not
+ *
+ * There is no wind here, no front, and nothing evaporates. A cloud is a mass of
+ * lobes with a thickness, and the only question it answers is how much of the
+ * light gets past it at a point.
+ */
+
+import { makeRandom } from "./perlin.ts"
+
+/** One of the swells a cloud is a mass of, about the cloud's own middle. */
+export interface Lobe {
+  /** Across, in px. */
+  readonly dx: number
+  /** And down, in px. */
+  readonly dy: number
+  readonly r: number
+}
+
+export interface Cloud {
+  readonly lobes: readonly Lobe[]
+  /** How far it reaches from its middle, in px, which is what a wrap needs. */
+  readonly span: number
+  /**
+   * How much of the light it holds back where it is thickest.
+   *
+   * A share rather than an alpha, because how dark a renderer is allowed to
+   * draw is its own business: a website owes a contrast ratio to the words in
+   * front of it and a desktop owes nothing to anybody.
+   */
+  readonly thick: number
+  x: number
+  y: number
+}
+
+export interface Clouds {
+  readonly clouds: readonly Cloud[]
+  /**
+   * How much cloud is over a point: nothing in the clear, and at its highest
+   * under the middle of the thickest mass there is.
+   *
+   * This is what mutes a body rather than the drawing. A shape painted over the
+   * moon dims the moon where the shape is, and the shaft under it goes on
+   * arriving at full strength out of a moon that is no longer there.
+   */
+  cover(x: number, y: number): number
+  resize(width: number, height: number, count?: number): void
+  step(seconds: number): void
+}
+
+export interface CloudsOptions {
+  count: number
+  height: number
+  seed: number
+  /**
+   * How much of the box is sky, as a share of its height, for a picture whose
+   * sky is not the usual band.
+   *
+   * A round window holds a fraction of what a wall of water does and the light
+   * in it sits lower down the box, so the band it wants is deeper. Left out, a
+   * cloud stays in the top of the picture, which is where a wide box keeps its
+   * light.
+   */
+  sky?: number
+  width: number
+}
+
+/**
+ * How far down the box a cloud may sit, as a share of the height.
+ *
+ * The sky is the top of this picture and the light comes from up there, so
+ * anything lower is a shadow lying in open water with nothing casting it. The
+ * bodies cross well inside this band, which is the point: a cloud has to be
+ * able to get in front of one.
+ */
+const SKY = 0.3
+
+/** How wide one is, least and most, as shares of the box's width. */
+const SPAN_LEAST = 0.14
+
+const SPAN_SPAN = 0.3
+
+/** How far the lobes wander off the line they sit on, against how wide the
+ *  mass is, which is what keeps it a cloud rather than a heap. */
+const SQUAT = 0.14
+
+/** How much of the light the thinnest and the thickest hold back. */
+const THICK_LEAST = 0.3
+
+const THICK_MOST = 0.78
+
+/**
+ * How fast one travels, least and most, in widths a second.
+ *
+ * Slow enough that nothing here is ever the fastest thing on the screen, and
+ * slow enough that a cloud crossing the moon is an evening rather than a
+ * moment. Snow falls, fish swim, and the weather takes longer than either.
+ */
+const PACE_LEAST = 0.004
+
+const PACE_SPAN = 0.011
+
+/**
+ * How far off flat a cloud's heading may lean, in radians.
+ *
+ * The lean is the whole of which way one goes: it splits the pace between
+ * along and up, so a mass at nothing is tracking flat across the picture and
+ * one at the far end of this is climbing as fast as it travels. A quarter turn
+ * is as steep as it gets, since what rises faster than it drifts is weather
+ * nobody has seen.
+ */
+const LEAN = Math.PI / 4
+
+/** How much of the sky one may take up rising and falling, and how long a rise
+ *  and a fall takes, in cycles a second. */
+const SWELL_MOST = 0.3
+
+const SWELL_SLOWEST = 0.006
+
+const SWELL_FASTEST = 0.022
+
+/**
+ * The lobes: how many a mass is made of, and how wide the smallest and the
+ * largest are against the mass they are in.
+ *
+ * Enough of them, and wide enough, that consecutive ones overlap. A row of
+ * lobes that do not touch is not a cloud with gaps in it, it is a row of
+ * lobes.
+ */
+const LOBES_LEAST = 5
+
+const LOBES_SPAN = 4
+
+const LOBE_LEAST = 0.24
+
+const LOBE_SPAN = 0.2
+
+const MIN_SPAN = 1
+
+/** Where a cloud is going, and how far up and down it goes on the way. */
+interface Drift {
+  readonly at: number
+  readonly lean: number
+  readonly pace: number
+  readonly rate: number
+  readonly seat: number
+  readonly swell: number
+}
+
+export function createClouds(options: CloudsOptions): Clouds {
+  const random = makeRandom(options.seed ^ 0x5ce7)
+  const overhead = options.sky ?? SKY
+
+  let width = Math.max(MIN_SPAN, options.width)
+  let height = Math.max(MIN_SPAN, options.height)
+  let clock = 0
+
+  const drifts: Drift[] = []
+  const clouds: Cloud[] = []
+
+  function shape(span: number): Lobe[] {
+    const lobes: Lobe[] = []
+    const many = LOBES_LEAST + Math.floor(random() * (LOBES_SPAN + 1))
+
+    for (let made = 0; made < many; made++) {
+      const along = many < 2 ? 0.5 : made / (many - 1)
+      const r = span * (LOBE_LEAST + random() * LOBE_SPAN) * 0.5
+
+      lobes.push({
+        dx: (along - 0.5) * span,
+        dy: (random() - 0.5) * span * SQUAT,
+        r,
+      })
+    }
+
+    return lobes
+  }
+
+  /**
+   * One of them, made where it will be able to swell without leaving the sky.
+   *
+   * How far it rises and falls comes out of its heading rather than being drawn
+   * on its own: at the top of the swell it is going up as fast as its lean says
+   * it should, which is what makes a steep cloud a climbing one and a flat
+   * cloud a travelling one. Its seat is then drawn from what is left of the
+   * band, so nothing here is ever held against the top of the picture.
+   */
+  function born(): Cloud {
+    const band = height * overhead
+    const span = width * (SPAN_LEAST + random() * SPAN_SPAN)
+    const lean = (random() - 0.5) * 2 * LEAN
+    const pace = width * (PACE_LEAST + random() * PACE_SPAN)
+    const rate = SWELL_SLOWEST + random() * (SWELL_FASTEST - SWELL_SLOWEST)
+    const swell = Math.min(
+      band * SWELL_MOST,
+      (Math.abs(Math.sin(lean)) * pace) / (2 * Math.PI * rate),
+    )
+    const seat = swell + random() * Math.max(0, band - 2 * swell)
+
+    drifts.push({ at: random() * Math.PI * 2, lean, pace, rate, seat, swell })
+
+    return {
+      lobes: shape(span),
+      span,
+      thick: THICK_LEAST + random() * (THICK_MOST - THICK_LEAST),
+      x: random() * width,
+      y: seat,
+    }
+  }
+
+  for (let made = 0; made < Math.max(0, options.count); made++) clouds.push(born())
+
+  function settle(one: Cloud, drift: Drift): void {
+    one.y = drift.seat + Math.sin(drift.at + clock * drift.rate * Math.PI * 2) * drift.swell
+  }
+
+  return {
+    clouds,
+
+    cover(x, y) {
+      let held = 0
+
+      for (const one of clouds) {
+        if (Math.abs(x - one.x) > one.span) continue
+
+        let under = 0
+        for (const lobe of one.lobes) {
+          const from = Math.hypot(x - (one.x + lobe.dx), y - (one.y + lobe.dy)) / lobe.r
+          if (from >= 1) continue
+          under = Math.max(under, (1 - from * from) ** 2)
+        }
+
+        held = Math.max(held, under * one.thick)
+      }
+
+      return held
+    },
+
+    /**
+     * A box of another shape is another sky.
+     *
+     * Everything about a cloud is a share of the box it is in: how wide it is,
+     * how far it travels in a second, how far down it may sit. Carrying the
+     * old ones over would be masses of the old box's width drifting at the old
+     * box's pace, so they are made again. Nothing here is watched closely
+     * enough for that to show.
+     */
+    resize(nextWidth, nextHeight, count) {
+      width = Math.max(MIN_SPAN, nextWidth)
+      height = Math.max(MIN_SPAN, nextHeight)
+
+      const many = count ?? clouds.length
+      clouds.length = 0
+      drifts.length = 0
+      for (let made = 0; made < Math.max(0, many); made++) clouds.push(born())
+    },
+
+    step(seconds) {
+      clock += Math.min(Math.max(seconds, 0), 0.1)
+
+      for (let at = 0; at < clouds.length; at++) {
+        const one = clouds[at]
+        const drift = drifts[at]
+        if (!one || !drift) continue
+
+        one.x += Math.cos(drift.lean) * drift.pace * seconds
+        const over = width + one.span * 2
+        if (one.x > width + one.span) one.x -= over
+        if (one.x < -one.span) one.x += over
+
+        settle(one, drift)
+      }
+    },
+  }
+}