RenderTarget, Swapchain updates

Author: karnkaul

guide/src/SUMMARY.md

@@ -19,3 +19,4 @@
 - [Rendering](rendering/README.md)
   - [Swapchain Loop](rendering/swapchain_loop.md)
   - [Render Sync](rendering/render_sync.md)
+  - [Swapchain Update](rendering/swapchain_update.md)

guide/src/rendering/swapchain_update.md

@@ -0,0 +1,96 @@
+# Swapchain Acquire/Present
+
+Swapchain acquire/present operations can have various results. We constrain ourselves to the following:
+
+- `eSuccess`: all good
+- `eSuboptimalKHR`: also all good (this is also unlikely to occur on a desktop)
+- `eErrorOutOfDateKHR`: Swapchain needs to be recreated, consider the operation to have not succeeded
+- Any other `vk::Result`: fatal/unexpected error
+
+Expressing as a helper function in `swapchain.cpp`:
+
+```cpp
+auto needs_recreation(vk::Result const result) -> bool {
+	switch (result) {
+	case vk::Result::eSuccess:
+	case vk::Result::eSuboptimalKHR: return false;
+	case vk::Result::eErrorOutOfDateKHR: return true;
+	default: break;
+	}
+	throw std::runtime_error{"Swapchain Error"};
+}
+```
+
+We also want to return the Image, Image View, and size upon successful acquisition of the underlying Swapchain Image. Wrapping those in a `struct`:
+
+```cpp
+struct RenderTarget {
+	vk::Image image{};
+	vk::ImageView image_view{};
+	vk::Extent2D extent{};
+};
+```
+
+VulkanHPP's primary API throws if the `vk::Result` corresponds to an error (based on the spec). `eErrorOutOfDateKHR` is technically an error, but it's quite possible to get it when the framebuffer size doesn't match the Swapchain size. To avoid having to deal with exceptions here, we use the alternate API for the acquire and present calls (overloads distinguished by pointer arguments and/or out parameters, and returning a `vk::Result`).
+
+Implementing the acquire operation:
+
+```cpp
+auto Swapchain::acquire_next_image(vk::Semaphore const to_signal)
+	-> std::optional<RenderTarget> {
+	assert(!m_image_index);
+	static constexpr auto timeout_v = std::numeric_limits<std::uint64_t>::max();
+	auto image_index = std::uint32_t{};
+	auto const result = m_device.acquireNextImageKHR(
+		*m_swapchain, timeout_v, to_signal, {}, &image_index);
+	if (needs_recreation(result)) { return {}; }
+
+	m_image_index = static_cast<std::size_t>(image_index);
+	return RenderTarget{
+		.image = m_images.at(*m_image_index),
+		.image_view = *m_image_views.at(*m_image_index),
+		.extent = m_ci.imageExtent,
+	};
+}
+```
+
+Similarly, present:
+
+```cpp
+auto Swapchain::present(vk::Queue const queue, vk::Semaphore const to_wait)
+	-> bool {
+	assert(m_image_index);
+	auto const image_index = static_cast<std::uint32_t>(*m_image_index);
+	auto present_info = vk::PresentInfoKHR{};
+	present_info.setSwapchains(*m_swapchain)
+		.setImageIndices(image_index)
+		.setWaitSemaphores(to_wait);
+	auto const result = queue.presentKHR(&present_info);
+	m_image_index.reset();
+	return !needs_recreation(result);
+}
+```
+
+It is the responsibility of the user (`class App`) to recreate the Swapchain on receiving `std::nullopt` / `false` return values for either operation. Users will also need to transition the layouts of the returned images between acquire and present operations. Add a helper to assist in that process, and extract the Image Subresource Range out as a common constant:
+
+```cpp
+constexpr auto subresource_range_v = [] {
+	auto ret = vk::ImageSubresourceRange{};
+	ret.setAspectMask(vk::ImageAspectFlagBits::eColor)
+		.setLayerCount(1)
+		.setLevelCount(1);
+	return ret;
+}();
+
+// ...
+auto Swapchain::base_barrier() const -> vk::ImageMemoryBarrier2 {
+	assert(m_image_index);
+	// fill up the parts common to all barriers.
+	auto ret = vk::ImageMemoryBarrier2{};
+	ret.setImage(m_images.at(*m_image_index))
+		.setSubresourceRange(subresource_range_v)
+		.setSrcQueueFamilyIndex(m_gpu.queue_family)
+		.setDstQueueFamilyIndex(m_gpu.queue_family);
+	return ret;
+}
+```

src/render_target.hpp

@@ -0,0 +1,10 @@
+#pragma once
+#include <vulkan/vulkan.hpp>
+
+namespace lvk {
+struct RenderTarget {
+	vk::Image image{};
+	vk::ImageView image_view{};
+	vk::Extent2D extent{};
+};
+} // namespace lvk

src/swapchain.cpp

@@ -2,6 +2,7 @@
 #include <algorithm>
 #include <array>
 #include <cassert>
+#include <limits>
 #include <print>
 #include <stdexcept>
 
@@ -14,6 +15,14 @@ constexpr auto srgb_formats_v = std::array{
 	vk::Format::eB8G8R8A8Srgb,
 };
 
+constexpr auto subresource_range_v = [] {
+	auto ret = vk::ImageSubresourceRange{};
+	ret.setAspectMask(vk::ImageAspectFlagBits::eColor)
+		.setLayerCount(1)
+		.setLevelCount(1);
+	return ret;
+}();
+
 [[nodiscard]] constexpr auto
 get_surface_format(std::span<vk::SurfaceFormatKHR const> supported)
 	-> vk::SurfaceFormatKHR {
@@ -58,6 +67,16 @@ get_image_count(vk::SurfaceCapabilitiesKHR const& capabilities)
 void require_success(vk::Result const result, char const* error_msg) {
 	if (result != vk::Result::eSuccess) { throw std::runtime_error{error_msg}; }
 }
+
+auto needs_recreation(vk::Result const result) -> bool {
+	switch (result) {
+	case vk::Result::eSuccess:
+	case vk::Result::eSuboptimalKHR: return false;
+	case vk::Result::eErrorOutOfDateKHR: return true;
+	default: break;
+	}
+	throw std::runtime_error{"Swapchain Error"};
+}
 } // namespace
 
 Swapchain::Swapchain(vk::Device const device, Gpu const& gpu,
@@ -100,6 +119,47 @@ auto Swapchain::recreate(glm::ivec2 size) -> bool {
 	return true;
 }
 
+auto Swapchain::acquire_next_image(vk::Semaphore const to_signal)
+	-> std::optional<RenderTarget> {
+	assert(!m_image_index);
+	static constexpr auto timeout_v = std::numeric_limits<std::uint64_t>::max();
+	auto image_index = std::uint32_t{};
+	auto const result = m_device.acquireNextImageKHR(
+		*m_swapchain, timeout_v, to_signal, {}, &image_index);
+	if (needs_recreation(result)) { return {}; }
+
+	m_image_index = static_cast<std::size_t>(image_index);
+	return RenderTarget{
+		.image = m_images.at(*m_image_index),
+		.image_view = *m_image_views.at(*m_image_index),
+		.extent = m_ci.imageExtent,
+	};
+}
+
+auto Swapchain::base_barrier() const -> vk::ImageMemoryBarrier2 {
+	assert(m_image_index);
+	// fill up the parts common to all barriers.
+	auto ret = vk::ImageMemoryBarrier2{};
+	ret.setImage(m_images.at(*m_image_index))
+		.setSubresourceRange(subresource_range_v)
+		.setSrcQueueFamilyIndex(m_gpu.queue_family)
+		.setDstQueueFamilyIndex(m_gpu.queue_family);
+	return ret;
+}
+
+auto Swapchain::present(vk::Queue const queue, vk::Semaphore const to_wait)
+	-> bool {
+	assert(m_image_index);
+	auto const image_index = static_cast<std::uint32_t>(*m_image_index);
+	auto present_info = vk::PresentInfoKHR{};
+	present_info.setSwapchains(*m_swapchain)
+		.setImageIndices(image_index)
+		.setWaitSemaphores(to_wait);
+	auto const result = queue.presentKHR(&present_info);
+	m_image_index.reset();
+	return !needs_recreation(result);
+}
+
 void Swapchain::populate_images() {
 	auto image_count = std::uint32_t{};
 	auto result =
@@ -113,14 +173,10 @@ void Swapchain::populate_images() {
 }
 
 void Swapchain::create_image_views() {
-	auto subresource_range = vk::ImageSubresourceRange{};
-	subresource_range.setAspectMask(vk::ImageAspectFlagBits::eColor)
-		.setLayerCount(1)
-		.setLevelCount(1);
 	auto image_view_ci = vk::ImageViewCreateInfo{};
 	image_view_ci.setViewType(vk::ImageViewType::e2D)
 		.setFormat(m_ci.imageFormat)
-		.setSubresourceRange(subresource_range);
+		.setSubresourceRange(subresource_range_v);
 	m_image_views.clear();
 	m_image_views.reserve(m_images.size());
 	for (auto const image : m_images) {

src/swapchain.hpp

@@ -1,6 +1,7 @@
 #pragma once
 #include <glm/vec2.hpp>
 #include <gpu.hpp>
+#include <render_target.hpp>
 #include <optional>
 #include <vector>
 
@@ -16,6 +17,13 @@ class Swapchain {
 		return {m_ci.imageExtent.width, m_ci.imageExtent.height};
 	}
 
+	[[nodiscard]] auto acquire_next_image(vk::Semaphore to_signal)
+		-> std::optional<RenderTarget>;
+
+	[[nodiscard]] auto base_barrier() const -> vk::ImageMemoryBarrier2;
+
+	[[nodiscard]] auto present(vk::Queue queue, vk::Semaphore to_wait) -> bool;
+
   private:
 	void populate_images();
 	void create_image_views();