diff options
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/FILE_HIERARCHY_CLEANUP_2026-02-13.md | 202 | ||||
| -rw-r--r-- | doc/SHADER_REUSE_INVESTIGATION.md | 21 | ||||
| -rw-r--r-- | doc/WORKSPACE_SYSTEM.md | 60 |
3 files changed, 265 insertions, 18 deletions
diff --git a/doc/FILE_HIERARCHY_CLEANUP_2026-02-13.md b/doc/FILE_HIERARCHY_CLEANUP_2026-02-13.md new file mode 100644 index 0000000..8af5efd --- /dev/null +++ b/doc/FILE_HIERARCHY_CLEANUP_2026-02-13.md @@ -0,0 +1,202 @@ +# File Hierarchy Cleanup - February 13, 2026 + +## Summary + +Comprehensive reorganization of project file structure for improved maintainability and code reuse. + +--- + +## Changes Implemented + +### 1. Application Entry Points → `src/app/` + +**Before:** +``` +src/ + main.cc + stub_main.cc + test_demo.cc +``` + +**After:** +``` +src/app/ + main.cc + stub_main.cc + test_demo.cc +``` + +**Impact:** Cleaner src/ directory, separates application code from libraries. + +--- + +### 2. Workspace Reorganization + +**Before:** +``` +workspaces/main/ + assets/music/*.spec + shaders/*.wgsl + obj/*.obj + +assets/ + demo.seq + music.track + originals/ + common/ + final/ +``` + +**After:** +``` +workspaces/{main,test}/ + music/ # Audio samples (.spec) + weights/ # CNN binary weights (.bin) + obj/ # 3D models (.obj) + shaders/ # Workspace-specific WGSL only + +common/ + shaders/ # Shared WGSL utilities + math/ + render/ + compute/ + +tools/ + originals/ # Source audio files + test_demo.seq + test_demo.track +``` + +**Removed:** +- `assets/` directory (legacy structure) +- `assets/common/` (replaced by `common/`) +- `assets/final/` (superseded by workspaces) +- `assets/originals/` → `tools/originals/` + +--- + +### 3. Shared Shader System + +**Problem:** 36 duplicate shader files across workspaces (byte-identical). + +**Solution:** Implemented Option 1 from `SHADER_REUSE_INVESTIGATION.md`. + +**Structure:** +``` +common/shaders/ + common_uniforms.wgsl + lighting.wgsl + passthrough.wgsl + ray_box.wgsl + ray_triangle.wgsl + sdf_primitives.wgsl + skybox.wgsl + math/ + common_utils.wgsl + noise.wgsl + sdf_shapes.wgsl + sdf_utils.wgsl + render/ + lighting_utils.wgsl + scene_query_bvh.wgsl + scene_query_linear.wgsl + shadows.wgsl + compute/ + gen_blend.wgsl + gen_grid.wgsl + gen_mask.wgsl + gen_noise.wgsl + gen_perlin.wgsl +``` + +**Reference in assets.txt:** +``` +SHADER_COMMON_UNIFORMS, NONE, ../../common/shaders/common_uniforms.wgsl +SHADER_MATH_NOISE, NONE, ../../common/shaders/math/noise.wgsl +``` + +**Asset Packer Enhancement:** +- Added `#include <filesystem>` for path normalization +- Implemented `lexically_normal()` to resolve `../../common/` references +- Cross-platform path handling for workspace-relative includes + +--- + +## Updated Files + +### Configuration +- `workspaces/main/workspace.cfg` - Updated asset_dirs and shader_dirs +- `workspaces/test/workspace.cfg` - Updated asset_dirs and shader_dirs +- `workspaces/main/assets.txt` - Common shader references +- `workspaces/test/assets.txt` - Common shader references + +### Build System +- `cmake/DemoExecutables.cmake` - src/app/ paths, test_demo paths +- `cmake/DemoCodegen.cmake` - Removed legacy fallback paths +- `cmake/Validation.cmake` - Workspace shader paths + +### Tools +- `tools/asset_packer.cc` - Filesystem path normalization +- `scripts/gen_spectrograms.sh` - tools/originals/ paths +- `scripts/train_cnn_v2_full.sh` - workspaces/main/weights/ paths +- `training/export_cnn_v2_weights.py` - workspaces/main/weights/ paths + +### Application +- `src/app/main.cc` - Hot-reload workspace paths + +--- + +## Metrics + +**File Reduction:** +- Removed 36 duplicate shader files +- Deleted legacy assets/ structure (~70 files) +- Net: ~100 files eliminated + +**Disk Space:** +- Common shaders: 20 files +- Per-workspace shaders: ~30-35 files +- Saved: ~36 shader duplicates + +**Workspace Structure:** +``` +workspaces/main/: 31 shaders (workspace-specific) +workspaces/test/: 19 shaders (workspace-specific) +common/: 20 shaders (shared) +Total unique: 70 shaders (vs 106 before) +``` + +--- + +## Benefits + +1. **Single Source of Truth:** Common shaders in one location +2. **No Duplication:** Bug fixes apply everywhere automatically +3. **Clear Separation:** Common vs workspace-specific code +4. **Size Optimization:** Important for 64k target +5. **Maintainability:** Easier to understand and modify +6. **Workspace Isolation:** Each workspace still self-contained for specific content + +--- + +## Migration Notes + +**For New Workspaces:** +1. Create `workspaces/new_workspace/` with subdirs: `music/`, `weights/`, `obj/`, `shaders/` +2. Reference common shaders: `../../common/shaders/...` +3. Add workspace-specific shaders to local `shaders/` +4. Update `workspace.cfg`: `asset_dirs = ["music/", "weights/", "obj/"]` + +**For Common Shader Changes:** +- Edit files in `common/shaders/` +- Changes apply to all workspaces immediately +- Run full build to verify all workspaces + +--- + +## Documentation Updated + +- `doc/WORKSPACE_SYSTEM.md` - New structure reflected +- `doc/SHADER_REUSE_INVESTIGATION.md` - Implementation status +- `doc/PROJECT_CONTEXT.md` - Current project state +- `doc/FILE_HIERARCHY_CLEANUP_2026-02-13.md` - This document diff --git a/doc/SHADER_REUSE_INVESTIGATION.md b/doc/SHADER_REUSE_INVESTIGATION.md index 4f83f1d..0eb36f9 100644 --- a/doc/SHADER_REUSE_INVESTIGATION.md +++ b/doc/SHADER_REUSE_INVESTIGATION.md @@ -1,6 +1,25 @@ # Shader Code Reuse Investigation -## Current State +## ✅ Implementation Status + +**Date:** February 13, 2026 +**Solution:** Option 1 - Shared Common Directory +**Status:** IMPLEMENTED + +**Results:** +- Created `common/shaders/` with 20 shared shader files +- Eliminated 36 duplicate files across workspaces +- Asset references use `../../common/shaders/...` +- Enhanced asset_packer with filesystem path normalization +- Build passes, all tests pass + +See `doc/FILE_HIERARCHY_CLEANUP_2026-02-13.md` for full details. + +--- + +## Investigation (Historical) + +### Current State ### Duplication Analysis - **36 duplicate shader files** between main and test workspaces diff --git a/doc/WORKSPACE_SYSTEM.md b/doc/WORKSPACE_SYSTEM.md index e8e2615..9362da6 100644 --- a/doc/WORKSPACE_SYSTEM.md +++ b/doc/WORKSPACE_SYSTEM.md @@ -46,7 +46,7 @@ This makes it hard to: 4. Shaders hard to categorize (shared vs demo-specific) 5. Adding new demos requires scattered changes -## Proposed Structure +## Current Structure (Implemented) ### Workspace Directory Layout @@ -57,10 +57,10 @@ This makes it hard to: timeline.seq # Visual effects music.track # Audio patterns assets.txt # Asset list - /assets/ - /music/*.spec # Demo-specific audio - /meshes/*.obj # Demo-specific meshes - /shaders/ # Demo-specific shaders + /music/*.spec # Audio samples + /weights/*.bin # CNN binary weights + /obj/*.obj # 3D models + /shaders/ # Workspace-specific shaders only custom_effect.wgsl /test/ # Test/validation demo @@ -68,23 +68,41 @@ This makes it hard to: timeline.seq music.track assets.txt - /assets/ + /music/ + /weights/ + /obj/ /shaders/ - /experiments/ # Experimental demos - /demo2024_revision/ - workspace.cfg - ... - -/assets/common/ # Shared resources +/common/ # Shared resources /shaders/ /math/ # Shared math utilities common_utils.wgsl - sdf.wgsl - /common_uniforms/ # Shared uniforms - common.wgsl - /audio/ - standard_drums.spec # Shared samples + noise.wgsl + sdf_shapes.wgsl + sdf_utils.wgsl + /render/ # Shared rendering helpers + lighting_utils.wgsl + scene_query_bvh.wgsl + scene_query_linear.wgsl + shadows.wgsl + /compute/ # Shared compute shaders + gen_blend.wgsl + gen_grid.wgsl + gen_mask.wgsl + gen_noise.wgsl + gen_perlin.wgsl + common_uniforms.wgsl + lighting.wgsl + passthrough.wgsl + ray_box.wgsl + ray_triangle.wgsl + sdf_primitives.wgsl + skybox.wgsl + +/tools/ + originals/ # Source audio files (.wav, .aif) + test_demo.seq # Test demo timeline + test_demo.track # Test demo music ``` ### Workspace Configuration @@ -97,6 +115,14 @@ description = "Production 64k demo" version = "1.0" [build] +target = "demo64k" +timeline = "timeline.seq" +music = "music.track" +assets = "assets.txt" +asset_dirs = ["music/", "weights/", "obj/"] +shader_dirs = ["shaders/"] + +[build] # Output binary name target = "demo64k" |