diff --git a/docs/gfx/Buddy_allocator.png b/docs/gfx/Buddy_allocator.png deleted file mode 100644 index 507314d..0000000 Binary files a/docs/gfx/Buddy_allocator.png and /dev/null differ diff --git a/docs/html/allocation_annotation.html b/docs/html/allocation_annotation.html index 3681cca..9af143b 100644 --- a/docs/html/allocation_annotation.html +++ b/docs/html/allocation_annotation.html @@ -84,18 +84,18 @@ Allocation user data
VmaAllocation allocation;
vmaCreateBuffer(allocator, &bufCreateInfo, &allocCreateInfo, &buffer, &allocation, nullptr);
vmaCreateBuffer
VkResult vmaCreateBuffer(VmaAllocator allocator, const VkBufferCreateInfo *pBufferCreateInfo, const VmaAllocationCreateInfo *pAllocationCreateInfo, VkBuffer *pBuffer, VmaAllocation *pAllocation, VmaAllocationInfo *pAllocationInfo)
-
VMA_MEMORY_USAGE_AUTO
@ VMA_MEMORY_USAGE_AUTO
Definition: vk_mem_alloc.h:493
-
VmaAllocationCreateInfo
Definition: vk_mem_alloc.h:1218
-
VmaAllocationCreateInfo::pUserData
void * pUserData
Custom general-purpose pointer that will be stored in VmaAllocation, can be read as VmaAllocationInfo...
Definition: vk_mem_alloc.h:1257
-
VmaAllocationCreateInfo::usage
VmaMemoryUsage usage
Intended usage of memory.
Definition: vk_mem_alloc.h:1226
+
VMA_MEMORY_USAGE_AUTO
@ VMA_MEMORY_USAGE_AUTO
Definition: vk_mem_alloc.h:488
+
VmaAllocationCreateInfo
Definition: vk_mem_alloc.h:1211
+
VmaAllocationCreateInfo::pUserData
void * pUserData
Custom general-purpose pointer that will be stored in VmaAllocation, can be read as VmaAllocationInfo...
Definition: vk_mem_alloc.h:1250
+
VmaAllocationCreateInfo::usage
VmaMemoryUsage usage
Intended usage of memory.
Definition: vk_mem_alloc.h:1219
VmaAllocation
Represents single memory allocation.

The pointer may be later retrieved as VmaAllocationInfo::pUserData:

VmaAllocationInfo allocInfo;
vmaGetAllocationInfo(allocator, allocation, &allocInfo);
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:1333
-
void * pUserData
Custom general-purpose pointer that was passed as VmaAllocationCreateInfo::pUserData or set using vma...
Definition: vk_mem_alloc.h:1380
+
Parameters of VmaAllocation objects, that can be retrieved using function vmaGetAllocationInfo().
Definition: vk_mem_alloc.h:1326
+
void * pUserData
Custom general-purpose pointer that was passed as VmaAllocationCreateInfo::pUserData or set using vma...
Definition: vk_mem_alloc.h:1373

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.

@@ -115,8 +115,8 @@ Allocation names

VmaAllocation allocation;
vmaCreateImage(allocator, &imageInfo, &allocCreateInfo, &image, &allocation, nullptr);
vmaCreateImage
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
@ VMA_ALLOCATION_CREATE_USER_DATA_COPY_STRING_BIT
Definition: vk_mem_alloc.h:561
-
VmaAllocationCreateInfo::flags
VmaAllocationCreateFlags flags
Use VmaAllocationCreateFlagBits enum.
Definition: vk_mem_alloc.h:1220
+
VMA_ALLOCATION_CREATE_USER_DATA_COPY_STRING_BIT
@ VMA_ALLOCATION_CREATE_USER_DATA_COPY_STRING_BIT
Definition: vk_mem_alloc.h:556
+
VmaAllocationCreateInfo::flags
VmaAllocationCreateFlags flags
Use VmaAllocationCreateFlagBits enum.
Definition: vk_mem_alloc.h:1213

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.

VmaAllocationInfo allocInfo;
vmaGetAllocationInfo(allocator, allocation, &allocInfo);
diff --git a/docs/html/annotated.html b/docs/html/annotated.html index 02b4f0a..138b744 100644 --- a/docs/html/annotated.html +++ b/docs/html/annotated.html @@ -74,24 +74,23 @@ $(function() {  CVmaAllocatorCreateInfoDescription of a Allocator to be created  CVmaAllocatorInfoInformation about existing VmaAllocator object  CVmaBudgetStatistics of current memory usage and available budget for a specific memory heap - CVmaDefragmentationContextRepresents Opaque object that represents started defragmentation process - CVmaDefragmentationInfoDeprecated. Optional configuration parameters to be passed to function vmaDefragment() - CVmaDefragmentationInfo2Parameters for defragmentation - CVmaDefragmentationPassInfoParameters for incremental defragmentation steps - CVmaDefragmentationPassMoveInfo - CVmaDefragmentationStatsStatistics returned by function vmaDefragment() - CVmaDetailedStatisticsMore detailed statistics than VmaStatistics - CVmaDeviceMemoryCallbacksSet of callbacks that the library will call for vkAllocateMemory and vkFreeMemory - CVmaPoolRepresents custom memory pool - CVmaPoolCreateInfoDescribes parameter of created VmaPool - CVmaStatisticsCalculated statistics of memory usage e.g. in a specific memory type, heap, custom pool, or total - CVmaTotalStatisticsGeneral statistics from current state of the Allocator - total memory usage across all memory heaps and types - CVmaVirtualAllocationRepresents single memory allocation done inside VmaVirtualBlock - CVmaVirtualAllocationCreateInfoParameters of created virtual allocation to be passed to vmaVirtualAllocate() - CVmaVirtualAllocationInfoParameters of an existing virtual allocation, returned by vmaGetVirtualAllocationInfo() - CVmaVirtualBlockHandle to a virtual block object that allows to use core allocation algorithm without allocating any real GPU memory - CVmaVirtualBlockCreateInfoParameters of created VmaVirtualBlock object to be passed to vmaCreateVirtualBlock() - CVmaVulkanFunctionsPointers to some Vulkan functions - a subset used by the library + CVmaDefragmentationContextAn opaque object that represents started defragmentation process + CVmaDefragmentationInfoParameters for defragmentation + CVmaDefragmentationMoveSingle move of an allocation to be done for defragmentation + CVmaDefragmentationPassMoveInfoParameters for incremental defragmentation steps + CVmaDefragmentationStatsStatistics returned for defragmentation process in function vmaEndDefragmentation() + CVmaDetailedStatisticsMore detailed statistics than VmaStatistics + CVmaDeviceMemoryCallbacksSet of callbacks that the library will call for vkAllocateMemory and vkFreeMemory + CVmaPoolRepresents custom memory pool + CVmaPoolCreateInfoDescribes parameter of created VmaPool + CVmaStatisticsCalculated statistics of memory usage e.g. in a specific memory type, heap, custom pool, or total + CVmaTotalStatisticsGeneral statistics from current state of the Allocator - total memory usage across all memory heaps and types + CVmaVirtualAllocationRepresents single memory allocation done inside VmaVirtualBlock + CVmaVirtualAllocationCreateInfoParameters of created virtual allocation to be passed to vmaVirtualAllocate() + CVmaVirtualAllocationInfoParameters of an existing virtual allocation, returned by vmaGetVirtualAllocationInfo() + CVmaVirtualBlockHandle to a virtual block object that allows to use core allocation algorithm without allocating any real GPU memory + CVmaVirtualBlockCreateInfoParameters of created VmaVirtualBlock object to be passed to vmaCreateVirtualBlock() + CVmaVulkanFunctionsPointers to some Vulkan functions - a subset used by the library
diff --git a/docs/html/choosing_memory_type.html b/docs/html/choosing_memory_type.html index 71fae5d..bf51bf1 100644 --- a/docs/html/choosing_memory_type.html +++ b/docs/html/choosing_memory_type.html @@ -94,9 +94,9 @@ Usage
VmaAllocation allocation;
vmaCreateBuffer(allocator, &bufferInfo, &allocInfo, &buffer, &allocation, nullptr);
vmaCreateBuffer
VkResult vmaCreateBuffer(VmaAllocator allocator, const VkBufferCreateInfo *pBufferCreateInfo, const VmaAllocationCreateInfo *pAllocationCreateInfo, VkBuffer *pBuffer, VmaAllocation *pAllocation, VmaAllocationInfo *pAllocationInfo)
-
VMA_MEMORY_USAGE_AUTO
@ VMA_MEMORY_USAGE_AUTO
Definition: vk_mem_alloc.h:493
-
VmaAllocationCreateInfo
Definition: vk_mem_alloc.h:1218
-
VmaAllocationCreateInfo::usage
VmaMemoryUsage usage
Intended usage of memory.
Definition: vk_mem_alloc.h:1226
+
VMA_MEMORY_USAGE_AUTO
@ VMA_MEMORY_USAGE_AUTO
Definition: vk_mem_alloc.h:488
+
VmaAllocationCreateInfo
Definition: vk_mem_alloc.h:1211
+
VmaAllocationCreateInfo::usage
VmaMemoryUsage usage
Intended usage of memory.
Definition: vk_mem_alloc.h:1219
VmaAllocation
Represents single memory allocation.

If you have a preference for putting the resource in GPU (device) memory or CPU (host) memory on systems with discrete graphics card that have the memories separate, you can use VMA_MEMORY_USAGE_AUTO_PREFER_DEVICE or VMA_MEMORY_USAGE_AUTO_PREFER_HOST.

When using VMA_MEMORY_USAGE_AUTO* while you want to map the allocated memory, you also need to specify one of the host access flags: VMA_ALLOCATION_CREATE_HOST_ACCESS_SEQUENTIAL_WRITE_BIT or VMA_ALLOCATION_CREATE_HOST_ACCESS_RANDOM_BIT. This will help the library decide about preferred memory type to ensure it has VK_MEMORY_PROPERTY_HOST_VISIBLE_BIT so you can map it.

@@ -112,8 +112,8 @@ Usage
VkBuffer stagingBuffer;
VmaAllocation stagingAllocation;
vmaCreateBuffer(allocator, &stagingBufferInfo, &stagingAllocInfo, &stagingBuffer, &stagingAllocation, nullptr);
-
VMA_ALLOCATION_CREATE_HOST_ACCESS_SEQUENTIAL_WRITE_BIT
@ VMA_ALLOCATION_CREATE_HOST_ACCESS_SEQUENTIAL_WRITE_BIT
Definition: vk_mem_alloc.h:598
-
VmaAllocationCreateInfo::flags
VmaAllocationCreateFlags flags
Use VmaAllocationCreateFlagBits enum.
Definition: vk_mem_alloc.h:1220
+
VMA_ALLOCATION_CREATE_HOST_ACCESS_SEQUENTIAL_WRITE_BIT
@ VMA_ALLOCATION_CREATE_HOST_ACCESS_SEQUENTIAL_WRITE_BIT
Definition: vk_mem_alloc.h:593
+
VmaAllocationCreateInfo::flags
VmaAllocationCreateFlags flags
Use VmaAllocationCreateFlagBits enum.
Definition: vk_mem_alloc.h:1213

For more examples of creating different kinds of resources, see chapter Recommended usage patterns.

Usage values VMA_MEMORY_USAGE_AUTO* are legal to use only when the library knows about the resource being created by having VkBufferCreateInfo / VkImageCreateInfo passed, so they work with functions like: vmaCreateBuffer(), vmaCreateImage(), vmaFindMemoryTypeIndexForBufferInfo() etc. If you allocate raw memory using function vmaAllocateMemory(), you have to use other means of selecting memory type, as decribed below.

Note
Old usage values (VMA_MEMORY_USAGE_GPU_ONLY, VMA_MEMORY_USAGE_CPU_ONLY, VMA_MEMORY_USAGE_CPU_TO_GPU, VMA_MEMORY_USAGE_GPU_TO_CPU, VMA_MEMORY_USAGE_CPU_COPY) are still available and work same way as in previous versions of the library for backward compatibility, but they are not recommended.
@@ -128,10 +128,10 @@ Required and preferred flags
VkBuffer buffer;
VmaAllocation allocation;
vmaCreateBuffer(allocator, &bufferInfo, &allocInfo, &buffer, &allocation, nullptr);
-
VMA_ALLOCATION_CREATE_MAPPED_BIT
@ 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:551
-
VMA_ALLOCATION_CREATE_HOST_ACCESS_RANDOM_BIT
@ VMA_ALLOCATION_CREATE_HOST_ACCESS_RANDOM_BIT
Definition: vk_mem_alloc.h:610
-
VmaAllocationCreateInfo::preferredFlags
VkMemoryPropertyFlags preferredFlags
Flags that preferably should be set in a memory type chosen for an allocation.
Definition: vk_mem_alloc.h:1236
-
VmaAllocationCreateInfo::requiredFlags
VkMemoryPropertyFlags requiredFlags
Flags that must be set in a Memory Type chosen for an allocation.
Definition: vk_mem_alloc.h:1231
+
VMA_ALLOCATION_CREATE_MAPPED_BIT
@ 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:546
+
VMA_ALLOCATION_CREATE_HOST_ACCESS_RANDOM_BIT
@ VMA_ALLOCATION_CREATE_HOST_ACCESS_RANDOM_BIT
Definition: vk_mem_alloc.h:605
+
VmaAllocationCreateInfo::preferredFlags
VkMemoryPropertyFlags preferredFlags
Flags that preferably should be set in a memory type chosen for an allocation.
Definition: vk_mem_alloc.h:1229
+
VmaAllocationCreateInfo::requiredFlags
VkMemoryPropertyFlags requiredFlags
Flags that must be set in a Memory Type chosen for an allocation.
Definition: vk_mem_alloc.h:1224

A memory type is chosen that has all the required flags and as many preferred flags set as possible.

Value passed in VmaAllocationCreateInfo::usage is internally converted to a set of required and preferred flags, plus some extra "magic" (heuristics).

@@ -146,7 +146,7 @@ Explicit memory types

VkBuffer buffer;
VmaAllocation allocation;
vmaCreateBuffer(allocator, &bufferInfo, &allocInfo, &buffer, &allocation, nullptr);
-
VmaAllocationCreateInfo::memoryTypeBits
uint32_t memoryTypeBits
Bitmask containing one bit set for every memory type acceptable for this allocation.
Definition: vk_mem_alloc.h:1244
+
VmaAllocationCreateInfo::memoryTypeBits
uint32_t memoryTypeBits
Bitmask containing one bit set for every memory type acceptable for this allocation.
Definition: vk_mem_alloc.h:1237

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/classes.html b/docs/html/classes.html index b0a5180..1193dba 100644 --- a/docs/html/classes.html +++ b/docs/html/classes.html @@ -69,7 +69,7 @@ $(function() {
V
-
VmaAllocation
VmaAllocationCreateInfo
VmaAllocationInfo
VmaAllocator
VmaAllocatorCreateInfo
VmaAllocatorInfo
VmaBudget
VmaDefragmentationContext
VmaDefragmentationInfo
VmaDefragmentationInfo2
VmaDefragmentationPassInfo
VmaDefragmentationPassMoveInfo
VmaDefragmentationStats
VmaDetailedStatistics
VmaDeviceMemoryCallbacks
VmaPool
VmaPoolCreateInfo
VmaStatistics
VmaTotalStatistics
VmaVirtualAllocation
VmaVirtualAllocationCreateInfo
VmaVirtualAllocationInfo
VmaVirtualBlock
VmaVirtualBlockCreateInfo
VmaVulkanFunctions
+
VmaAllocation
VmaAllocationCreateInfo
VmaAllocationInfo
VmaAllocator
VmaAllocatorCreateInfo
VmaAllocatorInfo
VmaBudget
VmaDefragmentationContext
VmaDefragmentationInfo
VmaDefragmentationMove
VmaDefragmentationPassMoveInfo
VmaDefragmentationStats
VmaDetailedStatistics
VmaDeviceMemoryCallbacks
VmaPool
VmaPoolCreateInfo
VmaStatistics
VmaTotalStatistics
VmaVirtualAllocation
VmaVirtualAllocationCreateInfo
VmaVirtualAllocationInfo
VmaVirtualBlock
VmaVirtualBlockCreateInfo
VmaVulkanFunctions
diff --git a/docs/html/custom_memory_pools.html b/docs/html/custom_memory_pools.html index dd6d371..5a7f550 100644 --- a/docs/html/custom_memory_pools.html +++ b/docs/html/custom_memory_pools.html @@ -109,13 +109,13 @@ $(function() {
vmaCreateBuffer(allocator, &bufCreateInfo, &allocCreateInfo, &buf, &alloc, &allocInfo);
vmaCreatePool
VkResult vmaCreatePool(VmaAllocator allocator, const VmaPoolCreateInfo *pCreateInfo, VmaPool *pPool)
Allocates Vulkan device memory and creates VmaPool object.
vmaCreateBuffer
VkResult vmaCreateBuffer(VmaAllocator allocator, const VkBufferCreateInfo *pBufferCreateInfo, const VmaAllocationCreateInfo *pAllocationCreateInfo, VkBuffer *pBuffer, VmaAllocation *pAllocation, VmaAllocationInfo *pAllocationInfo)
-
VmaAllocationCreateInfo
Definition: vk_mem_alloc.h:1218
-
VmaAllocationCreateInfo::pool
VmaPool pool
Pool that this allocation should be created in.
Definition: vk_mem_alloc.h:1250
+
VmaAllocationCreateInfo
Definition: vk_mem_alloc.h:1211
+
VmaAllocationCreateInfo::pool
VmaPool pool
Pool that this allocation should be created in.
Definition: vk_mem_alloc.h:1243
VmaAllocation
Represents single memory allocation.
-
VmaAllocationInfo
Parameters of VmaAllocation objects, that can be retrieved using function vmaGetAllocationInfo().
Definition: vk_mem_alloc.h:1333
-
VmaPoolCreateInfo
Describes parameter of created VmaPool.
Definition: vk_mem_alloc.h:1269
-
VmaPoolCreateInfo::memoryTypeIndex
uint32_t memoryTypeIndex
Vulkan memory type index to allocate this pool from.
Definition: vk_mem_alloc.h:1272
-
VmaPoolCreateInfo::maxBlockCount
size_t maxBlockCount
Maximum number of blocks that can be allocated in this pool. Optional.
Definition: vk_mem_alloc.h:1298
+
VmaAllocationInfo
Parameters of VmaAllocation objects, that can be retrieved using function vmaGetAllocationInfo().
Definition: vk_mem_alloc.h:1326
+
VmaPoolCreateInfo
Describes parameter of created VmaPool.
Definition: vk_mem_alloc.h:1262
+
VmaPoolCreateInfo::memoryTypeIndex
uint32_t memoryTypeIndex
Vulkan memory type index to allocate this pool from.
Definition: vk_mem_alloc.h:1265
+
VmaPoolCreateInfo::maxBlockCount
size_t maxBlockCount
Maximum number of blocks that can be allocated in this pool. Optional.
Definition: vk_mem_alloc.h:1291
VmaPool
Represents custom memory pool.

You have to free all allocations made from this pool before destroying it.

vmaDestroyBuffer(allocator, buf, alloc);
@@ -141,8 +141,8 @@ Choosing memory type index
poolCreateInfo.memoryTypeIndex = memTypeIndex;
// ...
VkResult vmaFindMemoryTypeIndexForBufferInfo(VmaAllocator allocator, const VkBufferCreateInfo *pBufferCreateInfo, const VmaAllocationCreateInfo *pAllocationCreateInfo, uint32_t *pMemoryTypeIndex)
Helps to find memoryTypeIndex, given VkBufferCreateInfo and VmaAllocationCreateInfo.
-
@ VMA_MEMORY_USAGE_AUTO
Definition: vk_mem_alloc.h:493
-
VmaMemoryUsage usage
Intended usage of memory.
Definition: vk_mem_alloc.h:1226
+
@ VMA_MEMORY_USAGE_AUTO
Definition: vk_mem_alloc.h:488
+
VmaMemoryUsage usage
Intended usage of memory.
Definition: vk_mem_alloc.h:1219

When creating buffers/images allocated in that pool, provide following parameters: