onejs-sl 0.6.0 → 0.7.0

package/src/core.ts

@@ -8,13 +8,13 @@
  * game never executes.
  */
 export * as sl from "./sl"
-export type { Float, Vec2, Vec3, Vec4, Num, ProgramInputs, Texture } from "./sl"
+export type { Float, Vec2, Vec3, Vec4, Num, ProgramInputs, PreviousFrame, Texture } from "./sl"
 export {
-    TYPE, INPUTS, MAX_NODES, SLError, hashProgram, widthName, SL_IR_VERSION, SL_HASH_VERSION, inputsUsed,
-    CONTROL_FIELDS, controlProblem,
+    TYPE, INPUTS, STEP_INPUTS, PREVIOUS, MAX_NODES, SLError, hashProgram, widthName, SL_IR_VERSION, SL_HASH_VERSION,
+    inputsUsed, readsOf, CONTROL_FIELDS, controlProblem,
 } from "./ir"
 export type {
-    SLType, InputName, NodeRef, SLNode, Program, UniformDecl, UniformControl, TextureDecl,
+    SLType, InputName, StepInputName, HostInputName, SLReads, NodeRef, SLNode, Program, UniformDecl, UniformControl, TextureDecl,
 } from "./ir"
 export { SLOP, SL_ARITY, SL_NAME, INPUT_ID, isSampling, UNIFORM_SLOTS, TEXTURE_SLOTS } from "./ops"
 export type { SLOpCode } from "./ops"

package/src/hlsl.ts

@@ -15,7 +15,7 @@
  * next time it is generated.
  */
 
-import { SLError, SL_HASH_VERSION, type Program } from "./ir"
+import { SLError, SL_HASH_VERSION, readsOf, type Program } from "./ir"
 import { emitBody, lit, type BodyTarget } from "./body"
 
 /** The property name a uniform gets. Prefixed so it cannot collide with ours. */
@@ -48,6 +48,7 @@ export function emitShader(p: Program, options: EmitOptions = {}): string {
     const name = options.name ?? `Hidden/SLGenerated/${p.hash}`
     const include = options.include ?? "SLCommon.cginc"
     const body = emitFragmentBody(p)
+    const reads = readsOf(p)
 
     const props: string[] = [
         `        _Secs ("Seconds", Float) = 0`,
@@ -69,6 +70,16 @@ export function emitShader(p: Program, options: EmitOptions = {}): string {
         props.push(`        _Tex${t.slot} ("${t.name}", 2D) = "white" {}`)
         decls.push(`            sampler2D _Tex${t.slot};`)
     }
+    // Only for a program that samples it, so every other program's shader is
+    // the text it always was. Transparent black is the previous frame's clear
+    // value, so a host that binds nothing draws the first frame.
+    if (reads.previous) {
+        props.push(`        _Prev ("Previous frame", 2D) = "black" {}`)
+        decls.push(`            sampler2D _Prev;`)
+    }
+    // What the program returns is the next frame's previous, kept at 16 bits
+    // a channel, so it leaves at full precision rather than as a fixed4.
+    const out = reads.previous ? "float4" : "fixed4"
 
     return `// GENERATED from a shader language program. Do not edit.
 //
@@ -112,7 +123,7 @@ ${decls.join("\n")}
                 return o;
             }
 
-            fixed4 frag(v2f i) : SV_Target
+            ${out} frag(v2f i) : SV_Target
             {
 ${body}
             }
@@ -125,7 +136,9 @@ ${body}
 
 /**
  * The frame's side of the body: OneJS's names for the inputs, a uniform's
- * material property, and `tex2D` and `tex2Dlod` on the slot's sampler. `sl_toLinear` stays a
+ * material property, and `tex2D` and `tex2Dlod` on the slot's sampler. The
+ * host puts the frame count and the step in `_Res`'s spare zw, and binds the
+ * previous frame as `_Prev`. `sl_toLinear` stays a
  * call because `SLCommon.cginc` decides Gamma or Linear per project, at the
  * shader compile, so this target always emits it.
  */
@@ -147,10 +160,15 @@ function unityTarget(p: Program): BodyTarget {
             resolution: "_Res.xy",
             time: "_Secs",
             aspect: "(_Res.x / max(_Res.y, 1.0))",
+            frame: "_Res.z",
+            deltaTime: "_Res.w",
         },
         uniform: (slot) => uniformProperty(p.uniforms[slot]!.name),
         sample: (slot, uv) => `tex2D(_Tex${slot}, ${uv})`,
         sampleLevel: (slot, uv, lod) => `tex2Dlod(_Tex${slot}, float4(${uv}, 0.0, ${lod}))`,
+        // Flipped as this frame flipped the uv it wrote at, so a read at a
+        // pixel's own uv is that pixel whichever way the host's target runs.
+        previous: (uv) => `tex2Dlod(_Prev, float4(${uv} * float2(1.0, 1.0 - 2.0 * _FlipY) + float2(0.0, _FlipY), 0.0, 0.0))`,
         colour: "linear",
         indent: "                ",
         loopAttribute: "[loop]",

package/src/ir.ts

@@ -57,9 +57,35 @@ export const DERIVED_INPUTS = {
 } as const
 export type DerivedInputName = keyof typeof DERIVED_INPUTS
 
+/**
+ * Inputs the host hands over only to a program that reads one (IR 5,
+ * `Specs/SL_NEXT.md` 4). They are not recorded up front as `INPUTS` are, so a
+ * program that never names one holds no node for it and keeps its IR version,
+ * its hash and its bytes. `compile(p).reads` says which a program reads.
+ *
+ *   frame      frames drawn since the previous frame was last cleared, from 0.
+ *              An int in the language; the host hands over a float holding it
+ *              exactly, and the program converts
+ *   deltaTime  seconds from the frame before to this one; 0 on a frame that
+ *              redraws the same time
+ *
+ * The previous frame itself is SLOP.SAMPLE_PREVIOUS, an op rather than an input.
+ */
+export const STEP_INPUTS = {
+    frame: TYPE.FLOAT,
+    deltaTime: TYPE.FLOAT,
+} as const
+export type StepInputName = keyof typeof STEP_INPUTS
+
+/** The name `.sl` reads the previous frame by, as a texture: `tex2D(previous, uv)`. */
+export const PREVIOUS = "previous"
+
+/** Every input a host hands over: the ones every program has, then the ones a program asks for. */
+export type HostInputName = InputName | StepInputName
+
 /** Every input a program can name: the host's, then the derived ones. */
-export type SourceInputName = InputName | DerivedInputName
-export const SOURCE_INPUTS: Readonly<Record<SourceInputName, SLType>> = { ...INPUTS, ...DERIVED_INPUTS }
+export type SourceInputName = HostInputName | DerivedInputName
+export const SOURCE_INPUTS: Readonly<Record<SourceInputName, SLType>> = { ...INPUTS, ...STEP_INPUTS, ...DERIVED_INPUTS }
 
 /** Index into `Program.nodes`. Always refers backwards. */
 export type NodeRef = number
@@ -77,7 +103,7 @@ export type SLKind = "int" | "uint" | "bool"
  */
 export type ValueNode =
     | { k: "const"; type: SLType; kind?: SLKind; v: number[] }
-    | { k: "input"; type: SLType; kind?: undefined; name: InputName }
+    | { k: "input"; type: SLType; kind?: undefined; name: HostInputName }
     | { 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[] }
@@ -454,17 +480,43 @@ export function reachable(nodes: SLNode[], result: NodeRef): NodeRef[] {
 }
 
 /**
- * The inputs a program reads, in `INPUTS` order. Dead nodes do not count: a
- * value computed and never used is not in the picture, so a program that does
- * that with `time` is still not animated.
+ * The inputs a program reads, in `INPUTS` order and then `STEP_INPUTS` order.
+ * Dead nodes do not count: a value computed and never used is not in the
+ * picture, so a program that does that with `time` is still not animated.
  */
-export function inputsUsed(p: Program): InputName[] {
-    const read = new Set<InputName>()
+export function inputsUsed(p: Program): HostInputName[] {
+    const read = new Set<HostInputName>()
     for (const ref of reachable(p.nodes, p.result)) {
         const n = p.nodes[ref]
         if (n.k === "input") read.add(n.name)
     }
-    return (Object.keys(INPUTS) as InputName[]).filter((name) => read.has(name))
+    return ([...Object.keys(INPUTS), ...Object.keys(STEP_INPUTS)] as HostInputName[]).filter((name) => read.has(name))
+}
+
+/**
+ * What a program needs its host to keep from one frame to the next
+ * (`Specs/SL_NEXT.md` 4). A host that draws a program reading any of these
+ * has to hand it over, or refuse the program: nothing here has a value that
+ * would pass for right.
+ *
+ *   previous   the host keeps what the program drew last and binds it
+ *   frame      frames drawn since `previous` was last cleared
+ *   deltaTime  seconds since the frame before
+ */
+export interface SLReads {
+    previous: boolean
+    frame: boolean
+    deltaTime: boolean
+}
+
+export function readsOf(p: Program): SLReads {
+    const out: SLReads = { previous: false, frame: false, deltaTime: false }
+    for (const ref of reachable(p.nodes, p.result)) {
+        const n = p.nodes[ref]!
+        if (n.k === "call" && n.op === SLOP.SAMPLE_PREVIOUS) out.previous = true
+        else if (n.k === "input" && n.name in STEP_INPUTS) out[n.name as StepInputName] = true
+    }
+    return out
 }
 
 /** Structural key for hash consing. Order matters and is fixed by the node shape. */
@@ -681,10 +733,12 @@ const IR4_OPS = new Set<number>([
  * holds, and `fromJSON` moves it to the form IR 3 has.
  */
 function nodeVersion(n: SLNode): number {
+    if (n.k === "input" && n.name in STEP_INPUTS) return 5
     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_PREVIOUS: return 5
         case SLOP.SAMPLE_LOD: return 3
         case SLOP.SDF:
         case SLOP.FBM:
@@ -705,6 +759,8 @@ function nodeVersion(n: SLNode): number {
  *        the shape id the one immediate
  *   FBM, TURBULENCE, RIDGED  the point and the octave count, FBM's kind the
  *        one immediate
+ *   SAMPLE_PREVIOUS  a float4 at a float2, and no immediates: there is one
+ *        previous frame, so there is no slot to name
  */
 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(",")
@@ -719,6 +775,9 @@ export function formProblem(n: Extract<SLNode, { k: "call" }>, nodes: readonly S
             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`
         }
+        case SLOP.SAMPLE_PREVIOUS:
+            if (widths === "2" && n.type === 4 && n.kind === undefined && (n.imm?.length ?? 0) === 0) return null
+            return "the previous frame is a float4 read at a float2"
         default:
             return null
     }
@@ -759,8 +818,9 @@ export const SL_HASH_VERSION = 2
  *   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
+ *   5  the previous frame (SAMPLE_PREVIOUS), and the frame and deltaTime inputs
  */
-export const SL_IR_VERSION = 4
+export const SL_IR_VERSION = 5
 
 function fnv1a(s: string): string {
     let h = 0x811c9dc5

package/src/lang/README.md

@@ -245,7 +245,8 @@ It rewrites tokens and keeps everything else: comments, layout and names stay
 where they were, so the result reads as the shader it came from. What it does:
 
 - The spellings that mean the same (`vec3`, `mix`, `fract`, `texture`,
-  `iTime`, `gl_FragCoord`) become the HLSL ones. So do the calls that need an
+  `iTime`, `iFrame`, `iTimeDelta`, `gl_FragCoord`) become the HLSL ones and
+  the inputs. So do the calls that need an
   expression: `mod` floors (`a - b * floor(a / b)`, never `%`, which
   truncates), and `atan`, `inversesqrt`, `radians`, `degrees`, `exp2` and
   `log2` become what they compute.
@@ -269,8 +270,8 @@ where they were, so the result reads as the shader it came from. What it does:
   becomes a const; any other directive is kept as a comment, with a note.
 - A name the language already means something by gets a `_` suffix, and an
   `int` becomes a float (a for-loop counter stays an int), each with a note.
-- What has no counterpart (`iFrame`, `textureLod`, `dFdx`, a function returning
-  nothing) is left in place with a note, for `errors` to point at.
+- What has no counterpart (`iFrameRate`, `texelFetch`, `dFdx`, a function
+  returning nothing) is left in place with a note, for `errors` to point at.
 
 It is not a GLSL parser, and is not meant to be: a shader it cannot follow comes
 out with errors on the lines to look at, which is where a person pasting one

package/src/lang/check.ts

@@ -28,7 +28,7 @@
  * is refused with the reason.
  */
 
-import { DERIVED_INPUTS, INPUTS, tooManyTextures, tooManyUniforms } from "../ir"
+import { DERIVED_INPUTS, INPUTS, PREVIOUS, STEP_INPUTS, tooManyTextures, tooManyUniforms } from "../ir"
 import { TEXTURE_SLOTS, UNIFORM_SLOTS } from "../ops"
 import { SL_GLSL_HINT } from "../ops"
 import { BUILTINS, NOT_YET } from "./builtins"
@@ -44,6 +44,17 @@ const INPUT_NAMES = new Set(Object.keys(INPUTS))
  * long before the language had one, and that must keep compiling.
  */
 const DERIVED_NAMES = new Set(Object.keys(DERIVED_INPUTS))
+/**
+ * `frame` and `deltaTime`, and `previous`, the texture that is the frame drawn
+ * before (IR 5). The language had none of them before 0.7.0, so a program may
+ * already use the name for its own value, texture or function, and keeps it.
+ * A function by the name is called by it; the bare name is still the input.
+ */
+const STEP_NAMES = new Set(Object.keys(STEP_INPUTS))
+/** What a declaration may take the name of, with the words for it. */
+const SHADOWABLE = new Set(["a builtin", "a derived input", "a built in input", "the previous frame"])
+/** What a function may take the name of: only the names that came after files could have used them. */
+const FUNCTION_MAY_TAKE = new Set(["a built in input", "the previous frame"])
 
 /**
  * The GLSL spellings whose HLSL name means the same wherever it is written, so
@@ -145,13 +156,15 @@ export function check(unit: Unit, prelude: FuncDecl[], options: CheckOptions = {
         if (textures.has(n)) return "a texture"
         if (consts.has(n)) return "a const"
         if (DERIVED_NAMES.has(n)) return "a derived input"
+        if (STEP_NAMES.has(n)) return "a built in input"
+        if (n === PREVIOUS) return "the previous frame"
         return null
     }
 
     /** What a value may not be called: anything spoken for, except a builtin's or a prelude function's name. */
     const valueClash = (n: string): string | null => {
         const why = taken(n)
-        if (why !== null && why !== "a builtin" && why !== "a derived input") return why
+        if (why !== null && !SHADOWABLE.has(why)) return why
         const fn = funcs.get(n)
         return fn !== undefined && !fn.prelude ? "a function" : null
     }
@@ -194,7 +207,7 @@ export function check(unit: Unit, prelude: FuncDecl[], options: CheckOptions = {
     for (const fn of unit.funcs) {
         attempt(() => {
             const clash = taken(fn.name)
-            if (clash !== null) fail(`"${fn.name}" already names ${clash}`, fn.pos, fn.name.length)
+            if (clash !== null && !FUNCTION_MAY_TAKE.has(clash)) fail(`"${fn.name}" already names ${clash}`, fn.pos, fn.name.length)
             if (unit.funcs.filter((f) => f.name === fn.name).length > 1) {
                 fail(
                     `this file declares ${fn.name} more than once. There is no overloading: a function ` +
@@ -222,7 +235,8 @@ export function check(unit: Unit, prelude: FuncDecl[], options: CheckOptions = {
         if (main.params.length > 0) {
             fail(
                 "main takes no parameters: what a program is given are the free identifiers uv, " +
-                "fragCoord, resolution, time, aspect, texel and centered",
+                "fragCoord, resolution, time, aspect, texel, centered, frame and deltaTime, and the " +
+                "texture previous",
                 main.params[0]!.pos,
             )
         }
@@ -486,7 +500,15 @@ export function check(unit: Unit, prelude: FuncDecl[], options: CheckOptions = {
             case "bool":
                 return
             case "ident": {
-                if (scope.has(e.name) || INPUT_NAMES.has(e.name) || DERIVED_NAMES.has(e.name) || uniforms.has(e.name) || consts.has(e.name)) return
+                if (scope.has(e.name) || INPUT_NAMES.has(e.name) || DERIVED_NAMES.has(e.name) || STEP_NAMES.has(e.name) ||
+                    uniforms.has(e.name) || consts.has(e.name)) return
+                if (e.name === PREVIOUS && !textures.has(e.name)) {
+                    fail(
+                        "previous is the frame this program drew before, a texture, and a texture is only " +
+                        "ever the first argument of tex2D. Write `tex2D(previous, uv)`",
+                        e.pos, e.name.length,
+                    )
+                }
                 if (textures.has(e.name)) {
                     fail(
                         `"${e.name}" is a texture, and a texture is only ever the first argument of ` +
@@ -604,7 +626,17 @@ export function check(unit: Unit, prelude: FuncDecl[], options: CheckOptions = {
                     )
                 }
                 arity(e, n, builtin.min, builtin.max)
-                if (tex === undefined || tex.k !== "ident" || !textures.has(tex.name)) {
+                // The previous frame, unless something in this file took its name.
+                const previous = tex?.k === "ident" && tex.name === PREVIOUS && !textures.has(PREVIOUS) &&
+                    !scope.has(PREVIOUS) && !uniforms.has(PREVIOUS) && !consts.has(PREVIOUS)
+                if (previous && n === "tex2Dlod") {
+                    fail(
+                        "previous has one level, the frame as drawn, so there is no mip level to pick. " +
+                        "Read it with `tex2D(previous, uv)`",
+                        e.pos,
+                    )
+                }
+                if (!previous && (tex === undefined || tex.k !== "ident" || !textures.has(tex.name))) {
                     const lod = n === "tex2Dlod" ? ", 0" : ""
                     fail(
                         `${n} samples a texture declared in this file, as in \`texture2D grain;\` ` +
@@ -654,7 +686,7 @@ export function check(unit: Unit, prelude: FuncDecl[], options: CheckOptions = {
     /** Refuses a name nothing declares, offering the nearest one spelled almost like it. */
     function unknown(n: string, scope: Set<string>, pos: Pos): never {
         const near = nearest(n, [
-            ...scope, ...INPUT_NAMES, ...DERIVED_NAMES, ...uniforms.keys(), ...textures.keys(), ...consts.keys(),
+            ...scope, ...INPUT_NAMES, ...DERIVED_NAMES, ...STEP_NAMES, ...uniforms.keys(), ...textures.keys(), ...consts.keys(),
             ...funcs.keys(), ...Object.keys(BUILTINS),
         ])
         if (near === null) fail(`"${n}" is not declared`, pos, n.length)

package/src/lang/classify.ts

@@ -13,7 +13,7 @@
  * wants that should ask it.
  */
 
-import { SOURCE_INPUTS } from "../ir"
+import { PREVIOUS, SOURCE_INPUTS } from "../ir"
 import { BUILTINS } from "./builtins"
 import { lex } from "./lexer"
 import { PRELUDE_NAMES } from "./prelude-source"
@@ -42,7 +42,7 @@ export interface SLClassifiedToken {
     length: number
 }
 
-const INPUT_NAMES: ReadonlySet<string> = new Set(Object.keys(SOURCE_INPUTS))
+const INPUT_NAMES: ReadonlySet<string> = new Set([...Object.keys(SOURCE_INPUTS), PREVIOUS])
 
 /** The tokens of `source`, comments included, in order, each with its class. */
 export function classify(source: string): SLClassifiedToken[] {

package/src/lang/glsl.ts

@@ -76,6 +76,7 @@ const GLSL_TYPES = new Set(["float", "int", "uint", "bool", "vec2", "vec3", "vec
 const RENAME: Record<string, string> = {
     vec2: "float2", vec3: "float3", vec4: "float4", mix: "lerp", fract: "frac",
     texture: "tex2D", texture2D: "tex2D", textureLod: "tex2Dlod", iTime: "time", iGlobalTime: "time", gl_FragCoord: "fragCoord",
+    iFrame: "frame", iTimeDelta: "deltaTime",
 }
 
 /**
@@ -94,8 +95,6 @@ const NARROW: Record<string, [string, string]> = {
 
 /** Shadertoy's inputs with no counterpart yet, and why. */
 const MISSING: Record<string, string> = {
-    iFrame: "there is no frame counter yet",
-    iTimeDelta: "there is no delta time yet",
     iFrameRate: "there is no frame rate",
     iDate: "there is no date",
     iChannelTime: "a texture has no time of its own",
@@ -115,6 +114,7 @@ const MISSING: Record<string, string> = {
 const HOST_UNIFORMS: Record<string, string> = {
     u_time: "time", u_resolution: "resolution", time: "time", resolution: "resolution",
     iTime: "time", iGlobalTime: "time", iResolution: "resolution", iMouse: "mouse",
+    iFrame: "frame", iTimeDelta: "deltaTime",
 }
 
 const QUALIFIERS = new Set(["highp", "mediump", "lowp"])

package/src/lang/lower.ts

@@ -50,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"
@@ -246,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 },
                 })
@@ -289,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)

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, intUniformProblem,
-    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": {

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) {

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"