onejs-sl 0.3.0 → 0.5.0

package/src/sl.ts

@@ -24,10 +24,10 @@
 
 import { parseColor as parseHex } from "./color"
 import {
-    Builder, INPUTS, SLError, SL_IR_VERSION, TYPE, hashProgram, widthName,
-    type InputName, type NodeRef, type Program, type SLNode, type SLType, type UniformControl,
+    Builder, INPUTS, RAMP_STOP_COMPUTED, SLError, TYPE, hashProgram, programVersion, truncateHeld, widthName, writtenColour,
+    type InputName, type NodeRef, type Program, type SLKind, type SLNode, type SLType, type UniformControl,
 } from "./ir"
-import { SLOP, type SLOpCode } from "./ops"
+import { SLOP, SL_HLSL, SL_NAME, type SLOpCode } from "./ops"
 import { SL_SDF_PARAMS, SL_SDF_SHAPES, type SlSdfKind } from "./shapes"
 
 // MARK: values
@@ -55,7 +55,8 @@ export type Num = Val | number
 // point rather than a hazard; see the comment above that loop.
 // eslint-disable-next-line @typescript-eslint/no-unsafe-declaration-merging
 export class Val {
-    constructor(readonly owner: Builder, readonly ref: NodeRef, readonly width: SLType) {}
+    /** `kind` is what the value holds beside its width: an int, a uint or a bool. None means floats. */
+    constructor(readonly owner: Builder, readonly ref: NodeRef, readonly width: SLType, readonly kind?: SLKind) {}
 
     // Arithmetic. Mixing a vector with a Float broadcasts, as in HLSL.
     add(o: Num): this { return bin(SLOP.ADD, this, o) as this }
@@ -73,6 +74,11 @@ export class Val {
     min(o: Num): this { return bin(SLOP.MIN, this, o) as this }
     max(o: Num): this { return bin(SLOP.MAX, this, o) as this }
     clamp(lo: Num, hi: Num): this {
+        if ([this, lo, hi].some((v) => typeof v !== "number" && v.kind !== undefined)) {
+            const u = unify([this, lo, hi])
+            if (u.kind !== undefined) return mk(u.owner, u.owner.call(SLOP.CLAMP, u.width, u.refs, undefined, u.kind), u.width, u.kind) as this
+            return (mk(u.owner, u.refs[0]!, u.width) as Val).clamp(mk(u.owner, u.refs[1]!, u.width) as Val, mk(u.owner, u.refs[2]!, u.width) as Val) as this
+        }
         const { refs, width } = alignN([this, lo, hi])
         return mk(this.owner, this.owner.call(SLOP.CLAMP, width, refs), width) as this
     }
@@ -89,6 +95,27 @@ export class Val {
     }
     normalize(): this { return un(SLOP.NORMALIZE, this) as this }
 
+    // Comparisons give a bool per component; an int meeting a float is compared as a float.
+    lt(o: Num): Bool { return compare(SLOP.LT, this, o) }
+    le(o: Num): Bool { return compare(SLOP.LE, this, o) }
+    gt(o: Num): Bool { return compare(SLOP.GT, this, o) }
+    ge(o: Num): Bool { return compare(SLOP.GE, this, o) }
+    eq(o: Num): Bool { return compare(SLOP.EQ, this, o) }
+    ne(o: Num): Bool { return compare(SLOP.NE, this, o) }
+
+    // Logic, on bools.
+    and(o: Val | boolean): Bool { return logic(SLOP.AND, this, o) }
+    or(o: Val | boolean): Bool { return logic(SLOP.OR, this, o) }
+    not(): Bool { return logic(SLOP.NOT, this) }
+
+    // Bits, on ints and uints. A shift takes its count modulo 32 on every backend.
+    band(o: Num): this { return bits(SLOP.BIT_AND, this, o) as this }
+    bor(o: Num): this { return bits(SLOP.BIT_OR, this, o) as this }
+    bxor(o: Num): this { return bits(SLOP.BIT_XOR, this, o) as this }
+    shl(o: Num): this { return bits(SLOP.SHL, this, o) as this }
+    shr(o: Num): this { return bits(SLOP.SHR, this, o) as this }
+    bnot(): this { return bits(SLOP.BIT_NOT, this) as this }
+
     /**
      * Arbitrary swizzle. The common single and full width ones are also getters
      * (`p.x`, `c.rgb`); this covers everything else and is typed by its argument,
@@ -106,7 +133,7 @@ export class Val {
             chans.push(c)
         }
         const t = chans.length as SLType
-        return mk(this.owner, this.owner.add({ k: "swizzle", type: t, src: this.ref, chans }), t) as Widen<S>
+        return mk(this.owner, this.owner.add(withKind({ k: "swizzle", type: t, src: this.ref, chans }, this.kind)), t, this.kind) as Widen<S>
     }
 
     get x(): Float { return this.swz("x") }
@@ -160,9 +187,18 @@ export interface Float extends Val { readonly width: 1 }
 export interface Vec2 extends Val { readonly width: 2 }
 export interface Vec3 extends Val { readonly width: 3 }
 export interface Vec4 extends Val { readonly width: 4 }
+/** A value holding a bool, an int or a uint rather than floats. */
+export interface Bool extends Val { readonly width: 1; readonly kind: "bool" }
+export interface Int extends Val { readonly width: 1; readonly kind: "int" }
+export interface UInt extends Val { readonly width: 1; readonly kind: "uint" }
+
+function mk(b: Builder, ref: NodeRef, width: SLType, kind?: SLKind): any {
+    return new Val(b, ref, width, kind)
+}
 
-function mk(b: Builder, ref: NodeRef, width: SLType): any {
-    return new Val(b, ref, width)
+/** A node with its kind, which a float node leaves out so it keys and hashes as it always did. */
+function withKind<T extends SLNode>(n: T, kind: SLKind | undefined): T {
+    return kind === undefined ? n : { ...n, kind }
 }
 
 // MARK: recording context
@@ -233,19 +269,222 @@ function alignN(vs: Num[]): { refs: NodeRef[]; width: SLType } {
 
 /** float -> vecN by repeating the component. */
 function broadcast(v: Val, width: SLType): NodeRef {
-    return v.owner.add({ k: "swizzle", type: width, src: v.ref, chans: new Array(width).fill(0) })
+    return v.owner.add(withKind({ k: "swizzle", type: width, src: v.ref, chans: new Array(width).fill(0) }, v.kind))
 }
 
 function bin(op: SLOpCode, a: Val, o: Num): Val {
+    if (a.kind !== undefined || (typeof o !== "number" && o.kind !== undefined)) return kindedBin(op, a, o)
     const [x, y] = align2(a, o)
     const width = typeof o === "number" ? a.width : (Math.max(a.width, o.width) as SLType)
     return mk(a.owner, a.owner.call(op, width, [x, y]), width)
 }
 
 function un(op: SLOpCode, a: Val): Val {
+    if (a.kind !== undefined) {
+        if ((op === SLOP.NEG || op === SLOP.ABS) && a.kind === "int") return mk(a.owner, a.owner.call(op, a.width, [a.ref], undefined, a.kind), a.width, a.kind)
+        a = toFloat(a)
+    }
     return mk(a.owner, a.owner.call(op, a.width, [a.ref]), a.width)
 }
 
+// MARK: kinds (IR 4)
+
+/** The ops an int or a uint keeps its kind through. Anything else takes it as a float. */
+const INT_OPS = new Set<number>([SLOP.ADD, SLOP.SUB, SLOP.MUL, SLOP.DIV, SLOP.MOD, SLOP.MIN, SLOP.MAX, SLOP.CLAMP])
+
+/** A value as floats: itself when it already is, a conversion otherwise (a bool is 0 or 1). */
+export function toFloat(v: Val): Val {
+    if (v.kind === undefined) return v
+    return mk(v.owner, v.owner.call(SLOP.CAST, v.width, [v.ref]), v.width)
+}
+
+/**
+ * The operands of an op brought to one kind and one width.
+ *
+ * Two ints stay ints, and a whole number beside one is an int too. Anything
+ * else meeting a float, a bool among them, becomes a float, as HLSL converts
+ * it. An int and a uint are refused, since which one wins is a guess.
+ */
+function unify(vs: Num[]): { refs: NodeRef[]; width: SLType; kind: SLKind | undefined; owner: Builder } {
+    let owner: Builder | null = null
+    const kinds = new Set<SLKind | undefined>()
+    let width: SLType = 1
+    for (const v of vs) {
+        if (typeof v === "number") continue
+        if (owner === null) owner = v.owner
+        else if (v.owner !== owner) throw new SLError("a value from another program cannot be used in this one")
+        kinds.add(v.kind)
+        if (v.width > width) width = v.width
+    }
+    const b = owner ?? ctx()
+    if (kinds.has("int") && kinds.has("uint")) {
+        throw new SLError("cannot combine an int with a uint; convert one with int(...) or uint(...)")
+    }
+    let kind = kinds.size === 1 ? [...kinds][0] : undefined
+    if (kind === "bool") kind = undefined
+    if (kind !== undefined && vs.some((v) => typeof v === "number" && !Number.isInteger(v))) kind = undefined
+    const refs = vs.map((v) => {
+        if (typeof v === "number") return b.constant(new Array(width).fill(v), kind)
+        const x = kind === undefined ? toFloat(v) : v
+        if (x.width === width) return x.ref
+        if (x.width === 1) return broadcast(x, width)
+        throw new SLError(`cannot combine a ${widthName(x.width)} with a ${widthName(width)}`)
+    })
+    return { refs, width, kind, owner: b }
+}
+
+function kindedBin(op: SLOpCode, a: Val, o: Num): Val {
+    const { refs, width, kind, owner } = unify([a, o])
+    if (kind === undefined || !INT_OPS.has(op)) {
+        const x = mk(owner, refs[0]!, width) as Val
+        return bin(op, x, mk(owner, refs[1]!, width) as Val)
+    }
+    return mk(owner, owner.call(op, width, refs, undefined, kind), width, kind)
+}
+
+function compare(op: SLOpCode, a: Val, o: Num): Bool {
+    const { refs, width, kind, owner } = unify([a, o])
+    void kind
+    return mk(owner, owner.call(op, width, refs, undefined, "bool"), width, "bool")
+}
+
+/** A bool operand, a JS boolean made a constant. */
+function asBool(b: Builder, v: Val | boolean, what: string): Val {
+    if (typeof v === "boolean") return mk(b, b.constant([v ? 1 : 0], "bool"), 1, "bool")
+    if (v.kind !== "bool") throw new SLError(`${what} takes bools, and this is ${v.kind === undefined ? `a ${widthName(v.width)}` : `an ${v.kind}`}; compare it, as in x > 0`)
+    return v
+}
+
+function logic(op: SLOpCode, a: Val, o?: Val | boolean): Bool {
+    const name = op === SLOP.AND ? "&&" : op === SLOP.OR ? "||" : "!"
+    const x = asBool(a.owner, a, name)
+    if (o === undefined) return mk(a.owner, a.owner.call(op, x.width, [x.ref], undefined, "bool"), x.width, "bool")
+    const y = asBool(a.owner, o, name)
+    if (x.width !== y.width) throw new SLError(`cannot combine a bool${x.width} with a bool${y.width}`)
+    return mk(a.owner, a.owner.call(op, x.width, [x.ref, y.ref], undefined, "bool"), x.width, "bool")
+}
+
+function bits(op: SLOpCode, a: Val, o?: Num): Val {
+    const word = SL_HLSL[op]?.syntax ?? SL_NAME[op]
+    const intOnly = (v: Num) => {
+        if (typeof v === "number" ? !Number.isInteger(v) : v.kind !== "int" && v.kind !== "uint") {
+            throw new SLError(`${word} works on the bits of an int or a uint, and this is ${typeof v === "number" ? "a fraction" : v.kind === "bool" ? "a bool; use && or ||" : `a ${widthName(v.width)}`}`)
+        }
+    }
+    intOnly(a)
+    if (o === undefined) return mk(a.owner, a.owner.call(op, a.width, [a.ref], undefined, a.kind), a.width, a.kind)
+    intOnly(o)
+    // A shift's count is its own kind; the value shifted keeps its own.
+    if (op === SLOP.SHL || op === SLOP.SHR) {
+        const count = typeof o === "number" ? a.owner.constant([o], a.kind) : o.ref
+        return mk(a.owner, a.owner.call(op, a.width, [a.ref, count], undefined, a.kind), a.width, a.kind)
+    }
+    const { refs, width, kind, owner } = unify([a, o])
+    return mk(owner, owner.call(op, width, refs, undefined, kind), width, kind)
+}
+
+/** A conversion to `kind`, or to floats when it is undefined. A float to an int truncates toward zero, held to the int's range. */
+function convert(v: Num | boolean, kind: SLKind | undefined): Val {
+    const b = typeof v === "object" ? v.owner : ctx()
+    if (typeof v === "boolean") v = mk(b, b.constant([v ? 1 : 0], "bool"), 1, "bool") as Val
+    if (typeof v === "number") {
+        if (kind === undefined) return mk(b, b.constant([v]), 1)
+        if (kind === "bool") return mk(b, b.constant([v !== 0 ? 1 : 0], "bool"), 1, "bool")
+        // A whole number the kind holds is that number exactly (`747796405u`);
+        // anything else is a float converted, as the GPU would.
+        const exact = Number.isInteger(v) && (kind === "int" ? v >= -2147483648 && v <= 2147483647 : v >= 0 && v <= 4294967295)
+        return mk(b, b.constant([exact ? v : truncateHeld(v, kind)], kind), 1, kind)
+    }
+    if (v.kind === kind) return v
+    return mk(b, b.call(SLOP.CAST, v.width, [v.ref], undefined, kind), v.width, kind)
+}
+
+/** An int: a whole number, or a value converted, a float truncating toward zero. */
+export function int(v: Num | boolean): Int { return convert(v, "int") as Int }
+export function uint(v: Num | boolean): UInt { return convert(v, "uint") as UInt }
+/** A bool: true or false, or a value converted, where anything but zero is true. */
+export function bool(v: Num | boolean): Bool { return convert(v, "bool") as Bool }
+
+function choose(b: Builder, cond: Num | boolean, whenTrue: Num, whenFalse: Num): Val {
+    if (typeof cond === "boolean") return convertTo(cond ? whenTrue : whenFalse, whenTrue, whenFalse)
+    // What SELECT reads a float condition as, so the two agree.
+    const c = typeof cond === "number" ? asBool(b, cond >= 0.5, "a choice")
+        : cond.kind === "bool" ? cond : cond.kind === undefined ? cond.ge(0.5) : cond.ne(0)
+    if (c.width !== 1) throw new SLError("a choice takes one bool, and this is several; combine them with && or ||")
+    const { refs, width, kind, owner } = unify([whenTrue, whenFalse])
+    return mk(owner, owner.call(SLOP.CHOOSE, width, [c.ref, ...refs], undefined, kind), width, kind)
+}
+
+/** `v` as the type the two would unify to, for a choice whose condition is known. */
+function convertTo(v: Num, a: Num, c: Num): Val {
+    const { refs, width, kind, owner } = unify([a, c])
+    return mk(owner, v === a ? refs[0]! : refs[1]!, width, kind)
+}
+
+/**
+ * A real branch: only the side `cond` picks runs, and its results come back.
+ * Both sides give the same number of results, pairwise of one type; a plain
+ * number takes its partner's. A value only one side needs is computed only when
+ * that side runs.
+ */
+export function branch(cond: Val | boolean, whenTrue: () => Num[], whenFalse: () => Num[]): Val[] {
+    const b = ctx()
+    if (typeof cond === "boolean") return (cond ? whenTrue() : whenFalse()).map((v) => (typeof v === "number" ? float(v) : v))
+    const c = asBool(b, cond, "a branch")
+    if (c.width !== 1) throw new SLError("a branch takes one bool, and this is several; combine them with && or ||")
+    const t = whenTrue()
+    const f = whenFalse()
+    if (t.length !== f.length) throw new SLError(`a branch's sides give ${t.length} and ${f.length} results; they must give the same`)
+    const types = t.map((x, i) => pairType(x, f[i]!, i))
+    if (types.length === 0) return []
+    const node = b.add({ k: "if", cond: c.ref, then: t.map((v, i) => typed(b, v, types[i]!)), else: f.map((v, i) => typed(b, v, types[i]!)) })
+    return types.map((ty, i) => mk(b, b.add(withKind({ k: "proj", type: ty.width, src: node, index: i }, ty.kind)), ty.width, ty.kind))
+}
+
+/**
+ * A real loop. The values start as `init`; while `cond` of them holds, and
+ * fewer than `max` turns have run, they become `body` of them. What comes back
+ * is the values when it stops. `max` is what guarantees it stops: a loop that
+ * reaches it leaves as if its condition had failed.
+ */
+export function loop(init: Num[], cond: (v: Val[]) => Val | boolean, body: (v: Val[]) => Num[], max = 1024): Val[] {
+    const b = ctx()
+    if (!Number.isInteger(max) || max < 1) throw new SLError(`a loop's turn limit is a whole number from 1, got ${max}`)
+    const start = init.map((v) => (typeof v === "number" ? (float(v) as Val) : v))
+    const id = b.newLoop()
+    const params = start.map((v, i) => mk(b, b.add(withKind({ k: "param", type: v.width, loop: id, index: i }, v.kind)), v.width, v.kind) as Val)
+    const c = asBool(b, cond(params), "a loop's condition")
+    if (c.width !== 1) throw new SLError("a loop's condition is one bool, and this is several; combine them with && or ||")
+    const next = body(params)
+    if (next.length !== params.length) throw new SLError(`a loop carries ${params.length} values and its body gave ${next.length}`)
+    const ty = params.map((p) => ({ width: p.width, kind: p.kind }))
+    const node = b.add({
+        k: "loop", id, init: start.map((v) => v.ref), cond: c.ref,
+        next: next.map((v, i) => { pairType(params[i]!, v, i); return typed(b, v, ty[i]!) }), max,
+    })
+    return ty.map((t, i) => mk(b, b.add(withKind({ k: "proj", type: t.width, src: node, index: i }, t.kind)), t.width, t.kind))
+}
+
+interface ValType { width: SLType; kind: SLKind | undefined }
+
+/** The one type two results share, or why they do not. */
+function pairType(a: Num, c: Num, i: number): ValType {
+    if (typeof a === "number" && typeof c === "number") return { width: 1, kind: undefined }
+    if (typeof a === "number") return { width: (c as Val).width, kind: (c as Val).kind }
+    if (typeof c === "number") return { width: a.width, kind: a.kind }
+    if (a.width !== c.width || a.kind !== c.kind) {
+        const name = (v: Val) => (v.kind === undefined ? widthName(v.width) : v.width === 1 ? v.kind : `${v.kind}${v.width}`)
+        throw new SLError(`result ${i} is a ${name(a)} one way and a ${name(c)} the other`)
+    }
+    return { width: a.width, kind: a.kind }
+}
+
+/** A result as a node of its type, a plain number becoming a constant. */
+function typed(b: Builder, v: Num, t: ValType): NodeRef {
+    if (typeof v === "number") return b.constant(new Array(t.width).fill(v), t.kind)
+    return v.ref
+}
+
 // MARK: the public surface
 
 export interface ProgramInputs {
@@ -288,7 +527,7 @@ export function program(fn: (inputs: ProgramInputs) => Vec4): Program {
         }
         const nodes: SLNode[] = b.nodes.slice()
         return {
-            version: SL_IR_VERSION,
+            version: programVersion(nodes, out.ref),
             nodes,
             result: out.ref,
             uniforms: b.uniforms.slice(),
@@ -302,7 +541,8 @@ export function program(fn: (inputs: ProgramInputs) => Vec4): Program {
 
 export function float(v: Num): Float {
     const b = ctx()
-    return typeof v === "number" ? mk(b, b.constant([v]), TYPE.FLOAT) : (v as Float)
+    if (typeof v !== "number") return (v.kind === undefined ? v : toFloat(v)) as Float
+    return mk(b, b.constant([v]), TYPE.FLOAT)
 }
 
 /** Builds a wider value from narrower parts, which must add up exactly. */
@@ -478,8 +718,12 @@ export function atan2(y: Num, x: Num): Float {
  * rather than an `if`: a real branch would have to survive both backends
  * identically, and this does not.
  */
-export function select(cond: Num, whenTrue: Num, whenFalse: Num): Val {
+export function select(cond: Num | boolean, whenTrue: Num, whenFalse: Num): Val {
     const b = ctx()
+    const kinded = (v: Num | boolean) => typeof v === "object" && v.kind !== undefined
+    // A bool condition, or results that are not floats: a choice, which carries
+    // any kind, where SELECT's arithmetic carries only floats (IR 4).
+    if (typeof cond === "boolean" || kinded(cond) || kinded(whenTrue) || kinded(whenFalse)) return choose(b, cond, whenTrue, whenFalse)
     const c = typeof cond === "number" ? float(cond) : cond
     const t = typeof whenTrue === "number" ? float(whenTrue) : whenTrue
     const f = typeof whenFalse === "number" ? float(whenFalse) : whenFalse
@@ -533,6 +777,10 @@ export function uniformDefaults(p: Program): number[] {
  * fields `fx.noise` draws: a value or simplex base, layered as fBm, or the
  * turbulence and ridged variants built on simplex. A program has no seed;
  * offset the input for a different field. Octaves are 1 to 4, as in fx.
+ *
+ * The octave count may be a value, a uniform say, rounded to the nearest whole
+ * number and held to 1 to 4 where it is read. It is an operand either way
+ * (IR 3); a constant one is checked here, and prints as the number it is.
  */
 export function noise(p: Vec2): Float {
     return mk(p.owner, p.owner.call(SLOP.NOISE, TYPE.FLOAT, [p.ref]), TYPE.FLOAT)
@@ -540,24 +788,31 @@ export function noise(p: Vec2): Float {
 export function simplex(p: Vec2): Float {
     return mk(p.owner, p.owner.call(SLOP.SIMPLEX, TYPE.FLOAT, [p.ref]), TYPE.FLOAT)
 }
-function octaveCount(name: string, octaves: number): number {
-    if (!Number.isInteger(octaves) || octaves < 1 || octaves > 4) {
-        throw new SLError(`${name} octaves must be a whole number from 1 to 4, got ${octaves}`)
+/**
+ * An octave op: the point and the count as operands, with `rest` (fbm's kind)
+ * the immediates. A constant count is checked here.
+ */
+function octaves(op: SLOpCode, name: string, p: Vec2, count: Num, rest: number[]): Float {
+    const c = components(p.owner, count)
+    if (c.length !== 1) throw new SLError(`${name}'s octave count is one number, and this is a ${widthName(c.length as SLType)}`)
+    const n = c[0]!
+    if (typeof n === "number" && (!Number.isInteger(n) || n < 1 || n > 4)) {
+        throw new SLError(`${name} octaves must be a whole number from 1 to 4, got ${n}`)
     }
-    return octaves
+    const v = typeof n === "number" ? float(n) : n
+    return mk(p.owner, p.owner.call(op, TYPE.FLOAT, [p.ref, v.ref], rest), TYPE.FLOAT)
 }
 /** Layered noise. `base` picks the grid ("value", the default) or triangles ("simplex"). */
-export function fbm(p: Vec2, octaves = 3, base: "value" | "simplex" = "value"): Float {
-    const kind = base === "simplex" ? 1 : 0
-    return mk(p.owner, p.owner.call(SLOP.FBM, TYPE.FLOAT, [p.ref], [octaveCount("fbm", octaves), kind]), TYPE.FLOAT)
+export function fbm(p: Vec2, octaveCount: Num = 3, base: "value" | "simplex" = "value"): Float {
+    return octaves(SLOP.FBM, "fbm", p, octaveCount, [base === "simplex" ? 1 : 0])
 }
 /** Sum of |simplex| octaves: creases that stack into veins and licks. Fire, smoke, marble. */
-export function turbulence(p: Vec2, octaves = 3): Float {
-    return mk(p.owner, p.owner.call(SLOP.TURBULENCE, TYPE.FLOAT, [p.ref], [octaveCount("turbulence", octaves)]), TYPE.FLOAT)
+export function turbulence(p: Vec2, octaveCount: Num = 3): Float {
+    return octaves(SLOP.TURBULENCE, "turbulence", p, octaveCount, [])
 }
 /** The turbulence crease made bright and squared: ridges, lightning, cracks. */
-export function ridged(p: Vec2, octaves = 3): Float {
-    return mk(p.owner, p.owner.call(SLOP.RIDGED, TYPE.FLOAT, [p.ref], [octaveCount("ridged", octaves)]), TYPE.FLOAT)
+export function ridged(p: Vec2, octaveCount: Num = 3): Float {
+    return octaves(SLOP.RIDGED, "ridged", p, octaveCount, [])
 }
 
 /** "#rgb", "#rrggbb" or "#rrggbbaa" to 0..1 components. Shared with fx. */
@@ -581,14 +836,23 @@ export function parseColor(hex: string): [number, number, number, number] {
  *
  * This is the argument for the EDSL in miniature. A library function that
  * composes from primitives costs one function here and nothing anywhere else.
+ *
+ * A stop is a colour as written: a hex, four numbers, or a value that is a
+ * colour as written, which is one `color`, `sl.uniform.colour` or a hex
+ * literal made (a colour uniform, say). The ramp blends the colours as
+ * written, so a value computed any other way, already in the working space,
+ * has nothing it could blend, and is refused.
  */
-export function ramp(t: Num, stops: Array<string | [number, number, number, number]>): Vec4 {
+export function ramp(t: Num, stops: Array<string | [number, number, number, number] | Vec3 | Vec4>): Vec4 {
     if (stops.length < 2) throw new SLError(`a ramp needs at least 2 stops, got ${stops.length}`)
     const tv = (typeof t === "number" ? float(t) : t).saturate()
+    const written = stops.map((s) => (s instanceof Val ? asWritten(s) : null))
     // Each stop is built immediately before the mix that consumes it. The graph
     // and the hash are the same either way (the hash is over the shape, not the
     // storage order); the order only mattered to the VM's register allocator.
     const colourAt = (i: number) => {
+        const w = written[i]
+        if (w !== null && w !== undefined) return w
         const v = typeof stops[i] === "string" ? parseColor(stops[i] as string) : (stops[i] as number[])
         return vec4(v[0], v[1], v[2], v[3])
     }
@@ -606,6 +870,18 @@ export function ramp(t: Num, stops: Array<string | [number, number, number, numb
     return toLinear(out)
 }
 
+/**
+ * A colour value as it was written, a float4: the operand of the `toLinear`
+ * that reading it as a colour applied, with alpha 1 when it has three
+ * components. Anything else was computed in the working space.
+ */
+function asWritten(v: Vec3 | Vec4): Vec4 {
+    const ref = writtenColour(v.owner.nodes, v.ref)
+    if (ref === null) throw new SLError(RAMP_STOP_COMPUTED)
+    const raw = mk(v.owner, ref, v.width) as Val
+    return v.width === TYPE.VEC4 ? (raw as Vec4) : vec4(raw, 1)
+}
+
 /**
  * Signed distance to a shape, positive outside and negative inside.
  *
@@ -621,27 +897,45 @@ export function ramp(t: Num, stops: Array<string | [number, number, number, numb
  *
  * A shape takes up to `SL_SDF_PARAMS[kind]` parameters, six at most. Fewer
  * fills zeros, which is all a program could pass before six shapes grew their
- * fifth and sixth.
+ * fifth and sixth. A vector parameter counts as its components, so a box's
+ * half extents can be one float2.
  *
  * Which parameters a shape takes is the shape's own business; `circle` wants a
  * radius, `roundedBox` wants half extents and a corner. See `lib/sdf2d.hlsl`.
+ *
+ * A parameter may be any value, a uniform or one computed per pixel. The six
+ * are operands either way (IR 3), a float4 and a float2, and constant ones
+ * print as the numbers they are.
  */
-export function sdf(kind: SlSdfKind, p: Vec2, params: number[] = []): Float {
+export function sdf(kind: SlSdfKind, p: Vec2, params: Num[] = []): Float {
     const id = SL_SDF_SHAPES[kind]
     if (id === undefined) throw new SLError(`"${kind}" is not a shape; see SL_SDF_SHAPES for the 42 names`)
+    const c = params.flatMap((v) => components(p.owner, v))
     // At least four, so a program that passed a shape more than it reads, which
     // was harmless when every shape took four, still builds.
     const most = Math.max(4, SL_SDF_PARAMS[kind])
-    if (params.length > most) {
-        throw new SLError(`sl.sdf("${kind}") takes at most ${most} parameters and was given ${params.length}`)
+    if (c.length > most) {
+        throw new SLError(`sl.sdf("${kind}") takes at most ${most} parameters and was given ${c.length}`)
     }
-    for (const v of params) {
-        if (!Number.isFinite(v)) throw new SLError(`sl.sdf parameters must be finite, got ${v}`)
+    for (const v of c) {
+        if (typeof v === "number" && !Number.isFinite(v)) throw new SLError(`sl.sdf parameters must be finite, got ${v}`)
     }
-    // Four always, as before, and a fifth and sixth only when given: a program
-    // using four or fewer is the same node, and hashes the same, as it was.
-    const imm = [params[0] ?? 0, params[1] ?? 0, params[2] ?? 0, params[3] ?? 0, ...params.slice(4)]
-    return mk(p.owner, p.owner.call(SLOP.SDF, TYPE.FLOAT, [p.ref], [id, ...imm]), TYPE.FLOAT)
+    const q = vec4(c[0] ?? 0, c[1] ?? 0, c[2] ?? 0, c[3] ?? 0)
+    const r = vec2(c[4] ?? 0, c[5] ?? 0)
+    return mk(p.owner, p.owner.call(SLOP.SDF, TYPE.FLOAT, [p.ref, q.ref, r.ref], [id]), TYPE.FLOAT)
+}
+
+/**
+ * A value as its components: numbers for a constant, which is what it would
+ * have been written as, and a float per component otherwise.
+ */
+function components(b: Builder, v: Num): Num[] {
+    if (typeof v === "number") return [v]
+    if (v.owner !== b) throw new SLError("a value from another program cannot be used in this one")
+    const n = b.nodes[v.ref]!
+    if (n.k === "const") return n.v.slice()
+    if (v.width === 1) return [v]
+    return Array.from({ length: v.width }, (_, i) => v.swz("xyzw"[i] as "x"))
 }
 
 /** Distance to the nearest point of a jittered lattice. Cells, cracks, scales. */
@@ -696,7 +990,14 @@ export const uniform = {
 }
 
 export interface Texture {
+    /** The colour at `uv`, filtered as the texture's own settings say. */
     sample(uv: Vec2): Vec4
+    /**
+     * The colour at `uv` from mip level `lod`: 0 is the full size texture, 1
+     * half, and a fraction blends two levels where the texture's filter does.
+     * A texture with no mips has only level 0.
+     */
+    sampleLevel(uv: Vec2, lod: Num): Vec4
 }
 
 export function texture(name: string): Texture {
@@ -707,6 +1008,15 @@ export function texture(name: string): Texture {
             if (uv.owner !== b) throw new SLError("a value from another program cannot be used in this one")
             return mk(b, b.call(SLOP.SAMPLE, TYPE.VEC4, [uv.ref], [slot]), TYPE.VEC4)
         },
+        sampleLevel(uv: Vec2, lod: Num): Vec4 {
+            if (uv.owner !== b) throw new SLError("a value from another program cannot be used in this one")
+            const level = typeof lod === "number" ? b.constant([lod]) : lod
+            if (typeof level !== "number") {
+                if (level.owner !== b) throw new SLError("a value from another program cannot be used in this one")
+                if (level.width !== 1) throw new SLError(`a mip level is one number, and this is a ${widthName(level.width)}`)
+            }
+            return mk(b, b.call(SLOP.SAMPLE_LOD, TYPE.VEC4, [uv.ref, typeof level === "number" ? level : level.ref], [slot]), TYPE.VEC4)
+        },
     }
 }