1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
|
# 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` (debug 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 (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`.
|
