# 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.)
- [x] 9. work on the compact in-line and off-line asset system (@ASSET_SYSTEM.md)

## Session Decisions and Current State

### Asset Management System:
- **Architecture**: Implemented a C++ tool (`asset_packer`) that bundles external files into the binary.
- **Descriptors**: Assets are defined in `assets/final/assets.txt` with optional compression settings.
- **Runtime Access**: Provides a type-safe `AssetId` enum and `GetAsset` function for retrieving raw byte data at runtime.
- **Integration**: Fully integrated into the CMake build process with automatic header/source generation.
- **Lazy Decompression**: Scaffolding implemented for future on-demand decompression support.

### 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.
- **Peak Detection**: Real-time output peak detection with exponential decay for smooth visual synchronization.
- **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.
- `asset_packer`: A build-time tool for embedding assets into the binary.

### 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.
- **Visuals**: Pulsating heptagon synchronized with audio peaks, with automatic aspect ratio correction.

### Coding Style:
- **Standard**: Adopted a consistent coding style enforced by `.clang-format`.
- **Rules**: 2-space indentation, no tabs, 80-column line limit.
- **Headers**: Mandatory 3-line descriptive header at the top of every `.h` and `.cc` file.
- **File Extension**: All C++ source files renamed from `.cpp` to `.cc`.

### Platform & Input:
- **Windowing**: Uses GLFW for cross-platform window management.
- **Input**: Supports 'Esc' and 'Q' for quitting, and 'F' for toggling fullscreen.

### Development Workflow:
- **Commit Policy**: Explicit rule to always run the full test suite before preparing any commit, documented in `CONTRIBUTING.md`.
- **Testing**: Comprehensive test suite including `AssetManagerTest`, `SynthEngineTest`, `HammingWindowTest`, and `SpectoolEndToEndTest`.