onejs-sl 0.1.0 → 0.1.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "onejs-sl",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "The OneJS shader language: a small typed language for per pixel programs, compiled to a portable IR and emitted as HLSL, WGSL, GLSL ES or a VM buffer",
   "main": "src/index.ts",
   "types": "src/index.ts",
@@ -10,6 +10,7 @@
     "./tables": "./src/tables.ts",
     "./limits": "./src/limits.ts",
     "./vm": "./src/vm.ts",
+    "./emit/hlsl-body": "./src/emit/hlsl-body.ts",
     "./emit/unity": "./src/emit/unity.ts",
     "./emit/web": "./src/emit/web.ts"
   },
@@ -18,6 +19,7 @@
     "src",
     "!src/**/*.test.ts",
     "!src/fixtures",
+    "goldens/goldens.json",
     "CHANGELOG.md"
   ],
   "keywords": [
@@ -43,7 +45,8 @@
     "typecheck": "tsc --noEmit",
     "lint": "eslint .",
     "test": "vitest run && node quickjs/run.mjs",
-    "test:quickjs": "node quickjs/run.mjs"
+    "test:quickjs": "node quickjs/run.mjs",
+    "goldens": "node goldens/run.mjs"
   },
   "devDependencies": {
     "@eslint/js": "^10.0.1",

package/src/body.ts

@@ -0,0 +1,202 @@
+/**
+ * A program as the body of a function, in the HLSL and Metal shared subset,
+ * for any host that supplies the frame around it.
+ *
+ * `Specs/SL_PACKAGE.md` section 4. OneJS's Unity shader (`hlsl.ts`) is one
+ * frame over this and Magerie's compute kernel is another, so HLSL has one
+ * emitter rather than one per host. A target says only what differs between
+ * hosts: how an input, a uniform slot and a texture sample are spelled, and
+ * whether `toLinear` is real.
+ *
+ * The subset is HLSL's spelling (`float2`, `lerp`, `frac`, `fmod`, `atan2`,
+ * `saturate`), which Metal takes through a host's compatibility defines. `fmod`
+ * is the same truncating remainder in both. Nothing here uses `mul`, `static`,
+ * derivatives, or an overload the library does not resolve by width.
+ *
+ * One local per reachable node, in order, named `n<index>` and unreadable on
+ * purpose: generated code that looks hand written invites hand editing, and a
+ * hand edit is lost the next time it is generated. One local per node also
+ * gives common subexpression elimination for free.
+ */
+
+import { SLError, TYPE, type InputName, type Program, type SLNode, type SLType } from "./ir"
+import { SLOP } from "./ops"
+
+export interface BodyTarget {
+    /** An expression for each input, e.g. `{ uv: "SL_UV", time: "SL_TIME", ... }`. */
+    inputs: Record<InputName, string>
+    /** The float4 holding a uniform slot. The body swizzles it down to the uniform's width. */
+    uniform: (slot: number, name: string) => string
+    /** A float4 sample of the texture in `slot` at the float2 expression `uv`, straight alpha. */
+    sample: (slot: number, uv: string) => string
+    /**
+     * `linear`: `toLinear` calls `sl_toLinear`, for a host whose target holds
+     * linear light. `gamma`: `toLinear` is the identity, decided here, so hex
+     * colours and ramps stay as written.
+     */
+    colour: "gamma" | "linear"
+    /** Assign the result to this local instead of returning it. */
+    result?: string
+    /** Put in front of every line. Default four spaces. */
+    indent?: string
+}
+
+export interface Body {
+    body: string
+    uses: {
+        /** Uniform slots the body reads, ascending. */
+        uniforms: number[]
+        /** Texture slots the body samples, ascending. */
+        textures: number[]
+        /** Library functions the body calls, sorted: `sl_fbm`, `sl_sdfDistance`, ... */
+        helpers: string[]
+    }
+}
+
+const HLSL_TYPE: Record<SLType, string> = { 1: "float", 2: "float2", 3: "float3", 4: "float4" }
+
+/** A literal that survives a float32 round trip and never reads as an int. */
+export function lit(n: number): string {
+    if (!Number.isFinite(n)) throw new SLError(`cannot emit ${n} as a shader literal`)
+    const s = Number.isInteger(n) ? n.toFixed(1) : String(n)
+    return s
+}
+
+function ctor(type: SLType, parts: string[]): string {
+    return type === TYPE.FLOAT ? parts[0] : `${HLSL_TYPE[type]}(${parts.join(", ")})`
+}
+
+const SWZ = "xyzw"
+
+export function emitBody(p: Program, target: BodyTarget): Body {
+    const indent = target.indent ?? "    "
+    const lines: string[] = []
+    const name = (ref: number) => `n${ref}`
+    const emitted = new Set<number>()
+    const uniforms = new Set<number>()
+    const textures = new Set<number>()
+    const helpers = new Set<string>()
+    const helper = (fn: string) => { helpers.add(fn); return fn }
+
+    const expr = (n: SLNode): string => {
+        switch (n.k) {
+            case "const":
+                return ctor(n.type, n.v.map(lit))
+            case "input":
+                return target.inputs[n.name]
+            case "uniform": {
+                const u = p.uniforms[n.slot]
+                if (u === undefined) throw new SLError(`a node reads uniform slot ${n.slot}, which is not declared`)
+                uniforms.add(n.slot)
+                const v = target.uniform(n.slot, u.name)
+                return n.type === TYPE.VEC4 ? v : `${v}.${SWZ.slice(0, n.type)}`
+            }
+            case "swizzle":
+                return `${name(n.src)}.${n.chans.map((c) => SWZ[c]).join("")}`
+            case "call":
+                return call(n)
+        }
+    }
+
+    const call = (n: Extract<SLNode, { k: "call" }>): string => {
+        const a = n.args.map(name)
+        const imm = n.imm ?? []
+        switch (n.op) {
+            case SLOP.COMPOSE: return ctor(n.type, a)
+
+            case SLOP.ADD: return `(${a[0]} + ${a[1]})`
+            case SLOP.SUB: return `(${a[0]} - ${a[1]})`
+            case SLOP.MUL: return `(${a[0]} * ${a[1]})`
+            case SLOP.DIV: return `(${a[0]} / ${a[1]})`
+            case SLOP.MOD: return `fmod(${a[0]}, ${a[1]})`
+            // abs on the base, matching the VM. pow of a negative base is
+            // undefined in HLSL and the backends must be undefined in the same
+            // direction.
+            case SLOP.POW: return `pow(abs(${a[0]}), ${a[1]})`
+            case SLOP.NEG: return `(-${a[0]})`
+            case SLOP.RECIP: return `(1.0 / ${a[0]})`
+
+            case SLOP.SIN: return `sin(${a[0]})`
+            case SLOP.COS: return `cos(${a[0]})`
+            case SLOP.TAN: return `tan(${a[0]})`
+            case SLOP.ASIN: return `asin(clamp(${a[0]}, -1, 1))`
+            case SLOP.ACOS: return `acos(clamp(${a[0]}, -1, 1))`
+            case SLOP.ATAN2: return `atan2(${a[0]}, ${a[1]})`
+            case SLOP.EXP: return `exp(${a[0]})`
+            case SLOP.LOG: return `log(max(${a[0]}, 1e-8))`
+            case SLOP.SQRT: return `sqrt(max(${a[0]}, 0))`
+            case SLOP.ABS: return `abs(${a[0]})`
+            case SLOP.SIGN: return `sign(${a[0]})`
+            case SLOP.FLOOR: return `floor(${a[0]})`
+            case SLOP.CEIL: return `ceil(${a[0]})`
+            case SLOP.ROUND: return `round(${a[0]})`
+            case SLOP.FRACT: return `frac(${a[0]})`
+            case SLOP.MIN: return `min(${a[0]}, ${a[1]})`
+            case SLOP.MAX: return `max(${a[0]}, ${a[1]})`
+            case SLOP.CLAMP: return `clamp(${a[0]}, ${a[1]}, ${a[2]})`
+            case SLOP.SATURATE: return `saturate(${a[0]})`
+
+            case SLOP.LENGTH: return `length(${a[0]})`
+            case SLOP.DISTANCE: return `distance(${a[0]}, ${a[1]})`
+            case SLOP.DOT: return `dot(${a[0]}, ${a[1]})`
+            case SLOP.CROSS: return `cross(${a[0]}, ${a[1]})`
+            case SLOP.NORMALIZE: return `normalize(${a[0]})`
+            case SLOP.REFLECT: return `reflect(${a[0]}, ${a[1]})`
+            case SLOP.LUMINANCE: return `${helper("sl_luminance")}(${a[0]}.rgb)`
+            case SLOP.TO_LINEAR: return target.colour === "linear" ? `${helper("sl_toLinear")}(${a[0]})` : a[0]!
+
+            case SLOP.MIX: return `lerp(${a[0]}, ${a[1]}, ${a[2]})`
+            case SLOP.STEP: return `step(${a[0]}, ${a[1]})`
+            case SLOP.SMOOTHSTEP: return `smoothstep(${a[0]}, ${a[1]}, ${a[2]})`
+            // Matches the VM exactly, branchlessly, rather than using an if.
+            // Two backends that pick differently here disagree on every edge
+            // value.
+            case SLOP.SELECT: return `lerp(${a[2]}, ${a[1]}, step(0.5, ${a[0]}))`
+
+            case SLOP.HSV2RGB: return `${helper("sl_hsv2rgb")}(${a[0]})`
+            case SLOP.NOISE: return `${helper("sl_valueNoise")}(${a[0]})`
+            case SLOP.SIMPLEX: return `${helper("sl_simplex")}(${a[0]})`
+            case SLOP.FBM: return `${helper("sl_fbm")}(${a[0]}, ${Math.round(imm[0] ?? 3)}, ${Math.round(imm[1] ?? 0)})`
+            case SLOP.TURBULENCE: return `${helper("sl_fbm")}(${a[0]}, ${Math.round(imm[0] ?? 3)}, 2)`
+            case SLOP.RIDGED: return `${helper("sl_fbm")}(${a[0]}, ${Math.round(imm[0] ?? 3)}, 3)`
+            case SLOP.SDF: {
+                const id = Math.round(imm[0] ?? 0)
+                const q = [imm[1] ?? 0, imm[2] ?? 0, imm[3] ?? 0, imm[4] ?? 0].map(lit)
+                const r = [imm[5] ?? 0, imm[6] ?? 0].map(lit)
+                return `${helper("sl_sdfDistance")}(${id}, ${a[0]}, float4(${q.join(", ")}), float2(${r.join(", ")}))`
+            }
+            case SLOP.VORONOI: return `${helper("sl_voronoi")}(${a[0]})`
+            case SLOP.SAMPLE: {
+                const slot = Math.round(imm[0] ?? 0)
+                textures.add(slot)
+                return target.sample(slot, a[0]!)
+            }
+
+            default:
+                throw new SLError(
+                    `the HLSL emitter has no case for opcode ${n.op}. A program using it would silently ` +
+                    `differ between the VM and a compiled build, which is the one failure this design ` +
+                    `cannot tolerate.`,
+                )
+        }
+    }
+
+    const walk = (ref: number): void => {
+        if (emitted.has(ref)) return
+        const n = p.nodes[ref]
+        const deps = n.k === "swizzle" ? [n.src] : n.k === "call" ? n.args : []
+        for (const d of deps) walk(d)
+        emitted.add(ref)
+        lines.push(`${indent}${HLSL_TYPE[n.type]} ${name(ref)} = ${expr(n)};`)
+    }
+    walk(p.result)
+    lines.push(target.result === undefined
+        ? `${indent}return ${name(p.result)};`
+        : `${indent}${target.result} = ${name(p.result)};`)
+
+    const sorted = (s: Set<number>) => [...s].sort((x, y) => x - y)
+    return {
+        body: lines.join("\n"),
+        uses: { uniforms: sorted(uniforms), textures: sorted(textures), helpers: [...helpers].sort() },
+    }
+}

package/src/core.ts

@@ -10,7 +10,7 @@
 export * as sl from "./sl"
 export type { Float, Vec2, Vec3, Vec4, Num, ProgramInputs, Texture } from "./sl"
 export {
-    TYPE, INPUTS, MAX_TEXTURES, MAX_NODES, SLError, hashProgram, widthName, SL_IR_VERSION,
+    TYPE, INPUTS, MAX_TEXTURES, MAX_NODES, SLError, hashProgram, widthName, SL_IR_VERSION, inputsUsed,
 } from "./ir"
 export type {
     SLType, InputName, NodeRef, SLNode, Program, UniformDecl, TextureDecl,

package/src/emit/hlsl-body.ts

@@ -0,0 +1,6 @@
+/**
+ * `onejs-sl/emit/hlsl-body`: a program as a function body in the HLSL and Metal
+ * shared subset, for a host that supplies its own frame. See `BodyTarget`.
+ */
+export { emitBody } from "../body"
+export type { Body, BodyTarget } from "../body"

package/src/encode.ts

@@ -24,7 +24,7 @@
  */
 
 import {
-    MAX_TEXTURES, SLError, TYPE, type NodeRef, type Program, type SLNode, type SLType,
+    MAX_TEXTURES, SLError, TYPE, reachable, type NodeRef, type Program, type SLNode, type SLType,
 } from "./ir"
 import { INPUT_ID, SLOP } from "./ops"
 import { emitShader } from "./hlsl"
@@ -34,6 +34,8 @@ import { uniformDefaults } from "./sl"
 // Lives in ops.ts with the other wire constants; re-exported so nothing that
 // reached it through the encoder has to move.
 export { INPUT_ID }
+// Lives in ir.ts, since a host reads a graph with it too (`inputsUsed`).
+export { reachable }
 
 /**
  * Registers in the VM's file. Phase 0's answer, not a preference.
@@ -143,29 +145,6 @@ interface Instr {
     imm: [number, number, number, number]
 }
 
-/**
- * Nodes the result actually depends on, in order.
- *
- * Dead nodes are dropped rather than encoded. An author can produce them easily
- * by computing something and not using it, and the hash already ignores them, so
- * encoding them would make the buffer disagree with its own hash about what the
- * program is.
- */
-export function reachable(nodes: SLNode[], result: NodeRef): NodeRef[] {
-    const keep = new Set<NodeRef>()
-    const stack = [result]
-    while (stack.length > 0) {
-        const ref = stack.pop()!
-        if (keep.has(ref)) continue
-        keep.add(ref)
-        const n = nodes[ref]
-        if (n.k === "swizzle") stack.push(n.src)
-        else if (n.k === "call") for (const a of n.args) stack.push(a)
-    }
-    // Ascending, which is still topological because a node only refers backwards.
-    return [...keep].sort((x, y) => x - y)
-}
-
 /**
  * The last position in `order` that reads each node.
  *

package/src/hlsl.ts

@@ -22,23 +22,8 @@
  * next time it is generated.
  */
 
-import { SLError, TYPE, type Program, type SLNode, type SLType } from "./ir"
-import { INPUT_ID, SLOP } from "./ops"
-
-const HLSL_TYPE: Record<SLType, string> = { 1: "float", 2: "float2", 3: "float3", 4: "float4" }
-
-/** A literal that survives a float32 round trip and never reads as an int. */
-function lit(n: number): string {
-    if (!Number.isFinite(n)) throw new SLError(`cannot emit ${n} as a shader literal`)
-    const s = Number.isInteger(n) ? n.toFixed(1) : String(n)
-    return s
-}
-
-function ctor(type: SLType, parts: string[]): string {
-    return type === TYPE.FLOAT ? parts[0] : `${HLSL_TYPE[type]}(${parts.join(", ")})`
-}
-
-const SWZ = "xyzw"
+import { SLError, type Program } from "./ir"
+import { emitBody, lit, type BodyTarget } from "./body"
 
 /** The property name a uniform gets. Prefixed so it cannot collide with ours. */
 export function uniformProperty(name: string): string {
@@ -143,133 +128,39 @@ ${body}
 `
 }
 
-/** The straight line body: one local per reachable node, in order. */
-export function emitFragmentBody(p: Program): string {
-    const lines: string[] = []
-    const name = (ref: number) => `n${ref}`
-    const emitted = new Set<number>()
-
-    const walk = (ref: number): void => {
-        if (emitted.has(ref)) return
-        const n = p.nodes[ref]
-        const deps = n.k === "swizzle" ? [n.src] : n.k === "call" ? n.args : []
-        for (const d of deps) walk(d)
-        emitted.add(ref)
-        lines.push(`                ${HLSL_TYPE[n.type]} ${name(ref)} = ${expr(n, name, p)};`)
-    }
-    walk(p.result)
-    lines.push(`                return ${name(p.result)};`)
-    return lines.join("\n")
-}
-
-function expr(n: SLNode, name: (r: number) => string, p: Program): string {
-    switch (n.k) {
-        case "const":
-            return ctor(n.type, n.v.map(lit))
-        case "input": {
-            // `_Res` is the TARGET's size, set by the host, not `_ScreenParams`.
-            //
-            // A program is drawn with Graphics.Blit into the element's own
-            // render texture, and Unity leaves _ScreenParams at whatever the
-            // last camera set: blitting into a 64x256 target reads it as the
-            // game view's 1737x1226. So `resolution` and `fragCoord` were the
-            // window's and `aspect` was the window's ratio, identically wrong
-            // on both backends, which is why nothing caught it. Aspect
-            // correction, the thing `aspect` exists for, stretched every
-            // circle by the shape of the window it happened to be in.
-            switch (INPUT_ID[n.name]) {
-                case 0: return "i.uv"
-                case 1: return "i.uv * _Res.xy"
-                case 2: return "_Res.xy"
-                case 3: return "_Secs"
-                default: return "(_Res.x / max(_Res.y, 1.0))"
-            }
-        }
-        case "uniform": {
-            const u = p.uniforms[n.slot]
-            const prop = uniformProperty(u.name)
-            return n.type === TYPE.VEC4 ? prop : `${prop}.${SWZ.slice(0, n.type)}`
-        }
-        case "swizzle":
-            return `${name(n.src)}.${n.chans.map((c) => SWZ[c]).join("")}`
-        case "call":
-            return call(n, name)
+/**
+ * The frame's side of the body: OneJS's names for the inputs, a uniform's
+ * material property, and `tex2D` on the slot's sampler. `sl_toLinear` stays a
+ * call because `SLCommon.cginc` decides Gamma or Linear per project, at the
+ * shader compile, so this target always emits it.
+ */
+function unityTarget(p: Program): BodyTarget {
+    return {
+        // `_Res` is the TARGET's size, set by the host, not `_ScreenParams`.
+        //
+        // A program is drawn with Graphics.Blit into the element's own render
+        // texture, and Unity leaves _ScreenParams at whatever the last camera
+        // set: blitting into a 64x256 target reads it as the game view's
+        // 1737x1226. So `resolution` and `fragCoord` were the window's and
+        // `aspect` was the window's ratio, identically wrong on both backends,
+        // which is why nothing caught it. Aspect correction, the thing `aspect`
+        // exists for, stretched every circle by the shape of the window it
+        // happened to be in.
+        inputs: {
+            uv: "i.uv",
+            fragCoord: "i.uv * _Res.xy",
+            resolution: "_Res.xy",
+            time: "_Secs",
+            aspect: "(_Res.x / max(_Res.y, 1.0))",
+        },
+        uniform: (slot) => uniformProperty(p.uniforms[slot]!.name),
+        sample: (slot, uv) => `tex2D(_Tex${slot}, ${uv})`,
+        colour: "linear",
+        indent: "                ",
     }
 }
 
-function call(n: Extract<SLNode, { k: "call" }>, name: (r: number) => string): string {
-    const a = n.args.map(name)
-    const imm = n.imm ?? []
-    switch (n.op) {
-        case SLOP.COMPOSE: return ctor(n.type, a)
-
-        case SLOP.ADD: return `(${a[0]} + ${a[1]})`
-        case SLOP.SUB: return `(${a[0]} - ${a[1]})`
-        case SLOP.MUL: return `(${a[0]} * ${a[1]})`
-        case SLOP.DIV: return `(${a[0]} / ${a[1]})`
-        case SLOP.MOD: return `fmod(${a[0]}, ${a[1]})`
-        // abs on the base, matching the VM. pow of a negative base is undefined
-        // in HLSL and the two backends must be undefined in the same direction.
-        case SLOP.POW: return `pow(abs(${a[0]}), ${a[1]})`
-        case SLOP.NEG: return `(-${a[0]})`
-        case SLOP.RECIP: return `(1.0 / ${a[0]})`
-
-        case SLOP.SIN: return `sin(${a[0]})`
-        case SLOP.COS: return `cos(${a[0]})`
-        case SLOP.TAN: return `tan(${a[0]})`
-        case SLOP.ASIN: return `asin(clamp(${a[0]}, -1, 1))`
-        case SLOP.ACOS: return `acos(clamp(${a[0]}, -1, 1))`
-        case SLOP.ATAN2: return `atan2(${a[0]}, ${a[1]})`
-        case SLOP.EXP: return `exp(${a[0]})`
-        case SLOP.LOG: return `log(max(${a[0]}, 1e-8))`
-        case SLOP.SQRT: return `sqrt(max(${a[0]}, 0))`
-        case SLOP.ABS: return `abs(${a[0]})`
-        case SLOP.SIGN: return `sign(${a[0]})`
-        case SLOP.FLOOR: return `floor(${a[0]})`
-        case SLOP.CEIL: return `ceil(${a[0]})`
-        case SLOP.ROUND: return `round(${a[0]})`
-        case SLOP.FRACT: return `frac(${a[0]})`
-        case SLOP.MIN: return `min(${a[0]}, ${a[1]})`
-        case SLOP.MAX: return `max(${a[0]}, ${a[1]})`
-        case SLOP.CLAMP: return `clamp(${a[0]}, ${a[1]}, ${a[2]})`
-        case SLOP.SATURATE: return `saturate(${a[0]})`
-
-        case SLOP.LENGTH: return `length(${a[0]})`
-        case SLOP.DISTANCE: return `distance(${a[0]}, ${a[1]})`
-        case SLOP.DOT: return `dot(${a[0]}, ${a[1]})`
-        case SLOP.CROSS: return `cross(${a[0]}, ${a[1]})`
-        case SLOP.NORMALIZE: return `normalize(${a[0]})`
-        case SLOP.REFLECT: return `reflect(${a[0]}, ${a[1]})`
-        case SLOP.LUMINANCE: return `sl_luminance(${a[0]}.rgb)`
-        case SLOP.TO_LINEAR: return `sl_toLinear(${a[0]})`
-
-        case SLOP.MIX: return `lerp(${a[0]}, ${a[1]}, ${a[2]})`
-        case SLOP.STEP: return `step(${a[0]}, ${a[1]})`
-        case SLOP.SMOOTHSTEP: return `smoothstep(${a[0]}, ${a[1]}, ${a[2]})`
-        // Matches the VM exactly, branchlessly, rather than using an if. Two
-        // backends that pick differently here disagree on every edge value.
-        case SLOP.SELECT: return `lerp(${a[2]}, ${a[1]}, step(0.5, ${a[0]}))`
-
-        case SLOP.HSV2RGB: return `sl_hsv2rgb(${a[0]})`
-        case SLOP.NOISE: return `sl_valueNoise(${a[0]})`
-        case SLOP.SIMPLEX: return `sl_simplex(${a[0]})`
-        case SLOP.FBM: return `sl_fbm(${a[0]}, ${Math.round(imm[0] ?? 3)}, ${Math.round(imm[1] ?? 0)})`
-        case SLOP.TURBULENCE: return `sl_fbm(${a[0]}, ${Math.round(imm[0] ?? 3)}, 2)`
-        case SLOP.RIDGED: return `sl_fbm(${a[0]}, ${Math.round(imm[0] ?? 3)}, 3)`
-        case SLOP.SDF: {
-            const id = Math.round(imm[0] ?? 0)
-            const q = [imm[1] ?? 0, imm[2] ?? 0, imm[3] ?? 0, imm[4] ?? 0].map(lit)
-            const r = [imm[5] ?? 0, imm[6] ?? 0].map(lit)
-            return `sl_sdfDistance(${id}, ${a[0]}, float4(${q.join(", ")}), float2(${r.join(", ")}))`
-        }
-        case SLOP.VORONOI: return `sl_voronoi(${a[0]})`
-        case SLOP.SAMPLE: return `tex2D(_Tex${Math.round(imm[0] ?? 0)}, ${a[0]})`
-
-        default:
-            throw new SLError(
-                `the HLSL emitter has no case for opcode ${n.op}. A program using it would silently ` +
-                `differ between the VM and a compiled build, which is the one failure this design ` +
-                `cannot tolerate.`,
-            )
-    }
+/** The straight line body: one local per reachable node, in order. */
+export function emitFragmentBody(p: Program): string {
+    return emitBody(p, unityTarget(p)).body
 }

package/src/ir.ts

@@ -57,6 +57,13 @@ export interface UniformDecl {
     type: SLType
     /** Default, used when a caller does not supply the uniform. */
     value: number[]
+    /**
+     * A colour: `value` is sRGB as written, what a host sets and a colour
+     * picker shows, and every read converts it to linear. Set by a hex default
+     * in a `.sl` file or `sl.uniform.colour`. Metadata for a host: the reads'
+     * conversion is already in the graph, so it is not part of the hash.
+     */
+    colour?: true
 }
 
 export interface TextureDecl {
@@ -154,17 +161,20 @@ export class Builder {
         return this.add({ k: "const", type: v.length as SLType, v: v.slice() })
     }
 
-    uniform(name: string, type: SLType, value: number[]): NodeRef {
+    uniform(name: string, type: SLType, value: number[], colour = false): NodeRef {
         const existing = this.uniforms.findIndex((u) => u.name === name)
         if (existing >= 0) {
             const u = this.uniforms[existing]
             if (u.type !== type) {
                 throw new SLError(`uniform "${name}" is declared as both a ${widthName(u.type)} and a ${widthName(type)}`)
             }
+            if ((u.colour === true) !== colour) {
+                throw new SLError(`uniform "${name}" is declared both as a colour and as plain numbers`)
+            }
             return this.add({ k: "uniform", type, slot: existing })
         }
         const slot = this.uniforms.length
-        this.uniforms.push({ name, type, value: value.slice() })
+        this.uniforms.push(colour ? { name, type, value: value.slice(), colour: true } : { name, type, value: value.slice() })
         return this.add({ k: "uniform", type, slot })
     }
 
@@ -184,6 +194,43 @@ export class Builder {
     }
 }
 
+/**
+ * Nodes the result actually depends on, in order.
+ *
+ * Dead nodes are dropped rather than encoded. An author can produce them easily
+ * by computing something and not using it, and the hash already ignores them, so
+ * encoding them would make the buffer disagree with its own hash about what the
+ * program is.
+ */
+export function reachable(nodes: SLNode[], result: NodeRef): NodeRef[] {
+    const keep = new Set<NodeRef>()
+    const stack = [result]
+    while (stack.length > 0) {
+        const ref = stack.pop()!
+        if (keep.has(ref)) continue
+        keep.add(ref)
+        const n = nodes[ref]
+        if (n.k === "swizzle") stack.push(n.src)
+        else if (n.k === "call") for (const a of n.args) stack.push(a)
+    }
+    // Ascending, which is still topological because a node only refers backwards.
+    return [...keep].sort((x, y) => x - y)
+}
+
+/**
+ * The inputs a program reads, in `INPUTS` order. Dead nodes do not count: a
+ * value computed and never used is not in the picture, so a program that does
+ * that with `time` is still not animated.
+ */
+export function inputsUsed(p: Program): InputName[] {
+    const read = new Set<InputName>()
+    for (const ref of reachable(p.nodes, p.result)) {
+        const n = p.nodes[ref]
+        if (n.k === "input") read.add(n.name)
+    }
+    return (Object.keys(INPUTS) as InputName[]).filter((name) => read.has(name))
+}
+
 /** Structural key for hash consing. Order matters and is fixed by the node shape. */
 function keyOf(n: SLNode): string {
     switch (n.k) {

package/src/lang/lower.ts

@@ -144,12 +144,15 @@ export function lower(checked: Checked): Program {
             for (const u of unit.uniforms) {
                 const width = TYPE_WIDTH[u.type]
                 const { components, colour } = uniformDefault(u.type, u.init)
-                const raw = at(u.pos, () => declareUniform(u.name, u.type, components))
                 // A hex default says the uniform IS a colour, so every read of it
                 // converts, exactly as a hex literal in an expression does. Without
                 // that, `#ff8040` and a uniform defaulting to `#ff8040` would be two
-                // different colours in one file.
-                global.declare(u.name, { width, value: colour ? at(u.pos, () => sl.toLinear(raw)) : raw })
+                // different colours in one file. `sl.uniform.colour` also marks
+                // the declaration, for a host's colour picker.
+                const value = colour && u.init?.k === "hex"
+                    ? at(u.pos, () => sl.uniform.colour(u.name, (u.init as { hex: string }).hex, width as 3 | 4) as unknown as Val)
+                    : at(u.pos, () => declareUniform(u.name, u.type, components))
+                global.declare(u.name, { width, value })
             }
 
             for (const t of unit.textures) samplers.set(t.name, at(t.pos, () => sl.texture(t.name)))

package/src/serial.ts

@@ -123,7 +123,9 @@ function uniform(u: unknown, i: number): UniformDecl {
     if (typeof x.name !== "string" || ![1, 2, 3, 4].includes(x.type as number) || !Array.isArray(x.value)) {
         fail(`uniform ${i} needs a name, a width and a value`)
     }
-    return { name: x.name!, type: x.type as SLType, value: x.value!.slice() }
+    const out: UniformDecl = { name: x.name!, type: x.type as SLType, value: x.value!.slice() }
+    if (x.colour === true) out.colour = true
+    return out
 }
 
 function texture(t: unknown, i: number): TextureDecl {

package/src/sl.ts

@@ -664,6 +664,24 @@ export const uniform = {
         const b = ctx()
         return mk(b, b.uniform(name, TYPE.VEC4, value), TYPE.VEC4)
     },
+    /**
+     * A colour, defaulting to `hex` as written (sRGB, the way CSS reads it).
+     * Returns it converted to linear, as a hex literal is, and marks the
+     * declaration `colour` so a host can offer a colour picker for it. Three
+     * components when `width` is 3, dropping the alpha.
+     */
+    colour: ((name: string, hex: string, width: 3 | 4 = 4): Vec3 | Vec4 => {
+        const b = ctx()
+        const c = parseHex(hex)
+        const type = width === 3 ? TYPE.VEC3 : TYPE.VEC4
+        const raw = mk(b, b.uniform(name, type, c.slice(0, width), true), type)
+        return toLinear(raw) as Vec3 | Vec4
+    }) as {
+        (name: string, hex: string): Vec4
+        (name: string, hex: string, width: 3): Vec3
+        (name: string, hex: string, width: 4): Vec4
+        (name: string, hex: string, width: 3 | 4): Vec3 | Vec4
+    },
 }
 
 export interface Texture {