@woosh/meep-engine 3.16.0 → 3.17.0

package/src/shade/renderer/particles/vm/chunk_particle_vm_registers_fast.js

@@ -0,0 +1,55 @@
+import { CodeChunk } from "../../shader/compiler/CodeChunk.js";
+import { PARTICLE_VM_FAST_REGISTER_SLOTS } from "../ParticleConstants.js";
+
+/**
+ * The fast register backing for {@link ./chunk_particle_vm.js}: the VM's register file as a
+ * `var<private>` array of {@link ../ParticleConstants.js PARTICLE_VM_FAST_REGISTER_SLOTS} floats.
+ *
+ * This is the interpreter the system runs on. The array is dynamically indexed — an operand's base
+ * comes out of the instruction word — which is what keeps it in registers rather than scratch, and
+ * therefore what makes the file's size the shader's register footprint outright. Every program pays
+ * that footprint, not only the ones with a wide working set, so the slot count is a whole-system
+ * cost and not a per-effect one. See {@link ../ParticleConstants.js} for what it was measured at.
+ *
+ * The file is zero when a program starts, and the language is what says so: WGSL zero-initialises a
+ * `var<private>` declared without an initializer, once per invocation, and a fast pass runs exactly
+ * one program per invocation ({@link ../shaders/shader_particle_simulate.js},
+ * {@link ../shaders/shader_particle_emit.js}). Nothing in the compiler's output reads a slot it has
+ * not written — the graph allocator assigns a register at the instruction that defines the value — so
+ * that zero is not what makes correct programs work. It is what makes an INCORRECT program
+ * deterministic, and that matters because it is the behaviour {@link ./ParticleVMReference.js}
+ * defines and the parity spec holds the two to. The wide backing cannot offer the same guarantee and
+ * does not try; see {@link ./chunk_particle_vm_registers_wide.js}.
+ *
+ * Nothing here clears the file. A `vm_reg_clear` used to zero it in a loop on top of the
+ * initialisation above, which could only ever be a second pass over the same slots; it outlived its
+ * reason when {@link ../../../wgsl/emulator/ComputeShaderEmulator.js} learned to reset private state
+ * per dispatch, and an empty one outlived its reason with it. Removed 2026-09-06.
+ *
+ * Measured before removing, compiled to RDNA2 (gfx1030): the two zeroing passes folded into one, so
+ * the loop cost 2 instructions of 917 at unchanged VGPRs — what a compiler that sees through it
+ * charges. One pass is about 22 instructions there (893 with no zeroing, 915 with the mandatory
+ * one), which is what a driver that does not see through it charges again on every particle.
+ *
+ * A fast pass that ran more than one program per invocation — the grid-stride shape the wide passes
+ * use — would not inherit the guarantee, since the second program would start on the first's
+ * registers. That pass would zero the file itself, in the loop it needs and where its cost is
+ * visible, rather than every pass carrying a call for it.
+ *
+ * The enclosing shader includes this chunk or the wide one, never both — they define the same two
+ * symbols.
+ *
+ * @type {CodeChunk}
+ */
+export const chunk_particle_vm_registers_fast = CodeChunk.from(/* language=wgsl */ `
+// One f32 per slot. A value of width w occupies w consecutive slots, and an operand names the first.
+var<private> vm_reg : array<f32, ${PARTICLE_VM_FAST_REGISTER_SLOTS}>;
+
+fn vm_reg_read(index : u32) -> f32 {
+    return vm_reg[index];
+}
+
+fn vm_reg_write(index : u32, value : f32) {
+    vm_reg[index] = value;
+}
+`);

package/src/shade/renderer/particles/vm/chunk_particle_vm_registers_wide.d.ts

@@ -0,0 +1,62 @@
+/**
+ * The wide register backing for {@link ./chunk_particle_vm.js}: the VM's register file in a storage
+ * buffer, {@link ../ParticleConstants.js PARTICLE_VM_REGISTER_SLOTS} slots deep — every slot the
+ * instruction set can name.
+ *
+ * This is the fallback. It exists so that "the effect is too big for the register file" is not a
+ * thing an author of a particle graph can be told. It is slow, and it is meant to be: it runs when
+ * the alternative is not running at all.
+ *
+ * ## Why it is slow
+ *
+ * Both, and neither is fixable within this shape. Every operand access becomes a memory access —
+ * three sources of up to four lanes each and four write-back lanes, so up to twelve loads and four
+ * stores per instruction where the fast backing has none. And it gives up the scalar register
+ * indexing that the wave-uniform section decode in the simulate pass buys: the fast file is indexed
+ * through M0, this one through a per-lane address. Instruction fetch and the opcode switch stay
+ * scalar, so the loss is narrower than it could be, but it is real.
+ *
+ * ## Slot-major, and why it is not negotiable
+ *
+ * \`vm_registers[slot * PARTICLE_VM_WIDE_LAUNCH_LANES + lane]\`. The slot moves slowly, the lane fast,
+ * so the lanes of one wave reading one slot read consecutive floats — a single coalesced run, and a
+ * whole workgroup's file stays resident in L1.
+ *
+ * Laid out the other way round — \`[lane * SLOTS + slot]\`, which is the way it reads more naturally
+ * — each lane would stride a kilobyte and every operand access would touch a distinct cache line per
+ * lane. That is roughly an order of magnitude, in a shader that is already the slow path, and it is
+ * invisible afterwards. Hence the note.
+ *
+ * ## The file is never cleared
+ *
+ * Nothing zeroes this file, and the buffer backing it is transient — recycled frame to frame,
+ * holding whatever the last user left. Reading a register before writing it is a corrupt program,
+ * not a defined one, and the compiler does not emit them: the graph allocator assigns a value its
+ * register at the instruction that defines it, so every read follows a write.
+ *
+ * This is the one place the two backings are not interchangeable. The fast file zeroes, so a corrupt
+ * program reads 0.0 there and in {@link ./ParticleVMReference.js} — defined, and the same in both.
+ * Here it reads the previous batch. Anything that generates programs without the def-before-use
+ * guarantee (the fuzzer, hand-written test assembly) must not be run against this backing and expect
+ * to match the reference; the parity spec zeroes the buffer to close that gap for tests only.
+ *
+ * Zeroing in production would be its own cost — {@link ../ParticleConstants.js
+ * PARTICLE_VM_REGISTER_SLOTS} stores per particle, before a single instruction runs, on the path
+ * that is already the slow one.
+ *
+ * ## Binding contract
+ *
+ * The enclosing shader must declare a read_write storage buffer named \`vm_registers\` of
+ * \`array<f32>\`, at least \`PARTICLE_VM_WIDE_LAUNCH_LANES * PARTICLE_VM_REGISTER_SLOTS\` elements, and
+ * must call \`particle_vm_bind_registers(lane)\` once per invocation with a lane index below
+ * {@link ../ParticleConstants.js PARTICLE_VM_WIDE_LAUNCH_LANES} — which is what the wide passes'
+ * bounded launch guarantees, and why they have one.
+ *
+ * The enclosing shader includes this chunk or the fast one, never both — they define the same two
+ * symbols.
+ *
+ * @type {CodeChunk}
+ */
+export const chunk_particle_vm_registers_wide: CodeChunk;
+import { CodeChunk } from "../../shader/compiler/CodeChunk.js";
+//# sourceMappingURL=chunk_particle_vm_registers_wide.d.ts.map

package/src/shade/renderer/particles/vm/chunk_particle_vm_registers_wide.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"chunk_particle_vm_registers_wide.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/particles/vm/chunk_particle_vm_registers_wide.js"],"names":[],"mappings":"AAGA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0DG;AACH,+CAFU,SAAS,CAyBhB;0BArFuB,oCAAoC"}

package/src/shade/renderer/particles/vm/chunk_particle_vm_registers_wide.js

@@ -0,0 +1,86 @@
+import { CodeChunk } from "../../shader/compiler/CodeChunk.js";
+import { PARTICLE_VM_REGISTER_SLOTS, PARTICLE_VM_WIDE_LAUNCH_LANES } from "../ParticleConstants.js";
+
+/**
+ * The wide register backing for {@link ./chunk_particle_vm.js}: the VM's register file in a storage
+ * buffer, {@link ../ParticleConstants.js PARTICLE_VM_REGISTER_SLOTS} slots deep — every slot the
+ * instruction set can name.
+ *
+ * This is the fallback. It exists so that "the effect is too big for the register file" is not a
+ * thing an author of a particle graph can be told. It is slow, and it is meant to be: it runs when
+ * the alternative is not running at all.
+ *
+ * ## Why it is slow
+ *
+ * Both, and neither is fixable within this shape. Every operand access becomes a memory access —
+ * three sources of up to four lanes each and four write-back lanes, so up to twelve loads and four
+ * stores per instruction where the fast backing has none. And it gives up the scalar register
+ * indexing that the wave-uniform section decode in the simulate pass buys: the fast file is indexed
+ * through M0, this one through a per-lane address. Instruction fetch and the opcode switch stay
+ * scalar, so the loss is narrower than it could be, but it is real.
+ *
+ * ## Slot-major, and why it is not negotiable
+ *
+ * \`vm_registers[slot * PARTICLE_VM_WIDE_LAUNCH_LANES + lane]\`. The slot moves slowly, the lane fast,
+ * so the lanes of one wave reading one slot read consecutive floats — a single coalesced run, and a
+ * whole workgroup's file stays resident in L1.
+ *
+ * Laid out the other way round — \`[lane * SLOTS + slot]\`, which is the way it reads more naturally
+ * — each lane would stride a kilobyte and every operand access would touch a distinct cache line per
+ * lane. That is roughly an order of magnitude, in a shader that is already the slow path, and it is
+ * invisible afterwards. Hence the note.
+ *
+ * ## The file is never cleared
+ *
+ * Nothing zeroes this file, and the buffer backing it is transient — recycled frame to frame,
+ * holding whatever the last user left. Reading a register before writing it is a corrupt program,
+ * not a defined one, and the compiler does not emit them: the graph allocator assigns a value its
+ * register at the instruction that defines it, so every read follows a write.
+ *
+ * This is the one place the two backings are not interchangeable. The fast file zeroes, so a corrupt
+ * program reads 0.0 there and in {@link ./ParticleVMReference.js} — defined, and the same in both.
+ * Here it reads the previous batch. Anything that generates programs without the def-before-use
+ * guarantee (the fuzzer, hand-written test assembly) must not be run against this backing and expect
+ * to match the reference; the parity spec zeroes the buffer to close that gap for tests only.
+ *
+ * Zeroing in production would be its own cost — {@link ../ParticleConstants.js
+ * PARTICLE_VM_REGISTER_SLOTS} stores per particle, before a single instruction runs, on the path
+ * that is already the slow one.
+ *
+ * ## Binding contract
+ *
+ * The enclosing shader must declare a read_write storage buffer named \`vm_registers\` of
+ * \`array<f32>\`, at least \`PARTICLE_VM_WIDE_LAUNCH_LANES * PARTICLE_VM_REGISTER_SLOTS\` elements, and
+ * must call \`particle_vm_bind_registers(lane)\` once per invocation with a lane index below
+ * {@link ../ParticleConstants.js PARTICLE_VM_WIDE_LAUNCH_LANES} — which is what the wide passes'
+ * bounded launch guarantees, and why they have one.
+ *
+ * The enclosing shader includes this chunk or the fast one, never both — they define the same two
+ * symbols.
+ *
+ * @type {CodeChunk}
+ */
+export const chunk_particle_vm_registers_wide = CodeChunk.from(/* language=wgsl */ `
+const PARTICLE_VM_WIDE_LAUNCH_LANES : u32 = ${PARTICLE_VM_WIDE_LAUNCH_LANES}u;
+
+// This invocation's column in the register file. Set once, before any program runs.
+var<private> vm_reg_lane : u32;
+
+fn particle_vm_bind_registers(lane : u32) {
+    vm_reg_lane = lane;
+}
+
+// Slot-major: one slot's lanes are consecutive, so a wave reads a coalesced run. See the note above
+// before changing this.
+fn vm_reg_index(index : u32) -> u32 {
+    return index * PARTICLE_VM_WIDE_LAUNCH_LANES + vm_reg_lane;
+}
+
+fn vm_reg_read(index : u32) -> f32 {
+    return vm_registers[vm_reg_index(index)];
+}
+
+fn vm_reg_write(index : u32, value : f32) {
+    vm_registers[vm_reg_index(index)] = value;
+}
+`);

package/src/shade/renderer/shader/chunk/math/chunk_mod_v3f.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Floored modulo of a `vec3<f32>` by a scalar — GLSL's `mod(x, y)`, which WGSL does not have.
+ *
+ * WGSL's `%` is a *remainder*: it takes the sign of the dividend, so `-1.0 % 289.0` is `-1.0`. A
+ * modulo takes the sign of the divisor, so the same expression is `288.0` here. The two agree for
+ * non-negative input and disagree everywhere else, which is exactly where a lattice hash and a
+ * tiling wrap live — noise sampled left of the origin has negative cell coordinates, and `%` would
+ * fold them onto the wrong side of the period and mirror the field about zero.
+ *
+ * The divisor is a scalar because every caller wraps three components of one axis by one period.
+ * {@link chunk_mod_v3i} is the integer counterpart and takes a vector divisor; the two are not
+ * interchangeable.
+ *
+ * Inherited from the GLSL definition, and worth knowing: for a small negative `value` the quotient
+ * rounds to a whole number and the result can come back as exactly `divisor` rather than `0`. Every
+ * consumer here feeds the result to a hash or to a `floor`, both of which tolerate it.
+ *
+ * @type {CodeChunk}
+ */
+export const chunk_mod_v3f: CodeChunk;
+import { CodeChunk } from "../../compiler/CodeChunk.js";
+//# sourceMappingURL=chunk_mod_v3f.d.ts.map

package/src/shade/renderer/shader/chunk/math/chunk_mod_v3f.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"chunk_mod_v3f.d.ts","sourceRoot":"","sources":["../../../../../../../src/shade/renderer/shader/chunk/math/chunk_mod_v3f.js"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;GAkBG;AACH,4BAFU,SAAS,CAYjB;0BA/BwB,6BAA6B"}

package/src/shade/renderer/shader/chunk/math/chunk_mod_v3f.js

@@ -0,0 +1,32 @@
+import { CodeChunk } from "../../compiler/CodeChunk.js";
+
+/**
+ * Floored modulo of a `vec3<f32>` by a scalar — GLSL's `mod(x, y)`, which WGSL does not have.
+ *
+ * WGSL's `%` is a *remainder*: it takes the sign of the dividend, so `-1.0 % 289.0` is `-1.0`. A
+ * modulo takes the sign of the divisor, so the same expression is `288.0` here. The two agree for
+ * non-negative input and disagree everywhere else, which is exactly where a lattice hash and a
+ * tiling wrap live — noise sampled left of the origin has negative cell coordinates, and `%` would
+ * fold them onto the wrong side of the period and mirror the field about zero.
+ *
+ * The divisor is a scalar because every caller wraps three components of one axis by one period.
+ * {@link chunk_mod_v3i} is the integer counterpart and takes a vector divisor; the two are not
+ * interchangeable.
+ *
+ * Inherited from the GLSL definition, and worth knowing: for a small negative `value` the quotient
+ * rounds to a whole number and the result can come back as exactly `divisor` rather than `0`. Every
+ * consumer here feeds the result to a hash or to a `floor`, both of which tolerate it.
+ *
+ * @type {CodeChunk}
+ */
+export const chunk_mod_v3f = CodeChunk.from(
+    //language=WGSL
+    `
+fn mod_v3f(
+    value: vec3<f32>,
+    divisor: f32
+) -> vec3<f32> {
+    return value - floor(value / divisor) * divisor;
+}
+    `
+);

package/src/shade/renderer/shader/chunk/math/chunk_mod_v4f.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Floored modulo of a `vec4<f32>` by a scalar. The four-wide {@link chunk_mod_v3f}; see it for why
+ * WGSL's `%` is not this.
+ *
+ * @type {CodeChunk}
+ */
+export const chunk_mod_v4f: CodeChunk;
+import { CodeChunk } from "../../compiler/CodeChunk.js";
+//# sourceMappingURL=chunk_mod_v4f.d.ts.map

package/src/shade/renderer/shader/chunk/math/chunk_mod_v4f.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"chunk_mod_v4f.d.ts","sourceRoot":"","sources":["../../../../../../../src/shade/renderer/shader/chunk/math/chunk_mod_v4f.js"],"names":[],"mappings":"AAEA;;;;;GAKG;AACH,4BAFU,SAAS,CAYjB;0BAlBwB,6BAA6B"}

package/src/shade/renderer/shader/chunk/math/chunk_mod_v4f.js

@@ -0,0 +1,19 @@
+import { CodeChunk } from "../../compiler/CodeChunk.js";
+
+/**
+ * Floored modulo of a `vec4<f32>` by a scalar. The four-wide {@link chunk_mod_v3f}; see it for why
+ * WGSL's `%` is not this.
+ *
+ * @type {CodeChunk}
+ */
+export const chunk_mod_v4f = CodeChunk.from(
+    //language=WGSL
+    `
+fn mod_v4f(
+    value: vec4<f32>,
+    divisor: f32
+) -> vec4<f32> {
+    return value - floor(value / divisor) * divisor;
+}
+    `
+);

package/src/shade/renderer/shader/chunk/noise/psrdnoise/README.md

@@ -0,0 +1,65 @@
+# psrdnoise
+
+**P**eriodic **s**implex noise with **r**otating gradients and analytic **d**erivatives, by Stefan
+Gustavson and Ian McEwan.
+
+```
+psrdnoise (c) 2021 Stefan Gustavson and Ian McEwan.
+Published under the MIT license.
+https://github.com/stegu/psrdnoise/
+```
+
+Three properties, none of which classic simplex noise has:
+
+- **it tiles.** The lattice is axis-aligned in texture space rather than skewed, so a rectangular
+  period can be imposed on it. Any integer period up to 289 per axis (2-D: even periods in y).
+- **its gradients rotate.** One `alpha` turns every gradient in the field. Animating it swirls the
+  pattern in place instead of crossfading between two fields, which is what flow noise is.
+- **its derivative is exact.** Analytic, and roughly free — the terms are already computed. Curl
+  noise, erosion and normal generation all need it, and a finite difference is both three times the
+  cost and wrong at cell boundaries.
+
+## What is here
+
+| chunk | signature |
+| --- | --- |
+| `psrdnoise2` | `(x: vec2<f32>, period: vec2<f32>, alpha: f32) -> vec3<f32>` |
+| `srdnoise2` | `(x: vec2<f32>, alpha: f32) -> vec3<f32>` |
+| `psrdnoise3` | `(x: vec3<f32>, period: vec3<f32>, alpha: f32) -> vec4<f32>` |
+| `srdnoise3` | `(x: vec3<f32>, alpha: f32) -> vec4<f32>` |
+
+The noise value is in `.x` and the gradient in the remaining components. Upstream returns a struct
+per dimension (`NG2`, `NG3`); packing into a vector instead means no chunk declares a type, so
+nothing that includes one of these has to have the declaration in scope.
+
+The `s*` variants are the non-periodic ones — the same function with the wrap deleted, so a caller
+that never tiles does not pay for the branch. Everything after the lattice is shared with the
+periodic version through `psrdnoise{2,3}_kernel`, which is where the cost of a sample actually is.
+
+Supporting chunks: `psrdnoise2_hash`, `psrdnoise3_permute` (the modulo-289 hashes),
+`psrdnoise3_skew` / `psrdnoise3_unskew` (the lattice transform and its inverse), and
+`math/chunk_mod_v3f` / `chunk_mod_v4f` (GLSL's floored `mod`, which WGSL's remainder `%` is not, and
+which both the hashes and the period wrap need).
+
+## What is not here, and why
+
+- **the value-only variants** (`psrnoise2`, `snoise3`, …). Upstream ships eight functions per
+  dimension because in 2021 it did not trust WGSL's dead-code elimination. Write `.x` and let the
+  compiler drop the derivative; that is what upstream's own GLSL relies on.
+- **the `alpha = 0` wrappers** (`psdnoise2`, `sdnoise3`, …). Pass `0.0`. In 3-D that value is also
+  what selects the cheap gradient path at runtime, so nothing is lost by not naming it.
+- **`FASTROTATION`.** A second gradient rotation, ~10% cheaper but with no shortcut at `alpha = 0`,
+  and it does not agree with the default at `alpha = 0` either. One rotation, one field.
+- **`PERLINGRID`.** An alternative lattice that costs 1% more and constrains every period to a
+  multiple of 3.
+- **`psrddnoise2/3`.** Second derivatives. They return a Hessian on top of the gradient — 6 more
+  floats in 2-D, 6 in 3-D — which no longer fits in a vector return, and nothing here needs them.
+- **`mpsrdnoise2`.** A 16-bit variant, for platforms without `f32`.
+
+## Period, and the 289 in everything
+
+The hash is a permutation polynomial modulo 289 (= 17²), and coordinates congruent modulo 289 hash
+identically. So the field repeats every 289 cells whether or not a period was asked for, a period
+longer than 289 does not tile but corrupts, and the modulus cannot simply be raised: the
+coefficients are sized to keep the polynomial's intermediate products exactly representable in an
+`f32`.

package/src/shade/renderer/shader/chunk/noise/psrdnoise/chunk_psrdnoise2.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Periodic (tiling) 2-D simplex noise with rotating gradients and an analytic derivative.
+ *
+ * Returns `vec3(noise, gradient.x, gradient.y)`: the noise value is in `.x`, in `[-1, 1]`, and
+ * `.yz` is its exact gradient. Ask for only `.x` and the compiler drops the derivative.
+ *
+ * **What tiles.** The lattice is axis-aligned and stretched in y precisely so a rectangular period
+ * can be imposed on it, which ordinary simplex noise's skewed grid cannot do. `period.x` may be any
+ * integer up to 289; `period.y` must be *even* — the hexagonal rows alternate by half a cell, so an
+ * odd y period tiles at twice the number given. Zero or negative on either axis skips the wrap for
+ * that axis, and `vec2(0.0)` on both takes a shortcut worth about 15% by upstream's measurement of
+ * the GLSL. A caller that always passes zero should call {@link chunk_srdnoise2} instead and not pay
+ * for the branch at all. 289 is the hash's modulus, so it is a hard ceiling, not a recommendation.
+ *
+ * **What `alpha` does.** It turns every gradient in the field by that many radians. Animating it
+ * swirls the pattern in place rather than crossfading it — see {@link chunk_psrdnoise2_kernel}.
+ *
+ * psrdnoise (c) 2021 Stefan Gustavson and Ian McEwan. Published under the MIT license.
+ * @see https://github.com/stegu/psrdnoise/
+ * @type {CodeChunk}
+ */
+export const chunk_psrdnoise2: CodeChunk;
+import { CodeChunk } from "../../../compiler/CodeChunk.js";
+//# sourceMappingURL=chunk_psrdnoise2.d.ts.map

package/src/shade/renderer/shader/chunk/noise/psrdnoise/chunk_psrdnoise2.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"chunk_psrdnoise2.d.ts","sourceRoot":"","sources":["../../../../../../../../src/shade/renderer/shader/chunk/noise/psrdnoise/chunk_psrdnoise2.js"],"names":[],"mappings":"AAIA;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,+BAFU,SAAS,CA2DjB;0BAlFwB,gCAAgC"}

package/src/shade/renderer/shader/chunk/noise/psrdnoise/chunk_psrdnoise2.js

@@ -0,0 +1,83 @@
+import { CodeChunk } from "../../../compiler/CodeChunk.js";
+import { chunk_mod_v3f } from "../../math/chunk_mod_v3f.js";
+import { chunk_psrdnoise2_kernel } from "./chunk_psrdnoise2_kernel.js";
+
+/**
+ * Periodic (tiling) 2-D simplex noise with rotating gradients and an analytic derivative.
+ *
+ * Returns `vec3(noise, gradient.x, gradient.y)`: the noise value is in `.x`, in `[-1, 1]`, and
+ * `.yz` is its exact gradient. Ask for only `.x` and the compiler drops the derivative.
+ *
+ * **What tiles.** The lattice is axis-aligned and stretched in y precisely so a rectangular period
+ * can be imposed on it, which ordinary simplex noise's skewed grid cannot do. `period.x` may be any
+ * integer up to 289; `period.y` must be *even* — the hexagonal rows alternate by half a cell, so an
+ * odd y period tiles at twice the number given. Zero or negative on either axis skips the wrap for
+ * that axis, and `vec2(0.0)` on both takes a shortcut worth about 15% by upstream's measurement of
+ * the GLSL. A caller that always passes zero should call {@link chunk_srdnoise2} instead and not pay
+ * for the branch at all. 289 is the hash's modulus, so it is a hard ceiling, not a recommendation.
+ *
+ * **What `alpha` does.** It turns every gradient in the field by that many radians. Animating it
+ * swirls the pattern in place rather than crossfading it — see {@link chunk_psrdnoise2_kernel}.
+ *
+ * psrdnoise (c) 2021 Stefan Gustavson and Ian McEwan. Published under the MIT license.
+ * @see https://github.com/stegu/psrdnoise/
+ * @type {CodeChunk}
+ */
+export const chunk_psrdnoise2 = CodeChunk.from(
+    //language=WGSL
+    `
+fn psrdnoise2(
+    x: vec2<f32>,
+    period: vec2<f32>,
+    alpha: f32
+) -> vec3<f32> {
+    // into simplex space — an axis-aligned hexagonal grid, stretched in y so it can tile
+    let uv = vec2<f32>(x.x + x.y * 0.5, x.y);
+
+    // which simplex we are in. i0 is the base corner, o1 the offset to the second: the cell is a
+    // rhombus split along its diagonal, and which half we are in decides which corner joins
+    let i0 = floor(uv);
+    let f0 = uv - i0;
+    let o1 = select(vec2<f32>(0.0, 1.0), vec2<f32>(1.0, 0.0), f0.x > f0.y);
+
+    let i1 = i0 + o1;
+    let i2 = i0 + vec2<f32>(1.0);
+
+    // the three corners back in texture space
+    let v0 = vec2<f32>(i0.x - i0.y * 0.5, i0.y);
+    let v1 = vec2<f32>(v0.x + o1.x - o1.y * 0.5, v0.y + o1.y);
+    let v2 = vec2<f32>(v0.x + 0.5, v0.y + 1.0);
+
+    var iu = vec3<f32>(i0.x, i1.x, i2.x);
+    var iv = vec3<f32>(i0.y, i1.y, i2.y);
+
+    if (any(period > vec2<f32>(0.0))) {
+        // the wrap has to happen in texture space, where the period is rectangular, and the corners
+        // then go back to simplex space to be hashed. Only the hash inputs move; the offsets below
+        // stay measured from the unwrapped corners, which is what keeps the field continuous
+        // across the seam
+        var xw = vec3<f32>(v0.x, v1.x, v2.x);
+        var yw = vec3<f32>(v0.y, v1.y, v2.y);
+
+        if (period.x > 0.0) {
+            xw = mod_v3f(xw, period.x);
+        }
+
+        if (period.y > 0.0) {
+            yw = mod_v3f(yw, period.y);
+        }
+
+        // xw + 0.5*yw is the skew back to simplex space, where the corners are integer lattice
+        // points — but the wrap leaves them a hair off one, so the trailing +0.5 under the floor
+        // rounds to nearest rather than truncating into the neighbouring cell
+        iu = floor(xw + 0.5 * yw + 0.5);
+        iv = floor(yw + 0.5);
+    }
+
+    return psrdnoise2_kernel(iu, iv, x - v0, x - v1, x - v2, alpha);
+}
+    `, [
+        chunk_mod_v3f,
+        chunk_psrdnoise2_kernel,
+    ]
+);

package/src/shade/renderer/shader/chunk/noise/psrdnoise/chunk_psrdnoise2_hash.d.ts

@@ -0,0 +1,25 @@
+/**
+ * One pseudo-random value per corner of a 2-D simplex, from the corner's lattice coordinates.
+ *
+ * Permutation polynomials modulo 289, composed — the "mod289" hash of the Perlin/McEwan noise
+ * lineage, evaluated on all three corners at once. The modulus is what bounds the period: coordinates
+ * congruent modulo 289 hash the same, so the noise field repeats every 289 cells whether or not a
+ * period was asked for, and a period larger than that cannot be represented.
+ *
+ * `289` is `17²`, and the coefficients are sized so the intermediate products stay inside the range
+ * an `f32` represents exactly — which is why the modulus cannot simply be raised to lengthen the
+ * period. They are not free parameters: what the hash owes its caller is that the three corners of a
+ * cell get three unrelated values and that the whole of `[0, 289)` is reached, and its spec checks
+ * both rather than trusting the constants.
+ *
+ * The two coordinate arguments are transposed with respect to the corners: `iu` holds the u
+ * coordinate of all three corners and `iv` the v coordinate, which is the layout the caller already
+ * has and what makes this three hashes for the price of one.
+ *
+ * psrdnoise (c) 2021 Stefan Gustavson and Ian McEwan. Published under the MIT license.
+ * @see https://github.com/stegu/psrdnoise/
+ * @type {CodeChunk}
+ */
+export const chunk_psrdnoise2_hash: CodeChunk;
+import { CodeChunk } from "../../../compiler/CodeChunk.js";
+//# sourceMappingURL=chunk_psrdnoise2_hash.d.ts.map

package/src/shade/renderer/shader/chunk/noise/psrdnoise/chunk_psrdnoise2_hash.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"chunk_psrdnoise2_hash.d.ts","sourceRoot":"","sources":["../../../../../../../../src/shade/renderer/shader/chunk/noise/psrdnoise/chunk_psrdnoise2_hash.js"],"names":[],"mappings":"AAGA;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,oCAFU,SAAS,CAkBjB;0BAzCwB,gCAAgC"}

package/src/shade/renderer/shader/chunk/noise/psrdnoise/chunk_psrdnoise2_hash.js

@@ -0,0 +1,42 @@
+import { CodeChunk } from "../../../compiler/CodeChunk.js";
+import { chunk_mod_v3f } from "../../math/chunk_mod_v3f.js";
+
+/**
+ * One pseudo-random value per corner of a 2-D simplex, from the corner's lattice coordinates.
+ *
+ * Permutation polynomials modulo 289, composed — the "mod289" hash of the Perlin/McEwan noise
+ * lineage, evaluated on all three corners at once. The modulus is what bounds the period: coordinates
+ * congruent modulo 289 hash the same, so the noise field repeats every 289 cells whether or not a
+ * period was asked for, and a period larger than that cannot be represented.
+ *
+ * `289` is `17²`, and the coefficients are sized so the intermediate products stay inside the range
+ * an `f32` represents exactly — which is why the modulus cannot simply be raised to lengthen the
+ * period. They are not free parameters: what the hash owes its caller is that the three corners of a
+ * cell get three unrelated values and that the whole of `[0, 289)` is reached, and its spec checks
+ * both rather than trusting the constants.
+ *
+ * The two coordinate arguments are transposed with respect to the corners: `iu` holds the u
+ * coordinate of all three corners and `iv` the v coordinate, which is the layout the caller already
+ * has and what makes this three hashes for the price of one.
+ *
+ * psrdnoise (c) 2021 Stefan Gustavson and Ian McEwan. Published under the MIT license.
+ * @see https://github.com/stegu/psrdnoise/
+ * @type {CodeChunk}
+ */
+export const chunk_psrdnoise2_hash = CodeChunk.from(
+    //language=WGSL
+    `
+fn psrdnoise2_hash(
+    iu: vec3<f32>,
+    iv: vec3<f32>
+) -> vec3<f32> {
+    var hash = mod_v3f(iu, 289.0);
+
+    hash = mod_v3f((hash * 51.0 + 2.0) * hash + iv, 289.0);
+
+    return mod_v3f((hash * 34.0 + 10.0) * hash, 289.0);
+}
+    `, [
+        chunk_mod_v3f,
+    ]
+);

package/src/shade/renderer/shader/chunk/noise/psrdnoise/chunk_psrdnoise2_kernel.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Everything a 2-D psrdnoise sample does once its simplex is known: hash the three corners, turn
+ * each hash into a rotating unit gradient, and sum the radially-weighted ramps into a noise value
+ * and its exact first derivative.
+ *
+ * This is the whole cost of the function. It is factored out because it is identical for the
+ * periodic {@link chunk_psrdnoise2} and the non-periodic {@link chunk_srdnoise2} — the two differ
+ * only in how they arrive at `iu`/`iv`, and sharing this keeps that difference down to the wrap
+ * itself.
+ *
+ * **Rotating gradients.** Each corner's gradient is a *unit vector at an angle*, not a table entry:
+ * `psi` is the hashed angle and `alpha` turns every gradient in the field by the same amount. The
+ * result is a swirl rather than a crossfade, which is what "flow noise" is — animate `alpha` and the
+ * pattern rotates in place instead of dissolving. The rotation is a single add, so unlike the 3-D
+ * version there is nothing to gain from `alpha == 0`.
+ *
+ * **Why the derivative is free.** `w⁴·(g·x)` is a product of two things whose derivatives are
+ * already computed, so the product rule costs a handful of multiply-adds and no transcendentals.
+ * Curl noise, normal mapping and erosion all need the gradient, and a finite difference would cost
+ * three more evaluations and be wrong at the cell boundaries.
+ *
+ * Returns `vec3(noise, gradient.x, gradient.y)` — the noise value in `.x`, so a caller that wants
+ * only the value writes `.x` and lets the compiler drop the derivative tail.
+ *
+ * psrdnoise (c) 2021 Stefan Gustavson and Ian McEwan. Published under the MIT license.
+ * @see https://github.com/stegu/psrdnoise/
+ * @type {CodeChunk}
+ */
+export const chunk_psrdnoise2_kernel: CodeChunk;
+import { CodeChunk } from "../../../compiler/CodeChunk.js";
+//# sourceMappingURL=chunk_psrdnoise2_kernel.d.ts.map

package/src/shade/renderer/shader/chunk/noise/psrdnoise/chunk_psrdnoise2_kernel.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"chunk_psrdnoise2_kernel.d.ts","sourceRoot":"","sources":["../../../../../../../../src/shade/renderer/shader/chunk/noise/psrdnoise/chunk_psrdnoise2_kernel.js"],"names":[],"mappings":"AAGA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,sCAFU,SAAS,CAkDjB;0BA/EwB,gCAAgC"}