onejs-sl 0.1.0 → 0.1.2

package/CHANGELOG.md

@@ -1,5 +1,25 @@
 # Changelog
 
+## 0.1.2
+
+The helper library has one source, `lib/*.hlsl`, translated at build time into GLSL ES, WGSL and the shared subset and copied into OneJS as its `.cginc` files. The web draws exactly what it drew; the Unity shader's text changes where Metal needed it to, and draws the same.
+
+- `emitLibrary` prints the library functions a body calls, in the shared subset
+- `emitBody` prints no scalar swizzles, and types every literal and scalar it passes to an intrinsic
+- `atan2` of vectors is refused; no web backend compiled it
+- `onejs-sl/goldens.json` exports the goldens
+- The tests compile the shared subset as Metal on a Mac with Xcode
+
+## 0.1.1
+
+A host can now supply its own frame for a program's body and get goldens for the pictures it should draw. Nothing an existing program draws changes, and OneJS's generated Unity shader is byte for byte what 0.1.0 printed.
+
+- `onejs-sl/emit/hlsl-body`: `emitBody` and `BodyTarget`, the body in the HLSL and Metal shared subset
+- The Unity shader is printed through `emitBody`
+- `UniformDecl.colour` marks a uniform with a hex default, and `sl.uniform.colour` declares one
+- `inputsUsed` lists the inputs a program reads
+- `goldens/goldens.json`: every corpus fixture as a Linear game stores it, drawn by `npm run goldens`
+
 ## 0.1.0
 
 The shader language compiler as its own package, moved out of `onejs-unity` with its history and its tests. It behaves exactly as `onejs-unity` 0.5.15's `sl` did, at IR version 2 and VM wire version 2.

package/README.md

@@ -40,11 +40,100 @@ only what it calls.
 | `onejs-sl/tables` | `BUILTINS`, `SL_HLSL`, `INPUTS`, `SL_SDF_SHAPES`, `SL_SDF_PARAMS`: what completion and highlighting read |
 | `onejs-sl/limits` | `vmFit(program)`: whether the VM runs it, and why not, without encoding |
 | `onejs-sl/vm` | `encode`, `SL_WIRE_VERSION` |
-| `onejs-sl/emit/unity` | `emitShader`: the `.shader` a Unity editor generates |
+| `onejs-sl/emit/hlsl-body` | `emitBody`: a program as a function body for a host's own frame; `emitLibrary`: the library functions it calls |
+| `onejs-sl/emit/unity` | `emitShader`: the `.shader` a Unity editor generates, a frame over `emitBody` |
 | `onejs-sl/emit/web` | `emitWGSL`, `emitGLSL`: OneJS's web frame |
+| `onejs-sl/goldens.json` | the goldens (below), as data |
 
 `src/entries.test.ts` pins every name, since removing one breaks a host.
 
+## A host's own frame: `emitBody`
+
+`emitBody(program, target)` prints the body only: one local per node, in the
+HLSL and Metal shared subset (HLSL spelling, `fmod`, no `mul`, no `static`, no
+derivatives, no swizzle of a scalar, and every literal and scalar in an
+intrinsic at its exact type, since Metal overloads where HLSL converts). The `BodyTarget` says what differs between hosts: an expression
+for each input, the float4 holding a uniform slot, a texture sample, whether
+`toLinear` is real (`colour: "linear"`) or the identity (`"gamma"`), and
+optionally a local to assign the result to. It returns the uniform and texture
+slots the body uses and the library functions it calls. OneJS's Unity shader is
+one frame over it (`hlsl.ts`); Magerie's compute kernel is another, and its
+target is in `src/body.test.ts` so an opcode cannot change without the text
+Magerie compiles changing in front of a test.
+
+`emitLibrary(body.uses.helpers, colour)` prints the library functions the body
+calls, and everything they call, in the same subset and dependency order, with
+the colour branch asked for: the text a host puts ahead of its frame. It is a
+separate call because OneJS's own frame never needs it (the Unity shader
+includes `SLCommon.cginc`), and a bundle that prints only Unity shaders should
+not carry the library too. On a Mac with Xcode, `src/metal.test.ts` compiles
+the whole library and a body for every corpus program and every builtin at
+every width as Metal, behind the two defines a host's compatibility header
+supplies (`frac`, `lerp`).
+
+A uniform declared with a hex default (`uniform float4 tint = #ff8040;`), or
+with `sl.uniform.colour`, is marked `colour: true`: its value is sRGB as
+written, which is what a colour picker shows, and its reads convert. `inputsUsed`
+says which inputs the result depends on, dead nodes aside, so a host knows
+whether a program animates.
+
+## The helper library: one source
+
+Value and simplex noise, the octave kinds, voronoi, hsv2rgb, `toLinear` and the
+42 distance shapes are written once, in HLSL, in `lib/sdf2d.hlsl`,
+`lib/noise2d.hlsl` and `lib/common.hlsl`. Everything else is printed from them
+by `npm run lib`, and nobody edits the copies:
+
+- **OneJS's `.cginc` files** (`SDF2D`, `Noise2D`, `SLCommon` in
+  `Resources/OneJS/`) are the source with an include guard and a generated
+  header around it. The VM, the generated Unity shaders and `fx` include them.
+  `npm run lib` writes them when the package sits in the OneJS container.
+- **`src/lib/`**: `table.ts` (every function, its signature, what it calls, and
+  the shape table read from `sl_sdfDistance`'s switch), and the text of each
+  function as GLSL ES (`glsl.ts`), WGSL (`wgsl.ts`) and the shared subset
+  (`hlsl.ts`). The web emitters and `emitLibrary` take only what a program calls.
+
+`lib/translate.ts` does the printing, at build time only. It reads a subset of
+HLSL, listed at its top (functions, locals, `if`, bounded `for`, `switch`,
+intrinsics, `mul(v, float2x2(...))`, and one preprocessor switch,
+`UNITY_COLORSPACE_GAMMA`, which becomes the target's colour), and anything
+outside it is an error with a file and line rather than a guess. HLSL converts
+where GLSL, WGSL and Metal refuse, so it makes every conversion explicit first;
+the printers then differ in spelling, plus what WGSL lacks (overloading,
+ternaries, swizzle assignment, assignable parameters). On the web the colour
+switch stays a runtime branch on the frame's `opt.x`, since a web build does not
+know the project's colour space when it prints.
+
+`src/lib/lib.test.ts` regenerates everything and fails on any byte of
+difference, the `.cginc` copies included in the container, and OneJS's
+`SLSharedLibraryTests` checks them from the other side. What proves the
+translations draw the same picture: the goldens compile the whole library on
+WebGPU and WebGL2 and draw every fixture; OneJS's parity harness holds the web
+output to the VM; `SLSharedLibraryTests` draws every corpus program in Unity
+through `SLCommon.cginc` and through the translated shared subset and requires
+them to agree; and the Metal check above compiles the shared subset.
+
+## Goldens
+
+`goldens/goldens.json` is every corpus fixture drawn as a Linear OneJS game
+stores it: the package's WGSL and GLSL ES in OneJS's web frame, into an
+`rgba8unorm-srgb` target (the format the element's render texture has), read
+back raw, with no Unity, no UI Toolkit and no browser colour management. A
+second host's own backend is checked against it; OneJS's parity harness is what
+proves the web emitters equal the VM in the first place.
+
+`npm run goldens` draws it on WebGPU and WebGL2 in a Chrome with its own
+profile (set `CHROME` to choose one). The two backends must agree within 1/255
+over every pixel, and three anchors must match arithmetic, not each other:
+`orient.sl` (orientation, and the linear to sRGB store), `hex.sl` (a hex colour
+stores as written) and `texture.sl` (a texture's orientation and sRGB decode).
+The whole translated library must also compile on both backends, including
+the functions no fixture reaches. The file describes the sampling grid, the
+times and the texture every sampled slot gets. A host imports it as
+`onejs-sl/goldens.json`. No CI runner here has a GPU, so `src/goldens.test.ts` checks instead
+that the file still covers the corpus at today's hashes; a change that moves a
+hash fails there until the goldens are drawn again.
+
 ## Runs anywhere ES2020 runs
 
 The source reaches for no host API: no `fs`, `process`, `Buffer`,
@@ -56,7 +145,7 @@ and QuickJS (Magerie). Two checks hold it to that:
 - `npm run test:quickjs` bundles `quickjs/corpus.ts` as one ES2020 IIFE, the
   way Magerie bundles a script, runs it in QuickJS-ng and in a bare Node
   context, and fails unless the two results agree byte for byte. The corpus
-  parses, encodes, fits and emits every program in `quickjs/corpus/`, every
+  parses, encodes, fits and emits every program in `corpus/`, every
   shape at its full parameter count, and the error paths. `npm test` runs it
   after vitest.
 
@@ -90,8 +179,8 @@ would rather write its programs out at build time.
 
 **A third and fourth backend, for the browser.** A player cannot compile a
 shader, but the page it runs in can. `web.ts` prints every program as WGSL and
-as GLSL ES 3.00 (`weblib.ts` holds the noise, colour and 42 distance functions
-ported from `SLCommon.cginc`, `Noise2D.cginc` and `SDF2D.cginc`), and OneJS's
+as GLSL ES 3.00 (carrying the library functions it calls, translated from
+`lib/*.hlsl`), and OneJS's
 `Plugins/WebGL/OneJSSLWeb.jslib` compiles whichever one Unity's device speaks
 and draws it into the element's target in place of the VM. A `.sl` import
 carries both strings, printed at build time; an `encode()` result has them as
@@ -253,13 +342,13 @@ linear light. `sl.ramp` mixes its stops in sRGB, which is what reads as an even
 ramp, and converts the result once through `TO_LINEAR`; `sl.color("#hex")` is
 `parseColor` plus that conversion, and `sl.toLinear` is the conversion on its
 own for a vec4 built from raw components. Both backends implement it gamma
-aware (`sl_toLinear` in `SLCommon.cginc`), so a Gamma project gets the value as
-written. Alpha is coverage and is never converted. Same rule as `fx`.
+aware (`sl_toLinear` in `lib/common.hlsl`), so a Gamma project gets the value
+as written. Alpha is coverage and is never converted. Same rule as `fx`.
 
 ## Noise
 
 `sl.noise`, `sl.simplex`, `sl.fbm(p, octaves, base)`, `sl.turbulence` and
-`sl.ridged` are the fields `fx.noise` draws, from the same `Noise2D.cginc`, so
+`sl.ridged` are the fields `fx.noise` draws, from the same `lib/noise2d.hlsl`, so
 a simplex here is the simplex there. Octaves are 1 to 4. A program has no seed;
 offset the input for a different field. `sl.simplex` used to be value noise on
 a rotated lattice, and `sl.fbm` had its own value noise; both changed on