onejs-sl 0.3.0 → 0.5.0

package/CHANGELOG.md

@@ -1,5 +1,34 @@
 # Changelog
 
+## 0.5.0
+
+Real control flow: an `if` runs only the side it picks, a loop that cannot unroll runs as a loop, and `int`, `uint` and `bool` are types. A program with an `if` statement gets a new hash, which a build regenerates; every other program keeps its hash and its shader.
+
+- `if` is a real branch, and `return` works anywhere
+- `while`, `break`, `continue` and `switch`; a case never falls through
+- A `for` unrolls when its turns are known, 64 or fewer, and nothing leaves early; any other loop is real, with a turn limit
+- `int`, `uint` and `bool`; two ints divide toward zero; bit operators and `5u` literals
+- Braces on their own are a block with its own scope
+- A local declared without a value holds zero
+- `sl.branch` and `sl.loop` record control flow from code
+- IR 4: `if`, `loop`, `param` and `proj` nodes and int, uint and bool values; a program without them stays IR 3
+- `fromGLSL` keeps `int`, `uint` and `bool`
+
+## 0.4.0
+
+Every hash changes once, so a program built in code is recorded again: run the app in the editor once, then build. A program from a `.sl` file needs only the app rebuilt. A host reading programs as JSON reads 0.3.0's files as before.
+
+- Every hash changes once: `a + b` and `b + a` share one, as do `8 * uv` and `uv * 8` (`SL_HASH_VERSION` 2)
+- A generated shader names its hash scheme on a line of its own (`// SL_HASH_VERSION 2`); `SL_HASH_VERSION` is exported from `onejs-sl/core`
+- `tex2Dlod(t, uv, lod)` samples a mip level; `sampleLevel` on `sl.texture`
+- `BodyTarget.sampleLevel` is required, for `tex2Dlod`
+- `fromGLSL` turns `textureLod` into `tex2Dlod`
+- A shape's parameters may be any value, a uniform included; a vector counts as its components
+- `fbm`, `turbulence` and `ridged` take an octave count that is a value, rounded and held to 1 to 4
+- IR 3: a shape's parameters and an octave count are always operands; `fromJSON` migrates an older file
+- `toJSON` writes the hash scheme (`h`), so `fromJSON` rehashes a file an older scheme wrote instead of refusing it
+- A ramp's stop may be a colour uniform or a const holding a hex, as well as a hex
+
 ## 0.3.0
 
 The VM is gone: every program is compiled, so there is no instruction buffer, wire version or VM limit left to import. A host on `compile` changes nothing; one still importing `onejs-sl/vm` or `onejs-sl/limits` moves to `onejs-sl/compile` and `onejs-sl/core`.

package/README.md

@@ -51,7 +51,8 @@ only what it calls.
 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
+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
 slots the body uses and the library functions it calls. The sample's contract
@@ -131,9 +132,13 @@ 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 three anchors must match arithmetic, not each other:
+over every pixel, and seven 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).
+stores as written), `texture.sl` (a texture's orientation and sRGB decode) and
+`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
+shape, a noise or a ramp draws differently with its parameters as values than
+as constants.
 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
@@ -305,7 +310,11 @@ So it is a Merkle hash over the graph reachable from the result, not a walk of
 the node array. An earlier version hashed storage order, which meant hoisting a
 shared subexpression into a `const` changed the hash without changing what the
 program computed. Constants go through a fixed precision, so `0.1 + 0.2` and
-`0.3` do not produce different shaders. It is eight lowercase hex characters
+`0.3` do not produce different shaders. It is normalised, so two ways of
+writing one computation share a hash: `a + b` and `b + a` (and `*`, `dot`,
+`distance`), and `8 * uv`, whose 8 is a broadcast, and `uv * 8`, whose 8 is a
+float2. `min` and `max` keep their order, since which of -0 and +0 they return
+depends on it. It is eight lowercase hex characters
 from FNV-1a, chosen so a C# implementation can produce the same string rather
 than for any cryptographic reason.
 
@@ -314,35 +323,62 @@ than for any cryptographic reason.
 Two numbers, with one rule: a reader accepts every version up to its own and
 refuses a newer one with a message naming both.
 
-- **`SL_IR_VERSION`** (`ir.ts`) is on every `Program` and in the hash, and is
-  bumped whenever an opcode, a shape or what one computes changes. Because it
-  is in the hash, a bump recompiles every cached shader. `toJSON` and
-  `fromJSON` (`serial.ts`) are the IR as JSON for a host that stores programs;
-  `fromJSON` checks everything an emitter relies on, refuses a newer version,
-  and migrates an older one.
+- **`SL_HASH_VERSION`** (`ir.ts`) is bumped when the hashing scheme changes,
+  which changes every hash. 2 is the normalised hash above. `toJSON` writes it
+  beside the hash, and `fromJSON` checks a file's hash only when it was written
+  under the same scheme and IR version, and otherwise rehashes it.
+
+- **`SL_IR_VERSION`** (`ir.ts`) is bumped whenever an opcode, a shape or what
+  one computes changes. A program carries the lowest version that has all its
+  nodes (`programVersion`), and that is what its hash carries, so a bump
+  rehashes only the programs using what it added: every other program keeps
+  the hash its shader was recorded under. `toJSON` and `fromJSON`
+  (`serial.ts`) are the IR as JSON for a host that stores programs; `fromJSON`
+  checks everything an emitter relies on, refuses a newer version, and
+  migrates an older one.
 IR 2 came with #129. A shape takes as many parameters as it reads
 (`SL_SDF_PARAMS`, six at most, and never fewer than four accepted), where it
-used to take four and lose the rest.
+used to take four and lose the rest. IR 3 added `SAMPLE_LOD`, and made an
+SDF's shape parameters and a noise's octave count operands, where they were
+immediates, so they can be any value; a constant one still prints as its
+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.
 
 ## Control flow
 
-There is none in the IR, deliberately. `sl.select`, `sl.step`, `sl.smoothstep` and
-`sl.mix` cover branching without branching, and `sl.repeat(n, body, seed)`
-unrolls at record time because `n` is a JavaScript number.
-
-`repeat` is honest about being a macro rather than a loop. It covers fbm,
-layered noise and small iterated distance fields, which is most of what 2D
-shaders loop for. A loop with a runtime count is `Specs/SL_NEXT.md` proposal
-3b. Because it unrolls, the count multiplies the body's operation count.
-`compile` has no ceiling, so a long program costs what it costs, as any shader
-does; `corpus/long.sl` is over a thousand operations.
-
-Every loop that reaches a GPU is therefore bounded by a constant: `repeat` is
-unrolled, fbm's octaves are a constant 1 to 4, the helper loops in the noise
-and Voronoi functions have fixed trip counts. No program can hang a GPU today,
-so the compiled backends carry no loop cap. A data dependent loop (the
-raymarching tier) would need one emitted into every loop it prints, since a GPU
-reset takes the whole page's device, Unity's included.
+IR 4 has it: an `if` node runs one of its two regions and gives back their
+results, and a `loop` node carries its values through turns while its
+condition holds. `sl.branch(cond, whenTrue, whenFalse)` and
+`sl.loop(init, cond, body, max)` record them, and the text form lowers `if`,
+`for`, `while`, `break`, `continue`, `switch` and a `return` anywhere onto the
+two (`src/lang/lower.ts` says how: a return or break that only some ways
+through reach is a flag, and what follows runs under a branch on it). No
+emitter ever prints a statement that returns or breaks from inside a region;
+every one prints the same structured body.
+
+`structure.ts` decides where each node is computed: in the innermost region
+every use of it is inside. A value only a branch needs is computed only when
+the branch runs, one only a loop's body reads is computed each turn, and one
+needed on both sides is computed once, before either. It also marks the
+regions whose flow differs between neighbouring pixels, where a texture
+sample has no neighbours to take its mip level from; every emitter samples
+level 0 there, so every backend draws the same picture.
+
+A `for` in the text form still unrolls when its turns are known, are 64 or
+fewer, and nothing in it leaves early, and `sl.repeat(n, body, seed)` still
+unrolls at record time because `n` is a JavaScript number. Everything else is
+a real loop.
+
+Every real loop has a turn limit, `max`, emitted into the loop itself: the
+count a constant bound gives, the `[Range]` maximum of a uniform bound, or
+1024 when the bound says neither. A loop that reaches it leaves as if its
+condition had failed. That is what keeps a data dependent loop, a ray march
+say, from hanging a GPU, whose reset takes the whole page's device, Unity's
+included. `Tools/sl-loop-timing` in the container times a loop that breaks
+early against the same maths unrolled, on each backend.
 
 ## See also
 
@@ -408,6 +444,12 @@ own for a vec4 built from raw components. Both backends implement it gamma
 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`.
 
+A ramp's stop can also be a colour value that was written as one: a colour
+uniform, or a const holding a hex. The ramp takes the value from under the
+conversion that reading it applied (`writtenColour` in `ir.ts`), so it blends
+as written like a hex stop. A value computed in linear light has no written
+form to take, so it is refused, with lerp as the way to blend it.
+
 ## Noise
 
 `sl.noise`, `sl.simplex`, `sl.fbm(p, octaves, base)`, `sl.turbulence` and