summaryrefslogtreecommitdiff
path: root/examples/spheres/README.md
diff options
context:
space:
mode:
authorGabriel Schneider <[email protected]>2026-11-17 00:15:15 -0300
committerGabriel Schneider <[email protected]>2026-11-17 12:15:01 -0300
commit9bd77e54943d954291b5faef287ccca5dcebd7a4 (patch)
tree3f2d628781441568620b8108fab920713f26f649 /examples/spheres/README.md
parente997fc3e6b312b30f5af90012fc22365bab701d4 (diff)
downloadsketchbook-9bd77e54943d954291b5faef287ccca5dcebd7a4.tar.gz
sketchbook-9bd77e54943d954291b5faef287ccca5dcebd7a4.zip
examples: micscope and spheres come home, as they were, building
Both lived outside any repository, beside sketchbook, with manifests that pointed at ../01-drat-meout/lib/sketchbook, which no longer exists. They are copied into examples/micscope and examples/spheres (their sources, shaders, tests, test material and web icons; not their caches, builds, packages, state files or .gitignore, which the root's covers), their manifests depend on "../.." as the other examples do, and their READMEs link sketchbook there. Nothing else changed: both build against today's library and pass their own zig build test (micscope 62/62 steps, 11/11 tests, its transport, record, render and tuner scripts; spheres 75/75 steps, 3/3 tests, its play script). The originals are untouched. micscope's test/reference.flac (3.7 MiB, CC BY-SA 3.0, credited in its test/README.md) is the rendering reference its render script opens. The README lists both examples. Co-Authored-By: Claude Opus 5.5 <[email protected]> Claude-Session: https://claude.ai/code/session_016Y9MNBECMWcJD5pdS4SR6T
Diffstat (limited to 'examples/spheres/README.md')
-rw-r--r--examples/spheres/README.md153
1 files changed, 153 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