onejs-sl 0.3.0 → 0.4.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "onejs-sl",
-  "version": "0.3.0",
+  "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",

package/src/body.ts

@@ -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 => {
@@ -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,6 +225,11 @@ 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(

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_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

@@ -15,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. */
@@ -74,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
@@ -123,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.
  */
@@ -148,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/ir.ts

@@ -171,7 +171,10 @@ export interface TextureDecl {
 }
 
 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. */
@@ -210,6 +213,24 @@ export function checkCaps(p: Pick<Program, "uniforms" | "textures">): void {
     if (p.textures.length > TEXTURE_SLOTS) throw new SLError(tooManyTextures(p.textures.length, "program"))
 }
 
+/**
+ * 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
 
@@ -402,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 => {
@@ -417,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)
@@ -426,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("|"))
@@ -449,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
@@ -467,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

@@ -152,13 +152,13 @@ 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 **no backend implements them**; every emitter throws on them. |
+| `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. |
 
 A `.sl` file and the EDSL are held to the same caps, `UNIFORM_SLOTS` (16) and

package/src/lang/builtins.ts

@@ -125,12 +125,10 @@ value(SLOP.LUMINANCE, 1, 1, (a) => sl.luminance(colourOperand("luminance", a[0]!
 value(SLOP.NOISE, 1, 1, (a) => sl.noise(point("noise", a[0]!) as never))
 value(SLOP.SIMPLEX, 1, 1, (a) => sl.simplex(point("simplex", a[0]!) as never))
 value(SLOP.VORONOI, 1, 1, (a) => sl.voronoi(point("voronoi", a[0]!) as never))
-// The octave count is an immediate, so it has to be a number at parse time.
-// `lower.ts` folds constants before it gets here and rejects anything else with
-// a message that says why, rather than letting this cast be the error.
-value(SLOP.FBM, 1, 2, (a) => sl.fbm(point("fbm", a[0]!) as never, octaves("fbm", a[1])))
-value(SLOP.TURBULENCE, 1, 2, (a) => sl.turbulence(point("turbulence", a[0]!) as never, octaves("turbulence", a[1])))
-value(SLOP.RIDGED, 1, 2, (a) => sl.ridged(point("ridged", a[0]!) as never, octaves("ridged", a[1])))
+// The octave count is 3 when left out, and may be a value (`sl.fbm` says how).
+value(SLOP.FBM, 1, 2, (a) => sl.fbm(point("fbm", a[0]!) as never, a[1] ?? 3))
+value(SLOP.TURBULENCE, 1, 2, (a) => sl.turbulence(point("turbulence", a[0]!) as never, a[1] ?? 3))
+value(SLOP.RIDGED, 1, 2, (a) => sl.ridged(point("ridged", a[0]!) as never, a[1] ?? 3))
 
 /** Every field is sampled at a float2. */
 function point(fn: string, v: Num): Val {
@@ -138,20 +136,10 @@ function point(fn: string, v: Num): Val {
 }
 
 special(SLOP.SAMPLE, 2, 2)
+special(SLOP.SAMPLE_LOD, 3, 3)
 special(SLOP.SDF, 1, 7)
 special(SLOP.RAMP, 3, 64)
 
-function octaves(fn: string, v: Num | undefined): number {
-    if (v === undefined) return 3
-    if (typeof v !== "number") {
-        throw new SLError(
-            `${fn}'s octave count is part of the operation, so it has to be a constant. ` +
-            `A uniform or a computed value cannot change how many octaves the shader runs.`,
-        )
-    }
-    return v
-}
-
 export const BUILTINS: Readonly<Record<string, Builtin>> = table
 
 /**

package/src/lang/check.ts

@@ -49,11 +49,15 @@ const DERIVED_NAMES = new Set(Object.keys(DERIVED_INPUTS))
  * The GLSL spellings whose HLSL name means the same wherever it is written, so
  * the hint can be a one click fix (`Specs/SL_NEXT.md` 5, Decision 1 A). The
  * rest of `SL_GLSL_HINT` gets the hint alone: `mod` floors where `%` truncates,
- * `ivec2` truncates where `float2` does not, `atan` is `atan2` only with two
- * arguments (handled at the call), and `textureLod` names a builtin that is not
- * implemented yet.
+ * `ivec2` truncates where `float2` does not, and `atan` is `atan2` only with two
+ * arguments (handled at the call).
  */
-const GLSL_RENAMES = new Set(["mix", "fract", "texture", "vec2", "vec3", "vec4", "gl_FragCoord", "iTime", "iResolution"])
+const GLSL_RENAMES = new Set([
+    "mix", "fract", "texture", "textureLod", "vec2", "vec3", "vec4", "gl_FragCoord", "iTime", "iResolution",
+])
+
+/** The builtins whose first argument is a texture, which is not a value anywhere else. */
+const SAMPLES = new Set(["tex2D", "tex2Dlod"])
 
 const rename = (from: string, to: string): SLFix => ({ title: `Replace ${from} with ${to}`, replacement: to })
 
@@ -427,7 +431,7 @@ export function check(unit: Unit, prelude: FuncDecl[], options: CheckOptions = {
                 if (textures.has(e.name)) {
                     fail(
                         `"${e.name}" is a texture, and a texture is only ever the first argument of ` +
-                        `tex2D. Write \`tex2D(${e.name}, uv)\``,
+                        `tex2D or tex2Dlod. Write \`tex2D(${e.name}, uv)\``,
                         e.pos, e.name.length,
                     )
                 }
@@ -458,9 +462,9 @@ export function check(unit: Unit, prelude: FuncDecl[], options: CheckOptions = {
                 // Only reached while collecting: the call was refused, and its
                 // arguments are separate questions, so a mistake inside one is
                 // not hidden by the call's own. `fract(uv * wrap)` is two
-                // mistakes. tex2D's first argument is the texture, which is a
-                // value only there.
-                const tex = e.callee.k === "ident" && e.callee.name === "tex2D"
+                // mistakes. A sample's first argument is the texture, which is
+                // not a value.
+                const tex = e.callee.k === "ident" && SAMPLES.has(e.callee.name)
                 for (const a of tex ? e.args.slice(1) : e.args) attempt(() => checkExpr(fn, a, scope))
                 return
             }
@@ -529,13 +533,22 @@ export function check(unit: Unit, prelude: FuncDecl[], options: CheckOptions = {
 
         const builtin = BUILTINS[n]
         if (builtin !== undefined) {
-            if (n === "tex2D") {
+            if (SAMPLES.has(n)) {
                 const [tex, ...rest] = e.args
+                // HLSL's own tex2Dlod packs the level into a float4 with the uv.
+                if (n === "tex2Dlod" && e.args.length === 2) {
+                    fail(
+                        "tex2Dlod takes the uv and the mip level separately, `tex2Dlod(t, uv, lod)`, " +
+                        "rather than HLSL's float4(uv, 0, lod)",
+                        e.pos,
+                    )
+                }
                 arity(e, n, builtin.min, builtin.max)
                 if (tex === undefined || tex.k !== "ident" || !textures.has(tex.name)) {
+                    const lod = n === "tex2Dlod" ? ", 0" : ""
                     fail(
-                        `tex2D samples a texture declared in this file, as in \`texture2D grain;\` ` +
-                        `then \`tex2D(grain, uv)\``,
+                        `${n} samples a texture declared in this file, as in \`texture2D grain;\` ` +
+                        `then \`${n}(grain, uv${lod})\``,
                         (tex ?? e).pos,
                     )
                 }

package/src/lang/glsl.ts

@@ -75,7 +75,7 @@ const GLSL_TYPES = new Set(["float", "int", "uint", "bool", "vec2", "vec3", "vec
 /** A straight rename, the meaning unchanged. */
 const RENAME: Record<string, string> = {
     vec2: "float2", vec3: "float3", vec4: "float4", mix: "lerp", fract: "frac",
-    texture: "tex2D", texture2D: "tex2D", iTime: "time", iGlobalTime: "time", gl_FragCoord: "fragCoord",
+    texture: "tex2D", texture2D: "tex2D", textureLod: "tex2Dlod", iTime: "time", iGlobalTime: "time", gl_FragCoord: "fragCoord",
 }
 
 /** A rename that changes what the value can hold, so it is said. */
@@ -101,7 +101,6 @@ const MISSING: Record<string, string> = {
     iChannelTime: "a texture has no time of its own",
     iChannelResolution: "a texture's size cannot be read yet",
     iSampleRate: "there is no audio",
-    textureLod: "tex2Dlod is not implemented yet; tex2D samples with the texture's own filtering",
     texelFetch: "a texture cannot be read without filtering yet",
     textureSize: "a texture's size cannot be read yet",
     dFdx: "there are no derivatives", dFdy: "there are no derivatives", fwidth: "there are no derivatives",

package/src/lang/lower.ts

@@ -32,7 +32,9 @@
  * than an optimisation.
  */
 
-import { controlProblem, DERIVED_INPUTS, INPUTS, type Program, type SLType, type UniformControl } from "../ir"
+import {
+    controlProblem, DERIVED_INPUTS, INPUTS, RAMP_STOP_COMPUTED, writtenColour, type Program, type SLType, type UniformControl,
+} from "../ir"
 import type { SlSdfKind } from "../shapes"
 import * as sl from "../sl"
 import type { Num, Val } from "../sl"
@@ -602,19 +604,7 @@ export function lower(checked: Checked, errors?: SLParseError[]): Program {
             if (typeof p === "number" || p.width !== 2) {
                 fail(`sdf.${shape} measures the distance to a point, so it takes a float2`, e.args[0]!.pos)
             }
-            const params: number[] = []
-            for (const a of e.args.slice(1)) {
-                const v = lowerExpr(a, scope)
-                if (typeof v !== "number") {
-                    fail(
-                        `sdf.${shape}'s shape parameters are part of the operation, so they have to ` +
-                        `be constants. A size that changes belongs on the point: scale or offset it ` +
-                        `before the call`,
-                        a.pos,
-                    )
-                }
-                params.push(v)
-            }
+            const params = e.args.slice(1).map((a) => lowerExpr(a, scope))
             return at(e.pos, () => sl.sdf(shape, p as never, params))
         }
 
@@ -624,29 +614,35 @@ export function lower(checked: Checked, errors?: SLParseError[]): Program {
             return construct(n as TypeName, e.args.map((a) => lowerExpr(a, scope)), e.pos)
         }
 
-        if (n === "tex2D") {
+        if (n === "tex2D" || n === "tex2Dlod") {
             const texName = (e.args[0] as Extract<Expr, { k: "ident" }>).name
             const tex = samplers.get(texName)!
             const uv = lowerExpr(e.args[1]!, scope)
             if (typeof uv === "number" || uv.width !== 2) {
-                fail("tex2D samples at a float2", e.args[1]!.pos)
+                fail(`${n} samples at a float2`, e.args[1]!.pos)
             }
-            return at(e.pos, () => tex.sample(uv as never) as unknown as Val)
+            if (n === "tex2D") return at(e.pos, () => tex.sample(uv as never) as unknown as Val)
+            const lod = lowerExpr(e.args[2]!, scope)
+            if (typeof lod !== "number" && lod.width !== 1) {
+                fail(`a mip level is one number, and this is a ${widthType(lod.width)}`, e.args[2]!.pos)
+            }
+            return at(e.pos, () => tex.sampleLevel(uv as never, lod) as unknown as Val)
         }
 
         if (n === "ramp") {
             const t = lowerExpr(e.args[0]!, scope)
-            const stops: string[] = []
-            for (const a of e.args.slice(1)) {
-                if (a.k !== "hex") {
-                    fail(
-                        "a ramp's stops are constants, written as colours: `ramp(t, #000018, #0080ff, " +
-                        "#ffffff)`. A stop that changes wants lerp between two uniforms instead",
-                        a.pos,
-                    )
+            // A hex stays the string it was, so a ramp of hexes is the program
+            // it always was. Anything else is a value, which has to be a colour
+            // as written (`sl.ramp` says why), a colour uniform say.
+            const stops = e.args.slice(1).map((a) => {
+                if (a.k === "hex") return a.hex
+                const v = lowerExpr(a, scope)
+                if (typeof v === "number" || v.width < 3) {
+                    fail(`a ramp's stop is a colour, a float3 or a float4, and this is a ${typeof v === "number" ? "float" : widthType(v.width)}`, a.pos)
                 }
-                stops.push(a.hex)
-            }
+                if (writtenColour(v.owner.nodes, v.ref) === null) fail(RAMP_STOP_COMPUTED, a.pos)
+                return v as never
+            })
             return at(e.pos, () => sl.ramp(t, stops) as unknown as Val)
         }
 

package/src/ops.ts

@@ -156,8 +156,10 @@ export const SL_ARITY: Record<number, number> = {
 
     [SLOP.RAMP]: -1, [SLOP.HSV2RGB]: 1, [SLOP.RGB2HSV]: 1, [SLOP.LUMINANCE]: 1, [SLOP.TO_LINEAR]: 1,
 
-    [SLOP.NOISE]: 1, [SLOP.SIMPLEX]: 1, [SLOP.FBM]: 1, [SLOP.SDF]: 1,
-    [SLOP.VORONOI]: 1, [SLOP.TURBULENCE]: 1, [SLOP.RIDGED]: 1,
+    // An SDF takes the point, or the point and its parameters as operands; an
+    // octave op the point, or the point and its count (`formProblem` in ir.ts).
+    [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,
 }
@@ -282,7 +284,6 @@ export const SL_HLSL: Record<number, SLSurface> = {
  */
 export const SL_UNIMPLEMENTED: Record<number, string> = {
     [SLOP.RGB2HSV]: "no backend has a case for it yet",
-    [SLOP.SAMPLE_LOD]: "no backend samples at an explicit LOD yet; use tex2D",
     [SLOP.REMAP]: "the surface form is a macro over arithmetic, so the opcode is unused",
 }
 

package/src/params.ts

@@ -54,6 +54,7 @@ const INTRINSIC: Record<string, readonly string[]> = {
     distance: ["x", "y"], dot: ["x", "y"], cross: ["x", "y"], reflect: ["i", "n"],
     lerp: ["x", "y", "s"], step: ["y", "x"], smoothstep: ["min", "max", "x"],
     tex2D: ["s", "t"],
+    tex2Dlod: ["s", "t", "lod"],
 }
 
 /**
@@ -161,6 +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.",
     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.",
 }