onejs-sl 0.3.0 → 0.4.0

package/src/serial.ts

@@ -9,14 +9,16 @@
  * older one is migrated to this one and rehashed under it.
  */
 import {
-    INPUTS, SLError, SL_IR_VERSION, TYPE, checkCaps, controlOf, controlProblem, hashProgram,
-    type NodeRef, type Program, type SLNode, type SLType, type TextureDecl, type UniformDecl,
+    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,
 } from "./ir"
-import { SL_ARITY, SL_NAME } from "./ops"
+import { SLOP, SL_ARITY, SL_NAME } from "./ops"
 
 export interface ProgramJSON {
     /** `SL_IR_VERSION` of the writer. Absent means 1. */
     v: number
+    /** `SL_HASH_VERSION` of the writer, which `hash` was computed under. Absent means 1. */
+    h?: number
     nodes: SLNode[]
     result: NodeRef
     uniforms: UniformDecl[]
@@ -25,7 +27,10 @@ export interface ProgramJSON {
 }
 
 export function toJSON(p: Program): ProgramJSON {
-    return { v: p.version, nodes: p.nodes, result: p.result, uniforms: p.uniforms, textures: p.textures, hash: p.hash }
+    return {
+        v: p.version, h: SL_HASH_VERSION, nodes: p.nodes, result: p.result, uniforms: p.uniforms, textures: p.textures,
+        hash: p.hash,
+    }
 }
 
 export function fromJSON(json: unknown): Program {
@@ -38,24 +43,71 @@ export function fromJSON(json: unknown): Program {
             `Update onejs-sl to read it, or rebuild it from its .sl source.`)
     }
     if (!Array.isArray(j.nodes) || j.nodes.length === 0) fail("it has no nodes")
-    const nodes = j.nodes.map((n, i) => node(n, i))
-    const result = j.result
-    if (!Number.isInteger(result) || result! < 0 || result! >= nodes.length) fail(`its result ${String(result)} is not a node`)
-    if (nodes[result!]!.type !== TYPE.VEC4) fail("its result is not a float4")
+    const written = j.nodes.map((n, i) => node(n, i))
+    if (!Number.isInteger(j.result) || j.result! < 0 || j.result! >= written.length) {
+        fail(`its result ${String(j.result)} is not a node`)
+    }
+    // The lowest version that has these nodes, which is what the writer
+    // recorded unless the file predates version 2 (whose nodes version 2 reads
+    // as they are) or was edited. One that claims less than its nodes need
+    // holds something its version never had.
+    const needs = programVersion(written)
+    if (v < needs && v >= 2) fail(`it says IR version ${v} and holds nodes version ${needs} added; it was changed after it was written`)
+    const { nodes, result } = v < 3 ? toOperands(written, j.result!) : { nodes: written, result: j.result! }
+    nodes.forEach((n, i) => {
+        const problem = n.k === "call" ? formProblem(n, nodes) : null
+        if (problem !== null) fail(`node ${i} is not a form its op has: ${problem}`)
+    })
+    if (nodes[result]!.type !== TYPE.VEC4) fail("its result is not a float4")
     const uniforms = (j.uniforms ?? []).map(uniform)
     const textures = (j.textures ?? []).map(texture)
     checkCaps({ uniforms, textures })
     for (const n of nodes) {
         if (n.k === "uniform" && n.slot >= uniforms.length) fail(`a node reads uniform slot ${n.slot}, which is not declared`)
     }
-    const hash = hashProgram(nodes, result!, uniforms, textures)
-    // Same version, so the same maths and the same hash; a different one means
-    // the file was edited or damaged, and its cached shader belongs to
-    // something else. An older version is rehashed under this one on purpose.
-    if (v === SL_IR_VERSION && j.hash !== undefined && j.hash !== hash) {
+    const version = programVersion(nodes)
+    const hash = hashProgram(nodes, result, uniforms, textures)
+    // The same IR version and hash scheme, so the same hash; a different one
+    // means the file was edited or damaged, and its cached shader belongs to
+    // something else. A file an older version or scheme wrote is rehashed under
+    // this one on purpose.
+    if (v === version && (j.h ?? 1) === SL_HASH_VERSION && j.hash !== undefined && j.hash !== hash) {
         fail(`its hash ${j.hash} does not match its nodes (${hash}); it was changed after it was written`)
     }
-    return { version: SL_IR_VERSION, nodes, result: result!, uniforms, textures, hash }
+    return { version, nodes, result, uniforms, textures, hash }
+}
+
+/**
+ * A graph written before IR 3, with the forms it had then moved to the one each
+ * op has now: an sdf's shape parameters after its id and an octave op's count
+ * were immediates, and are operands. Each constant goes in just before the
+ * call that reads it, and every later reference moves along.
+ */
+function toOperands(written: readonly SLNode[], writtenResult: NodeRef): { nodes: SLNode[]; result: NodeRef } {
+    const nodes: SLNode[] = []
+    const at: NodeRef[] = []
+    const constant = (type: SLType, v: number[]): NodeRef => nodes.push({ k: "const", type, v }) - 1
+    written.forEach((n, i) => {
+        const imm = n.k === "call" ? n.imm ?? [] : []
+        if (n.k === "call" && n.op === SLOP.SDF && n.args.length === 1) {
+            if (imm.length < 5) fail(`node ${i} is an sdf with ${imm.length} immediates; one written before IR 3 has at least 5`)
+            const q = constant(TYPE.VEC4, [imm[1]!, imm[2]!, imm[3]!, imm[4]!])
+            const r = constant(TYPE.VEC2, [imm[5] ?? 0, imm[6] ?? 0])
+            at[i] = nodes.push({ ...n, args: [at[n.args[0]!]!, q, r], imm: [imm[0]!] }) - 1
+            return
+        }
+        const octaves = n.k === "call" && (n.op === SLOP.FBM || n.op === SLOP.TURBULENCE || n.op === SLOP.RIDGED)
+        if (octaves && n.args.length === 1) {
+            if (imm.length < 1) fail(`node ${i} is ${SL_NAME[n.op]} with no octave count`)
+            const count = constant(TYPE.FLOAT, [imm[0]!])
+            at[i] = nodes.push({ ...n, args: [at[n.args[0]!]!, count], imm: imm.slice(1) }) - 1
+            return
+        }
+        const moved: SLNode = n.k === "call" ? { ...n, args: n.args.map((a) => at[a]!) }
+            : n.k === "swizzle" ? { ...n, src: at[n.src]! } : n
+        at[i] = nodes.push(moved) - 1
+    })
+    return { nodes, result: at[writtenResult]! }
 }
 
 function node(n: unknown, i: number): SLNode {

package/src/sl.ts

@@ -24,7 +24,7 @@
 
 import { parseColor as parseHex } from "./color"
 import {
-    Builder, INPUTS, SLError, SL_IR_VERSION, TYPE, hashProgram, widthName,
+    Builder, INPUTS, RAMP_STOP_COMPUTED, SLError, TYPE, hashProgram, programVersion, widthName, writtenColour,
     type InputName, type NodeRef, type Program, type SLNode, type SLType, type UniformControl,
 } from "./ir"
 import { SLOP, type SLOpCode } from "./ops"
@@ -288,7 +288,7 @@ export function program(fn: (inputs: ProgramInputs) => Vec4): Program {
         }
         const nodes: SLNode[] = b.nodes.slice()
         return {
-            version: SL_IR_VERSION,
+            version: programVersion(nodes),
             nodes,
             result: out.ref,
             uniforms: b.uniforms.slice(),
@@ -533,6 +533,10 @@ export function uniformDefaults(p: Program): number[] {
  * fields `fx.noise` draws: a value or simplex base, layered as fBm, or the
  * turbulence and ridged variants built on simplex. A program has no seed;
  * offset the input for a different field. Octaves are 1 to 4, as in fx.
+ *
+ * The octave count may be a value, a uniform say, rounded to the nearest whole
+ * number and held to 1 to 4 where it is read. It is an operand either way
+ * (IR 3); a constant one is checked here, and prints as the number it is.
  */
 export function noise(p: Vec2): Float {
     return mk(p.owner, p.owner.call(SLOP.NOISE, TYPE.FLOAT, [p.ref]), TYPE.FLOAT)
@@ -540,24 +544,31 @@ export function noise(p: Vec2): Float {
 export function simplex(p: Vec2): Float {
     return mk(p.owner, p.owner.call(SLOP.SIMPLEX, TYPE.FLOAT, [p.ref]), TYPE.FLOAT)
 }
-function octaveCount(name: string, octaves: number): number {
-    if (!Number.isInteger(octaves) || octaves < 1 || octaves > 4) {
-        throw new SLError(`${name} octaves must be a whole number from 1 to 4, got ${octaves}`)
+/**
+ * An octave op: the point and the count as operands, with `rest` (fbm's kind)
+ * the immediates. A constant count is checked here.
+ */
+function octaves(op: SLOpCode, name: string, p: Vec2, count: Num, rest: number[]): Float {
+    const c = components(p.owner, count)
+    if (c.length !== 1) throw new SLError(`${name}'s octave count is one number, and this is a ${widthName(c.length as SLType)}`)
+    const n = c[0]!
+    if (typeof n === "number" && (!Number.isInteger(n) || n < 1 || n > 4)) {
+        throw new SLError(`${name} octaves must be a whole number from 1 to 4, got ${n}`)
     }
-    return octaves
+    const v = typeof n === "number" ? float(n) : n
+    return mk(p.owner, p.owner.call(op, TYPE.FLOAT, [p.ref, v.ref], rest), TYPE.FLOAT)
 }
 /** Layered noise. `base` picks the grid ("value", the default) or triangles ("simplex"). */
-export function fbm(p: Vec2, octaves = 3, base: "value" | "simplex" = "value"): Float {
-    const kind = base === "simplex" ? 1 : 0
-    return mk(p.owner, p.owner.call(SLOP.FBM, TYPE.FLOAT, [p.ref], [octaveCount("fbm", octaves), kind]), TYPE.FLOAT)
+export function fbm(p: Vec2, octaveCount: Num = 3, base: "value" | "simplex" = "value"): Float {
+    return octaves(SLOP.FBM, "fbm", p, octaveCount, [base === "simplex" ? 1 : 0])
 }
 /** Sum of |simplex| octaves: creases that stack into veins and licks. Fire, smoke, marble. */
-export function turbulence(p: Vec2, octaves = 3): Float {
-    return mk(p.owner, p.owner.call(SLOP.TURBULENCE, TYPE.FLOAT, [p.ref], [octaveCount("turbulence", octaves)]), TYPE.FLOAT)
+export function turbulence(p: Vec2, octaveCount: Num = 3): Float {
+    return octaves(SLOP.TURBULENCE, "turbulence", p, octaveCount, [])
 }
 /** The turbulence crease made bright and squared: ridges, lightning, cracks. */
-export function ridged(p: Vec2, octaves = 3): Float {
-    return mk(p.owner, p.owner.call(SLOP.RIDGED, TYPE.FLOAT, [p.ref], [octaveCount("ridged", octaves)]), TYPE.FLOAT)
+export function ridged(p: Vec2, octaveCount: Num = 3): Float {
+    return octaves(SLOP.RIDGED, "ridged", p, octaveCount, [])
 }
 
 /** "#rgb", "#rrggbb" or "#rrggbbaa" to 0..1 components. Shared with fx. */
@@ -581,14 +592,23 @@ export function parseColor(hex: string): [number, number, number, number] {
  *
  * This is the argument for the EDSL in miniature. A library function that
  * composes from primitives costs one function here and nothing anywhere else.
+ *
+ * A stop is a colour as written: a hex, four numbers, or a value that is a
+ * colour as written, which is one `color`, `sl.uniform.colour` or a hex
+ * literal made (a colour uniform, say). The ramp blends the colours as
+ * written, so a value computed any other way, already in the working space,
+ * has nothing it could blend, and is refused.
  */
-export function ramp(t: Num, stops: Array<string | [number, number, number, number]>): Vec4 {
+export function ramp(t: Num, stops: Array<string | [number, number, number, number] | Vec3 | Vec4>): Vec4 {
     if (stops.length < 2) throw new SLError(`a ramp needs at least 2 stops, got ${stops.length}`)
     const tv = (typeof t === "number" ? float(t) : t).saturate()
+    const written = stops.map((s) => (s instanceof Val ? asWritten(s) : null))
     // Each stop is built immediately before the mix that consumes it. The graph
     // and the hash are the same either way (the hash is over the shape, not the
     // storage order); the order only mattered to the VM's register allocator.
     const colourAt = (i: number) => {
+        const w = written[i]
+        if (w !== null && w !== undefined) return w
         const v = typeof stops[i] === "string" ? parseColor(stops[i] as string) : (stops[i] as number[])
         return vec4(v[0], v[1], v[2], v[3])
     }
@@ -606,6 +626,18 @@ export function ramp(t: Num, stops: Array<string | [number, number, number, numb
     return toLinear(out)
 }
 
+/**
+ * A colour value as it was written, a float4: the operand of the `toLinear`
+ * that reading it as a colour applied, with alpha 1 when it has three
+ * components. Anything else was computed in the working space.
+ */
+function asWritten(v: Vec3 | Vec4): Vec4 {
+    const ref = writtenColour(v.owner.nodes, v.ref)
+    if (ref === null) throw new SLError(RAMP_STOP_COMPUTED)
+    const raw = mk(v.owner, ref, v.width) as Val
+    return v.width === TYPE.VEC4 ? (raw as Vec4) : vec4(raw, 1)
+}
+
 /**
  * Signed distance to a shape, positive outside and negative inside.
  *
@@ -621,27 +653,45 @@ export function ramp(t: Num, stops: Array<string | [number, number, number, numb
  *
  * A shape takes up to `SL_SDF_PARAMS[kind]` parameters, six at most. Fewer
  * fills zeros, which is all a program could pass before six shapes grew their
- * fifth and sixth.
+ * fifth and sixth. A vector parameter counts as its components, so a box's
+ * half extents can be one float2.
  *
  * Which parameters a shape takes is the shape's own business; `circle` wants a
  * radius, `roundedBox` wants half extents and a corner. See `lib/sdf2d.hlsl`.
+ *
+ * A parameter may be any value, a uniform or one computed per pixel. The six
+ * are operands either way (IR 3), a float4 and a float2, and constant ones
+ * print as the numbers they are.
  */
-export function sdf(kind: SlSdfKind, p: Vec2, params: number[] = []): Float {
+export function sdf(kind: SlSdfKind, p: Vec2, params: Num[] = []): Float {
     const id = SL_SDF_SHAPES[kind]
     if (id === undefined) throw new SLError(`"${kind}" is not a shape; see SL_SDF_SHAPES for the 42 names`)
+    const c = params.flatMap((v) => components(p.owner, v))
     // At least four, so a program that passed a shape more than it reads, which
     // was harmless when every shape took four, still builds.
     const most = Math.max(4, SL_SDF_PARAMS[kind])
-    if (params.length > most) {
-        throw new SLError(`sl.sdf("${kind}") takes at most ${most} parameters and was given ${params.length}`)
+    if (c.length > most) {
+        throw new SLError(`sl.sdf("${kind}") takes at most ${most} parameters and was given ${c.length}`)
     }
-    for (const v of params) {
-        if (!Number.isFinite(v)) throw new SLError(`sl.sdf parameters must be finite, got ${v}`)
+    for (const v of c) {
+        if (typeof v === "number" && !Number.isFinite(v)) throw new SLError(`sl.sdf parameters must be finite, got ${v}`)
     }
-    // Four always, as before, and a fifth and sixth only when given: a program
-    // using four or fewer is the same node, and hashes the same, as it was.
-    const imm = [params[0] ?? 0, params[1] ?? 0, params[2] ?? 0, params[3] ?? 0, ...params.slice(4)]
-    return mk(p.owner, p.owner.call(SLOP.SDF, TYPE.FLOAT, [p.ref], [id, ...imm]), TYPE.FLOAT)
+    const q = vec4(c[0] ?? 0, c[1] ?? 0, c[2] ?? 0, c[3] ?? 0)
+    const r = vec2(c[4] ?? 0, c[5] ?? 0)
+    return mk(p.owner, p.owner.call(SLOP.SDF, TYPE.FLOAT, [p.ref, q.ref, r.ref], [id]), TYPE.FLOAT)
+}
+
+/**
+ * A value as its components: numbers for a constant, which is what it would
+ * have been written as, and a float per component otherwise.
+ */
+function components(b: Builder, v: Num): Num[] {
+    if (typeof v === "number") return [v]
+    if (v.owner !== b) throw new SLError("a value from another program cannot be used in this one")
+    const n = b.nodes[v.ref]!
+    if (n.k === "const") return n.v.slice()
+    if (v.width === 1) return [v]
+    return Array.from({ length: v.width }, (_, i) => v.swz("xyzw"[i] as "x"))
 }
 
 /** Distance to the nearest point of a jittered lattice. Cells, cracks, scales. */
@@ -696,7 +746,14 @@ export const uniform = {
 }
 
 export interface Texture {
+    /** The colour at `uv`, filtered as the texture's own settings say. */
     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.
+     */
+    sampleLevel(uv: Vec2, lod: Num): Vec4
 }
 
 export function texture(name: string): Texture {
@@ -707,6 +764,15 @@ export function texture(name: string): Texture {
             if (uv.owner !== b) throw new SLError("a value from another program cannot be used in this one")
             return mk(b, b.call(SLOP.SAMPLE, TYPE.VEC4, [uv.ref], [slot]), TYPE.VEC4)
         },
+        sampleLevel(uv: Vec2, lod: Num): Vec4 {
+            if (uv.owner !== b) throw new SLError("a value from another program cannot be used in this one")
+            const level = typeof lod === "number" ? b.constant([lod]) : lod
+            if (typeof level !== "number") {
+                if (level.owner !== b) throw new SLError("a value from another program cannot be used in this one")
+                if (level.width !== 1) throw new SLError(`a mip level is one number, and this is a ${widthName(level.width)}`)
+            }
+            return mk(b, b.call(SLOP.SAMPLE_LOD, TYPE.VEC4, [uv.ref, typeof level === "number" ? level : level.ref], [slot]), TYPE.VEC4)
+        },
     }
 }
 

package/src/web.ts

@@ -52,6 +52,11 @@ function emitWeb(p: Program, lang: WebLanguage): string {
     const emitted = new Set<number>()
     const T = (t: SLType) => (W ? (t === 1 ? "f32" : `vec${t}f`) : t === 1 ? "float" : `vec${t}`)
     const typeOf = (ref: number) => p.nodes[ref].type
+    /** A constant node's value, or null for anything computed. */
+    const constantOf = (ref: number): number[] | null => {
+        const c = p.nodes[ref]!
+        return c.k === "const" ? c.v : null
+    }
 
     /** A node's value widened to `t` when it is a scalar and `t` is not. */
     const splat = (ref: number, t: SLType) => (typeOf(ref) === 1 && t > 1 ? `${T(t)}(n${ref})` : `n${ref}`)
@@ -168,16 +173,23 @@ function emitWeb(p: Program, lang: WebLanguage): string {
             case SLOP.HSV2RGB: return `${lib("sl_hsv2rgb")}(${a[0]})`
             case SLOP.NOISE: return `${lib("sl_valueNoise")}(${a[0]})`
             case SLOP.SIMPLEX: return `${lib("sl_simplex")}(${a[0]})`
-            case SLOP.FBM: return octaveCall(Math.round(imm[1] ?? 0), a[0], imm[0])
-            case SLOP.TURBULENCE: return octaveCall(2, a[0], imm[0])
-            case SLOP.RIDGED: return octaveCall(3, a[0], imm[0])
+            case SLOP.FBM: return octaveCall(Math.round((n.args.length > 1 ? imm[0] : imm[1]) ?? 0), a[0])
+            case SLOP.TURBULENCE: return octaveCall(2, a[0])
+            case SLOP.RIDGED: return octaveCall(3, a[0])
             case SLOP.VORONOI: return `${lib("sl_voronoi")}(${a[0]})`
-            case SLOP.SDF: return sdfCall(Math.round(imm[0] ?? 0), a[0], imm)
+            case SLOP.SDF: return sdfCall(Math.round(imm[0] ?? 0), a[0], sdfParams())
             case SLOP.SAMPLE: {
                 const slot = Math.round(imm[0] ?? 0)
                 sampled.add(slot)
                 return W ? `textureSample(sl_tex${slot}, sl_samp${slot}, ${a[0]})` : `texture(sl_Tex${slot}, ${a[0]})`
             }
+            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]})`
+            }
             default:
                 throw new SLError(
                     `the ${lang.toUpperCase()} emitter has no case for opcode ${n.op}. A program using it would ` +
@@ -188,24 +200,45 @@ function emitWeb(p: Program, lang: WebLanguage): string {
         /**
          * The library's onejsFbmKind, resolved here since the kind is a
          * constant: calling the dispatcher would print a WGSL `select` that
-         * runs two of the four fields to keep one.
+         * runs two of the four fields to keep one. The count is a literal when
+         * it is a constant, and otherwise rounded and held to 1 to 4 as
+         * `sl_fbm` holds it.
          */
-        function octaveCall(kind: number, pt: string, octaves: number | undefined): string {
-            const o = Math.min(4, Math.max(1, Math.round(octaves ?? 3)))
+        function octaveCall(kind: number, pt: string): string {
+            const c = constantOf(n.args[1]!)
+            const o = c !== null
+                ? String(Math.min(4, Math.max(1, Math.round(c[0]!))))
+                : `clamp(${W ? "i32" : "int"}(floor(${a[1]} + 0.5)), 1, 4)`
             const fn = kind === 2 ? "onejsTurbulence" : kind === 3 ? "onejsRidged" : kind === 1 ? "onejsFbmSimplex" : "onejsFbm"
             return `${lib(fn, ["float2", "float", "int", "float", "float"])}(${pt}, 0.0, ${o}, 2.0, 0.5)`
         }
 
+        /**
+         * The six shape parameters, each as a float expression and, when it
+         * is a constant, its number: literals from a constant float4 or
+         * float2, and their components otherwise.
+         */
+        function sdfParams(): Array<{ text: string; value?: number }> {
+            const part = (ref: number, chans: string[]) => {
+                const c = constantOf(ref)
+                return chans.map((ch, i) => c !== null ? { text: lit(c[i]!), value: c[i]! } : { text: `${a[n.args.indexOf(ref)]}.${ch}` })
+            }
+            return [...part(n.args[1]!, ["x", "y", "z", "w"]), ...part(n.args[2]!, ["x", "y"])]
+        }
+
         /** The shape is a constant, so this calls it directly instead of sl_sdfDistance's switch. */
-        function sdfCall(id: number, pt: string, im: number[]): string {
+        function sdfCall(id: number, pt: string, v: Array<{ text: string; value?: number }>): string {
             const shape = SDF_CALLS[id]
             // sl_sdfDistance returns 1e6 for an id it does not know.
             if (shape === undefined) return lit(1e6)
             const fn = lib(shape.fn)
-            const v = [im[1] ?? 0, im[2] ?? 0, im[3] ?? 0, im[4] ?? 0, im[5] ?? 0, im[6] ?? 0]
             const args = shape.args.map((arg) => {
-                if ("int" in arg) return String(Math.trunc(v[arg.int]))
-                const parts = arg.map((i) => lit(v[i]))
+                // Truncated toward zero, as HLSL's int() of the float4 does.
+                if ("int" in arg) {
+                    const p = v[arg.int]!
+                    return p.value !== undefined ? String(Math.trunc(p.value)) : W ? `i32(${p.text})` : `int(${p.text})`
+                }
+                const parts = arg.map((i) => v[i]!.text)
                 return parts.length === 1 ? parts[0] : `${T(parts.length as SLType)}(${parts.join(", ")})`
             })
             return `${fn}(${[pt, ...args].join(", ")})`