onejs-sl 0.5.0 → 0.7.0

package/src/lang/lower.ts

@@ -39,8 +39,9 @@
  * `uv.mul(8)`, not as `uv.mul(sl.float(8))`, because the first broadcasts to a
  * float2 constant and the second builds a float plus a swizzle. Same picture,
  * different graph, different hash, so the distinction is load bearing rather
- * than an optimisation. An int constant is a bigint and a bool constant a
- * boolean for the same reason: folded until something needs a node.
+ * than an optimisation. An int constant is a bigint, a uint constant a `Uint`
+ * and a bool constant a boolean for the same reason: folded until something
+ * needs a node.
  *
  * A COMPARISON WAITS to be used (`Test`). Where arithmetic or a `?:` reads it,
  * it is the float that is 0 or 1 it always was, built the way it always was,
@@ -49,7 +50,7 @@
  */
 
 import {
-    controlProblem, DERIVED_INPUTS, INPUTS, RAMP_STOP_COMPUTED, truncateHeld, writtenColour,
+    controlProblem, DERIVED_INPUTS, INPUTS, PREVIOUS, RAMP_STOP_COMPUTED, STEP_INPUTS, truncateHeld, writtenColour,
     type Program, type SLKind, type SLType, type UniformControl,
 } from "../ir"
 import { SLOP } from "../ops"
@@ -80,17 +81,30 @@ class Test {
 }
 
 /**
- * A lowered value. A number is a float, a bigint an int and a boolean a bool,
- * none of which has had to become a node yet; a Test is a comparison not yet
- * either of its forms.
+ * A uint constant, 0 to 2^32 - 1, not yet a node. A bigint is already an int,
+ * so a uint needs a form of its own to fold the way an int does.
  */
-type LV = Val | number | bigint | boolean | Test
+class Uint {
+    readonly v: bigint
+    /**
+     * Any whole number, wrapped to 32 bits as a uint wraps. By a mask, not
+     * `BigInt.asUintN`, which QuickJS-ng answers with a negative from 2^31 up.
+     */
+    constructor(v: bigint) { this.v = v & 0xffffffffn }
+}
+
+/**
+ * A lowered value. A number is a float, a bigint an int, a Uint a uint and a
+ * boolean a bool, none of which has had to become a node yet; a Test is a
+ * comparison not yet either of its forms.
+ */
+type LV = Val | number | bigint | Uint | boolean | Test
 
 /** A declared type: its width, and its kind when it is not floats. */
 interface VType { width: SLType; kind: SLKind | undefined }
 
 interface Binding extends VType {
-    /** Always of the declared type: a Test is resolved and an int is a bigint or an int node. */
+    /** Always of the declared type: a Test is resolved and an int is a bigint or an int node, a uint a Uint or a uint node. */
     value: LV
 }
 
@@ -205,7 +219,7 @@ export function lower(checked: Checked, errors?: SLParseError[]): Program {
     const blank = (t: VType, pos: Pos): LV => {
         if (t.kind === "int") return 0n
         if (t.kind === "bool") return false
-        if (t.kind === "uint") return at(pos, () => sl.uint(0))
+        if (t.kind === "uint") return new Uint(0n)
         return t.width === 1 ? 0 : at(pos, () => compose(t.width, new Array<LV>(t.width).fill(0)))
     }
 
@@ -232,11 +246,11 @@ export function lower(checked: Checked, errors?: SLParseError[]): Program {
             // Read through, so a program that never names one records nothing
             // for it. The setter only serves a refused assignment, which the
             // checker has already reported and lowering carries on past.
-            for (const [name, width] of Object.entries(DERIVED_INPUTS)) {
+            for (const [name, width] of Object.entries({ ...DERIVED_INPUTS, ...STEP_INPUTS })) {
                 let value: LV | undefined
                 global.declare(name, {
                     width: width as SLType,
-                    kind: undefined,
+                    kind: name === "frame" ? "int" : undefined,
                     get value() { return value ??= (inputs as never)[name] },
                     set value(v: LV) { value = v },
                 })
@@ -275,6 +289,15 @@ export function lower(checked: Checked, errors?: SLParseError[]): Program {
             }
 
             for (const t of unit.textures) samplers.set(t.name, at(t.pos, () => sl.texture(t.name)))
+            // Unless the file declared a texture of its own by the name. The
+            // checker refuses tex2Dlod on it, and anything else that took the
+            // name, before lowering could reach either.
+            if (!samplers.has(PREVIOUS)) {
+                samplers.set(PREVIOUS, {
+                    sample: (uv) => inputs.previous.sample(uv),
+                    sampleLevel: () => { throw new Error("tex2Dlod(previous) reached lowering; the checker refuses it") },
+                })
+            }
 
             for (const c of unit.consts) {
                 const t = typeOf(c.type)
@@ -298,7 +321,7 @@ export function lower(checked: Checked, errors?: SLParseError[]): Program {
             case "float3": return sl.uniform.vec3(name, [c[0]!, c[1]!, c[2]!], control) as unknown as Val
             case "float4": return sl.uniform.vec4(name, [c[0]!, c[1]!, c[2]!, c[3]!], control) as unknown as Val
             // A float slot, as every host binds, read as the whole number it holds.
-            case "int": return sl.int(sl.uniform.float(name, c[0]!, control)) as unknown as Val
+            case "int": return sl.uniform.int(name, c[0]!, control) as unknown as Val
             case "uint":
             case "bool": throw new Error(`the checker let a ${type} uniform through`)
         }
@@ -585,7 +608,7 @@ export function lower(checked: Checked, errors?: SLParseError[]): Program {
         const got = widthOf(v)
         if (got !== t.width) {
             if (fn === main) {
-                const what = typeof v === "number" || typeof v === "bigint" ? "a single number" : `a ${widthType(got)}`
+                const what = isConstant(v) ? "a single number" : `a ${widthType(got)}`
                 fail(`main returns a float4, a colour with alpha, and this returns ${what}. Wrap it: float4(value, 1)`, pos, 6)
             }
             fail(`${fn.name} is declared to return a ${fn.ret} and returns a ${widthType(got)}`, fn.pos)
@@ -755,8 +778,8 @@ export function lower(checked: Checked, errors?: SLParseError[]): Program {
             if (c.labels.includes(null)) { otherwise = c.body; continue }
             let cond: Expr | null = null
             for (const l of c.labels as Expr[]) {
-                const k = lowerExpr(l, scope, v instanceof Val && v.kind === "uint" ? "uint" : "int")
-                const key = typeof k === "bigint" ? k : k instanceof Val ? constValue(k) : null
+                const k = lowerExpr(l, scope, kindWant(v))
+                const key = typeof k === "bigint" ? k : k instanceof Uint ? k.v : k instanceof Val ? constValue(k) : null
                 if (key === null) fail("a case label is a whole number, or a const int", l.pos)
                 if (seen.has(key)) fail(`this switch already has a case ${key}`, l.pos)
                 seen.add(key)
@@ -795,13 +818,13 @@ export function lower(checked: Checked, errors?: SLParseError[]): Program {
             }
             case "int":
                 if (isInt(v)) return v
-                if (v instanceof Val && v.kind === "uint") fail(`${name} is an int and this is a uint; convert it with int(...)`, pos)
+                if (isUint(v)) fail(`${name} is an int and this is a uint; convert it with int(...)`, pos)
                 if (isBoolish(v)) fail(`${name} is an int and this is a bool; convert it with int(...)`, pos)
                 fail(`${name} is an int and this is a ${widthType(widthOf(v))}; convert it with int(...), which truncates toward zero`, pos)
                 break
             case "uint":
-                if (v instanceof Val && v.kind === "uint") return v
-                if (typeof v === "bigint" && v >= 0n) return at(pos, () => sl.uint(Number(v)) as unknown as Val)
+                if (isUint(v)) return v
+                if (typeof v === "bigint" && v >= 0n) return new Uint(v)
                 fail(`${name} is a uint and this is ${describeLV(v)}; convert it with uint(...)`, pos)
                 break
             case "bool": {
@@ -820,6 +843,7 @@ export function lower(checked: Checked, errors?: SLParseError[]): Program {
     function toFloat(v: LV, pos: Pos): number | Val {
         if (typeof v === "number") return v
         if (typeof v === "bigint") return Number(v)
+        if (v instanceof Uint) return Number(v.v)
         if (typeof v === "boolean") return v ? 1 : 0
         if (v instanceof Test) return v.float
         return v.kind === undefined ? v : at(pos, () => sl.float(v) as unknown as Val)
@@ -839,6 +863,7 @@ export function lower(checked: Checked, errors?: SLParseError[]): Program {
         if (typeof v === "boolean") return v
         if (typeof v === "number") return v >= 0.5
         if (typeof v === "bigint") return v !== 0n
+        if (v instanceof Uint) return v.v !== 0n
         if (v instanceof Test) return v.bool
         if (v.kind === "bool") return v
         return at(pos, () => (v.kind === undefined ? v.ge(0.5) : v.ne(0)) as unknown as Val)
@@ -898,9 +923,8 @@ export function lower(checked: Checked, errors?: SLParseError[]): Program {
     function lowerExpr(e: Expr, scope: Scope, want?: "int" | "uint"): LV {
         switch (e.k) {
             case "num":
-                if (e.unsigned === true) return at(e.pos, () => sl.uint(e.value) as unknown as Val)
+                if (e.unsigned === true || (e.whole && want === "uint")) return new Uint(BigInt(e.value))
                 if (e.whole && want === "int") return BigInt.asIntN(32, BigInt(e.value))
-                if (e.whole && want === "uint") return at(e.pos, () => sl.uint(e.value) as unknown as Val)
                 return e.value
             case "bool": return e.value
             case "hex": return at(e.pos, () => sl.color(e.hex) as unknown as Val)
@@ -927,18 +951,22 @@ export function lower(checked: Checked, errors?: SLParseError[]): Program {
             case "-":
                 if (typeof v === "number") return -v
                 if (typeof v === "bigint") return BigInt.asIntN(32, -v)
+                // As the node would: a uint negated is taken as a float.
+                if (v instanceof Uint) return -Number(v.v)
                 if (v instanceof Val && v.kind !== "bool") return at(e.pos, () => v.neg())
                 return at(e.pos, () => asVal(toFloat(v, e.pos)).neg())
             case "!":
                 if (typeof v === "boolean") return !v
                 if (typeof v === "number") return 1 - v
                 if (typeof v === "bigint") return v === 0n
+                if (v instanceof Uint) return v.v === 0n
                 if (v instanceof Test) return new Test(v.width, () => oneMinus(v.float, e.pos), () => notBool(v.bool))
                 if (v.kind === "bool") return at(e.pos, () => v.not())
                 if (v.kind === undefined) return oneMinus(v, e.pos)
                 return at(e.pos, () => v.eq(0))
             case "~":
                 if (typeof v === "bigint") return BigInt.asIntN(32, ~v)
+                if (v instanceof Uint) return new Uint(~v.v)
                 if (v instanceof Val && (v.kind === "int" || v.kind === "uint")) return at(e.pos, () => v.bnot())
                 fail(`~ flips the bits of an int or a uint, and this is ${describeLV(v)}`, e.pos)
         }
@@ -978,7 +1006,11 @@ export function lower(checked: Checked, errors?: SLParseError[]): Program {
         }
         if (isUint(a) || isUint(b)) {
             if (!isIntLike(a) || !isIntLike(b)) fail(`a uint only meets another uint here; convert with uint(...) or float(...)`, pos)
-            return at(pos, () => intVal(a)[METHOD[op]](typeof b === "bigint" ? Number(b) : b as Val))
+            if (a instanceof Uint && b instanceof Uint) {
+                if ((op === "/" || op === "%") && b.v === 0n) return new Uint(0n)
+                return new Uint(INT_ARITH[op](a.v, b.v))
+            }
+            return at(pos, () => intVal(a)[METHOD[op]](other(b)))
         }
         return floatArithmetic(op, toFloat(a, pos), toFloat(b, pos), pos)
     }
@@ -1002,8 +1034,13 @@ export function lower(checked: Checked, errors?: SLParseError[]): Program {
             if (!isIntLike(v)) fail(`${op} works on the bits of an int or a uint, and this is ${describeLV(v)}${isBoolish(v) ? "; use && or ||" : ""}`, pos)
         }
         if (typeof a === "bigint" && typeof b === "bigint") return BigInt.asIntN(32, INT_BITS[op](a, b))
-        const x = intVal(a as bigint | Val)
-        const y = typeof b === "bigint" ? Number(b) : b as Val
+        // A shift's count may be either kind, and the value shifted keeps its own.
+        const shift = op === "<<" || op === ">>"
+        const count = typeof b === "bigint" ? b : b instanceof Uint ? b.v : null
+        if (a instanceof Uint && count !== null && (shift || b instanceof Uint)) return new Uint(INT_BITS[op](a.v, count))
+        if (typeof a === "bigint" && shift && b instanceof Uint) return BigInt.asIntN(32, INT_BITS[op](a, b.v))
+        const x = intVal(a as bigint | Uint | Val)
+        const y = other(b as bigint | Uint | Val)
         return at(pos, () => {
             switch (op) {
                 case "&": return x.band(y)
@@ -1025,7 +1062,8 @@ export function lower(checked: Checked, errors?: SLParseError[]): Program {
             return at(pos, () => intVal(a)[CMP_METHOD[op]!](typeof b === "bigint" ? Number(b) : b as Val) as unknown as Val)
         }
         if ((isUint(a) || isUint(b)) && isIntLike(a) && isIntLike(b)) {
-            return at(pos, () => intVal(a)[CMP_METHOD[op]!](typeof b === "bigint" ? Number(b) : b as Val) as unknown as Val)
+            if (a instanceof Uint && b instanceof Uint) return INT_CMP[op]!(a.v, b.v)
+            return at(pos, () => intVal(a)[CMP_METHOD[op]!](other(b)) as unknown as Val)
         }
         const fa = toFloat(a, pos)
         const fb = toFloat(b, pos)
@@ -1082,7 +1120,7 @@ export function lower(checked: Checked, errors?: SLParseError[]): Program {
     /** `c ? a : b`: always a select, both sides computed. A float condition is the select it always was. */
     function lowerChoice(e: Extract<Expr, { k: "cond" }>, scope: Scope, want?: "int" | "uint"): LV {
         const cond = lowerExpr(e.cond, scope)
-        if (typeof cond === "boolean" || typeof cond === "number" || typeof cond === "bigint") {
+        if (typeof cond === "boolean" || typeof cond === "number" || typeof cond === "bigint" || cond instanceof Uint) {
             return lowerExpr(boolOf(cond, e.pos) ? e.then : e.else, scope, want)
         }
         // Built before the sides, as it always was, so a program's nodes keep
@@ -1093,13 +1131,13 @@ export function lower(checked: Checked, errors?: SLParseError[]): Program {
         let f = lowerExpr(e.else, scope, want)
         if (isIntLike(t) && typeof f === "number" && wholeExpr(e.else)) f = lowerExpr(e.else, scope, kindWant(t))
         if (isIntLike(f) && typeof t === "number" && wholeExpr(e.then)) t = lowerExpr(e.then, scope, kindWant(f))
-        const kinded = [t, f].some((v) => typeof v === "bigint" || typeof v === "boolean" || (v instanceof Val && v.kind !== undefined))
+        const kinded = [t, f].some((v) => typeof v === "bigint" || v instanceof Uint || typeof v === "boolean" || (v instanceof Val && v.kind !== undefined))
         if (!kinded) {
             const c = cond instanceof Test ? cond.float : cond
             return at(e.pos, () => sl.select(c, toFloat(t, e.pos), toFloat(f, e.pos)))
         }
         const c = boolOf(cond, e.pos)
-        const side = (v: LV): Num => (typeof v === "bigint" ? sl.int(Number(v)) : typeof v === "boolean" ? sl.bool(v) : v instanceof Test ? v.float : v) as Num
+        const side = (v: LV): Num => (isIntLike(v) ? intVal(v) : typeof v === "boolean" ? sl.bool(v) : v instanceof Test ? v.float : v) as Num
         return at(e.pos, () => sl.select(c, side(t), side(f)))
     }
 
@@ -1160,7 +1198,7 @@ export function lower(checked: Checked, errors?: SLParseError[]): Program {
             // min, max, abs and clamp keep ints ints; everything else takes floats.
             if (INT_BUILTINS.has(n) && args.some(isIntLike) && args.every((v, i) => isIntLike(v) || (typeof v === "number" && wholeExpr(e.args[i]!)))) {
                 const k = kindWant(args.find(isIntLike)!)
-                args = e.args.map((a) => lowerExpr(a, scope, k)).map((v) => (typeof v === "bigint" ? sl.int(Number(v)) : v) as LV)
+                args = e.args.map((a) => lowerExpr(a, scope, k)).map((v) => (isIntLike(v) ? intVal(v) : v) as LV)
                 return at(e.pos, () => builtin.lower!(args as Num[]))
             }
             const fs = args.map((v, i) => toFloat(v, e.args[i]!.pos))
@@ -1177,17 +1215,26 @@ export function lower(checked: Checked, errors?: SLParseError[]): Program {
         const v = lowerExpr(e.args[0]!, scope, n === "bool" ? undefined : n)
         if (widthOf(v) !== 1) fail(`${n}(x) takes one component, and this is a ${widthType(widthOf(v))}; convert each one`, e.pos)
         const x = v instanceof Test ? v.bool : v
+        // Between an int and a uint the bits are kept, as the GPU keeps them.
         if (n === "int") {
             if (typeof x === "bigint") return x
+            if (x instanceof Uint) return BigInt.asIntN(32, x.v)
             if (typeof x === "number") return BigInt(truncateHeld(x, "int"))
             if (typeof x === "boolean") return x ? 1n : 0n
         }
+        if (n === "uint") {
+            if (x instanceof Uint) return x
+            if (typeof x === "bigint") return new Uint(x)
+            if (typeof x === "number") return new Uint(BigInt(truncateHeld(x, "uint")))
+            if (typeof x === "boolean") return new Uint(x ? 1n : 0n)
+        }
         if (n === "bool") {
             if (typeof x === "boolean") return x
             if (typeof x === "number") return x !== 0
             if (typeof x === "bigint") return x !== 0n
+            if (x instanceof Uint) return x.v !== 0n
         }
-        const c = typeof x === "bigint" ? Number(x) : x
+        const c = isIntLike(x) ? intVal(x) : x
         return at(e.pos, () => (n === "int" ? sl.int(c) : n === "uint" ? sl.uint(c) : sl.bool(c)) as unknown as Val)
     }
 
@@ -1238,7 +1285,7 @@ export function lower(checked: Checked, errors?: SLParseError[]): Program {
     }
 
     function compose(width: SLType, parts: LV[]): Val {
-        const ps = parts.map((p) => (p instanceof Test ? p.float : typeof p === "bigint" ? Number(p) : typeof p === "boolean" ? (p ? 1 : 0) : p)) as Num[]
+        const ps = parts.map((p) => (p instanceof Test ? p.float : typeof p === "bigint" ? Number(p) : p instanceof Uint ? Number(p.v) : typeof p === "boolean" ? (p ? 1 : 0) : p)) as Num[]
         if (width === 2) return sl.vec2(...ps) as unknown as Val
         if (width === 3) return sl.vec3(...ps) as unknown as Val
         return sl.vec4(...ps) as unknown as Val
@@ -1284,6 +1331,12 @@ const INT_BITS: Record<BitOp, (a: bigint, b: bigint) => bigint> = {
     ">>": (a, b) => a >> (b & 31n),
 }
 
+/** Comparisons of two uints, whose bigints compare as the values do. */
+const INT_CMP: Record<string, (a: bigint, b: bigint) => boolean> = {
+    "<": (a, b) => a < b, "<=": (a, b) => a <= b, ">": (a, b) => a > b,
+    ">=": (a, b) => a >= b, "==": (a, b) => a === b, "!=": (a, b) => a !== b,
+}
+
 const FOLD_CMP: Record<string, (a: number, b: number) => boolean> = {
     "<": (a, b) => a < b, "<=": (a, b) => a <= b, ">": (a, b) => a > b,
     ">=": (a, b) => a >= b, "==": (a, b) => a === b, "!=": (a, b) => a !== b,
@@ -1313,11 +1366,11 @@ function isInt(v: LV): v is bigint | Val {
     return typeof v === "bigint" || (v instanceof Val && v.kind === "int")
 }
 
-function isUint(v: LV): v is Val {
-    return v instanceof Val && v.kind === "uint"
+function isUint(v: LV): v is Uint | Val {
+    return v instanceof Uint || (v instanceof Val && v.kind === "uint")
 }
 
-function isIntLike(v: LV): v is bigint | Val {
+function isIntLike(v: LV): v is bigint | Uint | Val {
     return isInt(v) || isUint(v)
 }
 
@@ -1325,25 +1378,37 @@ function isBoolish(v: LV): boolean {
     return typeof v === "boolean" || v instanceof Test || (v instanceof Val && v.kind === "bool")
 }
 
-function isConstant(v: LV): v is number | bigint {
-    return typeof v === "number" || typeof v === "bigint"
+function isConstant(v: LV): v is number | bigint | Uint {
+    return typeof v === "number" || typeof v === "bigint" || v instanceof Uint
 }
 
-function kindWant(v: bigint | Val): "int" | "uint" {
-    return v instanceof Val && v.kind === "uint" ? "uint" : "int"
+function kindWant(v: LV): "int" | "uint" {
+    return isUint(v) ? "uint" : "int"
 }
 
 function num(v: LV): number {
-    return typeof v === "bigint" ? Number(v) : v as number
+    return typeof v === "bigint" ? Number(v) : v instanceof Uint ? Number(v.v) : v as number
 }
 
-/** An int operand as a node the EDSL's int methods take. */
-function intVal(v: bigint | Val): Val {
-    return typeof v === "bigint" ? sl.int(Number(v)) as unknown as Val : v
+/** An int or uint operand as a node the EDSL's int methods take. */
+function intVal(v: bigint | Uint | Val): Val {
+    if (typeof v === "bigint") return sl.int(Number(v)) as unknown as Val
+    if (v instanceof Uint) return sl.uint(Number(v.v)) as unknown as Val
+    return v
+}
+
+/**
+ * The second operand of an int method: an int constant as a number, which
+ * takes the first operand's kind, and a uint one as a node, so an int meeting
+ * it is refused rather than made a uint.
+ */
+function other(v: bigint | Uint | Val): number | Val {
+    return typeof v === "bigint" ? Number(v) : intVal(v)
 }
 
 function asVal(v: LV): Val {
     if (v instanceof Val) return v
+    if (v instanceof Uint) return intVal(v)
     return sl.float(typeof v === "number" ? v : num(v)) as unknown as Val
 }
 
@@ -1366,6 +1431,7 @@ function article(t: VType): string {
 
 function describeLV(v: LV): string {
     if (typeof v === "bigint") return "an int"
+    if (v instanceof Uint) return "a uint"
     if (typeof v === "boolean" || v instanceof Test) return "a bool"
     if (typeof v === "number") return "a float"
     return v.kind === undefined ? `a ${widthType(v.width)}` : v.kind === "int" ? "an int" : `a ${v.kind}`
@@ -1380,6 +1446,7 @@ function constValue(v: Val): bigint | null {
 /** Two lowered values that are certainly the same, so a join can leave them out. */
 function same(a: LV, b: LV): boolean {
     if (a === b) return true
+    if (a instanceof Uint && b instanceof Uint) return a.v === b.v
     return a instanceof Val && b instanceof Val && a.ref === b.ref && a.width === b.width && a.kind === b.kind
 }
 

package/src/lang/parser.ts

@@ -636,7 +636,7 @@ function zeroOf(type: TypeName, at: Pos): Expr {
  * inside braces that are the case's last statement, as in `case 0: { ...; break; }`.
  */
 function dropClosingBreak(body: Stmt[]): boolean {
-    const last = body.at(-1)
+    const last = body[body.length - 1]
     if (last?.k === "break") {
         body.pop()
         return true

package/src/ops.ts

@@ -39,7 +39,7 @@ export const TEXTURE_SLOTS = 4
 
 /** Input ids, which the web emitter switches on. */
 export const INPUT_ID: Record<string, number> = {
-    uv: 0, fragCoord: 1, resolution: 2, time: 3, aspect: 4,
+    uv: 0, fragCoord: 1, resolution: 2, time: 3, aspect: 4, frame: 5, deltaTime: 6,
 }
 
 export const SLOP = {
@@ -146,6 +146,9 @@ export const SLOP = {
     // Sampling
     SAMPLE: 144,
     SAMPLE_LOD: 145,
+    // What this program drew the frame before, at a uv (IR 5). No slot: the
+    // host keeps it, and a program that never reads it has none.
+    SAMPLE_PREVIOUS: 146,
 } as const
 
 export type SLOpCode = (typeof SLOP)[keyof typeof SLOP]
@@ -187,7 +190,7 @@ export const SL_ARITY: Record<number, number> = {
     [SLOP.NOISE]: 1, [SLOP.SIMPLEX]: 1, [SLOP.FBM]: -1, [SLOP.SDF]: -1,
     [SLOP.VORONOI]: 1, [SLOP.TURBULENCE]: -1, [SLOP.RIDGED]: -1,
 
-    [SLOP.SAMPLE]: 1, [SLOP.SAMPLE_LOD]: 2,
+    [SLOP.SAMPLE]: 1, [SLOP.SAMPLE_LOD]: 2, [SLOP.SAMPLE_PREVIOUS]: 1,
 }
 
 /** Name per opcode, for error messages and for the HLSL emitter's comments. */
@@ -230,7 +233,7 @@ export interface SLSurface {
 
 export const SL_HLSL: Record<number, SLSurface> = {
     [SLOP.CONST]: { syntax: "a number literal" },
-    [SLOP.INPUT]: { syntax: "uv, fragCoord, resolution, time, aspect" },
+    [SLOP.INPUT]: { syntax: "uv, fragCoord, resolution, time, aspect, frame, deltaTime" },
     [SLOP.UNIFORM]: { syntax: "uniform <type> name = <default>;" },
     [SLOP.COMPOSE]: { syntax: "float2(), float3(), float4()" },
     [SLOP.SWIZZLE]: { syntax: ".xyzw / .rgba" },
@@ -312,6 +315,7 @@ export const SL_HLSL: Record<number, SLSurface> = {
 
     [SLOP.SAMPLE]: { call: "tex2D" },
     [SLOP.SAMPLE_LOD]: { call: "tex2Dlod" },
+    [SLOP.SAMPLE_PREVIOUS]: { syntax: "tex2D(previous, uv)" },
 }
 
 /**

package/src/params.ts

@@ -20,7 +20,7 @@ import { BUILTINS } from "./lang/builtins"
 import { LIB_FUNCTIONS, SDF_CALLS } from "./lib/table"
 import { LIB_PARAM_NAMES } from "./lib/names"
 import { SL_SDF_PARAMS, SL_SDF_SHAPES, type SlSdfKind } from "./shapes"
-import type { SourceInputName } from "./ir"
+import type { PREVIOUS, SourceInputName } from "./ir"
 import type { AttributeName } from "./lang/attributes"
 
 /** One function of the helper library, as its source declares it. */
@@ -186,12 +186,15 @@ export const ATTRIBUTE_DOCS: Readonly<Record<AttributeName, string>> = {
  * the output is a UI element in OneJS and an image on a Magerie board, and the
  * clock is whichever one the host runs.
  */
-export const INPUT_DOCS: Readonly<Record<SourceInputName, string>> = {
+export const INPUT_DOCS: Readonly<Record<SourceInputName | typeof PREVIOUS, string>> = {
     uv: "The centre of this pixel in the output, 0 to 1 on each axis, with y up.",
     fragCoord: "The centre of this pixel in the output, in pixels, with y up: the first column is at 0.5.",
     resolution: "The output's size in pixels.",
     time: "The clock, in seconds.",
     aspect: "The output's width divided by its height.",
+    frame: "Frames drawn since previous was last cleared, from 0: an int, 0 exactly when previous is clear.",
+    deltaTime: "Seconds since the frame before; 0 when a frame redraws the same time.",
+    previous: "What this program drew the frame before, as a texture: tex2D(previous, uv). Clear on the first.",
     texel: "One pixel, in uv: 1 / resolution. Step by it to read a neighbouring pixel.",
     centered: "uv with 0 at the centre and x scaled by aspect, so a circle drawn in it stays round.",
 }

package/src/serial.ts

@@ -9,11 +9,13 @@
  * older one is migrated to this one and rehashed under it.
  */
 import {
-    INPUTS, SLError, SL_HASH_VERSION, SL_IR_VERSION, TYPE, checkCaps, controlOf, controlProblem, formProblem, hashProgram,
-    programVersion, type NodeRef, type Program, type SLNode, type SLType, type TextureDecl, type UniformDecl,
+    INPUTS, STEP_INPUTS, SLError, SL_HASH_VERSION, SL_IR_VERSION, TYPE, checkCaps, controlOf, controlProblem, formProblem, hashProgram, intUniformProblem,
+    programVersion, type HostInputName, type NodeRef, type Program, type SLNode, type SLType, type TextureDecl, type UniformDecl,
 } from "./ir"
 import { SLOP, SL_ARITY, SL_NAME } from "./ops"
 
+const HOST_INPUTS: Readonly<Record<HostInputName, SLType>> = { ...INPUTS, ...STEP_INPUTS }
+
 export interface ProgramJSON {
     /** `SL_IR_VERSION` of the writer. Absent means 1. */
     v: number
@@ -166,8 +168,10 @@ function node(n: unknown, i: number): SLNode {
             return withKind({ k: "const", type: t, v })
         }
         case "input": {
-            const name = x.name as keyof typeof INPUTS
-            if (!(name in INPUTS) || INPUTS[name] !== t) fail(`node ${i} reads an input "${String(x.name)}" that does not exist at that width`)
+            const name = x.name as HostInputName
+            if (!Object.prototype.hasOwnProperty.call(HOST_INPUTS, name) || HOST_INPUTS[name] !== t) {
+                fail(`node ${i} reads an input "${String(x.name)}" that does not exist at that width`)
+            }
             return { k: "input", type: t, name }
         }
         case "uniform": {
@@ -209,6 +213,12 @@ function uniform(u: unknown, i: number): UniformDecl {
     }
     const out: UniformDecl = { name: x.name!, type: x.type as SLType, value: x.value!.slice() }
     if (x.colour === true) out.colour = true
+    if (x.kind !== undefined) {
+        if (x.kind !== "int") fail(`uniform ${i} holds a "${String(x.kind)}"; a uniform is a float or an int`)
+        const problem = intUniformProblem(out.type, out.value)
+        if (problem !== null) fail(`uniform ${i}: ${problem}`)
+        out.kind = "int"
+    }
     // Its control: shapes checked here, sense checked by the one check the
     // compiler uses, so a hand edited file cannot give a host a range it would
     // choke on.

package/src/sl.ts

@@ -24,8 +24,8 @@
 
 import { parseColor as parseHex } from "./color"
 import {
-    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,
+    Builder, INPUTS, RAMP_STOP_COMPUTED, STEP_INPUTS, SLError, TYPE, hashProgram, programVersion, truncateHeld, widthName, writtenColour,
+    type HostInputName, type InputName, type NodeRef, type Program, type SLKind, type SLNode, type SLType, type UniformControl,
 } from "./ir"
 import { SLOP, SL_HLSL, SL_NAME, type SLOpCode } from "./ops"
 import { SL_SDF_PARAMS, SL_SDF_SHAPES, type SlSdfKind } from "./shapes"
@@ -497,6 +497,26 @@ export interface ProgramInputs {
     texel: Vec2
     /** `(uv - 0.5) * vec2(aspect, 1)`: 0 at the centre, and a circle stays round. Recorded only if read. */
     centered: Vec2
+    /**
+     * Frames drawn since `previous` was last cleared, from 0: so `frame` is 0
+     * exactly when `previous` is clear. Recorded only if read, and the host
+     * counts frames only for a program that reads it (`compile(p).reads`).
+     */
+    frame: Int
+    /** Seconds from the frame before to this one; 0 when a frame redraws the same time. Recorded only if read. */
+    deltaTime: Float
+    /**
+     * What this program drew the frame before: transparent black on the first
+     * frame and after anything that clears it (a new size, a seek, time going
+     * back). Linear and straight alpha, as `main` returned it, bilinear and
+     * clamped at the edges. A host keeps it only for a program that samples it.
+     */
+    previous: PreviousFrame
+}
+
+/** The frame a program drew before this one. It has one level, so there is no `sampleLevel`. */
+export interface PreviousFrame {
+    sample(uv: Vec2): Vec4
 }
 
 /**
@@ -515,11 +535,25 @@ export function program(fn: (inputs: ProgramInputs) => Vec4): Program {
             ;(inputs as any)[name] = mk(b, ref, width as SLType)
         }
         // Getters, so a program that never reads one records nothing for it
-        // (DERIVED_INPUTS in ir.ts). A second read is hash consed to the first.
+        // (DERIVED_INPUTS and STEP_INPUTS in ir.ts). A second read is hash
+        // consed to the first.
+        const step = (name: keyof typeof STEP_INPUTS): Val =>
+            mk(b, b.add({ k: "input", type: STEP_INPUTS[name], name: name as HostInputName }), STEP_INPUTS[name])
         Object.defineProperties(inputs, {
             texel: { enumerable: true, get: () => vec2(1, 1).div(inputs.resolution) },
             centered: { enumerable: true, get: () => inputs.uv.sub(0.5).mul(vec2(inputs.aspect, 1)) },
+            // The host hands the count over as a float, which holds it exactly
+            // for as long as anything will run.
+            frame: { enumerable: true, get: () => convert(step("frame"), "int") },
+            deltaTime: { enumerable: true, get: () => step("deltaTime") },
         })
+        inputs.previous = {
+            sample(uv: Vec2): Vec4 {
+                if (uv.owner !== b) throw new SLError("a value from another program cannot be used in this one")
+                if (uv.width !== TYPE.VEC2 || uv.kind !== undefined) throw new SLError(`the previous frame is read at a float2, and this is ${uv.kind === undefined ? `a ${widthName(uv.width)}` : `an ${uv.kind}`}`)
+                return mk(b, b.call(SLOP.SAMPLE_PREVIOUS, TYPE.VEC4, [uv.ref]), TYPE.VEC4)
+            },
+        }
         const out = fn(inputs)
         if (!(out instanceof Val)) throw new SLError("a program must return an sl value, not " + typeof out)
         if (out.width !== TYPE.VEC4) {
@@ -956,6 +990,15 @@ export const uniform = {
         const b = ctx()
         return mk(b, b.uniform(name, TYPE.FLOAT, [value], false, control), TYPE.FLOAT)
     },
+    /**
+     * An int, read as the whole number it holds. Its slot is a float, as every
+     * host binds one; the declaration says `kind: "int"`, so a host shows a
+     * whole number field for it.
+     */
+    int(name: string, value = 0, control: UniformControl = {}): Int {
+        const b = ctx()
+        return int(mk(b, b.uniform(name, TYPE.FLOAT, [value], false, control, "int"), TYPE.FLOAT) as Float)
+    },
     vec2(name: string, value: [number, number] = [0, 0], control: UniformControl = {}): Vec2 {
         const b = ctx()
         return mk(b, b.uniform(name, TYPE.VEC2, value, false, control), TYPE.VEC2)

package/src/structure.ts

@@ -16,7 +16,7 @@
  */
 
 import { INPUTS, operands, reachable, type NodeRef, type Program, type SLNode } from "./ir"
-import { SLOP } from "./ops"
+import { isSampling } from "./ops"
 
 export interface Region {
     id: number
@@ -171,7 +171,7 @@ function varyingValues(nodes: readonly SLNode[], reach: NodeRef[]): Set<NodeRef>
             switch (n.k) {
                 case "input": if (PER_PIXEL.has(n.name)) mark(ref); break
                 case "call":
-                    if (n.op === SLOP.SAMPLE || n.op === SLOP.SAMPLE_LOD || n.args.some((a) => out.has(a))) mark(ref)
+                    if (isSampling(n.op) || n.args.some((a) => out.has(a))) mark(ref)
                     break
                 case "swizzle": if (out.has(n.src)) mark(ref); break
                 case "proj": {

package/src/tables.ts

@@ -13,8 +13,8 @@ export {
     SLOP, SL_ARITY, SL_NAME, SL_HLSL, SL_CALL_NAMES, SL_GLSL_HINT, SL_UNIMPLEMENTED,
 } from "./ops"
 export type { SLSurface } from "./ops"
-export { DERIVED_INPUTS, INPUTS, SOURCE_INPUTS } from "./ir"
-export type { DerivedInputName, InputName, SourceInputName } from "./ir"
+export { DERIVED_INPUTS, INPUTS, PREVIOUS, SOURCE_INPUTS, STEP_INPUTS } from "./ir"
+export type { DerivedInputName, HostInputName, InputName, SourceInputName, StepInputName } from "./ir"
 export { SL_SDF_SHAPES, SL_SDF_PARAMS } from "./shapes"
 export { ATTRIBUTE_DOCS, BUILTIN_DOCS, BUILTIN_PARAMS, INPUT_DOCS, LIB_SIGNATURES, SL_SDF_PARAM_NAMES } from "./params"
 export { ATTRIBUTE_NAMES } from "./lang/attributes"