diff options
Diffstat (limited to 'doc/SEQUENCE.md')
| -rw-r--r-- | doc/SEQUENCE.md | 85 |
1 files changed, 53 insertions, 32 deletions
diff --git a/doc/SEQUENCE.md b/doc/SEQUENCE.md index 68bd129..03d0c45 100644 --- a/doc/SEQUENCE.md +++ b/doc/SEQUENCE.md @@ -20,13 +20,13 @@ Sequence files (`.seq`) define the timeline and layering of visual effects. They ``` # BPM 120 ``` -Specifies beats per minute. Used to convert beat notation to seconds. +Specifies beats per minute. Required. Used to convert beats to physical seconds at runtime. ### END_DEMO Directive ``` END_DEMO <time> ``` -Optional auto-exit time. Supports beat notation (`64b`) or seconds (`32.0`). +Optional auto-exit time in beats (e.g., `64` or `64b`) or explicit seconds (`32.0s`). ### SEQUENCE Declaration ``` @@ -35,10 +35,10 @@ SEQUENCE <global_start> <priority> ["optional_name"] [optional_end] ``` **Parameters:** -- `global_start`: Sequence start time (beats or seconds) +- `global_start`: Sequence start time in beats (default) or explicit seconds (`2.5s`) - `priority`: Render order (0-9 for scenes, 10+ for post-processing) - `"optional_name"`: Optional display name for Gantt charts -- `[optional_end]`: Optional sequence end time (forces effect termination) +- `[optional_end]`: Optional sequence end time in beats (forces effect termination) **Examples:** ``` @@ -60,34 +60,47 @@ EFFECT <+|=|-> <EffectClassName> <local_start> <local_end> [constructor_args...] **Parameters:** - `EffectClassName`: C++ class from `demo_effects.h` -- `local_start`, `local_end`: Time relative to sequence start +- `local_start`, `local_end`: Time in beats relative to sequence start - `constructor_args`: Optional (rarely used, most effects use standard params only) --- ## Time Notation +**Beat-based timing (default):** All times are in musical beats, ensuring alignment regardless of BPM changes. + | Notation | Example | Description | |----------|---------|-------------| -| Integer beats | `0`, `64`, `128` | No decimal point = beats | -| Explicit beats | `0b`, `64b`, `128b` | Suffix 'b' = beats | -| Decimal seconds | `0.0`, `32.0`, `64.0` | Decimal point = seconds | -| Explicit seconds | `32.0s`, `64.0s` | Suffix 's' = seconds | +| **Beats (default)** | `0`, `4`, `16` | Integer or decimal, no suffix | +| Explicit beats | `4b`, `16.5b` | Optional 'b' suffix for clarity | +| Explicit seconds | `2.0s`, `8.25s` | Suffix 's' for physical time (rare) | + +**Conversion:** At 120 BPM, 1 beat = 0.5 seconds, 4 beats = 2 seconds -**At 120 BPM:** Beat 64 = 32.0 seconds, Beat 120 = 60.0 seconds +**Why beats?** +- Musical alignment: Sequences stay synchronized to music structure +- BPM independence: Changing BPM preserves musical timing +- Intuitive authoring: Timeline matches bars/beats --- ## Runtime Parameters -All effects receive these parameters every frame in `render()`: +All effects receive these parameters every frame in `render()` via `CommonPostProcessUniforms`: | Parameter | Type | Description | |-----------|------|-------------| -| `time` | float | Global time in seconds | -| `beat` | float | Current beat fraction (0.0-1.0) | -| `intensity` | float | Audio peak (0.0-1.0, for beat sync) | -| `aspect_ratio` | float | Screen width/height | +| `resolution` | vec2 | Screen dimensions in pixels | +| `aspect_ratio` | float | Screen width/height ratio | +| `time` | float | Physical time in seconds (unaffected by tempo) | +| `beat_time` | float | Musical time in beats (absolute) | +| `beat_phase` | float | Fractional beat (0.0-1.0 within current beat) | +| `audio_intensity` | float | Audio peak (0.0-1.0, for beat sync) | + +**Use cases:** +- `time`: Physics-based animation (constant speed) +- `beat_time`: Musical animation (sync to bars/beats) +- `beat_phase`: Smooth oscillation per beat --- @@ -108,47 +121,55 @@ All effects receive these parameters every frame in `render()`: ### Basic Sequence ``` +# BPM 120 SEQUENCE 0 0 - EFFECT + FlashEffect 0.0 0.5 # Priority 0 - EFFECT + HeptagonEffect 0.2 10 # Priority 1 + EFFECT + FlashEffect 0 1 # Priority 0, beats 0-1 (0-0.5s @ 120 BPM) + EFFECT + HeptagonEffect 0.4 20 # Priority 1, beats 0.4-20 ``` ### Same Priority Layering ``` SEQUENCE 0 0 - EFFECT + Flash 0.0 0.5 # Priority 0 - EFFECT = Fade 0.1 0.3 # Priority 0 (same layer) - EFFECT + Other 0.2 3 # Priority 1 + EFFECT + Flash 0 1 # Priority 0 + EFFECT = Fade 0.2 0.6 # Priority 0 (same layer) + EFFECT + Other 0.4 6 # Priority 1 ``` ### Background Elements ``` SEQUENCE 0 0 - EFFECT - FlashCube 0 10 # Priority -1 (background) - EFFECT = BgEffect 0 5 # Priority -1 (same layer) - EFFECT + MainEffect 0 10 # Priority 0 (foreground) + EFFECT - FlashCube 0 20 # Priority -1 (background) + EFFECT = BgEffect 0 10 # Priority -1 (same layer) + EFFECT + MainEffect 0 20 # Priority 0 (foreground) ``` ### Sequence with Explicit End ``` -SEQUENCE 8b 0 [5.0] - EFFECT + Particles 0 120 # Runs until 5s (sequence end) +SEQUENCE 16 0 [10] + EFFECT + Particles 0 240 # Runs until beat 26 (sequence end at 16+10) ``` ### Post-Processing Chain ``` SEQUENCE 0 10 - EFFECT + GaussianBlur 0 60 # Applied first - EFFECT + ChromaAberration 0 60 # Applied second - EFFECT + Solarize 0 60 # Applied last + EFFECT + GaussianBlur 0 120 # Applied first + EFFECT + ChromaAberration 0 120 # Applied second + EFFECT + Solarize 0 120 # Applied last ``` -### Music-Synchronized +### Four-Bar Sequence (16 beats) ``` # BPM 120 -SEQUENCE 0b 0 - EFFECT + Flash 0b 1b # Beat 0-1 (0-0.5s) - EFFECT + Heptagon 4b 8b # Beat 4-8 (2-4s) +SEQUENCE 0 0 "Intro" + EFFECT + Flash 0 1 # First beat + EFFECT + Heptagon 4 12 # Second bar through third bar + EFFECT + Fade 15 16 # Final beat +``` + +### Explicit Physical Time (Rare) +``` +SEQUENCE 2.5s 0 "Intro timing" # Start at 2.5 physical seconds + EFFECT + Fade 0 4 # Fade from beat 0-4 (relative) ``` --- |