# How To

Common commands for building and testing.

---

## Building

### Debug Build
```bash
cmake -S . -B build
cmake --build build -j4
./build/demo64k
```

Options: `--fullscreen`, `--resolution WxH`, `--seek TIME`, `--hot-reload` (debug only)

Keyboard: `Esc` (exit), `F` (toggle fullscreen)

**Hot-Reload Mode:**
```bash
./build/demo64k --hot-reload
```
Watches config files and notifies when changes detected. See `doc/HOT_RELOAD.md`.

### 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.

### Final Build (Maximum Stripping)
```bash
./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)
```bash
cmake -S . -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.

---

## Build System

**Dependency Tracking:** CMake tracks 42 demo + 17 test assets. Editing shaders/audio auto-triggers rebuild.

**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
```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

---

## 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.

---

For developer tools reference (spectool, Windows cross-compilation, code coverage), see `doc/TOOLS_REFERENCE.md`.