From dd9d3013d260f27f86b268c203a290f91431d8e5 Mon Sep 17 00:00:00 2001
From: skal <pascal.massimino@gmail.com>
Date: Wed, 4 Feb 2026 22:08:56 +0100
Subject: feat: Optional sequence end times and comprehensive effect
 documentation

This milestone implements several key enhancements to the sequencing system
and developer documentation:

## Optional Sequence End Times (New Feature)
- Added support for explicit sequence termination via [time] syntax
- Example: SEQUENCE 0 0 [30.0] forcefully ends all effects at 30 seconds
- Updated seq_compiler.cc to parse optional [time] parameter with brackets
- Added end_time_ field to Sequence class (default -1.0 = no explicit end)
- Modified update_active_list() to check sequence end time and deactivate
  all effects when reached
- Fully backward compatible - existing sequences work unchanged

## Comprehensive Effect Documentation (demo.seq)
- Documented all effect constructor parameters (standard: device, queue, format)
- Added runtime parameter documentation (time, beat, intensity, aspect_ratio)
- Created detailed effect catalog with specific behaviors:
  * Scene effects: HeptagonEffect, ParticlesEffect, Hybrid3DEffect, FlashCubeEffect
  * Post-process effects: GaussianBlurEffect, SolarizeEffect, ChromaAberrationEffect,
    ThemeModulationEffect, FadeEffect, FlashEffect
- Added examples section showing common usage patterns
- Documented exact parameter behaviors (e.g., blur pulsates 0.5x-2.5x,
  flash triggers at intensity > 0.7, theme cycles every 8 seconds)

## Code Quality & Verification
- Audited all hardcoded 1280x720 dimensions throughout codebase
- Verified all shaders use uniforms.resolution and uniforms.aspect_ratio
- Confirmed Effect::resize() properly updates width_/height_ members
- No issues found - dimension handling is fully dynamic and robust

## Files Changed
- tools/seq_compiler.cc: Parse [end_time], generate set_end_time() calls
- src/gpu/effect.h: Added end_time_, set_end_time(), get_end_time()
- src/gpu/effect.cc: Check sequence end time in update_active_list()
- assets/demo.seq: Comprehensive syntax and effect documentation
- Generated files updated (timeline.cc, assets_data.cc, music_data.cc)

This work establishes a more flexible sequencing system and provides
developers with clear documentation for authoring demo timelines.

handoff(Claude): Optional sequence end times implemented, effect documentation
complete, dimension handling verified. Ready for next phase of development.
---
 assets/demo.seq | 217 +++++++++++++++++++++++++++++++++++++++++++++++++++++---
 1 file changed, 207 insertions(+), 10 deletions(-)

(limited to 'assets/demo.seq')

diff --git a/assets/demo.seq b/assets/demo.seq
index 2c54dfb..fced9d6 100644
--- a/assets/demo.seq
+++ b/assets/demo.seq
@@ -1,10 +1,207 @@
-SEQUENCE 0.0 0
-  EFFECT HeptagonEffect 0.0 60.0 0
-  EFFECT ParticlesEffect 0.0 60.0 1
-  EFFECT Hybrid3DEffect 0.0 60.0 2
-
-# Post-processing chain
-SEQUENCE 0.0 10
-  EFFECT GaussianBlurEffect 0.0 60.0 0
-  EFFECT ChromaAberrationEffect 0.0 60.0 1
-  EFFECT SolarizeEffect 0.0 60.0 2
+# ============================================================================
+# DEMO SEQUENCE DEFINITION
+# ============================================================================
+# This file defines the timeline and layering of visual effects.
+# Compiled by seq_compiler into src/generated/timeline.cc at build time.
+#
+# 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
+  EFFECT FlashEffect 0.0 1. 0
+  EFFECT FadeEffect 0.1 1. 1         # Add fade
+  EFFECT FlashCubeEffect .2 3 -1      # Background cube (priority -1 = behind everything)
+  EFFECT SolarizeEffect 0 4b 3           # Color inversion (last)
+
+SEQUENCE 4b 0
+  EFFECT FlashEffect 0.0 0.2 4        # Add flash after solarize
+  EFFECT FlashCubeEffect 0.1 3. -1
+
+SEQUENCE 6b 1
+  EFFECT ParticlesEffect 0 4 1       # Particles layer
+  EFFECT GaussianBlurEffect 0 8 1       # Blur
+
+SEQUENCE 7b 0
+  EFFECT FadeEffect 0.1 1.0 5         # Add fade
+  EFFECT HeptagonEffect 0.0 .2 0        # Main geometric effect
+
+# Post-processing chain (priority 10 = applied after scene rendering)
+# Effects are applied in priority order: lower numbers first
+SEQUENCE 8b 3
+  EFFECT ThemeModulationEffect 0 4 0    # Brightness modulation (first)
+  EFFECT HeptagonEffect 0.0 4.0 0        # Main geometric effect
+  EFFECT GaussianBlurEffect 0 8 1       # Blur
+  EFFECT ChromaAberrationEffect 0 6 2   # Color separation
+  EFFECT SolarizeEffect 0 10 3           # Color inversion (last)
+
+SEQUENCE 12b 2
+  EFFECT FlashCubeEffect .2 3 -1      # Background cube (priority -1 = behind everything)
+  EFFECT HeptagonEffect 0 4 0
+  EFFECT ParticlesEffect 0 4 1       # Particles layer
+
+SEQUENCE 15b 2
+  EFFECT FlashCubeEffect .2 3 -1      # Background cube (priority -1 = behind everything)
+  EFFECT FlashEffect 0.0 1 0
+
+SEQUENCE 16b 10
+  EFFECT FlashCubeEffect .2 3 -1      # Background cube (priority -1 = behind everything)
+  EFFECT GaussianBlurEffect 0 8 1       # Blur
+  EFFECT FlashEffect 0.0 0.2 4        # Add flash after solarize
+  EFFECT FlashEffect 1b 0.2 4        # Add flash after solarize
+
+SEQUENCE 17b 2
+  EFFECT ThemeModulationEffect 0 4 0    # Brightness modulation (first)
+  EFFECT HeptagonEffect 0.2 2.0 1        # Main geometric effect
+  EFFECT ParticlesEffect 0 4 1       # Particles layer
+  EFFECT GaussianBlurEffect 0 8 3       # Blur
+  EFFECT Hybrid3DEffect 0 4 2        # 3D objects (priority 2 = foreground)
+  EFFECT ChromaAberrationEffect 0 6 4   # Color separation
+
+SEQUENCE 24b 1
+  EFFECT ThemeModulationEffect 0 8 0    # Brightness modulation (first)
+  EFFECT HeptagonEffect 0.2 2.0 1        # Main geometric effect
+  EFFECT Hybrid3DEffect 0 20 2        # 3D objects (priority 2 = foreground)
+  EFFECT GaussianBlurEffect 0 8 3       # Blur
+  EFFECT ChromaAberrationEffect 0 10 4   # Color separation
+  EFFECT SolarizeEffect 0 10 5           # Color inversion (last)
+
+SEQUENCE 32b 0
+  EFFECT ThemeModulationEffect 0 4 0    # Brightness modulation (first)
+  EFFECT HeptagonEffect 0 16 1        # Main geometric effect
+  EFFECT ChromaAberrationEffect 0 16 3   # Color separation
+  EFFECT GaussianBlurEffect 0 8 4       # Blur
+
+SEQUENCE 48b 0
+  EFFECT ThemeModulationEffect 0 4 0    # Brightness modulation (first)
+  EFFECT HeptagonEffect 0.2 2.0 1        # Main geometric effect
+  EFFECT GaussianBlurEffect 0 8 3       # Blur
+  EFFECT SolarizeEffect 0 2 5           # Color inversion (last)
+
+SEQUENCE 56b 0
+  EFFECT ThemeModulationEffect 0 8 0    # Brightness modulation (first)
+  EFFECT HeptagonEffect 0.2 2.0 0        # Main geometric effect
+  EFFECT Hybrid3DEffect 0 4 1        # 3D objects (priority 2 = foreground)
+  EFFECT HeptagonEffect 0 16 2        # Main geometric effect
+  EFFECT ChromaAberrationEffect 0 16 3   # Color separation
+  EFFECT GaussianBlurEffect 0 8 4       # Blur
+
+SEQUENCE 62b 0
+  EFFECT ThemeModulationEffect 0 3 0    # Brightness modulation (first)
+  EFFECT SolarizeEffect 0 3 5           # Color inversion (last)
+# Demo automatically exits at this time (supports beat notation)
+END_DEMO 65b
-- 
cgit v1.2.3