onejs-sl 0.3.0 → 0.4.0

package/CHANGELOG.md

@@ -1,5 +1,20 @@
 # Changelog
 
+## 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,15 +323,25 @@ 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.
 
 ## Control flow
 
@@ -338,8 +357,8 @@ shaders loop for. A loop with a runtime count is `Specs/SL_NEXT.md` proposal
 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,
+unrolled, fbm's octaves are held to 1 to 4 even when the count is a value, 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.
@@ -408,6 +427,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