diff options
Diffstat (limited to 'doc/EFFECT_WORKFLOW.md')
| -rw-r--r-- | doc/EFFECT_WORKFLOW.md | 332 |
1 files changed, 170 insertions, 162 deletions
diff --git a/doc/EFFECT_WORKFLOW.md b/doc/EFFECT_WORKFLOW.md index 57cf904..bdec2b6 100644 --- a/doc/EFFECT_WORKFLOW.md +++ b/doc/EFFECT_WORKFLOW.md @@ -1,248 +1,256 @@ -# Effect Creation Workflow +# Effect Creation Workflow (v2) **Target Audience:** AI coding agents and developers -Automated checklist for adding new visual effects to the demo. +Checklist for adding visual effects using Sequence v2 system. --- ## Quick Reference -**For ShaderToy conversions:** Use `tools/shadertoy/convert_shadertoy.py` then follow steps 3-8 below. - -**For SDF/raymarching effects:** See `doc/SDF_EFFECT_GUIDE.md` for streamlined workflow using SDFEffect base class. - -**For custom effects:** Follow all steps 1-8. +**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 --- -## Step-by-Step Workflow +## Workflow ### 1. Create Effect Files -**Description:** Each visual effect must have its own dedicated header (`.h`) and implementation (`.cc`) file pair. - -**Location:** -- Header: `src/effects/<effect_name>_effect.h` -- Implementation: `src/effects/<effect_name>_effect.cc` -- Shader: `workspaces/main/shaders/<effect_name>.wgsl` +**Files** (v2 naming): +- Header: `src/effects/<name>_effect_v2.h` +- Implementation: `src/effects/<name>_effect_v2.cc` +- Shader: `workspaces/main/shaders/<name>_v2.wgsl` -**Naming Convention:** -- Class name: `<EffectName>Effect` (e.g., `TunnelEffect`, `PlasmaEffect`) -- Files: `<effect_name>_effect.*` (snake_case) +**Class name**: `<Name>EffectV2` (e.g., `TunnelEffectV2`) -**Base Class:** -- Post-process effects: inherit from `PostProcessEffect` -- Scene effects: inherit from `Effect` +**Base class**: `EffectV2` (all effects) -**Render Signature:** +**Constructor**: ```cpp -void render(WGPURenderPassEncoder pass, - const CommonPostProcessUniforms& uniforms) override; +MyEffectV2(const GpuContext& ctx, + const std::vector<std::string>& inputs, + const std::vector<std::string>& outputs); ``` -**Uniforms Available:** +**Required methods**: ```cpp -uniforms.time; // Physical seconds (constant speed) -uniforms.beat_time; // Musical beats (bar synchronization) -uniforms.beat_phase; // Fractional beat 0.0-1.0 (smooth oscillation) -uniforms.audio_intensity; // Audio peak for beat sync -uniforms.resolution; // Screen dimensions -uniforms.aspect_ratio; // Width/height ratio +void render(WGPUCommandEncoder encoder, + const UniformsSequenceParams& params, + NodeRegistry& nodes) override; + +// Optional: for effects needing temp nodes (depth buffers, intermediate textures) +void declare_nodes(NodeRegistry& registry) override; ``` -**Template:** See `tools/shadertoy/template.*` or use `convert_shadertoy.py` +**Uniforms**: +```cpp +params.time; // Physical seconds +params.beat_time; // Musical beats +params.beat_phase; // Fractional beat 0.0-1.0 +params.audio_intensity; // Audio peak +params.resolution; // vec2(width, height) +params.aspect_ratio; // width/height +``` ### 2. Add Shader to Assets -**File:** `workspaces/main/assets.txt` +**File**: `workspaces/main/assets.txt` -**Format:** ``` -SHADER_<UPPER_SNAKE_NAME>, NONE, shaders/<effect_name>.wgsl, "Effect description" +SHADER_<UPPER_NAME>, NONE, shaders/<name>_v2.wgsl, "Description" ``` -**Example:** -``` -SHADER_TUNNEL, NONE, shaders/tunnel.wgsl, "Tunnel effect shader" -``` - -**Asset ID:** Will be `AssetId::ASSET_SHADER_<UPPER_SNAKE_NAME>` in C++ +Asset ID: `AssetId::ASSET_SHADER_<UPPER_NAME>` ### 3. Add to CMakeLists.txt -**File:** `CMakeLists.txt` +**File**: `CMakeLists.txt` -**Action:** Add `src/effects/<effect_name>_effect.cc` to **BOTH** GPU_SOURCES sections: -- Headless mode section (around line 141-167) -- Normal mode section (around line 171-197) - -**Location:** After similar effects (post-process with post-process, scene with scene) - -**Example:** -```cmake -# In headless section (line ~152): - src/effects/solarize_effect.cc - src/effects/tunnel_effect.cc # <-- Add here - src/effects/chroma_aberration_effect.cc - -# In normal section (line ~183): - src/effects/solarize_effect.cc - src/effects/tunnel.cc # <-- Add here - src/effects/chroma_aberration_effect.cc -``` +Add `src/effects/<name>_effect_v2.cc` to **BOTH** GPU_SOURCES sections: +- Headless mode (around line 141-167) +- Normal mode (around line 171-197) ### 4. Include in demo_effects.h -**File:** `src/gpu/demo_effects.h` +**File**: `src/gpu/demo_effects.h` -**Action:** `src/gpu/demo_effects.h` now acts as a central include file. Add a single include directive for your new effect's header: ```cpp -#include "effects/<effect_name>_effect.h" +#include "effects/<name>_effect_v2.h" ``` -**Location:** Alphabetically with other effect includes - ### 5. Add to Timeline -**File:** `workspaces/main/timeline.seq` - -**Format:** -``` -SEQUENCE <start_time> <priority> - EFFECT <+|=|-> <EffectName>Effect <local_start> <local_end> [params...] -``` - -**Priority Modifiers (REQUIRED):** -- `+` : Increment priority -- `=` : Same priority as previous effect -- `-` : Decrement priority (for backgrounds) +**File**: `workspaces/main/timeline_v2.seq` -**Example:** ``` -SEQUENCE 0.0 0 - EFFECT + TunnelEffect 0.0 10.0 +SEQUENCE <start> <priority> "name" + EFFECT + MyEffectV2 source -> sink 0.0 4.0 ``` -**Common Mistake:** Missing priority modifier (`+`, `=`, `-`) after EFFECT keyword +**Priority modifiers** (REQUIRED): `+` (increment), `=` (same), `-` (decrement) -### 6. Update Tests - -**File:** `src/tests/gpu/test_demo_effects.cc` - -**Action:** Add effect to appropriate list: - -**Post-Process Effects (lines 80-93):** -```cpp -{"TunnelEffect", std::make_shared<TunnelEffect>(fixture.ctx())}, -``` - -**Scene Effects (lines 125-137):** -```cpp -{"TunnelEffect", std::make_shared<TunnelEffect>(fixture.ctx())}, -``` - -**3D Effects:** If requires Renderer3D, add to `requires_3d` check (line 148-151) - -### 7. Build and Test +### 6. Regenerate and Build ```bash -# Full build -cmake --build build -j4 +# Regenerate timeline.cc +python3 tools/seq_compiler_v2.py workspaces/main/timeline_v2.seq \ + --output src/generated/timeline.cc -# Run effect tests -cmake -S . -B build -DDEMO_BUILD_TESTS=ON -cmake --build build -j4 --target test_demo_effects -cd build && ./test_demo_effects +# Build +cmake --build build -j4 -# Run all tests -cd build && ctest +# Test +./build/demo64k ``` -### 8. Verify +--- -**Checklist:** -- [ ] Effect compiles without errors -- [ ] Effect appears in timeline -- [ ] test_demo_effects passes -- [ ] Effect renders correctly: `./build/demo64k` -- [ ] No shader compilation errors -- [ ] Follows naming conventions +## Templates ---- +### Standard Post-Process Effect -## Common Issues +```cpp +// my_effect_v2.h +#pragma once +#include "gpu/effect_v2.h" +#include "gpu/uniform_helper.h" -### Build Error: "no member named 'ASSET_..._SHADER'" +class MyEffectV2 : public EffectV2 { + public: + MyEffectV2(const GpuContext& ctx, + const std::vector<std::string>& inputs, + const std::vector<std::string>& outputs); + ~MyEffectV2() override; -**Cause:** Shader not in assets.txt or wrong asset ID name + void render(WGPUCommandEncoder encoder, + const UniformsSequenceParams& params, + NodeRegistry& nodes) override; -**Fix:** -1. Check `workspaces/main/assets.txt` has shader entry -2. Asset ID is `ASSET_` + uppercase entry name (e.g., `SHADER_TUNNEL` → `ASSET_SHADER_TUNNEL`) + private: + WGPURenderPipeline pipeline_; + WGPUBindGroup bind_group_; + UniformBuffer<UniformsSequenceParams> uniforms_buffer_; +}; +``` -### Build Error: "undefined symbol for architecture" +```cpp +// my_effect_v2.cc +#include "effects/my_effect_v2.h" +#include "gpu/post_process_helper.h" +#include "gpu/shaders.h" -**Cause:** Effect not in CMakeLists.txt GPU_SOURCES +MyEffectV2::MyEffectV2(const GpuContext& ctx, + const std::vector<std::string>& inputs, + const std::vector<std::string>& outputs) + : EffectV2(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); +} -**Fix:** Add `.cc` file to BOTH sections (headless and normal mode) +MyEffectV2::~MyEffectV2() { + if (bind_group_) wgpuBindGroupRelease(bind_group_); + if (pipeline_) wgpuRenderPipelineRelease(pipeline_); +} -### Timeline Parse Error: "Expected '+', '=', or '-'" +void MyEffectV2::render(WGPUCommandEncoder encoder, + const UniformsSequenceParams& params, + NodeRegistry& nodes) { + WGPUTextureView input_view = nodes.get_view(input_nodes_[0]); + WGPUTextureView output_view = nodes.get_view(output_nodes_[0]); -**Cause:** Missing priority modifier after EFFECT keyword + uniforms_buffer_.update(ctx_.queue, params); + pp_update_bind_group(ctx_.device, pipeline_, &bind_group_, input_view, + uniforms_buffer_.get(), {nullptr, 0}); -**Fix:** Use `EFFECT +`, `EFFECT =`, or `EFFECT -` (never just `EFFECT`) + WGPURenderPassColorAttachment color_attachment = { + .view = output_view, +#if !defined(DEMO_CROSS_COMPILE_WIN32) + .depthSlice = WGPU_DEPTH_SLICE_UNDEFINED, +#endif + .loadOp = WGPULoadOp_Clear, + .storeOp = WGPUStoreOp_Store, + .clearValue = {0.0, 0.0, 0.0, 1.0} + }; -### Test Failure: Effect not in test list + WGPURenderPassDescriptor pass_desc = { + .colorAttachmentCount = 1, + .colorAttachments = &color_attachment + }; -**Cause:** Effect not added to test_demo_effects.cc + WGPURenderPassEncoder pass = wgpuCommandEncoderBeginRenderPass(encoder, &pass_desc); + wgpuRenderPassEncoderSetPipeline(pass, pipeline_); + wgpuRenderPassEncoderSetBindGroup(pass, 0, bind_group_, 0, nullptr); + wgpuRenderPassEncoderDraw(pass, 3, 1, 0, 0); // Fullscreen triangle + wgpuRenderPassEncoderEnd(pass); + wgpuRenderPassEncoderRelease(pass); +} +``` -**Fix:** Add to `post_process_effects` or `scene_effects` list +### 3D Effect with Depth ---- +```cpp +class My3DEffectV2 : public EffectV2 { + std::string depth_node_; -## Automation Script Example + My3DEffectV2(const GpuContext& ctx, ...) + : EffectV2(ctx, inputs, outputs), + depth_node_(outputs[0] + "_depth") {} -```bash -#!/bin/bash -# Example automation for AI agents + void declare_nodes(NodeRegistry& registry) override { + registry.declare_node(depth_node_, NodeType::DEPTH24, -1, -1); + } -EFFECT_NAME="$1" # CamelCase (e.g., "Tunnel") -SNAKE_NAME=$(echo "$EFFECT_NAME" | sed 's/\([A-Z]\)/_\L\1/g' | sed 's/^_//') -UPPER_NAME=$(echo "$SNAKE_NAME" | tr '[:lower:]' '[:upper:]') + void render(WGPUCommandEncoder encoder, + const UniformsSequenceParams& params, + NodeRegistry& nodes) override { + WGPUTextureView color_view = nodes.get_view(output_nodes_[0]); + WGPUTextureView depth_view = nodes.get_view(depth_node_); -echo "Creating effect: $EFFECT_NAME" -echo " Snake case: $SNAKE_NAME" -echo " Upper case: $UPPER_NAME" + WGPURenderPassDepthStencilAttachment depth_attachment = { + .view = depth_view, + .depthLoadOp = WGPULoadOp_Clear, + .depthStoreOp = WGPUStoreOp_Discard, + .depthClearValue = 1.0f + }; -# 1. Generate files (if using ShaderToy) -# ./tools/shadertoy/convert_shadertoy.py shader.txt "$EFFECT_NAME" + WGPURenderPassDescriptor pass_desc = { + .colorAttachmentCount = 1, + .colorAttachments = &color_attachment, + .depthStencilAttachment = &depth_attachment + }; + // ... render 3D scene + } +}; +``` -# 2. Add to assets.txt -echo "SHADER_${UPPER_NAME}, NONE, shaders/${SNAKE_NAME}.wgsl, \"${EFFECT_NAME} effect\"" \ - >> workspaces/main/assets.txt +--- -# 3. Add to CMakeLists.txt (both sections) -# Use Edit tool to add to both GPU_SOURCES sections +## Common Issues -# 4. Add include to demo_effects.h -# Use Edit tool to add #include line +**Build Error: "no member named 'ASSET_..._SHADER'"** +- Shader not in `assets.txt` or wrong name +- Asset ID is `ASSET_` + uppercase entry name -# 5. Add to timeline.seq -# Use Edit tool to add EFFECT line with priority modifier +**Build Error: "undefined symbol"** +- Effect not in CMakeLists.txt GPU_SOURCES +- Must add to BOTH sections (headless + normal) -# 6. Add to test file -# Use Edit tool to add to appropriate test list +**Runtime Error: "Node not found"** +- Forgot `declare_nodes()` for temp nodes +- `init_effect_nodes()` not called (check generated timeline.cc) -# 7. Build -cmake --build build -j4 -``` +**Runtime Error: "invalid bind group"** +- Pipeline format doesn't match framebuffer (use RGBA8Unorm) +- Missing texture view or null resource --- ## See Also -- `tools/shadertoy/README.md` - ShaderToy conversion guide -- `doc/SEQUENCE.md` - Timeline format documentation -- `doc/CONTRIBUTING.md` - General contribution guidelines -- `src/effects/` - Existing effect examples +- `doc/SEQUENCE_v2.md` - Timeline syntax and architecture +- `tools/seq_compiler_v2.py` - Compiler implementation +- `src/effects/*_v2.{h,cc}` - Example effects |