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/audio/jittered_audio_backend.h | 51 ++++++++++++++++++++++++++++++++++++++
 1 file changed, 51 insertions(+)
 create mode 100644 src/audio/jittered_audio_backend.h

(limited to 'src/audio/jittered_audio_backend.h')

diff --git a/src/audio/jittered_audio_backend.h b/src/audio/jittered_audio_backend.h
new file mode 100644
index 0000000..e0ce9d7
--- /dev/null
+++ b/src/audio/jittered_audio_backend.h
@@ -0,0 +1,51 @@
+// This file is part of the 64k demo project.
+// It implements a test backend that simulates jittered audio consumption.
+// Useful for stress-testing ring buffer under realistic timing conditions.
+
+#pragma once
+
+#if !defined(STRIP_ALL)
+
+#include "audio_backend.h"
+#include <atomic>
+#include <thread>
+
+// Simulates a real audio device with timing jitter and variable chunk sizes
+class JitteredAudioBackend : public AudioBackend {
+ public:
+  JitteredAudioBackend();
+  ~JitteredAudioBackend() override;
+
+  void init() override;
+  void start() override;
+  void shutdown() override;
+
+  // Control simulation
+  void set_jitter_amount(float jitter_ms);  // Random jitter in ms (default: 5ms)
+  void set_base_interval(float interval_ms);  // Base interval between reads (default: 10ms)
+  void set_chunk_size_range(int min_frames, int max_frames);  // Variable chunk sizes
+
+  // Query state
+  int get_total_frames_consumed() const { return total_frames_consumed_.load(); }
+  int get_underrun_count() const { return underrun_count_.load(); }
+  bool is_running() const { return running_.load(); }
+
+ private:
+  void audio_thread_loop();
+
+  std::thread audio_thread_;
+  std::atomic<bool> running_;
+  std::atomic<bool> should_stop_;
+
+  // Configuration
+  float jitter_ms_;
+  float base_interval_ms_;
+  int min_chunk_frames_;
+  int max_chunk_frames_;
+
+  // Statistics
+  std::atomic<int> total_frames_consumed_;
+  std::atomic<int> underrun_count_;  // How many times buffer was empty
+};
+
+#endif /* !defined(STRIP_ALL) */
-- 
cgit v1.2.3