onejs-sl 0.3.0 → 0.5.0

package/src/ir.ts

@@ -64,12 +64,75 @@ export const SOURCE_INPUTS: Readonly<Record<SourceInputName, SLType>> = { ...INP
 /** Index into `Program.nodes`. Always refers backwards. */
 export type NodeRef = number
 
-export type SLNode =
-    | { k: "const"; type: SLType; v: number[] }
-    | { k: "input"; type: SLType; name: InputName }
-    | { k: "uniform"; type: SLType; slot: number }
-    | { k: "swizzle"; type: SLType; src: NodeRef; chans: number[] }
-    | { k: "call"; type: SLType; op: SLOpCode; args: NodeRef[]; imm?: number[] }
+/**
+ * What a value holds, beside its width. A node without one holds floats, which
+ * is every node before IR 4, so a program of floats is the graph and the hash
+ * it always was.
+ */
+export type SLKind = "int" | "uint" | "bool"
+
+/**
+ * A node that is a value. `param` is a loop's carried value at the top of an
+ * iteration, `proj` one result of an `if` or a `loop`.
+ */
+export type ValueNode =
+    | { k: "const"; type: SLType; kind?: SLKind; v: number[] }
+    | { k: "input"; type: SLType; kind?: undefined; name: InputName }
+    | { k: "uniform"; type: SLType; kind?: undefined; slot: number }
+    | { k: "swizzle"; type: SLType; kind?: SLKind; src: NodeRef; chans: number[] }
+    | { k: "call"; type: SLType; kind?: SLKind; op: SLOpCode; args: NodeRef[]; imm?: number[] }
+    | { k: "param"; type: SLType; kind?: SLKind; loop: number; index: number }
+    | { k: "proj"; type: SLType; kind?: SLKind; src: NodeRef; index: number }
+
+/**
+ * Structured control flow (IR 4), as regions of the one graph rather than as
+ * statements: the graph stays a pure DAG, hash consed and hashed as before, and
+ * an emitter places each node in the innermost region that uses it
+ * (`structure.ts`), which is what makes a branch skip what only it needs.
+ *
+ *   if    `then` or `else` are the results, per the bool `cond`; its `proj`s read them
+ *   loop  the `param`s of loop `id` start as `init`; while `cond` holds and fewer
+ *         than `max` turns have run, they become `next`. Its `proj`s are the params
+ *         when it stops. `cond` and `next` are computed from the params.
+ */
+export type ControlNode =
+    | { k: "if"; cond: NodeRef; then: NodeRef[]; else: NodeRef[] }
+    | { k: "loop"; id: number; init: NodeRef[]; cond: NodeRef; next: NodeRef[]; max: number }
+
+export type SLNode = ValueNode | ControlNode
+
+/**
+ * A float to an int or a uint as the GPU converts one: as a 32 bit float,
+ * held to the widest such float the kind can hold, then truncated toward zero.
+ * The emitters clamp to these bounds, so a folded conversion
+ * and a computed one agree.
+ */
+export function truncateHeld(v: number, kind: "int" | "uint"): number {
+    const [lo, hi] = INT_BOUNDS[kind]
+    return Math.trunc(Math.min(hi, Math.max(lo, Math.fround(v))))
+}
+
+/** The widest 32 bit floats an int and a uint hold, which a conversion clamps to first. */
+export const INT_BOUNDS = { int: [-2147483648, 2147483520], uint: [0, 4294967040] } as const
+
+/** The value node at `ref`. A control node is only ever read through its projs. */
+export function valueAt(nodes: readonly SLNode[], ref: NodeRef): ValueNode {
+    const n = nodes[ref]
+    if (n === undefined || n.k === "if" || n.k === "loop") throw new SLError(`node ${ref} is not a value`)
+    return n
+}
+
+/** The refs a node reads, in order. */
+export function operands(n: SLNode): NodeRef[] {
+    switch (n.k) {
+        case "swizzle": return [n.src]
+        case "call": return n.args
+        case "proj": return [n.src]
+        case "if": return [n.cond, ...n.then, ...n.else]
+        case "loop": return [...n.init, n.cond, ...n.next]
+        default: return []
+    }
+}
 
 /**
  * How a host presents a uniform: a slider, a checkbox, a dropdown, a heading
@@ -171,7 +234,10 @@ export interface TextureDecl {
 }
 
 export interface Program {
-    /** The `SL_IR_VERSION` this program's nodes mean what they mean under. */
+    /**
+     * The `SL_IR_VERSION` this program's nodes mean what they mean under: the
+     * lowest one that has every node it holds. See `programVersion`.
+     */
     version: number
     nodes: SLNode[]
     /** Must be VEC4: a program produces a colour. */
@@ -210,6 +276,24 @@ export function checkCaps(p: Pick<Program, "uniforms" | "textures">): void {
     if (p.textures.length > TEXTURE_SLOTS) throw new SLError(tooManyTextures(p.textures.length, "program"))
 }
 
+/**
+ * The colour as written behind a colour value: the operand of the `TO_LINEAR`
+ * that reading a hex or a colour uniform applied, or null for a value computed
+ * in the working space. What a ramp's stop has to be, since a ramp blends its
+ * stops as written (`sl.ramp`).
+ */
+export function writtenColour(nodes: readonly SLNode[], ref: NodeRef): NodeRef | null {
+    const n = nodes[ref]!
+    if (n.k !== "call" || n.op !== SLOP.TO_LINEAR || (n.type !== TYPE.VEC3 && n.type !== TYPE.VEC4)) return null
+    return n.args[0]!
+}
+
+/** Why a computed value is not a ramp's stop, in one wording for both surfaces. */
+export const RAMP_STOP_COMPUTED =
+    "a ramp's stop is a colour as written: a hex like #ff8040, or a uniform or const that holds one. " +
+    "This one is computed, and a ramp blends its stops as written before it converts them, so it has " +
+    "no written colour to blend. Blend computed colours with lerp instead"
+
 /** Operations a single program may hold. Generous: a guard against a runaway builder, not a budget. */
 export const MAX_NODES = 4096
 
@@ -233,6 +317,10 @@ export class Builder {
     readonly textures: TextureDecl[] = []
     private readonly interned = new Map<string, NodeRef>()
 
+    /** The next loop's id: unique within the program, so two loops' params never intern to one node. */
+    private loops = 0
+    newLoop(): number { return this.loops++ }
+
     add(node: SLNode): NodeRef {
         if (this.nodes.length >= MAX_NODES) {
             throw new SLError(`a program may hold at most ${MAX_NODES} operations`)
@@ -245,7 +333,7 @@ export class Builder {
         return ref
     }
 
-    call(op: SLOpCode, type: SLType, args: NodeRef[], imm?: number[]): NodeRef {
+    call(op: SLOpCode, type: SLType, args: NodeRef[], imm?: number[], kind?: SLKind): NodeRef {
         const arity = SL_ARITY[op]
         if (arity >= 0 && args.length !== arity) {
             throw new SLError(`${SL_NAME[op]} takes ${arity} argument(s), got ${args.length}`)
@@ -255,14 +343,19 @@ export class Builder {
                 throw new SLError(`${SL_NAME[op]} refers to a node that does not exist yet`)
             }
         }
-        return this.add(imm === undefined ? { k: "call", type, op, args } : { k: "call", type, op, args, imm })
+        const node: SLNode = imm === undefined ? { k: "call", type, op, args } : { k: "call", type, op, args, imm }
+        if (kind !== undefined) node.kind = kind
+        return this.add(node)
     }
 
-    constant(v: number[]): NodeRef {
+    constant(v: number[], kind?: SLKind): NodeRef {
         for (const n of v) {
             if (!Number.isFinite(n)) throw new SLError(`a constant must be finite, got ${n}`)
+            if (kind !== undefined && !Number.isInteger(n)) throw new SLError(`an ${kind} constant must be a whole number, got ${n}`)
         }
-        return this.add({ k: "const", type: v.length as SLType, v: v.slice() })
+        const node: SLNode = { k: "const", type: v.length as SLType, v: v.slice() }
+        if (kind !== undefined) node.kind = kind
+        return this.add(node)
     }
 
     uniform(name: string, type: SLType, value: number[], colour = false, control: UniformControl = {}): NodeRef {
@@ -327,9 +420,7 @@ export function reachable(nodes: SLNode[], result: NodeRef): NodeRef[] {
         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)
+        for (const a of operands(nodes[ref]!)) stack.push(a)
     }
     // Ascending, which is still topological because a node only refers backwards.
     return [...keep].sort((x, y) => x - y)
@@ -351,12 +442,17 @@ export function inputsUsed(p: Program): InputName[] {
 
 /** Structural key for hash consing. Order matters and is fixed by the node shape. */
 function keyOf(n: SLNode): string {
+    const kind = "kind" in n && n.kind !== undefined ? `@${n.kind}` : ""
     switch (n.k) {
-        case "const": return `c:${n.type}:${n.v.map(fixed).join(",")}`
+        case "const": return `c:${n.type}:${n.v.map((v) => constText(v, n.kind)).join(",")}${kind}`
         case "input": return `i:${n.name}`
         case "uniform": return `u:${n.slot}`
-        case "swizzle": return `s:${n.src}:${n.chans.join("")}`
-        case "call": return `f:${n.op}:${n.args.join(",")}:${(n.imm ?? []).map(fixed).join(",")}`
+        case "swizzle": return `s:${n.src}:${n.chans.join("")}${kind}`
+        case "call": return `f:${n.op}:${n.args.join(",")}:${(n.imm ?? []).map(fixed).join(",")}${kind}`
+        case "param": return `p:${n.loop}:${n.index}`
+        case "proj": return `j:${n.src}:${n.index}`
+        case "if": return `?:${n.cond}:${n.then.join(",")}:${n.else.join(",")}`
+        case "loop": return `L:${n.max}:${n.init.join(",")}:${n.cond}:${n.next.join(",")}`
     }
 }
 
@@ -369,6 +465,11 @@ export function fixed(n: number): string {
     return Object.is(n, -0) ? "0" : n.toPrecision(9)
 }
 
+/** A constant's value as keyed and hashed: a float at `fixed`'s precision, an int, a uint or a bool exactly. */
+function constText(n: number, kind: SLKind | undefined): string {
+    return kind === undefined ? fixed(n) : String(n)
+}
+
 export function widthName(t: SLType): string {
     return t === 1 ? "float" : `vec${t}`
 }
@@ -402,41 +503,113 @@ export function hashProgram(nodes: SLNode[], result: NodeRef, uniforms: UniformD
     // digests, so two graphs that compute the same thing agree however they were
     // assembled. It also ignores nodes not reachable from the result, which is
     // correct: dead nodes generate no shader code.
+    //
+    // NORMALISED, so two ways of writing one computation agree (hash version 2).
+    // A commutative op's operands are digested in sorted order, so `a + b` is
+    // `b + a`; and a swizzle of a constant is digested as the constant it picks,
+    // so `8 * uv` (8 broadcast by a swizzle) is `uv * 8` (a float2 constant).
+    // Only where every backend computes the same bits either way: min and max
+    // are left out, since which of -0 and +0 they return depends on the order.
     const digest = new Map<NodeRef, string>()
+    const depth = loopDepths(nodes, result)
 
     const of = (ref: NodeRef): string => {
         const seen = digest.get(ref)
         if (seen !== undefined) return seen
-        const n = nodes[ref]
+        const n = nodes[ref]!
         let body: string
         switch (n.k) {
-            case "const": body = `c:${n.type}:${n.v.map(fixed).join(",")}`; break
+            // Control nodes have no type of their own: their projs carry it.
+            case "if": {
+                body = `?:${of(n.cond)}:${n.then.map(of).join(",")}:${n.else.map(of).join(",")}`
+                const d = fnv1a(body)
+                digest.set(ref, d)
+                return d
+            }
+            case "loop": {
+                body = `L:${n.max}:${n.init.map(of).join(",")}:${of(n.cond)}:${n.next.map(of).join(",")}`
+                const d = fnv1a(body)
+                digest.set(ref, d)
+                return d
+            }
+            // By nesting depth, not by id: two programs that nest the same
+            // loops the same way agree however their ids were handed out, and
+            // two loops nested in one another never share a digest for a param.
+            case "param": body = `p:${depth.get(n.loop) ?? 1}:${n.index}`; break
+            case "proj": body = `j:${of(n.src)}:${n.index}`; break
+            case "const": body = `c:${n.type}:${n.v.map((v) => constText(v, n.kind)).join(",")}`; break
             case "input": body = `i:${n.name}`; break
             // By slot rather than by name: the slot is what the generated shader
             // lays out, so two programs whose uniforms differ only in name still
             // produce different shaders and must not share a hash. The names go
             // in separately below.
             case "uniform": body = `u:${n.slot}:${n.type}`; break
-            case "swizzle": body = `s:${of(n.src)}:${n.chans.join("")}`; break
-            case "call": body = `f:${n.op}:${n.args.map(of).join(",")}:${(n.imm ?? []).map(fixed).join(",")}`; break
+            case "swizzle": {
+                const src = nodes[n.src]!
+                body = src.k === "const" && src.kind === n.kind
+                    ? `c:${n.type}:${n.chans.map((c) => constText(src.v[c]!, src.kind)).join(",")}`
+                    : `s:${of(n.src)}:${n.chans.join("")}`
+                break
+            }
+            case "call": {
+                const args = n.args.map(of)
+                if (COMMUTATIVE.has(n.op)) args.sort()
+                body = `f:${n.op}:${args.join(",")}:${(n.imm ?? []).map(fixed).join(",")}`
+                break
+            }
         }
-        const d = fnv1a(body + "|" + n.type)
+        const d = fnv1a(body + "|" + n.type + (n.kind === undefined ? "" : n.kind))
         digest.set(ref, d)
         return d
     }
 
     // The IR version is in the hash, so a change to what an opcode means in the
-    // IR changes every hash and every cache keyed by one recompiles rather than
-    // serving the old maths. A change to the helper library alone (a noise's
-    // arithmetic, say) is not one: every host includes the library's text when
-    // it compiles, and none caches a compiled program by hash across a
-    // library update, so the new text reaches every shader without a bump.
-    const parts: string[] = [`v${SL_HASH_VERSION}:${SL_IR_VERSION}`, of(result)]
+    // IR changes the hash of every program using it, and every cache keyed by
+    // one recompiles rather than serving the old maths. It is the PROGRAM's
+    // version, the lowest that has its nodes, so a version that adds a node
+    // leaves every program without one on the hash it had. A change to the
+    // helper library alone (a noise's arithmetic, say) is not one: every host
+    // includes the library's text when it compiles, and none caches a compiled
+    // program by hash across a library update, so the new text reaches every
+    // shader without a bump.
+    const parts: string[] = [`v${SL_HASH_VERSION}:${programVersion(nodes, result)}`, of(result)]
     for (const u of uniforms) parts.push(`U:${u.name}:${u.type}:${u.value.map(fixed).join(",")}`)
     for (const t of textures) parts.push(`T:${t.name}:${t.slot}`)
     return fnv1a(parts.join("|"))
 }
 
+/**
+ * Each reachable loop's nesting depth, 1 for a loop inside no other: 1 more than
+ * the deepest loop whose params it reads. Read from the graph, so it does not
+ * depend on the order anything was built or walked in.
+ */
+function loopDepths(nodes: readonly SLNode[], result: NodeRef): Map<number, number> {
+    const free = new Map<NodeRef, Set<number>>()
+    const loops = new Map<number, Extract<SLNode, { k: "loop" }>>()
+    const freeOf = (ref: NodeRef): Set<number> => free.get(ref) ?? new Set()
+    for (const ref of reachable(nodes as SLNode[], result)) {
+        const n = nodes[ref]!
+        const out = new Set<number>()
+        if (n.k === "param") out.add(n.loop)
+        for (const a of operands(n)) for (const l of freeOf(a)) out.add(l)
+        if (n.k === "loop") { out.delete(n.id); loops.set(n.id, n) }
+        free.set(ref, out)
+    }
+    const loopFree = new Map<number, Set<number>>()
+    for (const [ref, n] of nodes.entries()) if (n.k === "loop" && free.has(ref)) loopFree.set(n.id, free.get(ref)!)
+    const depth = new Map<number, number>()
+    const of = (id: number): number => {
+        const seen = depth.get(id)
+        if (seen !== undefined) return seen
+        let d = 1
+        for (const outer of loopFree.get(id) ?? []) d = Math.max(d, of(outer) + 1)
+        depth.set(id, d)
+        return d
+    }
+    for (const id of loops.keys()) of(id)
+    return depth
+}
+
 /** The control fields of `c` that are set, copied, in `CONTROL_FIELDS` order. */
 export function controlOf(c: UniformControl): UniformControl {
     const out: UniformControl = {}
@@ -449,8 +622,91 @@ export function controlOf(c: UniformControl): UniformControl {
     return out
 }
 
-/** Bumped when the hashing scheme changes, which invalidates generated shaders. */
-export const SL_HASH_VERSION = 1
+/**
+ * The lowest `SL_IR_VERSION` that has every node here, and never below 2.
+ *
+ * A version that adds a node, or a form of one, raises only the programs that
+ * hold it. Everything else keeps the version, the hash and the JSON it had, so
+ * a program recorded before the bump still finds its shader, and a reader that
+ * predates the bump still reads it. Every node counts, used or not: the JSON
+ * carries them all, and an older reader has to refuse by the version rather
+ * than halfway through the nodes.
+ *
+ * Only the nodes the result reads count: lowering leaves dead nodes behind (an
+ * int constant a fold used up, say), and they draw nothing. `toJSON` writes
+ * only the live ones, so an older reader never meets a dead newer node.
+ */
+export function programVersion(nodes: readonly SLNode[], result: NodeRef): number {
+    let v = 2
+    for (const ref of reachable(nodes as SLNode[], result)) v = Math.max(v, nodeVersion(nodes[ref]!))
+    return v
+}
+
+/** The ops IR 4 added. */
+const IR4_OPS = new Set<number>([
+    SLOP.CAST, SLOP.LT, SLOP.LE, SLOP.GT, SLOP.GE, SLOP.EQ, SLOP.NE, SLOP.AND, SLOP.OR, SLOP.NOT,
+    SLOP.BIT_AND, SLOP.BIT_OR, SLOP.BIT_XOR, SLOP.BIT_NOT, SLOP.SHL, SLOP.SHR, SLOP.CHOOSE,
+])
+
+/**
+ * The version that added this node's form. An sdf or octave call with one
+ * operand is the form before IR 3, which only a file an older compiler wrote
+ * holds, and `fromJSON` moves it to the form IR 3 has.
+ */
+function nodeVersion(n: SLNode): number {
+    if (n.k === "if" || n.k === "loop" || n.k === "param" || n.k === "proj" || n.kind !== undefined) return 4
+    if (n.k !== "call") return 2
+    if (IR4_OPS.has(n.op)) return 4
+    switch (n.op) {
+        case SLOP.SAMPLE_LOD: return 3
+        case SLOP.SDF:
+        case SLOP.FBM:
+        case SLOP.TURBULENCE:
+        case SLOP.RIDGED:
+            return n.args.length > 1 ? 3 : 2
+        default: return 2
+    }
+}
+
+/**
+ * What is wrong with a call's form, for the ops whose operand list alone does
+ * not say it, or null. The builder only makes the right ones; this is for a
+ * program read from JSON, which an emitter would otherwise print as something
+ * else.
+ *
+ *   SDF  the point, a float4 and a float2 holding the six shape parameters,
+ *        the shape id the one immediate
+ *   FBM, TURBULENCE, RIDGED  the point and the octave count, FBM's kind the
+ *        one immediate
+ */
+export function formProblem(n: Extract<SLNode, { k: "call" }>, nodes: readonly SLNode[]): string | null {
+    const widths = n.args.map((a) => { const v = nodes[a]!; return v.k === "if" || v.k === "loop" ? "control" : v.type }).join(",")
+    switch (n.op) {
+        case SLOP.SDF:
+            if (widths === "2,4,2" && n.imm?.length === 1) return null
+            return "an sdf takes a float2, a float4 and a float2, and its shape as the one immediate"
+        case SLOP.FBM:
+        case SLOP.TURBULENCE:
+        case SLOP.RIDGED: {
+            const rest = n.op === SLOP.FBM ? 1 : 0
+            if (widths === "2,1" && (n.imm?.length ?? 0) === rest) return null
+            return `${SL_NAME[n.op]} takes a float2 and its octave count, a float`
+        }
+        default:
+            return null
+    }
+}
+
+/** The ops whose two operands the hash takes in either order: exact in IEEE arithmetic on every backend. */
+const COMMUTATIVE = new Set<number>([SLOP.ADD, SLOP.MUL, SLOP.DOT, SLOP.DISTANCE])
+
+/**
+ * Bumped when the hashing scheme changes, which invalidates generated shaders.
+ *
+ *   1  the Merkle hash over the reachable graph
+ *   2  normalised: commutative operands in either order, a swizzle of a constant as the constant
+ */
+export const SL_HASH_VERSION = 2
 
 /**
  * Bumped whenever the IR changes in a way a reader has to know about: a new
@@ -467,13 +723,17 @@ export const SL_HASH_VERSION = 1
  * records it again, for no gain.
  *
  * A reader accepts every version up to its own and refuses a newer one with a
- * message naming both, the rule the particle wire and fx follow. Part of the
- * hash, so a bump recompiles every cached shader.
+ * message naming both, the rule the particle wire and fx follow. A program's
+ * version is the lowest that has its nodes (`programVersion`), and that is what
+ * its hash carries, so a bump rehashes only the programs using what it added.
  *
  *   1  the first versioned IR
  *   2  an SDF call carries up to six shape parameters, not four (#129)
+ *   3  SAMPLE_LOD; an SDF's shape parameters and a noise's octave count are
+ *      operands, where they were immediates
+ *   4  control flow (if, loop, their params and projs), ints, uints and bools
  */
-export const SL_IR_VERSION = 2
+export const SL_IR_VERSION = 4
 
 function fnv1a(s: string): string {
     let h = 0x811c9dc5

package/src/lang/README.md

@@ -152,13 +152,13 @@ one the local does not have, is refused.
 
 ## Not yet spellable
 
-Three things the EDSL or the opcode table has and a file cannot say. Each is a
+Two things the EDSL or the opcode table has and a file cannot say. Each is a
 recorded gap, not an oversight, and each has its own error message rather than
 "unknown identifier".
 
 | | Why |
 |---|---|
-| `rgb2hsv`, `tex2Dlod` | The opcodes are numbered and **no backend implements them**; every emitter throws on them. |
+| `rgb2hsv` | The opcode is numbered and **no backend implements it**; every emitter throws on it. |
 | `fbm`'s simplex base | `sl.fbm(p, octaves, "simplex")` picks the base with a string, and the language has no strings. `fbm(p, octaves)` is the value base, and `turbulence` and `ridged` are the simplex family. |
 
 A `.sl` file and the EDSL are held to the same caps, `UNIFORM_SLOTS` (16) and

package/src/lang/ast.ts

@@ -11,41 +11,71 @@
  * pass over the source.
  */
 
+import type { SLKind } from "../ir"
 import type { Pos } from "./lexer"
 
-/** The four value types, under their HLSL names. `texture2D` is not one: it declares a slot. */
-export type TypeName = "float" | "float2" | "float3" | "float4"
+/** The value types, under their HLSL names. `texture2D` is not one: it declares a slot. */
+export type TypeName = "float" | "float2" | "float3" | "float4" | "int" | "uint" | "bool"
 
 export const TYPE_WIDTH: Record<TypeName, 1 | 2 | 3 | 4> = {
-    float: 1, float2: 2, float3: 3, float4: 4,
+    float: 1, float2: 2, float3: 3, float4: 4, int: 1, uint: 1, bool: 1,
+}
+
+/** What a type holds beside its width; the floats hold nothing else. */
+export const TYPE_KIND: Record<TypeName, SLKind | undefined> = {
+    float: undefined, float2: undefined, float3: undefined, float4: undefined, int: "int", uint: "uint", bool: "bool",
 }
 
 export type BinaryOp =
     | "+" | "-" | "*" | "/" | "%"
     | "<" | "<=" | ">" | ">=" | "==" | "!="
     | "&&" | "||"
+    | "&" | "|" | "^" | "<<" | ">>"
 
 export type Expr =
-    | { k: "num"; value: number; pos: Pos }
+    /**
+     * `whole` is a number written with no point and no exponent, `3` not `3.0`:
+     * a float, except beside an int, where it is an int. `unsigned` is `3u`.
+     */
+    | { k: "num"; value: number; whole: boolean; unsigned?: boolean; pos: Pos }
+    | { k: "bool"; value: boolean; pos: Pos }
     | { k: "hex"; hex: string; pos: Pos }
     | { k: "ident"; name: string; pos: Pos }
     /** A swizzle, or the shape half of `sdf.circle`. Which one is decided later. */
     | { k: "member"; obj: Expr; name: string; pos: Pos }
     | { k: "call"; callee: Expr; args: Expr[]; pos: Pos }
-    | { k: "unary"; op: "-" | "+" | "!"; arg: Expr; pos: Pos }
+    | { k: "unary"; op: "-" | "+" | "!" | "~"; arg: Expr; pos: Pos }
     | { k: "binary"; op: BinaryOp; a: Expr; b: Expr; pos: Pos }
     | { k: "cond"; cond: Expr; then: Expr; else: Expr; pos: Pos }
 
-export type AssignOp = "=" | "+=" | "-=" | "*=" | "/=" | "%="
+export type AssignOp = "=" | "+=" | "-=" | "*=" | "/=" | "%=" | "&=" | "|=" | "^=" | "<<=" | ">>="
+
+/** One `case` group of a switch: its labels, `null` for `default`, and its body without the closing break. */
+export interface SwitchCase {
+    labels: Array<Expr | null>
+    body: Stmt[]
+    /** Whether it ended in a break, which is dropped from `body`. */
+    closed: boolean
+    pos: Pos
+}
 
 export type Stmt =
     | { k: "var"; type: TypeName; name: string; init: Expr; pos: Pos }
     /** A compile time constant: usable as a value and as a `for` bound. */
     | { k: "const"; type: TypeName; name: string; init: Expr; pos: Pos }
+    /** `x++` is `x += 1`, with the 1 whole. */
     | { k: "assign"; target: Expr; op: AssignOp; value: Expr; pos: Pos }
     | { k: "if"; cond: Expr; then: Stmt[]; else: Stmt[]; pos: Pos }
-    | { k: "for"; counter: string; from: Expr; to: Expr; inclusive: boolean; step: Expr; body: Stmt[]; pos: Pos }
+    /** `for (type counter = from; cond; update)`: the update changes the counter and nothing else. */
+    | { k: "for"; type: TypeName; counter: string; from: Expr; cond: Expr; update: Extract<Stmt, { k: "assign" }>; body: Stmt[]; pos: Pos }
+    | { k: "while"; cond: Expr; body: Stmt[]; pos: Pos }
+    | { k: "break"; pos: Pos }
+    | { k: "continue"; pos: Pos }
+    /** Cases never fall through: each ends in break, return or continue, and the break is dropped here. */
+    | { k: "switch"; value: Expr; cases: SwitchCase[]; pos: Pos }
     | { k: "return"; value: Expr; pos: Pos }
+    /** `{ ... }` on its own: a body with its own scope, as a case's braces are. */
+    | { k: "block"; body: Stmt[]; pos: Pos }
 
 export interface Param {
     type: TypeName

package/src/lang/builtins.ts

@@ -125,12 +125,10 @@ value(SLOP.LUMINANCE, 1, 1, (a) => sl.luminance(colourOperand("luminance", a[0]!
 value(SLOP.NOISE, 1, 1, (a) => sl.noise(point("noise", a[0]!) as never))
 value(SLOP.SIMPLEX, 1, 1, (a) => sl.simplex(point("simplex", a[0]!) as never))
 value(SLOP.VORONOI, 1, 1, (a) => sl.voronoi(point("voronoi", a[0]!) as never))
-// The octave count is an immediate, so it has to be a number at parse time.
-// `lower.ts` folds constants before it gets here and rejects anything else with
-// a message that says why, rather than letting this cast be the error.
-value(SLOP.FBM, 1, 2, (a) => sl.fbm(point("fbm", a[0]!) as never, octaves("fbm", a[1])))
-value(SLOP.TURBULENCE, 1, 2, (a) => sl.turbulence(point("turbulence", a[0]!) as never, octaves("turbulence", a[1])))
-value(SLOP.RIDGED, 1, 2, (a) => sl.ridged(point("ridged", a[0]!) as never, octaves("ridged", a[1])))
+// The octave count is 3 when left out, and may be a value (`sl.fbm` says how).
+value(SLOP.FBM, 1, 2, (a) => sl.fbm(point("fbm", a[0]!) as never, a[1] ?? 3))
+value(SLOP.TURBULENCE, 1, 2, (a) => sl.turbulence(point("turbulence", a[0]!) as never, a[1] ?? 3))
+value(SLOP.RIDGED, 1, 2, (a) => sl.ridged(point("ridged", a[0]!) as never, a[1] ?? 3))
 
 /** Every field is sampled at a float2. */
 function point(fn: string, v: Num): Val {
@@ -138,20 +136,10 @@ function point(fn: string, v: Num): Val {
 }
 
 special(SLOP.SAMPLE, 2, 2)
+special(SLOP.SAMPLE_LOD, 3, 3)
 special(SLOP.SDF, 1, 7)
 special(SLOP.RAMP, 3, 64)
 
-function octaves(fn: string, v: Num | undefined): number {
-    if (v === undefined) return 3
-    if (typeof v !== "number") {
-        throw new SLError(
-            `${fn}'s octave count is part of the operation, so it has to be a constant. ` +
-            `A uniform or a computed value cannot change how many octaves the shader runs.`,
-        )
-    }
-    return v
-}
-
 export const BUILTINS: Readonly<Record<string, Builtin>> = table
 
 /**