Rename ShaderBuffer to DescriptorBuffer

Author: karnkaul

guide/src/SUMMARY.md

@@ -45,7 +45,7 @@
   - [Images](memory/images.md)
 - [Descriptor Sets](descriptor_sets/README.md)
   - [Pipeline Layout](descriptor_sets/pipeline_layout.md)
-  - [Shader Buffer](descriptor_sets/shader_buffer.md)
+  - [Descriptor Buffer](descriptor_sets/descriptor_buffer.md)
   - [Texture](descriptor_sets/texture.md)
   - [View Matrix](descriptor_sets/view_matrix.md)
   - [Instanced Rendering](descriptor_sets/instanced_rendering.md)

guide/src/descriptor_sets/shader_buffer.md renamed to guide/src/descriptor_sets/descriptor_buffer.md

@@ -1,81 +1,82 @@
-# Shader Buffer
+# Descriptor Buffer
 
-Uniform and Storage buffers need to be N-buffered unless they are "GPU const", ie contents do not change after creation.  Encapsulate a `vma::Buffer` per virtual frame in a `ShaderBuffer`:
+Uniform and Storage buffers need to be N-buffered unless they are "GPU const", ie contents do not change after creation.  Encapsulate a `vma::Buffer` per virtual frame in a `DescriptorBuffer`:
 
 ```cpp
-class ShaderBuffer {
- public:
-  explicit ShaderBuffer(VmaAllocator allocator, std::uint32_t queue_family,
-                        vk::BufferUsageFlags usage);
+class DescriptorBuffer {
+  public:
+	explicit DescriptorBuffer(VmaAllocator allocator,
+							  std::uint32_t queue_family,
+							  vk::BufferUsageFlags usage);
 
-  void write_at(std::size_t frame_index, std::span<std::byte const> bytes);
+	void write_at(std::size_t frame_index, std::span<std::byte const> bytes);
 
-  [[nodiscard]] auto descriptor_info_at(std::size_t frame_index) const
-    -> vk::DescriptorBufferInfo;
+	[[nodiscard]] auto descriptor_info_at(std::size_t frame_index) const
+		-> vk::DescriptorBufferInfo;
 
- private:
-  struct Buffer {
-    vma::Buffer buffer{};
-    vk::DeviceSize size{};
-  };
+  private:
+	struct Buffer {
+		vma::Buffer buffer{};
+		vk::DeviceSize size{};
+	};
 
-  void write_to(Buffer& out, std::span<std::byte const> bytes) const;
+	void write_to(Buffer& out, std::span<std::byte const> bytes) const;
 
-  VmaAllocator m_allocator{};
-  std::uint32_t m_queue_family{};
-  vk::BufferUsageFlags m_usage{};
-  Buffered<Buffer> m_buffers{};
+	VmaAllocator m_allocator{};
+	std::uint32_t m_queue_family{};
+	vk::BufferUsageFlags m_usage{};
+	Buffered<Buffer> m_buffers{};
 };
 ```
 
 The implementation is fairly straightforward, it reuses existing buffers if they are large enough, else recreates them before copying data. It also ensures buffers are always valid to be bound to descriptors.
 
 ```cpp
-ShaderBuffer::ShaderBuffer(VmaAllocator allocator,
-                           std::uint32_t const queue_family,
-                           vk::BufferUsageFlags const usage)
-  : m_allocator(allocator), m_queue_family(queue_family), m_usage(usage) {
-  // ensure buffers are created and can be bound after returning.
-  for (auto& buffer : m_buffers) { write_to(buffer, {}); }
+DescriptorBuffer::DescriptorBuffer(VmaAllocator allocator,
+								   std::uint32_t const queue_family,
+								   vk::BufferUsageFlags const usage)
+	: m_allocator(allocator), m_queue_family(queue_family), m_usage(usage) {
+	// ensure buffers are created and can be bound after returning.
+	for (auto& buffer : m_buffers) { write_to(buffer, {}); }
 }
 
-void ShaderBuffer::write_at(std::size_t const frame_index,
-                            std::span<std::byte const> bytes) {
-  write_to(m_buffers.at(frame_index), bytes);
+void DescriptorBuffer::write_at(std::size_t const frame_index,
+								std::span<std::byte const> bytes) {
+	write_to(m_buffers.at(frame_index), bytes);
 }
 
-auto ShaderBuffer::descriptor_info_at(std::size_t const frame_index) const
-  -> vk::DescriptorBufferInfo {
-  auto const& buffer = m_buffers.at(frame_index);
-  auto ret = vk::DescriptorBufferInfo{};
-  ret.setBuffer(buffer.buffer.get().buffer).setRange(buffer.size);
-  return ret;
+auto DescriptorBuffer::descriptor_info_at(std::size_t const frame_index) const
+	-> vk::DescriptorBufferInfo {
+	auto const& buffer = m_buffers.at(frame_index);
+	auto ret = vk::DescriptorBufferInfo{};
+	ret.setBuffer(buffer.buffer.get().buffer).setRange(buffer.size);
+	return ret;
 }
 
-void ShaderBuffer::write_to(Buffer& out,
-                            std::span<std::byte const> bytes) const {
-  static constexpr auto blank_byte_v = std::array{std::byte{}};
-  // fallback to an empty byte if bytes is empty.
-  if (bytes.empty()) { bytes = blank_byte_v; }
-  out.size = bytes.size();
-  if (out.buffer.get().size < bytes.size()) {
-    // size is too small (or buffer doesn't exist yet), recreate buffer.
-    auto const buffer_ci = vma::BufferCreateInfo{
-      .allocator = m_allocator,
-      .usage = m_usage,
-      .queue_family = m_queue_family,
-    };
-    out.buffer = vma::create_buffer(buffer_ci, vma::BufferMemoryType::Host,
-                    out.size);
-  }
-  std::memcpy(out.buffer.get().mapped, bytes.data(), bytes.size());
+void DescriptorBuffer::write_to(Buffer& out,
+								std::span<std::byte const> bytes) const {
+	static constexpr auto blank_byte_v = std::array{std::byte{}};
+	// fallback to an empty byte if bytes is empty.
+	if (bytes.empty()) { bytes = blank_byte_v; }
+	out.size = bytes.size();
+	if (out.buffer.get().size < bytes.size()) {
+		// size is too small (or buffer doesn't exist yet), recreate buffer.
+		auto const buffer_ci = vma::BufferCreateInfo{
+			.allocator = m_allocator,
+			.usage = m_usage,
+			.queue_family = m_queue_family,
+		};
+		out.buffer = vma::create_buffer(buffer_ci, vma::BufferMemoryType::Host,
+										out.size);
+	}
+	std::memcpy(out.buffer.get().mapped, bytes.data(), bytes.size());
 }
 ```
 
-Store a `ShaderBuffer` in `App` and rename `create_vertex_buffer()` to `create_shader_resources()`:
+Store a `DescriptorBuffer` in `App` and rename `create_vertex_buffer()` to `create_shader_resources()`:
 
 ```cpp
-std::optional<ShaderBuffer> m_view_ubo{};
+std::optional<DescriptorBuffer> m_view_ubo{};
 
 // ...
 m_vbo = vma::create_device_buffer(buffer_ci, create_command_block(),
@@ -170,4 +171,4 @@ static constexpr auto vertices_v = std::array{
 
 ![View UBO](./view_ubo.png)
 
-When such shader buffers are created and (more importantly) destroyed dynamically, they would need to store a `ScopedWaiter` to ensure all rendering with descriptor sets bound to them completes before destruction. Alternatively, the app can maintain a pool of scratch buffers (similar to small/dynamic vertex buffers) per virtual frame which get destroyed in a batch instead of individually.
+When such descriptor buffers are created and destroyed dynamically, they would need to store a `ScopedWaiter` to ensure all rendering with descriptor sets bound to them completes before destruction. Alternatively, the app can maintain a pool of scratch buffers (similar to small/dynamic vertex buffers) per virtual frame which get destroyed in a batch instead of individually.

guide/src/descriptor_sets/instanced_rendering.md

@@ -6,7 +6,7 @@ Store the SSBO and a buffer for instance matrices:
 
 ```cpp
 std::vector<glm::mat4> m_instance_data{}; // model matrices.
-std::optional<ShaderBuffer> m_instance_ssbo{};
+std::optional<DescriptorBuffer> m_instance_ssbo{};
 ```
 
 Add two `Transform`s as the source of rendering instances, and a function to update the matrices:

src/app.hpp

@@ -1,10 +1,10 @@
 #pragma once
 #include <command_block.hpp>
 #include <dear_imgui.hpp>
+#include <descriptor_buffer.hpp>
 #include <gpu.hpp>
 #include <resource_buffering.hpp>
 #include <scoped_waiter.hpp>
-#include <shader_buffer.hpp>
 #include <shader_program.hpp>
 #include <swapchain.hpp>
 #include <texture.hpp>
@@ -101,10 +101,10 @@ class App {
 	std::optional<ShaderProgram> m_shader{};
 
 	vma::Buffer m_vbo{};
-	std::optional<ShaderBuffer> m_view_ubo{};
+	std::optional<DescriptorBuffer> m_view_ubo{};
 	std::optional<Texture> m_texture{};
 	std::vector<glm::mat4> m_instance_data{}; // model matrices.
-	std::optional<ShaderBuffer> m_instance_ssbo{};
+	std::optional<DescriptorBuffer> m_instance_ssbo{};
 	Buffered<std::vector<vk::DescriptorSet>> m_descriptor_sets{};
 
 	glm::ivec2 m_framebuffer_size{};

src/shader_buffer.cpp renamed to src/descriptor_buffer.cpp

@@ -1,29 +1,29 @@
-#include <shader_buffer.hpp>
+#include <descriptor_buffer.hpp>
 
 namespace lvk {
-ShaderBuffer::ShaderBuffer(VmaAllocator allocator,
-						   std::uint32_t const queue_family,
-						   vk::BufferUsageFlags const usage)
+DescriptorBuffer::DescriptorBuffer(VmaAllocator allocator,
+								   std::uint32_t const queue_family,
+								   vk::BufferUsageFlags const usage)
 	: m_allocator(allocator), m_queue_family(queue_family), m_usage(usage) {
 	// ensure buffers are created and can be bound after returning.
 	for (auto& buffer : m_buffers) { write_to(buffer, {}); }
 }
 
-void ShaderBuffer::write_at(std::size_t const frame_index,
-							std::span<std::byte const> bytes) {
+void DescriptorBuffer::write_at(std::size_t const frame_index,
+								std::span<std::byte const> bytes) {
 	write_to(m_buffers.at(frame_index), bytes);
 }
 
-auto ShaderBuffer::descriptor_info_at(std::size_t const frame_index) const
+auto DescriptorBuffer::descriptor_info_at(std::size_t const frame_index) const
 	-> vk::DescriptorBufferInfo {
 	auto const& buffer = m_buffers.at(frame_index);
 	auto ret = vk::DescriptorBufferInfo{};
 	ret.setBuffer(buffer.buffer.get().buffer).setRange(buffer.size);
 	return ret;
 }
 
-void ShaderBuffer::write_to(Buffer& out,
-							std::span<std::byte const> bytes) const {
+void DescriptorBuffer::write_to(Buffer& out,
+								std::span<std::byte const> bytes) const {
 	static constexpr auto blank_byte_v = std::array{std::byte{}};
 	// fallback to an empty byte if bytes is empty.
 	if (bytes.empty()) { bytes = blank_byte_v; }

src/shader_buffer.hpp renamed to src/descriptor_buffer.hpp

@@ -4,10 +4,11 @@
 #include <cstdint>
 
 namespace lvk {
-class ShaderBuffer {
+class DescriptorBuffer {
   public:
-	explicit ShaderBuffer(VmaAllocator allocator, std::uint32_t queue_family,
-						  vk::BufferUsageFlags usage);
+	explicit DescriptorBuffer(VmaAllocator allocator,
+							  std::uint32_t queue_family,
+							  vk::BufferUsageFlags usage);
 
 	void write_at(std::size_t frame_index, std::span<std::byte const> bytes);