diff options
Diffstat (limited to 'doc/HOWTO.md')
| -rw-r--r-- | doc/HOWTO.md | 90 |
1 files changed, 27 insertions, 63 deletions
diff --git a/doc/HOWTO.md b/doc/HOWTO.md index 967b554..876d7dc 100644 --- a/doc/HOWTO.md +++ b/doc/HOWTO.md @@ -2,6 +2,8 @@ Common commands for building and testing. +--- + ## Building ### Debug Build @@ -11,10 +13,7 @@ cmake --build build -j4 ./build/demo64k ``` -Options: -- `--fullscreen`: Run in fullscreen -- `--resolution WxH`: Set window size (e.g., 1024x768) -- `--seek TIME`: Jump to timestamp (debug builds only) +Options: `--fullscreen`, `--resolution WxH`, `--seek TIME` (debug only) Keyboard: `Esc` (exit), `F` (toggle fullscreen) @@ -45,27 +44,34 @@ cmake --build build_final -j4 - STRIP_ALL: Full checks, no debug (~64k target) - FINAL_STRIP: No checks, no debug (absolute minimum) -### Developer Build +### Developer Build (Tests + Tools) ```bash -cmake -S . -B build -DDEMO_ALL_OPTIONS=ON +cmake -S . -B build -DDEMO_BUILD_TESTS=ON -DDEMO_BUILD_TOOLS=ON cmake --build build -j4 ``` -Enables tests, tools, size optimizations. + +**Note:** `DEMO_ALL_OPTIONS=ON` enables tests, tools, AND `STRIP_ALL`, which removes debug-only code. Use selective flags for debugging. + +--- ## Build System -**Dependency Tracking**: CMake tracks 42 demo + 17 test assets. Editing shaders/audio auto-triggers rebuild. +**Dependency Tracking:** CMake tracks 42 demo + 17 test assets. Editing shaders/audio auto-triggers rebuild. -**Header Organization**: +**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 ``` +--- + ## Audio System ### AudioEngine API @@ -90,10 +96,7 @@ audio_shutdown(); - `seek(time)`: Jump to timestamp (debug only) **Direct Synth APIs** (performance-critical): -- `synth_register_spectrogram()`: Register samples -- `synth_trigger_voice()`: Trigger playback -- `synth_get_output_peak()`: Get audio level -- `synth_render()`: Low-level rendering +- `synth_register_spectrogram()`, `synth_trigger_voice()`, `synth_get_output_peak()`, `synth_render()` **Testing:** ```cpp @@ -103,6 +106,8 @@ engine.update(1.0f); engine.shutdown(); ``` +--- + ## Auxiliary Texture Masking Share textures between effects: @@ -116,6 +121,8 @@ WGPUTextureView view = demo_->get_auxiliary_view("mask_name"); ``` See `doc/MASKING_SYSTEM.md` for details. +--- + ## Demo Timeline Edit `assets/demo.seq`: @@ -125,6 +132,8 @@ SEQUENCE 0.0 0 ``` Rebuild to update timeline. +--- + ## Testing **Run all tests:** @@ -140,56 +149,7 @@ cd build && ctest - `SynthEngineTest`: Audio synthesis - `SequenceSystemTest`: Timeline logic -## Code Coverage (macOS) -```bash -brew install lcov -./scripts/gen_coverage_report.sh [target_dir] -``` - -## Tools - -### Windows Cross-Compilation -```bash -./scripts/fetch_win_deps.sh -./scripts/build_win.sh -./scripts/run_win.sh -``` - -### spectool (Audio Analysis) -```bash -cmake -S . -B build -DDEMO_BUILD_TOOLS=ON -cmake --build build -j4 - -# Analyze -./build/spectool analyze input.wav output.spec - -# Play -./build/spectool play input.spec -``` - -### specview (Visualization) -```bash -./build/specview input.spec -``` - -### specplay (Diagnostic) -```bash -./build/specplay input.spec -# or -./build/specplay input.wav -``` -Output: Peak, RMS, clipping detection. - -### Submodule Updates -```bash -cd third_party/wgpu-native -git fetch -git checkout trunk -git reset --hard origin/trunk -cd ../.. -git add third_party/wgpu-native -git commit -m "chore: Update wgpu-native" -``` +--- ## Asset Management @@ -216,3 +176,7 @@ const uint8_t* data = GetAsset(AssetId::KICK_1, &size); ``` Build system auto-runs `asset_packer` when asset lists change. + +--- + +For developer tools reference (spectool, Windows cross-compilation, code coverage), see `doc/TOOLS_REFERENCE.md`. |