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.
---
 src/gpu/effect.cc | 21 +++++++++++++++++++++
 1 file changed, 21 insertions(+)

(limited to 'src/gpu/effect.cc')

diff --git a/src/gpu/effect.cc b/src/gpu/effect.cc
index 0d4dde7..96e7489 100644
--- a/src/gpu/effect.cc
+++ b/src/gpu/effect.cc
@@ -7,6 +7,7 @@
 #include <algorithm>
 #include <cstdio>
 #include <vector>
+#include <typeinfo>
 
 // --- PostProcessEffect ---
 void PostProcessEffect::render(WGPURenderPassEncoder pass, float, float, float,
@@ -51,14 +52,27 @@ void Sequence::sort_items() {
 }
 
 void Sequence::update_active_list(float seq_time) {
+  // Check if sequence has ended (if explicit end time is set)
+  const bool sequence_ended = (end_time_ >= 0.0f && seq_time >= end_time_);
+
   for (SequenceItem& item : items_) {
     bool should_be_active =
+        !sequence_ended &&
         (seq_time >= item.start_time && seq_time < item.end_time);
 
     if (should_be_active && !item.active) {
+#if !defined(STRIP_ALL)
+      const char* effect_name = typeid(*item.effect).name();
+      printf("  [EFFECT START] %s (priority=%d, time=%.2f-%.2f)\n",
+             effect_name, item.priority, item.start_time, item.end_time);
+#endif
       item.effect->start();
       item.active = true;
     } else if (!should_be_active && item.active) {
+#if !defined(STRIP_ALL)
+      const char* effect_name = typeid(*item.effect).name();
+      printf("  [EFFECT END] %s (priority=%d)\n", effect_name, item.priority);
+#endif
       item.effect->end();
       item.active = false;
     }
@@ -216,6 +230,13 @@ void MainSequence::render_frame(float global_time, float beat, float peak,
   std::vector<SequenceItem*> post_effects;
   for (ActiveSequence& entry : sequences_) {
     if (global_time >= entry.start_time) {
+#if !defined(STRIP_ALL)
+      if (!entry.activated) {
+        printf("[SEQUENCE START] priority=%d, start_time=%.2f\n",
+               entry.priority, entry.start_time);
+        entry.activated = true;
+      }
+#endif
       float seq_time = global_time - entry.start_time;
       entry.seq->update_active_list(seq_time);
       entry.seq->collect_active_effects(scene_effects, post_effects);
-- 
cgit v1.2.3