diff options
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/COMPLETED.md | 5 | ||||
| -rw-r--r-- | doc/WORKSPACE_SYSTEM.md | 582 | ||||
| -rw-r--r-- | doc/archive/GEOM_BUFFER.md (renamed from doc/GEOM_BUFFER.md) | 0 | ||||
| -rw-r--r-- | doc/archive/GPU_PROCEDURAL_PHASE4.md (renamed from doc/GPU_PROCEDURAL_PHASE4.md) | 0 | ||||
| -rw-r--r-- | doc/archive/SHADER_REUSE_INVESTIGATION.md (renamed from doc/SHADER_REUSE_INVESTIGATION.md) | 0 | ||||
| -rw-r--r-- | doc/archive/SPECTRAL_BRUSH_EDITOR.md (renamed from doc/SPECTRAL_BRUSH_EDITOR.md) | 0 | ||||
| -rw-r--r-- | doc/archive/WORKSPACE_SYSTEM.md | 576 |
7 files changed, 602 insertions, 561 deletions
diff --git a/doc/COMPLETED.md b/doc/COMPLETED.md index 9299a93..42e4bc6 100644 --- a/doc/COMPLETED.md +++ b/doc/COMPLETED.md @@ -11,6 +11,11 @@ Completed task archive. See `doc/archive/` for detailed historical documents. - AUDIO_LIFECYCLE_REFACTOR.md, AUDIO_TIMING_ARCHITECTURE.md - BUILD_OPTIMIZATION_PROPOSAL.md, BUILD_OPTIMIZATION_PROPOSAL_V2.md - PLATFORM_ANALYSIS.md, SHADER_PARAMETRIZATION_PLAN.md +- SHADER_REUSE_INVESTIGATION.md (shared `src/shaders/` approach implemented Feb 2026) +- GPU_PROCEDURAL_PHASE4.md (multi-input composite shaders with sampler cache, ~830 bytes) +- GEOM_BUFFER.md (G-buffer ideation, not yet implemented — see BACKLOG) +- WORKSPACE_SYSTEM.md (full design; compacted to operational reference Feb 2026) +- SPECTRAL_BRUSH_EDITOR.md (v1 DCT approach; superseded by MQ-based v2 in SPECTRAL_BRUSH_2.md) **Handoffs & Summaries:** - HANDOFF.md, HANDOFF_2026-02-04.md, HANDOFF_2026-02-08.md, HANDOFF_CLAUDE.md diff --git a/doc/WORKSPACE_SYSTEM.md b/doc/WORKSPACE_SYSTEM.md index 6b4319d..f0981fd 100644 --- a/doc/WORKSPACE_SYSTEM.md +++ b/doc/WORKSPACE_SYSTEM.md @@ -1,576 +1,36 @@ -# Workspace System (Task #77) [COMPLETED] +# Workspace System -## Status +**Status:** ✅ Complete (Feb 9, 2026) -**Implemented:** Feb 9, 2026 +Self-contained demo workspaces. Select with `cmake -B build -DDEMO_WORKSPACE=<name>`. -Workspace system is now active. Use `cmake -B build -DDEMO_WORKSPACE=<name>` to select workspace. +## Directory Layout -## Overview - -Self-contained demo workspaces for parallel development and clean content separation. - -**Motivation:** Current structure scatters demo content across multiple locations: -- `assets/demo.seq` - Timeline -- `assets/music.track` - Audio -- `assets/final/demo_assets.txt` - Asset list -- `assets/final/music/*.spec` - Audio samples -- `assets/shaders/*.wgsl` - Shaders (some demo-specific, some shared) - -This makes it hard to: -- Work on multiple demos simultaneously -- Understand what files belong to which demo -- Share common resources cleanly -- Onboard new developers - -## Problem Statement - -**Current structure (flat):** ``` -/assets/ - demo.seq # Main demo timeline - music.track # Main demo music - test_demo.seq # Test demo timeline - test_demo.track # Test demo music - /final/ - demo_assets.txt # Main demo assets - /music/*.spec # Audio samples (mixed usage) - /shaders/ - *.wgsl # Mixed: common + demo-specific -``` - -**Issues:** -1. No clear ownership of files -2. Can't easily switch between demos -3. Assets intermingled (demo vs test) -4. Shaders hard to categorize (shared vs demo-specific) -5. Adding new demos requires scattered changes - -## Current Structure (Implemented) - -### Workspace Directory Layout - -``` -/workspaces/ - /main/ # Main production demo - workspace.cfg # Workspace metadata - timeline.seq # Visual effects - music.track # Audio patterns - assets.txt # Asset list - /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 - workspace.cfg - timeline.seq - music.track - assets.txt - /music/ - /weights/ - /obj/ - /shaders/ - -/common/ # Shared resources - /shaders/ - /math/ # Shared math utilities - common_utils.wgsl - 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) -``` - -### Workspace Configuration - -**`workspace.cfg` format:** -```ini -[workspace] -name = "Main Demo" -description = "Production 64k demo" -version = "1.0" +workspaces/ + main/ # Main production demo + timeline.seq # Visual effects + music.track # Audio patterns + assets.txt # Asset list + music/*.spec # Audio samples + weights/*.bin # CNN weights + obj/*.obj # 3D models + shaders/ # Workspace-specific shaders only + test/ # Test demo (same structure) -[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" - -# Include paths (relative to workspace root) -timeline = "timeline.seq" -music = "music.track" -assets = "assets.txt" - -# Asset directories -asset_dirs = ["assets/", "../common/audio/"] - -# Shader directories (order matters: workspace-specific first) -shader_dirs = ["shaders/", "../src/shaders/"] - -[options] -# Default resolution -width = 1280 -height = 720 - -# Duration (seconds, -1 = auto-detect) -duration = -1 - -# BPM for timeline -bpm = 120 +src/shaders/ # Shared common shaders (math/, render/, compute/) ``` -## Architecture - -### Build System Integration - -**CMakeLists.txt changes:** -```cmake -# Select active workspace (default: main) -set(DEMO_WORKSPACE "main" CACHE STRING "Active workspace") +## Usage -# Parse workspace config -set(WORKSPACE_DIR "${CMAKE_SOURCE_DIR}/workspaces/${DEMO_WORKSPACE}") -set(WORKSPACE_CFG "${WORKSPACE_DIR}/workspace.cfg") - -# Read config and set variables -parse_workspace_config(${WORKSPACE_CFG} - TIMELINE_PATH - MUSIC_PATH - ASSETS_PATH - ASSET_DIRS - SHADER_DIRS - TARGET_NAME -) - -# Generate assets from workspace -add_custom_command( - OUTPUT ${GEN_ASSETS_H} - COMMAND asset_packer ${WORKSPACE_DIR}/${ASSETS_PATH} ... - DEPENDS ${WORKSPACE_DIR}/${ASSETS_PATH} -) - -# Generate timeline from workspace -add_custom_command( - OUTPUT ${GEN_TIMELINE_CC} - COMMAND seq_compiler ${WORKSPACE_DIR}/${TIMELINE_PATH} ... - DEPENDS ${WORKSPACE_DIR}/${TIMELINE_PATH} -) - -# Add shader include paths from workspace -foreach(SHADER_DIR ${SHADER_DIRS}) - list(APPEND SHADER_INCLUDE_DIRS "${WORKSPACE_DIR}/${SHADER_DIR}") -endforeach() -``` - -**Building specific workspace:** ```bash -# Default (main workspace) -cmake -S . -B build -cmake --build build -j4 - -# Specific workspace -cmake -S . -B build_test -DDEMO_WORKSPACE=test -cmake --build build_test -j4 - -# Experimental workspace -cmake -S . -B build_exp -DDEMO_WORKSPACE=experiments/demo2024_revision -cmake --build build_exp -j4 -``` - -### Asset Packer Changes - -**Support workspace-relative paths:** -```cpp -// asset_packer.cc -void PackerContext::resolve_asset_path(const char* rel_path) { - // Try workspace-local first - std::string workspace_path = workspace_dir + "/" + rel_path; - if (file_exists(workspace_path)) { - return workspace_path; - } - - // Try common assets - std::string common_path = "assets/common/" + rel_path; - if (file_exists(common_path)) { - return common_path; - } - - error("Asset not found: %s", rel_path); -} -``` - -### Shader Composer Changes - -**Support multiple include paths:** -```cpp -// shader_composer.cc -class ShaderComposer { - std::vector<std::string> include_paths_; - - void add_include_path(const char* path) { - include_paths_.push_back(path); - } - - std::string resolve_include(const char* filename) { - for (const auto& base : include_paths_) { - std::string full = base + "/" + filename; - if (file_exists(full)) { - return full; - } - } - error("Shader include not found: %s", filename); - } -}; -``` - -**Shader includes with search paths:** -```wgsl -// workspace-specific shader -#include "custom_uniforms.wgsl" // From workspaces/main/shaders/ -#include "math/common_utils.wgsl" // From src/shaders/ -``` - -### CLI Tool - -**`scripts/workspace.sh` - Workspace management:** -```bash -#!/bin/bash -# workspace.sh - Manage demo workspaces - -case "$1" in - list) - # List all workspaces - ls -1 workspaces/ - ;; - - create) - # Create new workspace from template - NAME=$2 - mkdir -p workspaces/$NAME/{assets,shaders} - cp templates/workspace.cfg workspaces/$NAME/ - echo "Created workspace: $NAME" - ;; - - build) - # Build specific workspace - NAME=$2 - cmake -S . -B build_$NAME -DDEMO_WORKSPACE=$NAME - cmake --build build_$NAME -j4 - ;; - - info) - # Show workspace details - NAME=$2 - cat workspaces/$NAME/workspace.cfg - ;; -esac -``` - -**Usage:** -```bash -./scripts/workspace.sh list -./scripts/workspace.sh create my_demo -./scripts/workspace.sh build main -./scripts/workspace.sh info test -``` - -## Implementation Plan - -### Phase 1: Create Workspace Structure - -**1.1 Create directory tree:** -```bash -mkdir -p workspaces/{main,test}/assets -mkdir -p workspaces/{main,test}/shaders -mkdir -p assets/common/{shaders,audio} -``` - -**1.2 Move existing files:** -```bash -# Main demo -mv assets/demo.seq workspaces/main/timeline.seq -mv assets/music.track workspaces/main/music.track -mv assets/final/demo_assets.txt workspaces/main/assets.txt -mv assets/final/music workspaces/main/assets/ +# Main demo (default) +cmake -S . -B build -DDEMO_WORKSPACE=main && cmake --build build -j4 # Test demo -mv assets/test_demo.seq workspaces/test/timeline.seq -mv assets/test_demo.track workspaces/test/music.track -cp assets/final/demo_assets.txt workspaces/test/assets.txt # Or create minimal version - -# Common shaders -mv assets/shaders/math assets/common/shaders/ -mv assets/shaders/common_uniforms assets/common/shaders/ -``` - -**1.3 Create workspace configs:** -```bash -# Generate workspace.cfg for main and test -# See format above -``` - -### Phase 2: Update Build System - -**2.1 Add workspace parsing:** -- Create `cmake/ParseWorkspace.cmake` -- Parse INI-style config -- Set CMake variables - -**2.2 Update CMakeLists.txt:** -- Add `DEMO_WORKSPACE` option -- Use workspace paths for assets/timeline/music -- Pass shader include paths to ShaderComposer - -**2.3 Update compiler tools:** -- `asset_packer`: Accept workspace root dir -- `seq_compiler`: Accept workspace root dir -- `tracker_compiler`: Accept workspace root dir - -### Phase 3: Update Code - -**3.1 ShaderComposer:** -- Add multi-path include resolution -- Search workspace shaders first, then common - -**3.2 Asset loading:** -- Update paths to match new structure -- Ensure backward compatibility during transition - -**3.3 Generated code:** -- Verify generated assets.h/timeline.cc still work -- Update include paths if needed - -### Phase 4: Documentation & Tools - -**4.1 Update docs:** -- README.md: Explain workspace structure -- HOWTO.md: Document workspace build commands -- CONTRIBUTING.md: Workspace best practices - -**4.2 Create helper scripts:** -- `scripts/workspace.sh`: Workspace management CLI -- `templates/workspace.cfg`: Template for new workspaces - -**4.3 Update CI:** -- Build both main and test workspaces -- Validate workspace isolation - -### Phase 5: Migration & Validation - -**5.1 Test builds:** -```bash -# Build both workspaces -cmake -S . -B build_main -DDEMO_WORKSPACE=main -cmake --build build_main -j4 - -cmake -S . -B build_test -DDEMO_WORKSPACE=test -cmake --build build_test -j4 - -# Run tests -cd build_main && ctest -cd build_test && ctest +cmake -S . -B build_test -DDEMO_WORKSPACE=test && cmake --build build_test -j4 ``` -**5.2 Verify isolation:** -- Modify workspace-specific shader → only that workspace affected -- Modify common shader → both workspaces affected - -**5.3 Update .gitignore:** -``` -/build_*/ -/workspaces/*/generated/ -``` - -## Benefits - -### 1. Clear Ownership -Each workspace is self-contained: -```bash -workspaces/main/ -├── workspace.cfg # Configuration -├── timeline.seq # Timeline -├── music.track # Music -├── assets.txt # Assets -├── assets/ # Local assets -└── shaders/ # Local shaders -``` - -### 2. Parallel Development -Multiple developers can work on different demos without conflicts: -```bash -# Developer A: Main demo -cd workspaces/main -vim timeline.seq - -# Developer B: Experimental demo -cd workspaces/experiments/christmas_demo -vim timeline.seq -``` - -### 3. Easy Switching -```bash -# Build main demo -cmake -B build -DDEMO_WORKSPACE=main -./build/demo64k - -# Build test demo -cmake -B build -DDEMO_WORKSPACE=test -./build/test_demo -``` - -### 4. Clean Sharing -Common resources in one place: -``` -assets/common/ -├── shaders/ -│ ├── math/ # Shared by all -│ └── common_uniforms/ -└── audio/ - └── standard_drums.spec -``` - -### 5. Scalability -Easy to add new demos: -```bash -./scripts/workspace.sh create party2025 -cd workspaces/party2025 -# Start developing... -``` - -## Migration Path - -### Backward Compatibility - -During transition, support both structures: -```cmake -if(EXISTS "${CMAKE_SOURCE_DIR}/workspaces/${DEMO_WORKSPACE}") - # New workspace structure - set(USING_WORKSPACES TRUE) -else() - # Legacy flat structure - set(USING_WORKSPACES FALSE) -endif() -``` - -### Gradual Migration - -1. **Phase 1:** Create workspace structure alongside existing -2. **Phase 2:** Update build system to support both -3. **Phase 3:** Move files to workspaces -4. **Phase 4:** Remove legacy paths -5. **Phase 5:** Update all documentation - -**Timeline:** 1-2 weeks for full migration - -## Trade-offs - -### Pros -- Clear project organization -- Parallel demo development -- Clean resource sharing -- Better onboarding for new devs -- Scales to many demos - -### Cons -- Initial migration effort -- Build system complexity increases -- More directories to navigate -- Learning curve for contributors - -### Alternative Approaches - -**1. Monorepo with subprojects:** -- Separate CMake projects per demo -- More isolated but harder to share code - -**2. Configuration files only:** -- Keep flat structure, use config to select files -- Less clear, harder to understand ownership - -**3. Git branches per demo:** -- Each demo is a branch -- Conflicts when merging shared code - -**Chosen:** Workspace system (best balance) - -## Implementation Effort - -**Estimated time: 12-16 hours** - -- Phase 1: Create structure (2-3 hours) -- Phase 2: Build system (4-5 hours) -- Phase 3: Code updates (3-4 hours) -- Phase 4: Documentation (2-3 hours) -- Phase 5: Validation (1-2 hours) - -**Priority:** Medium (improves workflow, not blocking) - -## Success Criteria - -1. Both `main` and `test` workspaces build successfully -2. Switching workspaces requires only CMake flag change -3. Workspace-specific changes don't affect other workspaces -4. Common shader changes affect all workspaces -5. New workspace creation takes < 5 minutes -6. All tests pass for both workspaces -7. Documentation clear for new contributors - -## Related Files - -**New files:** -- `workspaces/main/workspace.cfg` - Main demo config -- `workspaces/test/workspace.cfg` - Test demo config -- `cmake/ParseWorkspace.cmake` - Config parser -- `scripts/workspace.sh` - Workspace CLI tool -- `templates/workspace.cfg` - New workspace template - -**Modified files:** -- `CMakeLists.txt` - Workspace support -- `tools/asset_packer.cc` - Multi-path resolution -- `src/gpu/shader_composer.cc` - Multi-path includes -- `README.md` - Workspace documentation -- `doc/HOWTO.md` - Build commands -- `doc/CONTRIBUTING.md` - Workspace guidelines - -**Moved files:** -- `assets/demo.seq` → `workspaces/main/timeline.seq` -- `assets/music.track` → `workspaces/main/music.track` -- `assets/final/demo_assets.txt` → `workspaces/main/assets.txt` -- `assets/test_demo.*` → `workspaces/test/` -- `assets/shaders/math/` → `assets/common/shaders/math/` - -## Notes +Shared shaders in `src/shaders/` are referenced as `../../src/shaders/...` in `assets.txt`. -- This is a **structural refactor**, not a feature -- No runtime behavior changes -- Enables future scalability -- Makes project more professional -- Good foundation for demoscene releases (multiple demos per repo) +See `doc/archive/WORKSPACE_SYSTEM.md` for full design and implementation history. diff --git a/doc/GEOM_BUFFER.md b/doc/archive/GEOM_BUFFER.md index 0188125..0188125 100644 --- a/doc/GEOM_BUFFER.md +++ b/doc/archive/GEOM_BUFFER.md diff --git a/doc/GPU_PROCEDURAL_PHASE4.md b/doc/archive/GPU_PROCEDURAL_PHASE4.md index 4cfc271..4cfc271 100644 --- a/doc/GPU_PROCEDURAL_PHASE4.md +++ b/doc/archive/GPU_PROCEDURAL_PHASE4.md diff --git a/doc/SHADER_REUSE_INVESTIGATION.md b/doc/archive/SHADER_REUSE_INVESTIGATION.md index e840126..e840126 100644 --- a/doc/SHADER_REUSE_INVESTIGATION.md +++ b/doc/archive/SHADER_REUSE_INVESTIGATION.md diff --git a/doc/SPECTRAL_BRUSH_EDITOR.md b/doc/archive/SPECTRAL_BRUSH_EDITOR.md index a7d0e3a..a7d0e3a 100644 --- a/doc/SPECTRAL_BRUSH_EDITOR.md +++ b/doc/archive/SPECTRAL_BRUSH_EDITOR.md diff --git a/doc/archive/WORKSPACE_SYSTEM.md b/doc/archive/WORKSPACE_SYSTEM.md new file mode 100644 index 0000000..6b4319d --- /dev/null +++ b/doc/archive/WORKSPACE_SYSTEM.md @@ -0,0 +1,576 @@ +# Workspace System (Task #77) [COMPLETED] + +## Status + +**Implemented:** Feb 9, 2026 + +Workspace system is now active. Use `cmake -B build -DDEMO_WORKSPACE=<name>` to select workspace. + +## Overview + +Self-contained demo workspaces for parallel development and clean content separation. + +**Motivation:** Current structure scatters demo content across multiple locations: +- `assets/demo.seq` - Timeline +- `assets/music.track` - Audio +- `assets/final/demo_assets.txt` - Asset list +- `assets/final/music/*.spec` - Audio samples +- `assets/shaders/*.wgsl` - Shaders (some demo-specific, some shared) + +This makes it hard to: +- Work on multiple demos simultaneously +- Understand what files belong to which demo +- Share common resources cleanly +- Onboard new developers + +## Problem Statement + +**Current structure (flat):** +``` +/assets/ + demo.seq # Main demo timeline + music.track # Main demo music + test_demo.seq # Test demo timeline + test_demo.track # Test demo music + /final/ + demo_assets.txt # Main demo assets + /music/*.spec # Audio samples (mixed usage) + /shaders/ + *.wgsl # Mixed: common + demo-specific +``` + +**Issues:** +1. No clear ownership of files +2. Can't easily switch between demos +3. Assets intermingled (demo vs test) +4. Shaders hard to categorize (shared vs demo-specific) +5. Adding new demos requires scattered changes + +## Current Structure (Implemented) + +### Workspace Directory Layout + +``` +/workspaces/ + /main/ # Main production demo + workspace.cfg # Workspace metadata + timeline.seq # Visual effects + music.track # Audio patterns + assets.txt # Asset list + /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 + workspace.cfg + timeline.seq + music.track + assets.txt + /music/ + /weights/ + /obj/ + /shaders/ + +/common/ # Shared resources + /shaders/ + /math/ # Shared math utilities + common_utils.wgsl + 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) +``` + +### Workspace Configuration + +**`workspace.cfg` format:** +```ini +[workspace] +name = "Main Demo" +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" + +# Include paths (relative to workspace root) +timeline = "timeline.seq" +music = "music.track" +assets = "assets.txt" + +# Asset directories +asset_dirs = ["assets/", "../common/audio/"] + +# Shader directories (order matters: workspace-specific first) +shader_dirs = ["shaders/", "../src/shaders/"] + +[options] +# Default resolution +width = 1280 +height = 720 + +# Duration (seconds, -1 = auto-detect) +duration = -1 + +# BPM for timeline +bpm = 120 +``` + +## Architecture + +### Build System Integration + +**CMakeLists.txt changes:** +```cmake +# Select active workspace (default: main) +set(DEMO_WORKSPACE "main" CACHE STRING "Active workspace") + +# Parse workspace config +set(WORKSPACE_DIR "${CMAKE_SOURCE_DIR}/workspaces/${DEMO_WORKSPACE}") +set(WORKSPACE_CFG "${WORKSPACE_DIR}/workspace.cfg") + +# Read config and set variables +parse_workspace_config(${WORKSPACE_CFG} + TIMELINE_PATH + MUSIC_PATH + ASSETS_PATH + ASSET_DIRS + SHADER_DIRS + TARGET_NAME +) + +# Generate assets from workspace +add_custom_command( + OUTPUT ${GEN_ASSETS_H} + COMMAND asset_packer ${WORKSPACE_DIR}/${ASSETS_PATH} ... + DEPENDS ${WORKSPACE_DIR}/${ASSETS_PATH} +) + +# Generate timeline from workspace +add_custom_command( + OUTPUT ${GEN_TIMELINE_CC} + COMMAND seq_compiler ${WORKSPACE_DIR}/${TIMELINE_PATH} ... + DEPENDS ${WORKSPACE_DIR}/${TIMELINE_PATH} +) + +# Add shader include paths from workspace +foreach(SHADER_DIR ${SHADER_DIRS}) + list(APPEND SHADER_INCLUDE_DIRS "${WORKSPACE_DIR}/${SHADER_DIR}") +endforeach() +``` + +**Building specific workspace:** +```bash +# Default (main workspace) +cmake -S . -B build +cmake --build build -j4 + +# Specific workspace +cmake -S . -B build_test -DDEMO_WORKSPACE=test +cmake --build build_test -j4 + +# Experimental workspace +cmake -S . -B build_exp -DDEMO_WORKSPACE=experiments/demo2024_revision +cmake --build build_exp -j4 +``` + +### Asset Packer Changes + +**Support workspace-relative paths:** +```cpp +// asset_packer.cc +void PackerContext::resolve_asset_path(const char* rel_path) { + // Try workspace-local first + std::string workspace_path = workspace_dir + "/" + rel_path; + if (file_exists(workspace_path)) { + return workspace_path; + } + + // Try common assets + std::string common_path = "assets/common/" + rel_path; + if (file_exists(common_path)) { + return common_path; + } + + error("Asset not found: %s", rel_path); +} +``` + +### Shader Composer Changes + +**Support multiple include paths:** +```cpp +// shader_composer.cc +class ShaderComposer { + std::vector<std::string> include_paths_; + + void add_include_path(const char* path) { + include_paths_.push_back(path); + } + + std::string resolve_include(const char* filename) { + for (const auto& base : include_paths_) { + std::string full = base + "/" + filename; + if (file_exists(full)) { + return full; + } + } + error("Shader include not found: %s", filename); + } +}; +``` + +**Shader includes with search paths:** +```wgsl +// workspace-specific shader +#include "custom_uniforms.wgsl" // From workspaces/main/shaders/ +#include "math/common_utils.wgsl" // From src/shaders/ +``` + +### CLI Tool + +**`scripts/workspace.sh` - Workspace management:** +```bash +#!/bin/bash +# workspace.sh - Manage demo workspaces + +case "$1" in + list) + # List all workspaces + ls -1 workspaces/ + ;; + + create) + # Create new workspace from template + NAME=$2 + mkdir -p workspaces/$NAME/{assets,shaders} + cp templates/workspace.cfg workspaces/$NAME/ + echo "Created workspace: $NAME" + ;; + + build) + # Build specific workspace + NAME=$2 + cmake -S . -B build_$NAME -DDEMO_WORKSPACE=$NAME + cmake --build build_$NAME -j4 + ;; + + info) + # Show workspace details + NAME=$2 + cat workspaces/$NAME/workspace.cfg + ;; +esac +``` + +**Usage:** +```bash +./scripts/workspace.sh list +./scripts/workspace.sh create my_demo +./scripts/workspace.sh build main +./scripts/workspace.sh info test +``` + +## Implementation Plan + +### Phase 1: Create Workspace Structure + +**1.1 Create directory tree:** +```bash +mkdir -p workspaces/{main,test}/assets +mkdir -p workspaces/{main,test}/shaders +mkdir -p assets/common/{shaders,audio} +``` + +**1.2 Move existing files:** +```bash +# Main demo +mv assets/demo.seq workspaces/main/timeline.seq +mv assets/music.track workspaces/main/music.track +mv assets/final/demo_assets.txt workspaces/main/assets.txt +mv assets/final/music workspaces/main/assets/ + +# Test demo +mv assets/test_demo.seq workspaces/test/timeline.seq +mv assets/test_demo.track workspaces/test/music.track +cp assets/final/demo_assets.txt workspaces/test/assets.txt # Or create minimal version + +# Common shaders +mv assets/shaders/math assets/common/shaders/ +mv assets/shaders/common_uniforms assets/common/shaders/ +``` + +**1.3 Create workspace configs:** +```bash +# Generate workspace.cfg for main and test +# See format above +``` + +### Phase 2: Update Build System + +**2.1 Add workspace parsing:** +- Create `cmake/ParseWorkspace.cmake` +- Parse INI-style config +- Set CMake variables + +**2.2 Update CMakeLists.txt:** +- Add `DEMO_WORKSPACE` option +- Use workspace paths for assets/timeline/music +- Pass shader include paths to ShaderComposer + +**2.3 Update compiler tools:** +- `asset_packer`: Accept workspace root dir +- `seq_compiler`: Accept workspace root dir +- `tracker_compiler`: Accept workspace root dir + +### Phase 3: Update Code + +**3.1 ShaderComposer:** +- Add multi-path include resolution +- Search workspace shaders first, then common + +**3.2 Asset loading:** +- Update paths to match new structure +- Ensure backward compatibility during transition + +**3.3 Generated code:** +- Verify generated assets.h/timeline.cc still work +- Update include paths if needed + +### Phase 4: Documentation & Tools + +**4.1 Update docs:** +- README.md: Explain workspace structure +- HOWTO.md: Document workspace build commands +- CONTRIBUTING.md: Workspace best practices + +**4.2 Create helper scripts:** +- `scripts/workspace.sh`: Workspace management CLI +- `templates/workspace.cfg`: Template for new workspaces + +**4.3 Update CI:** +- Build both main and test workspaces +- Validate workspace isolation + +### Phase 5: Migration & Validation + +**5.1 Test builds:** +```bash +# Build both workspaces +cmake -S . -B build_main -DDEMO_WORKSPACE=main +cmake --build build_main -j4 + +cmake -S . -B build_test -DDEMO_WORKSPACE=test +cmake --build build_test -j4 + +# Run tests +cd build_main && ctest +cd build_test && ctest +``` + +**5.2 Verify isolation:** +- Modify workspace-specific shader → only that workspace affected +- Modify common shader → both workspaces affected + +**5.3 Update .gitignore:** +``` +/build_*/ +/workspaces/*/generated/ +``` + +## Benefits + +### 1. Clear Ownership +Each workspace is self-contained: +```bash +workspaces/main/ +├── workspace.cfg # Configuration +├── timeline.seq # Timeline +├── music.track # Music +├── assets.txt # Assets +├── assets/ # Local assets +└── shaders/ # Local shaders +``` + +### 2. Parallel Development +Multiple developers can work on different demos without conflicts: +```bash +# Developer A: Main demo +cd workspaces/main +vim timeline.seq + +# Developer B: Experimental demo +cd workspaces/experiments/christmas_demo +vim timeline.seq +``` + +### 3. Easy Switching +```bash +# Build main demo +cmake -B build -DDEMO_WORKSPACE=main +./build/demo64k + +# Build test demo +cmake -B build -DDEMO_WORKSPACE=test +./build/test_demo +``` + +### 4. Clean Sharing +Common resources in one place: +``` +assets/common/ +├── shaders/ +│ ├── math/ # Shared by all +│ └── common_uniforms/ +└── audio/ + └── standard_drums.spec +``` + +### 5. Scalability +Easy to add new demos: +```bash +./scripts/workspace.sh create party2025 +cd workspaces/party2025 +# Start developing... +``` + +## Migration Path + +### Backward Compatibility + +During transition, support both structures: +```cmake +if(EXISTS "${CMAKE_SOURCE_DIR}/workspaces/${DEMO_WORKSPACE}") + # New workspace structure + set(USING_WORKSPACES TRUE) +else() + # Legacy flat structure + set(USING_WORKSPACES FALSE) +endif() +``` + +### Gradual Migration + +1. **Phase 1:** Create workspace structure alongside existing +2. **Phase 2:** Update build system to support both +3. **Phase 3:** Move files to workspaces +4. **Phase 4:** Remove legacy paths +5. **Phase 5:** Update all documentation + +**Timeline:** 1-2 weeks for full migration + +## Trade-offs + +### Pros +- Clear project organization +- Parallel demo development +- Clean resource sharing +- Better onboarding for new devs +- Scales to many demos + +### Cons +- Initial migration effort +- Build system complexity increases +- More directories to navigate +- Learning curve for contributors + +### Alternative Approaches + +**1. Monorepo with subprojects:** +- Separate CMake projects per demo +- More isolated but harder to share code + +**2. Configuration files only:** +- Keep flat structure, use config to select files +- Less clear, harder to understand ownership + +**3. Git branches per demo:** +- Each demo is a branch +- Conflicts when merging shared code + +**Chosen:** Workspace system (best balance) + +## Implementation Effort + +**Estimated time: 12-16 hours** + +- Phase 1: Create structure (2-3 hours) +- Phase 2: Build system (4-5 hours) +- Phase 3: Code updates (3-4 hours) +- Phase 4: Documentation (2-3 hours) +- Phase 5: Validation (1-2 hours) + +**Priority:** Medium (improves workflow, not blocking) + +## Success Criteria + +1. Both `main` and `test` workspaces build successfully +2. Switching workspaces requires only CMake flag change +3. Workspace-specific changes don't affect other workspaces +4. Common shader changes affect all workspaces +5. New workspace creation takes < 5 minutes +6. All tests pass for both workspaces +7. Documentation clear for new contributors + +## Related Files + +**New files:** +- `workspaces/main/workspace.cfg` - Main demo config +- `workspaces/test/workspace.cfg` - Test demo config +- `cmake/ParseWorkspace.cmake` - Config parser +- `scripts/workspace.sh` - Workspace CLI tool +- `templates/workspace.cfg` - New workspace template + +**Modified files:** +- `CMakeLists.txt` - Workspace support +- `tools/asset_packer.cc` - Multi-path resolution +- `src/gpu/shader_composer.cc` - Multi-path includes +- `README.md` - Workspace documentation +- `doc/HOWTO.md` - Build commands +- `doc/CONTRIBUTING.md` - Workspace guidelines + +**Moved files:** +- `assets/demo.seq` → `workspaces/main/timeline.seq` +- `assets/music.track` → `workspaces/main/music.track` +- `assets/final/demo_assets.txt` → `workspaces/main/assets.txt` +- `assets/test_demo.*` → `workspaces/test/` +- `assets/shaders/math/` → `assets/common/shaders/math/` + +## Notes + +- This is a **structural refactor**, not a feature +- No runtime behavior changes +- Enables future scalability +- Makes project more professional +- Good foundation for demoscene releases (multiple demos per repo) |