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
    • - + @@ -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