diff options
Diffstat (limited to 'doc/archive/SEQUENCE_V1.md')
| -rw-r--r-- | doc/archive/SEQUENCE_V1.md | 220 |
1 files changed, 220 insertions, 0 deletions
diff --git a/doc/archive/SEQUENCE_V1.md b/doc/archive/SEQUENCE_V1.md new file mode 100644 index 0000000..03d0c45 --- /dev/null +++ b/doc/archive/SEQUENCE_V1.md @@ -0,0 +1,220 @@ +# Sequence System Documentation + +This document describes the `.seq` file format used to define demo timelines. + +## Overview + +Sequence files (`.seq`) define the timeline and layering of visual effects. They are compiled by `seq_compiler` into C++ code at build time. + +**Locations:** +- Main demo: `workspaces/main/timeline.seq` +- Test demo: `workspaces/test/timeline.seq` +- Compiler: `tools/seq_compiler.cc` +- Generated output: `src/generated/timeline.cc` + +--- + +## Syntax Reference + +### BPM Declaration +``` +# BPM 120 +``` +Specifies beats per minute. Required. Used to convert beats to physical seconds at runtime. + +### END_DEMO Directive +``` +END_DEMO <time> +``` +Optional auto-exit time in beats (e.g., `64` or `64b`) or explicit seconds (`32.0s`). + +### SEQUENCE Declaration +``` +SEQUENCE <global_start> <priority> ["optional_name"] [optional_end] + EFFECT <+|=|-> <EffectClassName> <local_start> <local_end> [constructor_args...] +``` + +**Parameters:** +- `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 in beats (forces effect termination) + +**Examples:** +``` +SEQUENCE 0 0 # Basic sequence +SEQUENCE 0 0 "Intro" # Named sequence +SEQUENCE 0 0 [5.0] # Explicit end time +SEQUENCE 0 0 "Action Scene" [10.0] # Both name and end time +``` + +### EFFECT Declaration +``` +EFFECT <+|=|-> <EffectClassName> <local_start> <local_end> [constructor_args...] +``` + +**Priority Modifiers:** +- `+`: Increment priority (or start at 0 if first) +- `=`: Keep same priority as previous +- `-`: Decrement priority (or start at -1 if first, for backgrounds) + +**Parameters:** +- `EffectClassName`: C++ class from `demo_effects.h` +- `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 | +|----------|---------|-------------| +| **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 + +**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()` via `CommonPostProcessUniforms`: + +| Parameter | Type | Description | +|-----------|------|-------------| +| `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 + +--- + +## Priority System + +**Scene Effects (0-9):** +- `-1`: Background (skybox, far objects) +- `0-5`: Midground (main geometry) +- `6-9`: Foreground (overlays, particles) + +**Post-Process (10+):** +- Applied in order: blur → distortion → color grading +- Higher priority = rendered later (on top) + +--- + +## Examples + +### Basic Sequence +``` +# BPM 120 +SEQUENCE 0 0 + 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 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 20 # Priority -1 (background) + EFFECT = BgEffect 0 10 # Priority -1 (same layer) + EFFECT + MainEffect 0 20 # Priority 0 (foreground) +``` + +### Sequence with Explicit 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 120 # Applied first + EFFECT + ChromaAberration 0 120 # Applied second + EFFECT + Solarize 0 120 # Applied last +``` + +### Four-Bar Sequence (16 beats) +``` +# BPM 120 +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) +``` + +--- + +## Visualization + +### Gantt Charts + +**ASCII Chart (Terminal):** +```bash +./build/seq_compiler workspaces/main/timeline.seq --gantt=timeline.txt +``` + +**HTML/SVG Chart (Recommended):** +```bash +./build/seq_compiler workspaces/main/timeline.seq --gantt-html=timeline.html +``` +Interactive visualization with hover tooltips, color coding, and zoom/pan. + +### Validation Only +```bash +./build/seq_compiler workspaces/main/timeline.seq +``` +Validates syntax without generating code. + +--- + +## Integration + +CMake automatically invokes the compiler on workspace timeline changes: + +```cmake +add_custom_command( + OUTPUT ${GENERATED_DIR}/timeline.cc + COMMAND seq_compiler ${WORKSPACE_TIMELINE} ${GENERATED_DIR}/timeline.cc + DEPENDS ${WORKSPACE_TIMELINE} +) +``` + +--- + +## See Also + +- `workspaces/main/timeline.seq` - Main demo timeline +- `workspaces/test/timeline.seq` - Test demo timeline +- `doc/WORKSPACE_SYSTEM.md` - Workspace organization +- `src/gpu/demo_effects.h` - Available effect classes +- `doc/HOWTO.md` - Building and running |