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
|
# How To
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`
### Production Builds
```bash
# Size-optimized (development)
cmake -B build -DDEMO_SIZE_OPT=ON && cmake --build build -j4
# 64k target (full checks, no debug)
cmake -B build -DDEMO_STRIP_ALL=ON && cmake --build build -j4
# Final release (no checks, absolute minimum)
./scripts/build_final.sh
```
### Developer Build
```bash
cmake -B build -DDEMO_BUILD_TESTS=ON -DDEMO_BUILD_TOOLS=ON
cmake --build build -j4
```
### Headless Testing
```bash
cmake -B build_headless -DDEMO_HEADLESS=ON && cmake --build build_headless -j4
./build_headless/demo64k --headless --duration 30
```
See `doc/HEADLESS_MODE.md`.
### Size Measurement
```bash
./scripts/measure_size.sh
```
Measures demo vs external library size. See `doc/SIZE_MEASUREMENT.md`.
---
## Testing
### Run All Tests
```bash
cmake -B build -DDEMO_BUILD_TESTS=ON
cmake --build build -j4
cd build && ctest
# OR: make run_all_tests
```
### Run Subsystem Tests
```bash
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
```
### Run Specific Test
```bash
./build/test_synth
```
---
## Training
```bash
./training/train_cnn.py --layers 3 --kernel_sizes 3,5,3 --epochs 10000 --batch_size 8 --input training/input/ --target training/output/ --checkpoint-every 1000
```
Generate shaders from checkpoint:
```bash
./training/train_cnn.py --export-only training/checkpoints/checkpoint_epoch_7000.pth
```
Generate ground truth (for shader validation):
```bash
./training/train_cnn.py --infer input.png --export-only checkpoints/checkpoint_epoch_7000.pth --output ground_truth.png
```
**Note:** Kernel sizes must match shader functions:
- 3×3 kernel → `cnn_conv3x3_7to4` (36 weights: 9 pos × 4 channels)
- 5×5 kernel → `cnn_conv5x5_7to4` (100 weights: 25 pos × 4 channels)
---
## Timeline
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
```cpp
#include "audio/audio_engine.h"
audio_init();
static AudioEngine g_audio_engine;
g_audio_engine.init();
g_audio_engine.update(music_time);
g_audio_engine.shutdown();
audio_shutdown();
```
See `doc/TRACKER.md` for music system.
---
## Assets
Edit `workspaces/main/assets.txt`, then rebuild:
```bash
cmake --build build -j4
```
See `doc/ASSET_SYSTEM.md` and `doc/WORKSPACE_SYSTEM.md`.
---
## Additional Documentation
- **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
|
