diff options
| -rw-r--r-- | GEMINI.md | 2 | ||||
| -rw-r--r-- | HANDOFF_2026-02-07_AssetRegeneration.md | 112 | ||||
| -rw-r--r-- | HANDOFF_2026-02-07_Final.md | 55 | ||||
| -rw-r--r-- | HANDOFF_2026-02-07_GpuContext.md | 83 | ||||
| -rw-r--r-- | HANDOFF_2026-02-09_UniformAlignment.md | 125 |
5 files changed, 1 insertions, 376 deletions
@@ -52,7 +52,7 @@ # @doc/HANDOFF_CLAUDE.md # @doc/HANDOFF.md # @doc/HANDOFF_2026-02-04.md -# @HANDOFF_2026-02-09_DemoEffectsTest.md + # # Task Tracking: # @doc/TASKS_SUMMARY.md diff --git a/HANDOFF_2026-02-07_AssetRegeneration.md b/HANDOFF_2026-02-07_AssetRegeneration.md deleted file mode 100644 index dd41b31..0000000 --- a/HANDOFF_2026-02-07_AssetRegeneration.md +++ /dev/null @@ -1,112 +0,0 @@ -# Handoff: Asset Regeneration Fix (February 7, 2026) - -## Session Summary -Fixed build system issue where generated files weren't automatically regenerated after `make clean`, causing "fatal error: 'generated/assets.h' file not found" errors. - -## Problem -After running `make clean` in the build directory, the build would fail because: -1. Generated asset files (`generated/assets.h`, etc.) were removed -2. CMake didn't know to regenerate them before compiling libraries -3. Libraries (`audio`, `3d`, `gpu`) tried to compile before assets existed - -## Solution - -### 1. Mark Generated Files with GENERATED Property -Added `set_source_files_properties()` calls to tell CMake these files are generated and should be checked for rebuild: - -```cmake -# Mark generated files so CMake always checks if they need rebuilding -set_source_files_properties(${GEN_DEMO_H} ${GEN_DEMO_CC} PROPERTIES GENERATED TRUE) -set_source_files_properties(${GEN_TEST_H} ${GEN_TEST_CC} PROPERTIES GENERATED TRUE) -set_source_files_properties(${GENERATED_TIMELINE_CC} PROPERTIES GENERATED TRUE) -set_source_files_properties(${GENERATED_MUSIC_DATA_CC} PROPERTIES GENERATED TRUE) -set_source_files_properties(${GENERATED_TEST_DEMO_TIMELINE_CC} PROPERTIES GENERATED TRUE) -set_source_files_properties(${GENERATED_TEST_DEMO_MUSIC_CC} PROPERTIES GENERATED TRUE) -``` - -### 2. Add Explicit Library Dependencies -Added `add_dependencies()` to ensure libraries wait for asset generation: - -```cmake -# Libraries must wait for asset generation (they include generated/assets.h) -add_dependencies(audio generate_demo_assets) -add_dependencies(3d generate_demo_assets) -add_dependencies(gpu generate_demo_assets) -``` - -### 3. Update seq_compiler for GpuContext -Updated code generator to match the GpuContext refactor from earlier session: - -**Before:** -```cpp -"void LoadTimeline(MainSequence& main_seq, WGPUDevice device, " - "WGPUQueue queue, WGPUTextureFormat format) {\n"; - -">(device, queue, format" << eff.extra_args << "), " -``` - -**After:** -```cpp -"void LoadTimeline(MainSequence& main_seq, const GpuContext& ctx) {\n"; - -">(ctx" << eff.extra_args << "), " -``` - -### 4. Cleanup Stale Files -Removed old generated test assets that were incorrectly placed in `src/generated/`: -- `test_assets.h` / `test_assets_data.cc` (now in `build/src/generated_test/`) -- `test_demo_assets.h` / `test_demo_assets_data.cc` (now in `build/src/generated_test/`) - -## Commit Made - -**Commit:** fb2aa8b -**Title:** `fix: Auto-regenerate assets after clean build` - -**Changes:** -- CMakeLists.txt: +15 lines (GENERATED properties + dependencies) -- tools/seq_compiler.cc: Updated signatures -- Removed 4 stale generated files (~41K lines) - -## Verification - -**Clean Build Test:** -```bash -cd build -make clean -rm -f ../src/generated/*.{h,cc} -cmake --build . --target demo64k -``` - -**Result:** ✅ Build succeeds, assets regenerated automatically - -**Tests:** ✅ All 28 tests pass - -## Technical Details - -**Build Order (After Fix):** -1. Build tools: `seq_compiler`, `tracker_compiler`, `asset_packer` -2. Generate files: `generate_timeline`, `generate_tracker_music`, `generate_demo_assets` -3. **Wait for generation to complete** (new dependency) -4. Build libraries: `audio`, `3d`, `gpu` (now safe to compile) -5. Build executables: `demo64k`, `test_demo` - -**Key Insight:** -The `GENERATED` property alone isn't enough - you also need explicit `add_dependencies()` for libraries that consume generated headers. Without it, CMake may start compiling library sources before the generation targets complete. - -## Files Modified -- CMakeLists.txt (15 insertions) -- tools/seq_compiler.cc (5 changes) -- Removed 4 stale files - -## Current State -- ✅ All targets build successfully after clean -- ✅ All 28 tests passing -- ✅ Working tree clean -- ✅ 4 commits ahead of origin/main - -## Ready For -- Push to origin (`git push`) -- Continue with next priorities - ---- -**handoff(Claude):** Asset regeneration fixed. Clean builds now work correctly. All dependencies tracked properly. diff --git a/HANDOFF_2026-02-07_Final.md b/HANDOFF_2026-02-07_Final.md deleted file mode 100644 index 36b53c3..0000000 --- a/HANDOFF_2026-02-07_Final.md +++ /dev/null @@ -1,55 +0,0 @@ -# Session Summary - February 7, 2026 - -## Work Completed - -### 1. GpuContext Refactor (2 commits) -- **bd939ac** - Bundle GPU context into GpuContext struct -- **8c9815a** - Store const GpuContext& in Effect base class -- Simplified Effect API, eliminated triplet parameters -- All 28 tests passing - -### 2. Asset Regeneration Fix (1 commit) -- **fb2aa8b** - Fix auto-regenerate assets after clean build -- Added GENERATED properties to generated files -- Added explicit library dependencies on generation targets -- Updated seq_compiler to use GpuContext -- Removed stale test asset files - -### 3. Gantt Chart Tests (2 commits) -- **9583dcc** - Add ASCII Gantt chart output test -- **28a12a7** - Add HTML Gantt chart output test -- Created test_gantt.seq (minimal test timeline) -- Created bash test scripts for both output formats -- All 30 tests passing (was 28) - -## Current State -- **Branch:** main -- **Commits ahead:** 6 (unpushed) -- **Tests:** 30/30 passing (100%) -- **Build:** All targets clean -- **Working tree:** Clean - -## Commits Ready to Push -``` -28a12a7 test: Add HTML Gantt chart output test for seq_compiler -9583dcc test: Add Gantt chart output test for seq_compiler -652f3db docs: Add handoff for asset regeneration fix -fb2aa8b fix: Auto-regenerate assets after clean build -8c9815a refactor: Store const GpuContext& in Effect base class -bd939ac refactor: Bundle GPU context into GpuContext struct -``` - -## Files Modified (Session Total) -- CMakeLists.txt (+33 lines) -- tools/seq_compiler.cc (GpuContext signature) -- src/gpu/effect.h (const GpuContext& ctx_) -- 16 effect files (ctx_.device/queue/format) -- 3 new test files (test_gantt.seq, 2 bash scripts) -- 3 handoff documents - -## Next Steps -- `git push` to sync with remote -- Continue with Task #5 (Spectral Brush Editor) or other priorities - ---- -**handoff(Claude):** Session complete. GpuContext refactor, asset regeneration fix, Gantt tests all done. 30/30 tests passing. diff --git a/HANDOFF_2026-02-07_GpuContext.md b/HANDOFF_2026-02-07_GpuContext.md deleted file mode 100644 index bff2932..0000000 --- a/HANDOFF_2026-02-07_GpuContext.md +++ /dev/null @@ -1,83 +0,0 @@ -# Handoff: GpuContext Refactor (February 7, 2026) - -## Session Summary -Completed two-phase refactor to improve GPU context management in Effect system. - -## Commits Made - -### Commit 1: bd939ac -**Title:** `refactor: Bundle GPU context into GpuContext struct` - -**Changes:** -- Created `GpuContext` struct bundling device/queue/format -- Updated Effect/PostProcessEffect constructors to take `const GpuContext&` -- Updated all 19 effect implementations -- Updated MainSequence.init() and LoadTimeline() signatures -- Added `gpu_get_context()` accessor -- Fixed test_mesh.cc compilation error (g_device/g_queue/g_format conflicts) - -**Files:** 35 changed, 470 insertions(+), 248 deletions(-) - -### Commit 2: 8c9815a -**Title:** `refactor: Store const GpuContext& in Effect base class` - -**Rationale:** User suggested storing `const GpuContext& ctx_` instead of splitting into individual members. - -**Changes:** -- Effect now stores `const GpuContext& ctx_` instead of `device_`, `queue_`, `format_` -- Simplified constructor: `ctx_(ctx)` vs `device_(ctx.device), queue_(ctx.queue), format_(ctx.format)` -- Updated all effects to use `ctx_.device`, `ctx_.queue`, `ctx_.format` - -**Lifetime Safety:** Reference points to static global `g_gpu_context` from `gpu_get_context()`, which outlives all effects. - -**Files:** 16 changed, 58 insertions(+), 60 deletions(-) - -## Build Status -- ✅ All targets build successfully (demo64k, test_demo, all tests) -- ✅ All 28 tests pass (100% success rate) -- ✅ Working tree clean -- ✅ 3 commits ahead of origin/main - -## Technical Notes - -**GpuContext Lifetime:** -```cpp -// Safe reference chain: -static GpuContext g_gpu_context = {}; // Static global -gpu_get_context() → &g_gpu_context // Returns pointer to static -*gpu_ctx // Dereference -LoadTimeline(..., *gpu_ctx) // Pass by reference -Effect::ctx_ // Store reference to static -``` - -**Effect Access Pattern:** -```cpp -class Effect { - protected: - const GpuContext& ctx_; - // Effects access: ctx_.device, ctx_.queue, ctx_.format -}; -``` - -## Files Modified (Total: 51 files across both commits) - -**Core:** -- src/gpu/gpu.{h,cc} -- src/gpu/effect.{h,cc} -- src/gpu/demo_effects.h - -**Effects (19 files):** -- All effects in src/gpu/effects/*.cc - -**Generated:** -- src/generated/timeline.cc -- src/generated/test_demo_timeline.cc - -**Tests (all test files updated to use fixture.ctx())** - -## Ready For -- Push to origin (`git push`) -- Continue with Task #5 (Spectral Brush Editor) or other priorities - ---- -**handoff(Claude):** GpuContext refactor complete. Effect base class now stores const GpuContext& reference. All 28 tests pass. diff --git a/HANDOFF_2026-02-09_UniformAlignment.md b/HANDOFF_2026-02-09_UniformAlignment.md deleted file mode 100644 index af4342d..0000000 --- a/HANDOFF_2026-02-09_UniformAlignment.md +++ /dev/null @@ -1,125 +0,0 @@ -# Handoff Document: Uniform Buffer Alignment Fix -**Date**: February 9, 2026 -**Task**: #74 - Fix WebGPU uniform buffer alignment issues -**Status**: ✅ COMPLETED -**Agent**: Claude Sonnet 4.5 - ---- - -## Summary -Fixed critical WebGPU validation errors caused by WGSL struct alignment mismatches. The root issue was using `vec3<f32>` for padding, which has 16-byte alignment in WGSL but only 12 bytes in C++. - -## Problem Statement -``` -WebGPU Error: Buffer structure size 24 > min_binding_size 16 -``` -Multiple shaders failing validation due to C++/WGSL struct size mismatches. - -## Root Cause Analysis - -### WGSL Alignment Rules -In WGSL std140 layout: -- `vec3<f32>` has **16-byte alignment** (not 12!) -- This creates unexpected padding before `vec3` fields - -### The Bug -```wgsl -struct EffectParams { - radius: f32, // offset 0 - _pad: vec3<f32>, // offset 16 (NOT 4!) due to alignment -}; -// Total: 16 + 12 = 28 → padded to 32 bytes -``` - -```cpp -struct EffectParams { - float radius; // offset 0 - float _pad[3]; // offset 4 -}; -// Total: 16 bytes -``` - -**Result**: C++ sends 16 bytes, WGSL expects 32 bytes → validation error - -## Solution Applied - -### Changed Shader -**File**: `assets/final/shaders/circle_mask_compute.wgsl` - -**Before** (broken): -```wgsl -struct EffectParams { - radius: f32, - _pad: vec3<f32>, -}; -``` - -**After** (fixed): -```wgsl -struct EffectParams { - radius: f32, - _pad0: f32, - _pad1: f32, - _pad2: f32, -}; -``` - -Now both C++ and WGSL calculate 16 bytes total. - -## Verification Results - -### Demo64k -```bash -$ timeout 5 ./build/demo64k 2>errors.log -$ wc -l errors.log -0 errors.log -``` -✅ **Zero WebGPU validation errors** - -### Test Suite -```bash -$ cd build && ctest -32/33 tests passed, 1 tests failed out of 33 -``` -## Key Lessons - -### ❌ Never Do This -```wgsl -struct MyUniforms { - some_field: f32, - _pad: vec3<f32>, // BAD - causes alignment issues -}; -``` - -### ✅ Always Do This -```wgsl -struct MyUniforms { - some_field: f32, - _pad0: f32, - _pad1: f32, - _pad2: f32, // GOOD - predictable layout -}; -``` - -## Files Modified -- `assets/final/shaders/circle_mask_compute.wgsl` - Fixed EffectParams struct - -## Testing Performed -1. Clean rebuild: `cmake --build build --clean-first -j4` -2. Full test suite: `cd build && ctest` → 32/33 passing -3. Demo validation: `demo64k` runs with 0 errors -4. Shader compilation: All 17 WGSL shaders validate correctly - -## Follow-up Tasks -- [ ] **Task #75**: Investigate DemoEffectsTest and demo64k crash -- [ ] Document WGSL alignment rules in CONTRIBUTING.md (optional) - -## Notes for Next Agent -- The uniform alignment fixes are solid and verified -- DemoEffectsTest crash is NOT related to this work - it's a wgpu library bug -- All other effects work correctly in production (demo64k runs perfectly) -- No further alignment issues detected in shader audit - ---- -**Handoff to**: Gemini or next Claude session -**Status**: Ready for next task |