diff --git a/docs/html/allocation_annotation.html b/docs/html/allocation_annotation.html
index b729345..5b0b8ce 100644
--- a/docs/html/allocation_annotation.html
+++ b/docs/html/allocation_annotation.html
@@ -85,18 +85,18 @@ Allocation user data
vmaCreateBuffer(allocator, &bufferInfo, &allocCreateInfo, &buffer, &allocation,
nullptr);
VkResult vmaCreateBuffer(VmaAllocator allocator, const VkBufferCreateInfo *pBufferCreateInfo, const VmaAllocationCreateInfo *pAllocationCreateInfo, VkBuffer *pBuffer, VmaAllocation *pAllocation, VmaAllocationInfo *pAllocationInfo)
@ VMA_MEMORY_USAGE_GPU_ONLY
Definition: vk_mem_alloc.h:466
Definition: vk_mem_alloc.h:1116
void * pUserData
Custom general-purpose pointer that will be stored in VmaAllocation, can be read as VmaAllocationInfo...
Definition: vk_mem_alloc.h:1155
VmaMemoryUsage usage
Intended usage of memory.
Definition: vk_mem_alloc.h:1124
@ VMA_MEMORY_USAGE_GPU_ONLY
Definition: vk_mem_alloc.h:468
Definition: vk_mem_alloc.h:1120
void * pUserData
Custom general-purpose pointer that will be stored in VmaAllocation, can be read as VmaAllocationInfo...
Definition: vk_mem_alloc.h:1159
VmaMemoryUsage usage
Intended usage of memory.
Definition: vk_mem_alloc.h:1128
Represents single memory allocation.
The pointer may be later retrieved as VmaAllocationInfo::pUserData:
MyBufferMetadata* pMetadata = (MyBufferMetadata*)allocInfo.
pUserData;
void vmaGetAllocationInfo(VmaAllocator allocator, VmaAllocation allocation, VmaAllocationInfo *pAllocationInfo)
Returns current information about specified allocation.
-
Parameters of VmaAllocation objects, that can be retrieved using function vmaGetAllocationInfo().
Definition: vk_mem_alloc.h:1258
-
void * pUserData
Custom general-purpose pointer that was passed as VmaAllocationCreateInfo::pUserData or set using vma...
Definition: vk_mem_alloc.h:1305
+
Parameters of VmaAllocation objects, that can be retrieved using function vmaGetAllocationInfo().
Definition: vk_mem_alloc.h:1262
+
void * pUserData
Custom general-purpose pointer that was passed as VmaAllocationCreateInfo::pUserData or set using vma...
Definition: vk_mem_alloc.h:1309
It can also be changed using function vmaSetAllocationUserData().
Values of (non-zero) allocations' pUserData are printed in JSON report created by vmaBuildStatsString(), in hexadecimal form.
@@ -117,8 +117,8 @@ Allocation names
vmaCreateImage(allocator, &imageInfo, &allocCreateInfo, &image, &allocation,
nullptr);
VkResult vmaCreateImage(VmaAllocator allocator, const VkImageCreateInfo *pImageCreateInfo, const VmaAllocationCreateInfo *pAllocationCreateInfo, VkImage *pImage, VmaAllocation *pAllocation, VmaAllocationInfo *pAllocationInfo)
Function similar to vmaCreateBuffer().
@ VMA_ALLOCATION_CREATE_USER_DATA_COPY_STRING_BIT
Definition: vk_mem_alloc.h:550
VmaAllocationCreateFlags flags
Use VmaAllocationCreateFlagBits enum.
Definition: vk_mem_alloc.h:1118
@ VMA_ALLOCATION_CREATE_USER_DATA_COPY_STRING_BIT
Definition: vk_mem_alloc.h:552
VmaAllocationCreateFlags flags
Use VmaAllocationCreateFlagBits enum.
Definition: vk_mem_alloc.h:1122
The value of pUserData pointer of the allocation will be different than the one you passed when setting allocation's name - pointing to a buffer managed internally that holds copy of the string.
diff --git a/docs/html/choosing_memory_type.html b/docs/html/choosing_memory_type.html
index d1fb65c..a546db4 100644
--- a/docs/html/choosing_memory_type.html
+++ b/docs/html/choosing_memory_type.html
@@ -94,9 +94,9 @@ Usage
vmaCreateBuffer(allocator, &bufferInfo, &allocInfo, &buffer, &allocation,
nullptr);
VkResult vmaCreateBuffer(VmaAllocator allocator, const VkBufferCreateInfo *pBufferCreateInfo, const VmaAllocationCreateInfo *pAllocationCreateInfo, VkBuffer *pBuffer, VmaAllocation *pAllocation, VmaAllocationInfo *pAllocationInfo)
-
@ VMA_MEMORY_USAGE_GPU_ONLY
Definition: vk_mem_alloc.h:466
-
Definition: vk_mem_alloc.h:1116
-
VmaMemoryUsage usage
Intended usage of memory.
Definition: vk_mem_alloc.h:1124
+
@ VMA_MEMORY_USAGE_GPU_ONLY
Definition: vk_mem_alloc.h:468
+
Definition: vk_mem_alloc.h:1120
+
VmaMemoryUsage usage
Intended usage of memory.
Definition: vk_mem_alloc.h:1128
Represents single memory allocation.
Required and preferred flags
@@ -109,10 +109,10 @@ Required and preferred flags
VkBuffer buffer;
vmaCreateBuffer(allocator, &bufferInfo, &allocInfo, &buffer, &allocation,
nullptr);
-@ VMA_ALLOCATION_CREATE_MAPPED_BIT
Set this flag to use a memory that will be persistently mapped and retrieve pointer to it.
Definition: vk_mem_alloc.h:540
VkMemoryPropertyFlags preferredFlags
Flags that preferably should be set in a memory type chosen for an allocation.
Definition: vk_mem_alloc.h:1134
VkMemoryPropertyFlags requiredFlags
Flags that must be set in a Memory Type chosen for an allocation.
Definition: vk_mem_alloc.h:1129
VmaAllocationCreateFlags flags
Use VmaAllocationCreateFlagBits enum.
Definition: vk_mem_alloc.h:1118
@ VMA_ALLOCATION_CREATE_MAPPED_BIT
Set this flag to use a memory that will be persistently mapped and retrieve pointer to it.
Definition: vk_mem_alloc.h:542
VkMemoryPropertyFlags preferredFlags
Flags that preferably should be set in a memory type chosen for an allocation.
Definition: vk_mem_alloc.h:1138
VkMemoryPropertyFlags requiredFlags
Flags that must be set in a Memory Type chosen for an allocation.
Definition: vk_mem_alloc.h:1133
VmaAllocationCreateFlags flags
Use VmaAllocationCreateFlagBits enum.
Definition: vk_mem_alloc.h:1122
A memory type is chosen that has all the required flags and as many preferred flags set as possible.
If you use VmaAllocationCreateInfo::usage, it is just internally converted to a set of required and preferred flags.
@@ -127,7 +127,7 @@ Explicit memory types
VkBuffer buffer;
vmaCreateBuffer(allocator, &bufferInfo, &allocInfo, &buffer, &allocation,
nullptr);
-uint32_t memoryTypeBits
Bitmask containing one bit set for every memory type acceptable for this allocation.
Definition: vk_mem_alloc.h:1142
uint32_t memoryTypeBits
Bitmask containing one bit set for every memory type acceptable for this allocation.
Definition: vk_mem_alloc.h:1146
Custom memory pools
If you allocate from custom memory pool, all the ways of specifying memory requirements described above are not applicable and the aforementioned members of VmaAllocationCreateInfo structure are ignored. Memory type is selected explicitly when creating the pool and then used to make all the allocations from that pool. For further details, see Custom memory pools.
diff --git a/docs/html/custom_memory_pools.html b/docs/html/custom_memory_pools.html
index 2c2dbba..a15b91e 100644
--- a/docs/html/custom_memory_pools.html
+++ b/docs/html/custom_memory_pools.html
@@ -108,13 +108,13 @@ $(function() {
vmaCreateBuffer(allocator, &bufCreateInfo, &allocCreateInfo, &buf, &alloc, &allocInfo);
VkResult vmaCreatePool(VmaAllocator allocator, const VmaPoolCreateInfo *pCreateInfo, VmaPool *pPool)
Allocates Vulkan device memory and creates VmaPool object.
VkResult vmaCreateBuffer(VmaAllocator allocator, const VkBufferCreateInfo *pBufferCreateInfo, const VmaAllocationCreateInfo *pAllocationCreateInfo, VkBuffer *pBuffer, VmaAllocation *pAllocation, VmaAllocationInfo *pAllocationInfo)
Definition: vk_mem_alloc.h:1116
VmaPool pool
Pool that this allocation should be created in.
Definition: vk_mem_alloc.h:1148
Definition: vk_mem_alloc.h:1120
VmaPool pool
Pool that this allocation should be created in.
Definition: vk_mem_alloc.h:1152
Represents single memory allocation.
Parameters of VmaAllocation objects, that can be retrieved using function vmaGetAllocationInfo().
Definition: vk_mem_alloc.h:1258
Describes parameter of created VmaPool.
Definition: vk_mem_alloc.h:1167
uint32_t memoryTypeIndex
Vulkan memory type index to allocate this pool from.
Definition: vk_mem_alloc.h:1170
size_t maxBlockCount
Maximum number of blocks that can be allocated in this pool. Optional.
Definition: vk_mem_alloc.h:1196
Parameters of VmaAllocation objects, that can be retrieved using function vmaGetAllocationInfo().
Definition: vk_mem_alloc.h:1262
Describes parameter of created VmaPool.
Definition: vk_mem_alloc.h:1171
uint32_t memoryTypeIndex
Vulkan memory type index to allocate this pool from.
Definition: vk_mem_alloc.h:1174
size_t maxBlockCount
Maximum number of blocks that can be allocated in this pool. Optional.
Definition: vk_mem_alloc.h:1200
Represents custom memory pool.
You have to free all allocations made from this pool before destroying it.
@@ -139,8 +139,8 @@ Choosing memory type index
VkResult vmaFindMemoryTypeIndexForBufferInfo(VmaAllocator allocator, const VkBufferCreateInfo *pBufferCreateInfo, const VmaAllocationCreateInfo *pAllocationCreateInfo, uint32_t *pMemoryTypeIndex)
Helps to find memoryTypeIndex, given VkBufferCreateInfo and VmaAllocationCreateInfo.
-
@ VMA_MEMORY_USAGE_GPU_ONLY
Definition: vk_mem_alloc.h:466
-
VmaMemoryUsage usage
Intended usage of memory.
Definition: vk_mem_alloc.h:1124
+
@ VMA_MEMORY_USAGE_GPU_ONLY
Definition: vk_mem_alloc.h:468
+
VmaMemoryUsage usage
Intended usage of memory.
Definition: vk_mem_alloc.h:1128
When creating buffers/images allocated in that pool, provide following parameters:
VkBufferCreateInfo: Prefer to pass same parameters as above. Otherwise you risk creating resources in a memory type that is not suitable for them, which may result in undefined behavior. Using different VK_BUFFER_USAGE_ flags may work, but you shouldn't create images in a pool intended for buffers or the other way around.VkResult vmaBindBufferMemory(VmaAllocator allocator, VmaAllocation allocation, VkBuffer buffer)
Binds buffer to allocation.
void vmaGetAllocationInfo(VmaAllocator allocator, VmaAllocation allocation, VmaAllocationInfo *pAllocationInfo)
Returns current information about specified allocation.
VkResult vmaDefragmentationEnd(VmaAllocator allocator, VmaDefragmentationContext context)
Ends defragmentation process.
Parameters of VmaAllocation objects, that can be retrieved using function vmaGetAllocationInfo().
Definition: vk_mem_alloc.h:1258
Parameters of VmaAllocation objects, that can be retrieved using function vmaGetAllocationInfo().
Definition: vk_mem_alloc.h:1262
Represents main object of this library initialized.
Represents Opaque object that represents started defragmentation process.
Parameters for defragmentation.
Definition: vk_mem_alloc.h:1313
uint32_t allocationCount
Number of allocations in pAllocations array.
Definition: vk_mem_alloc.h:1319
VkBool32 * pAllocationsChanged
Optional, output. Pointer to array that will be filled with information whether the allocation at cer...
Definition: vk_mem_alloc.h:1333
uint32_t maxCpuAllocationsToMove
Maximum number of allocations that can be moved to a different place using transfers on CPU side,...
Definition: vk_mem_alloc.h:1362
const VmaAllocation * pAllocations
Pointer to array of allocations that can be defragmented.
Definition: vk_mem_alloc.h:1327
VkDeviceSize maxCpuBytesToMove
Maximum total numbers of bytes that can be copied while moving allocations to different places using ...
Definition: vk_mem_alloc.h:1357
Parameters for defragmentation.
Definition: vk_mem_alloc.h:1317
uint32_t allocationCount
Number of allocations in pAllocations array.
Definition: vk_mem_alloc.h:1323
VkBool32 * pAllocationsChanged
Optional, output. Pointer to array that will be filled with information whether the allocation at cer...
Definition: vk_mem_alloc.h:1337
uint32_t maxCpuAllocationsToMove
Maximum number of allocations that can be moved to a different place using transfers on CPU side,...
Definition: vk_mem_alloc.h:1366
const VmaAllocation * pAllocations
Pointer to array of allocations that can be defragmented.
Definition: vk_mem_alloc.h:1331
VkDeviceSize maxCpuBytesToMove
Maximum total numbers of bytes that can be copied while moving allocations to different places using ...
Definition: vk_mem_alloc.h:1361
Setting VmaDefragmentationInfo2::pAllocationsChanged is optional. This output array tells whether particular allocation in VmaDefragmentationInfo2::pAllocations at the same index has been modified during defragmentation. You can pass null, but you then need to query every allocation passed to defragmentation for new parameters using vmaGetAllocationInfo() if you might need to recreate and rebind a buffer or image associated with it.
If you use Custom memory pools, you can fill VmaDefragmentationInfo2::poolCount and VmaDefragmentationInfo2::pPools instead of VmaDefragmentationInfo2::allocationCount and VmaDefragmentationInfo2::pAllocations to defragment all allocations in given pools. You cannot use VmaDefragmentationInfo2::pAllocationsChanged in that case. You can also combine both methods.
@@ -203,9 +203,9 @@ Defragmenting GPU memory
}
}
-uint32_t maxGpuAllocationsToMove
Maximum number of allocations that can be moved to a different place using transfers on GPU side,...
Definition: vk_mem_alloc.h:1372
VkDeviceSize maxGpuBytesToMove
Maximum total numbers of bytes that can be copied while moving allocations to different places using ...
Definition: vk_mem_alloc.h:1367
VkCommandBuffer commandBuffer
Optional. Command buffer where GPU copy commands will be posted.
Definition: vk_mem_alloc.h:1381
uint32_t maxGpuAllocationsToMove
Maximum number of allocations that can be moved to a different place using transfers on GPU side,...
Definition: vk_mem_alloc.h:1376
VkDeviceSize maxGpuBytesToMove
Maximum total numbers of bytes that can be copied while moving allocations to different places using ...
Definition: vk_mem_alloc.h:1371
VkCommandBuffer commandBuffer
Optional. Command buffer where GPU copy commands will be posted.
Definition: vk_mem_alloc.h:1385
You can combine these two methods by specifying non-zero maxGpu* as well as maxCpu* parameters. The library automatically chooses best method to defragment each memory pool.
You may try not to block your entire program to wait until defragmentation finishes, but do it in the background, as long as you carefully fullfill requirements described in function vmaDefragmentationBegin().
diff --git a/docs/html/memory_mapping.html b/docs/html/memory_mapping.html
index 4d93fca..5e772c7 100644
--- a/docs/html/memory_mapping.html
+++ b/docs/html/memory_mapping.html
@@ -117,13 +117,13 @@ Persistently mapped memory
memcpy(allocInfo.
pMappedData, &constantBufferData,
sizeof(constantBufferData));
VkResult vmaCreateBuffer(VmaAllocator allocator, const VkBufferCreateInfo *pBufferCreateInfo, const VmaAllocationCreateInfo *pAllocationCreateInfo, VkBuffer *pBuffer, VmaAllocation *pAllocation, VmaAllocationInfo *pAllocationInfo)
@ VMA_MEMORY_USAGE_CPU_ONLY
Definition: vk_mem_alloc.h:476
@ VMA_ALLOCATION_CREATE_MAPPED_BIT
Set this flag to use a memory that will be persistently mapped and retrieve pointer to it.
Definition: vk_mem_alloc.h:540
Definition: vk_mem_alloc.h:1116
VmaMemoryUsage usage
Intended usage of memory.
Definition: vk_mem_alloc.h:1124
VmaAllocationCreateFlags flags
Use VmaAllocationCreateFlagBits enum.
Definition: vk_mem_alloc.h:1118
Parameters of VmaAllocation objects, that can be retrieved using function vmaGetAllocationInfo().
Definition: vk_mem_alloc.h:1258
void * pMappedData
Pointer to the beginning of this allocation as mapped data.
Definition: vk_mem_alloc.h:1300
@ VMA_MEMORY_USAGE_CPU_ONLY
Definition: vk_mem_alloc.h:478
@ VMA_ALLOCATION_CREATE_MAPPED_BIT
Set this flag to use a memory that will be persistently mapped and retrieve pointer to it.
Definition: vk_mem_alloc.h:542
Definition: vk_mem_alloc.h:1120
VmaMemoryUsage usage
Intended usage of memory.
Definition: vk_mem_alloc.h:1128
VmaAllocationCreateFlags flags
Use VmaAllocationCreateFlagBits enum.
Definition: vk_mem_alloc.h:1122
Parameters of VmaAllocation objects, that can be retrieved using function vmaGetAllocationInfo().
Definition: vk_mem_alloc.h:1262
void * pMappedData
Pointer to the beginning of this allocation as mapped data.
Definition: vk_mem_alloc.h:1304
There are some exceptions though, when you should consider mapping memory only for a short period of time:
- When operating system is Windows 7 or 8.x (Windows 10 is not affected because it uses WDDM2), device is discrete AMD GPU, and memory type is the special 256 MiB pool of
DEVICE_LOCAL + HOST_VISIBLE memory (selected when you use VMA_MEMORY_USAGE_CPU_TO_GPU), then whenever a memory block allocated from this memory type stays mapped for the time of any call to vkQueueSubmit() or vkQueuePresentKHR(), this block is migrated by WDDM to system RAM, which degrades performance. It doesn't matter if that particular memory block is actually used by the command buffer being submitted.
@@ -167,8 +167,8 @@ Finding out if memory is mappable
}
void vmaGetAllocationMemoryProperties(VmaAllocator allocator, VmaAllocation allocation, VkMemoryPropertyFlags *pFlags)
Given an allocation, returns Property Flags of its memory type.
@ VMA_MEMORY_USAGE_GPU_ONLY
Definition: vk_mem_alloc.h:466
VkMemoryPropertyFlags preferredFlags
Flags that preferably should be set in a memory type chosen for an allocation.
Definition: vk_mem_alloc.h:1134
@ VMA_MEMORY_USAGE_GPU_ONLY
Definition: vk_mem_alloc.h:468
VkMemoryPropertyFlags preferredFlags
Flags that preferably should be set in a memory type chosen for an allocation.
Definition: vk_mem_alloc.h:1138
You can even use VMA_ALLOCATION_CREATE_MAPPED_BIT flag while creating allocations that are not necessarily HOST_VISIBLE (e.g. using VMA_MEMORY_USAGE_GPU_ONLY). If the allocation ends up in memory type that is HOST_VISIBLE, it will be persistently mapped and you can use it directly. If not, the flag is just ignored. Example:
VkBufferCreateInfo bufCreateInfo = { VK_STRUCTURE_TYPE_BUFFER_CREATE_INFO };
bufCreateInfo.size = sizeof(ConstantBuffer);
diff --git a/docs/html/quick_start.html b/docs/html/quick_start.html
index 6e4393e..8f48f5e 100644
--- a/docs/html/quick_start.html
+++ b/docs/html/quick_start.html
@@ -81,14 +81,8 @@ Project setup
#define VMA_IMPLEMENTATION
#include "vk_mem_alloc.h"
It may be a good idea to create dedicated CPP file just for this purpose.
-
Note on language: This library is written in C++, but has C-compatible interface. Thus you can include and use vk_mem_alloc.h in C or C++ code, but full implementation with VMA_IMPLEMENTATION macro must be compiled as C++, NOT as C.
-
Please note that this library includes header <vulkan/vulkan.h>, which in turn includes <windows.h> on Windows. If you need some specific macros defined before including these headers (like WIN32_LEAN_AND_MEAN or WINVER for Windows, VK_USE_PLATFORM_WIN32_KHR for Vulkan), you must define them before every #include of this library.
-
You may need to configure the way you import Vulkan functions.
-
-- By default, VMA assumes you you link statically with Vulkan API. If this is not the case,
#define VMA_STATIC_VULKAN_FUNCTIONS 0 before #include of the VMA implementation and use another way.
-- You can
#define VMA_DYNAMIC_VULKAN_FUNCTIONS 1 and pass only pointers to vkGetInstanceProcAddr and vkGetDeviceProcAddr functions through VmaAllocatorCreateInfo::pVulkanFunctions. All the remaining Vulkan functions will be fetched automatically.
-- Finally, you can provide your own pointers to all Vulkan functions needed by VMA using structure member VmaAllocatorCreateInfo::pVulkanFunctions, if you fetched them in some custom way e.g. using some loader like Volk.
-
+
This library includes header <vulkan/vulkan.h>, which in turn includes <windows.h> on Windows. If you need some specific macros defined before including these headers (like WIN32_LEAN_AND_MEAN or WINVER for Windows, VK_USE_PLATFORM_WIN32_KHR for Vulkan), you must define them before every #include of this library.
+
- Note
- This library is written in C++, but has C-compatible interface. Thus you can include and use vk_mem_alloc.h in C or C++ code, but full implementation with
VMA_IMPLEMENTATION macro must be compiled as C++, NOT as C.
Initialization
At program startup:
@@ -96,29 +90,57 @@ Initialization
- Initialize Vulkan to have
VkPhysicalDevice, VkDevice and VkInstance object.
- Fill VmaAllocatorCreateInfo structure and create VmaAllocator object by calling vmaCreateAllocator().
-
-
-
-
allocatorInfo.
device = device;
-
+
Only members physicalDevice, device, instance are required. However, you should inform the library which Vulkan version do you use by setting VmaAllocatorCreateInfo::vulkanApiVersion and which extensions did you enable by setting VmaAllocatorCreateInfo::flags (like VMA_ALLOCATOR_CREATE_BUFFER_DEVICE_ADDRESS_BIT for VK_KHR_buffer_device_address). Otherwise, VMA would use only features of Vulkan 1.0 core with no extensions.
+
You may need to configure importing Vulkan functions. There are 3 ways to do this:
+
+- If you link with Vulkan static library (e.g. "vulkan-1.lib" on Windows):
+- You don't need to do anything.
+- VMA will use these, as macro
VMA_STATIC_VULKAN_FUNCTIONS is defined to 1 by default.
+
+
+- If you want VMA to fetch pointers to Vulkan functions dynamically using
vkGetInstanceProcAddr, vkGetDeviceProcAddr (this is the option presented in the example below):
+
+- If you fetch pointers to all Vulkan functions in a custom way, e.g. using some loader like Volk:
+- Define
VMA_STATIC_VULKAN_FUNCTIONS and VMA_DYNAMIC_VULKAN_FUNCTIONS to 0.
+- Pass these pointers via structure VmaVulkanFunctions.
+
+
+
+
+
+
+
+
+
+
+
allocatorCreateInfo.
device = device;
+
allocatorCreateInfo.
instance = instance;
+
-
+
VkResult vmaCreateAllocator(const VmaAllocatorCreateInfo *pCreateInfo, VmaAllocator *pAllocator)
Creates VmaAllocator object.
-
Description of a Allocator to be created.
Definition: vk_mem_alloc.h:942
-
VkPhysicalDevice physicalDevice
Vulkan physical device.
Definition: vk_mem_alloc.h:947
-
VkInstance instance
Handle to Vulkan instance object.
Definition: vk_mem_alloc.h:995
-
VkDevice device
Vulkan device.
Definition: vk_mem_alloc.h:950
-
uint32_t vulkanApiVersion
Optional. The highest version of Vulkan that the application is designed to use.
Definition: vk_mem_alloc.h:1004
+
Description of a Allocator to be created.
Definition: vk_mem_alloc.h:946
+
VkPhysicalDevice physicalDevice
Vulkan physical device.
Definition: vk_mem_alloc.h:951
+
const VmaVulkanFunctions * pVulkanFunctions
Pointers to Vulkan functions. Can be null.
Definition: vk_mem_alloc.h:994
+
VkInstance instance
Handle to Vulkan instance object.
Definition: vk_mem_alloc.h:999
+
VkDevice device
Vulkan device.
Definition: vk_mem_alloc.h:954
+
uint32_t vulkanApiVersion
Optional. The highest version of Vulkan that the application is designed to use.
Definition: vk_mem_alloc.h:1008
Represents main object of this library initialized.
-
Only members physicalDevice, device, instance are required. However, you should inform the library which Vulkan version do you use by setting VmaAllocatorCreateInfo::vulkanApiVersion and which extensions did you enable by setting VmaAllocatorCreateInfo::flags (like VMA_ALLOCATOR_CREATE_BUFFER_DEVICE_ADDRESS_BIT for VK_KHR_buffer_device_address). Otherwise, VMA would use only features of Vulkan 1.0 core with no extensions.
-
+Pointers to some Vulkan functions - a subset used by the library.
Definition: vk_mem_alloc.h:905
PFN_vkGetInstanceProcAddr vkGetInstanceProcAddr
Required when using VMA_DYNAMIC_VULKAN_FUNCTIONS.
Definition: vk_mem_alloc.h:907
PFN_vkGetDeviceProcAddr vkGetDeviceProcAddr
Required when using VMA_DYNAMIC_VULKAN_FUNCTIONS.
Definition: vk_mem_alloc.h:909
Resource allocation
When you want to create a buffer or image:
- Fill
VkBufferCreateInfo / VkImageCreateInfo structure.
- Fill VmaAllocationCreateInfo structure.
-- Call vmaCreateBuffer() / vmaCreateImage() to get
VkBuffer/VkImage with memory already allocated and bound to it.
+- Call vmaCreateBuffer() / vmaCreateImage() to get
VkBuffer/VkImage with memory already allocated and bound to it, plus VmaAllocation objects that represents its underlying memory.
VkBufferCreateInfo bufferInfo = { VK_STRUCTURE_TYPE_BUFFER_CREATE_INFO };
bufferInfo.size = 65536;
@@ -131,9 +153,9 @@ Resource allocation
vmaCreateBuffer(allocator, &bufferInfo, &allocInfo, &buffer, &allocation,
nullptr);
VkResult vmaCreateBuffer(VmaAllocator allocator, const VkBufferCreateInfo *pBufferCreateInfo, const VmaAllocationCreateInfo *pAllocationCreateInfo, VkBuffer *pBuffer, VmaAllocation *pAllocation, VmaAllocationInfo *pAllocationInfo)
-
@ VMA_MEMORY_USAGE_GPU_ONLY
Definition: vk_mem_alloc.h:466
-
Definition: vk_mem_alloc.h:1116
-
VmaMemoryUsage usage
Intended usage of memory.
Definition: vk_mem_alloc.h:1124
+
@ VMA_MEMORY_USAGE_GPU_ONLY
Definition: vk_mem_alloc.h:468
+
Definition: vk_mem_alloc.h:1120
+
VmaMemoryUsage usage
Intended usage of memory.
Definition: vk_mem_alloc.h:1128
Represents single memory allocation.
Don't forget to destroy your objects when no longer needed:
diff --git a/docs/html/resource_aliasing.html b/docs/html/resource_aliasing.html
index 93edd0f..477463f 100644
--- a/docs/html/resource_aliasing.html
+++ b/docs/html/resource_aliasing.html
@@ -140,9 +140,9 @@ $(function() {
VkResult vmaBindImageMemory(VmaAllocator allocator, VmaAllocation allocation, VkImage image)
Binds image to allocation.
void vmaFreeMemory(VmaAllocator allocator, const VmaAllocation allocation)
Frees memory previously allocated using vmaAllocateMemory(), vmaAllocateMemoryForBuffer(),...
VkResult vmaAllocateMemory(VmaAllocator allocator, const VkMemoryRequirements *pVkMemoryRequirements, const VmaAllocationCreateInfo *pCreateInfo, VmaAllocation *pAllocation, VmaAllocationInfo *pAllocationInfo)
General purpose memory allocation.
-
@ VMA_MEMORY_USAGE_GPU_ONLY
Definition: vk_mem_alloc.h:466
-
Definition: vk_mem_alloc.h:1116
-
VmaMemoryUsage usage
Intended usage of memory.
Definition: vk_mem_alloc.h:1124
+
@ VMA_MEMORY_USAGE_GPU_ONLY
Definition: vk_mem_alloc.h:468
+
Definition: vk_mem_alloc.h:1120
+
VmaMemoryUsage usage
Intended usage of memory.
Definition: vk_mem_alloc.h:1128
Represents single memory allocation.
Remember that using resources that alias in memory requires proper synchronization. You need to issue a memory barrier to make sure commands that use img1 and img2 don't overlap on GPU timeline. You also need to treat a resource after aliasing as uninitialized - containing garbage data. For example, if you use img1 and then want to use img2, you need to issue an image memory barrier for img2 with oldLayout = VK_IMAGE_LAYOUT_UNDEFINED.
Additional considerations:
diff --git a/docs/html/struct_vma_allocator_create_info.html b/docs/html/struct_vma_allocator_create_info.html
index 2f605e1..1716d68 100644
--- a/docs/html/struct_vma_allocator_create_info.html
+++ b/docs/html/struct_vma_allocator_create_info.html
@@ -303,7 +303,7 @@ Public Attributes
Optional. The highest version of Vulkan that the application is designed to use.
-
It must be a value in the format as created by macro VK_MAKE_VERSION or a constant like: VK_API_VERSION_1_1, VK_API_VERSION_1_0. The patch version number specified is ignored. Only the major and minor versions are considered. It must be less or equal (preferably equal) to value as passed to vkCreateInstance as VkApplicationInfo::apiVersion. Only versions 1.0, 1.1, 1.2 are supported by the current implementation. Leaving it initialized to zero is equivalent to VK_API_VERSION_1_0.
+
It must be a value in the format as created by macro VK_MAKE_VERSION or a constant like: VK_API_VERSION_1_1, VK_API_VERSION_1_0. The patch version number specified is ignored. Only the major and minor versions are considered. It must be less or equal (preferably equal) to value as passed to vkCreateInstance as VkApplicationInfo::apiVersion. Only versions 1.0, 1.1, 1.2, 1.3 are supported by the current implementation. Leaving it initialized to zero is equivalent to VK_API_VERSION_1_0.
diff --git a/docs/html/virtual_allocator.html b/docs/html/virtual_allocator.html
index dd757a9..243b747 100644
--- a/docs/html/virtual_allocator.html
+++ b/docs/html/virtual_allocator.html
@@ -84,8 +84,8 @@ Creating virtual block
VkResult vmaCreateVirtualBlock(const VmaVirtualBlockCreateInfo *pCreateInfo, VmaVirtualBlock *pVirtualBlock)
Creates new VmaVirtualBlock object.
Parameters of created VmaVirtualBlock object to be passed to vmaCreateVirtualBlock().
Definition: vk_mem_alloc.h:1441
VkDeviceSize size
Total size of the virtual block.
Definition: vk_mem_alloc.h:1447
Parameters of created VmaVirtualBlock object to be passed to vmaCreateVirtualBlock().
Definition: vk_mem_alloc.h:1445
VkDeviceSize size
Total size of the virtual block.
Definition: vk_mem_alloc.h:1451
Handle to a virtual block object that allows to use core allocation algorithm without allocating any ...
Making virtual allocations
@@ -111,8 +111,8 @@ Making virtual allocations
}
VkResult vmaVirtualAllocate(VmaVirtualBlock virtualBlock, const VmaVirtualAllocationCreateInfo *pCreateInfo, VmaVirtualAllocation *pAllocation, VkDeviceSize *pOffset)
Allocates new virtual allocation inside given VmaVirtualBlock.
Parameters of created virtual allocation to be passed to vmaVirtualAllocate().
Definition: vk_mem_alloc.h:1462
VkDeviceSize size
Size of the allocation.
Definition: vk_mem_alloc.h:1467
Parameters of created virtual allocation to be passed to vmaVirtualAllocate().
Definition: vk_mem_alloc.h:1466
VkDeviceSize size
Size of the allocation.
Definition: vk_mem_alloc.h:1471
Represents single memory allocation done inside VmaVirtualBlock.
Deallocation
@@ -140,8 +140,8 @@ Allocation parameters
void vmaGetVirtualAllocationInfo(VmaVirtualBlock virtualBlock, VmaVirtualAllocation allocation, VmaVirtualAllocationInfo *pVirtualAllocInfo)
Returns information about a specific virtual allocation within a virtual block, like its size and pUs...
Parameters of an existing virtual allocation, returned by vmaGetVirtualAllocationInfo().
Definition: vk_mem_alloc.h:1485
void * pUserData
Custom pointer associated with the allocation.
Definition: vk_mem_alloc.h:1500
Parameters of an existing virtual allocation, returned by vmaGetVirtualAllocationInfo().
Definition: vk_mem_alloc.h:1489
void * pUserData
Custom pointer associated with the allocation.
Definition: vk_mem_alloc.h:1504
Alignment and units
It feels natural to express sizes and offsets in bytes. If an offset of an allocation needs to be aligned to a multiply of some number (e.g. 4 bytes), you can fill optional member VmaVirtualAllocationCreateInfo::alignment to request it. Example:
@@ -151,7 +151,7 @@ Alignment and units
-VkDeviceSize alignment
Required alignment of the allocation. Optional.
Definition: vk_mem_alloc.h:1472
VkDeviceSize alignment
Required alignment of the allocation. Optional.
Definition: vk_mem_alloc.h:1476
Alignments of different allocations made from one block may vary. However, if all alignments and sizes are always multiply of some size e.g. 4 B or sizeof(MyDataStruct), you can express all sizes, alignments, and offsets in multiples of that size instead of individual bytes. It might be more convenient, but you need to make sure to use this new unit consistently in all the places:
- VmaVirtualBlockCreateInfo::size
@@ -166,9 +166,9 @@ Statistics
printf("My virtual block has %llu bytes used by %u virtual allocations\n",
void vmaCalculateVirtualBlockStats(VmaVirtualBlock virtualBlock, VmaStatInfo *pStatInfo)
Calculates and returns statistics about virtual allocations and memory usage in given VmaVirtualBlock...
Calculated statistics of memory usage in entire allocator.
Definition: vk_mem_alloc.h:1048
uint32_t allocationCount
Number of VmaAllocation allocation objects allocated.
Definition: vk_mem_alloc.h:1052
VkDeviceSize usedBytes
Total number of bytes occupied by all allocations.
Definition: vk_mem_alloc.h:1056
Calculated statistics of memory usage in entire allocator.
Definition: vk_mem_alloc.h:1052
uint32_t allocationCount
Number of VmaAllocation allocation objects allocated.
Definition: vk_mem_alloc.h:1056
VkDeviceSize usedBytes
Total number of bytes occupied by all allocations.
Definition: vk_mem_alloc.h:1060
You can also request a full list of allocations and free regions as a string in JSON format by calling vmaBuildVirtualBlockStatsString(). Returned string must be later freed using vmaFreeVirtualBlockStatsString(). The format of this string differs from the one returned by the main Vulkan allocator, but it is similar.
Additional considerations
diff --git a/docs/html/vk_khr_dedicated_allocation.html b/docs/html/vk_khr_dedicated_allocation.html
index 68fea64..7209015 100644
--- a/docs/html/vk_khr_dedicated_allocation.html
+++ b/docs/html/vk_khr_dedicated_allocation.html
@@ -82,7 +82,7 @@ $(function() {
VkResult vmaCreateAllocator(const VmaAllocatorCreateInfo *pCreateInfo, VmaAllocator *pAllocator)
Creates VmaAllocator object.
@ VMA_ALLOCATOR_CREATE_KHR_DEDICATED_ALLOCATION_BIT
Enables usage of VK_KHR_dedicated_allocation extension.
Definition: vk_mem_alloc.h:350
@ VMA_ALLOCATOR_CREATE_KHR_DEDICATED_ALLOCATION_BIT
Enables usage of VK_KHR_dedicated_allocation extension.
Definition: vk_mem_alloc.h:352
That is all. The extension will be automatically used whenever you create a buffer using vmaCreateBuffer() or image using vmaCreateImage().
When using the extension together with Vulkan Validation Layer, you will receive warnings like this:
vkBindBufferMemory(): Binding memory to buffer 0x33 but vkGetBufferMemoryRequirements() has not been called on that buffer.
It is OK, you should just ignore it. It happens because you use function vkGetBufferMemoryRequirements2KHR() instead of standard vkGetBufferMemoryRequirements(), while the validation layer seems to be unaware of it.
diff --git a/include/vk_mem_alloc.h b/include/vk_mem_alloc.h
index 6a0feb0..5351d37 100644
--- a/include/vk_mem_alloc.h
+++ b/include/vk_mem_alloc.h
@@ -17943,25 +17943,15 @@ To do it properly:
It may be a good idea to create dedicated CPP file just for this purpose.
-Note on language: This library is written in C++, but has C-compatible interface.
-Thus you can include and use vk_mem_alloc.h in C or C++ code, but full
-implementation with `VMA_IMPLEMENTATION` macro must be compiled as C++, NOT as C.
-
-Please note that this library includes header ``, which in turn
+This library includes header ``, which in turn
includes `` on Windows. If you need some specific macros defined
before including these headers (like `WIN32_LEAN_AND_MEAN` or
`WINVER` for Windows, `VK_USE_PLATFORM_WIN32_KHR` for Vulkan), you must define
them before every `#include` of this library.
-You may need to configure the way you import Vulkan functions.
-
-- By default, VMA assumes you you link statically with Vulkan API. If this is not the case,
- `#define VMA_STATIC_VULKAN_FUNCTIONS 0` before `#include` of the VMA implementation and use another way.
-- You can `#define VMA_DYNAMIC_VULKAN_FUNCTIONS 1` and pass only pointers to `vkGetInstanceProcAddr` and
- `vkGetDeviceProcAddr` functions through VmaAllocatorCreateInfo::pVulkanFunctions.
- All the remaining Vulkan functions will be fetched automatically.
-- Finally, you can provide your own pointers to all Vulkan functions needed by VMA using structure member
- VmaAllocatorCreateInfo::pVulkanFunctions, if you fetched them in some custom way e.g. using some loader like [Volk](https://github.com/zeux/volk).
+\note This library is written in C++, but has C-compatible interface.
+Thus you can include and use vk_mem_alloc.h in C or C++ code, but full
+implementation with `VMA_IMPLEMENTATION` macro must be compiled as C++, NOT as C.
\section quick_start_initialization Initialization
@@ -17972,23 +17962,44 @@ At program startup:
-# Fill VmaAllocatorCreateInfo structure and create #VmaAllocator object by
calling vmaCreateAllocator().
-\code
-VmaAllocatorCreateInfo allocatorInfo = {};
-allocatorInfo.vulkanApiVersion = VK_API_VERSION_1_2;
-allocatorInfo.physicalDevice = physicalDevice;
-allocatorInfo.device = device;
-allocatorInfo.instance = instance;
-
-VmaAllocator allocator;
-vmaCreateAllocator(&allocatorInfo, &allocator);
-\endcode
-
Only members `physicalDevice`, `device`, `instance` are required.
However, you should inform the library which Vulkan version do you use by setting
VmaAllocatorCreateInfo::vulkanApiVersion and which extensions did you enable
by setting VmaAllocatorCreateInfo::flags (like #VMA_ALLOCATOR_CREATE_BUFFER_DEVICE_ADDRESS_BIT for VK_KHR_buffer_device_address).
Otherwise, VMA would use only features of Vulkan 1.0 core with no extensions.
+You may need to configure importing Vulkan functions. There are 3 ways to do this:
+
+-# **If you link with Vulkan static library** (e.g. "vulkan-1.lib" on Windows):
+ - You don't need to do anything.
+ - VMA will use these, as macro `VMA_STATIC_VULKAN_FUNCTIONS` is defined to 1 by default.
+-# **If you want VMA to fetch pointers to Vulkan functions dynamically** using `vkGetInstanceProcAddr`,
+ `vkGetDeviceProcAddr` (this is the option presented in the example below):
+ - Define `VMA_STATIC_VULKAN_FUNCTIONS` to 0, `VMA_DYNAMIC_VULKAN_FUNCTIONS` to 1.
+ - Provide pointers to these two functions via VmaVulkanFunctions::vkGetInstanceProcAddr,
+ VmaVulkanFunctions::vkGetDeviceProcAddr.
+ - The library will fetch pointers to all other functions it needs internally.
+-# **If you fetch pointers to all Vulkan functions in a custom way**, e.g. using some loader like
+ [Volk](https://github.com/zeux/volk):
+ - Define `VMA_STATIC_VULKAN_FUNCTIONS` and `VMA_DYNAMIC_VULKAN_FUNCTIONS` to 0.
+ - Pass these pointers via structure #VmaVulkanFunctions.
+
+\code
+VmaVulkanFunctions vulkanFunctions = {};
+vulkanFunctions.vkGetInstanceProcAddr = &vkGetInstanceProcAddr;
+vulkanFunctions.vkGetDeviceProcAddr = &vkGetDeviceProcAddr;
+
+VmaAllocatorCreateInfo allocatorCreateInfo = {};
+allocatorCreateInfo.vulkanApiVersion = VK_API_VERSION_1_2;
+allocatorCreateInfo.physicalDevice = physicalDevice;
+allocatorCreateInfo.device = device;
+allocatorCreateInfo.instance = instance;
+allocatorCreateInfo.pVulkanFunctions = &vulkanFunctions;
+
+VmaAllocator allocator;
+vmaCreateAllocator(&allocatorCreateInfo, &allocator);
+\endcode
+
\section quick_start_resource_allocation Resource allocation
@@ -17997,7 +18008,7 @@ When you want to create a buffer or image:
-# Fill `VkBufferCreateInfo` / `VkImageCreateInfo` structure.
-# Fill VmaAllocationCreateInfo structure.
-# Call vmaCreateBuffer() / vmaCreateImage() to get `VkBuffer`/`VkImage` with memory
- already allocated and bound to it.
+ already allocated and bound to it, plus #VmaAllocation objects that represents its underlying memory.
\code
VkBufferCreateInfo bufferInfo = { VK_STRUCTURE_TYPE_BUFFER_CREATE_INFO };