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
|
# 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 mono
- Procedurally generated samples
- Real-time additive synthesis from spectrograms (IDCT)
- Modifiable Loops and Patterns, w/ script to generate them (like a Tracker)
Constraints:
- Size-sensitive
- Minimal dependencies
- Explicit control over all allocations
Style:
- Demoscene
- No engine abstractions
---
## Project Roadmap
### Recently Completed
#### Milestone: Audio System Robustness & Variable Tempo (February 4, 2026)
- **Variable Tempo System**: Implemented unified music time abstraction in `main.cc` that decouples tracker timing from physical time. Music time advances at configurable `tempo_scale` rate (default 1.0), enabling dynamic tempo changes without pitch shifting. Created comprehensive test suite (`test_variable_tempo.cc`) verifying 2x speed-up and 2x slow-down "reset tricks" work perfectly. All 6 test scenarios pass with mathematical precision. System ready for expressive tempo control in demo with zero size impact.
- **Task #51: Tracker Timing Verification System**: Created robust audio testing infrastructure with mock backend abstraction. Implemented `AudioBackend` interface separating synthesis from output, `MiniaudioBackend` for production, and `MockAudioBackend` for testing. Added event recording with precise timestamp tracking (32kHz sample rate). Created comprehensive test suite (`test_tracker_timing.cc`) that **verified simultaneous pattern triggers have 0.000ms delta** (perfect synchronization). All test infrastructure under `#if !defined(STRIP_ALL)` for zero production impact. 16/16 tests passing.
- **Task #50: WGSL Modularization**: Updated `ShaderComposer` to support recursive `#include` directives, refactored the entire shader library into granular snippets (shapes, utils, lighting), and updated the 3D renderer to use this modular system. This resolved macOS shader compilation issues and significantly improved shader maintainability.
- **Task #48: Improve Audio Coverage**: Achieved 93% coverage for `src/audio/` by adding dedicated tests for DCT transforms, procedural generation, and synthesis rendering.
- **Task #47: Improve Asset Manager Coverage**: Increased `asset_manager.cc` coverage to 88% by testing runtime error paths (unknown functions, generation failure).
- **Task #46: Enhance Coverage Script**: Updated coverage report script to support directory filtering (e.g., `./scripts/gen_coverage_report.sh src/procedural`).
- **Task #45: Improve Procedural Generation Coverage**: Achieved 96% coverage for `src/procedural/` by implementing comprehensive tests for Perlin noise, periodic blending, and parameter handling.
- **Task #44: Developer Tooling (Coverage)**: Added `DEMO_ENABLE_COVERAGE` CMake option and created `scripts/gen_coverage_report.sh` to generate HTML coverage reports using `lcov` on macOS.
- **Skybox & Two-pass Rendering Stability**: Resolved "black screen" and validation errors by implementing a robust two-pass rendering architecture (Pass 1: Skybox/Clear, Pass 2: Scene Objects). Implemented a rotating skybox using world-space ray unprojection (`inv_view_proj`) and a multi-octave procedural noise generator.
- **Task #20: Platform & Code Hygiene**: Consolidated platform-specific shims and WebGPU headers into `platform.h`. Refactored `platform_init` and `platform_poll` for better abstraction. Removed STL containers from initial hot paths (`AssetManager`, `procedural`). Full STL removal for CRT replacement is deferred to the final optimization phase.
- **Task #26: Shader Asset Testing & Validation**: Developed comprehensive tests for `ShaderComposer` and WGSL asset loading/composition. Added a shader validation test to ensure production assets are valid.
- **Asset Pipeline Improvement**: Created a robust `gen_spectrograms.sh` script to automate the conversion of `.wav` and `.aif` files to `.spec` format, replacing the old, fragile script. Added 13 new drum and bass samples to the project.
- **Build System Consolidation (Task #25)**: Modularized the build by creating subsystem libraries (audio, gpu, 3d, util, procedural) and implemented helper macros to reduce boilerplate in `CMakeLists.txt`. This improves build maintenance and prepares for future CRT replacement.
- **Asset System Robustness**: Resolved "static initialization order fiasco" by wrapping the asset table in a "Construct On First Use" getter (`GetAssetRecordTable()`), ensuring assets are available during dynamic global initialization (e.g., shader strings).
- **Shader Asset Integration (Task #24)**: Extracted all hardcoded WGSL strings into `.wgsl` assets, registered them in `demo_assets.txt`, and updated `Renderer3D`, `VisualDebug`, and `Effects` to use `GetAsset` and `ShaderComposer`.
- **WebGPU Stabilization**: Resolved `WGPUSurface` creation failures on macOS by adding platform-specific `GLFW_EXPOSE_NATIVE_COCOA` definitions and fixed validation errors in the render pass configuration.
- **Final Build Stripping (Task #8)**: Implemented the `STRIP_ALL` macro to remove non-essential code (CLI parsing, debug labels, iostream) and refined size optimization flags (`-dead_strip`) for macOS.
- **Minimal Audio Tracker (Task 21.3)**: Finalized a pattern-based audio tracker supporting both procedural notes and asset-based spectrograms with a unified "one-voice-per-pattern" pasting strategy.
- **WGSL Library (Task 21.1)**: Implemented `ShaderComposer` for modular WGSL snippet management.
- **Tight Ray Bounds (Task 21.2)**: Implemented local-space ray-box intersection to optimize SDF raymarching.
- **High-DPI Fix**: Resolved viewport "squishing" via dynamic resolution uniforms and explicit viewports.
- **Unified 3D Shadows**: Implemented robust SDF shadows across all objects using `inv_model` transforms.
---
## Next Up
- **Task #49: Physics & Collision**
- [ ] **Task #49.1: CPU-Side SDF Library**: Implement `sdSphere`, `sdBox` etc. in C++ (`src/3d/sdf_cpu.h`).
- [ ] **Task #49.2: BVH Construction**: Implement BVH builder and traversal for broad-phase collision.
- [ ] **Task #49.3: Physics Loop**: Implement integration, narrow-phase SDF probing, and collision resolution.
- **Task #18: 3D System Enhancements**
- [ ] **Task #36: Blender Exporter**: Create script to export scenes to internal binary format.
- [ ] **Task #37: Asset Ingestion**: Update `asset_packer` to handle the new 3D binary format.
- [ ] **Task #38: Runtime Loader**: Implement a minimal C++ parser to load the scene data into the ECS/Renderer.
---
## Future Goals
- **Task #5: Implement Spectrogram Editor**
- [ ] Develop a web-based tool (`tools/editor`) for creating and editing `.spec` files visually.
- **Task #21: Shader Optimization**
- [ ] Use macros or code generation to factorize common WGSL code (normals, bump, lighting).
- [ ] Implement Tri-planar mapping for better procedural textures.
- **Task #18-B: GPU BVH & Shadows**: Optimize scene queries with a GPU-based BVH.
- **Phase 2: Advanced Size Optimization**
- [ ] **Task #22: Windows Native Platform**: Replace GLFW with minimal native Windows API.
- [ ] **Task #28: Spectrogram Quantization**: Quantize spectrograms to logarithmic frequency and uint16_t.
- [ ] **Task #35: CRT Replacement**: Investigation and implementation of CRT-free entry point.
---
*For a detailed list of all completed tasks, see the git history.*
## Architectural Overview
### Hybrid 3D Renderer
- **Core Idea**: Uses standard rasterization to draw proxy hulls (boxes), then raymarches inside the fragment shader to find the exact SDF surface.
- **Transforms**: Uses `inv_model` matrices to perform all raymarching in local object space, handling rotation and non-uniform scaling correctly.
- **Shadows**: Instance-based shadow casting with self-shadowing prevention (`skip_idx`).
### Sequence & Effect System
- **Effect**: Abstract base for visual elements. Supports `compute` and `render` phases.
- **Sequence**: Timeline of effects with start/end times.
- **MainSequence**: Top-level coordinator and framebuffer manager.
- **seq_compiler**: Transpiles `assets/demo.seq` into C++ `timeline.cc`.
### Asset & Build System
- **asset_packer**: Embeds binary assets (like `.spec` files) into C++ arrays.
- **Runtime Manager**: O(1) retrieval with lazy procedural generation support.
- **Automation**: `gen_assets.sh`, `build_win.sh`, and `check_all.sh` for multi-platform validation.
### Audio Engine
- **Synthesis**: Real-time additive synthesis from spectrograms via IDCT.
- **Dynamic Updates**: Double-buffered spectrograms for live thread-safe updates.
- **Procedural Library**: Melodies and spectral filters (noise, comb) generated at runtime.
- **Pattern and loop**: spectrograms grouped as pattern and loops, and modifiers can be applied to loops (randomize, accents, etc.)
|
