diff options
| author | skal <pascal.massimino@gmail.com> | 2026-02-09 15:35:14 +0100 |
|---|---|---|
| committer | skal <pascal.massimino@gmail.com> | 2026-02-09 15:35:14 +0100 |
| commit | 802e97ee695de1bc8657c5cbca653bb2f13b90a8 (patch) | |
| tree | 85ecd65f78457ede14d7fbaf85c78280aad01b59 /doc/ARCHITECTURE.md | |
| parent | c784f8e1472991b8f4c35136b3468f3bfc6c37a7 (diff) | |
docs: Condense essential context files (856→599 lines)
Extract detailed examples and untriaged tasks to on-demand docs.
Created BACKLOG.md, ARCHITECTURE.md, CODING_STYLE.md, TOOLS_REFERENCE.md.
Reduces always-loaded token budget by 30% while preserving all information.
Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
Diffstat (limited to 'doc/ARCHITECTURE.md')
| -rw-r--r-- | doc/ARCHITECTURE.md | 60 |
1 files changed, 60 insertions, 0 deletions
diff --git a/doc/ARCHITECTURE.md b/doc/ARCHITECTURE.md new file mode 100644 index 0000000..1a32300 --- /dev/null +++ b/doc/ARCHITECTURE.md @@ -0,0 +1,60 @@ +# Architectural Overview + +Detailed system architecture for the 64k demo project. + +--- + +## 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 FFT-based IDCT (O(N log N)). Stereo output (32kHz, 16-bit, interleaved L/R). Uses orthonormal DCT-II/DCT-III transforms with Numerical Recipes reordering method. + +### Variable Tempo +Music time abstraction with configurable tempo_scale. Tempo changes don't affect pitch. + +### Event-Based Tracker +Individual TrackerEvents trigger as separate voices with dynamic beat calculation. Notes within patterns respect tempo scaling. + +### Backend Abstraction +`AudioBackend` interface with `MiniaudioBackend` (production), `MockAudioBackend` (testing), and `WavDumpBackend` (offline rendering). + +### Dynamic Updates +Double-buffered spectrograms for live thread-safe updates. + +### Procedural Library +Melodies and spectral filters (noise, comb) generated at runtime. + +### Pattern System +TrackerPatterns contain lists of TrackerEvents (beat, sample_id, volume, pan). Events trigger individually based on elapsed music time. |
