From 01364c79702d6fefe38a2e88e16f0a8bb4a300dd Mon Sep 17 00:00:00 2001 From: Adam Sawicki Date: Mon, 28 Feb 2022 12:10:18 +0100 Subject: [PATCH] Added documentation chapter "VK_EXT_memory_priority" Other fixes in documentation --- docs/html/allocation_annotation.html | 18 +- docs/html/annotated.html | 2 +- docs/html/choosing_memory_type.html | 34 +- docs/html/custom_memory_pools.html | 22 +- docs/html/defragmentation.html | 14 +- docs/html/general_considerations.html | 4 +- docs/html/group__group__alloc.html | 84 ++-- docs/html/group__group__init.html | 3 + docs/html/index.html | 4 + docs/html/memory_mapping.html | 18 +- docs/html/modules.html | 2 +- docs/html/quick_start.html | 30 +- docs/html/resource_aliasing.html | 4 +- docs/html/search/all_11.js | 393 +++++++++--------- docs/html/search/pages_a.js | 5 +- docs/html/struct_vma_allocation.html | 2 +- .../struct_vma_allocation_create_info.html | 8 +- docs/html/struct_vma_allocation_info.html | 2 +- docs/html/usage_patterns.html | 26 +- docs/html/virtual_allocator.html | 20 +- docs/html/vk__mem__alloc_8h.html | 19 +- docs/html/vk_ext_memory_priority.html | 132 ++++++ docs/html/vk_khr_dedicated_allocation.html | 4 +- include/vk_mem_alloc.h | 126 +++++- src/Tests.cpp | 16 +- 25 files changed, 644 insertions(+), 348 deletions(-) create mode 100644 docs/html/vk_ext_memory_priority.html diff --git a/docs/html/allocation_annotation.html b/docs/html/allocation_annotation.html index 7af9a6c..5b4f7c6 100644 --- a/docs/html/allocation_annotation.html +++ b/docs/html/allocation_annotation.html @@ -83,19 +83,19 @@ Allocation user data
VkBuffer buffer;
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: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
+
vmaCreateBuffer
VkResult vmaCreateBuffer(VmaAllocator allocator, const VkBufferCreateInfo *pBufferCreateInfo, const VmaAllocationCreateInfo *pAllocationCreateInfo, VkBuffer *pBuffer, VmaAllocation *pAllocation, VmaAllocationInfo *pAllocationInfo)
Creates a new VkBuffer, allocates and binds memory for it.
+
VMA_MEMORY_USAGE_AUTO
@ VMA_MEMORY_USAGE_AUTO
Definition: vk_mem_alloc.h:492
+
VmaAllocationCreateInfo
Parameters of new VmaAllocation.
Definition: vk_mem_alloc.h:1221
+
VmaAllocationCreateInfo::pUserData
void * pUserData
Custom general-purpose pointer that will be stored in VmaAllocation, can be read as VmaAllocationInfo...
Definition: vk_mem_alloc.h:1260
+
VmaAllocationCreateInfo::usage
VmaMemoryUsage usage
Intended usage of memory.
Definition: vk_mem_alloc.h:1229
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: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
+
VmaAllocationInfo
Parameters of VmaAllocation objects, that can be retrieved using function vmaGetAllocationInfo().
Definition: vk_mem_alloc.h:1336
+
VmaAllocationInfo::pUserData
void * pUserData
Custom general-purpose pointer that was passed as VmaAllocationCreateInfo::pUserData or set using vma...
Definition: vk_mem_alloc.h:1383

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:557
-
VmaAllocationCreateInfo::flags
VmaAllocationCreateFlags flags
Use VmaAllocationCreateFlagBits enum.
Definition: vk_mem_alloc.h:1214
+
VMA_ALLOCATION_CREATE_USER_DATA_COPY_STRING_BIT
@ VMA_ALLOCATION_CREATE_USER_DATA_COPY_STRING_BIT
Definition: vk_mem_alloc.h:560
+
VmaAllocationCreateInfo::flags
VmaAllocationCreateFlags flags
Use VmaAllocationCreateFlagBits enum.
Definition: vk_mem_alloc.h:1223

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/annotated.html b/docs/html/annotated.html index 138b744..99cfd69 100644 --- a/docs/html/annotated.html +++ b/docs/html/annotated.html @@ -68,7 +68,7 @@ $(function() {
Here are the classes, structs, unions and interfaces with brief descriptions:
- + diff --git a/docs/html/choosing_memory_type.html b/docs/html/choosing_memory_type.html index ae1a29c..13d0908 100644 --- a/docs/html/choosing_memory_type.html +++ b/docs/html/choosing_memory_type.html @@ -69,16 +69,16 @@ $(function() {
Choosing memory type
-

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

+

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

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

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

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

-

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

+

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

Usage

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

@@ -93,10 +93,10 @@ Usage
VkBuffer buffer;
VmaAllocation allocation;
vmaCreateBuffer(allocator, &bufferInfo, &allocInfo, &buffer, &allocation, nullptr);
-
vmaCreateBuffer
VkResult vmaCreateBuffer(VmaAllocator allocator, const VkBufferCreateInfo *pBufferCreateInfo, const VmaAllocationCreateInfo *pAllocationCreateInfo, VkBuffer *pBuffer, VmaAllocation *pAllocation, VmaAllocationInfo *pAllocationInfo)
-
VMA_MEMORY_USAGE_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
+
vmaCreateBuffer
VkResult vmaCreateBuffer(VmaAllocator allocator, const VkBufferCreateInfo *pBufferCreateInfo, const VmaAllocationCreateInfo *pAllocationCreateInfo, VkBuffer *pBuffer, VmaAllocation *pAllocation, VmaAllocationInfo *pAllocationInfo)
Creates a new VkBuffer, allocates and binds memory for it.
+
VMA_MEMORY_USAGE_AUTO
@ VMA_MEMORY_USAGE_AUTO
Definition: vk_mem_alloc.h:492
+
VmaAllocationCreateInfo
Parameters of new VmaAllocation.
Definition: vk_mem_alloc.h:1221
+
VmaAllocationCreateInfo::usage
VmaMemoryUsage usage
Intended usage of memory.
Definition: vk_mem_alloc.h:1229
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,10 +112,10 @@ 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:594
-
VmaAllocationCreateInfo::flags
VmaAllocationCreateFlags flags
Use VmaAllocationCreateFlagBits enum.
Definition: vk_mem_alloc.h:1214
+
VMA_ALLOCATION_CREATE_HOST_ACCESS_SEQUENTIAL_WRITE_BIT
@ VMA_ALLOCATION_CREATE_HOST_ACCESS_SEQUENTIAL_WRITE_BIT
Definition: vk_mem_alloc.h:597
+
VmaAllocationCreateInfo::flags
VmaAllocationCreateFlags flags
Use VmaAllocationCreateFlagBits enum.
Definition: vk_mem_alloc.h:1223

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.

+

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

Note
Old usage values (VMA_MEMORY_USAGE_GPU_ONLY, VMA_MEMORY_USAGE_CPU_ONLY, VMA_MEMORY_USAGE_CPU_TO_GPU, VMA_MEMORY_USAGE_GPU_TO_CPU, VMA_MEMORY_USAGE_CPU_COPY) are still available and work same way as in previous versions of the library for backward compatibility, but they are not recommended.

Required and preferred flags

@@ -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: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
+
VMA_ALLOCATION_CREATE_MAPPED_BIT
@ VMA_ALLOCATION_CREATE_MAPPED_BIT
Set this flag to use a memory that will be persistently mapped and retrieve pointer to it.
Definition: vk_mem_alloc.h:550
+
VMA_ALLOCATION_CREATE_HOST_ACCESS_RANDOM_BIT
@ VMA_ALLOCATION_CREATE_HOST_ACCESS_RANDOM_BIT
Definition: vk_mem_alloc.h:609
+
VmaAllocationCreateInfo::preferredFlags
VkMemoryPropertyFlags preferredFlags
Flags that preferably should be set in a memory type chosen for an allocation.
Definition: vk_mem_alloc.h:1239
+
VmaAllocationCreateInfo::requiredFlags
VkMemoryPropertyFlags requiredFlags
Flags that must be set in a Memory Type chosen for an allocation.
Definition: vk_mem_alloc.h:1234

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

Custom memory pools

-

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

+

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

Dedicated allocations

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

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

    • To use custom memory pools:

    @@ -122,17 +122,17 @@ $(function() {
    res = vmaCreateBuffer(allocator, &bufCreateInfo, &allocCreateInfo, &buf, &alloc, nullptr);
    // Check res...
    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)
    +
    vmaCreateBuffer
    VkResult vmaCreateBuffer(VmaAllocator allocator, const VkBufferCreateInfo *pBufferCreateInfo, const VmaAllocationCreateInfo *pAllocationCreateInfo, VkBuffer *pBuffer, VmaAllocation *pAllocation, VmaAllocationInfo *pAllocationInfo)
    Creates a new VkBuffer, allocates and binds memory for it.
    vmaFindMemoryTypeIndexForBufferInfo
    VkResult vmaFindMemoryTypeIndexForBufferInfo(VmaAllocator allocator, const VkBufferCreateInfo *pBufferCreateInfo, const VmaAllocationCreateInfo *pAllocationCreateInfo, uint32_t *pMemoryTypeIndex)
    Helps to find memoryTypeIndex, given VkBufferCreateInfo and VmaAllocationCreateInfo.
    -
    VMA_MEMORY_USAGE_AUTO
    @ VMA_MEMORY_USAGE_AUTO
    Definition: vk_mem_alloc.h:489
    -
    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
    -
    VmaAllocationCreateInfo::usage
    VmaMemoryUsage usage
    Intended usage of memory.
    Definition: vk_mem_alloc.h:1220
    +
    VMA_MEMORY_USAGE_AUTO
    @ VMA_MEMORY_USAGE_AUTO
    Definition: vk_mem_alloc.h:492
    +
    VmaAllocationCreateInfo
    Parameters of new VmaAllocation.
    Definition: vk_mem_alloc.h:1221
    +
    VmaAllocationCreateInfo::pool
    VmaPool pool
    Pool that this allocation should be created in.
    Definition: vk_mem_alloc.h:1253
    +
    VmaAllocationCreateInfo::usage
    VmaMemoryUsage usage
    Intended usage of memory.
    Definition: vk_mem_alloc.h:1229
    VmaAllocation
    Represents single memory allocation.
    -
    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::blockSize
    VkDeviceSize blockSize
    Size of a single VkDeviceMemory block to be allocated as part of this pool, in bytes....
    Definition: vk_mem_alloc.h:1279
    -
    VmaPoolCreateInfo::maxBlockCount
    size_t maxBlockCount
    Maximum number of blocks that can be allocated in this pool. Optional.
    Definition: vk_mem_alloc.h:1292
    +
    VmaPoolCreateInfo
    Describes parameter of created VmaPool.
    Definition: vk_mem_alloc.h:1272
    +
    VmaPoolCreateInfo::memoryTypeIndex
    uint32_t memoryTypeIndex
    Vulkan memory type index to allocate this pool from.
    Definition: vk_mem_alloc.h:1275
    +
    VmaPoolCreateInfo::blockSize
    VkDeviceSize blockSize
    Size of a single VkDeviceMemory block to be allocated as part of this pool, in bytes....
    Definition: vk_mem_alloc.h:1288
    +
    VmaPoolCreateInfo::maxBlockCount
    size_t maxBlockCount
    Maximum number of blocks that can be allocated in this pool. Optional.
    Definition: vk_mem_alloc.h:1301
    VmaPool
    Represents custom memory pool.

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

    vmaDestroyBuffer(allocator, buf, alloc);
    @@ -160,7 +160,7 @@ Choosing memory type index

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

    • VkBufferCreateInfo: Prefer to pass same parameters as above. Otherwise you risk creating resources in a memory type that is not suitable for them, which may result in undefined behavior. Using different VK_BUFFER_USAGE_ flags may work, but you shouldn't create images in a pool intended for buffers or the other way around.
      • -
    • VmaAllocationCreateInfo: You don't need to pass same parameters. Fill only pool member. Other members are ignored anyway.
      • +
    • VmaAllocationCreateInfo: You don't need to pass same parameters. Fill only pool member. Other members are ignored anyway.

    Linear allocation algorithm

    diff --git a/docs/html/defragmentation.html b/docs/html/defragmentation.html index e06abd1..d8fb2ec 100644 --- a/docs/html/defragmentation.html +++ b/docs/html/defragmentation.html @@ -91,7 +91,7 @@ $(function() {
    for(uint32_t i = 0; i < pass.moveCount; ++i)
    {
    //- Inspect pass.pMoves[i].srcAllocation, identify what buffer or image it represents.
    -
    //- Recreate this buffer or image at pass.pMoves[i].dstMemory, pass.pMoves[i].dstOffset.
    +
    //- Recreate and bind this buffer or image at pass.pMoves[i].dstMemory, pass.pMoves[i].dstOffset.
    //- Issue a vkCmdCopyBuffer/vkCmdCopyImage to copy its content to the new place.
    }
    //- Make sure the copy commands finished executing.
    @@ -111,13 +111,13 @@ $(function() {
    vmaBeginDefragmentationPass
    VkResult vmaBeginDefragmentationPass(VmaAllocator allocator, VmaDefragmentationContext context, VmaDefragmentationPassMoveInfo *pPassInfo)
    Starts single defragmentation pass.
    vmaBeginDefragmentation
    VkResult vmaBeginDefragmentation(VmaAllocator allocator, const VmaDefragmentationInfo *pInfo, VmaDefragmentationContext *pContext)
    Begins defragmentation process.
    vmaEndDefragmentationPass
    VkResult vmaEndDefragmentationPass(VmaAllocator allocator, VmaDefragmentationContext context, VmaDefragmentationPassMoveInfo *pPassInfo)
    Ends single defragmentation pass.
    -
    VMA_DEFRAGMENTATION_FLAG_ALGORITHM_FAST_BIT
    @ VMA_DEFRAGMENTATION_FLAG_ALGORITHM_FAST_BIT
    Definition: vk_mem_alloc.h:701
    +
    VMA_DEFRAGMENTATION_FLAG_ALGORITHM_FAST_BIT
    @ VMA_DEFRAGMENTATION_FLAG_ALGORITHM_FAST_BIT
    Definition: vk_mem_alloc.h:705
    VmaDefragmentationContext
    An opaque object that represents started defragmentation process.
    -
    VmaDefragmentationInfo
    Parameters for defragmentation.
    Definition: vk_mem_alloc.h:1382
    -
    VmaDefragmentationInfo::pool
    VmaPool pool
    Custom pool to be defragmented.
    Definition: vk_mem_alloc.h:1389
    -
    VmaDefragmentationInfo::flags
    VmaDefragmentationFlags flags
    Use combination of VmaDefragmentationFlagBits.
    Definition: vk_mem_alloc.h:1384
    -
    VmaDefragmentationPassMoveInfo
    Parameters for incremental defragmentation steps.
    Definition: vk_mem_alloc.h:1422
    -
    VmaDefragmentationPassMoveInfo::moveCount
    uint32_t moveCount
    Number of elements in the pMoves array.
    Definition: vk_mem_alloc.h:1424
    +
    VmaDefragmentationInfo
    Parameters for defragmentation.
    Definition: vk_mem_alloc.h:1391
    +
    VmaDefragmentationInfo::pool
    VmaPool pool
    Custom pool to be defragmented.
    Definition: vk_mem_alloc.h:1398
    +
    VmaDefragmentationInfo::flags
    VmaDefragmentationFlags flags
    Use combination of VmaDefragmentationFlagBits.
    Definition: vk_mem_alloc.h:1393
    +
    VmaDefragmentationPassMoveInfo
    Parameters for incremental defragmentation steps.
    Definition: vk_mem_alloc.h:1431
    +
    VmaDefragmentationPassMoveInfo::moveCount
    uint32_t moveCount
    Number of elements in the pMoves array.
    Definition: vk_mem_alloc.h:1433

    You can defragment a specific custom pool by setting VmaDefragmentationInfo::pool (like in the example above) or all the default pools by setting this member to null.

    Unlike in previous iterations of the defragmentation API, there is no list of "movable" allocations passed as a parameter. 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. 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. You should then set pass.pMoves[i].operation to VMA_DEFRAGMENTATION_MOVE_OPERATION_DESTROY.

    diff --git a/docs/html/general_considerations.html b/docs/html/general_considerations.html index 4d4d779..a941a25 100644 --- a/docs/html/general_considerations.html +++ b/docs/html/general_considerations.html @@ -113,7 +113,7 @@ Allocation algorithm
  • If failed, try to create a new block of VkDeviceMemory, with preferred block size.
  • If failed, try to create such block with size / 2, size / 4, size / 8.
  • If failed, try to allocate separate VkDeviceMemory for this allocation, just like when you use VMA_ALLOCATION_CREATE_DEDICATED_MEMORY_BIT.
    • -
  • If failed, choose other memory type that meets the requirements specified in VmaAllocationCreateInfo and go to point 1.
    • +
  • If failed, choose other memory type that meets the requirements specified in VmaAllocationCreateInfo and go to point 1.
  • If failed, return VK_ERROR_OUT_OF_DEVICE_MEMORY.

    • @@ -121,7 +121,7 @@ Features not supported

    Features deliberately excluded from the scope of this library:

    1. Data transfer. Uploading (streaming) and downloading data of buffers and images between CPU and GPU memory and related synchronization is responsibility of the user. Defining some "texture" object that would automatically stream its data from a staging copy in CPU memory to GPU memory would rather be a feature of another, higher-level library implemented on top of VMA. VMA doesn't record any commands to a VkCommandBuffer. It just allocates memory.
      2. -
    2. Recreation of buffers and images. Although the library has functions for buffer and image creation: vmaCreateBuffer(), vmaCreateImage(), you need to recreate these objects yourself after defragmentation. That is because the big structures VkBufferCreateInfo, VkImageCreateInfo are not stored in VmaAllocation object.
      3. +
    3. Recreation of buffers and images. Although the library has functions for buffer and image creation: vmaCreateBuffer(), vmaCreateImage(), you need to recreate these objects yourself after defragmentation. That is because the big structures VkBufferCreateInfo, VkImageCreateInfo are not stored in VmaAllocation object.
    4. Handling CPU memory allocation failures. When dynamically creating small C++ objects in CPU memory (not Vulkan memory), allocation failures are not checked and handled gracefully, because that would complicate code significantly and is usually not needed in desktop PC applications anyway. Success of an allocation is just checked with an assert.
    5. Code free of any compiler warnings. Maintaining the library to compile and work correctly on so many different platforms is hard enough. Being free of any warnings, on any version of any compiler, is simply not feasible. There are many preprocessor macros that make some variables unused, function parameters unreferenced, or conditional expressions constant in some configurations. The code of this library should not be bigger or more complicated just to silence these warnings. It is recommended to disable such warnings instead.
    6. This is a C++ library with C interface. Bindings or ports to any other programming languages are welcome as external projects but are not going to be included into this repository.
      7. diff --git a/docs/html/group__group__alloc.html b/docs/html/group__group__alloc.html index eb735f8..ab27ce5 100644 --- a/docs/html/group__group__alloc.html +++ b/docs/html/group__group__alloc.html @@ -71,12 +71,13 @@ $(function() {
      -

      API elements related to the allocation, deallocation, and management of Vulkan memory, buffers, images. Most basic ones being: vmaCreateBuffer(), vmaCreateImage(). +

      API elements related to the allocation, deallocation, and management of Vulkan memory, buffers, images. Most basic ones being: vmaCreateBuffer(), vmaCreateImage(). More...

     CVmaAllocationRepresents single memory allocation
     CVmaAllocationCreateInfo
     CVmaAllocationCreateInfoParameters of new VmaAllocation
     CVmaAllocationInfoParameters of VmaAllocation objects, that can be retrieved using function vmaGetAllocationInfo()
     CVmaAllocatorRepresents main object of this library initialized
     CVmaAllocatorCreateInfoDescription of a Allocator to be created
    + @@ -115,6 +116,7 @@ Typedefs + @@ -126,11 +128,13 @@ Typedefs + + @@ -229,13 +233,13 @@ Enumerations - + - + - + @@ -259,12 +263,13 @@ Functions + - + - + @@ -324,6 +329,7 @@ Functions + @@ -332,14 +338,14 @@ Functions - +

    Classes

    struct  VmaAllocationCreateInfo
     Parameters of new VmaAllocation. More...
     
    struct  VmaPoolCreateInfo
     Describes parameter of created VmaPool. More...
     Flags to be passed as VmaAllocationCreateInfo::flags. More...
     
    typedef VkFlags VmaAllocationCreateFlags
     See VmaAllocationCreateFlagBits. More...
     
    typedef enum VmaPoolCreateFlagBits VmaPoolCreateFlagBits
     Flags to be passed as VmaPoolCreateInfo::flags. More...
     Flags to be passed as VmaDefragmentationInfo::flags. More...
     
    typedef VkFlags VmaDefragmentationFlags
     See VmaDefragmentationFlagBits. More...
     
    typedef enum VmaDefragmentationMoveOperation VmaDefragmentationMoveOperation
     Operation performed on single defragmentation move. See structure VmaDefragmentationMove. More...
     
    typedef struct VmaAllocationCreateInfo VmaAllocationCreateInfo
     Parameters of new VmaAllocation. More...
     
    typedef struct VmaPoolCreateInfo VmaPoolCreateInfo
     Describes parameter of created VmaPool. More...

    Functions

    VkResult vmaFindMemoryTypeIndex (VmaAllocator allocator, uint32_t memoryTypeBits, const VmaAllocationCreateInfo *pAllocationCreateInfo, uint32_t *pMemoryTypeIndex)
     Helps to find memoryTypeIndex, given memoryTypeBits and VmaAllocationCreateInfo. More...
     Helps to find memoryTypeIndex, given memoryTypeBits and VmaAllocationCreateInfo. More...
     
    VkResult vmaFindMemoryTypeIndexForBufferInfo (VmaAllocator allocator, const VkBufferCreateInfo *pBufferCreateInfo, const VmaAllocationCreateInfo *pAllocationCreateInfo, uint32_t *pMemoryTypeIndex)
     Helps to find memoryTypeIndex, given VkBufferCreateInfo and VmaAllocationCreateInfo. More...
     Helps to find memoryTypeIndex, given VkBufferCreateInfo and VmaAllocationCreateInfo. More...
     
    VkResult vmaFindMemoryTypeIndexForImageInfo (VmaAllocator allocator, const VkImageCreateInfo *pImageCreateInfo, const VmaAllocationCreateInfo *pAllocationCreateInfo, uint32_t *pMemoryTypeIndex)
     Helps to find memoryTypeIndex, given VkImageCreateInfo and VmaAllocationCreateInfo. More...
     Helps to find memoryTypeIndex, given VkImageCreateInfo and VmaAllocationCreateInfo. More...
     
    VkResult vmaCreatePool (VmaAllocator allocator, const VmaPoolCreateInfo *pCreateInfo, VmaPool *pPool)
     Allocates Vulkan device memory and creates VmaPool object. More...
     General purpose memory allocation for multiple allocation objects at once. More...
     
    VkResult vmaAllocateMemoryForBuffer (VmaAllocator allocator, VkBuffer buffer, const VmaAllocationCreateInfo *pCreateInfo, VmaAllocation *pAllocation, VmaAllocationInfo *pAllocationInfo)
     Allocates memory suitable for given VkBuffer. More...
     
    VkResult vmaAllocateMemoryForImage (VmaAllocator allocator, VkImage image, const VmaAllocationCreateInfo *pCreateInfo, VmaAllocation *pAllocation, VmaAllocationInfo *pAllocationInfo)
     Function similar to vmaAllocateMemoryForBuffer(). More...
     Allocates memory suitable for given VkImage. More...
     
    void vmaFreeMemory (VmaAllocator allocator, const VmaAllocation allocation)
     Frees memory previously allocated using vmaAllocateMemory(), vmaAllocateMemoryForBuffer(), or vmaAllocateMemoryForImage(). More...
     Frees memory previously allocated using vmaAllocateMemory(), vmaAllocateMemoryForBuffer(), or vmaAllocateMemoryForImage(). More...
     
    void vmaFreeMemoryPages (VmaAllocator allocator, size_t allocationCount, const VmaAllocation *pAllocations)
     Frees memory and destroys multiple allocations. More...
     Binds image to allocation with additional parameters. More...
     
    VkResult vmaCreateBuffer (VmaAllocator allocator, const VkBufferCreateInfo *pBufferCreateInfo, const VmaAllocationCreateInfo *pAllocationCreateInfo, VkBuffer *pBuffer, VmaAllocation *pAllocation, VmaAllocationInfo *pAllocationInfo)
     Creates a new VkBuffer, allocates and binds memory for it. More...
     
    VkResult vmaCreateBufferWithAlignment (VmaAllocator allocator, const VkBufferCreateInfo *pBufferCreateInfo, const VmaAllocationCreateInfo *pAllocationCreateInfo, VkDeviceSize minAlignment, VkBuffer *pBuffer, VmaAllocation *pAllocation, VmaAllocationInfo *pAllocationInfo)
     Creates a buffer with additional minimum alignment. More...
     Destroys Vulkan buffer and frees allocated memory. More...
     
    VkResult vmaCreateImage (VmaAllocator allocator, const VkImageCreateInfo *pImageCreateInfo, const VmaAllocationCreateInfo *pAllocationCreateInfo, VkImage *pImage, VmaAllocation *pAllocation, VmaAllocationInfo *pAllocationInfo)
     Function similar to vmaCreateBuffer(). More...
     Function similar to vmaCreateBuffer(). More...
     
    void vmaDestroyImage (VmaAllocator allocator, VkImage image, VmaAllocation allocation)
     Destroys Vulkan image and frees allocated memory. More...
     

    Detailed Description

    -

    API elements related to the allocation, deallocation, and management of Vulkan memory, buffers, images. Most basic ones being: vmaCreateBuffer(), vmaCreateImage().

    +

    API elements related to the allocation, deallocation, and management of Vulkan memory, buffers, images. Most basic ones being: vmaCreateBuffer(), vmaCreateImage().

    Typedef Documentation

    ◆ VmaAllocationCreateFlagBits

    @@ -369,6 +375,8 @@ Functions
    +

    See VmaAllocationCreateFlagBits.

    +
    @@ -383,6 +391,9 @@ Functions
    +

    Parameters of new VmaAllocation.

    +

    To be used with functions like vmaCreateBuffer(), vmaCreateImage(), and many others.

    +
    @@ -429,6 +440,8 @@ Functions
    +

    See VmaDefragmentationFlagBits.

    +
    @@ -613,7 +626,7 @@ Functions VMA_ALLOCATION_CREATE_UPPER_ADDRESS_BIT 

    Allocation will be created from upper stack in a double stack pool.

    This flag is only allowed for custom pools created with VMA_POOL_CREATE_LINEAR_ALGORITHM_BIT flag.

    -VMA_ALLOCATION_CREATE_DONT_BIND_BIT 

    Create both buffer/image and allocation, but don't bind them together. It is useful when you want to bind yourself to do some more advanced binding, e.g. using some extensions. The flag is meaningful only with functions that bind by default: vmaCreateBuffer(), vmaCreateImage(). Otherwise it is ignored.

    +VMA_ALLOCATION_CREATE_DONT_BIND_BIT 

    Create both buffer/image and allocation, but don't bind them together. It is useful when you want to bind yourself to do some more advanced binding, e.g. using some extensions. The flag is meaningful only with functions that bind by default: vmaCreateBuffer(), vmaCreateImage(). Otherwise it is ignored.

    VMA_ALLOCATION_CREATE_WITHIN_BUDGET_BIT 

    Create allocation only if additional device memory required for it, if any, won't exceed memory budget. Otherwise return VK_ERROR_OUT_OF_DEVICE_MEMORY.

    @@ -719,7 +732,7 @@ Functions

    Intended usage of the allocated memory.

    - @@ -737,15 +750,15 @@ Functions
    Enumerator
    VMA_MEMORY_USAGE_UNKNOWN 

    No intended memory usage specified. Use other members of VmaAllocationCreateInfo to specify your requirements.

    +
    Enumerator
    VMA_MEMORY_USAGE_UNKNOWN 

    No intended memory usage specified. Use other members of VmaAllocationCreateInfo to specify your requirements.

    VMA_MEMORY_USAGE_GPU_ONLY 
    Deprecated:
    Obsolete, preserved for backward compatibility. Prefers VK_MEMORY_PROPERTY_DEVICE_LOCAL_BIT.
    VMA_MEMORY_USAGE_AUTO 

    Selects best memory type automatically. This flag is recommended for most common use cases.

    When using this flag, if you want to map the allocation (using vmaMapMemory() or VMA_ALLOCATION_CREATE_MAPPED_BIT), you must pass one of the flags: VMA_ALLOCATION_CREATE_HOST_ACCESS_SEQUENTIAL_WRITE_BIT or VMA_ALLOCATION_CREATE_HOST_ACCESS_RANDOM_BIT in VmaAllocationCreateInfo::flags.

    -

    It can be used only with functions that let the library know VkBufferCreateInfo or VkImageCreateInfo, e.g. vmaCreateBuffer(), vmaCreateImage(), vmaFindMemoryTypeIndexForBufferInfo(), vmaFindMemoryTypeIndexForImageInfo() and not with generic memory allocation functions.

    +

    It can be used only with functions that let the library know VkBufferCreateInfo or VkImageCreateInfo, e.g. vmaCreateBuffer(), vmaCreateImage(), vmaFindMemoryTypeIndexForBufferInfo(), vmaFindMemoryTypeIndexForImageInfo() and not with generic memory allocation functions.

    VMA_MEMORY_USAGE_AUTO_PREFER_DEVICE 

    Selects best memory type automatically with preference for GPU (device) memory.

    When using this flag, if you want to map the allocation (using vmaMapMemory() or VMA_ALLOCATION_CREATE_MAPPED_BIT), you must pass one of the flags: VMA_ALLOCATION_CREATE_HOST_ACCESS_SEQUENTIAL_WRITE_BIT or VMA_ALLOCATION_CREATE_HOST_ACCESS_RANDOM_BIT in VmaAllocationCreateInfo::flags.

    -

    It can be used only with functions that let the library know VkBufferCreateInfo or VkImageCreateInfo, e.g. vmaCreateBuffer(), vmaCreateImage(), vmaFindMemoryTypeIndexForBufferInfo(), vmaFindMemoryTypeIndexForImageInfo() and not with generic memory allocation functions.

    +

    It can be used only with functions that let the library know VkBufferCreateInfo or VkImageCreateInfo, e.g. vmaCreateBuffer(), vmaCreateImage(), vmaFindMemoryTypeIndexForBufferInfo(), vmaFindMemoryTypeIndexForImageInfo() and not with generic memory allocation functions.

    VMA_MEMORY_USAGE_AUTO_PREFER_HOST 

    Selects best memory type automatically with preference for CPU (host) memory.

    When using this flag, if you want to map the allocation (using vmaMapMemory() or VMA_ALLOCATION_CREATE_MAPPED_BIT), you must pass one of the flags: VMA_ALLOCATION_CREATE_HOST_ACCESS_SEQUENTIAL_WRITE_BIT or VMA_ALLOCATION_CREATE_HOST_ACCESS_RANDOM_BIT in VmaAllocationCreateInfo::flags.

    -

    It can be used only with functions that let the library know VkBufferCreateInfo or VkImageCreateInfo, e.g. vmaCreateBuffer(), vmaCreateImage(), vmaFindMemoryTypeIndexForBufferInfo(), vmaFindMemoryTypeIndexForImageInfo() and not with generic memory allocation functions.

    +

    It can be used only with functions that let the library know VkBufferCreateInfo or VkImageCreateInfo, e.g. vmaCreateBuffer(), vmaCreateImage(), vmaFindMemoryTypeIndexForBufferInfo(), vmaFindMemoryTypeIndexForImageInfo() and not with generic memory allocation functions.

    VMA_MEMORY_USAGE_MAX_ENUM 
    @@ -768,8 +781,8 @@ Functions

    You should free the memory using vmaFreeMemory() or vmaFreeMemoryPages().

    -

    It is recommended to use vmaAllocateMemoryForBuffer(), vmaAllocateMemoryForImage(), vmaCreateBuffer(), vmaCreateImage() instead whenever possible.

    +

    It is recommended to use vmaAllocateMemoryForBuffer(), vmaAllocateMemoryForImage(), vmaCreateBuffer(), vmaCreateImage() instead whenever possible.

    @@ -886,6 +899,8 @@ Functions
    Enumerator
    VMA_POOL_CREATE_IGNORE_BUFFER_IMAGE_GRANULARITY_BIT 

    Use this flag if you always allocate only buffers and linear images or only optimal images out of this pool and so Buffer-Image Granularity can be ignored.

    This is an optional optimization flag.

    -

    If you always allocate using vmaCreateBuffer(), vmaCreateImage(), vmaAllocateMemoryForBuffer(), then you don't need to use it because allocator knows exact type of your allocations so it can handle Buffer-Image Granularity in the optimal way.

    -

    If you also allocate using vmaAllocateMemoryForImage() or vmaAllocateMemory(), exact type of such allocations is not known, so allocator must be conservative in handling Buffer-Image Granularity, which can lead to suboptimal allocation (wasted memory). In that case, if you can make sure you always allocate only buffers and linear images or only optimal images out of this pool, use this flag to make allocator disregard Buffer-Image Granularity and so make allocations faster and more optimal.

    +

    If you always allocate using vmaCreateBuffer(), vmaCreateImage(), vmaAllocateMemoryForBuffer(), then you don't need to use it because allocator knows exact type of your allocations so it can handle Buffer-Image Granularity in the optimal way.

    +

    If you also allocate using vmaAllocateMemoryForImage() or vmaAllocateMemory(), exact type of such allocations is not known, so allocator must be conservative in handling Buffer-Image Granularity, which can lead to suboptimal allocation (wasted memory). In that case, if you can make sure you always allocate only buffers and linear images or only optimal images out of this pool, use this flag to make allocator disregard Buffer-Image Granularity and so make allocations faster and more optimal.

    VMA_POOL_CREATE_LINEAR_ALGORITHM_BIT 

    Enables alternative, linear allocation algorithm in this pool.

    Specify this flag to enable linear allocation algorithm, which always creates new allocations after last one and doesn't reuse space from allocations freed in between. It trades memory consumption for simplified algorithm and data structure, which has better performance and uses less memory for metadata.

    @@ -839,7 +852,7 @@ Functions
    + +

    Allocates memory suitable for given VkBuffer.

    Parameters
    @@ -896,7 +911,9 @@ Functions
    allocator
    -

    You should free the memory using vmaFreeMemory().

    +

    It only creates VmaAllocation. To bind the memory to the buffer, use vmaBindBufferMemory().

    +

    This is a special-purpose function. In most cases you should use vmaCreateBuffer().

    +

    You must free the allocation using vmaFreeMemory() when no longer needed.

    @@ -944,7 +961,20 @@ Functions
    -

    Function similar to vmaAllocateMemoryForBuffer().

    +

    Allocates memory suitable for given VkImage.

    +
    Parameters
    + + + + + + +
    allocator
    image
    pCreateInfo
    [out]pAllocationHandle to allocated memory.
    [out]pAllocationInfoOptional. Information about allocated memory. It can be later fetched using function vmaGetAllocationInfo().
    +
    +
    +

    It only creates VmaAllocation. To bind the memory to the buffer, use vmaBindImageMemory().

    +

    This is a special-purpose function. In most cases you should use vmaCreateImage().

    +

    You must free the allocation using vmaFreeMemory() when no longer needed.

    @@ -1144,7 +1174,7 @@ Functions

    Binds buffer to allocation.

    Binds specified buffer to region of memory represented by specified allocation. Gets VkDeviceMemory handle and offset from the allocation. If you want to create a buffer, allocate memory for it and bind them together separately, you should use this function for binding instead of standard vkBindBufferMemory(), because it ensures proper synchronization so that when a VkDeviceMemory object is used by multiple allocations, calls to vkBind*Memory() or vkMapMemory() won't happen from multiple threads simultaneously (which is illegal in Vulkan).

    -

    It is recommended to use function vmaCreateBuffer() instead of this one.

    +

    It is recommended to use function vmaCreateBuffer() instead of this one.

    @@ -1438,6 +1468,8 @@ Functions
    + +

    Creates a new VkBuffer, allocates and binds memory for it.

    Parameters
    @@ -1519,7 +1551,7 @@ Functions

    Creates a buffer with additional minimum alignment.

    -

    Similar to vmaCreateBuffer() but provides additional parameter minAlignment which allows to specify custom, minimum alignment to be used when placing the buffer inside a larger memory block, which may be needed e.g. for interop with OpenGL.

    +

    Similar to vmaCreateBuffer() but provides additional parameter minAlignment which allows to specify custom, minimum alignment to be used when placing the buffer inside a larger memory block, which may be needed e.g. for interop with OpenGL.

    @@ -1573,7 +1605,7 @@ Functions
    allocator
    -

    Function similar to vmaCreateBuffer().

    +

    Function similar to vmaCreateBuffer().

    @@ -1866,7 +1898,7 @@ Functions
    -

    Helps to find memoryTypeIndex, given memoryTypeBits and VmaAllocationCreateInfo.

    +

    Helps to find memoryTypeIndex, given memoryTypeBits and VmaAllocationCreateInfo.

    This algorithm tries to find a memory type that:

    -

    Helps to find memoryTypeIndex, given VkBufferCreateInfo and VmaAllocationCreateInfo.

    +

    Helps to find memoryTypeIndex, given VkBufferCreateInfo and VmaAllocationCreateInfo.

    It can be useful e.g. to determine value to be used as VmaPoolCreateInfo::memoryTypeIndex. It internally creates a temporary, dummy buffer that never has memory bound.

    @@ -1959,7 +1991,7 @@ Functions
    -

    Helps to find memoryTypeIndex, given VkImageCreateInfo and VmaAllocationCreateInfo.

    +

    Helps to find memoryTypeIndex, given VkImageCreateInfo and VmaAllocationCreateInfo.

    It can be useful e.g. to determine value to be used as VmaPoolCreateInfo::memoryTypeIndex. It internally creates a temporary, dummy image that never has memory bound.

    @@ -2102,7 +2134,7 @@ Functions
    -

    Frees memory previously allocated using vmaAllocateMemory(), vmaAllocateMemoryForBuffer(), or vmaAllocateMemoryForImage().

    +

    Frees memory previously allocated using vmaAllocateMemory(), vmaAllocateMemoryForBuffer(), or vmaAllocateMemoryForImage().

    Passing VK_NULL_HANDLE as allocation is valid. Such function call is just skipped.

    @@ -2179,7 +2211,7 @@ Functions

    Returns current information about specified allocation.

    Current paramteres of given allocation are returned in pAllocationInfo.

    -

    Although this function doesn't lock any mutex, so it should be quite efficient, you should avoid calling it too often. You can retrieve same VmaAllocationInfo structure while creating your resource, from function vmaCreateBuffer(), vmaCreateImage(). You can remember it if you are sure parameters don't change (e.g. due to defragmentation).

    +

    Although this function doesn't lock any mutex, so it should be quite efficient, you should avoid calling it too often. You can retrieve same VmaAllocationInfo structure while creating your resource, from function vmaCreateBuffer(), vmaCreateImage(). You can remember it if you are sure parameters don't change (e.g. due to defragmentation).

    diff --git a/docs/html/group__group__init.html b/docs/html/group__group__init.html index dcc8e65..1ab6ae8 100644 --- a/docs/html/group__group__init.html +++ b/docs/html/group__group__init.html @@ -98,6 +98,7 @@ Typedefs  Flags for created VmaAllocator. More...
      typedef VkFlags VmaAllocatorCreateFlags + See #VmaAllocatorCreateFlagBigs. More...
      typedef void(VKAPI_PTR * PFN_vmaAllocateDeviceMemoryFunction) (VmaAllocator allocator, uint32_t memoryType, VkDeviceMemory memory, VkDeviceSize size, void *pUserData)  Callback function called after successful vkAllocateMemory. More...
    @@ -220,6 +221,8 @@ Functions
    +

    See #VmaAllocatorCreateFlagBigs.

    +
    diff --git a/docs/html/index.html b/docs/html/index.html index 10391cc..b16c690 100644 --- a/docs/html/index.html +++ b/docs/html/index.html @@ -146,9 +146,13 @@ Table of contents
  • Device heap memory limit
    • +
  • Extension support +
  • General considerations