# 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
- **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 #20: Platform & Code Hygiene** (Completed)
    - [x] Gather all cross-compile and platform-specific conditional code into `platform.h`.
    - [x] Refactor `platform_init()` and `platform_poll()` for cleaner abstraction.
    - [x] Consolidate WebGPU header inclusions.
    - [ ] **Task #34: Full STL Removal**: Remove `std::map`/`std::vector` from remaining paths (Deferred to Phase 2).

- **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.)