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
|
# To-Do List
This file tracks prioritized tasks with detailed attack plans.
**Note:** For completed tasks, see `doc/COMPLETED.md`.
---
## Priority 1: Spectral Brush Editor (Task #5) [IN PROGRESS]
**Goal:** Web-based tool for procedurally tracing audio spectrograms. Replaces large `.spec` binary assets with tiny procedural C++ code (50-100× compression).
**Design Document:** See `doc/SPECTRAL_BRUSH_EDITOR.md` for complete architecture.
**Core Concept:** Bezier curves trace time-frequency paths. Gaussian profiles shape "brush strokes" around curves.
**Workflow:** `.wav` → Load in editor → Trace with Bezier curves → Export `procedural_params.txt` + C++ code
### Phase 1: C++ Runtime (Foundation)
- [ ] Files: `src/audio/spectral_brush.h`, `src/audio/spectral_brush.cc`
- [ ] Define API (`ProfileType`, `draw_bezier_curve()`, `evaluate_profile()`)
- [ ] Implement linear Bezier interpolation
- [ ] Implement Gaussian profile evaluation
- [ ] Implement home-brew deterministic RNG
- [ ] Add unit tests (`src/tests/test_spectral_brush.cc`)
- [ ] **Deliverable:** Compiles, tests pass
### Phase 2: Editor Core
- [ ] Files: `tools/spectral_editor/index.html`, `script.js`, `style.css`, `dct.js`
- [ ] HTML structure (canvas, controls, file input)
- [ ] Canvas rendering (dual-layer: reference + procedural)
- [ ] Bezier curve editor (click, drag, delete control points)
- [ ] Profile controls (Gaussian sigma slider)
- [ ] Real-time spectrogram rendering
- [ ] Audio playback (IDCT → Web Audio API)
- [ ] Undo/Redo system
- [ ] Keyboard shortcuts (1=play procedural, 2=play original, Space, Ctrl+Z, Delete)
- [ ] **Deliverable:** Interactive editor, can trace .wav files
### Phase 3: File I/O
- [ ] Load .wav (decode, FFT/STFT → spectrogram)
- [ ] Load .spec (binary format parser)
- [ ] Save procedural_params.txt (human-readable, re-editable)
- [ ] Generate C++ code (ready to compile)
- [ ] Load procedural_params.txt (re-editing workflow)
- [ ] **Deliverable:** Full save/load cycle works
### Phase 4: Future Extensions (Post-MVP)
- [ ] Cubic Bezier interpolation (smoother curves)
- [ ] Decaying sinusoid profile (metallic sounds)
- [ ] Noise profile (textured sounds)
- [ ] Composite profiles (add/subtract/multiply)
**Design Decisions:** Linear Bezier (Phase 1), cubic later. Soft parameter limits. Home-brew RNG. Single function per sound initially.
**Size Impact:** 50-100× compression (5 KB .spec → ~100 bytes C++ code)
---
## Priority 2: Workspace System (Task #77)
**Goal:** Reorganize project into self-contained workspaces to support parallel demo development.
**Design Document:** See `doc/WORKSPACE_SYSTEM.md` for complete architecture.
**Core Concept:** Each demo gets its own workspace directory with timeline, music, assets, and shaders. Common resources shared via `assets/common/`.
**Proposed Structure:**
```
/workspaces/
/main/ # Main production demo
workspace.cfg
timeline.seq
music.track
assets.txt
/assets/
/shaders/
/test/ # Test demo
...
/assets/common/ # Shared resources
/shaders/
/audio/
```
**Benefits:**
- Clear project organization
- Parallel development without conflicts
- Easy workspace switching (`-DDEMO_WORKSPACE=main`)
- Scales to multiple demos
**Implementation:** 12-16 hours (5 phases)
**Priority:** Medium (workflow improvement)
---
## Priority 3: 3D System Enhancements (Task #18)
**Goal:** Establish pipeline for importing complex 3D scenes to replace hardcoded geometry.
**Progress:** C++ pipeline for loading object-specific data (plane_distance) is in place. Shader integration for SDFs pending.
---
## Priority 3: WGSL Modularization (Task #50) [RECURRENT]
**Goal:** Refactor `ShaderComposer` and WGSL assets to support granular, reusable snippets. Ongoing task for shader code hygiene.
### Sub-task: Split common_uniforms.wgsl (Low Priority)
**Current:** `common_uniforms.wgsl` contains 4 structs (CommonUniforms, GlobalUniforms, ObjectData, ObjectsBuffer)
**Goal:** Split into separate files:
- `common_uniforms/common.wgsl` - CommonUniforms only
- `common_uniforms/global.wgsl` - GlobalUniforms only
- `common_uniforms/object.wgsl` - ObjectData + ObjectsBuffer
**Benefit:** Shaders only include what they need, reducing compiled size
**Impact:** Minimal (most shaders only use CommonUniforms)
**Priority:** Low (nice-to-have)
### Sub-task: Type-safe shader composition (Low Priority)
**Problem:** Recurrent error of forgetting `ShaderComposer::Get().Compose({}, code)` and using raw `code` directly. Runtime error only (crashes demo, tests may pass).
**Solution:** Use strong typing to make it compile-time error:
```cpp
class ComposedShader {
private:
std::string code_;
friend class ShaderComposer;
explicit ComposedShader(std::string code) : code_(std::move(code)) {}
public:
const char* c_str() const { return code_.c_str(); }
};
```
**Changes:**
- `ShaderComposer::Compose()` returns `ComposedShader` instead of `std::string`
- All shader creation functions take `const ComposedShader&` instead of `const char*`
- Cannot pass raw string to shader functions (compile error)
**Benefits:** Impossible to forget composition (type mismatch). Self-documenting API. Compile-time error.
**Trade-offs:** More verbose code. Small overhead (extra std::string copy, negligible).
**Priority:** Low (recurrent but rare, easy to catch in testing)
---
## Phase 2: Size Optimization (Final Goal)
- [ ] **Task #34: Full STL Removal** - Replace remaining `std::vector`, `std::map`, `std::string` with custom containers
- [ ] **Task #22: Windows Native Platform** - Replace GLFW with Win32 API
- [ ] **Task #28: Spectrogram Quantization** - Research optimal frequency distribution
- [ ] **Task #35: CRT Replacement** - Investigation and implementation of CRT-free entry
- [ ] **Task #76: External Library Size Measurement** - STRIP_EXTERNAL_LIBS mode with stub implementations to measure core demo size vs external library overhead. See `doc/SIZE_MEASUREMENT.md`.
---
For untriaged future goals and ideas, see `doc/BACKLOG.md`.
|
