SPB Git

Repository Public

loops.md 7.3 KB 234 lines markdown

1# Loops23A loop repeats a block. In a DJ script that usually means a rhythm: cut the fader on every eighth note, halve a loop every two beats, step a filter through a list of values. ORIX Script has five loop statements, and all of them are bounded: a loop always ends.45| Statement | Repeats | Typical use |6| --- | --- | --- |7| `repeat N { … }` | N times | "Do this four times" |8| `for i in 1...8 { … }` | once per number of a range | Steps that depend on the step number |9| `for x in [a, b, c] { … }` | once per element of an array | A pattern of values |10| `every P for T { … }` | on a time grid, every P during T | Rhythmic effects |11| `while C limit N { … }` | while a condition is true, at most N times | Waiting for something |1213## `repeat`1415```orixdj16repeat 4 {17    deck.A.eq.high = -26dB18    wait 1/2beat19    deck.A.eq.high = 0dB20    wait 1/2beat21}22```2324The body runs four times. Each turn takes one beat because of the two waits, so the loop takes one bar.2526A loop does not take time by itself. A body without `wait` or `over` runs all its turns at the same instant.2728The count may be computed. It must be a whole number, zero or more, and at most 10000.2930```orixdj31let turns = floor(toBeats(deck.A.remaining) / 4)     // whole bars left on deck A32print("bars left:", turns)33repeat min(turns, 2) {34    wait 1 bar35}36```3738## `for` over a range3940`a...b` includes both ends; `a..<b` stops before `b`. The loop variable is a number, exists only inside the loop, and cannot be assigned.4142```orixdj43for step in 1...4 {44    deck.A.filter.highpass = hz(200 * step)       // 200, 400, 600, 800 Hz45    wait 1 beat46}47deck.A.filter.highpass = 20Hz48```4950```orixdj51for index in 0..<4 {52    print(index)             // 0, 1, 2, 353}54```5556The bounds are evaluated once, before the first turn. The variable goes up by 1 each turn; if the first bound is greater than the last, the body does not run. A range can cover at most 10000 values.5758## `for` over an array5960```orixdj61let pattern = [0dB, -60dB, 0dB, 0dB, -60dB, 0dB, -60dB, -60dB]62for level in pattern {63    deck.A.volume = level64    wait 1/2beat65}66deck.A.volume = 0dB67```6869The variable takes each element in turn and has the element's type. This is the simplest way to write a rhythmic pattern: the array is the pattern, the loop plays it.7071## `every`: a loop on a time grid7273`every P for T { … }` runs its body at the cursor, then again P later, and so on, for a total length T. Then the cursor is T after where the loop started.7475```orixdj76every 1 beat for 2 bars {77    deck.A.eq.low = -26dB78    wait 1/4beat79    deck.A.eq.low = 0dB80}81```8283The body runs at beats 0, 1, 2, … 7 (eight times), and the statement after the loop runs at beat 8.8485The difference with `repeat`: the grid of `every` does not depend on how long the body takes. The body above takes a quarter of a beat; the next turn still starts on the next beat. With `repeat`, you must make the waits of the body add up to the period yourself.8687Rules:8889- P and T are durations. P must be greater than zero and at least 1/64 beat.90- T divided by P can be at most 10000.91- A turn starts only if it begins before the end of T. `every 1 beat for 3.5 beats` runs at 0, 1, 2 and 3, and ends at 3.5.92- If a turn is still running when the next one is due, the next one starts as soon as the body ends. The loop then finishes late: keep the body shorter than the period.9394Both durations may be in seconds; they are converted with the tempo when the loop starts.9596## `while`: repeat as long as a condition holds9798```orixdj99var level = 0dB100while level > -24dB limit 16 {101    level = level - 3dB102    deck.A.eq.mid = level103    wait 1 beat104}105deck.A.eq.mid = 0dB106```107108The condition is tested before each turn. `limit` is mandatory: it is the largest number of turns the loop is allowed to make, a constant whole number from 1 to 10000.109110```orixdj-error111while deck.A.playing {112    wait 1 beat113}114```115116```text117A 'while' loop needs an iteration bound: while condition limit 64 { … }. [E-UNBOUNDED]118```119120**Reaching the limit is an error, not a normal exit.** If the body has run `limit` times and the condition is still true, the automation fails with `E-UNBOUNDED`:121122```orixdj-error123var k = 0124while k >= 0 limit 50 {125    k = k + 1126}127```128129```text130The 'while' loop reached its limit without its condition becoming false. [E-UNBOUNDED]131```132133So the limit is a safety net, not a way to say "at most N times". When "give up after N turns" is an expected outcome, put the count in the condition and choose a limit that the condition makes unreachable:134135```orixdj136var turns = 0137while not deck.B.playing and turns < 32 limit 32 {138    wait 1 beat139    turns = turns + 1140}141```142143Here the condition becomes false after 32 turns at the latest, so the limit is never exceeded.144145## `break` and `continue`146147- `break` leaves the innermost loop at once.148- `continue` ends the current turn and goes to the next one. In an `every` loop the next turn still starts on the grid.149150```orixdj151for barNumber in [1, 2, 3, 4, 5, 6, 7, 8] {152    if not deck.A.playing {153        break                       // the deck was stopped: abandon the pattern154    }155    if barNumber % 2 == 1 {156        wait 1 bar157        continue                    // odd bars: nothing to do158    }159    deck.A.eq.high = -12dB160    wait 1 bar161    deck.A.eq.high = 0dB162}163```164165Both are errors outside a loop (`E-LOOP`). A block scheduled with `at` or an event handler written inside a loop is not "inside the loop" for this purpose: it runs later, on its own.166167## Loops and scheduling168169A loop is a convenient way to schedule many blocks with `at`. Each block keeps the value the loop variable had when it was scheduled.170171```orixdj172// kill the bass for the last beat of each of the next four bars173for barNumber in 1...4 {174    at beat barNumber * 4 { deck.A.eq.low = -26dB }175    at bar barNumber + 1 { deck.A.eq.low = 0dB }176}177wait 4 bars178```179180The loop itself takes no time; it only fills the timeline. The `wait` afterwards keeps the main sequence in step with what was scheduled. At most 256 scheduled blocks can be pending at once.181182## Nested loops183184```orixdj185// two bars: a four-step pattern played twice per bar186let steps = [0dB, -12dB, 0dB, -60dB]187repeat 4 {188    for level in steps {189        deck.A.volume = level190        wait 1/2beat191    }192}193deck.A.volume = 0dB194```195196## How much a loop may do197198Loops are where a script can do a lot of work in no time, so two run-time limits apply (see [Performance Guidelines](performance.md)):199200- at most 20000 operations between two waits (`E-BUDGET`);201- at most 512 parameter changes and actions within one beat (`E-RATE`).202203```orixdj-error204repeat 2000 {205    mixer.crossfader = 0.5206}207```208209```text210More than 512 commands in one beat. The automation was stopped to protect the performance. [E-RATE]211```212213A loop that waits in its body spreads its work over time and stays far below both limits.214215## Choosing a loop216217| You want | Use |218| --- | --- |219| The same thing N times | `repeat N` |220| Steps numbered 1 to N | `for i in 1...N` |221| A pattern of values | `for x in [ … ]` |222| Something on every beat, half-beat… for a fixed length | `every P for T` |223| Something on every beat or bar with no fixed end | `on beat`, `on bar` ([Events](events.md)) |224| To wait for a condition | `while … limit`, with a counter in the condition |225226## Related227228- [Timing](timing.md)229- [Conditions](conditions.md)230- [Events](events.md)231- [Variables](variables.md)232- [Performance Guidelines](performance.md)233- [Error Handling](errors.md)234
Files main
Menu

Theme