VMA

Author: karnkaul

ext/CMakeLists.txt

@@ -27,6 +27,10 @@ target_compile_definitions(glm PUBLIC
 message(STATUS "[Vulkan-Headers]")
 add_subdirectory(src/Vulkan-Headers)
 
+# add VulkanMemoryAllocator to build tree
+message(STATUS "[VulkanMemoryAllocator]")
+add_subdirectory(src/VulkanMemoryAllocator)
+
 # setup Dear ImGui library
 message(STATUS "[Dear ImGui]")
 add_library(imgui)
@@ -55,6 +59,25 @@ target_sources(imgui PRIVATE
   src/imgui/backends/imgui_impl_vulkan.h
 )
 
+# setup vma library (source file with VMA interface)
+message(STATUS "[vma]")
+add_library(vma)
+add_library(vma::vma ALIAS vma)
+target_link_libraries(vma PUBLIC
+  Vulkan::Headers
+  GPUOpen::VulkanMemoryAllocator
+)
+target_compile_definitions(vma PUBLIC
+  VMA_STATIC_VULKAN_FUNCTIONS=0
+  VMA_DYNAMIC_VULKAN_FUNCTIONS=1
+)
+target_sources(vma PRIVATE
+  vk_mem_alloc.cpp
+)
+
+# ignore compiler warnings
+target_compile_options(vma PRIVATE -w)
+
 # declare ext library target
 add_library(${PROJECT_NAME} INTERFACE)
 add_library(learn-vk::ext ALIAS ${PROJECT_NAME})
@@ -63,6 +86,7 @@ add_library(learn-vk::ext ALIAS ${PROJECT_NAME})
 target_link_libraries(${PROJECT_NAME} INTERFACE
   glm::glm
   imgui::imgui
+  vma::vma
 )
 
 # setup preprocessor defines

ext/src.zip

@@ -0,0 +1,3 @@
+#define VMA_IMPLEMENTATION
+
+#include <vk_mem_alloc.h>

ext/vk_mem_alloc.cpp

@@ -33,3 +33,8 @@
   - [GLSL to SPIR-V](shader_objects/glsl_to_spir_v.md)
   - [Drawing a Triangle](shader_objects/drawing_triangle.md)
   - [Graphics Pipelines](shader_objects/pipelines.md)
+
+# Shader Resources
+
+- [Memory Allocation](memory/README.md)
+  - [Vulkan Memory Allocator](memory/vma.md)

guide/src/SUMMARY.md

@@ -0,0 +1,5 @@
+# Memory Allocation
+
+Being an explicit API, [allocating memory](https://docs.vulkan.org/guide/latest/memory_allocation.html) in Vulkan that can be used by the device is the application's responsibility. The specifics can get quite complicated, but as recommended by the spec, we shall simply defer all that to a library: [Vulkan Memory Allocator (VMA)](https://github.com/GPUOpen-LibrariesAndSDKs/VulkanMemoryAllocator).
+
+Vulkan exposes two kinds of objects that use such allocated memory: Buffers and Images, VMA offers transparent support for both: we just have to allocate/free buffers and images through VMA instead of the device directly. Unlike memory allocation / object construction on the CPU, there are many more parameters (than say alignment and size) to provide for the creation of buffers and images. As you might have guessed, we shall constrain ourselves to a subset that's relevant for shader resources: vertex buffers, uniform/storage buffers, and texture images.

guide/src/memory/README.md

@@ -0,0 +1,65 @@
+# Vulkan Memory Allocator
+
+VMA has full CMake support, but it is also a single-header library that requires users to "instantiate" it in a single translation unit. Isolating that into a wrapper library to minimize warning pollution etc, we create our own `vma::vma` target that compiles this source file:
+
+```cpp
+// vk_mem_alloc.cpp
+#define VMA_IMPLEMENTATION
+
+#include <vk_mem_alloc.h>
+```
+
+Unlike VulkanHPP, VMA's interface is C only, thus we shall use our `Scoped` class template to wrap objects in RAII types. The first thing we need is a `VmaAllocator`, which is similar to a `vk::Device` or `GLFWwindow*`:
+
+```cpp
+// vma.hpp
+namespace lvk::vma {
+struct Deleter {
+  void operator()(VmaAllocator allocator) const noexcept;
+};
+
+using Allocator = Scoped<VmaAllocator, Deleter>;
+
+[[nodiscard]] auto create_allocator(vk::Instance instance,
+                                    vk::PhysicalDevice physical_device,
+                                    vk::Device device) -> Allocator;
+} // namespace lvk::vma
+
+// vma.cpp
+void vma::Deleter::operator()(VmaAllocator allocator) const noexcept {
+  vmaDestroyAllocator(allocator);
+}
+
+auto vma::create_allocator(vk::Instance const instance,
+                           vk::PhysicalDevice const physical_device,
+                           vk::Device const device) -> Allocator {
+  auto const& dispatcher = VULKAN_HPP_DEFAULT_DISPATCHER;
+  // need to zero initialize C structs, unlike VulkanHPP.
+  auto vma_vk_funcs = VmaVulkanFunctions{};
+  vma_vk_funcs.vkGetInstanceProcAddr = dispatcher.vkGetInstanceProcAddr;
+  vma_vk_funcs.vkGetDeviceProcAddr = dispatcher.vkGetDeviceProcAddr;
+
+  auto allocator_ci = VmaAllocatorCreateInfo{};
+  allocator_ci.physicalDevice = physical_device;
+  allocator_ci.device = device;
+  allocator_ci.pVulkanFunctions = &vma_vk_funcs;
+  allocator_ci.instance = instance;
+  VmaAllocator ret{};
+  auto const result = vmaCreateAllocator(&allocator_ci, &ret);
+  if (result == VK_SUCCESS) { return ret; }
+
+  throw std::runtime_error{"Failed to create Vulkan Memory Allocator"};
+}
+```
+
+`App` stores and creates a `vma::Allocator` object:
+
+```cpp
+// ...
+vma::Allocator m_allocator{}; // anywhere between m_device and m_shader.
+
+// ...
+void App::create_allocator() {
+  m_allocator = vma::create_allocator(*m_instance, m_gpu.device, *m_device);
+}
+```

guide/src/memory/vma.md

@@ -228,6 +228,10 @@ void App::create_imgui() {
 	m_imgui.emplace(imgui_ci);
 }
 
+void App::create_allocator() {
+	m_allocator = vma::create_allocator(*m_instance, m_gpu.device, *m_device);
+}
+
 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"));

src/app.cpp

@@ -5,6 +5,7 @@
 #include <scoped_waiter.hpp>
 #include <shader_program.hpp>
 #include <swapchain.hpp>
+#include <vma.hpp>
 #include <window.hpp>
 #include <filesystem>
 
@@ -35,6 +36,7 @@ class App {
 	void create_swapchain();
 	void create_render_sync();
 	void create_imgui();
+	void create_allocator();
 	void create_shader();
 
 	[[nodiscard]] auto asset_path(std::string_view uri) const -> fs::path;
@@ -61,7 +63,8 @@ class App {
 	vk::UniqueSurfaceKHR m_surface{};
 	Gpu m_gpu{}; // not an RAII member.
 	vk::UniqueDevice m_device{};
-	vk::Queue m_queue{}; // not an RAII member.
+	vk::Queue m_queue{};		  // not an RAII member.
+	vma::Allocator m_allocator{}; // anywhere between m_device and m_shader.
 
 	std::optional<Swapchain> m_swapchain{};
 	// command pool for all render Command Buffers.

src/app.hpp

@@ -0,0 +1,29 @@
+#include <vma.hpp>
+#include <stdexcept>
+
+namespace lvk {
+void vma::Deleter::operator()(VmaAllocator allocator) const noexcept {
+	vmaDestroyAllocator(allocator);
+}
+
+auto vma::create_allocator(vk::Instance const instance,
+						   vk::PhysicalDevice const physical_device,
+						   vk::Device const device) -> Allocator {
+	auto const& dispatcher = VULKAN_HPP_DEFAULT_DISPATCHER;
+	// need to zero initialize C structs, unlike VulkanHPP.
+	auto vma_vk_funcs = VmaVulkanFunctions{};
+	vma_vk_funcs.vkGetInstanceProcAddr = dispatcher.vkGetInstanceProcAddr;
+	vma_vk_funcs.vkGetDeviceProcAddr = dispatcher.vkGetDeviceProcAddr;
+
+	auto allocator_ci = VmaAllocatorCreateInfo{};
+	allocator_ci.physicalDevice = physical_device;
+	allocator_ci.device = device;
+	allocator_ci.pVulkanFunctions = &vma_vk_funcs;
+	allocator_ci.instance = instance;
+	VmaAllocator ret{};
+	auto const result = vmaCreateAllocator(&allocator_ci, &ret);
+	if (result == VK_SUCCESS) { return ret; }
+
+	throw std::runtime_error{"Failed to create Vulkan Memory Allocator"};
+}
+} // namespace lvk

src/vma.cpp

@@ -0,0 +1,16 @@
+#pragma once
+#include <vk_mem_alloc.h>
+#include <scoped.hpp>
+#include <vulkan/vulkan.hpp>
+
+namespace lvk::vma {
+struct Deleter {
+	void operator()(VmaAllocator allocator) const noexcept;
+};
+
+using Allocator = Scoped<VmaAllocator, Deleter>;
+
+[[nodiscard]] auto create_allocator(vk::Instance instance,
+									vk::PhysicalDevice physical_device,
+									vk::Device device) -> Allocator;
+} // namespace lvk::vma