diff --git a/docs/html/allocation_annotation.html b/docs/html/allocation_annotation.html index 8605640..26909d3 100644 --- a/docs/html/allocation_annotation.html +++ b/docs/html/allocation_annotation.html @@ -93,18 +93,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)
Creates a new VkBuffer, allocates and binds memory for it.
-
VMA_MEMORY_USAGE_AUTO
@ VMA_MEMORY_USAGE_AUTO
Definition vk_mem_alloc.h:510
-
VmaAllocationCreateInfo
Parameters of new VmaAllocation.
Definition vk_mem_alloc.h:1245
-
VmaAllocationCreateInfo::pUserData
void * pUserData
Custom general-purpose pointer that will be stored in VmaAllocation, can be read as VmaAllocationInfo...
Definition vk_mem_alloc.h:1284
-
VmaAllocationCreateInfo::usage
VmaMemoryUsage usage
Intended usage of memory.
Definition vk_mem_alloc.h:1253
+
VMA_MEMORY_USAGE_AUTO
@ VMA_MEMORY_USAGE_AUTO
Definition vk_mem_alloc.h:511
+
VmaAllocationCreateInfo
Parameters of new VmaAllocation.
Definition vk_mem_alloc.h:1246
+
VmaAllocationCreateInfo::pUserData
void * pUserData
Custom general-purpose pointer that will be stored in VmaAllocation, can be read as VmaAllocationInfo...
Definition vk_mem_alloc.h:1285
+
VmaAllocationCreateInfo::usage
VmaMemoryUsage usage
Intended usage of memory.
Definition vk_mem_alloc.h:1254
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;
vmaGetAllocationInfo
void vmaGetAllocationInfo(VmaAllocator allocator, VmaAllocation allocation, VmaAllocationInfo *pAllocationInfo)
Returns current information about specified allocation.
-
VmaAllocationInfo
Definition vk_mem_alloc.h:1364
-
VmaAllocationInfo::pUserData
void * pUserData
Custom general-purpose pointer that was passed as VmaAllocationCreateInfo::pUserData or set using vma...
Definition vk_mem_alloc.h:1411
+
VmaAllocationInfo
Definition vk_mem_alloc.h:1365
+
VmaAllocationInfo::pUserData
void * pUserData
Custom general-purpose pointer that was passed as VmaAllocationCreateInfo::pUserData or set using vma...
Definition vk_mem_alloc.h:1412

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.

diff --git a/docs/html/choosing_memory_type.html b/docs/html/choosing_memory_type.html index 9784a9c..073bcab 100644 --- a/docs/html/choosing_memory_type.html +++ b/docs/html/choosing_memory_type.html @@ -103,9 +103,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)
Creates a new VkBuffer, allocates and binds memory for it.
-
VMA_MEMORY_USAGE_AUTO
@ VMA_MEMORY_USAGE_AUTO
Definition vk_mem_alloc.h:510
-
VmaAllocationCreateInfo
Parameters of new VmaAllocation.
Definition vk_mem_alloc.h:1245
-
VmaAllocationCreateInfo::usage
VmaMemoryUsage usage
Intended usage of memory.
Definition vk_mem_alloc.h:1253
+
VMA_MEMORY_USAGE_AUTO
@ VMA_MEMORY_USAGE_AUTO
Definition vk_mem_alloc.h:511
+
VmaAllocationCreateInfo
Parameters of new VmaAllocation.
Definition vk_mem_alloc.h:1246
+
VmaAllocationCreateInfo::usage
VmaMemoryUsage usage
Intended usage of memory.
Definition vk_mem_alloc.h:1254
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.

@@ -121,8 +121,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:619
-
VmaAllocationCreateInfo::flags
VmaAllocationCreateFlags flags
Use VmaAllocationCreateFlagBits enum.
Definition vk_mem_alloc.h:1247
+
VMA_ALLOCATION_CREATE_HOST_ACCESS_SEQUENTIAL_WRITE_BIT
@ VMA_ALLOCATION_CREATE_HOST_ACCESS_SEQUENTIAL_WRITE_BIT
Definition vk_mem_alloc.h:620
+
VmaAllocationCreateInfo::flags
VmaAllocationCreateFlags flags
Use VmaAllocationCreateFlagBits enum.
Definition vk_mem_alloc.h:1248

For more examples of creating different kinds of resources, see chapter Recommended usage patterns. See also: Memory mapping.

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 described 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 deprecated.
@@ -137,10 +137,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:570
-
VMA_ALLOCATION_CREATE_HOST_ACCESS_RANDOM_BIT
@ VMA_ALLOCATION_CREATE_HOST_ACCESS_RANDOM_BIT
Definition vk_mem_alloc.h:631
-
VmaAllocationCreateInfo::preferredFlags
VkMemoryPropertyFlags preferredFlags
Flags that preferably should be set in a memory type chosen for an allocation.
Definition vk_mem_alloc.h:1263
-
VmaAllocationCreateInfo::requiredFlags
VkMemoryPropertyFlags requiredFlags
Flags that must be set in a Memory Type chosen for an allocation.
Definition vk_mem_alloc.h:1258
+
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:571
+
VMA_ALLOCATION_CREATE_HOST_ACCESS_RANDOM_BIT
@ VMA_ALLOCATION_CREATE_HOST_ACCESS_RANDOM_BIT
Definition vk_mem_alloc.h:632
+
VmaAllocationCreateInfo::preferredFlags
VkMemoryPropertyFlags preferredFlags
Flags that preferably should be set in a memory type chosen for an allocation.
Definition vk_mem_alloc.h:1264
+
VmaAllocationCreateInfo::requiredFlags
VkMemoryPropertyFlags requiredFlags
Flags that must be set in a Memory Type chosen for an allocation.
Definition vk_mem_alloc.h:1259

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).

@@ -155,7 +155,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:1271
+
VmaAllocationCreateInfo::memoryTypeBits
uint32_t memoryTypeBits
Bitmask containing one bit set for every memory type acceptable for this allocation.
Definition vk_mem_alloc.h:1272

You can also use this parameter to exclude some memory types. If you inspect memory heaps and types available on the current physical device and you determine that for some reason you don't want to use a specific memory type for the allocation, you can enable automatic memory type selection but exclude certain memory type or types by setting all bits of memoryTypeBits to 1 except the ones you choose.

// ...
uint32_t excludedMemoryTypeIndex = 2;
diff --git a/docs/html/custom_memory_pools.html b/docs/html/custom_memory_pools.html index cad9d57..98e4b0a 100644 --- a/docs/html/custom_memory_pools.html +++ b/docs/html/custom_memory_pools.html @@ -133,15 +133,15 @@ $(function() {
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)
Creates a new VkBuffer, allocates and binds memory for it.
vmaFindMemoryTypeIndexForBufferInfo
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
@ VMA_MEMORY_USAGE_AUTO
Definition vk_mem_alloc.h:510
-
VmaAllocationCreateInfo
Parameters of new VmaAllocation.
Definition vk_mem_alloc.h:1245
-
VmaAllocationCreateInfo::pool
VmaPool pool
Pool that this allocation should be created in.
Definition vk_mem_alloc.h:1277
-
VmaAllocationCreateInfo::usage
VmaMemoryUsage usage
Intended usage of memory.
Definition vk_mem_alloc.h:1253
+
VMA_MEMORY_USAGE_AUTO
@ VMA_MEMORY_USAGE_AUTO
Definition vk_mem_alloc.h:511
+
VmaAllocationCreateInfo
Parameters of new VmaAllocation.
Definition vk_mem_alloc.h:1246
+
VmaAllocationCreateInfo::pool
VmaPool pool
Pool that this allocation should be created in.
Definition vk_mem_alloc.h:1278
+
VmaAllocationCreateInfo::usage
VmaMemoryUsage usage
Intended usage of memory.
Definition vk_mem_alloc.h:1254
VmaAllocation
Represents single memory allocation.
-
VmaPoolCreateInfo
Describes parameter of created VmaPool.
Definition vk_mem_alloc.h:1296
-
VmaPoolCreateInfo::memoryTypeIndex
uint32_t memoryTypeIndex
Vulkan memory type index to allocate this pool from.
Definition vk_mem_alloc.h:1299
-
VmaPoolCreateInfo::blockSize
VkDeviceSize blockSize
Size of a single VkDeviceMemory block to be allocated as part of this pool, in bytes....
Definition vk_mem_alloc.h:1312
-
VmaPoolCreateInfo::maxBlockCount
size_t maxBlockCount
Maximum number of blocks that can be allocated in this pool. Optional.
Definition vk_mem_alloc.h:1325
+
VmaPoolCreateInfo
Describes parameter of created VmaPool.
Definition vk_mem_alloc.h:1297
+
VmaPoolCreateInfo::memoryTypeIndex
uint32_t memoryTypeIndex
Vulkan memory type index to allocate this pool from.
Definition vk_mem_alloc.h:1300
+
VmaPoolCreateInfo::blockSize
VkDeviceSize blockSize
Size of a single VkDeviceMemory block to be allocated as part of this pool, in bytes....
Definition vk_mem_alloc.h:1313
+
VmaPoolCreateInfo::maxBlockCount
size_t maxBlockCount
Maximum number of blocks that can be allocated in this pool. Optional.
Definition vk_mem_alloc.h:1326
VmaPool
Represents custom memory pool.

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

vmaDestroyBuffer(allocator, buf, alloc);
diff --git a/docs/html/debugging_memory_usage.html b/docs/html/debugging_memory_usage.html index 788fcff..1dadcff 100644 --- a/docs/html/debugging_memory_usage.html +++ b/docs/html/debugging_memory_usage.html @@ -111,7 +111,11 @@ Corruption detection

When this feature is enabled, number of bytes specified as VMA_DEBUG_MARGIN (it must be multiply of 4) after every allocation is filled with a magic number. This idea is also know as "canary". Memory is automatically mapped and unmapped if necessary.

This number is validated automatically when the allocation is destroyed. If it is not equal to the expected value, VMA_ASSERT() is executed. It clearly means that either CPU or GPU overwritten the memory outside of boundaries of the allocation, which indicates a serious bug.

You can also explicitly request checking margins of all allocations in all memory blocks that belong to specified memory types by using function vmaCheckCorruption(), or in memory blocks that belong to specified custom pool, by using function vmaCheckPoolCorruption().

-

Margin validation (corruption detection) works only for memory types that are HOST_VISIBLE and HOST_COHERENT.

+

Margin validation (corruption detection) works only for memory types that are HOST_VISIBLE and HOST_COHERENT.

+

+Leak detection features

+

At allocation and allocator destruction time VMA checks for unfreed and unmapped blocks using VMA_ASSERT_LEAK(). This macro defaults to an assertion, triggering a typically fatal error in Debug builds, and doing nothing in Release builds. You can provide your own definition of VMA_ASSERT_LEAK() to change this behavior.

+

At memory block destruction time VMA lists out all unfreed allocations using the VMA_LEAK_LOG_FORMAT() macro, which defaults to VMA_DEBUG_LOG_FORMAT, which in turn defaults to a no-op. If you're having trouble with leaks - for example, the aforementioned assertion triggers, but you don't quite know why -, overriding this macro to print out the the leaking blocks, combined with assigning individual names to allocations using vmaSetAllocationName(), can greatly aid in fixing them.

diff --git a/docs/html/defragmentation.html b/docs/html/defragmentation.html index 784f407..35b8025 100644 --- a/docs/html/defragmentation.html +++ b/docs/html/defragmentation.html @@ -143,18 +143,18 @@ $(function() {
vmaBeginDefragmentationPass
VkResult vmaBeginDefragmentationPass(VmaAllocator allocator, VmaDefragmentationContext context, VmaDefragmentationPassMoveInfo *pPassInfo)
Starts single defragmentation pass.
vmaBeginDefragmentation
VkResult vmaBeginDefragmentation(VmaAllocator allocator, const VmaDefragmentationInfo *pInfo, VmaDefragmentationContext *pContext)
Begins defragmentation process.
vmaEndDefragmentationPass
VkResult vmaEndDefragmentationPass(VmaAllocator allocator, VmaDefragmentationContext context, VmaDefragmentationPassMoveInfo *pPassInfo)
Ends single defragmentation pass.
-
VMA_DEFRAGMENTATION_FLAG_ALGORITHM_FAST_BIT
@ VMA_DEFRAGMENTATION_FLAG_ALGORITHM_FAST_BIT
Definition vk_mem_alloc.h:727
-
VmaAllocationInfo
Definition vk_mem_alloc.h:1364
-
VmaAllocationInfo::pUserData
void * pUserData
Custom general-purpose pointer that was passed as VmaAllocationCreateInfo::pUserData or set using vma...
Definition vk_mem_alloc.h:1411
+
VMA_DEFRAGMENTATION_FLAG_ALGORITHM_FAST_BIT
@ VMA_DEFRAGMENTATION_FLAG_ALGORITHM_FAST_BIT
Definition vk_mem_alloc.h:728
+
VmaAllocationInfo
Definition vk_mem_alloc.h:1365
+
VmaAllocationInfo::pUserData
void * pUserData
Custom general-purpose pointer that was passed as VmaAllocationCreateInfo::pUserData or set using vma...
Definition vk_mem_alloc.h:1412
VmaDefragmentationContext
An opaque object that represents started defragmentation process.
-
VmaDefragmentationInfo
Parameters for defragmentation.
Definition vk_mem_alloc.h:1454
-
VmaDefragmentationInfo::pool
VmaPool pool
Custom pool to be defragmented.
Definition vk_mem_alloc.h:1461
-
VmaDefragmentationInfo::flags
VmaDefragmentationFlags flags
Use combination of VmaDefragmentationFlagBits.
Definition vk_mem_alloc.h:1456
-
VmaDefragmentationMove::srcAllocation
VmaAllocation srcAllocation
Allocation that should be moved.
Definition vk_mem_alloc.h:1487
-
VmaDefragmentationMove::dstTmpAllocation
VmaAllocation dstTmpAllocation
Temporary allocation pointing to destination memory that will replace srcAllocation.
Definition vk_mem_alloc.h:1494
-
VmaDefragmentationPassMoveInfo
Parameters for incremental defragmentation steps.
Definition vk_mem_alloc.h:1502
-
VmaDefragmentationPassMoveInfo::moveCount
uint32_t moveCount
Number of elements in the pMoves array.
Definition vk_mem_alloc.h:1504
-
VmaDefragmentationPassMoveInfo::pMoves
VmaDefragmentationMove * pMoves
Array of moves to be performed by the user in the current defragmentation pass.
Definition vk_mem_alloc.h:1528
+
VmaDefragmentationInfo
Parameters for defragmentation.
Definition vk_mem_alloc.h:1455
+
VmaDefragmentationInfo::pool
VmaPool pool
Custom pool to be defragmented.
Definition vk_mem_alloc.h:1462
+
VmaDefragmentationInfo::flags
VmaDefragmentationFlags flags
Use combination of VmaDefragmentationFlagBits.
Definition vk_mem_alloc.h:1457
+
VmaDefragmentationMove::srcAllocation
VmaAllocation srcAllocation
Allocation that should be moved.
Definition vk_mem_alloc.h:1488
+
VmaDefragmentationMove::dstTmpAllocation
VmaAllocation dstTmpAllocation
Temporary allocation pointing to destination memory that will replace srcAllocation.
Definition vk_mem_alloc.h:1495
+
VmaDefragmentationPassMoveInfo
Parameters for incremental defragmentation steps.
Definition vk_mem_alloc.h:1503
+
VmaDefragmentationPassMoveInfo::moveCount
uint32_t moveCount
Number of elements in the pMoves array.
Definition vk_mem_alloc.h:1505
+
VmaDefragmentationPassMoveInfo::pMoves
VmaDefragmentationMove * pMoves
Array of moves to be performed by the user in the current defragmentation pass.
Definition vk_mem_alloc.h:1529

Although functions like vmaCreateBuffer(), vmaCreateImage(), vmaDestroyBuffer(), vmaDestroyImage() create/destroy an allocation and a buffer/image at once, these are just a shortcut for creating the resource, allocating memory, and binding them together. Defragmentation works on memory allocations only. You must handle the rest manually. Defragmentation is an iterative process that should repreat "passes" as long as related functions return VK_INCOMPLETE not VK_SUCCESS. In each pass:

  1. vmaBeginDefragmentationPass() function call: