onejs-sl 0.6.0 → 0.8.0

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. */
@@ -162,7 +162,7 @@ export const BUILTIN_DOCS: Readonly<Record<string, string>> = {
     turbulence: "Simplex creases layered in octaves, 1 to 4: fire, smoke, marble.",
     ridged: "Turbulence made bright at its creases: ridges, lightning, cracks.",
     tex2D: "The colour of texture s at the uv t, with straight alpha.",
-    tex2Dlod: "The colour of texture s at the uv t from mip level lod: 0 is the full size, 1 half, and so on.",
+    tex2Dlod: "Texture s at uv t from mip level lod: 0 is full size, 1 half, and a fraction blends the two.",
     sdf: "The signed distance from p to a shape, negative inside: `sdf.circle(p, r)`.",
     ramp: "t mapped through evenly spaced colour stops, from the first at 0 to the last at 1.",
 }
@@ -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) {
@@ -1003,8 +1037,8 @@ export interface Texture {
     sample(uv: Vec2): Vec4
     /**
      * The colour at `uv` from mip level `lod`: 0 is the full size texture, 1
-     * half, and a fraction blends two levels where the texture's filter does.
-     * A texture with no mips has only level 0.
+     * half, and a fraction blends the two levels either side, whatever the
+     * texture's filter mode. A texture with no mips has only level 0.
      */
     sampleLevel(uv: Vec2, lod: Num): 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"

package/src/web.ts

@@ -12,25 +12,34 @@
  * named `n<index>`. What differs is the contract with the host, which is fixed
  * and the same for both languages:
  *
- *   sl_Res   (target width, target height, seconds, 0)
- *   sl_Opt   (1 in a Linear colour space project else 0, 1 to flip uv.y, 0, 0)
+ *   sl_Res   (target width, target height, seconds, frame)
+ *   sl_Opt   (1 in a Linear colour space project else 0, 1 to flip uv.y, deltaTime, 0)
  *   sl_U[16] uniform slots, each a vec4, in the program's slot order
  *   textures by slot: GLSL `sl_Tex<slot>`; WGSL `sl_tex<slot>` at binding
  *            2 + 2 * slot with its own sampler `sl_samp<slot>` at 1 + 2 * slot,
  *            all in group 0 beside the frame block at binding 0. Only the
  *            slots the program samples are declared.
+ *   the previous frame, only for a program that samples it: GLSL `sl_Prev`;
+ *            WGSL `sl_prev` with its sampler `sl_prevSamp`, at the two
+ *            bindings after the last texture slot's, whatever the program
+ *            declares. Read at level 0 (`body.ts`, `BodyTarget.previous`),
+ *            its y flipped when `sl_Opt.y` flips uv, so the texture the host
+ *            drew last frame reads back the way it was written.
+ *
+ * `frame` and `deltaTime` ride in components that were 0, and a host sets
+ * them only for a program that reads them (`readsOf`).
  *
  * WGSL also carries its vertex stage (`sl_vs`, a full-target triangle from the
  * vertex index) so one module is one pipeline; the GLSL host supplies its own.
  */
 
 import { INT_LIMITS } from "./body"
-import { SLError, TYPE, valueAt, type NodeRef, type Program, type SLKind, type SLType, type ValueNode } from "./ir"
+import { SLError, TYPE, isWhole, valueAt, type NodeRef, type Program, type SLKind, type SLType, type ValueNode } from "./ir"
 import { inVaryingFlow, local, printBody, structure, type Syntax } from "./structure"
 import { libClosure, libIndex, LIB_FUNCTIONS, SDF_CALLS } from "./lib"
 import { LIB_GLSL } from "./lib/glsl"
 import { LIB_WGSL } from "./lib/wgsl"
-import { INPUT_ID, SLOP, UNIFORM_SLOTS } from "./ops"
+import { INPUT_ID, SLOP, TEXTURE_SLOTS, UNIFORM_SLOTS } from "./ops"
 
 export type WebLanguage = "glsl" | "wgsl"
 
@@ -50,6 +59,8 @@ function emitWeb(p: Program, lang: WebLanguage): string {
     const need = new Set<number>()
     const smoothsteps = new Set<SLType>()
     const sampled = new Set<number>()
+    /** Whether the body samples the previous frame, which declares its binding. */
+    let previous = false
     const shape = structure(p)
     const T = (t: SLType) => (W ? (t === 1 ? "f32" : `vec${t}f`) : t === 1 ? "float" : `vec${t}`)
     /** A value's type in this language, its kind included. */
@@ -90,7 +101,10 @@ function emitWeb(p: Program, lang: WebLanguage): string {
                     case 1: return `(sl_uv * ${res}.xy)`
                     case 2: return `${res}.xy`
                     case 3: return `${res}.z`
-                    default: return `(${res}.x / max(${res}.y, 1.0))`
+                    case 4: return `(${res}.x / max(${res}.y, 1.0))`
+                    case 5: return `${res}.w`
+                    case 6: return W ? "sl.opt.z" : "sl_Opt.z"
+                    default: throw new Error(`no web mapping for the input "${n.name}"`)
                 }
             }
             case "uniform": {
@@ -247,10 +261,24 @@ function emitWeb(p: Program, lang: WebLanguage): string {
             case SLOP.SAMPLE_LOD: {
                 const slot = Math.round(imm[0] ?? 0)
                 sampled.add(slot)
-                return W
-                    ? `textureSampleLevel(sl_tex${slot}, sl_samp${slot}, ${a[0]}, ${a[1]})`
-                    : `textureLod(sl_Tex${slot}, ${a[0]}, ${a[1]})`
+                const at = (level: string) => W
+                    ? `textureSampleLevel(sl_tex${slot}, sl_samp${slot}, ${a[0]}, ${level})`
+                    : `textureLod(sl_Tex${slot}, ${a[0]}, ${level})`
+                // A fraction blends the level below and the level above,
+                // whatever the texture's filter between levels, as the HLSL
+                // emitter does (`isWhole`). Past the smallest level both read
+                // the smallest, as a whole level past it does.
+                if (isWhole(p.nodes, n.args[1]!)) return at(a[1]!)
+                const below = `floor(${a[1]})`
+                return `mix(${at(below)}, ${at(`${below} + 1.0`)}, fract(${a[1]}))`
             }
+            case SLOP.SAMPLE_PREVIOUS:
+                previous = true
+                // Flipped as this frame flipped the uv it wrote at, so a read at
+                // a pixel's own uv is that pixel on either backend.
+                return W
+                    ? `textureSampleLevel(sl_prev, sl_prevSamp, ${a[0]} * vec2f(1.0, 1.0 - 2.0 * sl.opt.y) + vec2f(0.0, sl.opt.y), 0.0)`
+                    : `textureLod(sl_Prev, ${a[0]} * vec2(1.0, 1.0 - 2.0 * sl_Opt.y) + vec2(0.0, sl_Opt.y), 0.0)`
             default:
                 throw new SLError(
                     `the ${lang.toUpperCase()} emitter has no case for opcode ${n.op}. A program using it would ` +
@@ -342,9 +370,12 @@ function emitWeb(p: Program, lang: WebLanguage): string {
     const textures = p.textures.filter((t) => sampled.has(t.slot))
 
     if (W) {
-        const bindings = textures.map((t) =>
+        const bindings = [...textures.map((t) =>
             `@group(0) @binding(${1 + 2 * t.slot}) var sl_samp${t.slot}: sampler;\n` +
-            `@group(0) @binding(${2 + 2 * t.slot}) var sl_tex${t.slot}: texture_2d<f32>;`).join("\n")
+            `@group(0) @binding(${2 + 2 * t.slot}) var sl_tex${t.slot}: texture_2d<f32>;`),
+        ...previous ? [
+            `@group(0) @binding(${1 + 2 * TEXTURE_SLOTS}) var sl_prevSamp: sampler;\n` +
+            `@group(0) @binding(${2 + 2 * TEXTURE_SLOTS}) var sl_prev: texture_2d<f32>;`] : []].join("\n")
         return `${header}
 struct SLFrame { res: vec4f, opt: vec4f, u: array<vec4f, ${WEB_UNIFORM_SLOTS}> }
 @group(0) @binding(0) var<uniform> sl: SLFrame;
@@ -362,7 +393,7 @@ ${body}
 }
 `
     }
-    const samplers = textures.map((t) => `uniform sampler2D sl_Tex${t.slot};`).join("\n")
+    const samplers = [...textures.map((t) => `uniform sampler2D sl_Tex${t.slot};`), ...previous ? ["uniform sampler2D sl_Prev;"] : []].join("\n")
     return `#version 300 es
 ${header}
 precision highp float;