diff options
Diffstat (limited to 'doc/WORKSPACE_SYSTEM.md')
| -rw-r--r-- | doc/WORKSPACE_SYSTEM.md | 582 |
1 files changed, 21 insertions, 561 deletions
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. |