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/effects/flash_effect.cc | 79 +++++++++++++++++++++++++++++++++++++++++
 1 file changed, 79 insertions(+)
 create mode 100644 src/gpu/effects/flash_effect.cc

(limited to 'src/gpu/effects/flash_effect.cc')

diff --git a/src/gpu/effects/flash_effect.cc b/src/gpu/effects/flash_effect.cc
new file mode 100644
index 0000000..de7be62
--- /dev/null
+++ b/src/gpu/effects/flash_effect.cc
@@ -0,0 +1,79 @@
+// This file is part of the 64k demo project.
+// It implements the FlashEffect - brief white flash on beat hits.
+
+#include "gpu/effects/flash_effect.h"
+#include "gpu/effects/post_process_helper.h"
+#include <cmath>
+
+FlashEffect::FlashEffect(WGPUDevice device, WGPUQueue queue,
+                         WGPUTextureFormat format)
+    : PostProcessEffect(device, queue) {
+  const char* shader_code = R"(
+    struct VertexOutput {
+      @builtin(position) position: vec4<f32>,
+      @location(0) uv: vec2<f32>,
+    };
+
+    struct Uniforms {
+      flash_intensity: f32,
+      _pad0: f32,
+      _pad1: f32,
+      _pad2: f32,
+    };
+
+    @group(0) @binding(0) var inputSampler: sampler;
+    @group(0) @binding(1) var inputTexture: texture_2d<f32>;
+    @group(0) @binding(2) var<uniform> uniforms: Uniforms;
+
+    @vertex
+    fn vs_main(@builtin(vertex_index) vertexIndex: u32) -> VertexOutput {
+      var output: VertexOutput;
+      var pos = array<vec2<f32>, 3>(
+        vec2<f32>(-1.0, -1.0),
+        vec2<f32>(3.0, -1.0),
+        vec2<f32>(-1.0, 3.0)
+      );
+      output.position = vec4<f32>(pos[vertexIndex], 0.0, 1.0);
+      output.uv = pos[vertexIndex] * 0.5 + 0.5;
+      return output;
+    }
+
+    @fragment
+    fn fs_main(input: VertexOutput) -> @location(0) vec4<f32> {
+      let color = textureSample(inputTexture, inputSampler, input.uv);
+      // Add white flash: blend towards white based on flash intensity
+      let white = vec3<f32>(1.0, 1.0, 1.0);
+      let flashed = mix(color.rgb, white, uniforms.flash_intensity);
+      return vec4<f32>(flashed, color.a);
+    }
+  )";
+
+  pipeline_ = create_post_process_pipeline(device, format, shader_code);
+  uniforms_ = gpu_create_buffer(device, 16, WGPUBufferUsage_Uniform | WGPUBufferUsage_CopyDst);
+}
+
+void FlashEffect::update_bind_group(WGPUTextureView input_view) {
+  pp_update_bind_group(device_, pipeline_, &bind_group_, input_view, uniforms_);
+}
+
+void FlashEffect::render(WGPURenderPassEncoder pass, float time,
+                         float beat, float intensity, float aspect_ratio) {
+  (void)time;
+  (void)beat;
+  (void)aspect_ratio;
+
+  // Trigger flash on strong beat hits
+  if (intensity > 0.7f && flash_intensity_ < 0.2f) {
+    flash_intensity_ = 0.8f;  // Trigger flash
+  }
+
+  // Exponential decay
+  flash_intensity_ *= 0.85f;
+
+  float uniforms[4] = {flash_intensity_, 0.0f, 0.0f, 0.0f};
+  wgpuQueueWriteBuffer(queue_, uniforms_.buffer, 0, uniforms, sizeof(uniforms));
+
+  wgpuRenderPassEncoderSetPipeline(pass, pipeline_);
+  wgpuRenderPassEncoderSetBindGroup(pass, 0, bind_group_, 0, nullptr);
+  wgpuRenderPassEncoderDraw(pass, 3, 1, 0, 0);
+}
-- 
cgit v1.2.3