Part of gogpu/gogpu#373 — Headless Golden Image Testing (ADR-053), Phase 1.
Summary
Add headless mode to the software HAL backend — render to pixel buffer without requiring a platform window (HWND, X11 Window, Wayland wl_surface).
This is the foundation for golden image testing in CI (ADR-053 in gogpu). GitHub Actions runners have no GPU or display — headless software rendering is the only path for automated visual verification.
Problem
Software backend currently requires a platform surface to render. CreateSurface needs a window handle. CI runners cannot create windows → no visual tests.
Proposed Solution
Add CreateHeadlessSurface(width, height) that:
- Allocates internal BGRA buffer (same as current software surface)
- Supports normal Acquire → Render → Present cycle
- Present writes to buffer instead of BitBlt/SHM/XPutImage
ReadPixels() []byte extracts rendered RGBA data
The software HAL already has the full rendering pipeline (SPIR-V interpreter, rasterizer, blending). Headless mode only changes the output: buffer instead of window.
Key Files
hal/software/surface.go — add headless surface variant
hal/software/present.go — add headless present path (buffer capture)
Testing
- Unit: create headless surface, render solid color, verify pixel values
- Integration: render triangle via standard pipeline, verify output matches expected
Blocked By
Nothing — this is Phase 1 (foundation).
Blocks
- gogpu golden test harness (Phase 2)
- gg 2D rendering goldens (Phase 3)
- ui widget snapshot goldens (Phase 4)
Part of gogpu/gogpu#373 — Headless Golden Image Testing (ADR-053), Phase 1.
Summary
Add headless mode to the software HAL backend — render to pixel buffer without requiring a platform window (HWND, X11 Window, Wayland wl_surface).
This is the foundation for golden image testing in CI (ADR-053 in gogpu). GitHub Actions runners have no GPU or display — headless software rendering is the only path for automated visual verification.
Problem
Software backend currently requires a platform surface to render.
CreateSurfaceneeds a window handle. CI runners cannot create windows → no visual tests.Proposed Solution
Add
CreateHeadlessSurface(width, height)that:ReadPixels() []byteextracts rendered RGBA dataThe software HAL already has the full rendering pipeline (SPIR-V interpreter, rasterizer, blending). Headless mode only changes the output: buffer instead of window.
Key Files
hal/software/surface.go— add headless surface varianthal/software/present.go— add headless present path (buffer capture)Testing
Blocked By
Nothing — this is Phase 1 (foundation).
Blocks