Skip to content

Add headless / offscreen mode to Vulkan backend and render tests - #274

Merged
fabmax merged 1 commit into
mainfrom
vk-headless-mode
Oct 25, 2026
Merged

fabmax merged 1 commit into
mainfrom
vk-headless-mode

Conversation

@fabmax

@fabmax fabmax commented Oct 25, 2026

Copy link
Copy Markdown
Collaborator

Vulkan backend:

  • Extract frame output abstraction (FrameOutput) from Swapchain and move per-frame fences into FrameSync, so that the backend can run without a surface / swapchain
  • Add HeadlessOutput, which blits the screen pass output into an image and reads it back via per-frame readback buffers (sync or async)
  • Make surface, present queue and swapchain extension optional
  • Track validation layer errors in Instance (used by render tests)
  • Add VkSetup.preferredDeviceType, forceDeviceName substring matching
  • Fix device selection falling back to first device instead of first suitable device, skip resolve image with numSamples = 1, fix source layout restore in ImageVk.copyFromImage

Headless window subsystem (platform/headless):

  • HeadlessWindowSubsystem with Manual (tests) and Continuous (embedding) frame loops, frame capture / frame listeners, optional fixed time step
  • Thread-safe resize and input injection (HeadlessWindow, HeadlessInput)
  • Fails with a clear message if used with a non-Vulkan backend

Render tests:

  • Headless render test harness comparing frames against reference images, failing on validation errors
  • Separate renderTest gradle task (not part of build / desktopTest)
  • Manually triggered GitHub workflow running tests on lavapipe

Vulkan backend:
- Extract frame output abstraction (FrameOutput) from Swapchain and move
  per-frame fences into FrameSync, so that the backend can run without
  a surface / swapchain
- Add HeadlessOutput, which blits the screen pass output into an image
  and reads it back via per-frame readback buffers (sync or async)
- Make surface, present queue and swapchain extension optional
- Track validation layer errors in Instance (used by render tests)
- Add VkSetup.preferredDeviceType, forceDeviceName substring matching
- Fix device selection falling back to first device instead of first
  suitable device, skip resolve image with numSamples = 1, fix source
  layout restore in ImageVk.copyFromImage

Headless window subsystem (platform/headless):
- HeadlessWindowSubsystem with Manual (tests) and Continuous (embedding)
  frame loops, frame capture / frame listeners, optional fixed time step
- Thread-safe resize and input injection (HeadlessWindow, HeadlessInput)
- Fails with a clear message if used with a non-Vulkan backend

Render tests:
- Headless render test harness comparing frames against reference
  images, failing on validation errors
- Separate renderTest gradle task (not part of build / desktopTest)
- Manually triggered GitHub workflow running tests on lavapipe

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@fabmax
fabmax merged commit bdf39fc into main Oct 25, 2026
2 checks passed
@fabmax
fabmax deleted the vk-headless-mode branch October 25, 2026 14:12
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant