onejs-sl 0.1.1 → 0.1.3

package/src/params.ts

@@ -0,0 +1,113 @@
+/**
+ * Parameter names, for an editor's completions and signature help: so it can
+ * offer `lerp(x, y, s)` rather than "lerp takes 3 arguments".
+ *
+ * Metadata only. Nothing that checks or emits a program reads this file, and
+ * only `onejs-sl/tables` imports it, so it cannot change what any program
+ * compiles to. Each table is built by a call marked pure, so a bundle that
+ * imports `onejs-sl/tables` for BUILTINS alone (the Play editor's parser) drops
+ * all of it.
+ *
+ * The intrinsics carry the names the HLSL documentation gives them. Everything
+ * the library implements is named as `lib/*.hlsl` writes it, read by the
+ * translator into `src/lib/names.ts` when `npm run lib` runs, so there is no
+ * second list of those to drift: a builtin that lowers to a library helper takes
+ * that helper's names, and a shape's parameters are named after its function's
+ * parameters, in the slots `sl_sdfDistance` passes them in.
+ */
+
+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"
+
+/** One function of the helper library, as its source declares it. */
+export interface LibSignature {
+    name: string
+    params: ReadonlyArray<{ name: string; type: string }>
+    ret: string
+}
+
+/** Every function in the helper library, by `LIB_FUNCTIONS` index, overloads included. */
+export const LIB_SIGNATURES: readonly LibSignature[] = /* @__PURE__ */ LIB_FUNCTIONS.map((f, i) => ({
+    name: f.name,
+    params: f.params.map((type, j) => ({ name: LIB_PARAM_NAMES[i]![j]!, type })),
+    ret: f.ret,
+}))
+
+/** A library function's parameter names, the same for every overload of it. */
+function namesOf(fn: string): readonly string[] {
+    const found = LIB_SIGNATURES.filter((s) => s.name === fn).map((s) => s.params.map((p) => p.name).join(", "))
+    if (found.length === 0) throw new Error(`the library has no ${fn}`)
+    if (new Set(found).size > 1) throw new Error(`${fn}'s overloads name their parameters differently: ${found.join(" / ")}`)
+    return found[0]!.split(", ")
+}
+
+/** The HLSL documentation's names. */
+const INTRINSIC: Record<string, readonly string[]> = {
+    sin: ["x"], cos: ["x"], tan: ["x"], asin: ["x"], acos: ["x"], exp: ["x"], log: ["x"], sqrt: ["x"],
+    sign: ["x"], ceil: ["x"], round: ["x"], abs: ["x"], floor: ["x"], frac: ["x"], saturate: ["x"],
+    rcp: ["x"], normalize: ["x"], length: ["x"],
+    pow: ["x", "y"], min: ["x", "y"], max: ["x", "y"], clamp: ["x", "min", "max"], atan2: ["y", "x"],
+    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"],
+}
+
+/**
+ * The library helper each builtin lowers to (`emitBody` calls it, and a test
+ * checks that it does), and how many of its parameters an author writes: fbm's
+ * third, the kind, is the opcode's own.
+ */
+export const LIBRARY: Readonly<Record<string, [string, number]>> = {
+    toLinear: ["sl_toLinear", 1], hsv2rgb: ["sl_hsv2rgb", 1], luminance: ["sl_luminance", 1],
+    noise: ["sl_valueNoise", 1], simplex: ["sl_simplex", 1], voronoi: ["sl_voronoi", 1],
+    fbm: ["sl_fbm", 2], turbulence: ["sl_fbm", 2], ridged: ["sl_fbm", 2],
+    // The point; the shape's own parameters are SL_SDF_PARAM_NAMES.
+    sdf: ["sl_sdfDistance", 0],
+}
+
+/** The two the language defines itself, named as the EDSL's `sl.remap` and `sl.ramp` name theirs. */
+const MACRO: Record<string, readonly string[]> = {
+    remap: ["v", "fromMin", "fromMax", "toMin", "toMax"],
+    // At least two stops, and as many more as `max` allows.
+    ramp: ["t", "stop", "stop..."],
+}
+
+/**
+ * Each builtin's parameter names, one per argument up to its `max`; those past
+ * its `min` are optional. A name ending in `...` repeats up to `max`. `sdf` is
+ * written `sdf.circle(p, r)`: its entry names the point, and the shape's own
+ * parameters are `SL_SDF_PARAM_NAMES[shape]`.
+ */
+export const BUILTIN_PARAMS: Readonly<Record<string, readonly string[]>> = /* @__PURE__ */ Object.fromEntries(
+    Object.keys(BUILTINS).map((name) => {
+        const lib = LIBRARY[name]
+        if (name === "sdf") return [name, [namesOf(lib![0])[1]!]]
+        const names = INTRINSIC[name] ?? MACRO[name] ?? (lib && namesOf(lib[0]).slice(0, lib[1]))
+        if (names === undefined) throw new Error(`builtin ${name} has no parameter names in params.ts`)
+        return [name, names]
+    }),
+)
+
+/**
+ * Each shape's parameters, in the order `sdf.<shape>(p, ...)` takes them, named
+ * after its function's: a vector parameter's components as `b.x`, `b.y`.
+ */
+export const SL_SDF_PARAM_NAMES: Readonly<Record<SlSdfKind, readonly string[]>> = /* @__PURE__ */ shapeNames()
+
+function shapeNames(): Record<SlSdfKind, readonly string[]> {
+    const out = {} as Record<SlSdfKind, readonly string[]>
+    for (const shape of Object.keys(SL_SDF_SHAPES) as SlSdfKind[]) {
+        const call = SDF_CALLS[SL_SDF_SHAPES[shape]]!
+        // The function's first parameter is the point, which `sl_sdfDistance` passes itself.
+        const fn = namesOf(call.fn).slice(1)
+        const slots = new Array<string>(SL_SDF_PARAMS[shape])
+        call.args.forEach((arg, i) => {
+            const at = "int" in arg ? [arg.int] : arg
+            at.forEach((slot, j) => { slots[slot] = at.length === 1 ? fn[i]! : `${fn[i]}.${"xyzw"[j]}` })
+        })
+        out[shape] = slots
+    }
+    return out
+}

package/src/shapes.ts

@@ -12,8 +12,8 @@
  *
  * Duplicating and pinning is the trade this repository already makes for the
  * painter and particle opcode tables, and for the SDF dispatcher that exists in
- * both FxSources and SLCommon. The ids are a contract with SDF2D.cginc either
- * way; what matters is that a test fails when they drift, not that there is
+ * both FxSources and SLCommon. The ids are a contract with `lib/sdf2d.hlsl`
+ * (SDF2D.cginc in OneJS) either way; what matters is that a test fails when they drift, not that there is
  * only one copy.
  */
 export const SL_SDF_SHAPES = {
@@ -30,8 +30,8 @@ export const SL_SDF_SHAPES = {
 export type SlSdfKind = keyof typeof SL_SDF_SHAPES
 
 /**
- * How many parameters each shape reads, in the order SDF2D.cginc takes them
- * (its `a` then `b`). Six shapes take more than four: roundedBox's last two
+ * How many parameters each shape reads, in the order `sl_sdfDistance` in
+ * `lib/common.hlsl` takes them (its `a` then `b`). Six shapes take more than four: roundedBox's last two
  * corner radii, orientedBox's thickness, triangle's third vertex, horseshoe's
  * second width, orientedVesica's width and bezier's end point. `sl.sdf` takes
  * up to this many, and a test derives the same counts from the web emitters'

package/src/sl.ts

@@ -461,6 +461,14 @@ function difference(a: Num, b: Num): Num {
 
 export function atan2(y: Num, x: Num): Float {
     const b = ctx()
+    // An angle is one number. Given vectors, the node would still be a float
+    // and every backend would disagree about which lane it kept: HLSL takes
+    // .x silently, GLSL and WGSL refuse to compile.
+    for (const v of [y, x]) {
+        if (typeof v !== "number" && v.width !== 1) {
+            throw new SLError(`atan2 takes two floats, and this is a ${v.width === 2 ? "float2" : v.width === 3 ? "float3" : "float4"}: call it per component`)
+        }
+    }
     const yy = typeof y === "number" ? float(y) : y
     const [a, c] = align2(yy as Val, x)
     return mk(b, b.call(SLOP.ATAN2, TYPE.FLOAT, [a, c]), TYPE.FLOAT)
@@ -622,7 +630,7 @@ export function ramp(t: Num, stops: Array<string | [number, number, number, numb
  * fifth and sixth.
  *
  * Which parameters a shape takes is the shape's own business; `circle` wants a
- * radius, `roundedBox` wants half extents and a corner. See SDF2D.cginc.
+ * radius, `roundedBox` wants half extents and a corner. See `lib/sdf2d.hlsl`.
  */
 export function sdf(kind: SlSdfKind, p: Vec2, params: number[] = []): Float {
     const id = SL_SDF_SHAPES[kind]

package/src/tables.ts

@@ -2,7 +2,8 @@
  * `onejs-sl/tables`: what completion and highlighting read.
  *
  * The same tables the checker and the emitters use, so an editor offers
- * exactly the builtins that compile, with the arities they take.
+ * exactly the builtins that compile, with the arities they take and the names
+ * of their parameters (`params.ts`), and the helper library's signatures.
  */
 export { BUILTINS, NOT_YET } from "./lang/builtins"
 export type { Builtin } from "./lang/builtins"
@@ -12,4 +13,6 @@ export {
 export type { SLSurface } from "./ops"
 export { INPUTS } from "./ir"
 export { SL_SDF_SHAPES, SL_SDF_PARAMS } from "./shapes"
+export { BUILTIN_PARAMS, LIB_SIGNATURES, SL_SDF_PARAM_NAMES } from "./params"
+export type { LibSignature } from "./params"
 export type { SlSdfKind } from "./shapes"

package/src/web.ts

@@ -26,8 +26,10 @@
  */
 
 import { SLError, TYPE, type Program, type SLNode, type SLType } from "./ir"
+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, VM_UNIFORMS } from "./ops"
-import { SDF_CALLS, WEB_LIB } from "./weblib"
 
 export type WebLanguage = "glsl" | "wgsl"
 
@@ -44,7 +46,8 @@ export function emitWGSL(p: Program): string {
 
 function emitWeb(p: Program, lang: WebLanguage): string {
     const W = lang === "wgsl"
-    const need = new Set<string>()
+    const need = new Set<number>()
+    const smoothsteps = new Set<SLType>()
     const sampled = new Set<number>()
     const lines: string[] = []
     const emitted = new Set<number>()
@@ -100,7 +103,13 @@ function emitWeb(p: Program, lang: WebLanguage): string {
         const s = n.args.map((r) => splat(r, t))
         const w0 = n.args.length > 0 ? typeOf(n.args[0]) : 1
         const imm = n.imm ?? []
-        const lib = (name: string) => { need.add(name); return name }
+        /** A library function by name, and by HLSL parameter types where it is overloaded. */
+        const lib = (name: string, params?: string[]) => {
+            const i = libIndex(name, params)
+            need.add(i)
+            return W ? LIB_FUNCTIONS[i]!.wgsl : name
+        }
+        const hlslType = (w: SLType) => (w === 1 ? "float" : `float${w}`)
         switch (n.op) {
             case SLOP.COMPOSE: return t === 1 ? a[0] : `${T(t)}(${a.join(", ")})`
 
@@ -145,11 +154,11 @@ function emitWeb(p: Program, lang: WebLanguage): string {
                 ? `(${a[0]} - 2.0 * ${a[1]} * ${a[0]} * ${a[1]})`
                 : `reflect(${a[0]}, ${a[1]})`
             case SLOP.LUMINANCE: return `dot(${a[0]}.rgb, ${T(3)}(0.2126, 0.7152, 0.0722))`
-            case SLOP.TO_LINEAR: return `${lib(`sl_toLinear${t}`)}(${a[0]})`
+            case SLOP.TO_LINEAR: return `${lib("sl_toLinear", [hlslType(t)])}(${a[0]})`
 
             case SLOP.MIX: return `mix(${s[0]}, ${s[1]}, ${s[2]})`
             case SLOP.STEP: return `step(${s[0]}, ${s[1]})`
-            case SLOP.SMOOTHSTEP: return `${lib(`sl_smoothstep${t}`)}(${s[0]}, ${s[1]}, ${s[2]})`
+            case SLOP.SMOOTHSTEP: smoothsteps.add(t); return `sl_smoothstep${t}(${s[0]}, ${s[1]}, ${s[2]})`
             // As the VM and the HLSL emitter do it: branchless, so every
             // backend agrees on the edge value.
             case SLOP.SELECT: {
@@ -158,8 +167,8 @@ function emitWeb(p: Program, lang: WebLanguage): string {
             }
 
             case SLOP.HSV2RGB: return `${lib("sl_hsv2rgb")}(${a[0]})`
-            case SLOP.NOISE: return `${lib("oj_vnoise")}(${a[0]}, 0.0)`
-            case SLOP.SIMPLEX: return `${lib("oj_simplex")}(${a[0]}, 0.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])
@@ -177,32 +186,36 @@ function emitWeb(p: Program, lang: WebLanguage): string {
                 )
         }
 
-        /** Noise2D.cginc's onejsFbmKind, resolved here since the kind is a constant. */
+        /**
+         * 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.
+         */
         function octaveCall(kind: number, pt: string, octaves: number | undefined): string {
             const o = Math.min(4, Math.max(1, Math.round(octaves ?? 3)))
-            const fn = kind === 2 ? "oj_turbulence" : kind === 3 ? "oj_ridged" : kind === 1 ? "oj_fbmSimplex" : "oj_fbm"
-            return `${lib(fn)}(${pt}, 0.0, ${o})`
+            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 shape is a constant, so this calls it directly instead of SLCommon's switch. */
+        /** 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 {
             const shape = SDF_CALLS[id]
-            // SLCommon's dispatcher returns 1e6 for an id it does not know.
+            // sl_sdfDistance returns 1e6 for an id it does not know.
             if (shape === undefined) return lit(1e6)
-            lib(shape.fn)
+            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 (!Array.isArray(arg)) return String(Math.trunc(v[arg.int]))
+                if ("int" in arg) return String(Math.trunc(v[arg.int]))
                 const parts = arg.map((i) => lit(v[i]))
                 return parts.length === 1 ? parts[0] : `${T(parts.length as SLType)}(${parts.join(", ")})`
             })
-            return `${shape.fn}(${[pt, ...args].join(", ")})`
+            return `${fn}(${[pt, ...args].join(", ")})`
         }
     }
 
     walk(p.result)
     const body = lines.join("\n")
-    const library = librarySource(need, lang)
+    const library = [...[...smoothsteps].sort().map((w) => smoothstep(w, lang)), ...librarySource(need, lang)].join("\n")
     const header = `// GENERATED from a shader language program (${p.hash}). Do not edit.`
     // Only the textures the program samples. WebGPU's automatic layout leaves
     // out a binding the shader never reads, and a bind group that supplies one
@@ -251,19 +264,31 @@ ${body}
 `
 }
 
-/** The needed entries and everything they depend on, in library order. */
-function librarySource(need: Set<string>, lang: WebLanguage): string {
-    const want = new Set<string>()
-    const byName = new Map(WEB_LIB.map((e) => [e.name, e]))
-    const add = (name: string) => {
-        if (want.has(name)) return
-        const entry = byName.get(name)
-        if (entry === undefined) throw new SLError(`internal: the web library has no entry "${name}"`)
-        want.add(name)
-        for (const d of entry.deps) add(d)
+/** The needed library functions and everything they call, in library order. */
+function librarySource(need: Set<number>, lang: WebLanguage): string[] {
+    const texts = lang === "wgsl" ? LIB_WGSL : LIB_GLSL
+    return libClosure(need).map((i) => texts[i]!.trim())
+}
+
+/**
+ * HLSL's smoothstep is the formula whatever the edge order; GLSL leaves
+ * edge0 >= edge1 undefined, so the web writes the formula out. This belongs
+ * to the web frame rather than the library: the HLSL backends call the
+ * intrinsic, which already means this.
+ */
+function smoothstep(w: SLType, lang: WebLanguage): string {
+    if (lang === "glsl") {
+        const g = w === 1 ? "float" : `vec${w}`
+        return `${g} sl_smoothstep${w}(${g} a, ${g} b, ${g} x) {
+    ${g} t = clamp((x - a) / (b - a), 0.0, 1.0);
+    return t * t * (3.0 - 2.0 * t);
+}`
     }
-    for (const n of need) add(n)
-    return WEB_LIB.filter((e) => want.has(e.name)).map((e) => (lang === "wgsl" ? e.wgsl : e.glsl).trim()).join("\n")
+    const t = w === 1 ? "f32" : `vec${w}f`
+    return `fn sl_smoothstep${w}(a: ${t}, b: ${t}, x: ${t}) -> ${t} {
+    let t = saturate((x - a) / (b - a));
+    return t * t * (3.0 - 2.0 * t);
+}`
 }
 
 /** A literal that survives a float32 round trip and never reads as an int. */