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>
The renderer was effectively single-buffered despite allocating
triple-buffered infrastructure: Render() ended with an unconditional
vkQueueWaitIdle, and a single (presentComplete, renderComplete)
semaphore pair with zero fences was shared for the Window's lifetime.
Rework the pacing model so up to numFrames frames overlap:
- Per-swapchain-image VkFence, signaled by the submit and waited+reset
before that image's command buffer / descriptor-heap slot is
re-recorded. Keyed by acquired image index (drawCmdBuffers, the heap
slots, and the swapchain images are all image-indexed — see
WriteSwapchainDescriptors). Created signaled so first use passes.
- Per-image render-finished (present) semaphore: the presentation engine
holds it until the image is re-acquired, so per-image is the only safe
key (per-CPU-frame trips VUID-vkQueueSubmit-pSignalSemaphores-00067).
- Per-CPU-frame acquire semaphores (image index unknown until acquire
returns), sized numFrames+1: in-flight depth is bounded by the
per-image fences, so numFrames+1 distinct acquire semaphores guarantee
the reused one has no pending op (VUID-vkAcquireNextImageKHR-01779).
- Drop the steady-state vkQueueWaitIdle; keep it on resize / OUT_OF_DATE
/ teardown.
Add tests/FrameLoopSync: drives the real frame loop against a live
Wayland compositor for 60 frames (>> in-flight slots) and asserts the
CPU frame counter advanced, the swapchain rotated across multiple
images, and the validation layer stayed silent — the load-bearing check,
since the old single-pair design only avoided being an active race
because the wait-idle masked it.
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
catbot