From d2f0313d20c803f83cc3637ac1facf8e4d6899e4 Mon Sep 17 00:00:00 2001 From: Adam Sawicki Date: Mon, 18 Oct 2021 17:32:40 +0200 Subject: [PATCH] Fixes in comments Regenerated documentation. --- docs/html/allocation_annotation.html | 86 +-- docs/html/annotated.html | 20 +- docs/html/choosing_memory_type.html | 92 +-- docs/html/classes.html | 22 +- docs/html/configuration.html | 48 +- docs/html/custom_memory_pools.html | 140 ++--- docs/html/debugging_memory_usage.html | 62 +- docs/html/defragmentation.html | 132 ++-- docs/html/deprecated.html | 22 +- .../dir_d44c64559bbebec7f509842c48db8b23.html | 26 +- docs/html/doxygen.css | 40 +- docs/html/enabling_buffer_device_address.html | 44 +- docs/html/files.html | 20 +- docs/html/functions.html | 413 ++++--------- docs/html/functions_vars.html | 413 ++++--------- docs/html/general_considerations.html | 28 +- docs/html/globals.html | 549 +++++------------ docs/html/globals_defs.html | 49 +- docs/html/globals_enum.html | 41 +- docs/html/globals_eval.html | 187 ++---- docs/html/globals_func.html | 227 ++----- docs/html/globals_type.html | 137 ++--- docs/html/index.html | 28 +- docs/html/jquery.js | 4 +- docs/html/lost_allocations.html | 82 +-- docs/html/memory_mapping.html | 126 ++-- docs/html/menu.js | 86 ++- docs/html/opengl_interop.html | 40 +- docs/html/pages.html | 20 +- docs/html/quick_start.html | 86 +-- docs/html/record_and_replay.html | 30 +- docs/html/resource_aliasing.html | 56 +- docs/html/search/all_0.html | 6 +- docs/html/search/all_1.html | 6 +- docs/html/search/all_1.js | 12 +- docs/html/search/all_10.html | 6 +- docs/html/search/all_10.js | 16 +- docs/html/search/all_11.html | 6 +- docs/html/search/all_11.js | 312 +++++----- docs/html/search/all_2.html | 6 +- docs/html/search/all_2.js | 8 +- docs/html/search/all_3.html | 6 +- docs/html/search/all_3.js | 12 +- docs/html/search/all_4.html | 6 +- docs/html/search/all_4.js | 2 +- docs/html/search/all_5.html | 6 +- docs/html/search/all_5.js | 4 +- docs/html/search/all_6.html | 6 +- docs/html/search/all_6.js | 2 +- docs/html/search/all_7.html | 6 +- docs/html/search/all_7.js | 2 +- docs/html/search/all_8.html | 6 +- docs/html/search/all_8.js | 2 +- docs/html/search/all_9.html | 6 +- docs/html/search/all_9.js | 32 +- docs/html/search/all_a.html | 6 +- docs/html/search/all_a.js | 4 +- docs/html/search/all_b.html | 6 +- docs/html/search/all_b.js | 48 +- docs/html/search/all_c.html | 6 +- docs/html/search/all_c.js | 2 +- docs/html/search/all_d.html | 6 +- docs/html/search/all_d.js | 8 +- docs/html/search/all_e.html | 6 +- docs/html/search/all_e.js | 6 +- docs/html/search/all_f.html | 6 +- docs/html/search/all_f.js | 2 +- docs/html/search/classes_0.html | 6 +- docs/html/search/classes_0.js | 42 +- docs/html/search/defines_0.html | 6 +- docs/html/search/defines_0.js | 16 +- docs/html/search/enums_0.html | 6 +- docs/html/search/enums_0.js | 12 +- docs/html/search/enumvalues_0.html | 6 +- docs/html/search/enumvalues_0.js | 84 +-- docs/html/search/files_0.html | 6 +- docs/html/search/files_0.js | 2 +- docs/html/search/functions_0.html | 6 +- docs/html/search/functions_0.js | 104 ++-- docs/html/search/pages_0.html | 6 +- docs/html/search/pages_0.js | 2 +- docs/html/search/pages_1.html | 6 +- docs/html/search/pages_1.js | 6 +- docs/html/search/pages_2.html | 6 +- docs/html/search/pages_2.js | 6 +- docs/html/search/pages_3.html | 6 +- docs/html/search/pages_3.js | 2 +- docs/html/search/pages_4.html | 6 +- docs/html/search/pages_4.js | 2 +- docs/html/search/pages_5.html | 6 +- docs/html/search/pages_5.js | 2 +- docs/html/search/pages_6.html | 6 +- docs/html/search/pages_6.js | 2 +- docs/html/search/pages_7.html | 6 +- docs/html/search/pages_7.js | 2 +- docs/html/search/pages_8.html | 6 +- docs/html/search/pages_8.js | 2 +- docs/html/search/pages_9.html | 6 +- docs/html/search/pages_9.js | 6 +- docs/html/search/pages_a.html | 6 +- docs/html/search/pages_a.js | 4 +- docs/html/search/pages_b.html | 6 +- docs/html/search/pages_b.js | 6 +- docs/html/search/search.css | 12 +- docs/html/search/search.js | 66 +- docs/html/search/typedefs_0.html | 6 +- docs/html/search/typedefs_0.js | 4 +- docs/html/search/typedefs_1.html | 6 +- docs/html/search/typedefs_1.js | 56 +- docs/html/search/variables_0.html | 6 +- docs/html/search/variables_0.js | 14 +- docs/html/search/variables_1.html | 6 +- docs/html/search/variables_1.js | 12 +- docs/html/search/variables_2.html | 6 +- docs/html/search/variables_2.js | 2 +- docs/html/search/variables_3.html | 6 +- docs/html/search/variables_3.js | 6 +- docs/html/search/variables_4.html | 6 +- docs/html/search/variables_4.js | 4 +- docs/html/search/variables_5.html | 6 +- docs/html/search/variables_5.js | 2 +- docs/html/search/variables_6.html | 6 +- docs/html/search/variables_6.js | 30 +- docs/html/search/variables_7.html | 6 +- docs/html/search/variables_7.js | 2 +- docs/html/search/variables_8.html | 6 +- docs/html/search/variables_8.js | 44 +- docs/html/search/variables_9.html | 6 +- docs/html/search/variables_9.js | 2 +- docs/html/search/variables_a.html | 6 +- docs/html/search/variables_a.js | 2 +- docs/html/search/variables_b.html | 6 +- docs/html/search/variables_b.js | 2 +- docs/html/search/variables_c.html | 6 +- docs/html/search/variables_c.js | 16 +- docs/html/search/variables_d.html | 6 +- docs/html/search/variables_d.js | 36 +- docs/html/statistics.html | 36 +- docs/html/staying_within_budget.html | 40 +- docs/html/struct_vma_allocation.html | 34 +- ...ct_vma_allocation_create_info-members.html | 28 +- .../struct_vma_allocation_create_info.html | 54 +- .../struct_vma_allocation_info-members.html | 26 +- docs/html/struct_vma_allocation_info.html | 58 +- docs/html/struct_vma_allocator.html | 28 +- ...uct_vma_allocator_create_info-members.html | 32 +- .../struct_vma_allocator_create_info.html | 88 +-- .../struct_vma_allocator_info-members.html | 22 +- docs/html/struct_vma_allocator_info.html | 38 +- docs/html/struct_vma_budget-members.html | 24 +- docs/html/struct_vma_budget.html | 46 +- .../struct_vma_defragmentation_context.html | 26 +- ...ruct_vma_defragmentation_info-members.html | 22 +- .../html/struct_vma_defragmentation_info.html | 34 +- ...uct_vma_defragmentation_info2-members.html | 30 +- .../struct_vma_defragmentation_info2.html | 72 +-- ...vma_defragmentation_pass_info-members.html | 22 +- .../struct_vma_defragmentation_pass_info.html | 32 +- ...efragmentation_pass_move_info-members.html | 22 +- ...ct_vma_defragmentation_pass_move_info.html | 30 +- ...uct_vma_defragmentation_stats-members.html | 24 +- .../struct_vma_defragmentation_stats.html | 34 +- ...t_vma_device_memory_callbacks-members.html | 22 +- .../struct_vma_device_memory_callbacks.html | 36 +- docs/html/struct_vma_pool.html | 28 +- .../struct_vma_pool_create_info-members.html | 28 +- docs/html/struct_vma_pool_create_info.html | 68 +-- docs/html/struct_vma_pool_stats-members.html | 26 +- docs/html/struct_vma_pool_stats.html | 40 +- .../struct_vma_record_settings-members.html | 22 +- docs/html/struct_vma_record_settings.html | 32 +- docs/html/struct_vma_stat_info-members.html | 30 +- docs/html/struct_vma_stat_info.html | 48 +- docs/html/struct_vma_stats-members.html | 22 +- docs/html/struct_vma_stats.html | 32 +- .../struct_vma_vulkan_functions-members.html | 36 +- docs/html/struct_vma_vulkan_functions.html | 62 +- docs/html/tabs.css | 2 +- docs/html/usage_patterns.html | 72 +-- docs/html/vk__mem__alloc_8h.html | 574 +++++++++--------- docs/html/vk_amd_device_coherent_memory.html | 44 +- docs/html/vk_khr_dedicated_allocation.html | 44 +- include/vk_mem_alloc.h | 5 +- 183 files changed, 3052 insertions(+), 3879 deletions(-) diff --git a/docs/html/allocation_annotation.html b/docs/html/allocation_annotation.html index 9f39d7c..cd9fe6c 100644 --- a/docs/html/allocation_annotation.html +++ b/docs/html/allocation_annotation.html @@ -2,8 +2,8 @@ - - + + Vulkan Memory Allocator: Allocation names and user data @@ -29,21 +29,22 @@ - + +/* @license-end */ + -
-
-
Allocation names and user data
+
+
Allocation names and user data

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.

+

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...
MyBufferMetadata* pMetadata = CreateBufferMetadata();
-
VmaAllocationCreateInfo allocCreateInfo = {};
-
allocCreateInfo.usage = VMA_MEMORY_USAGE_GPU_ONLY;
-
allocCreateInfo.pUserData = pMetadata;
+
VmaAllocationCreateInfo allocCreateInfo = {};
+
allocCreateInfo.usage = VMA_MEMORY_USAGE_GPU_ONLY;
+
allocCreateInfo.pUserData = pMetadata;
VkBuffer buffer;
-
VmaAllocation allocation;
-
vmaCreateBuffer(allocator, &bufferInfo, &allocCreateInfo, &buffer, &allocation, nullptr);
-
VmaAllocationCreateInfo
Definition: vk_mem_alloc.h:991
-
VmaAllocationCreateInfo::pUserData
void * pUserData
Custom general-purpose pointer that will be stored in VmaAllocation, can be read as VmaAllocationInfo...
Definition: vk_mem_alloc.h:1030
-
VmaAllocationCreateInfo::usage
VmaMemoryUsage usage
Intended usage of memory.
Definition: vk_mem_alloc.h:999
+
VmaAllocation allocation;
+
vmaCreateBuffer(allocator, &bufferInfo, &allocCreateInfo, &buffer, &allocation, nullptr);
+
VmaAllocationCreateInfo
Definition: vk_mem_alloc.h:987
+
VmaAllocationCreateInfo::pUserData
void * pUserData
Custom general-purpose pointer that will be stored in VmaAllocation, can be read as VmaAllocationInfo...
Definition: vk_mem_alloc.h:1026
+
VmaAllocationCreateInfo::usage
VmaMemoryUsage usage
Intended usage of memory.
Definition: vk_mem_alloc.h:995
VmaAllocation
Represents single memory allocation.
-
VMA_MEMORY_USAGE_GPU_ONLY
@ VMA_MEMORY_USAGE_GPU_ONLY
Definition: vk_mem_alloc.h:833
+
VMA_MEMORY_USAGE_GPU_ONLY
@ VMA_MEMORY_USAGE_GPU_ONLY
Definition: vk_mem_alloc.h:829
vmaCreateBuffer
VkResult vmaCreateBuffer(VmaAllocator allocator, const VkBufferCreateInfo *pBufferCreateInfo, const VmaAllocationCreateInfo *pAllocationCreateInfo, VkBuffer *pBuffer, VmaAllocation *pAllocation, VmaAllocationInfo *pAllocationInfo)
-

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

-
VmaAllocationInfo allocInfo;
-
vmaGetAllocationInfo(allocator, allocation, &allocInfo);
-
MyBufferMetadata* pMetadata = (MyBufferMetadata*)allocInfo.pUserData;
-
VmaAllocationInfo
Parameters of VmaAllocation objects, that can be retrieved using function vmaGetAllocationInfo().
Definition: vk_mem_alloc.h:1358
-
VmaAllocationInfo::pUserData
void * pUserData
Custom general-purpose pointer that was passed as VmaAllocationCreateInfo::pUserData or set using vma...
Definition: vk_mem_alloc.h:1407
+

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

+
VmaAllocationInfo allocInfo;
+
vmaGetAllocationInfo(allocator, allocation, &allocInfo);
+
MyBufferMetadata* pMetadata = (MyBufferMetadata*)allocInfo.pUserData;
+
VmaAllocationInfo
Parameters of VmaAllocation objects, that can be retrieved using function vmaGetAllocationInfo().
Definition: vk_mem_alloc.h:1354
+
VmaAllocationInfo::pUserData
void * pUserData
Custom general-purpose pointer that was passed as VmaAllocationCreateInfo::pUserData or set using vma...
Definition: vk_mem_alloc.h:1403
vmaGetAllocationInfo
void vmaGetAllocationInfo(VmaAllocator allocator, VmaAllocation allocation, VmaAllocationInfo *pAllocationInfo)
Returns current information about specified allocation and atomically marks it as used in current fra...
-

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.

+

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.

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.

+

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...
std::string imageName = "Texture: ";
imageName += fileName;
-
VmaAllocationCreateInfo allocCreateInfo = {};
-
allocCreateInfo.usage = VMA_MEMORY_USAGE_GPU_ONLY;
-
allocCreateInfo.flags = VMA_ALLOCATION_CREATE_USER_DATA_COPY_STRING_BIT;
-
allocCreateInfo.pUserData = imageName.c_str();
+
VmaAllocationCreateInfo allocCreateInfo = {};
+
allocCreateInfo.usage = VMA_MEMORY_USAGE_GPU_ONLY;
+
allocCreateInfo.flags = VMA_ALLOCATION_CREATE_USER_DATA_COPY_STRING_BIT;
+
allocCreateInfo.pUserData = imageName.c_str();
VkImage image;
-
VmaAllocation allocation;
-
vmaCreateImage(allocator, &imageInfo, &allocCreateInfo, &image, &allocation, nullptr);
-
VmaAllocationCreateInfo::flags
VmaAllocationCreateFlags flags
Use VmaAllocationCreateFlagBits enum.
Definition: vk_mem_alloc.h:993
+
VmaAllocation allocation;
+
vmaCreateImage(allocator, &imageInfo, &allocCreateInfo, &image, &allocation, nullptr);
+
VmaAllocationCreateInfo::flags
VmaAllocationCreateFlags flags
Use VmaAllocationCreateFlagBits enum.
Definition: vk_mem_alloc.h:989
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:936
-

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);
-
const char* imageName = (const char*)allocInfo.pUserData;
+
VMA_ALLOCATION_CREATE_USER_DATA_COPY_STRING_BIT
@ VMA_ALLOCATION_CREATE_USER_DATA_COPY_STRING_BIT
Definition: vk_mem_alloc.h:932
+

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);
+
const char* imageName = (const char*)allocInfo.pUserData;
printf("Image name: %s\n", imageName);
-

That string is also printed in JSON report created by vmaBuildStatsString().

+

That string is also printed in JSON report created by vmaBuildStatsString().

Note
Passing string name to VMA allocation doesn't automatically set it to the Vulkan buffer or image created with it. You must do it manually using an extension like VK_EXT_debug_utils, which is independent of this library.
-Generated by doxygen 1.9.1 +Generated by doxygen 1.9.2
diff --git a/docs/html/annotated.html b/docs/html/annotated.html index 5d50e51..c9a6816 100644 --- a/docs/html/annotated.html +++ b/docs/html/annotated.html @@ -2,8 +2,8 @@ - - + + Vulkan Memory Allocator: Class List @@ -29,21 +29,22 @@ - + +/* @license-end */ + @@ -61,8 +62,7 @@ $(function() {
-
-
Class List
+
Class List
Here are the classes, structs, unions and interfaces with brief descriptions:
@@ -93,7 +93,7 @@ $(function() {
-Generated by doxygen 1.9.1 +Generated by doxygen 1.9.2
diff --git a/docs/html/choosing_memory_type.html b/docs/html/choosing_memory_type.html index 93114b6..541f066 100644 --- a/docs/html/choosing_memory_type.html +++ b/docs/html/choosing_memory_type.html @@ -2,8 +2,8 @@ - - + + Vulkan Memory Allocator: Choosing memory type @@ -29,21 +29,22 @@
- + +/* @license-end */ + -
-
-
Choosing memory type
+
+
Choosing memory type
-

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.

+

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. 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.
  3. 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().
  4. 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.
-

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.

+

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

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;
+
VmaAllocationCreateInfo allocInfo = {};
+
allocInfo.usage = VMA_MEMORY_USAGE_GPU_ONLY;
VkBuffer buffer;
-
VmaAllocation allocation;
-
vmaCreateBuffer(allocator, &bufferInfo, &allocInfo, &buffer, &allocation, nullptr);
-
VmaAllocationCreateInfo
Definition: vk_mem_alloc.h:991
-
VmaAllocationCreateInfo::usage
VmaMemoryUsage usage
Intended usage of memory.
Definition: vk_mem_alloc.h:999
+
VmaAllocation allocation;
+
vmaCreateBuffer(allocator, &bufferInfo, &allocInfo, &buffer, &allocation, nullptr);
+
VmaAllocationCreateInfo
Definition: vk_mem_alloc.h:987
+
VmaAllocationCreateInfo::usage
VmaMemoryUsage usage
Intended usage of memory.
Definition: vk_mem_alloc.h:995
VmaAllocation
Represents single memory allocation.
-
VMA_MEMORY_USAGE_GPU_ONLY
@ VMA_MEMORY_USAGE_GPU_ONLY
Definition: vk_mem_alloc.h:833
+
VMA_MEMORY_USAGE_GPU_ONLY
@ VMA_MEMORY_USAGE_GPU_ONLY
Definition: vk_mem_alloc.h:829
vmaCreateBuffer
VkResult vmaCreateBuffer(VmaAllocator allocator, const VkBufferCreateInfo *pBufferCreateInfo, const VmaAllocationCreateInfo *pAllocationCreateInfo, VkBuffer *pBuffer, VmaAllocation *pAllocation, VmaAllocationInfo *pAllocationInfo)

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

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;
VkBuffer buffer;
-
VmaAllocation allocation;
-
vmaCreateBuffer(allocator, &bufferInfo, &allocInfo, &buffer, &allocation, nullptr);
-
VmaAllocationCreateInfo::preferredFlags
VkMemoryPropertyFlags preferredFlags
Flags that preferably should be set in a memory type chosen for an allocation.
Definition: vk_mem_alloc.h:1009
-
VmaAllocationCreateInfo::requiredFlags
VkMemoryPropertyFlags requiredFlags
Flags that must be set in a Memory Type chosen for an allocation.
Definition: vk_mem_alloc.h:1004
-
VmaAllocationCreateInfo::flags
VmaAllocationCreateFlags flags
Use VmaAllocationCreateFlagBits enum.
Definition: vk_mem_alloc.h:993
-
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:910
-

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.

+
VmaAllocation allocation;
+
vmaCreateBuffer(allocator, &bufferInfo, &allocInfo, &buffer, &allocation, nullptr);
+
VmaAllocationCreateInfo::preferredFlags
VkMemoryPropertyFlags preferredFlags
Flags that preferably should be set in a memory type chosen for an allocation.
Definition: vk_mem_alloc.h:1005
+
VmaAllocationCreateInfo::requiredFlags
VkMemoryPropertyFlags requiredFlags
Flags that must be set in a Memory Type chosen for an allocation.
Definition: vk_mem_alloc.h:1000
+
VmaAllocationCreateInfo::flags
VmaAllocationCreateFlags flags
Use VmaAllocationCreateFlagBits enum.
Definition: vk_mem_alloc.h:989
+
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:906
+

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.

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.

-

Please note that this member is NOT just a memory type index. Still you can use it to choose just one, specific memory type. For example, if you already determined that your buffer should be created in memory type 2, use following code:

+

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.

+

Please note that this member is NOT just a memory type index. Still you can use it to choose just one, specific memory type. For example, if you already determined that your buffer should be created in memory type 2, use following code:

uint32_t memoryTypeIndex = 2;
-
VmaAllocationCreateInfo allocInfo = {};
-
allocInfo.memoryTypeBits = 1u << memoryTypeIndex;
+
VmaAllocationCreateInfo allocInfo = {};
+
allocInfo.memoryTypeBits = 1u << memoryTypeIndex;
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:1017
+
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:1013

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.

+

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.

Dedicated allocations

-

Memory for allocations is reserved out of larger block of VkDeviceMemory allocated from Vulkan internally. That is the main feature of this whole library. You can still request a separate memory block to be created for an allocation, just like you would do in a trivial solution without using any allocator. In that case, a buffer or image is always bound to that memory at offset 0. This is called a "dedicated allocation". You can explicitly request it by using flag VMA_ALLOCATION_CREATE_DEDICATED_MEMORY_BIT. The library can also internally decide to use dedicated allocation in some cases, e.g.:

+

Memory for allocations is reserved out of larger block of VkDeviceMemory allocated from Vulkan internally. That is the main feature of this whole library. You can still request a separate memory block to be created for an allocation, just like you would do in a trivial solution without using any allocator. In that case, a buffer or image is always bound to that memory at offset 0. This is called a "dedicated allocation". You can explicitly request it by using flag VMA_ALLOCATION_CREATE_DEDICATED_MEMORY_BIT. The library can also internally decide to use dedicated allocation in some cases, e.g.:

  • When the size of the allocation is large.
  • When VK_KHR_dedicated_allocation extension is enabled and it reports that dedicated allocation is required or recommended for the resource.
    • @@ -143,7 +143,7 @@ Dedicated allocations
-Generated by doxygen 1.9.1 +Generated by doxygen 1.9.2
diff --git a/docs/html/classes.html b/docs/html/classes.html index e63f3fa..779fdd4 100644 --- a/docs/html/classes.html +++ b/docs/html/classes.html @@ -2,8 +2,8 @@ - - + + Vulkan Memory Allocator: Class Index @@ -29,21 +29,22 @@
- + +/* @license-end */ +
@@ -61,20 +62,19 @@ $(function() {
-
-
Class Index
+
Class Index
V
-
V
+
V
VmaAllocation
VmaAllocationCreateInfo
VmaAllocationInfo
VmaAllocator
VmaAllocatorCreateInfo
VmaAllocatorInfo
VmaBudget
VmaDefragmentationContext
VmaDefragmentationInfo
VmaDefragmentationInfo2
VmaDefragmentationPassInfo
VmaDefragmentationPassMoveInfo
VmaDefragmentationStats
VmaDeviceMemoryCallbacks
VmaPool
VmaPoolCreateInfo
VmaPoolStats
VmaRecordSettings
VmaStatInfo
VmaStats
VmaVulkanFunctions
-Generated by doxygen 1.9.1 +Generated by doxygen 1.9.2
diff --git a/docs/html/configuration.html b/docs/html/configuration.html index 555858a..fe03f45 100644 --- a/docs/html/configuration.html +++ b/docs/html/configuration.html @@ -2,8 +2,8 @@ - - + + Vulkan Memory Allocator: Configuration @@ -29,21 +29,22 @@
- + +/* @license-end */ +
-
-
-
Configuration
+
+
Configuration
-

Please check "CONFIGURATION SECTION" in the code to find macros that you can define before each include of this file or change directly in this file to provide your own implementation of basic facilities like assert, min() and max() functions, mutex, atomic etc. The library uses its own implementation of containers by default, but you can switch to using STL containers instead.

-

For example, define VMA_ASSERT(expr) before including the library to provide custom implementation of the assertion, compatible with your project. By default it is defined to standard C assert(expr) in _DEBUG configuration and empty otherwise.

+

Please check "CONFIGURATION SECTION" in the code to find macros that you can define before each include of this file or change directly in this file to provide your own implementation of basic facilities like assert, min() and max() functions, mutex, atomic etc. The library uses its own implementation of containers by default, but you can switch to using STL containers instead.

+

For example, define VMA_ASSERT(expr) before including the library to provide custom implementation of the assertion, compatible with your project. By default it is defined to standard C assert(expr) in _DEBUG configuration and empty otherwise.

Pointers to Vulkan functions

-

There are multiple ways to import pointers to Vulkan functions in the library. In the simplest case you don't need to do anything. If the compilation or linking of your program or the initialization of the VmaAllocator doesn't work for you, you can try to reconfigure it.

-

First, the allocator tries to fetch pointers to Vulkan functions linked statically, like this:

+

There are multiple ways to import pointers to Vulkan functions in the library. In the simplest case you don't need to do anything. If the compilation or linking of your program or the initialization of the VmaAllocator doesn't work for you, you can try to reconfigure it.

+

First, the allocator tries to fetch pointers to Vulkan functions linked statically, like this:

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.

-

Finally, all the function pointers required by the library (considering selected Vulkan version and enabled extensions) are checked with VMA_ASSERT if they are not null.

+

If you want to disable this feature, set configuration macro: #define VMA_STATIC_VULKAN_FUNCTIONS 0.

+

Second, you can provide the pointers yourself by setting member VmaAllocatorCreateInfo::pVulkanFunctions. You can fetch them e.g. using functions vkGetInstanceProcAddr and vkGetDeviceProcAddr or by using a helper library like volk.

+

Third, VMA tries to fetch remaining pointers that are still null by calling vkGetInstanceProcAddr and vkGetDeviceProcAddr on its own. If you want to disable this feature, set configuration macro: #define VMA_DYNAMIC_VULKAN_FUNCTIONS 0.

+

Finally, all the function pointers required by the library (considering selected Vulkan version and enabled extensions) are checked with VMA_ASSERT if they are not null.

Custom host memory allocator

-

If you use custom allocator for CPU memory rather than default operator new and delete from C++, you can make this library using your allocator as well by filling optional member VmaAllocatorCreateInfo::pAllocationCallbacks. These functions will be passed to Vulkan, as well as used by the library itself to make any CPU-side allocations.

+

If you use custom allocator for CPU memory rather than default operator new and delete from C++, you can make this library using your allocator as well by filling optional member VmaAllocatorCreateInfo::pAllocationCallbacks. These functions will be passed to Vulkan, as well as used by the library itself to make any CPU-side allocations.

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

+

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.

-

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.

+

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.

-Generated by doxygen 1.9.1 +Generated by doxygen 1.9.2
diff --git a/docs/html/custom_memory_pools.html b/docs/html/custom_memory_pools.html index 1165c9f..3965dc3 100644 --- a/docs/html/custom_memory_pools.html +++ b/docs/html/custom_memory_pools.html @@ -2,8 +2,8 @@ - - + + Vulkan Memory Allocator: Custom memory pools @@ -29,21 +29,22 @@
- + +/* @license-end */ +
-
-
-
Custom memory pools
+
+
Custom memory pools
-

A memory pool contains a number of VkDeviceMemory blocks. The library automatically creates and manages default pool for each memory type available on the device. Default memory pool automatically grows in size. Size of allocated blocks is also variable and managed automatically.

-

You can create custom pool and allocate memory out of it. It can be useful if you want to:

+

A memory pool contains a number of VkDeviceMemory blocks. The library automatically creates and manages default pool for each memory type available on the device. Default memory pool automatically grows in size. Size of allocated blocks is also variable and managed automatically.

+

You can create custom pool and allocate memory out of it. It can be useful if you want to:

  • Keep certain kind of allocations separate from others.
  • Enforce particular, fixed size of Vulkan memory blocks.
    • @@ -78,116 +78,116 @@ $(function() {
  • 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.
-

To use custom memory pools:

+

To use custom memory pools:

  1. Fill VmaPoolCreateInfo structure.
  2. Call vmaCreatePool() to obtain VmaPool handle.
  3. When making an allocation, set VmaAllocationCreateInfo::pool to this handle. You don't need to specify any other parameters of this structure, like usage.
-

Example:

+

Example:

// Create a pool that can have at most 2 blocks, 128 MiB each.
-
VmaPoolCreateInfo poolCreateInfo = {};
-
poolCreateInfo.memoryTypeIndex = ...
+
VmaPoolCreateInfo poolCreateInfo = {};
+
poolCreateInfo.memoryTypeIndex = ...
poolCreateInfo.blockSize = 128ull * 1024 * 1024;
-
poolCreateInfo.maxBlockCount = 2;
+
poolCreateInfo.maxBlockCount = 2;
-
VmaPool pool;
-
vmaCreatePool(allocator, &poolCreateInfo, &pool);
+
VmaPool pool;
+
vmaCreatePool(allocator, &poolCreateInfo, &pool);
// Allocate a buffer out of it.
VkBufferCreateInfo bufCreateInfo = { VK_STRUCTURE_TYPE_BUFFER_CREATE_INFO };
bufCreateInfo.size = 1024;
bufCreateInfo.usage = VK_BUFFER_USAGE_UNIFORM_BUFFER_BIT | VK_BUFFER_USAGE_TRANSFER_DST_BIT;
-
VmaAllocationCreateInfo allocCreateInfo = {};
-
allocCreateInfo.pool = pool;
+
VmaAllocationCreateInfo allocCreateInfo = {};
+
allocCreateInfo.pool = pool;
VkBuffer buf;
-
VmaAllocation alloc;
-
VmaAllocationInfo allocInfo;
-
vmaCreateBuffer(allocator, &bufCreateInfo, &allocCreateInfo, &buf, &alloc, &allocInfo);
-
VmaAllocationCreateInfo
Definition: vk_mem_alloc.h:991
-
VmaAllocationCreateInfo::pool
VmaPool pool
Pool that this allocation should be created in.
Definition: vk_mem_alloc.h:1023
+
VmaAllocation alloc;
+
VmaAllocationInfo allocInfo;
+
vmaCreateBuffer(allocator, &bufCreateInfo, &allocCreateInfo, &buf, &alloc, &allocInfo);
+
VmaAllocationCreateInfo
Definition: vk_mem_alloc.h:987
+
VmaAllocationCreateInfo::pool
VmaPool pool
Pool that this allocation should be created in.
Definition: vk_mem_alloc.h:1019
VmaAllocation
Represents single memory allocation.
-
VmaAllocationInfo
Parameters of VmaAllocation objects, that can be retrieved using function vmaGetAllocationInfo().
Definition: vk_mem_alloc.h:1358
-
VmaPoolCreateInfo
Describes parameter of created VmaPool.
Definition: vk_mem_alloc.h:1159
-
VmaPoolCreateInfo::memoryTypeIndex
uint32_t memoryTypeIndex
Vulkan memory type index to allocate this pool from.
Definition: vk_mem_alloc.h:1162
-
VmaPoolCreateInfo::maxBlockCount
size_t maxBlockCount
Maximum number of blocks that can be allocated in this pool. Optional.
Definition: vk_mem_alloc.h:1187
+
VmaAllocationInfo
Parameters of VmaAllocation objects, that can be retrieved using function vmaGetAllocationInfo().
Definition: vk_mem_alloc.h:1354
+
VmaPoolCreateInfo
Describes parameter of created VmaPool.
Definition: vk_mem_alloc.h:1155
+
VmaPoolCreateInfo::memoryTypeIndex
uint32_t memoryTypeIndex
Vulkan memory type index to allocate this pool from.
Definition: vk_mem_alloc.h:1158
+
VmaPoolCreateInfo::maxBlockCount
size_t maxBlockCount
Maximum number of blocks that can be allocated in this pool. Optional.
Definition: vk_mem_alloc.h:1183
VmaPool
Represents custom memory pool.
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)
-

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

-
vmaDestroyBuffer(allocator, buf, alloc);
-
vmaDestroyPool(allocator, pool);
+

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

+
vmaDestroyBuffer(allocator, buf, alloc);
+
vmaDestroyPool(allocator, pool);
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.

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.

+

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.
-
VmaAllocationCreateInfo allocCreateInfo = {};
-
allocCreateInfo.usage = VMA_MEMORY_USAGE_GPU_ONLY; // Change if needed.
+
VmaAllocationCreateInfo allocCreateInfo = {};
+
allocCreateInfo.usage = VMA_MEMORY_USAGE_GPU_ONLY; // Change if needed.
uint32_t memTypeIndex;
-
vmaFindMemoryTypeIndexForBufferInfo(allocator, &exampleBufCreateInfo, &allocCreateInfo, &memTypeIndex);
+
vmaFindMemoryTypeIndexForBufferInfo(allocator, &exampleBufCreateInfo, &allocCreateInfo, &memTypeIndex);
-
VmaPoolCreateInfo poolCreateInfo = {};
-
poolCreateInfo.memoryTypeIndex = memTypeIndex;
+
VmaPoolCreateInfo poolCreateInfo = {};
+
poolCreateInfo.memoryTypeIndex = memTypeIndex;
// ...
-
VmaAllocationCreateInfo::usage
VmaMemoryUsage usage
Intended usage of memory.
Definition: vk_mem_alloc.h:999
-
VMA_MEMORY_USAGE_GPU_ONLY
@ VMA_MEMORY_USAGE_GPU_ONLY
Definition: vk_mem_alloc.h:833
+
VmaAllocationCreateInfo::usage
VmaMemoryUsage usage
Intended usage of memory.
Definition: vk_mem_alloc.h:995
+
VMA_MEMORY_USAGE_GPU_ONLY
@ VMA_MEMORY_USAGE_GPU_ONLY
Definition: vk_mem_alloc.h:829
vmaFindMemoryTypeIndexForBufferInfo
VkResult vmaFindMemoryTypeIndexForBufferInfo(VmaAllocator allocator, const VkBufferCreateInfo *pBufferCreateInfo, const VmaAllocationCreateInfo *pAllocationCreateInfo, uint32_t *pMemoryTypeIndex)
Helps to find memoryTypeIndex, given VkBufferCreateInfo and VmaAllocationCreateInfo.
-

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

+

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.
  • VmaAllocationCreateInfo: You don't need to pass same parameters. Fill only pool member. Other members are ignored anyway.

Linear allocation algorithm

-

Each Vulkan memory block managed by this library has accompanying metadata that keeps track of used and unused regions. By default, the metadata structure and algorithm tries to find best place for new allocations among free regions to optimize memory usage. This way you can allocate and free objects in any order.

-

Default allocation algorithm

-

Sometimes there is a need to use simpler, linear allocation algorithm. You can create custom pool that uses such algorithm by adding flag VMA_POOL_CREATE_LINEAR_ALGORITHM_BIT to VmaPoolCreateInfo::flags while creating VmaPool object. Then an alternative metadata management is used. It always creates new allocations after last one and doesn't reuse free regions after allocations freed in the middle. It results in better allocation performance and less memory consumed by metadata.

-

Linear allocation algorithm

-

With this one flag, you can create a custom pool that can be used in many ways: free-at-once, stack, double stack, and ring buffer. See below for details.

+

Each Vulkan memory block managed by this library has accompanying metadata that keeps track of used and unused regions. By default, the metadata structure and algorithm tries to find best place for new allocations among free regions to optimize memory usage. This way you can allocate and free objects in any order.

+

Default allocation algorithm

+

Sometimes there is a need to use simpler, linear allocation algorithm. You can create custom pool that uses such algorithm by adding flag VMA_POOL_CREATE_LINEAR_ALGORITHM_BIT to VmaPoolCreateInfo::flags while creating VmaPool object. Then an alternative metadata management is used. It always creates new allocations after last one and doesn't reuse free regions after allocations freed in the middle. It results in better allocation performance and less memory consumed by metadata.

+

Linear allocation algorithm

+

With this one flag, you can create a custom pool that can be used in many ways: free-at-once, stack, double stack, and ring buffer. See below for details.

Free-at-once

-

In a pool that uses linear algorithm, you still need to free all the allocations individually, e.g. by using vmaFreeMemory() or vmaDestroyBuffer(). You can free them in any order. New allocations are always made after last one - free space in the middle is not reused. However, when you release all the allocation and the pool becomes empty, allocation starts from the beginning again. This way you can use linear algorithm to speed up creation of allocations that you are going to release all at once.

-

Free-at-once

-

This mode is also available for pools created with VmaPoolCreateInfo::maxBlockCount value that allows multiple memory blocks.

+

In a pool that uses linear algorithm, you still need to free all the allocations individually, e.g. by using vmaFreeMemory() or vmaDestroyBuffer(). You can free them in any order. New allocations are always made after last one - free space in the middle is not reused. However, when you release all the allocation and the pool becomes empty, allocation starts from the beginning again. This way you can use linear algorithm to speed up creation of allocations that you are going to release all at once.

+

Free-at-once

+

This mode is also available for pools created with VmaPoolCreateInfo::maxBlockCount value that allows multiple memory blocks.

Stack

-

When you free an allocation that was created last, its space can be reused. Thanks to this, if you always release allocations in the order opposite to their creation (LIFO - Last In First Out), you can achieve behavior of a stack.

-

Stack

-

This mode is also available for pools created with VmaPoolCreateInfo::maxBlockCount value that allows multiple memory blocks.

+

When you free an allocation that was created last, its space can be reused. Thanks to this, if you always release allocations in the order opposite to their creation (LIFO - Last In First Out), you can achieve behavior of a stack.

+

Stack

+

This mode is also available for pools created with VmaPoolCreateInfo::maxBlockCount value that allows multiple memory blocks.

Double stack

-

The space reserved by a custom pool with linear algorithm may be used by two stacks:

+

The space reserved by a custom pool with linear algorithm may be used by two stacks:

  • First, default one, growing up from offset 0.
  • Second, "upper" one, growing down from the end towards lower offsets.
-

To make allocation from upper stack, add flag VMA_ALLOCATION_CREATE_UPPER_ADDRESS_BIT to VmaAllocationCreateInfo::flags.

-

Double stack

-

Double stack is available only in pools with one memory block - VmaPoolCreateInfo::maxBlockCount must be 1. Otherwise behavior is undefined.

-

When the two stacks' ends meet so there is not enough space between them for a new allocation, such allocation fails with usual VK_ERROR_OUT_OF_DEVICE_MEMORY error.

+

To make allocation from upper stack, add flag VMA_ALLOCATION_CREATE_UPPER_ADDRESS_BIT to VmaAllocationCreateInfo::flags.

+

Double stack

+

Double stack is available only in pools with one memory block - VmaPoolCreateInfo::maxBlockCount must be 1. Otherwise behavior is undefined.

+

When the two stacks' ends meet so there is not enough space between them for a new allocation, such allocation fails with usual VK_ERROR_OUT_OF_DEVICE_MEMORY error.

Ring buffer

-

When you free some allocations from the beginning and there is not enough free space for a new one at the end of a pool, allocator's "cursor" wraps around to the beginning and starts allocation there. Thanks to this, if you always release allocations in the same order as you created them (FIFO - First In First Out), you can achieve behavior of a ring buffer / queue.

-

Ring buffer

-

Pools with linear algorithm support lost allocations when used as ring buffer. If there is not enough free space for a new allocation, but existing allocations from the front of the queue can become lost, they become lost and the allocation succeeds.

-

Ring buffer with lost allocations

-

Ring buffer is available only in pools with one memory block - VmaPoolCreateInfo::maxBlockCount must be 1. Otherwise behavior is undefined.

+

When you free some allocations from the beginning and there is not enough free space for a new one at the end of a pool, allocator's "cursor" wraps around to the beginning and starts allocation there. Thanks to this, if you always release allocations in the same order as you created them (FIFO - First In First Out), you can achieve behavior of a ring buffer / queue.

+

Ring buffer

+

Pools with linear algorithm support lost allocations when used as ring buffer. If there is not enough free space for a new allocation, but existing allocations from the front of the queue can become lost, they become lost and the allocation succeeds.

+

Ring buffer with lost allocations

+

Ring buffer is available only in pools with one memory block - VmaPoolCreateInfo::maxBlockCount must be 1. Otherwise behavior is undefined.

Buddy allocation algorithm

-

There is another allocation algorithm that can be used with custom pools, called "buddy". Its internal data structure is based on a tree of blocks, each having size that is a power of two and a half of its parent's size. When you want to allocate memory of certain size, a free node in the tree is located. If it is too large, it is recursively split into two halves (called "buddies"). However, if requested allocation size is not a power of two, the size of a tree node is aligned up to the nearest power of two and the remaining space is wasted. When two buddy nodes become free, they are merged back into one larger node.

-

Buddy allocator

-

The advantage of buddy allocation algorithm over default algorithm is faster allocation and deallocation, as well as smaller external fragmentation. The disadvantage is more wasted space (internal fragmentation).

-

For more information, please read "Buddy memory allocation" on Wikipedia or other sources that describe this concept in general.

-

To use buddy allocation algorithm with a custom pool, add flag VMA_POOL_CREATE_BUDDY_ALGORITHM_BIT to VmaPoolCreateInfo::flags while creating VmaPool object.

-

Several limitations apply to pools that use buddy algorithm:

+

There is another allocation algorithm that can be used with custom pools, called "buddy". Its internal data structure is based on a tree of blocks, each having size that is a power of two and a half of its parent's size. When you want to allocate memory of certain size, a free node in the tree is located. If it is too large, it is recursively split into two halves (called "buddies"). However, if requested allocation size is not a power of two, the size of a tree node is aligned up to the nearest power of two and the remaining space is wasted. When two buddy nodes become free, they are merged back into one larger node.

+

Buddy allocator

+

The advantage of buddy allocation algorithm over default algorithm is faster allocation and deallocation, as well as smaller external fragmentation. The disadvantage is more wasted space (internal fragmentation).

+

For more information, please search the Internet for "Buddy memory allocation" - sources that describe this concept in general.

+

To use buddy allocation algorithm with a custom pool, add flag VMA_POOL_CREATE_BUDDY_ALGORITHM_BIT to VmaPoolCreateInfo::flags while creating VmaPool object.

+

Several limitations apply to pools that use buddy algorithm:

  • It is recommended to use VmaPoolCreateInfo::blockSize that is a power of two. Otherwise, only largest power of two smaller than the size is used for allocations. The remaining space always stays unused.
  • Margins and corruption detection don't work in such pools.
    • @@ -198,7 +198,7 @@ Buddy allocation algorithm
-Generated by doxygen 1.9.1 +Generated by doxygen 1.9.2
diff --git a/docs/html/debugging_memory_usage.html b/docs/html/debugging_memory_usage.html index b66e56f..6c6b739 100644 --- a/docs/html/debugging_memory_usage.html +++ b/docs/html/debugging_memory_usage.html @@ -2,8 +2,8 @@ - - + + Vulkan Memory Allocator: Debugging incorrect memory usage @@ -29,21 +29,22 @@
- + +/* @license-end */ +
-
-
-
Debugging incorrect memory usage
+
+
Debugging incorrect memory usage
-

If you suspect a bug with memory usage, like usage of uninitialized memory or memory being overwritten out of bounds of an allocation, you can use debug features of this library to verify this.

+

If you suspect a bug with memory usage, like usage of uninitialized memory or memory being overwritten out of bounds of an allocation, you can use debug features of this library to verify this.

Memory initialization

-

If you experience a bug with incorrect and nondeterministic data in your program and you suspect uninitialized memory to be used, you can enable automatic memory initialization to verify this. To do it, define macro VMA_DEBUG_INITIALIZE_ALLOCATIONS to 1.

+

If you experience a bug with incorrect and nondeterministic data in your program and you suspect uninitialized memory to be used, you can enable automatic memory initialization to verify this. To do it, define macro VMA_DEBUG_INITIALIZE_ALLOCATIONS to 1.

#define VMA_DEBUG_INITIALIZE_ALLOCATIONS 1
#include "vk_mem_alloc.h"
-

It makes memory of all new allocations initialized to bit pattern 0xDCDCDCDC. Before an allocation is destroyed, its memory is filled with bit pattern 0xEFEFEFEF. Memory is automatically mapped and unmapped if necessary.

-

If you find these values while debugging your program, good chances are that you incorrectly read Vulkan memory that is allocated but not initialized, or already freed, respectively.

-

Memory initialization works only with memory types that are HOST_VISIBLE. It works also with dedicated allocations. It doesn't work with allocations created with VMA_ALLOCATION_CREATE_CAN_BECOME_LOST_BIT flag, as they cannot be mapped.

+

It makes memory of all new allocations initialized to bit pattern 0xDCDCDCDC. Before an allocation is destroyed, its memory is filled with bit pattern 0xEFEFEFEF. Memory is automatically mapped and unmapped if necessary.

+

If you find these values while debugging your program, good chances are that you incorrectly read Vulkan memory that is allocated but not initialized, or already freed, respectively.

+

Memory initialization works only with memory types that are HOST_VISIBLE. It works also with dedicated allocations. It doesn't work with allocations created with VMA_ALLOCATION_CREATE_CAN_BECOME_LOST_BIT flag, as they cannot be mapped.

Margins

-

By default, allocations are laid out in memory blocks next to each other if possible (considering required alignment, bufferImageGranularity, and nonCoherentAtomSize).

-

Allocations without margin

-

Define macro VMA_DEBUG_MARGIN to some non-zero value (e.g. 16) to enforce specified number of bytes as a margin before and after every allocation.

+

By default, allocations are laid out in memory blocks next to each other if possible (considering required alignment, bufferImageGranularity, and nonCoherentAtomSize).

+

Allocations without margin

+

Define macro VMA_DEBUG_MARGIN to some non-zero value (e.g. 16) to enforce specified number of bytes as a margin before and after every allocation.

#define VMA_DEBUG_MARGIN 16
#include "vk_mem_alloc.h"
-

Allocations with margin

-

If your bug goes away after enabling margins, it means it may be caused by memory being overwritten outside of allocation boundaries. It is not 100% certain though. Change in application behavior may also be caused by different order and distribution of allocations across memory blocks after margins are applied.

-

The margin is applied also before first and after last allocation in a block. It may occur only once between two adjacent allocations.

-

Margins work with all types of memory.

-

Margin is applied only to allocations made out of memory blocks and not to dedicated allocations, which have their own memory block of specific size. It is thus not applied to allocations made using VMA_ALLOCATION_CREATE_DEDICATED_MEMORY_BIT flag or those automatically decided to put into dedicated allocations, e.g. due to its large size or recommended by VK_KHR_dedicated_allocation extension. Margins are also not active in custom pools created with VMA_POOL_CREATE_BUDDY_ALGORITHM_BIT flag.

-

Margins appear in JSON dump as part of free space.

-

Note that enabling margins increases memory usage and fragmentation.

+

Allocations with margin

+

If your bug goes away after enabling margins, it means it may be caused by memory being overwritten outside of allocation boundaries. It is not 100% certain though. Change in application behavior may also be caused by different order and distribution of allocations across memory blocks after margins are applied.

+

The margin is applied also before first and after last allocation in a block. It may occur only once between two adjacent allocations.

+

Margins work with all types of memory.

+

Margin is applied only to allocations made out of memory blocks and not to dedicated allocations, which have their own memory block of specific size. It is thus not applied to allocations made using VMA_ALLOCATION_CREATE_DEDICATED_MEMORY_BIT flag or those automatically decided to put into dedicated allocations, e.g. due to its large size or recommended by VK_KHR_dedicated_allocation extension. Margins are also not active in custom pools created with VMA_POOL_CREATE_BUDDY_ALGORITHM_BIT flag.

+

Margins appear in JSON dump as part of free space.

+

Note that enabling margins increases memory usage and fragmentation.

Corruption detection

-

You can additionally define macro VMA_DEBUG_DETECT_CORRUPTION to 1 to enable validation of contents of the margins.

+

You can additionally define macro VMA_DEBUG_DETECT_CORRUPTION to 1 to enable validation of contents of the margins.

#define VMA_DEBUG_MARGIN 16
#define VMA_DEBUG_DETECT_CORRUPTION 1
#include "vk_mem_alloc.h"
-

When this feature is enabled, number of bytes specified as VMA_DEBUG_MARGIN (it must be multiply of 4) before and 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.

+

When this feature is enabled, number of bytes specified as VMA_DEBUG_MARGIN (it must be multiply of 4) before and 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.

-Generated by doxygen 1.9.1 +Generated by doxygen 1.9.2
diff --git a/docs/html/defragmentation.html b/docs/html/defragmentation.html index cfe3ac5..e6d478c 100644 --- a/docs/html/defragmentation.html +++ b/docs/html/defragmentation.html @@ -2,8 +2,8 @@ - - + + Vulkan Memory Allocator: Defragmentation @@ -29,21 +29,22 @@
- + +/* @license-end */ +
-
-
-
Defragmentation
+
+
Defragmentation
-

Interleaved allocations and deallocations of many objects of varying size can cause fragmentation over time, which can lead to a situation where the library is unable to find a continuous range of free memory for a new allocation despite there is enough free space, just scattered across many small free ranges between existing allocations.

-

To mitigate this problem, you can use defragmentation feature: structure VmaDefragmentationInfo2, function vmaDefragmentationBegin(), vmaDefragmentationEnd(). Given set of allocations, this function can move them to compact used memory, ensure more continuous free space and possibly also free some VkDeviceMemory blocks.

-

What the defragmentation does is:

+

Interleaved allocations and deallocations of many objects of varying size can cause fragmentation over time, which can lead to a situation where the library is unable to find a continuous range of free memory for a new allocation despite there is enough free space, just scattered across many small free ranges between existing allocations.

+

To mitigate this problem, you can use defragmentation feature: structure VmaDefragmentationInfo2, function vmaDefragmentationBegin(), vmaDefragmentationEnd(). Given set of allocations, this function can move them to compact used memory, ensure more continuous free space and possibly also free some VkDeviceMemory blocks.

+

What the defragmentation does is:

-

What it doesn't do, so you need to do it yourself:

+

What it doesn't do, so you need to do it yourself:

Defragmenting CPU memory

-

Following example demonstrates how you can run defragmentation on CPU. Only allocations created in memory types that are HOST_VISIBLE can be defragmented. Others are ignored.

-

The way it works is:

+

Following example demonstrates how you can run defragmentation on CPU. Only allocations created in memory types that are HOST_VISIBLE can be defragmented. Others are ignored.

+

The way it works is:

  • It temporarily maps entire memory blocks when necessary.
  • It moves data using memmove() function.
// Given following variables already initialized:
VkDevice device;
-
VmaAllocator allocator;
+
VmaAllocator allocator;
std::vector<VkBuffer> buffers;
std::vector<VmaAllocation> allocations;
@@ -99,16 +99,16 @@ Defragmenting CPU memory
const uint32_t allocCount = (uint32_t)allocations.size();
std::vector<VkBool32> allocationsChanged(allocCount);
-
VmaDefragmentationInfo2 defragInfo = {};
-
defragInfo.allocationCount = allocCount;
-
defragInfo.pAllocations = allocations.data();
-
defragInfo.pAllocationsChanged = allocationsChanged.data();
-
defragInfo.maxCpuBytesToMove = VK_WHOLE_SIZE; // No limit.
-
defragInfo.maxCpuAllocationsToMove = UINT32_MAX; // No limit.
+
VmaDefragmentationInfo2 defragInfo = {};
+
defragInfo.allocationCount = allocCount;
+
defragInfo.pAllocations = allocations.data();
+
defragInfo.pAllocationsChanged = allocationsChanged.data();
+
defragInfo.maxCpuBytesToMove = VK_WHOLE_SIZE; // No limit.
+
defragInfo.maxCpuAllocationsToMove = UINT32_MAX; // No limit.
-
VmaDefragmentationContext defragCtx;
-
vmaDefragmentationBegin(allocator, &defragInfo, nullptr, &defragCtx);
-
vmaDefragmentationEnd(allocator, defragCtx);
+
VmaDefragmentationContext defragCtx;
+
vmaDefragmentationBegin(allocator, &defragInfo, nullptr, &defragCtx);
+
vmaDefragmentationEnd(allocator, defragCtx);
for(uint32_t i = 0; i < allocCount; ++i)
{
@@ -124,37 +124,37 @@ Defragmenting CPU memory
// You can make dummy call to vkGetBufferMemoryRequirements here to silence validation layer warning.
// Bind new buffer to new memory region. Data contained in it is already moved.
-
VmaAllocationInfo allocInfo;
-
vmaGetAllocationInfo(allocator, allocations[i], &allocInfo);
-
vmaBindBufferMemory(allocator, allocations[i], buffers[i]);
+
VmaAllocationInfo allocInfo;
+
vmaGetAllocationInfo(allocator, allocations[i], &allocInfo);
+
vmaBindBufferMemory(allocator, allocations[i], buffers[i]);
}
}
-
VmaAllocationInfo
Parameters of VmaAllocation objects, that can be retrieved using function vmaGetAllocationInfo().
Definition: vk_mem_alloc.h:1358
+
VmaAllocationInfo
Parameters of VmaAllocation objects, that can be retrieved using function vmaGetAllocationInfo().
Definition: vk_mem_alloc.h:1354
VmaAllocator
Represents main object of this library initialized.
VmaDefragmentationContext
Represents Opaque object that represents started defragmentation process.
-
VmaDefragmentationInfo2
Parameters for defragmentation.
Definition: vk_mem_alloc.h:1764
-
VmaDefragmentationInfo2::allocationCount
uint32_t allocationCount
Number of allocations in pAllocations array.
Definition: vk_mem_alloc.h:1770
-
VmaDefragmentationInfo2::pAllocationsChanged
VkBool32 * pAllocationsChanged
Optional, output. Pointer to array that will be filled with information whether the allocation at cer...
Definition: vk_mem_alloc.h:1785
-
VmaDefragmentationInfo2::maxCpuAllocationsToMove
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:1814
-
VmaDefragmentationInfo2::pAllocations
const VmaAllocation * pAllocations
Pointer to array of allocations that can be defragmented.
Definition: vk_mem_alloc.h:1779
-
VmaDefragmentationInfo2::maxCpuBytesToMove
VkDeviceSize maxCpuBytesToMove
Maximum total numbers of bytes that can be copied while moving allocations to different places using ...
Definition: vk_mem_alloc.h:1809
+
VmaDefragmentationInfo2
Parameters for defragmentation.
Definition: vk_mem_alloc.h:1760
+
VmaDefragmentationInfo2::allocationCount
uint32_t allocationCount
Number of allocations in pAllocations array.
Definition: vk_mem_alloc.h:1766
+
VmaDefragmentationInfo2::pAllocationsChanged
VkBool32 * pAllocationsChanged
Optional, output. Pointer to array that will be filled with information whether the allocation at cer...
Definition: vk_mem_alloc.h:1781
+
VmaDefragmentationInfo2::maxCpuAllocationsToMove
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:1810
+
VmaDefragmentationInfo2::pAllocations
const VmaAllocation * pAllocations
Pointer to array of allocations that can be defragmented.
Definition: vk_mem_alloc.h:1775
+
VmaDefragmentationInfo2::maxCpuBytesToMove
VkDeviceSize maxCpuBytesToMove
Maximum total numbers of bytes that can be copied while moving allocations to different places using ...
Definition: vk_mem_alloc.h:1805
vmaDefragmentationBegin
VkResult vmaDefragmentationBegin(VmaAllocator allocator, const VmaDefragmentationInfo2 *pInfo, VmaDefragmentationStats *pStats, VmaDefragmentationContext *pContext)
Begins defragmentation process.
vmaBindBufferMemory
VkResult vmaBindBufferMemory(VmaAllocator allocator, VmaAllocation allocation, VkBuffer buffer)
Binds buffer to allocation.
vmaGetAllocationInfo
void vmaGetAllocationInfo(VmaAllocator allocator, VmaAllocation allocation, VmaAllocationInfo *pAllocationInfo)
Returns current information about specified allocation and atomically marks it as used in current fra...
vmaDefragmentationEnd
VkResult vmaDefragmentationEnd(VmaAllocator allocator, VmaDefragmentationContext context)
Ends defragmentation process.
-

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.

+

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.

Defragmenting GPU memory

-

It is also possible to defragment allocations created in memory types that are not HOST_VISIBLE. To do that, you need to pass a command buffer that meets requirements as described in VmaDefragmentationInfo2::commandBuffer. The way it works is:

+

It is also possible to defragment allocations created in memory types that are not HOST_VISIBLE. To do that, you need to pass a command buffer that meets requirements as described in VmaDefragmentationInfo2::commandBuffer. The way it works is:

  • It creates temporary buffers and binds them to entire memory blocks when necessary.
  • It issues vkCmdCopyBuffer() to passed command buffer.
-

Example:

+

Example:

// Given following variables already initialized:
VkDevice device;
-
VmaAllocator allocator;
+
VmaAllocator allocator;
VkCommandBuffer commandBuffer;
std::vector<VkBuffer> buffers;
std::vector<VmaAllocation> allocations;
@@ -166,23 +166,23 @@ Defragmenting GPU memory
VkCommandBufferBeginInfo cmdBufBeginInfo = ...;
vkBeginCommandBuffer(commandBuffer, &cmdBufBeginInfo);
-
VmaDefragmentationInfo2 defragInfo = {};
-
defragInfo.allocationCount = allocCount;
-
defragInfo.pAllocations = allocations.data();
-
defragInfo.pAllocationsChanged = allocationsChanged.data();
-
defragInfo.maxGpuBytesToMove = VK_WHOLE_SIZE; // Notice it is "GPU" this time.
-
defragInfo.maxGpuAllocationsToMove = UINT32_MAX; // Notice it is "GPU" this time.
-
defragInfo.commandBuffer = commandBuffer;
+
VmaDefragmentationInfo2 defragInfo = {};
+
defragInfo.allocationCount = allocCount;
+
defragInfo.pAllocations = allocations.data();
+
defragInfo.pAllocationsChanged = allocationsChanged.data();
+
defragInfo.maxGpuBytesToMove = VK_WHOLE_SIZE; // Notice it is "GPU" this time.
+
defragInfo.maxGpuAllocationsToMove = UINT32_MAX; // Notice it is "GPU" this time.
+
defragInfo.commandBuffer = commandBuffer;
-
VmaDefragmentationContext defragCtx;
-
vmaDefragmentationBegin(allocator, &defragInfo, nullptr, &defragCtx);
+
VmaDefragmentationContext defragCtx;
+
vmaDefragmentationBegin(allocator, &defragInfo, nullptr, &defragCtx);
vkEndCommandBuffer(commandBuffer);
// Submit commandBuffer.
// Wait for a fence that ensures commandBuffer execution finished.
-
vmaDefragmentationEnd(allocator, defragCtx);
+
vmaDefragmentationEnd(allocator, defragCtx);
for(uint32_t i = 0; i < allocCount; ++i)
{
@@ -198,30 +198,30 @@ Defragmenting GPU memory
// You can make dummy call to vkGetBufferMemoryRequirements here to silence validation layer warning.
// Bind new buffer to new memory region. Data contained in it is already moved.
-
VmaAllocationInfo allocInfo;
-
vmaGetAllocationInfo(allocator, allocations[i], &allocInfo);
-
vmaBindBufferMemory(allocator, allocations[i], buffers[i]);
+
VmaAllocationInfo allocInfo;
+
vmaGetAllocationInfo(allocator, allocations[i], &allocInfo);
+
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:1824
-
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:1819
-
VmaDefragmentationInfo2::commandBuffer
VkCommandBuffer commandBuffer
Optional. Command buffer where GPU copy commands will be posted.
Definition: vk_mem_alloc.h:1833
-

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

+
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:1820
+
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:1815
+
VmaDefragmentationInfo2::commandBuffer
VkCommandBuffer commandBuffer
Optional. Command buffer where GPU copy commands will be posted.
Definition: vk_mem_alloc.h:1829
+

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

Additional notes

-

It is only legal to defragment allocations bound to:

+

It is only legal to defragment allocations bound to:

  • buffers
  • images created with VK_IMAGE_CREATE_ALIAS_BIT, VK_IMAGE_TILING_LINEAR, and being currently in VK_IMAGE_LAYOUT_GENERAL or VK_IMAGE_LAYOUT_PREINITIALIZED.
-

Defragmentation of images created with VK_IMAGE_TILING_OPTIMAL or in any other layout may give undefined results.

-

If you defragment allocations bound to images, new images to be bound to new memory region after defragmentation should be created with VK_IMAGE_LAYOUT_PREINITIALIZED and then transitioned to their original layout from before defragmentation if needed using an image memory barrier.

-

While using defragmentation, you may experience validation layer warnings, which you just need to ignore. See Validation layer warnings.

-

Please don't expect memory to be fully compacted after defragmentation. Algorithms inside are based on some heuristics that try to maximize number of Vulkan memory blocks to make totally empty to release them, as well as to maximize continuous empty space inside remaining blocks, while minimizing the number and size of allocations that need to be moved. Some fragmentation may still remain - this is normal.

+

Defragmentation of images created with VK_IMAGE_TILING_OPTIMAL or in any other layout may give undefined results.

+

If you defragment allocations bound to images, new images to be bound to new memory region after defragmentation should be created with VK_IMAGE_LAYOUT_PREINITIALIZED and then transitioned to their original layout from before defragmentation if needed using an image memory barrier.

+

While using defragmentation, you may experience validation layer warnings, which you just need to ignore. See Validation layer warnings.

+

Please don't expect memory to be fully compacted after defragmentation. Algorithms inside are based on some heuristics that try to maximize number of Vulkan memory blocks to make totally empty to release them, as well as to maximize continuous empty space inside remaining blocks, while minimizing the number and size of allocations that need to be moved. Some fragmentation may still remain - this is normal.

Writing custom defragmentation algorithm

-

If you want to implement your own, custom defragmentation algorithm, there is infrastructure prepared for that, but it is not exposed through the library API - you need to hack its source code. Here are steps needed to do this:

+

If you want to implement your own, custom defragmentation algorithm, there is infrastructure prepared for that, but it is not exposed through the library API - you need to hack its source code. Here are steps needed to do this:

  1. Main thing you need to do is to define your own class derived from base abstract class VmaDefragmentationAlgorithm and implement your version of its pure virtual methods. See definition and comments of this class for details.
  2. Your code needs to interact with device memory block metadata. If you need more access to its data than it is provided by its public interface, declare your new class as a friend class e.g. in class VmaBlockMetadata_Generic.
    3. @@ -232,7 +232,7 @@ Writing custom defragmentation algorithm
-Generated by doxygen 1.9.1 +Generated by doxygen 1.9.2
diff --git a/docs/html/deprecated.html b/docs/html/deprecated.html index 033bb68..0d266db 100644 --- a/docs/html/deprecated.html +++ b/docs/html/deprecated.html @@ -2,8 +2,8 @@ - - + + Vulkan Memory Allocator: Deprecated List @@ -29,21 +29,22 @@
- + +/* @license-end */ +
-
-
-
Deprecated List
+
+
Deprecated List
@@ -75,7 +75,7 @@ $(function() {
-Generated by doxygen 1.9.1 +Generated by doxygen 1.9.2
diff --git a/docs/html/dir_d44c64559bbebec7f509842c48db8b23.html b/docs/html/dir_d44c64559bbebec7f509842c48db8b23.html index b45f55f..db98dc8 100644 --- a/docs/html/dir_d44c64559bbebec7f509842c48db8b23.html +++ b/docs/html/dir_d44c64559bbebec7f509842c48db8b23.html @@ -2,10 +2,10 @@ - - + + -Vulkan Memory Allocator: include Directory Reference +Vulkan Memory Allocator: D:/PROJECTS/Vulkan Memory Allocator/REPO/include Directory Reference @@ -29,21 +29,22 @@
- + +/* @license-end */ +
-
-
include Directory Reference
+
include Directory Reference
- - +

+

Files

file  vk_mem_alloc.h
file  vk_mem_alloc.h
 
-Generated by doxygen 1.9.1 +Generated by doxygen 1.9.2
diff --git a/docs/html/doxygen.css b/docs/html/doxygen.css index ffbff02..8e9cca3 100644 --- a/docs/html/doxygen.css +++ b/docs/html/doxygen.css @@ -1,4 +1,4 @@ -/* The standard CSS for doxygen 1.9.1 */ +/* The standard CSS for doxygen 1.9.2 */ body, table, div, p, dl { font: 400 14px/22px Roboto,sans-serif; @@ -228,6 +228,33 @@ a.codeRef, a.codeRef:visited, a.lineRef, a.lineRef:visited { color: #4665A2; } +a.code.hl_class { /* style for links to class names in code snippets */ } +a.code.hl_struct { /* style for links to struct names in code snippets */ } +a.code.hl_union { /* style for links to union names in code snippets */ } +a.code.hl_interface { /* style for links to interface names in code snippets */ } +a.code.hl_protocol { /* style for links to protocol names in code snippets */ } +a.code.hl_category { /* style for links to category names in code snippets */ } +a.code.hl_exception { /* style for links to exception names in code snippets */ } +a.code.hl_service { /* style for links to service names in code snippets */ } +a.code.hl_singleton { /* style for links to singleton names in code snippets */ } +a.code.hl_concept { /* style for links to concept names in code snippets */ } +a.code.hl_namespace { /* style for links to namespace names in code snippets */ } +a.code.hl_package { /* style for links to package names in code snippets */ } +a.code.hl_define { /* style for links to macro names in code snippets */ } +a.code.hl_function { /* style for links to function names in code snippets */ } +a.code.hl_variable { /* style for links to variable names in code snippets */ } +a.code.hl_typedef { /* style for links to typedef names in code snippets */ } +a.code.hl_enumvalue { /* style for links to enum value names in code snippets */ } +a.code.hl_enumeration { /* style for links to enumeration names in code snippets */ } +a.code.hl_signal { /* style for links to Qt signal names in code snippets */ } +a.code.hl_slot { /* style for links to Qt slot names in code snippets */ } +a.code.hl_friend { /* style for links to friend names in code snippets */ } +a.code.hl_dcop { /* style for links to KDE3 DCOP names in code snippets */ } +a.code.hl_property { /* style for links to property names in code snippets */ } +a.code.hl_event { /* style for links to event names in code snippets */ } +a.code.hl_sequence { /* style for links to sequence names in code snippets */ } +a.code.hl_dictionary { /* style for links to dictionary names in code snippets */ } + /* @end */ dl.el { @@ -313,6 +340,7 @@ div.line.glow { span.lineno { padding-right: 4px; + margin-right: 9px; text-align: right; border-right: 2px solid #0F0; background-color: #E8E8E8; @@ -439,6 +467,12 @@ img.footer { vertical-align: middle; } +.compoundTemplParams { + color: #4665A2; + font-size: 80%; + line-height: 120%; +} + /* @group Code Colorization */ span.keyword { @@ -1341,14 +1375,14 @@ dl.section dd { #projectname { - font: 300% Tahoma, Arial,sans-serif; + font: 200% Tahoma, Arial,sans-serif; margin: 0px; padding: 2px 0px; } #projectbrief { - font: 120% Tahoma, Arial,sans-serif; + font: 90% Tahoma, Arial,sans-serif; margin: 0px; padding: 0px; } diff --git a/docs/html/enabling_buffer_device_address.html b/docs/html/enabling_buffer_device_address.html index 0ac8009..e8cead4 100644 --- a/docs/html/enabling_buffer_device_address.html +++ b/docs/html/enabling_buffer_device_address.html @@ -2,8 +2,8 @@ - - + + Vulkan Memory Allocator: Enabling buffer device address @@ -29,21 +29,22 @@
- + +/* @license-end */ +
-
-
-
Enabling buffer device address
+
+
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.

-

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

+

Device extension VK_KHR_buffer_device_address allow to fetch raw GPU pointer to a buffer and pass it for usage in a shader code. It is promoted to core Vulkan 1.2.

+

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

Initialization

-

1) (For Vulkan version < 1.2) Call vkEnumerateDeviceExtensionProperties for the physical device. Check if the extension is supported - if returned array of VkExtensionProperties contains "VK_KHR_buffer_device_address".

-

2) Call vkGetPhysicalDeviceFeatures2 for the physical device instead of old vkGetPhysicalDeviceFeatures. Attach additional structure VkPhysicalDeviceBufferDeviceAddressFeatures* to VkPhysicalDeviceFeatures2::pNext to be returned. Check if the device feature is really supported - check if VkPhysicalDeviceBufferDeviceAddressFeatures::bufferDeviceAddress is true.

-

3) (For Vulkan version < 1.2) While creating device with vkCreateDevice, enable this extension - add "VK_KHR_buffer_device_address" to the list passed as VkDeviceCreateInfo::ppEnabledExtensionNames.

-

4) While creating the device, also don't set VkDeviceCreateInfo::pEnabledFeatures. Fill in VkPhysicalDeviceFeatures2 structure instead and pass it as VkDeviceCreateInfo::pNext. Enable this device feature - attach additional structure VkPhysicalDeviceBufferDeviceAddressFeatures* to VkPhysicalDeviceFeatures2::pNext and set its member bufferDeviceAddress to VK_TRUE.

-

5) While creating VmaAllocator with vmaCreateAllocator() inform VMA that you have enabled this feature - add VMA_ALLOCATOR_CREATE_BUFFER_DEVICE_ADDRESS_BIT to VmaAllocatorCreateInfo::flags.

+

1) (For Vulkan version < 1.2) Call vkEnumerateDeviceExtensionProperties for the physical device. Check if the extension is supported - if returned array of VkExtensionProperties contains "VK_KHR_buffer_device_address".

+

2) Call vkGetPhysicalDeviceFeatures2 for the physical device instead of old vkGetPhysicalDeviceFeatures. Attach additional structure VkPhysicalDeviceBufferDeviceAddressFeatures* to VkPhysicalDeviceFeatures2::pNext to be returned. Check if the device feature is really supported - check if VkPhysicalDeviceBufferDeviceAddressFeatures::bufferDeviceAddress is true.

+

3) (For Vulkan version < 1.2) While creating device with vkCreateDevice, enable this extension - add "VK_KHR_buffer_device_address" to the list passed as VkDeviceCreateInfo::ppEnabledExtensionNames.

+

4) While creating the device, also don't set VkDeviceCreateInfo::pEnabledFeatures. Fill in VkPhysicalDeviceFeatures2 structure instead and pass it as VkDeviceCreateInfo::pNext. Enable this device feature - attach additional structure VkPhysicalDeviceBufferDeviceAddressFeatures* to VkPhysicalDeviceFeatures2::pNext and set its member bufferDeviceAddress to VK_TRUE.

+

5) While creating VmaAllocator with vmaCreateAllocator() inform VMA that you have enabled this feature - add VMA_ALLOCATOR_CREATE_BUFFER_DEVICE_ADDRESS_BIT to VmaAllocatorCreateInfo::flags.

Usage

-

After following steps described above, you can create buffers with VK_BUFFER_USAGE_SHADER_DEVICE_ADDRESS_BIT* using VMA. The library automatically adds VK_MEMORY_ALLOCATE_DEVICE_ADDRESS_BIT* to allocated memory blocks wherever it might be needed.

-

Please note that the library supports only VK_BUFFER_USAGE_SHADER_DEVICE_ADDRESS_BIT*. The second part of this functionality related to "capture and replay" is not supported, as it is intended for usage in debugging tools like RenderDoc, not in everyday Vulkan usage.

+

After following steps described above, you can create buffers with VK_BUFFER_USAGE_SHADER_DEVICE_ADDRESS_BIT* using VMA. The library automatically adds VK_MEMORY_ALLOCATE_DEVICE_ADDRESS_BIT* to allocated memory blocks wherever it might be needed.

+

Please note that the library supports only VK_BUFFER_USAGE_SHADER_DEVICE_ADDRESS_BIT*. The second part of this functionality related to "capture and replay" is not supported, as it is intended for usage in debugging tools like RenderDoc, not in everyday Vulkan usage.

More information

-

To learn more about this extension, see VK_KHR_buffer_device_address in Vulkan specification

-

Example use of this extension can be found in the code of the sample and test suite accompanying this library.

+

To learn more about this extension, see VK_KHR_buffer_device_address in Vulkan specification

+

Example use of this extension can be found in the code of the sample and test suite accompanying this library.

-Generated by doxygen 1.9.1 +Generated by doxygen 1.9.2
diff --git a/docs/html/files.html b/docs/html/files.html index 4027c8f..c6bc01b 100644 --- a/docs/html/files.html +++ b/docs/html/files.html @@ -2,8 +2,8 @@ - - + + Vulkan Memory Allocator: File List @@ -29,21 +29,22 @@
- + +/* @license-end */ +
@@ -61,8 +62,7 @@ $(function() {
-
-
File List
+
File List
Here is a list of all files with brief descriptions:
@@ -74,7 +74,7 @@ $(function() {
-Generated by doxygen 1.9.1 +Generated by doxygen 1.9.2
diff --git a/docs/html/functions.html b/docs/html/functions.html index 961439a..a4517d3 100644 --- a/docs/html/functions.html +++ b/docs/html/functions.html @@ -2,8 +2,8 @@ - - + + Vulkan Memory Allocator: Class Members @@ -29,21 +29,22 @@
- + +/* @license-end */ +
@@ -63,345 +64,151 @@ $(function() {
Here is a list of all class members with links to the classes they belong to:
-

- a -

-Generated by doxygen 1.9.1 +Generated by doxygen 1.9.2
diff --git a/docs/html/functions_vars.html b/docs/html/functions_vars.html index eff4550..b92b3b2 100644 --- a/docs/html/functions_vars.html +++ b/docs/html/functions_vars.html @@ -2,8 +2,8 @@ - - + + Vulkan Memory Allocator: Class Members - Variables @@ -29,21 +29,22 @@
- + +/* @license-end */ +
@@ -63,345 +64,151 @@ $(function() {
  -

- a -

-Generated by doxygen 1.9.1 +Generated by doxygen 1.9.2
diff --git a/docs/html/general_considerations.html b/docs/html/general_considerations.html index 4bd639f..b1ef2be 100644 --- a/docs/html/general_considerations.html +++ b/docs/html/general_considerations.html @@ -2,8 +2,8 @@ - - + + Vulkan Memory Allocator: General considerations @@ -29,21 +29,22 @@ - + +/* @license-end */ + -
-
-
General considerations
+
+
General considerations

@@ -79,7 +79,7 @@ Thread safety

Validation layer warnings

-

When using this library, you can meet following types of warnings issued by Vulkan validation layer. They don't necessarily indicate a bug, so you may need to just ignore them.

+

When using this library, you can meet following types of warnings issued by Vulkan validation layer. They don't necessarily indicate a bug, so you may need to just ignore them.

  • vkBindBufferMemory(): Binding memory to buffer 0xeb8e4 but vkGetBufferMemoryRequirements() has not been called on that buffer.
    • It happens when VK_KHR_dedicated_allocation extension is enabled. vkGetBufferMemoryRequirements2KHR function is used instead, while validation layer seems to be unaware of it.
      • @@ -97,7 +97,7 @@ Validation layer warnings

    Allocation algorithm

    -

    The library uses following algorithm for allocation, in order:

    +

    The library uses following algorithm for allocation, in order:

    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. @@ -109,7 +109,7 @@ Allocation algorithm

    Features not supported

    -

    Features deliberately excluded from the scope of this library:

    +

    Features deliberately excluded from the scope of this library:

    • Data transfer. Uploading (streaming) and downloading data of buffers and images between CPU and GPU memory and related synchronization is responsibility of the user. Defining some "texture" object that would automatically stream its data from a staging copy in CPU memory to GPU memory would rather be a feature of another, higher-level library implemented on top of VMA.
    • Recreation of buffers and images. Although the library has functions for buffer and image creation (vmaCreateBuffer(), vmaCreateImage()), you need to recreate these objects yourself after defragmentation. That is because the big structures VkBufferCreateInfo, VkImageCreateInfo are not stored in VmaAllocation object.
      • @@ -121,7 +121,7 @@ Features not supported
-Generated by doxygen 1.9.1 +Generated by doxygen 1.9.2
diff --git a/docs/html/globals.html b/docs/html/globals.html index 06f4292..55ab7c7 100644 --- a/docs/html/globals.html +++ b/docs/html/globals.html @@ -2,8 +2,8 @@ - - + + Vulkan Memory Allocator: File Members @@ -29,21 +29,22 @@
- + +/* @license-end */ +
@@ -63,412 +64,148 @@ $(function() {
Here is a list of all file members with links to the files they belong to:
-

- p -

-Generated by doxygen 1.9.1 +Generated by doxygen 1.9.2
diff --git a/docs/html/globals_defs.html b/docs/html/globals_defs.html index 26dd4e0..914c064 100644 --- a/docs/html/globals_defs.html +++ b/docs/html/globals_defs.html @@ -2,8 +2,8 @@ - - + + Vulkan Memory Allocator: File Members @@ -29,21 +29,22 @@
- + +/* @license-end */ +
@@ -62,35 +63,19 @@ $(function() {
 
-Generated by doxygen 1.9.1 +Generated by doxygen 1.9.2
diff --git a/docs/html/globals_enum.html b/docs/html/globals_enum.html index 1d58808..b375526 100644 --- a/docs/html/globals_enum.html +++ b/docs/html/globals_enum.html @@ -2,8 +2,8 @@ - - + + Vulkan Memory Allocator: File Members @@ -29,21 +29,22 @@ - + +/* @license-end */ + @@ -62,29 +63,17 @@ $(function() {
 
-Generated by doxygen 1.9.1 +Generated by doxygen 1.9.2
diff --git a/docs/html/globals_eval.html b/docs/html/globals_eval.html index b370fa0..9bdb584 100644 --- a/docs/html/globals_eval.html +++ b/docs/html/globals_eval.html @@ -2,8 +2,8 @@ - - + + Vulkan Memory Allocator: File Members @@ -29,21 +29,22 @@ - + +/* @license-end */ + @@ -63,138 +64,54 @@ $(function() {
  -

- v -

-Generated by doxygen 1.9.1 +Generated by doxygen 1.9.2
diff --git a/docs/html/globals_func.html b/docs/html/globals_func.html index 85841af..5a67266 100644 --- a/docs/html/globals_func.html +++ b/docs/html/globals_func.html @@ -2,8 +2,8 @@ - - + + Vulkan Memory Allocator: File Members @@ -29,21 +29,22 @@ - + +/* @license-end */ + @@ -63,168 +64,64 @@ $(function() {
  -

- v -

-Generated by doxygen 1.9.1 +Generated by doxygen 1.9.2
diff --git a/docs/html/globals_type.html b/docs/html/globals_type.html index b54a1cf..9048d63 100644 --- a/docs/html/globals_type.html +++ b/docs/html/globals_type.html @@ -2,8 +2,8 @@ - - + + Vulkan Memory Allocator: File Members @@ -29,21 +29,22 @@ - + +/* @license-end */ + @@ -62,101 +63,41 @@ $(function() {
 
-Generated by doxygen 1.9.1 +Generated by doxygen 1.9.2
diff --git a/docs/html/index.html b/docs/html/index.html index 5563299..f538a88 100644 --- a/docs/html/index.html +++ b/docs/html/index.html @@ -2,8 +2,8 @@ - - + + Vulkan Memory Allocator: Vulkan Memory Allocator @@ -29,21 +29,22 @@ - + +/* @license-end */ + @@ -60,15 +61,14 @@ $(function() { -
-
-
Vulkan Memory Allocator
+
+
Vulkan Memory Allocator
-

Version 3.0.0-development (2021-06-21)

-

Copyright (c) 2017-2021 Advanced Micro Devices, Inc. All rights reserved.
+

Version 3.0.0-development (2021-06-21)

+

Copyright (c) 2017-2021 Advanced Micro Devices, Inc. All rights reserved.
License: MIT

-

Documentation of all members: vk_mem_alloc.h

+

Documentation of all members: vk_mem_alloc.h

Table of contents

    @@ -174,7 +174,7 @@ See also
-Generated by doxygen 1.9.1 +Generated by doxygen 1.9.2
diff --git a/docs/html/jquery.js b/docs/html/jquery.js index 103c32d..c9ed3d9 100644 --- a/docs/html/jquery.js +++ b/docs/html/jquery.js @@ -1,5 +1,5 @@ -/*! jQuery v3.4.1 | (c) JS Foundation and other contributors | jquery.org/license */ -!function(e,t){"use strict";"object"==typeof module&&"object"==typeof module.exports?module.exports=e.document?t(e,!0):function(e){if(!e.document)throw new Error("jQuery requires a window with a document");return t(e)}:t(e)}("undefined"!=typeof window?window:this,function(C,e){"use strict";var t=[],E=C.document,r=Object.getPrototypeOf,s=t.slice,g=t.concat,u=t.push,i=t.indexOf,n={},o=n.toString,v=n.hasOwnProperty,a=v.toString,l=a.call(Object),y={},m=function(e){return"function"==typeof e&&"number"!=typeof e.nodeType},x=function(e){return null!=e&&e===e.window},c={type:!0,src:!0,nonce:!0,noModule:!0};function b(e,t,n){var r,i,o=(n=n||E).createElement("script");if(o.text=e,t)for(r in c)(i=t[r]||t.getAttribute&&t.getAttribute(r))&&o.setAttribute(r,i);n.head.appendChild(o).parentNode.removeChild(o)}function w(e){return null==e?e+"":"object"==typeof e||"function"==typeof e?n[o.call(e)]||"object":typeof e}var f="3.4.1",k=function(e,t){return new k.fn.init(e,t)},p=/^[\s\uFEFF\xA0]+|[\s\uFEFF\xA0]+$/g;function d(e){var t=!!e&&"length"in e&&e.length,n=w(e);return!m(e)&&!x(e)&&("array"===n||0===t||"number"==typeof t&&0+~]|"+M+")"+M+"*"),U=new RegExp(M+"|>"),X=new RegExp($),V=new RegExp("^"+I+"$"),G={ID:new RegExp("^#("+I+")"),CLASS:new RegExp("^\\.("+I+")"),TAG:new RegExp("^("+I+"|[*])"),ATTR:new RegExp("^"+W),PSEUDO:new RegExp("^"+$),CHILD:new RegExp("^:(only|first|last|nth|nth-last)-(child|of-type)(?:\\("+M+"*(even|odd|(([+-]|)(\\d*)n|)"+M+"*(?:([+-]|)"+M+"*(\\d+)|))"+M+"*\\)|)","i"),bool:new RegExp("^(?:"+R+")$","i"),needsContext:new RegExp("^"+M+"*[>+~]|:(even|odd|eq|gt|lt|nth|first|last)(?:\\("+M+"*((?:-\\d)?\\d*)"+M+"*\\)|)(?=[^-]|$)","i")},Y=/HTML$/i,Q=/^(?:input|select|textarea|button)$/i,J=/^h\d$/i,K=/^[^{]+\{\s*\[native \w/,Z=/^(?:#([\w-]+)|(\w+)|\.([\w-]+))$/,ee=/[+~]/,te=new RegExp("\\\\([\\da-f]{1,6}"+M+"?|("+M+")|.)","ig"),ne=function(e,t,n){var r="0x"+t-65536;return r!=r||n?t:r<0?String.fromCharCode(r+65536):String.fromCharCode(r>>10|55296,1023&r|56320)},re=/([\0-\x1f\x7f]|^-?\d)|^-$|[^\0-\x1f\x7f-\uFFFF\w-]/g,ie=function(e,t){return t?"\0"===e?"\ufffd":e.slice(0,-1)+"\\"+e.charCodeAt(e.length-1).toString(16)+" ":"\\"+e},oe=function(){T()},ae=be(function(e){return!0===e.disabled&&"fieldset"===e.nodeName.toLowerCase()},{dir:"parentNode",next:"legend"});try{H.apply(t=O.call(m.childNodes),m.childNodes),t[m.childNodes.length].nodeType}catch(e){H={apply:t.length?function(e,t){L.apply(e,O.call(t))}:function(e,t){var n=e.length,r=0;while(e[n++]=t[r++]);e.length=n-1}}}function se(t,e,n,r){var i,o,a,s,u,l,c,f=e&&e.ownerDocument,p=e?e.nodeType:9;if(n=n||[],"string"!=typeof t||!t||1!==p&&9!==p&&11!==p)return n;if(!r&&((e?e.ownerDocument||e:m)!==C&&T(e),e=e||C,E)){if(11!==p&&(u=Z.exec(t)))if(i=u[1]){if(9===p){if(!(a=e.getElementById(i)))return n;if(a.id===i)return n.push(a),n}else if(f&&(a=f.getElementById(i))&&y(e,a)&&a.id===i)return n.push(a),n}else{if(u[2])return H.apply(n,e.getElementsByTagName(t)),n;if((i=u[3])&&d.getElementsByClassName&&e.getElementsByClassName)return H.apply(n,e.getElementsByClassName(i)),n}if(d.qsa&&!A[t+" "]&&(!v||!v.test(t))&&(1!==p||"object"!==e.nodeName.toLowerCase())){if(c=t,f=e,1===p&&U.test(t)){(s=e.getAttribute("id"))?s=s.replace(re,ie):e.setAttribute("id",s=k),o=(l=h(t)).length;while(o--)l[o]="#"+s+" "+xe(l[o]);c=l.join(","),f=ee.test(t)&&ye(e.parentNode)||e}try{return H.apply(n,f.querySelectorAll(c)),n}catch(e){A(t,!0)}finally{s===k&&e.removeAttribute("id")}}}return g(t.replace(B,"$1"),e,n,r)}function ue(){var r=[];return function e(t,n){return r.push(t+" ")>b.cacheLength&&delete e[r.shift()],e[t+" "]=n}}function le(e){return e[k]=!0,e}function ce(e){var t=C.createElement("fieldset");try{return!!e(t)}catch(e){return!1}finally{t.parentNode&&t.parentNode.removeChild(t),t=null}}function fe(e,t){var n=e.split("|"),r=n.length;while(r--)b.attrHandle[n[r]]=t}function pe(e,t){var n=t&&e,r=n&&1===e.nodeType&&1===t.nodeType&&e.sourceIndex-t.sourceIndex;if(r)return r;if(n)while(n=n.nextSibling)if(n===t)return-1;return e?1:-1}function de(t){return function(e){return"input"===e.nodeName.toLowerCase()&&e.type===t}}function he(n){return function(e){var t=e.nodeName.toLowerCase();return("input"===t||"button"===t)&&e.type===n}}function ge(t){return function(e){return"form"in e?e.parentNode&&!1===e.disabled?"label"in e?"label"in e.parentNode?e.parentNode.disabled===t:e.disabled===t:e.isDisabled===t||e.isDisabled!==!t&&ae(e)===t:e.disabled===t:"label"in e&&e.disabled===t}}function ve(a){return le(function(o){return o=+o,le(function(e,t){var n,r=a([],e.length,o),i=r.length;while(i--)e[n=r[i]]&&(e[n]=!(t[n]=e[n]))})})}function ye(e){return e&&"undefined"!=typeof e.getElementsByTagName&&e}for(e in d=se.support={},i=se.isXML=function(e){var t=e.namespaceURI,n=(e.ownerDocument||e).documentElement;return!Y.test(t||n&&n.nodeName||"HTML")},T=se.setDocument=function(e){var t,n,r=e?e.ownerDocument||e:m;return r!==C&&9===r.nodeType&&r.documentElement&&(a=(C=r).documentElement,E=!i(C),m!==C&&(n=C.defaultView)&&n.top!==n&&(n.addEventListener?n.addEventListener("unload",oe,!1):n.attachEvent&&n.attachEvent("onunload",oe)),d.attributes=ce(function(e){return e.className="i",!e.getAttribute("className")}),d.getElementsByTagName=ce(function(e){return e.appendChild(C.createComment("")),!e.getElementsByTagName("*").length}),d.getElementsByClassName=K.test(C.getElementsByClassName),d.getById=ce(function(e){return a.appendChild(e).id=k,!C.getElementsByName||!C.getElementsByName(k).length}),d.getById?(b.filter.ID=function(e){var t=e.replace(te,ne);return function(e){return e.getAttribute("id")===t}},b.find.ID=function(e,t){if("undefined"!=typeof t.getElementById&&E){var n=t.getElementById(e);return n?[n]:[]}}):(b.filter.ID=function(e){var n=e.replace(te,ne);return function(e){var t="undefined"!=typeof e.getAttributeNode&&e.getAttributeNode("id");return t&&t.value===n}},b.find.ID=function(e,t){if("undefined"!=typeof t.getElementById&&E){var n,r,i,o=t.getElementById(e);if(o){if((n=o.getAttributeNode("id"))&&n.value===e)return[o];i=t.getElementsByName(e),r=0;while(o=i[r++])if((n=o.getAttributeNode("id"))&&n.value===e)return[o]}return[]}}),b.find.TAG=d.getElementsByTagName?function(e,t){return"undefined"!=typeof t.getElementsByTagName?t.getElementsByTagName(e):d.qsa?t.querySelectorAll(e):void 0}:function(e,t){var n,r=[],i=0,o=t.getElementsByTagName(e);if("*"===e){while(n=o[i++])1===n.nodeType&&r.push(n);return r}return o},b.find.CLASS=d.getElementsByClassName&&function(e,t){if("undefined"!=typeof t.getElementsByClassName&&E)return t.getElementsByClassName(e)},s=[],v=[],(d.qsa=K.test(C.querySelectorAll))&&(ce(function(e){a.appendChild(e).innerHTML="",e.querySelectorAll("[msallowcapture^='']").length&&v.push("[*^$]="+M+"*(?:''|\"\")"),e.querySelectorAll("[selected]").length||v.push("\\["+M+"*(?:value|"+R+")"),e.querySelectorAll("[id~="+k+"-]").length||v.push("~="),e.querySelectorAll(":checked").length||v.push(":checked"),e.querySelectorAll("a#"+k+"+*").length||v.push(".#.+[+~]")}),ce(function(e){e.innerHTML="";var t=C.createElement("input");t.setAttribute("type","hidden"),e.appendChild(t).setAttribute("name","D"),e.querySelectorAll("[name=d]").length&&v.push("name"+M+"*[*^$|!~]?="),2!==e.querySelectorAll(":enabled").length&&v.push(":enabled",":disabled"),a.appendChild(e).disabled=!0,2!==e.querySelectorAll(":disabled").length&&v.push(":enabled",":disabled"),e.querySelectorAll("*,:x"),v.push(",.*:")})),(d.matchesSelector=K.test(c=a.matches||a.webkitMatchesSelector||a.mozMatchesSelector||a.oMatchesSelector||a.msMatchesSelector))&&ce(function(e){d.disconnectedMatch=c.call(e,"*"),c.call(e,"[s!='']:x"),s.push("!=",$)}),v=v.length&&new RegExp(v.join("|")),s=s.length&&new RegExp(s.join("|")),t=K.test(a.compareDocumentPosition),y=t||K.test(a.contains)?function(e,t){var n=9===e.nodeType?e.documentElement:e,r=t&&t.parentNode;return e===r||!(!r||1!==r.nodeType||!(n.contains?n.contains(r):e.compareDocumentPosition&&16&e.compareDocumentPosition(r)))}:function(e,t){if(t)while(t=t.parentNode)if(t===e)return!0;return!1},D=t?function(e,t){if(e===t)return l=!0,0;var n=!e.compareDocumentPosition-!t.compareDocumentPosition;return n||(1&(n=(e.ownerDocument||e)===(t.ownerDocument||t)?e.compareDocumentPosition(t):1)||!d.sortDetached&&t.compareDocumentPosition(e)===n?e===C||e.ownerDocument===m&&y(m,e)?-1:t===C||t.ownerDocument===m&&y(m,t)?1:u?P(u,e)-P(u,t):0:4&n?-1:1)}:function(e,t){if(e===t)return l=!0,0;var n,r=0,i=e.parentNode,o=t.parentNode,a=[e],s=[t];if(!i||!o)return e===C?-1:t===C?1:i?-1:o?1:u?P(u,e)-P(u,t):0;if(i===o)return pe(e,t);n=e;while(n=n.parentNode)a.unshift(n);n=t;while(n=n.parentNode)s.unshift(n);while(a[r]===s[r])r++;return r?pe(a[r],s[r]):a[r]===m?-1:s[r]===m?1:0}),C},se.matches=function(e,t){return se(e,null,null,t)},se.matchesSelector=function(e,t){if((e.ownerDocument||e)!==C&&T(e),d.matchesSelector&&E&&!A[t+" "]&&(!s||!s.test(t))&&(!v||!v.test(t)))try{var n=c.call(e,t);if(n||d.disconnectedMatch||e.document&&11!==e.document.nodeType)return n}catch(e){A(t,!0)}return 0":{dir:"parentNode",first:!0}," ":{dir:"parentNode"},"+":{dir:"previousSibling",first:!0},"~":{dir:"previousSibling"}},preFilter:{ATTR:function(e){return e[1]=e[1].replace(te,ne),e[3]=(e[3]||e[4]||e[5]||"").replace(te,ne),"~="===e[2]&&(e[3]=" "+e[3]+" "),e.slice(0,4)},CHILD:function(e){return e[1]=e[1].toLowerCase(),"nth"===e[1].slice(0,3)?(e[3]||se.error(e[0]),e[4]=+(e[4]?e[5]+(e[6]||1):2*("even"===e[3]||"odd"===e[3])),e[5]=+(e[7]+e[8]||"odd"===e[3])):e[3]&&se.error(e[0]),e},PSEUDO:function(e){var t,n=!e[6]&&e[2];return G.CHILD.test(e[0])?null:(e[3]?e[2]=e[4]||e[5]||"":n&&X.test(n)&&(t=h(n,!0))&&(t=n.indexOf(")",n.length-t)-n.length)&&(e[0]=e[0].slice(0,t),e[2]=n.slice(0,t)),e.slice(0,3))}},filter:{TAG:function(e){var t=e.replace(te,ne).toLowerCase();return"*"===e?function(){return!0}:function(e){return e.nodeName&&e.nodeName.toLowerCase()===t}},CLASS:function(e){var t=p[e+" "];return t||(t=new RegExp("(^|"+M+")"+e+"("+M+"|$)"))&&p(e,function(e){return t.test("string"==typeof e.className&&e.className||"undefined"!=typeof e.getAttribute&&e.getAttribute("class")||"")})},ATTR:function(n,r,i){return function(e){var t=se.attr(e,n);return null==t?"!="===r:!r||(t+="","="===r?t===i:"!="===r?t!==i:"^="===r?i&&0===t.indexOf(i):"*="===r?i&&-1:\x20\t\r\n\f]*)[\x20\t\r\n\f]*\/?>(?:<\/\1>|)$/i;function j(e,n,r){return m(n)?k.grep(e,function(e,t){return!!n.call(e,t,e)!==r}):n.nodeType?k.grep(e,function(e){return e===n!==r}):"string"!=typeof n?k.grep(e,function(e){return-1)[^>]*|#([\w-]+))$/;(k.fn.init=function(e,t,n){var r,i;if(!e)return this;if(n=n||q,"string"==typeof e){if(!(r="<"===e[0]&&">"===e[e.length-1]&&3<=e.length?[null,e,null]:L.exec(e))||!r[1]&&t)return!t||t.jquery?(t||n).find(e):this.constructor(t).find(e);if(r[1]){if(t=t instanceof k?t[0]:t,k.merge(this,k.parseHTML(r[1],t&&t.nodeType?t.ownerDocument||t:E,!0)),D.test(r[1])&&k.isPlainObject(t))for(r in t)m(this[r])?this[r](t[r]):this.attr(r,t[r]);return this}return(i=E.getElementById(r[2]))&&(this[0]=i,this.length=1),this}return e.nodeType?(this[0]=e,this.length=1,this):m(e)?void 0!==n.ready?n.ready(e):e(k):k.makeArray(e,this)}).prototype=k.fn,q=k(E);var H=/^(?:parents|prev(?:Until|All))/,O={children:!0,contents:!0,next:!0,prev:!0};function P(e,t){while((e=e[t])&&1!==e.nodeType);return e}k.fn.extend({has:function(e){var t=k(e,this),n=t.length;return this.filter(function(){for(var e=0;e\x20\t\r\n\f]*)/i,he=/^$|^module$|\/(?:java|ecma)script/i,ge={option:[1,""],thead:[1,"","
"],col:[2,"","
"],tr:[2,"","
"],td:[3,"","
"],_default:[0,"",""]};function ve(e,t){var n;return n="undefined"!=typeof e.getElementsByTagName?e.getElementsByTagName(t||"*"):"undefined"!=typeof e.querySelectorAll?e.querySelectorAll(t||"*"):[],void 0===t||t&&A(e,t)?k.merge([e],n):n}function ye(e,t){for(var n=0,r=e.length;nx",y.noCloneChecked=!!me.cloneNode(!0).lastChild.defaultValue;var Te=/^key/,Ce=/^(?:mouse|pointer|contextmenu|drag|drop)|click/,Ee=/^([^.]*)(?:\.(.+)|)/;function ke(){return!0}function Se(){return!1}function Ne(e,t){return e===function(){try{return E.activeElement}catch(e){}}()==("focus"===t)}function Ae(e,t,n,r,i,o){var a,s;if("object"==typeof t){for(s in"string"!=typeof n&&(r=r||n,n=void 0),t)Ae(e,s,n,r,t[s],o);return e}if(null==r&&null==i?(i=n,r=n=void 0):null==i&&("string"==typeof n?(i=r,r=void 0):(i=r,r=n,n=void 0)),!1===i)i=Se;else if(!i)return e;return 1===o&&(a=i,(i=function(e){return k().off(e),a.apply(this,arguments)}).guid=a.guid||(a.guid=k.guid++)),e.each(function(){k.event.add(this,t,i,r,n)})}function De(e,i,o){o?(Q.set(e,i,!1),k.event.add(e,i,{namespace:!1,handler:function(e){var t,n,r=Q.get(this,i);if(1&e.isTrigger&&this[i]){if(r.length)(k.event.special[i]||{}).delegateType&&e.stopPropagation();else if(r=s.call(arguments),Q.set(this,i,r),t=o(this,i),this[i](),r!==(n=Q.get(this,i))||t?Q.set(this,i,!1):n={},r!==n)return e.stopImmediatePropagation(),e.preventDefault(),n.value}else r.length&&(Q.set(this,i,{value:k.event.trigger(k.extend(r[0],k.Event.prototype),r.slice(1),this)}),e.stopImmediatePropagation())}})):void 0===Q.get(e,i)&&k.event.add(e,i,ke)}k.event={global:{},add:function(t,e,n,r,i){var o,a,s,u,l,c,f,p,d,h,g,v=Q.get(t);if(v){n.handler&&(n=(o=n).handler,i=o.selector),i&&k.find.matchesSelector(ie,i),n.guid||(n.guid=k.guid++),(u=v.events)||(u=v.events={}),(a=v.handle)||(a=v.handle=function(e){return"undefined"!=typeof k&&k.event.triggered!==e.type?k.event.dispatch.apply(t,arguments):void 0}),l=(e=(e||"").match(R)||[""]).length;while(l--)d=g=(s=Ee.exec(e[l])||[])[1],h=(s[2]||"").split(".").sort(),d&&(f=k.event.special[d]||{},d=(i?f.delegateType:f.bindType)||d,f=k.event.special[d]||{},c=k.extend({type:d,origType:g,data:r,handler:n,guid:n.guid,selector:i,needsContext:i&&k.expr.match.needsContext.test(i),namespace:h.join(".")},o),(p=u[d])||((p=u[d]=[]).delegateCount=0,f.setup&&!1!==f.setup.call(t,r,h,a)||t.addEventListener&&t.addEventListener(d,a)),f.add&&(f.add.call(t,c),c.handler.guid||(c.handler.guid=n.guid)),i?p.splice(p.delegateCount++,0,c):p.push(c),k.event.global[d]=!0)}},remove:function(e,t,n,r,i){var o,a,s,u,l,c,f,p,d,h,g,v=Q.hasData(e)&&Q.get(e);if(v&&(u=v.events)){l=(t=(t||"").match(R)||[""]).length;while(l--)if(d=g=(s=Ee.exec(t[l])||[])[1],h=(s[2]||"").split(".").sort(),d){f=k.event.special[d]||{},p=u[d=(r?f.delegateType:f.bindType)||d]||[],s=s[2]&&new RegExp("(^|\\.)"+h.join("\\.(?:.*\\.|)")+"(\\.|$)"),a=o=p.length;while(o--)c=p[o],!i&&g!==c.origType||n&&n.guid!==c.guid||s&&!s.test(c.namespace)||r&&r!==c.selector&&("**"!==r||!c.selector)||(p.splice(o,1),c.selector&&p.delegateCount--,f.remove&&f.remove.call(e,c));a&&!p.length&&(f.teardown&&!1!==f.teardown.call(e,h,v.handle)||k.removeEvent(e,d,v.handle),delete u[d])}else for(d in u)k.event.remove(e,d+t[l],n,r,!0);k.isEmptyObject(u)&&Q.remove(e,"handle events")}},dispatch:function(e){var t,n,r,i,o,a,s=k.event.fix(e),u=new Array(arguments.length),l=(Q.get(this,"events")||{})[s.type]||[],c=k.event.special[s.type]||{};for(u[0]=s,t=1;t\x20\t\r\n\f]*)[^>]*)\/>/gi,qe=/\s*$/g;function Oe(e,t){return A(e,"table")&&A(11!==t.nodeType?t:t.firstChild,"tr")&&k(e).children("tbody")[0]||e}function Pe(e){return e.type=(null!==e.getAttribute("type"))+"/"+e.type,e}function Re(e){return"true/"===(e.type||"").slice(0,5)?e.type=e.type.slice(5):e.removeAttribute("type"),e}function Me(e,t){var n,r,i,o,a,s,u,l;if(1===t.nodeType){if(Q.hasData(e)&&(o=Q.access(e),a=Q.set(t,o),l=o.events))for(i in delete a.handle,a.events={},l)for(n=0,r=l[i].length;n")},clone:function(e,t,n){var r,i,o,a,s,u,l,c=e.cloneNode(!0),f=oe(e);if(!(y.noCloneChecked||1!==e.nodeType&&11!==e.nodeType||k.isXMLDoc(e)))for(a=ve(c),r=0,i=(o=ve(e)).length;r").attr(n.scriptAttrs||{}).prop({charset:n.scriptCharset,src:n.url}).on("load error",i=function(e){r.remove(),i=null,e&&t("error"===e.type?404:200,e.type)}),E.head.appendChild(r[0])},abort:function(){i&&i()}}});var Vt,Gt=[],Yt=/(=)\?(?=&|$)|\?\?/;k.ajaxSetup({jsonp:"callback",jsonpCallback:function(){var e=Gt.pop()||k.expando+"_"+kt++;return this[e]=!0,e}}),k.ajaxPrefilter("json jsonp",function(e,t,n){var r,i,o,a=!1!==e.jsonp&&(Yt.test(e.url)?"url":"string"==typeof e.data&&0===(e.contentType||"").indexOf("application/x-www-form-urlencoded")&&Yt.test(e.data)&&"data");if(a||"jsonp"===e.dataTypes[0])return r=e.jsonpCallback=m(e.jsonpCallback)?e.jsonpCallback():e.jsonpCallback,a?e[a]=e[a].replace(Yt,"$1"+r):!1!==e.jsonp&&(e.url+=(St.test(e.url)?"&":"?")+e.jsonp+"="+r),e.converters["script json"]=function(){return o||k.error(r+" was not called"),o[0]},e.dataTypes[0]="json",i=C[r],C[r]=function(){o=arguments},n.always(function(){void 0===i?k(C).removeProp(r):C[r]=i,e[r]&&(e.jsonpCallback=t.jsonpCallback,Gt.push(r)),o&&m(i)&&i(o[0]),o=i=void 0}),"script"}),y.createHTMLDocument=((Vt=E.implementation.createHTMLDocument("").body).innerHTML="
",2===Vt.childNodes.length),k.parseHTML=function(e,t,n){return"string"!=typeof e?[]:("boolean"==typeof t&&(n=t,t=!1),t||(y.createHTMLDocument?((r=(t=E.implementation.createHTMLDocument("")).createElement("base")).href=E.location.href,t.head.appendChild(r)):t=E),o=!n&&[],(i=D.exec(e))?[t.createElement(i[1])]:(i=we([e],t,o),o&&o.length&&k(o).remove(),k.merge([],i.childNodes)));var r,i,o},k.fn.load=function(e,t,n){var r,i,o,a=this,s=e.indexOf(" ");return-1").append(k.parseHTML(e)).find(r):e)}).always(n&&function(e,t){a.each(function(){n.apply(this,o||[e.responseText,t,e])})}),this},k.each(["ajaxStart","ajaxStop","ajaxComplete","ajaxError","ajaxSuccess","ajaxSend"],function(e,t){k.fn[t]=function(e){return this.on(t,e)}}),k.expr.pseudos.animated=function(t){return k.grep(k.timers,function(e){return t===e.elem}).length},k.offset={setOffset:function(e,t,n){var r,i,o,a,s,u,l=k.css(e,"position"),c=k(e),f={};"static"===l&&(e.style.position="relative"),s=c.offset(),o=k.css(e,"top"),u=k.css(e,"left"),("absolute"===l||"fixed"===l)&&-1<(o+u).indexOf("auto")?(a=(r=c.position()).top,i=r.left):(a=parseFloat(o)||0,i=parseFloat(u)||0),m(t)&&(t=t.call(e,n,k.extend({},s))),null!=t.top&&(f.top=t.top-s.top+a),null!=t.left&&(f.left=t.left-s.left+i),"using"in t?t.using.call(e,f):c.css(f)}},k.fn.extend({offset:function(t){if(arguments.length)return void 0===t?this:this.each(function(e){k.offset.setOffset(this,t,e)});var e,n,r=this[0];return r?r.getClientRects().length?(e=r.getBoundingClientRect(),n=r.ownerDocument.defaultView,{top:e.top+n.pageYOffset,left:e.left+n.pageXOffset}):{top:0,left:0}:void 0},position:function(){if(this[0]){var e,t,n,r=this[0],i={top:0,left:0};if("fixed"===k.css(r,"position"))t=r.getBoundingClientRect();else{t=this.offset(),n=r.ownerDocument,e=r.offsetParent||n.documentElement;while(e&&(e===n.body||e===n.documentElement)&&"static"===k.css(e,"position"))e=e.parentNode;e&&e!==r&&1===e.nodeType&&((i=k(e).offset()).top+=k.css(e,"borderTopWidth",!0),i.left+=k.css(e,"borderLeftWidth",!0))}return{top:t.top-i.top-k.css(r,"marginTop",!0),left:t.left-i.left-k.css(r,"marginLeft",!0)}}},offsetParent:function(){return this.map(function(){var e=this.offsetParent;while(e&&"static"===k.css(e,"position"))e=e.offsetParent;return e||ie})}}),k.each({scrollLeft:"pageXOffset",scrollTop:"pageYOffset"},function(t,i){var o="pageYOffset"===i;k.fn[t]=function(e){return _(this,function(e,t,n){var r;if(x(e)?r=e:9===e.nodeType&&(r=e.defaultView),void 0===n)return r?r[i]:e[t];r?r.scrollTo(o?r.pageXOffset:n,o?n:r.pageYOffset):e[t]=n},t,e,arguments.length)}}),k.each(["top","left"],function(e,n){k.cssHooks[n]=ze(y.pixelPosition,function(e,t){if(t)return t=_e(e,n),$e.test(t)?k(e).position()[n]+"px":t})}),k.each({Height:"height",Width:"width"},function(a,s){k.each({padding:"inner"+a,content:s,"":"outer"+a},function(r,o){k.fn[o]=function(e,t){var n=arguments.length&&(r||"boolean"!=typeof e),i=r||(!0===e||!0===t?"margin":"border");return _(this,function(e,t,n){var r;return x(e)?0===o.indexOf("outer")?e["inner"+a]:e.document.documentElement["client"+a]:9===e.nodeType?(r=e.documentElement,Math.max(e.body["scroll"+a],r["scroll"+a],e.body["offset"+a],r["offset"+a],r["client"+a])):void 0===n?k.css(e,t,i):k.style(e,t,n,i)},s,n?e:void 0,n)}})}),k.each("blur focus focusin focusout resize scroll click dblclick mousedown mouseup mousemove mouseover mouseout mouseenter mouseleave change select submit keydown keypress keyup contextmenu".split(" "),function(e,n){k.fn[n]=function(e,t){return 0+~]|"+M+")"+M+"*"),U=new RegExp(M+"|>"),X=new RegExp(F),V=new RegExp("^"+I+"$"),G={ID:new RegExp("^#("+I+")"),CLASS:new RegExp("^\\.("+I+")"),TAG:new RegExp("^("+I+"|[*])"),ATTR:new RegExp("^"+W),PSEUDO:new RegExp("^"+F),CHILD:new RegExp("^:(only|first|last|nth|nth-last)-(child|of-type)(?:\\("+M+"*(even|odd|(([+-]|)(\\d*)n|)"+M+"*(?:([+-]|)"+M+"*(\\d+)|))"+M+"*\\)|)","i"),bool:new RegExp("^(?:"+R+")$","i"),needsContext:new RegExp("^"+M+"*[>+~]|:(even|odd|eq|gt|lt|nth|first|last)(?:\\("+M+"*((?:-\\d)?\\d*)"+M+"*\\)|)(?=[^-]|$)","i")},Y=/HTML$/i,Q=/^(?:input|select|textarea|button)$/i,J=/^h\d$/i,K=/^[^{]+\{\s*\[native \w/,Z=/^(?:#([\w-]+)|(\w+)|\.([\w-]+))$/,ee=/[+~]/,te=new RegExp("\\\\[\\da-fA-F]{1,6}"+M+"?|\\\\([^\\r\\n\\f])","g"),ne=function(e,t){var n="0x"+e.slice(1)-65536;return t||(n<0?String.fromCharCode(n+65536):String.fromCharCode(n>>10|55296,1023&n|56320))},re=/([\0-\x1f\x7f]|^-?\d)|^-$|[^\0-\x1f\x7f-\uFFFF\w-]/g,ie=function(e,t){return t?"\0"===e?"\ufffd":e.slice(0,-1)+"\\"+e.charCodeAt(e.length-1).toString(16)+" ":"\\"+e},oe=function(){T()},ae=be(function(e){return!0===e.disabled&&"fieldset"===e.nodeName.toLowerCase()},{dir:"parentNode",next:"legend"});try{H.apply(t=O.call(p.childNodes),p.childNodes),t[p.childNodes.length].nodeType}catch(e){H={apply:t.length?function(e,t){L.apply(e,O.call(t))}:function(e,t){var n=e.length,r=0;while(e[n++]=t[r++]);e.length=n-1}}}function se(t,e,n,r){var i,o,a,s,u,l,c,f=e&&e.ownerDocument,p=e?e.nodeType:9;if(n=n||[],"string"!=typeof t||!t||1!==p&&9!==p&&11!==p)return n;if(!r&&(T(e),e=e||C,E)){if(11!==p&&(u=Z.exec(t)))if(i=u[1]){if(9===p){if(!(a=e.getElementById(i)))return n;if(a.id===i)return n.push(a),n}else if(f&&(a=f.getElementById(i))&&y(e,a)&&a.id===i)return n.push(a),n}else{if(u[2])return H.apply(n,e.getElementsByTagName(t)),n;if((i=u[3])&&d.getElementsByClassName&&e.getElementsByClassName)return H.apply(n,e.getElementsByClassName(i)),n}if(d.qsa&&!N[t+" "]&&(!v||!v.test(t))&&(1!==p||"object"!==e.nodeName.toLowerCase())){if(c=t,f=e,1===p&&(U.test(t)||z.test(t))){(f=ee.test(t)&&ye(e.parentNode)||e)===e&&d.scope||((s=e.getAttribute("id"))?s=s.replace(re,ie):e.setAttribute("id",s=S)),o=(l=h(t)).length;while(o--)l[o]=(s?"#"+s:":scope")+" "+xe(l[o]);c=l.join(",")}try{return H.apply(n,f.querySelectorAll(c)),n}catch(e){N(t,!0)}finally{s===S&&e.removeAttribute("id")}}}return g(t.replace($,"$1"),e,n,r)}function ue(){var r=[];return function e(t,n){return r.push(t+" ")>b.cacheLength&&delete e[r.shift()],e[t+" "]=n}}function le(e){return e[S]=!0,e}function ce(e){var t=C.createElement("fieldset");try{return!!e(t)}catch(e){return!1}finally{t.parentNode&&t.parentNode.removeChild(t),t=null}}function fe(e,t){var n=e.split("|"),r=n.length;while(r--)b.attrHandle[n[r]]=t}function pe(e,t){var n=t&&e,r=n&&1===e.nodeType&&1===t.nodeType&&e.sourceIndex-t.sourceIndex;if(r)return r;if(n)while(n=n.nextSibling)if(n===t)return-1;return e?1:-1}function de(t){return function(e){return"input"===e.nodeName.toLowerCase()&&e.type===t}}function he(n){return function(e){var t=e.nodeName.toLowerCase();return("input"===t||"button"===t)&&e.type===n}}function ge(t){return function(e){return"form"in e?e.parentNode&&!1===e.disabled?"label"in e?"label"in e.parentNode?e.parentNode.disabled===t:e.disabled===t:e.isDisabled===t||e.isDisabled!==!t&&ae(e)===t:e.disabled===t:"label"in e&&e.disabled===t}}function ve(a){return le(function(o){return o=+o,le(function(e,t){var n,r=a([],e.length,o),i=r.length;while(i--)e[n=r[i]]&&(e[n]=!(t[n]=e[n]))})})}function ye(e){return e&&"undefined"!=typeof e.getElementsByTagName&&e}for(e in d=se.support={},i=se.isXML=function(e){var t=e&&e.namespaceURI,n=e&&(e.ownerDocument||e).documentElement;return!Y.test(t||n&&n.nodeName||"HTML")},T=se.setDocument=function(e){var t,n,r=e?e.ownerDocument||e:p;return r!=C&&9===r.nodeType&&r.documentElement&&(a=(C=r).documentElement,E=!i(C),p!=C&&(n=C.defaultView)&&n.top!==n&&(n.addEventListener?n.addEventListener("unload",oe,!1):n.attachEvent&&n.attachEvent("onunload",oe)),d.scope=ce(function(e){return a.appendChild(e).appendChild(C.createElement("div")),"undefined"!=typeof e.querySelectorAll&&!e.querySelectorAll(":scope fieldset div").length}),d.attributes=ce(function(e){return e.className="i",!e.getAttribute("className")}),d.getElementsByTagName=ce(function(e){return e.appendChild(C.createComment("")),!e.getElementsByTagName("*").length}),d.getElementsByClassName=K.test(C.getElementsByClassName),d.getById=ce(function(e){return a.appendChild(e).id=S,!C.getElementsByName||!C.getElementsByName(S).length}),d.getById?(b.filter.ID=function(e){var t=e.replace(te,ne);return function(e){return e.getAttribute("id")===t}},b.find.ID=function(e,t){if("undefined"!=typeof t.getElementById&&E){var n=t.getElementById(e);return n?[n]:[]}}):(b.filter.ID=function(e){var n=e.replace(te,ne);return function(e){var t="undefined"!=typeof e.getAttributeNode&&e.getAttributeNode("id");return t&&t.value===n}},b.find.ID=function(e,t){if("undefined"!=typeof t.getElementById&&E){var n,r,i,o=t.getElementById(e);if(o){if((n=o.getAttributeNode("id"))&&n.value===e)return[o];i=t.getElementsByName(e),r=0;while(o=i[r++])if((n=o.getAttributeNode("id"))&&n.value===e)return[o]}return[]}}),b.find.TAG=d.getElementsByTagName?function(e,t){return"undefined"!=typeof t.getElementsByTagName?t.getElementsByTagName(e):d.qsa?t.querySelectorAll(e):void 0}:function(e,t){var n,r=[],i=0,o=t.getElementsByTagName(e);if("*"===e){while(n=o[i++])1===n.nodeType&&r.push(n);return r}return o},b.find.CLASS=d.getElementsByClassName&&function(e,t){if("undefined"!=typeof t.getElementsByClassName&&E)return t.getElementsByClassName(e)},s=[],v=[],(d.qsa=K.test(C.querySelectorAll))&&(ce(function(e){var t;a.appendChild(e).innerHTML="",e.querySelectorAll("[msallowcapture^='']").length&&v.push("[*^$]="+M+"*(?:''|\"\")"),e.querySelectorAll("[selected]").length||v.push("\\["+M+"*(?:value|"+R+")"),e.querySelectorAll("[id~="+S+"-]").length||v.push("~="),(t=C.createElement("input")).setAttribute("name",""),e.appendChild(t),e.querySelectorAll("[name='']").length||v.push("\\["+M+"*name"+M+"*="+M+"*(?:''|\"\")"),e.querySelectorAll(":checked").length||v.push(":checked"),e.querySelectorAll("a#"+S+"+*").length||v.push(".#.+[+~]"),e.querySelectorAll("\\\f"),v.push("[\\r\\n\\f]")}),ce(function(e){e.innerHTML="";var t=C.createElement("input");t.setAttribute("type","hidden"),e.appendChild(t).setAttribute("name","D"),e.querySelectorAll("[name=d]").length&&v.push("name"+M+"*[*^$|!~]?="),2!==e.querySelectorAll(":enabled").length&&v.push(":enabled",":disabled"),a.appendChild(e).disabled=!0,2!==e.querySelectorAll(":disabled").length&&v.push(":enabled",":disabled"),e.querySelectorAll("*,:x"),v.push(",.*:")})),(d.matchesSelector=K.test(c=a.matches||a.webkitMatchesSelector||a.mozMatchesSelector||a.oMatchesSelector||a.msMatchesSelector))&&ce(function(e){d.disconnectedMatch=c.call(e,"*"),c.call(e,"[s!='']:x"),s.push("!=",F)}),v=v.length&&new RegExp(v.join("|")),s=s.length&&new RegExp(s.join("|")),t=K.test(a.compareDocumentPosition),y=t||K.test(a.contains)?function(e,t){var n=9===e.nodeType?e.documentElement:e,r=t&&t.parentNode;return e===r||!(!r||1!==r.nodeType||!(n.contains?n.contains(r):e.compareDocumentPosition&&16&e.compareDocumentPosition(r)))}:function(e,t){if(t)while(t=t.parentNode)if(t===e)return!0;return!1},j=t?function(e,t){if(e===t)return l=!0,0;var n=!e.compareDocumentPosition-!t.compareDocumentPosition;return n||(1&(n=(e.ownerDocument||e)==(t.ownerDocument||t)?e.compareDocumentPosition(t):1)||!d.sortDetached&&t.compareDocumentPosition(e)===n?e==C||e.ownerDocument==p&&y(p,e)?-1:t==C||t.ownerDocument==p&&y(p,t)?1:u?P(u,e)-P(u,t):0:4&n?-1:1)}:function(e,t){if(e===t)return l=!0,0;var n,r=0,i=e.parentNode,o=t.parentNode,a=[e],s=[t];if(!i||!o)return e==C?-1:t==C?1:i?-1:o?1:u?P(u,e)-P(u,t):0;if(i===o)return pe(e,t);n=e;while(n=n.parentNode)a.unshift(n);n=t;while(n=n.parentNode)s.unshift(n);while(a[r]===s[r])r++;return r?pe(a[r],s[r]):a[r]==p?-1:s[r]==p?1:0}),C},se.matches=function(e,t){return se(e,null,null,t)},se.matchesSelector=function(e,t){if(T(e),d.matchesSelector&&E&&!N[t+" "]&&(!s||!s.test(t))&&(!v||!v.test(t)))try{var n=c.call(e,t);if(n||d.disconnectedMatch||e.document&&11!==e.document.nodeType)return n}catch(e){N(t,!0)}return 0":{dir:"parentNode",first:!0}," ":{dir:"parentNode"},"+":{dir:"previousSibling",first:!0},"~":{dir:"previousSibling"}},preFilter:{ATTR:function(e){return e[1]=e[1].replace(te,ne),e[3]=(e[3]||e[4]||e[5]||"").replace(te,ne),"~="===e[2]&&(e[3]=" "+e[3]+" "),e.slice(0,4)},CHILD:function(e){return e[1]=e[1].toLowerCase(),"nth"===e[1].slice(0,3)?(e[3]||se.error(e[0]),e[4]=+(e[4]?e[5]+(e[6]||1):2*("even"===e[3]||"odd"===e[3])),e[5]=+(e[7]+e[8]||"odd"===e[3])):e[3]&&se.error(e[0]),e},PSEUDO:function(e){var t,n=!e[6]&&e[2];return G.CHILD.test(e[0])?null:(e[3]?e[2]=e[4]||e[5]||"":n&&X.test(n)&&(t=h(n,!0))&&(t=n.indexOf(")",n.length-t)-n.length)&&(e[0]=e[0].slice(0,t),e[2]=n.slice(0,t)),e.slice(0,3))}},filter:{TAG:function(e){var t=e.replace(te,ne).toLowerCase();return"*"===e?function(){return!0}:function(e){return e.nodeName&&e.nodeName.toLowerCase()===t}},CLASS:function(e){var t=m[e+" "];return t||(t=new RegExp("(^|"+M+")"+e+"("+M+"|$)"))&&m(e,function(e){return t.test("string"==typeof e.className&&e.className||"undefined"!=typeof e.getAttribute&&e.getAttribute("class")||"")})},ATTR:function(n,r,i){return function(e){var t=se.attr(e,n);return null==t?"!="===r:!r||(t+="","="===r?t===i:"!="===r?t!==i:"^="===r?i&&0===t.indexOf(i):"*="===r?i&&-1:\x20\t\r\n\f]*)[\x20\t\r\n\f]*\/?>(?:<\/\1>|)$/i;function j(e,n,r){return m(n)?S.grep(e,function(e,t){return!!n.call(e,t,e)!==r}):n.nodeType?S.grep(e,function(e){return e===n!==r}):"string"!=typeof n?S.grep(e,function(e){return-1)[^>]*|#([\w-]+))$/;(S.fn.init=function(e,t,n){var r,i;if(!e)return this;if(n=n||D,"string"==typeof e){if(!(r="<"===e[0]&&">"===e[e.length-1]&&3<=e.length?[null,e,null]:q.exec(e))||!r[1]&&t)return!t||t.jquery?(t||n).find(e):this.constructor(t).find(e);if(r[1]){if(t=t instanceof S?t[0]:t,S.merge(this,S.parseHTML(r[1],t&&t.nodeType?t.ownerDocument||t:E,!0)),N.test(r[1])&&S.isPlainObject(t))for(r in t)m(this[r])?this[r](t[r]):this.attr(r,t[r]);return this}return(i=E.getElementById(r[2]))&&(this[0]=i,this.length=1),this}return e.nodeType?(this[0]=e,this.length=1,this):m(e)?void 0!==n.ready?n.ready(e):e(S):S.makeArray(e,this)}).prototype=S.fn,D=S(E);var L=/^(?:parents|prev(?:Until|All))/,H={children:!0,contents:!0,next:!0,prev:!0};function O(e,t){while((e=e[t])&&1!==e.nodeType);return e}S.fn.extend({has:function(e){var t=S(e,this),n=t.length;return this.filter(function(){for(var e=0;e\x20\t\r\n\f]*)/i,he=/^$|^module$|\/(?:java|ecma)script/i;ce=E.createDocumentFragment().appendChild(E.createElement("div")),(fe=E.createElement("input")).setAttribute("type","radio"),fe.setAttribute("checked","checked"),fe.setAttribute("name","t"),ce.appendChild(fe),y.checkClone=ce.cloneNode(!0).cloneNode(!0).lastChild.checked,ce.innerHTML="",y.noCloneChecked=!!ce.cloneNode(!0).lastChild.defaultValue,ce.innerHTML="",y.option=!!ce.lastChild;var ge={thead:[1,"","
"],col:[2,"","
"],tr:[2,"","
"],td:[3,"","
"],_default:[0,"",""]};function ve(e,t){var n;return n="undefined"!=typeof e.getElementsByTagName?e.getElementsByTagName(t||"*"):"undefined"!=typeof e.querySelectorAll?e.querySelectorAll(t||"*"):[],void 0===t||t&&A(e,t)?S.merge([e],n):n}function ye(e,t){for(var n=0,r=e.length;n",""]);var me=/<|&#?\w+;/;function xe(e,t,n,r,i){for(var o,a,s,u,l,c,f=t.createDocumentFragment(),p=[],d=0,h=e.length;d\s*$/g;function je(e,t){return A(e,"table")&&A(11!==t.nodeType?t:t.firstChild,"tr")&&S(e).children("tbody")[0]||e}function De(e){return e.type=(null!==e.getAttribute("type"))+"/"+e.type,e}function qe(e){return"true/"===(e.type||"").slice(0,5)?e.type=e.type.slice(5):e.removeAttribute("type"),e}function Le(e,t){var n,r,i,o,a,s;if(1===t.nodeType){if(Y.hasData(e)&&(s=Y.get(e).events))for(i in Y.remove(t,"handle events"),s)for(n=0,r=s[i].length;n").attr(n.scriptAttrs||{}).prop({charset:n.scriptCharset,src:n.url}).on("load error",i=function(e){r.remove(),i=null,e&&t("error"===e.type?404:200,e.type)}),E.head.appendChild(r[0])},abort:function(){i&&i()}}});var _t,zt=[],Ut=/(=)\?(?=&|$)|\?\?/;S.ajaxSetup({jsonp:"callback",jsonpCallback:function(){var e=zt.pop()||S.expando+"_"+wt.guid++;return this[e]=!0,e}}),S.ajaxPrefilter("json jsonp",function(e,t,n){var r,i,o,a=!1!==e.jsonp&&(Ut.test(e.url)?"url":"string"==typeof e.data&&0===(e.contentType||"").indexOf("application/x-www-form-urlencoded")&&Ut.test(e.data)&&"data");if(a||"jsonp"===e.dataTypes[0])return r=e.jsonpCallback=m(e.jsonpCallback)?e.jsonpCallback():e.jsonpCallback,a?e[a]=e[a].replace(Ut,"$1"+r):!1!==e.jsonp&&(e.url+=(Tt.test(e.url)?"&":"?")+e.jsonp+"="+r),e.converters["script json"]=function(){return o||S.error(r+" was not called"),o[0]},e.dataTypes[0]="json",i=C[r],C[r]=function(){o=arguments},n.always(function(){void 0===i?S(C).removeProp(r):C[r]=i,e[r]&&(e.jsonpCallback=t.jsonpCallback,zt.push(r)),o&&m(i)&&i(o[0]),o=i=void 0}),"script"}),y.createHTMLDocument=((_t=E.implementation.createHTMLDocument("").body).innerHTML="
",2===_t.childNodes.length),S.parseHTML=function(e,t,n){return"string"!=typeof e?[]:("boolean"==typeof t&&(n=t,t=!1),t||(y.createHTMLDocument?((r=(t=E.implementation.createHTMLDocument("")).createElement("base")).href=E.location.href,t.head.appendChild(r)):t=E),o=!n&&[],(i=N.exec(e))?[t.createElement(i[1])]:(i=xe([e],t,o),o&&o.length&&S(o).remove(),S.merge([],i.childNodes)));var r,i,o},S.fn.load=function(e,t,n){var r,i,o,a=this,s=e.indexOf(" ");return-1").append(S.parseHTML(e)).find(r):e)}).always(n&&function(e,t){a.each(function(){n.apply(this,o||[e.responseText,t,e])})}),this},S.expr.pseudos.animated=function(t){return S.grep(S.timers,function(e){return t===e.elem}).length},S.offset={setOffset:function(e,t,n){var r,i,o,a,s,u,l=S.css(e,"position"),c=S(e),f={};"static"===l&&(e.style.position="relative"),s=c.offset(),o=S.css(e,"top"),u=S.css(e,"left"),("absolute"===l||"fixed"===l)&&-1<(o+u).indexOf("auto")?(a=(r=c.position()).top,i=r.left):(a=parseFloat(o)||0,i=parseFloat(u)||0),m(t)&&(t=t.call(e,n,S.extend({},s))),null!=t.top&&(f.top=t.top-s.top+a),null!=t.left&&(f.left=t.left-s.left+i),"using"in t?t.using.call(e,f):c.css(f)}},S.fn.extend({offset:function(t){if(arguments.length)return void 0===t?this:this.each(function(e){S.offset.setOffset(this,t,e)});var e,n,r=this[0];return r?r.getClientRects().length?(e=r.getBoundingClientRect(),n=r.ownerDocument.defaultView,{top:e.top+n.pageYOffset,left:e.left+n.pageXOffset}):{top:0,left:0}:void 0},position:function(){if(this[0]){var e,t,n,r=this[0],i={top:0,left:0};if("fixed"===S.css(r,"position"))t=r.getBoundingClientRect();else{t=this.offset(),n=r.ownerDocument,e=r.offsetParent||n.documentElement;while(e&&(e===n.body||e===n.documentElement)&&"static"===S.css(e,"position"))e=e.parentNode;e&&e!==r&&1===e.nodeType&&((i=S(e).offset()).top+=S.css(e,"borderTopWidth",!0),i.left+=S.css(e,"borderLeftWidth",!0))}return{top:t.top-i.top-S.css(r,"marginTop",!0),left:t.left-i.left-S.css(r,"marginLeft",!0)}}},offsetParent:function(){return this.map(function(){var e=this.offsetParent;while(e&&"static"===S.css(e,"position"))e=e.offsetParent;return e||re})}}),S.each({scrollLeft:"pageXOffset",scrollTop:"pageYOffset"},function(t,i){var o="pageYOffset"===i;S.fn[t]=function(e){return $(this,function(e,t,n){var r;if(x(e)?r=e:9===e.nodeType&&(r=e.defaultView),void 0===n)return r?r[i]:e[t];r?r.scrollTo(o?r.pageXOffset:n,o?n:r.pageYOffset):e[t]=n},t,e,arguments.length)}}),S.each(["top","left"],function(e,n){S.cssHooks[n]=Fe(y.pixelPosition,function(e,t){if(t)return t=We(e,n),Pe.test(t)?S(e).position()[n]+"px":t})}),S.each({Height:"height",Width:"width"},function(a,s){S.each({padding:"inner"+a,content:s,"":"outer"+a},function(r,o){S.fn[o]=function(e,t){var n=arguments.length&&(r||"boolean"!=typeof e),i=r||(!0===e||!0===t?"margin":"border");return $(this,function(e,t,n){var r;return x(e)?0===o.indexOf("outer")?e["inner"+a]:e.document.documentElement["client"+a]:9===e.nodeType?(r=e.documentElement,Math.max(e.body["scroll"+a],r["scroll"+a],e.body["offset"+a],r["offset"+a],r["client"+a])):void 0===n?S.css(e,t,i):S.style(e,t,n,i)},s,n?e:void 0,n)}})}),S.each(["ajaxStart","ajaxStop","ajaxComplete","ajaxError","ajaxSuccess","ajaxSend"],function(e,t){S.fn[t]=function(e){return this.on(t,e)}}),S.fn.extend({bind:function(e,t,n){return this.on(e,null,t,n)},unbind:function(e,t){return this.off(e,null,t)},delegate:function(e,t,n,r){return this.on(t,e,n,r)},undelegate:function(e,t,n){return 1===arguments.length?this.off(e,"**"):this.off(t,e||"**",n)},hover:function(e,t){return this.mouseenter(e).mouseleave(t||e)}}),S.each("blur focus focusin focusout resize scroll click dblclick mousedown mouseup mousemove mouseover mouseout mouseenter mouseleave change select submit keydown keypress keyup contextmenu".split(" "),function(e,n){S.fn[n]=function(e,t){return 0 - - + + Vulkan Memory Allocator: Lost allocations @@ -29,21 +29,22 @@
- + +/* @license-end */ +
-
-
-
Lost allocations
+
+
Lost allocations
-

If your game oversubscribes video memory, if may work OK in previous-generation graphics APIs (DirectX 9, 10, 11, OpenGL) because resources are automatically paged to system RAM. In Vulkan you can't do it because when you run out of memory, an allocation just fails. If you have more data (e.g. textures) that can fit into VRAM and you don't need it all at once, you may want to upload them to GPU on demand and "push out" ones that are not used for a long time to make room for the new ones, effectively using VRAM (or a cartain memory pool) as a form of cache. Vulkan Memory Allocator can help you with that by supporting a concept of "lost allocations".

-

To create an allocation that can become lost, include VMA_ALLOCATION_CREATE_CAN_BECOME_LOST_BIT flag in VmaAllocationCreateInfo::flags. Before using a buffer or image bound to such allocation in every new frame, you need to query it if it is not lost. To check it, call vmaTouchAllocation(). If the allocation is lost, you should not use it or buffer/image bound to it. You mustn't forget to destroy this allocation and this buffer/image. vmaGetAllocationInfo() can also be used for checking status of the allocation. Allocation is lost when returned VmaAllocationInfo::deviceMemory == VK_NULL_HANDLE.

-

To create an allocation that can make some other allocations lost to make room for it, use VMA_ALLOCATION_CREATE_CAN_MAKE_OTHER_LOST_BIT flag. You will usually use both flags VMA_ALLOCATION_CREATE_CAN_MAKE_OTHER_LOST_BIT and VMA_ALLOCATION_CREATE_CAN_BECOME_LOST_BIT at the same time.

-

Warning! Current implementation uses quite naive, brute force algorithm, which can make allocation calls that use VMA_ALLOCATION_CREATE_CAN_MAKE_OTHER_LOST_BIT flag quite slow. A new, more optimal algorithm and data structure to speed this up is planned for the future.

-

Q: When interleaving creation of new allocations with usage of existing ones, how do you make sure that an allocation won't become lost while it is used in the current frame?

-

It is ensured because vmaTouchAllocation() / vmaGetAllocationInfo() not only returns allocation status/parameters and checks whether it is not lost, but when it is not, it also atomically marks it as used in the current frame, which makes it impossible to become lost in that frame. It uses lockless algorithm, so it works fast and doesn't involve locking any internal mutex.

-

Q: What if my allocation may still be in use by the GPU when it is rendering a previous frame while I already submit new frame on the CPU?

-

You can make sure that allocations "touched" by vmaTouchAllocation() / vmaGetAllocationInfo() will not become lost for a number of additional frames back from the current one by specifying this number as VmaAllocatorCreateInfo::frameInUseCount (for default memory pool) and VmaPoolCreateInfo::frameInUseCount (for custom pool).

-

Q: How do you inform the library when new frame starts?

-

You need to call function vmaSetCurrentFrameIndex().

-

Example code:

+

If your game oversubscribes video memory, if may work OK in previous-generation graphics APIs (DirectX 9, 10, 11, OpenGL) because resources are automatically paged to system RAM. In Vulkan you can't do it because when you run out of memory, an allocation just fails. If you have more data (e.g. textures) that can fit into VRAM and you don't need it all at once, you may want to upload them to GPU on demand and "push out" ones that are not used for a long time to make room for the new ones, effectively using VRAM (or a cartain memory pool) as a form of cache. Vulkan Memory Allocator can help you with that by supporting a concept of "lost allocations".

+

To create an allocation that can become lost, include VMA_ALLOCATION_CREATE_CAN_BECOME_LOST_BIT flag in VmaAllocationCreateInfo::flags. Before using a buffer or image bound to such allocation in every new frame, you need to query it if it is not lost. To check it, call vmaTouchAllocation(). If the allocation is lost, you should not use it or buffer/image bound to it. You mustn't forget to destroy this allocation and this buffer/image. vmaGetAllocationInfo() can also be used for checking status of the allocation. Allocation is lost when returned VmaAllocationInfo::deviceMemory == VK_NULL_HANDLE.

+

To create an allocation that can make some other allocations lost to make room for it, use VMA_ALLOCATION_CREATE_CAN_MAKE_OTHER_LOST_BIT flag. You will usually use both flags VMA_ALLOCATION_CREATE_CAN_MAKE_OTHER_LOST_BIT and VMA_ALLOCATION_CREATE_CAN_BECOME_LOST_BIT at the same time.

+

Warning! Current implementation uses quite naive, brute force algorithm, which can make allocation calls that use VMA_ALLOCATION_CREATE_CAN_MAKE_OTHER_LOST_BIT flag quite slow. A new, more optimal algorithm and data structure to speed this up is planned for the future.

+

Q: When interleaving creation of new allocations with usage of existing ones, how do you make sure that an allocation won't become lost while it is used in the current frame?

+

It is ensured because vmaTouchAllocation() / vmaGetAllocationInfo() not only returns allocation status/parameters and checks whether it is not lost, but when it is not, it also atomically marks it as used in the current frame, which makes it impossible to become lost in that frame. It uses lockless algorithm, so it works fast and doesn't involve locking any internal mutex.

+

Q: What if my allocation may still be in use by the GPU when it is rendering a previous frame while I already submit new frame on the CPU?

+

You can make sure that allocations "touched" by vmaTouchAllocation() / vmaGetAllocationInfo() will not become lost for a number of additional frames back from the current one by specifying this number as VmaAllocatorCreateInfo::frameInUseCount (for default memory pool) and VmaPoolCreateInfo::frameInUseCount (for custom pool).

+

Q: How do you inform the library when new frame starts?

+

You need to call function vmaSetCurrentFrameIndex().

+

Example code:

struct MyBuffer
{
VkBuffer m_Buf = nullptr;
-
VmaAllocation m_Alloc = nullptr;
+
VmaAllocation m_Alloc = nullptr;
// Called when the buffer is really needed in the current frame.
void EnsureBuffer();
@@ -95,7 +95,7 @@ $(function() {
if(m_Buf != VK_NULL_HANDLE)
{
// Check if its allocation is not lost + mark it as used in current frame.
-
if(vmaTouchAllocation(allocator, m_Alloc))
+
if(vmaTouchAllocation(allocator, m_Alloc))
{
// It is all OK - safe to use m_Buf.
return;
@@ -104,39 +104,39 @@ $(function() {
// Buffer not yet exists or lost - destroy and recreate it.
-
vmaDestroyBuffer(allocator, m_Buf, m_Alloc);
+
vmaDestroyBuffer(allocator, m_Buf, m_Alloc);
VkBufferCreateInfo bufCreateInfo = { VK_STRUCTURE_TYPE_BUFFER_CREATE_INFO };
bufCreateInfo.size = 1024;
bufCreateInfo.usage = VK_BUFFER_USAGE_UNIFORM_BUFFER_BIT | VK_BUFFER_USAGE_TRANSFER_DST_BIT;
-
VmaAllocationCreateInfo allocCreateInfo = {};
-
allocCreateInfo.usage = VMA_MEMORY_USAGE_GPU_ONLY;
-
allocCreateInfo.flags = VMA_ALLOCATION_CREATE_CAN_BECOME_LOST_BIT |
-
VMA_ALLOCATION_CREATE_CAN_MAKE_OTHER_LOST_BIT;
+
VmaAllocationCreateInfo allocCreateInfo = {};
+
allocCreateInfo.usage = VMA_MEMORY_USAGE_GPU_ONLY;
+
allocCreateInfo.flags = VMA_ALLOCATION_CREATE_CAN_BECOME_LOST_BIT |
+
VMA_ALLOCATION_CREATE_CAN_MAKE_OTHER_LOST_BIT;
-
vmaCreateBuffer(allocator, &bufCreateInfo, &allocCreateInfo, &m_Buf, &m_Alloc, nullptr);
+
vmaCreateBuffer(allocator, &bufCreateInfo, &allocCreateInfo, &m_Buf, &m_Alloc, nullptr);
}
-
VmaAllocationCreateInfo
Definition: vk_mem_alloc.h:991
-
VmaAllocationCreateInfo::usage
VmaMemoryUsage usage
Intended usage of memory.
Definition: vk_mem_alloc.h:999
-
VmaAllocationCreateInfo::flags
VmaAllocationCreateFlags flags
Use VmaAllocationCreateFlagBits enum.
Definition: vk_mem_alloc.h:993
+
VmaAllocationCreateInfo
Definition: vk_mem_alloc.h:987
+
VmaAllocationCreateInfo::usage
VmaMemoryUsage usage
Intended usage of memory.
Definition: vk_mem_alloc.h:995
+
VmaAllocationCreateInfo::flags
VmaAllocationCreateFlags flags
Use VmaAllocationCreateFlagBits enum.
Definition: vk_mem_alloc.h:989
VmaAllocation
Represents single memory allocation.
vmaDestroyBuffer
void vmaDestroyBuffer(VmaAllocator allocator, VkBuffer buffer, VmaAllocation allocation)
Destroys Vulkan buffer and frees allocated memory.
vmaTouchAllocation
VkBool32 vmaTouchAllocation(VmaAllocator allocator, VmaAllocation allocation)
Returns VK_TRUE if allocation is not lost and atomically marks it as used in current frame.
-
VMA_MEMORY_USAGE_GPU_ONLY
@ VMA_MEMORY_USAGE_GPU_ONLY
Definition: vk_mem_alloc.h:833
+
VMA_MEMORY_USAGE_GPU_ONLY
@ VMA_MEMORY_USAGE_GPU_ONLY
Definition: vk_mem_alloc.h:829
vmaCreateBuffer
VkResult vmaCreateBuffer(VmaAllocator allocator, const VkBufferCreateInfo *pBufferCreateInfo, const VmaAllocationCreateInfo *pAllocationCreateInfo, VkBuffer *pBuffer, VmaAllocation *pAllocation, VmaAllocationInfo *pAllocationInfo)
-
VMA_ALLOCATION_CREATE_CAN_BECOME_LOST_BIT
@ VMA_ALLOCATION_CREATE_CAN_BECOME_LOST_BIT
Definition: vk_mem_alloc.h:923
-
VMA_ALLOCATION_CREATE_CAN_MAKE_OTHER_LOST_BIT
@ VMA_ALLOCATION_CREATE_CAN_MAKE_OTHER_LOST_BIT
Definition: vk_mem_alloc.h:930
-

When using lost allocations, you may see some Vulkan validation layer warnings about overlapping regions of memory bound to different kinds of buffers and images. This is still valid as long as you implement proper handling of lost allocations (like in the example above) and don't use them.

-

You can create an allocation that is already in lost state from the beginning using function vmaCreateLostAllocation(). It may be useful if you need a "dummy" allocation that is not null.

-

You can call function vmaMakePoolAllocationsLost() to set all eligible allocations in a specified custom pool to lost state. Allocations that have been "touched" in current frame or VmaPoolCreateInfo::frameInUseCount frames back cannot become lost.

-

Q: Can I touch allocation that cannot become lost?

-

Yes, although it has no visible effect. Calls to vmaGetAllocationInfo() and vmaTouchAllocation() update last use frame index also for allocations that cannot become lost, but the only way to observe it is to dump internal allocator state using vmaBuildStatsString(). You can use this feature for debugging purposes to explicitly mark allocations that you use in current frame and then analyze JSON dump to see for how long each allocation stays unused.

+
VMA_ALLOCATION_CREATE_CAN_BECOME_LOST_BIT
@ VMA_ALLOCATION_CREATE_CAN_BECOME_LOST_BIT
Definition: vk_mem_alloc.h:919
+
VMA_ALLOCATION_CREATE_CAN_MAKE_OTHER_LOST_BIT
@ VMA_ALLOCATION_CREATE_CAN_MAKE_OTHER_LOST_BIT
Definition: vk_mem_alloc.h:926
+

When using lost allocations, you may see some Vulkan validation layer warnings about overlapping regions of memory bound to different kinds of buffers and images. This is still valid as long as you implement proper handling of lost allocations (like in the example above) and don't use them.

+

You can create an allocation that is already in lost state from the beginning using function vmaCreateLostAllocation(). It may be useful if you need a "dummy" allocation that is not null.

+

You can call function vmaMakePoolAllocationsLost() to set all eligible allocations in a specified custom pool to lost state. Allocations that have been "touched" in current frame or VmaPoolCreateInfo::frameInUseCount frames back cannot become lost.

+

Q: Can I touch allocation that cannot become lost?

+

Yes, although it has no visible effect. Calls to vmaGetAllocationInfo() and vmaTouchAllocation() update last use frame index also for allocations that cannot become lost, but the only way to observe it is to dump internal allocator state using vmaBuildStatsString(). You can use this feature for debugging purposes to explicitly mark allocations that you use in current frame and then analyze JSON dump to see for how long each allocation stays unused.

-Generated by doxygen 1.9.1 +Generated by doxygen 1.9.2
diff --git a/docs/html/memory_mapping.html b/docs/html/memory_mapping.html index 54933c6..a772859 100644 --- a/docs/html/memory_mapping.html +++ b/docs/html/memory_mapping.html @@ -2,8 +2,8 @@ - - + + Vulkan Memory Allocator: Memory mapping @@ -29,21 +29,22 @@
- + +/* @license-end */ +
-
-
-
Memory mapping
+
+
Memory mapping
-

To "map memory" in Vulkan means to obtain a CPU pointer to VkDeviceMemory, to be able to read from it or write to it in CPU code. Mapping is possible only of memory allocated from a memory type that has VK_MEMORY_PROPERTY_HOST_VISIBLE_BIT flag. Functions vkMapMemory(), vkUnmapMemory() are designed for this purpose. You can use them directly with memory allocated by this library, but it is not recommended because of following issue: Mapping the same VkDeviceMemory block multiple times is illegal - only one mapping at a time is allowed. This includes mapping disjoint regions. Mapping is not reference-counted internally by Vulkan. Because of this, Vulkan Memory Allocator provides following facilities:

+

To "map memory" in Vulkan means to obtain a CPU pointer to VkDeviceMemory, to be able to read from it or write to it in CPU code. Mapping is possible only of memory allocated from a memory type that has VK_MEMORY_PROPERTY_HOST_VISIBLE_BIT flag. Functions vkMapMemory(), vkUnmapMemory() are designed for this purpose. You can use them directly with memory allocated by this library, but it is not recommended because of following issue: Mapping the same VkDeviceMemory block multiple times is illegal - only one mapping at a time is allowed. This includes mapping disjoint regions. Mapping is not reference-counted internally by Vulkan. Because of this, Vulkan Memory Allocator provides following facilities:

Mapping functions

-

The library provides following functions for mapping of a specific VmaAllocation: vmaMapMemory(), vmaUnmapMemory(). They are safer and more convenient to use than standard Vulkan functions. You can map an allocation multiple times simultaneously - mapping is reference-counted internally. You can also map different allocations simultaneously regardless of whether they use the same VkDeviceMemory block. The way it is implemented is that the library always maps entire memory block, not just region of the allocation. For further details, see description of vmaMapMemory() function. Example:

+

The library provides following functions for mapping of a specific VmaAllocation: vmaMapMemory(), vmaUnmapMemory(). They are safer and more convenient to use than standard Vulkan functions. You can map an allocation multiple times simultaneously - mapping is reference-counted internally. You can also map different allocations simultaneously regardless of whether they use the same VkDeviceMemory block. The way it is implemented is that the library always maps entire memory block, not just region of the allocation. For further details, see description of vmaMapMemory() function. Example:

// Having these objects initialized:
struct ConstantBuffer
@@ -81,115 +81,115 @@ Mapping functions
};
ConstantBuffer constantBufferData;
-
VmaAllocator allocator;
+
VmaAllocator allocator;
VkBuffer constantBuffer;
-
VmaAllocation constantBufferAllocation;
+
VmaAllocation constantBufferAllocation;
// You can map and fill your buffer using following code:
void* mappedData;
-
vmaMapMemory(allocator, constantBufferAllocation, &mappedData);
+
vmaMapMemory(allocator, constantBufferAllocation, &mappedData);
memcpy(mappedData, &constantBufferData, sizeof(constantBufferData));
-
vmaUnmapMemory(allocator, constantBufferAllocation);
+
vmaUnmapMemory(allocator, constantBufferAllocation);
VmaAllocation
Represents single memory allocation.
VmaAllocator
Represents main object of this library initialized.
vmaUnmapMemory
void vmaUnmapMemory(VmaAllocator allocator, VmaAllocation allocation)
Unmaps memory represented by given allocation, mapped previously using vmaMapMemory().
vmaMapMemory
VkResult vmaMapMemory(VmaAllocator allocator, VmaAllocation allocation, void **ppData)
Maps memory represented by given allocation and returns pointer to it.
-

When mapping, you may see a warning from Vulkan validation layer similar to this one:

-

Mapping an image with layout VK_IMAGE_LAYOUT_DEPTH_STENCIL_ATTACHMENT_OPTIMAL can result in undefined behavior if this memory is used by the device. Only GENERAL or PREINITIALIZED should be used.

-

It happens because the library maps entire VkDeviceMemory block, where different types of images and buffers may end up together, especially on GPUs with unified memory like Intel. You can safely ignore it if you are sure you access only memory of the intended object that you wanted to map.

+

When mapping, you may see a warning from Vulkan validation layer similar to this one:

+

Mapping an image with layout VK_IMAGE_LAYOUT_DEPTH_STENCIL_ATTACHMENT_OPTIMAL can result in undefined behavior if this memory is used by the device. Only GENERAL or PREINITIALIZED should be used.

+

It happens because the library maps entire VkDeviceMemory block, where different types of images and buffers may end up together, especially on GPUs with unified memory like Intel. You can safely ignore it if you are sure you access only memory of the intended object that you wanted to map.

Persistently mapped memory

-

Kepping your memory persistently mapped is generally OK in Vulkan. You don't need to unmap it before using its data on the GPU. The library provides a special feature designed for that: Allocations made with VMA_ALLOCATION_CREATE_MAPPED_BIT flag set in VmaAllocationCreateInfo::flags stay mapped all the time, so you can just access CPU pointer to it any time without a need to call any "map" or "unmap" function. Example:

+

Kepping your memory persistently mapped is generally OK in Vulkan. You don't need to unmap it before using its data on the GPU. The library provides a special feature designed for that: Allocations made with VMA_ALLOCATION_CREATE_MAPPED_BIT flag set in VmaAllocationCreateInfo::flags stay mapped all the time, so you can just access CPU pointer to it any time without a need to call any "map" or "unmap" function. Example:

VkBufferCreateInfo bufCreateInfo = { VK_STRUCTURE_TYPE_BUFFER_CREATE_INFO };
bufCreateInfo.size = sizeof(ConstantBuffer);
bufCreateInfo.usage = VK_BUFFER_USAGE_TRANSFER_SRC_BIT;
-
VmaAllocationCreateInfo allocCreateInfo = {};
-
allocCreateInfo.usage = VMA_MEMORY_USAGE_CPU_ONLY;
-
allocCreateInfo.flags = VMA_ALLOCATION_CREATE_MAPPED_BIT;
+
VmaAllocationCreateInfo allocCreateInfo = {};
+
allocCreateInfo.usage = VMA_MEMORY_USAGE_CPU_ONLY;
+
allocCreateInfo.flags = VMA_ALLOCATION_CREATE_MAPPED_BIT;
VkBuffer buf;
-
VmaAllocation alloc;
-
VmaAllocationInfo allocInfo;
-
vmaCreateBuffer(allocator, &bufCreateInfo, &allocCreateInfo, &buf, &alloc, &allocInfo);
+
VmaAllocation alloc;
+
VmaAllocationInfo allocInfo;
+
vmaCreateBuffer(allocator, &bufCreateInfo, &allocCreateInfo, &buf, &alloc, &allocInfo);
// Buffer is already mapped. You can access its memory.
-
memcpy(allocInfo.pMappedData, &constantBufferData, sizeof(constantBufferData));
-
VmaAllocationCreateInfo
Definition: vk_mem_alloc.h:991
-
VmaAllocationCreateInfo::usage
VmaMemoryUsage usage
Intended usage of memory.
Definition: vk_mem_alloc.h:999
-
VmaAllocationCreateInfo::flags
VmaAllocationCreateFlags flags
Use VmaAllocationCreateFlagBits enum.
Definition: vk_mem_alloc.h:993
-
VmaAllocationInfo
Parameters of VmaAllocation objects, that can be retrieved using function vmaGetAllocationInfo().
Definition: vk_mem_alloc.h:1358
-
VmaAllocationInfo::pMappedData
void * pMappedData
Pointer to the beginning of this allocation as mapped data.
Definition: vk_mem_alloc.h:1402
-
VMA_MEMORY_USAGE_CPU_ONLY
@ VMA_MEMORY_USAGE_CPU_ONLY
Definition: vk_mem_alloc.h:843
+
memcpy(allocInfo.pMappedData, &constantBufferData, sizeof(constantBufferData));
+
VmaAllocationCreateInfo
Definition: vk_mem_alloc.h:987
+
VmaAllocationCreateInfo::usage
VmaMemoryUsage usage
Intended usage of memory.
Definition: vk_mem_alloc.h:995
+
VmaAllocationCreateInfo::flags
VmaAllocationCreateFlags flags
Use VmaAllocationCreateFlagBits enum.
Definition: vk_mem_alloc.h:989
+
VmaAllocationInfo
Parameters of VmaAllocation objects, that can be retrieved using function vmaGetAllocationInfo().
Definition: vk_mem_alloc.h:1354
+
VmaAllocationInfo::pMappedData
void * pMappedData
Pointer to the beginning of this allocation as mapped data.
Definition: vk_mem_alloc.h:1398
+
VMA_MEMORY_USAGE_CPU_ONLY
@ VMA_MEMORY_USAGE_CPU_ONLY
Definition: vk_mem_alloc.h:839
vmaCreateBuffer
VkResult vmaCreateBuffer(VmaAllocator allocator, const VkBufferCreateInfo *pBufferCreateInfo, const VmaAllocationCreateInfo *pAllocationCreateInfo, VkBuffer *pBuffer, VmaAllocation *pAllocation, VmaAllocationInfo *pAllocationInfo)
-
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:910
-

There are some exceptions though, when you should consider mapping memory only for a short period of time:

+
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:906
+

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.
  • Keeping many large memory blocks mapped may impact performance or stability of some debugging tools.

Cache flush and invalidate

-

Memory in Vulkan doesn't need to be unmapped before using it on GPU, but unless a memory types has VK_MEMORY_PROPERTY_HOST_COHERENT_BIT flag set, you need to manually invalidate cache before reading of mapped pointer and flush cache after writing to mapped pointer. Map/unmap operations don't do that automatically. Vulkan provides following functions for this purpose vkFlushMappedMemoryRanges(), vkInvalidateMappedMemoryRanges(), but this library provides more convenient functions that refer to given allocation object: vmaFlushAllocation(), vmaInvalidateAllocation(), or multiple objects at once: vmaFlushAllocations(), vmaInvalidateAllocations().

-

Regions of memory specified for flush/invalidate must be aligned to VkPhysicalDeviceLimits::nonCoherentAtomSize. This is automatically ensured by the library. In any memory type that is HOST_VISIBLE but not HOST_COHERENT, all allocations within blocks are aligned to this value, so their offsets are always multiply of nonCoherentAtomSize and two different allocations never share same "line" of this size.

-

Please note that memory allocated with VMA_MEMORY_USAGE_CPU_ONLY is guaranteed to be HOST_COHERENT.

-

Also, Windows drivers from all 3 PC GPU vendors (AMD, Intel, NVIDIA) currently provide HOST_COHERENT flag on all memory types that are HOST_VISIBLE, so on this platform you may not need to bother.

+

Memory in Vulkan doesn't need to be unmapped before using it on GPU, but unless a memory types has VK_MEMORY_PROPERTY_HOST_COHERENT_BIT flag set, you need to manually invalidate cache before reading of mapped pointer and flush cache after writing to mapped pointer. Map/unmap operations don't do that automatically. Vulkan provides following functions for this purpose vkFlushMappedMemoryRanges(), vkInvalidateMappedMemoryRanges(), but this library provides more convenient functions that refer to given allocation object: vmaFlushAllocation(), vmaInvalidateAllocation(), or multiple objects at once: vmaFlushAllocations(), vmaInvalidateAllocations().

+

Regions of memory specified for flush/invalidate must be aligned to VkPhysicalDeviceLimits::nonCoherentAtomSize. This is automatically ensured by the library. In any memory type that is HOST_VISIBLE but not HOST_COHERENT, all allocations within blocks are aligned to this value, so their offsets are always multiply of nonCoherentAtomSize and two different allocations never share same "line" of this size.

+

Please note that memory allocated with VMA_MEMORY_USAGE_CPU_ONLY is guaranteed to be HOST_COHERENT.

+

Also, Windows drivers from all 3 PC GPU vendors (AMD, Intel, NVIDIA) currently provide HOST_COHERENT flag on all memory types that are HOST_VISIBLE, so on this platform you may not need to bother.

Finding out if memory is mappable

-

It may happen that your allocation ends up in memory that is HOST_VISIBLE (available for mapping) despite it wasn't explicitly requested. For example, application may work on integrated graphics with unified memory (like Intel) or allocation from video memory might have failed, so the library chose system memory as fallback.

-

You can detect this case and map such allocation to access its memory on CPU directly, instead of launching a transfer operation. In order to do that: inspect allocInfo.memoryType, call vmaGetMemoryTypeProperties(), and look for VK_MEMORY_PROPERTY_HOST_VISIBLE_BIT flag in properties of that memory type.

+

It may happen that your allocation ends up in memory that is HOST_VISIBLE (available for mapping) despite it wasn't explicitly requested. For example, application may work on integrated graphics with unified memory (like Intel) or allocation from video memory might have failed, so the library chose system memory as fallback.

+

You can detect this case and map such allocation to access its memory on CPU directly, instead of launching a transfer operation. In order to do that: inspect allocInfo.memoryType, call vmaGetMemoryTypeProperties(), and look for VK_MEMORY_PROPERTY_HOST_VISIBLE_BIT flag in properties of that memory type.

VkBufferCreateInfo bufCreateInfo = { VK_STRUCTURE_TYPE_BUFFER_CREATE_INFO };
bufCreateInfo.size = sizeof(ConstantBuffer);
bufCreateInfo.usage = VK_BUFFER_USAGE_UNIFORM_BUFFER_BIT | VK_BUFFER_USAGE_TRANSFER_DST_BIT;
-
VmaAllocationCreateInfo allocCreateInfo = {};
-
allocCreateInfo.usage = VMA_MEMORY_USAGE_GPU_ONLY;
-
allocCreateInfo.preferredFlags = VK_MEMORY_PROPERTY_HOST_VISIBLE_BIT;
+
VmaAllocationCreateInfo allocCreateInfo = {};
+
allocCreateInfo.usage = VMA_MEMORY_USAGE_GPU_ONLY;
+
allocCreateInfo.preferredFlags = VK_MEMORY_PROPERTY_HOST_VISIBLE_BIT;
VkBuffer buf;
-
VmaAllocation alloc;
-
VmaAllocationInfo allocInfo;
-
vmaCreateBuffer(allocator, &bufCreateInfo, &allocCreateInfo, &buf, &alloc, &allocInfo);
+
VmaAllocation alloc;
+
VmaAllocationInfo allocInfo;
+
vmaCreateBuffer(allocator, &bufCreateInfo, &allocCreateInfo, &buf, &alloc, &allocInfo);
VkMemoryPropertyFlags memFlags;
-
vmaGetMemoryTypeProperties(allocator, allocInfo.memoryType, &memFlags);
+
vmaGetMemoryTypeProperties(allocator, allocInfo.memoryType, &memFlags);
if((memFlags & VK_MEMORY_PROPERTY_HOST_VISIBLE_BIT) != 0)
{
// Allocation ended up in mappable memory. You can map it and access it directly.
void* mappedData;
-
vmaMapMemory(allocator, alloc, &mappedData);
+
vmaMapMemory(allocator, alloc, &mappedData);
memcpy(mappedData, &constantBufferData, sizeof(constantBufferData));
-
vmaUnmapMemory(allocator, alloc);
+
vmaUnmapMemory(allocator, alloc);
}
else
{
// Allocation ended up in non-mappable memory.
// You need to create CPU-side buffer in VMA_MEMORY_USAGE_CPU_ONLY and make a transfer.
}
-
VmaAllocationCreateInfo::preferredFlags
VkMemoryPropertyFlags preferredFlags
Flags that preferably should be set in a memory type chosen for an allocation.
Definition: vk_mem_alloc.h:1009
-
VmaAllocationInfo::memoryType
uint32_t memoryType
Memory type index that this allocation was allocated from.
Definition: vk_mem_alloc.h:1363
+
VmaAllocationCreateInfo::preferredFlags
VkMemoryPropertyFlags preferredFlags
Flags that preferably should be set in a memory type chosen for an allocation.
Definition: vk_mem_alloc.h:1005
+
VmaAllocationInfo::memoryType
uint32_t memoryType
Memory type index that this allocation was allocated from.
Definition: vk_mem_alloc.h:1359
vmaGetMemoryTypeProperties
void vmaGetMemoryTypeProperties(VmaAllocator allocator, uint32_t memoryTypeIndex, VkMemoryPropertyFlags *pFlags)
Given Memory Type Index, returns Property Flags of this memory type.
-
VMA_MEMORY_USAGE_GPU_ONLY
@ VMA_MEMORY_USAGE_GPU_ONLY
Definition: vk_mem_alloc.h:833
-

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:

+
VMA_MEMORY_USAGE_GPU_ONLY
@ VMA_MEMORY_USAGE_GPU_ONLY
Definition: vk_mem_alloc.h:829
+

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);
bufCreateInfo.usage = VK_BUFFER_USAGE_UNIFORM_BUFFER_BIT | VK_BUFFER_USAGE_TRANSFER_DST_BIT;
-
VmaAllocationCreateInfo allocCreateInfo = {};
-
allocCreateInfo.usage = VMA_MEMORY_USAGE_GPU_ONLY;
-
allocCreateInfo.flags = VMA_ALLOCATION_CREATE_MAPPED_BIT;
+
VmaAllocationCreateInfo allocCreateInfo = {};
+
allocCreateInfo.usage = VMA_MEMORY_USAGE_GPU_ONLY;
+
allocCreateInfo.flags = VMA_ALLOCATION_CREATE_MAPPED_BIT;
VkBuffer buf;
-
VmaAllocation alloc;
-
VmaAllocationInfo allocInfo;
-
vmaCreateBuffer(allocator, &bufCreateInfo, &allocCreateInfo, &buf, &alloc, &allocInfo);
+
VmaAllocation alloc;
+
VmaAllocationInfo allocInfo;
+
vmaCreateBuffer(allocator, &bufCreateInfo, &allocCreateInfo, &buf, &alloc, &allocInfo);
-
if(allocInfo.pMappedData != nullptr)
+
if(allocInfo.pMappedData != nullptr)
{
// Allocation ended up in mappable memory.
// It is persistently mapped. You can access it directly.
-
memcpy(allocInfo.pMappedData, &constantBufferData, sizeof(constantBufferData));
+
memcpy(allocInfo.pMappedData, &constantBufferData, sizeof(constantBufferData));
}
else
{
@@ -200,7 +200,7 @@ Finding out if memory is mappable
-Generated by doxygen 1.9.1 +Generated by doxygen 1.9.2
diff --git a/docs/html/menu.js b/docs/html/menu.js index 2fe2214..54e81cf 100644 --- a/docs/html/menu.js +++ b/docs/html/menu.js @@ -36,16 +36,92 @@ function initMenu(relPath,searchEnabled,serverSide,searchPage,search) { } return result; } - - $('#main-nav').append(makeTree(menudata,relPath)); - $('#main-nav').children(':first').addClass('sm sm-dox').attr('id','main-menu'); + var searchBox; if (searchEnabled) { if (serverSide) { - $('#main-menu').append('
    • '); + searchBox='
    '+ + '
    '+ + '
    '+ + ''+ + '
    '+ + '
    '+ + '
    '+ + '
    '; } else { - $('#main-menu').append('
    • '); + searchBox='
    '+ + ''+ + ''+ + ''+ + ''+ + ''+ + '' + '' + '
    '; } } + + $('#main-nav').before('
    '+ + ''+ + ''+ + '
    '); + $('#main-nav').append(makeTree(menudata,relPath)); + $('#main-nav').children(':first').addClass('sm sm-dox').attr('id','main-menu'); + if (searchBox) { + $('#main-menu').append('
  • '); + } + var $mainMenuState = $('#main-menu-state'); + var prevWidth = 0; + if ($mainMenuState.length) { + function initResizableIfExists() { + if (typeof initResizable==='function') initResizable(); + } + // animate mobile menu + $mainMenuState.change(function(e) { + var $menu = $('#main-menu'); + var options = { duration: 250, step: initResizableIfExists }; + if (this.checked) { + options['complete'] = function() { $menu.css('display', 'block') }; + $menu.hide().slideDown(options); + } else { + options['complete'] = function() { $menu.css('display', 'none') }; + $menu.show().slideUp(options); + } + }); + // set default menu visibility + function resetState() { + var $menu = $('#main-menu'); + var $mainMenuState = $('#main-menu-state'); + var newWidth = $(window).outerWidth(); + if (newWidth!=prevWidth) { + if ($(window).outerWidth()<768) { + $mainMenuState.prop('checked',false); $menu.hide(); + $('#searchBoxPos1').html(searchBox); + $('#searchBoxPos2').hide(); + } else { + $menu.show(); + $('#searchBoxPos1').empty(); + $('#searchBoxPos2').html(searchBox); + $('#searchBoxPos2').show(); + } + prevWidth = newWidth; + } + } + $(window).ready(function() { resetState(); initResizableIfExists(); }); + $(window).resize(resetState); + } $('#main-menu').smartmenus(); } /* @license-end */ diff --git a/docs/html/opengl_interop.html b/docs/html/opengl_interop.html index dad3455..12911a7 100644 --- a/docs/html/opengl_interop.html +++ b/docs/html/opengl_interop.html @@ -2,8 +2,8 @@ - - + + Vulkan Memory Allocator: OpenGL Interop @@ -29,21 +29,22 @@
    - + +/* @license-end */ +
    -
    -
    -
    OpenGL Interop
    +
    +
    OpenGL Interop
    -

    VMA provides some features that help with interoperability with OpenGL.

    +

    VMA provides some features that help with interoperability with OpenGL.

    Exporting memory

    -

    If you want to attach VkExportMemoryAllocateInfoKHR structure to pNext chain of memory allocations made by the library:

    -

    It is recommended to create Custom memory pools for such allocations. Define and fill in your VkExportMemoryAllocateInfoKHR structure and attach it to VmaPoolCreateInfo::pMemoryAllocateNext while creating the custom pool. Please note that the structure must remain alive and unchanged for the whole lifetime of the VmaPool, not only while creating it, as no copy of the structure is made, but its original pointer is used for each allocation instead.

    -

    If you want to export all memory allocated by the library from certain memory types, also dedicated allocations or other allocations made from default pools, an alternative solution is to fill in VmaAllocatorCreateInfo::pTypeExternalMemoryHandleTypes. It should point to an array with VkExternalMemoryHandleTypeFlagsKHR to be automatically passed by the library through VkExportMemoryAllocateInfoKHR on each allocation made from a specific memory type. This is currently the only method to use if you need exported dedicated allocations, as they cannot be created out of custom pools. This will change in future versions of the library though.

    -

    You should not mix these two methods in a way that allows to apply both to the same memory type. Otherwise, VkExportMemoryAllocateInfoKHR structure would be attached twice to the pNext chain of VkMemoryAllocateInfo.

    +

    If you want to attach VkExportMemoryAllocateInfoKHR structure to pNext chain of memory allocations made by the library:

    +

    It is recommended to create Custom memory pools for such allocations. Define and fill in your VkExportMemoryAllocateInfoKHR structure and attach it to VmaPoolCreateInfo::pMemoryAllocateNext while creating the custom pool. Please note that the structure must remain alive and unchanged for the whole lifetime of the VmaPool, not only while creating it, as no copy of the structure is made, but its original pointer is used for each allocation instead.

    +

    If you want to export all memory allocated by the library from certain memory types, also dedicated allocations or other allocations made from default pools, an alternative solution is to fill in VmaAllocatorCreateInfo::pTypeExternalMemoryHandleTypes. It should point to an array with VkExternalMemoryHandleTypeFlagsKHR to be automatically passed by the library through VkExportMemoryAllocateInfoKHR on each allocation made from a specific memory type. This is currently the only method to use if you need exported dedicated allocations, as they cannot be created out of custom pools. This will change in future versions of the library though.

    +

    You should not mix these two methods in a way that allows to apply both to the same memory type. Otherwise, VkExportMemoryAllocateInfoKHR structure would be attached twice to the pNext chain of VkMemoryAllocateInfo.

    Custom alignment

    -

    Buffers or images exported to a different API like OpenGL may require a different alignment, higher than the one used by the library automatically, queried from functions like vkGetBufferMemoryRequirements. To impose such alignment:

    -

    It is recommended to create Custom memory pools for such allocations. Set VmaPoolCreateInfo::minAllocationAlignment member to the minimum alignment required for each allocation to be made out of this pool. The alignment actually used will be the maximum of this member and the alignment returned for the specific buffer or image from a function like vkGetBufferMemoryRequirements, which is called by VMA automatically.

    -

    If you want to create a buffer with a specific minimum alignment out of default pools, use special function vmaCreateBufferWithAlignment(), which takes additional parameter minAlignment. This is currently the only method to use if you need exported dedicated allocations, as they cannot be created out of custom pools. This will change in future versions of the library though.

    -

    Note the problem of alignment affects only resources placed inside bigger VkDeviceMemory blocks and not dedicated allocations, as these, by definition, always have alignment = 0 because the resource is bound to the beginning of its dedicated block. Contrary to Direct3D 12, Vulkan doesn't have a concept of alignment of the entire memory block passed on its allocation.

    +

    Buffers or images exported to a different API like OpenGL may require a different alignment, higher than the one used by the library automatically, queried from functions like vkGetBufferMemoryRequirements. To impose such alignment:

    +

    It is recommended to create Custom memory pools for such allocations. Set VmaPoolCreateInfo::minAllocationAlignment member to the minimum alignment required for each allocation to be made out of this pool. The alignment actually used will be the maximum of this member and the alignment returned for the specific buffer or image from a function like vkGetBufferMemoryRequirements, which is called by VMA automatically.

    +

    If you want to create a buffer with a specific minimum alignment out of default pools, use special function vmaCreateBufferWithAlignment(), which takes additional parameter minAlignment. This is currently the only method to use if you need exported dedicated allocations, as they cannot be created out of custom pools. This will change in future versions of the library though.

    +

    Note the problem of alignment affects only resources placed inside bigger VkDeviceMemory blocks and not dedicated allocations, as these, by definition, always have alignment = 0 because the resource is bound to the beginning of its dedicated block. Contrary to Direct3D 12, Vulkan doesn't have a concept of alignment of the entire memory block passed on its allocation.

    -Generated by doxygen 1.9.1 +Generated by doxygen 1.9.2
    diff --git a/docs/html/pages.html b/docs/html/pages.html index 6525b8f..f8dfeda 100644 --- a/docs/html/pages.html +++ b/docs/html/pages.html @@ -2,8 +2,8 @@ - - + + Vulkan Memory Allocator: Related Pages @@ -29,21 +29,22 @@
    - + +/* @license-end */ +
    @@ -61,8 +62,7 @@ $(function() {
    -
    -
    Related Pages
    +
    Related Pages
    Here is a list of all related documentation pages:
    @@ -73,7 +73,7 @@ $(function() {
    -Generated by doxygen 1.9.1 +Generated by doxygen 1.9.2
    diff --git a/docs/html/quick_start.html b/docs/html/quick_start.html index be980ca..632b350 100644 --- a/docs/html/quick_start.html +++ b/docs/html/quick_start.html @@ -2,8 +2,8 @@ - - + + Vulkan Memory Allocator: Quick start @@ -29,21 +29,22 @@
    - + +/* @license-end */ +
    -
    -
    -
    Quick start
    +
    +
    Quick start

    Project setup

    -

    Vulkan Memory Allocator comes in form of a "stb-style" single header file. You don't need to build it as a separate library project. You can add this file directly to your project and submit it to code repository next to your other source files.

    -

    "Single header" doesn't mean that everything is contained in C/C++ declarations, like it tends to be in case of inline functions or C++ templates. It means that implementation is bundled with interface in a single file and needs to be extracted using preprocessor macro. If you don't do it properly, you will get linker errors.

    -

    To do it properly:

    +

    Vulkan Memory Allocator comes in form of a "stb-style" single header file. You don't need to build it as a separate library project. You can add this file directly to your project and submit it to code repository next to your other source files.

    +

    "Single header" doesn't mean that everything is contained in C/C++ declarations, like it tends to be in case of inline functions or C++ templates. It means that implementation is bundled with interface in a single file and needs to be extracted using preprocessor macro. If you don't do it properly, you will get linker errors.

    +

    To do it properly:

    1. Include "vk_mem_alloc.h" file in each CPP file where you want to use the library. This includes declarations of all members of the library.
    2. In exactly one CPP file define following macro before this include. It enables also internal definitions.
    #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.

    +

    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 make sure vkGetInstanceProcAddr and vkGetDeviceProcAddr globals are defined. All the remaining Vulkan functions will be fetched automatically.
      • @@ -91,30 +91,30 @@ Project setup

    Initialization

    -

    At program startup:

    +

    At program startup:

    1. Initialize Vulkan to have VkPhysicalDevice, VkDevice and VkInstance object.
    2. Fill VmaAllocatorCreateInfo structure and create VmaAllocator object by calling vmaCreateAllocator().
    -
    VmaAllocatorCreateInfo allocatorInfo = {};
    -
    allocatorInfo.vulkanApiVersion = VK_API_VERSION_1_2;
    -
    allocatorInfo.physicalDevice = physicalDevice;
    -
    allocatorInfo.device = device;
    -
    allocatorInfo.instance = instance;
    +
    VmaAllocatorCreateInfo allocatorInfo = {};
    +
    allocatorInfo.vulkanApiVersion = VK_API_VERSION_1_2;
    +
    allocatorInfo.physicalDevice = physicalDevice;
    +
    allocatorInfo.device = device;
    +
    allocatorInfo.instance = instance;
    -
    VmaAllocator allocator;
    -
    vmaCreateAllocator(&allocatorInfo, &allocator);
    -
    VmaAllocatorCreateInfo
    Description of a Allocator to be created.
    Definition: vk_mem_alloc.h:509
    -
    VmaAllocatorCreateInfo::physicalDevice
    VkPhysicalDevice physicalDevice
    Vulkan physical device.
    Definition: vk_mem_alloc.h:514
    -
    VmaAllocatorCreateInfo::instance
    VkInstance instance
    Handle to Vulkan instance object.
    Definition: vk_mem_alloc.h:583
    -
    VmaAllocatorCreateInfo::device
    VkDevice device
    Vulkan device.
    Definition: vk_mem_alloc.h:517
    -
    VmaAllocatorCreateInfo::vulkanApiVersion
    uint32_t vulkanApiVersion
    Optional. The highest version of Vulkan that the application is designed to use.
    Definition: vk_mem_alloc.h:592
    +
    VmaAllocator allocator;
    +
    vmaCreateAllocator(&allocatorInfo, &allocator);
    +
    VmaAllocatorCreateInfo
    Description of a Allocator to be created.
    Definition: vk_mem_alloc.h:505
    +
    VmaAllocatorCreateInfo::physicalDevice
    VkPhysicalDevice physicalDevice
    Vulkan physical device.
    Definition: vk_mem_alloc.h:510
    +
    VmaAllocatorCreateInfo::instance
    VkInstance instance
    Handle to Vulkan instance object.
    Definition: vk_mem_alloc.h:579
    +
    VmaAllocatorCreateInfo::device
    VkDevice device
    Vulkan device.
    Definition: vk_mem_alloc.h:513
    +
    VmaAllocatorCreateInfo::vulkanApiVersion
    uint32_t vulkanApiVersion
    Optional. The highest version of Vulkan that the application is designed to use.
    Definition: vk_mem_alloc.h:588
    VmaAllocator
    Represents main object of this library initialized.
    vmaCreateAllocator
    VkResult vmaCreateAllocator(const VmaAllocatorCreateInfo *pCreateInfo, VmaAllocator *pAllocator)
    Creates Allocator object.
    -

    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.

    +

    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.

    Resource allocation

    -

    When you want to create a buffer or image:

    +

    When you want to create a buffer or image:

    1. Fill VkBufferCreateInfo / VkImageCreateInfo structure.
    2. Fill VmaAllocationCreateInfo structure.
      3. @@ -124,27 +124,27 @@ Resource allocation
      bufferInfo.size = 65536;
      bufferInfo.usage = VK_BUFFER_USAGE_VERTEX_BUFFER_BIT | VK_BUFFER_USAGE_TRANSFER_DST_BIT;
      -
      VmaAllocationCreateInfo allocInfo = {};
      -
      allocInfo.usage = VMA_MEMORY_USAGE_GPU_ONLY;
      +
      VmaAllocationCreateInfo allocInfo = {};
      +
      allocInfo.usage = VMA_MEMORY_USAGE_GPU_ONLY;
      VkBuffer buffer;
      -
      VmaAllocation allocation;
      -
      vmaCreateBuffer(allocator, &bufferInfo, &allocInfo, &buffer, &allocation, nullptr);
      -
      VmaAllocationCreateInfo
      Definition: vk_mem_alloc.h:991
      -
      VmaAllocationCreateInfo::usage
      VmaMemoryUsage usage
      Intended usage of memory.
      Definition: vk_mem_alloc.h:999
      +
      VmaAllocation allocation;
      +
      vmaCreateBuffer(allocator, &bufferInfo, &allocInfo, &buffer, &allocation, nullptr);
      +
      VmaAllocationCreateInfo
      Definition: vk_mem_alloc.h:987
      +
      VmaAllocationCreateInfo::usage
      VmaMemoryUsage usage
      Intended usage of memory.
      Definition: vk_mem_alloc.h:995
      VmaAllocation
      Represents single memory allocation.
      -
      VMA_MEMORY_USAGE_GPU_ONLY
      @ VMA_MEMORY_USAGE_GPU_ONLY
      Definition: vk_mem_alloc.h:833
      +
      VMA_MEMORY_USAGE_GPU_ONLY
      @ VMA_MEMORY_USAGE_GPU_ONLY
      Definition: vk_mem_alloc.h:829
      vmaCreateBuffer
      VkResult vmaCreateBuffer(VmaAllocator allocator, const VkBufferCreateInfo *pBufferCreateInfo, const VmaAllocationCreateInfo *pAllocationCreateInfo, VkBuffer *pBuffer, VmaAllocation *pAllocation, VmaAllocationInfo *pAllocationInfo)
      -

    Don't forget to destroy your objects when no longer needed:

    -
    vmaDestroyBuffer(allocator, buffer, allocation);
    -
    vmaDestroyAllocator(allocator);
    +

    Don't forget to destroy your objects when no longer needed:

    +
    vmaDestroyBuffer(allocator, buffer, allocation);
    +
    vmaDestroyAllocator(allocator);
    vmaDestroyBuffer
    void vmaDestroyBuffer(VmaAllocator allocator, VkBuffer buffer, VmaAllocation allocation)
    Destroys Vulkan buffer and frees allocated memory.
    vmaDestroyAllocator
    void vmaDestroyAllocator(VmaAllocator allocator)
    Destroys allocator object.
    -Generated by doxygen 1.9.1 +Generated by doxygen 1.9.2
    diff --git a/docs/html/record_and_replay.html b/docs/html/record_and_replay.html index 695e846..3d2359c 100644 --- a/docs/html/record_and_replay.html +++ b/docs/html/record_and_replay.html @@ -2,8 +2,8 @@ - - + + Vulkan Memory Allocator: Record and replay @@ -29,21 +29,22 @@
    - + +/* @license-end */ +
    -
    -
    -
    Record and replay
    +
    +
    Record and replay

    Introduction

    -

    While using the library, sequence of calls to its functions together with their parameters can be recorded to a file and later replayed using standalone player application. It can be useful to:

    +

    While using the library, sequence of calls to its functions together with their parameters can be recorded to a file and later replayed using standalone player application. It can be useful to:

    • Test correctness - check if same sequence of calls will not cause crash or failures on a target platform.
    • Gather statistics - see number of allocations, peak memory usage, number of calls etc.
      • @@ -79,10 +79,10 @@ Introduction

    Usage

    -

    Recording functionality is disabled by default. To enable it, define following macro before every include of this library:

    +

    Recording functionality is disabled by default. To enable it, define following macro before every include of this library:

    #define VMA_RECORDING_ENABLED 1
    -

    To record sequence of calls to a file: Fill in VmaAllocatorCreateInfo::pRecordSettings member while creating VmaAllocator object. File is opened and written during whole lifetime of the allocator.

    -

    To replay file: Use VmaReplay - standalone command-line program. Precompiled binary can be found in "bin" directory. Its source can be found in "src/VmaReplay" directory. Its project is generated by Premake. Command line syntax is printed when the program is launched without parameters. Basic usage: 

    VmaReplay.exe MyRecording.csv
+

    To record sequence of calls to a file: Fill in VmaAllocatorCreateInfo::pRecordSettings member while creating VmaAllocator object. File is opened and written during whole lifetime of the allocator.

    +

    To replay file: Use VmaReplay - standalone command-line program. Precompiled binary can be found in "bin" directory. Its source can be found in "src/VmaReplay" directory. Its project is generated by Premake. Command line syntax is printed when the program is launched without parameters. Basic usage: 

    VmaReplay.exe MyRecording.csv

    Documentation of file format can be found in file: "docs/Recording file format.md". It is a human-readable, text file in CSV format (Comma Separated Values).

    Additional considerations

    @@ -94,7 +94,7 @@ Additional considerations
    -Generated by doxygen 1.9.1 +Generated by doxygen 1.9.2
    diff --git a/docs/html/resource_aliasing.html b/docs/html/resource_aliasing.html index e716dc3..12feb63 100644 --- a/docs/html/resource_aliasing.html +++ b/docs/html/resource_aliasing.html @@ -2,8 +2,8 @@ - - + + Vulkan Memory Allocator: Resource aliasing (overlap) @@ -29,21 +29,22 @@
    - + +/* @license-end */ +
    -
    -
    -
    Resource aliasing (overlap)
    +
    +
    Resource aliasing (overlap)
    -

    New explicit graphics APIs (Vulkan and Direct3D 12), thanks to manual memory management, give an opportunity to alias (overlap) multiple resources in the same region of memory - a feature not available in the old APIs (Direct3D 11, OpenGL). It can be useful to save video memory, but it must be used with caution.

    -

    For example, if you know the flow of your whole render frame in advance, you are going to use some intermediate textures or buffers only during a small range of render passes, and you know these ranges don't overlap in time, you can bind these resources to the same place in memory, even if they have completely different parameters (width, height, format etc.).

    -

    Resource aliasing (overlap)

    -

    Such scenario is possible using VMA, but you need to create your images manually. Then you need to calculate parameters of an allocation to be made using formula:

    +

    New explicit graphics APIs (Vulkan and Direct3D 12), thanks to manual memory management, give an opportunity to alias (overlap) multiple resources in the same region of memory - a feature not available in the old APIs (Direct3D 11, OpenGL). It can be useful to save video memory, but it must be used with caution.

    +

    For example, if you know the flow of your whole render frame in advance, you are going to use some intermediate textures or buffers only during a small range of render passes, and you know these ranges don't overlap in time, you can bind these resources to the same place in memory, even if they have completely different parameters (width, height, format etc.).

    +

    Resource aliasing (overlap)

    +

    Such scenario is possible using VMA, but you need to create your images manually. Then you need to calculate parameters of an allocation to be made using formula:

    • allocation size = max(size of each image)
    • allocation alignment = max(alignment of each image)
    • allocation memoryTypeBits = bitwise AND(memoryTypeBits of each image)
    -

    Following example shows two different images bound to the same place in memory, allocated to fit largest of them.

    +

    Following example shows two different images bound to the same place in memory, allocated to fit largest of them.

    // A 512x512 texture to be sampled.
    VkImageCreateInfo img1CreateInfo = { VK_STRUCTURE_TYPE_IMAGE_CREATE_INFO };
    img1CreateInfo.imageType = VK_IMAGE_TYPE_2D;
    @@ -123,29 +123,29 @@ $(function() {
    finalMemReq.memoryTypeBits = img1MemReq.memoryTypeBits & img2MemReq.memoryTypeBits;
    // Validate if(finalMemReq.memoryTypeBits != 0)
    -
    VmaAllocationCreateInfo allocCreateInfo = {};
    -
    allocCreateInfo.usage = VMA_MEMORY_USAGE_GPU_ONLY;
    +
    VmaAllocationCreateInfo allocCreateInfo = {};
    +
    allocCreateInfo.usage = VMA_MEMORY_USAGE_GPU_ONLY;
    -
    VmaAllocation alloc;
    -
    res = vmaAllocateMemory(allocator, &finalMemReq, &allocCreateInfo, &alloc, nullptr);
    +
    VmaAllocation alloc;
    +
    res = vmaAllocateMemory(allocator, &finalMemReq, &allocCreateInfo, &alloc, nullptr);
    -
    res = vmaBindImageMemory(allocator, alloc, img1);
    -
    res = vmaBindImageMemory(allocator, alloc, img2);
    +
    res = vmaBindImageMemory(allocator, alloc, img1);
    +
    res = vmaBindImageMemory(allocator, alloc, img2);
    // You can use img1, img2 here, but not at the same time!
    -
    vmaFreeMemory(allocator, alloc);
    +
    vmaFreeMemory(allocator, alloc);
    vkDestroyImage(allocator, img2, nullptr);
    vkDestroyImage(allocator, img1, nullptr);
    -
    VmaAllocationCreateInfo
    Definition: vk_mem_alloc.h:991
    -
    VmaAllocationCreateInfo::usage
    VmaMemoryUsage usage
    Intended usage of memory.
    Definition: vk_mem_alloc.h:999
    +
    VmaAllocationCreateInfo
    Definition: vk_mem_alloc.h:987
    +
    VmaAllocationCreateInfo::usage
    VmaMemoryUsage usage
    Intended usage of memory.
    Definition: vk_mem_alloc.h:995
    VmaAllocation
    Represents single memory allocation.
    vmaBindImageMemory
    VkResult vmaBindImageMemory(VmaAllocator allocator, VmaAllocation allocation, VkImage image)
    Binds image to allocation.
    vmaFreeMemory
    void vmaFreeMemory(VmaAllocator allocator, const VmaAllocation allocation)
    Frees memory previously allocated using vmaAllocateMemory(), vmaAllocateMemoryForBuffer(),...
    -
    VMA_MEMORY_USAGE_GPU_ONLY
    @ VMA_MEMORY_USAGE_GPU_ONLY
    Definition: vk_mem_alloc.h:833
    +
    VMA_MEMORY_USAGE_GPU_ONLY
    @ VMA_MEMORY_USAGE_GPU_ONLY
    Definition: vk_mem_alloc.h:829
    vmaAllocateMemory
    VkResult vmaAllocateMemory(VmaAllocator allocator, const VkMemoryRequirements *pVkMemoryRequirements, const VmaAllocationCreateInfo *pCreateInfo, VmaAllocation *pAllocation, VmaAllocationInfo *pAllocationInfo)
    General purpose 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:

    +

    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:

    • Vulkan also allows to interpret contents of memory between aliasing resources consistently in some cases. See chapter 11.8. "Memory Aliasing" of Vulkan specification or VK_IMAGE_CREATE_ALIAS_BIT flag.
    • You can create more complex layout where different images and buffers are bound at different offsets inside one large allocation. For example, one can imagine a big texture used in some render passes, aliasing with a set of many small buffers used between in some further passes. To bind a resource at non-zero offset of an allocation, use vmaBindBufferMemory2() / vmaBindImageMemory2().
      • @@ -155,7 +155,7 @@ $(function() {
    -Generated by doxygen 1.9.1 +Generated by doxygen 1.9.2
    diff --git a/docs/html/search/all_0.html b/docs/html/search/all_0.html index 1ec5b2d..65f85b5 100644 --- a/docs/html/search/all_0.html +++ b/docs/html/search/all_0.html @@ -2,7 +2,7 @@ - + @@ -12,14 +12,14 @@
    Loading...
    Searching...
    No Matches
    @@ -12,14 +12,14 @@
    Loading...
    Searching...
    No Matches
    @@ -12,14 +12,14 @@
    Loading...
    Searching...
    No Matches
    @@ -12,14 +12,14 @@
    Loading...
    Searching...
    No Matches
    @@ -12,14 +12,14 @@
    Loading...
    Searching...
    No Matches
    @@ -12,14 +12,14 @@
    Loading...
    Searching...
    No Matches
    @@ -12,14 +12,14 @@
    Loading...
    Searching...
    No Matches
    @@ -12,14 +12,14 @@
    Loading...
    Searching...
    No Matches
    @@ -12,14 +12,14 @@
    Loading...
    Searching...
    No Matches
    @@ -12,14 +12,14 @@
    Loading...
    Searching...
    No Matches
    @@ -12,14 +12,14 @@
    Loading...
    Searching...
    No Matches
    @@ -12,14 +12,14 @@
    Loading...
    Searching...
    No Matches
    @@ -12,14 +12,14 @@
    Loading...
    Searching...
    No Matches
    @@ -12,14 +12,14 @@
    Loading...
    Searching...
    No Matches
    @@ -12,14 +12,14 @@
    Loading...
    Searching...
    No Matches
    @@ -12,14 +12,14 @@
    Loading...
    Searching...
    No Matches
    @@ -12,14 +12,14 @@
    Loading...
    Searching...
    No Matches
    @@ -12,14 +12,14 @@
    Loading...
    Searching...
    No Matches
    @@ -12,14 +12,14 @@
    Loading...
    Searching...
    No Matches
    @@ -12,14 +12,14 @@
    Loading...
    Searching...
    No Matches
    @@ -12,14 +12,14 @@
    Loading...
    Searching...
    No Matches
    @@ -12,14 +12,14 @@
    Loading...
    Searching...
    No Matches
    @@ -12,14 +12,14 @@
    Loading...
    Searching...
    No Matches
    @@ -12,14 +12,14 @@
    Loading...
    Searching...
    No Matches
    @@ -12,14 +12,14 @@
    Loading...
    Searching...
    No Matches
    @@ -12,14 +12,14 @@
    Loading...
    Searching...
    No Matches
    @@ -12,14 +12,14 @@
    Loading...
    Searching...
    No Matches
    @@ -12,14 +12,14 @@
    Loading...
    Searching...
    No Matches
    @@ -12,14 +12,14 @@
    Loading...
    Searching...
    No Matches
    @@ -12,14 +12,14 @@
    Loading...
    Searching...
    No Matches
    @@ -12,14 +12,14 @@
    Loading...
    Searching...
    No Matches
    @@ -12,14 +12,14 @@
    Loading...
    Searching...
    No Matches
    @@ -12,14 +12,14 @@
    Loading...
    Searching...
    No Matches
    @@ -12,14 +12,14 @@
    Loading...
    Searching...
    No Matches
    @@ -12,14 +12,14 @@
    Loading...
    Searching...
    No Matches
    @@ -12,14 +12,14 @@
    Loading...
    Searching...
    No Matches
    @@ -12,14 +12,14 @@
    Loading...
    Searching...
    No Matches
    @@ -12,14 +12,14 @@
    Loading...
    Searching...
    No Matches
    @@ -12,14 +12,14 @@
    Loading...
    Searching...
    No Matches
    @@ -12,14 +12,14 @@
    Loading...
    Searching...
    No Matches
    @@ -12,14 +12,14 @@
    Loading...
    Searching...
    No Matches
    @@ -12,14 +12,14 @@
    Loading...
    Searching...
    No Matches
    @@ -12,14 +12,14 @@
    Loading...
    Searching...
    No Matches
    @@ -12,14 +12,14 @@
    Loading...
    Searching...
    No Matches
    @@ -12,14 +12,14 @@
    Loading...
    Searching...
    No Matches
    @@ -12,14 +12,14 @@
    Loading...
    Searching...
    No Matches
    @@ -12,14 +12,14 @@
    Loading...
    Searching...
    No Matches
    @@ -12,14 +12,14 @@
    Loading...
    Searching...
    No Matches
    @@ -12,14 +12,14 @@
    Loading...
    Searching...
    No Matches
    @@ -12,14 +12,14 @@
    Loading...
    Searching...
    No Matches
    @@ -12,14 +12,14 @@
    Loading...
    Searching...
    No Matches
    @@ -12,14 +12,14 @@
    Loading...
    Searching...
    No Matches
    +/* @license-end */ +
    -
    -
    -
    Statistics
    +
    +
    Statistics
    -

    This library contains functions that return information about its internal state, especially the amount of memory allocated from Vulkan. Please keep in mind that these functions need to traverse all internal data structures to gather these information, so they may be quite time-consuming. Don't call them too often.

    +

    This library contains functions that return information about its internal state, especially the amount of memory allocated from Vulkan. Please keep in mind that these functions need to traverse all internal data structures to gather these information, so they may be quite time-consuming. Don't call them too often.

    Numeric statistics

    -

    You can query for overall statistics of the allocator using function vmaCalculateStats(). Information are returned using structure VmaStats. It contains VmaStatInfo - number of allocated blocks, number of allocations (occupied ranges in these blocks), number of unused (free) ranges in these blocks, number of bytes used and unused (but still allocated from Vulkan) and other information. They are summed across memory heaps, memory types and total for whole allocator.

    -

    You can query for statistics of a custom pool using function vmaGetPoolStats(). Information are returned using structure VmaPoolStats.

    -

    You can query for information about specific allocation using function vmaGetAllocationInfo(). It fill structure VmaAllocationInfo.

    +

    You can query for overall statistics of the allocator using function vmaCalculateStats(). Information are returned using structure VmaStats. It contains VmaStatInfo - number of allocated blocks, number of allocations (occupied ranges in these blocks), number of unused (free) ranges in these blocks, number of bytes used and unused (but still allocated from Vulkan) and other information. They are summed across memory heaps, memory types and total for whole allocator.

    +

    You can query for statistics of a custom pool using function vmaGetPoolStats(). Information are returned using structure VmaPoolStats.

    +

    You can query for information about specific allocation using function vmaGetAllocationInfo(). It fill structure VmaAllocationInfo.

    JSON dump

    -

    You can dump internal state of the allocator to a string in JSON format using function vmaBuildStatsString(). The result is guaranteed to be correct JSON. It uses ANSI encoding. Any strings provided by user (see Allocation names) are copied as-is and properly escaped for JSON, so if they use UTF-8, ISO-8859-2 or any other encoding, this JSON string can be treated as using this encoding. It must be freed using function vmaFreeStatsString().

    -

    The format of this JSON string is not part of official documentation of the library, but it will not change in backward-incompatible way without increasing library major version number and appropriate mention in changelog.

    -

    The JSON string contains all the data that can be obtained using vmaCalculateStats(). It can also contain detailed map of allocated memory blocks and their regions - free and occupied by allocations. This allows e.g. to visualize the memory or assess fragmentation.

    +

    You can dump internal state of the allocator to a string in JSON format using function vmaBuildStatsString(). The result is guaranteed to be correct JSON. It uses ANSI encoding. Any strings provided by user (see Allocation names) are copied as-is and properly escaped for JSON, so if they use UTF-8, ISO-8859-2 or any other encoding, this JSON string can be treated as using this encoding. It must be freed using function vmaFreeStatsString().

    +

    The format of this JSON string is not part of official documentation of the library, but it will not change in backward-incompatible way without increasing library major version number and appropriate mention in changelog.

    +

    The JSON string contains all the data that can be obtained using vmaCalculateStats(). It can also contain detailed map of allocated memory blocks and their regions - free and occupied by allocations. This allows e.g. to visualize the memory or assess fragmentation.

    -Generated by doxygen 1.9.1 +Generated by doxygen 1.9.2
    diff --git a/docs/html/staying_within_budget.html b/docs/html/staying_within_budget.html index 267252f..cb0aa59 100644 --- a/docs/html/staying_within_budget.html +++ b/docs/html/staying_within_budget.html @@ -2,8 +2,8 @@ - - + + Vulkan Memory Allocator: Staying within budget @@ -29,21 +29,22 @@
    - + +/* @license-end */ +
    -
    -
    -
    Staying within budget
    +
    +
    Staying within budget
    -

    When developing a graphics-intensive game or program, it is important to avoid allocating more GPU memory than it is physically available. When the memory is over-committed, various bad things can happen, depending on the specific GPU, graphics driver, and operating system:

    +

    When developing a graphics-intensive game or program, it is important to avoid allocating more GPU memory than it is physically available. When the memory is over-committed, various bad things can happen, depending on the specific GPU, graphics driver, and operating system:

    • It may just work without any problems.
    • The application may slow down because some memory blocks are moved to system RAM and the GPU has to access them through PCI Express bus.
      • @@ -79,9 +79,9 @@ $(function() {

    Querying for budget

    -

    To query for current memory usage and available budget, use function vmaGetBudget(). Returned structure VmaBudget contains quantities expressed in bytes, per Vulkan memory heap.

    -

    Please note that this function returns different information and works faster than vmaCalculateStats(). vmaGetBudget() can be called every frame or even before every allocation, while vmaCalculateStats() is intended to be used rarely, only to obtain statistical information, e.g. for debugging purposes.

    -

    It is recommended to use VK_EXT_memory_budget device extension to obtain information about the budget from Vulkan device. VMA is able to use this extension automatically. When not enabled, the allocator behaves same way, but then it estimates current usage and available budget based on its internal information and Vulkan memory heap sizes, which may be less precise. In order to use this extension:

    +

    To query for current memory usage and available budget, use function vmaGetBudget(). Returned structure VmaBudget contains quantities expressed in bytes, per Vulkan memory heap.

    +

    Please note that this function returns different information and works faster than vmaCalculateStats(). vmaGetBudget() can be called every frame or even before every allocation, while vmaCalculateStats() is intended to be used rarely, only to obtain statistical information, e.g. for debugging purposes.

    +

    It is recommended to use VK_EXT_memory_budget device extension to obtain information about the budget from Vulkan device. VMA is able to use this extension automatically. When not enabled, the allocator behaves same way, but then it estimates current usage and available budget based on its internal information and Vulkan memory heap sizes, which may be less precise. In order to use this extension:

    1. Make sure extensions VK_EXT_memory_budget and VK_KHR_get_physical_device_properties2 required by it are available and enable them. Please note that the first is a device extension and the second is instance extension!
    2. Use flag VMA_ALLOCATOR_CREATE_EXT_MEMORY_BUDGET_BIT when creating VmaAllocator object.
      3. @@ -89,16 +89,16 @@ Querying for budget

    Controlling memory usage

    -

    There are many ways in which you can try to stay within the budget.

    -

    First, when making new allocation requires allocating a new memory block, the library tries not to exceed the budget automatically. If a block with default recommended size (e.g. 256 MB) would go over budget, a smaller block is allocated, possibly even dedicated memory for just this resource.

    -

    If the size of the requested resource plus current memory usage is more than the budget, by default the library still tries to create it, leaving it to the Vulkan implementation whether the allocation succeeds or fails. You can change this behavior by using VMA_ALLOCATION_CREATE_WITHIN_BUDGET_BIT flag. With it, the allocation is not made if it would exceed the budget or if the budget is already exceeded. Some other allocations become lost instead to make room for it, if the mechanism of lost allocations is used. If that is not possible, the allocation fails with VK_ERROR_OUT_OF_DEVICE_MEMORY. Example usage pattern may be to pass the VMA_ALLOCATION_CREATE_WITHIN_BUDGET_BIT flag when creating resources that are not essential for the application (e.g. the texture of a specific object) and not to pass it when creating critically important resources (e.g. render targets).

    -

    Finally, you can also use VMA_ALLOCATION_CREATE_NEVER_ALLOCATE_BIT flag to make sure a new allocation is created only when it fits inside one of the existing memory blocks. If it would require to allocate a new block, if fails instead with VK_ERROR_OUT_OF_DEVICE_MEMORY. This also ensures that the function call is very fast because it never goes to Vulkan to obtain a new block.

    -

    Please note that creating Custom memory pools with VmaPoolCreateInfo::minBlockCount set to more than 0 will try to allocate memory blocks without checking whether they fit within budget.

    +

    There are many ways in which you can try to stay within the budget.

    +

    First, when making new allocation requires allocating a new memory block, the library tries not to exceed the budget automatically. If a block with default recommended size (e.g. 256 MB) would go over budget, a smaller block is allocated, possibly even dedicated memory for just this resource.

    +

    If the size of the requested resource plus current memory usage is more than the budget, by default the library still tries to create it, leaving it to the Vulkan implementation whether the allocation succeeds or fails. You can change this behavior by using VMA_ALLOCATION_CREATE_WITHIN_BUDGET_BIT flag. With it, the allocation is not made if it would exceed the budget or if the budget is already exceeded. Some other allocations become lost instead to make room for it, if the mechanism of lost allocations is used. If that is not possible, the allocation fails with VK_ERROR_OUT_OF_DEVICE_MEMORY. Example usage pattern may be to pass the VMA_ALLOCATION_CREATE_WITHIN_BUDGET_BIT flag when creating resources that are not essential for the application (e.g. the texture of a specific object) and not to pass it when creating critically important resources (e.g. render targets).

    +

    Finally, you can also use VMA_ALLOCATION_CREATE_NEVER_ALLOCATE_BIT flag to make sure a new allocation is created only when it fits inside one of the existing memory blocks. If it would require to allocate a new block, if fails instead with VK_ERROR_OUT_OF_DEVICE_MEMORY. This also ensures that the function call is very fast because it never goes to Vulkan to obtain a new block.

    +

    Please note that creating Custom memory pools with VmaPoolCreateInfo::minBlockCount set to more than 0 will try to allocate memory blocks without checking whether they fit within budget.

    -Generated by doxygen 1.9.1 +Generated by doxygen 1.9.2
    diff --git a/docs/html/struct_vma_allocation.html b/docs/html/struct_vma_allocation.html index 6064ef5..e1618f1 100644 --- a/docs/html/struct_vma_allocation.html +++ b/docs/html/struct_vma_allocation.html @@ -2,8 +2,8 @@ - - + + Vulkan Memory Allocator: VmaAllocation Struct Reference @@ -29,21 +29,22 @@
    - + +/* @license-end */ +
    -
    -
    VmaAllocation Struct Reference
    +
    VmaAllocation Struct Reference
    @@ -71,19 +71,19 @@ $(function() {

    #include <vk_mem_alloc.h>

    Detailed Description

    -

    Represents single memory allocation.

    -

    It may be either dedicated block of VkDeviceMemory or a specific region of a bigger block of this type plus unique offset.

    -

    There are multiple ways to create such object. You need to fill structure VmaAllocationCreateInfo. For more information see Choosing memory type.

    -

    Although the library provides convenience functions that create Vulkan buffer or image, allocate memory for it and bind them together, binding of the allocation to a buffer or an image is out of scope of the allocation itself. Allocation object can exist without buffer/image bound, binding can be done manually by the user, and destruction of it can be done independently of destruction of the allocation.

    -

    The object also remembers its size and some other information. To retrieve this information, use function vmaGetAllocationInfo() and inspect returned structure VmaAllocationInfo.

    -

    Some kinds allocations can be in lost state. For more information, see Lost allocations.

    +

    Represents single memory allocation.

    +

    It may be either dedicated block of VkDeviceMemory or a specific region of a bigger block of this type plus unique offset.

    +

    There are multiple ways to create such object. You need to fill structure VmaAllocationCreateInfo. For more information see Choosing memory type.

    +

    Although the library provides convenience functions that create Vulkan buffer or image, allocate memory for it and bind them together, binding of the allocation to a buffer or an image is out of scope of the allocation itself. Allocation object can exist without buffer/image bound, binding can be done manually by the user, and destruction of it can be done independently of destruction of the allocation.

    +

    The object also remembers its size and some other information. To retrieve this information, use function vmaGetAllocationInfo() and inspect returned structure VmaAllocationInfo.

    +

    Some kinds allocations can be in lost state. For more information, see Lost allocations.

    The documentation for this struct was generated from the following file:
    -Generated by doxygen 1.9.1 +Generated by doxygen 1.9.2
    diff --git a/docs/html/struct_vma_allocation_create_info-members.html b/docs/html/struct_vma_allocation_create_info-members.html index a97d4f7..5a08805 100644 --- a/docs/html/struct_vma_allocation_create_info-members.html +++ b/docs/html/struct_vma_allocation_create_info-members.html @@ -2,8 +2,8 @@ - - + + Vulkan Memory Allocator: Member List @@ -29,21 +29,22 @@
    - + +/* @license-end */ +
    -
    -
    VmaAllocationCreateInfo Member List
    +
    VmaAllocationCreateInfo Member List

    This is the complete list of members for VmaAllocationCreateInfo, including all inherited members.

    - + - + - + - +
    flagsVmaAllocationCreateInfo
    memoryTypeBitsVmaAllocationCreateInfo
    memoryTypeBitsVmaAllocationCreateInfo
    poolVmaAllocationCreateInfo
    preferredFlagsVmaAllocationCreateInfo
    preferredFlagsVmaAllocationCreateInfo
    priorityVmaAllocationCreateInfo
    pUserDataVmaAllocationCreateInfo
    pUserDataVmaAllocationCreateInfo
    requiredFlagsVmaAllocationCreateInfo
    usageVmaAllocationCreateInfo
    usageVmaAllocationCreateInfo
    -Generated by doxygen 1.9.1 +Generated by doxygen 1.9.2
    diff --git a/docs/html/struct_vma_allocation_create_info.html b/docs/html/struct_vma_allocation_create_info.html index d1692f2..9c41a97 100644 --- a/docs/html/struct_vma_allocation_create_info.html +++ b/docs/html/struct_vma_allocation_create_info.html @@ -2,8 +2,8 @@ - - + + Vulkan Memory Allocator: VmaAllocationCreateInfo Struct Reference @@ -29,21 +29,22 @@
    - + +/* @license-end */ + -
    -
    VmaAllocationCreateInfo Struct Reference
    +
    VmaAllocationCreateInfo Struct Reference

    #include <vk_mem_alloc.h>

    - @@ -99,7 +99,7 @@ Public Attributes

    +

    Public Attributes

    VmaAllocationCreateFlags flags
     Use VmaAllocationCreateFlagBits enum. More...
     

    Member Data Documentation

    - +

    ◆ flags

    @@ -115,7 +115,7 @@ Public Attributes
    - +

    ◆ memoryTypeBits

    @@ -128,12 +128,12 @@ Public Attributes

    Bitmask containing one bit set for every memory type acceptable for this allocation.

    -

    Value 0 is equivalent to UINT32_MAX - it means any memory type is accepted if it meets other requirements specified by this structure, with no further restrictions on memory type index.
    +

    Value 0 is equivalent to UINT32_MAX - it means any memory type is accepted if it meets other requirements specified by this structure, with no further restrictions on memory type index.
    If pool is not null, this member is ignored.

    - +

    ◆ pool

    @@ -146,11 +146,11 @@ If pool is not null, this member is ignored.

    Pool that this allocation should be created in.

    -

    Leave VK_NULL_HANDLE to allocate from default pool. If not null, members: usage, requiredFlags, preferredFlags, memoryTypeBits are ignored.

    +

    Leave VK_NULL_HANDLE to allocate from default pool. If not null, members: usage, requiredFlags, preferredFlags, memoryTypeBits are ignored.

    - +

    ◆ preferredFlags

    @@ -163,12 +163,12 @@ If pool is not null, this member is ignored.

    Flags that preferably should be set in a memory type chosen for an allocation.

    -

    Set to 0 if no additional flags are preferred.
    +

    Set to 0 if no additional flags are preferred.
    If pool is not null, this member is ignored.

    - +

    ◆ priority

    @@ -181,11 +181,11 @@ If pool is not null, this member is ignored.

    A floating-point value between 0 and 1, indicating the priority of the allocation relative to other memory allocations.

    -

    It is used only when VMA_ALLOCATOR_CREATE_EXT_MEMORY_PRIORITY_BIT flag was used during creation of the VmaAllocator object and this allocation ends up as dedicated or is explicitly forced as dedicated using VMA_ALLOCATION_CREATE_DEDICATED_MEMORY_BIT. Otherwise, it has the priority of a memory block where it is placed and this variable is ignored.

    +

    It is used only when VMA_ALLOCATOR_CREATE_EXT_MEMORY_PRIORITY_BIT flag was used during creation of the VmaAllocator object and this allocation ends up as dedicated or is explicitly forced as dedicated using VMA_ALLOCATION_CREATE_DEDICATED_MEMORY_BIT. Otherwise, it has the priority of a memory block where it is placed and this variable is ignored.

    - +

    ◆ pUserData

    @@ -198,11 +198,11 @@ If pool is not null, this member is ignored.

    Custom general-purpose pointer that will be stored in VmaAllocation, can be read as VmaAllocationInfo::pUserData and changed using vmaSetAllocationUserData().

    -

    If VMA_ALLOCATION_CREATE_USER_DATA_COPY_STRING_BIT is used, it must be either null or pointer to a null-terminated string. The string will be then copied to internal buffer, so it doesn't need to be valid after allocation call.

    +

    If VMA_ALLOCATION_CREATE_USER_DATA_COPY_STRING_BIT is used, it must be either null or pointer to a null-terminated string. The string will be then copied to internal buffer, so it doesn't need to be valid after allocation call.

    - +

    ◆ requiredFlags

    @@ -215,12 +215,12 @@ If pool is not null, this member is ignored.

    Flags that must be set in a Memory Type chosen for an allocation.

    -

    Leave 0 if you specify memory requirements in other way.
    +

    Leave 0 if you specify memory requirements in other way.
    If pool is not null, this member is ignored.

    - +

    ◆ usage

    @@ -233,18 +233,18 @@ If pool is not null, this member is ignored.

    Intended usage of memory.

    -

    You can leave VMA_MEMORY_USAGE_UNKNOWN if you specify memory requirements in other way.
    +

    You can leave VMA_MEMORY_USAGE_UNKNOWN if you specify memory requirements in other way.
    If pool is not null, this member is ignored.

    The documentation for this struct was generated from the following file:
    -Generated by doxygen 1.9.1 +Generated by doxygen 1.9.2
    diff --git a/docs/html/struct_vma_allocation_info-members.html b/docs/html/struct_vma_allocation_info-members.html index 7556c0a..33ed9d8 100644 --- a/docs/html/struct_vma_allocation_info-members.html +++ b/docs/html/struct_vma_allocation_info-members.html @@ -2,8 +2,8 @@ - - + + Vulkan Memory Allocator: Member List @@ -29,21 +29,22 @@ - + +/* @license-end */ +
    -
    -
    VmaAllocationInfo Member List
    +
    VmaAllocationInfo Member List

    This is the complete list of members for VmaAllocationInfo, including all inherited members.

    - + - + - +
    deviceMemoryVmaAllocationInfo
    memoryTypeVmaAllocationInfo
    memoryTypeVmaAllocationInfo
    offsetVmaAllocationInfo
    pMappedDataVmaAllocationInfo
    pMappedDataVmaAllocationInfo
    pUserDataVmaAllocationInfo
    sizeVmaAllocationInfo
    sizeVmaAllocationInfo
    -Generated by doxygen 1.9.1 +Generated by doxygen 1.9.2
    diff --git a/docs/html/struct_vma_allocation_info.html b/docs/html/struct_vma_allocation_info.html index 3fc652f..b83d3fa 100644 --- a/docs/html/struct_vma_allocation_info.html +++ b/docs/html/struct_vma_allocation_info.html @@ -2,8 +2,8 @@ - - + + Vulkan Memory Allocator: VmaAllocationInfo Struct Reference @@ -29,21 +29,22 @@
    - + +/* @license-end */ +
    Public Attributes | List of all members
    -
    -
    VmaAllocationInfo Struct Reference
    +
    VmaAllocationInfo Struct Reference
    @@ -74,7 +74,7 @@ $(function() {

    #include <vk_mem_alloc.h>

    - @@ -96,9 +96,9 @@ Public Attributes

    +

    Public Attributes

    uint32_t memoryType
     Memory type index that this allocation was allocated from. More...
     

    Detailed Description

    -

    Parameters of VmaAllocation objects, that can be retrieved using function vmaGetAllocationInfo().

    +

    Parameters of VmaAllocation objects, that can be retrieved using function vmaGetAllocationInfo().

    Member Data Documentation

    - +

    ◆ deviceMemory

    @@ -111,13 +111,13 @@ Public Attributes

    Handle to Vulkan memory object.

    -

    Same memory object can be shared by multiple allocations.

    -

    It can change after call to vmaDefragment() if this allocation is passed to the function, or if allocation is lost.

    -

    If the allocation is lost, it is equal to VK_NULL_HANDLE.

    +

    Same memory object can be shared by multiple allocations.

    +

    It can change after call to vmaDefragment() if this allocation is passed to the function, or if allocation is lost.

    +

    If the allocation is lost, it is equal to VK_NULL_HANDLE.

    - +

    ◆ memoryType

    @@ -130,11 +130,11 @@ Public Attributes

    Memory type index that this allocation was allocated from.

    -

    It never changes.

    +

    It never changes.

    - +

    ◆ offset

    @@ -147,12 +147,12 @@ Public Attributes

    Offset in VkDeviceMemory object to the beginning of this allocation, in bytes. (deviceMemory, offset) pair is unique to this allocation.

    -

    You usually don't need to use this offset. If you create a buffer or an image together with the allocation using e.g. function vmaCreateBuffer(), vmaCreateImage(), functions that operate on these resources refer to the beginning of the buffer or image, not entire device memory block. Functions like vmaMapMemory(), vmaBindBufferMemory() also refer to the beginning of the allocation and apply this offset automatically.

    -

    It can change after call to vmaDefragment() if this allocation is passed to the function, or if allocation is lost.

    +

    You usually don't need to use this offset. If you create a buffer or an image together with the allocation using e.g. function vmaCreateBuffer(), vmaCreateImage(), functions that operate on these resources refer to the beginning of the buffer or image, not entire device memory block. Functions like vmaMapMemory(), vmaBindBufferMemory() also refer to the beginning of the allocation and apply this offset automatically.

    +

    It can change after call to vmaDefragment() if this allocation is passed to the function, or if allocation is lost.

    - +

    ◆ pMappedData

    @@ -165,12 +165,12 @@ Public Attributes

    Pointer to the beginning of this allocation as mapped data.

    -

    If the allocation hasn't been mapped using vmaMapMemory() and hasn't been created with VMA_ALLOCATION_CREATE_MAPPED_BIT flag, this value is null.

    -

    It can change after call to vmaMapMemory(), vmaUnmapMemory(). It can also change after call to vmaDefragment() if this allocation is passed to the function.

    +

    If the allocation hasn't been mapped using vmaMapMemory() and hasn't been created with VMA_ALLOCATION_CREATE_MAPPED_BIT flag, this value is null.

    +

    It can change after call to vmaMapMemory(), vmaUnmapMemory(). It can also change after call to vmaDefragment() if this allocation is passed to the function.

    - +

    ◆ pUserData

    @@ -183,11 +183,11 @@ Public Attributes

    Custom general-purpose pointer that was passed as VmaAllocationCreateInfo::pUserData or set using vmaSetAllocationUserData().

    -

    It can change after call to vmaSetAllocationUserData() for this allocation.

    +

    It can change after call to vmaSetAllocationUserData() for this allocation.

    - +

    ◆ size

    @@ -200,18 +200,18 @@ Public Attributes

    Size of this allocation, in bytes.

    -

    It never changes, unless allocation is lost.

    +

    It never changes, unless allocation is lost.

    Note
    Allocation size returned in this variable may be greater than the size requested for the resource e.g. as VkBufferCreateInfo::size. Whole size of the allocation is accessible for operations on memory e.g. using a pointer after mapping with vmaMapMemory(), but operations on the resource e.g. using vkCmdCopyBuffer must be limited to the size of the resource.
    The documentation for this struct was generated from the following file:
    -Generated by doxygen 1.9.1 +Generated by doxygen 1.9.2
    diff --git a/docs/html/struct_vma_allocator.html b/docs/html/struct_vma_allocator.html index 3032241..4427b98 100644 --- a/docs/html/struct_vma_allocator.html +++ b/docs/html/struct_vma_allocator.html @@ -2,8 +2,8 @@ - - + + Vulkan Memory Allocator: VmaAllocator Struct Reference @@ -29,21 +29,22 @@ - + +/* @license-end */ +
    -
    -
    VmaAllocator Struct Reference
    +
    VmaAllocator Struct Reference
    @@ -71,16 +71,16 @@ $(function() {

    #include <vk_mem_alloc.h>

    Detailed Description

    -

    Represents main object of this library initialized.

    -

    Fill structure VmaAllocatorCreateInfo and call function vmaCreateAllocator() to create it. Call function vmaDestroyAllocator() to destroy it.

    -

    It is recommended to create just one object of this type per VkDevice object, right after Vulkan is initialized and keep it alive until before Vulkan device is destroyed.

    +

    Represents main object of this library initialized.

    +

    Fill structure VmaAllocatorCreateInfo and call function vmaCreateAllocator() to create it. Call function vmaDestroyAllocator() to destroy it.

    +

    It is recommended to create just one object of this type per VkDevice object, right after Vulkan is initialized and keep it alive until before Vulkan device is destroyed.

    The documentation for this struct was generated from the following file:
    -Generated by doxygen 1.9.1 +Generated by doxygen 1.9.2
    diff --git a/docs/html/struct_vma_allocator_create_info-members.html b/docs/html/struct_vma_allocator_create_info-members.html index 866fd46..46bc817 100644 --- a/docs/html/struct_vma_allocator_create_info-members.html +++ b/docs/html/struct_vma_allocator_create_info-members.html @@ -2,8 +2,8 @@ - - + + Vulkan Memory Allocator: Member List @@ -29,21 +29,22 @@
    - + +/* @license-end */ +
    -
    -
    VmaAllocatorCreateInfo Member List
    +
    VmaAllocatorCreateInfo Member List

    This is the complete list of members for VmaAllocatorCreateInfo, including all inherited members.

    - + - + - + - + - + - +
    deviceVmaAllocatorCreateInfo
    flagsVmaAllocatorCreateInfo
    flagsVmaAllocatorCreateInfo
    frameInUseCountVmaAllocatorCreateInfo
    instanceVmaAllocatorCreateInfo
    instanceVmaAllocatorCreateInfo
    pAllocationCallbacksVmaAllocatorCreateInfo
    pDeviceMemoryCallbacksVmaAllocatorCreateInfo
    pDeviceMemoryCallbacksVmaAllocatorCreateInfo
    pHeapSizeLimitVmaAllocatorCreateInfo
    physicalDeviceVmaAllocatorCreateInfo
    physicalDeviceVmaAllocatorCreateInfo
    pRecordSettingsVmaAllocatorCreateInfo
    preferredLargeHeapBlockSizeVmaAllocatorCreateInfo
    preferredLargeHeapBlockSizeVmaAllocatorCreateInfo
    pTypeExternalMemoryHandleTypesVmaAllocatorCreateInfo
    pVulkanFunctionsVmaAllocatorCreateInfo
    pVulkanFunctionsVmaAllocatorCreateInfo
    vulkanApiVersionVmaAllocatorCreateInfo
    -Generated by doxygen 1.9.1 +Generated by doxygen 1.9.2
    diff --git a/docs/html/struct_vma_allocator_create_info.html b/docs/html/struct_vma_allocator_create_info.html index acce0a0..35045b5 100644 --- a/docs/html/struct_vma_allocator_create_info.html +++ b/docs/html/struct_vma_allocator_create_info.html @@ -2,8 +2,8 @@ - - + + Vulkan Memory Allocator: VmaAllocatorCreateInfo Struct Reference @@ -29,21 +29,22 @@
    - + +/* @license-end */ + -
    -
    VmaAllocatorCreateInfo Struct Reference
    +
    VmaAllocatorCreateInfo Struct Reference
    @@ -74,7 +74,7 @@ $(function() {

    #include <vk_mem_alloc.h>

    - @@ -117,9 +117,9 @@ Public Attributes

    +

    Public Attributes

    VmaAllocatorCreateFlags flags
     Flags for created allocator. Use VmaAllocatorCreateFlagBits enum. More...
     

    Detailed Description

    -

    Description of a Allocator to be created.

    +

    Description of a Allocator to be created.

    Member Data Documentation

    - +

    ◆ device

    @@ -132,11 +132,11 @@ Public Attributes

    Vulkan device.

    -

    It must be valid throughout whole lifetime of created allocator.

    +

    It must be valid throughout whole lifetime of created allocator.

    - +

    ◆ flags

    @@ -152,7 +152,7 @@ Public Attributes
    - +

    ◆ frameInUseCount

    @@ -165,13 +165,13 @@ Public Attributes

    Maximum number of additional frames that are in use at the same time as current frame.

    -

    This value is used only when you make allocations with VMA_ALLOCATION_CREATE_CAN_BECOME_LOST_BIT flag. Such allocation cannot become lost if allocation.lastUseFrameIndex >= allocator.currentFrameIndex - frameInUseCount.

    -

    For example, if you double-buffer your command buffers, so resources used for rendering in previous frame may still be in use by the GPU at the moment you allocate resources needed for the current frame, set this value to 1.

    -

    If you want to allow any allocations other than used in the current frame to become lost, set this value to 0.

    +

    This value is used only when you make allocations with VMA_ALLOCATION_CREATE_CAN_BECOME_LOST_BIT flag. Such allocation cannot become lost if allocation.lastUseFrameIndex >= allocator.currentFrameIndex - frameInUseCount.

    +

    For example, if you double-buffer your command buffers, so resources used for rendering in previous frame may still be in use by the GPU at the moment you allocate resources needed for the current frame, set this value to 1.

    +

    If you want to allow any allocations other than used in the current frame to become lost, set this value to 0.

    - +

    ◆ instance

    @@ -184,11 +184,11 @@ Public Attributes

    Handle to Vulkan instance object.

    -

    Starting from version 3.0.0 this member is no longer optional, it must be set!

    +

    Starting from version 3.0.0 this member is no longer optional, it must be set!

    - +

    ◆ pAllocationCallbacks

    @@ -201,11 +201,11 @@ Public Attributes

    Custom CPU memory allocation callbacks. Optional.

    -

    Optional, can be null. When specified, will also be used for all CPU-side memory allocations.

    +

    Optional, can be null. When specified, will also be used for all CPU-side memory allocations.

    - +

    ◆ pDeviceMemoryCallbacks

    @@ -218,11 +218,11 @@ Public Attributes

    Informative callbacks for vkAllocateMemory, vkFreeMemory. Optional.

    -

    Optional, can be null.

    +

    Optional, can be null.

    - +

    ◆ pHeapSizeLimit

    @@ -235,18 +235,18 @@ Public Attributes

    Either null or a pointer to an array of limits on maximum number of bytes that can be allocated out of particular Vulkan memory heap.

    -

    If not NULL, it must be a pointer to an array of VkPhysicalDeviceMemoryProperties::memoryHeapCount elements, defining limit on maximum number of bytes that can be allocated out of particular Vulkan memory heap.

    -

    Any of the elements may be equal to VK_WHOLE_SIZE, which means no limit on that heap. This is also the default in case of pHeapSizeLimit = NULL.

    -

    If there is a limit defined for a heap:

    +

    If not NULL, it must be a pointer to an array of VkPhysicalDeviceMemoryProperties::memoryHeapCount elements, defining limit on maximum number of bytes that can be allocated out of particular Vulkan memory heap.

    +

    Any of the elements may be equal to VK_WHOLE_SIZE, which means no limit on that heap. This is also the default in case of pHeapSizeLimit = NULL.

    +

    If there is a limit defined for a heap:

    -

    Warning! Using this feature may not be equivalent to installing a GPU with smaller amount of memory, because graphics driver doesn't necessary fail new allocations with VK_ERROR_OUT_OF_DEVICE_MEMORY result when memory capacity is exceeded. It may return success and just silently migrate some device memory blocks to system RAM. This driver behavior can also be controlled using VK_AMD_memory_overallocation_behavior extension.

    +

    Warning! Using this feature may not be equivalent to installing a GPU with smaller amount of memory, because graphics driver doesn't necessary fail new allocations with VK_ERROR_OUT_OF_DEVICE_MEMORY result when memory capacity is exceeded. It may return success and just silently migrate some device memory blocks to system RAM. This driver behavior can also be controlled using VK_AMD_memory_overallocation_behavior extension.

    - +

    ◆ physicalDevice

    @@ -259,11 +259,11 @@ Public Attributes

    Vulkan physical device.

    -

    It must be valid throughout whole lifetime of created allocator.

    +

    It must be valid throughout whole lifetime of created allocator.

    - +

    ◆ pRecordSettings

    @@ -276,11 +276,11 @@ Public Attributes

    Parameters for recording of VMA calls. Can be null.

    -

    If not null, it enables recording of calls to VMA functions to a file. If support for recording is not enabled using VMA_RECORDING_ENABLED macro, creation of the allocator object fails with VK_ERROR_FEATURE_NOT_PRESENT.

    +

    If not null, it enables recording of calls to VMA functions to a file. If support for recording is not enabled using VMA_RECORDING_ENABLED macro, creation of the allocator object fails with VK_ERROR_FEATURE_NOT_PRESENT.

    - +

    ◆ preferredLargeHeapBlockSize

    @@ -293,11 +293,11 @@ Public Attributes

    Preferred size of a single VkDeviceMemory block to be allocated from large heaps > 1 GiB. Optional.

    -

    Set to 0 to use default, which is currently 256 MiB.

    +

    Set to 0 to use default, which is currently 256 MiB.

    - +

    ◆ pTypeExternalMemoryHandleTypes

    @@ -310,12 +310,12 @@ Public Attributes

    Either null or a pointer to an array of external memory handle types for each Vulkan memory type.

    -

    If not NULL, it must be a pointer to an array of VkPhysicalDeviceMemoryProperties::memoryTypeCount elements, defining external memory handle types of particular Vulkan memory type, to be passed using VkExportMemoryAllocateInfoKHR.

    -

    Any of the elements may be equal to 0, which means not to use VkExportMemoryAllocateInfoKHR on this memory type. This is also the default in case of pTypeExternalMemoryHandleTypes = NULL.

    +

    If not NULL, it must be a pointer to an array of VkPhysicalDeviceMemoryProperties::memoryTypeCount elements, defining external memory handle types of particular Vulkan memory type, to be passed using VkExportMemoryAllocateInfoKHR.

    +

    Any of the elements may be equal to 0, which means not to use VkExportMemoryAllocateInfoKHR on this memory type. This is also the default in case of pTypeExternalMemoryHandleTypes = NULL.

    - +

    ◆ pVulkanFunctions

    @@ -328,11 +328,11 @@ Public Attributes

    Pointers to Vulkan functions. Can be null.

    -

    For details see Pointers to Vulkan functions.

    +

    For details see Pointers to Vulkan functions.

    - +

    ◆ vulkanApiVersion

    @@ -345,17 +345,17 @@ 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 are supported by the current implementation. Leaving it initialized to zero is equivalent to VK_API_VERSION_1_0.

    The documentation for this struct was generated from the following file:
    -Generated by doxygen 1.9.1 +Generated by doxygen 1.9.2
    diff --git a/docs/html/struct_vma_allocator_info-members.html b/docs/html/struct_vma_allocator_info-members.html index e3bfe36..2e634e4 100644 --- a/docs/html/struct_vma_allocator_info-members.html +++ b/docs/html/struct_vma_allocator_info-members.html @@ -2,8 +2,8 @@ - - + + Vulkan Memory Allocator: Member List @@ -29,21 +29,22 @@ - + +/* @license-end */ +
    -
    -
    VmaAllocatorInfo Member List
    +
    VmaAllocatorInfo Member List

    This is the complete list of members for VmaAllocatorInfo, including all inherited members.

    - +
    deviceVmaAllocatorInfo
    instanceVmaAllocatorInfo
    instanceVmaAllocatorInfo
    physicalDeviceVmaAllocatorInfo
    -Generated by doxygen 1.9.1 +Generated by doxygen 1.9.2
    diff --git a/docs/html/struct_vma_allocator_info.html b/docs/html/struct_vma_allocator_info.html index 6f4b1eb..9d7aad5 100644 --- a/docs/html/struct_vma_allocator_info.html +++ b/docs/html/struct_vma_allocator_info.html @@ -2,8 +2,8 @@ - - + + Vulkan Memory Allocator: VmaAllocatorInfo Struct Reference @@ -29,21 +29,22 @@
    - + +/* @license-end */ +
    Public Attributes | List of all members
    -
    -
    VmaAllocatorInfo Struct Reference
    +
    VmaAllocatorInfo Struct Reference
    @@ -74,7 +74,7 @@ $(function() {

    #include <vk_mem_alloc.h>

    - @@ -87,9 +87,9 @@ Public Attributes

    +

    Public Attributes

    VkInstance instance
     Handle to Vulkan instance object. More...
     

    Detailed Description

    -

    Information about existing VmaAllocator object.

    +

    Information about existing VmaAllocator object.

    Member Data Documentation

    - +

    ◆ device

    @@ -102,11 +102,11 @@ Public Attributes

    Handle to Vulkan device object.

    -

    This is the same value as has been passed through VmaAllocatorCreateInfo::device.

    +

    This is the same value as has been passed through VmaAllocatorCreateInfo::device.

    - +

    ◆ instance

    @@ -119,11 +119,11 @@ Public Attributes

    Handle to Vulkan instance object.

    -

    This is the same value as has been passed through VmaAllocatorCreateInfo::instance.

    +

    This is the same value as has been passed through VmaAllocatorCreateInfo::instance.

    - +

    ◆ physicalDevice

    @@ -136,17 +136,17 @@ Public Attributes

    Handle to Vulkan physical device object.

    -

    This is the same value as has been passed through VmaAllocatorCreateInfo::physicalDevice.

    +

    This is the same value as has been passed through VmaAllocatorCreateInfo::physicalDevice.

    The documentation for this struct was generated from the following file:
    -Generated by doxygen 1.9.1 +Generated by doxygen 1.9.2
    diff --git a/docs/html/struct_vma_budget-members.html b/docs/html/struct_vma_budget-members.html index 209d1a2..7784596 100644 --- a/docs/html/struct_vma_budget-members.html +++ b/docs/html/struct_vma_budget-members.html @@ -2,8 +2,8 @@ - - + + Vulkan Memory Allocator: Member List @@ -29,21 +29,22 @@ - + +/* @license-end */ +
    -
    -
    VmaBudget Member List
    +
    VmaBudget Member List

    This is the complete list of members for VmaBudget, including all inherited members.

    - + - +
    allocationBytesVmaBudget
    blockBytesVmaBudget
    blockBytesVmaBudget
    budgetVmaBudget
    usageVmaBudget
    usageVmaBudget
    -Generated by doxygen 1.9.1 +Generated by doxygen 1.9.2
    diff --git a/docs/html/struct_vma_budget.html b/docs/html/struct_vma_budget.html index 757f5cc..87b0cbc 100644 --- a/docs/html/struct_vma_budget.html +++ b/docs/html/struct_vma_budget.html @@ -2,8 +2,8 @@ - - + + Vulkan Memory Allocator: VmaBudget Struct Reference @@ -29,21 +29,22 @@
    - + +/* @license-end */ +
    Public Attributes | List of all members
    -
    -
    VmaBudget Struct Reference
    +
    VmaBudget Struct Reference
    @@ -74,7 +74,7 @@ $(function() {

    #include <vk_mem_alloc.h>

    - @@ -90,9 +90,9 @@ Public Attributes

    +

    Public Attributes

    VkDeviceSize blockBytes
     Sum size of all VkDeviceMemory blocks allocated from particular heap, in bytes. More...
     

    Detailed Description

    -

    Statistics of current memory usage and available budget, in bytes, for specific memory heap.

    +

    Statistics of current memory usage and available budget, in bytes, for specific memory heap.

    Member Data Documentation

    - +

    ◆ allocationBytes

    @@ -105,12 +105,12 @@ Public Attributes

    Sum size of all allocations created in particular heap, in bytes.

    -

    Usually less or equal than blockBytes. Difference blockBytes - allocationBytes is the amount of memory allocated but unused - available for new allocations or wasted due to fragmentation.

    -

    It might be greater than blockBytes if there are some allocations in lost state, as they account to this value as well.

    +

    Usually less or equal than blockBytes. Difference blockBytes - allocationBytes is the amount of memory allocated but unused - available for new allocations or wasted due to fragmentation.

    +

    It might be greater than blockBytes if there are some allocations in lost state, as they account to this value as well.

    - +

    ◆ blockBytes

    @@ -126,7 +126,7 @@ Public Attributes
    - +

    ◆ budget

    @@ -139,12 +139,12 @@ Public Attributes

    Estimated amount of memory available to the program, in bytes.

    -

    Fetched from system using VK_EXT_memory_budget extension if enabled.

    -

    It might be different (most probably smaller) than VkMemoryHeap::size[heapIndex] due to factors external to the program, like other programs also consuming system resources. Difference budget - usage is the amount of additional memory that can probably be allocated without problems. Exceeding the budget may result in various problems.

    +

    Fetched from system using VK_EXT_memory_budget extension if enabled.

    +

    It might be different (most probably smaller) than VkMemoryHeap::size[heapIndex] due to factors external to the program, like other programs also consuming system resources. Difference budget - usage is the amount of additional memory that can probably be allocated without problems. Exceeding the budget may result in various problems.

    - +

    ◆ usage

    @@ -157,18 +157,18 @@ Public Attributes

    Estimated current memory usage of the program, in bytes.

    -

    Fetched from system using VK_EXT_memory_budget extension if enabled.

    -

    It might be different than blockBytes (usually higher) due to additional implicit objects also occupying the memory, like swapchain, pipelines, descriptor heaps, command buffers, or VkDeviceMemory blocks allocated outside of this library, if any.

    +

    Fetched from system using VK_EXT_memory_budget extension if enabled.

    +

    It might be different than blockBytes (usually higher) due to additional implicit objects also occupying the memory, like swapchain, pipelines, descriptor heaps, command buffers, or VkDeviceMemory blocks allocated outside of this library, if any.

    The documentation for this struct was generated from the following file:
    -Generated by doxygen 1.9.1 +Generated by doxygen 1.9.2
    diff --git a/docs/html/struct_vma_defragmentation_context.html b/docs/html/struct_vma_defragmentation_context.html index 3576917..51acec5 100644 --- a/docs/html/struct_vma_defragmentation_context.html +++ b/docs/html/struct_vma_defragmentation_context.html @@ -2,8 +2,8 @@ - - + + Vulkan Memory Allocator: VmaDefragmentationContext Struct Reference @@ -29,21 +29,22 @@ - + +/* @license-end */ +
    -
    -
    VmaDefragmentationContext Struct Reference
    +
    VmaDefragmentationContext Struct Reference
    @@ -71,15 +71,15 @@ $(function() {

    #include <vk_mem_alloc.h>

    Detailed Description

    -

    Represents Opaque object that represents started defragmentation process.

    -

    Fill structure VmaDefragmentationInfo2 and call function vmaDefragmentationBegin() to create it. Call function vmaDefragmentationEnd() to destroy it.

    +

    Represents Opaque object that represents started defragmentation process.

    +

    Fill structure VmaDefragmentationInfo2 and call function vmaDefragmentationBegin() to create it. Call function vmaDefragmentationEnd() to destroy it.

    The documentation for this struct was generated from the following file:
    -Generated by doxygen 1.9.1 +Generated by doxygen 1.9.2
    diff --git a/docs/html/struct_vma_defragmentation_info-members.html b/docs/html/struct_vma_defragmentation_info-members.html index 9ca5100..0e26a93 100644 --- a/docs/html/struct_vma_defragmentation_info-members.html +++ b/docs/html/struct_vma_defragmentation_info-members.html @@ -2,8 +2,8 @@ - - + + Vulkan Memory Allocator: Member List @@ -29,21 +29,22 @@
    - + +/* @license-end */ +
    -
    -
    VmaDefragmentationInfo Member List
    +
    VmaDefragmentationInfo Member List

    This is the complete list of members for VmaDefragmentationInfo, including all inherited members.

    - +
    maxAllocationsToMoveVmaDefragmentationInfo
    maxBytesToMoveVmaDefragmentationInfo
    maxBytesToMoveVmaDefragmentationInfo
    -Generated by doxygen 1.9.1 +Generated by doxygen 1.9.2
    diff --git a/docs/html/struct_vma_defragmentation_info.html b/docs/html/struct_vma_defragmentation_info.html index cf717dd..013ca68 100644 --- a/docs/html/struct_vma_defragmentation_info.html +++ b/docs/html/struct_vma_defragmentation_info.html @@ -2,8 +2,8 @@ - - + + Vulkan Memory Allocator: VmaDefragmentationInfo Struct Reference @@ -29,21 +29,22 @@
    - + +/* @license-end */ + -
    -
    VmaDefragmentationInfo Struct Reference
    +
    VmaDefragmentationInfo Struct Reference
    @@ -74,7 +74,7 @@ $(function() {

    #include <vk_mem_alloc.h>

    - @@ -84,10 +84,10 @@ Public Attributes

    +

    Public Attributes

    VkDeviceSize maxBytesToMove
     Maximum total numbers of bytes that can be copied while moving allocations to different places. More...
     

    Detailed Description

    -

    Deprecated. Optional configuration parameters to be passed to function vmaDefragment().

    +

    Deprecated. Optional configuration parameters to be passed to function vmaDefragment().

    Deprecated:
    This is a part of the old interface. It is recommended to use structure VmaDefragmentationInfo2 and function vmaDefragmentationBegin() instead.

    Member Data Documentation

    - +

    ◆ maxAllocationsToMove

    @@ -100,11 +100,11 @@ Public Attributes

    Maximum number of allocations that can be moved to different place.

    -

    Default is UINT32_MAX, which means no limit.

    +

    Default is UINT32_MAX, which means no limit.

    - +

    ◆ maxBytesToMove

    @@ -117,17 +117,17 @@ Public Attributes

    Maximum total numbers of bytes that can be copied while moving allocations to different places.

    -

    Default is VK_WHOLE_SIZE, which means no limit.

    +

    Default is VK_WHOLE_SIZE, which means no limit.

    The documentation for this struct was generated from the following file:
    -Generated by doxygen 1.9.1 +Generated by doxygen 1.9.2
    diff --git a/docs/html/struct_vma_defragmentation_info2-members.html b/docs/html/struct_vma_defragmentation_info2-members.html index 3c01166..a17b9ef 100644 --- a/docs/html/struct_vma_defragmentation_info2-members.html +++ b/docs/html/struct_vma_defragmentation_info2-members.html @@ -2,8 +2,8 @@ - - + + Vulkan Memory Allocator: Member List @@ -29,21 +29,22 @@ - + +/* @license-end */ +
    -
    -
    VmaDefragmentationInfo2 Member List
    +
    VmaDefragmentationInfo2 Member List

    This is the complete list of members for VmaDefragmentationInfo2, including all inherited members.

    - + - + - + - + - +
    allocationCountVmaDefragmentationInfo2
    commandBufferVmaDefragmentationInfo2
    commandBufferVmaDefragmentationInfo2
    flagsVmaDefragmentationInfo2
    maxCpuAllocationsToMoveVmaDefragmentationInfo2
    maxCpuAllocationsToMoveVmaDefragmentationInfo2
    maxCpuBytesToMoveVmaDefragmentationInfo2
    maxGpuAllocationsToMoveVmaDefragmentationInfo2
    maxGpuAllocationsToMoveVmaDefragmentationInfo2
    maxGpuBytesToMoveVmaDefragmentationInfo2
    pAllocationsVmaDefragmentationInfo2
    pAllocationsVmaDefragmentationInfo2
    pAllocationsChangedVmaDefragmentationInfo2
    poolCountVmaDefragmentationInfo2
    poolCountVmaDefragmentationInfo2
    pPoolsVmaDefragmentationInfo2
    -Generated by doxygen 1.9.1 +Generated by doxygen 1.9.2
    diff --git a/docs/html/struct_vma_defragmentation_info2.html b/docs/html/struct_vma_defragmentation_info2.html index 6e8fd50..c9e667c 100644 --- a/docs/html/struct_vma_defragmentation_info2.html +++ b/docs/html/struct_vma_defragmentation_info2.html @@ -2,8 +2,8 @@ - - + + Vulkan Memory Allocator: VmaDefragmentationInfo2 Struct Reference @@ -29,21 +29,22 @@
    - + +/* @license-end */ +
    Public Attributes | List of all members
    -
    -
    VmaDefragmentationInfo2 Struct Reference
    +
    VmaDefragmentationInfo2 Struct Reference
    @@ -74,7 +74,7 @@ $(function() {

    #include <vk_mem_alloc.h>

    - @@ -111,10 +111,10 @@ Public Attributes

    +

    Public Attributes

    VmaDefragmentationFlags flags
     Reserved for future use. Should be 0. More...
     

    Detailed Description

    -

    Parameters for defragmentation.

    -

    To be used with function vmaDefragmentationBegin().

    +

    Parameters for defragmentation.

    +

    To be used with function vmaDefragmentationBegin().

    Member Data Documentation

    - +

    ◆ allocationCount

    @@ -130,7 +130,7 @@ Public Attributes
    - +

    ◆ commandBuffer

    @@ -143,12 +143,12 @@ Public Attributes

    Optional. Command buffer where GPU copy commands will be posted.

    -

    If not null, it must be a valid command buffer handle that supports Transfer queue type. It must be in the recording state and outside of a render pass instance. You need to submit it and make sure it finished execution before calling vmaDefragmentationEnd().

    -

    Passing null means that only CPU defragmentation will be performed.

    +

    If not null, it must be a valid command buffer handle that supports Transfer queue type. It must be in the recording state and outside of a render pass instance. You need to submit it and make sure it finished execution before calling vmaDefragmentationEnd().

    +

    Passing null means that only CPU defragmentation will be performed.

    - +

    ◆ flags

    @@ -164,7 +164,7 @@ Public Attributes
    - +

    ◆ maxCpuAllocationsToMove

    @@ -177,11 +177,11 @@ Public Attributes

    Maximum number of allocations that can be moved to a different place using transfers on CPU side, like memcpy(), memmove().

    -

    UINT32_MAX means no limit.

    +

    UINT32_MAX means no limit.

    - +

    ◆ maxCpuBytesToMove

    @@ -194,11 +194,11 @@ Public Attributes

    Maximum total numbers of bytes that can be copied while moving allocations to different places using transfers on CPU side, like memcpy(), memmove().

    -

    VK_WHOLE_SIZE means no limit.

    +

    VK_WHOLE_SIZE means no limit.

    - +

    ◆ maxGpuAllocationsToMove

    @@ -211,11 +211,11 @@ Public Attributes

    Maximum number of allocations that can be moved to a different place using transfers on GPU side, posted to commandBuffer.

    -

    UINT32_MAX means no limit.

    +

    UINT32_MAX means no limit.

    - +

    ◆ maxGpuBytesToMove

    @@ -228,11 +228,11 @@ Public Attributes

    Maximum total numbers of bytes that can be copied while moving allocations to different places using transfers on GPU side, posted to commandBuffer.

    -

    VK_WHOLE_SIZE means no limit.

    +

    VK_WHOLE_SIZE means no limit.

    - +

    ◆ pAllocations

    @@ -245,11 +245,11 @@ Public Attributes

    Pointer to array of allocations that can be defragmented.

    -

    The array should have allocationCount elements. The array should not contain nulls. Elements in the array should be unique - same allocation cannot occur twice. It is safe to pass allocations that are in the lost state - they are ignored. All allocations not present in this array are considered non-moveable during this defragmentation.

    +

    The array should have allocationCount elements. The array should not contain nulls. Elements in the array should be unique - same allocation cannot occur twice. It is safe to pass allocations that are in the lost state - they are ignored. All allocations not present in this array are considered non-moveable during this defragmentation.

    - +

    ◆ pAllocationsChanged

    @@ -262,11 +262,11 @@ Public Attributes

    Optional, output. Pointer to array that will be filled with information whether the allocation at certain index has been changed during defragmentation.

    -

    The array should have allocationCount elements. You can pass null if you are not interested in this information.

    +

    The array should have allocationCount elements. You can pass null if you are not interested in this information.

    - +

    ◆ poolCount

    @@ -282,7 +282,7 @@ Public Attributes
    - +

    ◆ pPools

    @@ -295,19 +295,19 @@ Public Attributes

    Either null or pointer to array of pools to be defragmented.

    -

    All the allocations in the specified pools can be moved during defragmentation and there is no way to check if they were really moved as in pAllocationsChanged, so you must query all the allocations in all these pools for new VkDeviceMemory and offset using vmaGetAllocationInfo() if you might need to recreate buffers and images bound to them.

    -

    The array should have poolCount elements. The array should not contain nulls. Elements in the array should be unique - same pool cannot occur twice.

    -

    Using this array is equivalent to specifying all allocations from the pools in pAllocations. It might be more efficient.

    +

    All the allocations in the specified pools can be moved during defragmentation and there is no way to check if they were really moved as in pAllocationsChanged, so you must query all the allocations in all these pools for new VkDeviceMemory and offset using vmaGetAllocationInfo() if you might need to recreate buffers and images bound to them.

    +

    The array should have poolCount elements. The array should not contain nulls. Elements in the array should be unique - same pool cannot occur twice.

    +

    Using this array is equivalent to specifying all allocations from the pools in pAllocations. It might be more efficient.

    The documentation for this struct was generated from the following file:
    -Generated by doxygen 1.9.1 +Generated by doxygen 1.9.2
    diff --git a/docs/html/struct_vma_defragmentation_pass_info-members.html b/docs/html/struct_vma_defragmentation_pass_info-members.html index 472df8c..4d33a3a 100644 --- a/docs/html/struct_vma_defragmentation_pass_info-members.html +++ b/docs/html/struct_vma_defragmentation_pass_info-members.html @@ -2,8 +2,8 @@ - - + + Vulkan Memory Allocator: Member List @@ -29,21 +29,22 @@ - + +/* @license-end */ +
    -
    -
    VmaDefragmentationPassInfo Member List
    +
    VmaDefragmentationPassInfo Member List

    This is the complete list of members for VmaDefragmentationPassInfo, including all inherited members.

    - +
    moveCountVmaDefragmentationPassInfo
    pMovesVmaDefragmentationPassInfo
    pMovesVmaDefragmentationPassInfo
    -Generated by doxygen 1.9.1 +Generated by doxygen 1.9.2
    diff --git a/docs/html/struct_vma_defragmentation_pass_info.html b/docs/html/struct_vma_defragmentation_pass_info.html index ab938ee..49eac0e 100644 --- a/docs/html/struct_vma_defragmentation_pass_info.html +++ b/docs/html/struct_vma_defragmentation_pass_info.html @@ -2,8 +2,8 @@ - - + + Vulkan Memory Allocator: VmaDefragmentationPassInfo Struct Reference @@ -29,21 +29,22 @@
    - + +/* @license-end */ +
    Public Attributes | List of all members
    -
    -
    VmaDefragmentationPassInfo Struct Reference
    +
    VmaDefragmentationPassInfo Struct Reference
    @@ -74,7 +74,7 @@ $(function() {

    #include <vk_mem_alloc.h>

    - @@ -82,10 +82,10 @@ Public Attributes

    +

    Public Attributes

    uint32_t moveCount
     
     

    Detailed Description

    -

    Parameters for incremental defragmentation steps.

    -

    To be used with function vmaBeginDefragmentationPass().

    +

    Parameters for incremental defragmentation steps.

    +

    To be used with function vmaBeginDefragmentationPass().

    Member Data Documentation

    - +

    ◆ moveCount

    @@ -99,7 +99,7 @@ Public Attributes
    - +

    ◆ pMoves

    @@ -114,12 +114,12 @@ Public Attributes
    The documentation for this struct was generated from the following file:
    -Generated by doxygen 1.9.1 +Generated by doxygen 1.9.2
    diff --git a/docs/html/struct_vma_defragmentation_pass_move_info-members.html b/docs/html/struct_vma_defragmentation_pass_move_info-members.html index 61f0179..96425a6 100644 --- a/docs/html/struct_vma_defragmentation_pass_move_info-members.html +++ b/docs/html/struct_vma_defragmentation_pass_move_info-members.html @@ -2,8 +2,8 @@ - - + + Vulkan Memory Allocator: Member List @@ -29,21 +29,22 @@ - + +/* @license-end */ +
    -
    -
    VmaDefragmentationPassMoveInfo Member List
    +
    VmaDefragmentationPassMoveInfo Member List

    This is the complete list of members for VmaDefragmentationPassMoveInfo, including all inherited members.

    - +
    allocationVmaDefragmentationPassMoveInfo
    memoryVmaDefragmentationPassMoveInfo
    memoryVmaDefragmentationPassMoveInfo
    offsetVmaDefragmentationPassMoveInfo
    -Generated by doxygen 1.9.1 +Generated by doxygen 1.9.2
    diff --git a/docs/html/struct_vma_defragmentation_pass_move_info.html b/docs/html/struct_vma_defragmentation_pass_move_info.html index 1e936d7..b077c3a 100644 --- a/docs/html/struct_vma_defragmentation_pass_move_info.html +++ b/docs/html/struct_vma_defragmentation_pass_move_info.html @@ -2,8 +2,8 @@ - - + + Vulkan Memory Allocator: VmaDefragmentationPassMoveInfo Struct Reference @@ -29,21 +29,22 @@
    - + +/* @license-end */ +
    Public Attributes | List of all members
    -
    -
    VmaDefragmentationPassMoveInfo Struct Reference
    +
    VmaDefragmentationPassMoveInfo Struct Reference

    #include <vk_mem_alloc.h>

    - @@ -81,7 +81,7 @@ Public Attributes

    +

    Public Attributes

    VmaAllocation allocation
     
     

    Member Data Documentation

    - +

    ◆ allocation

    @@ -95,7 +95,7 @@ Public Attributes
    - +

    ◆ memory

    @@ -109,7 +109,7 @@ Public Attributes
    - +

    ◆ offset

    @@ -124,12 +124,12 @@ Public Attributes
    The documentation for this struct was generated from the following file:
    -Generated by doxygen 1.9.1 +Generated by doxygen 1.9.2
    diff --git a/docs/html/struct_vma_defragmentation_stats-members.html b/docs/html/struct_vma_defragmentation_stats-members.html index ac8b730..f647f8b 100644 --- a/docs/html/struct_vma_defragmentation_stats-members.html +++ b/docs/html/struct_vma_defragmentation_stats-members.html @@ -2,8 +2,8 @@ - - + + Vulkan Memory Allocator: Member List @@ -29,21 +29,22 @@ - + +/* @license-end */ +
    -
    -
    VmaDefragmentationStats Member List
    +
    VmaDefragmentationStats Member List

    This is the complete list of members for VmaDefragmentationStats, including all inherited members.

    - + - +
    allocationsMovedVmaDefragmentationStats
    bytesFreedVmaDefragmentationStats
    bytesFreedVmaDefragmentationStats
    bytesMovedVmaDefragmentationStats
    deviceMemoryBlocksFreedVmaDefragmentationStats
    deviceMemoryBlocksFreedVmaDefragmentationStats
    -Generated by doxygen 1.9.1 +Generated by doxygen 1.9.2
    diff --git a/docs/html/struct_vma_defragmentation_stats.html b/docs/html/struct_vma_defragmentation_stats.html index e770650..3c35ef6 100644 --- a/docs/html/struct_vma_defragmentation_stats.html +++ b/docs/html/struct_vma_defragmentation_stats.html @@ -2,8 +2,8 @@ - - + + Vulkan Memory Allocator: VmaDefragmentationStats Struct Reference @@ -29,21 +29,22 @@
    - + +/* @license-end */ +
    Public Attributes | List of all members
    -
    -
    VmaDefragmentationStats Struct Reference
    +
    VmaDefragmentationStats Struct Reference
    @@ -74,7 +74,7 @@ $(function() {

    #include <vk_mem_alloc.h>

    - @@ -90,9 +90,9 @@ Public Attributes

    +

    Public Attributes

    VkDeviceSize bytesMoved
     Total number of bytes that have been copied while moving allocations to different places. More...
     

    Detailed Description

    -

    Statistics returned by function vmaDefragment().

    +

    Statistics returned by function vmaDefragment().

    Member Data Documentation

    - +

    ◆ allocationsMoved

    @@ -108,7 +108,7 @@ Public Attributes
    - +

    ◆ bytesFreed

    @@ -124,7 +124,7 @@ Public Attributes
    - +

    ◆ bytesMoved

    @@ -140,7 +140,7 @@ Public Attributes
    - +

    ◆ deviceMemoryBlocksFreed

    @@ -157,12 +157,12 @@ Public Attributes
    The documentation for this struct was generated from the following file:
    -Generated by doxygen 1.9.1 +Generated by doxygen 1.9.2
    diff --git a/docs/html/struct_vma_device_memory_callbacks-members.html b/docs/html/struct_vma_device_memory_callbacks-members.html index 4c3ff43..0f6c885 100644 --- a/docs/html/struct_vma_device_memory_callbacks-members.html +++ b/docs/html/struct_vma_device_memory_callbacks-members.html @@ -2,8 +2,8 @@ - - + + Vulkan Memory Allocator: Member List @@ -29,21 +29,22 @@ - + +/* @license-end */ +
    -
    -
    VmaDeviceMemoryCallbacks Member List
    +
    VmaDeviceMemoryCallbacks Member List

    This is the complete list of members for VmaDeviceMemoryCallbacks, including all inherited members.

    - +
    pfnAllocateVmaDeviceMemoryCallbacks
    pfnFreeVmaDeviceMemoryCallbacks
    pfnFreeVmaDeviceMemoryCallbacks
    pUserDataVmaDeviceMemoryCallbacks
    -Generated by doxygen 1.9.1 +Generated by doxygen 1.9.2
    diff --git a/docs/html/struct_vma_device_memory_callbacks.html b/docs/html/struct_vma_device_memory_callbacks.html index 7282842..5394c34 100644 --- a/docs/html/struct_vma_device_memory_callbacks.html +++ b/docs/html/struct_vma_device_memory_callbacks.html @@ -2,8 +2,8 @@ - - + + Vulkan Memory Allocator: VmaDeviceMemoryCallbacks Struct Reference @@ -29,21 +29,22 @@
    - + +/* @license-end */ +
    Public Attributes | List of all members
    -
    -
    VmaDeviceMemoryCallbacks Struct Reference
    +
    VmaDeviceMemoryCallbacks Struct Reference
    @@ -74,7 +74,7 @@ $(function() {

    #include <vk_mem_alloc.h>

    - @@ -87,11 +87,11 @@ Public Attributes

    +

    Public Attributes

    PFN_vmaAllocateDeviceMemoryFunction pfnAllocate
     Optional, can be null. More...
     

    Detailed Description

    -

    Set of callbacks that the library will call for vkAllocateMemory and vkFreeMemory.

    -

    Provided for informative purpose, e.g. to gather statistics about number of allocations or total amount of memory allocated in Vulkan.

    -

    Used in VmaAllocatorCreateInfo::pDeviceMemoryCallbacks.

    +

    Set of callbacks that the library will call for vkAllocateMemory and vkFreeMemory.

    +

    Provided for informative purpose, e.g. to gather statistics about number of allocations or total amount of memory allocated in Vulkan.

    +

    Used in VmaAllocatorCreateInfo::pDeviceMemoryCallbacks.

    Member Data Documentation

    - +

    ◆ pfnAllocate

    @@ -107,7 +107,7 @@ Public Attributes
    - +

    ◆ pfnFree

    @@ -123,7 +123,7 @@ Public Attributes
    - +

    ◆ pUserData

    @@ -140,12 +140,12 @@ Public Attributes
    The documentation for this struct was generated from the following file:
    -Generated by doxygen 1.9.1 +Generated by doxygen 1.9.2
    diff --git a/docs/html/struct_vma_pool.html b/docs/html/struct_vma_pool.html index efdf04a..c87851b 100644 --- a/docs/html/struct_vma_pool.html +++ b/docs/html/struct_vma_pool.html @@ -2,8 +2,8 @@ - - + + Vulkan Memory Allocator: VmaPool Struct Reference @@ -29,21 +29,22 @@ - + +/* @license-end */ +
    -
    -
    VmaPool Struct Reference
    +
    VmaPool Struct Reference
    @@ -71,16 +71,16 @@ $(function() {

    #include <vk_mem_alloc.h>

    Detailed Description

    -

    Represents custom memory pool.

    -

    Fill structure VmaPoolCreateInfo and call function vmaCreatePool() to create it. Call function vmaDestroyPool() to destroy it.

    -

    For more information see Custom memory pools.

    +

    Represents custom memory pool.

    +

    Fill structure VmaPoolCreateInfo and call function vmaCreatePool() to create it. Call function vmaDestroyPool() to destroy it.

    +

    For more information see Custom memory pools.

    The documentation for this struct was generated from the following file:
    -Generated by doxygen 1.9.1 +Generated by doxygen 1.9.2
    diff --git a/docs/html/struct_vma_pool_create_info-members.html b/docs/html/struct_vma_pool_create_info-members.html index a77487e..d1fa9e7 100644 --- a/docs/html/struct_vma_pool_create_info-members.html +++ b/docs/html/struct_vma_pool_create_info-members.html @@ -2,8 +2,8 @@ - - + + Vulkan Memory Allocator: Member List @@ -29,21 +29,22 @@
    - + +/* @license-end */ +
    -
    -
    VmaPoolCreateInfo Member List
    +
    VmaPoolCreateInfo Member List

    This is the complete list of members for VmaPoolCreateInfo, including all inherited members.

    - + - + - + - +
    blockSizeVmaPoolCreateInfo
    flagsVmaPoolCreateInfo
    flagsVmaPoolCreateInfo
    frameInUseCountVmaPoolCreateInfo
    maxBlockCountVmaPoolCreateInfo
    maxBlockCountVmaPoolCreateInfo
    memoryTypeIndexVmaPoolCreateInfo
    minAllocationAlignmentVmaPoolCreateInfo
    minAllocationAlignmentVmaPoolCreateInfo
    minBlockCountVmaPoolCreateInfo
    pMemoryAllocateNextVmaPoolCreateInfo
    pMemoryAllocateNextVmaPoolCreateInfo
    priorityVmaPoolCreateInfo
    -Generated by doxygen 1.9.1 +Generated by doxygen 1.9.2
    diff --git a/docs/html/struct_vma_pool_create_info.html b/docs/html/struct_vma_pool_create_info.html index 3c5f2ad..8f1a25f 100644 --- a/docs/html/struct_vma_pool_create_info.html +++ b/docs/html/struct_vma_pool_create_info.html @@ -2,8 +2,8 @@ - - + + Vulkan Memory Allocator: VmaPoolCreateInfo Struct Reference @@ -29,21 +29,22 @@
    - + +/* @license-end */ + -
    -
    VmaPoolCreateInfo Struct Reference
    +
    VmaPoolCreateInfo Struct Reference
    @@ -74,7 +74,7 @@ $(function() {

    #include <vk_mem_alloc.h>

    - @@ -105,9 +105,9 @@ Public Attributes

    +

    Public Attributes

    uint32_t memoryTypeIndex
     Vulkan memory type index to allocate this pool from. More...
     

    Detailed Description

    -

    Describes parameter of created VmaPool.

    +

    Describes parameter of created VmaPool.

    Member Data Documentation

    - +

    ◆ blockSize

    @@ -120,12 +120,12 @@ Public Attributes

    Size of a single VkDeviceMemory block to be allocated as part of this pool, in bytes. Optional.

    -

    Specify nonzero to set explicit, constant size of memory blocks used by this pool.

    -

    Leave 0 to use default and let the library manage block sizes automatically. Sizes of particular blocks may vary.

    +

    Specify nonzero to set explicit, constant size of memory blocks used by this pool.

    +

    Leave 0 to use default and let the library manage block sizes automatically. Sizes of particular blocks may vary.

    - +

    ◆ flags

    @@ -141,7 +141,7 @@ Public Attributes
    - +

    ◆ frameInUseCount

    @@ -154,13 +154,13 @@ Public Attributes

    Maximum number of additional frames that are in use at the same time as current frame.

    -

    This value is used only when you make allocations with VMA_ALLOCATION_CREATE_CAN_BECOME_LOST_BIT flag. Such allocation cannot become lost if allocation.lastUseFrameIndex >= allocator.currentFrameIndex - frameInUseCount.

    -

    For example, if you double-buffer your command buffers, so resources used for rendering in previous frame may still be in use by the GPU at the moment you allocate resources needed for the current frame, set this value to 1.

    -

    If you want to allow any allocations other than used in the current frame to become lost, set this value to 0.

    +

    This value is used only when you make allocations with VMA_ALLOCATION_CREATE_CAN_BECOME_LOST_BIT flag. Such allocation cannot become lost if allocation.lastUseFrameIndex >= allocator.currentFrameIndex - frameInUseCount.

    +

    For example, if you double-buffer your command buffers, so resources used for rendering in previous frame may still be in use by the GPU at the moment you allocate resources needed for the current frame, set this value to 1.

    +

    If you want to allow any allocations other than used in the current frame to become lost, set this value to 0.

    - +

    ◆ maxBlockCount

    @@ -173,12 +173,12 @@ Public Attributes

    Maximum number of blocks that can be allocated in this pool. Optional.

    -

    Set to 0 to use default, which is SIZE_MAX, which means no limit.

    -

    Set to same value as VmaPoolCreateInfo::minBlockCount to have fixed amount of memory allocated throughout whole lifetime of this pool.

    +

    Set to 0 to use default, which is SIZE_MAX, which means no limit.

    +

    Set to same value as VmaPoolCreateInfo::minBlockCount to have fixed amount of memory allocated throughout whole lifetime of this pool.

    - +

    ◆ memoryTypeIndex

    @@ -194,7 +194,7 @@ Public Attributes
    - +

    ◆ minAllocationAlignment

    @@ -207,11 +207,11 @@ Public Attributes

    Additional minimum alignment to be used for all allocations created from this pool. Can be 0.

    -

    Leave 0 (default) not to impose any additional alignment. If not 0, it must be a power of two. It can be useful in cases where alignment returned by Vulkan by functions like vkGetBufferMemoryRequirements is not enough, e.g. when doing interop with OpenGL.

    +

    Leave 0 (default) not to impose any additional alignment. If not 0, it must be a power of two. It can be useful in cases where alignment returned by Vulkan by functions like vkGetBufferMemoryRequirements is not enough, e.g. when doing interop with OpenGL.

    - +

    ◆ minBlockCount

    @@ -224,11 +224,11 @@ Public Attributes

    Minimum number of blocks to be always allocated in this pool, even if they stay empty.

    -

    Set to 0 to have no preallocated blocks and allow the pool be completely empty.

    +

    Set to 0 to have no preallocated blocks and allow the pool be completely empty.

    - +

    ◆ pMemoryAllocateNext

    @@ -241,12 +241,12 @@ Public Attributes

    Additional pNext chain to be attached to VkMemoryAllocateInfo used for every allocation made by this pool. Optional.

    -

    Optional, can be null. If not null, it must point to a pNext chain of structures that can be attached to VkMemoryAllocateInfo. It can be useful for special needs such as adding VkExportMemoryAllocateInfoKHR. Structures pointed by this member must remain alive and unchanged for the whole lifetime of the custom pool.

    -

    Please note that some structures, e.g. VkMemoryPriorityAllocateInfoEXT, VkMemoryDedicatedAllocateInfoKHR, can be attached automatically by this library when using other, more convenient of its features.

    +

    Optional, can be null. If not null, it must point to a pNext chain of structures that can be attached to VkMemoryAllocateInfo. It can be useful for special needs such as adding VkExportMemoryAllocateInfoKHR. Structures pointed by this member must remain alive and unchanged for the whole lifetime of the custom pool.

    +

    Please note that some structures, e.g. VkMemoryPriorityAllocateInfoEXT, VkMemoryDedicatedAllocateInfoKHR, can be attached automatically by this library when using other, more convenient of its features.

    - +

    ◆ priority

    @@ -259,17 +259,17 @@ Public Attributes

    A floating-point value between 0 and 1, indicating the priority of the allocations in this pool relative to other memory allocations.

    -

    It is used only when VMA_ALLOCATOR_CREATE_EXT_MEMORY_PRIORITY_BIT flag was used during creation of the VmaAllocator object. Otherwise, this variable is ignored.

    +

    It is used only when VMA_ALLOCATOR_CREATE_EXT_MEMORY_PRIORITY_BIT flag was used during creation of the VmaAllocator object. Otherwise, this variable is ignored.

    The documentation for this struct was generated from the following file:
    -Generated by doxygen 1.9.1 +Generated by doxygen 1.9.2
    diff --git a/docs/html/struct_vma_pool_stats-members.html b/docs/html/struct_vma_pool_stats-members.html index 14d90f6..0e79b96 100644 --- a/docs/html/struct_vma_pool_stats-members.html +++ b/docs/html/struct_vma_pool_stats-members.html @@ -2,8 +2,8 @@ - - + + Vulkan Memory Allocator: Member List @@ -29,21 +29,22 @@ - + +/* @license-end */ +
    -
    -
    VmaPoolStats Member List
    +
    VmaPoolStats Member List

    This is the complete list of members for VmaPoolStats, including all inherited members.

    - + - + - +
    allocationCountVmaPoolStats
    blockCountVmaPoolStats
    blockCountVmaPoolStats
    sizeVmaPoolStats
    unusedRangeCountVmaPoolStats
    unusedRangeCountVmaPoolStats
    unusedRangeSizeMaxVmaPoolStats
    unusedSizeVmaPoolStats
    unusedSizeVmaPoolStats
    -Generated by doxygen 1.9.1 +Generated by doxygen 1.9.2
    diff --git a/docs/html/struct_vma_pool_stats.html b/docs/html/struct_vma_pool_stats.html index 4dd6bd5..1801053 100644 --- a/docs/html/struct_vma_pool_stats.html +++ b/docs/html/struct_vma_pool_stats.html @@ -2,8 +2,8 @@ - - + + Vulkan Memory Allocator: VmaPoolStats Struct Reference @@ -29,21 +29,22 @@
    - + +/* @license-end */ +
    Public Attributes | List of all members
    -
    -
    VmaPoolStats Struct Reference
    +
    VmaPoolStats Struct Reference
    @@ -74,7 +74,7 @@ $(function() {

    #include <vk_mem_alloc.h>

    - @@ -96,9 +96,9 @@ Public Attributes

    +

    Public Attributes

    VkDeviceSize size
     Total amount of VkDeviceMemory allocated from Vulkan for this pool, in bytes. More...
     

    Detailed Description

    -

    Describes parameter of existing VmaPool.

    +

    Describes parameter of existing VmaPool.

    Member Data Documentation

    - +

    ◆ allocationCount

    @@ -114,7 +114,7 @@ Public Attributes
    - +

    ◆ blockCount

    @@ -130,7 +130,7 @@ Public Attributes
    - +

    ◆ size

    @@ -146,7 +146,7 @@ Public Attributes
    - +

    ◆ unusedRangeCount

    @@ -162,7 +162,7 @@ Public Attributes
    - +

    ◆ unusedRangeSizeMax

    @@ -175,11 +175,11 @@ Public Attributes

    Size of the largest continuous free memory region available for new allocation.

    -

    Making a new allocation of that size is not guaranteed to succeed because of possible additional margin required to respect alignment and buffer/image granularity.

    +

    Making a new allocation of that size is not guaranteed to succeed because of possible additional margin required to respect alignment and buffer/image granularity.

    - +

    ◆ unusedSize

    @@ -196,12 +196,12 @@ Public Attributes
    The documentation for this struct was generated from the following file:
    -Generated by doxygen 1.9.1 +Generated by doxygen 1.9.2
    diff --git a/docs/html/struct_vma_record_settings-members.html b/docs/html/struct_vma_record_settings-members.html index c7eef40..7724949 100644 --- a/docs/html/struct_vma_record_settings-members.html +++ b/docs/html/struct_vma_record_settings-members.html @@ -2,8 +2,8 @@ - - + + Vulkan Memory Allocator: Member List @@ -29,21 +29,22 @@ - + +/* @license-end */ +
    -
    -
    VmaRecordSettings Member List
    +
    VmaRecordSettings Member List

    This is the complete list of members for VmaRecordSettings, including all inherited members.

    - +
    flagsVmaRecordSettings
    pFilePathVmaRecordSettings
    pFilePathVmaRecordSettings
    -Generated by doxygen 1.9.1 +Generated by doxygen 1.9.2
    diff --git a/docs/html/struct_vma_record_settings.html b/docs/html/struct_vma_record_settings.html index f9ccf1e..da6cd19 100644 --- a/docs/html/struct_vma_record_settings.html +++ b/docs/html/struct_vma_record_settings.html @@ -2,8 +2,8 @@ - - + + Vulkan Memory Allocator: VmaRecordSettings Struct Reference @@ -29,21 +29,22 @@
    - + +/* @license-end */ +
    Public Attributes | List of all members
    -
    -
    VmaRecordSettings Struct Reference
    +
    VmaRecordSettings Struct Reference
    @@ -74,7 +74,7 @@ $(function() {

    #include <vk_mem_alloc.h>

    - @@ -84,9 +84,9 @@ Public Attributes

    +

    Public Attributes

    VmaRecordFlags flags
     Flags for recording. Use VmaRecordFlagBits enum. More...
     

    Detailed Description

    -

    Parameters for recording calls to VMA functions. To be used in VmaAllocatorCreateInfo::pRecordSettings.

    +

    Parameters for recording calls to VMA functions. To be used in VmaAllocatorCreateInfo::pRecordSettings.

    Member Data Documentation

    - +

    ◆ flags

    @@ -102,7 +102,7 @@ Public Attributes
    - +

    ◆ pFilePath

    @@ -115,17 +115,17 @@ Public Attributes

    Path to the file that should be written by the recording.

    -

    Suggested extension: "csv". If the file already exists, it will be overwritten. It will be opened for the whole time VmaAllocator object is alive. If opening this file fails, creation of the whole allocator object fails.

    +

    Suggested extension: "csv". If the file already exists, it will be overwritten. It will be opened for the whole time VmaAllocator object is alive. If opening this file fails, creation of the whole allocator object fails.

    The documentation for this struct was generated from the following file:
    -Generated by doxygen 1.9.1 +Generated by doxygen 1.9.2
    diff --git a/docs/html/struct_vma_stat_info-members.html b/docs/html/struct_vma_stat_info-members.html index 332e116..e498b99 100644 --- a/docs/html/struct_vma_stat_info-members.html +++ b/docs/html/struct_vma_stat_info-members.html @@ -2,8 +2,8 @@ - - + + Vulkan Memory Allocator: Member List @@ -29,21 +29,22 @@ - + +/* @license-end */ +
    -
    -
    VmaStatInfo Member List
    +
    VmaStatInfo Member List

    This is the complete list of members for VmaStatInfo, including all inherited members.

    - + - + - + - + - +
    allocationCountVmaStatInfo
    allocationSizeAvgVmaStatInfo
    allocationSizeAvgVmaStatInfo
    allocationSizeMaxVmaStatInfo
    allocationSizeMinVmaStatInfo
    allocationSizeMinVmaStatInfo
    blockCountVmaStatInfo
    unusedBytesVmaStatInfo
    unusedBytesVmaStatInfo
    unusedRangeCountVmaStatInfo
    unusedRangeSizeAvgVmaStatInfo
    unusedRangeSizeAvgVmaStatInfo
    unusedRangeSizeMaxVmaStatInfo
    unusedRangeSizeMinVmaStatInfo
    unusedRangeSizeMinVmaStatInfo
    usedBytesVmaStatInfo
    -Generated by doxygen 1.9.1 +Generated by doxygen 1.9.2
    diff --git a/docs/html/struct_vma_stat_info.html b/docs/html/struct_vma_stat_info.html index fbea80d..003f8ea 100644 --- a/docs/html/struct_vma_stat_info.html +++ b/docs/html/struct_vma_stat_info.html @@ -2,8 +2,8 @@ - - + + Vulkan Memory Allocator: VmaStatInfo Struct Reference @@ -29,21 +29,22 @@
    - + +/* @license-end */ +
    Public Attributes | List of all members
    -
    -
    VmaStatInfo Struct Reference
    +
    VmaStatInfo Struct Reference
    @@ -74,7 +74,7 @@ $(function() {

    #include <vk_mem_alloc.h>

    - @@ -105,9 +105,9 @@ Public Attributes

    +

    Public Attributes

    uint32_t blockCount
     Number of VkDeviceMemory Vulkan memory blocks allocated. More...
     

    Detailed Description

    -

    Calculated statistics of memory usage in entire allocator.

    +

    Calculated statistics of memory usage in entire allocator.

    Member Data Documentation

    - +

    ◆ allocationCount

    @@ -123,7 +123,7 @@ Public Attributes
    - +

    ◆ allocationSizeAvg

    @@ -137,7 +137,7 @@ Public Attributes
    - +

    ◆ allocationSizeMax

    @@ -151,7 +151,7 @@ Public Attributes
    - +

    ◆ allocationSizeMin

    @@ -165,7 +165,7 @@ Public Attributes
    - +

    ◆ blockCount

    @@ -181,7 +181,7 @@ Public Attributes
    - +

    ◆ unusedBytes

    @@ -197,7 +197,7 @@ Public Attributes
    - +

    ◆ unusedRangeCount

    @@ -213,7 +213,7 @@ Public Attributes
    - +

    ◆ unusedRangeSizeAvg

    @@ -227,7 +227,7 @@ Public Attributes
    - +

    ◆ unusedRangeSizeMax

    @@ -241,7 +241,7 @@ Public Attributes
    - +

    ◆ unusedRangeSizeMin

    @@ -255,7 +255,7 @@ Public Attributes
    - +

    ◆ usedBytes

    @@ -272,12 +272,12 @@ Public Attributes
    The documentation for this struct was generated from the following file:
    -Generated by doxygen 1.9.1 +Generated by doxygen 1.9.2
    diff --git a/docs/html/struct_vma_stats-members.html b/docs/html/struct_vma_stats-members.html index 14ae84a..4a25867 100644 --- a/docs/html/struct_vma_stats-members.html +++ b/docs/html/struct_vma_stats-members.html @@ -2,8 +2,8 @@ - - + + Vulkan Memory Allocator: Member List @@ -29,21 +29,22 @@ - + +/* @license-end */ +
    -
    -
    VmaStats Member List
    +
    VmaStats Member List

    This is the complete list of members for VmaStats, including all inherited members.

    - +
    memoryHeapVmaStats
    memoryTypeVmaStats
    memoryTypeVmaStats
    totalVmaStats
    -Generated by doxygen 1.9.1 +Generated by doxygen 1.9.2
    diff --git a/docs/html/struct_vma_stats.html b/docs/html/struct_vma_stats.html index 717b9bf..519980e 100644 --- a/docs/html/struct_vma_stats.html +++ b/docs/html/struct_vma_stats.html @@ -2,8 +2,8 @@ - - + + Vulkan Memory Allocator: VmaStats Struct Reference @@ -29,21 +29,22 @@
    - + +/* @license-end */ +
    Public Attributes | List of all members
    -
    -
    VmaStats Struct Reference
    +
    VmaStats Struct Reference
    @@ -74,7 +74,7 @@ $(function() {

    #include <vk_mem_alloc.h>

    - @@ -84,9 +84,9 @@ Public Attributes

    +

    Public Attributes

    VmaStatInfo memoryType [VK_MAX_MEMORY_TYPES]
     
     

    Detailed Description

    -

    General statistics from current state of Allocator.

    +

    General statistics from current state of Allocator.

    Member Data Documentation

    - +

    ◆ memoryHeap

    @@ -100,7 +100,7 @@ Public Attributes
    - +

    ◆ memoryType

    @@ -114,7 +114,7 @@ Public Attributes
    - +

    ◆ total

    @@ -129,12 +129,12 @@ Public Attributes
    The documentation for this struct was generated from the following file:
    -Generated by doxygen 1.9.1 +Generated by doxygen 1.9.2
    diff --git a/docs/html/struct_vma_vulkan_functions-members.html b/docs/html/struct_vma_vulkan_functions-members.html index 877721c..9b65af5 100644 --- a/docs/html/struct_vma_vulkan_functions-members.html +++ b/docs/html/struct_vma_vulkan_functions-members.html @@ -2,8 +2,8 @@ - - + + Vulkan Memory Allocator: Member List @@ -29,21 +29,22 @@ - + +/* @license-end */ +
    -
    -
    VmaVulkanFunctions Member List
    +
    VmaVulkanFunctions Member List

    This is the complete list of members for VmaVulkanFunctions, including all inherited members.

    - + - + - + - + - + - + - + - +
    vkAllocateMemoryVmaVulkanFunctions
    vkBindBufferMemoryVmaVulkanFunctions
    vkBindBufferMemoryVmaVulkanFunctions
    vkBindImageMemoryVmaVulkanFunctions
    vkCmdCopyBufferVmaVulkanFunctions
    vkCmdCopyBufferVmaVulkanFunctions
    vkCreateBufferVmaVulkanFunctions
    vkCreateImageVmaVulkanFunctions
    vkCreateImageVmaVulkanFunctions
    vkDestroyBufferVmaVulkanFunctions
    vkDestroyImageVmaVulkanFunctions
    vkDestroyImageVmaVulkanFunctions
    vkFlushMappedMemoryRangesVmaVulkanFunctions
    vkFreeMemoryVmaVulkanFunctions
    vkFreeMemoryVmaVulkanFunctions
    vkGetBufferMemoryRequirementsVmaVulkanFunctions
    vkGetImageMemoryRequirementsVmaVulkanFunctions
    vkGetImageMemoryRequirementsVmaVulkanFunctions
    vkGetPhysicalDeviceMemoryPropertiesVmaVulkanFunctions
    vkGetPhysicalDevicePropertiesVmaVulkanFunctions
    vkGetPhysicalDevicePropertiesVmaVulkanFunctions
    vkInvalidateMappedMemoryRangesVmaVulkanFunctions
    vkMapMemoryVmaVulkanFunctions
    vkMapMemoryVmaVulkanFunctions
    vkUnmapMemoryVmaVulkanFunctions
    -Generated by doxygen 1.9.1 +Generated by doxygen 1.9.2
    diff --git a/docs/html/struct_vma_vulkan_functions.html b/docs/html/struct_vma_vulkan_functions.html index e2a46dd..c5a8b32 100644 --- a/docs/html/struct_vma_vulkan_functions.html +++ b/docs/html/struct_vma_vulkan_functions.html @@ -2,8 +2,8 @@ - - + + Vulkan Memory Allocator: VmaVulkanFunctions Struct Reference @@ -29,21 +29,22 @@
    - + +/* @license-end */ +
    Public Attributes | List of all members
    -
    -
    VmaVulkanFunctions Struct Reference
    +
    VmaVulkanFunctions Struct Reference
    @@ -74,7 +74,7 @@ $(function() {

    #include <vk_mem_alloc.h>

    - @@ -112,10 +112,10 @@ Public Attributes

    +

    Public Attributes

    PFN_vkGetPhysicalDeviceProperties vkGetPhysicalDeviceProperties
     
     

    Detailed Description

    -

    Pointers to some Vulkan functions - a subset used by the library.

    -

    Used in VmaAllocatorCreateInfo::pVulkanFunctions.

    +

    Pointers to some Vulkan functions - a subset used by the library.

    +

    Used in VmaAllocatorCreateInfo::pVulkanFunctions.

    Member Data Documentation

    - +

    ◆ vkAllocateMemory

    @@ -129,7 +129,7 @@ Public Attributes
    - +

    ◆ vkBindBufferMemory

    @@ -143,7 +143,7 @@ Public Attributes
    - +

    ◆ vkBindImageMemory

    @@ -157,7 +157,7 @@ Public Attributes
    - +

    ◆ vkCmdCopyBuffer

    @@ -171,7 +171,7 @@ Public Attributes
    - +

    ◆ vkCreateBuffer

    @@ -185,7 +185,7 @@ Public Attributes
    - +

    ◆ vkCreateImage

    @@ -199,7 +199,7 @@ Public Attributes
    - +

    ◆ vkDestroyBuffer

    @@ -213,7 +213,7 @@ Public Attributes
    - +

    ◆ vkDestroyImage

    @@ -227,7 +227,7 @@ Public Attributes
    - +

    ◆ vkFlushMappedMemoryRanges

    @@ -241,7 +241,7 @@ Public Attributes
    - +

    ◆ vkFreeMemory

    @@ -255,7 +255,7 @@ Public Attributes
    - +

    ◆ vkGetBufferMemoryRequirements

    @@ -269,7 +269,7 @@ Public Attributes
    - +

    ◆ vkGetImageMemoryRequirements

    @@ -283,7 +283,7 @@ Public Attributes
    - +

    ◆ vkGetPhysicalDeviceMemoryProperties

    @@ -297,7 +297,7 @@ Public Attributes
    - +

    ◆ vkGetPhysicalDeviceProperties

    @@ -311,7 +311,7 @@ Public Attributes
    - +

    ◆ vkInvalidateMappedMemoryRanges

    @@ -325,7 +325,7 @@ Public Attributes
    - +

    ◆ vkMapMemory

    @@ -339,7 +339,7 @@ Public Attributes
    - +

    ◆ vkUnmapMemory

    @@ -354,12 +354,12 @@ Public Attributes
    The documentation for this struct was generated from the following file:
    -Generated by doxygen 1.9.1 +Generated by doxygen 1.9.2
    diff --git a/docs/html/tabs.css b/docs/html/tabs.css index 85a0cd5..00d1c60 100644 --- a/docs/html/tabs.css +++ b/docs/html/tabs.css @@ -1 +1 @@ -.sm{position:relative;z-index:9999}.sm,.sm ul,.sm li{display:block;list-style:none;margin:0;padding:0;line-height:normal;direction:ltr;text-align:left;-webkit-tap-highlight-color:rgba(0,0,0,0)}.sm-rtl,.sm-rtl ul,.sm-rtl li{direction:rtl;text-align:right}.sm>li>h1,.sm>li>h2,.sm>li>h3,.sm>li>h4,.sm>li>h5,.sm>li>h6{margin:0;padding:0}.sm ul{display:none}.sm li,.sm a{position:relative}.sm a{display:block}.sm a.disabled{cursor:not-allowed}.sm:after{content:"\00a0";display:block;height:0;font:0/0 serif;clear:both;visibility:hidden;overflow:hidden}.sm,.sm *,.sm *:before,.sm *:after{-moz-box-sizing:border-box;-webkit-box-sizing:border-box;box-sizing:border-box}.sm-dox{background-image:url("tab_b.png")}.sm-dox a,.sm-dox a:focus,.sm-dox a:hover,.sm-dox a:active{padding:0 12px;padding-right:43px;font-family:"Lucida Grande","Geneva","Helvetica",Arial,sans-serif;font-size:13px;font-weight:bold;line-height:36px;text-decoration:none;text-shadow:0 1px 1px rgba(255,255,255,0.9);color:#283a5d;outline:0}.sm-dox a:hover{background-image:url("tab_a.png");background-repeat:repeat-x;color:white;text-shadow:0 1px 1px black}.sm-dox a.current{color:#d23600}.sm-dox a.disabled{color:#bbb}.sm-dox a span.sub-arrow{position:absolute;top:50%;margin-top:-14px;left:auto;right:3px;width:28px;height:28px;overflow:hidden;font:bold 12px/28px monospace!important;text-align:center;text-shadow:none;background:rgba(255,255,255,0.5);-moz-border-radius:5px;-webkit-border-radius:5px;border-radius:5px}.sm-dox a.highlighted span.sub-arrow:before{display:block;content:'-'}.sm-dox>li:first-child>a,.sm-dox>li:first-child>:not(ul) a{-moz-border-radius:5px 5px 0 0;-webkit-border-radius:5px;border-radius:5px 5px 0 0}.sm-dox>li:last-child>a,.sm-dox>li:last-child>*:not(ul) a,.sm-dox>li:last-child>ul,.sm-dox>li:last-child>ul>li:last-child>a,.sm-dox>li:last-child>ul>li:last-child>*:not(ul) a,.sm-dox>li:last-child>ul>li:last-child>ul,.sm-dox>li:last-child>ul>li:last-child>ul>li:last-child>a,.sm-dox>li:last-child>ul>li:last-child>ul>li:last-child>*:not(ul) a,.sm-dox>li:last-child>ul>li:last-child>ul>li:last-child>ul,.sm-dox>li:last-child>ul>li:last-child>ul>li:last-child>ul>li:last-child>a,.sm-dox>li:last-child>ul>li:last-child>ul>li:last-child>ul>li:last-child>*:not(ul) a,.sm-dox>li:last-child>ul>li:last-child>ul>li:last-child>ul>li:last-child>ul,.sm-dox>li:last-child>ul>li:last-child>ul>li:last-child>ul>li:last-child>ul>li:last-child>a,.sm-dox>li:last-child>ul>li:last-child>ul>li:last-child>ul>li:last-child>ul>li:last-child>*:not(ul) a,.sm-dox>li:last-child>ul>li:last-child>ul>li:last-child>ul>li:last-child>ul>li:last-child>ul{-moz-border-radius:0 0 5px 5px;-webkit-border-radius:0;border-radius:0 0 5px 5px}.sm-dox>li:last-child>a.highlighted,.sm-dox>li:last-child>*:not(ul) a.highlighted,.sm-dox>li:last-child>ul>li:last-child>a.highlighted,.sm-dox>li:last-child>ul>li:last-child>*:not(ul) a.highlighted,.sm-dox>li:last-child>ul>li:last-child>ul>li:last-child>a.highlighted,.sm-dox>li:last-child>ul>li:last-child>ul>li:last-child>*:not(ul) a.highlighted,.sm-dox>li:last-child>ul>li:last-child>ul>li:last-child>ul>li:last-child>a.highlighted,.sm-dox>li:last-child>ul>li:last-child>ul>li:last-child>ul>li:last-child>*:not(ul) a.highlighted,.sm-dox>li:last-child>ul>li:last-child>ul>li:last-child>ul>li:last-child>ul>li:last-child>a.highlighted,.sm-dox>li:last-child>ul>li:last-child>ul>li:last-child>ul>li:last-child>ul>li:last-child>*:not(ul) a.highlighted{-moz-border-radius:0;-webkit-border-radius:0;border-radius:0}.sm-dox ul{background:rgba(162,162,162,0.1)}.sm-dox ul a,.sm-dox ul a:focus,.sm-dox ul a:hover,.sm-dox ul a:active{font-size:12px;border-left:8px solid transparent;line-height:36px;text-shadow:none;background-color:white;background-image:none}.sm-dox ul a:hover{background-image:url("tab_a.png");background-repeat:repeat-x;color:white;text-shadow:0 1px 1px black}.sm-dox ul ul a,.sm-dox ul ul a:hover,.sm-dox ul ul a:focus,.sm-dox ul ul a:active{border-left:16px solid transparent}.sm-dox ul ul ul a,.sm-dox ul ul ul a:hover,.sm-dox ul ul ul a:focus,.sm-dox ul ul ul a:active{border-left:24px solid transparent}.sm-dox ul ul ul ul a,.sm-dox ul ul ul ul a:hover,.sm-dox ul ul ul ul a:focus,.sm-dox ul ul ul ul a:active{border-left:32px solid transparent}.sm-dox ul ul ul ul ul a,.sm-dox ul ul ul ul ul a:hover,.sm-dox ul ul ul ul ul a:focus,.sm-dox ul ul ul ul ul a:active{border-left:40px solid transparent}@media(min-width:768px){.sm-dox ul{position:absolute;width:12em}.sm-dox li{float:left}.sm-dox.sm-rtl li{float:right}.sm-dox ul li,.sm-dox.sm-rtl ul li,.sm-dox.sm-vertical li{float:none}.sm-dox a{white-space:nowrap}.sm-dox ul a,.sm-dox.sm-vertical a{white-space:normal}.sm-dox .sm-nowrap>li>a,.sm-dox .sm-nowrap>li>:not(ul) a{white-space:nowrap}.sm-dox{padding:0 10px;background-image:url("tab_b.png");line-height:36px}.sm-dox a span.sub-arrow{top:50%;margin-top:-2px;right:12px;width:0;height:0;border-width:4px;border-style:solid dashed dashed dashed;border-color:#283a5d transparent transparent transparent;background:transparent;-moz-border-radius:0;-webkit-border-radius:0;border-radius:0}.sm-dox a,.sm-dox a:focus,.sm-dox a:active,.sm-dox a:hover,.sm-dox a.highlighted{padding:0 12px;background-image:url("tab_s.png");background-repeat:no-repeat;background-position:right;-moz-border-radius:0!important;-webkit-border-radius:0;border-radius:0!important}.sm-dox a:hover{background-image:url("tab_a.png");background-repeat:repeat-x;color:white;text-shadow:0 1px 1px black}.sm-dox a:hover span.sub-arrow{border-color:white transparent transparent transparent}.sm-dox a.has-submenu{padding-right:24px}.sm-dox li{border-top:0}.sm-dox>li>ul:before,.sm-dox>li>ul:after{content:'';position:absolute;top:-18px;left:30px;width:0;height:0;overflow:hidden;border-width:9px;border-style:dashed dashed solid dashed;border-color:transparent transparent #bbb transparent}.sm-dox>li>ul:after{top:-16px;left:31px;border-width:8px;border-color:transparent transparent #fff transparent}.sm-dox ul{border:1px solid #bbb;padding:5px 0;background:#fff;-moz-border-radius:5px!important;-webkit-border-radius:5px;border-radius:5px!important;-moz-box-shadow:0 5px 9px rgba(0,0,0,0.2);-webkit-box-shadow:0 5px 9px rgba(0,0,0,0.2);box-shadow:0 5px 9px rgba(0,0,0,0.2)}.sm-dox ul a span.sub-arrow{right:8px;top:50%;margin-top:-5px;border-width:5px;border-color:transparent transparent transparent #555;border-style:dashed dashed dashed solid}.sm-dox ul a,.sm-dox ul a:hover,.sm-dox ul a:focus,.sm-dox ul a:active,.sm-dox ul a.highlighted{color:#555;background-image:none;border:0!important;color:#555;background-image:none}.sm-dox ul a:hover{background-image:url("tab_a.png");background-repeat:repeat-x;color:white;text-shadow:0 1px 1px black}.sm-dox ul a:hover span.sub-arrow{border-color:transparent transparent transparent white}.sm-dox span.scroll-up,.sm-dox span.scroll-down{position:absolute;display:none;visibility:hidden;overflow:hidden;background:#fff;height:36px}.sm-dox span.scroll-up:hover,.sm-dox span.scroll-down:hover{background:#eee}.sm-dox span.scroll-up:hover span.scroll-up-arrow,.sm-dox span.scroll-up:hover span.scroll-down-arrow{border-color:transparent transparent #d23600 transparent}.sm-dox span.scroll-down:hover span.scroll-down-arrow{border-color:#d23600 transparent transparent transparent}.sm-dox span.scroll-up-arrow,.sm-dox span.scroll-down-arrow{position:absolute;top:0;left:50%;margin-left:-6px;width:0;height:0;overflow:hidden;border-width:6px;border-style:dashed dashed solid dashed;border-color:transparent transparent #555 transparent}.sm-dox span.scroll-down-arrow{top:8px;border-style:solid dashed dashed dashed;border-color:#555 transparent transparent transparent}.sm-dox.sm-rtl a.has-submenu{padding-right:12px;padding-left:24px}.sm-dox.sm-rtl a span.sub-arrow{right:auto;left:12px}.sm-dox.sm-rtl.sm-vertical a.has-submenu{padding:10px 20px}.sm-dox.sm-rtl.sm-vertical a span.sub-arrow{right:auto;left:8px;border-style:dashed solid dashed dashed;border-color:transparent #555 transparent transparent}.sm-dox.sm-rtl>li>ul:before{left:auto;right:30px}.sm-dox.sm-rtl>li>ul:after{left:auto;right:31px}.sm-dox.sm-rtl ul a.has-submenu{padding:10px 20px!important}.sm-dox.sm-rtl ul a span.sub-arrow{right:auto;left:8px;border-style:dashed solid dashed dashed;border-color:transparent #555 transparent transparent}.sm-dox.sm-vertical{padding:10px 0;-moz-border-radius:5px;-webkit-border-radius:5px;border-radius:5px}.sm-dox.sm-vertical a{padding:10px 20px}.sm-dox.sm-vertical a:hover,.sm-dox.sm-vertical a:focus,.sm-dox.sm-vertical a:active,.sm-dox.sm-vertical a.highlighted{background:#fff}.sm-dox.sm-vertical a.disabled{background-image:url("tab_b.png")}.sm-dox.sm-vertical a span.sub-arrow{right:8px;top:50%;margin-top:-5px;border-width:5px;border-style:dashed dashed dashed solid;border-color:transparent transparent transparent #555}.sm-dox.sm-vertical>li>ul:before,.sm-dox.sm-vertical>li>ul:after{display:none}.sm-dox.sm-vertical ul a{padding:10px 20px}.sm-dox.sm-vertical ul a:hover,.sm-dox.sm-vertical ul a:focus,.sm-dox.sm-vertical ul a:active,.sm-dox.sm-vertical ul a.highlighted{background:#eee}.sm-dox.sm-vertical ul a.disabled{background:#fff}} \ No newline at end of file +.sm{position:relative;z-index:9999}.sm,.sm ul,.sm li{display:block;list-style:none;margin:0;padding:0;line-height:normal;direction:ltr;text-align:left;-webkit-tap-highlight-color:rgba(0,0,0,0)}.sm-rtl,.sm-rtl ul,.sm-rtl li{direction:rtl;text-align:right}.sm>li>h1,.sm>li>h2,.sm>li>h3,.sm>li>h4,.sm>li>h5,.sm>li>h6{margin:0;padding:0}.sm ul{display:none}.sm li,.sm a{position:relative}.sm a{display:block}.sm a.disabled{cursor:not-allowed}.sm:after{content:"\00a0";display:block;height:0;font:0/0 serif;clear:both;visibility:hidden;overflow:hidden}.sm,.sm *,.sm *:before,.sm *:after{-moz-box-sizing:border-box;-webkit-box-sizing:border-box;box-sizing:border-box}.main-menu-btn{position:relative;display:inline-block;width:36px;height:36px;text-indent:36px;margin-left:8px;white-space:nowrap;overflow:hidden;cursor:pointer;-webkit-tap-highlight-color:rgba(0,0,0,0)}.main-menu-btn-icon,.main-menu-btn-icon:before,.main-menu-btn-icon:after{position:absolute;top:50%;left:2px;height:2px;width:24px;background:#666;-webkit-transition:all .25s;transition:all .25s}.main-menu-btn-icon:before{content:'';top:-7px;left:0}.main-menu-btn-icon:after{content:'';top:7px;left:0}#main-menu-state:checked ~ .main-menu-btn .main-menu-btn-icon{height:0}#main-menu-state:checked ~ .main-menu-btn .main-menu-btn-icon:before{top:0;-webkit-transform:rotate(-45deg);transform:rotate(-45deg)}#main-menu-state:checked ~ .main-menu-btn .main-menu-btn-icon:after{top:0;-webkit-transform:rotate(45deg);transform:rotate(45deg)}#main-menu-state{position:absolute;width:1px;height:1px;margin:-1px;border:0;padding:0;overflow:hidden;clip:rect(1px,1px,1px,1px)}#main-menu-state:not(:checked) ~ #main-menu{display:none}#main-menu-state:checked ~ #main-menu{display:block}@media(min-width:768px){.main-menu-btn{position:absolute;top:-99999px}#main-menu-state:not(:checked) ~ #main-menu{display:block}}.sm-dox{background-image:url("tab_b.png")}.sm-dox a,.sm-dox a:focus,.sm-dox a:hover,.sm-dox a:active{padding:0 12px;padding-right:43px;font-family:"Lucida Grande","Geneva","Helvetica",Arial,sans-serif;font-size:13px;font-weight:bold;line-height:36px;text-decoration:none;text-shadow:0 1px 1px rgba(255,255,255,0.9);color:#283a5d;outline:0}.sm-dox a:hover{background-image:url("tab_a.png");background-repeat:repeat-x;color:white;text-shadow:0 1px 1px black}.sm-dox a.current{color:#d23600}.sm-dox a.disabled{color:#bbb}.sm-dox a span.sub-arrow{position:absolute;top:50%;margin-top:-14px;left:auto;right:3px;width:28px;height:28px;overflow:hidden;font:bold 12px/28px monospace !important;text-align:center;text-shadow:none;background:rgba(255,255,255,0.5);-moz-border-radius:5px;-webkit-border-radius:5px;border-radius:5px}.sm-dox a span.sub-arrow:before{display:block;content:'+'}.sm-dox a.highlighted span.sub-arrow:before{display:block;content:'-'}.sm-dox>li:first-child>a,.sm-dox>li:first-child>:not(ul) a{-moz-border-radius:5px 5px 0 0;-webkit-border-radius:5px;border-radius:5px 5px 0 0}.sm-dox>li:last-child>a,.sm-dox>li:last-child>*:not(ul) a,.sm-dox>li:last-child>ul,.sm-dox>li:last-child>ul>li:last-child>a,.sm-dox>li:last-child>ul>li:last-child>*:not(ul) a,.sm-dox>li:last-child>ul>li:last-child>ul,.sm-dox>li:last-child>ul>li:last-child>ul>li:last-child>a,.sm-dox>li:last-child>ul>li:last-child>ul>li:last-child>*:not(ul) a,.sm-dox>li:last-child>ul>li:last-child>ul>li:last-child>ul,.sm-dox>li:last-child>ul>li:last-child>ul>li:last-child>ul>li:last-child>a,.sm-dox>li:last-child>ul>li:last-child>ul>li:last-child>ul>li:last-child>*:not(ul) a,.sm-dox>li:last-child>ul>li:last-child>ul>li:last-child>ul>li:last-child>ul,.sm-dox>li:last-child>ul>li:last-child>ul>li:last-child>ul>li:last-child>ul>li:last-child>a,.sm-dox>li:last-child>ul>li:last-child>ul>li:last-child>ul>li:last-child>ul>li:last-child>*:not(ul) a,.sm-dox>li:last-child>ul>li:last-child>ul>li:last-child>ul>li:last-child>ul>li:last-child>ul{-moz-border-radius:0 0 5px 5px;-webkit-border-radius:0;border-radius:0 0 5px 5px}.sm-dox>li:last-child>a.highlighted,.sm-dox>li:last-child>*:not(ul) a.highlighted,.sm-dox>li:last-child>ul>li:last-child>a.highlighted,.sm-dox>li:last-child>ul>li:last-child>*:not(ul) a.highlighted,.sm-dox>li:last-child>ul>li:last-child>ul>li:last-child>a.highlighted,.sm-dox>li:last-child>ul>li:last-child>ul>li:last-child>*:not(ul) a.highlighted,.sm-dox>li:last-child>ul>li:last-child>ul>li:last-child>ul>li:last-child>a.highlighted,.sm-dox>li:last-child>ul>li:last-child>ul>li:last-child>ul>li:last-child>*:not(ul) a.highlighted,.sm-dox>li:last-child>ul>li:last-child>ul>li:last-child>ul>li:last-child>ul>li:last-child>a.highlighted,.sm-dox>li:last-child>ul>li:last-child>ul>li:last-child>ul>li:last-child>ul>li:last-child>*:not(ul) a.highlighted{-moz-border-radius:0;-webkit-border-radius:0;border-radius:0}.sm-dox ul{background:rgba(162,162,162,0.1)}.sm-dox ul a,.sm-dox ul a:focus,.sm-dox ul a:hover,.sm-dox ul a:active{font-size:12px;border-left:8px solid transparent;line-height:36px;text-shadow:none;background-color:white;background-image:none}.sm-dox ul a:hover{background-image:url("tab_a.png");background-repeat:repeat-x;color:white;text-shadow:0 1px 1px black}.sm-dox ul ul a,.sm-dox ul ul a:hover,.sm-dox ul ul a:focus,.sm-dox ul ul a:active{border-left:16px solid transparent}.sm-dox ul ul ul a,.sm-dox ul ul ul a:hover,.sm-dox ul ul ul a:focus,.sm-dox ul ul ul a:active{border-left:24px solid transparent}.sm-dox ul ul ul ul a,.sm-dox ul ul ul ul a:hover,.sm-dox ul ul ul ul a:focus,.sm-dox ul ul ul ul a:active{border-left:32px solid transparent}.sm-dox ul ul ul ul ul a,.sm-dox ul ul ul ul ul a:hover,.sm-dox ul ul ul ul ul a:focus,.sm-dox ul ul ul ul ul a:active{border-left:40px solid transparent}@media(min-width:768px){.sm-dox ul{position:absolute;width:12em}.sm-dox li{float:left}.sm-dox.sm-rtl li{float:right}.sm-dox ul li,.sm-dox.sm-rtl ul li,.sm-dox.sm-vertical li{float:none}.sm-dox a{white-space:nowrap}.sm-dox ul a,.sm-dox.sm-vertical a{white-space:normal}.sm-dox .sm-nowrap>li>a,.sm-dox .sm-nowrap>li>:not(ul) a{white-space:nowrap}.sm-dox{padding:0 10px;background-image:url("tab_b.png");line-height:36px}.sm-dox a span.sub-arrow{top:50%;margin-top:-2px;right:12px;width:0;height:0;border-width:4px;border-style:solid dashed dashed dashed;border-color:#283a5d transparent transparent transparent;background:transparent;-moz-border-radius:0;-webkit-border-radius:0;border-radius:0}.sm-dox a,.sm-dox a:focus,.sm-dox a:active,.sm-dox a:hover,.sm-dox a.highlighted{padding:0 12px;background-image:url("tab_s.png");background-repeat:no-repeat;background-position:right;-moz-border-radius:0 !important;-webkit-border-radius:0;border-radius:0 !important}.sm-dox a:hover{background-image:url("tab_a.png");background-repeat:repeat-x;color:white;text-shadow:0 1px 1px black}.sm-dox a:hover span.sub-arrow{border-color:white transparent transparent transparent}.sm-dox a.has-submenu{padding-right:24px}.sm-dox li{border-top:0}.sm-dox>li>ul:before,.sm-dox>li>ul:after{content:'';position:absolute;top:-18px;left:30px;width:0;height:0;overflow:hidden;border-width:9px;border-style:dashed dashed solid dashed;border-color:transparent transparent #bbb transparent}.sm-dox>li>ul:after{top:-16px;left:31px;border-width:8px;border-color:transparent transparent #fff transparent}.sm-dox ul{border:1px solid #bbb;padding:5px 0;background:#fff;-moz-border-radius:5px !important;-webkit-border-radius:5px;border-radius:5px !important;-moz-box-shadow:0 5px 9px rgba(0,0,0,0.2);-webkit-box-shadow:0 5px 9px rgba(0,0,0,0.2);box-shadow:0 5px 9px rgba(0,0,0,0.2)}.sm-dox ul a span.sub-arrow{right:8px;top:50%;margin-top:-5px;border-width:5px;border-color:transparent transparent transparent #555;border-style:dashed dashed dashed solid}.sm-dox ul a,.sm-dox ul a:hover,.sm-dox ul a:focus,.sm-dox ul a:active,.sm-dox ul a.highlighted{color:#555;background-image:none;border:0 !important;color:#555;background-image:none}.sm-dox ul a:hover{background-image:url("tab_a.png");background-repeat:repeat-x;color:white;text-shadow:0 1px 1px black}.sm-dox ul a:hover span.sub-arrow{border-color:transparent transparent transparent white}.sm-dox span.scroll-up,.sm-dox span.scroll-down{position:absolute;display:none;visibility:hidden;overflow:hidden;background:#fff;height:36px}.sm-dox span.scroll-up:hover,.sm-dox span.scroll-down:hover{background:#eee}.sm-dox span.scroll-up:hover span.scroll-up-arrow,.sm-dox span.scroll-up:hover span.scroll-down-arrow{border-color:transparent transparent #d23600 transparent}.sm-dox span.scroll-down:hover span.scroll-down-arrow{border-color:#d23600 transparent transparent transparent}.sm-dox span.scroll-up-arrow,.sm-dox span.scroll-down-arrow{position:absolute;top:0;left:50%;margin-left:-6px;width:0;height:0;overflow:hidden;border-width:6px;border-style:dashed dashed solid dashed;border-color:transparent transparent #555 transparent}.sm-dox span.scroll-down-arrow{top:8px;border-style:solid dashed dashed dashed;border-color:#555 transparent transparent transparent}.sm-dox.sm-rtl a.has-submenu{padding-right:12px;padding-left:24px}.sm-dox.sm-rtl a span.sub-arrow{right:auto;left:12px}.sm-dox.sm-rtl.sm-vertical a.has-submenu{padding:10px 20px}.sm-dox.sm-rtl.sm-vertical a span.sub-arrow{right:auto;left:8px;border-style:dashed solid dashed dashed;border-color:transparent #555 transparent transparent}.sm-dox.sm-rtl>li>ul:before{left:auto;right:30px}.sm-dox.sm-rtl>li>ul:after{left:auto;right:31px}.sm-dox.sm-rtl ul a.has-submenu{padding:10px 20px !important}.sm-dox.sm-rtl ul a span.sub-arrow{right:auto;left:8px;border-style:dashed solid dashed dashed;border-color:transparent #555 transparent transparent}.sm-dox.sm-vertical{padding:10px 0;-moz-border-radius:5px;-webkit-border-radius:5px;border-radius:5px}.sm-dox.sm-vertical a{padding:10px 20px}.sm-dox.sm-vertical a:hover,.sm-dox.sm-vertical a:focus,.sm-dox.sm-vertical a:active,.sm-dox.sm-vertical a.highlighted{background:#fff}.sm-dox.sm-vertical a.disabled{background-image:url("tab_b.png")}.sm-dox.sm-vertical a span.sub-arrow{right:8px;top:50%;margin-top:-5px;border-width:5px;border-style:dashed dashed dashed solid;border-color:transparent transparent transparent #555}.sm-dox.sm-vertical>li>ul:before,.sm-dox.sm-vertical>li>ul:after{display:none}.sm-dox.sm-vertical ul a{padding:10px 20px}.sm-dox.sm-vertical ul a:hover,.sm-dox.sm-vertical ul a:focus,.sm-dox.sm-vertical ul a:active,.sm-dox.sm-vertical ul a.highlighted{background:#eee}.sm-dox.sm-vertical ul a.disabled{background:#fff}} \ No newline at end of file diff --git a/docs/html/usage_patterns.html b/docs/html/usage_patterns.html index d57a74c..990991f 100644 --- a/docs/html/usage_patterns.html +++ b/docs/html/usage_patterns.html @@ -2,8 +2,8 @@ - - + + Vulkan Memory Allocator: Recommended usage patterns @@ -29,21 +29,22 @@ - + +/* @license-end */ + -
    -
    -
    Recommended usage patterns
    +
    +
    Recommended usage patterns
    -

    See also slides from talk: Sawicki, Adam. Advanced Graphics Techniques Tutorial: Memory management in Vulkan and DX12. Game Developers Conference, 2018

    +

    See also slides from talk: Sawicki, Adam. Advanced Graphics Techniques Tutorial: Memory management in Vulkan and DX12. Game Developers Conference, 2018

    Common mistakes

    -

    Use of CPU_TO_GPU instead of CPU_ONLY memory

    -

    VMA_MEMORY_USAGE_CPU_TO_GPU is recommended only for resources that will be mapped and written by the CPU, as well as read directly by the GPU - like some buffers or textures updated every frame (dynamic). If you create a staging copy of a resource to be written by CPU and then used as a source of transfer to another resource placed in the GPU memory, that staging resource should be created with VMA_MEMORY_USAGE_CPU_ONLY. Please read the descriptions of these enums carefully for details.

    -

    Unnecessary use of custom pools

    -

    Custom memory 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, limit maximum amount of memory they can occupy, or make some of them push out the other through the mechanism of Lost allocations. 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.

    +

    Use of CPU_TO_GPU instead of CPU_ONLY memory

    +

    VMA_MEMORY_USAGE_CPU_TO_GPU is recommended only for resources that will be mapped and written by the CPU, as well as read directly by the GPU - like some buffers or textures updated every frame (dynamic). If you create a staging copy of a resource to be written by CPU and then used as a source of transfer to another resource placed in the GPU memory, that staging resource should be created with VMA_MEMORY_USAGE_CPU_ONLY. Please read the descriptions of these enums carefully for details.

    +

    Unnecessary use of custom pools

    +

    Custom memory 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, limit maximum amount of memory they can occupy, or make some of them push out the other through the mechanism of Lost allocations. 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.

    Simple patterns

    Render targets

    -

    When: Any resources that you frequently write and read on GPU, e.g. images used as color attachments (aka "render targets"), depth-stencil attachments, images/buffers used as storage image/buffer (aka "Unordered Access View (UAV)").

    -

    What to do: Create them in video memory that is fastest to access from GPU using VMA_MEMORY_USAGE_GPU_ONLY.

    -

    Consider using VK_KHR_dedicated_allocation extension and/or manually creating them as dedicated allocations using VMA_ALLOCATION_CREATE_DEDICATED_MEMORY_BIT, especially if they are large or if you plan to destroy and recreate them e.g. when display resolution changes. Prefer to create such resources first and all other GPU resources (like textures and vertex buffers) later.

    +

    When: Any resources that you frequently write and read on GPU, e.g. images used as color attachments (aka "render targets"), depth-stencil attachments, images/buffers used as storage image/buffer (aka "Unordered Access View (UAV)").

    +

    What to do: Create them in video memory that is fastest to access from GPU using VMA_MEMORY_USAGE_GPU_ONLY.

    +

    Consider using VK_KHR_dedicated_allocation extension and/or manually creating them as dedicated allocations using VMA_ALLOCATION_CREATE_DEDICATED_MEMORY_BIT, especially if they are large or if you plan to destroy and recreate them e.g. when display resolution changes. Prefer to create such resources first and all other GPU resources (like textures and vertex buffers) later.

    Immutable resources

    -

    When: Any resources that you fill on CPU only once (aka "immutable") or infrequently and then read frequently on GPU, e.g. textures, vertex and index buffers, constant buffers that don't change often.

    -

    What to do: Create them in video memory that is fastest to access from GPU using VMA_MEMORY_USAGE_GPU_ONLY.

    -

    To initialize content of such resource, create a CPU-side (aka "staging") copy of it in system memory - VMA_MEMORY_USAGE_CPU_ONLY, map it, fill it, and submit a transfer from it to the GPU resource. You can keep the staging copy if you need it for another upload transfer in the future. If you don't, you can destroy it or reuse this buffer for uploading different resource after the transfer finishes.

    -

    Prefer to create just buffers in system memory rather than images, even for uploading textures. Use vkCmdCopyBufferToImage(). Dont use images with VK_IMAGE_TILING_LINEAR.

    +

    When: Any resources that you fill on CPU only once (aka "immutable") or infrequently and then read frequently on GPU, e.g. textures, vertex and index buffers, constant buffers that don't change often.

    +

    What to do: Create them in video memory that is fastest to access from GPU using VMA_MEMORY_USAGE_GPU_ONLY.

    +

    To initialize content of such resource, create a CPU-side (aka "staging") copy of it in system memory - VMA_MEMORY_USAGE_CPU_ONLY, map it, fill it, and submit a transfer from it to the GPU resource. You can keep the staging copy if you need it for another upload transfer in the future. If you don't, you can destroy it or reuse this buffer for uploading different resource after the transfer finishes.

    +

    Prefer to create just buffers in system memory rather than images, even for uploading textures. Use vkCmdCopyBufferToImage(). Dont use images with VK_IMAGE_TILING_LINEAR.

    Dynamic resources

    -

    When: Any resources that change frequently (aka "dynamic"), e.g. every frame or every draw call, written on CPU, read on GPU.

    -

    What to do: Create them using VMA_MEMORY_USAGE_CPU_TO_GPU. You can map it and write to it directly on CPU, as well as read from it on GPU.

    -

    This is a more complex situation. Different solutions are possible, and the best one depends on specific GPU type, but you can use this simple approach for the start. Prefer to write to such resource sequentially (e.g. using memcpy). Don't perform random access or any reads from it on CPU, as it may be very slow. Also note that textures written directly from the host through a mapped pointer need to be in LINEAR not OPTIMAL layout.

    +

    When: Any resources that change frequently (aka "dynamic"), e.g. every frame or every draw call, written on CPU, read on GPU.

    +

    What to do: Create them using VMA_MEMORY_USAGE_CPU_TO_GPU. You can map it and write to it directly on CPU, as well as read from it on GPU.

    +

    This is a more complex situation. Different solutions are possible, and the best one depends on specific GPU type, but you can use this simple approach for the start. Prefer to write to such resource sequentially (e.g. using memcpy). Don't perform random access or any reads from it on CPU, as it may be very slow. Also note that textures written directly from the host through a mapped pointer need to be in LINEAR not OPTIMAL layout.

    Readback

    -

    When: Resources that contain data written by GPU that you want to read back on CPU, e.g. results of some computations.

    -

    What to do: Create them using VMA_MEMORY_USAGE_GPU_TO_CPU. You can write to them directly on GPU, as well as map and read them on CPU.

    +

    When: Resources that contain data written by GPU that you want to read back on CPU, e.g. results of some computations.

    +

    What to do: Create them using VMA_MEMORY_USAGE_GPU_TO_CPU. You can write to them directly on GPU, as well as map and read them on CPU.

    Advanced patterns

    Detecting integrated graphics

    -

    You can support integrated graphics (like Intel HD Graphics, AMD APU) better by detecting it in Vulkan. To do it, call vkGetPhysicalDeviceProperties(), inspect VkPhysicalDeviceProperties::deviceType and look for VK_PHYSICAL_DEVICE_TYPE_INTEGRATED_GPU. When you find it, you can assume that memory is unified and all memory types are comparably fast to access from GPU, regardless of VK_MEMORY_PROPERTY_DEVICE_LOCAL_BIT.

    -

    You can then sum up sizes of all available memory heaps and treat them as useful for your GPU resources, instead of only DEVICE_LOCAL ones. You can also prefer to create your resources in memory types that are HOST_VISIBLE to map them directly instead of submitting explicit transfer (see below).

    +

    You can support integrated graphics (like Intel HD Graphics, AMD APU) better by detecting it in Vulkan. To do it, call vkGetPhysicalDeviceProperties(), inspect VkPhysicalDeviceProperties::deviceType and look for VK_PHYSICAL_DEVICE_TYPE_INTEGRATED_GPU. When you find it, you can assume that memory is unified and all memory types are comparably fast to access from GPU, regardless of VK_MEMORY_PROPERTY_DEVICE_LOCAL_BIT.

    +

    You can then sum up sizes of all available memory heaps and treat them as useful for your GPU resources, instead of only DEVICE_LOCAL ones. You can also prefer to create your resources in memory types that are HOST_VISIBLE to map them directly instead of submitting explicit transfer (see below).

    Direct access versus transfer

    -

    For resources that you frequently write on CPU and read on GPU, many solutions are possible:

    +

    For resources that you frequently write on CPU and read on GPU, many solutions are possible:

    1. Create one copy in video memory using VMA_MEMORY_USAGE_GPU_ONLY, second copy in system memory using VMA_MEMORY_USAGE_CPU_ONLY and submit explicit transfer each time.
    2. Create just a single copy using VMA_MEMORY_USAGE_CPU_TO_GPU, map it and fill it on CPU, read it directly on GPU.
    3. Create just a single copy using VMA_MEMORY_USAGE_CPU_ONLY, map it and fill it on CPU, read it directly on GPU.
    -

    Which solution is the most efficient depends on your resource and especially on the GPU. It is best to measure it and then make the decision. Some general recommendations:

    +

    Which solution is the most efficient depends on your resource and especially on the GPU. It is best to measure it and then make the decision. Some general recommendations:

    • On integrated graphics use (2) or (3) to avoid unnecessary time and memory overhead related to using a second copy and making transfer.
    • For small resources (e.g. constant buffers) use (2). Discrete AMD cards have special 256 MiB pool of video memory that is directly mappable. Even if the resource ends up in system memory, its data may be cached on GPU after first fetch over PCIe bus.
    • For larger resources (e.g. textures), decide between (1) and (2). You may want to differentiate NVIDIA and AMD, e.g. by looking for memory type that is both DEVICE_LOCAL and HOST_VISIBLE. When you find it, use (2), otherwise use (1).
    -

    Similarly, for resources that you frequently write on GPU and read on CPU, multiple solutions are possible:

    +

    Similarly, for resources that you frequently write on GPU and read on CPU, multiple solutions are possible:

    1. Create one copy in video memory using VMA_MEMORY_USAGE_GPU_ONLY, second copy in system memory using VMA_MEMORY_USAGE_GPU_TO_CPU and submit explicit tranfer each time.
    2. Create just single copy using VMA_MEMORY_USAGE_GPU_TO_CPU, write to it directly on GPU, map it and read it on CPU.
    -

    You should take some measurements to decide which option is faster in case of your specific resource.

    -

    Note that textures accessed directly from the host through a mapped pointer need to be in LINEAR layout, which may slow down their usage on the device. Textures accessed only by the device and transfer operations can use OPTIMAL layout.

    -

    If you don't want to specialize your code for specific types of GPUs, you can still make an simple optimization for cases when your resource ends up in mappable memory to use it directly in this case instead of creating CPU-side staging copy. For details see Finding out if memory is mappable.

    +

    You should take some measurements to decide which option is faster in case of your specific resource.

    +

    Note that textures accessed directly from the host through a mapped pointer need to be in LINEAR layout, which may slow down their usage on the device. Textures accessed only by the device and transfer operations can use OPTIMAL layout.

    +

    If you don't want to specialize your code for specific types of GPUs, you can still make an simple optimization for cases when your resource ends up in mappable memory to use it directly in this case instead of creating CPU-side staging copy. For details see Finding out if memory is mappable.

    -Generated by doxygen 1.9.1 +Generated by doxygen 1.9.2
    diff --git a/docs/html/vk__mem__alloc_8h.html b/docs/html/vk__mem__alloc_8h.html index 8f5575e..8d7fdb8 100644 --- a/docs/html/vk__mem__alloc_8h.html +++ b/docs/html/vk__mem__alloc_8h.html @@ -2,10 +2,10 @@ - - + + -Vulkan Memory Allocator: include/vk_mem_alloc.h File Reference +Vulkan Memory Allocator: D:/PROJECTS/Vulkan Memory Allocator/REPO/include/vk_mem_alloc.h File Reference @@ -29,21 +29,22 @@
    - + +/* @license-end */ +
    Typedefs | Enumerations | Functions
    -
    -
    vk_mem_alloc.h File Reference
    +
    vk_mem_alloc.h File Reference
    #include <vulkan/vulkan.h>
    - @@ -129,7 +129,7 @@ Classes

    +

    Classes

    struct  VmaDeviceMemoryCallbacks
     Set of callbacks that the library will call for vkAllocateMemory and vkFreeMemory. More...
     Statistics returned by function vmaDefragment(). More...
     
    - @@ -148,7 +148,7 @@ Macros

    +

    Macros

    #define VMA_RECORDING_ENABLED   0
     
    #define VMA_STATS_STRING_ENABLED   1
     
    - @@ -233,7 +233,7 @@ Typedefs

    +

    Typedefs

    typedef void(VKAPI_PTR * PFN_vmaAllocateDeviceMemoryFunction) (VmaAllocator allocator, uint32_t memoryType, VkDeviceMemory memory, VkDeviceSize size, void *pUserData)
     Callback function called after successful vkAllocateMemory. More...
     Statistics returned by function vmaDefragment(). More...
     
    -

    +

    Enumerations

    enum  VmaAllocatorCreateFlagBits {
      VMA_ALLOCATOR_CREATE_EXTERNALLY_SYNCHRONIZED_BIT = 0x00000001 @@ -310,7 +310,7 @@ Enumerations
     Flags to be used in vmaDefragmentationBegin(). None at the moment. Reserved for future use. More...
     
    - @@ -463,7 +463,7 @@ Functions

    +

    Functions

    VkResult vmaCreateAllocator (const VmaAllocatorCreateInfo *pCreateInfo, VmaAllocator *pAllocator)
     Creates Allocator object. More...
     

    Macro Definition Documentation

    - +

    ◆ VMA_BIND_MEMORY2

    @@ -477,7 +477,7 @@ Functions
    - +

    ◆ VMA_BUFFER_DEVICE_ADDRESS

    @@ -491,7 +491,7 @@ Functions
    - +

    ◆ VMA_DEDICATED_ALLOCATION

    @@ -505,7 +505,7 @@ Functions
    - +

    ◆ VMA_MEMORY_BUDGET

    @@ -519,7 +519,7 @@ Functions
    - +

    ◆ VMA_MEMORY_PRIORITY

    @@ -533,7 +533,7 @@ Functions
    - +

    ◆ VMA_RECORDING_ENABLED

    @@ -547,7 +547,7 @@ Functions
    - +

    ◆ VMA_STATS_STRING_ENABLED

    @@ -561,7 +561,7 @@ Functions
    - +

    ◆ VMA_VULKAN_VERSION

    @@ -576,7 +576,7 @@ Functions

    Typedef Documentation

    - +

    ◆ PFN_vmaAllocateDeviceMemoryFunction

    @@ -592,7 +592,7 @@ Functions
    - +

    ◆ PFN_vmaFreeDeviceMemoryFunction

    @@ -608,7 +608,7 @@ Functions
    - +

    ◆ VmaAllocationCreateFlagBits

    @@ -624,7 +624,7 @@ Functions
    - +

    ◆ VmaAllocationCreateFlags

    @@ -638,7 +638,7 @@ Functions
    - +

    ◆ VmaAllocationCreateInfo

    @@ -652,7 +652,7 @@ Functions
    - +

    ◆ VmaAllocationInfo

    @@ -668,7 +668,7 @@ Functions
    - +

    ◆ VmaAllocatorCreateFlagBits

    @@ -684,7 +684,7 @@ Functions
    - +

    ◆ VmaAllocatorCreateFlags

    @@ -698,7 +698,7 @@ Functions
    - +

    ◆ VmaAllocatorCreateInfo

    @@ -714,7 +714,7 @@ Functions
    - +

    ◆ VmaAllocatorInfo

    @@ -730,7 +730,7 @@ Functions
    - +

    ◆ VmaBudget

    @@ -746,7 +746,7 @@ Functions
    - +

    ◆ VmaDefragmentationFlagBits

    @@ -762,7 +762,7 @@ Functions
    - +

    ◆ VmaDefragmentationFlags

    @@ -776,7 +776,7 @@ Functions
    - +

    ◆ VmaDefragmentationInfo

    @@ -793,7 +793,7 @@ Functions
    - +

    ◆ VmaDefragmentationInfo2

    @@ -806,11 +806,11 @@ Functions

    Parameters for defragmentation.

    -

    To be used with function vmaDefragmentationBegin().

    +

    To be used with function vmaDefragmentationBegin().

    - +

    ◆ VmaDefragmentationPassInfo

    @@ -823,11 +823,11 @@ Functions

    Parameters for incremental defragmentation steps.

    -

    To be used with function vmaBeginDefragmentationPass().

    +

    To be used with function vmaBeginDefragmentationPass().

    - +

    ◆ VmaDefragmentationPassMoveInfo

    @@ -841,7 +841,7 @@ Functions
    - +

    ◆ VmaDefragmentationStats

    @@ -857,7 +857,7 @@ Functions
    - +

    ◆ VmaDeviceMemoryCallbacks

    @@ -870,12 +870,12 @@ Functions

    Set of callbacks that the library will call for vkAllocateMemory and vkFreeMemory.

    -

    Provided for informative purpose, e.g. to gather statistics about number of allocations or total amount of memory allocated in Vulkan.

    -

    Used in VmaAllocatorCreateInfo::pDeviceMemoryCallbacks.

    +

    Provided for informative purpose, e.g. to gather statistics about number of allocations or total amount of memory allocated in Vulkan.

    +

    Used in VmaAllocatorCreateInfo::pDeviceMemoryCallbacks.

    - +

    ◆ VmaMemoryUsage

    @@ -889,7 +889,7 @@ Functions
    - +

    ◆ VmaPoolCreateFlagBits

    @@ -905,7 +905,7 @@ Functions
    - +

    ◆ VmaPoolCreateFlags

    @@ -919,7 +919,7 @@ Functions
    - +

    ◆ VmaPoolCreateInfo

    @@ -935,7 +935,7 @@ Functions
    - +

    ◆ VmaPoolStats

    @@ -951,7 +951,7 @@ Functions
    - +

    ◆ VmaRecordFlagBits

    @@ -967,7 +967,7 @@ Functions
    - +

    ◆ VmaRecordFlags

    @@ -981,7 +981,7 @@ Functions
    - +

    ◆ VmaRecordSettings

    @@ -997,7 +997,7 @@ Functions
    - +

    ◆ VmaStatInfo

    @@ -1013,7 +1013,7 @@ Functions
    - +

    ◆ VmaStats

    @@ -1029,7 +1029,7 @@ Functions
    - +

    ◆ VmaVulkanFunctions

    @@ -1042,12 +1042,12 @@ Functions

    Pointers to some Vulkan functions - a subset used by the library.

    -

    Used in VmaAllocatorCreateInfo::pVulkanFunctions.

    +

    Used in VmaAllocatorCreateInfo::pVulkanFunctions.

    Enumeration Type Documentation

    - +

    ◆ VmaAllocationCreateFlagBits

    @@ -1061,58 +1061,58 @@ Functions

    Flags to be passed as VmaAllocationCreateInfo::flags.

    - - - - - - - - - - - - - - - - - +
    Enumerator
    VMA_ALLOCATION_CREATE_DEDICATED_MEMORY_BIT 

    Set this flag if the allocation should have its own memory block.

    -

    Use it for special, big resources, like fullscreen images used as attachments.

    -

    You should not use this flag if VmaAllocationCreateInfo::pool is not null.

    +
    Enumerator
    VMA_ALLOCATION_CREATE_DEDICATED_MEMORY_BIT 

    Set this flag if the allocation should have its own memory block.

    +

    Use it for special, big resources, like fullscreen images used as attachments.

    +

    You should not use this flag if VmaAllocationCreateInfo::pool is not null.

    VMA_ALLOCATION_CREATE_NEVER_ALLOCATE_BIT 

    Set this flag to only try to allocate from existing VkDeviceMemory blocks and never create new such block.

    -

    If new allocation cannot be placed in any of the existing blocks, allocation fails with VK_ERROR_OUT_OF_DEVICE_MEMORY error.

    -

    You should not use VMA_ALLOCATION_CREATE_DEDICATED_MEMORY_BIT and VMA_ALLOCATION_CREATE_NEVER_ALLOCATE_BIT at the same time. It makes no sense.

    -

    If VmaAllocationCreateInfo::pool is not null, this flag is implied and ignored.

    +
    VMA_ALLOCATION_CREATE_NEVER_ALLOCATE_BIT 

    Set this flag to only try to allocate from existing VkDeviceMemory blocks and never create new such block.

    +

    If new allocation cannot be placed in any of the existing blocks, allocation fails with VK_ERROR_OUT_OF_DEVICE_MEMORY error.

    +

    You should not use VMA_ALLOCATION_CREATE_DEDICATED_MEMORY_BIT and VMA_ALLOCATION_CREATE_NEVER_ALLOCATE_BIT at the same time. It makes no sense.

    +

    If VmaAllocationCreateInfo::pool is not null, this flag is implied and ignored.

    VMA_ALLOCATION_CREATE_MAPPED_BIT 

    Set this flag to use a memory that will be persistently mapped and retrieve pointer to it.

    -

    Pointer to mapped memory will be returned through VmaAllocationInfo::pMappedData.

    -

    It is valid to use this flag for allocation made from memory type that is not HOST_VISIBLE. This flag is then ignored and memory is not mapped. This is useful if you need an allocation that is efficient to use on GPU (DEVICE_LOCAL) and still want to map it directly if possible on platforms that support it (e.g. Intel GPU).

    -

    You should not use this flag together with VMA_ALLOCATION_CREATE_CAN_BECOME_LOST_BIT.

    +
    VMA_ALLOCATION_CREATE_MAPPED_BIT 

    Set this flag to use a memory that will be persistently mapped and retrieve pointer to it.

    +

    Pointer to mapped memory will be returned through VmaAllocationInfo::pMappedData.

    +

    It is valid to use this flag for allocation made from memory type that is not HOST_VISIBLE. This flag is then ignored and memory is not mapped. This is useful if you need an allocation that is efficient to use on GPU (DEVICE_LOCAL) and still want to map it directly if possible on platforms that support it (e.g. Intel GPU).

    +

    You should not use this flag together with VMA_ALLOCATION_CREATE_CAN_BECOME_LOST_BIT.

    VMA_ALLOCATION_CREATE_CAN_BECOME_LOST_BIT 

    Allocation created with this flag can become lost as a result of another allocation with VMA_ALLOCATION_CREATE_CAN_MAKE_OTHER_LOST_BIT flag, so you must check it before use.

    -

    To check if allocation is not lost, call vmaGetAllocationInfo() and check if VmaAllocationInfo::deviceMemory is not VK_NULL_HANDLE.

    -

    For details about supporting lost allocations, see Lost Allocations chapter of User Guide on Main Page.

    -

    You should not use this flag together with VMA_ALLOCATION_CREATE_MAPPED_BIT.

    +
    VMA_ALLOCATION_CREATE_CAN_BECOME_LOST_BIT 

    Allocation created with this flag can become lost as a result of another allocation with VMA_ALLOCATION_CREATE_CAN_MAKE_OTHER_LOST_BIT flag, so you must check it before use.

    +

    To check if allocation is not lost, call vmaGetAllocationInfo() and check if VmaAllocationInfo::deviceMemory is not VK_NULL_HANDLE.

    +

    For details about supporting lost allocations, see Lost Allocations chapter of User Guide on Main Page.

    +

    You should not use this flag together with VMA_ALLOCATION_CREATE_MAPPED_BIT.

    VMA_ALLOCATION_CREATE_CAN_MAKE_OTHER_LOST_BIT 

    While creating allocation using this flag, other allocations that were created with flag VMA_ALLOCATION_CREATE_CAN_BECOME_LOST_BIT can become lost.

    -

    For details about supporting lost allocations, see Lost Allocations chapter of User Guide on Main Page.

    +
    VMA_ALLOCATION_CREATE_CAN_MAKE_OTHER_LOST_BIT 

    While creating allocation using this flag, other allocations that were created with flag VMA_ALLOCATION_CREATE_CAN_BECOME_LOST_BIT can become lost.

    +

    For details about supporting lost allocations, see Lost Allocations chapter of User Guide on Main Page.

    VMA_ALLOCATION_CREATE_USER_DATA_COPY_STRING_BIT 

    Set this flag to treat VmaAllocationCreateInfo::pUserData as pointer to a null-terminated string. Instead of copying pointer value, a local copy of the string is made and stored in allocation's pUserData. The string is automatically freed together with the allocation. It is also used in vmaBuildStatsString().

    +
    VMA_ALLOCATION_CREATE_USER_DATA_COPY_STRING_BIT 

    Set this flag to treat VmaAllocationCreateInfo::pUserData as pointer to a null-terminated string. Instead of copying pointer value, a local copy of the string is made and stored in allocation's pUserData. The string is automatically freed together with the allocation. It is also used in vmaBuildStatsString().

    VMA_ALLOCATION_CREATE_UPPER_ADDRESS_BIT 

    Allocation will be created from upper stack in a double stack pool.

    -

    This flag is only allowed for custom pools created with VMA_POOL_CREATE_LINEAR_ALGORITHM_BIT flag.

    +
    VMA_ALLOCATION_CREATE_UPPER_ADDRESS_BIT 

    Allocation will be created from upper stack in a double stack pool.

    +

    This flag is only allowed for custom pools created with VMA_POOL_CREATE_LINEAR_ALGORITHM_BIT flag.

    VMA_ALLOCATION_CREATE_DONT_BIND_BIT 

    Create both buffer/image and allocation, but don't bind them together. It is useful when you want to bind yourself to do some more advanced binding, e.g. using some extensions. The flag is meaningful only with functions that bind by default: vmaCreateBuffer(), vmaCreateImage(). Otherwise it is ignored.

    +
    VMA_ALLOCATION_CREATE_DONT_BIND_BIT 

    Create both buffer/image and allocation, but don't bind them together. It is useful when you want to bind yourself to do some more advanced binding, e.g. using some extensions. The flag is meaningful only with functions that bind by default: vmaCreateBuffer(), vmaCreateImage(). Otherwise it is ignored.

    VMA_ALLOCATION_CREATE_WITHIN_BUDGET_BIT 

    Create allocation only if additional device memory required for it, if any, won't exceed memory budget. Otherwise return VK_ERROR_OUT_OF_DEVICE_MEMORY.

    +
    VMA_ALLOCATION_CREATE_WITHIN_BUDGET_BIT 

    Create allocation only if additional device memory required for it, if any, won't exceed memory budget. Otherwise return VK_ERROR_OUT_OF_DEVICE_MEMORY.

    VMA_ALLOCATION_CREATE_STRATEGY_BEST_FIT_BIT 

    Allocation strategy that chooses smallest possible free range for the allocation.

    +
    VMA_ALLOCATION_CREATE_STRATEGY_BEST_FIT_BIT 

    Allocation strategy that chooses smallest possible free range for the allocation.

    VMA_ALLOCATION_CREATE_STRATEGY_WORST_FIT_BIT 

    Allocation strategy that chooses biggest possible free range for the allocation.

    +
    VMA_ALLOCATION_CREATE_STRATEGY_WORST_FIT_BIT 

    Allocation strategy that chooses biggest possible free range for the allocation.

    VMA_ALLOCATION_CREATE_STRATEGY_FIRST_FIT_BIT 

    Allocation strategy that chooses first suitable free range for the allocation.

    -

    "First" doesn't necessarily means the one with smallest offset in memory, but rather the one that is easiest and fastest to find.

    +
    VMA_ALLOCATION_CREATE_STRATEGY_FIRST_FIT_BIT 

    Allocation strategy that chooses first suitable free range for the allocation.

    +

    "First" doesn't necessarily means the one with smallest offset in memory, but rather the one that is easiest and fastest to find.

    VMA_ALLOCATION_CREATE_STRATEGY_MIN_MEMORY_BIT 

    Allocation strategy that tries to minimize memory usage.

    +
    VMA_ALLOCATION_CREATE_STRATEGY_MIN_MEMORY_BIT 

    Allocation strategy that tries to minimize memory usage.

    VMA_ALLOCATION_CREATE_STRATEGY_MIN_TIME_BIT 

    Allocation strategy that tries to minimize allocation time.

    +
    VMA_ALLOCATION_CREATE_STRATEGY_MIN_TIME_BIT 

    Allocation strategy that tries to minimize allocation time.

    VMA_ALLOCATION_CREATE_STRATEGY_MIN_FRAGMENTATION_BIT 

    Allocation strategy that tries to minimize memory fragmentation.

    +
    VMA_ALLOCATION_CREATE_STRATEGY_MIN_FRAGMENTATION_BIT 

    Allocation strategy that tries to minimize memory fragmentation.

    VMA_ALLOCATION_CREATE_STRATEGY_MASK 

    A bit mask to extract only STRATEGY bits from entire set of flags.

    +
    VMA_ALLOCATION_CREATE_STRATEGY_MASK 

    A bit mask to extract only STRATEGY bits from entire set of flags.

    VMA_ALLOCATION_CREATE_FLAG_BITS_MAX_ENUM 
    VMA_ALLOCATION_CREATE_FLAG_BITS_MAX_ENUM 
    - +

    ◆ VmaAllocatorCreateFlagBits

    @@ -1126,61 +1126,61 @@ Functions

    Flags for created VmaAllocator.

    - - - - - - - - +
    Enumerator
    VMA_ALLOCATOR_CREATE_EXTERNALLY_SYNCHRONIZED_BIT 

    Allocator and all objects created from it will not be synchronized internally, so you must guarantee they are used from only one thread at a time or synchronized externally by you.

    -

    Using this flag may increase performance because internal mutexes are not used.

    +
    Enumerator
    VMA_ALLOCATOR_CREATE_EXTERNALLY_SYNCHRONIZED_BIT 

    Allocator and all objects created from it will not be synchronized internally, so you must guarantee they are used from only one thread at a time or synchronized externally by you.

    +

    Using this flag may increase performance because internal mutexes are not used.

    VMA_ALLOCATOR_CREATE_KHR_DEDICATED_ALLOCATION_BIT 

    Enables usage of VK_KHR_dedicated_allocation extension.

    -

    The flag works only if VmaAllocatorCreateInfo::vulkanApiVersion == VK_API_VERSION_1_0. When it is VK_API_VERSION_1_1, the flag is ignored because the extension has been promoted to Vulkan 1.1.

    -

    Using this extension will automatically allocate dedicated blocks of memory for some buffers and images instead of suballocating place for them out of bigger memory blocks (as if you explicitly used VMA_ALLOCATION_CREATE_DEDICATED_MEMORY_BIT flag) when it is recommended by the driver. It may improve performance on some GPUs.

    -

    You may set this flag only if you found out that following device extensions are supported, you enabled them while creating Vulkan device passed as VmaAllocatorCreateInfo::device, and you want them to be used internally by this library:

    +
    VMA_ALLOCATOR_CREATE_KHR_DEDICATED_ALLOCATION_BIT 

    Enables usage of VK_KHR_dedicated_allocation extension.

    +

    The flag works only if VmaAllocatorCreateInfo::vulkanApiVersion == VK_API_VERSION_1_0. When it is VK_API_VERSION_1_1, the flag is ignored because the extension has been promoted to Vulkan 1.1.

    +

    Using this extension will automatically allocate dedicated blocks of memory for some buffers and images instead of suballocating place for them out of bigger memory blocks (as if you explicitly used VMA_ALLOCATION_CREATE_DEDICATED_MEMORY_BIT flag) when it is recommended by the driver. It may improve performance on some GPUs.

    +

    You may set this flag only if you found out that following device extensions are supported, you enabled them while creating Vulkan device passed as VmaAllocatorCreateInfo::device, and you want them to be used internally by this library:

    • VK_KHR_get_memory_requirements2 (device extension)
    • VK_KHR_dedicated_allocation (device extension)
    -

    When this flag is set, you can experience following warnings reported by Vulkan validation layer. You can ignore them.

    +

    When this flag is set, you can experience following warnings reported by Vulkan validation layer. You can ignore them.

    -

    vkBindBufferMemory(): Binding memory to buffer 0x2d but vkGetBufferMemoryRequirements() has not been called on that buffer.

    +

    vkBindBufferMemory(): Binding memory to buffer 0x2d but vkGetBufferMemoryRequirements() has not been called on that buffer.

    VMA_ALLOCATOR_CREATE_KHR_BIND_MEMORY2_BIT 

    Enables usage of VK_KHR_bind_memory2 extension.

    -

    The flag works only if VmaAllocatorCreateInfo::vulkanApiVersion == VK_API_VERSION_1_0. When it is VK_API_VERSION_1_1, the flag is ignored because the extension has been promoted to Vulkan 1.1.

    -

    You may set this flag only if you found out that this device extension is supported, you enabled it while creating Vulkan device passed as VmaAllocatorCreateInfo::device, and you want it to be used internally by this library.

    -

    The extension provides functions vkBindBufferMemory2KHR and vkBindImageMemory2KHR, which allow to pass a chain of pNext structures while binding. This flag is required if you use pNext parameter in vmaBindBufferMemory2() or vmaBindImageMemory2().

    +
    VMA_ALLOCATOR_CREATE_KHR_BIND_MEMORY2_BIT 

    Enables usage of VK_KHR_bind_memory2 extension.

    +

    The flag works only if VmaAllocatorCreateInfo::vulkanApiVersion == VK_API_VERSION_1_0. When it is VK_API_VERSION_1_1, the flag is ignored because the extension has been promoted to Vulkan 1.1.

    +

    You may set this flag only if you found out that this device extension is supported, you enabled it while creating Vulkan device passed as VmaAllocatorCreateInfo::device, and you want it to be used internally by this library.

    +

    The extension provides functions vkBindBufferMemory2KHR and vkBindImageMemory2KHR, which allow to pass a chain of pNext structures while binding. This flag is required if you use pNext parameter in vmaBindBufferMemory2() or vmaBindImageMemory2().

    VMA_ALLOCATOR_CREATE_EXT_MEMORY_BUDGET_BIT 

    Enables usage of VK_EXT_memory_budget extension.

    -

    You may set this flag only if you found out that this device extension is supported, you enabled it while creating Vulkan device passed as VmaAllocatorCreateInfo::device, and you want it to be used internally by this library, along with another instance extension VK_KHR_get_physical_device_properties2, which is required by it (or Vulkan 1.1, where this extension is promoted).

    -

    The extension provides query for current memory usage and budget, which will probably be more accurate than an estimation used by the library otherwise.

    +
    VMA_ALLOCATOR_CREATE_EXT_MEMORY_BUDGET_BIT 

    Enables usage of VK_EXT_memory_budget extension.

    +

    You may set this flag only if you found out that this device extension is supported, you enabled it while creating Vulkan device passed as VmaAllocatorCreateInfo::device, and you want it to be used internally by this library, along with another instance extension VK_KHR_get_physical_device_properties2, which is required by it (or Vulkan 1.1, where this extension is promoted).

    +

    The extension provides query for current memory usage and budget, which will probably be more accurate than an estimation used by the library otherwise.

    VMA_ALLOCATOR_CREATE_AMD_DEVICE_COHERENT_MEMORY_BIT 

    Enables usage of VK_AMD_device_coherent_memory extension.

    -

    You may set this flag only if you:

    +
    VMA_ALLOCATOR_CREATE_AMD_DEVICE_COHERENT_MEMORY_BIT 

    Enables usage of VK_AMD_device_coherent_memory extension.

    +

    You may set this flag only if you:

    • found out that this device extension is supported and enabled it while creating Vulkan device passed as VmaAllocatorCreateInfo::device,
    • checked that VkPhysicalDeviceCoherentMemoryFeaturesAMD::deviceCoherentMemory is true and set it while creating the Vulkan device,
    • want it to be used internally by this library.
    -

    The extension and accompanying device feature provide access to memory types with VK_MEMORY_PROPERTY_DEVICE_COHERENT_BIT_AMD and VK_MEMORY_PROPERTY_DEVICE_UNCACHED_BIT_AMD flags. They are useful mostly for writing breadcrumb markers - a common method for debugging GPU crash/hang/TDR.

    -

    When the extension is not enabled, such memory types are still enumerated, but their usage is illegal. To protect from this error, if you don't create the allocator with this flag, it will refuse to allocate any memory or create a custom pool in such memory type, returning VK_ERROR_FEATURE_NOT_PRESENT.

    +

    The extension and accompanying device feature provide access to memory types with VK_MEMORY_PROPERTY_DEVICE_COHERENT_BIT_AMD and VK_MEMORY_PROPERTY_DEVICE_UNCACHED_BIT_AMD flags. They are useful mostly for writing breadcrumb markers - a common method for debugging GPU crash/hang/TDR.

    +

    When the extension is not enabled, such memory types are still enumerated, but their usage is illegal. To protect from this error, if you don't create the allocator with this flag, it will refuse to allocate any memory or create a custom pool in such memory type, returning VK_ERROR_FEATURE_NOT_PRESENT.

    VMA_ALLOCATOR_CREATE_BUFFER_DEVICE_ADDRESS_BIT 

    Enables usage of "buffer device address" feature, which allows you to use function vkGetBufferDeviceAddress* to get raw GPU pointer to a buffer and pass it for usage inside a shader.

    -

    You may set this flag only if you:

    +
    VMA_ALLOCATOR_CREATE_BUFFER_DEVICE_ADDRESS_BIT 

    Enables usage of "buffer device address" feature, which allows you to use function vkGetBufferDeviceAddress* to get raw GPU pointer to a buffer and pass it for usage inside a shader.

    +

    You may set this flag only if you:

    1. (For Vulkan version < 1.2) Found as available and enabled device extension VK_KHR_buffer_device_address. This extension is promoted to core Vulkan 1.2.
    2. Found as available and enabled device feature VkPhysicalDeviceBufferDeviceAddressFeatures::bufferDeviceAddress.
    -

    When this flag is set, you can create buffers with VK_BUFFER_USAGE_SHADER_DEVICE_ADDRESS_BIT using VMA. The library automatically adds VK_MEMORY_ALLOCATE_DEVICE_ADDRESS_BIT to allocated memory blocks wherever it might be needed.

    -

    For more information, see documentation chapter Enabling buffer device address.

    +

    When this flag is set, you can create buffers with VK_BUFFER_USAGE_SHADER_DEVICE_ADDRESS_BIT using VMA. The library automatically adds VK_MEMORY_ALLOCATE_DEVICE_ADDRESS_BIT to allocated memory blocks wherever it might be needed.

    +

    For more information, see documentation chapter Enabling buffer device address.

    VMA_ALLOCATOR_CREATE_EXT_MEMORY_PRIORITY_BIT 

    Enables usage of VK_EXT_memory_priority extension in the library.

    -

    You may set this flag only if you found available and enabled this device extension, along with VkPhysicalDeviceMemoryPriorityFeaturesEXT::memoryPriority == VK_TRUE, while creating Vulkan device passed as VmaAllocatorCreateInfo::device.

    -

    When this flag is used, VmaAllocationCreateInfo::priority and VmaPoolCreateInfo::priority are used to set priorities of allocated Vulkan memory. Without it, these variables are ignored.

    -

    A priority must be a floating-point value between 0 and 1, indicating the priority of the allocation relative to other memory allocations. Larger values are higher priority. The granularity of the priorities is implementation-dependent. It is automatically passed to every call to vkAllocateMemory done by the library using structure VkMemoryPriorityAllocateInfoEXT. The value to be used for default priority is 0.5. For more details, see the documentation of the VK_EXT_memory_priority extension.

    +
    VMA_ALLOCATOR_CREATE_EXT_MEMORY_PRIORITY_BIT 

    Enables usage of VK_EXT_memory_priority extension in the library.

    +

    You may set this flag only if you found available and enabled this device extension, along with VkPhysicalDeviceMemoryPriorityFeaturesEXT::memoryPriority == VK_TRUE, while creating Vulkan device passed as VmaAllocatorCreateInfo::device.

    +

    When this flag is used, VmaAllocationCreateInfo::priority and VmaPoolCreateInfo::priority are used to set priorities of allocated Vulkan memory. Without it, these variables are ignored.

    +

    A priority must be a floating-point value between 0 and 1, indicating the priority of the allocation relative to other memory allocations. Larger values are higher priority. The granularity of the priorities is implementation-dependent. It is automatically passed to every call to vkAllocateMemory done by the library using structure VkMemoryPriorityAllocateInfoEXT. The value to be used for default priority is 0.5. For more details, see the documentation of the VK_EXT_memory_priority extension.

    VMA_ALLOCATOR_CREATE_FLAG_BITS_MAX_ENUM 
    VMA_ALLOCATOR_CREATE_FLAG_BITS_MAX_ENUM 
    - +

    ◆ VmaDefragmentationFlagBits

    @@ -1194,13 +1194,13 @@ Functions

    Flags to be used in vmaDefragmentationBegin(). None at the moment. Reserved for future use.

    - - + +
    Enumerator
    VMA_DEFRAGMENTATION_FLAG_INCREMENTAL 
    VMA_DEFRAGMENTATION_FLAG_BITS_MAX_ENUM 
    Enumerator
    VMA_DEFRAGMENTATION_FLAG_INCREMENTAL 
    VMA_DEFRAGMENTATION_FLAG_BITS_MAX_ENUM 
    - +

    ◆ VmaMemoryUsage

    @@ -1212,42 +1212,42 @@ Functions
    - - - - - - - - +
    Enumerator
    VMA_MEMORY_USAGE_UNKNOWN 

    No intended memory usage specified. Use other members of VmaAllocationCreateInfo to specify your requirements.

    +
    Enumerator
    VMA_MEMORY_USAGE_UNKNOWN 

    No intended memory usage specified. Use other members of VmaAllocationCreateInfo to specify your requirements.

    VMA_MEMORY_USAGE_GPU_ONLY 

    Memory will be used on device only, so fast access from the device is preferred. It usually means device-local GPU (video) memory. No need to be mappable on host. It is roughly equivalent of D3D12_HEAP_TYPE_DEFAULT.

    -

    Usage:

    +
    VMA_MEMORY_USAGE_GPU_ONLY 

    Memory will be used on device only, so fast access from the device is preferred. It usually means device-local GPU (video) memory. No need to be mappable on host. It is roughly equivalent of D3D12_HEAP_TYPE_DEFAULT.

    +

    Usage:

    • Resources written and read by device, e.g. images used as attachments.
    • Resources transferred from host once (immutable) or infrequently and read by device multiple times, e.g. textures to be sampled, vertex buffers, uniform (constant) buffers, and majority of other types of resources used on GPU.
    -

    Allocation may still end up in HOST_VISIBLE memory on some implementations. In such case, you are free to map it. You can use VMA_ALLOCATION_CREATE_MAPPED_BIT with this usage type.

    +

    Allocation may still end up in HOST_VISIBLE memory on some implementations. In such case, you are free to map it. You can use VMA_ALLOCATION_CREATE_MAPPED_BIT with this usage type.

    VMA_MEMORY_USAGE_CPU_ONLY 

    Memory will be mappable on host. It usually means CPU (system) memory. Guarantees to be HOST_VISIBLE and HOST_COHERENT. CPU access is typically uncached. Writes may be write-combined. Resources created in this pool may still be accessible to the device, but access to them can be slow. It is roughly equivalent of D3D12_HEAP_TYPE_UPLOAD.

    -

    Usage: Staging copy of resources used as transfer source.

    +
    VMA_MEMORY_USAGE_CPU_ONLY 

    Memory will be mappable on host. It usually means CPU (system) memory. Guarantees to be HOST_VISIBLE and HOST_COHERENT. CPU access is typically uncached. Writes may be write-combined. Resources created in this pool may still be accessible to the device, but access to them can be slow. It is roughly equivalent of D3D12_HEAP_TYPE_UPLOAD.

    +

    Usage: Staging copy of resources used as transfer source.

    VMA_MEMORY_USAGE_CPU_TO_GPU 

    Memory that is both mappable on host (guarantees to be HOST_VISIBLE) and preferably fast to access by GPU. CPU access is typically uncached. Writes may be write-combined.

    -

    Usage: Resources written frequently by host (dynamic), read by device. E.g. textures (with LINEAR layout), vertex buffers, uniform buffers updated every frame or every draw call.

    +
    VMA_MEMORY_USAGE_CPU_TO_GPU 

    Memory that is both mappable on host (guarantees to be HOST_VISIBLE) and preferably fast to access by GPU. CPU access is typically uncached. Writes may be write-combined.

    +

    Usage: Resources written frequently by host (dynamic), read by device. E.g. textures (with LINEAR layout), vertex buffers, uniform buffers updated every frame or every draw call.

    VMA_MEMORY_USAGE_GPU_TO_CPU 

    Memory mappable on host (guarantees to be HOST_VISIBLE) and cached. It is roughly equivalent of D3D12_HEAP_TYPE_READBACK.

    -

    Usage:

    +
    VMA_MEMORY_USAGE_GPU_TO_CPU 

    Memory mappable on host (guarantees to be HOST_VISIBLE) and cached. It is roughly equivalent of D3D12_HEAP_TYPE_READBACK.

    +

    Usage:

    • Resources written by device, read by host - results of some computations, e.g. screen capture, average scene luminance for HDR tone mapping.
    • Any resources read or accessed randomly on host, e.g. CPU-side copy of vertex buffer used as source of transfer, but also used for collision detection.
    VMA_MEMORY_USAGE_CPU_COPY 

    CPU memory - memory that is preferably not DEVICE_LOCAL, but also not guaranteed to be HOST_VISIBLE.

    -

    Usage: Staging copy of resources moved from GPU memory to CPU memory as part of custom paging/residency mechanism, to be moved back to GPU memory when needed.

    +
    VMA_MEMORY_USAGE_CPU_COPY 

    CPU memory - memory that is preferably not DEVICE_LOCAL, but also not guaranteed to be HOST_VISIBLE.

    +

    Usage: Staging copy of resources moved from GPU memory to CPU memory as part of custom paging/residency mechanism, to be moved back to GPU memory when needed.

    VMA_MEMORY_USAGE_GPU_LAZILY_ALLOCATED 

    Lazily allocated GPU memory having VK_MEMORY_PROPERTY_LAZILY_ALLOCATED_BIT. Exists mostly on mobile platforms. Using it on desktop PC or other GPUs with no such memory type present will fail the allocation.

    -

    Usage: Memory for transient attachment images (color attachments, depth attachments etc.), created with VK_IMAGE_USAGE_TRANSIENT_ATTACHMENT_BIT.

    -

    Allocations with this usage are always created as dedicated - it implies VMA_ALLOCATION_CREATE_DEDICATED_MEMORY_BIT.

    +
    VMA_MEMORY_USAGE_GPU_LAZILY_ALLOCATED 

    Lazily allocated GPU memory having VK_MEMORY_PROPERTY_LAZILY_ALLOCATED_BIT. Exists mostly on mobile platforms. Using it on desktop PC or other GPUs with no such memory type present will fail the allocation.

    +

    Usage: Memory for transient attachment images (color attachments, depth attachments etc.), created with VK_IMAGE_USAGE_TRANSIENT_ATTACHMENT_BIT.

    +

    Allocations with this usage are always created as dedicated - it implies VMA_ALLOCATION_CREATE_DEDICATED_MEMORY_BIT.

    VMA_MEMORY_USAGE_MAX_ENUM 
    VMA_MEMORY_USAGE_MAX_ENUM 
    - +

    ◆ VmaPoolCreateFlagBits

    @@ -1261,29 +1261,29 @@ Functions

    Flags to be passed as VmaPoolCreateInfo::flags.

    - - - - - +
    Enumerator
    VMA_POOL_CREATE_IGNORE_BUFFER_IMAGE_GRANULARITY_BIT 

    Use this flag if you always allocate only buffers and linear images or only optimal images out of this pool and so Buffer-Image Granularity can be ignored.

    -

    This is an optional optimization flag.

    -

    If you always allocate using vmaCreateBuffer(), vmaCreateImage(), vmaAllocateMemoryForBuffer(), then you don't need to use it because allocator knows exact type of your allocations so it can handle Buffer-Image Granularity in the optimal way.

    -

    If you also allocate using vmaAllocateMemoryForImage() or vmaAllocateMemory(), exact type of such allocations is not known, so allocator must be conservative in handling Buffer-Image Granularity, which can lead to suboptimal allocation (wasted memory). In that case, if you can make sure you always allocate only buffers and linear images or only optimal images out of this pool, use this flag to make allocator disregard Buffer-Image Granularity and so make allocations faster and more optimal.

    +
    Enumerator
    VMA_POOL_CREATE_IGNORE_BUFFER_IMAGE_GRANULARITY_BIT 

    Use this flag if you always allocate only buffers and linear images or only optimal images out of this pool and so Buffer-Image Granularity can be ignored.

    +

    This is an optional optimization flag.

    +

    If you always allocate using vmaCreateBuffer(), vmaCreateImage(), vmaAllocateMemoryForBuffer(), then you don't need to use it because allocator knows exact type of your allocations so it can handle Buffer-Image Granularity in the optimal way.

    +

    If you also allocate using vmaAllocateMemoryForImage() or vmaAllocateMemory(), exact type of such allocations is not known, so allocator must be conservative in handling Buffer-Image Granularity, which can lead to suboptimal allocation (wasted memory). In that case, if you can make sure you always allocate only buffers and linear images or only optimal images out of this pool, use this flag to make allocator disregard Buffer-Image Granularity and so make allocations faster and more optimal.

    VMA_POOL_CREATE_LINEAR_ALGORITHM_BIT 

    Enables alternative, linear allocation algorithm in this pool.

    -

    Specify this flag to enable linear allocation algorithm, which always creates new allocations after last one and doesn't reuse space from allocations freed in between. It trades memory consumption for simplified algorithm and data structure, which has better performance and uses less memory for metadata.

    -

    By using this flag, you can achieve behavior of free-at-once, stack, ring buffer, and double stack. For details, see documentation chapter Linear allocation algorithm.

    -

    When using this flag, you must specify VmaPoolCreateInfo::maxBlockCount == 1 (or 0 for default).

    -

    For more details, see Linear allocation algorithm.

    +
    VMA_POOL_CREATE_LINEAR_ALGORITHM_BIT 

    Enables alternative, linear allocation algorithm in this pool.

    +

    Specify this flag to enable linear allocation algorithm, which always creates new allocations after last one and doesn't reuse space from allocations freed in between. It trades memory consumption for simplified algorithm and data structure, which has better performance and uses less memory for metadata.

    +

    By using this flag, you can achieve behavior of free-at-once, stack, ring buffer, and double stack. For details, see documentation chapter Linear allocation algorithm.

    +

    When using this flag, you must specify VmaPoolCreateInfo::maxBlockCount == 1 (or 0 for default).

    +

    For more details, see Linear allocation algorithm.

    VMA_POOL_CREATE_BUDDY_ALGORITHM_BIT 

    Enables alternative, buddy allocation algorithm in this pool.

    -

    It operates on a tree of blocks, each having size that is a power of two and a half of its parent's size. Comparing to default algorithm, this one provides faster allocation and deallocation and decreased external fragmentation, at the expense of more memory wasted (internal fragmentation).

    -

    For more details, see Buddy allocation algorithm.

    +
    VMA_POOL_CREATE_BUDDY_ALGORITHM_BIT 

    Enables alternative, buddy allocation algorithm in this pool.

    +

    It operates on a tree of blocks, each having size that is a power of two and a half of its parent's size. Comparing to default algorithm, this one provides faster allocation and deallocation and decreased external fragmentation, at the expense of more memory wasted (internal fragmentation).

    +

    For more details, see Buddy allocation algorithm.

    VMA_POOL_CREATE_ALGORITHM_MASK 

    Bit mask to extract only ALGORITHM bits from entire set of flags.

    +
    VMA_POOL_CREATE_ALGORITHM_MASK 

    Bit mask to extract only ALGORITHM bits from entire set of flags.

    VMA_POOL_CREATE_FLAG_BITS_MAX_ENUM 
    VMA_POOL_CREATE_FLAG_BITS_MAX_ENUM 
    - +

    ◆ VmaRecordFlagBits

    @@ -1297,16 +1297,16 @@ Functions

    Flags to be used in VmaRecordSettings::flags.

    - - +
    Enumerator
    VMA_RECORD_FLUSH_AFTER_CALL_BIT 

    Enables flush after recording every function call.

    -

    Enable it if you expect your application to crash, which may leave recording file truncated. It may degrade performance though.

    +
    Enumerator
    VMA_RECORD_FLUSH_AFTER_CALL_BIT 

    Enables flush after recording every function call.

    +

    Enable it if you expect your application to crash, which may leave recording file truncated. It may degrade performance though.

    VMA_RECORD_FLAG_BITS_MAX_ENUM 
    VMA_RECORD_FLAG_BITS_MAX_ENUM 

    Function Documentation

    - +

    ◆ vmaAllocateMemory()

    @@ -1362,11 +1362,11 @@ Functions

    You should free the memory using vmaFreeMemory() or vmaFreeMemoryPages().

    -

    It is recommended to use vmaAllocateMemoryForBuffer(), vmaAllocateMemoryForImage(), vmaCreateBuffer(), vmaCreateImage() instead whenever possible.

    +

    It is recommended to use vmaAllocateMemoryForBuffer(), vmaAllocateMemoryForImage(), vmaCreateBuffer(), vmaCreateImage() instead whenever possible.

    - +

    ◆ vmaAllocateMemoryForBuffer()

    @@ -1423,7 +1423,7 @@ Functions
    - +

    ◆ vmaAllocateMemoryForImage()

    @@ -1471,7 +1471,7 @@ Functions
    - +

    ◆ vmaAllocateMemoryPages()

    @@ -1534,12 +1534,12 @@ Functions

    You should free the memory using vmaFreeMemory() or vmaFreeMemoryPages().

    -

    Word "pages" is just a suggestion to use this function to allocate pieces of memory needed for sparse binding. It is just a general purpose allocation function able to make multiple allocations at once. It may be internally optimized to be more efficient than calling vmaAllocateMemory() allocationCount times.

    -

    All allocations are made using same parameters. All of them are created out of the same memory pool and type. If any allocation fails, all allocations already made within this function call are also freed, so that when returned result is not VK_SUCCESS, pAllocation array is always entirely filled with VK_NULL_HANDLE.

    +

    Word "pages" is just a suggestion to use this function to allocate pieces of memory needed for sparse binding. It is just a general purpose allocation function able to make multiple allocations at once. It may be internally optimized to be more efficient than calling vmaAllocateMemory() allocationCount times.

    +

    All allocations are made using same parameters. All of them are created out of the same memory pool and type. If any allocation fails, all allocations already made within this function call are also freed, so that when returned result is not VK_SUCCESS, pAllocation array is always entirely filled with VK_NULL_HANDLE.

    - +

    ◆ vmaBeginDefragmentationPass()

    @@ -1573,7 +1573,7 @@ Functions
    - +

    ◆ vmaBindBufferMemory()

    @@ -1606,12 +1606,12 @@ Functions

    Binds buffer to allocation.

    -

    Binds specified buffer to region of memory represented by specified allocation. Gets VkDeviceMemory handle and offset from the allocation. If you want to create a buffer, allocate memory for it and bind them together separately, you should use this function for binding instead of standard vkBindBufferMemory(), because it ensures proper synchronization so that when a VkDeviceMemory object is used by multiple allocations, calls to vkBind*Memory() or vkMapMemory() won't happen from multiple threads simultaneously (which is illegal in Vulkan).

    -

    It is recommended to use function vmaCreateBuffer() instead of this one.

    +

    Binds specified buffer to region of memory represented by specified allocation. Gets VkDeviceMemory handle and offset from the allocation. If you want to create a buffer, allocate memory for it and bind them together separately, you should use this function for binding instead of standard vkBindBufferMemory(), because it ensures proper synchronization so that when a VkDeviceMemory object is used by multiple allocations, calls to vkBind*Memory() or vkMapMemory() won't happen from multiple threads simultaneously (which is illegal in Vulkan).

    +

    It is recommended to use function vmaCreateBuffer() instead of this one.

    - +

    ◆ vmaBindBufferMemory2()

    @@ -1667,11 +1667,11 @@ Functions

    This function is similar to vmaBindBufferMemory(), but it provides additional parameters.

    -

    If pNext is not null, VmaAllocator object must have been created with VMA_ALLOCATOR_CREATE_KHR_BIND_MEMORY2_BIT flag or with VmaAllocatorCreateInfo::vulkanApiVersion >= VK_API_VERSION_1_1. Otherwise the call fails.

    +

    If pNext is not null, VmaAllocator object must have been created with VMA_ALLOCATOR_CREATE_KHR_BIND_MEMORY2_BIT flag or with VmaAllocatorCreateInfo::vulkanApiVersion >= VK_API_VERSION_1_1. Otherwise the call fails.

    - +

    ◆ vmaBindImageMemory()

    @@ -1704,12 +1704,12 @@ Functions

    Binds image to allocation.

    -

    Binds specified image to region of memory represented by specified allocation. Gets VkDeviceMemory handle and offset from the allocation. If you want to create an image, allocate memory for it and bind them together separately, you should use this function for binding instead of standard vkBindImageMemory(), because it ensures proper synchronization so that when a VkDeviceMemory object is used by multiple allocations, calls to vkBind*Memory() or vkMapMemory() won't happen from multiple threads simultaneously (which is illegal in Vulkan).

    -

    It is recommended to use function vmaCreateImage() instead of this one.

    +

    Binds specified image to region of memory represented by specified allocation. Gets VkDeviceMemory handle and offset from the allocation. If you want to create an image, allocate memory for it and bind them together separately, you should use this function for binding instead of standard vkBindImageMemory(), because it ensures proper synchronization so that when a VkDeviceMemory object is used by multiple allocations, calls to vkBind*Memory() or vkMapMemory() won't happen from multiple threads simultaneously (which is illegal in Vulkan).

    +

    It is recommended to use function vmaCreateImage() instead of this one.

    - +

    ◆ vmaBindImageMemory2()

    @@ -1765,11 +1765,11 @@ Functions

    This function is similar to vmaBindImageMemory(), but it provides additional parameters.

    -

    If pNext is not null, VmaAllocator object must have been created with VMA_ALLOCATOR_CREATE_KHR_BIND_MEMORY2_BIT flag or with VmaAllocatorCreateInfo::vulkanApiVersion >= VK_API_VERSION_1_1. Otherwise the call fails.

    +

    If pNext is not null, VmaAllocator object must have been created with VMA_ALLOCATOR_CREATE_KHR_BIND_MEMORY2_BIT flag or with VmaAllocatorCreateInfo::vulkanApiVersion >= VK_API_VERSION_1_1. Otherwise the call fails.

    - +

    ◆ vmaBuildStatsString()

    @@ -1813,7 +1813,7 @@ Functions
    - +

    ◆ vmaCalculateStats()

    @@ -1840,12 +1840,12 @@ Functions

    Retrieves statistics from current state of the Allocator.

    -

    This function is called "calculate" not "get" because it has to traverse all internal data structures, so it may be quite slow. For faster but more brief statistics suitable to be called every frame or every allocation, use vmaGetBudget().

    -

    Note that when using allocator from multiple threads, returned information may immediately become outdated.

    +

    This function is called "calculate" not "get" because it has to traverse all internal data structures, so it may be quite slow. For faster but more brief statistics suitable to be called every frame or every allocation, use vmaGetBudget().

    +

    Note that when using allocator from multiple threads, returned information may immediately become outdated.

    - +

    ◆ vmaCheckCorruption()

    @@ -1880,17 +1880,17 @@ Functions

    Corruption detection is enabled only when VMA_DEBUG_DETECT_CORRUPTION macro is defined to nonzero, VMA_DEBUG_MARGIN is defined to nonzero and only for memory types that are HOST_VISIBLE and HOST_COHERENT. For more information, see Corruption detection.

    -

    Possible return values:

    +

    Possible return values:

    - +

    ◆ vmaCheckPoolCorruption()

    @@ -1917,18 +1917,18 @@ Functions

    Checks magic number in margins around all allocations in given memory pool in search for corruptions.

    -

    Corruption detection is enabled only when VMA_DEBUG_DETECT_CORRUPTION macro is defined to nonzero, VMA_DEBUG_MARGIN is defined to nonzero and the pool is created in memory type that is HOST_VISIBLE and HOST_COHERENT. For more information, see Corruption detection.

    -

    Possible return values:

    +

    Corruption detection is enabled only when VMA_DEBUG_DETECT_CORRUPTION macro is defined to nonzero, VMA_DEBUG_MARGIN is defined to nonzero and the pool is created in memory type that is HOST_VISIBLE and HOST_COHERENT. For more information, see Corruption detection.

    +

    Possible return values:

    - +

    ◆ vmaCreateAllocator()

    @@ -1958,7 +1958,7 @@ Functions
    - +

    ◆ vmaCreateBuffer()

    @@ -2024,14 +2024,14 @@ Functions
  • Allocates appropriate memory for it.
  • Binds the buffer with the memory.
    • -

    If any of these operations fail, buffer and allocation are not created, returned value is negative error code, *pBuffer and *pAllocation are null.

    -

    If the function succeeded, you must destroy both buffer and allocation when you no longer need them using either convenience function vmaDestroyBuffer() or separately, using vkDestroyBuffer() and vmaFreeMemory().

    -

    If VMA_ALLOCATOR_CREATE_KHR_DEDICATED_ALLOCATION_BIT flag was used, VK_KHR_dedicated_allocation extension is used internally to query driver whether it requires or prefers the new buffer to have dedicated allocation. If yes, and if dedicated allocation is possible (VmaAllocationCreateInfo::pool is null and VMA_ALLOCATION_CREATE_NEVER_ALLOCATE_BIT is not used), it creates dedicated allocation for this buffer, just like when using VMA_ALLOCATION_CREATE_DEDICATED_MEMORY_BIT.

    +

    If any of these operations fail, buffer and allocation are not created, returned value is negative error code, *pBuffer and *pAllocation are null.

    +

    If the function succeeded, you must destroy both buffer and allocation when you no longer need them using either convenience function vmaDestroyBuffer() or separately, using vkDestroyBuffer() and vmaFreeMemory().

    +

    If VMA_ALLOCATOR_CREATE_KHR_DEDICATED_ALLOCATION_BIT flag was used, VK_KHR_dedicated_allocation extension is used internally to query driver whether it requires or prefers the new buffer to have dedicated allocation. If yes, and if dedicated allocation is possible (VmaAllocationCreateInfo::pool is null and VMA_ALLOCATION_CREATE_NEVER_ALLOCATE_BIT is not used), it creates dedicated allocation for this buffer, just like when using VMA_ALLOCATION_CREATE_DEDICATED_MEMORY_BIT.

    Note
    This function creates a new VkBuffer. Sub-allocation of parts of one large buffer, although recommended as a good practice, is out of scope of this library and could be implemented by the user as a higher-level logic on top of VMA.
    - +

    ◆ vmaCreateBufferWithAlignment()

    @@ -2088,11 +2088,11 @@ Functions

    Creates a buffer with additional minimum alignment.

    -

    Similar to vmaCreateBuffer() but provides additional parameter minAlignment which allows to specify custom, minimum alignment to be used when placing the buffer inside a larger memory block, which may be needed e.g. for interop with OpenGL.

    +

    Similar to vmaCreateBuffer() but provides additional parameter minAlignment which allows to specify custom, minimum alignment to be used when placing the buffer inside a larger memory block, which may be needed e.g. for interop with OpenGL.

    - +

    ◆ vmaCreateImage()

    @@ -2146,7 +2146,7 @@ Functions
    - +

    ◆ vmaCreateLostAllocation()

    @@ -2173,13 +2173,13 @@ Functions

    Creates new allocation that is in lost state from the beginning.

    -

    It can be useful if you need a dummy, non-null allocation.

    -

    You still need to destroy created object using vmaFreeMemory().

    -

    Returned allocation is not tied to any specific memory pool or memory type and not bound to any image or buffer. It has size = 0. It cannot be turned into a real, non-empty allocation.

    +

    It can be useful if you need a dummy, non-null allocation.

    +

    You still need to destroy created object using vmaFreeMemory().

    +

    Returned allocation is not tied to any specific memory pool or memory type and not bound to any image or buffer. It has size = 0. It cannot be turned into a real, non-empty allocation.

    - +

    ◆ vmaCreatePool()

    @@ -2223,7 +2223,7 @@ Functions
    - +

    ◆ vmaDefragment()

    @@ -2287,7 +2287,7 @@ Functions
    Returns
    VK_SUCCESS if completed, negative error code in case of error.
    Deprecated:
    This is a part of the old interface. It is recommended to use structure VmaDefragmentationInfo2 and function vmaDefragmentationBegin() instead.
    -

    This function works by moving allocations to different places (different VkDeviceMemory objects and/or different offsets) in order to optimize memory usage. Only allocations that are in pAllocations array can be moved. All other allocations are considered nonmovable in this call. Basic rules:

    +

    This function works by moving allocations to different places (different VkDeviceMemory objects and/or different offsets) in order to optimize memory usage. Only allocations that are in pAllocations array can be moved. All other allocations are considered nonmovable in this call. Basic rules:

    -

    The function also frees empty VkDeviceMemory blocks.

    -

    Warning: This function may be time-consuming, so you shouldn't call it too often (like after every resource creation/destruction). You can call it on special occasions (like when reloading a game level or when you just destroyed a lot of objects). Calling it every frame may be OK, but you should measure that on your platform.

    -

    For more information, see Defragmentation chapter.

    +

    The function also frees empty VkDeviceMemory blocks.

    +

    Warning: This function may be time-consuming, so you shouldn't call it too often (like after every resource creation/destruction). You can call it on special occasions (like when reloading a game level or when you just destroyed a lot of objects). Calling it every frame may be OK, but you should measure that on your platform.

    +

    For more information, see Defragmentation chapter.

    - +

    ◆ vmaDefragmentationBegin()

    @@ -2351,18 +2351,18 @@ Functions
    Returns
    VK_SUCCESS and *pContext == null if defragmentation finished within this function call. VK_NOT_READY and *pContext != null if defragmentation has been started and you need to call vmaDefragmentationEnd() to finish it. Negative value in case of error.

    Use this function instead of old, deprecated vmaDefragment().

    -

    Warning! Between the call to vmaDefragmentationBegin() and vmaDefragmentationEnd():

    +

    Warning! Between the call to vmaDefragmentationBegin() and vmaDefragmentationEnd():

    -

    For more information and important limitations regarding defragmentation, see documentation chapter: Defragmentation.

    +

    For more information and important limitations regarding defragmentation, see documentation chapter: Defragmentation.

    - +

    ◆ vmaDefragmentationEnd()

    @@ -2389,11 +2389,11 @@ Functions

    Ends defragmentation process.

    -

    Use this function to finish defragmentation started by vmaDefragmentationBegin(). It is safe to pass context == null. The function then does nothing.

    +

    Use this function to finish defragmentation started by vmaDefragmentationBegin(). It is safe to pass context == null. The function then does nothing.

    - +

    ◆ vmaDestroyAllocator()

    @@ -2413,7 +2413,7 @@ Functions
    - +

    ◆ vmaDestroyBuffer()

    @@ -2446,15 +2446,15 @@ Functions

    Destroys Vulkan buffer and frees allocated memory.

    -

    This is just a convenience function equivalent to:

    +

    This is just a convenience function equivalent to:

    vkDestroyBuffer(device, buffer, allocationCallbacks);
    -
    vmaFreeMemory(allocator, allocation);
    +
    vmaFreeMemory(allocator, allocation);
    vmaFreeMemory
    void vmaFreeMemory(VmaAllocator allocator, const VmaAllocation allocation)
    Frees memory previously allocated using vmaAllocateMemory(), vmaAllocateMemoryForBuffer(),...
    -

    It it safe to pass null as buffer and/or allocation.

    +

    It it safe to pass null as buffer and/or allocation.

    - +

    ◆ vmaDestroyImage()

    @@ -2487,14 +2487,14 @@ Functions

    Destroys Vulkan image and frees allocated memory.

    -

    This is just a convenience function equivalent to:

    +

    This is just a convenience function equivalent to:

    vkDestroyImage(device, image, allocationCallbacks);
    -
    vmaFreeMemory(allocator, allocation);
    -

    It it safe to pass null as image and/or allocation.

    +
    vmaFreeMemory(allocator, allocation);
    +

    It it safe to pass null as image and/or allocation.

    - +

    ◆ vmaDestroyPool()

    @@ -2524,7 +2524,7 @@ Functions
    - +

    ◆ vmaEndDefragmentationPass()

    @@ -2552,7 +2552,7 @@ Functions
    - +

    ◆ vmaFindMemoryTypeIndex()

    @@ -2591,7 +2591,7 @@ Functions

    Helps to find memoryTypeIndex, given memoryTypeBits and VmaAllocationCreateInfo.

    -

    This algorithm tries to find a memory type that:

    +

    This algorithm tries to find a memory type that:

    - +

    ◆ vmaFindMemoryTypeIndexForBufferInfo()

    @@ -2641,7 +2641,7 @@ Functions

    Helps to find memoryTypeIndex, given VkBufferCreateInfo and VmaAllocationCreateInfo.

    -

    It can be useful e.g. to determine value to be used as VmaPoolCreateInfo::memoryTypeIndex. It internally creates a temporary, dummy buffer that never has memory bound. It is just a convenience function, equivalent to calling:

    +

    It can be useful e.g. to determine value to be used as VmaPoolCreateInfo::memoryTypeIndex. It internally creates a temporary, dummy buffer that never has memory bound. It is just a convenience function, equivalent to calling:

    - +

    ◆ vmaFindMemoryTypeIndexForImageInfo()

    @@ -2690,7 +2690,7 @@ Functions

    Helps to find memoryTypeIndex, given VkImageCreateInfo and VmaAllocationCreateInfo.

    -

    It can be useful e.g. to determine value to be used as VmaPoolCreateInfo::memoryTypeIndex. It internally creates a temporary, dummy image that never has memory bound. It is just a convenience function, equivalent to calling:

    +

    It can be useful e.g. to determine value to be used as VmaPoolCreateInfo::memoryTypeIndex. It internally creates a temporary, dummy image that never has memory bound. It is just a convenience function, equivalent to calling:

    - +

    ◆ vmaFlushAllocation()

    @@ -2739,7 +2739,7 @@ Functions

    Flushes memory of given allocation.

    -

    Calls vkFlushMappedMemoryRanges() for memory associated with given range of given allocation. It needs to be called after writing to a mapped memory for memory types that are not HOST_COHERENT. Unmap operation doesn't do that automatically.

    +

    Calls vkFlushMappedMemoryRanges() for memory associated with given range of given allocation. It needs to be called after writing to a mapped memory for memory types that are not HOST_COHERENT. Unmap operation doesn't do that automatically.

    -

    Warning! offset and size are relative to the contents of given allocation. If you mean whole allocation, you can pass 0 and VK_WHOLE_SIZE, respectively. Do not pass allocation's offset as offset!!!

    -

    This function returns the VkResult from vkFlushMappedMemoryRanges if it is called, otherwise VK_SUCCESS.

    +

    Warning! offset and size are relative to the contents of given allocation. If you mean whole allocation, you can pass 0 and VK_WHOLE_SIZE, respectively. Do not pass allocation's offset as offset!!!

    +

    This function returns the VkResult from vkFlushMappedMemoryRanges if it is called, otherwise VK_SUCCESS.

    - +

    ◆ vmaFlushAllocations()

    @@ -2797,7 +2797,7 @@ Functions

    Flushes memory of given set of allocations.

    -

    Calls vkFlushMappedMemoryRanges() for memory associated with given ranges of given allocations. For more information, see documentation of vmaFlushAllocation().

    +

    Calls vkFlushMappedMemoryRanges() for memory associated with given ranges of given allocations. For more information, see documentation of vmaFlushAllocation().

    Parameters
    @@ -2812,7 +2812,7 @@ Functions - +

    ◆ vmaFreeMemory()

    @@ -2839,11 +2839,11 @@ Functions

    Frees memory previously allocated using vmaAllocateMemory(), vmaAllocateMemoryForBuffer(), or vmaAllocateMemoryForImage().

    -

    Passing VK_NULL_HANDLE as allocation is valid. Such function call is just skipped.

    +

    Passing VK_NULL_HANDLE as allocation is valid. Such function call is just skipped.

    - +

    ◆ vmaFreeMemoryPages()

    @@ -2876,12 +2876,12 @@ Functions

    Frees memory and destroys multiple allocations.

    -

    Word "pages" is just a suggestion to use this function to free pieces of memory used for sparse binding. It is just a general purpose function to free memory and destroy allocations made using e.g. vmaAllocateMemory(), vmaAllocateMemoryPages() and other functions. It may be internally optimized to be more efficient than calling vmaFreeMemory() allocationCount times.

    -

    Allocations in pAllocations array can come from any memory pools and types. Passing VK_NULL_HANDLE as elements of pAllocations array is valid. Such entries are just skipped.

    +

    Word "pages" is just a suggestion to use this function to free pieces of memory used for sparse binding. It is just a general purpose function to free memory and destroy allocations made using e.g. vmaAllocateMemory(), vmaAllocateMemoryPages() and other functions. It may be internally optimized to be more efficient than calling vmaFreeMemory() allocationCount times.

    +

    Allocations in pAllocations array can come from any memory pools and types. Passing VK_NULL_HANDLE as elements of pAllocations array is valid. Such entries are just skipped.

    - +

    ◆ vmaFreeStatsString()

    @@ -2909,7 +2909,7 @@ Functions
    - +

    ◆ vmaGetAllocationInfo()

    @@ -2942,9 +2942,9 @@ Functions

    Returns current information about specified allocation and atomically marks it as used in current frame.

    -

    Current paramteres of given allocation are returned in pAllocationInfo.

    -

    This function also atomically "touches" allocation - marks it as used in current frame, just like vmaTouchAllocation(). If the allocation is in lost state, pAllocationInfo->deviceMemory == VK_NULL_HANDLE.

    -

    Although this function uses atomics and doesn't lock any mutex, so it should be quite efficient, you can avoid calling it too often.

    +

    Current paramteres of given allocation are returned in pAllocationInfo.

    +

    This function also atomically "touches" allocation - marks it as used in current frame, just like vmaTouchAllocation(). If the allocation is in lost state, pAllocationInfo->deviceMemory == VK_NULL_HANDLE.

    +

    Although this function uses atomics and doesn't lock any mutex, so it should be quite efficient, you can avoid calling it too often.

    • You can retrieve same VmaAllocationInfo structure while creating your resource, from function vmaCreateBuffer(), vmaCreateImage(). You can remember it if you are sure parameters don't change (e.g. due to defragmentation or allocation becoming lost).
    • If you just want to check if allocation is not lost, vmaTouchAllocation() will work faster.
      • @@ -2952,7 +2952,7 @@ Functions
    - +

    ◆ vmaGetAllocatorInfo()

    @@ -2979,11 +2979,11 @@ Functions

    Returns information about existing VmaAllocator object - handle to Vulkan device etc.

    -

    It might be useful if you want to keep just the VmaAllocator handle and fetch other required handles to VkPhysicalDevice, VkDevice etc. every time using this function.

    +

    It might be useful if you want to keep just the VmaAllocator handle and fetch other required handles to VkPhysicalDevice, VkDevice etc. every time using this function.

    - +

    ◆ vmaGetBudget()

    @@ -3018,11 +3018,11 @@ Functions

    This function is called "get" not "calculate" because it is very fast, suitable to be called every frame or every allocation. For more detailed statistics use vmaCalculateStats().

    -

    Note that when using allocator from multiple threads, returned information may immediately become outdated.

    +

    Note that when using allocator from multiple threads, returned information may immediately become outdated.

    - +

    ◆ vmaGetMemoryProperties()

    @@ -3047,11 +3047,11 @@ Functions
    allocator
    -

    PhysicalDeviceMemoryProperties are fetched from physicalDevice by the allocator. You can access it here, without fetching it again on your own.

    +

    PhysicalDeviceMemoryProperties are fetched from physicalDevice by the allocator. You can access it here, without fetching it again on your own.

    - +

    ◆ vmaGetMemoryTypeProperties()

    @@ -3084,11 +3084,11 @@ Functions

    Given Memory Type Index, returns Property Flags of this memory type.

    -

    This is just a convenience function. Same information can be obtained using vmaGetMemoryProperties().

    +

    This is just a convenience function. Same information can be obtained using vmaGetMemoryProperties().

    - +

    ◆ vmaGetPhysicalDeviceProperties()

    @@ -3113,11 +3113,11 @@ Functions
    -

    PhysicalDeviceProperties are fetched from physicalDevice by the allocator. You can access it here, without fetching it again on your own.

    +

    PhysicalDeviceProperties are fetched from physicalDevice by the allocator. You can access it here, without fetching it again on your own.

    - +

    ◆ vmaGetPoolName()

    @@ -3150,11 +3150,11 @@ Functions

    Retrieves name of a custom pool.

    -

    After the call ppName is either null or points to an internally-owned null-terminated string containing name of the pool that was previously set. The pointer becomes invalid when the pool is destroyed or its name is changed using vmaSetPoolName().

    +

    After the call ppName is either null or points to an internally-owned null-terminated string containing name of the pool that was previously set. The pointer becomes invalid when the pool is destroyed or its name is changed using vmaSetPoolName().

    - +

    ◆ vmaGetPoolStats()

    @@ -3198,7 +3198,7 @@ Functions
    - +

    ◆ vmaInvalidateAllocation()

    @@ -3237,7 +3237,7 @@ Functions

    Invalidates memory of given allocation.

    -

    Calls vkInvalidateMappedMemoryRanges() for memory associated with given range of given allocation. It needs to be called before reading from a mapped memory for memory types that are not HOST_COHERENT. Map operation doesn't do that automatically.

    +

    Calls vkInvalidateMappedMemoryRanges() for memory associated with given range of given allocation. It needs to be called before reading from a mapped memory for memory types that are not HOST_COHERENT. Map operation doesn't do that automatically.

    -

    Warning! offset and size are relative to the contents of given allocation. If you mean whole allocation, you can pass 0 and VK_WHOLE_SIZE, respectively. Do not pass allocation's offset as offset!!!

    -

    This function returns the VkResult from vkInvalidateMappedMemoryRanges if it is called, otherwise VK_SUCCESS.

    +

    Warning! offset and size are relative to the contents of given allocation. If you mean whole allocation, you can pass 0 and VK_WHOLE_SIZE, respectively. Do not pass allocation's offset as offset!!!

    +

    This function returns the VkResult from vkInvalidateMappedMemoryRanges if it is called, otherwise VK_SUCCESS.

    - +

    ◆ vmaInvalidateAllocations()

    @@ -3295,7 +3295,7 @@ Functions

    Invalidates memory of given set of allocations.

    -

    Calls vkInvalidateMappedMemoryRanges() for memory associated with given ranges of given allocations. For more information, see documentation of vmaInvalidateAllocation().

    +

    Calls vkInvalidateMappedMemoryRanges() for memory associated with given ranges of given allocations. For more information, see documentation of vmaInvalidateAllocation().

    Parameters
    @@ -3310,7 +3310,7 @@ Functions - +

    ◆ vmaMakePoolAllocationsLost()

    @@ -3354,7 +3354,7 @@ Functions
    - +

    ◆ vmaMapMemory()

    @@ -3387,18 +3387,18 @@ Functions

    Maps memory represented by given allocation and returns pointer to it.

    -

    Maps memory represented by given allocation to make it accessible to CPU code. When succeeded, *ppData contains pointer to first byte of this memory. If the allocation is part of bigger VkDeviceMemory block, the pointer is correctly offsetted to the beginning of region assigned to this particular allocation.

    -

    Mapping is internally reference-counted and synchronized, so despite raw Vulkan function vkMapMemory() cannot be used to map same block of VkDeviceMemory multiple times simultaneously, it is safe to call this function on allocations assigned to the same memory block. Actual Vulkan memory will be mapped on first mapping and unmapped on last unmapping.

    -

    If the function succeeded, you must call vmaUnmapMemory() to unmap the allocation when mapping is no longer needed or before freeing the allocation, at the latest.

    -

    It also safe to call this function multiple times on the same allocation. You must call vmaUnmapMemory() same number of times as you called vmaMapMemory().

    -

    It is also safe to call this function on allocation created with VMA_ALLOCATION_CREATE_MAPPED_BIT flag. Its memory stays mapped all the time. You must still call vmaUnmapMemory() same number of times as you called vmaMapMemory(). You must not call vmaUnmapMemory() additional time to free the "0-th" mapping made automatically due to VMA_ALLOCATION_CREATE_MAPPED_BIT flag.

    -

    This function fails when used on allocation made in memory type that is not HOST_VISIBLE.

    -

    This function always fails when called for allocation that was created with VMA_ALLOCATION_CREATE_CAN_BECOME_LOST_BIT flag. Such allocations cannot be mapped.

    -

    This function doesn't automatically flush or invalidate caches. If the allocation is made from a memory types that is not HOST_COHERENT, you also need to use vmaInvalidateAllocation() / vmaFlushAllocation(), as required by Vulkan specification.

    +

    Maps memory represented by given allocation to make it accessible to CPU code. When succeeded, *ppData contains pointer to first byte of this memory. If the allocation is part of bigger VkDeviceMemory block, the pointer is correctly offsetted to the beginning of region assigned to this particular allocation.

    +

    Mapping is internally reference-counted and synchronized, so despite raw Vulkan function vkMapMemory() cannot be used to map same block of VkDeviceMemory multiple times simultaneously, it is safe to call this function on allocations assigned to the same memory block. Actual Vulkan memory will be mapped on first mapping and unmapped on last unmapping.

    +

    If the function succeeded, you must call vmaUnmapMemory() to unmap the allocation when mapping is no longer needed or before freeing the allocation, at the latest.

    +

    It also safe to call this function multiple times on the same allocation. You must call vmaUnmapMemory() same number of times as you called vmaMapMemory().

    +

    It is also safe to call this function on allocation created with VMA_ALLOCATION_CREATE_MAPPED_BIT flag. Its memory stays mapped all the time. You must still call vmaUnmapMemory() same number of times as you called vmaMapMemory(). You must not call vmaUnmapMemory() additional time to free the "0-th" mapping made automatically due to VMA_ALLOCATION_CREATE_MAPPED_BIT flag.

    +

    This function fails when used on allocation made in memory type that is not HOST_VISIBLE.

    +

    This function always fails when called for allocation that was created with VMA_ALLOCATION_CREATE_CAN_BECOME_LOST_BIT flag. Such allocations cannot be mapped.

    +

    This function doesn't automatically flush or invalidate caches. If the allocation is made from a memory types that is not HOST_COHERENT, you also need to use vmaInvalidateAllocation() / vmaFlushAllocation(), as required by Vulkan specification.

    - +

    ◆ vmaSetAllocationUserData()

    @@ -3431,12 +3431,12 @@ Functions

    Sets pUserData in given allocation to new value.

    -

    If the allocation was created with VMA_ALLOCATION_CREATE_USER_DATA_COPY_STRING_BIT, pUserData must be either null, or pointer to a null-terminated string. The function makes local copy of the string and sets it as allocation's pUserData. String passed as pUserData doesn't need to be valid for whole lifetime of the allocation - you can free it after this call. String previously pointed by allocation's pUserData is freed from memory.

    -

    If the flag was not used, the value of pointer pUserData is just copied to allocation's pUserData. It is opaque, so you can use it however you want - e.g. as a pointer, ordinal number or some handle to you own data.

    +

    If the allocation was created with VMA_ALLOCATION_CREATE_USER_DATA_COPY_STRING_BIT, pUserData must be either null, or pointer to a null-terminated string. The function makes local copy of the string and sets it as allocation's pUserData. String passed as pUserData doesn't need to be valid for whole lifetime of the allocation - you can free it after this call. String previously pointed by allocation's pUserData is freed from memory.

    +

    If the flag was not used, the value of pointer pUserData is just copied to allocation's pUserData. It is opaque, so you can use it however you want - e.g. as a pointer, ordinal number or some handle to you own data.

    - +

    ◆ vmaSetCurrentFrameIndex()

    @@ -3463,11 +3463,11 @@ Functions

    Sets index of the current frame.

    -

    This function must be used if you make allocations with VMA_ALLOCATION_CREATE_CAN_BECOME_LOST_BIT and VMA_ALLOCATION_CREATE_CAN_MAKE_OTHER_LOST_BIT flags to inform the allocator when a new frame begins. Allocations queried using vmaGetAllocationInfo() cannot become lost in the current frame.

    +

    This function must be used if you make allocations with VMA_ALLOCATION_CREATE_CAN_BECOME_LOST_BIT and VMA_ALLOCATION_CREATE_CAN_MAKE_OTHER_LOST_BIT flags to inform the allocator when a new frame begins. Allocations queried using vmaGetAllocationInfo() cannot become lost in the current frame.

    - +

    ◆ vmaSetPoolName()

    @@ -3500,11 +3500,11 @@ Functions

    Sets name of a custom pool.

    -

    pName can be either null or pointer to a null-terminated string with new name for the pool. Function makes internal copy of the string, so it can be changed or freed immediately after this call.

    +

    pName can be either null or pointer to a null-terminated string with new name for the pool. Function makes internal copy of the string, so it can be changed or freed immediately after this call.

    - +

    ◆ vmaTouchAllocation()

    @@ -3531,13 +3531,13 @@ Functions

    Returns VK_TRUE if allocation is not lost and atomically marks it as used in current frame.

    -

    If the allocation has been created with VMA_ALLOCATION_CREATE_CAN_BECOME_LOST_BIT flag, this function returns VK_TRUE if it is not in lost state, so it can still be used. It then also atomically "touches" the allocation - marks it as used in current frame, so that you can be sure it won't become lost in current frame or next frameInUseCount frames.

    -

    If the allocation is in lost state, the function returns VK_FALSE. Memory of such allocation, as well as buffer or image bound to it, should not be used. Lost allocation and the buffer/image still need to be destroyed.

    -

    If the allocation has been created without VMA_ALLOCATION_CREATE_CAN_BECOME_LOST_BIT flag, this function always returns VK_TRUE.

    +

    If the allocation has been created with VMA_ALLOCATION_CREATE_CAN_BECOME_LOST_BIT flag, this function returns VK_TRUE if it is not in lost state, so it can still be used. It then also atomically "touches" the allocation - marks it as used in current frame, so that you can be sure it won't become lost in current frame or next frameInUseCount frames.

    +

    If the allocation is in lost state, the function returns VK_FALSE. Memory of such allocation, as well as buffer or image bound to it, should not be used. Lost allocation and the buffer/image still need to be destroyed.

    +

    If the allocation has been created without VMA_ALLOCATION_CREATE_CAN_BECOME_LOST_BIT flag, this function always returns VK_TRUE.

    - +

    ◆ vmaUnmapMemory()

    @@ -3564,15 +3564,15 @@ Functions

    Unmaps memory represented by given allocation, mapped previously using vmaMapMemory().

    -

    For details, see description of vmaMapMemory().

    -

    This function doesn't automatically flush or invalidate caches. If the allocation is made from a memory types that is not HOST_COHERENT, you also need to use vmaInvalidateAllocation() / vmaFlushAllocation(), as required by Vulkan specification.

    +

    For details, see description of vmaMapMemory().

    +

    This function doesn't automatically flush or invalidate caches. If the allocation is made from a memory types that is not HOST_COHERENT, you also need to use vmaInvalidateAllocation() / vmaFlushAllocation(), as required by Vulkan specification.

    -Generated by doxygen 1.9.1 +Generated by doxygen 1.9.2
    diff --git a/docs/html/vk_amd_device_coherent_memory.html b/docs/html/vk_amd_device_coherent_memory.html index 256014b..ac8f0a7 100644 --- a/docs/html/vk_amd_device_coherent_memory.html +++ b/docs/html/vk_amd_device_coherent_memory.html @@ -2,8 +2,8 @@ - - + +Vulkan Memory Allocator: VK_AMD_device_coherent_memory @@ -29,21 +29,22 @@
    allocator
    - + +/* @license-end */ + -
    -
    -
    VK_AMD_device_coherent_memory
    +
    +
    VK_AMD_device_coherent_memory
    -

    VK_AMD_device_coherent_memory is a device extension that enables access to additional memory types with VK_MEMORY_PROPERTY_DEVICE_COHERENT_BIT_AMD and VK_MEMORY_PROPERTY_DEVICE_UNCACHED_BIT_AMD flag. It is useful mostly for allocation of buffers intended for writing "breadcrumb markers" in between passes or draw calls, which in turn are useful for debugging GPU crash/hang/TDR cases.

    -

    When the extension is available but has not been enabled, Vulkan physical device still exposes those memory types, but their usage is forbidden. VMA automatically takes care of that - it returns VK_ERROR_FEATURE_NOT_PRESENT when an attempt to allocate memory of such type is made.

    -

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

    +

    VK_AMD_device_coherent_memory is a device extension that enables access to additional memory types with VK_MEMORY_PROPERTY_DEVICE_COHERENT_BIT_AMD and VK_MEMORY_PROPERTY_DEVICE_UNCACHED_BIT_AMD flag. It is useful mostly for allocation of buffers intended for writing "breadcrumb markers" in between passes or draw calls, which in turn are useful for debugging GPU crash/hang/TDR cases.

    +

    When the extension is available but has not been enabled, Vulkan physical device still exposes those memory types, but their usage is forbidden. VMA automatically takes care of that - it returns VK_ERROR_FEATURE_NOT_PRESENT when an attempt to allocate memory of such type is made.

    +

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

    Initialization

    -

    1) Call vkEnumerateDeviceExtensionProperties for the physical device. Check if the extension is supported - if returned array of VkExtensionProperties contains "VK_AMD_device_coherent_memory".

    -

    2) Call vkGetPhysicalDeviceFeatures2 for the physical device instead of old vkGetPhysicalDeviceFeatures. Attach additional structure VkPhysicalDeviceCoherentMemoryFeaturesAMD to VkPhysicalDeviceFeatures2::pNext to be returned. Check if the device feature is really supported - check if VkPhysicalDeviceCoherentMemoryFeaturesAMD::deviceCoherentMemory is true.

    -

    3) While creating device with vkCreateDevice, enable this extension - add "VK_AMD_device_coherent_memory" to the list passed as VkDeviceCreateInfo::ppEnabledExtensionNames.

    -

    4) While creating the device, also don't set VkDeviceCreateInfo::pEnabledFeatures. Fill in VkPhysicalDeviceFeatures2 structure instead and pass it as VkDeviceCreateInfo::pNext. Enable this device feature - attach additional structure VkPhysicalDeviceCoherentMemoryFeaturesAMD to VkPhysicalDeviceFeatures2::pNext and set its member deviceCoherentMemory to VK_TRUE.

    -

    5) While creating VmaAllocator with vmaCreateAllocator() inform VMA that you have enabled this extension and feature - add VMA_ALLOCATOR_CREATE_AMD_DEVICE_COHERENT_MEMORY_BIT to VmaAllocatorCreateInfo::flags.

    +

    1) Call vkEnumerateDeviceExtensionProperties for the physical device. Check if the extension is supported - if returned array of VkExtensionProperties contains "VK_AMD_device_coherent_memory".

    +

    2) Call vkGetPhysicalDeviceFeatures2 for the physical device instead of old vkGetPhysicalDeviceFeatures. Attach additional structure VkPhysicalDeviceCoherentMemoryFeaturesAMD to VkPhysicalDeviceFeatures2::pNext to be returned. Check if the device feature is really supported - check if VkPhysicalDeviceCoherentMemoryFeaturesAMD::deviceCoherentMemory is true.

    +

    3) While creating device with vkCreateDevice, enable this extension - add "VK_AMD_device_coherent_memory" to the list passed as VkDeviceCreateInfo::ppEnabledExtensionNames.

    +

    4) While creating the device, also don't set VkDeviceCreateInfo::pEnabledFeatures. Fill in VkPhysicalDeviceFeatures2 structure instead and pass it as VkDeviceCreateInfo::pNext. Enable this device feature - attach additional structure VkPhysicalDeviceCoherentMemoryFeaturesAMD to VkPhysicalDeviceFeatures2::pNext and set its member deviceCoherentMemory to VK_TRUE.

    +

    5) While creating VmaAllocator with vmaCreateAllocator() inform VMA that you have enabled this extension and feature - add VMA_ALLOCATOR_CREATE_AMD_DEVICE_COHERENT_MEMORY_BIT to VmaAllocatorCreateInfo::flags.

    Usage

    -

    After following steps described above, you can create VMA allocations and custom pools out of the special DEVICE_COHERENT and DEVICE_UNCACHED memory types on eligible devices. There are multiple ways to do it, for example:

    +

    After following steps described above, you can create VMA allocations and custom pools out of the special DEVICE_COHERENT and DEVICE_UNCACHED memory types on eligible devices. There are multiple ways to do it, for example:

    More information

    -

    To learn more about this extension, see VK_AMD_device_coherent_memory in Vulkan specification

    -

    Example use of this extension can be found in the code of the sample and test suite accompanying this library.

    +

    To learn more about this extension, see VK_AMD_device_coherent_memory in Vulkan specification

    +

    Example use of this extension can be found in the code of the sample and test suite accompanying this library.

    -Generated by doxygen 1.9.1 +Generated by doxygen 1.9.2
    diff --git a/docs/html/vk_khr_dedicated_allocation.html b/docs/html/vk_khr_dedicated_allocation.html index f91be7c..0bee2e2 100644 --- a/docs/html/vk_khr_dedicated_allocation.html +++ b/docs/html/vk_khr_dedicated_allocation.html @@ -2,8 +2,8 @@ - - + + Vulkan Memory Allocator: VK_KHR_dedicated_allocation @@ -29,21 +29,22 @@
    - + +/* @license-end */ +
    -
    -
    -
    VK_KHR_dedicated_allocation
    +
    +
    VK_KHR_dedicated_allocation
    -

    VK_KHR_dedicated_allocation is a Vulkan extension which can be used to improve performance on some GPUs. It augments Vulkan API with possibility to query driver whether it prefers particular buffer or image to have its own, dedicated allocation (separate VkDeviceMemory block) for better efficiency - to be able to do some internal optimizations.

    -

    The extension is supported by this library. It will be used automatically when enabled. To enable it:

    -

    1 . When creating Vulkan device, check if following 2 device extensions are supported (call vkEnumerateDeviceExtensionProperties()). If yes, enable them (fill VkDeviceCreateInfo::ppEnabledExtensionNames).

    +

    VK_KHR_dedicated_allocation is a Vulkan extension which can be used to improve performance on some GPUs. It augments Vulkan API with possibility to query driver whether it prefers particular buffer or image to have its own, dedicated allocation (separate VkDeviceMemory block) for better efficiency - to be able to do some internal optimizations.

    +

    The extension is supported by this library. It will be used automatically when enabled. To enable it:

    +

    1 . When creating Vulkan device, check if following 2 device extensions are supported (call vkEnumerateDeviceExtensionProperties()). If yes, enable them (fill VkDeviceCreateInfo::ppEnabledExtensionNames).

    • VK_KHR_get_memory_requirements2
    • VK_KHR_dedicated_allocation
    -

    If you enabled these extensions:

    -

    2 . Use VMA_ALLOCATOR_CREATE_KHR_DEDICATED_ALLOCATION_BIT flag when creating your VmaAllocator`to inform the library that you enabled required extensions and you want the library to use them.

    -
    allocatorInfo.flags |= VMA_ALLOCATOR_CREATE_KHR_DEDICATED_ALLOCATION_BIT;
    +

    If you enabled these extensions:

    +

    2 . Use VMA_ALLOCATOR_CREATE_KHR_DEDICATED_ALLOCATION_BIT flag when creating your VmaAllocator`to inform the library that you enabled required extensions and you want the library to use them.

    +
    allocatorInfo.flags |= VMA_ALLOCATOR_CREATE_KHR_DEDICATED_ALLOCATION_BIT;
    -
    vmaCreateAllocator(&allocatorInfo, &allocator);
    +
    vmaCreateAllocator(&allocatorInfo, &allocator);
    vmaCreateAllocator
    VkResult vmaCreateAllocator(const VmaAllocatorCreateInfo *pCreateInfo, VmaAllocator *pAllocator)
    Creates Allocator object.
    -
    VMA_ALLOCATOR_CREATE_KHR_DEDICATED_ALLOCATION_BIT
    @ VMA_ALLOCATOR_CREATE_KHR_DEDICATED_ALLOCATION_BIT
    Enables usage of VK_KHR_dedicated_allocation extension.
    Definition: vk_mem_alloc.h:358
    -

    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.
+
    VMA_ALLOCATOR_CREATE_KHR_DEDICATED_ALLOCATION_BIT
    @ VMA_ALLOCATOR_CREATE_KHR_DEDICATED_ALLOCATION_BIT
    Enables usage of VK_KHR_dedicated_allocation extension.
    Definition: vk_mem_alloc.h:354
    
+

    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.

    -

    To learn more about this extension, see:

    +

    To learn more about this extension, see:

    -Generated by doxygen 1.9.1 +Generated by doxygen 1.9.2
    diff --git a/include/vk_mem_alloc.h b/include/vk_mem_alloc.h index 2d991c3..5a84798 100644 --- a/include/vk_mem_alloc.h +++ b/include/vk_mem_alloc.h @@ -2228,7 +2228,6 @@ the containers. #define VMA_USE_STL_SHARED_MUTEX 1 // Visual studio defines __cplusplus properly only when passed additional parameter: /Zc:__cplusplus // Otherwise it is always 199711L, despite shared_mutex works since Visual Studio 2015 Update 2. - // See: https://blogs.msdn.microsoft.com/vcblog/2018/04/09/msvc-now-correctly-reports-__cplusplus/ #elif defined(_MSC_FULL_VER) && _MSC_FULL_VER >= 190023918 && __cplusplus == 199711L && _MSVC_LANG >= 201703L #define VMA_USE_STL_SHARED_MUTEX 1 #else @@ -18712,8 +18711,8 @@ The advantage of buddy allocation algorithm over default algorithm is faster allocation and deallocation, as well as smaller external fragmentation. The disadvantage is more wasted space (internal fragmentation). -For more information, please read ["Buddy memory allocation" on Wikipedia](https://en.wikipedia.org/wiki/Buddy_memory_allocation) -or other sources that describe this concept in general. +For more information, please search the Internet for "Buddy memory allocation" - +sources that describe this concept in general. To use buddy allocation algorithm with a custom pool, add flag #VMA_POOL_CREATE_BUDDY_ALGORITHM_BIT to VmaPoolCreateInfo::flags while creating