onejs-sl 0.6.0 → 0.8.0

package/CHANGELOG.md

@@ -1,5 +1,27 @@
 # Changelog
 
+## 0.8.0
+
+A fractional `tex2Dlod` level now blends the two levels either side on every backend. No existing program's hash changes, but a host now gets two whole-level samples and a blend where it got one fractional sample, so a host that blended levels itself would blend twice, which makes this a minor.
+
+- A fractional `tex2Dlod` level blends the two levels either side, whatever the texture's filter mode
+
+## 0.7.0
+
+A program can read what it drew the frame before, and count frames (`Specs/SL_NEXT.md` 4). Every existing program keeps its hash and its shader; one that reads the new names is IR 5. A host has to forward the new `reads` to draw such a program, which makes this a minor.
+
+- `previous`, the frame this program drew last, read as `tex2D(previous, uv)`; `previous.sample(uv)` in `sl.program`
+- `frame`, an int counting frames since `previous` was last cleared, and `deltaTime`, the seconds since the frame before
+- A file that already used one of the three names keeps its own
+- `readsOf(program)` and `compile(p).reads` say which of the three a host has to keep between frames
+- `BodyTarget` takes `inputs.frame`, `inputs.deltaTime` and `previous(uv)`, all optional; `emitBody` names the one a program needs and a target lacks
+- The Unity shader reads the step from `_Res.zw` and the previous frame from `_Prev`; the web frame from `sl_Res.w`, `sl_Opt.z` and its own binding
+- IR 5: `SAMPLE_PREVIOUS` and the two inputs
+- `fromGLSL` turns `iFrame` and `iTimeDelta` into `frame` and `deltaTime`
+- The goldens step the programs that read the three, and hold the history to the bit
+- The web emitters refuse an input they have no mapping for
+- The shipped source is typechecked against ES2020 with no Node types, which found the parser's `Array.prototype.at`
+
 ## 0.6.0
 
 An int uniform says it is one, and uint constants fold as int ones do. A `.sl` program whose uint constants now fold gets a new hash and shader, which a build regenerates; every other program keeps its hash and its shader, and a program built in code keeps both, since the fold is the `.sl` file's. That hash change and `sl.uniform.int` make this a minor.

package/README.md

@@ -27,6 +27,11 @@ const plasma = sl.program(({ uv, time }) => {
 })
 ```
 
+`npm install onejs-sl`. The package ships TypeScript source (its `exports`
+point at `src/*.ts`): bundle it (esbuild, Vite) or run it with a TypeScript
+loader (`npx tsx script.ts`). Plain `node` cannot load `.ts` from
+`node_modules`.
+
 ## Entry points
 
 `"sideEffects": false`, and each backend is its own entry, so a host bundles
@@ -43,7 +48,9 @@ only what it calls.
 | `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.
+[`src/entries.test.ts`](https://github.com/Singtaa/onejs-sl/blob/main/src/entries.test.ts)
+(in the repository, not the npm package) pins every name, since removing one
+breaks a host.
 
 ## A host's own frame: `emitBody`
 
@@ -54,13 +61,21 @@ intrinsic at its exact type, since Metal overloads where HLSL converts). The `Bo
 for each input, the float4 holding a uniform slot, a texture sample and a
 sample at a mip level (`sampleLevel`, for `tex2Dlod`), 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
+optionally a local to assign the result to. A host that steps a program frame
+by frame adds `frame` and `deltaTime` to its inputs and a `previous` read (below,
+"What a program is given"); a target without one cannot draw a program that
+reads it, and `emitBody` says which is missing rather than print a shader that
+stands still. It returns the uniform and texture
 slots the body uses and the library functions it calls. The sample's contract
 is on `BodyTarget.sample`: straight alpha in and out, rgb in the space `colour`
 names (an sRGB texture decoded before filtering when it is `linear`), and
 filtering and wrapping left to the host, which OneJS's hosts take from the
-bound texture's own settings. OneJS's Unity shader is
-one frame over it (`hlsl.ts`); Magerie's compute kernel is another, and its
+bound texture's own settings. Between mip levels the body decides instead: a
+fractional `tex2Dlod` level blends the two levels either side by the fraction,
+whatever the texture's filter mode, since the body asks for both whole levels
+and blends them itself. A level it can prove whole (a whole constant, a
+`floor`, an int) costs one sample, and a level past the smallest reads the
+smallest. 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.
 
@@ -83,7 +98,8 @@ program reads it as one, so a host shows a whole number field; a float uniform
 has no `kind`. Neither mark is in the hash, since the reads' conversion already
 is. `inputsUsed`
 says which inputs the result depends on, dead nodes aside, so a host knows
-whether a program animates.
+whether a program animates, and `readsOf` (also `compile(p).reads`) says which
+of the previous frame, `frame` and `deltaTime` it needs kept between frames.
 
 ## The helper library: one source
 
@@ -137,13 +153,23 @@ what a WebGL player draws.
 
 `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 seven anchors must match arithmetic, not each other:
+over every pixel, and eight anchors must match arithmetic, not each other:
 `orient.sl` (orientation, and the linear to sRGB store), `hex.sl` (a hex colour
-stores as written), `texture.sl` (a texture's orientation and sRGB decode) and
+stores as written), `texture.sl` (a texture's orientation and sRGB decode),
 `lod.sl` (each mip level `tex2Dlod` reads, the texture's smaller levels being
-solid colours). `sdf-values.sl`, `fbm-values.sl` and `ramp-values.sl` are black unless a
+solid colours) and `lod-frac.sl` (a fractional level blends the two levels
+either side, on a texture sampled nearest between levels). `sdf-values.sl`, `fbm-values.sl` and `ramp-values.sl` are black unless a
 shape, a noise or a ramp draws differently with its parameters as values than
 as constants.
+A fixture that reads the previous frame, `frame` or `deltaTime` is stepped
+instead of drawn at times: eight frames at 1/30 of a second, into an
+`rgba16float` history pair that starts clear, each frame then copied into the
+target as an element shows it. goldens.json holds its samples at frames 0, 1
+and 7, as shown and as the raw history. Three are anchors on the history, to
+the bit: `counter.sl` (a step taken twice, a missed swap or 8 bit history),
+`drift.sl` (the previous frame read upside down) and `frame-delta.sl` (`frame`
+and `deltaTime` as a host hands them over); `trail.sl` is the fading trail the
+docs show.
 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
@@ -156,7 +182,8 @@ bits per pixel, and `corpus/probe-hash.sl` does the same through a program;
 every pixel must match `goldens/reference.mjs`, which computes the hashes in
 JavaScript. goldens.json ships each probe under its name, as HLSL, WGSL and
 GLSL ES and with the bits it must draw, for a host to run on its own compiler,
-and marks the fixtures compared at 0/255 `exact`.
+and marks the fixtures compared at 0/255 `exact`, and the stepped fixtures
+whose history is compared to the bit `historyExact`.
 
 `npm run goldens -- --check` draws everything again and compares it with
 goldens.json instead of writing it: within 1/255, and exact fixtures and probes
@@ -170,9 +197,12 @@ hash fails there until the goldens are drawn again.
 The source reaches for no host API: no `fs`, `process`, `Buffer`,
 `TextEncoder`, `performance`, `structuredClone` or `Intl`. It runs in a
 browser (the Play editor's diagnostics), a Cloudflare worker (the Play build)
-and QuickJS (Magerie). Two checks hold it to that:
+and QuickJS (Magerie). Three checks hold it to that:
 
 - lint refuses those globals and any Node module in `src/`;
+- `npm run typecheck` also checks the shipped source alone against ES2020 with
+  no Node types (`tsconfig.lib.json`), since `@types/node` adds later methods
+  such as `Array.prototype.at`, which 0.5.0 used by mistake;
 - `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
@@ -225,8 +255,9 @@ drew what had no shader yet; OneJS 3.8 deleted it.) `hlsl.ts` feeds OneJS's
 draws a program asks the compiled program for its
 `hlsl` (a lazy getter, never read in Play), records it into
 `Assets/OneJS/Recorded.sl.json`, generates the shader and
-moves the live material onto it. `manifest()` is still there for an app that
-would rather write its programs out at build time.
+moves the live material onto it. `manifest()`, in `onejs-unity/sl` and
+`onejs-unity/sl/compiler` rather than this package, is still there for an app
+that 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
@@ -350,7 +381,9 @@ number. `fromJSON` moves an older file's immediates to operands. IR 4 added
 control flow (the `if` and `loop` nodes, a loop's `param`s and each result's
 `proj`) and int, uint and bool values (a node's `kind`). A program that uses
 none of them is still IR 3 and keeps its hash; one with an `if` statement is
-IR 4, since the statement is now a real branch rather than a select.
+IR 4, since the statement is now a real branch rather than a select. IR 5 added
+the previous frame (`SAMPLE_PREVIOUS`) and the `frame` and `deltaTime` inputs;
+a program that reads none of them keeps the version and the hash it had.
 
 ## Control flow
 
@@ -405,6 +438,25 @@ program that does not compiles to the bytes it always did, and a program with a
 `texel` of its own keeps it: a local, a parameter or a uniform of that name
 shadows the input.
 
+Three are for a program drawn frame after frame, and a host hands them over
+only to a program that reads them (`readsOf`):
+
+- `previous`, a texture: what this program drew the frame before, read as
+  `tex2D(previous, uv)`. It is the program's result exactly, linear and
+  straight alpha, kept at 16 bits a channel, filtered bilinear and clamped at
+  the edges, with one level (so `tex2Dlod` refuses it). A read at a pixel's own
+  `uv` is that pixel.
+- `frame`, an int: frames drawn since `previous` was last cleared, from 0.
+- `deltaTime`: seconds since the frame before, 0 on the first.
+
+A host advances a frame when it draws with `time` moved forward: the last
+result becomes `previous`, `frame` goes up by one and `deltaTime` is the step.
+A draw at the same time draws the same frame again. It clears (`previous`
+transparent black, `frame` and `deltaTime` 0) on the first draw, a new size, a
+new program, a seek and time going back, so `frame` is 0 exactly when
+`previous` is clear. A file that already used one of the three names for its
+own value, texture or function keeps it.
+
 Why `resolution` and `aspect` are the target's: a program is drawn with
 `Graphics.Blit` into the element's own render texture, and Unity sets `_ScreenParams` per camera and
 leaves it alone for a blit: reading it from a 64x256 target answers with the