From 4039e45a196c100adc49e0c66085a5c7b86420b0 Mon Sep 17 00:00:00 2001 From: Adam Sawicki Date: Sat, 26 Feb 2022 13:26:20 +0100 Subject: [PATCH] Added documentation chapter "Versioning and compatibility" Many improvements in documentation and README. --- README.md | 20 +++++------ docs/html/allocation_annotation.html | 16 ++++----- docs/html/choosing_memory_type.html | 20 +++++------ docs/html/custom_memory_pools.html | 19 +++++----- docs/html/defragmentation.html | 17 ++++----- docs/html/general_considerations.html | 10 ++++++ docs/html/group__group__alloc.html | 12 +++---- docs/html/index.html | 1 + docs/html/memory_mapping.html | 16 ++++----- docs/html/quick_start.html | 24 ++++++------- docs/html/resource_aliasing.html | 4 +-- docs/html/struct_vma_budget.html | 2 +- docs/html/usage_patterns.html | 27 ++++++++------- docs/html/virtual_allocator.html | 20 +++++------ docs/html/vk__mem__alloc_8h.html | 4 +-- docs/html/vk_khr_dedicated_allocation.html | 2 +- include/vk_mem_alloc.h | 40 +++++++++++++++++++--- 17 files changed, 150 insertions(+), 104 deletions(-) diff --git a/README.md b/README.md index cd7a619..d5cb93b 100644 --- a/README.md +++ b/README.md @@ -39,9 +39,9 @@ This library can help game developers to manage memory allocations and resource Additional features: - Well-documented - description of all functions and structures provided, along with chapters that contain general description and example code. -- Thread-safety: Library is designed to be used in multithreaded code. Access to a single device memory block referred by different buffers and textures (binding, mapping) is synchronized internally. -- Configuration: Fill optional members of CreateInfo structure to provide custom CPU memory allocator, pointers to Vulkan functions and other parameters. -- Customization: Predefine appropriate macros to provide your own implementation of all external facilities used by the library, from assert, mutex, and atomic, to vector and linked list. +- Thread-safety: Library is designed to be used in multithreaded code. Access to a single device memory block referred by different buffers and textures (binding, mapping) is synchronized internally. Memory mapping is reference-counted. +- Configuration: Fill optional members of `VmaAllocatorCreateInfo` structure to provide custom CPU memory allocator, pointers to Vulkan functions and other parameters. +- Customization: Predefine appropriate macros to provide your own implementation of all external facilities used by the library like assert, mutex, atomic. - Support for memory mapping, reference-counted internally. Support for persistently mapped memory: Just allocate with appropriate flag and you get access to mapped pointer. - Support for non-coherent memory. Functions that flush/invalidate memory. `nonCoherentAtomSize` is respected automatically. - Support for resource aliasing (overlap). @@ -50,10 +50,11 @@ Additional features: - Linear allocator: Create a pool with linear algorithm and use it for much faster allocations and deallocations in free-at-once, stack, double stack, or ring buffer fashion. - Support for Vulkan 1.0, 1.1, 1.2, 1.3. - Support for extensions (and equivalent functionality included in new Vulkan versions): - - VK_EXT_memory_budget: Used internally if available to query for current usage and budget. If not available, it falls back to an estimation based on memory heap sizes. - VK_KHR_dedicated_allocation: Just enable it and it will be used automatically by the library. + - VK_KHR_buffer_device_address: Flag `VK_MEMORY_ALLOCATE_DEVICE_ADDRESS_BIT_KHR` is automatically added to memory allocations where needed. + - VK_EXT_memory_budget: Used internally if available to query for current usage and budget. If not available, it falls back to an estimation based on memory heap sizes. + - VK_EXT_memory_priority: Set `priority` of allocations or custom pools and it will be set automatically using this extension. - VK_AMD_device_coherent_memory - - VK_KHR_buffer_device_address - Defragmentation of GPU and CPU memory: Let the library move data around to free some memory blocks and make your allocations better compacted. - Statistics: Obtain detailed statistics about the amount of memory used, unused, number of allocated blocks, number of allocations etc. - globally, per memory heap, and per memory type. - Debug annotations: Associate string with name or opaque pointer to your own data with every allocation. @@ -65,7 +66,7 @@ Additional features: # Prequisites -- Self-contained C++ library in single header file. No external dependencies other than standard C and C++ library and of course Vulkan. Some features of C++14 used. STL containers are not used. +- Self-contained C++ library in single header file. No external dependencies other than standard C and C++ library and of course Vulkan. Some features of C++14 used. STL containers or C++ exceptions are not used. - Public interface in C, in same convention as Vulkan API. Implementation in C++. - Error handling implemented by returning `VkResult` error codes - same way as in Vulkan. - Interface documented using Doxygen-style comments. @@ -94,7 +95,7 @@ With this one function call: 2. `VkDeviceMemory` block is allocated if needed. 3. An unused region of the memory block is bound to this buffer. -`VmaAllocation` is an object that represents memory assigned to this buffer. It can be queried for parameters like Vulkan memory handle and offset. +`VmaAllocation` is an object that represents memory assigned to this buffer. It can be queried for parameters like `VkDeviceMemory` handle and offset. # How to build @@ -115,9 +116,8 @@ The following targets are available | ------------- | ------------- | ------------- | ------------- | | VmaSample | VMA sample application | `VMA_BUILD_SAMPLE` | `OFF` | | VmaBuildSampleShaders | Shaders for VmaSample | `VMA_BUILD_SAMPLE_SHADERS` | `OFF` | -| VmaReplay | Replay tool for VMA .csv trace files | `VMA_BUILD_REPLAY` | `OFF` | -Please note that while VulkanMemoryAllocator library is supported on other platforms besides Windows, VmaSample and VmaReplay are not. +Please note that while VulkanMemoryAllocator library is supported on other platforms besides Windows, VmaSample is not. These CMake options are available @@ -134,7 +134,7 @@ These CMake options are available # Binaries -The release comes with precompiled binary executables for "VulkanSample" application which contains test suite and "VmaReplay" tool. They are compiled using Visual Studio 2019, so they require appropriate libraries to work, including "MSVCP140.dll", "VCRUNTIME140.dll", "VCRUNTIME140_1.dll". If their launch fails with error message telling about those files missing, please download and install [Microsoft Visual C++ Redistributable for Visual Studio 2015, 2017 and 2019](https://support.microsoft.com/en-us/help/2977003/the-latest-supported-visual-c-downloads), "x64" version. +The release comes with precompiled binary executable for "VulkanSample" application which contains test suite. It is compiled using Visual Studio 2019, so it requires appropriate libraries to work, including "MSVCP140.dll", "VCRUNTIME140.dll", "VCRUNTIME140_1.dll". If the launch fails with error message telling about those files missing, please download and install [Microsoft Visual C++ Redistributable for Visual Studio 2015, 2017 and 2019](https://support.microsoft.com/en-us/help/2977003/the-latest-supported-visual-c-downloads), "x64" version. # Read more diff --git a/docs/html/allocation_annotation.html b/docs/html/allocation_annotation.html index 9af143b..7af9a6c 100644 --- a/docs/html/allocation_annotation.html +++ b/docs/html/allocation_annotation.html @@ -84,18 +84,18 @@ Allocation user data
VmaAllocation allocation;
vmaCreateBuffer(allocator, &bufCreateInfo, &allocCreateInfo, &buffer, &allocation, nullptr);
vmaCreateBuffer
VkResult vmaCreateBuffer(VmaAllocator allocator, const VkBufferCreateInfo *pBufferCreateInfo, const VmaAllocationCreateInfo *pAllocationCreateInfo, VkBuffer *pBuffer, VmaAllocation *pAllocation, VmaAllocationInfo *pAllocationInfo)
-
VMA_MEMORY_USAGE_AUTO
@ VMA_MEMORY_USAGE_AUTO
Definition: vk_mem_alloc.h:488
-
VmaAllocationCreateInfo
Definition: vk_mem_alloc.h:1211
-
VmaAllocationCreateInfo::pUserData
void * pUserData
Custom general-purpose pointer that will be stored in VmaAllocation, can be read as VmaAllocationInfo...
Definition: vk_mem_alloc.h:1250
-
VmaAllocationCreateInfo::usage
VmaMemoryUsage usage
Intended usage of memory.
Definition: vk_mem_alloc.h:1219
+
VMA_MEMORY_USAGE_AUTO
@ VMA_MEMORY_USAGE_AUTO
Definition: vk_mem_alloc.h:489
+
VmaAllocationCreateInfo
Definition: vk_mem_alloc.h:1212
+
VmaAllocationCreateInfo::pUserData
void * pUserData
Custom general-purpose pointer that will be stored in VmaAllocation, can be read as VmaAllocationInfo...
Definition: vk_mem_alloc.h:1251
+
VmaAllocationCreateInfo::usage
VmaMemoryUsage usage
Intended usage of memory.
Definition: vk_mem_alloc.h:1220
VmaAllocation
Represents single memory allocation.

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

VmaAllocationInfo allocInfo;
vmaGetAllocationInfo(allocator, allocation, &allocInfo);
MyBufferMetadata* pMetadata = (MyBufferMetadata*)allocInfo.pUserData;
vmaGetAllocationInfo
void vmaGetAllocationInfo(VmaAllocator allocator, VmaAllocation allocation, VmaAllocationInfo *pAllocationInfo)
Returns current information about specified allocation.
-
VmaAllocationInfo
Parameters of VmaAllocation objects, that can be retrieved using function vmaGetAllocationInfo().
Definition: vk_mem_alloc.h:1326
-
VmaAllocationInfo::pUserData
void * pUserData
Custom general-purpose pointer that was passed as VmaAllocationCreateInfo::pUserData or set using vma...
Definition: vk_mem_alloc.h:1373
+
VmaAllocationInfo
Parameters of VmaAllocation objects, that can be retrieved using function vmaGetAllocationInfo().
Definition: vk_mem_alloc.h:1327
+
VmaAllocationInfo::pUserData
void * pUserData
Custom general-purpose pointer that was passed as VmaAllocationCreateInfo::pUserData or set using vma...
Definition: vk_mem_alloc.h:1374

It can also be changed using function vmaSetAllocationUserData().

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

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

VmaAllocation allocation;
vmaCreateImage(allocator, &imageInfo, &allocCreateInfo, &image, &allocation, nullptr);
vmaCreateImage
VkResult vmaCreateImage(VmaAllocator allocator, const VkImageCreateInfo *pImageCreateInfo, const VmaAllocationCreateInfo *pAllocationCreateInfo, VkImage *pImage, VmaAllocation *pAllocation, VmaAllocationInfo *pAllocationInfo)
Function similar to vmaCreateBuffer().
-
VMA_ALLOCATION_CREATE_USER_DATA_COPY_STRING_BIT
@ VMA_ALLOCATION_CREATE_USER_DATA_COPY_STRING_BIT
Definition: vk_mem_alloc.h:556
-
VmaAllocationCreateInfo::flags
VmaAllocationCreateFlags flags
Use VmaAllocationCreateFlagBits enum.
Definition: vk_mem_alloc.h:1213
+
VMA_ALLOCATION_CREATE_USER_DATA_COPY_STRING_BIT
@ VMA_ALLOCATION_CREATE_USER_DATA_COPY_STRING_BIT
Definition: vk_mem_alloc.h:557
+
VmaAllocationCreateInfo::flags
VmaAllocationCreateFlags flags
Use VmaAllocationCreateFlagBits enum.
Definition: vk_mem_alloc.h:1214

The value of pUserData pointer of the allocation will be different than the one you passed when setting allocation's name - pointing to a buffer managed internally that holds copy of the string.

VmaAllocationInfo allocInfo;
vmaGetAllocationInfo(allocator, allocation, &allocInfo);
diff --git a/docs/html/choosing_memory_type.html b/docs/html/choosing_memory_type.html index bf51bf1..ae1a29c 100644 --- a/docs/html/choosing_memory_type.html +++ b/docs/html/choosing_memory_type.html @@ -94,9 +94,9 @@ Usage
VmaAllocation allocation;
vmaCreateBuffer(allocator, &bufferInfo, &allocInfo, &buffer, &allocation, nullptr);
vmaCreateBuffer
VkResult vmaCreateBuffer(VmaAllocator allocator, const VkBufferCreateInfo *pBufferCreateInfo, const VmaAllocationCreateInfo *pAllocationCreateInfo, VkBuffer *pBuffer, VmaAllocation *pAllocation, VmaAllocationInfo *pAllocationInfo)
-
VMA_MEMORY_USAGE_AUTO
@ VMA_MEMORY_USAGE_AUTO
Definition: vk_mem_alloc.h:488
-
VmaAllocationCreateInfo
Definition: vk_mem_alloc.h:1211
-
VmaAllocationCreateInfo::usage
VmaMemoryUsage usage
Intended usage of memory.
Definition: vk_mem_alloc.h:1219
+
VMA_MEMORY_USAGE_AUTO
@ VMA_MEMORY_USAGE_AUTO
Definition: vk_mem_alloc.h:489
+
VmaAllocationCreateInfo
Definition: vk_mem_alloc.h:1212
+
VmaAllocationCreateInfo::usage
VmaMemoryUsage usage
Intended usage of memory.
Definition: vk_mem_alloc.h:1220
VmaAllocation
Represents single memory allocation.

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

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

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

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

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

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

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

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

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

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

Custom memory pools

If you allocate from custom memory pool, all the ways of specifying memory requirements described above are not applicable and the aforementioned members of VmaAllocationCreateInfo structure are ignored. Memory type is selected explicitly when creating the pool and then used to make all the allocations from that pool. For further details, see Custom memory pools.

diff --git a/docs/html/custom_memory_pools.html b/docs/html/custom_memory_pools.html index 5a7f550..10feea8 100644 --- a/docs/html/custom_memory_pools.html +++ b/docs/html/custom_memory_pools.html @@ -109,13 +109,13 @@ $(function() {
vmaCreateBuffer(allocator, &bufCreateInfo, &allocCreateInfo, &buf, &alloc, &allocInfo);
vmaCreatePool
VkResult vmaCreatePool(VmaAllocator allocator, const VmaPoolCreateInfo *pCreateInfo, VmaPool *pPool)
Allocates Vulkan device memory and creates VmaPool object.
vmaCreateBuffer
VkResult vmaCreateBuffer(VmaAllocator allocator, const VkBufferCreateInfo *pBufferCreateInfo, const VmaAllocationCreateInfo *pAllocationCreateInfo, VkBuffer *pBuffer, VmaAllocation *pAllocation, VmaAllocationInfo *pAllocationInfo)
-
VmaAllocationCreateInfo
Definition: vk_mem_alloc.h:1211
-
VmaAllocationCreateInfo::pool
VmaPool pool
Pool that this allocation should be created in.
Definition: vk_mem_alloc.h:1243
+
VmaAllocationCreateInfo
Definition: vk_mem_alloc.h:1212
+
VmaAllocationCreateInfo::pool
VmaPool pool
Pool that this allocation should be created in.
Definition: vk_mem_alloc.h:1244
VmaAllocation
Represents single memory allocation.
-
VmaAllocationInfo
Parameters of VmaAllocation objects, that can be retrieved using function vmaGetAllocationInfo().
Definition: vk_mem_alloc.h:1326
-
VmaPoolCreateInfo
Describes parameter of created VmaPool.
Definition: vk_mem_alloc.h:1262
-
VmaPoolCreateInfo::memoryTypeIndex
uint32_t memoryTypeIndex
Vulkan memory type index to allocate this pool from.
Definition: vk_mem_alloc.h:1265
-
VmaPoolCreateInfo::maxBlockCount
size_t maxBlockCount
Maximum number of blocks that can be allocated in this pool. Optional.
Definition: vk_mem_alloc.h:1291
+
VmaAllocationInfo
Parameters of VmaAllocation objects, that can be retrieved using function vmaGetAllocationInfo().
Definition: vk_mem_alloc.h:1327
+
VmaPoolCreateInfo
Describes parameter of created VmaPool.
Definition: vk_mem_alloc.h:1263
+
VmaPoolCreateInfo::memoryTypeIndex
uint32_t memoryTypeIndex
Vulkan memory type index to allocate this pool from.
Definition: vk_mem_alloc.h:1266
+
VmaPoolCreateInfo::maxBlockCount
size_t maxBlockCount
Maximum number of blocks that can be allocated in this pool. Optional.
Definition: vk_mem_alloc.h:1292
VmaPool
Represents custom memory pool.

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

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

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

+

+Versioning and compatibility

+

The library uses Semantic Versioning, which means version numbers follow convention: Major.Minor.Patch (e.g. 2.3.0), where:

+ +

All changes between official releases are documented in file "CHANGELOG.md".

+
Warning
Backward compatiblity is considered on the level of C++ source code, not binary linkage. Adding new members to existing structures is treated as backward compatible if initializing the new members to binary zero results in the old behavior. You should always fully initialize all library structures to zeros and not rely on their exact binary size.

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.

diff --git a/docs/html/group__group__alloc.html b/docs/html/group__group__alloc.html index 594d1b2..eb735f8 100644 --- a/docs/html/group__group__alloc.html +++ b/docs/html/group__group__alloc.html @@ -128,7 +128,7 @@ Typedefs typedef VkFlags VmaDefragmentationFlags   typedef enum VmaDefragmentationMoveOperation VmaDefragmentationMoveOperation - Operation performed on single defragmentation move. More...
+ Operation performed on single defragmentation move. See structure VmaDefragmentationMove. More...
  typedef struct VmaAllocationCreateInfo VmaAllocationCreateInfo   @@ -223,7 +223,7 @@ Enumerations , VMA_DEFRAGMENTATION_MOVE_OPERATION_IGNORE = 1 , VMA_DEFRAGMENTATION_MOVE_OPERATION_DESTROY = 2 } - Operation performed on single defragmentation move. More...
+ Operation performed on single defragmentation move. See structure VmaDefragmentationMove. More...
 

@@ -476,7 +476,7 @@ Functions

-

Operation performed on single defragmentation move.

+

Operation performed on single defragmentation move. See structure VmaDefragmentationMove.

@@ -626,14 +626,14 @@ Functions
  • If you use other value of VmaMemoryUsage, this flag is ignored and mapping is always possible in memory types that are HOST_VISIBLE. This includes allocations created in Custom memory pools.

    • Declares that mapped memory will only be written sequentially, e.g. using memcpy() or a loop writing number-by-number, never read or accessed randomly, so a memory type can be selected that is uncached and write-combined.

    -
    Warning
    Violating this declaration may work correctly, but will likely be very slow. Watch out for implicit reads introduces by doing e.g. pMappedData[i] += x; Better prepare your data in a local variable and memcpy() it to the mapped pointer all at once.
    +
    Warning
    Violating this declaration may work correctly, but will likely be very slow. Watch out for implicit reads introduced by doing e.g. pMappedData[i] += x; Better prepare your data in a local variable and memcpy() it to the mapped pointer all at once.
    VMA_ALLOCATION_CREATE_HOST_ACCESS_RANDOM_BIT 

    Requests possibility to map the allocation (using vmaMapMemory() or VMA_ALLOCATION_CREATE_MAPPED_BIT).

    -

    Declares that mapped memory can be read, written, and accessed in random order, so a HOST_CACHED memory type is preferred.

    +

    Declares that mapped memory can be read, written, and accessed in random order, so a HOST_CACHED memory type is required.

    VMA_ALLOCATION_CREATE_HOST_ACCESS_ALLOW_TRANSFER_INSTEAD_BIT 

    Together with VMA_ALLOCATION_CREATE_HOST_ACCESS_SEQUENTIAL_WRITE_BIT or VMA_ALLOCATION_CREATE_HOST_ACCESS_RANDOM_BIT, it says that despite request for host access, a not-HOST_VISIBLE memory type can be selected if it may improve performance.

    By using this flag, you declare that you will check if the allocation ended up in a HOST_VISIBLE memory type (e.g. using vmaGetAllocationMemoryProperties()) and if not, you will create some "staging" buffer and issue an explicit transfer to write/read your data. To prepare for this possibility, don't forget to add appropriate flags like VK_BUFFER_USAGE_TRANSFER_DST_BIT, VK_BUFFER_USAGE_TRANSFER_SRC_BIT to the parameters of created buffer or image.

    @@ -693,7 +693,7 @@ Functions
    -

    Operation performed on single defragmentation move.

    +

    Operation performed on single defragmentation move. See structure VmaDefragmentationMove.

    diff --git a/docs/html/index.html b/docs/html/index.html index a02c299..10391cc 100644 --- a/docs/html/index.html +++ b/docs/html/index.html @@ -151,6 +151,7 @@ Table of contents
  • VK_AMD_device_coherent_memory
  • General considerations
    • Thread safety
      • +
    • Versioning and compatibility
    • Validation layer warnings
    • Allocation algorithm
    • Features not supported
      • diff --git a/docs/html/memory_mapping.html b/docs/html/memory_mapping.html index 69b3ff0..fb646a7 100644 --- a/docs/html/memory_mapping.html +++ b/docs/html/memory_mapping.html @@ -116,15 +116,15 @@ Persistently mapped memory
      // Buffer is already mapped. You can access its memory.
      memcpy(allocInfo.pMappedData, &constantBufferData, sizeof(constantBufferData));
      vmaCreateBuffer
      VkResult vmaCreateBuffer(VmaAllocator allocator, const VkBufferCreateInfo *pBufferCreateInfo, const VmaAllocationCreateInfo *pAllocationCreateInfo, VkBuffer *pBuffer, VmaAllocation *pAllocation, VmaAllocationInfo *pAllocationInfo)
      -
      VMA_MEMORY_USAGE_AUTO
      @ VMA_MEMORY_USAGE_AUTO
      Definition: vk_mem_alloc.h:488
      -
      VMA_ALLOCATION_CREATE_MAPPED_BIT
      @ VMA_ALLOCATION_CREATE_MAPPED_BIT
      Set this flag to use a memory that will be persistently mapped and retrieve pointer to it.
      Definition: vk_mem_alloc.h:546
      -
      VMA_ALLOCATION_CREATE_HOST_ACCESS_SEQUENTIAL_WRITE_BIT
      @ VMA_ALLOCATION_CREATE_HOST_ACCESS_SEQUENTIAL_WRITE_BIT
      Definition: vk_mem_alloc.h:593
      -
      VmaAllocationCreateInfo
      Definition: vk_mem_alloc.h:1211
      -
      VmaAllocationCreateInfo::usage
      VmaMemoryUsage usage
      Intended usage of memory.
      Definition: vk_mem_alloc.h:1219
      -
      VmaAllocationCreateInfo::flags
      VmaAllocationCreateFlags flags
      Use VmaAllocationCreateFlagBits enum.
      Definition: vk_mem_alloc.h:1213
      +
      VMA_MEMORY_USAGE_AUTO
      @ VMA_MEMORY_USAGE_AUTO
      Definition: vk_mem_alloc.h:489
      +
      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:547
      +
      VMA_ALLOCATION_CREATE_HOST_ACCESS_SEQUENTIAL_WRITE_BIT
      @ VMA_ALLOCATION_CREATE_HOST_ACCESS_SEQUENTIAL_WRITE_BIT
      Definition: vk_mem_alloc.h:594
      +
      VmaAllocationCreateInfo
      Definition: vk_mem_alloc.h:1212
      +
      VmaAllocationCreateInfo::usage
      VmaMemoryUsage usage
      Intended usage of memory.
      Definition: vk_mem_alloc.h:1220
      +
      VmaAllocationCreateInfo::flags
      VmaAllocationCreateFlags flags
      Use VmaAllocationCreateFlagBits enum.
      Definition: vk_mem_alloc.h:1214
      VmaAllocation
      Represents single memory allocation.
      -
      VmaAllocationInfo
      Parameters of VmaAllocation objects, that can be retrieved using function vmaGetAllocationInfo().
      Definition: vk_mem_alloc.h:1326
      -
      VmaAllocationInfo::pMappedData
      void * pMappedData
      Pointer to the beginning of this allocation as mapped data.
      Definition: vk_mem_alloc.h:1368
      +
      VmaAllocationInfo
      Parameters of VmaAllocation objects, that can be retrieved using function vmaGetAllocationInfo().
      Definition: vk_mem_alloc.h:1327
      +
      VmaAllocationInfo::pMappedData
      void * pMappedData
      Pointer to the beginning of this allocation as mapped data.
      Definition: vk_mem_alloc.h:1369
      Note
      VMA_ALLOCATION_CREATE_MAPPED_BIT by itself doesn't guarantee that the allocation will end up in a mappable memory type. For this, you need to also specify VMA_ALLOCATION_CREATE_HOST_ACCESS_SEQUENTIAL_WRITE_BIT or VMA_ALLOCATION_CREATE_HOST_ACCESS_RANDOM_BIT. VMA_ALLOCATION_CREATE_MAPPED_BIT only guarantees that if the memory is HOST_VISIBLE, the allocation will be mapped on creation. For an example of how to make use of this fact, see section Advanced data uploading.

      Cache flush and invalidate

      diff --git a/docs/html/quick_start.html b/docs/html/quick_start.html index 14bba29..db7808b 100644 --- a/docs/html/quick_start.html +++ b/docs/html/quick_start.html @@ -124,16 +124,16 @@ Initialization
      VmaAllocator allocator;
      vmaCreateAllocator(&allocatorCreateInfo, &allocator);
      vmaCreateAllocator
      VkResult vmaCreateAllocator(const VmaAllocatorCreateInfo *pCreateInfo, VmaAllocator *pAllocator)
      Creates VmaAllocator object.
      -
      VmaAllocatorCreateInfo
      Description of a Allocator to be created.
      Definition: vk_mem_alloc.h:994
      -
      VmaAllocatorCreateInfo::physicalDevice
      VkPhysicalDevice physicalDevice
      Vulkan physical device.
      Definition: vk_mem_alloc.h:999
      -
      VmaAllocatorCreateInfo::pVulkanFunctions
      const VmaVulkanFunctions * pVulkanFunctions
      Pointers to Vulkan functions. Can be null.
      Definition: vk_mem_alloc.h:1042
      -
      VmaAllocatorCreateInfo::instance
      VkInstance instance
      Handle to Vulkan instance object.
      Definition: vk_mem_alloc.h:1047
      -
      VmaAllocatorCreateInfo::device
      VkDevice device
      Vulkan device.
      Definition: vk_mem_alloc.h:1002
      -
      VmaAllocatorCreateInfo::vulkanApiVersion
      uint32_t vulkanApiVersion
      Optional. The highest version of Vulkan that the application is designed to use.
      Definition: vk_mem_alloc.h:1056
      +
      VmaAllocatorCreateInfo
      Description of a Allocator to be created.
      Definition: vk_mem_alloc.h:995
      +
      VmaAllocatorCreateInfo::physicalDevice
      VkPhysicalDevice physicalDevice
      Vulkan physical device.
      Definition: vk_mem_alloc.h:1000
      +
      VmaAllocatorCreateInfo::pVulkanFunctions
      const VmaVulkanFunctions * pVulkanFunctions
      Pointers to Vulkan functions. Can be null.
      Definition: vk_mem_alloc.h:1043
      +
      VmaAllocatorCreateInfo::instance
      VkInstance instance
      Handle to Vulkan instance object.
      Definition: vk_mem_alloc.h:1048
      +
      VmaAllocatorCreateInfo::device
      VkDevice device
      Vulkan device.
      Definition: vk_mem_alloc.h:1003
      +
      VmaAllocatorCreateInfo::vulkanApiVersion
      uint32_t vulkanApiVersion
      Optional. The highest version of Vulkan that the application is designed to use.
      Definition: vk_mem_alloc.h:1057
      VmaAllocator
      Represents main object of this library initialized.
      -
      VmaVulkanFunctions
      Pointers to some Vulkan functions - a subset used by the library.
      Definition: vk_mem_alloc.h:947
      -
      VmaVulkanFunctions::vkGetInstanceProcAddr
      PFN_vkGetInstanceProcAddr vkGetInstanceProcAddr
      Required when using VMA_DYNAMIC_VULKAN_FUNCTIONS.
      Definition: vk_mem_alloc.h:949
      -
      VmaVulkanFunctions::vkGetDeviceProcAddr
      PFN_vkGetDeviceProcAddr vkGetDeviceProcAddr
      Required when using VMA_DYNAMIC_VULKAN_FUNCTIONS.
      Definition: vk_mem_alloc.h:951
      +
      VmaVulkanFunctions
      Pointers to some Vulkan functions - a subset used by the library.
      Definition: vk_mem_alloc.h:948
      +
      VmaVulkanFunctions::vkGetInstanceProcAddr
      PFN_vkGetInstanceProcAddr vkGetInstanceProcAddr
      Required when using VMA_DYNAMIC_VULKAN_FUNCTIONS.
      Definition: vk_mem_alloc.h:950
      +
      VmaVulkanFunctions::vkGetDeviceProcAddr
      PFN_vkGetDeviceProcAddr vkGetDeviceProcAddr
      Required when using VMA_DYNAMIC_VULKAN_FUNCTIONS.
      Definition: vk_mem_alloc.h:952

      Resource allocation

      When you want to create a buffer or image:

      @@ -153,9 +153,9 @@ Resource allocation
      VmaAllocation allocation;
      vmaCreateBuffer(allocator, &bufferInfo, &allocInfo, &buffer, &allocation, nullptr);
      vmaCreateBuffer
      VkResult vmaCreateBuffer(VmaAllocator allocator, const VkBufferCreateInfo *pBufferCreateInfo, const VmaAllocationCreateInfo *pAllocationCreateInfo, VkBuffer *pBuffer, VmaAllocation *pAllocation, VmaAllocationInfo *pAllocationInfo)
      -
      VMA_MEMORY_USAGE_AUTO
      @ VMA_MEMORY_USAGE_AUTO
      Definition: vk_mem_alloc.h:488
      -
      VmaAllocationCreateInfo
      Definition: vk_mem_alloc.h:1211
      -
      VmaAllocationCreateInfo::usage
      VmaMemoryUsage usage
      Intended usage of memory.
      Definition: vk_mem_alloc.h:1219
      +
      VMA_MEMORY_USAGE_AUTO
      @ VMA_MEMORY_USAGE_AUTO
      Definition: vk_mem_alloc.h:489
      +
      VmaAllocationCreateInfo
      Definition: vk_mem_alloc.h:1212
      +
      VmaAllocationCreateInfo::usage
      VmaMemoryUsage usage
      Intended usage of memory.
      Definition: vk_mem_alloc.h:1220
      VmaAllocation
      Represents single memory allocation.

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

      vmaDestroyBuffer(allocator, buffer, allocation);
      diff --git a/docs/html/resource_aliasing.html b/docs/html/resource_aliasing.html index 1a29aa3..11d2e1d 100644 --- a/docs/html/resource_aliasing.html +++ b/docs/html/resource_aliasing.html @@ -140,8 +140,8 @@ $(function() {
      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(),...
      vmaAllocateMemory
      VkResult vmaAllocateMemory(VmaAllocator allocator, const VkMemoryRequirements *pVkMemoryRequirements, const VmaAllocationCreateInfo *pCreateInfo, VmaAllocation *pAllocation, VmaAllocationInfo *pAllocationInfo)
      General purpose memory allocation.
      -
      VmaAllocationCreateInfo
      Definition: vk_mem_alloc.h:1211
      -
      VmaAllocationCreateInfo::preferredFlags
      VkMemoryPropertyFlags preferredFlags
      Flags that preferably should be set in a memory type chosen for an allocation.
      Definition: vk_mem_alloc.h:1229
      +
      VmaAllocationCreateInfo
      Definition: vk_mem_alloc.h:1212
      +
      VmaAllocationCreateInfo::preferredFlags
      VkMemoryPropertyFlags preferredFlags
      Flags that preferably should be set in a memory type chosen for an allocation.
      Definition: vk_mem_alloc.h:1230
      VmaAllocation
      Represents single memory allocation.

      Remember that using resources that alias in memory requires proper synchronization. You need to issue a memory barrier to make sure commands that use img1 and img2 don't overlap on GPU timeline. You also need to treat a resource after aliasing as uninitialized - containing garbage data. For example, if you use img1 and then want to use img2, you need to issue an image memory barrier for img2 with oldLayout = VK_IMAGE_LAYOUT_UNDEFINED.

      Additional considerations:

      diff --git a/docs/html/struct_vma_budget.html b/docs/html/struct_vma_budget.html index b24a595..49f8bdf 100644 --- a/docs/html/struct_vma_budget.html +++ b/docs/html/struct_vma_budget.html @@ -102,7 +102,7 @@ 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.

      +

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

      diff --git a/docs/html/usage_patterns.html b/docs/html/usage_patterns.html index 8cf973f..d94295c 100644 --- a/docs/html/usage_patterns.html +++ b/docs/html/usage_patterns.html @@ -91,18 +91,20 @@ GPU-only resource
      VmaAllocationCreateInfo allocCreateInfo = {};
      allocCreateInfo.usage = VMA_MEMORY_USAGE_AUTO;
      allocCreateInfo.flags = VMA_ALLOCATION_CREATE_DEDICATED_MEMORY_BIT;
      +
      allocCreateInfo.priority = 1.0f;
      VkImage img;
      VmaAllocation alloc;
      vmaCreateImage(allocator, &imgCreateInfo, &allocCreateInfo, &img, &alloc, nullptr);
      vmaCreateImage
      VkResult vmaCreateImage(VmaAllocator allocator, const VkImageCreateInfo *pImageCreateInfo, const VmaAllocationCreateInfo *pAllocationCreateInfo, VkImage *pImage, VmaAllocation *pAllocation, VmaAllocationInfo *pAllocationInfo)
      Function similar to vmaCreateBuffer().
      -
      VMA_MEMORY_USAGE_AUTO
      @ VMA_MEMORY_USAGE_AUTO
      Definition: vk_mem_alloc.h:488
      -
      VMA_ALLOCATION_CREATE_DEDICATED_MEMORY_BIT
      @ VMA_ALLOCATION_CREATE_DEDICATED_MEMORY_BIT
      Set this flag if the allocation should have its own memory block.
      Definition: vk_mem_alloc.h:524
      -
      VmaAllocationCreateInfo
      Definition: vk_mem_alloc.h:1211
      -
      VmaAllocationCreateInfo::usage
      VmaMemoryUsage usage
      Intended usage of memory.
      Definition: vk_mem_alloc.h:1219
      -
      VmaAllocationCreateInfo::flags
      VmaAllocationCreateFlags flags
      Use VmaAllocationCreateFlagBits enum.
      Definition: vk_mem_alloc.h:1213
      +
      VMA_MEMORY_USAGE_AUTO
      @ VMA_MEMORY_USAGE_AUTO
      Definition: vk_mem_alloc.h:489
      +
      VMA_ALLOCATION_CREATE_DEDICATED_MEMORY_BIT
      @ VMA_ALLOCATION_CREATE_DEDICATED_MEMORY_BIT
      Set this flag if the allocation should have its own memory block.
      Definition: vk_mem_alloc.h:525
      +
      VmaAllocationCreateInfo
      Definition: vk_mem_alloc.h:1212
      +
      VmaAllocationCreateInfo::priority
      float priority
      A floating-point value between 0 and 1, indicating the priority of the allocation relative to other m...
      Definition: vk_mem_alloc.h:1258
      +
      VmaAllocationCreateInfo::usage
      VmaMemoryUsage usage
      Intended usage of memory.
      Definition: vk_mem_alloc.h:1220
      +
      VmaAllocationCreateInfo::flags
      VmaAllocationCreateFlags flags
      Use VmaAllocationCreateFlagBits enum.
      Definition: vk_mem_alloc.h:1214
      VmaAllocation
      Represents single memory allocation.
      -

      Also consider: Consider 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 with different sizes e.g. when display resolution changes. Prefer to create such resources first and all other GPU resources (like textures and vertex buffers) later.

      +

      Also consider: Consider 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 with different sizes e.g. when display resolution changes. Prefer to create such resources first and all other GPU resources (like textures and vertex buffers) later. When VK_EXT_memory_priority extension is enabled, it is also worth setting high priority to such allocation to decrease chances to be evicted to system memory by the operating system.

      Staging copy for upload

      When: A "staging" buffer than you want to map and fill from CPU code, then use as a source od transfer to some GPU resource.

      @@ -125,10 +127,10 @@ Staging copy for upload
      memcpy(allocInfo.pMappedData, myData, myDataSize);
      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:546
      -
      VMA_ALLOCATION_CREATE_HOST_ACCESS_SEQUENTIAL_WRITE_BIT
      @ VMA_ALLOCATION_CREATE_HOST_ACCESS_SEQUENTIAL_WRITE_BIT
      Definition: vk_mem_alloc.h:593
      -
      VmaAllocationInfo
      Parameters of VmaAllocation objects, that can be retrieved using function vmaGetAllocationInfo().
      Definition: vk_mem_alloc.h:1326
      -
      VmaAllocationInfo::pMappedData
      void * pMappedData
      Pointer to the beginning of this allocation as mapped data.
      Definition: vk_mem_alloc.h:1368
      +
      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:547
      +
      VMA_ALLOCATION_CREATE_HOST_ACCESS_SEQUENTIAL_WRITE_BIT
      @ VMA_ALLOCATION_CREATE_HOST_ACCESS_SEQUENTIAL_WRITE_BIT
      Definition: vk_mem_alloc.h:594
      +
      VmaAllocationInfo
      Parameters of VmaAllocation objects, that can be retrieved using function vmaGetAllocationInfo().
      Definition: vk_mem_alloc.h:1327
      +
      VmaAllocationInfo::pMappedData
      void * pMappedData
      Pointer to the beginning of this allocation as mapped data.
      Definition: vk_mem_alloc.h:1369

      Also consider: You can map the allocation using vmaMapMemory() or you can create it as persistenly mapped using VMA_ALLOCATION_CREATE_MAPPED_BIT, as in the example above.

      Readback

      @@ -151,7 +153,7 @@ Readback
      ...
      const float* downloadedData = (const float*)allocInfo.pMappedData;
      -
      VMA_ALLOCATION_CREATE_HOST_ACCESS_RANDOM_BIT
      @ VMA_ALLOCATION_CREATE_HOST_ACCESS_RANDOM_BIT
      Definition: vk_mem_alloc.h:605
      +
      VMA_ALLOCATION_CREATE_HOST_ACCESS_RANDOM_BIT
      @ VMA_ALLOCATION_CREATE_HOST_ACCESS_RANDOM_BIT
      Definition: vk_mem_alloc.h:606

      Advanced data uploading

      For resources that you frequently write on CPU via mapped pointer and freqnently read on GPU e.g. as a uniform buffer (also called "dynamic"), multiple options are possible:

      @@ -213,6 +215,7 @@ Advanced data uploading
      // [Executed in runtime]:
      memcpy(stagingAllocInfo.pMappedData, myData, myDataSize);
      +
      //vkCmdPipelineBarrier: VK_ACCESS_HOST_WRITE_BIT --> VK_ACCESS_TRANSFER_READ_BIT
      VkBufferCopy bufCopy = {
      0, // srcOffset
      0, // dstOffset,
      @@ -220,7 +223,7 @@ Advanced data uploading
      vkCmdCopyBuffer(cmdBuf, stagingBuf, buf, 1, &bufCopy);
      }
      vmaGetAllocationMemoryProperties
      void vmaGetAllocationMemoryProperties(VmaAllocator allocator, VmaAllocation allocation, VkMemoryPropertyFlags *pFlags)
      Given an allocation, returns Property Flags of its memory type.
      -
      VMA_ALLOCATION_CREATE_HOST_ACCESS_ALLOW_TRANSFER_INSTEAD_BIT
      @ VMA_ALLOCATION_CREATE_HOST_ACCESS_ALLOW_TRANSFER_INSTEAD_BIT
      Definition: vk_mem_alloc.h:617
      +
      VMA_ALLOCATION_CREATE_HOST_ACCESS_ALLOW_TRANSFER_INSTEAD_BIT
      @ VMA_ALLOCATION_CREATE_HOST_ACCESS_ALLOW_TRANSFER_INSTEAD_BIT
      Definition: vk_mem_alloc.h:618

      Other use cases

      Here are some other, less obvious use cases and their recommended settings:

      diff --git a/docs/html/virtual_allocator.html b/docs/html/virtual_allocator.html index d29811c..9210b38 100644 --- a/docs/html/virtual_allocator.html +++ b/docs/html/virtual_allocator.html @@ -84,8 +84,8 @@ Creating virtual block
      VmaVirtualBlock block;
      VkResult res = vmaCreateVirtualBlock(&blockCreateInfo, &block);
      vmaCreateVirtualBlock
      VkResult vmaCreateVirtualBlock(const VmaVirtualBlockCreateInfo *pCreateInfo, VmaVirtualBlock *pVirtualBlock)
      Creates new VmaVirtualBlock object.
      -
      VmaVirtualBlockCreateInfo
      Parameters of created VmaVirtualBlock object to be passed to vmaCreateVirtualBlock().
      Definition: vk_mem_alloc.h:1472
      -
      VmaVirtualBlockCreateInfo::size
      VkDeviceSize size
      Total size of the virtual block.
      Definition: vk_mem_alloc.h:1478
      +
      VmaVirtualBlockCreateInfo
      Parameters of created VmaVirtualBlock object to be passed to vmaCreateVirtualBlock().
      Definition: vk_mem_alloc.h:1473
      +
      VmaVirtualBlockCreateInfo::size
      VkDeviceSize size
      Total size of the virtual block.
      Definition: vk_mem_alloc.h:1479
      VmaVirtualBlock
      Handle to a virtual block object that allows to use core allocation algorithm without allocating any ...

      Making virtual allocations

      @@ -111,8 +111,8 @@ Making virtual allocations
      // Allocation failed - no space for it could be found. Handle this error!
      }
      vmaVirtualAllocate
      VkResult vmaVirtualAllocate(VmaVirtualBlock virtualBlock, const VmaVirtualAllocationCreateInfo *pCreateInfo, VmaVirtualAllocation *pAllocation, VkDeviceSize *pOffset)
      Allocates new virtual allocation inside given VmaVirtualBlock.
      -
      VmaVirtualAllocationCreateInfo
      Parameters of created virtual allocation to be passed to vmaVirtualAllocate().
      Definition: vk_mem_alloc.h:1493
      -
      VmaVirtualAllocationCreateInfo::size
      VkDeviceSize size
      Size of the allocation.
      Definition: vk_mem_alloc.h:1498
      +
      VmaVirtualAllocationCreateInfo
      Parameters of created virtual allocation to be passed to vmaVirtualAllocate().
      Definition: vk_mem_alloc.h:1494
      +
      VmaVirtualAllocationCreateInfo::size
      VkDeviceSize size
      Size of the allocation.
      Definition: vk_mem_alloc.h:1499
      VmaVirtualAllocation
      Represents single memory allocation done inside VmaVirtualBlock.

      Deallocation

      @@ -140,8 +140,8 @@ Allocation parameters
      vmaVirtualFree(block, alloc);
      vmaGetVirtualAllocationInfo
      void vmaGetVirtualAllocationInfo(VmaVirtualBlock virtualBlock, VmaVirtualAllocation allocation, VmaVirtualAllocationInfo *pVirtualAllocInfo)
      Returns information about a specific virtual allocation within a virtual block, like its size and pUs...
      -
      VmaVirtualAllocationInfo
      Parameters of an existing virtual allocation, returned by vmaGetVirtualAllocationInfo().
      Definition: vk_mem_alloc.h:1516
      -
      VmaVirtualAllocationInfo::pUserData
      void * pUserData
      Custom pointer associated with the allocation.
      Definition: vk_mem_alloc.h:1531
      +
      VmaVirtualAllocationInfo
      Parameters of an existing virtual allocation, returned by vmaGetVirtualAllocationInfo().
      Definition: vk_mem_alloc.h:1517
      +
      VmaVirtualAllocationInfo::pUserData
      void * pUserData
      Custom pointer associated with the allocation.
      Definition: vk_mem_alloc.h:1532

      Alignment and units

      It feels natural to express sizes and offsets in bytes. If an offset of an allocation needs to be aligned to a multiply of some number (e.g. 4 bytes), you can fill optional member VmaVirtualAllocationCreateInfo::alignment to request it. Example:

      @@ -151,7 +151,7 @@ Alignment and units
      VmaVirtualAllocation alloc;
      res = vmaVirtualAllocate(block, &allocCreateInfo, &alloc, nullptr);
      -
      VmaVirtualAllocationCreateInfo::alignment
      VkDeviceSize alignment
      Required alignment of the allocation. Optional.
      Definition: vk_mem_alloc.h:1503
      +
      VmaVirtualAllocationCreateInfo::alignment
      VkDeviceSize alignment
      Required alignment of the allocation. Optional.
      Definition: vk_mem_alloc.h:1504

      Alignments of different allocations made from one block may vary. However, if all alignments and sizes are always multiply of some size e.g. 4 B or sizeof(MyDataStruct), you can express all sizes, alignments, and offsets in multiples of that size instead of individual bytes. It might be more convenient, but you need to make sure to use this new unit consistently in all the places:

      • VmaVirtualBlockCreateInfo::size
        • @@ -166,9 +166,9 @@ Statistics
        printf("My virtual block has %llu bytes used by %u virtual allocations\n",
        stats.allocationBytes, stats.allocationCount);
        vmaGetVirtualBlockStatistics
        void vmaGetVirtualBlockStatistics(VmaVirtualBlock virtualBlock, VmaStatistics *pStats)
        Calculates and returns statistics about virtual allocations and memory usage in given VmaVirtualBlock...
        -
        VmaStatistics
        Calculated statistics of memory usage e.g. in a specific memory type, heap, custom pool,...
        Definition: vk_mem_alloc.h:1104
        -
        VmaStatistics::allocationBytes
        VkDeviceSize allocationBytes
        Total number of bytes occupied by all VmaAllocation objects.
        Definition: vk_mem_alloc.h:1126
        -
        VmaStatistics::allocationCount
        uint32_t allocationCount
        Number of VmaAllocation objects allocated.
        Definition: vk_mem_alloc.h:1112
        +
        VmaStatistics
        Calculated statistics of memory usage e.g. in a specific memory type, heap, custom pool,...
        Definition: vk_mem_alloc.h:1105
        +
        VmaStatistics::allocationBytes
        VkDeviceSize allocationBytes
        Total number of bytes occupied by all VmaAllocation objects.
        Definition: vk_mem_alloc.h:1127
        +
        VmaStatistics::allocationCount
        uint32_t allocationCount
        Number of VmaAllocation objects allocated.
        Definition: vk_mem_alloc.h:1113

        You can also request a full list of allocations and free regions as a string in JSON format by calling vmaBuildVirtualBlockStatsString(). Returned string must be later freed using vmaFreeVirtualBlockStatsString(). The format of this string differs from the one returned by the main Vulkan allocator, but it is similar.

        Additional considerations

        diff --git a/docs/html/vk__mem__alloc_8h.html b/docs/html/vk__mem__alloc_8h.html index d5fa800..61d96a2 100644 --- a/docs/html/vk__mem__alloc_8h.html +++ b/docs/html/vk__mem__alloc_8h.html @@ -173,7 +173,7 @@ Typedefs
    • - + @@ -333,7 +333,7 @@ Enumerations , VMA_DEFRAGMENTATION_MOVE_OPERATION_IGNORE = 1 , VMA_DEFRAGMENTATION_MOVE_OPERATION_DESTROY = 2 } - +
    Enumerator
    VMA_DEFRAGMENTATION_MOVE_OPERATION_COPY 

    Buffer/image has been recreated at dstMemory + dstOffset, data has been copied, old buffer/image has been destroyed. srcAllocation should be changed to point to the new place. This is the default value set by vmaBeginDefragmentationPass().

    typedef VkFlags VmaDefragmentationFlags
     
    typedef enum VmaDefragmentationMoveOperation VmaDefragmentationMoveOperation
     Operation performed on single defragmentation move. More...
     Operation performed on single defragmentation move. See structure VmaDefragmentationMove. More...
     
    typedef enum VmaVirtualBlockCreateFlagBits VmaVirtualBlockCreateFlagBits
     Flags to be passed as VmaVirtualBlockCreateInfo::flags. More...
     Operation performed on single defragmentation move. More...
     Operation performed on single defragmentation move. See structure VmaDefragmentationMove. More...
     
    enum  VmaVirtualBlockCreateFlagBits { VMA_VIRTUAL_BLOCK_CREATE_LINEAR_ALGORITHM_BIT = 0x00000001 , VMA_VIRTUAL_BLOCK_CREATE_ALGORITHM_MASK diff --git a/docs/html/vk_khr_dedicated_allocation.html b/docs/html/vk_khr_dedicated_allocation.html index a9e58fb..c074a1e 100644 --- a/docs/html/vk_khr_dedicated_allocation.html +++ b/docs/html/vk_khr_dedicated_allocation.html @@ -83,7 +83,7 @@ $(function() {
    vmaCreateAllocator(&allocatorInfo, &allocator);
    vmaCreateAllocator
    VkResult vmaCreateAllocator(const VmaAllocatorCreateInfo *pCreateInfo, VmaAllocator *pAllocator)
    Creates VmaAllocator 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:342
    +
    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:343

    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.

    diff --git a/include/vk_mem_alloc.h b/include/vk_mem_alloc.h index c596e76..bf9bd34 100644 --- a/include/vk_mem_alloc.h +++ b/include/vk_mem_alloc.h @@ -89,6 +89,7 @@ License: MIT - \subpage vk_amd_device_coherent_memory - \subpage general_considerations - [Thread safety](@ref general_considerations_thread_safety) + - [Versioning and compatibility](@ref general_considerations_versioning_and_compatibility) - [Validation layer warnings](@ref general_considerations_validation_layer_warnings) - [Allocation algorithm](@ref general_considerations_allocation_algorithm) - [Features not supported](@ref general_considerations_features_not_supported) @@ -587,7 +588,7 @@ typedef enum VmaAllocationCreateFlagBits never read or accessed randomly, so a memory type can be selected that is uncached and write-combined. \warning Violating this declaration may work correctly, but will likely be very slow. - Watch out for implicit reads introduces by doing e.g. `pMappedData[i] += x;` + Watch out for implicit reads introduced by doing e.g. `pMappedData[i] += x;` Better prepare your data in a local variable and `memcpy()` it to the mapped pointer all at once. */ VMA_ALLOCATION_CREATE_HOST_ACCESS_SEQUENTIAL_WRITE_BIT = 0x00000400, @@ -724,7 +725,7 @@ typedef enum VmaDefragmentationFlagBits } VmaDefragmentationFlagBits; typedef VkFlags VmaDefragmentationFlags; -/// Operation performed on single defragmentation move. +/// Operation performed on single defragmentation move. See structure #VmaDefragmentationMove. typedef enum VmaDefragmentationMoveOperation { /// Buffer/image has been recreated at `dstMemory` + `dstOffset`, data has been copied, old buffer/image has been destroyed. `srcAllocation` should be changed to point to the new place. This is the default value set by vmaBeginDefragmentationPass(). @@ -1193,7 +1194,7 @@ typedef struct VmaBudget 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. + external to the program, decided by the operating system. Difference `budget - usage` is the amount of additional memory that can probably be allocated without problems. Exceeding the budget may result in various problems. */ @@ -17945,6 +17946,8 @@ you can achieve behavior of a ring buffer / queue. Ring buffer is available only in pools with one memory block - VmaPoolCreateInfo::maxBlockCount must be 1. Otherwise behavior is undefined. +\note \ref defragmentation is not supported in custom pools created with #VMA_POOL_CREATE_LINEAR_ALGORITHM_BIT. + \page defragmentation Defragmentation @@ -18007,7 +18010,7 @@ Unlike in previous iterations of the defragmentation API, there is no list of "m Defragmentation algorithm tries to move all suitable allocations. You can, however, refuse to move some of them inside a defragmentation pass, by setting `pass.pMoves[i].operation` to #VMA_DEFRAGMENTATION_MOVE_OPERATION_IGNORE. -However, this is not recommended and may result in suboptimal packing of the allocations after defragmentation. +This is not recommended and may result in suboptimal packing of the allocations after defragmentation. If you cannot ensure any allocation can be moved, it is better to keep movable allocations separate in a custom pool. You can also decide to destroy an allocation instead of moving it. @@ -18021,6 +18024,8 @@ It is also safe to perform the defragmentation asynchronously to render frames a usage, possibly from multiple threads, with the exception that allocations returned in VmaDefragmentationPassMoveInfo::pMoves shouldn't be destroyed until the defragmentation pass is ended. +\note Defragmentation is not supported in custom pools created with #VMA_POOL_CREATE_LINEAR_ALGORITHM_BIT. + \page statistics Statistics @@ -18503,6 +18508,7 @@ imgCreateInfo.samples = VK_SAMPLE_COUNT_1_BIT; VmaAllocationCreateInfo allocCreateInfo = {}; allocCreateInfo.usage = VMA_MEMORY_USAGE_AUTO; allocCreateInfo.flags = VMA_ALLOCATION_CREATE_DEDICATED_MEMORY_BIT; +allocCreateInfo.priority = 1.0f; VkImage img; VmaAllocation alloc; @@ -18514,7 +18520,8 @@ Consider creating them as dedicated allocations using #VMA_ALLOCATION_CREATE_DED especially if they are large or if you plan to destroy and recreate them with different sizes e.g. when display resolution changes. Prefer to create such resources first and all other GPU resources (like textures and vertex buffers) later. - +When VK_EXT_memory_priority extension is enabled, it is also worth setting high priority to such allocation +to decrease chances to be evicted to system memory by the operating system. \section usage_patterns_staging_copy_upload Staging copy for upload @@ -18665,6 +18672,7 @@ else // [Executed in runtime]: memcpy(stagingAllocInfo.pMappedData, myData, myDataSize); + //vkCmdPipelineBarrier: VK_ACCESS_HOST_WRITE_BIT --> VK_ACCESS_TRANSFER_READ_BIT VkBufferCopy bufCopy = { 0, // srcOffset 0, // dstOffset, @@ -18951,6 +18959,28 @@ accompanying this library. functions. - #VmaVirtualBlock is not safe to be used from multiple threads simultaneously. +\section general_considerations_versioning_and_compatibility Versioning and compatibility + +The library uses [**Semantic Versioning**](https://semver.org/), +which means version numbers follow convention: Major.Minor.Patch (e.g. 2.3.0), where: + +- Incremented Patch version means a release is backward- and forward-compatible, + introducing only some internal improvements, bug fixes, optimizations etc. + or changes that are out of scope of the official API described in this documentation. +- Incremented Minor version means a release is backward-compatible, + so existing code that uses the library should continue to work, while some new + symbols could have been added: new structures, functions, new values in existing + enums and bit flags, new structure members, but not new function parameters. +- Incrementing Major version means a release could break some backward compatibility. + +All changes between official releases are documented in file "CHANGELOG.md". + +\warning Backward compatiblity is considered on the level of C++ source code, not binary linkage. +Adding new members to existing structures is treated as backward compatible if initializing +the new members to binary zero results in the old behavior. +You should always fully initialize all library structures to zeros and not rely on their +exact binary size. + \section general_considerations_validation_layer_warnings Validation layer warnings When using this library, you can meet following types of warnings issued by