Please check "CONFIGURATION SECTION" in the code to find macros that you can define before each include of this file or change directly in this file to provide your own implementation of basic facilities like assert, min() and max() functions, mutex, atomic etc. The library uses its own implementation of containers by default, but you can switch to using STL containers instead.
For example, define VMA_ASSERT(expr) before including the library to provide custom implementation of the assertion, compatible with your project. By default it is defined to standard C assert(expr) in _DEBUG configuration and empty otherwise.
There are multiple ways to import pointers to Vulkan functions in the library. In the simplest case you don't need to do anything. If the compilation or linking of your program or the initialization of the VmaAllocator doesn't work for you, you can try to reconfigure it.
+First, the allocator tries to fetch pointers to Vulkan functions linked statically, like this:
+If you want to disable this feature, set configuration macro: #define VMA_STATIC_VULKAN_FUNCTIONS 0.
Second, you can provide the pointers yourself by setting member VmaAllocatorCreateInfo::pVulkanFunctions. You can fetch them e.g. using functions vkGetInstanceProcAddr and vkGetDeviceProcAddr or by using a helper library like volk.
Third, VMA tries to fetch remaining pointers that are still null by calling vkGetInstanceProcAddr and vkGetDeviceProcAddr on its own. If you want to disable this feature, set configuration macro: #define VMA_DYNAMIC_VULKAN_FUNCTIONS 0.
Finally, all the function pointers required by the library (considering selected Vulkan version and enabled extensions) are checked with VMA_ASSERT if they are not null.
If you use custom allocator for CPU memory rather than default operator new and delete from C++, you can make this library using your allocator as well by filling optional member VmaAllocatorCreateInfo::pAllocationCallbacks. These functions will be passed to Vulkan, as well as used by the library itself to make any CPU-side allocations.
Device extensions VK_EXT_buffer_device_address / VK_KHR_buffer_device_address allow to fetch raw GPU pointer to a buffer and pass it for usage in a shader code. They are promoted to core Vulkan 1.2.
+Device extension VK_KHR_buffer_device_address allow to fetch raw GPU pointer to a buffer and pass it for usage in a shader code. It is promoted to core Vulkan 1.2.
If you want to use this feature in connection with VMA, follow these steps:
1) (For Vulkan version < 1.2) Call vkEnumerateDeviceExtensionProperties for the physical device. Check if the extension is supported - if returned array of VkExtensionProperties contains "VK_EXT_buffer_device_address" or "VK_KHR_buffer_device_address".
1) (For Vulkan version < 1.2) Call vkEnumerateDeviceExtensionProperties for the physical device. Check if the extension is supported - if returned array of VkExtensionProperties contains "VK_KHR_buffer_device_address".
2) Call vkGetPhysicalDeviceFeatures2 for the physical device instead of old vkGetPhysicalDeviceFeatures. Attach additional structure VkPhysicalDeviceBufferDeviceAddressFeatures* to VkPhysicalDeviceFeatures2::pNext to be returned. Check if the device feature is really supported - check if VkPhysicalDeviceBufferDeviceAddressFeatures*::bufferDeviceAddress is true.
3) (For Vulkan version < 1.2) While creating device with vkCreateDevice, enable this extension - add "VK_EXT_buffer_device_address" or "VK_KHR_buffer_device_address" to the list passed as VkDeviceCreateInfo::ppEnabledExtensionNames.
3) (For Vulkan version < 1.2) While creating device with vkCreateDevice, enable this extension - add "VK_KHR_buffer_device_address" to the list passed as VkDeviceCreateInfo::ppEnabledExtensionNames.
4) While creating the device, also don't set VkDeviceCreateInfo::pEnabledFeatures. Fill in VkPhysicalDeviceFeatures2 structure instead and pass it as VkDeviceCreateInfo::pNext. Enable this device feature - attach additional structure VkPhysicalDeviceBufferDeviceAddressFeatures* to VkPhysicalDeviceFeatures2::pNext and set its member bufferDeviceAddress to VK_TRUE.
5) While creating VmaAllocator with vmaCreateAllocator() inform VMA that you have enabled this feature - add VMA_ALLOCATOR_CREATE_BUFFER_DEVICE_ADDRESS_BIT to VmaAllocatorCreateInfo::flags.
After following steps described above, you can create buffers with VK_BUFFER_USAGE_SHADER_DEVICE_ADDRESS_BIT using VMA. The library automatically adds VK_MEMORY_ALLOCATE_DEVICE_ADDRESS_BIT_KHR to allocated memory blocks wherever it might be needed.
Please note that the library supports only VK_BUFFER_USAGE_SHADER_DEVICE_ADDRESS_BIT. The second part of this functionality related to "capture and replay" is not supported, as it is intended for usage in debugging tools like RenderDoc, not in everyday Vulkan usage.
After following steps described above, you can create buffers with VK_BUFFER_USAGE_SHADER_DEVICE_ADDRESS_BIT* using VMA. The library automatically adds VK_MEMORY_ALLOCATE_DEVICE_ADDRESS_BIT* to allocated memory blocks wherever it might be needed.
Please note that the library supports only VK_BUFFER_USAGE_SHADER_DEVICE_ADDRESS_BIT*. The second part of this functionality related to "capture and replay" is not supported, as it is intended for usage in debugging tools like RenderDoc, not in everyday Vulkan usage.
To learn more about this extension, see VK_KHR_buffer_device_address in Vulkan specification
diff --git a/docs/html/index.html b/docs/html/index.html index e89324e..c7adb70 100644 --- a/docs/html/index.html +++ b/docs/html/index.html @@ -145,6 +145,7 @@ Table of contentsOptional handle to Vulkan instance object.
-Optional, can be null. Must be set if VMA_ALLOCATOR_CREATE_EXT_MEMORY_BUDGET_BIT flas is used or if vulkanApiVersion >= VK_MAKE_VERSION(1, 1, 0).
Handle to Vulkan instance object.
+Starting from version 3.0.0 this member is no longer optional, it must be set!
Pointers to Vulkan functions. Can be null.
-You can pass null as this member, because the library will fetch pointers to Vulkan functions internally. Fill this member if you want to provide your own pointers to Vulkan functions, e.g. fetched using vkGetInstanceProcAddr() and vkGetDeviceProcAddr().
For details see Pointers to Vulkan functions.
Handle to Vulkan instance object.
-This is the same value as has been passed through VmaAllocatorCreateInfo::instance.
+This is the same value as has been passed through VmaAllocatorCreateInfo::instance.
Enables usage of "buffer device address" feature, which allows you to use function vkGetBufferDeviceAddress* to get raw GPU pointer to a buffer and pass it for usage inside a shader.
You may set this flag only if you:
VkPhysicalDeviceBufferDeviceAddressFeatures*::bufferDeviceAddress.When this flag is set, you can create buffers with VK_BUFFER_USAGE_SHADER_DEVICE_ADDRESS_BIT using VMA. The library automatically adds VK_MEMORY_ALLOCATE_DEVICE_ADDRESS_BIT_KHR to allocated memory blocks wherever it might be needed.
When this flag is set, you can create buffers with VK_BUFFER_USAGE_SHADER_DEVICE_ADDRESS_BIT* using VMA. The library automatically adds VK_MEMORY_ALLOCATE_DEVICE_ADDRESS_BIT* to allocated memory blocks wherever it might be needed.
For more information, see documentation chapter Enabling buffer device address.