diff options
| author | skal <pascal.massimino@gmail.com> | 2026-02-16 14:32:59 +0100 |
|---|---|---|
| committer | skal <pascal.massimino@gmail.com> | 2026-02-16 14:32:59 +0100 |
| commit | b2ede3f0680edc894a54e28374cb87ab2690afa2 (patch) | |
| tree | 69e0a8c04eb29be953b037eb98e0a9ac0f1b417a /doc | |
| parent | 0fd3c982247d05bacbd67db08c865ec67602437f (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')
| -rw-r--r-- | doc/EFFECT_WORKFLOW.md | 68 | ||||
| -rw-r--r-- | doc/SEQUENCE.md (renamed from doc/SEQUENCE_v2.md) | 52 | ||||
| -rw-r--r-- | doc/archive/timeline_v1.seq | 97 |
3 files changed, 157 insertions, 60 deletions
diff --git a/doc/EFFECT_WORKFLOW.md b/doc/EFFECT_WORKFLOW.md index bdec2b6..c4010db 100644 --- a/doc/EFFECT_WORKFLOW.md +++ b/doc/EFFECT_WORKFLOW.md @@ -1,8 +1,8 @@ -# Effect Creation Workflow (v2) +# Effect Creation Workflow **Target Audience:** AI coding agents and developers -Checklist for adding visual effects using Sequence v2 system. +Checklist for adding visual effects. --- @@ -10,7 +10,7 @@ Checklist for adding visual effects using Sequence v2 system. **ShaderToy:** `tools/shadertoy/convert_shadertoy.py` then follow steps below **SDF/Raymarching:** See `doc/SDF_EFFECT_GUIDE.md` -**Custom v2 effects:** Follow all steps 1-6 +**Custom effects:** Follow all steps 1-6 --- @@ -18,18 +18,18 @@ Checklist for adding visual effects using Sequence v2 system. ### 1. Create Effect Files -**Files** (v2 naming): -- Header: `src/effects/<name>_effect_v2.h` -- Implementation: `src/effects/<name>_effect_v2.cc` -- Shader: `workspaces/main/shaders/<name>_v2.wgsl` +**Files**: +- Header: `src/effects/<name>_effect.h` +- Implementation: `src/effects/<name>_effect.cc` +- Shader: `workspaces/main/shaders/<name>.wgsl` -**Class name**: `<Name>EffectV2` (e.g., `TunnelEffectV2`) +**Class name**: `<Name>Effect` (e.g., `TunnelEffect`) -**Base class**: `EffectV2` (all effects) +**Base class**: `Effect` (all effects) **Constructor**: ```cpp -MyEffectV2(const GpuContext& ctx, +MyEffect(const GpuContext& ctx, const std::vector<std::string>& inputs, const std::vector<std::string>& outputs); ``` @@ -59,7 +59,7 @@ params.aspect_ratio; // width/height **File**: `workspaces/main/assets.txt` ``` -SHADER_<UPPER_NAME>, NONE, shaders/<name>_v2.wgsl, "Description" +SHADER_<UPPER_NAME>, NONE, shaders/<name>.wgsl, "Description" ``` Asset ID: `AssetId::ASSET_SHADER_<UPPER_NAME>` @@ -68,7 +68,7 @@ Asset ID: `AssetId::ASSET_SHADER_<UPPER_NAME>` **File**: `CMakeLists.txt` -Add `src/effects/<name>_effect_v2.cc` to **BOTH** GPU_SOURCES sections: +Add `src/effects/<name>_effect.cc` to **BOTH** GPU_SOURCES sections: - Headless mode (around line 141-167) - Normal mode (around line 171-197) @@ -77,16 +77,16 @@ Add `src/effects/<name>_effect_v2.cc` to **BOTH** GPU_SOURCES sections: **File**: `src/gpu/demo_effects.h` ```cpp -#include "effects/<name>_effect_v2.h" +#include "effects/<name>_effect.h" ``` ### 5. Add to Timeline -**File**: `workspaces/main/timeline_v2.seq` +**File**: `workspaces/main/timeline.seq` ``` SEQUENCE <start> <priority> "name" - EFFECT + MyEffectV2 source -> sink 0.0 4.0 + EFFECT + MyEffect source -> sink 0.0 4.0 ``` **Priority modifiers** (REQUIRED): `+` (increment), `=` (same), `-` (decrement) @@ -95,7 +95,7 @@ SEQUENCE <start> <priority> "name" ```bash # Regenerate timeline.cc -python3 tools/seq_compiler_v2.py workspaces/main/timeline_v2.seq \ +python3 tools/seq_compiler.py workspaces/main/timeline.seq \ --output src/generated/timeline.cc # Build @@ -112,17 +112,17 @@ cmake --build build -j4 ### Standard Post-Process Effect ```cpp -// my_effect_v2.h +// my_effect.h #pragma once -#include "gpu/effect_v2.h" +#include "gpu/effect.h" #include "gpu/uniform_helper.h" -class MyEffectV2 : public EffectV2 { +class MyEffect : public Effect { public: - MyEffectV2(const GpuContext& ctx, + MyEffect(const GpuContext& ctx, const std::vector<std::string>& inputs, const std::vector<std::string>& outputs); - ~MyEffectV2() override; + ~MyEffect() override; void render(WGPUCommandEncoder encoder, const UniformsSequenceParams& params, @@ -136,27 +136,27 @@ class MyEffectV2 : public EffectV2 { ``` ```cpp -// my_effect_v2.cc -#include "effects/my_effect_v2.h" +// my_effect.cc +#include "effects/my_effect.h" #include "gpu/post_process_helper.h" #include "gpu/shaders.h" -MyEffectV2::MyEffectV2(const GpuContext& ctx, +MyEffect::MyEffect(const GpuContext& ctx, const std::vector<std::string>& inputs, const std::vector<std::string>& outputs) - : EffectV2(ctx, inputs, outputs), pipeline_(nullptr), bind_group_(nullptr) { + : Effect(ctx, inputs, outputs), pipeline_(nullptr), bind_group_(nullptr) { uniforms_buffer_.init(ctx_.device); pipeline_ = create_post_process_pipeline(ctx_.device, WGPUTextureFormat_RGBA8Unorm, - my_shader_v2_wgsl); + my_shader_wgsl); } -MyEffectV2::~MyEffectV2() { +MyEffect::~MyEffect() { if (bind_group_) wgpuBindGroupRelease(bind_group_); if (pipeline_) wgpuRenderPipelineRelease(pipeline_); } -void MyEffectV2::render(WGPUCommandEncoder encoder, +void MyEffect::render(WGPUCommandEncoder encoder, const UniformsSequenceParams& params, NodeRegistry& nodes) { WGPUTextureView input_view = nodes.get_view(input_nodes_[0]); @@ -193,11 +193,11 @@ void MyEffectV2::render(WGPUCommandEncoder encoder, ### 3D Effect with Depth ```cpp -class My3DEffectV2 : public EffectV2 { +class My3DEffect : public Effect { std::string depth_node_; - My3DEffectV2(const GpuContext& ctx, ...) - : EffectV2(ctx, inputs, outputs), + My3DEffect(const GpuContext& ctx, ...) + : Effect(ctx, inputs, outputs), depth_node_(outputs[0] + "_depth") {} void declare_nodes(NodeRegistry& registry) override { @@ -251,6 +251,6 @@ class My3DEffectV2 : public EffectV2 { ## See Also -- `doc/SEQUENCE_v2.md` - Timeline syntax and architecture -- `tools/seq_compiler_v2.py` - Compiler implementation -- `src/effects/*_v2.{h,cc}` - Example effects +- `doc/SEQUENCE.md` - Timeline syntax and architecture +- `tools/seq_compiler.py` - Compiler implementation +- `src/effects/*.{h,cc}` - Example effects diff --git a/doc/SEQUENCE_v2.md b/doc/SEQUENCE.md index 7ce6efc..76e19d4 100644 --- a/doc/SEQUENCE_v2.md +++ b/doc/SEQUENCE.md @@ -1,17 +1,17 @@ -# Sequence v2: DAG-based Effect Routing +# Sequence: DAG-based Effect Routing -**Status:** ✅ Operational (Phase 4 complete, v1 removed) +**Status:** ✅ Operational -Explicit node system with DAG effect routing. Replaces v1 implicit framebuffer ping-pong. +Explicit node system with DAG effect routing. ## Quick Start ```bash # Compile timeline -python3 tools/seq_compiler_v2.py workspaces/main/timeline_v2.seq --output src/generated/timeline.cc +python3 tools/seq_compiler.py workspaces/main/timeline.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 +python3 tools/seq_compiler.py timeline.seq --output timeline.cc --flatten ``` ## Timeline Syntax @@ -72,10 +72,10 @@ SEQUENCE 0.0 0 "blur" ## Architecture -### SequenceV2 Class +### Sequence Class ```cpp -class SequenceV2 { +class Sequence { NodeRegistry nodes_; // Typed texture management std::vector<EffectDAGNode> effect_dag_; // Topologically sorted UniformsSequenceParams params_; // Per-frame uniforms @@ -85,10 +85,10 @@ class SequenceV2 { }; ``` -### EffectV2 Class +### Effect Class ```cpp -class EffectV2 { +class Effect { std::vector<std::string> input_nodes_; std::vector<std::string> output_nodes_; @@ -112,30 +112,30 @@ class EffectV2 { ## Compiler Features -**seq_compiler_v2.py** generates optimized C++ from `.seq`: +**seq_compiler.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 +4. **Code Generation**: Sequence 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 +- Multiple `Sequence` subclasses (one per SEQUENCE) +- `InitializeSequences()` - Registry initialization +- `GetActiveSequence(float time)` - Active sequence lookup +- `RenderTimeline()` - Encoder-based and surface-based variants ## Creating Effects **For standard post-process:** ```cpp -class MyEffectV2 : public EffectV2 { +class MyEffect : public Effect { WGPURenderPipeline pipeline_; UniformBuffer<UniformsSequenceParams> uniforms_; - MyEffectV2(const GpuContext& ctx, const std::vector<std::string>& inputs, + MyEffect(const GpuContext& ctx, const std::vector<std::string>& inputs, const std::vector<std::string>& outputs); const std::vector<std::string>& outputs) - : EffectV2(ctx, inputs, outputs) { + : Effect(ctx, inputs, outputs) { uniforms_.init(ctx_.device); pipeline_ = create_post_process_pipeline(ctx_.device, WGPUTextureFormat_RGBA8Unorm, @@ -154,10 +154,10 @@ class MyEffectV2 : public EffectV2 { **For 3D effects with depth:** ```cpp -class My3DEffectV2 : public EffectV2 { +class My3DEffect : public Effect { std::string depth_node_; - My3DEffectV2(...) : EffectV2(...), depth_node_(outputs[0] + "_depth") {} + My3DEffect(...) : Effect(...), depth_node_(outputs[0] + "_depth") {} void declare_nodes(NodeRegistry& registry) override { registry.declare_node(depth_node_, NodeType::DEPTH24, -1, -1); @@ -201,21 +201,21 @@ params.aspect_ratio; // width/height **TODO**: - Port remaining effects (10+ effects, CNN effects) - Implement flatten mode (inline effects, direct members) -- Update HTML timeline editor for v2 graph visualization +- Update HTML timeline editor for graph visualization ## Migration Notes -**V1 → V2 Differences**: +**Key Features**: - V1: Implicit framebuffer ping-pong (framebuffer_a_ ↔ framebuffer_b_) -- V2: Explicit node declarations with routing +- Explicit node declarations with routing **Breaking Changes**: -- Effect base class changed (Effect → EffectV2) +- Effect base class standardized - 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 +- `tools/seq_compiler.py` - Compiler implementation +- `workspaces/main/timeline.seq` - Example timeline diff --git a/doc/archive/timeline_v1.seq b/doc/archive/timeline_v1.seq new file mode 100644 index 0000000..b4663bb --- /dev/null +++ b/doc/archive/timeline_v1.seq @@ -0,0 +1,97 @@ +# Demo Timeline +# Generated by Timeline Editor +# BPM 90 + +SEQUENCE 0.00 0 + EFFECT - FlashCubeEffect 0.00 4.00 +# EFFECT + FlashEffect 0.00 2.00 color=1.0,0.5,0.5 decay=0.95 +# EFFECT + FadeEffect 2.00 4.00 +# EFFECT + SolarizeEffect 0.00 4.00 + EFFECT + VignetteEffect 0.00 4.00 radius=0.6 softness=0.1 + +SEQUENCE 4.00 0 "rotating cube" + EFFECT + CircleMaskEffect 0.00 4.00 0.50 + EFFECT + RotatingCubeEffect 0.00 4.00 + EFFECT + GaussianBlurEffect 1.00 4.00 strength=1.0 + +SEQUENCE 8.00 0 "Flash Cube" + EFFECT - FlashCubeEffect 0.00 4.02 + EFFECT + FlashEffect 0.00 0.40 + +SEQUENCE 12.00 1 "spray" + EFFECT + ParticleSprayEffect 0.00 2.00 + EFFECT + ParticlesEffect 2.00 4.00 + EFFECT = GaussianBlurEffect 0.00 4.00 strength=3.0 + +SEQUENCE 16.00 2 "Hybrid3D + CNN" + EFFECT + ThemeModulationEffect 0.00 4.00 + EFFECT + HeptagonEffect 0.00 4.00 + EFFECT + ParticleSprayEffect 0.00 2.00 + EFFECT = ParticlesEffect 2.00 4.00 + EFFECT + Hybrid3DEffect 0.00 4.00 + EFFECT + CNNv1Effect 0.00 4.00 layers=3 blend=.9 + +SEQUENCE 20.00 0 "CNN effect" + EFFECT + HeptagonEffect 0.00 8.00 + EFFECT + Scene1Effect 0.00 8.00 + EFFECT + CNNv1Effect 6.00 8.00 layers=3 blend=.5 + +SEQUENCE 28.00 0 "buggy" + EFFECT + HeptagonEffect 0.00 2.00 + EFFECT + FadeEffect 0.00 2.00 + +SEQUENCE 30.00 3 "Seq-8" + EFFECT + ThemeModulationEffect 0.00 10.00 + EFFECT = HeptagonEffect 0.00 10.00 + EFFECT + GaussianBlurEffect 0.00 10.00 strength=1.5 + EFFECT + ChromaAberrationEffect 0.00 10.00 offset=0.03 angle=0.785 + EFFECT + SolarizeEffect 0.00 10.00 + +SEQUENCE 40.00 2 + EFFECT - FlashCubeEffect 0.00 4.00 + EFFECT + HeptagonEffect 0.00 4.00 + EFFECT + ParticleSprayEffect 0.00 4.00 + +SEQUENCE 44.00 2 "Fade" + EFFECT - FlashCubeEffect 0.00 2.00 + EFFECT + FlashEffect 1.00 2.00 + +SEQUENCE 46.00 10 + EFFECT - FlashCubeEffect 0.00 3.00 + EFFECT + GaussianBlurEffect 0.00 3.00 + EFFECT + FlashEffect 0.00 3.00 + +SEQUENCE 49.00 1 + EFFECT + ThemeModulationEffect 0.00 8.00 + EFFECT + HeptagonEffect 0.00 8.00 + EFFECT + ParticleSprayEffect 0.00 8.00 + EFFECT + Hybrid3DEffect 0.00 8.00 + EFFECT + GaussianBlurEffect 0.00 8.00 + EFFECT + ChromaAberrationEffect 0.00 8.00 + +SEQUENCE 57.00 0 + EFFECT + ThemeModulationEffect 0.00 7.00 + EFFECT + VignetteEffect 0.00 7.00 radius=0.6 softness=0.3 + EFFECT + SolarizeEffect 0.00 7.00 + +SEQUENCE 64.00 0 + EFFECT + ThemeModulationEffect 0.00 4.00 + EFFECT + HeptagonEffect 0.00 4.00 + EFFECT + GaussianBlurEffect 0.00 4.00 + EFFECT + SolarizeEffect 0.00 4.00 + +SEQUENCE 68.00 0 "double hepta!" + EFFECT + ThemeModulationEffect 0.00 4.00 + EFFECT = HeptagonEffect 0.00 4.00 + EFFECT + Hybrid3DEffect 0.00 4.00 + EFFECT + ParticleSprayEffect 0.00 4.00 + EFFECT + HeptagonEffect 0.00 4.00 + EFFECT + ChromaAberrationEffect 0.00 4.00 + EFFECT + GaussianBlurEffect 0.00 4.00 + +SEQUENCE 72.00 0 "The End" + EFFECT + ThemeModulationEffect 0.00 7.00 + EFFECT + HeptagonEffect 0.00 7.00 + EFFECT + ChromaAberrationEffect 0.00 7.00 + EFFECT + GaussianBlurEffect 0.00 7.00 + |
