diff options
| -rw-r--r-- | doc/ARCHITECTURE.md | 2 | ||||
| -rw-r--r-- | doc/ASSET_SYSTEM.md | 16 | ||||
| -rw-r--r-- | doc/CONTRIBUTING.md | 2 | ||||
| -rw-r--r-- | doc/HOWTO.md | 21 | ||||
| -rw-r--r-- | doc/SEQUENCE.md | 20 |
5 files changed, 38 insertions, 23 deletions
diff --git a/doc/ARCHITECTURE.md b/doc/ARCHITECTURE.md index 1a32300..97413de 100644 --- a/doc/ARCHITECTURE.md +++ b/doc/ARCHITECTURE.md @@ -22,7 +22,7 @@ Detailed system architecture for the 64k demo project. **MainSequence**: Top-level coordinator and framebuffer manager. -**seq_compiler**: Transpiles `assets/demo.seq` into C++ `timeline.cc`. +**seq_compiler**: Transpiles workspace `timeline.seq` into C++ `timeline.cc`. --- diff --git a/doc/ASSET_SYSTEM.md b/doc/ASSET_SYSTEM.md index 8f31a6a..f52e382 100644 --- a/doc/ASSET_SYSTEM.md +++ b/doc/ASSET_SYSTEM.md @@ -17,11 +17,11 @@ DropAsset(ASSET_SAMPLE_142, mysample); // For lazy decompression cleanup ## Asset Manifest Format -File: `assets/final/demo_assets.txt` +Files: `workspaces/main/assets.txt`, `workspaces/test/assets.txt` Format (CSV): ``` -ASSET_NAME, filename.ext, COMPRESSION, "Description" +ASSET_NAME, COMPRESSION, filename.ext, "Description" ``` Example: @@ -43,8 +43,8 @@ enum class AssetId : uint16_t { Tool: `tools/asset_packer.cc` -1. Parse `demo_assets.txt` -2. Read binary files from `assets/final/` +1. Parse workspace `assets.txt` +2. Read files from workspace `assets/` or `assets/common/` 3. Generate `assets.h` (enum definitions) 4. Generate `assets_data.cc` (embedded byte arrays) 5. Auto-triggered by CMake on manifest changes @@ -92,12 +92,12 @@ Runtime: First `GetAsset()` call invokes generator, caches result. ## Developer Workflow **Add new asset:** -1. Place file in `assets/final/` -2. Edit `assets/final/demo_assets.txt`: +1. Place file in workspace `assets/` (or `assets/common/` for shared) +2. Edit workspace `assets.txt`: ``` - MY_ASSET, myfile.ext, NONE, "Description" + MY_ASSET, NONE, assets/myfile.ext, "Description" ``` -3. Regenerate: `./scripts/gen_assets.sh` or rebuild (auto-triggered) +3. Rebuild: `cmake --build build -j4` (auto-triggered) 4. Use in code: `GetAsset(AssetId::MY_ASSET, &size)` **Modify existing asset:** diff --git a/doc/CONTRIBUTING.md b/doc/CONTRIBUTING.md index de6378a..3344b18 100644 --- a/doc/CONTRIBUTING.md +++ b/doc/CONTRIBUTING.md @@ -63,7 +63,7 @@ See `doc/CODING_STYLE.md` for detailed examples. ### Adding Visual Effect 1. Implement `Effect` subclass in `src/gpu/demo_effects.cc` -2. Add to `assets/demo.seq` +2. Add to workspace `timeline.seq` (e.g., `workspaces/main/timeline.seq`) 3. **Update `test_demo_effects.cc`**: - Add to test list - Increment `EXPECTED_*_COUNT` diff --git a/doc/HOWTO.md b/doc/HOWTO.md index 9e32a86..97c7df7 100644 --- a/doc/HOWTO.md +++ b/doc/HOWTO.md @@ -6,6 +6,19 @@ Quick reference for common tasks. ## Building +### Workspace Selection +```bash +# Main demo (default) +cmake -S . -B build -DDEMO_WORKSPACE=main +cmake --build build -j4 +./build/demo64k + +# Test demo +cmake -S . -B build_test -DDEMO_WORKSPACE=test +cmake --build build_test -j4 +./build_test/test_demo +``` + ### Debug Build ```bash cmake -S . -B build @@ -52,7 +65,7 @@ cd build && ctest ## Timeline -Edit `assets/demo.seq`: +Edit `workspaces/main/timeline.seq`: ```text SEQUENCE 0.0 0 EFFECT HeptagonEffect 0.0 60.0 0 @@ -79,11 +92,11 @@ See `doc/TRACKER.md` for music system. ## Assets -Edit `assets/final/demo_assets.txt`, then: +Edit `workspaces/main/assets.txt`, then rebuild: ```bash -./scripts/gen_assets.sh +cmake --build build -j4 ``` -See `doc/ASSET_SYSTEM.md`. +See `doc/ASSET_SYSTEM.md` and `doc/WORKSPACE_SYSTEM.md`. --- diff --git a/doc/SEQUENCE.md b/doc/SEQUENCE.md index 954c816..68bd129 100644 --- a/doc/SEQUENCE.md +++ b/doc/SEQUENCE.md @@ -7,7 +7,8 @@ This document describes the `.seq` file format used to define demo timelines. Sequence files (`.seq`) define the timeline and layering of visual effects. They are compiled by `seq_compiler` into C++ code at build time. **Locations:** -- Demo sequence: `assets/demo.seq` +- Main demo: `workspaces/main/timeline.seq` +- Test demo: `workspaces/test/timeline.seq` - Compiler: `tools/seq_compiler.cc` - Generated output: `src/generated/timeline.cc` @@ -158,18 +159,18 @@ SEQUENCE 0b 0 **ASCII Chart (Terminal):** ```bash -./build/seq_compiler assets/demo.seq --gantt=timeline.txt +./build/seq_compiler workspaces/main/timeline.seq --gantt=timeline.txt ``` **HTML/SVG Chart (Recommended):** ```bash -./build/seq_compiler assets/demo.seq --gantt-html=timeline.html +./build/seq_compiler workspaces/main/timeline.seq --gantt-html=timeline.html ``` Interactive visualization with hover tooltips, color coding, and zoom/pan. ### Validation Only ```bash -./build/seq_compiler assets/demo.seq +./build/seq_compiler workspaces/main/timeline.seq ``` Validates syntax without generating code. @@ -177,13 +178,13 @@ Validates syntax without generating code. ## Integration -CMake automatically invokes the compiler on `assets/demo.seq` changes: +CMake automatically invokes the compiler on workspace timeline changes: ```cmake add_custom_command( OUTPUT ${GENERATED_DIR}/timeline.cc - COMMAND seq_compiler assets/demo.seq ${GENERATED_DIR}/timeline.cc - DEPENDS assets/demo.seq + COMMAND seq_compiler ${WORKSPACE_TIMELINE} ${GENERATED_DIR}/timeline.cc + DEPENDS ${WORKSPACE_TIMELINE} ) ``` @@ -191,7 +192,8 @@ add_custom_command( ## See Also -- `assets/demo.seq` - Current demo timeline +- `workspaces/main/timeline.seq` - Main demo timeline +- `workspaces/test/timeline.seq` - Test demo timeline +- `doc/WORKSPACE_SYSTEM.md` - Workspace organization - `src/gpu/demo_effects.h` - Available effect classes -- `doc/EFFECTS_CATALOG.md` - Detailed effect reference (if needed) - `doc/HOWTO.md` - Building and running |