# 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

### Next Up
- **Task #8: Implement Final Build Stripping**
    - [ ] Define and document a consistent set of rules for code stripping under the `STRIP_ALL` macro.
    - [ ] Remove unused functions, strip debug fields from structs, simplify code paths.
    - [ ] Verify no useless printf() or std::cout in final code.

- **Task #20: Code & Platform Hygiene**
    - [ ] Gather all cross-compile and platform-specific conditional code into `platform.h`.
    - [ ] Refactor `platform_init()` to return `PlatformState` directly.
    - [ ] Consolidate WebGPU header inclusions.

- **Task #21: Shader Optimization**
    - [ ] Use macros or code generation to factorize common WGSL code (normals, bump, lighting).
    - [ ] Implement tight ray-marching bounds (min/max t) derived from proxy hull hits.

### Future Goals
- **Task #5: Implement Spectrogram Editor**
    - [ ] Develop a web-based tool (`tools/editor`) for creating and editing `.spec` files visually.
- **Task #18: 3D System Enhancements**
    - [ ] **Blender Exporter**: Convert Blender scenes to internal asset format.
    - [ ] **GPU BVH & Shadows**: Optimize scene queries with a GPU-based BVH.
- **Phase 2: Advanced Size Optimization**
    - [ ] Replace GLFW with minimal native Windows API.
    - [ ] Quantize spectrograms to logarithmic frequency and uint16_t.
    - [ ] CRT replacement investigation.

### Recently Completed
- **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.
- **Tight Proxy Hulls**: Optimized Torus proxy geometry and debug wireframes.
- **Procedural Textures**: Restored floor grid and SDF bump mapping.

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