diff options
Diffstat (limited to 'doc/HOWTO.md')
| -rw-r--r-- | doc/HOWTO.md | 202 |
1 files changed, 64 insertions, 138 deletions
diff --git a/doc/HOWTO.md b/doc/HOWTO.md index fa3395a..bdc0214 100644 --- a/doc/HOWTO.md +++ b/doc/HOWTO.md @@ -1,206 +1,132 @@ # How To -Common commands for building and testing. +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 cmake --build build -j4 ./build/demo64k ``` +Options: `--fullscreen`, `--resolution WxH`, `--seek TIME`, `--hot-reload` -Options: `--fullscreen`, `--resolution WxH`, `--seek TIME`, `--hot-reload` (debug only) +### Production Builds +```bash +# Size-optimized (development) +cmake -B build -DDEMO_SIZE_OPT=ON && cmake --build build -j4 -Keyboard: `Esc` (exit), `F` (toggle fullscreen) +# 64k target (full checks, no debug) +cmake -B build -DDEMO_STRIP_ALL=ON && cmake --build build -j4 -**Hot-Reload Mode:** -```bash -./build/demo64k --hot-reload +# Final release (no checks, absolute minimum) +./scripts/build_final.sh ``` -Watches config files and notifies when changes detected. See `doc/HOT_RELOAD.md`. -### Size-Optimized Build +### Developer Build ```bash -cmake -S . -B build -DDEMO_SIZE_OPT=ON +cmake -B build -DDEMO_BUILD_TESTS=ON -DDEMO_BUILD_TOOLS=ON cmake --build build -j4 ``` -### Strip Build (64k Target) +### Headless Testing ```bash -cmake -S . -B build -DDEMO_STRIP_ALL=ON -cmake --build build -j4 +cmake -B build_headless -DDEMO_HEADLESS=ON && cmake --build build_headless -j4 +./build_headless/demo64k --headless --duration 30 ``` -Always starts in fullscreen. Full error checking enabled. +See `doc/HEADLESS_MODE.md`. -### Final Build (Maximum Stripping) +### Size Measurement ```bash -./scripts/build_final.sh -# or -cmake -S . -B build_final -DDEMO_FINAL_STRIP=ON -cmake --build build_final -j4 +./scripts/measure_size.sh ``` -⚠️ Removes ALL error checking. Use only for final release. +Measures demo vs external library size. See `doc/SIZE_MEASUREMENT.md`. + +--- -**Build Hierarchy:** -- Debug: Full checks + debug features -- STRIP_ALL: Full checks, no debug (~64k target) -- FINAL_STRIP: No checks, no debug (absolute minimum) +## Testing -### Developer Build (Tests + Tools) +### Run All Tests ```bash -cmake -S . -B build -DDEMO_BUILD_TESTS=ON -DDEMO_BUILD_TOOLS=ON +cmake -B build -DDEMO_BUILD_TESTS=ON cmake --build build -j4 +cd build && ctest +# OR: make run_all_tests ``` -**Note:** `DEMO_ALL_OPTIONS=ON` enables tests, tools, AND `STRIP_ALL`, which removes debug-only code. Use selective flags for debugging. - -### Size Measurement Build +### Run Subsystem Tests ```bash -./scripts/measure_size.sh +make run_audio_tests # Audio system tests +make run_gpu_tests # GPU/shader tests +make run_3d_tests # 3D rendering tests +make run_assets_tests # Asset system tests +make run_util_tests # Utility tests ``` -Measures demo code size by stubbing external libraries (wgpu/GLFW/miniaudio). Binary compiles but **does NOT run**. -**Manual:** +### Run Specific Test ```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 +./build/test_synth ``` -**Typical results:** Demo=4.4MB (69%), External=2.0MB (31%) - -See `doc/SIZE_MEASUREMENT.md` for details. - --- -## Build System - -**Dependency Tracking:** CMake tracks 42 demo + 17 test assets. Editing shaders/audio auto-triggers rebuild. +## Timeline -**Header Organization:** -- `asset_manager_dcl.h`: Forward declarations -- `asset_manager.h`: Core API (GetAsset/DropAsset) -- `asset_manager_utils.h`: Typed helpers - ---- - -## Git Clone -```bash -git clone ssh://git@51.38.51.127/~/demo.git +Edit `workspaces/main/timeline.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. +See `doc/TRACKER.md` for music system. --- -## Demo Timeline +## Assets -Edit `assets/demo.seq`: -```text -SEQUENCE 0.0 0 - EFFECT HeptagonEffect 0.0 60.0 0 -``` -Rebuild to update timeline. - ---- - -## Testing - -**Run all tests:** +Edit `workspaces/main/assets.txt`, then rebuild: ```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/ASSET_SYSTEM.md` and `doc/WORKSPACE_SYSTEM.md`. --- -## Asset Management - -### Define Assets -Edit `assets/final/demo_assets.txt`: -``` -KICK_1, kick1.spec, NONE, "Drum kick" -``` - -### Regenerate -```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. - ---- +## Additional Documentation -For developer tools reference (spectool, Windows cross-compilation, code coverage), see `doc/TOOLS_REFERENCE.md`. +- **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 |