# 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

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

## Style
- Demoscene
- No engine abstractions

---

## Current Status

- Audio system: Sample-accurate synchronization. Hardware playback time as master clock. Variable tempo support. Pipeline optimized (Task #72): Zero heap allocations per frame, direct ring buffer writes. Comprehensive test coverage.
- Build system: Optimized with proper asset dependency tracking
- Shader system: Parameterization complete (UniformHelper, .seq syntax). Modular with compilation tests. WGSL composability improved (`math/common_utils.wgsl`).
- 3D rendering: Hybrid SDF/rasterization with BVH acceleration and binary scene loader. Object data loading pipeline enhanced.
- Asset pipeline: Blender export script and binary scene ingestion
- Error handling: Dual macro system (`FATAL_XXX` for programming errors, `CHECK_RETURN` for recoverable errors)
- Testing: **32/33 tests passing (97%)** - DemoEffectsTest fails due to wgpu_native library bug

---

## Next Up

- **Task #5: Spectral Brush Editor** [IN PROGRESS]
    - Web-based tool for procedurally tracing audio spectrograms
    - Replace large .spec assets with tiny C++ code (50-100× compression)
    - See TODO.md and `doc/SPECTRAL_BRUSH_EDITOR.md`

- **Visuals & Content**
    - Task #52: Procedural SDF Font
    - Task #53: Particles Shader Polish
    - Task #55: SDF Random Planes Intersection

- **Tooling & Optimization**
    - Task #54: Tracy Integration

---

## Design Docs Quick Reference

For detailed documentation, use Read tool to load specific docs:

- **doc/TRACKER.md**: Audio pattern system with unit-less timing
- **doc/3D.md**: Hybrid SDF raymarching with BVH acceleration
- **doc/ASSET_SYSTEM.md**: Build-time asset packer with 16-byte alignment
- **doc/BUILD.md**: Multi-platform builds (Debug/STRIP_ALL/FINAL_STRIP)
- **doc/SPECTRAL_BRUSH_EDITOR.md**: Web tool for tracing spectrograms
- **doc/SEQUENCE.md**: .seq timeline format with BPM notation
- **doc/MASKING_SYSTEM.md**: Auxiliary texture registry
- **doc/SCENE_FORMAT.md**: Binary scene format (SCN1)
- **doc/test_demo_README.md**: 16s audio/visual sync test tool
- **doc/CONTEXT_MAINTENANCE.md**: Context hygiene protocol

---

## Recently Completed (February 2026)

- **WGSL Uniform Buffer Validation (Task #75)** (Feb 9) - Standardized uniform buffer layout. Validation tool integrated into build. All effects use `CommonPostProcessUniforms` (binding 2) + effect-specific params (binding 3). Added `UNIFORM_BUFFER_GUIDELINES.md`.

- **Uniform Buffer Alignment (Task #74)** (Feb 9) - Fixed WGSL `vec3<f32>` alignment issues. Demo runs with 0 validation errors.

- **Shader Parametrization (Task #73)** (Feb 8) - Full uniform parameter system with .seq syntax. FlashEffect, ChromaAberrationEffect, GaussianBlurEffect support dynamic parameters. Size: ~400-500 bytes.

---

For detailed architecture, see `doc/ARCHITECTURE.md`.

For completed tasks history, see `doc/COMPLETED.md` and git history.