Pipeline Layout

Author: karnkaul

guide/src/SUMMARY.md

@@ -43,3 +43,5 @@
   - [Command Block](memory/command_block.md)
   - [Device Buffers](memory/device_buffers.md)
   - [Images](memory/images.md)
+- [Descriptor Sets](descriptor_sets/README.md)
+  - [Pipeline Layout](descriptor_sets/pipeline_layout.md)

guide/src/descriptor_sets/README.md

@@ -0,0 +1,5 @@
+# Descriptor Sets
+
+[Vulkan Descriptor](https://docs.vulkan.org/guide/latest/mapping_data_to_shaders.html#descriptors)s are essentially typed pointers to resources that shaders can use, eg uniform/storage buffers or combined image samplers (textures with samplers). A Descriptor Set is a collection of descriptors at various **bindings** that is bound together as an atomic unit. Shaders can declare input based on these set and binding numbers, and any sets the shader uses must have been updated and bound before drawing. A Descriptor Set Layout is a description of a collection of descriptor sets associated with a particular set number, usually describing all the sets in a shader. Descriptor sets are allocated using a Descriptor Pool and the desired set layout(s).
+
+Structuring set layouts and managing descriptor sets are complex topics with many viable approaches, each with their pros and cons. Some robust ones are described in this [page](https://docs.vulkan.org/samples/latest/samples/performance/descriptor_management/README.html). 2D frameworks - and even simple/basic 3D ones - can simply allocate and update sets every frame, as described in the docs as the "simplest approach". Here's an [extremely detailed](https://zeux.io/2020/02/27/writing-an-efficient-vulkan-renderer/) - albeit a bit dated now - post by Arseny on the subject. A more modern approach, namely "bindless" or Descriptor Indexing, is described in the official docs [here](https://docs.vulkan.org/samples/latest/samples/extensions/descriptor_indexing/README.html).

guide/src/descriptor_sets/pipeline_layout.md

@@ -0,0 +1,81 @@
+# Pipeline Layout
+
+A [Vulkan Pipeline Layout](https://registry.khronos.org/vulkan/specs/latest/man/html/VkPipelineLayout.html) represents a sequence of descriptor sets (and push constants) associated with a shader program. Even when using Shader Objects, a Pipeline Layout is needed to utilize descriptor sets.
+
+Starting with the layout of a single descriptor set containing a uniform buffer to set the view/projection matrices in, store a descriptor pool in `App` and create it before the shader:
+
+```cpp
+vk::UniqueDescriptorPool m_descriptor_pool{};
+
+// ...
+void App::create_descriptor_pool() {
+  static constexpr auto pool_sizes_v = std::array{
+    // 2 uniform buffers, can be more if desired.
+    vk::DescriptorPoolSize{vk::DescriptorType::eUniformBuffer, 2},
+  };
+  auto pool_ci = vk::DescriptorPoolCreateInfo{};
+  // allow 16 sets to be allocated from this pool.
+  pool_ci.setPoolSizes(pool_sizes_v).setMaxSets(16);
+  m_descriptor_pool = m_device->createDescriptorPoolUnique(pool_ci);
+}
+```
+
+Add new members to `App` to store the set layouts and pipeline layout. `m_set_layout_views` is just a copy of the descriptor set layout handles in a contiguous vector:
+
+```cpp
+std::vector<vk::UniqueDescriptorSetLayout> m_set_layouts{};
+std::vector<vk::DescriptorSetLayout> m_set_layout_views{};
+vk::UniquePipelineLayout m_pipeline_layout{};
+
+// ...
+constexpr auto layout_binding(std::uint32_t binding,
+                              vk::DescriptorType const type) {
+  return vk::DescriptorSetLayoutBinding{
+    binding, type, 1, vk::ShaderStageFlagBits::eAllGraphics};
+}
+
+// ...
+void App::create_pipeline_layout() {
+  static constexpr auto set_0_bindings_v = std::array{
+    layout_binding(0, vk::DescriptorType::eUniformBuffer),
+  };
+  auto set_layout_cis = std::array<vk::DescriptorSetLayoutCreateInfo, 1>{};
+  set_layout_cis[0].setBindings(set_0_bindings_v);
+
+  for (auto const& set_layout_ci : set_layout_cis) {
+    m_set_layouts.push_back(
+      m_device->createDescriptorSetLayoutUnique(set_layout_ci));
+    m_set_layout_views.push_back(*m_set_layouts.back());
+  }
+
+  auto pipeline_layout_ci = vk::PipelineLayoutCreateInfo{};
+  pipeline_layout_ci.setSetLayouts(m_set_layout_views);
+  m_pipeline_layout =
+    m_device->createPipelineLayoutUnique(pipeline_layout_ci);
+}
+```
+
+Add a helper function that allocates a set of descriptor sets for the entire layout:
+
+```cpp
+auto App::allocate_sets() const -> std::vector<vk::DescriptorSet> {
+  auto allocate_info = vk::DescriptorSetAllocateInfo{};
+  allocate_info.setDescriptorPool(*m_descriptor_pool)
+    .setSetLayouts(m_set_layout_views);
+  return m_device->allocateDescriptorSets(allocate_info);
+}
+```
+
+Store a Buffered copy of descriptor sets for one drawable object:
+
+```cpp
+Buffered<std::vector<vk::DescriptorSet>> m_descriptor_sets{};
+
+// ...
+
+void App::create_descriptor_sets() {
+  for (auto& descriptor_sets : m_descriptor_sets) {
+    descriptor_sets = allocate_sets();
+  }
+}
+```

src/app.cpp

@@ -18,6 +18,12 @@ template <typename T>
 	return std::bit_cast<std::array<std::byte, sizeof(T)>>(t);
 }
 
+constexpr auto layout_binding(std::uint32_t binding,
+							  vk::DescriptorType const type) {
+	return vk::DescriptorSetLayoutBinding{
+		binding, type, 1, vk::ShaderStageFlagBits::eAllGraphics};
+}
+
 [[nodiscard]] auto locate_assets_dir() -> fs::path {
 	// look for '<path>/assets/', starting from the working
 	// directory and walking up the parent directory tree.
@@ -88,10 +94,12 @@ void App::run() {
 	create_swapchain();
 	create_render_sync();
 	create_imgui();
+	create_descriptor_pool();
+	create_pipeline_layout();
 	create_shader();
 	create_cmd_block_pool();
 
-	create_vertex_buffer();
+	create_descriptor_sets();
 
 	main_loop();
 }
@@ -243,6 +251,36 @@ void App::create_allocator() {
 	m_allocator = vma::create_allocator(*m_instance, m_gpu.device, *m_device);
 }
 
+void App::create_descriptor_pool() {
+	static constexpr auto pool_sizes_v = std::array{
+		// 2 uniform buffers, can be more if desired.
+		vk::DescriptorPoolSize{vk::DescriptorType::eUniformBuffer, 2},
+	};
+	auto pool_ci = vk::DescriptorPoolCreateInfo{};
+	// allow 16 sets to be allocated from this pool.
+	pool_ci.setPoolSizes(pool_sizes_v).setMaxSets(16);
+	m_descriptor_pool = m_device->createDescriptorPoolUnique(pool_ci);
+}
+
+void App::create_pipeline_layout() {
+	static constexpr auto set_0_bindings_v = std::array{
+		layout_binding(0, vk::DescriptorType::eUniformBuffer),
+	};
+	auto set_layout_cis = std::array<vk::DescriptorSetLayoutCreateInfo, 1>{};
+	set_layout_cis[0].setBindings(set_0_bindings_v);
+
+	for (auto const& set_layout_ci : set_layout_cis) {
+		m_set_layouts.push_back(
+			m_device->createDescriptorSetLayoutUnique(set_layout_ci));
+		m_set_layout_views.push_back(*m_set_layouts.back());
+	}
+
+	auto pipeline_layout_ci = vk::PipelineLayoutCreateInfo{};
+	pipeline_layout_ci.setSetLayouts(m_set_layout_views);
+	m_pipeline_layout =
+		m_device->createPipelineLayoutUnique(pipeline_layout_ci);
+}
+
 void App::create_shader() {
 	auto const vertex_spirv = to_spir_v(asset_path("shader.vert"));
 	auto const fragment_spirv = to_spir_v(asset_path("shader.frag"));
@@ -298,6 +336,12 @@ void App::create_vertex_buffer() {
 	};
 	m_vbo = vma::create_device_buffer(buffer_ci, create_command_block(),
 									  total_bytes_v);
+
+
+void App::create_descriptor_sets() {
+	for (auto& descriptor_sets : m_descriptor_sets) {
+		descriptor_sets = allocate_sets();
+	}
 }
 
 auto App::asset_path(std::string_view const uri) const -> fs::path {
@@ -308,6 +352,13 @@ auto App::create_command_block() const -> CommandBlock {
 	return CommandBlock{*m_device, m_queue, *m_cmd_block_pool};
 }
 
+auto App::allocate_sets() const -> std::vector<vk::DescriptorSet> {
+	auto allocate_info = vk::DescriptorSetAllocateInfo{};
+	allocate_info.setDescriptorPool(*m_descriptor_pool)
+		.setSetLayouts(m_set_layout_views);
+	return m_device->allocateDescriptorSets(allocate_info);
+}
+
 void App::main_loop() {
 	while (glfwWindowShouldClose(m_window.get()) == GLFW_FALSE) {
 		glfwPollEvents();

src/app.hpp

@@ -38,12 +38,15 @@ class App {
 	void create_render_sync();
 	void create_imgui();
 	void create_allocator();
+	void create_descriptor_pool();
+	void create_pipeline_layout();
 	void create_shader();
 	void create_cmd_block_pool();
-	void create_vertex_buffer();
+	void create_descriptor_sets();
 
 	[[nodiscard]] auto asset_path(std::string_view uri) const -> fs::path;
 	[[nodiscard]] auto create_command_block() const -> CommandBlock;
+	[[nodiscard]] auto allocate_sets() const -> std::vector<vk::DescriptorSet>;
 
 	void main_loop();
 
@@ -82,9 +85,15 @@ class App {
 
 	std::optional<DearImGui> m_imgui{};
 
+	vk::UniqueDescriptorPool m_descriptor_pool{};
+	std::vector<vk::UniqueDescriptorSetLayout> m_set_layouts{};
+	std::vector<vk::DescriptorSetLayout> m_set_layout_views{};
+	vk::UniquePipelineLayout m_pipeline_layout{};
+
 	std::optional<ShaderProgram> m_shader{};
 
 	vma::Buffer m_vbo{};
+	Buffered<std::vector<vk::DescriptorSet>> m_descriptor_sets{};
 
 	glm::ivec2 m_framebuffer_size{};
 	std::optional<RenderTarget> m_render_target{};