Add more comments, fixup indents in guide

Author: karnkaul

guide/src/rendering/dynamic_rendering.md

@@ -73,6 +73,7 @@ attachment_info.setImageView(render_target->image_view)
   .setImageLayout(vk::ImageLayout::eAttachmentOptimal)
   .setLoadOp(vk::AttachmentLoadOp::eClear)
   .setStoreOp(vk::AttachmentStoreOp::eStore)
+  // temporarily red.
   .setClearValue(vk::ClearColorValue{1.0f, 0.0f, 0.0f, 1.0f});
 ```
 

guide/src/rendering/render_sync.md

@@ -14,62 +14,62 @@ using Buffered = std::array<Type, buffering_v>;
 Add a private `struct RenderSync` to `App`:
 
 ```cpp
-	struct RenderSync {
-		// signaled when Swapchain image has been acquired.
-		vk::UniqueSemaphore draw{};
-		// signaled when image is ready to be presented.
-		vk::UniqueSemaphore present{};
-		// signaled with present Semaphore, waited on before next render.
-		vk::UniqueFence drawn{};
-		// used to record rendering commands.
-		vk::CommandBuffer command_buffer{};
-	};
+struct RenderSync {
+  // signaled when Swapchain image has been acquired.
+  vk::UniqueSemaphore draw{};
+  // signaled when image is ready to be presented.
+  vk::UniqueSemaphore present{};
+  // signaled with present Semaphore, waited on before next render.
+  vk::UniqueFence drawn{};
+  // used to record rendering commands.
+  vk::CommandBuffer command_buffer{};
+};
 ```
 
 Add the new members associated with the Swapchain loop:
 
 ```cpp
-	// command pool for all render Command Buffers.
-	vk::UniqueCommandPool m_render_cmd_pool{};
-	// Sync and Command Buffer for virtual frames.
-	Buffered<RenderSync> m_render_sync{};
-	// Current virtual frame index.
-	std::size_t m_frame_index{};
+// command pool for all render Command Buffers.
+vk::UniqueCommandPool m_render_cmd_pool{};
+// Sync and Command Buffer for virtual frames.
+Buffered<RenderSync> m_render_sync{};
+// Current virtual frame index.
+std::size_t m_frame_index{};
 ```
 
 Add, implement, and call the create function:
 
 ```cpp
 void App::create_render_sync() {
-	// Command Buffers are 'allocated' from a Command Pool (which is 'created'
-	// like all other Vulkan objects so far). We can allocate all the buffers
-	// from a single pool here.
-	auto command_pool_ci = vk::CommandPoolCreateInfo{};
-	// this flag enables resetting the command buffer for re-recording (unlike a
-	// single-time submit scenario).
-	command_pool_ci.setFlags(vk::CommandPoolCreateFlagBits::eResetCommandBuffer)
-		.setQueueFamilyIndex(m_gpu.queue_family);
-	m_render_cmd_pool = m_device->createCommandPoolUnique(command_pool_ci);
+  // Command Buffers are 'allocated' from a Command Pool (which is 'created'
+  // like all other Vulkan objects so far). We can allocate all the buffers
+  // from a single pool here.
+  auto command_pool_ci = vk::CommandPoolCreateInfo{};
+  // this flag enables resetting the command buffer for re-recording (unlike a
+  // single-time submit scenario).
+  command_pool_ci.setFlags(vk::CommandPoolCreateFlagBits::eResetCommandBuffer)
+    .setQueueFamilyIndex(m_gpu.queue_family);
+  m_render_cmd_pool = m_device->createCommandPoolUnique(command_pool_ci);
 
-	auto command_buffer_ai = vk::CommandBufferAllocateInfo{};
-	command_buffer_ai.setCommandPool(*m_render_cmd_pool)
-		.setCommandBufferCount(static_cast<std::uint32_t>(resource_buffering_v))
-		.setLevel(vk::CommandBufferLevel::ePrimary);
-	auto const command_buffers =
-		m_device->allocateCommandBuffers(command_buffer_ai);
-	assert(command_buffers.size() == m_render_sync.size());
+  auto command_buffer_ai = vk::CommandBufferAllocateInfo{};
+  command_buffer_ai.setCommandPool(*m_render_cmd_pool)
+    .setCommandBufferCount(static_cast<std::uint32_t>(resource_buffering_v))
+    .setLevel(vk::CommandBufferLevel::ePrimary);
+  auto const command_buffers =
+    m_device->allocateCommandBuffers(command_buffer_ai);
+  assert(command_buffers.size() == m_render_sync.size());
 
-	// we create Render Fences as pre-signaled so that on the first render for
-	// each virtual frame we don't wait on their fences (since there's nothing
-	// to wait for yet).
-	static constexpr auto fence_create_info_v =
-		vk::FenceCreateInfo{vk::FenceCreateFlagBits::eSignaled};
-	for (auto [sync, command_buffer] :
-		 std::views::zip(m_render_sync, command_buffers)) {
-		sync.command_buffer = command_buffer;
-		sync.draw = m_device->createSemaphoreUnique({});
-		sync.present = m_device->createSemaphoreUnique({});
-		sync.drawn = m_device->createFenceUnique(fence_create_info_v);
-	}
+  // we create Render Fences as pre-signaled so that on the first render for
+  // each virtual frame we don't wait on their fences (since there's nothing
+  // to wait for yet).
+  static constexpr auto fence_create_info_v =
+    vk::FenceCreateInfo{vk::FenceCreateFlagBits::eSignaled};
+  for (auto [sync, command_buffer] :
+     std::views::zip(m_render_sync, command_buffers)) {
+    sync.command_buffer = command_buffer;
+    sync.draw = m_device->createSemaphoreUnique({});
+    sync.present = m_device->createSemaphoreUnique({});
+    sync.drawn = m_device->createFenceUnique(fence_create_info_v);
+  }
 }
 ```

guide/src/rendering/swapchain_update.md

@@ -11,23 +11,23 @@ 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"};
+  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{};
+  vk::Image image{};
+  vk::ImageView image_view{};
+  vk::Extent2D extent{};
 };
 ```
 
@@ -37,58 +37,62 @@ 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 {}; }
+  -> std::optional<RenderTarget> {
+  assert(!m_image_index);
+  static constexpr auto timeout_v = std::numeric_limits<std::uint64_t>::max();
+  // avoid VulkanHPP ErrorOutOfDateKHR exceptions by using alternate API that
+  // returns a Result.
+  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,
-	};
+  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 {
-	auto const image_index = static_cast<std::uint32_t>(m_image_index.value());
-	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);
+  -> bool {
+  auto const image_index = static_cast<std::uint32_t>(m_image_index.value());
+  auto present_info = vk::PresentInfoKHR{};
+  present_info.setSwapchains(*m_swapchain)
+    .setImageIndices(image_index)
+    .setWaitSemaphores(to_wait);
+  // avoid VulkanHPP ErrorOutOfDateKHR exceptions by using alternate API.
+  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 ret = vk::ImageSubresourceRange{};
+  // this is a color image with 1 layer and 1 mip-level (the default).
+  ret.setAspectMask(vk::ImageAspectFlagBits::eColor)
+    .setLayerCount(1)
+    .setLevelCount(1);
+  return ret;
 }();
 
 // ...
 auto Swapchain::base_barrier() const -> vk::ImageMemoryBarrier2 {
-	// fill up the parts common to all barriers.
-	auto ret = vk::ImageMemoryBarrier2{};
-	ret.setImage(m_images.at(m_image_index.value()))
-		.setSubresourceRange(subresource_range_v)
-		.setSrcQueueFamilyIndex(m_gpu.queue_family)
-		.setDstQueueFamilyIndex(m_gpu.queue_family);
-	return ret;
+  // fill up the parts common to all barriers.
+  auto ret = vk::ImageMemoryBarrier2{};
+  ret.setImage(m_images.at(m_image_index.value()))
+    .setSubresourceRange(subresource_range_v)
+    .setSrcQueueFamilyIndex(m_gpu.queue_family)
+    .setDstQueueFamilyIndex(m_gpu.queue_family);
+  return ret;
 }
 ```

src/app.cpp

@@ -193,6 +193,7 @@ void App::main_loop() {
 			.setImageLayout(vk::ImageLayout::eAttachmentOptimal)
 			.setLoadOp(vk::AttachmentLoadOp::eClear)
 			.setStoreOp(vk::AttachmentStoreOp::eStore)
+			// temporarily red.
 			.setClearValue(vk::ClearColorValue{1.0f, 0.0f, 0.0f, 1.0f});
 		auto rendering_info = vk::RenderingInfo{};
 		auto const render_area =

src/swapchain.cpp

@@ -130,6 +130,8 @@ 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();
+	// avoid VulkanHPP ErrorOutOfDateKHR exceptions by using alternate API that
+	// returns a Result.
 	auto image_index = std::uint32_t{};
 	auto const result = m_device.acquireNextImageKHR(
 		*m_swapchain, timeout_v, to_signal, {}, &image_index);
@@ -160,6 +162,7 @@ auto Swapchain::present(vk::Queue const queue, vk::Semaphore const to_wait)
 	present_info.setSwapchains(*m_swapchain)
 		.setImageIndices(image_index)
 		.setWaitSemaphores(to_wait);
+	// avoid VulkanHPP ErrorOutOfDateKHR exceptions by using alternate API.
 	auto const result = queue.presentKHR(&present_info);
 	m_image_index.reset();
 	return !needs_recreation(result);