diff options
| author | skal <pascal.massimino@gmail.com> | 2026-02-16 11:58:34 +0100 |
|---|---|---|
| committer | skal <pascal.massimino@gmail.com> | 2026-02-16 11:58:34 +0100 |
| commit | 7a383635525c9f9617965f3c79a9f2d6c86550cd (patch) | |
| tree | 84491cede72c416e2f0b8131854c849c4b1454a5 /doc/SEQUENCE.md | |
| parent | af5d0e4c3a6cb773a4fb51ac32f4c33a7f8d8224 (diff) | |
docs(sequence): update and compact v2 documentation
Documentation Changes:
- Rewrote SEQUENCE_v2.md: practical guide focused on actual implementation
- Removed design philosophy, added concrete examples
- Documented all implemented features and current limitations
- Added effect creation templates (standard post-process, 3D with depth)
- 130 lines → 222 lines (expanded with examples)
- Updated EFFECT_WORKFLOW.md for v2
- Changed from v1 Effect/PostProcessEffect to EffectV2
- Updated all steps for v2 workflow (6 steps instead of 8)
- Added complete templates with proper v2 signatures
- Documented common issues and solutions
- Removed v1-specific content
- Archived v1 documentation
- Moved doc/SEQUENCE.md → doc/archive/SEQUENCE_V1.md
- V1 system removed, documentation preserved for reference
Content Focus:
- Quick start examples (simple chain, multi-output, ping-pong)
- Timeline syntax reference with REQUIRED priority modifiers
- Architecture overview (SequenceV2, EffectV2, Node system)
- Compiler features (DAG validation, topological sort, ping-pong detection)
- Practical templates (copy-paste ready)
- Common issues section (build errors, runtime errors)
Status Documentation:
- ✅ Implemented: DAG validation, node aliasing, 7 effects ported
- ❌ Missing: Flatten mode, BPM handling, GetDemoDuration calculation
- TODO: Port remaining effects, implement flatten, update HTML editor
Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
Diffstat (limited to 'doc/SEQUENCE.md')
| -rw-r--r-- | doc/SEQUENCE.md | 220 |
1 files changed, 0 insertions, 220 deletions
diff --git a/doc/SEQUENCE.md b/doc/SEQUENCE.md deleted file mode 100644 index 03d0c45..0000000 --- a/doc/SEQUENCE.md +++ /dev/null @@ -1,220 +0,0 @@ -# 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 |
