From 7a383635525c9f9617965f3c79a9f2d6c86550cd Mon Sep 17 00:00:00 2001
From: skal <pascal.massimino@gmail.com>
Date: Mon, 16 Feb 2026 11:58:34 +0100
Subject: docs(sequence): update and compact v2 documentation
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

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>
---
 doc/archive/SEQUENCE_V1.md | 220 +++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 220 insertions(+)
 create mode 100644 doc/archive/SEQUENCE_V1.md

(limited to 'doc/archive/SEQUENCE_V1.md')

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
-- 
cgit v1.2.3