# How To

Common commands for building and testing.

## Building

### Debug Build
```bash
cmake -S . -B build
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)

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

### 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
```bash
cmake -S . -B build -DDEMO_ALL_OPTIONS=ON
cmake --build build -j4
```
Enables tests, tools, size optimizations.

## 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()`: Register samples
- `synth_trigger_voice()`: Trigger playback
- `synth_get_output_peak()`: Get audio level
- `synth_render()`: Low-level rendering

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

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

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