summaryrefslogtreecommitdiff
path: root/doc/HEADLESS_MODE.md
diff options
context:
space:
mode:
authorskal <pascal.massimino@gmail.com>2026-02-09 19:34:46 +0100
committerskal <pascal.massimino@gmail.com>2026-02-09 19:34:46 +0100
commitf449fe7f78e059d455dfefcf4b09d763363f6344 (patch)
tree0a1e6ebfc42025e4e72200d3c34e2bf799a32aa8 /doc/HEADLESS_MODE.md
parentdd42eeef53df8ea36f436986f915f29986c094a3 (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.md58
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.