fix(window): size the swapchain for its present mode, and key frames in flight by frame instead of image

Window
- CreateSwapchain asked for exactly numFrames (3) images whatever the
  surface said, read them into a three-element array, and keyed the
  command buffers, the fences and the descriptor-heap copy holding "its"
  swapchain image by the acquired image index. A swapchain of another
  size fell back to FIFO (asked for MAILBOX or IMMEDIATE) or threw, and a
  surface whose minimum is above three got a create info below it
  (#160). Mesa's MAILBOX needs four images: Turnip on phoc, llvmpipe on
  any Wayland compositor.
- The present mode is picked first, then the swapchain is sized by
  SwapchainCapabilities: the surface's counts for that mode where the
  instance has surface_maintenance1. With swapchain_maintenance1 the
  swapchain names its mode (VkSwapchainPresentModesCreateInfoKHR), which
  is what makes the mode's own count the one that applies, at creation and
  to the forward progress of a UINT64_MAX acquire; without it the stricter
  of the mode's and the surface's counts for all modes. It asks for
  numFrames or that minimum where more, never past the maximum
  (SwapchainMinImageCount). Turnip's FIFO keeps its three images and
  MAILBOX gets four. The FIFO fallback and presentModeUnfit are gone.
- images, imageViewInfos (was imageViews: they are create-infos), the made
  imageViews that descriptor sets take, imageInitialised and the
  render-finished semaphores are per image, as many as the driver made.
  The views are made once per swapchain. The semaphores only grow, since
  a present of the old swapchain may still wait on one.
- Frames in flight stay numFrames, keyed by currentFrame, frameCounter %
  numFrames: the command buffer, the fence, the acquire semaphore, the
  heap copy (or set), RenderingElement3D::tlases, the frameIdx a pass is
  recorded with. currentImage is the acquired image. currentBuffer is
  gone, so code that used it stops compiling instead of picking the wrong
  one; RenderPass::Record's frameIdx keeps its name and is now the frame
  slot, as RenderPass.cppm says.
- The frame's fence is waited before the acquire. The acquire semaphores
  need no spare then, and a frame waits for exactly the one numFrames
  before it, which the deletion queue and the staging rings count on and
  fences keyed by image did not promise once images come back out of
  order. The swapchain slots are written before the fence is reset.
- From the acquire to the present the window is recording: a Resize or
  SetPresentMode from a listener (a VSync key ticked in onUpdate) takes
  effect after the present, through RebuildSwapchain, together with a
  present that found the swapchain out of date. Rebuilding mid-frame used
  to destroy the image the frame was drawing into; with images sized per
  swapchain it would also index past the new one's end.

DescriptorHeapVulkan
- Frames and images pair up differently from frame to frame, so no heap
  copy can keep one swapchain image. AddSwapchainSlot(slot, window) lists
  an image slot as that window's swapchain image, and Window::Render
  writes the image a frame acquired into its window's listed slots in that
  frame's copy, or its set, before onUpdate, skipping a slot that holds it
  already. A slot is one window's, so two windows can share a heap without
  writing each other's slots under each other's frames in flight. A slot
  listed during a frame its window records is written at once. A slot past
  the heap's image slots, an empty ImageSlot's 0xFFFF among them, is
  refused. Freeing a slot unlists it, as does initialising the heap in
  either binding model. WriteImageSet, the one use of which this
  replaces, is gone, and with it the per-frame dimension of setImageViews.

Device
- VK_KHR_surface_maintenance1 (or EXT) and VK_KHR_get_surface_capabilities2
  are enabled where the loader has them (surfaceMaintenance1Supported,
  vkGetPhysicalDeviceSurfaceCapabilities2KHR), and the matching
  swapchain_maintenance1 with its feature where the device has it
  (swapchainMaintenance1Supported).
- DistinctGpus groups the physical devices by GPU as CRAFTER_GRAPHICS_DEVICE
  numbers them, for ChooseGpu and tests.

UI
- UIRenderer lists its output slot instead of writing every copy itself,
  and again on every resize; the resize listener is gone on both
  backends. The headers' frameIdx is currentFrame.

Examples
- VulkanTriangle, Sponza, SponzaBench and RTVolume list their output slot
  and write only the per-frame TLASes. They wrote imageViews[f] into copy
  f once, which a resize left pointing at destroyed images.

Tests
- SwapchainImageCount: SwapchainMinImageCount on the numbers drivers
  report; every offered mode keeps its mode and gets what the window asks
  for; every frame presents the colour it drew, read back a texel per
  frame; a switch and a resize asked for during a frame wait for its
  present; a slot listed during a frame holds its image at once; two
  windows on one heap draw their own colours. The frame checks run again
  in child processes, through CRAFTER_GRAPHICS_DEVICE, on a GPU whose
  swapchains have more images than frames (this one, else llvmpipe), in
  each binding model the parent didn't cover; a child skips only for a GPU
  that can't run the library, and checks it runs the model it was asked
  for.
- FrameLoopSync checks the frame slot follows the frame counter and counts
  the swapchain's own images. HeapASRead, HeapDynamicIndexHit and
  RTPassPushData list their swapchain slot and drop their resize rewrites.

Docs
- README, AGENTS.md and AGENTS.consumer.md: frames and images, the
  swapchain slots, rebuilds held to the present, the new optional groups.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
Jorijn van der Graaf 2026-10-31 08:51:18 +01:00
commit 234fcce099
Signed by: jorijnvdgraaf
GPG key ID: 2937E59CDCC1BCFB
29 changed files with 1378 additions and 550 deletions

View file

@ -538,20 +538,18 @@ Window::Window(std::uint32_t width, std::uint32_t height) : width(width), height
Device::CheckVkResult(vkAllocateCommandBuffers(Device::device, &cmdBufAllocateInfo, drawCmdBuffers));
// Per-frame-in-flight synchronisation objects (issue #40). The fences are
// created signaled so the first wait on each image's fence — before that
// image has ever been submitted — returns immediately instead of
// created signaled so the first wait on each frame slot's fence — before
// that slot has ever been submitted — returns immediately instead of
// deadlocking. The submitInfo is rebuilt per frame in Render() now that
// the wait/signal semaphores vary by frame.
// the wait/signal semaphores vary by frame. The per-image render-finished
// semaphores come with the images, in CreateSwapchain.
VkSemaphoreCreateInfo semaphoreCreateInfo {};
semaphoreCreateInfo.sType = VK_STRUCTURE_TYPE_SEMAPHORE_CREATE_INFO;
VkFenceCreateInfo fenceCreateInfo {};
fenceCreateInfo.sType = VK_STRUCTURE_TYPE_FENCE_CREATE_INFO;
fenceCreateInfo.flags = VK_FENCE_CREATE_SIGNALED_BIT;
for (std::uint8_t i = 0; i < numFrames; i++) {
Device::CheckVkResult(vkCreateSemaphore(Device::device, &semaphoreCreateInfo, nullptr, &renderFinishedSemaphores[i]));
Device::CheckVkResult(vkCreateFence(Device::device, &fenceCreateInfo, nullptr, &waitFences[i]));
}
for (std::uint8_t i = 0; i < numAcquireSemaphores; i++) {
Device::CheckVkResult(vkCreateSemaphore(Device::device, &semaphoreCreateInfo, nullptr, &imageAcquiredSemaphores[i]));
}
@ -562,7 +560,7 @@ Window::Window(std::uint32_t width, std::uint32_t height) : width(width), height
// Per-frame info structs: everything that never varies between frames is
// set here once. Render() patches the barriers' image/oldLayout and the
// sync handles that follow currentBuffer/frameCounter (submitInfo's
// sync handles that follow currentFrame/currentImage (submitInfo's
// wait/signal semaphores + command buffer, presentInfo's wait semaphore).
cmdBufInfo = {};
cmdBufInfo.sType = VK_STRUCTURE_TYPE_COMMAND_BUFFER_BEGIN_INFO;
@ -617,15 +615,15 @@ Window::Window(std::uint32_t width, std::uint32_t height) : width(width), height
};
// pImageIndices/pSwapchains point at members, so they follow value changes
// (currentBuffer each frame, swapChain across recreation) on their own. The
// (currentImage each frame, swapChain across recreation) on their own. The
// wait semaphore is the per-image render-finished semaphore, patched per
// frame in Render() (it follows currentBuffer).
// frame in Render() (it follows currentImage).
presentInfo = {};
presentInfo.sType = VK_STRUCTURE_TYPE_PRESENT_INFO_KHR;
presentInfo.pNext = NULL;
presentInfo.swapchainCount = 1;
presentInfo.pSwapchains = &swapChain;
presentInfo.pImageIndices = &currentBuffer;
presentInfo.pImageIndices = &currentImage;
presentInfo.waitSemaphoreCount = 1;
}
@ -636,12 +634,17 @@ Window::~Window() {
if (Device::device != VK_NULL_HANDLE) {
if (drawCmdBuffers[0] != VK_NULL_HANDLE) vkFreeCommandBuffers(Device::device, Device::commandPool, numFrames, drawCmdBuffers);
for (std::uint8_t i = 0; i < numFrames; i++) {
if (renderFinishedSemaphores[i]) vkDestroySemaphore(Device::device, renderFinishedSemaphores[i], nullptr);
if (waitFences[i]) vkDestroyFence(Device::device, waitFences[i], nullptr);
}
for (std::uint8_t i = 0; i < numAcquireSemaphores; i++) {
if (imageAcquiredSemaphores[i]) vkDestroySemaphore(Device::device, imageAcquiredSemaphores[i], nullptr);
}
for (VkSemaphore semaphore : renderFinishedSemaphores) {
vkDestroySemaphore(Device::device, semaphore, nullptr);
}
renderFinishedSemaphores.clear();
for (VkImageView view : imageViews) {
vkDestroyImageView(Device::device, view, nullptr);
}
imageViews.clear();
if (swapChain != VK_NULL_HANDLE) vkDestroySwapchainKHR(Device::device, swapChain, nullptr);
swapChain = VK_NULL_HANDLE;
}
@ -726,6 +729,15 @@ void Window::Resize(std::uint32_t newWidth, std::uint32_t newHeight) {
// Skip degenerate resizes. Win32 minimised windows give (0, 0); Wayland
// sometimes echoes the current size in a configure.
if (newWidth == 0 || newHeight == 0) return;
// A listener of the frame being recorded asked: the rest of that frame
// still draws into an image of the current swapchain at the current
// size, so the size changes once the frame has been presented. The last
// size asked for wins, the current one too.
if (recording) {
deferredWidth = newWidth;
deferredHeight = newHeight;
return;
}
if (newWidth == width && newHeight == height) return;
// Win32 fires WM_SIZE synchronously inside CreateWindowEx (before the
// constructor's CreateSwapchain). Defer the first resize to that
@ -739,9 +751,13 @@ void Window::Resize(std::uint32_t newWidth, std::uint32_t newHeight) {
width = newWidth;
height = newHeight;
RebuildSwapchain();
}
// Caller (configure handler / WM_SIZE) runs between frames, but be
// defensive: ensure no in-flight commands reference the old swapchain.
void Window::RebuildSwapchain() {
// Configure handlers and WM_SIZE run between frames, and a frame that
// asked waited for its present, but frames may still be in flight: none
// may still use the old swapchain.
Device::CheckVkResult(vkQueueWaitIdle(Device::queue));
// The queue is idle, so every deferred resource is now safe to free
// regardless of its retire frame (issue #101).
@ -771,15 +787,17 @@ void Window::RecreateSwapchainAndImages() {
void Window::SetPresentMode(PresentMode mode) {
presentMode = mode;
presentModeUnfit = false;
// A window without a swapchain yet picks the mode up when it makes one.
if (swapChain == VK_NULL_HANDLE) return;
// The mode is fixed when a swapchain is made, so make a new one, as
// Resize does: nothing in flight may still use the old images.
Device::CheckVkResult(vkQueueWaitIdle(Device::queue));
Device::DrainDeletions();
RecreateSwapchainAndImages();
onResize.Invoke();
// Resize does: after the present when a frame is being recorded (a
// VSync key ticked from onUpdate), since the rest of that frame draws
// into the old swapchain's image.
if (recording) {
swapchainRebuildPending = true;
return;
}
RebuildSwapchain();
}
void Window::SetTitle(const std::string_view title) {
@ -1255,37 +1273,61 @@ namespace {
}
void Window::Render() {
// This frame's slot among the numFrames in flight. Its command buffer,
// descriptor-heap copy and acquire semaphore were last used numFrames
// frames ago: wait for that submission's fence before touching any of
// them. This — not a full-queue wait-idle — is what bounds
// frames-in-flight and gives the CPU/GPU overlap. The wait comes before
// the acquire and is keyed by frame, not by the acquired image as when
// the two were one index, so the swapchain may have any number of images
// (#160) and a frame still waits for exactly the one numFrames before it,
// which the deletion queue and the staging rings count on.
currentFrame = static_cast<std::uint32_t>(frameCounter % numFrames);
Device::CheckVkResult(vkWaitForFences(Device::device, 1, &waitFences[currentFrame], VK_TRUE, UINT64_MAX));
// Acquire the next image from the swap chain. If the surface has
// changed size out from under us (compositor/Win32 resize delivered
// between Render calls), recreate and retry once.
// Pick this frame's acquire semaphore from a free-running CPU counter: the
// image index (currentBuffer) isn't known until acquire returns, so the
// acquire's signal semaphore can't be keyed by the image.
const std::uint32_t acquireSlot = static_cast<std::uint32_t>(frameCounter % numAcquireSemaphores);
VkSemaphore imageAcquired = imageAcquiredSemaphores[acquireSlot];
VkSemaphore imageAcquired = imageAcquiredSemaphores[currentFrame];
{
VkResult acquire = vkAcquireNextImageKHR(Device::device, swapChain, UINT64_MAX,
imageAcquired, (VkFence)nullptr, &currentBuffer);
imageAcquired, (VkFence)nullptr, &currentImage);
if (acquire == VK_ERROR_OUT_OF_DATE_KHR) {
Device::CheckVkResult(vkQueueWaitIdle(Device::queue));
Device::DrainDeletions();
RecreateSwapchainAndImages();
onResize.Invoke();
acquire = vkAcquireNextImageKHR(Device::device, swapChain, UINT64_MAX,
imageAcquired, (VkFence)nullptr, &currentBuffer);
imageAcquired, (VkFence)nullptr, &currentImage);
}
if (acquire != VK_SUBOPTIMAL_KHR) {
Device::CheckVkResult(acquire);
}
}
// drawCmdBuffers[currentBuffer] and this image's descriptor-heap slot are
// about to be re-recorded. Wait on the fence guarding this image's
// previous submission (keyed by image index, since acquire returns an
// arbitrary index), then reset it for this submit. This — not a full-queue
// wait-idle — is what bounds frames-in-flight and gives the CPU/GPU overlap.
Device::CheckVkResult(vkWaitForFences(Device::device, 1, &waitFences[currentBuffer], VK_TRUE, UINT64_MAX));
Device::CheckVkResult(vkResetFences(Device::device, 1, &waitFences[currentBuffer]));
// From here to the present the frame owns images[currentImage] and its
// heap copy: a Resize or SetPresentMode from a listener waits for the
// present (see the end of this function), and a swapchain slot listed
// now is written at once. The guard clears it on the way out of a throw
// too, so a failed frame doesn't hold every later rebuild back.
recording = true;
struct RecordingGuard {
bool& recording;
~RecordingGuard() { recording = false; }
} recordingGuard { recording };
// The image this frame draws into, at this window's swapchain slots, in
// this frame's copy of the heap (or its descriptor set), which the fence
// wait above freed. Before onUpdate and the passes, which record against
// it.
if (descriptorHeap) {
descriptorHeap->WriteSwapchainImage(*this);
}
// Reset for this frame's submit after the acquire, which can fail (and
// recreate the swapchain on the way), and the slot writes: a fence reset
// and then never submitted would hang the next wait on this slot.
Device::CheckVkResult(vkResetFences(Device::device, 1, &waitFences[currentFrame]));
// Now that a frame's fence has been waited, free any deferred resources
// whose retire frame has been reached (issue #101). frameCounter is bumped
@ -1293,19 +1335,19 @@ void Window::Render() {
// value entries enqueued this frame are tagged with.
Device::ReclaimDeletions();
Device::CheckVkResult(vkBeginCommandBuffer(drawCmdBuffers[currentBuffer], &cmdBufInfo));
Device::CheckVkResult(vkBeginCommandBuffer(drawCmdBuffers[currentFrame], &cmdBufInfo));
// On an image's first use after (re)creating the swapchain it is still in
// VK_IMAGE_LAYOUT_UNDEFINED; every subsequent frame leaves it in
// PRESENT_SRC_KHR. Transitioning from the wrong oldLayout is a validation
// error, so pick based on whether this image has been rendered before.
// The image was just acquired above, so touching it here is legal.
const bool firstUse = !imageInitialised[currentBuffer];
imageInitialised[currentBuffer] = true;
const bool firstUse = !imageInitialised[currentImage];
imageInitialised[currentImage] = true;
acquireBarrier.oldLayout = firstUse ? VK_IMAGE_LAYOUT_UNDEFINED
: VK_IMAGE_LAYOUT_PRESENT_SRC_KHR;
acquireBarrier.image = images[currentBuffer];
acquireBarrier.image = images[currentImage];
// Real per-pass stage union for this frame's passes — the swapchain image
// is only ever written by compute/RT (and possibly transfer), never by the
@ -1327,7 +1369,7 @@ void Window::Render() {
// The acquire->GENERAL transition only needs to be visible before the first
// pass writes the image, i.e. at the writer stages — not ALL_COMMANDS.
vkCmdPipelineBarrier(drawCmdBuffers[currentBuffer], VK_PIPELINE_STAGE_BOTTOM_OF_PIPE_BIT, swapWriterStages, 0, 0, nullptr, 0, nullptr, 1, &acquireBarrier);
vkCmdPipelineBarrier(drawCmdBuffers[currentFrame], VK_PIPELINE_STAGE_BOTTOM_OF_PIPE_BIT, swapWriterStages, 0, 0, nullptr, 0, nullptr, 1, &acquireBarrier);
// Synthesise key-repeat events before listeners run, so the focused
// widget's OnTextInput / OnKeyDown sees them in the same frame.
@ -1340,7 +1382,7 @@ void Window::Render() {
// Pass-side dispatches still run with the same heaps bound — moving
// the bind earlier doesn't change anything for them.
if (descriptorHeap) {
descriptorHeap->Bind(drawCmdBuffers[currentBuffer], currentBuffer);
descriptorHeap->Bind(drawCmdBuffers[currentFrame], currentFrame);
}
onUpdate.Invoke({startTime, startTime-lastFrameBegin});
@ -1360,7 +1402,7 @@ void Window::Render() {
(void)clearColor;
for (std::size_t i = 0; i < passes.size(); ++i) {
passes[i]->Record(drawCmdBuffers[currentBuffer], currentBuffer, *this);
passes[i]->Record(drawCmdBuffers[currentFrame], currentFrame, *this);
if (i + 1 < passes.size()) {
// Make pass i's writes to the swapchain image visible to pass i+1.
@ -1376,13 +1418,13 @@ void Window::Render() {
// default stage reports a union that names RAY_TRACING_SHADER.
const VkPipelineStageFlags srcStages = passes[i]->SwapchainStage() & Device::stageMask;
const VkPipelineStageFlags dstStages = passes[i + 1]->SwapchainStage() & Device::stageMask;
VkImageMemoryBarrier ib = BuildSwapchainInterPassBarrier(images[currentBuffer], srcStages, dstStages);
vkCmdPipelineBarrier(drawCmdBuffers[currentBuffer], srcStages, dstStages,
VkImageMemoryBarrier ib = BuildSwapchainInterPassBarrier(images[currentImage], srcStages, dstStages);
vkCmdPipelineBarrier(drawCmdBuffers[currentFrame], srcStages, dstStages,
0, 0, nullptr, 0, nullptr, 1, &ib);
}
}
presentBarrier.image = images[currentBuffer];
presentBarrier.image = images[currentImage];
// Mirror of the acquire barrier: srcAccessMask must be supported by the src
// stage mask (swapWriterStages). SHADER_WRITE alone is valid for COMPUTE/RT
@ -1395,7 +1437,7 @@ void Window::Render() {
std::optional<FrameCapture> capture;
VkPipelineStageFlags presentWaitStages = swapWriterStages;
if (pendingCapture) {
capture.emplace(RecordFrameCapture(drawCmdBuffers[currentBuffer], images[currentBuffer], width, height, swapWriterStages, presentBarrier.srcAccessMask));
capture.emplace(RecordFrameCapture(drawCmdBuffers[currentFrame], images[currentImage], width, height, swapWriterStages, presentBarrier.srcAccessMask));
presentWaitStages |= VK_PIPELINE_STAGE_TRANSFER_BIT;
capture->path = std::move(*pendingCapture);
pendingCapture.reset();
@ -1404,36 +1446,31 @@ void Window::Render() {
// The ->PRESENT_SRC transition only needs to wait on the stages that
// actually wrote the image (the per-pass union), not ALL_COMMANDS; present
// itself is gated by the render-finished semaphore, so dst stays BOTTOM.
vkCmdPipelineBarrier(drawCmdBuffers[currentBuffer], presentWaitStages, VK_PIPELINE_STAGE_BOTTOM_OF_PIPE_BIT, 0, 0, nullptr, 0, nullptr, 1, &presentBarrier);
vkCmdPipelineBarrier(drawCmdBuffers[currentFrame], presentWaitStages, VK_PIPELINE_STAGE_BOTTOM_OF_PIPE_BIT, 0, 0, nullptr, 0, nullptr, 1, &presentBarrier);
Device::CheckVkResult(vkEndCommandBuffer(drawCmdBuffers[currentBuffer]));
Device::CheckVkResult(vkEndCommandBuffer(drawCmdBuffers[currentFrame]));
// Patch the per-frame fields of the cached submitInfo/presentInfo (the
// invariant fields were set once in the constructor): submit waits on this
// frame's acquire semaphore and signals this image's render-finished
// semaphore, present waits on that same render-finished semaphore. The
// fence (keyed by image index) lets a future Render() reuse this image's
// command buffer + heap slot safely. The semaphore handles live in member
// arrays, so taking their addresses here is stable for the call.
submitInfo.pWaitSemaphores = &imageAcquiredSemaphores[acquireSlot];
submitInfo.pSignalSemaphores = &renderFinishedSemaphores[currentBuffer];
submitInfo.pCommandBuffers = &drawCmdBuffers[currentBuffer];
Device::CheckVkResult(vkQueueSubmit(Device::queue, 1, &submitInfo, waitFences[currentBuffer]));
// fence (keyed by frame slot) lets the Render() numFrames later reuse this
// slot's command buffer, heap copy and acquire semaphore safely. The
// semaphore handles live in member arrays, so taking their addresses here
// is stable for the call.
submitInfo.pWaitSemaphores = &imageAcquiredSemaphores[currentFrame];
submitInfo.pSignalSemaphores = &renderFinishedSemaphores[currentImage];
submitInfo.pCommandBuffers = &drawCmdBuffers[currentFrame];
Device::CheckVkResult(vkQueueSubmit(Device::queue, 1, &submitInfo, waitFences[currentFrame]));
presentInfo.pWaitSemaphores = &renderFinishedSemaphores[currentBuffer];
presentInfo.pWaitSemaphores = &renderFinishedSemaphores[currentImage];
VkResult result = vkQueuePresentKHR(Device::queue, &presentInfo);
// The frame is handed over: a swapchain rebuild may go ahead now.
recording = false;
if (result == VK_SUBOPTIMAL_KHR || result == VK_ERROR_OUT_OF_DATE_KHR) {
// Surface size changed mid-present. Drain the queue (the only place we
// still wait-idle, alongside Resize() and the acquire OUT_OF_DATE
// path), rebuild the swapchain, and let dependents (descriptors
// holding old image handles) re-bind via onResize before the next
// frame. The wait-idle here also re-settles every per-frame fence to a
// signaled state, so the next Render()'s fence wait passes through.
Device::CheckVkResult(vkQueueWaitIdle(Device::queue));
Device::DrainDeletions();
RecreateSwapchainAndImages();
onResize.Invoke();
// Surface size changed mid-present: rebuild below.
swapchainRebuildPending = true;
} else {
Device::CheckVkResult(result);
}
@ -1442,8 +1479,8 @@ void Window::Render() {
// while the GPU is still executing frame N.
frameCounter++;
// Advance the global deferred-deletion clock too (issue #101). Kept
// separate from the per-window frameCounter above (which also keys the
// acquire-semaphore slot) so non-window code can enqueue against it.
// separate from the per-window frameCounter above (which also picks the
// frame slot) so non-window code can enqueue against it.
Device::frameCounter++;
if (capture) {
@ -1452,6 +1489,25 @@ void Window::Render() {
Device::CheckVkResult(vkQueueWaitIdle(Device::queue));
WriteFrameCapture(*capture, colorFormat);
}
// The rebuild the frame held back: the present's, or a Resize or
// SetPresentMode from one of its listeners. RebuildSwapchain drains the
// queue (the only other wait-idles are Resize's and SetPresentMode's own
// and the acquire's OUT_OF_DATE path) and fires onResize before the next
// frame; the wait also leaves every per-frame fence signaled, so the next
// Render()'s fence wait passes through.
bool rebuild = swapchainRebuildPending;
if (deferredWidth != 0) {
rebuild = rebuild || deferredWidth != width || deferredHeight != height;
width = deferredWidth;
height = deferredHeight;
deferredWidth = 0;
deferredHeight = 0;
}
if (rebuild) {
swapchainRebuildPending = false;
RebuildSwapchain();
}
}
#ifdef CRAFTER_TIMING
@ -1493,14 +1549,86 @@ void Window::LogTiming() {
}
#endif
VkSurfaceCapabilitiesKHR Window::SwapchainCapabilities(VkPhysicalDevice gpu, VkSurfaceKHR surface,
VkPresentModeKHR mode, bool modePassedAlong) {
VkSurfaceCapabilitiesKHR allModes {};
if (!Device::surfaceMaintenance1Supported || !modePassedAlong) {
Device::CheckVkResult(vkGetPhysicalDeviceSurfaceCapabilitiesKHR(gpu, surface, &allModes));
if (!Device::surfaceMaintenance1Supported) {
return allModes;
}
}
VkSurfacePresentModeKHR modeInfo {
.sType = VK_STRUCTURE_TYPE_SURFACE_PRESENT_MODE_KHR,
.presentMode = mode,
};
const VkPhysicalDeviceSurfaceInfo2KHR surfaceInfo {
.sType = VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_SURFACE_INFO_2_KHR,
.pNext = &modeInfo,
.surface = surface,
};
VkSurfaceCapabilities2KHR forMode { .sType = VK_STRUCTURE_TYPE_SURFACE_CAPABILITIES_2_KHR };
Device::CheckVkResult(Device::vkGetPhysicalDeviceSurfaceCapabilities2KHR(gpu, &surfaceInfo, &forMode));
VkSurfaceCapabilitiesKHR capabilities = forMode.surfaceCapabilities;
if (!modePassedAlong) {
// VUID-VkSwapchainCreateInfoKHR-presentMode-02839 and the
// forward-progress rule of a UINT64_MAX acquire count against the
// surface's minimum for all modes unless the swapchain names its
// mode, so that minimum binds too.
capabilities.minImageCount = std::max(capabilities.minImageCount, allModes.minImageCount);
if (allModes.maxImageCount != 0) {
capabilities.maxImageCount = capabilities.maxImageCount == 0
? allModes.maxImageCount
: std::min(capabilities.maxImageCount, allModes.maxImageCount);
}
}
return capabilities;
}
std::uint32_t Window::SwapchainMinImageCount(const VkSurfaceCapabilitiesKHR& capabilities) {
std::uint32_t count = std::max<std::uint32_t>(numFrames, capabilities.minImageCount);
if (capabilities.maxImageCount != 0) {
count = std::min(count, capabilities.maxImageCount);
}
return count;
}
void Window::CreateSwapchain()
{
// Store the current swap chain handle so we can use it later on to ease up recreation
VkSwapchainKHR oldSwapchain = swapChain;
// Get physical device surface properties and formats
VkSurfaceCapabilitiesKHR surfCaps;
Device::CheckVkResult(vkGetPhysicalDeviceSurfaceCapabilitiesKHR(Device::physDevice, vulkanSurface, &surfCaps));
// VK_PRESENT_MODE_FIFO_KHR ("v-sync") is guaranteed available per spec, so
// it is the fallback for a mode the surface lacks. For benchmarking we
// want frame pacing uncapped from the display refresh, so when
// CRAFTER_PRESENT_IMMEDIATE is set in the environment we prefer IMMEDIATE
// (then MAILBOX) whatever presentMode asks for. Chosen first, because how
// many images the swapchain needs depends on it.
{
std::uint32_t presentModeCount = 0;
vkGetPhysicalDeviceSurfacePresentModesKHR(Device::physDevice, vulkanSurface, &presentModeCount, nullptr);
std::vector<VkPresentModeKHR> presentModes(presentModeCount);
vkGetPhysicalDeviceSurfacePresentModesKHR(Device::physDevice, vulkanSurface, &presentModeCount, presentModes.data());
auto offered = [&](VkPresentModeKHR mode) { return std::ranges::find(presentModes, mode) != presentModes.end(); };
swapchainPresentMode = VK_PRESENT_MODE_FIFO_KHR;
if (std::getenv("CRAFTER_PRESENT_IMMEDIATE")) {
if (offered(VK_PRESENT_MODE_IMMEDIATE_KHR)) swapchainPresentMode = VK_PRESENT_MODE_IMMEDIATE_KHR;
else if (offered(VK_PRESENT_MODE_MAILBOX_KHR)) swapchainPresentMode = VK_PRESENT_MODE_MAILBOX_KHR;
} else if (presentMode == PresentMode::Mailbox && offered(VK_PRESENT_MODE_MAILBOX_KHR)) {
swapchainPresentMode = VK_PRESENT_MODE_MAILBOX_KHR;
} else if (presentMode == PresentMode::Immediate && offered(VK_PRESENT_MODE_IMMEDIATE_KHR)) {
swapchainPresentMode = VK_PRESENT_MODE_IMMEDIATE_KHR;
}
}
// Get physical device surface properties, for that present mode. With
// swapchain_maintenance1 the swapchain names its mode, so that mode's
// image counts are the ones that apply, which on Mesa's Wayland are below
// the surface's for all modes (FIFO three where MAILBOX needs four, #160).
// This is the last capabilities query before vkCreateSwapchainKHR, as the
// validation layer checks minImageCount against the surface's last answer.
const VkSurfaceCapabilitiesKHR surfCaps = SwapchainCapabilities(Device::physDevice, vulkanSurface,
swapchainPresentMode, Device::swapchainMaintenance1Supported);
VkExtent2D swapchainExtent = {};
// If width (and height) equals the special value 0xFFFFFFFF, the size of the surface will be set by the swapchain
@ -1534,7 +1662,7 @@ void Window::CreateSwapchain()
VkSwapchainCreateInfoKHR swapchainCI = {};
swapchainCI.sType = VK_STRUCTURE_TYPE_SWAPCHAIN_CREATE_INFO_KHR;
swapchainCI.surface = vulkanSurface;
swapchainCI.minImageCount = numFrames;
swapchainCI.minImageCount = SwapchainMinImageCount(surfCaps);
swapchainCI.imageFormat = colorFormat;
swapchainCI.imageColorSpace = colorSpace;
swapchainCI.imageExtent = { swapchainExtent.width, swapchainExtent.height };
@ -1545,75 +1673,66 @@ void Window::CreateSwapchain()
swapchainCI.imageArrayLayers = 1;
swapchainCI.imageSharingMode = VK_SHARING_MODE_EXCLUSIVE;
swapchainCI.queueFamilyIndexCount = 0;
// VK_PRESENT_MODE_FIFO_KHR ("v-sync") is guaranteed available per spec, so
// it is the fallback for a mode the surface lacks. For benchmarking we
// want frame pacing uncapped from the display refresh, so when
// CRAFTER_PRESENT_IMMEDIATE is set in the environment we prefer IMMEDIATE
// (then MAILBOX) whatever presentMode asks for.
{
std::uint32_t presentModeCount = 0;
vkGetPhysicalDeviceSurfacePresentModesKHR(Device::physDevice, vulkanSurface, &presentModeCount, nullptr);
std::vector<VkPresentModeKHR> presentModes(presentModeCount);
vkGetPhysicalDeviceSurfacePresentModesKHR(Device::physDevice, vulkanSurface, &presentModeCount, presentModes.data());
auto offered = [&](VkPresentModeKHR mode) { return std::ranges::find(presentModes, mode) != presentModes.end(); };
swapchainPresentMode = VK_PRESENT_MODE_FIFO_KHR;
if (presentModeUnfit) {
// Stays FIFO; see below.
} else if (std::getenv("CRAFTER_PRESENT_IMMEDIATE")) {
if (offered(VK_PRESENT_MODE_IMMEDIATE_KHR)) swapchainPresentMode = VK_PRESENT_MODE_IMMEDIATE_KHR;
else if (offered(VK_PRESENT_MODE_MAILBOX_KHR)) swapchainPresentMode = VK_PRESENT_MODE_MAILBOX_KHR;
} else if (presentMode == PresentMode::Mailbox && offered(VK_PRESENT_MODE_MAILBOX_KHR)) {
swapchainPresentMode = VK_PRESENT_MODE_MAILBOX_KHR;
} else if (presentMode == PresentMode::Immediate && offered(VK_PRESENT_MODE_IMMEDIATE_KHR)) {
swapchainPresentMode = VK_PRESENT_MODE_IMMEDIATE_KHR;
}
}
swapchainCI.presentMode = swapchainPresentMode;
// The mode, named again for swapchain_maintenance1: what makes the mode's
// own image counts the ones that apply, at creation and to the acquires.
const VkSwapchainPresentModesCreateInfoKHR presentModes {
.sType = VK_STRUCTURE_TYPE_SWAPCHAIN_PRESENT_MODES_CREATE_INFO_KHR,
.presentModeCount = 1,
.pPresentModes = &swapchainPresentMode,
};
if (Device::swapchainMaintenance1Supported) {
swapchainCI.pNext = &presentModes;
}
// Setting oldSwapChain to the saved handle of the previous swapchain aids in resource reuse and makes sure that we can still present already acquired images
swapchainCI.oldSwapchain = oldSwapchain;
// Setting clipped to VK_TRUE allows the implementation to discard rendering outside of the surface area
swapchainCI.clipped = VK_TRUE;
swapchainCI.compositeAlpha = compositeAlpha;
// The old images' views go before the images do. Nothing uses them: the
// caller waited for the queue, and a heap copy or descriptor set that
// still names one is written again before its frame binds it.
for (VkImageView view : imageViews) {
vkDestroyImageView(Device::device, view, nullptr);
}
imageViews.clear();
Device::CheckVkResult(vkCreateSwapchainKHR(Device::device, &swapchainCI, nullptr, &swapChain));
// If an existing swap chain is re-created, destroy the old swap chain and the ressources owned by the application (image views, images are owned by the swap chain)
if (oldSwapchain != VK_NULL_HANDLE) {
vkDestroySwapchainKHR(Device::device, oldSwapchain, nullptr);
}
// The swap chain images: as many as the driver made, which may be more
// than minImageCount asked for. Everything kept per image is sized from
// this count; what is kept per frame in flight stays numFrames, so any
// count works (#160).
uint32_t imageCount{ 0 };
Device::CheckVkResult(vkGetSwapchainImagesKHR(Device::device, swapChain, &imageCount, nullptr));
// images[] and every other per-frame array hold exactly numFrames
// entries. A driver may create more images than minImageCount asked for
// (a surface whose minimum is above numFrames must, and Mesa gives
// MAILBOX at least four). MAILBOX and IMMEDIATE are wishes: FIFO, with
// numFrames, is the frame loop's own. If that has other than numFrames
// too, writing them into images[] would run off its end, so refuse.
if (imageCount != numFrames && swapchainPresentMode != VK_PRESENT_MODE_FIFO_KHR) {
std::println(std::cerr, "Window: the {} swapchain has {} images, not the frame loop's {}; using FIFO",
swapchainPresentMode == VK_PRESENT_MODE_MAILBOX_KHR ? "MAILBOX" : "IMMEDIATE", imageCount, numFrames);
vkDestroySwapchainKHR(Device::device, swapChain, nullptr);
presentModeUnfit = true;
swapchainPresentMode = VK_PRESENT_MODE_FIFO_KHR;
swapchainCI.presentMode = swapchainPresentMode;
swapchainCI.oldSwapchain = VK_NULL_HANDLE;
Device::CheckVkResult(vkCreateSwapchainKHR(Device::device, &swapchainCI, nullptr, &swapChain));
Device::CheckVkResult(vkGetSwapchainImagesKHR(Device::device, swapChain, &imageCount, nullptr));
}
if (imageCount != numFrames) {
throw std::runtime_error(std::format("Window: the swapchain has {} images, but the frame loop is built for exactly {}", imageCount, numFrames));
}
// Get the swap chain images
Device::CheckVkResult(vkGetSwapchainImagesKHR(Device::device, swapChain, &imageCount, images));
images.resize(imageCount);
Device::CheckVkResult(vkGetSwapchainImagesKHR(Device::device, swapChain, &imageCount, images.data()));
// Brand-new swapchain images are in VK_IMAGE_LAYOUT_UNDEFINED; none have
// been rendered/presented yet. Render() consults this to pick the correct
// oldLayout for each image's first post-acquire transition.
imageInitialised.fill(false);
imageInitialised.assign(imageCount, false);
for (std::uint8_t i = 0; i < numFrames; i++) {
imageViews[i] = {
// A render-finished semaphore per image. The ones the old swapchain's
// images used are kept: its last presents may still be waiting on them.
const VkSemaphoreCreateInfo semaphoreCreateInfo { .sType = VK_STRUCTURE_TYPE_SEMAPHORE_CREATE_INFO };
while (renderFinishedSemaphores.size() < imageCount) {
VkSemaphore semaphore = VK_NULL_HANDLE;
Device::CheckVkResult(vkCreateSemaphore(Device::device, &semaphoreCreateInfo, nullptr, &semaphore));
renderFinishedSemaphores.push_back(semaphore);
}
static std::atomic<std::uint64_t> swapchainsMade = 0;
swapchainGeneration = ++swapchainsMade;
imageViewInfos.resize(imageCount);
for (std::uint32_t i = 0; i < imageCount; i++) {
imageViewInfos[i] = {
.sType = VK_STRUCTURE_TYPE_IMAGE_VIEW_CREATE_INFO,
.flags = 0,
.image = images[i],
@ -1634,13 +1753,19 @@ void Window::CreateSwapchain()
},
};
}
// The views made, for descriptor sets, once per swapchain rather than
// once per frame whose image changed.
imageViews.resize(imageCount);
for (std::uint32_t i = 0; i < imageCount; i++) {
Device::CheckVkResult(vkCreateImageView(Device::device, &imageViewInfos[i], nullptr, &imageViews[i]));
}
}
VkCommandBuffer Window::StartInit() {
VkCommandBufferBeginInfo cmdBufInfo {};
cmdBufInfo.sType = VK_STRUCTURE_TYPE_COMMAND_BUFFER_BEGIN_INFO;
// StartInit reuses drawCmdBuffers[currentBuffer] — the same buffer the
// steady-state Render() loop submits, guarded by waitFences[currentBuffer].
// StartInit reuses drawCmdBuffers[currentFrame] — the same buffer the
// steady-state Render() loop submits, guarded by waitFences[currentFrame].
// When setup runs mid-session (e.g. building map meshes / acceleration
// structures on a scene transition) the loop's last submission of this
// buffer may still be in flight: re-beginning it would trip
@ -1653,7 +1778,7 @@ VkCommandBuffer Window::StartInit() {
// (not the per-frame path), so a full wait-idle here is fine — FinishInit
// already wait-idles at the end.
Device::CheckVkResult(vkQueueWaitIdle(Device::queue));
Device::CheckVkResult(vkBeginCommandBuffer(drawCmdBuffers[currentBuffer], &cmdBufInfo));
Device::CheckVkResult(vkBeginCommandBuffer(drawCmdBuffers[currentFrame], &cmdBufInfo));
// The swapchain images are deliberately NOT transitioned here. They are
// presentable images and may only be touched after vkAcquireNextImageKHR
@ -1662,15 +1787,15 @@ VkCommandBuffer Window::StartInit() {
// VK_IMAGE_LAYOUT_UNDEFINED on its first acquired use (see
// imageInitialised). This command buffer is for the caller's one-time
// setup work (uploads, acceleration-structure builds, etc.).
return drawCmdBuffers[currentBuffer];
return drawCmdBuffers[currentFrame];
}
void Window::FinishInit() {
VkSubmitInfo submitInfo{};
submitInfo.sType = VK_STRUCTURE_TYPE_SUBMIT_INFO;
submitInfo.commandBufferCount = 1;
submitInfo.pCommandBuffers = &drawCmdBuffers[currentBuffer];
Device::CheckVkResult(vkEndCommandBuffer(drawCmdBuffers[currentBuffer]));
submitInfo.pCommandBuffers = &drawCmdBuffers[currentFrame];
Device::CheckVkResult(vkEndCommandBuffer(drawCmdBuffers[currentFrame]));
Device::CheckVkResult(vkQueueSubmit(Device::queue, 1, &submitInfo, VK_NULL_HANDLE));
Device::CheckVkResult(vkQueueWaitIdle(Device::queue));
}
@ -1679,11 +1804,11 @@ VkCommandBuffer Window::GetCmd() {
VkCommandBufferBeginInfo cmdBufInfo {};
cmdBufInfo.sType = VK_STRUCTURE_TYPE_COMMAND_BUFFER_BEGIN_INFO;
// Same lifecycle hazard as StartInit: GetCmd re-begins and EndCmd
// re-submits the shared drawCmdBuffers[currentBuffer], so drain any
// re-submits the shared drawCmdBuffers[currentFrame], so drain any
// in-flight submission of it (and free the resources it references) before
// re-recording (issue #153).
Device::CheckVkResult(vkQueueWaitIdle(Device::queue));
Device::CheckVkResult(vkBeginCommandBuffer(drawCmdBuffers[currentBuffer], &cmdBufInfo));
Device::CheckVkResult(vkBeginCommandBuffer(drawCmdBuffers[currentFrame], &cmdBufInfo));
VkImageSubresourceRange range{};
range.aspectMask = VK_IMAGE_ASPECT_COLOR_BIT;
@ -1691,16 +1816,16 @@ VkCommandBuffer Window::GetCmd() {
range.levelCount = VK_REMAINING_MIP_LEVELS;
range.baseArrayLayer = 0;
range.layerCount = VK_REMAINING_ARRAY_LAYERS;
return drawCmdBuffers[currentBuffer];
return drawCmdBuffers[currentFrame];
}
void Window::EndCmd(VkCommandBuffer cmd) {
VkSubmitInfo submitInfo{};
submitInfo.sType = VK_STRUCTURE_TYPE_SUBMIT_INFO;
submitInfo.commandBufferCount = 1;
submitInfo.pCommandBuffers = &drawCmdBuffers[currentBuffer];
Device::CheckVkResult(vkEndCommandBuffer(drawCmdBuffers[currentBuffer]));
submitInfo.pCommandBuffers = &drawCmdBuffers[currentFrame];
Device::CheckVkResult(vkEndCommandBuffer(drawCmdBuffers[currentFrame]));
Device::CheckVkResult(vkQueueSubmit(Device::queue, 1, &submitInfo, VK_NULL_HANDLE));
Device::CheckVkResult(vkQueueWaitIdle(Device::queue));
}
@ -1974,7 +2099,7 @@ void Window::Render() {
if (!open) return;
Crafter::WebGPU::wgpuFrameBegin();
for (RenderPass* p : passes) {
if (p) p->Record(/*cmd*/ 0u, currentBuffer, *this);
if (p) p->Record(/*cmd*/ 0u, currentFrame, *this);
}
Crafter::WebGPU::wgpuFrameEnd();
}