summaryrefslogtreecommitdiff
path: root/examples
diff options
context:
space:
mode:
Diffstat (limited to 'examples')
-rw-r--r--examples/live/README.md89
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.