diff options
Diffstat (limited to 'examples')
| -rw-r--r-- | examples/live/README.md | 89 |
1 files changed, 89 insertions, 0 deletions
diff --git a/examples/live/README.md b/examples/live/README.md new file mode 100644 index 0000000..3c0c885 --- /dev/null +++ b/examples/live/README.md @@ -0,0 +1,89 @@ +# live + +A program typed over its own picture, and heard. Each line names an +expression; the `out` line is what you hear (-1..1), the `color` line what +you see. At every keystroke that leaves a program that parses, the +program is compiled into two tapes of at most 128 instructions, and one +interpreter on the GPU runs them per sample and per pixel. While a line +is broken, the last good program keeps playing and the problem is marked +under its byte. + +``` +bpm = 120 +beat = t * bpm / 60 +kick = exp(-7 * fract(beat)) +thump = sin(tau * 48 * t * (1 + 2 * kick)) * kick * 0.5 +out = thump +r = sqrt((x - 0.5) * (x - 0.5) + (y - 0.5) * (y - 0.5)) +color = hsv(fract(beat / 16 + r), 0.6, smoothstep(0.03, 0, abs(r - 0.2 - 0.1 * kick))) +``` + +The picture pulses with the kick because both lines say `kick`. + +## Running it + +`zig build run` (with `zig build lib --watch` beside it for hot reload). +Type; Backspace deletes the last character, Return starts a line. The +console (backtick) records, plays and seeks as for any sketch: `play +session 0`, `pause`, `seek 5000`, `step -60`, `stop`; a seek brings back +the text, the tapes and the picture of that moment, and the sound with +them. `capture` appends what is heard to `capture.f32` beside the save +(mono f32 at the device's rate) until `capture` again; `set crossfade +false` lets an edit click. `zig build test` runs the language's tests and +test/live.script headless; `zig build probe` times the interpreter on the +GPU (`--profile-gpu`). + +## The language + +A line is `name = expression`, a name defined once and before it is used, +so a program has no loops or recursion and always ends. Expressions: +numbers (`0.5`, `120`, `1e-3`), names, `+ - * /`, unary `-`, parentheses, +calls; `#` starts a comment. The builtins (src/Lang.zig's one table): + +| | | +| --- | --- | +| `t` | seconds | +| `x`, `y` | 0..1, left to right and bottom to top; 0 in sound | +| `tau`, `pi` | a turn and half a turn, in radians | +| `sin(a)`, `cos(a)` | of radians | +| `exp(a)`, `log(a)`, `pow(a, b)`, `sqrt(a)` | e to the a, its inverse, a to the b (a not negative), square root | +| `abs(a)`, `floor(a)`, `fract(a)` | without its sign, the whole number at or below, a - floor(a) | +| `min(a, b)`, `max(a, b)`, `clamp(v, lo, hi)` | the smaller, the larger, v kept between | +| `mix(a, b, w)` | a + (b - a) * w | +| `step(edge, v)` | 0 below edge, 1 from it on | +| `smoothstep(lo, hi, v)` | 0 to 1 smoothly as v goes from lo to hi, either way round | +| `atan2(y, x)` | the angle of the point (x, y) | +| `noise(x, y, z)` | smooth noise, -1..1, a new value about every 1; y and z 0 when left out | +| `saw(p)`, `sqr(p)`, `tri(p)` | waves of period 1 (cycles, not radians), -1..1; saw and tri rise through 0 at 0, sqr is 1 then -1 | +| `seq(i, v0, v1, ...)` | the value at floor(i), round the list: a step pattern, 16 values at most | +| `hsv(h, s, v)`, `rgb(r, g, b)` | a colour (hue 0..1 round the wheel); only as the whole `color` line | + +Capacities: 128 instructions a tape (a line reaches only what it uses), +512 terms and 128 names in the text, nesting 32 deep, 4 KiB of text. Past +any of them is a problem like a syntax error, in words, at its byte. + +## What it cannot say + +No state between samples or between frames: every sample is a function of +its time alone, every pixel of x, y and t. So no filters, feedback, delay +lines or reverb, and no picture that remembers the last frame. That is the +price of computing every sample alone on the GPU, and what makes a replayed +moment sound and look as it did. An echo can be said by evaluating again +at an earlier time (`t - 0.25` in a copy of the line). No user functions, +no vectors but the final colour, and `t` is a 32-bit float: past ten +minutes or so a high pitch begins to roughen. + +## How it works + +src/Lang.zig compiles the text in `update` (no allocation: fixed arrays on +the stack) into tapes of `{op, a, b, c}`, instruction i writing register +i; State keeps the text, both tapes, the problem and the time. The tapes +go to the GPU as data: the color tape as picture.frag's uniforms, the out +tape (with the one it replaces, for the crossfade) in a storage buffer for +synth.comp, both including shaders/vm.glsl, a loop over the tape with a +switch per op. No shader is compiled after the first frame, so typing +never stalls one. A color tape over 64 instructions is drawn at half +resolution: on an RTX 3050, 128 instructions took 2.7 ms at 1280x720 and +0.85 at half; 60 took 1.4 at full. The sound is `pub const audio_pull = +256` and a block a frame, as much as keeps the host's lead queued: a +change is heard a pull or so after the frame that made it. |
