Merge pull request 'feat(window): multi-frame-in-flight frame pacing (#40)' (#81) from claude/issue-40 into master

interfaces/Crafter.Graphics-Window.cppm

@@ -270,18 +270,59 @@ export namespace Crafter {
         std::array<bool, numFrames> imageInitialised{};
         std::thread thread;
         VkCommandBuffer drawCmdBuffers[numFrames];
-        VkSubmitInfo submitInfo;
         // Per-frame Vulkan info structs whose contents are almost entirely
         // invariant. Initialised once in the constructor; Render() patches only
         // the few fields that change each frame (the two barriers' image and
-        // the acquire barrier's oldLayout). presentInfo.pImageIndices and
-        // pSwapchains point at the currentBuffer/swapChain members, so they
-        // track value changes (including swapchain recreation) automatically.
+        // the acquire barrier's oldLayout, and — for the multi-frame-in-flight
+        // sync below — submitInfo/presentInfo's wait/signal semaphores plus
+        // submitInfo's command buffer, which follow currentBuffer/frameCounter).
+        // presentInfo.pImageIndices and pSwapchains point at the
+        // currentBuffer/swapChain members, so they track value changes
+        // (including swapchain recreation) automatically.
+        VkSubmitInfo submitInfo;
         VkCommandBufferBeginInfo cmdBufInfo;
         VkImageMemoryBarrier acquireBarrier;
         VkImageMemoryBarrier presentBarrier;
         VkPresentInfoKHR presentInfo;
-        Semaphores semaphores;
+
+        // ── Multi-frame-in-flight synchronisation (issue #40) ──────────────
+        // The renderer keeps up to numFrames frames in flight, so a single
+        // semaphore pair + a per-frame wait-idle is no longer enough. Note
+        // that drawCmdBuffers, the per-frame descriptor heap slots, and the
+        // swapchain images are ALL keyed by the acquired image index
+        // (currentBuffer) — WriteSwapchainDescriptors bakes heap slot i to
+        // write imageViews[i], so the index that selects a command buffer /
+        // heap slot must equal the acquired image index. Everything below
+        // follows from that.
+
+        // Signaled by the queue submit, waited by vkQueuePresentKHR. Keyed by
+        // the acquired IMAGE index: the presentation engine keeps this
+        // semaphore in use until the image is re-acquired, so a per-image
+        // semaphore is the only safe key. Keying it per-CPU-frame trips
+        // VUID-vkQueueSubmit-pSignalSemaphores-00067.
+        // https://docs.vulkan.org/guide/latest/swapchain_semaphore_reuse.html
+        std::array<VkSemaphore, numFrames> renderFinishedSemaphores{};
+
+        // Signaled by the queue submit, waited + reset before
+        // drawCmdBuffers[image] and that image's descriptor-heap slot are
+        // re-recorded. Keyed by image index. Created signaled so the first
+        // wait on each image passes through instead of deadlocking.
+        std::array<VkFence, numFrames> waitFences{};
+
+        // Signaled by vkAcquireNextImageKHR, waited by the queue submit. Keyed
+        // by a free-running CPU frame counter, because the image index isn't
+        // known until acquire returns. Sized numFrames+1: at most numFrames
+        // frames are ever in flight (each image's command buffer is gated by
+        // its own fence, and there are numFrames images), so numFrames+1
+        // distinct acquire semaphores guarantees the one being reused has no
+        // pending operation — required by
+        // VUID-vkAcquireNextImageKHR-semaphore-01779.
+        static constexpr std::uint8_t numAcquireSemaphores = numFrames + 1;
+        std::array<VkSemaphore, numAcquireSemaphores> imageAcquiredSemaphores{};
+
+        // Free-running count of Render() calls; drives the acquire-semaphore
+        // slot (frameCounter % numAcquireSemaphores).
+        std::uint64_t frameCounter = 0;
         std::uint32_t currentBuffer = 0;
         VkPipelineStageFlags submitPipelineStages = VK_PIPELINE_STAGE_COLOR_ATTACHMENT_OUTPUT_BIT;
         std::vector<RenderPass*> passes;