@codincod/ornament 0.0.0-stage → 0.1.0

package/src/rays.ts

@@ -0,0 +1,225 @@
+/**
+ * Light coming down through the surface.
+ *
+ * The simulation behind the shafts in a seascape, kept free of the DOM the way
+ * `shoal.ts` and `drift.ts` are.
+ *
+ * A shaft is what makes water have a top. Without one the picture is a dark
+ * field with animals in it and no reason for the dark to be dark; with one
+ * there is a surface somewhere up there, the murk is depth rather than colour,
+ * and everything else in the scene acquires a distance from the light. It is
+ * the cheapest thing in the whole seascape and it changes the most.
+ *
+ * ## What a shaft is here
+ *
+ * A wedge, hung from the surface, leaning slightly. It is not drawn as a beam
+ * with edges: it is widest and faintest at the bottom, narrow and strongest at
+ * the top, and it fades out before it reaches anything, so it never lands on
+ * the seabed and never picks out an object. A shaft that lit something would be
+ * a spotlight, and the argument for it stops the moment it starts to look like
+ * one.
+ *
+ * Where it ends is `fade`, and the curve matters more than the length. Light
+ * thinning at a steady rate still stops at a rate, and an eye reads that as an
+ * edge across the water; what it wants is a shaft already almost gone by the
+ * time it runs out.
+ *
+ * ## Why they breathe
+ *
+ * Real shafts come from a moving surface, so they wander and they pulse, and
+ * the pulse is slow. Each one here holds its own phase and its own rate, which
+ * is the same trick `shoal.ts` uses on its fish and for the same reason: a set
+ * of shafts brightening together is a light being turned up, and a set that
+ * never agrees is a surface with waves on it.
+ *
+ * The rates are drawn low enough that nothing here is ever the fastest thing on
+ * the screen. Snow falls, fish swim, and the light takes its time.
+ */
+
+import { makeRandom } from "./perlin.ts"
+
+export interface Ray {
+  /**
+   * How bright it is now, as a share of the caller's own ceiling.
+   *
+   * A share rather than a colour or an alpha, because how dark ornament is
+   * allowed to be is the renderer's business and differs between a website that
+   * owes a contrast ratio to the words on top of it and a desktop that does
+   * not.
+   */
+  glow: number
+  /** How far down it reaches before it is gone, in px. */
+  readonly reach: number
+  /** Its width where it meets the surface, in px. */
+  readonly span: number
+  /** How far off vertical it leans, in radians. */
+  readonly tilt: number
+  /** Where it meets the surface, in px across the box. */
+  x: number
+}
+
+export interface Rays {
+  readonly rays: readonly Ray[]
+  resize(width: number, height: number, count?: number): void
+  step(seconds: number): void
+}
+
+export interface RaysOptions {
+  count: number
+  height: number
+  seed: number
+  width: number
+}
+
+/**
+ * How much wider a shaft is where it fades out than where it enters the water.
+ *
+ * Exported because it is a fact about the shape rather than a taste, and there
+ * is more than one renderer drawing these. A canvas and a scene graph disagreeing
+ * about how a shaft opens would be the same light in two different seas.
+ *
+ * It widens rather than narrows, which is worth saying because a beam drawn
+ * from a lamp does the opposite. The light here has already been through a
+ * rough surface, so what is spreading it is the water.
+ */
+export const SPREAD = 2.4
+
+/**
+ * What is left of a shaft's brightness partway down it, where `down` is the
+ * share of its reach travelled: the surface at 0, the end at 1.
+ *
+ * Exported alongside `SPREAD`, and for the same reason: how a shaft ends is a
+ * fact about the light rather than a taste of whichever renderer is drawing it.
+ *
+ * The curve leaves the surface flat and arrives flat, so a shaft holds its
+ * strength where it has some and is already almost nothing by the time it is
+ * nothing. A straight ramp cannot do that, and in water it does worse than it
+ * sounds: the sea it is drawn on darkens with depth as well, so the same light
+ * stands out further the further it falls, and a shaft thinning at a steady
+ * rate is a shaft holding its own all the way down and then stopping at a line.
+ */
+export function fade(down: number): number {
+  const along = Math.min(Math.max(down, 0), 1)
+
+  return (1 - along ** 2) ** 2
+}
+
+/**
+ * How wide a shaft is at the surface, as a share of the box's width.
+ *
+ * Slim. The first pass drew them wide enough to overlap into slabs, and a slab
+ * of tinted water is not a shaft of light: what the eye wants is something
+ * narrower than it expects, because the width it remembers belongs to the glow
+ * around a shaft rather than to the shaft.
+ */
+const SPAN_LEAST = 0.018
+
+const SPAN_SPAN = 0.055
+
+/**
+ * How far down one reaches, as a share of the box's height.
+ *
+ * Shallow enough that the deepest of them is spent in open water. The ground
+ * furthest away sits a little over half way down, so a shaft drawn to the foot
+ * of the box is a shaft lying on a hill.
+ */
+const REACH_LEAST = 0.34
+
+const REACH_SPAN = 0.28
+
+/**
+ * How far off vertical a shaft may lean, in radians.
+ *
+ * Shallow, and all of them leaning the same way. Light refracting through a
+ * surface arrives from wherever the sun is, so shafts in the same water are
+ * near enough parallel; a set fanning out in all directions reads as a stage
+ * rather than a sea. The spread that is left is what stops them looking ruled.
+ */
+const TILT = 0.16
+
+const TILT_SPREAD = 0.07
+
+/** The ends of a shaft's own brightness, as shares of the caller's ceiling. */
+const GLOW_LEAST = 0.25
+
+const GLOW_MOST = 1
+
+/** How fast one breathes, slowest to fastest, in cycles a second. */
+const BREATH_SLOWEST = 0.045
+
+const BREATH_FASTEST = 0.11
+
+/** How far a shaft wanders along the surface, in px, and how fast. */
+const WANDER = 26
+
+const WANDER_RATE = 0.06
+
+const MIN_SPAN = 1
+
+interface Breath {
+  readonly at: number
+  readonly rate: number
+  readonly seat: number
+}
+
+export function createRays(options: RaysOptions): Rays {
+  const random = makeRandom(options.seed ^ 0x33b7)
+
+  let width = Math.max(MIN_SPAN, options.width)
+  let height = Math.max(MIN_SPAN, options.height)
+  let clock = 0
+
+  const breaths: Breath[] = []
+  const rays: Ray[] = []
+
+  function born(): Ray {
+    breaths.push({
+      at: random() * Math.PI * 2,
+      rate: BREATH_SLOWEST + random() * (BREATH_FASTEST - BREATH_SLOWEST),
+      seat: random() * Math.PI * 2,
+    })
+
+    return {
+      glow: GLOW_LEAST,
+      reach: height * (REACH_LEAST + random() * REACH_SPAN),
+      span: width * (SPAN_LEAST + random() * SPAN_SPAN),
+      tilt: TILT + (random() - 0.5) * TILT_SPREAD,
+      x: random() * width,
+    }
+  }
+
+  for (let made = 0; made < Math.max(0, options.count); made++) rays.push(born())
+
+  return {
+    rays,
+
+    resize(nextWidth, nextHeight, count) {
+      const scaleX = Math.max(MIN_SPAN, nextWidth) / width
+      width = Math.max(MIN_SPAN, nextWidth)
+      height = Math.max(MIN_SPAN, nextHeight)
+
+      for (const one of rays) one.x *= scaleX
+
+      if (count == null) return
+      while (rays.length > count) {
+        rays.pop()
+        breaths.pop()
+      }
+      while (rays.length < count) rays.push(born())
+    },
+
+    step(seconds) {
+      clock += Math.min(Math.max(seconds, 0), 0.1)
+
+      for (let at = 0; at < rays.length; at++) {
+        const one = rays[at]
+        const breath = breaths[at]
+        if (!one || !breath) continue
+
+        const swell = (Math.sin(breath.at + clock * breath.rate * Math.PI * 2) + 1) / 2
+        one.glow = GLOW_LEAST + swell * (GLOW_MOST - GLOW_LEAST)
+        one.x += Math.cos(breath.seat + clock * WANDER_RATE * Math.PI * 2) * WANDER * seconds
+      }
+    },
+  }
+}