# 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 (eliminates initialization fragility)

Constraints:
- Size-sensitive
- Minimal dependencies
- Explicit control over all allocations

Style:
- Demoscene
- No engine abstractions

---
## Project Roadmap

**Note:** For detailed history of recently completed milestones, see `COMPLETED.md`.

### Current Status
- Audio system: Stable with real-time peak tracking, variable tempo support, comprehensive test coverage
- Build system: Optimized with proper asset dependency tracking
- Shader system: Modular with comprehensive compilation tests
- 3D rendering: Hybrid SDF/rasterization with BVH acceleration

---
## Next Up

- **Task #5: Spectral Brush Editor** [IN PROGRESS - February 6, 2026]
    - Create web-based tool for procedurally tracing audio spectrograms
    - Replace large .spec assets with tiny C++ code (50-100× compression)
    - Phase 1: C++ runtime (`spectral_brush.h/cc` - Bezier curves + Gaussian profiles)
    - Phase 2: Editor UI (HTML/JS canvas, dual-layer visualization, keyboard shortcuts)
    - Phase 3: File I/O (load .wav/.spec, export procedural_params.txt + C++ code)
    - See `doc/SPECTRAL_BRUSH_EDITOR.md` for complete design

- **Task #18: 3D System Enhancements**
    - [ ] **Task #18.0: Basic OBJ Asset Pipeline**: Implement `ASSET_MESH` type, `asset_packer` OBJ support, and `Renderer3D` mesh rendering.
    - [ ] **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.

- **Visuals & Content**
    - [ ] **Task #52: Procedural SDF Font**: Minimal bezier/spline set for [A-Z, 0-9] and SDF rendering.
    - [ ] **Task #53: Particles Shader Polish**: Improve visual quality of particles.
    - [ ] **Task #55: SDF Random Planes Intersection**: Implement `sdPolyhedron` (crystal/gem shapes) via plane intersection.

- **Tooling & Optimization**
    - [ ] **Task #54: Tracy Integration**: Integrate Tracy debugger for performance profiling.

---
## Future Goals
- **Task #36: Blender Exporter**: Create script to export scenes to internal binary format. (Deprioritized)
- **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 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.