From 458b00d254f5e3b1fece6e57462769ce43c96a72 Mon Sep 17 00:00:00 2001
From: skal <pascal.massimino@gmail.com>
Date: Thu, 5 Feb 2026 00:03:44 +0100
Subject: docs: Extract sequence documentation to dedicated SEQUENCE.md file

Moves comprehensive sequence system documentation out of demo.seq into
a proper documentation file, keeping the timeline file clean and focused.

Changes:
- New file: doc/SEQUENCE.md with complete .seq format reference
- Streamlined: assets/demo.seq reduced from 207 to 104 lines
- Updated: README.md to include SEQUENCE.md reference

Benefits:
- Easier to read and navigate the actual timeline
- Documentation separately viewable in markdown
- Better for version control (timeline vs doc changes separated)
- Follows project convention of dedicated doc files
- Makes demo.seq more approachable for quick edits

The timeline file is now 50% smaller while all documentation remains
easily accessible in the standard doc/ directory.
---
 assets/demo.seq | 137 +++++---------------------------------------------------
 1 file changed, 10 insertions(+), 127 deletions(-)

(limited to 'assets/demo.seq')

diff --git a/assets/demo.seq b/assets/demo.seq
index 0d73374..35935a7 100644
--- a/assets/demo.seq
+++ b/assets/demo.seq
@@ -1,139 +1,22 @@
 # ============================================================================
 # DEMO SEQUENCE DEFINITION
 # ============================================================================
-# This file defines the timeline and layering of visual effects.
+# Defines the timeline and layering of visual effects for the demo.
 # Compiled by seq_compiler into src/generated/timeline.cc at build time.
 #
-# DEBUGGING & VALIDATION:
-#   Validate without generating code:
-#     ./build/seq_compiler assets/demo.seq
+# DOCUMENTATION: See doc/SEQUENCE.md for complete syntax reference
 #
-#   Generate ASCII Gantt chart:
-#     ./build/seq_compiler assets/demo.seq --gantt=timeline.txt
+# QUICK REFERENCE:
+#   SEQUENCE <start> <priority> [optional_end]
+#     EFFECT <ClassName> <start> <end> <priority>
 #
-#   Generate HTML/SVG Gantt chart (recommended):
-#     ./build/seq_compiler assets/demo.seq --gantt-html=timeline.html
-#     Open timeline.html in browser for interactive visualization
+#   Time notation: 0b (beats), 0.0 (seconds)
+#   Priority: Higher numbers render later (on top)
 #
-#   All modes can be combined:
-#     ./build/seq_compiler assets/demo.seq timeline.cc --gantt=t.txt --gantt-html=t.html
+# VALIDATION & VISUALIZATION:
+#   ./build/seq_compiler assets/demo.seq                    # Validate only
+#   ./build/seq_compiler assets/demo.seq --gantt-html=t.html  # HTML Gantt
 #
-# BPM 120
-#
-#
-# SYNTAX:
-#
-#   END_DEMO <time>
-#     Specifies when the demo should automatically exit (optional)
-#     If not specified, demo runs indefinitely until user closes window
-#
-#   SEQUENCE <global_start> <priority> [optional_end]
-#     EFFECT <EffectClassName> <local_start> <local_end> <priority> [constructor_args...]
-#
-#   Optional sequence end time:
-#     - Syntax: [time] (must be wrapped in brackets)
-#     - If specified, all effects in the sequence will be forcefully ended at this time
-#     - If not specified, effects run until their individual end times
-#     - Example: SEQUENCE 0 0 [30.0] ends the entire sequence at 30 seconds
-#
-# TIME NOTATION:
-#   - Beat numbers: "0", "64", "128" (no decimal point = beats)
-#   - Beat numbers with 'b': "0b", "64b", "128b" (explicit beat notation)
-#   - Seconds: "0.0", "32.0", "64.0" (decimal point = seconds)
-#   - Seconds with 's': "32.0s", "64.0s" (explicit seconds notation)
-#   Examples at 120 BPM:
-#     - Beat 0 = 0.0 seconds
-#     - Beat 64 = 32.0 seconds
-#     - Beat 120 = 60.0 seconds
-#
-# SEQUENCE:
-#   - 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, 10+ for post-processing
-#   - [optional_end]: Optional end time in brackets [time]. If specified, all effects
-#                     in the sequence will be forcefully ended at this time (relative
-#                     to the sequence start). If omitted, effects run until their
-#                     individual end times.
-#
-# EFFECT:
-#   - 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)
-#   - priority: Render order within sequence (lower = drawn first/background)
-#               Negative priorities draw behind everything
-#   - constructor_args: Optional additional constructor parameters (rarely used)
-#
-#   Effect Constructor Parameters:
-#     ALL effects automatically receive these standard parameters:
-#       - WGPUDevice device: WebGPU device handle
-#       - WGPUQueue queue: Command queue for GPU operations
-#       - WGPUTextureFormat format: Surface texture format
-#
-#     Most effects only use these standard parameters and don't require additional args.
-#     If an effect needs custom initialization parameters, they are specified after
-#     the priority field. Example (hypothetical):
-#       EFFECT CustomEffect 0 10 0 1.5 "param"
-#     This would translate to:
-#       std::make_shared<CustomEffect>(device, queue, format, 1.5, "param")
-#
-#   Runtime Parameters (passed to render() method):
-#     All effects receive these dynamic parameters every frame:
-#       - time: Global time in seconds (from demo start)
-#       - beat: Current beat fraction (0.0 to 1.0 within each beat)
-#       - intensity: Audio peak intensity (0.0 to 1.0, for beat detection)
-#       - aspect_ratio: Screen width/height ratio
-#
-#   Currently available effects (all use standard constructor only):
-#
-#     Scene Effects (render 3D geometry):
-#       - 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)
-#
-#     Post-Process Effects (full-screen shaders, applied in priority order):
-#       - 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
-#           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)
-#       - FlashEffect: White flash on strong beat hits
-#           Uses: intensity (triggers flash when > 0.7, exponential decay)
-#
-# TIPS:
-#   - Scene effects render to framebuffer with depth testing
-#   - Post-processing effects are full-screen shaders applied in order
-#   - Use negative priority for background elements (skybox, far objects)
-#   - Higher sequence priority = later in post-process chain
-#
-# EXAMPLES:
-#   # Basic sequence starting at beat 0 with priority 0
-#   SEQUENCE 0 0
-#     EFFECT FlashEffect 0.0 0.5 1    # Starts immediately, runs 0.5s, priority 1
-#     EFFECT HeptagonEffect 0.2 10 0  # Starts at 0.2s, runs until 10s, priority 0
-#
-#   # Sequence with explicit end time - all effects terminated at 5 seconds
-#   SEQUENCE 8b 0 [5.0]
-#     EFFECT ParticlesEffect 0 120 1  # Would run 120s, but sequence ends at 5s
-#
-#   # Post-processing chain (high priority renders last/on top)
-#   SEQUENCE 0 10
-#     EFFECT GaussianBlurEffect 0 60 1      # Applied first
-#     EFFECT ChromaAberrationEffect 0 60 2  # Applied second
-#     EFFECT SolarizeEffect 0 60 3          # Applied last
-#
-#   # Background element with negative priority (renders behind everything)
-#   SEQUENCE 0 0
-#     EFFECT FlashCubeEffect 0 10 -1  # priority -1 = background layer
 # ============================================================================
 
 SEQUENCE 0b 0
-- 
cgit v1.2.3