From c168e42de47b7ea7a84b95a9fdc4f743ce4bb7bc Mon Sep 17 00:00:00 2001 From: Adam Sawicki Date: Thu, 17 Feb 2022 14:44:48 +0100 Subject: [PATCH] Rebuilt the docs --- docs/html/allocation_annotation.html | 32 +- docs/html/choosing_memory_type.html | 51 ++- docs/html/configuration.html | 4 +- docs/html/custom_memory_pools.html | 24 +- docs/html/defragmentation.html | 20 +- docs/html/deprecated.html | 14 +- docs/html/enabling_buffer_device_address.html | 2 +- docs/html/general_considerations.html | 12 +- docs/html/globals.html | 7 +- docs/html/globals_defs.html | 1 - docs/html/globals_eval.html | 6 + docs/html/group__group__alloc.html | 86 ++-- docs/html/index.html | 17 +- docs/html/memory_mapping.html | 105 +---- docs/html/quick_start.html | 26 +- docs/html/resource_aliasing.html | 9 +- docs/html/search/all_11.js | 371 +++++++++--------- docs/html/search/defines_0.js | 11 +- docs/html/search/enumvalues_0.js | 98 ++--- docs/html/struct_vma_allocation.html | 2 - .../struct_vma_allocation_create_info.html | 2 - docs/html/struct_vma_allocation_info.html | 2 - docs/html/struct_vma_allocator.html | 2 - .../struct_vma_allocator_create_info.html | 2 - docs/html/struct_vma_allocator_info.html | 2 - docs/html/struct_vma_budget.html | 2 - .../struct_vma_defragmentation_context.html | 2 - .../html/struct_vma_defragmentation_info.html | 2 - .../struct_vma_defragmentation_info2.html | 2 - .../struct_vma_defragmentation_pass_info.html | 2 - ...ct_vma_defragmentation_pass_move_info.html | 2 - .../struct_vma_defragmentation_stats.html | 2 - .../struct_vma_device_memory_callbacks.html | 2 - docs/html/struct_vma_pool.html | 2 - docs/html/struct_vma_pool_create_info.html | 2 - docs/html/struct_vma_pool_stats.html | 2 - docs/html/struct_vma_stat_info.html | 2 - docs/html/struct_vma_stats.html | 2 - docs/html/struct_vma_virtual_allocation.html | 2 - ...ct_vma_virtual_allocation_create_info.html | 2 - .../struct_vma_virtual_allocation_info.html | 2 - docs/html/struct_vma_virtual_block.html | 2 - .../struct_vma_virtual_block_create_info.html | 2 - docs/html/struct_vma_vulkan_functions.html | 2 - docs/html/usage_patterns.html | 222 ++++++++--- docs/html/virtual_allocator.html | 20 +- docs/html/vk__mem__alloc_8h.html | 28 +- docs/html/vk_amd_device_coherent_memory.html | 2 +- docs/html/vk_khr_dedicated_allocation.html | 14 +- 49 files changed, 645 insertions(+), 587 deletions(-) diff --git a/docs/html/allocation_annotation.html b/docs/html/allocation_annotation.html index 5b0b8ce..4070853 100644 --- a/docs/html/allocation_annotation.html +++ b/docs/html/allocation_annotation.html @@ -72,44 +72,42 @@ $(function() {

Allocation user data

You can annotate allocations with your own information, e.g. for debugging purposes. To do that, fill VmaAllocationCreateInfo::pUserData field when creating an allocation. It is an opaque void* pointer. You can use it e.g. as a pointer, some handle, index, key, ordinal number or any other value that would associate the allocation with your custom metadata.

-
VkBufferCreateInfo bufferInfo = { VK_STRUCTURE_TYPE_BUFFER_CREATE_INFO };
-
// Fill bufferInfo...
+
VkBufferCreateInfo bufCreateInfo = ...
MyBufferMetadata* pMetadata = CreateBufferMetadata();
VmaAllocationCreateInfo allocCreateInfo = {};
-
allocCreateInfo.usage = VMA_MEMORY_USAGE_GPU_ONLY;
+
allocCreateInfo.usage = VMA_MEMORY_USAGE_AUTO;
allocCreateInfo.pUserData = pMetadata;
VkBuffer buffer;
VmaAllocation allocation;
-
vmaCreateBuffer(allocator, &bufferInfo, &allocCreateInfo, &buffer, &allocation, nullptr);
+
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_GPU_ONLY
@ VMA_MEMORY_USAGE_GPU_ONLY
Definition: vk_mem_alloc.h:468
-
VmaAllocationCreateInfo
Definition: vk_mem_alloc.h:1120
-
VmaAllocationCreateInfo::pUserData
void * pUserData
Custom general-purpose pointer that will be stored in VmaAllocation, can be read as VmaAllocationInfo...
Definition: vk_mem_alloc.h:1159
-
VmaAllocationCreateInfo::usage
VmaMemoryUsage usage
Intended usage of memory.
Definition: vk_mem_alloc.h:1128
+
VMA_MEMORY_USAGE_AUTO
@ VMA_MEMORY_USAGE_AUTO
Definition: vk_mem_alloc.h:492
+
VmaAllocationCreateInfo
Definition: vk_mem_alloc.h:1168
+
VmaAllocationCreateInfo::pUserData
void * pUserData
Custom general-purpose pointer that will be stored in VmaAllocation, can be read as VmaAllocationInfo...
Definition: vk_mem_alloc.h:1207
+
VmaAllocationCreateInfo::usage
VmaMemoryUsage usage
Intended usage of memory.
Definition: vk_mem_alloc.h:1176
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
Parameters of VmaAllocation objects, that can be retrieved using function vmaGetAllocationInfo().
Definition: vk_mem_alloc.h:1262
-
VmaAllocationInfo::pUserData
void * pUserData
Custom general-purpose pointer that was passed as VmaAllocationCreateInfo::pUserData or set using vma...
Definition: vk_mem_alloc.h:1309
+
VmaAllocationInfo
Parameters of VmaAllocation objects, that can be retrieved using function vmaGetAllocationInfo().
Definition: vk_mem_alloc.h:1310
+
VmaAllocationInfo::pUserData
void * pUserData
Custom general-purpose pointer that was passed as VmaAllocationCreateInfo::pUserData or set using vma...
Definition: vk_mem_alloc.h:1357

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.

+

Values of (non-zero) allocations' pUserData are printed in JSON report created by vmaBuildStatsString() in hexadecimal form.

Allocation names

-

There is alternative mode available where pUserData pointer is used to point to a null-terminated string, giving a name to the allocation. To use this mode, set VMA_ALLOCATION_CREATE_USER_DATA_COPY_STRING_BIT flag in VmaAllocationCreateInfo::flags. Then pUserData passed as VmaAllocationCreateInfo::pUserData or argument to vmaSetAllocationUserData() must be either null or pointer to a null-terminated string. The library creates internal copy of the string, so the pointer you pass doesn't need to be valid for whole lifetime of the allocation. You can free it after the call.

-
VkImageCreateInfo imageInfo = { VK_STRUCTURE_TYPE_IMAGE_CREATE_INFO };
-
// Fill imageInfo...
+

There is alternative mode available where pUserData pointer is used to point to a null-terminated string, giving a name to the allocation. To use this mode, set VMA_ALLOCATION_CREATE_USER_DATA_COPY_STRING_BIT flag in VmaAllocationCreateInfo::flags. Then pUserData passed as VmaAllocationCreateInfo::pUserData or argument to vmaSetAllocationUserData() must be either null or a pointer to a null-terminated string. The library creates internal copy of the string, so the pointer you pass doesn't need to be valid for whole lifetime of the allocation. You can free it after the call.

+
VkImageCreateInfo imageInfo = ...
std::string imageName = "Texture: ";
imageName += fileName;
VmaAllocationCreateInfo allocCreateInfo = {};
-
allocCreateInfo.usage = VMA_MEMORY_USAGE_GPU_ONLY;
+
allocCreateInfo.usage = VMA_MEMORY_USAGE_AUTO;
allocCreateInfo.flags = VMA_ALLOCATION_CREATE_USER_DATA_COPY_STRING_BIT;
allocCreateInfo.pUserData = imageName.c_str();
@@ -117,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:552
-
VmaAllocationCreateInfo::flags
VmaAllocationCreateFlags flags
Use VmaAllocationCreateFlagBits enum.
Definition: vk_mem_alloc.h:1122
+
VMA_ALLOCATION_CREATE_USER_DATA_COPY_STRING_BIT
@ VMA_ALLOCATION_CREATE_USER_DATA_COPY_STRING_BIT
Definition: vk_mem_alloc.h:560
+
VmaAllocationCreateInfo::flags
VmaAllocationCreateFlags flags
Use VmaAllocationCreateFlagBits enum.
Definition: vk_mem_alloc.h:1170

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/choosing_memory_type.html b/docs/html/choosing_memory_type.html index a546db4..54e52c4 100644 --- a/docs/html/choosing_memory_type.html +++ b/docs/html/choosing_memory_type.html @@ -71,50 +71,69 @@ $(function() {

Physical devices in Vulkan support various combinations of memory heaps and types. Help with choosing correct and optimal memory type for your specific resource is one of the key features of this library. You can use it by filling appropriate members of VmaAllocationCreateInfo structure, as described below. You can also combine multiple methods.

    -
  1. If you just want to find memory type index that meets your requirements, you can use function: vmaFindMemoryTypeIndex(), vmaFindMemoryTypeIndexForBufferInfo(), vmaFindMemoryTypeIndexForImageInfo().
    2. +
  2. If you just want to find memory type index that meets your requirements, you can use function: vmaFindMemoryTypeIndexForBufferInfo(), vmaFindMemoryTypeIndexForImageInfo(), vmaFindMemoryTypeIndex().
  3. If you want to allocate a region of device memory without association with any specific image or buffer, you can use function vmaAllocateMemory(). Usage of this function is not recommended and usually not needed. vmaAllocateMemoryPages() function is also provided for creating multiple allocations at once, which may be useful for sparse binding.
  4. If you already have a buffer or an image created, you want to allocate memory for it and then you will bind it yourself, you can use function vmaAllocateMemoryForBuffer(), vmaAllocateMemoryForImage(). For binding you should use functions: vmaBindBufferMemory(), vmaBindImageMemory() or their extended versions: vmaBindBufferMemory2(), vmaBindImageMemory2().
    5. -
  5. If you want to create a buffer or an image, allocate memory for it and bind them together, all in one call, you can use function vmaCreateBuffer(), vmaCreateImage(). This is the easiest and recommended way to use this library.
    6. +
  6. This is the easiest and recommended way to use this library: If you want to create a buffer or an image, allocate memory for it and bind them together, all in one call, you can use function vmaCreateBuffer(), vmaCreateImage().

When using 3. or 4., the library internally queries Vulkan for memory types supported for that buffer or image (function vkGetBufferMemoryRequirements()) and uses only one of these types.

If no memory type can be found that meets all the requirements, these functions return VK_ERROR_FEATURE_NOT_PRESENT.

You can leave VmaAllocationCreateInfo structure completely filled with zeros. It means no requirements are specified for memory type. It is valid, although not very useful.

Usage

-

The easiest way to specify memory requirements is to fill member VmaAllocationCreateInfo::usage using one of the values of enum VmaMemoryUsage. It defines high level, common usage types. For more details, see description of this enum.

-

For example, if you want to create a uniform buffer that will be filled using transfer only once or infrequently and used for rendering every frame, you can do it using following code:

+

The easiest way to specify memory requirements is to fill member VmaAllocationCreateInfo::usage using one of the values of enum VmaMemoryUsage. It defines high level, common usage types. Since version 3 of the library, it is recommended to use VMA_MEMORY_USAGE_AUTO to let it select best memory type for your resource automatically.

+

For example, if you want to create a uniform buffer that will be filled using transfer only once or infrequently and then used for rendering every frame as a uniform buffer, you can do it using following code. The buffer will most likely end up in a memory type with VK_MEMORY_PROPERTY_DEVICE_LOCAL_BIT to be fast to access by the GPU device.

VkBufferCreateInfo bufferInfo = { VK_STRUCTURE_TYPE_BUFFER_CREATE_INFO };
bufferInfo.size = 65536;
bufferInfo.usage = VK_BUFFER_USAGE_UNIFORM_BUFFER_BIT | VK_BUFFER_USAGE_TRANSFER_DST_BIT;
VmaAllocationCreateInfo allocInfo = {};
-
allocInfo.usage = VMA_MEMORY_USAGE_GPU_ONLY;
+
allocInfo.usage = VMA_MEMORY_USAGE_AUTO;
VkBuffer buffer;
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_GPU_ONLY
@ VMA_MEMORY_USAGE_GPU_ONLY
Definition: vk_mem_alloc.h:468
-
VmaAllocationCreateInfo
Definition: vk_mem_alloc.h:1120
-
VmaAllocationCreateInfo::usage
VmaMemoryUsage usage
Intended usage of memory.
Definition: vk_mem_alloc.h:1128
+
VMA_MEMORY_USAGE_AUTO
@ VMA_MEMORY_USAGE_AUTO
Definition: vk_mem_alloc.h:492
+
VmaAllocationCreateInfo
Definition: vk_mem_alloc.h:1168
+
VmaAllocationCreateInfo::usage
VmaMemoryUsage usage
Intended usage of memory.
Definition: vk_mem_alloc.h:1176
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.

+

For example, a staging buffer that will be filled via mapped pointer and then used as a source of transfer to the buffer decribed previously can be created like this. It will likely and up in a memory type that is HOST_VISIBLE and HOST_COHERENT but not HOST_CACHED (meaning uncached, write-combined) and not DEVICE_LOCAL (meaning system RAM).

+
VkBufferCreateInfo stagingBufferInfo = { VK_STRUCTURE_TYPE_BUFFER_CREATE_INFO };
+
stagingBufferInfo.size = 65536;
+
stagingBufferInfo.usage = VK_BUFFER_USAGE_TRANSFER_SRC_BIT;
+
+
VmaAllocationCreateInfo stagingAllocInfo = {};
+
stagingAllocInfo.usage = VMA_MEMORY_USAGE_AUTO;
+
stagingAllocInfo.flags = VMA_ALLOCATION_CREATE_HOST_ACCESS_SEQUENTIAL_WRITE_BIT;
+
+
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:597
+
VmaAllocationCreateInfo::flags
VmaAllocationCreateFlags flags
Use VmaAllocationCreateFlagBits enum.
Definition: vk_mem_alloc.h:1170
+

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

Required and preferred flags

You can specify more detailed requirements by filling members VmaAllocationCreateInfo::requiredFlags and VmaAllocationCreateInfo::preferredFlags with a combination of bits from enum VkMemoryPropertyFlags. For example, if you want to create a buffer that will be persistently mapped on host (so it must be HOST_VISIBLE) and preferably will also be HOST_COHERENT and HOST_CACHED, use following code:

VmaAllocationCreateInfo allocInfo = {};
allocInfo.requiredFlags = VK_MEMORY_PROPERTY_HOST_VISIBLE_BIT;
allocInfo.preferredFlags = VK_MEMORY_PROPERTY_HOST_COHERENT_BIT | VK_MEMORY_PROPERTY_HOST_CACHED_BIT;
-
allocInfo.flags = VMA_ALLOCATION_CREATE_MAPPED_BIT;
+
allocInfo.flags = VMA_ALLOCATION_CREATE_HOST_ACCESS_RANDOM_BIT | VMA_ALLOCATION_CREATE_MAPPED_BIT;
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:542
-
VmaAllocationCreateInfo::preferredFlags
VkMemoryPropertyFlags preferredFlags
Flags that preferably should be set in a memory type chosen for an allocation.
Definition: vk_mem_alloc.h:1138
-
VmaAllocationCreateInfo::requiredFlags
VkMemoryPropertyFlags requiredFlags
Flags that must be set in a Memory Type chosen for an allocation.
Definition: vk_mem_alloc.h:1133
-
VmaAllocationCreateInfo::flags
VmaAllocationCreateFlags flags
Use VmaAllocationCreateFlagBits enum.
Definition: vk_mem_alloc.h:1122
+
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:550
+
VMA_ALLOCATION_CREATE_HOST_ACCESS_RANDOM_BIT
@ VMA_ALLOCATION_CREATE_HOST_ACCESS_RANDOM_BIT
Definition: vk_mem_alloc.h:609
+
VmaAllocationCreateInfo::preferredFlags
VkMemoryPropertyFlags preferredFlags
Flags that preferably should be set in a memory type chosen for an allocation.
Definition: vk_mem_alloc.h:1186
+
VmaAllocationCreateInfo::requiredFlags
VkMemoryPropertyFlags requiredFlags
Flags that must be set in a Memory Type chosen for an allocation.
Definition: vk_mem_alloc.h:1181

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.

+

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

Explicit memory types

If you inspected memory types available on the physical device and you have a preference for memory types that you want to use, you can fill member VmaAllocationCreateInfo::memoryTypeBits. It is a bit mask, where each bit set means that a memory type with that index is allowed to be used for the allocation. Special value 0, just like UINT32_MAX, means there are no restrictions to memory type index.

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

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/configuration.html b/docs/html/configuration.html index fe03f45..8ddf8ab 100644 --- a/docs/html/configuration.html +++ b/docs/html/configuration.html @@ -78,7 +78,7 @@ Pointers to Vulkan functions
m_VulkanFunctions.vkAllocateMemory = (PFN_vkAllocateMemory)vkAllocateMemory;

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.

+

Third, VMA tries to fetch remaining pointers that are still null by calling vkGetInstanceProcAddr and vkGetDeviceProcAddr on its own. You need to only fill in VmaVulkanFunctions::vkGetInstanceProcAddr and VmaVulkanFunctions::vkGetDeviceProcAddr. Other pointers will be fetched automatically. 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.

Custom host memory allocator

@@ -88,7 +88,7 @@ Device memory allocation callbacks

The library makes calls to vkAllocateMemory() and vkFreeMemory() internally. You can setup callbacks to be informed about these calls, e.g. for the purpose of gathering some statistics. To do it, fill optional member VmaAllocatorCreateInfo::pDeviceMemoryCallbacks.

Device heap memory limit

-

When device memory of certain heap runs out of free space, new allocations may fail (returning error code) or they may succeed, silently pushing some existing memory blocks from GPU VRAM to system RAM (which degrades performance). This behavior is implementation-dependent - it depends on GPU vendor and graphics driver.

+

When device memory of certain heap runs out of free space, new allocations may fail (returning error code) or they may succeed, silently pushing some existing_ memory blocks from GPU VRAM to system RAM (which degrades performance). This behavior is implementation-dependent - it depends on GPU vendor and graphics driver.

On AMD cards it can be controlled while creating Vulkan device object by using VK_AMD_memory_overallocation_behavior extension, if available.

Alternatively, if you want to test how your program behaves with limited amount of Vulkan device memory available without switching your graphics card to one that really has smaller VRAM, you can use a feature of this library intended for this purpose. To do it, fill optional member VmaAllocatorCreateInfo::pHeapSizeLimit.

diff --git a/docs/html/custom_memory_pools.html b/docs/html/custom_memory_pools.html index a15b91e..946a034 100644 --- a/docs/html/custom_memory_pools.html +++ b/docs/html/custom_memory_pools.html @@ -77,6 +77,7 @@ $(function() {
  • Limit maximum amount of Vulkan memory allocated for that pool.
  • Reserve minimum or fixed amount of Vulkan memory always preallocated for that pool.
  • Use extra parameters for a set of your allocations that are available in VmaPoolCreateInfo but not in VmaAllocationCreateInfo - e.g., custom minimum alignment, custom pNext chain.
    • +
  • Perform defragmentation on a specific subset of your allocations.

    • To use custom memory pools:

      @@ -108,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:1120
      -
      VmaAllocationCreateInfo::pool
      VmaPool pool
      Pool that this allocation should be created in.
      Definition: vk_mem_alloc.h:1152
      +
      VmaAllocationCreateInfo
      Definition: vk_mem_alloc.h:1168
      +
      VmaAllocationCreateInfo::pool
      VmaPool pool
      Pool that this allocation should be created in.
      Definition: vk_mem_alloc.h:1200
      VmaAllocation
      Represents single memory allocation.
      -
      VmaAllocationInfo
      Parameters of VmaAllocation objects, that can be retrieved using function vmaGetAllocationInfo().
      Definition: vk_mem_alloc.h:1262
      -
      VmaPoolCreateInfo
      Describes parameter of created VmaPool.
      Definition: vk_mem_alloc.h:1171
      -
      VmaPoolCreateInfo::memoryTypeIndex
      uint32_t memoryTypeIndex
      Vulkan memory type index to allocate this pool from.
      Definition: vk_mem_alloc.h:1174
      -
      VmaPoolCreateInfo::maxBlockCount
      size_t maxBlockCount
      Maximum number of blocks that can be allocated in this pool. Optional.
      Definition: vk_mem_alloc.h:1200
      +
      VmaAllocationInfo
      Parameters of VmaAllocation objects, that can be retrieved using function vmaGetAllocationInfo().
      Definition: vk_mem_alloc.h:1310
      +
      VmaPoolCreateInfo
      Describes parameter of created VmaPool.
      Definition: vk_mem_alloc.h:1219
      +
      VmaPoolCreateInfo::memoryTypeIndex
      uint32_t memoryTypeIndex
      Vulkan memory type index to allocate this pool from.
      Definition: vk_mem_alloc.h:1222
      +
      VmaPoolCreateInfo::maxBlockCount
      size_t maxBlockCount
      Maximum number of blocks that can be allocated in this pool. Optional.
      Definition: vk_mem_alloc.h:1248
      VmaPool
      Represents custom memory pool.

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

    vmaDestroyBuffer(allocator, buf, alloc);
    @@ -122,15 +123,16 @@ $(function() {
    vmaDestroyBuffer
    void vmaDestroyBuffer(VmaAllocator allocator, VkBuffer buffer, VmaAllocation allocation)
    Destroys Vulkan buffer and frees allocated memory.
    vmaDestroyPool
    void vmaDestroyPool(VmaAllocator allocator, VmaPool pool)
    Destroys VmaPool object and frees Vulkan device memory.

    New versions of this library support creating dedicated allocations in custom pools. It is supported only when VmaPoolCreateInfo::blockSize = 0. To use this feature, set VmaAllocationCreateInfo::pool to the pointer to your custom pool and VmaAllocationCreateInfo::flags to VMA_ALLOCATION_CREATE_DEDICATED_MEMORY_BIT.

    +
    Note
    Excessive use of custom pools is a common mistake when using this library. Custom pools may be useful for special purposes - when you want to keep certain type of resources separate e.g. to reserve minimum amount of memory for them or limit maximum amount of memory they can occupy. For most resources this is not needed and so it is not recommended to create VmaPool objects and allocations out of them. Allocating from the default pool is sufficient.

    Choosing memory type index

    When creating a pool, you must explicitly specify memory type index. To find the one suitable for your buffers or images, you can use helper functions vmaFindMemoryTypeIndexForBufferInfo(), vmaFindMemoryTypeIndexForImageInfo(). You need to provide structures with example parameters of buffers or images that you are going to create in that pool.

    VkBufferCreateInfo exampleBufCreateInfo = { VK_STRUCTURE_TYPE_BUFFER_CREATE_INFO };
    -
    exampleBufCreateInfo.size = 1024; // Whatever.
    -
    exampleBufCreateInfo.usage = VK_BUFFER_USAGE_UNIFORM_BUFFER_BIT | VK_BUFFER_USAGE_TRANSFER_DST_BIT; // Change if needed.
    +
    exampleBufCreateInfo.size = 1024; // Doesn't matter
    +
    exampleBufCreateInfo.usage = VK_BUFFER_USAGE_UNIFORM_BUFFER_BIT | VK_BUFFER_USAGE_TRANSFER_DST_BIT;
    VmaAllocationCreateInfo allocCreateInfo = {};
    -
    allocCreateInfo.usage = VMA_MEMORY_USAGE_GPU_ONLY; // Change if needed.
    +
    allocCreateInfo.usage = VMA_MEMORY_USAGE_AUTO;
    uint32_t memTypeIndex;
    vmaFindMemoryTypeIndexForBufferInfo(allocator, &exampleBufCreateInfo, &allocCreateInfo, &memTypeIndex);
    @@ -139,8 +141,8 @@ Choosing memory type index
    poolCreateInfo.memoryTypeIndex = memTypeIndex;
    // ...
    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_GPU_ONLY
    @ VMA_MEMORY_USAGE_GPU_ONLY
    Definition: vk_mem_alloc.h:468
    -
    VmaAllocationCreateInfo::usage
    VmaMemoryUsage usage
    Intended usage of memory.
    Definition: vk_mem_alloc.h:1128
    +
    VMA_MEMORY_USAGE_AUTO
    @ VMA_MEMORY_USAGE_AUTO
    Definition: vk_mem_alloc.h:492
    +
    VmaAllocationCreateInfo::usage
    VmaMemoryUsage usage
    Intended usage of memory.
    Definition: vk_mem_alloc.h:1176

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

    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

    vmaBindBufferMemory(allocator, allocations[i], buffers[i]);
    }
    }
    -
    VmaDefragmentationInfo2::maxGpuAllocationsToMove
    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
    -
    VmaDefragmentationInfo2::maxGpuBytesToMove
    VkDeviceSize maxGpuBytesToMove
    Maximum total numbers of bytes that can be copied while moving allocations to different places using ...
    Definition: vk_mem_alloc.h:1371
    -
    VmaDefragmentationInfo2::commandBuffer
    VkCommandBuffer commandBuffer
    Optional. Command buffer where GPU copy commands will be posted.
    Definition: vk_mem_alloc.h:1385
    +
    VmaDefragmentationInfo2::maxGpuAllocationsToMove
    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:1424
    +
    VmaDefragmentationInfo2::maxGpuBytesToMove
    VkDeviceSize maxGpuBytesToMove
    Maximum total numbers of bytes that can be copied while moving allocations to different places using ...
    Definition: vk_mem_alloc.h:1419
    +
    VmaDefragmentationInfo2::commandBuffer
    VkCommandBuffer commandBuffer
    Optional. Command buffer where GPU copy commands will be posted.
    Definition: vk_mem_alloc.h:1433

    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/deprecated.html b/docs/html/deprecated.html index 9410dfe..16a6a4a 100644 --- a/docs/html/deprecated.html +++ b/docs/html/deprecated.html @@ -67,9 +67,19 @@ $(function() {
    Member VMA_ALLOCATION_CREATE_RESERVED_1_BIT
    -
    Removed. Do not use.
    +
    Removed. Do not use.
    Member VMA_ALLOCATION_CREATE_RESERVED_2_BIT
    -
    Removed. Do not use.
    +
    Removed. Do not use.
    +
    Member VMA_MEMORY_USAGE_CPU_COPY
    +
    Obsolete, preserved for backward compatibility. Prefers not VK_MEMORY_PROPERTY_DEVICE_LOCAL_BIT.
    +
    Member VMA_MEMORY_USAGE_CPU_ONLY
    +
    Obsolete, preserved for backward compatibility. Guarantees VK_MEMORY_PROPERTY_HOST_VISIBLE_BIT and VK_MEMORY_PROPERTY_HOST_COHERENT_BIT.
    +
    Member VMA_MEMORY_USAGE_CPU_TO_GPU
    +
    Obsolete, preserved for backward compatibility. Guarantees VK_MEMORY_PROPERTY_HOST_VISIBLE_BIT, prefers VK_MEMORY_PROPERTY_DEVICE_LOCAL_BIT.
    +
    Member VMA_MEMORY_USAGE_GPU_ONLY
    +
    Obsolete, preserved for backward compatibility. Prefers VK_MEMORY_PROPERTY_DEVICE_LOCAL_BIT.
    +
    Member VMA_MEMORY_USAGE_GPU_TO_CPU
    +
    Obsolete, preserved for backward compatibility. Guarantees VK_MEMORY_PROPERTY_HOST_VISIBLE_BIT, prefers VK_MEMORY_PROPERTY_HOST_CACHED_BIT.
    Member vmaDefragment (VmaAllocator allocator, const VmaAllocation *pAllocations, size_t allocationCount, VkBool32 *pAllocationsChanged, const VmaDefragmentationInfo *pDefragmentationInfo, VmaDefragmentationStats *pDefragmentationStats)
    This is a part of the old interface. It is recommended to use structure VmaDefragmentationInfo2 and function vmaDefragmentationBegin() instead.
    Member VmaDefragmentationInfo
    diff --git a/docs/html/enabling_buffer_device_address.html b/docs/html/enabling_buffer_device_address.html index a465503..feb2f81 100644 --- a/docs/html/enabling_buffer_device_address.html +++ b/docs/html/enabling_buffer_device_address.html @@ -69,7 +69,7 @@ $(function() {
    Enabling buffer device address
    -

    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.

    +

    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 has been promoted to core Vulkan 1.2.

    If you want to use this feature in connection with VMA, follow these steps:

    Initialization

    diff --git a/docs/html/general_considerations.html b/docs/html/general_considerations.html index 55e1952..9e6f009 100644 --- a/docs/html/general_considerations.html +++ b/docs/html/general_considerations.html @@ -76,7 +76,7 @@ Thread safety

  • By default, all calls to functions that take VmaAllocator as first parameter are safe to call from multiple threads simultaneously because they are synchronized internally when needed. This includes allocation and deallocation from default memory pool, as well as custom VmaPool.
  • When the allocator is created with VMA_ALLOCATOR_CREATE_EXTERNALLY_SYNCHRONIZED_BIT flag, calls to functions that take such VmaAllocator object must be synchronized externally.
  • Access to a VmaAllocation object must be externally synchronized. For example, you must not call vmaGetAllocationInfo() and vmaMapMemory() from different threads at the same time if you pass the same VmaAllocation object to these functions.
    • -
  • VmaVirtualBlock is also not safe to be used from multiple threads simultaneously.
    • +
  • VmaVirtualBlock is not safe to be used from multiple threads simultaneously.

    • Validation layer warnings

    @@ -101,7 +101,7 @@ Allocation algorithm
    1. Try to find free range of memory in existing blocks.
    2. If failed, try to create a new block of VkDeviceMemory, with preferred block size.
      3. -
    3. If failed, try to create such block with size/2, size/4, size/8.
      4. +
    4. If failed, try to create such block with size / 2, size / 4, size / 8.
    5. If failed, try to allocate separate VkDeviceMemory for this allocation, just like when you use VMA_ALLOCATION_CREATE_DEDICATED_MEMORY_BIT.
    6. If failed, choose other memory type that meets the requirements specified in VmaAllocationCreateInfo and go to point 1.
    7. If failed, return VK_ERROR_OUT_OF_DEVICE_MEMORY.
      8. @@ -109,13 +109,13 @@ Allocation algorithm

      Features not supported

      Features deliberately excluded from the scope of this library:

      - +
    diff --git a/docs/html/globals.html b/docs/html/globals.html index 6265014..4ca23ff 100644 --- a/docs/html/globals.html +++ b/docs/html/globals.html @@ -72,11 +72,13 @@ $(function() {

    - v -

  • Staying within budget
  • Recommended usage patterns
  • Configuration +
  • VK_KHR_dedicated_allocation
  • Enabling buffer device address
  • VK_AMD_device_coherent_memory
    • - -
  • General considerations