diff options
| author | Gabriel Schneider <[email protected]> | 2026-11-17 00:15:15 -0300 |
|---|---|---|
| committer | Gabriel Schneider <[email protected]> | 2026-11-17 12:15:01 -0300 |
| commit | 9bd77e54943d954291b5faef287ccca5dcebd7a4 (patch) | |
| tree | 3f2d628781441568620b8108fab920713f26f649 /examples/spheres/README.md | |
| parent | e997fc3e6b312b30f5af90012fc22365bab701d4 (diff) | |
| download | sketchbook-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.md | 153 |
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 |
