From 65f7d74cbd4b34640dda73100c45f25ad468349d Mon Sep 17 00:00:00 2001 From: skal Date: Fri, 13 Feb 2026 08:36:09 +0100 Subject: Documentation: Update for file hierarchy reorganization Updated docs to reflect February 13, 2026 changes: - doc/FILE_HIERARCHY_CLEANUP_2026-02-13.md: Complete summary - doc/WORKSPACE_SYSTEM.md: Current structure, workspace.cfg format - doc/SHADER_REUSE_INVESTIGATION.md: Implementation status - PROJECT_CONTEXT.md: Workspace and shader system updates Key changes documented: - src/app/ application structure - workspaces/{music,weights,obj,shaders}/ layout - common/shaders/ shared shader system - Eliminated 36 duplicate shaders - Asset packer path normalization handoff(Claude): Documentation updated for hierarchy cleanup --- doc/FILE_HIERARCHY_CLEANUP_2026-02-13.md | 202 +++++++++++++++++++++++++++++++ 1 file changed, 202 insertions(+) create mode 100644 doc/FILE_HIERARCHY_CLEANUP_2026-02-13.md (limited to 'doc/FILE_HIERARCHY_CLEANUP_2026-02-13.md') 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 ` 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 -- cgit v1.2.3