summaryrefslogtreecommitdiff
path: root/doc
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
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')
-rw-r--r--doc/EFFECT_WORKFLOW.md68
-rw-r--r--doc/SEQUENCE.md (renamed from doc/SEQUENCE_v2.md)52
-rw-r--r--doc/archive/timeline_v1.seq97
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
+