onejs-sl 0.4.0 → 0.6.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
@@ -162,6 +225,27 @@ export interface UniformDecl extends UniformControl {
      * conversion is already in the graph, so it is not part of the hash.
      */
     colour?: true
+    /**
+     * An int: `value` is a whole number and the program reads it as one, so a
+     * host shows a whole number field rather than a float's. The slot is a
+     * float, as every host binds it, and `type` is FLOAT. Set by `uniform int`
+     * in a `.sl` file or `sl.uniform.int`. Metadata for a host like `colour`:
+     * the reads' conversion to an int is already in the graph, so it is not
+     * part of the hash. A float uniform has none.
+     */
+    kind?: "int"
+}
+
+/** What is wrong with an int uniform of `type` and default `value`, or null. The one check, for the builder and `fromJSON`. */
+export function intUniformProblem(type: SLType, value: readonly number[]): string | null {
+    if (type !== TYPE.FLOAT) return `an int uniform is one number, and this is a ${widthName(type)}`
+    const v = value[0]!
+    // Its slot is a float, and a read is held to INT_BOUNDS: a default the
+    // program would read as another number is refused rather than shown.
+    if (!Number.isInteger(v) || Math.fround(v) !== v || v < INT_BOUNDS.int[0] || v > INT_BOUNDS.int[1]) {
+        return `an int uniform's default is a whole number its float slot holds exactly, and this is ${v}`
+    }
+    return null
 }
 
 export interface TextureDecl {
@@ -254,6 +338,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`)
@@ -266,7 +354,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}`)
@@ -276,17 +364,22 @@ 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 {
+    uniform(name: string, type: SLType, value: number[], colour = false, control: UniformControl = {}, kind?: "int"): NodeRef {
         const existing = this.uniforms.findIndex((u) => u.name === name)
         if (existing >= 0) {
             const u = this.uniforms[existing]
@@ -296,6 +389,9 @@ export class Builder {
             if ((u.colour === true) !== colour) {
                 throw new SLError(`uniform "${name}" is declared both as a colour and as plain numbers`)
             }
+            if (u.kind !== kind) {
+                throw new SLError(`uniform "${name}" is declared as both an int and a float`)
+            }
             // A second read may say nothing about the control, or the same thing again.
             const merged = { ...controlOf(u) }
             for (const f of CONTROL_FIELDS) {
@@ -312,10 +408,13 @@ export class Builder {
         }
         const problem = controlProblem(type, value, control)
         if (problem !== null) throw new SLError(`uniform "${name}": ${problem.message}`)
+        const kindProblem = kind === undefined ? null : intUniformProblem(type, value)
+        if (kindProblem !== null) throw new SLError(`uniform "${name}": ${kindProblem}`)
         const slot = this.uniforms.length
         if (slot >= UNIFORM_SLOTS) throw new SLError(tooManyUniforms(slot + 1, "program"))
         const decl: UniformDecl = { name, type, value: value.slice() }
         if (colour) decl.colour = true
+        if (kind !== undefined) decl.kind = kind
         Object.assign(decl, controlOf(control))
         this.uniforms.push(decl)
         return this.add({ k: "uniform", type, slot })
@@ -348,9 +447,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)
@@ -372,12 +469,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(",")}`
     }
 }
 
@@ -390,6 +492,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}`
 }
@@ -431,14 +538,33 @@ export function hashProgram(nodes: SLNode[], result: NodeRef, uniforms: UniformD
     // 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
@@ -447,8 +573,8 @@ export function hashProgram(nodes: SLNode[], result: NodeRef, uniforms: UniformD
             case "uniform": body = `u:${n.slot}:${n.type}`; break
             case "swizzle": {
                 const src = nodes[n.src]!
-                body = src.k === "const"
-                    ? `c:${n.type}:${n.chans.map((c) => fixed(src.v[c]!)).join(",")}`
+                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
             }
@@ -459,7 +585,7 @@ export function hashProgram(nodes: SLNode[], result: NodeRef, uniforms: UniformD
                 break
             }
         }
-        const d = fnv1a(body + "|" + n.type)
+        const d = fnv1a(body + "|" + n.type + (n.kind === undefined ? "" : n.kind))
         digest.set(ref, d)
         return d
     }
@@ -473,12 +599,44 @@ export function hashProgram(nodes: SLNode[], result: NodeRef, uniforms: UniformD
     // 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)}`, of(result)]
+    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 = {}
@@ -500,20 +658,32 @@ export function controlOf(c: UniformControl): UniformControl {
  * 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[]): number {
+export function programVersion(nodes: readonly SLNode[], result: NodeRef): number {
     let v = 2
-    for (const n of nodes) v = Math.max(v, nodeVersion(n))
+    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:
@@ -537,7 +707,7 @@ function nodeVersion(n: SLNode): number {
  *        one immediate
  */
 export function formProblem(n: Extract<SLNode, { k: "call" }>, nodes: readonly SLNode[]): string | null {
-    const widths = n.args.map((a) => nodes[a]!.type).join(",")
+    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
@@ -588,8 +758,9 @@ export const SL_HASH_VERSION = 2
  *   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 = 3
+export const SL_IR_VERSION = 4
 
 function fnv1a(s: string): string {
     let h = 0x811c9dc5

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