# 64k Demo Project

Goal:
- Produce a <=64k native demo binary
- Same C++ codebase for Windows, macOS, Linux

Graphics:
- WebGPU via wgpu-native
- WGSL shaders
- Single fullscreen pass initially

Audio:
- 32 kHz, 16-bit mono
- Procedurally generated samples
- No decoding, no assets

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

Style:
- Demoscene
- No engine abstractions

Incoming tasks in no particular order:
- [x] 1. add a fullscreen mode (as command line option)
- [x] 2. parse the keyboard key. Exit the demo when 'esc' is pressed. Toggle full-screen when 'f' is pressed.
- [x] 3. add binary crunchers for all platforms
- 4. add cross-compilation for PC+linux (x86_64) and PC+Windows (.exe binary)
- 5. implement a spectrogram editor for representing .spec with elementary
     shapes (bezier curves, lines, random noise, rectangles...)  as a mean
     of compression
- 6. add a scripting tool to edit the demo (compiled into the binary at the end)
- [x] 7. compile wgpu-native in optimized mode (not unoptimized)
- [x] 8. add a #define STRIP_ALL to remove all unnecessary code for the final build
     (for instance, command-line args parsing, or unnecessary options, constant
      parameters to function calls, etc.)
- [ ] 9. work on the compact in-line and off-line asset system (@ASSET_SYSTEM.md)
- 9. work on the compact in-line and off-line asset system (@ASSET_SYSTEM.md)

## Session Decisions and Current State

### Audio Engine (Synth):
- **Architecture**: Real-time additive synthesis from spectrograms using Inverse Discrete Cosine Transform (IDCT).
- **Dynamic Updates**: Implemented a double-buffering (flip-flop) mechanism for thread-safe, real-time updates of spectrogram data. The main thread writes to a back buffer, which is then atomically swapped to become the active front buffer for the audio thread, avoiding real-time allocations and locks.
- **Sample Generation**: Samples are generated in the frequency domain (spectrograms) and converted to time-domain audio using IDCT with a Hamming window.
- **Audio Input Support (`spectool`)**: Supports WAV and MP3 input for analysis (leveraging `miniaudio`'s built-in decoders). AAC is explicitly *not* supported due to complexity and dependency constraints.

### Tools Developed:
- `spectool`: A command-line tool for analyzing WAV/MP3 files into `.spec` spectrogram format and for playing back `.spec` files through the synth engine.
- `specview`: A command-line tool for visualizing `.spec` spectrogram files in ASCII art.

### WebGPU Integration:
- **Strategy**: Uses system-installed `wgpu-native` (e.g., via Homebrew) for the implementation.
- **Surface Creation**: Uses `glfw3webgpu` helper library to abstract platform-specific surface creation from GLFW windows, keeping the codebase clean and cross-platform.
- **Headers**: Uses standard `<webgpu.h>` provided by the system install.

### Coding Style:
- **Standard**: Adopted a consistent coding style enforced by `.clang-format`.
- **Rules**: 2-space indentation, no tabs, 80-column line limit.
- **File Extension**: All C++ source files renamed from `.cpp` to `.cc`.

### Development Workflow:
- **Commit Policy**: Explicit rule to always run the full test suite before preparing any commit, documented in `CONTRIBUTING.md`.