@motionscript/plot 0.0.0-stage → 0.1.0-alpha.3

package/src/graph2d/plane-fill.ts

@@ -0,0 +1,308 @@
+/**
+ * The ruled plane as a **paint** rather than as geometry.
+ *
+ * The grid used to be one filled rect per line — up to four hundred per axis per
+ * order, chained into one `Graphics` so at least the *draws* stayed constant.
+ * That is the arrangement `ChartCanvas` makes, and for a chart it is right: a
+ * chart's axes are ruled once and then sit still. A grapher's are not. Every
+ * rect moves on every frame of a pan, so the renderer's shape cache never hits;
+ * worse, the rect *count* changes as the ladder steps, and the cache is keyed by
+ * shape index, so a grid that gained a line shifted the key of every curve drawn
+ * after it and threw those away too.
+ *
+ * A shader has none of that. The plane is one shape whatever the zoom, so the
+ * curves' cache keys are stable, the wasm path behind it is built once, and the
+ * cost of ruling the plane stops depending on how much of it is ruled — which is
+ * the whole reason the old {@link MAX_TICKS} cap existed.
+ *
+ * ## Why not the built-in `grid` fill
+ *
+ * `Fills.grid` measures its pitch in *divisions of the shape* — deliberately, so
+ * a grid of eight stays a grid of eight when the shape resizes. A graph's pitch
+ * is decided by the tick ladder and is a different number of pixels on each
+ * axis, which one scalar `divisions` cannot say; and it carries one colour,
+ * where a graph has two orders in two colours plus its axes.
+ *
+ * ## Everything variable is a uniform
+ *
+ * `getOrCompileSkSL` caches by *source string* and never evicts, so a source
+ * built per frame is a new program per frame. {@link PLANE_SOURCE} is therefore a
+ * module constant and every switch — the two orders, the axes, the paper — is
+ * expressed by a uniform that can go to zero.
+ *
+ * ## The phase is the whole trick
+ *
+ * Uniforms reach the shader as **fp32**. Handing it "where x = 0 is" would be
+ * fine at the default zoom and 1e15 pixels at a deep one off the origin, which
+ * is not a number fp32 holds at all. So {@link planeUniforms} does the reduction
+ * in double precision on the way in: it splits the centre into a whole number of
+ * steps plus a remainder *before* anything is multiplied by the scale, and hands
+ * over a phase inside a single cell. Every number the shader sees is bounded by
+ * the node's own box.
+ */
+
+import type { NormalizedColor } from "@motionscript/sdk"
+
+import type { ResolvedPlane, TickLadder } from "./plane"
+
+/**
+ * The plane's paint program.
+ *
+ * Coverage-based rather than a hard test, and the ramp is one *device* pixel
+ * wide (`1 / u_scale`, the idiom every built-in pattern fill uses), so a ruling
+ * is a crisp hairline whether the camera is zoomed in on the node or the scene
+ * is being exported at four times scale.
+ *
+ * Uniforms are declared widest-first out of habit rather than necessity — a
+ * shader fill's uniforms are bound by *name* through reflection, unlike the
+ * built-in fills, whose flat positional array makes declaration order load
+ * bearing. `u_origin` and `u_scale` are supplied by the renderer.
+ */
+export const PLANE_SOURCE = `
+uniform vec4 u_paper;
+uniform vec4 u_minorColor;
+uniform vec4 u_majorColor;
+uniform vec4 u_axisColor;
+uniform vec2 u_origin;
+uniform vec2 u_pitch;
+uniform vec2 u_phase;
+uniform vec2 u_divisions;
+uniform vec2 u_axisAt;
+uniform float u_majorHalf;
+uniform float u_minorHalf;
+uniform float u_axisHalf;
+uniform float u_scale;
+
+// Coverage of a line \`d\` px away, of half-width \`w\`, ramped over \`feather\`.
+//
+// The zero test is not a shortcut. The ramp is centred on the line, so a line of
+// no width still lands half a pixel of coverage on the pixels it runs through —
+// an order you switched off, drawn faintly. Answering it here rather than in the
+// ramp is what lets one compiled program serve showGrid, showMinorGrid, showAxes
+// and a grid width of zero.
+float ink(float d, float w, float feather) {
+    if (w <= 0.0) return 0.0;
+    return clamp((w - d) / feather + 0.5, 0.0, 1.0);
+}
+
+// Distance from \`t\` to the nearest ruling. SkSL's mod is floor-based, so this
+// is right on either side of the phase without a sign test.
+float toRuling(float t, float pitch, float phase) {
+    float m = mod(t - phase, pitch);
+    return min(m, pitch - m);
+}
+
+// A straight colour under a coverage, premultiplied.
+vec4 lay(vec4 color, float cover) {
+    float a = color.a * cover;
+    return vec4(color.rgb * a, a);
+}
+
+// \`src\` over \`dst\`, both premultiplied.
+vec4 stack(vec4 src, vec4 dst) {
+    return src + dst * (1.0 - src.a);
+}
+
+vec4 main(vec2 fragCoord) {
+    vec2 p = fragCoord - u_origin;
+    float feather = 1.0 / max(u_scale, 0.0001);
+
+    // Floored well above zero: a mod by zero paints garbage rather than nothing.
+    vec2 major = max(u_pitch, vec2(0.01));
+    vec2 minor = major / max(u_divisions, vec2(1.0));
+
+    vec2 dMajor = vec2(toRuling(p.x, major.x, u_phase.x),
+                       toRuling(p.y, major.y, u_phase.y));
+    vec2 dMinor = vec2(toRuling(p.x, minor.x, u_phase.x),
+                       toRuling(p.y, minor.y, u_phase.y));
+
+    float majorCover = max(ink(dMajor.x, u_majorHalf, feather),
+                           ink(dMajor.y, u_majorHalf, feather));
+
+    // Every numbered ruling is also a faint one — the minor pitch divides the
+    // major exactly — so the faint order is cut away inside the numbered one's
+    // whole footprint, its ramp included. Drawing both would leave a hairline of
+    // the faint colour either side of every numbered line, where the numbered
+    // one's own ramp has not yet reached full coverage. The old ladder dropped
+    // coincident minors from a list; a shader has no list, so it subtracts.
+    float minorCover = max(
+        ink(dMinor.x, u_minorHalf, feather)
+            * (1.0 - ink(dMajor.x, u_majorHalf + feather, feather)),
+        ink(dMinor.y, u_minorHalf, feather)
+            * (1.0 - ink(dMajor.y, u_majorHalf + feather, feather)));
+
+    float axisCover = max(ink(abs(p.x - u_axisAt.x), u_axisHalf, feather),
+                          ink(abs(p.y - u_axisAt.y), u_axisHalf, feather));
+
+    vec4 c = lay(u_paper, 1.0);
+    c = stack(lay(u_minorColor, minorCover), c);
+    c = stack(lay(u_majorColor, majorCover), c);
+    c = stack(lay(u_axisColor, axisCover), c);
+    return c;
+}
+`
+
+/** What {@link planeUniforms} needs to know about how the plane is styled. */
+export interface PlaneStyle {
+  /** The paper's colour. */
+  paper: NormalizedColor
+  /** How opaque the paper is, 0–1. At 0 the graph draws over what is behind it. */
+  paperOpacity: number
+  showGrid: boolean
+  showMinorGrid: boolean
+  showAxes: boolean
+  colorGrid: NormalizedColor
+  colorMinorGrid: NormalizedColor
+  colorAxis: NormalizedColor
+  /** Width of a numbered ruling. The faint ones are drawn at two thirds of it. */
+  lineWidth: number
+  /** Width of the two lines through the origin. */
+  axisWidth: number
+}
+
+/**
+ * The uniform record {@link PLANE_SOURCE} is fed.
+ *
+ * A type alias rather than an interface so it satisfies the renderer's
+ * `Record<string, number | number[]>` without a cast — interfaces have no
+ * implicit index signature.
+ */
+export type PlaneUniforms = {
+  u_paper: number[]
+  u_minorColor: number[]
+  u_majorColor: number[]
+  u_axisColor: number[]
+  u_pitch: number[]
+  u_phase: number[]
+  u_divisions: number[]
+  u_axisAt: number[]
+  u_majorHalf: number
+  u_minorHalf: number
+  u_axisHalf: number
+}
+
+/**
+ * Where an axis is parked when it is not on screen, in box pixels.
+ *
+ * Finite on purpose: an infinity here would reach the coverage ramp as a `NaN`,
+ * and a `NaN` compares false against every clamp, which paints the axis colour
+ * over the entire plane rather than nowhere on it.
+ */
+const AXIS_OFF = -1e7
+
+/** Two thirds the width of a numbered ruling — the faint order's weight. */
+const MINOR_WEIGHT = 2 / 3
+
+/** Past this an integer index is no longer exact, so the reduction is meaningless. */
+const MAX_INDEX = Number.MAX_SAFE_INTEGER
+
+/**
+ * Whether the plane has anything to paint at all — no paper, no rulings and no
+ * axes is a draw the node can skip outright.
+ */
+export function planeVisible(style: PlaneStyle): boolean {
+  if (style.paper[3] * clamp01(style.paperOpacity) > 0.001) return true
+  if (style.showGrid && style.lineWidth > 0) return true
+  return style.showAxes && style.axisWidth > 0
+}
+
+/**
+ * The uniforms that put {@link PLANE_SOURCE} over a resolved plane.
+ *
+ * Everything handed over is bounded by the node's box — a pitch of tens of
+ * pixels, a phase inside one cell, an axis position inside the frame or parked
+ * at {@link AXIS_OFF}. That is deliberate and it is what makes the deep zoom
+ * work: see the module note.
+ */
+export function planeUniforms(
+  plane: ResolvedPlane,
+  style: PlaneStyle,
+  xTicks: TickLadder,
+  yTicks: TickLadder
+): PlaneUniforms {
+  const ruled = style.showGrid && style.lineWidth > 0
+  const majorHalf = ruled ? style.lineWidth / 2 : 0
+
+  return {
+    u_paper: withAlpha(style.paper, clamp01(style.paperOpacity)),
+    u_minorColor: rgba(style.colorMinorGrid),
+    u_majorColor: rgba(style.colorGrid),
+    u_axisColor: rgba(style.colorAxis),
+    u_pitch: [
+      pitchOf(xTicks.step, plane.scaleX),
+      pitchOf(yTicks.step, plane.scaleY),
+    ],
+    // The shader's y runs down the box and the graph's runs up it, which is the
+    // whole of the difference between these two: one signed scale each.
+    u_phase: [
+      phaseOf(plane.centerX, xTicks.step, plane.width / 2, -plane.scaleX),
+      phaseOf(plane.centerY, yTicks.step, plane.height / 2, plane.scaleY),
+    ],
+    u_divisions: [
+      Math.max(1, Math.round(xTicks.divisions)),
+      Math.max(1, Math.round(yTicks.divisions)),
+    ],
+    u_axisAt: [
+      // Only ever evaluated when the origin is inside the range, which bounds
+      // `centre × scale` by half the box — the same reduction `phaseOf` makes,
+      // for free.
+      style.showAxes && plane.xMin <= 0 && 0 <= plane.xMax
+        ? plane.width / 2 - plane.centerX * plane.scaleX
+        : AXIS_OFF,
+      style.showAxes && plane.yMin <= 0 && 0 <= plane.yMax
+        ? plane.height / 2 + plane.centerY * plane.scaleY
+        : AXIS_OFF,
+    ],
+    u_majorHalf: majorHalf,
+    u_minorHalf: ruled && style.showMinorGrid ? majorHalf * MINOR_WEIGHT : 0,
+    u_axisHalf: style.showAxes ? Math.max(0, style.axisWidth) / 2 : 0,
+  }
+}
+
+/** A ladder step in pixels, floored where the shader floors it. */
+function pitchOf(step: number, scale: number): number {
+  const pitch = Math.abs(step * scale)
+  return Number.isFinite(pitch) && pitch > 0.01 ? pitch : 0.01
+}
+
+/**
+ * Where the first ruling sits inside the box, in pixels from its leading edge —
+ * a number in `[0, pitch)`.
+ *
+ * The centre is split into a whole number of steps plus a remainder *before* it
+ * is ever multiplied by the scale, so the only quantity that ever carries the
+ * centre's own magnitude is an integer count that then cancels. Subtracting a
+ * tick value from the centre directly is exact at a span of 20 and has no
+ * significant digits left at 1e-9 around x = 1e6 — where the lines would still
+ * be drawn, just not evenly spaced.
+ *
+ * `signedScale` is negative for x and positive for y; see {@link planeUniforms}.
+ */
+function phaseOf(
+  center: number,
+  step: number,
+  halfBox: number,
+  signedScale: number
+): number {
+  const pitch = pitchOf(step, signedScale)
+  const index = Math.round(center / step)
+  if (!Number.isFinite(index) || Math.abs(index) > MAX_INDEX) return 0
+
+  const remainder = center - index * step
+  const anchor = halfBox + remainder * signedScale
+  if (!Number.isFinite(anchor)) return 0
+  return anchor - Math.floor(anchor / pitch) * pitch
+}
+
+function rgba(color: NormalizedColor): number[] {
+  return [color[0], color[1], color[2], color[3]]
+}
+
+function withAlpha(color: NormalizedColor, opacity: number): number[] {
+  return [color[0], color[1], color[2], color[3] * opacity]
+}
+
+function clamp01(value: number): number {
+  if (!Number.isFinite(value)) return 1
+  return value < 0 ? 0 : value > 1 ? 1 : value
+}