diff options
Diffstat (limited to 'doc/SEQUENCE.md')
| -rw-r--r-- | doc/SEQUENCE.md | 284 |
1 files changed, 63 insertions, 221 deletions
diff --git a/doc/SEQUENCE.md b/doc/SEQUENCE.md index 7aa951d..954c816 100644 --- a/doc/SEQUENCE.md +++ b/doc/SEQUENCE.md @@ -4,45 +4,13 @@ This document describes the `.seq` file format used to define demo timelines. ## Overview -Sequence files (`.seq`) define the timeline and layering of visual effects in the demo. They are compiled by `seq_compiler` into C++ code at build time. - -## File Location +Sequence files (`.seq`) define the timeline and layering of visual effects. They are compiled by `seq_compiler` into C++ code at build time. +**Locations:** - Demo sequence: `assets/demo.seq` - Compiler: `tools/seq_compiler.cc` - Generated output: `src/generated/timeline.cc` -## Command Line Usage - -### Basic Compilation -```bash -./build/seq_compiler assets/demo.seq src/generated/timeline.cc -``` - -### Validation Only -```bash -./build/seq_compiler assets/demo.seq -``` -Validates syntax without generating code. - -### Gantt Chart Visualization - -**ASCII Gantt Chart:** -```bash -./build/seq_compiler assets/demo.seq --gantt=timeline.txt -``` - -**HTML/SVG Gantt Chart (Recommended):** -```bash -./build/seq_compiler assets/demo.seq --gantt-html=timeline.html -``` -Open `timeline.html` in browser for interactive visualization with hover tooltips. - -**Combined Modes:** -```bash -./build/seq_compiler assets/demo.seq timeline.cc --gantt=t.txt --gantt-html=t.html -``` - --- ## Syntax Reference @@ -51,41 +19,32 @@ Open `timeline.html` in browser for interactive visualization with hover tooltip ``` # BPM 120 ``` -Specifies beats per minute for the demo. Used to convert beat notation to seconds. +Specifies beats per minute. Used to convert beat notation to seconds. ### END_DEMO Directive ``` END_DEMO <time> ``` -Specifies when the demo should automatically exit (optional). -- If not specified, demo runs indefinitely until user closes window -- Supports beat notation (e.g., `64b`) or seconds (e.g., `32.0`) +Optional auto-exit time. Supports beat notation (`64b`) or seconds (`32.0`). ### SEQUENCE Declaration ``` SEQUENCE <global_start> <priority> ["optional_name"] [optional_end] - EFFECT <EffectClassName> <local_start> <local_end> <priority> [constructor_args...] + EFFECT <+|=|-> <EffectClassName> <local_start> <local_end> [constructor_args...] ``` **Parameters:** -- `global_start`: When this sequence starts (beats or seconds) -- `priority`: Render order between sequences (higher = rendered later/on top) - - Use 0-9 for scene effects - - Use 10+ for post-processing -- `"optional_name"`: Optional human-readable name in quotes (e.g., `"Opening Scene"`) - - If specified, the name will be displayed in Gantt charts for better readability - - Helps identify sequences when visualizing complex timelines -- `[optional_end]`: Optional end time in brackets (e.g., `[30.0]`) - - If specified, all effects in the sequence will be forcefully ended at this time - - Time is relative to the sequence start - - If omitted, effects run until their individual end times +- `global_start`: Sequence start time (beats or seconds) +- `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) **Examples:** ``` -SEQUENCE 0 0 # Basic sequence (no name, no explicit end) +SEQUENCE 0 0 # Basic sequence SEQUENCE 0 0 "Intro" # Named sequence -SEQUENCE 0 0 [5.0] # Sequence with explicit end time -SEQUENCE 0 0 "Action Scene" [10.0] # Named sequence with explicit end time +SEQUENCE 0 0 [5.0] # Explicit end time +SEQUENCE 0 0 "Action Scene" [10.0] # Both name and end time ``` ### EFFECT Declaration @@ -93,29 +52,20 @@ SEQUENCE 0 0 "Action Scene" [10.0] # Named sequence with explicit end time EFFECT <+|=|-> <EffectClassName> <local_start> <local_end> [constructor_args...] ``` -**Parameters:** -- Priority modifier (one of): - - `+`: Increment priority (or start at 0 if first effect) - - `=`: Keep same priority as previous effect - - `-`: Decrement priority (or start at -1 if first effect, for background layers) -- `EffectClassName`: C++ class name (must be declared in `demo_effects.h`) -- `local_start`: Start time relative to sequence start (beats or seconds) -- `local_end`: End time relative to sequence start (beats or seconds) -- `constructor_args`: Optional additional parameters (rarely used) +**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) -**Priority System:** -- Effects are assigned priorities based on their order in the file -- First effect: `+` starts at 0, `-` starts at -1, `=` starts at 0 -- Subsequent effects: `+` increments, `=` keeps same, `-` decrements -- Priorities determine render order (lower = drawn first/background) -- Effects should be listed in desired priority order within each sequence +**Parameters:** +- `EffectClassName`: C++ class from `demo_effects.h` +- `local_start`, `local_end`: Time relative to sequence start +- `constructor_args`: Optional (rarely used, most effects use standard params only) --- ## Time Notation -The sequence file supports flexible time notation: - | Notation | Example | Description | |----------|---------|-------------| | Integer beats | `0`, `64`, `128` | No decimal point = beats | @@ -123,118 +73,33 @@ The sequence file supports flexible time notation: | Decimal seconds | `0.0`, `32.0`, `64.0` | Decimal point = seconds | | Explicit seconds | `32.0s`, `64.0s` | Suffix 's' = seconds | -**Examples at 120 BPM:** -- Beat 0 = 0.0 seconds -- Beat 64 = 32.0 seconds -- Beat 120 = 60.0 seconds +**At 120 BPM:** Beat 64 = 32.0 seconds, Beat 120 = 60.0 seconds --- -## Effect System - -### Constructor Parameters - -**Standard Parameters (ALL effects receive these automatically):** -- `WGPUDevice device`: WebGPU device handle -- `WGPUQueue queue`: Command queue for GPU operations -- `WGPUTextureFormat format`: Surface texture format +## Runtime Parameters -Most effects only use these standard parameters. If an effect needs custom initialization, parameters are specified after the priority field. - -**Example (hypothetical custom effect):** -``` -EFFECT CustomEffect 0 10 0 1.5 "param" -``` -Translates to: -```cpp -std::make_shared<CustomEffect>(device, queue, format, 1.5, "param") -``` - -### Runtime Parameters - -All effects receive these dynamic parameters every frame in their `render()` method: +All effects receive these parameters every frame in `render()`: | Parameter | Type | Description | |-----------|------|-------------| -| `time` | float | Global time in seconds (from demo start) | -| `beat` | float | Current beat fraction (0.0 to 1.0 within each beat) | -| `intensity` | float | Audio peak intensity (0.0 to 1.0, for beat detection) | -| `aspect_ratio` | float | Screen width/height ratio | - ---- - -## Available Effects - -### Scene Effects -Render 3D geometry to the framebuffer with depth testing. - -#### HeptagonEffect -Animated geometric heptagon shape. -- **Uses:** `time` (animation), `beat` (rotation), `aspect_ratio` (projection) - -#### ParticlesEffect -GPU-simulated particle system. -- **Uses:** `time` (physics), `intensity` (emission rate) - -#### Hybrid3DEffect -3D objects with camera movement. -- **Uses:** `time` (camera paths), `beat` (object animation), `aspect_ratio` - -#### FlashCubeEffect -Large background cube with Perlin noise texture. -- **Uses:** `time` (rotation), `intensity` (flash trigger on beat hits) -- **Note:** Typically used with priority -1 for background layer - -### Post-Process Effects -Full-screen shaders applied in priority order after scene rendering. - -#### GaussianBlurEffect -Gaussian blur with beat pulsation. -- **Uses:** `intensity` (blur size pulsates 0.5x-2.5x based on audio peak) - -#### SolarizeEffect -Color inversion with alternating red/blue tints. -- **Uses:** `time` (alternates every 2 seconds between color schemes) - -#### ChromaAberrationEffect -RGB channel separation effect. -- **Uses:** `time` (animation), `intensity` (separation amount) - -#### ThemeModulationEffect -Brightness cycling (bright/dark alternation). -- **Uses:** `time` (cycles every 8 seconds: 1.0 bright to 0.35 dark) - -#### FadeEffect -Fade to/from black. -- **Uses:** `time` (fades in first 2s, fades out after 36s - hardcoded timing) - -#### FlashEffect -White flash on strong beat hits. -- **Uses:** `intensity` (triggers flash when > 0.7, exponential decay) +| `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 | --- -## Tips & Best Practices - -### Layering -- Scene effects render to framebuffer with depth testing -- Post-processing effects are full-screen shaders applied in sequence priority order -- Use negative priority for background elements (skybox, far objects) -- Higher sequence priority = later in post-process chain (rendered on top) +## Priority System -### Priority Guidelines -- **Scene Effects:** priority 0-9 - - Background: -1 (e.g., skybox, distant objects) - - Midground: 0-5 (main geometry) - - Foreground: 6-9 (overlays, particles) -- **Post-Process:** priority 10+ - - Apply in order: blur → distortion → color grading +**Scene Effects (0-9):** +- `-1`: Background (skybox, far objects) +- `0-5`: Midground (main geometry) +- `6-9`: Foreground (overlays, particles) -### Timing -- Use beat notation for music-synchronized effects -- Use seconds for absolute timing -- Keep effect durations reasonable (avoid very short < 0.1s unless intentional) -- Use sequence `[end_time]` to forcefully terminate long-running effects +**Post-Process (10+):** +- Applied in order: blur → distortion → color grading +- Higher priority = rendered later (on top) --- @@ -243,16 +108,16 @@ White flash on strong beat hits. ### Basic Sequence ``` SEQUENCE 0 0 - EFFECT + FlashEffect 0.0 0.5 # Priority 0 (first with +) - EFFECT + HeptagonEffect 0.2 10 # Priority 1 (increment) + EFFECT + FlashEffect 0.0 0.5 # Priority 0 + EFFECT + HeptagonEffect 0.2 10 # Priority 1 ``` -### Same Priority (Layered Effects) +### Same Priority Layering ``` SEQUENCE 0 0 EFFECT + Flash 0.0 0.5 # Priority 0 - EFFECT = Fade 0.1 0.3 # Priority 0 (same as Flash) - EFFECT + Other 0.2 3 # Priority 1 (increment) + EFFECT = Fade 0.1 0.3 # Priority 0 (same layer) + EFFECT + Other 0.2 3 # Priority 1 ``` ### Background Elements @@ -263,93 +128,70 @@ SEQUENCE 0 0 EFFECT + MainEffect 0 10 # Priority 0 (foreground) ``` -### Sequence with Explicit End Time +### Sequence with Explicit End ``` SEQUENCE 8b 0 [5.0] - EFFECT + Particles 0 120 # Would run 120s, but sequence ends at 5s + EFFECT + Particles 0 120 # Runs until 5s (sequence end) ``` ### Post-Processing Chain ``` SEQUENCE 0 10 - EFFECT + GaussianBlur 0 60 # Priority 0 (applied first) - EFFECT + ChromaAberration 0 60 # Priority 1 (applied second) - EFFECT + Solarize 0 60 # Priority 2 (applied last) + EFFECT + GaussianBlur 0 60 # Applied first + EFFECT + ChromaAberration 0 60 # Applied second + EFFECT + Solarize 0 60 # Applied last ``` -### Music-Synchronized Effects +### Music-Synchronized ``` # BPM 120 -SEQUENCE 0b 0 # Start at beat 0 (0.0s) - EFFECT + Flash 0b 1b # Flash from beat 0 to beat 1 (0-0.5s) - EFFECT + Heptagon 4b 8b # Main effect from beat 4 to 8 (2-4s) +SEQUENCE 0b 0 + EFFECT + Flash 0b 1b # Beat 0-1 (0-0.5s) + EFFECT + Heptagon 4b 8b # Beat 4-8 (2-4s) ``` --- -## Debugging & Visualization +## Visualization ### Gantt Charts -Gantt charts help visualize the timeline structure: - -**ASCII Chart (Terminal-Friendly):** +**ASCII Chart (Terminal):** +```bash +./build/seq_compiler assets/demo.seq --gantt=timeline.txt ``` -Time (s): 0 5 10 15 20 - |----|----|----|----|----| -SEQ@0s [pri=0] - ████████████████████████ (0-20s) - FlashEffect [pri=1] - ▓▓·················· (0-1s) - HeptagonEffect [pri=0] - ▓▓▓▓▓▓▓▓▓▓▓▓········ (0-10s) +**HTML/SVG Chart (Recommended):** +```bash +./build/seq_compiler assets/demo.seq --gantt-html=timeline.html ``` +Interactive visualization with hover tooltips, color coding, and zoom/pan. -**HTML/SVG Chart (Interactive):** -- Color-coded sequences and effects -- Hover tooltips with full details -- Invalid time ranges highlighted in red -- Professional dark theme -- Zoom/pan support -- Easy to share or present - -### Validation - -Run validation without code generation to catch syntax errors: +### Validation Only ```bash ./build/seq_compiler assets/demo.seq -# Output: "Validation successful: 14 sequences, explicit end time." ``` - -### Common Issues Caught by Validation -- Invalid time ranges (end < start) -- Missing effect classes -- Syntax errors -- Malformed time notation +Validates syntax without generating code. --- -## Integration with Build System +## Integration -The sequence compiler is automatically invoked during build via CMake: +CMake automatically invokes the compiler on `assets/demo.seq` changes: ```cmake add_custom_command( OUTPUT ${GENERATED_DIR}/timeline.cc COMMAND seq_compiler assets/demo.seq ${GENERATED_DIR}/timeline.cc DEPENDS assets/demo.seq - COMMENT "Compiling demo sequence..." ) ``` -Editing `assets/demo.seq` triggers automatic recompilation and rebuilds affected targets. - --- ## See Also -- `doc/HOWTO.md` - Building and running the demo -- `doc/CONTRIBUTING.md` - Coding guidelines - `assets/demo.seq` - Current demo timeline - `src/gpu/demo_effects.h` - Available effect classes +- `doc/EFFECTS_CATALOG.md` - Detailed effect reference (if needed) +- `doc/HOWTO.md` - Building and running |