summaryrefslogtreecommitdiff
path: root/doc/SEQUENCE_v2.md
diff options
context:
space:
mode:
authorskal <pascal.massimino@gmail.com>2026-02-16 14:32:59 +0100
committerskal <pascal.massimino@gmail.com>2026-02-16 14:32:59 +0100
commitb2ede3f0680edc894a54e28374cb87ab2690afa2 (patch)
tree69e0a8c04eb29be953b037eb98e0a9ac0f1b417a /doc/SEQUENCE_v2.md
parent0fd3c982247d05bacbd67db08c865ec67602437f (diff)
refactor: remove v2 versioning artifacts, establish Sequence as canonical system
Complete v1→v2 migration cleanup: rename 29 files (sequence_v2→sequence, effect_v2→effect, 14 effect files, 8 shaders, compiler, docs), update all class names and references across 54 files. Archive v1 timeline. System now uses standard naming with all versioning removed. 30/34 tests passing. Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
Diffstat (limited to 'doc/SEQUENCE_v2.md')
-rw-r--r--doc/SEQUENCE_v2.md221
1 files changed, 0 insertions, 221 deletions
diff --git a/doc/SEQUENCE_v2.md b/doc/SEQUENCE_v2.md
deleted file mode 100644
index 7ce6efc..0000000
--- a/doc/SEQUENCE_v2.md
+++ /dev/null
@@ -1,221 +0,0 @@
-# Sequence v2: DAG-based Effect Routing
-
-**Status:** ✅ Operational (Phase 4 complete, v1 removed)
-
-Explicit node system with DAG effect routing. Replaces v1 implicit framebuffer ping-pong.
-
-## Quick Start
-
-```bash
-# Compile timeline
-python3 tools/seq_compiler_v2.py workspaces/main/timeline_v2.seq --output src/generated/timeline.cc
-
-# Flatten mode (future: inline effects, no vtables)
-python3 tools/seq_compiler_v2.py timeline.seq --output timeline.cc --flatten
-```
-
-## Timeline Syntax
-
-```
-# BPM 120 (optional, currently ignored)
-
-SEQUENCE <start_time> <priority> ["name"]
- # Node declarations (optional, auto-inferred as u8x4_norm)
- NODE temp1 u8x4_norm
- NODE depth depth24
- NODE gbuf_normal f16x8
-
- # Asset dependencies (validated at compile-time)
- ASSET shader_blur
-
- # Effect routing with priority modifier
- EFFECT <+|=|-> EffectClass input1 input2 -> output1 output2 start end [params]
-```
-
-**Priority modifiers** (REQUIRED):
-- `+` : Increment priority (foreground)
-- `=` : Same priority as previous
-- `-` : Decrement priority (background)
-
-**Node types**: `u8x4_norm` (default), `f32x4`, `f16x8`, `depth24`, `compute_f32`
-
-**Reserved nodes**: `source` (input), `sink` (output)
-
-### Examples
-
-**Simple chain:**
-```
-SEQUENCE 0.0 0 "basic"
- EFFECT + HeptagonEffect source -> temp1 0.0 10.0
- EFFECT + GaussianBlur temp1 -> sink 0.0 10.0
-```
-
-**Multi-output (G-buffer):**
-```
-SEQUENCE 0.0 0 "deferred"
- NODE gbuf_n f16x8
- NODE gbuf_p f32x4
- NODE depth depth24
-
- EFFECT + DeferredRender source depth -> gbuf_n gbuf_p 0.0 10.0
- EFFECT + Compose gbuf_n gbuf_p -> sink 0.0 10.0
-```
-
-**Ping-pong (auto-optimized):**
-```
-SEQUENCE 0.0 0 "blur"
- # Compiler detects alternating pattern, aliases temp2 -> temp1
- EFFECT + BlurH source -> temp1 0.0 10.0
- EFFECT + BlurV temp1 -> temp2 0.0 10.0
- EFFECT + Sharpen temp2 -> sink 0.0 10.0
-```
-
-## Architecture
-
-### SequenceV2 Class
-
-```cpp
-class SequenceV2 {
- NodeRegistry nodes_; // Typed texture management
- std::vector<EffectDAGNode> effect_dag_; // Topologically sorted
- UniformsSequenceParams params_; // Per-frame uniforms
-
- virtual void preprocess(float time, float beat_time, float beat_phase, float audio_intensity);
- virtual void render_effects(WGPUCommandEncoder encoder);
-};
-```
-
-### EffectV2 Class
-
-```cpp
-class EffectV2 {
- std::vector<std::string> input_nodes_;
- std::vector<std::string> output_nodes_;
-
- virtual void declare_nodes(NodeRegistry& registry) {} // Optional temp nodes
- virtual void render(WGPUCommandEncoder encoder,
- const UniformsSequenceParams& params,
- NodeRegistry& nodes) = 0;
-};
-```
-
-### Node System
-
-**Types**: Match WGSL texture formats
-- `U8X4_NORM`: RGBA8Unorm (default for source/sink/intermediate)
-- `F32X4`: RGBA32Float (HDR, compute outputs)
-- `F16X8`: 8-channel float16 (G-buffer normals/vectors)
-- `DEPTH24`: Depth24Plus (3D rendering)
-- `COMPUTE_F32`: Storage buffer (non-texture compute data)
-
-**Aliasing**: Compiler detects ping-pong patterns (Effect i writes A reads B, Effect i+1 writes B reads A) and aliases nodes to same backing texture.
-
-## Compiler Features
-
-**seq_compiler_v2.py** generates optimized C++ from `.seq`:
-
-1. **DAG Validation**: Cycle detection, connectivity checks
-2. **Topological Sort**: Execution order from dependencies
-3. **Ping-pong Detection**: Automatic node aliasing
-4. **Code Generation**: SequenceV2 subclasses with node declarations and effect DAG
-
-**Output**: Single `.cc` file with:
-- Multiple `SequenceV2` subclasses (one per SEQUENCE)
-- `InitializeV2Sequences()` - Registry initialization
-- `GetActiveV2Sequence(float time)` - Active sequence lookup
-- `RenderV2Timeline()` - Encoder-based and surface-based variants
-
-## Creating Effects
-
-**For standard post-process:**
-```cpp
-class MyEffectV2 : public EffectV2 {
- WGPURenderPipeline pipeline_;
- UniformBuffer<UniformsSequenceParams> uniforms_;
-
- MyEffectV2(const GpuContext& ctx, const std::vector<std::string>& inputs,
- const std::vector<std::string>& outputs)
- : EffectV2(ctx, inputs, outputs) {
- uniforms_.init(ctx_.device);
- pipeline_ = create_post_process_pipeline(ctx_.device,
- WGPUTextureFormat_RGBA8Unorm,
- my_shader_wgsl);
- }
-
- void render(WGPUCommandEncoder encoder, const UniformsSequenceParams& params,
- NodeRegistry& nodes) override {
- WGPUTextureView input = nodes.get_view(input_nodes_[0]);
- WGPUTextureView output = nodes.get_view(output_nodes_[0]);
- uniforms_.update(ctx_.queue, params);
- // ... render pass
- }
-};
-```
-
-**For 3D effects with depth:**
-```cpp
-class My3DEffectV2 : public EffectV2 {
- std::string depth_node_;
-
- My3DEffectV2(...) : EffectV2(...), depth_node_(outputs[0] + "_depth") {}
-
- void declare_nodes(NodeRegistry& registry) override {
- registry.declare_node(depth_node_, NodeType::DEPTH24, -1, -1);
- }
-
- void render(...) {
- WGPUTextureView color = nodes.get_view(output_nodes_[0]);
- WGPUTextureView depth = nodes.get_view(depth_node_);
- // ... render pass with depth attachment
- }
-};
-```
-
-## Uniform Access
-
-```cpp
-params.time; // Physical seconds (constant speed)
-params.beat_time; // Musical beats (tempo-scaled)
-params.beat_phase; // Fractional beat 0.0-1.0
-params.audio_intensity; // Audio peak for beat sync
-params.resolution; // vec2(width, height)
-params.aspect_ratio; // width/height
-```
-
-## Status & Limitations
-
-**Implemented** ✅:
-- DAG validation, topological sort, ping-pong optimization
-- Multi-input/multi-output effects
-- Node aliasing (compile-time optimization)
-- 7 effects ported (Passthrough, Placeholder, GaussianBlur, Heptagon, Particles, RotatingCube, Hybrid3D)
-
-**Missing/Future** ❌:
-- Flatten mode (--flatten generates same code as dev mode)
-- BPM handling (parsed but ignored)
-- GetDemoDuration() calculation (hardcoded 40.0f)
-- Sequence-relative time (uses global time)
-- Asset validation (not checked against AssetId enum)
-- Node type compatibility checking
-
-**TODO**:
-- Port remaining effects (10+ effects, CNN effects)
-- Implement flatten mode (inline effects, direct members)
-- Update HTML timeline editor for v2 graph visualization
-
-## Migration Notes
-
-**V1 → V2 Differences**:
-- V1: Implicit framebuffer ping-pong (framebuffer_a_ ↔ framebuffer_b_)
-- V2: Explicit node declarations with routing
-
-**Breaking Changes**:
-- Effect base class changed (Effect → EffectV2)
-- Constructor signature: `(GpuContext, inputs[], outputs[])`
-- Render signature: Added `NodeRegistry& nodes` parameter
-- No `is_post_process()` method (routing makes it explicit)
-
-**See Also**:
-- `doc/EFFECT_WORKFLOW.md` - Step-by-step effect creation
-- `tools/seq_compiler_v2.py` - Compiler implementation
-- `workspaces/main/timeline_v2.seq` - Example timeline