summaryrefslogtreecommitdiff
path: root/doc/SEQUENCE.md
diff options
context:
space:
mode:
authorskal <pascal.massimino@gmail.com>2026-02-16 11:58:34 +0100
committerskal <pascal.massimino@gmail.com>2026-02-16 11:58:34 +0100
commit7a383635525c9f9617965f3c79a9f2d6c86550cd (patch)
tree84491cede72c416e2f0b8131854c849c4b1454a5 /doc/SEQUENCE.md
parentaf5d0e4c3a6cb773a4fb51ac32f4c33a7f8d8224 (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.md220
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