Instanced rendering

Author: karnkaul

assets/shader.vert

@@ -48,3 +48,4 @@
   - [Shader Buffer](descriptor_sets/shader_buffer.md)
   - [Texture](descriptor_sets/texture.md)
   - [View Matrix](descriptor_sets/view_matrix.md)
+  - [Instanced Rendering](descriptor_sets/instanced_rendering.md)

guide/src/SUMMARY.md

@@ -0,0 +1,132 @@
+# Instanced Rendering
+
+When multiple copies of a drawable object are desired, one option is to use instanced rendering. The basic idea is to store per-instance data in a uniform/storage buffer and index into it in the vertex shader. We shall represent one model matrix per instance, feel free to add more data like an overall tint (color) that gets multiplied to the existing output color in the fragment shader. This will be bound to a Storage Buffer (SSBO), which can be "unbounded" in the shader (size is determined during invocation).
+
+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{};
+```
+
+Add two `Transform`s as the source of rendering instances, and a function to update the matrices:
+
+```cpp
+void update_instances();
+
+// ...
+std::array<Transform, 2> m_instances{}; // generates model matrices.
+
+// ...
+void App::update_instances() {
+  m_instance_data.clear();
+  m_instance_data.reserve(m_instances.size());
+  for (auto const& transform : m_instances) {
+    m_instance_data.push_back(transform.model_matrix());
+  }
+  // can't use bit_cast anymore, reinterpret data as a byte array instead.
+  auto const span = std::span{m_instance_data};
+  void* data = span.data();
+  auto const bytes =
+    std::span{static_cast<std::byte const*>(data), span.size_bytes()};
+  m_instance_ssbo->write_at(m_frame_index, bytes);
+}
+```
+
+Update the descriptor pool to also provide storage buffers:
+
+```cpp
+// ...
+vk::DescriptorPoolSize{vk::DescriptorType::eCombinedImageSampler, 2},
+vk::DescriptorPoolSize{vk::DescriptorType::eStorageBuffer, 2},
+```
+
+This time add a new binding to set 1 (instead of a new set):
+
+```cpp
+static constexpr auto set_1_bindings_v = std::array{
+  layout_binding(0, vk::DescriptorType::eCombinedImageSampler),
+  layout_binding(1, vk::DescriptorType::eStorageBuffer),
+};
+```
+
+Create the instance SSBO after the view UBO:
+
+```cpp
+m_instance_ssbo.emplace(m_allocator.get(), m_gpu.queue_family,
+                        vk::BufferUsageFlagBits::eStorageBuffer);
+```
+
+Call `update_instances()` after `update_view()`:
+
+```cpp
+// ...
+update_view();
+update_instances();
+```
+
+Extract transform inspection into a lambda and inspect each instance transform too:
+
+```cpp
+static auto const inspect_transform = [](Transform& out) {
+  ImGui::DragFloat2("position", &out.position.x);
+  ImGui::DragFloat("rotation", &out.rotation);
+  ImGui::DragFloat2("scale", &out.scale.x, 0.1f);
+};
+
+ImGui::Separator();
+if (ImGui::TreeNode("View")) {
+  inspect_transform(m_view_transform);
+  ImGui::TreePop();
+}
+
+ImGui::Separator();
+if (ImGui::TreeNode("Instances")) {
+  for (std::size_t i = 0; i < m_instances.size(); ++i) {
+    auto const label = std::to_string(i);
+    if (ImGui::TreeNode(label.c_str())) {
+      inspect_transform(m_instances.at(i));
+      ImGui::TreePop();
+    }
+  }
+  ImGui::TreePop();
+}
+```
+
+Add another descriptor write for the SSBO:
+
+```cpp
+auto writes = std::array<vk::WriteDescriptorSet, 3>{};
+// ...
+auto const instance_ssbo_info =
+  m_instance_ssbo->descriptor_info_at(m_frame_index);
+write.setBufferInfo(instance_ssbo_info)
+  .setDescriptorType(vk::DescriptorType::eStorageBuffer)
+  .setDescriptorCount(1)
+  .setDstSet(set1)
+  .setDstBinding(1);
+writes[2] = write;
+```
+
+Finally, change the instance count in the draw call:
+
+```cpp
+auto const instances = static_cast<std::uint32_t>(m_instances.size());
+// m_vbo has 6 indices.
+command_buffer.drawIndexed(6, instances, 0, 0, 0);
+```
+
+Update the vertex shader to incorporate the instance model matrix:
+
+```glsl
+// ...
+layout (set = 1, binding = 1) readonly buffer Instances {
+  mat4 mat_ms[];
+};
+
+// ...
+const mat4 mat_m = mat_ms[gl_InstanceIndex];
+const vec4 world_pos = mat_m * vec4(a_pos, 0.0, 1.0);
+```
+
+![Instanced Rendering](./instanced_rendering.png)

guide/src/descriptor_sets/instanced_rendering.md

@@ -55,7 +55,7 @@ auto Transform::view_matrix() const -> glm::mat4 {
 Add a `Transform` member to `App` to represent the view/camera, inspect its members, and combine with the existing projection matrix:
 
 ```cpp
-Transform m_view_transform{};
+Transform m_view_transform{}; // generates view matrix.
 
 // ...
 ImGui::Separator();

guide/src/descriptor_sets/instanced_rendering.png

@@ -258,6 +258,7 @@ void App::create_descriptor_pool() {
 		// 2 uniform buffers, can be more if desired.
 		vk::DescriptorPoolSize{vk::DescriptorType::eUniformBuffer, 2},
 		vk::DescriptorPoolSize{vk::DescriptorType::eCombinedImageSampler, 2},
+		vk::DescriptorPoolSize{vk::DescriptorType::eStorageBuffer, 2},
 	};
 	auto pool_ci = vk::DescriptorPoolCreateInfo{};
 	// allow 16 sets to be allocated from this pool.
@@ -271,6 +272,7 @@ void App::create_pipeline_layout() {
 	};
 	static constexpr auto set_1_bindings_v = std::array{
 		layout_binding(0, vk::DescriptorType::eCombinedImageSampler),
+		layout_binding(1, vk::DescriptorType::eStorageBuffer),
 	};
 	auto set_layout_cis = std::array<vk::DescriptorSetLayoutCreateInfo, 2>{};
 	set_layout_cis[0].setBindings(set_0_bindings_v);
@@ -347,6 +349,9 @@ void App::create_shader_resources() {
 	m_view_ubo.emplace(m_allocator.get(), m_gpu.queue_family,
 					   vk::BufferUsageFlagBits::eUniformBuffer);
 
+	m_instance_ssbo.emplace(m_allocator.get(), m_gpu.queue_family,
+							vk::BufferUsageFlagBits::eStorageBuffer);
+
 	using Pixel = std::array<std::byte, 4>;
 	static constexpr auto rgby_pixels_v = std::array{
 		Pixel{std::byte{0xff}, {}, {}, std::byte{0xff}},
@@ -484,6 +489,7 @@ void App::render(vk::CommandBuffer const command_buffer) {
 	command_buffer.beginRendering(rendering_info);
 	inspect();
 	update_view();
+	update_instances();
 	draw(command_buffer);
 	command_buffer.endRendering();
 
@@ -564,11 +570,27 @@ void App::inspect() {
 							 line_width_range[0], line_width_range[1]);
 		}
 
+		static auto const inspect_transform = [](Transform& out) {
+			ImGui::DragFloat2("position", &out.position.x);
+			ImGui::DragFloat("rotation", &out.rotation);
+			ImGui::DragFloat2("scale", &out.scale.x, 0.1f);
+		};
+
 		ImGui::Separator();
 		if (ImGui::TreeNode("View")) {
-			ImGui::DragFloat2("position", &m_view_transform.position.x);
-			ImGui::DragFloat("rotation", &m_view_transform.rotation);
-			ImGui::DragFloat2("scale", &m_view_transform.scale.x, 0.1f);
+			inspect_transform(m_view_transform);
+			ImGui::TreePop();
+		}
+
+		ImGui::Separator();
+		if (ImGui::TreeNode("Instances")) {
+			for (std::size_t i = 0; i < m_instances.size(); ++i) {
+				auto const label = std::to_string(i);
+				if (ImGui::TreeNode(label.c_str())) {
+					inspect_transform(m_instances.at(i));
+					ImGui::TreePop();
+				}
+			}
 			ImGui::TreePop();
 		}
 	}
@@ -586,6 +608,20 @@ void App::update_view() {
 	m_view_ubo->write_at(m_frame_index, bytes);
 }
 
+void App::update_instances() {
+	m_instance_data.clear();
+	m_instance_data.reserve(m_instances.size());
+	for (auto const& transform : m_instances) {
+		m_instance_data.push_back(transform.model_matrix());
+	}
+	// can't use bit_cast anymore, reinterpret data as a byte array instead.
+	auto const span = std::span{m_instance_data};
+	void* data = span.data();
+	auto const bytes =
+		std::span{static_cast<std::byte const*>(data), span.size_bytes()};
+	m_instance_ssbo->write_at(m_frame_index, bytes);
+}
+
 void App::draw(vk::CommandBuffer const command_buffer) const {
 	m_shader->bind(command_buffer, m_framebuffer_size);
 	bind_descriptor_sets(command_buffer);
@@ -594,12 +630,13 @@ void App::draw(vk::CommandBuffer const command_buffer) const {
 	// u32 indices after offset of 4 vertices.
 	command_buffer.bindIndexBuffer(m_vbo.get().buffer, 4 * sizeof(Vertex),
 								   vk::IndexType::eUint32);
+	auto const instances = static_cast<std::uint32_t>(m_instances.size());
 	// m_vbo has 6 indices.
-	command_buffer.drawIndexed(6, 1, 0, 0, 0);
+	command_buffer.drawIndexed(6, instances, 0, 0, 0);
 }
 
 void App::bind_descriptor_sets(vk::CommandBuffer const command_buffer) const {
-	auto writes = std::array<vk::WriteDescriptorSet, 2>{};
+	auto writes = std::array<vk::WriteDescriptorSet, 3>{};
 	auto const& descriptor_sets = m_descriptor_sets.at(m_frame_index);
 	auto const set0 = descriptor_sets[0];
 	auto write = vk::WriteDescriptorSet{};
@@ -619,6 +656,14 @@ void App::bind_descriptor_sets(vk::CommandBuffer const command_buffer) const {
 		.setDstSet(set1)
 		.setDstBinding(0);
 	writes[1] = write;
+	auto const instance_ssbo_info =
+		m_instance_ssbo->descriptor_info_at(m_frame_index);
+	write.setBufferInfo(instance_ssbo_info)
+		.setDescriptorType(vk::DescriptorType::eStorageBuffer)
+		.setDescriptorCount(1)
+		.setDstSet(set1)
+		.setDstBinding(1);
+	writes[2] = write;
 
 	m_device->updateDescriptorSets(writes, {});
 

guide/src/descriptor_sets/view_matrix.md

@@ -64,6 +64,7 @@ class App {
 	// ImGui code goes here.
 	void inspect();
 	void update_view();
+	void update_instances();
 	// Issue draw calls here.
 	void draw(vk::CommandBuffer command_buffer) const;
 
@@ -102,13 +103,16 @@ class App {
 	vma::Buffer m_vbo{};
 	std::optional<ShaderBuffer> m_view_ubo{};
 	std::optional<Texture> m_texture{};
+	std::vector<glm::mat4> m_instance_data{}; // model matrices.
+	std::optional<ShaderBuffer> m_instance_ssbo{};
 	Buffered<std::vector<vk::DescriptorSet>> m_descriptor_sets{};
 
 	glm::ivec2 m_framebuffer_size{};
 	std::optional<RenderTarget> m_render_target{};
 	bool m_wireframe{};
 
-	Transform m_view_transform{};
+	Transform m_view_transform{};			// generates view matrix.
+	std::array<Transform, 2> m_instances{}; // generates model matrices.
 
 	// waiter must be the last member to ensure it blocks until device is idle
 	// before other members get destroyed.

src/app.cpp

@@ -8,11 +8,16 @@ layout (set = 0, binding = 0) uniform View {
 	mat4 mat_vp;
 };
 
+layout (set = 1, binding = 1) readonly buffer Instances {
+	mat4 mat_ms[];
+};
+
 layout (location = 0) out vec3 out_color;
 layout (location = 1) out vec2 out_uv;
 
 void main() {
-	const vec4 world_pos = vec4(a_pos, 0.0, 1.0);
+	const mat4 mat_m = mat_ms[gl_InstanceIndex];
+	const vec4 world_pos = mat_m * vec4(a_pos, 0.0, 1.0);
 
 	out_color = a_color;
 	out_uv = a_uv;