summaryrefslogtreecommitdiff
path: root/examples/spheres
diff options
context:
space:
mode:
Diffstat (limited to 'examples/spheres')
-rw-r--r--examples/spheres/README.md153
-rw-r--r--examples/spheres/build.zig55
-rw-r--r--examples/spheres/build.zig.zon10
-rw-r--r--examples/spheres/shaders/advance.comp32
-rw-r--r--examples/spheres/shaders/fade.frag11
-rw-r--r--examples/spheres/shaders/fullscreen.vert6
-rw-r--r--examples/spheres/shaders/link.frag12
-rw-r--r--examples/spheres/shaders/link.vert47
-rw-r--r--examples/spheres/shaders/lookahead.comp52
-rw-r--r--examples/spheres/shaders/physics.glsl36
-rw-r--r--examples/spheres/shaders/rechord.comp27
-rw-r--r--examples/spheres/shaders/sim.comp86
-rw-r--r--examples/spheres/shaders/sprite.frag11
-rw-r--r--examples/spheres/shaders/sprite.vert23
-rw-r--r--examples/spheres/shaders/synth.comp112
-rw-r--r--examples/spheres/shaders/trail.frag7
-rw-r--r--examples/spheres/shaders/trail.vert48
-rw-r--r--examples/spheres/shaders/voices.glsl101
-rw-r--r--examples/spheres/src/chords.zig311
-rw-r--r--examples/spheres/src/layouts.zig163
-rw-r--r--examples/spheres/src/main.zig1134
-rw-r--r--examples/spheres/test/play.script58
-rw-r--r--examples/spheres/web/icon-192.pngbin0 -> 12407 bytes
-rw-r--r--examples/spheres/web/icon-512.pngbin0 -> 49109 bytes
-rw-r--r--examples/spheres/web/icon.svg28
25 files changed, 2523 insertions, 0 deletions
diff --git a/examples/spheres/README.md b/examples/spheres/README.md
new file mode 100644
index 0000000..3c65666
--- /dev/null
+++ b/examples/spheres/README.md
@@ -0,0 +1,153 @@
+# spheres
+
+The three-body problem, heard. Three bodies pull on each other; each is
+also a voice, synthesised from its motion. A [sketchbook](../..)
+sketch: native on Linux, and in browsers with WebGPU.
+
+Everything moves on the GPU:
+
+| Shader | Does |
+| --- | --- |
+| `sim.comp` | 16384 copies of the system at once, one per thread: system 0 as given, the others moved by up to 2×10⁻⁴. The copies drawn as a cloud show chaos as it happens: the Pythagorean problem's tears apart, the figure eight's stays a line. System 0 also leaves its trail and sings: from its own motion, or from a look-ahead snapshot while a chord is held. |
+| `physics.glsl`, `voices.glsl` | Included by the simulation and the look-ahead, so the live system and its futures move and sing alike. Leapfrog (kick, drift, kick), symplectic and time-reversible, with close passes split into steps of 2 % of the local dynamical time; and the mapping from motion to voices below. |
+| `lookahead.comp` | 32 futures of system 0, one per thread, from the preset's start: alternative 0 as system 0 began, the rest nudged by growing amounts so chaotic ones fan out. 8 snapshots a frame each (0.4 s of simulated time, against the live system's 0.7 s a second), every snapshot kept on the GPU with the chord sung there. |
+| `rechord.comp` | The look-ahead's chords again when SCALE changes. |
+| `synth.comp` | Each audio block, one thread per sample, from the voices: phases in closed form for frequencies gliding across the block, so blocks join seamlessly and every sample is computed alone. |
+| `advance.comp` | Where the block's phases ended, for the next. |
+| `sprite.*`, `trail.*`, `fade.frag` | The sky: the cloud as layered dust on a long exposure, system 0's bodies as glows, and their trails as ribbons tapering with age. |
+| `link.*` | The coupling: a ribbon from modulator to carrier, as bright as the coupling, with pulses flowing along it. |
+
+The sound reaches the speakers by a readback (`f.download`) about two
+frames later; the CPU only queues it, and hands it to sketchbook's `scope`
+module (the views micscope uses) for the oscilloscope, spectrum and
+spectrogram.
+
+## From motion to sound
+
+Each body is a voice:
+
+- **pitch** follows its speed (220 Hz at speed 0.6, two octaves down to two
+ and a half up), snapped to a scale (diatonic by default; pentatonic, chromatic or none);
+- **modulator ratio** follows how lopsided its distances to the other two
+ are: near 1 or 2 (harmonic) when balanced, in between (bell-like) when
+ not;
+- **modulation depth** follows how near its nearest neighbour is: a close
+ pass bursts into sidebands.
+
+And the **closest pair is one FM voice**: the faster of the two falls
+silent and becomes the modulator, a sine at its own frequency modulating
+the slower one's carrier (two operators, both moved by the bodies), with an
+index that grows as they close in, up to 4. So two voices sound: the pair,
+and the third body on its own. When the closest pair changes, the old
+modulator fades back in as a voice while the new one fades out. In additive
+mode every harmonic gets the same push, so the timbre bends without
+turning harsh. The sky draws the pair: pulses running from the modulator to
+its carrier; the voices' lines say who is `modulating` and who is
+`FM by A 2.10`, and the spectrum marks the pair's sidebands, |J_k(index)|
+at multiples of the modulator's frequency.
+
+The synthesis, with carrier phase c, modulator phase m and depth d:
+
+| Mode | Signal |
+| --- | --- |
+| SINE | sin c |
+| ADD (the default) | harmonics k with weights r^(k−1), r = d/(d+2): brighter with depth |
+| AM | sin c · (1 + a sin m)/(1 + a), a = min(d/4, 1): sidebands at c ± m |
+| RING | sin c · sin m: only c ± m |
+| FM | the carrier's frequency swung by d times itself, by cos m: the index (deviation over modulator frequency) is d/ratio, so it changes as the ratio does |
+| PM | sin(c + d sin m): the index is d, whatever the modulator |
+
+FM and PM sound alike for a steady modulator and part when it moves. The
+spectrum marks where the theory puts each voice's partials (Bessel
+functions |J_k(index)| at carrier + k·modulator for FM and PM): the
+focused voice's in full, the others' as ticks.
+
+## As an instrument
+
+CHORDS (or C) turns spheres into a chord instrument. The look-ahead runs
+ahead of the sky, 120 s of simulated time filled in about five seconds, and
+the chords it finds light up on a grid laid out as a sanfona's (Stradella)
+bass side: columns round the circle of fifths (G♭ D♭ A♭ E♭ B♭ F C G D A E
+B; a phone shows B♭ to B), so neighbours are related chords, and rows by
+quality (major, minor, seventh, sus, power), each half a button over from
+the one above, so a progression is the same hand shape in any key. A
+button is dim until some future sings its chord. The computer keyboard's
+rows are staggered the same way: the number row plays majors, QWERTY
+minors, ASDF sevenths, ZXCV sus chords, column by column; Escape goes back
+to running free.
+
+A chord is the pitch classes of the three bodies' notes, the silent
+modulator's included (it sets the carrier's sidebands), and it only counts
+in a playable voicing: every note from E2 to A5, an octave and a fifth at
+most from lowest to highest, and the FM pair's index at most 3. Otherwise
+the same pitch classes are another sound, shrill, sprawling or a cloud of
+sidebands. How many there are
+depends on the scale (SCALE): pentatonic gives few, diatonic (the default)
+the white-key chords, chromatic every one, and unsnapped pitches round to
+the nearest semitone.
+
+A button finds the best time its chord plays in any of the 32 futures,
+weighing how near it is against how it sounds: half a second's travel more
+for another future than the system's own, 0.6 s for a root not in the bass,
+and up to 3 s for a wide, high or hard-modulated voicing. Then:
+
+- the sound jumps there at once: queued sound is dropped, and system 0
+ sings from that snapshot on the GPU, holding the chord;
+- the sky travels: the whole simulation runs forwards or backwards to that
+ time, about a second's ride, its trails drawn smoothly all the way (points
+ by simulated time, many a frame) or, going back, rewound, and system 0 steps into the snapshot,
+ into that future if it was another's, the jump leaving a break in the
+ trails rather than a line;
+- the sky holds still on that moment, the configuration that sings the
+ chord, until the next.
+
+The strip over the grid shows the system's own future's chords along time,
+coloured by row, now as a white line and the travel's target in yellow.
+Costs: the look-ahead takes about 0.7 ms of GPU a frame (2.4 ms at worst,
+through close passes) while it fills, and nothing after; the whole frame is
+about 1.4 ms on an RTX 3050.
+
+## Presets
+
+1. **Figure eight** (Chenciner and Montgomery): three equal masses on one
+ figure of eight. Stable.
+2. **Butterfly I** (Šuvakov and Dmitrašinović): periodic, unstable.
+3. **Pythagorean** (Burrau): masses 3, 4, 5 at rest on a 3-4-5 triangle;
+ close passes, chaos, and in the end an escape.
+4. **Lagrange triangle**: equal masses turning rigidly; unstable, so the
+ cloud shows it coming apart.
+5. **Random**: three masses and velocities from a seed (R draws again).
+
+## Keys
+
+| Key | |
+| --- | --- |
+| C | the instrument (the chord grid); Escape back to running free |
+| keyboard rows | as an instrument: number row majors, QWERTY minors, ASDF sevenths, ZXCV sus chords, by fifths |
+| Space | pause / run |
+| Left / Right | run time backwards / forwards (leapfrog retraces its steps, until chaos amplifies rounding) |
+| Up / Down | faster / slower |
+| P, E, X | the next preset, the figure eight, a random system |
+| S | the next synthesis mode |
+| Q | the scale: diatonic, chromatic, unsnapped, pentatonic |
+| M | mute |
+| Tab | the voice the spectrum and oscilloscope follow |
+| R | the preset again, copies spread anew |
+
+The buttons do the same on touch screens. The header shows the simulated
+time and the total energy: the figure eight's holds to the last digit
+shown; through the Pythagorean problem's close passes it drifts a few
+percent, where the adaptive steps cost leapfrog its exact symplecticity.
+
+On the web it is an installable app (a PWA) that opens offline. Its icon
+is `web/icon.svg`, rendered to the PNGs beside it with
+`resvg -w N -h N icon.svg icon-N.png`.
+
+## Building
+
+Zig 0.17 and `glslc`; for the web build `naga` (`cargo install naga-cli`),
+and to serve it `miniserve` and `openssl`.
+
+ zig build run # native, with hot reload (`zig build lib --watch` alongside)
+ zig build test # unit tests and a headless run of every preset and mode
+ zig build serve # the web build over https on port 8042
diff --git a/examples/spheres/build.zig b/examples/spheres/build.zig
new file mode 100644
index 0000000..8cc8f60
--- /dev/null
+++ b/examples/spheres/build.zig
@@ -0,0 +1,55 @@
+const std = @import("std");
+const sketchbook = @import("sketchbook");
+
+pub fn build(b: *std.Build) void {
+ const target = b.standardTargetOptions(.{});
+ const optimize = b.standardOptimizeOption(.{});
+ const sb = sketchbook.init(b, .{ .target = target, .optimize = optimize });
+
+ // The simulation, the synthesiser and the sky, as SPIR-V for the native
+ // host and WGSL for the web; their uniforms are src/layouts.zig's structs.
+ const layouts = b.createModule(.{ .root_source_file = b.path("src/layouts.zig") });
+ const shaders = sb.addShaders(.{
+ .layouts = .{ .module = layouts, .types = &.{ "SimParams", "LookParams", "SynthParams", "SkyView", "Fade" } },
+ .sources = &.{
+ b.path("shaders/sim.comp"),
+ b.path("shaders/lookahead.comp"),
+ b.path("shaders/rechord.comp"),
+ b.path("shaders/synth.comp"),
+ b.path("shaders/advance.comp"),
+ b.path("shaders/fullscreen.vert"),
+ b.path("shaders/fade.frag"),
+ b.path("shaders/sprite.vert"),
+ b.path("shaders/sprite.frag"),
+ b.path("shaders/trail.vert"),
+ b.path("shaders/trail.frag"),
+ b.path("shaders/link.vert"),
+ b.path("shaders/link.frag"),
+ },
+ });
+
+ const app = sb.app(.{
+ .name = "spheres",
+ .root_source_file = b.path("src/main.zig"),
+ .imports = &.{
+ .{ .name = "layouts", .module = layouts },
+ .{ .name = "shaders", .module = shaders.module },
+ .{ .name = "scope", .module = sb.modules.scope },
+ },
+ });
+ _ = app.addSteps(.{
+ // Installable, and it opens offline (icons from web/icon.svg).
+ // ReleaseSmall: a third the size of ReleaseSafe's wasm, and Zig
+ // 0.17's LLVM spins for many minutes optimising this sketch for speed.
+ .web = .{ .optimize = .ReleaseSmall, .pwa = .{
+ .description = "The three-body problem on the GPU, heard: each body a voice in FM, PM, AM, ring or additive synthesis.",
+ .background = "#05070d",
+ .theme = "#05070d",
+ .icons = &.{
+ .{ .source = b.path("web/icon-192.png"), .size = 192 },
+ .{ .source = b.path("web/icon-512.png"), .size = 512 },
+ },
+ } },
+ .scripts = &.{b.path("test/play.script")},
+ });
+}
diff --git a/examples/spheres/build.zig.zon b/examples/spheres/build.zig.zon
new file mode 100644
index 0000000..b982c30
--- /dev/null
+++ b/examples/spheres/build.zig.zon
@@ -0,0 +1,10 @@
+.{
+ .name = .spheres,
+ .version = "0.0.1",
+ .dependencies = .{
+ .sketchbook = .{ .path = "../.." },
+ },
+ .minimum_zig_version = "0.17.0",
+ .paths = .{""},
+ .fingerprint = 0x688720ee43c1135a,
+}
diff --git a/examples/spheres/shaders/advance.comp b/examples/spheres/shaders/advance.comp
new file mode 100644
index 0000000..e1e8789
--- /dev/null
+++ b/examples/spheres/shaders/advance.comp
@@ -0,0 +1,32 @@
+#version 450
+#extension GL_GOOGLE_include_directive : require
+// After synth.comp: where the block's phases ended, wrapped, for the next
+// block to start from; and the voices and coupling it ended on, to glide
+// from. (The coupling pushes phases without moving them on, so the phases
+// need nothing from it.)
+layout(local_size_x = 1) in;
+
+#include "SynthParams.glsl"
+
+layout(set = 1, binding = 0) buffer Voices { vec4 voices[]; };
+layout(set = 1, binding = 1) buffer Phases { vec4 phases[]; };
+
+const float TAU = 6.28318530718;
+
+void main() {
+ float count = float(u.count);
+ for (int i = 0; i < 3; i++) {
+ vec4 from = voices[i];
+ vec4 to = voices[3 + i];
+ vec4 phase = phases[i];
+ float wc0 = TAU * from.x / u.rate;
+ float wc1 = TAU * to.x / u.rate;
+ // As synth.comp's glide at n = count.
+ float c = phase.x + 0.5 * (wc0 + wc1) * count;
+ float m = phase.y + 0.5 * (wc0 * from.y + wc1 * to.y) * count;
+ float fm = phase.z + (c - phase.x) + to.z / max(to.y, 1e-3) * (sin(m) - sin(phase.y));
+ phases[i] = vec4(mod(c, TAU), mod(m, TAU), mod(fm, TAU), 0.0);
+ voices[i] = to;
+ voices[6 + i] = voices[9 + i];
+ }
+}
diff --git a/examples/spheres/shaders/fade.frag b/examples/spheres/shaders/fade.frag
new file mode 100644
index 0000000..71b02f2
--- /dev/null
+++ b/examples/spheres/shaders/fade.frag
@@ -0,0 +1,11 @@
+#version 450
+#extension GL_GOOGLE_include_directive : require
+// Blended over the sky (premultiplied), it moves every pixel `amount` of
+// the way to the background: what was drawn before fades, a long exposure.
+layout(location = 0) out vec4 out_color;
+
+#include "Fade.glsl"
+
+void main() {
+ out_color = vec4(u.background * u.amount, u.amount);
+}
diff --git a/examples/spheres/shaders/fullscreen.vert b/examples/spheres/shaders/fullscreen.vert
new file mode 100644
index 0000000..f45ee09
--- /dev/null
+++ b/examples/spheres/shaders/fullscreen.vert
@@ -0,0 +1,6 @@
+#version 450
+// One triangle covering the target.
+void main() {
+ vec2 p = vec2(float((gl_VertexIndex << 1) & 2), float(gl_VertexIndex & 2));
+ gl_Position = vec4(p * 2.0 - 1.0, 0.0, 1.0);
+}
diff --git a/examples/spheres/shaders/link.frag b/examples/spheres/shaders/link.frag
new file mode 100644
index 0000000..53da3cf
--- /dev/null
+++ b/examples/spheres/shaders/link.frag
@@ -0,0 +1,12 @@
+#version 450
+// Pulses running from the modulator to the carrier, soft at the edges.
+layout(location = 0) in vec4 color;
+layout(location = 1) in vec2 along;
+layout(location = 2) flat in float time;
+layout(location = 0) out vec4 out_color;
+
+void main() {
+ float pulse = 0.5 + 0.5 * sin(along.x * 0.25 - time * 9.0);
+ float edge = 1.0 - along.y * along.y;
+ out_color = color * edge * (0.3 + 0.7 * pulse * pulse);
+}
diff --git a/examples/spheres/shaders/link.vert b/examples/spheres/shaders/link.vert
new file mode 100644
index 0000000..d4582e4
--- /dev/null
+++ b/examples/spheres/shaders/link.vert
@@ -0,0 +1,47 @@
+#version 450
+#extension GL_GOOGLE_include_directive : require
+// The FM pair, drawn: from the modulating body to its carrier, a ribbon
+// as wide and bright as the index is high, shading from the
+// modulator's colour to the carrier's. Six vertices for each of the six
+// ordered pairs; uncoupled pairs collapse to nothing.
+layout(location = 0) out vec4 color;
+layout(location = 1) out vec2 along;
+layout(location = 2) flat out float time;
+
+#include "SkyView.glsl"
+
+layout(set = 0, binding = 0) readonly buffer Bodies { vec4 bodies[]; };
+// layouts.voices_*: coupling rows now at 9..11.
+layout(set = 0, binding = 1) readonly buffer Voices { vec4 voices[]; };
+
+// Match main.zig's palette.
+const vec3 palette[3] = vec3[](vec3(0.40, 0.85, 1.0), vec3(1.0, 0.45, 0.82), vec3(1.0, 0.80, 0.35));
+// Pairs (carrier, modulator).
+const ivec2 pairs[6] = ivec2[](ivec2(0, 1), ivec2(0, 2), ivec2(1, 0), ivec2(1, 2), ivec2(2, 0), ivec2(2, 1));
+
+void main() {
+ ivec2 pair = pairs[uint(gl_VertexIndex) / 6u];
+ uint corner = uint(gl_VertexIndex) % 6u;
+ float amount = voices[9 + pair.x][pair.y];
+ time = u.time;
+ if (amount < 0.02) {
+ gl_Position = vec4(0.0, 0.0, 2.0, 1.0);
+ color = vec4(0.0);
+ along = vec2(0.0);
+ return;
+ }
+ // Corners 0, 3, 5 at the modulator, 1, 2, 4 at the carrier; 0, 1, 3 on
+ // one side.
+ bool far_end = corner == 1u || corner == 2u || corner == 4u;
+ bool side = corner == 2u || corner == 4u || corner == 5u;
+ vec2 from = (bodies[pair.y].xy - u.center) / u.per_pixel;
+ vec2 to = (bodies[pair.x].xy - u.center) / u.per_pixel;
+ vec2 d = to - from;
+ float len = max(length(d), 1e-3);
+ vec2 normal = vec2(-d.y, d.x) / len;
+ float width = u.radius * (0.4 + min(amount, 1.6));
+ vec2 at = (far_end ? to : from) + normal * (side ? width : -width);
+ gl_Position = vec4(at * 2.0 / u.size, 0.0, 1.0);
+ along = vec2(far_end ? len : 0.0, side ? 1.0 : -1.0);
+ color = vec4(mix(palette[pair.y], palette[pair.x], far_end ? 1.0 : 0.0), 1.0) * u.alpha * clamp(amount, 0.0, 1.0);
+}
diff --git a/examples/spheres/shaders/lookahead.comp b/examples/spheres/shaders/lookahead.comp
new file mode 100644
index 0000000..75902d7
--- /dev/null
+++ b/examples/spheres/shaders/lookahead.comp
@@ -0,0 +1,52 @@
+#version 450
+#extension GL_GOOGLE_include_directive : require
+// Futures of system 0, one per thread, for spheres as an instrument: from
+// the preset's start, alternative 0 exactly as system 0 began and the
+// others nudged by growing amounts, so where the system is chaotic their
+// futures fan out. Each is integrated ahead `count` samples a frame (with
+// physics.glsl, as the live system is), leaving a snapshot every
+// `sample_dt` and the chord its bodies would sing there (voices.glsl). A
+// chord chosen then finds the nearest time it plays, in any of them.
+layout(local_size_x = 32) in;
+
+#include "LookParams.glsl"
+#include "physics.glsl"
+#include "voices.glsl"
+
+// Where each alternative has got to: 3 vec4s each (position xy, velocity zw).
+layout(set = 1, binding = 0) buffer State { vec4 state[]; };
+// Snapshots, sample-major: sample t of alternative a at 3 (t * K + a).
+layout(set = 1, binding = 1) buffer Snapshots { vec4 snapshots[]; };
+// Chords, sample-major: t * K + a.
+layout(set = 1, binding = 2) buffer Chords { uint chords[]; };
+
+// Match main.zig's leapfrog step.
+const float BASE_STEP = 0.004;
+
+void main() {
+ uint alt = gl_GlobalInvocationID.x;
+ if (alt >= u.alternatives) return;
+ vec3 m = u.masses.xyz;
+ vec2 p[3];
+ vec2 v[3];
+ for (int i = 0; i < 3; i++) {
+ vec4 b = state[3u * alt + uint(i)];
+ p[i] = b.xy;
+ v[i] = b.zw;
+ }
+ vec2 a[3];
+ accelerations(p, m, u.softening, a);
+ Mapping map = Mapping(u.base, u.speed_ref, u.depth_scale, u.couple_scale, u.quantize);
+ uint steps = uint(ceil(u.sample_dt / BASE_STEP));
+ float dt = u.sample_dt / float(steps);
+ for (uint t = u.first; t < min(u.first + u.count, u.horizon); t++) {
+ uint at = t * u.alternatives + alt;
+ for (int i = 0; i < 3; i++) snapshots[3u * at + uint(i)] = vec4(p[i], v[i]);
+ vec4 sung[3];
+ vec4 coupled[3];
+ sing(p, v, map, sung, coupled);
+ chords[at] = chordOf(sung) | voicing(sung, coupled);
+ for (uint k = 0u; k < steps; k++) leapfrog(p, v, a, dt, m, u.softening, 256.0);
+ }
+ for (int i = 0; i < 3; i++) state[3u * alt + uint(i)] = vec4(p[i], v[i]);
+}
diff --git a/examples/spheres/shaders/physics.glsl b/examples/spheres/shaders/physics.glsl
new file mode 100644
index 0000000..5d74bee
--- /dev/null
+++ b/examples/spheres/shaders/physics.glsl
@@ -0,0 +1,36 @@
+// The three-body physics, shared by sim.comp and lookahead.comp so the live
+// system and its futures move alike: gravity with softening, and leapfrog
+// (kick, drift, kick), symplectic and time-reversible, split finer through
+// close passes, about 2 % of the local dynamical time a part: too coarse
+// and a close pass gains energy and flings a body out.
+
+void accelerations(vec2 p[3], vec3 m, float softening, out vec2 a[3]) {
+ float eps2 = softening * softening;
+ a[0] = vec2(0.0);
+ a[1] = vec2(0.0);
+ a[2] = vec2(0.0);
+ for (int i = 0; i < 3; i++) {
+ for (int j = i + 1; j < 3; j++) {
+ vec2 d = p[j] - p[i];
+ float inv = inversesqrt(dot(d, d) + eps2);
+ vec2 f = d * (inv * inv * inv);
+ a[i] += m[j] * f;
+ a[j] -= m[i] * f;
+ }
+ }
+}
+
+// One step of `dt`, in up to `most` parts; `a` holds the accelerations at
+// `p`, before and after.
+void leapfrog(inout vec2 p[3], inout vec2 v[3], inout vec2 a[3], float dt, vec3 m, float softening, float most) {
+ float near = min(min(distance(p[0], p[1]), distance(p[0], p[2])), distance(p[1], p[2])) + softening;
+ float local = sqrt(near * near * near / (m.x + m.y + m.z));
+ uint k = uint(clamp(ceil(abs(dt) / (0.02 * local)), 1.0, most));
+ float h = dt / float(k);
+ for (uint j = 0u; j < k; j++) {
+ for (int i = 0; i < 3; i++) v[i] += 0.5 * h * a[i];
+ for (int i = 0; i < 3; i++) p[i] += h * v[i];
+ accelerations(p, m, softening, a);
+ for (int i = 0; i < 3; i++) v[i] += 0.5 * h * a[i];
+ }
+}
diff --git a/examples/spheres/shaders/rechord.comp b/examples/spheres/shaders/rechord.comp
new file mode 100644
index 0000000..6119120
--- /dev/null
+++ b/examples/spheres/shaders/rechord.comp
@@ -0,0 +1,27 @@
+#version 450
+#extension GL_GOOGLE_include_directive : require
+// The look-ahead's chords again, for another scale setting: one thread per
+// snapshot, the first `count` of them.
+layout(local_size_x = 64) in;
+
+#include "LookParams.glsl"
+#include "voices.glsl"
+
+layout(set = 0, binding = 0) readonly buffer Snapshots { vec4 snapshots[]; };
+layout(set = 1, binding = 0) buffer Chords { uint chords[]; };
+
+void main() {
+ uint at = gl_GlobalInvocationID.x;
+ if (at >= u.count) return;
+ vec2 p[3];
+ vec2 v[3];
+ for (int i = 0; i < 3; i++) {
+ vec4 b = snapshots[3u * at + uint(i)];
+ p[i] = b.xy;
+ v[i] = b.zw;
+ }
+ vec4 sung[3];
+ vec4 coupled[3];
+ sing(p, v, Mapping(u.base, u.speed_ref, u.depth_scale, u.couple_scale, u.quantize), sung, coupled);
+ chords[at] = chordOf(sung) | voicing(sung, coupled);
+}
diff --git a/examples/spheres/shaders/sim.comp b/examples/spheres/shaders/sim.comp
new file mode 100644
index 0000000..4a79ce1
--- /dev/null
+++ b/examples/spheres/shaders/sim.comp
@@ -0,0 +1,86 @@
+#version 450
+#extension GL_GOOGLE_include_directive : require
+// The three-body problem, one system per thread: every copy of the system
+// at once, each a hair apart from system 0, so the cloud they make shows
+// how far apart chaos takes them (a stable orbit keeps it a thin line).
+// The physics and the voices are physics.glsl's and voices.glsl's, which
+// the look-ahead shares.
+//
+// System 0 also leaves its trail, reports its state, and sings: from its
+// own motion, or, while a chord is held, from the look-ahead's snapshot
+// that sings it. It can also adopt a snapshot, stepping into that future.
+layout(local_size_x = 64) in;
+
+#include "SimParams.glsl"
+#include "physics.glsl"
+#include "voices.glsl"
+
+// The look-ahead's snapshots: 3 vec4s each (position xy, velocity zw).
+layout(set = 0, binding = 0) readonly buffer Ahead { vec4 ahead[]; };
+// Position xy, velocity zw: system s's bodies are 3s, 3s + 1, 3s + 2.
+layout(set = 1, binding = 0) buffer Bodies { vec4 bodies[]; };
+// System 0's positions: body b's ring at b * TRAIL.
+layout(set = 1, binding = 1) buffer Trail { vec2 trail[]; };
+// layouts.voices_*: voices 0..2 as the synthesiser last used them, 3..5
+// now; coupling rows 6..8 last used, 9..11 now.
+layout(set = 1, binding = 2) buffer Voices { vec4 voices[]; };
+// layouts.Lead: bodies 0..2, voices 3..5, coupling 6..8, (energy, time) 9.
+layout(set = 1, binding = 3) buffer Lead { vec4 lead[]; };
+
+// Match layouts.zig.
+const uint TRAIL = 1024;
+
+void main() {
+ uint s = gl_GlobalInvocationID.x;
+ if (s >= u.systems) return;
+ vec3 m = u.masses.xyz;
+ vec2 p[3];
+ vec2 v[3];
+ for (int i = 0; i < 3; i++) {
+ vec4 b = s == 0u && u.adopt != 0u ? ahead[3u * (u.adopt - 1u) + uint(i)] : bodies[3u * s + uint(i)];
+ p[i] = b.xy;
+ v[i] = b.zw;
+ }
+ vec2 a[3];
+ accelerations(p, m, u.softening, a);
+ // System 0 leaves trail points as it goes, by simulated time, so a fast
+ // travel draws as smooth a path as running does.
+ uint written = 0u;
+ for (uint step = 0u; step < u.steps; step++) {
+ leapfrog(p, v, a, u.dt, m, u.softening, 512.0);
+ if (s == 0u && written < u.trail_points && step + 1u >= u.trail_first && (step + 1u - u.trail_first) % u.trail_every == 0u) {
+ for (int i = 0; i < 3; i++) trail[uint(i) * TRAIL + (u.trail_head + written) % TRAIL] = p[i];
+ written++;
+ }
+ }
+ for (int i = 0; i < 3; i++) bodies[3u * s + uint(i)] = vec4(p[i], v[i]);
+ if (s != 0u) return;
+
+ float kinetic = 0.0;
+ float potential = 0.0;
+ for (int i = 0; i < 3; i++) {
+ kinetic += 0.5 * m[i] * dot(v[i], v[i]);
+ for (int j = i + 1; j < 3; j++) potential -= m[i] * m[j] * inversesqrt(dot(p[j] - p[i], p[j] - p[i]) + u.softening * u.softening);
+ lead[i] = vec4(p[i], v[i]);
+ }
+
+ vec2 sp[3];
+ vec2 sv[3];
+ for (int i = 0; i < 3; i++) {
+ vec4 b = u.voice_source != 0u ? ahead[3u * (u.voice_source - 1u) + uint(i)] : vec4(p[i], v[i]);
+ sp[i] = b.xy;
+ sv[i] = b.zw;
+ }
+ vec4 sung[3];
+ vec4 coupled[3];
+ sing(sp, sv, Mapping(u.base, u.speed_ref, u.depth_scale, u.couple_scale, u.quantize), sung, coupled);
+ for (int i = 0; i < 3; i++) {
+ voices[3 + i] = sung[i];
+ lead[3 + i] = sung[i];
+ // A quarter of the way each frame: pairs hand over smoothly.
+ vec4 row = mix(voices[9 + i], coupled[i], 0.25);
+ voices[9 + i] = row;
+ lead[6 + i] = row;
+ }
+ lead[9] = vec4(kinetic + potential, lead[9].y + float(u.steps) * u.dt, 0.0, 0.0);
+}
diff --git a/examples/spheres/shaders/sprite.frag b/examples/spheres/shaders/sprite.frag
new file mode 100644
index 0000000..d39e7e4
--- /dev/null
+++ b/examples/spheres/shaders/sprite.frag
@@ -0,0 +1,11 @@
+#version 450
+// A Gaussian glow, premultiplied, for additive blending.
+layout(location = 0) in vec2 corner;
+layout(location = 1) in vec4 color;
+layout(location = 0) out vec4 out_color;
+
+void main() {
+ float r2 = dot(corner, corner);
+ float glow = exp(-5.0 * r2) * (1.0 - smoothstep(0.8, 1.0, r2));
+ out_color = color * glow;
+}
diff --git a/examples/spheres/shaders/sprite.vert b/examples/spheres/shaders/sprite.vert
new file mode 100644
index 0000000..13e1c73
--- /dev/null
+++ b/examples/spheres/shaders/sprite.vert
@@ -0,0 +1,23 @@
+#version 450
+#extension GL_GOOGLE_include_directive : require
+// A soft disc per body: of every system from `first` for `count` systems,
+// at `radius` pixels, coloured by body. Six vertices make each quad.
+layout(location = 0) out vec2 corner;
+layout(location = 1) out vec4 color;
+
+#include "SkyView.glsl"
+
+layout(set = 0, binding = 0) readonly buffer Bodies { vec4 bodies[]; };
+
+const vec2 corners[6] = vec2[](vec2(-1, -1), vec2(1, -1), vec2(1, 1), vec2(-1, -1), vec2(1, 1), vec2(-1, 1));
+// Match main.zig's palette.
+const vec3 palette[3] = vec3[](vec3(0.40, 0.85, 1.0), vec3(1.0, 0.45, 0.82), vec3(1.0, 0.80, 0.35));
+
+void main() {
+ uint sprite = uint(gl_VertexIndex) / 6u;
+ uint index = 3u * u.first + sprite;
+ vec2 at = (bodies[index].xy - u.center) / u.per_pixel + corners[uint(gl_VertexIndex) % 6u] * u.radius;
+ gl_Position = vec4(at * 2.0 / u.size, 0.0, 1.0);
+ corner = corners[uint(gl_VertexIndex) % 6u];
+ color = vec4(palette[index % 3u], 1.0) * u.alpha;
+}
diff --git a/examples/spheres/shaders/synth.comp b/examples/spheres/shaders/synth.comp
new file mode 100644
index 0000000..3a6c40c
--- /dev/null
+++ b/examples/spheres/shaders/synth.comp
@@ -0,0 +1,112 @@
+#version 450
+#extension GL_GOOGLE_include_directive : require
+// One audio block, one thread per sample: three voices from the bodies'
+// parameters, gliding from what the last block ended on to what sim.comp
+// set now, so blocks join without clicks.
+//
+// Each phase has a closed form, so every sample is computed alone: a
+// frequency gliding linearly from w0 to w1 (radians per sample) over N
+// samples has phase p0 + w0 n + (w1 - w0) n^2 / 2N after n of them.
+//
+// The modes, with carrier phase c, modulator phase m (at ratio times the
+// carrier's frequency) and depth d:
+// sine sin c
+// additive sum over harmonics k of r^(k-1) sin kc, r = d / (d + 2),
+// those under Nyquist, normalised
+// AM sin c (1 + a sin m) / (1 + a), a = min(d / 4, 1)
+// ring sin c sin m
+// FM sin of the integral of the carrier's frequency, pushed
+// d times the carrier's frequency either way by cos m: so the
+// index, deviation over modulator frequency, is d / ratio and
+// changes as the modulator does
+// PM sin(c + d sin m): the index is d, whatever the modulator
+// FM and PM sound alike for a steady modulator, and part when it moves.
+//
+// The closest pair (sim.comp) is one FM voice: the modulating body is
+// silent, and a sine at its frequency, times the index, pushes the other
+// body's carrier phase. Two operators, both moved by the bodies. The push
+// moves every harmonic of the additive voice alike, so its timbre bends
+// without turning harsh.
+layout(local_size_x = 64) in;
+
+#include "SynthParams.glsl"
+
+layout(set = 0, binding = 0) readonly buffer Voices { vec4 voices[]; };
+// Per voice: carrier phase, modulator phase, FM's phase.
+layout(set = 0, binding = 1) readonly buffer Phases { vec4 phases[]; };
+layout(set = 1, binding = 0) buffer Block { float block[]; };
+
+const float TAU = 6.28318530718;
+// Match layouts.Mode.
+const uint SINE = 0u;
+const uint ADDITIVE = 1u;
+const uint AM = 2u;
+const uint RING = 3u;
+const uint FM = 4u;
+
+float glide(float phase, float w0, float w1, float n, float count) {
+ return phase + w0 * n + (w1 - w0) * n * n / (2.0 * count);
+}
+
+// Voice i's signal, its carrier phase pushed by `push` radians.
+float voice(int i, float n, float count, float push) {
+ vec4 from = voices[i];
+ vec4 to = voices[3 + i];
+ vec4 phase = phases[i];
+ float t = n / count;
+ float wc0 = TAU * from.x / u.rate;
+ float wc1 = TAU * to.x / u.rate;
+ float c = glide(phase.x, wc0, wc1, n, count);
+ float m = glide(phase.y, wc0 * from.y, wc1 * to.y, n, count);
+ float depth = mix(from.z, to.z, t);
+ float ratio = mix(from.y, to.y, t);
+ float y;
+ if (u.mode == SINE) {
+ y = sin(c + push);
+ } else if (u.mode == ADDITIVE) {
+ float r = depth / (depth + 2.0);
+ float carrier = mix(from.x, to.x, t);
+ float sum = 0.0;
+ float norm = 0.0;
+ float weight = 1.0;
+ for (int k = 1; k <= 16; k++) {
+ if (float(k) * carrier >= 0.5 * u.rate) break;
+ sum += weight * sin(float(k) * c + push);
+ norm += weight;
+ weight *= r;
+ }
+ y = sum / max(norm, 1e-6);
+ } else if (u.mode == AM) {
+ float a = min(depth / 4.0, 1.0);
+ y = sin(c + push) * (1.0 + a * sin(m)) / (1.0 + a);
+ } else if (u.mode == RING) {
+ y = sin(c + push) * sin(m);
+ } else if (u.mode == FM) {
+ y = sin(phase.z + push + (c - phase.x) + depth / max(ratio, 1e-3) * (sin(m) - sin(phase.y)));
+ } else {
+ y = sin(c + push + depth * sin(m));
+ }
+ return y;
+}
+
+void main() {
+ uint n = gl_GlobalInvocationID.x;
+ if (n >= u.count) return;
+ float count = float(u.count);
+ float t = float(n) / count;
+ // Each body as a modulator: a sine at its carrier frequency.
+ vec3 sines;
+ for (int i = 0; i < 3; i++) {
+ float w0 = TAU * voices[i].x / u.rate;
+ float w1 = TAU * voices[3 + i].x / u.rate;
+ sines[i] = sin(glide(phases[i].x, w0, w1, float(n), count));
+ }
+ float sum = 0.0;
+ for (int i = 0; i < 3; i++) {
+ vec4 row = mix(voices[6 + i], voices[9 + i], t);
+ float audible = (1.0 - row.w) * mix(voices[i].w, voices[3 + i].w, t);
+ if (audible < 1e-4) continue;
+ sum += audible * voice(i, float(n), count, dot(row.xyz, sines));
+ }
+ block[n] = tanh(u.gain * sum);
+}
diff --git a/examples/spheres/shaders/trail.frag b/examples/spheres/shaders/trail.frag
new file mode 100644
index 0000000..8a82628
--- /dev/null
+++ b/examples/spheres/shaders/trail.frag
@@ -0,0 +1,7 @@
+#version 450
+layout(location = 0) in vec4 color;
+layout(location = 0) out vec4 out_color;
+
+void main() {
+ out_color = color;
+}
diff --git a/examples/spheres/shaders/trail.vert b/examples/spheres/shaders/trail.vert
new file mode 100644
index 0000000..7f9f35c
--- /dev/null
+++ b/examples/spheres/shaders/trail.vert
@@ -0,0 +1,48 @@
+#version 450
+#extension GL_GOOGLE_include_directive : require
+// System 0's trails: per body, a ribbon through its last positions,
+// `radius` pixels wide at the newest and tapering to nothing at the oldest,
+// fading as it goes. Six vertices per segment; segments past what has been
+// filled, or across a jump, collapse to nothing.
+layout(location = 0) out vec4 color;
+
+#include "SkyView.glsl"
+
+layout(set = 0, binding = 0) readonly buffer Trail { vec2 trail[]; };
+
+// Match layouts.zig and main.zig's palette.
+const uint TRAIL = 1024u;
+const vec3 palette[3] = vec3[](vec3(0.40, 0.85, 1.0), vec3(1.0, 0.45, 0.82), vec3(1.0, 0.80, 0.35));
+
+void main() {
+ uint segment = uint(gl_VertexIndex) / 6u;
+ uint corner = uint(gl_VertexIndex) % 6u;
+ uint body = segment / (TRAIL - 1u);
+ uint age = segment % (TRAIL - 1u);
+ if (age + 1u >= u.filled) {
+ gl_Position = vec4(0.0, 0.0, 2.0, 1.0);
+ color = vec4(0.0);
+ return;
+ }
+ // Corners 0, 3, 5 at the newer end, 1, 2, 4 at the older; 0, 1, 3 on
+ // one side, 2, 4, 5 on the other.
+ bool older = corner == 1u || corner == 2u || corner == 4u;
+ bool side = corner == 2u || corner == 4u || corner == 5u;
+ uint a = (u.head + TRAIL - age) % TRAIL;
+ uint b = (u.head + TRAIL - age - 1u) % TRAIL;
+ // A jump (system 0 stepping into a snapshot) breaks the trail.
+ if (distance(trail[body * TRAIL + a], trail[body * TRAIL + b]) > u.gap) {
+ gl_Position = vec4(0.0, 0.0, 2.0, 1.0);
+ color = vec4(0.0);
+ return;
+ }
+ vec2 pa = (trail[body * TRAIL + a] - u.center) / u.per_pixel;
+ vec2 pb = (trail[body * TRAIL + b] - u.center) / u.per_pixel;
+ vec2 along = pb - pa;
+ float len = length(along);
+ vec2 normal = len > 1e-4 ? vec2(-along.y, along.x) / len : vec2(0.0, 1.0);
+ float fade = 1.0 - float(older ? age + 1u : age) / float(u.filled);
+ vec2 at = (older ? pb : pa) + normal * (side ? 1.0 : -1.0) * u.radius * fade;
+ gl_Position = vec4(at * 2.0 / u.size, 0.0, 1.0);
+ color = vec4(palette[body], 1.0) * u.alpha * fade * fade;
+}
diff --git a/examples/spheres/shaders/voices.glsl b/examples/spheres/shaders/voices.glsl
new file mode 100644
index 0000000..c2fd56c
--- /dev/null
+++ b/examples/spheres/shaders/voices.glsl
@@ -0,0 +1,101 @@
+// From motion to sound, shared by sim.comp (what sounds) and lookahead.comp
+// (what would): each body a voice whose pitch follows its speed, whose
+// modulator ratio follows how lopsided its two distances are, and whose
+// depth follows how near its nearest neighbour is; and the closest pair one
+// FM voice, the faster body silent, modulating the other.
+
+struct Mapping {
+ float base;
+ float speed_ref;
+ float depth_scale;
+ float couple_scale;
+ // Match layouts.Scale: free, pentatonic, diatonic, chromatic.
+ uint scale;
+};
+
+// The nearest note of the scale, as a MIDI number: A minor pentatonic (A C
+// D E G), A minor / C major (the white keys), every semitone, or none.
+float snap(float midi, uint scale) {
+ if (scale == 0u) return midi;
+ if (scale == 3u) return round(midi);
+ float m = midi - 69.0;
+ float octave = floor(m / 12.0);
+ float degree = m - 12.0 * octave;
+ const float pentatonic[6] = float[](0.0, 3.0, 5.0, 7.0, 10.0, 12.0);
+ const float diatonic[8] = float[](0.0, 2.0, 3.0, 5.0, 7.0, 8.0, 10.0, 12.0);
+ float best = 0.0;
+ if (scale == 1u) {
+ for (int i = 1; i < 6; i++) if (abs(pentatonic[i] - degree) < abs(best - degree)) best = pentatonic[i];
+ } else {
+ for (int i = 1; i < 8; i++) if (abs(diatonic[i] - degree) < abs(best - degree)) best = diatonic[i];
+ }
+ return 69.0 + 12.0 * octave + best;
+}
+
+// Voices: (carrier Hz, ratio, depth, amplitude). Coupling rows: xyz the FM
+// index each voice gets from each other, w whether it is the silent
+// modulator.
+void sing(vec2 p[3], vec2 v[3], Mapping map, out vec4 voices[3], out vec4 coupling[3]) {
+ for (int i = 0; i < 3; i++) {
+ float speed = length(v[i]);
+ float octaves = clamp(log2(max(speed, 1e-4) / map.speed_ref), -2.0, 2.5);
+ float midi = 12.0 * log2(map.base / 440.0) + 69.0 + 12.0 * octaves;
+ midi = snap(midi, map.scale);
+ float d1 = distance(p[i], p[(i + 1) % 3]);
+ float d2 = distance(p[i], p[(i + 2) % 3]);
+ float near = min(d1, d2);
+ float far = max(d1, d2);
+ voices[i] = vec4(
+ 440.0 * exp2((midi - 69.0) / 12.0),
+ 0.5 + 4.0 * near / max(near + far, 1e-6),
+ clamp(map.depth_scale / max(near, 1e-3), 0.0, 12.0),
+ 0.2 + 0.15 * clamp(speed / (2.0 * map.speed_ref), 0.0, 1.0));
+ coupling[i] = vec4(0.0);
+ }
+ int first = 0;
+ int second = 1;
+ float closest = distance(p[0], p[1]);
+ if (distance(p[0], p[2]) < closest) { first = 0; second = 2; closest = distance(p[0], p[2]); }
+ if (distance(p[1], p[2]) < closest) { first = 1; second = 2; closest = distance(p[1], p[2]); }
+ int modulator = length(v[first]) > length(v[second]) ? first : second;
+ int carrier = modulator == first ? second : first;
+ coupling[carrier][modulator] = clamp(map.couple_scale / max(closest, 1e-3), 0.0, 4.0);
+ coupling[modulator].w = 1.0;
+}
+
+// The chord with its voicing, packed: bits 0-11 the pitch classes (the
+// chord), bit 12 set if it is playable, bits 16-19 the lowest note's pitch
+// class (for root position), bits 24-31 how bad it sounds, 0 to 255.
+// Playable: every note from E2 to A5, an octave and a fifth at most from
+// lowest to highest, and the FM pair's index at most 3; past those, the
+// same pitch classes are another sound, shrill, sprawling or a cloud of
+// sidebands. Within them, wider, higher and harder modulated cost more.
+uint voicing(vec4 voices[3], vec4 coupling[3]) {
+ int low = 1000;
+ int high = -1000;
+ int lowest_class = 0;
+ for (int i = 0; i < 3; i++) {
+ int midi = int(round(69.0 + 12.0 * log2(voices[i].x / 440.0)));
+ if (midi < low) {
+ low = midi;
+ lowest_class = ((midi % 12) + 12) % 12;
+ }
+ high = max(high, midi);
+ }
+ float index = 0.0;
+ for (int i = 0; i < 3; i++) index = max(index, max(coupling[i].x, max(coupling[i].y, coupling[i].z)));
+ int spread = high - low;
+ bool playable = low >= 40 && high <= 81 && spread <= 19 && index <= 3.0;
+ float bad = 6.0 * float(max(spread - 12, 0)) + 10.0 * float(max(high - 76, 0)) + 15.0 * index;
+ return (playable ? 1u << 12 : 0u) | (uint(lowest_class) << 16) | (uint(clamp(bad, 0.0, 255.0)) << 24);
+}
+
+// The pitch classes the three voices sing, as bits (C is bit 0): the chord.
+uint chordOf(vec4 voices[3]) {
+ uint mask = 0u;
+ for (int i = 0; i < 3; i++) {
+ int midi = int(round(69.0 + 12.0 * log2(voices[i].x / 440.0)));
+ mask |= 1u << uint(((midi % 12) + 12) % 12);
+ }
+ return mask;
+}
diff --git a/examples/spheres/src/chords.zig b/examples/spheres/src/chords.zig
new file mode 100644
index 0000000..54a4413
--- /dev/null
+++ b/examples/spheres/src/chords.zig
@@ -0,0 +1,311 @@
+//! spheres as an instrument: the CPU's side of the look-ahead. The GPU
+//! (lookahead.comp) integrates `alternatives` futures of system 0 from the
+//! preset's start, a few samples a frame, keeping a snapshot every
+//! `sample_dt` and the chord sung there: the pitch classes of the three
+//! voices (the silent modulator's counts: it sets the carrier's sidebands).
+//! The chords come back here, a frame or two later; the ones that fit the
+//! grid of buttons (a sanfona's bass side, see `Grid`) light up as found,
+//! and choosing one finds the nearest time it plays, in whichever future
+//! plays it soonest.
+const std = @import("std");
+const layouts = @import("layouts");
+
+/// The mapping from motion to voices (voices.glsl), which the shaders get
+/// as uniforms; and leapfrog's base step, as physics.glsl's callers use it.
+pub const base: f32 = 220;
+pub const speed_ref: f32 = 0.6;
+pub const depth_scale: f32 = 1.2;
+pub const couple_scale: f32 = 0.9;
+pub const base_step = 0.004;
+
+/// Futures integrated side by side: 0 is system 0's own, the rest nudged.
+pub const alternatives = layouts.alternatives;
+pub const horizon = layouts.horizon;
+pub const sample_dt = 0.05;
+/// Samples the look-ahead advances each frame: 0.4 s of simulated time,
+/// against the live system's 0.7 s a second, so it pulls well ahead.
+pub const per_frame = 8;
+/// What a pick costs besides its travel time, in seconds of travel: being
+/// in another future than the system's own; not having the root in the
+/// bass; and per unit of voicing badness (voices.glsl's 0 to 255: a
+/// sprawling, high or hard-modulated voicing costs up to 3 s more).
+const elsewhere = 0.5;
+const inverted = 0.6;
+const per_bad = 3.0 / 255.0;
+
+/// A snapshot's chord and voicing, as voices.glsl's `voicing` packs them.
+pub const Sung = packed struct(u32) {
+ chord: u12,
+ playable: bool,
+ _: u3,
+ lowest: u4,
+ _2: u4,
+ bad: u8,
+};
+
+/// The pitch classes three voices sing, as bits (C is bit 0): as
+/// voices.glsl's chordOf, for what is sounding.
+pub fn chordOf(voices: [3]layouts.Voice) u16 {
+ var mask: u16 = 0;
+ for (voices) |v| {
+ if (v.carrier <= 0) continue;
+ const midi: i32 = @intFromFloat(@round(69 + 12 * std.math.log2(v.carrier / 440)));
+ mask |= @as(u16, 1) << @intCast(@mod(midi, 12));
+ }
+ return mask;
+}
+
+const names = [12][]const u8{ "C", "C#", "D", "D#", "E", "F", "F#", "G", "G#", "A", "A#", "B" };
+
+fn bits(intervals: []const u4) u16 {
+ var m: u16 = 0;
+ for (intervals) |i| m |= @as(u16, 1) << i;
+ return m;
+}
+
+/// Chord shapes, most wanted first, as intervals over the root.
+const shapes = [_]struct { u16, []const u8 }{
+ .{ bits(&.{ 0, 4, 7 }), "" },
+ .{ bits(&.{ 0, 3, 7 }), "m" },
+ .{ bits(&.{ 0, 2, 7 }), "sus2" },
+ .{ bits(&.{ 0, 5, 7 }), "sus4" },
+ .{ bits(&.{ 0, 4, 10 }), "7" },
+ .{ bits(&.{ 0, 3, 10 }), "m7" },
+ .{ bits(&.{ 0, 4, 9 }), "6" },
+ .{ bits(&.{ 0, 3, 9 }), "m6" },
+ .{ bits(&.{ 0, 3, 6 }), "dim" },
+ .{ bits(&.{ 0, 4, 8 }), "aug" },
+ .{ bits(&.{ 0, 2, 4 }), "add9" },
+ .{ bits(&.{ 0, 5, 10 }), "7sus4" },
+ .{ bits(&.{ 0, 7, 10 }), "7no3" },
+ .{ bits(&.{ 0, 7 }), "5" },
+};
+
+/// A name for a set of pitch classes: a chord where one fits ("Am",
+/// "Csus2"), else the notes ("A+C+D").
+pub fn name(buf: []u8, mask: u16) []const u8 {
+ if (mask == 0) return "";
+ if (@popCount(mask) == 1) return names[@ctz(mask)];
+ for (shapes) |shape| for (0..12) |root| {
+ if (mask & (@as(u16, 1) << @intCast(root)) == 0) continue;
+ const r: u4 = @intCast(root);
+ const rotated = ((mask >> r) | (mask << @intCast(12 - @as(u5, r)))) & 0xfff;
+ if (rotated == shape[0]) return std.fmt.bufPrint(buf, "{s}{s}", .{ names[root], shape[1] }) catch "?";
+ };
+ var w: std.Io.Writer = .fixed(buf);
+ var first = true;
+ for (0..12) |pc| if (mask & (@as(u16, 1) << @intCast(pc)) != 0) {
+ w.print("{s}{s}", .{ if (first) "" else "+", names[pc] }) catch break;
+ first = false;
+ };
+ return w.buffered();
+}
+
+/// A snapshot: sample `sample` of future `alternative`, at `index` in the
+/// GPU's snapshot buffer.
+pub const Pick = struct {
+ sample: u32,
+ alternative: u32,
+
+ pub fn index(p: Pick) u32 {
+ return p.sample * alternatives + p.alternative;
+ }
+ pub fn time(p: Pick) f64 {
+ return @as(f64, @floatFromInt(p.sample)) * sample_dt;
+ }
+};
+
+/// The buttons, laid out as a sanfona's (Stradella) bass side: columns
+/// round the circle of fifths, so neighbours are related chords, and rows
+/// by quality, each half a button over from the one above, so a progression
+/// is the same shape of hand in any key.
+pub const Grid = struct {
+ pub const Quality = enum { major, minor, seventh, sus, power };
+ pub const rows = @typeInfo(Quality).@"enum".field_names.len;
+ pub const columns = 12;
+ /// Roots by column, by fifths from G flat to B, as pitch classes.
+ pub const roots = [columns]u4{ 6, 1, 8, 3, 10, 5, 0, 7, 2, 9, 4, 11 };
+ pub const root_names = [columns][]const u8{ "Gb", "Db", "Ab", "Eb", "Bb", "F", "C", "G", "D", "A", "E", "B" };
+
+ /// Three voices make triads at most: the seventh without its fifth.
+ pub fn shape(q: Quality) u16 {
+ return switch (q) {
+ .major => bits(&.{ 0, 4, 7 }),
+ .minor => bits(&.{ 0, 3, 7 }),
+ .seventh => bits(&.{ 0, 4, 10 }),
+ .sus => bits(&.{ 0, 5, 7 }),
+ .power => bits(&.{ 0, 7 }),
+ };
+ }
+
+ pub fn suffix(q: Quality) []const u8 {
+ return switch (q) {
+ .major => "",
+ .minor => "m",
+ .seventh => "7",
+ .sus => "sus",
+ .power => "5",
+ };
+ }
+
+ /// The chord of the button at `row`, `column`.
+ pub fn chord(row: usize, column: usize) u16 {
+ const s = shape(@enumFromInt(row));
+ const r: u4 = roots[column];
+ return ((s << r) | (s >> @intCast(12 - @as(u5, r)))) & 0xfff;
+ }
+
+ /// The button playing `mask`, if one does.
+ pub fn find(mask: u16) ?struct { row: usize, column: usize } {
+ for (0..rows) |row| for (0..columns) |column| {
+ if (chord(row, column) == mask) return .{ .row = row, .column = column };
+ };
+ return null;
+ }
+};
+
+pub const Ahead = struct {
+ /// The chords back from the GPU, with their voicings, sample-major as
+ /// it keeps them.
+ sung: [horizon][alternatives]Sung = undefined,
+ /// Samples asked of the GPU, and how many have come back.
+ asked: u32 = 0,
+ known: u32 = 0,
+ /// Every chord found in a playable voicing, by mask, and how many.
+ found: [1 << 12]bool = @splat(false),
+ distinct: u32 = 0,
+
+ pub fn reset(a: *Ahead) void {
+ a.asked = 0;
+ a.known = 0;
+ a.forget();
+ }
+
+ /// The chords again from nothing (another scale).
+ pub fn forget(a: *Ahead) void {
+ a.known = 0;
+ a.found = @splat(false);
+ a.distinct = 0;
+ }
+
+ /// Chords back from the GPU: samples from `first`, all alternatives.
+ pub fn arrived(a: *Ahead, first: u32, words: []const u32) void {
+ const samples: u32 = @intCast(words.len / alternatives);
+ for (0..samples) |s| {
+ const t = first + @as(u32, @intCast(s));
+ if (t >= horizon) break;
+ for (0..alternatives) |alt| {
+ const sung: Sung = @bitCast(words[s * alternatives + alt]);
+ a.sung[t][alt] = sung;
+ if (sung.playable) a.pad(sung.chord);
+ }
+ a.known = @max(a.known, t + 1);
+ }
+ }
+
+ fn pad(a: *Ahead, chord: u16) void {
+ if (chord == 0 or a.found[chord]) return;
+ a.found[chord] = true;
+ a.distinct += 1;
+ }
+
+ /// The best snapshot where `chord` plays in a playable voicing: near
+ /// `time`, in the system's own future, with `root` in the bass, and
+ /// sounding well, weighed against each other (see the costs above).
+ pub fn nearest(a: *const Ahead, chord: u16, root: u4, time: f64) ?Pick {
+ var best: ?Pick = null;
+ var cost: f64 = std.math.inf(f64);
+ for (a.sung[0..a.known], 0..) |row, t| for (row, 0..) |sung, alt| {
+ if (sung.chord != chord or !sung.playable) continue;
+ const pick: Pick = .{ .sample = @intCast(t), .alternative = @intCast(alt) };
+ const c = @abs(pick.time() - time) +
+ @as(f64, if (alt == 0) 0 else elsewhere) +
+ @as(f64, if (sung.lowest == root) 0 else inverted) +
+ per_bad * @as(f64, @floatFromInt(sung.bad));
+ if (c < cost) {
+ cost = c;
+ best = pick;
+ }
+ };
+ return best;
+ }
+};
+
+test "chords by name" {
+ var buf: [32]u8 = undefined;
+ const set = struct {
+ fn of(pcs: []const u5) u16 {
+ var m: u16 = 0;
+ for (pcs) |p| m |= @as(u16, 1) << @intCast(p);
+ return m;
+ }
+ }.of;
+ try std.testing.expectEqualStrings("Am", name(&buf, set(&.{ 9, 0, 4 })));
+ try std.testing.expectEqualStrings("C", name(&buf, set(&.{ 0, 4, 7 })));
+ try std.testing.expectEqualStrings("Csus2", name(&buf, set(&.{ 0, 2, 7 })));
+ try std.testing.expectEqualStrings("A5", name(&buf, set(&.{ 9, 4 })));
+ try std.testing.expectEqualStrings("E", name(&buf, set(&.{4})));
+ try std.testing.expectEqualStrings("C#+D", name(&buf, set(&.{ 1, 2 })));
+}
+
+fn word(chord: u12, playable: bool, lowest: u4, bad: u8) u32 {
+ return @bitCast(Sung{ .chord = chord, .playable = playable, ._ = 0, .lowest = lowest, ._2 = 0, .bad = bad });
+}
+
+test "a pick prefers the system's own future, unless another plays the chord much sooner" {
+ var a: Ahead = .{};
+ var words: [3 * alternatives]u32 = @splat(word(1, true, 0, 0));
+ // Chord 2 at sample 2 of future 0, and at sample 0 of future 5.
+ words[2 * alternatives + 0] = word(2, true, 1, 0);
+ words[0 * alternatives + 5] = word(2, true, 1, 0);
+ a.arrived(0, &words);
+ try std.testing.expectEqual(@as(u32, 3), a.known);
+ try std.testing.expect(a.found[1] and a.found[2]);
+ try std.testing.expectEqual(@as(u32, 2), a.distinct);
+ // From time 0.1: future 0 at 0.1 away beats future 5 at 0.1 + 0.5.
+ try std.testing.expectEqual(Pick{ .sample = 2, .alternative = 0 }, a.nearest(2, 1, 0.1).?);
+ // Ask for a chord no future plays: nothing.
+ try std.testing.expectEqual(@as(?Pick, null), a.nearest(4, 2, 0));
+}
+
+test "voicings: unplayable ones do not count, good ones win over near ones" {
+ var a: Ahead = .{};
+ var words: [3 * alternatives]u32 = @splat(word(1, true, 0, 0));
+ // Chord 2 now, but shrill and sprawling (unplayable); later, playable
+ // but inverted and harsh; later still, in root position and clean.
+ words[0] = word(2, false, 1, 0);
+ words[1 * alternatives] = word(2, true, 3, 200);
+ words[2 * alternatives] = word(2, true, 1, 0);
+ a.arrived(0, &words);
+ try std.testing.expectEqual(Pick{ .sample = 2, .alternative = 0 }, a.nearest(2, 1, 0).?);
+ // A chord heard only unplayably is not found.
+ var b: Ahead = .{};
+ var only: [alternatives]u32 = @splat(word(4, false, 2, 0));
+ b.arrived(0, &only);
+ try std.testing.expect(!b.found[4]);
+}
+
+test "the grid: fifths across, qualities down" {
+ var buf: [16]u8 = undefined;
+ // Column 6 is C, column 9 is A.
+ try std.testing.expectEqualStrings("C", name(&buf, Grid.chord(0, 6)));
+ try std.testing.expectEqualStrings("Am", name(&buf, Grid.chord(1, 9)));
+ try std.testing.expectEqualStrings("G5", name(&buf, Grid.chord(4, 7)));
+ const at = Grid.find(Grid.chord(2, 3)).?;
+ try std.testing.expectEqual(@as(usize, 2), at.row);
+ try std.testing.expectEqual(@as(usize, 3), at.column);
+ // Every button its own chord.
+ for (0..Grid.rows) |r| for (0..Grid.columns) |c| {
+ try std.testing.expectEqual(r, Grid.find(Grid.chord(r, c)).?.row);
+ };
+}
+
+test "voices to chords" {
+ const v = [3]layouts.Voice{
+ .{ .carrier = 220, .ratio = 1, .depth = 0, .amp = 1 },
+ .{ .carrier = 261.63, .ratio = 1, .depth = 0, .amp = 1 },
+ .{ .carrier = 329.63, .ratio = 1, .depth = 0, .amp = 1 },
+ };
+ var buf: [16]u8 = undefined;
+ try std.testing.expectEqualStrings("Am", name(&buf, chordOf(v)));
+}
diff --git a/examples/spheres/src/layouts.zig b/examples/spheres/src/layouts.zig
new file mode 100644
index 0000000..c282e16
--- /dev/null
+++ b/examples/spheres/src/layouts.zig
@@ -0,0 +1,163 @@
+//! What spheres' shaders read and write, as Zig structs: the only
+//! definition. The shaders include GLSL generated from the uniform blocks;
+//! storage layouts (std430) are mirrored by hand where noted. No imports.
+
+/// Copies of the system integrated side by side: system 0 is the one heard
+/// and drawn in full, the rest start a hair apart and show where it could
+/// have gone.
+pub const max_systems = 16384;
+pub const bodies = 3;
+/// Positions kept per body for the trail.
+pub const trail = 1024;
+/// The most samples synthesised in one frame.
+pub const max_block = 8192;
+/// The look-ahead (lookahead.comp): futures of system 0 integrated side by
+/// side, and snapshots kept of each, one every `chords.sample_dt`.
+pub const alternatives = 32;
+pub const horizon = 2400;
+
+/// One body of one system (std430: vec4).
+pub const Body = extern struct {
+ pos: [2]f32,
+ vel: [2]f32,
+};
+
+/// One voice's synthesis parameters (std430: vec4).
+pub const Voice = extern struct {
+ /// Hz.
+ carrier: f32,
+ /// Modulator over carrier frequency.
+ ratio: f32,
+ /// The modulation depth: PM's index; FM's deviation over the carrier;
+ /// AM's and the additive voice's brightness.
+ depth: f32,
+ amp: f32,
+};
+
+/// The voices buffer, in vec4s: what the synthesiser last used and what
+/// sim.comp set now, for the voices and the coupling between them.
+pub const voices_previous = 0;
+pub const voices_now = 3;
+/// Row i of the coupling: how much each voice's signal (x, y, z) pushes
+/// voice i's carrier phase. Only the closest pair couples.
+pub const coupling_previous = 6;
+pub const coupling_now = 9;
+pub const voices_len = 12;
+
+/// What sim.comp reports of system 0, for the CPU (std430).
+pub const Lead = extern struct {
+ bodies: [3]Body,
+ voices: [3]Voice,
+ /// Rows of the coupling, as in the voices buffer (w unused).
+ coupling: [3][4]f32,
+ /// Kinetic plus potential.
+ energy: f32,
+ /// Simulated time.
+ time: f32,
+ pad: [2]f32 = .{ 0, 0 },
+};
+
+pub const Mode = enum(u32) { sine, additive, am, ring, fm, pm };
+
+/// Where pitches snap; voices.glsl's `snap`. The uniforms carry it as a u32.
+pub const Scale = enum(u32) { free, pentatonic, diatonic, chromatic };
+
+/// sim.comp: one thread per system.
+pub const SimParams = extern struct {
+ systems: u32,
+ /// Substeps this frame, each `dt` (negative runs time backwards),
+ /// subdivided further where bodies pass close.
+ steps: u32,
+ dt: f32,
+ softening: f32,
+ masses: [4]f32,
+ /// Where system 0's positions go in the trail ring; past `trail`, none.
+ trail_head: u32,
+ quantize: u32,
+ /// The pitch at `speed_ref`, Hz.
+ base: f32,
+ speed_ref: f32,
+ /// Modulation depth at unit distance.
+ depth_scale: f32,
+ /// How hard the closest pair couples at unit distance.
+ couple_scale: f32,
+ /// A look-ahead snapshot, as its index plus one, or 0: system 0 sings
+ /// from it (a held chord) rather than from its own motion.
+ voice_source: u32 = 0,
+ /// Likewise: system 0 takes the snapshot's state before moving on.
+ adopt: u32 = 0,
+ /// Trail points this frame, by simulated time rather than by frame, so
+ /// a fast travel leaves as smooth a path as running does: after step
+ /// `trail_first` (1-based), then every `trail_every` steps, `trail_points`
+ /// of them, from slot `trail_head` on.
+ trail_points: u32 = 0,
+ trail_first: u32 = 1,
+ trail_every: u32 = 1,
+ pad0: u32 = 0,
+
+ pub const glsl = .{ .uniform = .{ .set = 2, .instance = "u" } };
+};
+
+/// lookahead.comp: alternatives `count` samples on from `first`; and
+/// rechord.comp: the chords of the first `count` snapshots again.
+pub const LookParams = extern struct {
+ alternatives: u32,
+ first: u32,
+ count: u32,
+ horizon: u32,
+ masses: [4]f32,
+ softening: f32,
+ quantize: u32,
+ base: f32,
+ speed_ref: f32,
+ depth_scale: f32,
+ couple_scale: f32,
+ sample_dt: f32,
+ pad: u32 = 0,
+
+ pub const glsl = .{ .uniform = .{ .set = 2, .instance = "u" } };
+};
+
+/// synth.comp: one thread per sample.
+pub const SynthParams = extern struct {
+ count: u32,
+ /// A `Mode`.
+ mode: u32,
+ rate: f32,
+ gain: f32,
+
+ pub const glsl = .{ .uniform = .{ .set = 2, .instance = "u" } };
+};
+
+/// The sky's camera and sprites (vertex uniforms).
+pub const SkyView = extern struct {
+ /// World point at the image's centre, and world units per pixel.
+ center: [2]f32,
+ size: [2]f32,
+ per_pixel: f32,
+ radius: f32,
+ alpha: f32,
+ first: u32,
+ count: u32,
+ /// Trail: where the newest point is, and how many are filled.
+ head: u32,
+ filled: u32,
+ /// Seconds, for what flows.
+ time: f32,
+ /// Trail segments longer than this (world units) are jumps, not motion
+ /// (system 0 stepping into a snapshot): not drawn.
+ gap: f32 = 1e9,
+ pad0: f32 = 0,
+ pad1: f32 = 0,
+ pad2: f32 = 0,
+
+ pub const glsl = .{ .uniform = .{ .set = 1, .instance = "u" } };
+};
+
+/// fade.frag: moves what is there `amount` of the way to `background`.
+pub const Fade = extern struct {
+ background: [3]f32,
+ amount: f32,
+
+ pub const glsl = .{ .uniform = .{ .set = 3, .instance = "u" } };
+};
diff --git a/examples/spheres/src/main.zig b/examples/spheres/src/main.zig
new file mode 100644
index 0000000..60b498f
--- /dev/null
+++ b/examples/spheres/src/main.zig
@@ -0,0 +1,1134 @@
+//! spheres: the three-body problem, heard. Three bodies attract each other;
+//! the GPU integrates thousands of copies of them at once, each a hair
+//! apart, and draws them as a cloud around the one it follows in full, so
+//! chaos shows as the cloud spreading (and a stable orbit as it staying a
+//! thin line). Each body is also a voice, synthesised on the GPU from its
+//! motion: speed is pitch, the balance of its two distances is the
+//! modulator's ratio, and the nearness of its closest neighbour is the
+//! modulation depth, as sine, additive, AM, ring, FM or PM synthesis. The
+//! scope shows the result: an oscilloscope, the spectrum with each voice's
+//! predicted partials marked, and a spectrogram.
+//!
+//! Memory by lifetime: State is the preset, the transport and the
+//! synthesis settings, changed by `update` and replayable. Session holds the
+//! GPU objects, the sound on its way to the speakers and the scope. No
+//! Store: a run is not worth keeping.
+const std = @import("std");
+const sk = @import("sketch");
+const gpu = sk.abi.gpu;
+const scope = @import("scope");
+const layouts = @import("layouts");
+const shaders = @import("shaders");
+const chords = @import("chords.zig");
+
+pub const name = "spheres";
+pub const width = 1280;
+pub const height = 800;
+
+/// The audio stream's key.
+const stream = 1;
+/// How much sound is kept queued ahead: synthesised, read back, queued.
+const lead_seconds = 0.1;
+/// Systems integrated: system 0 and its cloud.
+const systems = layouts.max_systems;
+/// How far apart the copies start.
+const spread = 2e-4;
+const background = 0x05070d;
+/// Body colours; match the shaders' palette.
+const palette = [3]u24{ 0x66d9ff, 0xff73d1, 0xffcc59 };
+
+pub const Preset = enum {
+ figure_eight,
+ butterfly,
+ pythagorean,
+ lagrange,
+ random,
+
+ fn label(p: Preset) []const u8 {
+ return switch (p) {
+ .figure_eight => "figure eight",
+ .butterfly => "butterfly",
+ .pythagorean => "Pythagorean",
+ .lagrange => "Lagrange triangle",
+ .random => "random",
+ };
+ }
+};
+pub const Mode = layouts.Mode;
+pub const Scale = layouts.Scale;
+
+pub const State = struct {
+ preset: Preset = .figure_eight,
+ /// Starts the preset over, its copies spread with this seed.
+ reset: sk.Request(u32) = .{},
+ running: bool = true,
+ backward: bool = false,
+ /// Simulated time per second: a little under real time, so the
+ /// look-ahead's share of each frame keeps it well ahead.
+ speed: f32 = 0.7,
+ mode: Mode = .additive,
+ /// Where pitches snap: the more notes, the more chords.
+ scale: Scale = .diatonic,
+ muted: bool = false,
+ /// The voice whose partials the spectrum marks in full.
+ focus: u8 = 0,
+ /// Played as an instrument: chord pads, each sending the sky to the
+ /// nearest time its chord plays and holding the chord. Off, it runs on
+ /// by itself.
+ instrument: bool = false,
+ /// A chord to play, as its pitch classes (a grid button's).
+ chord: sk.Request(u16) = .{},
+};
+
+/// On the way to a pad's chord: where to, and how fast (simulated seconds
+/// a second).
+const Travel = struct { to: chords.Pick, speed: f64 };
+
+pub const Session = struct {
+ reset: sk.Handled = .{},
+ started: bool = false,
+ /// Synthesised samples not back from the GPU yet.
+ in_flight: usize = 0,
+ /// System 0 as last read back, and whether it has been.
+ lead: layouts.Lead = std.mem.zeroes(layouts.Lead),
+ have_lead: bool = false,
+ masses: [3]f32 = .{ 1, 1, 1 },
+ softening: f32 = 0.01,
+ /// The trail's newest slot, how many are filled, and the steps since its
+ /// last point.
+ trail_head: u32 = 0,
+ trail_filled: u32 = 0,
+ trail_carry: u32 = 0,
+ /// The camera: world point at the sky's centre, and the half-extent it
+ /// shows, smoothed.
+ center: [2]f32 = .{ 0, 0 },
+ extent: f32 = 1.5,
+ scope: scope.Scope = .{},
+ /// Simulated time since the preset started.
+ time: f64 = 0,
+ chord: sk.Handled = .{},
+ ahead: chords.Ahead = .{},
+ /// The scale the look-ahead's chords were found with.
+ scale: Scale = .diatonic,
+ travel: ?Travel = null,
+ /// The snapshot whose chord is held.
+ held: ?chords.Pick = null,
+ /// Samples still to come back from before a chord was chosen, dropped.
+ discard: usize = 0,
+ gpu: Gpu = .{},
+};
+
+const Gpu = struct {
+ ahead_state: sk.Buffer = .none,
+ snapshots: sk.Buffer = .none,
+ ahead_chords: sk.Buffer = .none,
+ ready: bool = false,
+ bodies: sk.Buffer = .none,
+ trail: sk.Buffer = .none,
+ voices: sk.Buffer = .none,
+ phases: sk.Buffer = .none,
+ lead: sk.Buffer = .none,
+ block: sk.Buffer = .none,
+ sky: sk.Image = .none,
+ overlay: sk.Image = .none,
+ size: [2]u32 = .{ 0, 0 },
+ clear_sky: bool = true,
+};
+
+/// Readback keys; from `chords_from`, look-ahead chords from that sample.
+const Readback = enum(u32) { audio = 1, lead = 2, _ };
+const chords_from = 0x10000;
+
+// ---------------------------------------------------------------------------
+// Layout.
+
+const Layout = struct {
+ w: f32,
+ h: f32,
+ narrow: bool,
+ sky: sk.Rect,
+ voices: sk.Rect,
+ oscilloscope: sk.Rect,
+ spectrum: sk.Rect,
+ spectrogram: sk.Rect,
+ /// As an instrument: the look-ahead's chords along time, and the grid.
+ strip: sk.Rect = .{},
+ grid: sk.Rect = .{},
+
+ const header = 36;
+ const Grid = chords.Grid;
+ /// The grid's columns on a phone: B flat to B, round C.
+ const narrow_columns = 8;
+ const narrow_first = 4;
+ /// Two rows of buttons, on a phone.
+ const toolbar = 104;
+ const per_row = buttons.len / 2;
+
+ /// Wide: the sky on the left, the sound on the right, buttons on top.
+ /// Narrow (a phone): the sky, then the sound, buttons along the bottom.
+ fn of(w: f32, h: f32, instrument: bool) Layout {
+ const narrow = w < 900;
+ if (narrow) {
+ const sky_h = @round(@min(w, h * if (instrument) @as(f32, 0.27) else 0.42));
+ const sky: sk.Rect = .{ .x = 0, .y = header, .w = w, .h = sky_h };
+ var y = sky.y + sky.h;
+ var strip: sk.Rect = .{};
+ var grid: sk.Rect = .{};
+ if (instrument) {
+ strip = .{ .x = 8, .y = y + 6, .w = w - 16, .h = 10 };
+ grid = .{ .x = 8, .y = strip.y + strip.h + 6, .w = w - 16, .h = Grid.rows * 36 - 4 };
+ y = grid.y + grid.h;
+ }
+ const voices: sk.Rect = .{ .x = 8, .y = y + 6, .w = w - 16, .h = 54 };
+ // As an instrument the grid takes the oscilloscope's room.
+ const oscilloscope: sk.Rect = if (instrument) .{ .x = 8, .y = voices.y + voices.h, .w = 0, .h = 0 } else .{ .x = 8, .y = voices.y + voices.h + 4, .w = w - 16, .h = 64 };
+ const spectrum: sk.Rect = .{ .x = 8, .y = oscilloscope.y + oscilloscope.h + 6, .w = w - 16, .h = if (instrument) 90 else 120 };
+ const rest = h - toolbar - (spectrum.y + spectrum.h + 22);
+ return .{ .w = w, .h = h, .narrow = true, .sky = sky, .voices = voices, .oscilloscope = oscilloscope, .spectrum = spectrum, .spectrogram = .{ .x = 8, .y = spectrum.y + spectrum.h + 18, .w = w - 16, .h = @max(rest, 40) }, .strip = strip, .grid = grid };
+ }
+ const sky_w = @round((w - 48) * 0.58);
+ const full: sk.Rect = .{ .x = 16, .y = header + 8, .w = sky_w, .h = h - header - 8 - 28 };
+ var sky = full;
+ var strip: sk.Rect = .{};
+ var grid: sk.Rect = .{};
+ if (instrument) {
+ const grid_h: f32 = Grid.rows * 30 - 4;
+ sky.h -= grid_h + 34;
+ strip = .{ .x = sky.x, .y = sky.y + sky.h + 8, .w = sky.w, .h = 10 };
+ grid = .{ .x = sky.x, .y = strip.y + strip.h + 8, .w = sky.w, .h = grid_h };
+ }
+ const x = sky.x + sky.w + 16;
+ const cw = w - 16 - x;
+ const voices: sk.Rect = .{ .x = x, .y = sky.y, .w = cw, .h = 66 };
+ const oscilloscope: sk.Rect = .{ .x = x, .y = voices.y + voices.h + 6, .w = cw, .h = 110 };
+ const spectrum: sk.Rect = .{ .x = x, .y = oscilloscope.y + oscilloscope.h + 10, .w = cw, .h = 210 };
+ const spectrogram_y = spectrum.y + spectrum.h + 20;
+ return .{ .w = w, .h = h, .narrow = false, .sky = sky, .voices = voices, .oscilloscope = oscilloscope, .spectrum = spectrum, .spectrogram = .{ .x = x, .y = spectrogram_y, .w = cw, .h = full.y + full.h - spectrogram_y }, .strip = strip, .grid = grid };
+ }
+
+ /// The grid's columns on screen: all twelve, or a phone's eight.
+ fn columns(l: Layout) struct { first: usize, count: usize } {
+ return if (l.narrow) .{ .first = narrow_first, .count = narrow_columns } else .{ .first = 0, .count = Grid.columns };
+ }
+
+ /// The button at `row` and grid `column`, if on screen: rows staggered
+ /// half a button right each, as on a sanfona.
+ fn key(l: Layout, row: usize, column: usize) ?sk.Rect {
+ const cols = l.columns();
+ if (column < cols.first or column >= cols.first + cols.count) return null;
+ const gap = 4;
+ const n: f32 = @floatFromInt(cols.count);
+ const w = (l.grid.w - (n - 1) * gap) / (n + @as(f32, Grid.rows - 1) * 0.5);
+ const h = (l.grid.h - (Grid.rows - 1) * gap) / Grid.rows;
+ const r: f32 = @floatFromInt(row);
+ const j: f32 = @floatFromInt(column - cols.first);
+ return .{ .x = l.grid.x + r * w * 0.5 + j * (w + gap), .y = l.grid.y + r * (h + gap), .w = w, .h = h };
+ }
+
+ fn keyAt(l: Layout, x: f32, y: f32) ?u16 {
+ for (0..Grid.rows) |row| for (0..Grid.columns) |column| {
+ if (l.key(row, column)) |r| if (r.contains(x, y)) return Grid.chord(row, column);
+ };
+ return null;
+ }
+
+ fn button(l: Layout, i: usize) sk.Rect {
+ const n: f32 = @floatFromInt(buttons.len);
+ const at: f32 = @floatFromInt(i);
+ if (l.narrow) {
+ const per: f32 = per_row;
+ const w = (l.w - 8 - (per - 1) * 4) / per;
+ const column = @mod(at, per);
+ const line = @floor(at / per);
+ return .{ .x = 4 + column * (w + 4), .y = l.h - toolbar + 6 + line * 48, .w = w, .h = 44 };
+ }
+ const w = 66;
+ return .{ .x = l.w - 16 - (n - at) * (w + 6) + 6, .y = 5, .w = w, .h = 26 };
+ }
+
+ fn buttonAt(l: Layout, x: f32, y: f32) ?Action {
+ for (buttons, 0..) |a, i| if (l.button(i).contains(x, y)) return a;
+ return null;
+ }
+};
+
+// ---------------------------------------------------------------------------
+// Update.
+
+const Action = enum { play, reverse, mode, preset, scale, mute, faster, slower, reset, focus, eight, random, instrument };
+
+const keys = [_]struct { sk.Key, Action }{
+ .{ .space, .play }, .{ .left, .reverse }, .{ .right, .reverse }, .{ .s, .mode }, .{ .p, .preset },
+ .{ .q, .scale }, .{ .m, .mute }, .{ .up, .faster }, .{ .down, .slower }, .{ .r, .reset },
+ .{ .tab, .focus }, .{ .e, .eight }, .{ .x, .random }, .{ .c, .instrument },
+};
+
+/// What touch screens reach by button; on a phone, in two rows of four.
+const buttons = [_]Action{ .play, .reverse, .mode, .mute, .eight, .random, .instrument, .scale };
+
+/// The computer keyboard as the grid: its rows are staggered like a
+/// sanfona's, so the number row plays majors, QWERTY minors, ASDF sevenths
+/// and ZXCV sus chords, column by column round the fifths.
+const grid_keys = [_][]const sk.Key{
+ &.{ .@"1", .@"2", .@"3", .@"4", .@"5", .@"6", .@"7", .@"8", .@"9", .@"0", .minus, .equals },
+ &.{ .q, .w, .e, .r, .t, .y, .u, .i, .o, .p, .left_bracket, .right_bracket },
+ &.{ .a, .s, .d, .f, .g, .h, .j, .k, .l, .semicolon, .apostrophe },
+ &.{ .z, .x, .c, .v, .b, .n, .m, .comma, .period, .slash },
+};
+
+fn isLetterOrDigit(k: sk.Key) bool {
+ const v = @intFromEnum(k);
+ return v >= @intFromEnum(sk.Key.a) and v <= @intFromEnum(sk.Key.@"0");
+}
+
+pub fn update(s: *State, in: *const sk.Input) void {
+ // As an instrument, letters and digits play chords; Escape leaves.
+ if (s.instrument) {
+ for (grid_keys, 0..) |row, r| for (row, 0..) |k, column| {
+ if (in.pressed(k)) s.chord.send(chords.Grid.chord(r, column));
+ };
+ if (in.pressed(sk.Key.escape)) s.instrument = false;
+ }
+ for (keys) |k| if (in.pressed(k[0]) and !(s.instrument and isLetterOrDigit(k[0]))) {
+ // Left and right choose the way rather than flip it.
+ if (k[0] == .left) s.backward = true else if (k[0] == .right) s.backward = false else act(s, k[1]);
+ if (k[0] == .left or k[0] == .right) s.running = true;
+ };
+ const l = Layout.of(in.width, in.height, s.instrument);
+ for (in.events) |e| if (e.kind == .mouse_down and e.code == 1) {
+ if (l.buttonAt(e.x, e.y)) |a| act(s, a);
+ if (s.instrument) if (l.keyAt(e.x, e.y)) |chord| s.chord.send(chord);
+ };
+}
+
+fn act(s: *State, a: Action) void {
+ switch (a) {
+ .play => s.running = !s.running,
+ .reverse => {
+ s.backward = !s.backward;
+ s.running = true;
+ },
+ .mode => s.mode = @enumFromInt((@intFromEnum(s.mode) + 1) % @typeInfo(Mode).@"enum".field_names.len),
+ .preset => choose(s, @enumFromInt((@intFromEnum(s.preset) + 1) % @typeInfo(Preset).@"enum".field_names.len)),
+ .scale => s.scale = @enumFromInt((@intFromEnum(s.scale) + 1) % @typeInfo(Scale).@"enum".field_names.len),
+ .mute => s.muted = !s.muted,
+ .faster => s.speed = @min(s.speed * 1.25, 8),
+ .slower => s.speed = @max(s.speed / 1.25, 0.05),
+ .reset => s.reset.send(s.reset.value +% 1),
+ .focus => s.focus = (s.focus + 1) % 3,
+ .eight => choose(s, .figure_eight),
+ // A new seed each time: new bodies.
+ .random => choose(s, .random),
+ .instrument => s.instrument = !s.instrument,
+ }
+}
+
+fn choose(s: *State, p: Preset) void {
+ s.preset = p;
+ s.backward = false;
+ s.running = true;
+ s.reset.send(s.reset.value +% 1);
+}
+
+// ---------------------------------------------------------------------------
+// The presets.
+
+const Start = struct { masses: [3]f32, bodies: [3]layouts.Body, softening: f32 = 0.01 };
+
+fn start(p: Preset, seed: u32) Start {
+ return switch (p) {
+ // Chenciner and Montgomery's: three equal masses chasing each
+ // other round one figure of eight. Stable: the cloud stays thin.
+ .figure_eight => .{ .masses = .{ 1, 1, 1 }, .bodies = .{
+ .{ .pos = .{ 0.97000436, -0.24308753 }, .vel = .{ 0.46620368, 0.43236573 } },
+ .{ .pos = .{ -0.97000436, 0.24308753 }, .vel = .{ 0.46620368, 0.43236573 } },
+ .{ .pos = .{ 0, 0 }, .vel = .{ -0.93240737, -0.86473146 } },
+ } },
+ // Šuvakov and Dmitrašinović's butterfly I: periodic, and not stable.
+ .butterfly => .{ .masses = .{ 1, 1, 1 }, .bodies = .{
+ .{ .pos = .{ -1, 0 }, .vel = .{ 0.30689, 0.12551 } },
+ .{ .pos = .{ 1, 0 }, .vel = .{ 0.30689, 0.12551 } },
+ .{ .pos = .{ 0, 0 }, .vel = .{ -0.61378, -0.25102 } },
+ } },
+ // Burrau's: masses 3, 4 and 5 at rest on a 3-4-5 triangle. Close
+ // passes, chaos, and in the end two bodies leave as a pair.
+ .pythagorean => .{ .masses = .{ 3, 4, 5 }, .bodies = centred(.{ 3, 4, 5 }, .{
+ .{ .pos = .{ 1, 3 }, .vel = .{ 0, 0 } },
+ .{ .pos = .{ -2, -1 }, .vel = .{ 0, 0 } },
+ .{ .pos = .{ 1, -1 }, .vel = .{ 0, 0 } },
+ }) },
+ // Lagrange's equilateral solution, turning rigidly. For equal
+ // masses it is unstable: the cloud shows it coming apart.
+ .lagrange => blk: {
+ const speed: f32 = @sqrt(1.0 / @sqrt(3.0));
+ var bodies: [3]layouts.Body = undefined;
+ for (&bodies, 0..) |*b, i| {
+ const a = @as(f32, @floatFromInt(i)) * std.math.tau / 3;
+ b.* = .{ .pos = .{ @cos(a), @sin(a) }, .vel = .{ -@sin(a) * speed, @cos(a) * speed } };
+ }
+ break :blk .{ .masses = .{ 1, 1, 1 }, .bodies = bodies };
+ },
+ .random => blk: {
+ var rng: std.Random.DefaultPrng = .init(seed);
+ const r = rng.random();
+ var masses: [3]f32 = undefined;
+ var bodies: [3]layouts.Body = undefined;
+ for (&masses, &bodies) |*m, *b| {
+ m.* = 0.6 + 0.8 * r.float(f32);
+ b.* = .{ .pos = .{ 2 * r.float(f32) - 1, 2 * r.float(f32) - 1 }, .vel = .{ 0.6 * (r.float(f32) - 0.5), 0.6 * (r.float(f32) - 0.5) } };
+ }
+ break :blk .{ .masses = masses, .bodies = centred(masses, bodies) };
+ },
+ };
+}
+
+/// The bodies moved and pushed so their centre of mass sits still at 0.
+fn centred(masses: [3]f32, bodies: [3]layouts.Body) [3]layouts.Body {
+ var total: f32 = 0;
+ var p: [2]f32 = .{ 0, 0 };
+ var v: [2]f32 = .{ 0, 0 };
+ for (masses, bodies) |m, b| {
+ total += m;
+ for (0..2) |k| {
+ p[k] += m * b.pos[k];
+ v[k] += m * b.vel[k];
+ }
+ }
+ var out = bodies;
+ for (&out) |*b| for (0..2) |k| {
+ b.pos[k] -= p[k] / total;
+ b.vel[k] -= v[k] / total;
+ };
+ return out;
+}
+
+// ---------------------------------------------------------------------------
+// Draw.
+
+pub fn draw(s: *const State, ss: *Session, f: *sk.Frame) void {
+ const in = f.in;
+ f.canvas(@intFromFloat(@max(in.window_width, 320)), @intFromFloat(@max(in.window_height, 400)));
+ f.clear(background);
+ if (!f.host.gpu()) {
+ f.text(16, 40, 2, "spheres needs a GPU: the host has none.", 0xff8080);
+ return;
+ }
+ const rate: f64 = @floatFromInt(in.sample_rate);
+ const dt: f32 = @floatCast(@min(@as(f64, @floatFromInt(in.dt)) / std.time.ns_per_s, 0.05));
+ const g = &ss.gpu;
+ setup(g, f);
+
+ // What came back: sound for the speakers and the scope, and system 0.
+ for (in.downloads) |d| switch (@as(Readback, @enumFromInt(d.key))) {
+ .audio => {
+ const samples = std.mem.bytesAsSlice(f32, d.bytes[0 .. d.bytes.len / 4 * 4]);
+ const aligned = f.scratch.alloc(f32, samples.len) catch continue;
+ for (aligned, samples) |*to, from| to.* = from;
+ ss.in_flight -|= aligned.len;
+ // Sound made before a chord was chosen is not played.
+ const dropped = @min(ss.discard, aligned.len);
+ ss.discard -= dropped;
+ f.audio(stream, aligned[dropped..], .{});
+ ss.scope.push(aligned[dropped..]);
+ },
+ .lead => if (d.bytes.len >= @sizeOf(layouts.Lead)) {
+ ss.lead = std.mem.bytesToValue(layouts.Lead, d.bytes[0..@sizeOf(layouts.Lead)]);
+ ss.have_lead = true;
+ },
+ _ => if (d.key >= chords_from) {
+ const words = f.scratch.alloc(u32, d.bytes.len / 4) catch continue;
+ @memcpy(std.mem.sliceAsBytes(words), d.bytes[0 .. words.len * 4]);
+ ss.ahead.arrived(d.key - chords_from, words);
+ },
+ };
+
+ if (!ss.started or ss.reset.take(s.reset) != null) restart(s, ss, f);
+ if (!s.instrument) {
+ ss.travel = null;
+ ss.held = null;
+ }
+ lookAhead(s, ss, f);
+
+ // A chord: the sound jumps to it now, the sky travels there.
+ if (ss.chord.take(s.chord)) |chord| if (s.instrument and ss.ahead.found[chord]) {
+ const root: u4 = if (chords.Grid.find(chord)) |at| chords.Grid.roots[at.column] else 0;
+ if (ss.ahead.nearest(chord, root, ss.time)) |pick| {
+ ss.held = pick;
+ ss.travel = .{ .to = pick, .speed = @max(@abs(pick.time() - ss.time) / 1.2, 2) };
+ f.audio(stream, &.{}, .{ .clear = true });
+ ss.discard = ss.in_flight;
+ }
+ };
+
+ // The simulation: as much simulated time as `speed` asks, either way;
+ // or, travelling to a chord, as fast as it takes to arrive in a second
+ // or so, where system 0 takes the snapshot's state. It runs every frame,
+ // still or not, so system 0 always sings: a held chord, or its motion.
+ var span: f64 = 0;
+ var adopt: u32 = 0;
+ if (ss.travel) |travel| {
+ const remaining = travel.to.time() - ss.time;
+ const step = travel.speed * dt;
+ if (@abs(remaining) <= step) {
+ adopt = travel.to.index() + 1;
+ ss.time = travel.to.time();
+ ss.travel = null;
+ } else span = std.math.sign(remaining) * step;
+ } else if (s.running and !(s.instrument and ss.held != null)) {
+ // Arrived at a chord, the sky holds still on the moment that sings it.
+ span = s.speed * dt * @as(f64, if (s.backward) -1 else 1);
+ }
+ const steps: u32 = @intFromFloat(@min(@ceil(@abs(span) / chords.base_step), 256));
+ var trail = trailPoints(ss, steps, span);
+ // Travelling back retraces system 0's own path: its trail rewinds rather
+ // than drawing over itself, as far as it reaches.
+ if (ss.travel != null and span < 0 and trail.points < ss.trail_filled) {
+ ss.trail_head = (ss.trail_head + layouts.trail - trail.points) % layouts.trail;
+ ss.trail_filled -= trail.points;
+ trail.points = 0;
+ }
+ f.compute(.{
+ .label = "sim.comp",
+ .kernel = sim_kernel,
+ .readonly = &.{g.snapshots},
+ .readwrite = &.{ g.bodies, g.trail, g.voices, g.lead },
+ .uniforms = gpu.uniform(f.scratch, layouts.SimParams{
+ .systems = systems,
+ .steps = steps,
+ .dt = if (steps > 0) @floatCast(span / @as(f64, @floatFromInt(steps))) else 0,
+ .softening = ss.softening,
+ .masses = .{ ss.masses[0], ss.masses[1], ss.masses[2], 0 },
+ .trail_head = (ss.trail_head + 1) % layouts.trail,
+ .trail_points = trail.points,
+ .trail_first = trail.first,
+ .trail_every = trail.every,
+ .quantize = @intFromEnum(s.scale),
+ .base = chords.base,
+ .speed_ref = chords.speed_ref,
+ .depth_scale = chords.depth_scale,
+ .couple_scale = chords.couple_scale,
+ .voice_source = if (ss.held) |h| h.index() + 1 else 0,
+ .adopt = adopt,
+ }),
+ .groups = .{ (systems + 63) / 64, 1, 1 },
+ });
+ ss.time += span;
+ ss.trail_head = (ss.trail_head + trail.points) % layouts.trail;
+ ss.trail_filled = @min(ss.trail_filled + trail.points, layouts.trail);
+ f.download(g.lead, .{ .size = @sizeOf(layouts.Lead), .key = @intFromEnum(Readback.lead) });
+
+ // The sound: enough to keep `lead_seconds` queued, counting what is
+ // still on its way back from the GPU.
+ const queued = in.stream(stream).queued + ss.in_flight;
+ const want: usize = @min(@as(usize, @intFromFloat(lead_seconds * rate)) -| queued, layouts.max_block);
+ if (want > 0) {
+ const params = gpu.uniform(f.scratch, layouts.SynthParams{
+ .count = @intCast(want),
+ .mode = @intFromEnum(s.mode),
+ .rate = @floatCast(rate),
+ // Loud enough for a phone's speaker; tanh rounds the peaks off.
+ .gain = if (s.muted) 0 else 1.4,
+ });
+ f.compute(.{
+ .label = "synth.comp",
+ .kernel = synth_kernel,
+ .readonly = &.{ g.voices, g.phases },
+ .readwrite = &.{g.block},
+ .uniforms = params,
+ .groups = .{ @intCast((want + 63) / 64), 1, 1 },
+ });
+ f.compute(.{ .label = "advance.comp", .kernel = advance_kernel, .readwrite = &.{ g.voices, g.phases }, .uniforms = params });
+ f.download(g.block, .{ .size = @intCast(want * @sizeOf(f32)), .key = @intFromEnum(Readback.audio) });
+ ss.in_flight += want;
+ }
+
+ const l = Layout.of(in.width, in.height, s.instrument);
+ follow(ss, dt);
+ drawSky(s, ss, f, l);
+ sound(s, ss, f, l, rate);
+ labels(s, ss, f, l, rate);
+}
+
+/// Simulated time between trail points: about a frame's at the default
+/// speed, and many points a frame when travelling.
+const trail_dt = 0.012;
+
+/// Which of this frame's `steps` leave trail points: every so many steps,
+/// carrying the remainder to the next frame, 64 at most.
+fn trailPoints(ss: *Session, steps: u32, span: f64) struct { points: u32, first: u32, every: u32 } {
+ if (steps == 0) return .{ .points = 0, .first = 1, .every = 1 };
+ const step_dt = @abs(span) / @as(f64, @floatFromInt(steps));
+ var every: u32 = @intFromFloat(@max(1, @round(trail_dt / step_dt)));
+ var first = every -| @min(ss.trail_carry, every - 1);
+ var points: u32 = if (first > steps) 0 else 1 + (steps - first) / every;
+ if (points > 64) {
+ every = (steps + 63) / 64;
+ first = every;
+ points = steps / every;
+ }
+ ss.trail_carry = if (points == 0) ss.trail_carry + steps else steps - (first + (points - 1) * every);
+ return .{ .points = points, .first = first, .every = every };
+}
+
+fn setup(g: *Gpu, f: *sk.Frame) void {
+ if (g.ready) return;
+ g.ready = true;
+ g.bodies = f.host.newBuffer(systems * layouts.bodies * @sizeOf(layouts.Body));
+ g.trail = f.host.newBuffer(layouts.bodies * layouts.trail * @sizeOf([2]f32));
+ g.voices = f.host.newBuffer(layouts.voices_len * @sizeOf([4]f32));
+ g.phases = f.host.newBuffer(3 * @sizeOf([4]f32));
+ g.lead = f.host.newBuffer(@sizeOf(layouts.Lead));
+ g.block = f.host.newBuffer(layouts.max_block * @sizeOf(f32));
+ g.ahead_state = f.host.newBuffer(layouts.alternatives * 3 * @sizeOf(layouts.Body));
+ g.snapshots = f.host.newBuffer(layouts.horizon * layouts.alternatives * 3 * @sizeOf(layouts.Body));
+ g.ahead_chords = f.host.newBuffer(layouts.horizon * layouts.alternatives * @sizeOf(u32));
+}
+
+fn lookParams(s: *const State, ss: *const Session, first: u32, count: u32) layouts.LookParams {
+ return .{
+ .alternatives = layouts.alternatives,
+ .first = first,
+ .count = count,
+ .horizon = layouts.horizon,
+ .masses = .{ ss.masses[0], ss.masses[1], ss.masses[2], 0 },
+ .softening = ss.softening,
+ .quantize = @intFromEnum(s.scale),
+ .base = chords.base,
+ .speed_ref = chords.speed_ref,
+ .depth_scale = chords.depth_scale,
+ .couple_scale = chords.couple_scale,
+ .sample_dt = chords.sample_dt,
+ };
+}
+
+/// The look-ahead: its futures a few samples further, their chords on
+/// their way back; and all the chords again when the scale changes.
+fn lookAhead(s: *const State, ss: *Session, f: *sk.Frame) void {
+ const g = &ss.gpu;
+ if (ss.scale != s.scale) {
+ ss.scale = s.scale;
+ const count = ss.ahead.asked * layouts.alternatives;
+ ss.ahead.forget();
+ if (count > 0) {
+ f.compute(.{
+ .label = "rechord.comp",
+ .kernel = rechord_kernel,
+ .readonly = &.{g.snapshots},
+ .readwrite = &.{g.ahead_chords},
+ .uniforms = gpu.uniform(f.scratch, lookParams(s, ss, 0, count)),
+ .groups = .{ (count + 63) / 64, 1, 1 },
+ });
+ f.download(g.ahead_chords, .{ .size = count * @sizeOf(u32), .key = chords_from });
+ }
+ }
+ if (ss.ahead.asked >= layouts.horizon) return;
+ const first = ss.ahead.asked;
+ const count: u32 = @min(chords.per_frame, layouts.horizon - first);
+ f.compute(.{
+ .label = "lookahead.comp",
+ .kernel = lookahead_kernel,
+ .readwrite = &.{ g.ahead_state, g.snapshots, g.ahead_chords },
+ .uniforms = gpu.uniform(f.scratch, lookParams(s, ss, first, count)),
+ });
+ f.download(g.ahead_chords, .{ .offset = first * layouts.alternatives * @sizeOf(u32), .size = count * layouts.alternatives * @sizeOf(u32), .key = chords_from + first });
+ ss.ahead.asked += count;
+}
+
+/// Puts the preset on the GPU: system 0 as given, the others each body
+/// moved by up to `spread`.
+fn restart(s: *const State, ss: *Session, f: *sk.Frame) void {
+ ss.started = true;
+ const p = start(s.preset, s.reset.value);
+ ss.masses = p.masses;
+ ss.softening = p.softening;
+ const all = f.scratch.alloc(layouts.Body, systems * layouts.bodies) catch return;
+ var rng: std.Random.DefaultPrng = .init(s.reset.value *% 0x9e3779b9 +% 1);
+ const r = rng.random();
+ for (0..systems) |i| for (0..3) |b| {
+ var body = p.bodies[b];
+ if (i > 0) for (&body.pos) |*x| {
+ x.* += spread * (2 * r.float(f32) - 1);
+ };
+ all[3 * i + b] = body;
+ };
+ f.upload(ss.gpu.bodies, 0, std.mem.sliceAsBytes(all));
+ // The voices glide from a quiet start, uncoupled; the trail starts empty.
+ const quiet = f.scratch.alloc([4]f32, layouts.voices_len) catch return;
+ for (quiet, 0..) |*v, i| v.* = if (i < layouts.coupling_previous) .{ 220, 1, 0, 0 } else .{ 0, 0, 0, 0 };
+ f.upload(ss.gpu.voices, 0, std.mem.sliceAsBytes(quiet));
+ const lead = f.scratch.create(layouts.Lead) catch return;
+ lead.* = std.mem.zeroes(layouts.Lead);
+ lead.bodies = p.bodies;
+ f.upload(ss.gpu.lead, 0, std.mem.asBytes(lead));
+ ss.lead = lead.*;
+ ss.have_lead = true;
+ ss.trail_filled = 0;
+ ss.trail_carry = 0;
+ // The look-ahead's futures: 0 as given, the rest nudged by growing
+ // amounts, so in a chaotic system they fan out.
+ const futures = f.scratch.alloc(layouts.Body, layouts.alternatives * 3) catch return;
+ for (0..layouts.alternatives) |a| for (0..3) |b| {
+ var body = p.bodies[b];
+ // Small enough that every future is recognisably this system,
+ // apart where chaos amplifies the difference.
+ const nudge = 2e-4 * @as(f32, @floatFromInt(a));
+ for (&body.pos) |*x| {
+ x.* += nudge * (2 * r.float(f32) - 1);
+ }
+ futures[3 * a + b] = body;
+ };
+ f.upload(ss.gpu.ahead_state, 0, std.mem.sliceAsBytes(futures));
+ ss.ahead.reset();
+ ss.scale = s.scale;
+ ss.time = 0;
+ ss.travel = null;
+ ss.held = null;
+ ss.gpu.clear_sky = true;
+ ss.extent = 1.5;
+}
+
+/// The camera keeps system 0's bodies in view: quick to widen, slow to
+/// close in.
+fn follow(ss: *Session, dt: f32) void {
+ var c: [2]f32 = .{ 0, 0 };
+ var total: f32 = 0;
+ for (ss.lead.bodies, ss.masses) |b, m| {
+ c[0] += m * b.pos[0];
+ c[1] += m * b.pos[1];
+ total += m;
+ }
+ c = .{ c[0] / total, c[1] / total };
+ var reach: f32 = 0;
+ for (ss.lead.bodies) |b| reach = @max(reach, @max(@abs(b.pos[0] - c[0]), @abs(b.pos[1] - c[1])));
+ const want = std.math.clamp(reach * 1.25, 1.2, 40);
+ const rate: f32 = if (want > ss.extent) 4 else 0.6;
+ ss.extent += (want - ss.extent) * (1 - @exp(-rate * dt));
+ for (&ss.center, c) |*x, to| x.* += (to - x.*) * (1 - @exp(-2 * dt));
+}
+
+const sim_kernel: gpu.Kernel = .{ .code = shaders.sim_comp, .readonly_buffers = 1, .readwrite_buffers = 4, .uniform_buffers = 1, .threads = .{ 64, 1, 1 } };
+const synth_kernel: gpu.Kernel = .{ .code = shaders.synth_comp, .readonly_buffers = 2, .readwrite_buffers = 1, .uniform_buffers = 1, .threads = .{ 64, 1, 1 } };
+const advance_kernel: gpu.Kernel = .{ .code = shaders.advance_comp, .readwrite_buffers = 2, .uniform_buffers = 1, .threads = .{ 1, 1, 1 } };
+const lookahead_kernel: gpu.Kernel = .{ .code = shaders.lookahead_comp, .readwrite_buffers = 3, .uniform_buffers = 1, .threads = .{ 32, 1, 1 } };
+const rechord_kernel: gpu.Kernel = .{ .code = shaders.rechord_comp, .readonly_buffers = 1, .readwrite_buffers = 1, .uniform_buffers = 1, .threads = .{ 64, 1, 1 } };
+
+const sky_pipelines = [_]gpu.Pipeline{
+ // 0: the fade, blended over what is there.
+ .{ .vertex = .{ .code = shaders.fullscreen_vert }, .fragment = .{ .code = shaders.fade_frag, .uniform_buffers = 1 }, .stride = 0, .attributes = &.{}, .blend = .premultiplied },
+ // 1: glows, added.
+ .{ .vertex = .{ .code = shaders.sprite_vert, .uniform_buffers = 1, .storage_buffers = 1 }, .fragment = .{ .code = shaders.sprite_frag }, .stride = 0, .attributes = &.{}, .blend = .additive },
+ // 2: trails, added.
+ .{ .vertex = .{ .code = shaders.trail_vert, .uniform_buffers = 1, .storage_buffers = 1 }, .fragment = .{ .code = shaders.trail_frag }, .stride = 0, .attributes = &.{}, .blend = .additive },
+ // 3: the cloud, layered: where copies crowd it takes their body's
+ // colour rather than adding up to white.
+ .{ .vertex = .{ .code = shaders.sprite_vert, .uniform_buffers = 1, .storage_buffers = 1 }, .fragment = .{ .code = shaders.sprite_frag }, .stride = 0, .attributes = &.{}, .blend = .premultiplied },
+ // 4: the coupling between the closest pair, added.
+ .{ .vertex = .{ .code = shaders.link_vert, .uniform_buffers = 1, .storage_buffers = 2 }, .fragment = .{ .code = shaders.link_frag }, .stride = 0, .attributes = &.{}, .blend = .additive },
+};
+
+/// The sky: the cloud of copies on a long exposure, and over it system 0's
+/// trails and bodies, drawn fresh each frame.
+fn drawSky(s: *const State, ss: *Session, f: *sk.Frame, l: Layout) void {
+ const g = &ss.gpu;
+ const size: [2]u32 = .{ @intFromFloat(@max(l.sky.w, 1)), @intFromFloat(@max(l.sky.h, 1)) };
+ if (g.sky == .none or g.size[0] != size[0] or g.size[1] != size[1]) {
+ if (g.sky != .none) f.host.freeImage(g.sky);
+ if (g.overlay != .none) f.host.freeImage(g.overlay);
+ g.sky = f.host.newImage(size[0], size[1]);
+ g.overlay = f.host.newImage(size[0], size[1]);
+ g.size = size;
+ g.clear_sky = true;
+ }
+ const bg = sk.Color.hex(background);
+ const bgf: [3]f32 = .{ @as(f32, @floatFromInt(bg.r)) / 255, @as(f32, @floatFromInt(bg.g)) / 255, @as(f32, @floatFromInt(bg.b)) / 255 };
+ const per_pixel = 2 * ss.extent / @as(f32, @floatFromInt(@min(size[0], size[1])));
+ const base: layouts.SkyView = .{
+ .center = ss.center,
+ .size = .{ @floatFromInt(size[0]), @floatFromInt(size[1]) },
+ .per_pixel = per_pixel,
+ .radius = 1.6,
+ .alpha = 0.06,
+ .first = 1,
+ .count = systems - 1,
+ .head = ss.trail_head,
+ .filled = ss.trail_filled,
+ .time = @floatCast(@mod(@as(f64, @floatFromInt(f.in.now)) / std.time.ns_per_s, 1000)),
+ };
+ var cloud = base;
+ cloud.radius = 2.2;
+ cloud.alpha = 0.18;
+ f.gpu(.{
+ .label = "sky cloud",
+ .image = g.sky,
+ .width = size[0],
+ .height = size[1],
+ .clear = if (g.clear_sky) .{ bgf[0], bgf[1], bgf[2], 1 } else null,
+ .pipelines = &sky_pipelines,
+ .draws = &.{
+ .{ .pipeline = 0, .vertex_count = 3, .fragment_uniforms = gpu.uniform(f.scratch, layouts.Fade{ .background = bgf, .amount = if (s.running) 0.08 else 0.02 }) },
+ .{ .pipeline = 3, .vertex_count = (systems - 1) * 3 * 6, .vertex_uniforms = gpu.uniform(f.scratch, cloud), .vertex_storage = &.{g.bodies} },
+ },
+ });
+ g.clear_sky = false;
+
+ var trails = base;
+ trails.radius = 2.2;
+ trails.alpha = 0.9;
+ // Points are 0.012 apart in time; anything this far is a jump.
+ trails.gap = @max(0.5, ss.extent * 0.25);
+ var link = base;
+ link.radius = 3;
+ link.alpha = 0.9;
+ var halo = base;
+ halo.first = 0;
+ halo.count = 1;
+ halo.radius = 34;
+ halo.alpha = 0.35;
+ var core = halo;
+ core.radius = 9;
+ core.alpha = 1;
+ f.gpu(.{
+ .label = "sky bodies",
+ .image = g.overlay,
+ .width = size[0],
+ .height = size[1],
+ .clear = .{ 0, 0, 0, 0 },
+ .pipelines = &sky_pipelines,
+ .draws = &.{
+ .{ .pipeline = 2, .vertex_count = 3 * (layouts.trail - 1) * 6, .vertex_uniforms = gpu.uniform(f.scratch, trails), .vertex_storage = &.{g.trail} },
+ .{ .pipeline = 4, .vertex_count = 6 * 6, .vertex_uniforms = gpu.uniform(f.scratch, link), .vertex_storage = &.{ g.bodies, g.voices } },
+ .{ .pipeline = 1, .vertex_count = 3 * 6, .vertex_uniforms = gpu.uniform(f.scratch, halo), .vertex_storage = &.{g.bodies} },
+ .{ .pipeline = 1, .vertex_count = 3 * 6, .vertex_uniforms = gpu.uniform(f.scratch, core), .vertex_storage = &.{g.bodies} },
+ },
+ });
+ f.image(g.sky, l.sky, .{});
+ f.image(g.overlay, l.sky, .{});
+}
+
+/// The scope: an oscilloscope steadied on the focused voice, the spectrum
+/// and the spectrogram.
+fn sound(s: *const State, ss: *Session, f: *sk.Frame, l: Layout, rate: f64) void {
+ const v = ss.lead.voices[s.focus];
+ const period: u32 = if (v.carrier > 1) @intFromFloat(@round(rate / v.carrier)) else 256;
+ ss.scope.draw(f, .{
+ .seconds = 8,
+ .spectrogram = l.spectrogram,
+ .spectrum = l.spectrum,
+ .oscilloscope = .{
+ .rect = l.oscilloscope,
+ .samples = std.math.clamp(4 * period, 256, 4096),
+ .end = @intCast(ss.scope.heard % @max(period, 1)),
+ },
+ });
+}
+
+// ---------------------------------------------------------------------------
+// Text and marks.
+
+const dim = 0x7a8090;
+const bright = 0xe6e9ef;
+
+fn labels(s: *const State, ss: *const Session, f: *sk.Frame, l: Layout, rate: f64) void {
+ f.text(16, 10, 2, "spheres", 0xc9b6ff);
+ const room = if (l.narrow) l.w else l.button(0).x;
+ const lead = ss.lead;
+ const how = if (!s.running) " paused" else if (s.backward) " backwards" else "";
+ if (room > 420) {
+ f.print(140, 14, 1, dim, "{s} t {d:.1} energy {d:.4}{s}", .{ s.preset.label(), ss.time, lead.energy, how });
+ } else f.print(140, 14, 1, dim, "{s} t {d:.1}{s}", .{ s.preset.label(), ss.time, how });
+ for (buttons, 0..) |a, i| button(s, f, a, l.button(i));
+
+ // The voices, in their bodies' colours.
+ const v_rect = l.voices;
+ f.print(v_rect.x, v_rect.y, 1, bright, "{s} {s}", .{ modeName(s.mode), modeFormula(s.mode) });
+ for (lead.voices, 0..) |v, i| {
+ const y = v_rect.y + 16 + @as(f32, @floatFromInt(i)) * 14;
+ const mark = if (i == s.focus) ">" else " ";
+ const letter: u8 = 'A' + @as(u8, @intCast(i));
+ // Its role in the FM pair: modulating (silent), or modulated and by
+ // whom, at what index.
+ const row = lead.coupling[i];
+ var by: usize = 0;
+ for (0..3) |j| if (row[j] > row[by]) {
+ by = j;
+ };
+ const pushed = if (row[3] > 0.5)
+ f.format(" modulating", .{})
+ else if (row[by] > 0.05)
+ f.format(" FM by {c} {d:.2}", .{ @as(u8, 'A' + @as(u8, @intCast(by))), row[by] })
+ else
+ "";
+ if (l.narrow) {
+ f.print(v_rect.x, y, 1, palette[i], "{s}{c} {d:7.1} Hz r {d:4.2} d {d:5.2}{s}", .{ mark, letter, v.carrier, v.ratio, v.depth, pushed });
+ } else if (s.mode == .fm or s.mode == .pm) {
+ f.print(v_rect.x, y, 1, palette[i], "{s}{c} {d:7.1} Hz ratio {d:4.2} depth {d:5.2} index {d:5.2}{s}", .{ mark, letter, v.carrier, v.ratio, v.depth, index(s.mode, v), pushed });
+ } else f.print(v_rect.x, y, 1, palette[i], "{s}{c} {d:7.1} Hz ratio {d:4.2} depth {d:5.2}{s}", .{ mark, letter, v.carrier, v.ratio, v.depth, pushed });
+ }
+
+ // The spectrum's scale and each voice's partials where the theory puts
+ // them: the focused voice's all of them, the others' as small ticks.
+ spectrumMarks(s, ss, f, l.spectrum, rate);
+ instrumentView(s, ss, f, l);
+ f.text(l.oscilloscope.x + 4, l.oscilloscope.y + 4, 1, "oscilloscope", dim);
+ f.text(l.spectrogram.x + 4, l.spectrogram.y + 4, 1, "spectrogram, 8 s", sk.Color.white.alpha(150));
+ if (!l.narrow) f.text(16, l.h - 18, 1, if (s.instrument) "keys play the grid: 1 2 3 majors, Q W E minors, A S D sevenths, Z X C sus, by fifths ESC free SPACE pause" else "SPACE pause LEFT/RIGHT time's way UP/DOWN speed P/E/X preset C chords S synthesis Q scale M mute TAB voice R again", dim);
+}
+
+/// Grid rows' colours: majors gold, minors blue, sevenths orange, sus
+/// green, power chords violet.
+const row_colors = [chords.Grid.rows]u24{ 0xffcc59, 0x66b3ff, 0xff7a59, 0x69db7c, 0xb197fc };
+
+/// The chord sounding, over the sky; and as an instrument, the look-ahead's
+/// chords along time (system 0's own future) and the grid.
+fn instrumentView(s: *const State, ss: *const Session, f: *sk.Frame, l: Layout) void {
+ const Grid = chords.Grid;
+ var buf: [32]u8 = undefined;
+ const now = chords.chordOf(ss.lead.voices);
+ f.text(l.sky.x + 12, l.sky.y + 10, 2, f.format("{s}", .{chords.name(&buf, now)}), sk.Color.white.alpha(200));
+ if (!s.instrument) return;
+ f.print(l.sky.x + 12, l.sky.y + l.sky.h - 18, 1, sk.Color.white.alpha(120), "{d} chords found in {d} futures", .{ ss.ahead.distinct, layouts.alternatives });
+
+ const strip = l.strip;
+ const span = @as(f64, chords.horizon) * chords.sample_dt;
+ f.fill(strip, sk.Color.hex(0x10131c));
+ var t: u32 = 0;
+ while (t < ss.ahead.known) {
+ const sung = ss.ahead.sung[t][0];
+ const chord: u16 = if (sung.playable) sung.chord else 0;
+ var end = t + 1;
+ while (end < ss.ahead.known and @as(u16, if (ss.ahead.sung[end][0].playable) ss.ahead.sung[end][0].chord else 0) == chord) end += 1;
+ const x0 = strip.x + strip.w * @as(f32, @floatFromInt(t)) / chords.horizon;
+ const x1 = strip.x + strip.w * @as(f32, @floatFromInt(end)) / chords.horizon;
+ const color: sk.Color = if (Grid.find(chord)) |at| sk.Color.hex(row_colors[at.row]).alpha(170) else sk.Color.hex(0x2a2f3a);
+ f.fill(.{ .x = x0, .y = strip.y, .w = @max(x1 - x0, 1), .h = strip.h }, color);
+ t = end;
+ }
+ const at = struct {
+ fn x(r: sk.Rect, time: f64, total: f64) f32 {
+ return r.x + r.w * @as(f32, @floatCast(std.math.clamp(time / total, 0, 1)));
+ }
+ }.x;
+ if (ss.travel) |travel| f.fill(.{ .x = at(strip, travel.to.time(), span) - 1, .y = strip.y - 4, .w = 3, .h = strip.h + 8 }, sk.Color.hex(0xffd84d));
+ f.fill(.{ .x = at(strip, ss.time, span) - 1, .y = strip.y - 3, .w = 2, .h = strip.h + 6 }, sk.Color.white);
+
+ const held: ?u16 = if (ss.held) |h| ss.ahead.sung[h.sample][h.alternative].chord else null;
+ for (0..Grid.rows) |row| for (0..Grid.columns) |column| {
+ const r = l.key(row, column) orelse continue;
+ const chord = Grid.chord(row, column);
+ const found = ss.ahead.found[chord];
+ const lit = chord == now or chord == held;
+ const color = sk.Color.hex(row_colors[row]);
+ f.fill(r, if (lit) color.alpha(230) else if (found) color.alpha(70) else sk.Color.hex(0x12151d));
+ if (found) f.fill(.{ .x = r.x, .y = r.y + r.h - 2, .w = r.w, .h = 2 }, color);
+ const label = f.format("{s}{s}", .{ Grid.root_names[column], Grid.suffix(@enumFromInt(row)) });
+ const ink = if (lit) sk.Color.hex(0x05070d) else if (found) sk.Color.white else sk.Color.white.alpha(60);
+ f.text(r.x + (r.w - @as(f32, @floatFromInt(label.len * 8))) / 2, r.y + r.h / 2 - 4, 1, label, ink);
+ };
+}
+
+fn button(s: *const State, f: *sk.Frame, a: Action, r: sk.Rect) void {
+ const label: []const u8 = switch (a) {
+ .play => if (s.running) "PAUSE" else "PLAY",
+ .reverse => if (s.backward) "FWD" else "REV",
+ .mode => modeName(s.mode),
+ .preset => "NEXT",
+ .eight => "EIGHT",
+ .random => "RANDOM",
+ .instrument => if (s.instrument) "FREE" else "CHORDS",
+ .scale => switch (s.scale) {
+ .free => "UNSNAP",
+ .pentatonic => "PENTA",
+ .diatonic => "DIATON",
+ .chromatic => "CHROMA",
+ },
+ .mute => if (s.muted) "UNMUTE" else "MUTE",
+ else => "",
+ };
+ f.fill(r, sk.Color.hex(0x161a24));
+ f.fill(.{ .x = r.x, .y = r.y + r.h - 1, .w = r.w, .h = 1 }, sk.Color.hex(0x2e3440));
+ f.text(r.x + (r.w - @as(f32, @floatFromInt(label.len * 8))) / 2, r.y + r.h / 2 - 4, 1, label, bright);
+}
+
+fn modeName(m: Mode) []const u8 {
+ return switch (m) {
+ .sine => "SINE",
+ .additive => "ADD",
+ .am => "AM",
+ .ring => "RING",
+ .fm => "FM",
+ .pm => "PM",
+ };
+}
+
+fn modeFormula(m: Mode) []const u8 {
+ return switch (m) {
+ .sine => "sin c",
+ .additive => "sum r^(k-1) sin kc, r = d/(d+2)",
+ .am => "sin c (1 + a sin m)/(1 + a), a = min(d/4, 1)",
+ .ring => "sin c sin m",
+ .fm => "carrier swung d times its frequency by m: index d/ratio",
+ .pm => "sin(c + d sin m): index d",
+ };
+}
+
+/// The modulation index the theory works with: what sets the sidebands.
+fn index(m: Mode, v: layouts.Voice) f32 {
+ return switch (m) {
+ .fm => v.depth / @max(v.ratio, 1e-3),
+ .pm => v.depth,
+ else => 0,
+ };
+}
+
+/// A partial: frequency and amplitude relative to the voice's.
+const Partial = struct { hz: f64, amp: f64 };
+
+/// Where a voice's energy goes, by the textbook: FM and PM put
+/// |J_k(index)| at carrier + k modulator; AM puts a/2 at carrier ±
+/// modulator; ring modulation halves between the two; additive steps
+/// through harmonics.
+fn partials(m: Mode, v: layouts.Voice, out: []Partial) []Partial {
+ const fc: f64 = v.carrier;
+ const fm: f64 = fc * v.ratio;
+ var n: usize = 0;
+ switch (m) {
+ .sine => {
+ out[0] = .{ .hz = fc, .amp = 1 };
+ n = 1;
+ },
+ .additive => {
+ const r = v.depth / (v.depth + 2);
+ var norm: f64 = 0;
+ var w: f64 = 1;
+ for (0..16) |_| {
+ norm += w;
+ w *= r;
+ }
+ w = 1;
+ for (0..16) |k| {
+ out[n] = .{ .hz = fc * @as(f64, @floatFromInt(k + 1)), .amp = w / norm };
+ n += 1;
+ w *= r;
+ }
+ },
+ .am => {
+ const a = @min(v.depth / 4, 1);
+ out[0] = .{ .hz = fc, .amp = 1 / (1 + a) };
+ out[1] = .{ .hz = fc + fm, .amp = a / 2 / (1 + a) };
+ out[2] = .{ .hz = @abs(fc - fm), .amp = a / 2 / (1 + a) };
+ n = 3;
+ },
+ .ring => {
+ out[0] = .{ .hz = fc + fm, .amp = 0.5 };
+ out[1] = .{ .hz = @abs(fc - fm), .amp = 0.5 };
+ n = 2;
+ },
+ .fm, .pm => {
+ const beta: f64 = index(m, v);
+ var k: i32 = -12;
+ while (k <= 12) : (k += 1) {
+ out[n] = .{ .hz = @abs(fc + @as(f64, @floatFromInt(k)) * fm), .amp = @abs(bessel(@intCast(@abs(k)), beta)) };
+ n += 1;
+ }
+ },
+ }
+ return out[0..n];
+}
+
+/// A voice's partials with the FM pair's modulation on top: each of its own
+/// partials spread into sidebands |J_k(index)| at k times the modulating
+/// body's frequency (exact for sine and additive, whose harmonics all get
+/// the same push; a guide for the others).
+fn fmPair(m: Mode, v: layouts.Voice, voices: [3]layouts.Voice, row: [4]f32, own: []Partial, out: []Partial) []Partial {
+ const base = partials(m, v, own);
+ var by: usize = 0;
+ for (0..3) |j| if (row[j] > row[by]) {
+ by = j;
+ };
+ const beta: f64 = row[by];
+ if (beta < 0.05) return base;
+ const fm: f64 = voices[by].carrier;
+ var n: usize = 0;
+ for (base) |p| {
+ var k: i32 = -6;
+ while (k <= 6) : (k += 1) {
+ if (n == out.len) return out;
+ out[n] = .{ .hz = @abs(p.hz + @as(f64, @floatFromInt(k)) * fm), .amp = p.amp * @abs(bessel(@intCast(@abs(k)), beta)) };
+ n += 1;
+ }
+ }
+ return out[0..n];
+}
+
+/// J_n(x), the Bessel function of the first kind, by its series: enough
+/// terms for the indices here (x up to about 24).
+fn bessel(n: u32, x: f64) f64 {
+ const half = x / 2;
+ var term = std.math.pow(f64, half, @floatFromInt(n));
+ for (1..n + 1) |k| term /= @floatFromInt(k);
+ var sum = term;
+ for (1..80) |m| {
+ const mf: f64 = @floatFromInt(m);
+ term *= -half * half / (mf * (mf + @as(f64, @floatFromInt(n))));
+ sum += term;
+ if (@abs(term) < 1e-14 * @abs(sum) and m > 2 * @as(usize, @intFromFloat(@abs(x)))) break;
+ }
+ return sum;
+}
+
+fn spectrumMarks(s: *const State, ss: *const Session, f: *sk.Frame, r: sk.Rect, rate: f64) void {
+ for ([_]f64{ 50, 200, 1000, 5000, 20000 }) |hz| {
+ if (hz > scope.maxFreq(rate)) continue;
+ const x = r.x + scope.place(hz, rate) * r.w;
+ const label = if (hz >= 1000) f.format("{d}k", .{hz / 1000}) else f.format("{d}", .{hz});
+ f.text(@min(x + 3, r.x + r.w - 24), r.y + r.h + 4, 1, label, dim);
+ }
+ var own: [32]Partial = undefined;
+ var buf: [32 * 13]Partial = undefined;
+ for (ss.lead.voices, 0..) |v, i| {
+ const row = ss.lead.coupling[i];
+ if (row[3] > 0.5) continue;
+ const focused = i == s.focus;
+ const color = sk.Color.hex(palette[i]);
+ for (fmPair(s.mode, v, ss.lead.voices, row, &own, &buf)) |p| {
+ if (p.hz < scope.min_freq or p.hz > scope.maxFreq(rate) or p.amp < 1e-4) continue;
+ const x = @round(r.x + scope.place(p.hz, rate) * r.w);
+ // Level in dB of full scale, as the spectrum shows it.
+ const db = 20 * std.math.log10(@max(p.amp * v.amp, 1e-9));
+ const y = r.y + r.h * @as(f32, @floatCast(std.math.clamp(db / scope.floor_db, 0, 1)));
+ if (focused) {
+ f.fill(.{ .x = x, .y = y, .w = 1, .h = r.y + r.h - y }, color.alpha(70));
+ f.fill(.{ .x = x - 3, .y = y - 1, .w = 7, .h = 3 }, color.alpha(230));
+ } else f.fill(.{ .x = x - 2, .y = y, .w = 5, .h = 2 }, color.alpha(150));
+ }
+ }
+}
+
+test "the presets start with the centre of mass at rest" {
+ inline for (@typeInfo(Preset).@"enum".field_names) |field| {
+ const p = start(@field(Preset, field), 1);
+ var momentum: [2]f32 = .{ 0, 0 };
+ for (p.masses, p.bodies) |m, b| {
+ momentum[0] += m * b.vel[0];
+ momentum[1] += m * b.vel[1];
+ }
+ try std.testing.expectApproxEqAbs(@as(f32, 0), momentum[0], 1e-5);
+ try std.testing.expectApproxEqAbs(@as(f32, 0), momentum[1], 1e-5);
+ }
+}
+
+test "Bessel functions, against known values" {
+ try std.testing.expectApproxEqAbs(@as(f64, 1), bessel(0, 0), 1e-12);
+ try std.testing.expectApproxEqAbs(@as(f64, 0.7651976866), bessel(0, 1), 1e-9);
+ try std.testing.expectApproxEqAbs(@as(f64, 0.5767248078), bessel(1, 2), 1e-9);
+ // The first zero of J0: FM's carrier vanishes at index 2.405.
+ try std.testing.expectApproxEqAbs(@as(f64, 0), bessel(0, 2.404825558), 1e-8);
+ try std.testing.expectApproxEqAbs(@as(f64, -0.2459357645), bessel(0, 10), 1e-8);
+}
+
+test "PM's partials hold all the energy" {
+ var buf: [32]Partial = undefined;
+ var energy: f64 = 0;
+ for (partials(.pm, .{ .carrier = 220, .ratio = 1.5, .depth = 3, .amp = 1 }, &buf)) |p| energy += p.amp * p.amp;
+ try std.testing.expectApproxEqAbs(@as(f64, 1), energy, 1e-6);
+}
diff --git a/examples/spheres/test/play.script b/examples/spheres/test/play.script
new file mode 100644
index 0000000..1b06372
--- /dev/null
+++ b/examples/spheres/test/play.script
@@ -0,0 +1,58 @@
+# Plays each preset and synthesis mode headless; screenshots land in
+# .zig-cache/spheres/ for review.
+frames 120
+expect running true
+expect preset figure_eight
+screenshot .zig-cache/spheres/figure-eight.png
+expect mode additive
+key s
+key s
+key s
+expect mode fm
+frames 30
+key p
+key p
+expect preset pythagorean
+frames 240
+screenshot .zig-cache/spheres/pythagorean.png
+# Time backwards, then paused.
+key left
+expect backward true
+frames 30
+key space
+expect running false
+frames 10
+key space
+key right
+expect backward false
+key tab
+expect focus 1
+key p
+frames 200
+screenshot .zig-cache/spheres/lagrange.png
+# The buttons do what the keys do: pause, a random system, the figure eight.
+click 727 18
+expect running false
+click 1087 18
+expect preset random
+expect running true
+frames 60
+screenshot .zig-cache/spheres/random.png
+click 1015 18
+expect preset figure_eight
+# As an instrument: the look-ahead finds chords, a grid button sends the sky
+# to the nearest time its chord plays, and the sky holds still there.
+key c
+expect instrument true
+frames 200
+# 7 is the number row's C column: C major (bits 0, 4, 7).
+key 7
+expect chord.value 145
+frames 90
+screenshot .zig-cache/spheres/chords.png
+# U is QWERTY's C column, a row down: C minor (bits 0, 3, 7).
+key u
+expect chord.value 137
+frames 60
+key escape
+expect instrument false
diff --git a/examples/spheres/web/icon-192.png b/examples/spheres/web/icon-192.png
new file mode 100644
index 0000000..2a47f3d
--- /dev/null
+++ b/examples/spheres/web/icon-192.png
Binary files differ
diff --git a/examples/spheres/web/icon-512.png b/examples/spheres/web/icon-512.png
new file mode 100644
index 0000000..fb096b8
--- /dev/null
+++ b/examples/spheres/web/icon-512.png
Binary files differ
diff --git a/examples/spheres/web/icon.svg b/examples/spheres/web/icon.svg
new file mode 100644
index 0000000..7ed8bf8
--- /dev/null
+++ b/examples/spheres/web/icon.svg
@@ -0,0 +1,28 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 512 512">
+ <!-- spheres' icon: the figure-eight orbit, its three bodies glowing in
+ their colours. Full-bleed, so it also works masked. Rendered to the
+ PNGs beside it with: resvg -w N -h N icon.svg icon-N.png -->
+ <defs>
+ <filter id="glow" x="-1" y="-1" width="3" height="3">
+ <feGaussianBlur stdDeviation="14"/>
+ </filter>
+ <linearGradient id="orbit" gradientUnits="userSpaceOnUse" x1="76" y1="0" x2="436" y2="0">
+ <stop offset="0" stop-color="#ffcc59"/>
+ <stop offset="0.5" stop-color="#ff73d1"/>
+ <stop offset="1" stop-color="#66d9ff"/>
+ </linearGradient>
+ </defs>
+ <rect width="512" height="512" fill="#05070d"/>
+ <!-- the figure eight -->
+ <path d="M256 256 C 300 196 436 176 436 256 C 436 336 300 316 256 256 C 212 196 76 176 76 256 C 76 336 212 316 256 256 Z"
+ fill="none" stroke="url(#orbit)" stroke-width="10" opacity="0.8"/>
+ <!-- the bodies: glow, then core -->
+ <g filter="url(#glow)">
+ <circle cx="398" cy="205" r="30" fill="#66d9ff"/>
+ <circle cx="140" cy="307" r="30" fill="#ff73d1"/>
+ <circle cx="256" cy="256" r="30" fill="#ffcc59"/>
+ </g>
+ <circle cx="398" cy="205" r="15" fill="#e6f8ff"/>
+ <circle cx="140" cy="307" r="15" fill="#ffe6f6"/>
+ <circle cx="256" cy="256" r="15" fill="#fff4dc"/>
+</svg>