diff options
| author | skal <pascal.massimino@gmail.com> | 2026-02-09 19:34:46 +0100 |
|---|---|---|
| committer | skal <pascal.massimino@gmail.com> | 2026-02-09 19:34:46 +0100 |
| commit | f449fe7f78e059d455dfefcf4b09d763363f6344 (patch) | |
| tree | 0a1e6ebfc42025e4e72200d3c34e2bf799a32aa8 /doc/HEADLESS_MODE.md | |
| parent | dd42eeef53df8ea36f436986f915f29986c094a3 (diff) | |
feat: Add headless mode for testing without GPU
Implements DEMO_HEADLESS build option for fast iteration cycles:
- Functional GPU/platform stubs (not pure no-ops like STRIP_EXTERNAL_LIBS)
- Audio and timeline systems work normally
- No rendering overhead
- Useful for CI, audio development, timeline validation
Files added:
- doc/HEADLESS_MODE.md - Documentation
- src/gpu/headless_gpu.cc - Validated GPU stubs
- src/platform/headless_platform.cc - Time simulation (60Hz)
- scripts/test_headless.sh - End-to-end test script
Usage:
cmake -B build_headless -DDEMO_HEADLESS=ON
cmake --build build_headless -j4
./build_headless/demo64k --headless --duration 30
Progress printed every 5s. Compatible with --dump_wav mode.
handoff(Claude): Task #76 follow-up - headless mode complete
Diffstat (limited to 'doc/HEADLESS_MODE.md')
| -rw-r--r-- | doc/HEADLESS_MODE.md | 58 |
1 files changed, 58 insertions, 0 deletions
diff --git a/doc/HEADLESS_MODE.md b/doc/HEADLESS_MODE.md new file mode 100644 index 0000000..35098b1 --- /dev/null +++ b/doc/HEADLESS_MODE.md @@ -0,0 +1,58 @@ +// Headless Mode Documentation +// Workspace: demo (shared across all workspaces) + +# Headless Mode + +Minimal GPU/platform stubs for testing without graphics. + +## Use Cases + +- CI/CD without GPU +- Audio/tracker iteration +- Timeline validation +- Fast testing cycles + +## Build + +```bash +cmake -B build_headless -DDEMO_HEADLESS=ON +cmake --build build_headless -j4 +``` + +Or use the test script: +```bash +./scripts/test_headless.sh +``` + +## Usage + +```bash +# 30s simulation (default) +./build_headless/demo64k --headless + +# Custom duration +./build_headless/demo64k --headless --duration 60 + +# Audio validation +./build_headless/demo64k --dump_wav test.wav +``` + +Progress printed every 5s. + +## Implementation + +- **GPU stub:** Validates lifecycle, maintains MainSequence +- **Platform stub:** Simulates 60Hz time progression +- **Main loop:** Audio updates without rendering + +## vs STRIP_EXTERNAL_LIBS + +| Feature | HEADLESS | STRIP_EXTERNAL_LIBS | +|---------|----------|---------------------| +| Compiles | Yes | Yes | +| Runs | Yes | No | +| Audio | Full | No-op | +| Timeline | Full | No | +| Tests | Pass | Fail | + +See `src/gpu/headless_gpu.cc` and `src/platform/headless_platform.cc` for details. |
