diff options
| -rw-r--r-- | doc/ASSET_SYSTEM.md | 15 | ||||
| -rw-r--r-- | doc/BUILD.md | 27 | ||||
| -rw-r--r-- | doc/HOWTO.md | 184 | ||||
| -rw-r--r-- | doc/TRACKER.md | 39 |
4 files changed, 118 insertions, 147 deletions
diff --git a/doc/ASSET_SYSTEM.md b/doc/ASSET_SYSTEM.md index 4e34378..8f31a6a 100644 --- a/doc/ASSET_SYSTEM.md +++ b/doc/ASSET_SYSTEM.md @@ -89,6 +89,21 @@ Runtime: First `GetAsset()` call invokes generator, caches result. - **Hardcoded procedural dimensions**: Assumes 256×256 RGBA8 - **No integrity checks**: No CRC/hash validation +## Developer Workflow + +**Add new asset:** +1. Place file in `assets/final/` +2. Edit `assets/final/demo_assets.txt`: + ``` + MY_ASSET, myfile.ext, NONE, "Description" + ``` +3. Regenerate: `./scripts/gen_assets.sh` or rebuild (auto-triggered) +4. Use in code: `GetAsset(AssetId::MY_ASSET, &size)` + +**Modify existing asset:** +- Edit source file in `assets/final/` +- CMake auto-detects change and rebuilds + ## Planned Improvements See **TODO.md** for detailed task breakdown: diff --git a/doc/BUILD.md b/doc/BUILD.md index 1f65122..7cb3473 100644 --- a/doc/BUILD.md +++ b/doc/BUILD.md @@ -21,8 +21,17 @@ cmake --build build_final -j4 | Mode | Flags | Use Case | |------|-------|----------| | Debug | `-DCMAKE_BUILD_TYPE=Debug` | Development, full error checking + debug features | +| SIZE_OPT | `-DDEMO_SIZE_OPT=ON` | Size-optimized, with checks | | STRIP_ALL | `-DDEMO_STRIP_ALL=ON` | Release candidate, full error checking, no debug features (~64k target) | | FINAL_STRIP | `-DDEMO_FINAL_STRIP=ON` | Final release, no error checking, absolute minimum size | +| STRIP_EXTERNAL_LIBS | `-DDEMO_STRIP_EXTERNAL_LIBS=ON` | Size measurement only (binary won't run) | + +**Build Hierarchy:** +- **Debug:** Full checks + debug features (hot-reload, seek, etc.) +- **STRIP_ALL:** Full checks, no debug (~64k target, always fullscreen) +- **FINAL_STRIP:** No checks, no debug (absolute minimum, ⚠️ dangerous) + +**Note:** `DEMO_ALL_OPTIONS=ON` enables tests, tools, AND `STRIP_ALL`. ## Dependencies @@ -67,3 +76,21 @@ open build/demo.xcodeproj ``` Use Xcode Metal debugger for shader performance analysis. + +## Build System Internals + +**Asset Dependency Tracking:** +- CMake tracks 42 demo + 17 test assets +- Editing shaders/audio/sequences auto-triggers rebuild +- Asset lists parsed to extract individual file dependencies + +**Header Organization:** +- `asset_manager_dcl.h`: Forward declarations +- `asset_manager.h`: Core API (GetAsset/DropAsset) +- `asset_manager_utils.h`: Typed helpers + +**Code Generation:** +- Timeline: `seq_compiler` → `generated/timeline.cc` +- Music: `tracker_compiler` → `generated/music.cc` +- Assets: `asset_packer` → `generated/assets.h` + `assets_data.cc` +- Cross-compilation uses host-native tools for generation diff --git a/doc/HOWTO.md b/doc/HOWTO.md index fa3395a..9e32a86 100644 --- a/doc/HOWTO.md +++ b/doc/HOWTO.md @@ -1,6 +1,6 @@ # How To -Common commands for building and testing. +Quick reference for common tasks. --- @@ -12,195 +12,85 @@ cmake -S . -B build cmake --build build -j4 ./build/demo64k ``` +Options: `--fullscreen`, `--resolution WxH`, `--seek TIME`, `--hot-reload` -Options: `--fullscreen`, `--resolution WxH`, `--seek TIME`, `--hot-reload` (debug only) - -Keyboard: `Esc` (exit), `F` (toggle fullscreen) - -**Hot-Reload Mode:** +### Production Builds ```bash -./build/demo64k --hot-reload -``` -Watches config files and notifies when changes detected. See `doc/HOT_RELOAD.md`. +# Size-optimized (development) +cmake -B build -DDEMO_SIZE_OPT=ON && cmake --build build -j4 -### Size-Optimized Build -```bash -cmake -S . -B build -DDEMO_SIZE_OPT=ON -cmake --build build -j4 -``` - -### Strip Build (64k Target) -```bash -cmake -S . -B build -DDEMO_STRIP_ALL=ON -cmake --build build -j4 -``` -Always starts in fullscreen. Full error checking enabled. +# 64k target (full checks, no debug) +cmake -B build -DDEMO_STRIP_ALL=ON && cmake --build build -j4 -### Final Build (Maximum Stripping) -```bash +# Final release (no checks, absolute minimum) ./scripts/build_final.sh -# or -cmake -S . -B build_final -DDEMO_FINAL_STRIP=ON -cmake --build build_final -j4 ``` -⚠️ Removes ALL error checking. Use only for final release. - -**Build Hierarchy:** -- Debug: Full checks + debug features -- STRIP_ALL: Full checks, no debug (~64k target) -- FINAL_STRIP: No checks, no debug (absolute minimum) -### Developer Build (Tests + Tools) +### Developer Build ```bash -cmake -S . -B build -DDEMO_BUILD_TESTS=ON -DDEMO_BUILD_TOOLS=ON +cmake -B build -DDEMO_BUILD_TESTS=ON -DDEMO_BUILD_TOOLS=ON cmake --build build -j4 ``` -**Note:** `DEMO_ALL_OPTIONS=ON` enables tests, tools, AND `STRIP_ALL`, which removes debug-only code. Use selective flags for debugging. - -### Size Measurement Build +### Size Measurement ```bash ./scripts/measure_size.sh ``` -Measures demo code size by stubbing external libraries (wgpu/GLFW/miniaudio). Binary compiles but **does NOT run**. - -**Manual:** -```bash -cmake -S . -B build_size -DDEMO_STRIP_EXTERNAL_LIBS=ON -cmake --build build_size -j4 -strip build_size/demo64k -ls -lh build_size/demo64k -``` - -**Typical results:** Demo=4.4MB (69%), External=2.0MB (31%) - -See `doc/SIZE_MEASUREMENT.md` for details. +Measures demo vs external library size. See `doc/SIZE_MEASUREMENT.md`. --- -## Build System - -**Dependency Tracking:** CMake tracks 42 demo + 17 test assets. Editing shaders/audio auto-triggers rebuild. +## Testing -**Header Organization:** -- `asset_manager_dcl.h`: Forward declarations -- `asset_manager.h`: Core API (GetAsset/DropAsset) -- `asset_manager_utils.h`: Typed helpers +```bash +cmake -B build -DDEMO_BUILD_TESTS=ON +cmake --build build -j4 +cd build && ctest +``` --- -## Git Clone -```bash -git clone ssh://git@51.38.51.127/~/demo.git +## Timeline + +Edit `assets/demo.seq`: +```text +SEQUENCE 0.0 0 + EFFECT HeptagonEffect 0.0 60.0 0 ``` +Rebuild to apply. See `doc/SEQUENCE.md`. --- -## Audio System +## Audio -### AudioEngine API ```cpp #include "audio/audio_engine.h" audio_init(); static AudioEngine g_audio_engine; g_audio_engine.init(); - -// Main loop g_audio_engine.update(music_time); - g_audio_engine.shutdown(); audio_shutdown(); ``` - -**Methods:** -- `init()`: Initialize synth + tracker -- `update(music_time)`: Update music state -- `shutdown()`: Cleanup -- `seek(time)`: Jump to timestamp (debug only) - -**Direct Synth APIs** (performance-critical): -- `synth_register_spectrogram()`, `synth_trigger_voice()`, `synth_get_output_peak()`, `synth_render()` - -**Testing:** -```cpp -AudioEngine engine; -engine.init(); -engine.update(1.0f); -engine.shutdown(); -``` - ---- - -## Auxiliary Texture Masking - -Share textures between effects: -```cpp -// Generator effect -demo->register_auxiliary_texture("mask_name", width, height); -WGPUTextureView view = demo_->get_auxiliary_view("mask_name"); - -// Consumer effect -WGPUTextureView view = demo_->get_auxiliary_view("mask_name"); -``` -See `doc/MASKING_SYSTEM.md` for details. - ---- - -## Demo Timeline - -Edit `assets/demo.seq`: -```text -SEQUENCE 0.0 0 - EFFECT HeptagonEffect 0.0 60.0 0 -``` -Rebuild to update timeline. - ---- - -## Testing - -**Run all tests:** -```bash -cmake -S . -B build -DDEMO_BUILD_TESTS=ON -cmake --build build -j4 -cd build && ctest -``` - -**Key tests:** -- `HammingWindowTest`: Window function properties -- `MathUtilsTest`: Math utilities -- `SynthEngineTest`: Audio synthesis -- `SequenceSystemTest`: Timeline logic +See `doc/TRACKER.md` for music system. --- -## Asset Management +## Assets -### Define Assets -Edit `assets/final/demo_assets.txt`: -``` -KICK_1, kick1.spec, NONE, "Drum kick" -``` - -### Regenerate +Edit `assets/final/demo_assets.txt`, then: ```bash ./scripts/gen_assets.sh ``` -Converts WAV → .spec, packs into C++ arrays. - -### Use Assets -```cpp -#include "assets.h" - -size_t size; -const uint8_t* data = GetAsset(AssetId::KICK_1, &size); -// Use data... -// DropAsset(AssetId::KICK_1, data); // For compressed assets only -``` - -Build system auto-runs `asset_packer` when asset lists change. +See `doc/ASSET_SYSTEM.md`. --- -For developer tools reference (spectool, Windows cross-compilation, code coverage), see `doc/TOOLS_REFERENCE.md`. +## Additional Documentation + +- **Build System:** `doc/BUILD.md` - Multi-platform, size optimization +- **Tools:** `doc/TOOLS_REFERENCE.md` - spectool, coverage, Windows cross-compile +- **Shaders:** `doc/SEQUENCE.md` - Timeline format, shader parameters +- **3D:** `doc/3D.md` - Hybrid rendering, scene format +- **Hot Reload:** `doc/HOT_RELOAD.md` - Debug file watching diff --git a/doc/TRACKER.md b/doc/TRACKER.md index 6e71951..48829c0 100644 --- a/doc/TRACKER.md +++ b/doc/TRACKER.md @@ -74,3 +74,42 @@ PATTERN short_fill LENGTH 0.5 # 2 beats = 1 second at 120 BPM Potential runtime modifiers (not yet implemented): - Randomization, accents, volume modulation, distortion, noise, effects + +--- + +## AudioEngine API + +**Production usage:** +```cpp +#include "audio/audio_engine.h" + +audio_init(); +static AudioEngine g_audio_engine; +g_audio_engine.init(); + +// Main loop +g_audio_engine.update(music_time); + +g_audio_engine.shutdown(); +audio_shutdown(); +``` + +**Methods:** +- `init()`: Initialize synth + tracker +- `update(music_time)`: Update music state, trigger patterns +- `shutdown()`: Cleanup +- `seek(time)`: Jump to timestamp (debug builds only) + +**Testing:** +```cpp +AudioEngine engine; +engine.init(); +engine.update(1.0f); +engine.shutdown(); +``` + +**Direct synth APIs** (performance-critical code only): +- `synth_register_spectrogram()` +- `synth_trigger_voice()` +- `synth_get_output_peak()` +- `synth_render()` |