Skip to content

feat: Headless software surface for golden image testing #256

Description

@kolkov

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)

Metadata

Metadata

Assignees

No one assigned

    Type

    No type

    Fields

    No fields configured for issues without a type.

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions