onejs-sl 0.2.1 → 0.4.0

package/lib/common.hlsl

@@ -1,7 +1,7 @@
 // Helpers shared by EVERY shader language backend.
 //
-// The VM (OneJS/FxProgram.shader) includes this as SLCommon.cginc, and every
-// shader generated from a program by the HLSL emitter includes it too. The web
+// Every shader generated from a program by the HLSL emitter includes this as
+// SLCommon.cginc. The web
 // emitters and a host's own frame (`emitBody`) get it translated, by
 // `lib/translate.ts`, from this one text. That sharing is the whole reason this
 // file exists: the backends have to agree, and the fastest way to make them
@@ -134,10 +134,9 @@ float sl_luminance(float3 c) { return dot(c, float3(0.2126, 0.7152, 0.0722)); }
 // In a Gamma project the written value is already right. The float4 form keeps
 // alpha, which is coverage rather than light. Mirrors fxColorToWorking.
 //
-// Every width uses Unity's cubic approximation, lane by lane. The VM has one
-// TO_LINEAR for all widths (its registers are float4, so it converts .rgb),
-// and a scalar or float2 on the exact curve here drew up to 5/255 apart from
-// it in the dark range: the editor and a player disagreed.
+// Every width uses Unity's cubic approximation, lane by lane. A scalar or
+// float2 on the exact curve once drew up to 5/255 apart from the float3 form
+// in the dark range.
 //
 // The curve is Unity's GammaToLinearSpace, written out here so that a target
 // without UnityCG.cginc has it too. The switch below is the one piece of

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "onejs-sl",
-  "version": "0.2.1",
-  "description": "The OneJS shader language: a small typed language for per pixel programs, compiled to a portable IR and emitted as HLSL, WGSL, GLSL ES or a VM buffer",
+  "version": "0.4.0",
+  "description": "The OneJS shader language: a small typed language for per pixel programs, compiled to a portable IR and emitted as HLSL, WGSL or GLSL ES",
   "main": "src/index.ts",
   "types": "src/index.ts",
   "exports": {
@@ -9,8 +9,6 @@
     "./core": "./src/core.ts",
     "./compile": "./src/compile.ts",
     "./tables": "./src/tables.ts",
-    "./limits": "./src/limits.ts",
-    "./vm": "./src/vm.ts",
     "./emit/hlsl-body": "./src/emit/hlsl-body.ts",
     "./emit/unity": "./src/emit/unity.ts",
     "./emit/web": "./src/emit/web.ts",

package/src/body.ts

@@ -43,7 +43,7 @@ export interface BodyTarget {
      *   an sRGB texture is decoded before it is filtered, as an sRGB sampler
      *   does; with `gamma`, rgb is as stored.
      * - **Filtered and wrapped by the host.** The body does neither. OneJS's
-     *   hosts, the generated shader, the VM and the web backends alike, use the
+     *   hosts, the generated shader and the web backends alike, use the
      *   bound texture's own filter and wrap modes, so a host that filters by
      *   hand draws the same picture by following the texture's settings.
      *
@@ -51,6 +51,14 @@ export interface BodyTarget {
      * as it is, and a host that composites premultiplied multiplies on write.
      */
     sample: (slot: number, uv: string) => string
+    /**
+     * A float4 sample of the texture in `slot` at `uv` from mip level `lod`, a
+     * float expression: 0 is the full size texture, 1 half, and a fraction
+     * blends two levels where the texture's filter does. Otherwise the same
+     * contract as `sample`. `tex2Dlod` in a program; HLSL's
+     * `tex2Dlod(s, float4(uv, 0, lod))` and Metal's `sample(s, uv, level(lod))`.
+     */
+    sampleLevel: (slot: number, uv: string, lod: string) => string
     /**
      * `linear`: `toLinear` calls `sl_toLinear`, for a host whose target holds
      * linear light. `gamma`: `toLinear` is the identity, decided here, so hex
@@ -100,6 +108,11 @@ export function emitBody(p: Program, target: BodyTarget): Body {
     const helpers = new Set<string>()
     const helper = (fn: string) => { helpers.add(fn); return fn }
     /** A node at width `w`: a scalar repeated into a constructor, since HLSL refuses float3(x) and Metal x.xxx. */
+    /** 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
+    }
     const splat = (ref: number, w: SLType) => (p.nodes[ref]!.type === TYPE.FLOAT && w > 1 ? ctor(w, Array(w).fill(name(ref))) : name(ref))
 
     const expr = (n: SLNode): string => {
@@ -143,7 +156,7 @@ export function emitBody(p: Program, target: BodyTarget): Body {
             case SLOP.MUL: return `(${a[0]} * ${a[1]})`
             case SLOP.DIV: return `(${a[0]} / ${a[1]})`
             case SLOP.MOD: return `fmod(${s[0]}, ${s[1]})`
-            // abs on the base, matching the VM. pow of a negative base is
+            // abs on the base, matching the web emitters. pow of a negative base is
             // undefined in HLSL and the backends must be undefined in the same
             // direction.
             case SLOP.POW: return `pow(abs(${s[0]}), ${s[1]})`
@@ -170,8 +183,8 @@ export function emitBody(p: Program, target: BodyTarget): Body {
             case SLOP.CLAMP: return `clamp(${s[0]}, ${s[1]}, ${s[2]})`
             case SLOP.SATURATE: return `saturate(${a[0]})`
 
-            // Of a scalar, Metal's are ambiguous, so what the VM computes for one
-            // (its lanes past the width hold 0) is written out.
+            // Of a scalar, Metal's are ambiguous, so the scalar case is written
+            // out.
             case SLOP.LENGTH: return w0 === 1 ? `abs(${a[0]})` : `length(${a[0]})`
             case SLOP.DISTANCE: return w0 === 1 ? `abs(${a[0]} - ${a[1]})` : `distance(${a[0]}, ${a[1]})`
             case SLOP.DOT: return w0 === 1 ? `(${a[0]} * ${a[1]})` : `dot(${a[0]}, ${a[1]})`
@@ -184,7 +197,7 @@ export function emitBody(p: Program, target: BodyTarget): Body {
             case SLOP.MIX: return `lerp(${s[0]}, ${s[1]}, ${s[2]})`
             case SLOP.STEP: return `step(${s[0]}, ${s[1]})`
             case SLOP.SMOOTHSTEP: return `smoothstep(${s[0]}, ${s[1]}, ${s[2]})`
-            // Matches the VM exactly, branchlessly, rather than using an if.
+            // Branchless, as the web emitters do it, rather than using an if.
             // Two backends that pick differently here disagree on every edge
             // value.
             case SLOP.SELECT: return `lerp(${s[2]}, ${s[1]}, step(${k(0.5, t)}, ${s[0]}))`
@@ -192,14 +205,19 @@ export function emitBody(p: Program, target: BodyTarget): Body {
             case SLOP.HSV2RGB: return `${helper("sl_hsv2rgb")}(${a[0]})`
             case SLOP.NOISE: return `${helper("sl_valueNoise")}(${a[0]})`
             case SLOP.SIMPLEX: return `${helper("sl_simplex")}(${a[0]})`
-            case SLOP.FBM: return `${helper("sl_fbm")}(${a[0]}, ${Math.round(imm[0] ?? 3)}, ${Math.round(imm[1] ?? 0)})`
-            case SLOP.TURBULENCE: return `${helper("sl_fbm")}(${a[0]}, ${Math.round(imm[0] ?? 3)}, 2)`
-            case SLOP.RIDGED: return `${helper("sl_fbm")}(${a[0]}, ${Math.round(imm[0] ?? 3)}, 3)`
+            case SLOP.FBM:
+            case SLOP.TURBULENCE:
+            case SLOP.RIDGED: {
+                // The count rounded here and held to 1 to 4 by sl_fbm; a constant
+                // one is the whole number it is. fbm's kind is the one immediate.
+                const c = constantOf(n.args[1]!)
+                const count = c !== null ? String(Math.round(c[0]!)) : `int(floor(${a[1]} + 0.5))`
+                const kind = n.op === SLOP.TURBULENCE ? 2 : n.op === SLOP.RIDGED ? 3 : Math.round(imm[0] ?? 0)
+                return `${helper("sl_fbm")}(${a[0]}, ${count}, ${kind})`
+            }
             case SLOP.SDF: {
                 const id = Math.round(imm[0] ?? 0)
-                const q = [imm[1] ?? 0, imm[2] ?? 0, imm[3] ?? 0, imm[4] ?? 0].map(lit)
-                const r = [imm[5] ?? 0, imm[6] ?? 0].map(lit)
-                return `${helper("sl_sdfDistance")}(${id}, ${a[0]}, float4(${q.join(", ")}), float2(${r.join(", ")}))`
+                return `${helper("sl_sdfDistance")}(${id}, ${a[0]}, ${a[1]}, ${a[2]})`
             }
             case SLOP.VORONOI: return `${helper("sl_voronoi")}(${a[0]})`
             case SLOP.SAMPLE: {
@@ -207,11 +225,16 @@ export function emitBody(p: Program, target: BodyTarget): Body {
                 textures.add(slot)
                 return target.sample(slot, a[0]!)
             }
+            case SLOP.SAMPLE_LOD: {
+                const slot = Math.round(imm[0] ?? 0)
+                textures.add(slot)
+                return target.sampleLevel(slot, a[0]!, a[1]!)
+            }
 
             default:
                 throw new SLError(
                     `the HLSL emitter has no case for opcode ${n.op}. A program using it would silently ` +
-                    `differ between the VM and a compiled build, which is the one failure this design ` +
+                    `differ between a Unity build and a browser, which is the one failure this design ` +
                     `cannot tolerate.`,
                 )
         }

package/src/compile.ts

@@ -6,10 +6,9 @@
  * editor to generate a shader from, WGSL and GLSL ES 3.00 for a browser to
  * compile on Unity's own device.
  *
- * There is no budget. `encode` refuses a program past the VM's 256
- * instructions or 8 registers, because the VM cannot run it; every backend
- * here is a real compiler, so a long program costs what it costs, as any
- * shader does. `Specs/SL_NEXT.md` section 0.5, step 3.
+ * There is no budget: every backend is a real compiler, so a long program
+ * costs what it costs, as any shader does. The caps on uniforms and textures
+ * are the only refusal (`checkCaps`).
  */
 
 import { checkCaps, type Program } from "./ir"

package/src/core.ts

@@ -10,7 +10,7 @@
 export * as sl from "./sl"
 export type { Float, Vec2, Vec3, Vec4, Num, ProgramInputs, Texture } from "./sl"
 export {
-    TYPE, INPUTS, MAX_TEXTURES, MAX_NODES, SLError, hashProgram, widthName, SL_IR_VERSION, inputsUsed,
+    TYPE, INPUTS, MAX_NODES, SLError, hashProgram, widthName, SL_IR_VERSION, SL_HASH_VERSION, inputsUsed,
     CONTROL_FIELDS, controlProblem,
 } from "./ir"
 export type {

package/src/hlsl.ts

@@ -1,19 +1,12 @@
 /**
- * The second backend: prints a program as real HLSL, compiled at build time.
+ * The Unity backend: prints a program as real HLSL, compiled at build time.
  *
- * Phase 3 of `Specs/SHADER_LANG.md` section 6, and the half the whole design
- * exists for. Unity cannot compile a shader at runtime in a player build, so on
- * play.onejs.com a program has to be interpreted. Ejecting to a Unity project
- * does not change what the author wrote, it changes what is POSSIBLE, because
- * an editor compiles shaders at build time.
+ * Phase 3 of `Specs/SHADER_LANG.md` section 6. Unity cannot compile a shader
+ * at runtime in a player build, so the editor generates one per program and the
+ * build ships it; a browser compiles the web emitters' output instead
+ * (`web.ts`). The same source draws both ways with no edit in between.
  *
- * So the same source is interpreted in the browser and compiled after an eject,
- * with no edit in between. That is what stops "Play games eject cleanly" from
- * quietly acquiring an asterisk.
- *
- * WHY THIS IS THE EASY BACKEND. The VM keeps every value in a float4 register
- * and has to be told how wide each one really is. Here the IR's types become the
- * HLSL types directly, so `float2` is a `float2` and nothing needs padding or
+ * The IR's types become the HLSL types directly, so `float2` is a `float2` and nothing needs padding or
  * explaining. One local per node also gives common subexpression elimination for
  * free: a node is emitted once no matter how many nodes reference it.
  *
@@ -22,7 +15,7 @@
  * next time it is generated.
  */
 
-import { SLError, type Program } from "./ir"
+import { SLError, SL_HASH_VERSION, 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,8 +41,8 @@ export interface EmitOptions {
  * Emits a complete `.shader` for a program.
  *
  * The shader's name carries the program hash, which is how the runtime finds it
- * again. If that link breaks, the runtime silently falls back to the VM and
- * nobody is told: correct output, quietly slow, no error. See `hashProgram`.
+ * again. If that link breaks, the program has no shader and draws nothing. See
+ * `hashProgram`.
  */
 export function emitShader(p: Program, options: EmitOptions = {}): string {
     const name = options.name ?? `Hidden/SLGenerated/${p.hash}`
@@ -81,7 +74,9 @@ export function emitShader(p: Program, options: EmitOptions = {}): string {
 //
 // Source of truth is the program this was emitted from; edits here are lost the
 // next time it is generated. The name carries the program hash, which is how the
-// runtime pairs the two. See Specs/SHADER_LANG.md section 6.
+// runtime pairs the two. See Specs/SHADER_LANG.md section 6. The scheme that
+// hash was made under, which a build compares with the apps' manifests:
+// SL_HASH_VERSION ${SL_HASH_VERSION}
 Shader "${name}"
 {
     Properties
@@ -99,7 +94,7 @@ ${props.join("\n")}
             #pragma fragment frag
             #pragma target 3.0
             #include "UnityCG.cginc"
-            // Shared with the VM, so both backends compute the same noise.
+            // Shared with the web frame, so every backend computes the same noise.
             #include "${include}"
 
 ${decls.join("\n")}
@@ -111,8 +106,8 @@ ${decls.join("\n")}
             {
                 v2f o;
                 o.pos = UnityObjectToClipPos(v.vertex);
-                // Origin corrected here exactly as the VM does it, so an ejected
-                // game is not upside down relative to the one on the site.
+                // Origin corrected here, so a Unity build is not upside down
+                // relative to the same program in a browser.
                 o.uv = float2(v.uv.x, lerp(v.uv.y, 1.0 - v.uv.y, _FlipY));
                 return o;
             }
@@ -130,7 +125,7 @@ ${body}
 
 /**
  * The frame's side of the body: OneJS's names for the inputs, a uniform's
- * material property, and `tex2D` on the slot's sampler. `sl_toLinear` stays a
+ * material property, and `tex2D` and `tex2Dlod` on the slot's sampler. `sl_toLinear` stays a
  * call because `SLCommon.cginc` decides Gamma or Linear per project, at the
  * shader compile, so this target always emits it.
  */
@@ -155,6 +150,7 @@ function unityTarget(p: Program): BodyTarget {
         },
         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}))`,
         colour: "linear",
         indent: "                ",
     }

package/src/index.ts

@@ -2,16 +2,14 @@
  * `onejs-sl`: the shader language, with no Unity in it.
  *
  * Source text or the TypeScript form in, a `Program` out: a flat typed graph
- * with a hash. Everything a host does with a program (run it on the VM, emit
- * HLSL, WGSL or GLSL ES) is a separate entry, so a host bundles only what it
+ * with a hash. Everything a host does with a program (emit HLSL, WGSL or GLSL
+ * ES) is a separate entry, so a host bundles only what it
  * calls:
  *
  *   onejs-sl             this: parse, diagnose, classify, fromGLSL, the TypeScript form, the IR, its JSON
  *   onejs-sl/core        the same without the parser, for a game at run time
  *   onejs-sl/tables      builtins, opcodes, inputs, shapes: what an editor reads
  *   onejs-sl/compile     what a host draws a program with, and no budget
- *   onejs-sl/limits      whether a program fits the VM, until the VM goes
- *   onejs-sl/vm          the VM encoder, until the VM goes
  *   onejs-sl/emit/unity  the ShaderLab shader a Unity editor generates
  *   onejs-sl/emit/web    WGSL and GLSL ES with OneJS's web frame
  *

package/src/ir.ts

@@ -1,9 +1,8 @@
 /**
- * The shader language IR: one graph, two consumers.
+ * The shader language IR: one graph, and every backend a function of it.
  *
- * Phase 1 of `Specs/SHADER_LANG.md` section 4. Everything the VM encoder and the
- * HLSL emitter do is a function of this shape, so it is the part worth getting
- * right before either exists.
+ * Phase 1 of `Specs/SHADER_LANG.md` section 4. Every emitter (HLSL, WGSL, GLSL
+ * ES) reads this shape and nothing else.
  *
  * Four properties are load bearing:
  *
@@ -12,7 +11,7 @@
  * produces the author facing type errors.
  *
  * **Nodes are a flat array in topological order.** A node refers to earlier
- * nodes by index only, never forwards, so an encoder can walk the array once and
+ * nodes by index only, never forwards, so an emitter can walk the array once and
  * emit in order. The hash deliberately does NOT depend on that order; see
  * `hashProgram`.
  *
@@ -21,8 +20,7 @@
  * pass. A tree would silently square the cost of the most natural way to write a
  * shader.
  *
- * **Nothing here knows about shaders.** No HLSL, no texture layout, no register
- * allocation. Those belong to the backends; this file is the contract between
+ * **Nothing here knows about shaders.** No HLSL, no texture layout, no binding. Those belong to the backends; this file is the contract between
  * them, and it is fully testable with no GPU.
  */
 
@@ -47,7 +45,7 @@ export type InputName = keyof typeof INPUTS
  * handed over by the host (`Specs/SL_NEXT.md` 6). Each read records the same
  * few nodes a program would if it wrote the expression out, and the builder's
  * hash consing makes every later read the same node. So there is no new
- * instruction, no VM or host change, and a program that never names one holds
+ * operation, no host change, and a program that never names one holds
  * no extra node, compiling to the bytes it always did.
  *
  *   texel     1 / resolution: one pixel, in uv
@@ -172,20 +170,11 @@ export interface TextureDecl {
     slot: number
 }
 
-/**
- * The nodes one `sl.repeat` call unrolled into, as the half open range
- * `[start, end)` of `nodes`. Diagnostic only: the instruction ceiling error
- * uses it to say which loop the operations came from, since a program that is
- * "too long" has usually been made so by one count.
- */
-export interface LoopSpan {
-    count: number
-    start: NodeRef
-    end: NodeRef
-}
-
 export interface Program {
-    /** The `SL_IR_VERSION` this program's nodes mean what they mean under. */
+    /**
+     * The `SL_IR_VERSION` this program's nodes mean what they mean under: the
+     * lowest one that has every node it holds. See `programVersion`.
+     */
     version: number
     nodes: SLNode[]
     /** Must be VEC4: a program produces a colour. */
@@ -194,16 +183,8 @@ export interface Program {
     textures: TextureDecl[]
     /** Canonical, stable across machines. See `hashProgram`. */
     hash: string
-    /** Not part of the hash: it changes nothing about what the program computes. */
-    loops: LoopSpan[]
 }
 
-/**
- * @deprecated Use `TEXTURE_SLOTS`. Was 15, the WebGL2 sampler count, which let a
- * program declare textures no native host binds.
- */
-export const MAX_TEXTURES = TEXTURE_SLOTS
-
 /**
  * The refusals for a program past its caps, worded once for the parser (a
  * `file`) and the builder (a `program`) so the two cannot drift apart.
@@ -232,7 +213,25 @@ export function checkCaps(p: Pick<Program, "uniforms" | "textures">): void {
     if (p.textures.length > TEXTURE_SLOTS) throw new SLError(tooManyTextures(p.textures.length, "program"))
 }
 
-/** Instructions a single program may hold. Generous; the ceiling that matters is registers. */
+/**
+ * The colour as written behind a colour value: the operand of the `TO_LINEAR`
+ * that reading a hex or a colour uniform applied, or null for a value computed
+ * in the working space. What a ramp's stop has to be, since a ramp blends its
+ * stops as written (`sl.ramp`).
+ */
+export function writtenColour(nodes: readonly SLNode[], ref: NodeRef): NodeRef | null {
+    const n = nodes[ref]!
+    if (n.k !== "call" || n.op !== SLOP.TO_LINEAR || (n.type !== TYPE.VEC3 && n.type !== TYPE.VEC4)) return null
+    return n.args[0]!
+}
+
+/** Why a computed value is not a ramp's stop, in one wording for both surfaces. */
+export const RAMP_STOP_COMPUTED =
+    "a ramp's stop is a colour as written: a hex like #ff8040, or a uniform or const that holds one. " +
+    "This one is computed, and a ramp blends its stops as written before it converts them, so it has " +
+    "no written colour to blend. Blend computed colours with lerp instead"
+
+/** Operations a single program may hold. Generous: a guard against a runaway builder, not a budget. */
 export const MAX_NODES = 4096
 
 export class SLError extends Error {
@@ -253,7 +252,6 @@ export class Builder {
     readonly nodes: SLNode[] = []
     readonly uniforms: UniformDecl[] = []
     readonly textures: TextureDecl[] = []
-    readonly loops: LoopSpan[] = []
     private readonly interned = new Map<string, NodeRef>()
 
     add(node: SLNode): NodeRef {
@@ -401,8 +399,7 @@ export function widthName(t: SLType): string {
  *
  * This is the link between a program and its compiled shader. If it differs
  * between the machine that generated the shader and the machine that runs it,
- * the runtime silently falls back to the VM and nobody is told, which is the
- * worst failure this design can have: correct output, quietly slow, no error.
+ * a native player finds no shader for the program and draws nothing.
  *
  * So it hashes the canonicalised node array and nothing else. Never object
  * identity, never insertion order of a Map, never a JSON stringify whose key
@@ -426,6 +423,13 @@ export function hashProgram(nodes: SLNode[], result: NodeRef, uniforms: UniformD
     // digests, so two graphs that compute the same thing agree however they were
     // assembled. It also ignores nodes not reachable from the result, which is
     // correct: dead nodes generate no shader code.
+    //
+    // NORMALISED, so two ways of writing one computation agree (hash version 2).
+    // A commutative op's operands are digested in sorted order, so `a + b` is
+    // `b + a`; and a swizzle of a constant is digested as the constant it picks,
+    // so `8 * uv` (8 broadcast by a swizzle) is `uv * 8` (a float2 constant).
+    // Only where every backend computes the same bits either way: min and max
+    // are left out, since which of -0 and +0 they return depends on the order.
     const digest = new Map<NodeRef, string>()
 
     const of = (ref: NodeRef): string => {
@@ -441,8 +445,19 @@ export function hashProgram(nodes: SLNode[], result: NodeRef, uniforms: UniformD
             // produce different shaders and must not share a hash. The names go
             // in separately below.
             case "uniform": body = `u:${n.slot}:${n.type}`; break
-            case "swizzle": body = `s:${of(n.src)}:${n.chans.join("")}`; break
-            case "call": body = `f:${n.op}:${n.args.map(of).join(",")}:${(n.imm ?? []).map(fixed).join(",")}`; break
+            case "swizzle": {
+                const src = nodes[n.src]!
+                body = src.k === "const"
+                    ? `c:${n.type}:${n.chans.map((c) => fixed(src.v[c]!)).join(",")}`
+                    : `s:${of(n.src)}:${n.chans.join("")}`
+                break
+            }
+            case "call": {
+                const args = n.args.map(of)
+                if (COMMUTATIVE.has(n.op)) args.sort()
+                body = `f:${n.op}:${args.join(",")}:${(n.imm ?? []).map(fixed).join(",")}`
+                break
+            }
         }
         const d = fnv1a(body + "|" + n.type)
         digest.set(ref, d)
@@ -450,12 +465,15 @@ export function hashProgram(nodes: SLNode[], result: NodeRef, uniforms: UniformD
     }
 
     // The IR version is in the hash, so a change to what an opcode means in the
-    // IR changes every hash and every cache keyed by one recompiles rather than
-    // serving the old maths. A change to the helper library alone (a noise's
-    // arithmetic, say) is not one: every host includes the library's text when
-    // it compiles, and none caches a compiled program by hash across a
-    // library update, so the new text reaches every shader without a bump.
-    const parts: string[] = [`v${SL_HASH_VERSION}:${SL_IR_VERSION}`, of(result)]
+    // IR changes the hash of every program using it, and every cache keyed by
+    // one recompiles rather than serving the old maths. It is the PROGRAM's
+    // version, the lowest that has its nodes, so a version that adds a node
+    // leaves every program without one on the hash it had. A change to the
+    // helper library alone (a noise's arithmetic, say) is not one: every host
+    // includes the library's text when it compiles, and none caches a compiled
+    // program by hash across a library update, so the new text reaches every
+    // shader without a bump.
+    const parts: string[] = [`v${SL_HASH_VERSION}:${programVersion(nodes)}`, of(result)]
     for (const u of uniforms) parts.push(`U:${u.name}:${u.type}:${u.value.map(fixed).join(",")}`)
     for (const t of textures) parts.push(`T:${t.name}:${t.slot}`)
     return fnv1a(parts.join("|"))
@@ -473,8 +491,79 @@ export function controlOf(c: UniformControl): UniformControl {
     return out
 }
 
-/** Bumped when the hashing scheme changes, which invalidates generated shaders. */
-export const SL_HASH_VERSION = 1
+/**
+ * The lowest `SL_IR_VERSION` that has every node here, and never below 2.
+ *
+ * A version that adds a node, or a form of one, raises only the programs that
+ * hold it. Everything else keeps the version, the hash and the JSON it had, so
+ * a program recorded before the bump still finds its shader, and a reader that
+ * predates the bump still reads it. Every node counts, used or not: the JSON
+ * carries them all, and an older reader has to refuse by the version rather
+ * than halfway through the nodes.
+ */
+export function programVersion(nodes: readonly SLNode[]): number {
+    let v = 2
+    for (const n of nodes) v = Math.max(v, nodeVersion(n))
+    return v
+}
+
+/**
+ * The version that added this node's form. An sdf or octave call with one
+ * operand is the form before IR 3, which only a file an older compiler wrote
+ * holds, and `fromJSON` moves it to the form IR 3 has.
+ */
+function nodeVersion(n: SLNode): number {
+    if (n.k !== "call") return 2
+    switch (n.op) {
+        case SLOP.SAMPLE_LOD: return 3
+        case SLOP.SDF:
+        case SLOP.FBM:
+        case SLOP.TURBULENCE:
+        case SLOP.RIDGED:
+            return n.args.length > 1 ? 3 : 2
+        default: return 2
+    }
+}
+
+/**
+ * What is wrong with a call's form, for the ops whose operand list alone does
+ * not say it, or null. The builder only makes the right ones; this is for a
+ * program read from JSON, which an emitter would otherwise print as something
+ * else.
+ *
+ *   SDF  the point, a float4 and a float2 holding the six shape parameters,
+ *        the shape id the one immediate
+ *   FBM, TURBULENCE, RIDGED  the point and the octave count, FBM's kind the
+ *        one immediate
+ */
+export function formProblem(n: Extract<SLNode, { k: "call" }>, nodes: readonly SLNode[]): string | null {
+    const widths = n.args.map((a) => nodes[a]!.type).join(",")
+    switch (n.op) {
+        case SLOP.SDF:
+            if (widths === "2,4,2" && n.imm?.length === 1) return null
+            return "an sdf takes a float2, a float4 and a float2, and its shape as the one immediate"
+        case SLOP.FBM:
+        case SLOP.TURBULENCE:
+        case SLOP.RIDGED: {
+            const rest = n.op === SLOP.FBM ? 1 : 0
+            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`
+        }
+        default:
+            return null
+    }
+}
+
+/** The ops whose two operands the hash takes in either order: exact in IEEE arithmetic on every backend. */
+const COMMUTATIVE = new Set<number>([SLOP.ADD, SLOP.MUL, SLOP.DOT, SLOP.DISTANCE])
+
+/**
+ * Bumped when the hashing scheme changes, which invalidates generated shaders.
+ *
+ *   1  the Merkle hash over the reachable graph
+ *   2  normalised: commutative operands in either order, a swizzle of a constant as the constant
+ */
+export const SL_HASH_VERSION = 2
 
 /**
  * Bumped whenever the IR changes in a way a reader has to know about: a new
@@ -491,13 +580,16 @@ export const SL_HASH_VERSION = 1
  * records it again, for no gain.
  *
  * A reader accepts every version up to its own and refuses a newer one with a
- * message naming both, the rule the particle wire and fx follow. Part of the
- * hash, so a bump recompiles every cached shader.
+ * message naming both, the rule the particle wire and fx follow. A program's
+ * version is the lowest that has its nodes (`programVersion`), and that is what
+ * its hash carries, so a bump rehashes only the programs using what it added.
  *
  *   1  the first versioned IR
  *   2  an SDF call carries up to six shape parameters, not four (#129)
+ *   3  SAMPLE_LOD; an SDF's shape parameters and a noise's octave count are
+ *      operands, where they were immediates
  */
-export const SL_IR_VERSION = 2
+export const SL_IR_VERSION = 3
 
 function fnv1a(s: string): string {
     let h = 0x811c9dc5

package/src/lang/README.md

@@ -28,12 +28,12 @@ const plasma = parse(source, { file: "plasma.sl" })
 written, and the two produce the same graph. `parity.test.ts` asserts that as
 hash equality for every GPU fixture and for the example on play.onejs.com: same
 hash means same generated shader and same pixels, established without rendering
-anything. It also means the existing GPU fixtures, the codegen goldens and the
-C# VM tests cover the text form for free, because they run on the IR.
+anything. It also means the existing GPU fixtures and the codegen goldens
+cover the text form for free, because they run on the IR.
 
 If that property ever breaks, the failure is silent in the worst way: a program
-whose hash does not match its generated shader falls back to the VM and nobody
-is told. So parity is the test to keep green, not the parser's unit tests.
+whose hash does not match its generated shader draws nothing in a native
+player. So parity is the test to keep green, not the parser's unit tests.
 
 | File | What it does |
 |---|---|
@@ -49,8 +49,8 @@ is told. So parity is the test to keep green, not the parser's unit tests.
 
 ## The loader
 
-`slPlugin()`, in onejs-unity's `onejs-unity/esbuild`, parses and encodes at BUILD TIME, so an import resolves to a small
-object of numbers and the bundle carries neither the parser nor the source. A
+`slPlugin()`, in onejs-unity's `onejs-unity/esbuild`, parses and compiles at BUILD TIME, so an import resolves to a small
+object of names, defaults and shader sources and the bundle carries neither the parser nor the source. A
 parse error becomes an esbuild error with the file, line and column, which the
 Play editor surfaces and every terminal editor links.
 
@@ -152,22 +152,18 @@ one the local does not have, is refused.
 
 ## Not yet spellable
 
-Three things the EDSL or the opcode table has and a file cannot say. Each is a
+Two things the EDSL or the opcode table has and a file cannot say. Each is a
 recorded gap, not an oversight, and each has its own error message rather than
 "unknown identifier".
 
 | | Why |
 |---|---|
-| `rgb2hsv`, `tex2Dlod` | The opcodes are numbered and **neither backend implements them**. Writing one would render as whatever the VM's dispatch falls through to and fail outright in the HLSL emitter. |
+| `rgb2hsv` | The opcode is numbered and **no backend implements it**; every emitter throws on it. |
 | `fbm`'s simplex base | `sl.fbm(p, octaves, "simplex")` picks the base with a string, and the language has no strings. `fbm(p, octaves)` is the value base, and `turbulence` and `ridged` are the simplex family. |
 
-Related, and worth knowing: **the EDSL lets a program declare 15 textures and
-the VM has 4.** `ir.ts` picked its ceiling from the WebGL2 sampler count rather
-than from `FxProgram.shader`, which declares `_Tex0` to `_Tex3` and samples
-`_Tex3` for every slot past it, so slots 4 and up are silently wrong in the
-browser and correct after an eject. A `.sl` file is held to the real number, 4,
-reported at the declaration. The EDSL's ceiling is untouched here because
-lowering it changes recorded behaviour rather than parser behaviour.
+A `.sl` file and the EDSL are held to the same caps, `UNIFORM_SLOTS` (16) and
+`TEXTURE_SLOTS` (4), reported at the declaration in one wording (`ir.ts`'s
+`tooManyUniforms` and `tooManyTextures`).
 
 ## Attributes