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/SEQUENCE.md | 220 --------------------------------------------------------
 1 file changed, 220 deletions(-)
 delete mode 100644 doc/SEQUENCE.md

(limited to 'doc/SEQUENCE.md')

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