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
|
# 64k Demo Project
## Goal
- Produce a <=64k native demo binary
- Same C++ codebase for Windows, macOS, Linux
## Graphics
- WebGPU via wgpu-native
- WGSL shaders
- Hybrid rendering: Rasterized proxy geometry + SDF raymarching
## Audio
- 32 kHz, 16-bit stereo
- Procedurally generated samples
- Real-time additive synthesis from spectrograms (IDCT)
- Variable tempo system with music time abstraction
- Event-based pattern triggering for dynamic tempo scaling
- Modifiable Loops and Patterns, w/ script to generate them (like a Tracker)
- Unified AudioEngine for lifecycle management
## Constraints
- Size-sensitive
- Minimal dependencies
- Explicit control over all allocations
## Style
- Demoscene
- No engine abstractions
---
## Current Status
- Audio system: Sample-accurate synchronization. Hardware playback time as master clock. Variable tempo support. Pipeline optimized (Task #72): Zero heap allocations per frame, direct ring buffer writes. Comprehensive test coverage.
- Build system: Optimized with proper asset dependency tracking
- Shader system: Parameterization complete (UniformHelper, .seq syntax). Modular with compilation tests. WGSL composability improved (`math/common_utils.wgsl`).
- 3D rendering: Hybrid SDF/rasterization with BVH acceleration and binary scene loader. Object data loading pipeline enhanced.
- Asset pipeline: Blender export script and binary scene ingestion
- Error handling: Dual macro system (`FATAL_XXX` for programming errors, `CHECK_RETURN` for recoverable errors)
- Testing: **36/36 tests passing (100%)** - All tests operational
---
## Next Up
- **Task #5: Spectral Brush Editor** [IN PROGRESS]
- Web-based tool for procedurally tracing audio spectrograms
- Replace large .spec assets with tiny C++ code (50-100× compression)
- See TODO.md and `doc/SPECTRAL_BRUSH_EDITOR.md`
- **Visuals & Content**
- Task #52: Procedural SDF Font
- Task #53: Particles Shader Polish
- Task #55: SDF Random Planes Intersection
- **Tooling & Optimization**
- Task #54: Tracy Integration
- Task #76: External Library Size Measurement (Low priority)
---
## Design Docs Quick Reference
For detailed documentation, use Read tool to load specific docs:
- **doc/TRACKER.md**: Audio pattern system with unit-less timing
- **doc/3D.md**: Hybrid SDF raymarching with BVH acceleration
- **doc/ASSET_SYSTEM.md**: Build-time asset packer with 16-byte alignment
- **doc/BUILD.md**: Multi-platform builds (Debug/STRIP_ALL/FINAL_STRIP)
- **doc/SPECTRAL_BRUSH_EDITOR.md**: Web tool for tracing spectrograms
- **doc/SEQUENCE.md**: .seq timeline format with BPM notation
- **doc/MASKING_SYSTEM.md**: Auxiliary texture registry
- **doc/SCENE_FORMAT.md**: Binary scene format (SCN1)
- **doc/SIZE_MEASUREMENT.md**: External library size measurement strategy
- **doc/test_demo_README.md**: 16s audio/visual sync test tool
- **doc/HOT_RELOAD.md**: Debug-only file change detection
- **doc/CONTEXT_MAINTENANCE.md**: Context hygiene protocol
---
## Recently Completed (February 2026)
- **Hot-Reload File Watcher** (Feb 9) - Debug-only file change detection with `--hot-reload` flag. Watches config files (assets, sequences, music) and notifies on changes. 0 bytes overhead in release builds.
- **WGSL Uniform Buffer Validation (Task #75)** (Feb 9) - Standardized uniform buffer layout. Validation tool integrated into build. All effects use `CommonPostProcessUniforms` (binding 2) + effect-specific params (binding 3). Added `UNIFORM_BUFFER_GUIDELINES.md`.
- **Uniform Buffer Alignment (Task #74)** (Feb 9) - Fixed WGSL `vec3<f32>` alignment issues. Demo runs with 0 validation errors.
- **Shader Parametrization (Task #73)** (Feb 8) - Full uniform parameter system with .seq syntax. FlashEffect, ChromaAberrationEffect, GaussianBlurEffect support dynamic parameters. Size: ~400-500 bytes.
---
For detailed architecture, see `doc/ARCHITECTURE.md`.
For completed tasks history, see `doc/COMPLETED.md` and git history.
|
