diff --git a/CHANGELOG.md b/CHANGELOG.md index 3e21d9d4..26f4e9b6 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,3 +1,16 @@ +# 3.4.0 (2026-??-??) + +- Added member `VmaAllocationCreateInfo::minAlignment` (#523). + - Remember to always fully initialize structures with zeros and don't rely on their specific `sizeof` to ensure backward compatibility! + - Function `vmaCreateBufferWithAlignment` is now deprecated. +- Improvements for external memory export & import (#503): + - Added functions `vmaCreateDedicatedBuffer`, `vmaCreateDedicatedImage`, `vmaAllocateDedicatedMemory` offering extra parameter `void* pMemoryAllocateNext`. + - Added function `vmaGetMemoryWin32Handle2` offering extra parameter `VkExternalMemoryHandleTypeFlagBits handleType`. +- Added `VMA_VERSION` macro with library version number (#507). +- Improvements in the algorithm choosing memory type when `VMA_MEMORY_USAGE_AUTO*` is used (#520). +- Fixes for compatibility with C++20 modules on Clang 21 and GCC15 (#513, #514). +- Other fixes and improvements, including compatibility with various platforms and compilers, improvements in documentation, sample application, and tests. + # 3.3.0 (2025-05-12) Additions to the library API: diff --git a/CMakeLists.txt b/CMakeLists.txt index c284c581..1547f472 100644 --- a/CMakeLists.txt +++ b/CMakeLists.txt @@ -1,5 +1,5 @@ # -# Copyright (c) 2017-2025 Advanced Micro Devices, Inc. All rights reserved. +# Copyright (c) 2017-2026 Advanced Micro Devices, Inc. All rights reserved. # # Permission is hereby granted, free of charge, to any person obtaining a copy # of this software and associated documentation files (the "Software"), to deal @@ -26,6 +26,7 @@ project(VMA VERSION 3.3.0 LANGUAGES CXX) add_library(VulkanMemoryAllocator INTERFACE) add_library(GPUOpen::VulkanMemoryAllocator ALIAS VulkanMemoryAllocator) +add_library(VulkanMemoryAllocator::Headers ALIAS VulkanMemoryAllocator) target_include_directories(VulkanMemoryAllocator INTERFACE $) diff --git a/LICENSE.txt b/LICENSE.txt index a080d9bf..be95175d 100644 --- a/LICENSE.txt +++ b/LICENSE.txt @@ -1,4 +1,4 @@ -Copyright (c) 2017-2025 Advanced Micro Devices, Inc. All rights reserved. +Copyright (c) 2017-2026 Advanced Micro Devices, Inc. All rights reserved. Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal diff --git a/docs/html/allocation_annotation.html b/docs/html/allocation_annotation.html index 73454683..bfe2afdc 100644 --- a/docs/html/allocation_annotation.html +++ b/docs/html/allocation_annotation.html @@ -3,7 +3,7 @@ - + Vulkan Memory Allocator: Allocation names and user data @@ -31,7 +31,7 @@ - + @@ -80,7 +80,7 @@

Allocation user data

-

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

+

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

VkBufferCreateInfo bufCreateInfo = ...
MyBufferMetadata* pMetadata = CreateBufferMetadata();
@@ -103,8 +103,8 @@
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
Definition vk_mem_alloc.h:1413
-
VmaAllocationInfo::pUserData
void * pUserData
Custom general-purpose pointer that was passed as VmaAllocationCreateInfo::pUserData or set using vma...
Definition vk_mem_alloc.h:1460
+
VmaAllocationInfo
Definition vk_mem_alloc.h:1432
+
VmaAllocationInfo::pUserData
void * pUserData
Custom general-purpose pointer that was passed as VmaAllocationCreateInfo::pUserData or set using vma...
Definition vk_mem_alloc.h:1479

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.

@@ -120,7 +120,7 @@

-Generated by doxygen 1.14.0 +Generated by doxygen 1.16.1
diff --git a/docs/html/annotated.html b/docs/html/annotated.html index 4080b50a..b479d003 100644 --- a/docs/html/annotated.html +++ b/docs/html/annotated.html @@ -3,7 +3,7 @@ - + Vulkan Memory Allocator: Class List @@ -31,7 +31,7 @@ - + @@ -106,7 +106,7 @@
-Generated by doxygen 1.14.0 +Generated by doxygen 1.16.1
diff --git a/docs/html/choosing_memory_type.html b/docs/html/choosing_memory_type.html index 3e83c9b3..b258de8f 100644 --- a/docs/html/choosing_memory_type.html +++ b/docs/html/choosing_memory_type.html @@ -3,7 +3,7 @@ - + Vulkan Memory Allocator: Choosing memory type @@ -31,7 +31,7 @@ - + @@ -123,9 +123,9 @@

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:662
VmaAllocationCreateInfo::flags
VmaAllocationCreateFlags flags
Use VmaAllocationCreateFlagBits enum.
Definition vk_mem_alloc.h:1296
-

For more examples of creating different kinds of resources, see chapter Recommended usage patterns. See also: Memory mapping.

+

For more examples of creating different kinds of resources, see chapter Recommended usage patterns. See also: Memory mapping.

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

Required and preferred flags

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

@@ -165,20 +165,20 @@

// ...

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

-Generated by doxygen 1.14.0 +Generated by doxygen 1.16.1
diff --git a/docs/html/classes.html b/docs/html/classes.html index 82c10757..489d8b97 100644 --- a/docs/html/classes.html +++ b/docs/html/classes.html @@ -3,7 +3,7 @@ - + Vulkan Memory Allocator: Class Index @@ -31,7 +31,7 @@ - + @@ -83,7 +83,7 @@
-Generated by doxygen 1.14.0 +Generated by doxygen 1.16.1
diff --git a/docs/html/configuration.html b/docs/html/configuration.html index 6b7baee5..546dad53 100644 --- a/docs/html/configuration.html +++ b/docs/html/configuration.html @@ -3,7 +3,7 @@ - + Vulkan Memory Allocator: Configuration @@ -31,7 +31,7 @@ - + @@ -109,7 +109,7 @@

-Generated by doxygen 1.14.0 +Generated by doxygen 1.16.1
diff --git a/docs/html/custom_memory_pools.html b/docs/html/custom_memory_pools.html index 90449392..66eb8ca7 100644 --- a/docs/html/custom_memory_pools.html +++ b/docs/html/custom_memory_pools.html @@ -3,7 +3,7 @@ - + Vulkan Memory Allocator: Custom memory pools @@ -31,7 +31,7 @@ - + @@ -138,10 +138,10 @@
VmaAllocationCreateInfo::pool
VmaPool pool
Pool that this allocation should be created in.
Definition vk_mem_alloc.h:1326
VmaAllocationCreateInfo::usage
VmaMemoryUsage usage
Intended usage of memory.
Definition vk_mem_alloc.h:1302
VmaAllocation
Represents single memory allocation.
-
VmaPoolCreateInfo
Describes parameter of created VmaPool.
Definition vk_mem_alloc.h:1345
-
VmaPoolCreateInfo::memoryTypeIndex
uint32_t memoryTypeIndex
Vulkan memory type index to allocate this pool from.
Definition vk_mem_alloc.h:1348
-
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:1361
-
VmaPoolCreateInfo::maxBlockCount
size_t maxBlockCount
Maximum number of blocks that can be allocated in this pool. Optional.
Definition vk_mem_alloc.h:1374
+
VmaPoolCreateInfo
Describes parameter of created VmaPool.
Definition vk_mem_alloc.h:1358
+
VmaPoolCreateInfo::memoryTypeIndex
uint32_t memoryTypeIndex
Vulkan memory type index to allocate this pool from.
Definition vk_mem_alloc.h:1361
+
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:1374
+
VmaPoolCreateInfo::maxBlockCount
size_t maxBlockCount
Maximum number of blocks that can be allocated in this pool. Optional.
Definition vk_mem_alloc.h:1387
VmaPool
Represents custom memory pool.

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

vmaDestroyBuffer(allocator, buf, alloc);
@@ -187,7 +187,7 @@

<
  • If you want to keep your mapped and not mapped allocations separate, you don't need to. VMA respects nonCoherentAtomSize limit automatically. It also maps only those VkDeviceMemory blocks that need to map any allocation. It even tries to keep mappable and non-mappable allocations in separate blocks to minimize the amount of mapped memory.
  • If you want to choose a custom size for the default memory block, you can set it globally instead using VmaAllocatorCreateInfo::preferredLargeHeapBlockSize.
  • If you want to select specific memory type for your allocation, you can set VmaAllocationCreateInfo::memoryTypeBits to (1U << myMemoryTypeIndex) instead.
    • -
  • If you need to create a buffer with certain minimum alignment, you can still do it using default pools with dedicated function vmaCreateBufferWithAlignment().
    • +
  • If you need to create a buffer with certain minimum alignment, you can still do it using default pools by specifying VmaAllocationCreateInfo::minAlignment.

    • Linear allocation algorithm

    @@ -222,12 +222,12 @@

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

    Ring buffer

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

    -
    Note
    Defragmentation is not supported in custom pools created with VMA_POOL_CREATE_LINEAR_ALGORITHM_BIT.
    +
    Note
    Defragmentation is not supported in custom pools created with VMA_POOL_CREATE_LINEAR_ALGORITHM_BIT.

    -Generated by doxygen 1.14.0 +Generated by doxygen 1.16.1
    diff --git a/docs/html/debugging_memory_usage.html b/docs/html/debugging_memory_usage.html index aac63dff..22f08433 100644 --- a/docs/html/debugging_memory_usage.html +++ b/docs/html/debugging_memory_usage.html @@ -3,7 +3,7 @@ - + Vulkan Memory Allocator: Debugging incorrect memory usage @@ -31,7 +31,7 @@ - + @@ -99,9 +99,9 @@

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

    Margins work with all types of memory.

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

    -

    Margins appear in JSON dump as part of free space.

    +

    Margins appear in JSON dump as part of free space.

    Note that enabling margins increases memory usage and fragmentation.

    -

    Margins do not apply to Virtual allocator.

    +

    Margins do not apply to Virtual allocator.

    Corruption detection

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

    @@ -120,7 +120,7 @@

    -Generated by doxygen 1.14.0 +Generated by doxygen 1.16.1
    diff --git a/docs/html/defragmentation.html b/docs/html/defragmentation.html index dff4b8dd..24282ac2 100644 --- a/docs/html/defragmentation.html +++ b/docs/html/defragmentation.html @@ -3,7 +3,7 @@ - + Vulkan Memory Allocator: Defragmentation @@ -31,7 +31,7 @@ - + @@ -144,17 +144,17 @@
    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:770
    -
    VmaAllocationInfo
    Definition vk_mem_alloc.h:1413
    -
    VmaAllocationInfo::pUserData
    void * pUserData
    Custom general-purpose pointer that was passed as VmaAllocationCreateInfo::pUserData or set using vma...
    Definition vk_mem_alloc.h:1460
    +
    VmaAllocationInfo
    Definition vk_mem_alloc.h:1432
    +
    VmaAllocationInfo::pUserData
    void * pUserData
    Custom general-purpose pointer that was passed as VmaAllocationCreateInfo::pUserData or set using vma...
    Definition vk_mem_alloc.h:1479
    VmaDefragmentationContext
    An opaque object that represents started defragmentation process.
    -
    VmaDefragmentationInfo
    Parameters for defragmentation.
    Definition vk_mem_alloc.h:1503
    -
    VmaDefragmentationInfo::pool
    VmaPool pool
    Custom pool to be defragmented.
    Definition vk_mem_alloc.h:1510
    -
    VmaDefragmentationInfo::flags
    VmaDefragmentationFlags flags
    Use combination of VmaDefragmentationFlagBits.
    Definition vk_mem_alloc.h:1505
    -
    VmaDefragmentationMove::srcAllocation
    VmaAllocation srcAllocation
    Allocation that should be moved.
    Definition vk_mem_alloc.h:1536
    -
    VmaDefragmentationMove::dstTmpAllocation
    VmaAllocation dstTmpAllocation
    Temporary allocation pointing to destination memory that will replace srcAllocation.
    Definition vk_mem_alloc.h:1543
    -
    VmaDefragmentationPassMoveInfo
    Parameters for incremental defragmentation steps.
    Definition vk_mem_alloc.h:1551
    -
    VmaDefragmentationPassMoveInfo::moveCount
    uint32_t moveCount
    Number of elements in the pMoves array.
    Definition vk_mem_alloc.h:1553
    -
    VmaDefragmentationPassMoveInfo::pMoves
    VmaDefragmentationMove * pMoves
    Array of moves to be performed by the user in the current defragmentation pass.
    Definition vk_mem_alloc.h:1577
    +
    VmaDefragmentationInfo
    Parameters for defragmentation.
    Definition vk_mem_alloc.h:1522
    +
    VmaDefragmentationInfo::pool
    VmaPool pool
    Custom pool to be defragmented.
    Definition vk_mem_alloc.h:1529
    +
    VmaDefragmentationInfo::flags
    VmaDefragmentationFlags flags
    Use combination of VmaDefragmentationFlagBits.
    Definition vk_mem_alloc.h:1524
    +
    VmaDefragmentationMove::srcAllocation
    VmaAllocation srcAllocation
    Allocation that should be moved.
    Definition vk_mem_alloc.h:1555
    +
    VmaDefragmentationMove::dstTmpAllocation
    VmaAllocation dstTmpAllocation
    Temporary allocation pointing to destination memory that will replace srcAllocation.
    Definition vk_mem_alloc.h:1562
    +
    VmaDefragmentationPassMoveInfo
    Parameters for incremental defragmentation steps.
    Definition vk_mem_alloc.h:1570
    +
    VmaDefragmentationPassMoveInfo::moveCount
    uint32_t moveCount
    Number of elements in the pMoves array.
    Definition vk_mem_alloc.h:1572
    +
    VmaDefragmentationPassMoveInfo::pMoves
    VmaDefragmentationMove * pMoves
    Array of moves to be performed by the user in the current defragmentation pass.
    Definition vk_mem_alloc.h:1596

    Although functions like vmaCreateBuffer(), vmaCreateImage(), vmaDestroyBuffer(), vmaDestroyImage() create/destroy an allocation and a buffer/image at once, these are just a shortcut for creating the resource, allocating memory, and binding them together. Defragmentation works on memory allocations only. You must handle the rest manually. Defragmentation is an iterative process that should repreat "passes" as long as related functions return VK_INCOMPLETE not VK_SUCCESS. In each pass:

    1. vmaBeginDefragmentationPass() function call:
        @@ -204,7 +204,7 @@
        -Generated by doxygen 1.14.0 +Generated by doxygen 1.16.1
        diff --git a/docs/html/deprecated.html b/docs/html/deprecated.html index fdc6db35..05e1bdc3 100644 --- a/docs/html/deprecated.html +++ b/docs/html/deprecated.html @@ -3,7 +3,7 @@ - + Vulkan Memory Allocator: Deprecated List @@ -31,7 +31,7 @@ - + @@ -76,23 +76,25 @@
        Member VMA_ALLOCATION_CREATE_USER_DATA_COPY_STRING_BIT
        -
        Preserved for backward compatibility. Consider using vmaSetAllocationName() instead.
        +
        Preserved for backward compatibility. Consider using vmaSetAllocationName() instead.
        Member VMA_MEMORY_USAGE_CPU_COPY
        -
        Obsolete, preserved for backward compatibility. Prefers not VK_MEMORY_PROPERTY_DEVICE_LOCAL_BIT.
        +
        Obsolete, preserved for backward compatibility. Prefers not VK_MEMORY_PROPERTY_DEVICE_LOCAL_BIT.
        Member VMA_MEMORY_USAGE_CPU_ONLY
        -
        Obsolete, preserved for backward compatibility. Guarantees VK_MEMORY_PROPERTY_HOST_VISIBLE_BIT and VK_MEMORY_PROPERTY_HOST_COHERENT_BIT.
        +
        Obsolete, preserved for backward compatibility. Guarantees VK_MEMORY_PROPERTY_HOST_VISIBLE_BIT and VK_MEMORY_PROPERTY_HOST_COHERENT_BIT.
        Member VMA_MEMORY_USAGE_CPU_TO_GPU
        -
        Obsolete, preserved for backward compatibility. Guarantees VK_MEMORY_PROPERTY_HOST_VISIBLE_BIT, prefers VK_MEMORY_PROPERTY_DEVICE_LOCAL_BIT.
        +
        Obsolete, preserved for backward compatibility. Guarantees VK_MEMORY_PROPERTY_HOST_VISIBLE_BIT, prefers VK_MEMORY_PROPERTY_DEVICE_LOCAL_BIT.
        Member VMA_MEMORY_USAGE_GPU_ONLY
        -
        Obsolete, preserved for backward compatibility. Prefers VK_MEMORY_PROPERTY_DEVICE_LOCAL_BIT.
        +
        Obsolete, preserved for backward compatibility. Prefers VK_MEMORY_PROPERTY_DEVICE_LOCAL_BIT.
        Member VMA_MEMORY_USAGE_GPU_TO_CPU
        -
        Obsolete, preserved for backward compatibility. Guarantees VK_MEMORY_PROPERTY_HOST_VISIBLE_BIT, prefers VK_MEMORY_PROPERTY_HOST_CACHED_BIT.
        +
        Obsolete, preserved for backward compatibility. Guarantees VK_MEMORY_PROPERTY_HOST_VISIBLE_BIT, prefers VK_MEMORY_PROPERTY_HOST_CACHED_BIT.
        +
        Member vmaCreateBufferWithAlignment (VmaAllocator allocator, const VkBufferCreateInfo *pBufferCreateInfo, const VmaAllocationCreateInfo *pAllocationCreateInfo, VkDeviceSize minAlignment, VkBuffer *pBuffer, VmaAllocation *pAllocation, VmaAllocationInfo *pAllocationInfo)
        +
        This function in obsolete since new VmaAllocationCreateInfo::minAlignment member allows specifying custom alignment while using any allocation function, like the standard vmaCreateBuffer().
        -Generated by doxygen 1.14.0 +Generated by doxygen 1.16.1
        diff --git a/docs/html/dir_d44c64559bbebec7f509842c48db8b23.html b/docs/html/dir_d44c64559bbebec7f509842c48db8b23.html index cb11150f..303849ae 100644 --- a/docs/html/dir_d44c64559bbebec7f509842c48db8b23.html +++ b/docs/html/dir_d44c64559bbebec7f509842c48db8b23.html @@ -3,7 +3,7 @@ - + Vulkan Memory Allocator: C:/Code/VulkanMemoryAllocator/REPO/include Directory Reference @@ -31,7 +31,7 @@ - + @@ -81,12 +81,12 @@ - +

        Files

                 		vk_mem_alloc.h
                 		vk_mem_alloc.h
        -Generated by doxygen 1.14.0 +Generated by doxygen 1.16.1
        diff --git a/docs/html/doxygen.css b/docs/html/doxygen.css index 5d2eecd6..788923ab 100644 --- a/docs/html/doxygen.css +++ b/docs/html/doxygen.css @@ -1,4 +1,4 @@ -/* The standard CSS for doxygen 1.14.0*/ +/* The standard CSS for doxygen 1.16.1*/ html { /* page base colors */ @@ -19,7 +19,6 @@ html { --header-separator-color: #C4CFE5; --group-header-separator-color: #D9E0EE; --group-header-color: #354C7B; ---inherit-header-color: gray; --footer-foreground-color: #2A3D61; --footer-logo-width: 75px; @@ -28,8 +27,6 @@ html { --title-background-color: white; --title-separator-color: #C4CFE5; ---directory-separator-color: #9CAFD4; ---separator-color: #4A6AAA; --blockquote-background-color: #F7F8FB; --blockquote-border-color: #9CAFD4; @@ -39,10 +36,6 @@ html { --icon-background-color: #728DC1; --icon-foreground-color: white; -/* ---icon-doc-image: url('doc.svg'); ---icon-folder-open-image: url('folderopen.svg'); ---icon-folder-closed-image: url('folderclosed.svg');*/ --icon-folder-open-fill-color: #C4CFE5; --icon-folder-fill-color: #D8DFEE; --icon-folder-border-color: #4665A2; @@ -51,7 +44,6 @@ html { /* brief member declaration list */ --memdecl-background-color: #F9FAFC; ---memdecl-separator-color: #DEE4F0; --memdecl-foreground-color: #555; --memdecl-template-color: #4665A2; --memdecl-border-color: #D5DDEC; @@ -61,7 +53,6 @@ html { --memdef-title-background-color: #E2E8F2; --memdef-proto-background-color: #EEF1F7; --memdef-proto-text-color: #253555; ---memdef-doc-background-color: white; --memdef-param-name-color: #602020; --memdef-template-color: #4665A2; @@ -83,21 +74,17 @@ html { --nav-breadcrumb-separator-color: #C4CFE5; --nav-breadcrumb-active-bg: #EEF1F7; --nav-breadcrumb-color: #354C7B; ---nav-breadcrumb-border-color: #E1E7F2; --nav-splitbar-bg-color: #DCE2EF; --nav-splitbar-handle-color: #9CAFD4; --nav-font-size-level1: 13px; --nav-font-size-level2: 10px; --nav-font-size-level3: 9px; --nav-text-normal-color: #283A5D; ---nav-text-hover-color: white; ---nav-text-active-color: white; --nav-menu-button-color: #364D7C; --nav-menu-background-color: white; --nav-menu-foreground-color: #555555; --nav-menu-active-bg: #DCE2EF; --nav-menu-active-color: #9CAFD4; ---nav-menu-toggle-color: rgba(255, 255, 255, 0.5); --nav-arrow-color: #B6C4DF; --nav-arrow-selected-color: #90A5CE; @@ -145,8 +132,6 @@ html { --code-vhdl-char-color: #000000; --code-vhdl-keyword-color: #700070; --code-vhdl-logic-color: #FF0000; ---code-link-color: #4665A2; ---code-external-link-color: #4665A2; --fragment-foreground-color: black; --fragment-background-color: #FBFCFD; --fragment-border-color: #C4CFE5; @@ -158,6 +143,7 @@ html { --fragment-lineno-link-hover-fg-color: #4665A2; --fragment-lineno-link-hover-bg-color: #C8C8C8; --fragment-copy-ok-color: #2EC82E; +--fragment-highlight-filter: -3; --tooltip-foreground-color: black; --tooltip-background-color: rgba(255,255,255,0.8); --tooltip-arrow-background-color: white; @@ -201,6 +187,11 @@ html { --invariant-color-bg: #d8f1e3; --invariant-color-hl: #44b86f; --invariant-color-text: #265532; +--satisfies-color-hl: #b61825; +--satisfies-color-bg: #f8d1cc; +--verifies-color-hl: #b61825; +--verifies-color-bg: #f8d1cc; + } @media (prefers-color-scheme: dark) { @@ -225,7 +216,6 @@ html { --header-separator-color: #141C2E; --group-header-separator-color: #1D2A43; --group-header-color: #90A5CE; ---inherit-header-color: #A0A0A0; --footer-foreground-color: #5B7AB7; --footer-logo-width: 60px; @@ -234,8 +224,6 @@ html { --title-background-color: #090D16; --title-separator-color: #212F4B; ---directory-separator-color: #283A5D; ---separator-color: #283A5D; --blockquote-background-color: #101826; --blockquote-border-color: #283A5D; @@ -253,7 +241,6 @@ html { /* brief member declaration list */ --memdecl-background-color: #0B101A; ---memdecl-separator-color: #2C3F65; --memdecl-foreground-color: #BBB; --memdecl-template-color: #7C95C6; --memdecl-border-color: #233250; @@ -263,7 +250,6 @@ html { --memdef-title-background-color: #1B2840; --memdef-proto-background-color: #19243A; --memdef-proto-text-color: #9DB0D4; ---memdef-doc-background-color: black; --memdef-param-name-color: #D28757; --memdef-template-color: #7C95C6; @@ -285,21 +271,17 @@ html { --nav-breadcrumb-separator-color: #212F4B; --nav-breadcrumb-active-bg: #1D2A43; --nav-breadcrumb-color: #90A5CE; ---nav-breadcrumb-border-color: #2A3D61; --nav-splitbar-bg-color: #283A5D; --nav-splitbar-handle-color: #4665A2; --nav-font-size-level1: 13px; --nav-font-size-level2: 10px; --nav-font-size-level3: 9px; --nav-text-normal-color: #B6C4DF; ---nav-text-hover-color: #DCE2EF; ---nav-text-active-color: #DCE2EF; --nav-menu-button-color: #B6C4DF; --nav-menu-background-color: #05070C; --nav-menu-foreground-color: #BBBBBB; --nav-menu-active-bg: #1D2A43; --nav-menu-active-color: #C9D3E7; ---nav-menu-toggle-color: rgba(255, 255, 255, 0.2); --nav-arrow-color: #4665A2; --nav-arrow-selected-color: #6884BD; @@ -347,8 +329,6 @@ html { --code-vhdl-char-color: #C0C0C0; --code-vhdl-keyword-color: #CF53C9; --code-vhdl-logic-color: #FF0000; ---code-link-color: #79C0FF; ---code-external-link-color: #79C0FF; --fragment-foreground-color: #C9D1D9; --fragment-background-color: #090D16; --fragment-border-color: #30363D; @@ -360,6 +340,7 @@ html { --fragment-lineno-link-hover-fg-color: #8E96A1; --fragment-lineno-link-hover-bg-color: #505050; --fragment-copy-ok-color: #0EA80E; +--fragment-highlight-filter: 5; --tooltip-foreground-color: #C9D1D9; --tooltip-background-color: #202020; --tooltip-arrow-background-color: #202020; @@ -403,6 +384,11 @@ html { --invariant-color-bg: #303a35; --invariant-color-hl: #76ce96; --invariant-color-text: #cceed5; +--satisfies-color-hl: #ad2617; +--satisfies-color-bg: #2e1917; +--verifies-color-hl: #ad2617; +--verifies-color-bg: #2e1917; + }} body { background-color: var(--page-background-color); @@ -483,6 +469,7 @@ dt { p.startli, p.startdd { margin-top: 2px; + margin-bottom: 0px; } th p.starttd, th p.intertd, th p.endtd { @@ -674,6 +661,11 @@ a.code.hl_event { /* style for links to event names in code snippets */ } a.code.hl_sequence { /* style for links to sequence names in code snippets */ } a.code.hl_dictionary { /* style for links to dictionary names in code snippets */ } +div.embeddoc { + font-family: var(--font-family-monospace); + padding-left: 10px; +} + /* @end */ dl.el { @@ -681,15 +673,35 @@ dl.el { } ul.check { - list-style:none; - text-indent: -16px; - padding-left: 38px; + list-style: none; + padding-left: 40px; + margin: 0; +} + +ul.check li { + position: relative; +} + +li.unchecked::before, li.checked::before { + position: absolute; + left: -18px; + top: 0; } -li.unchecked:before { - content: "\2610\A0"; + +li.unchecked::before { + content: "☐"; +} + +li.checked::before { + content: "☑"; +} + +ul.check li > p { + display: inline; } -li.checked:before { - content: "\2611\A0"; + +ul.check li > p:not(:first-child) { + display: block; } ol { @@ -744,6 +756,7 @@ pre.fragment { span.tt { white-space: pre; font-family: var(--font-family-monospace); + background-color: var(--fragment-background-color); } .clipboard { @@ -1159,6 +1172,8 @@ tr:not(:first-child) > td.ititle { border-bottom: 1px solid var(--memdecl-border-color); padding-left: 10px; transition: none; + vertical-align: top; + text-align: right; } .memItemRight { @@ -1167,6 +1182,7 @@ tr:not(:first-child) > td.ititle { border-bottom: 1px solid var(--memdecl-border-color); padding-right: 10px; transition: none; + vertical-align: bottom; } tr.heading + tr[class^='memitem'] td.memItemLeft, @@ -1720,7 +1736,6 @@ table.fieldtable { text-align: right; } - .fieldtable td.fielddoc { border-bottom: 1px solid var(--memdef-border-color); } @@ -1750,6 +1765,41 @@ table.fieldtable { border-bottom: 1px solid var(--memdef-border-color); } +/* style requirements page */ + +div.req_title { + text-decoration-line: underline; + text-decoration-style: solid; + text-decoration-color: var(--table-cell-border-color); + text-decoration-thickness: 1px; + font-weight: bold; +} + +table.reqlist tr > td:first-child { + text-align: right; + font-weight: bold; +} + +div.missing_satisfies { + border-left: 8px solid var(--satisfies-color-hl); + border-radius: 4px; + background: var(--satisfies-color-bg); + padding: 10px; + margin: 10px 0px; + overflow: hidden; + margin-left: 0; +} + +div.missing_verifies { + border-left: 8px solid var(--verifies-color-hl); + border-radius: 4px; + background: var(--verifies-color-bg); + padding: 10px; + margin: 10px 0px; + overflow: hidden; + margin-left: 0; +} + /* ----------- navigation breadcrumb styling ----------- */ #nav-path ul { @@ -1914,6 +1964,10 @@ dl.warning dt, dl.attention dt, dl.important dt { color: var(--warning-color-hl); } +dl.warning .tt, dl.attention .tt, dl.important .tt { + background-color: hsl(from var(--warning-color-bg) h s calc(l + var(--fragment-highlight-filter))); +} + dl.note, dl.remark { background: var(--note-color-bg); border-left: 8px solid var(--note-color-hl); @@ -1924,6 +1978,10 @@ dl.note dt, dl.remark dt { color: var(--note-color-hl); } +dl.note .tt, dl.remark .tt { + background-color: hsl(from var(--note-color-bg) h s calc(l + var(--fragment-highlight-filter))); +} + dl.todo { background: var(--todo-color-bg); border-left: 8px solid var(--todo-color-hl); @@ -1934,6 +1992,10 @@ dl.todo dt { color: var(--todo-color-hl); } +dl.todo .tt { + background-color: hsl(from var(--todo-color-bg) h s calc(l + var(--fragment-highlight-filter))); +} + dl.test { background: var(--test-color-bg); border-left: 8px solid var(--test-color-hl); @@ -1944,6 +2006,10 @@ dl.test dt { color: var(--test-color-hl); } +dl.test .tt { + background-color: hsl(from var(--test-color-bg) h s calc(l + var(--fragment-highlight-filter))); +} + dl.bug dt a { color: var(--bug-color-hl) !important; } @@ -1958,6 +2024,10 @@ dl.bug dt a { color: var(--bug-color-hl) !important; } +dl.bug .tt { + background-color: hsl(from var(--bug-color-bg) h s calc(l + var(--fragment-highlight-filter))); +} + dl.deprecated { background: var(--deprecated-color-bg); border-left: 8px solid var(--deprecated-color-hl); @@ -1968,12 +2038,11 @@ dl.deprecated dt a { color: var(--deprecated-color-hl) !important; } -dl.note dd, dl.warning dd, dl.pre dd, dl.post dd, -dl.remark dd, dl.attention dd, dl.important dd, dl.invariant dd, -dl.bug dd, dl.deprecated dd, dl.todo dd, dl.test dd { - margin-inline-start: 0px; +dl.deprecated .tt { + background-color: hsl(from var(--deprecated-color-bg) h s calc(l + var(--fragment-highlight-filter))); } + dl.invariant, dl.pre, dl.post { background: var(--invariant-color-bg); border-left: 8px solid var(--invariant-color-hl); @@ -1984,6 +2053,16 @@ dl.invariant dt, dl.pre dt, dl.post dt { color: var(--invariant-color-hl); } +dl.invariant .tt, dl.pre .tt, dl.post .tt { + background-color: hsl(from var(--invariant-color-bg) h s calc(l + var(--fragment-highlight-filter))); +} + +dl.note dd, dl.warning dd, dl.pre dd, dl.post dd, +dl.remark dd, dl.attention dd, dl.important dd, dl.invariant dd, +dl.bug dd, dl.deprecated dd, dl.todo dd, dl.test dd { + margin-inline-start: 0px; +} + #projectrow { diff --git a/docs/html/doxygen_crawl.html b/docs/html/doxygen_crawl.html index f4404e93..773232da 100644 --- a/docs/html/doxygen_crawl.html +++ b/docs/html/doxygen_crawl.html @@ -4,7 +4,7 @@ Validator / crawler helper - + @@ -282,6 +282,7 @@ + diff --git a/docs/html/enabling_buffer_device_address.html b/docs/html/enabling_buffer_device_address.html index 46613248..6aed2892 100644 --- a/docs/html/enabling_buffer_device_address.html +++ b/docs/html/enabling_buffer_device_address.html @@ -3,7 +3,7 @@ - + Vulkan Memory Allocator: Enabling buffer device address @@ -31,7 +31,7 @@ - + @@ -99,7 +99,7 @@

        -Generated by doxygen 1.14.0 +Generated by doxygen 1.16.1
        diff --git a/docs/html/faq.html b/docs/html/faq.html index 2ac0387a..60ab2d7f 100644 --- a/docs/html/faq.html +++ b/docs/html/faq.html @@ -3,7 +3,7 @@ - + Vulkan Memory Allocator: Frequently asked questions @@ -31,7 +31,7 @@ - + @@ -90,7 +90,7 @@

        While VMA is useful for most applications that use the Vulkan API, there are cases when it may be a better choice not to use it. For example, if the application is very simple, e.g. serving as a sample or a learning exercise to help you understand or teach others the basics of Vulkan, and it creates only a small number of buffers and images, then including VMA may be an overkill. Developing your own memory allocator may also be a good learning exercise.

        What are the benefits of using VMA?

          -
        1. VMA helps in choosing the optimal memory type for your resource (buffer or image). In Vulkan, we have a two-level hierarchy of memory heaps and types with different flags, and each device can expose a different set of those. Implementing logic that would select the best memory type on each platform is a non-trivial task. VMA does that, expecting only a high-level description of the intended usage of your resource. For more information, see Choosing memory type.
          2. +
        2. VMA helps in choosing the optimal memory type for your resource (buffer or image). In Vulkan, we have a two-level hierarchy of memory heaps and types with different flags, and each device can expose a different set of those. Implementing logic that would select the best memory type on each platform is a non-trivial task. VMA does that, expecting only a high-level description of the intended usage of your resource. For more information, see Choosing memory type.
        3. VMA allocates large blocks of VkDeviceMemory and sub-allocates parts of them for your resources. Allocating a new block of device memory may be a time-consuming operation. Some platforms also have a limit on the maximum number of those blocks (VkPhysicalDeviceLimits::maxMemoryAllocationCount) as low as 4096, so allocating a separate one for each resource is not an option. Sub-allocating parts of a memory block requires implementing an allocation algorithm, which is a non-trivial task. VMA does that, using an advanced and efficient algorithm that works well in various use cases.
        4. VMA offers a simple API that allows creating buffers and textures within one function call. In Vulkan, the creation of a resource is a multi-step process. You need to create a VkBuffer or VkImage, ask it for memory requirements, allocate a VkDeviceMemory object, and finally bind the resource to the memory block. VMA does that automatically under a simple API within one function call: vmaCreateBuffer(), vmaCreateImage().
        @@ -103,7 +103,7 @@

        VMA is an STB-style single-header C++ library.

        You can pull the entire GitHub repository, e.g. using Git submodules. The repository contains ancillary files like the Cmake script, Doxygen config file, sample application, test suite, and others. You can compile it as a library and link with your project.

        However, a simpler way is taking the single file "include/vk_mem_alloc.h" and including it in your project. This extensive file contains all you need: a copyright notice, declarations of the public library interface (API), its internal implementation, and even the documentation in form of Doxygen-style comments.

        -

        The "STB style" means not everything is implemented as inline functions in the header file. You need to extract the internal implementation using a special macro. This means that in every .cpp file where you need to use the library you should #include "vk_mem_alloc.h" to include its public interface, but additionally in exactly one .cpp file you should #define VMA_IMPLEMENTATION before this #include to enable its internal implementation. For more information, see Project setup.

        +

        The "STB style" means not everything is implemented as inline functions in the header file. You need to extract the internal implementation using a special macro. This means that in every .cpp file where you need to use the library you should #include "vk_mem_alloc.h" to include its public interface, but additionally in exactly one .cpp file you should #define VMA_IMPLEMENTATION before this #include to enable its internal implementation. For more information, see Project setup.

        Does the library work with C or C++?

        The internal implementation of VMA is written in C++. It is distributed in the source format, so you need a compiler supporting at least C++14 to build it.

        However, the public interface of the library is written in C - using only enums, structs, and global functions, in the same style as Vulkan, so you can use the library in the C code.

        @@ -113,7 +113,7 @@
      • VMA doesn't throw or catch any C++ exceptions. It reports errors by returning a VkResult value instead, just like Vulkan. If you don't use exceptions in your project, your code is not exception-safe, or even if you disable exception handling in the compiler options, you can still use VMA.
      • VMA doesn't use C++ run-time type information like typeid or dynamic_cast, so if you disable RTTI in the compiler options, you can still use the library.
      • VMA uses only a limited subset of standard C and C++ library. It doesn't use STL containers like std::vector, map, or string, either in the public interface nor in the internal implementation. It implements its own containers instead.
        • -
      • If you don't use the default heap memory allocator through malloc/free or new/delete but implement your own allocator instead, you can pass it to VMA and the library will use your functions for every dynamic heap allocation made internally, as well as passing it further to Vulkan functions. For details, see Custom host memory allocator.
        • +
      • If you don't use the default heap memory allocator through malloc/free or new/delete but implement your own allocator instead, you can pass it to VMA and the library will use your functions for every dynamic heap allocation made internally, as well as passing it further to Vulkan functions. For details, see Custom host memory allocator.

      Is it available for other programming languages?

      VMA is a C++ library with C interface in similar style as Vulkan. An object-oriented C++ wrapper or bindings to other programming languages are out of scope of this project, but they are welcome as external projects. Some of them are listed in README.md, "See also" section, including binding to C++, Python, Rust, and Haskell. Before using any of them, please check if they are still maintained and updated to use a recent version of VMA.

      @@ -123,7 +123,7 @@

      No! While VMA is published by AMD, it works on any GPU that supports Vulkan, whether a discrete PC graphics card, a processor integrated graphics, or a mobile SoC. It doesn't give AMD GPUs any advantage over any other GPUs.

      What Vulkan versions and extensions are supported?

      VMA is updated to support the latest versions of Vulkan. It currently supports Vulkan up to 1.4. The library also supports older versions down to the first release of Vulkan 1.0. Defining a higher minimum version support would help simplify the code, but we acknowledge that developers on some platforms like Android still use older versions, so the support is provided for all of them.

      -

      Among many extensions available for Vulkan, only a few interact with memory management. VMA can automatically take advantage of them. Some of them are: VK_EXT_memory_budget, VK_EXT_memory_priority, VK_KHR_external_memory_win32, and VK_KHR_maintenance* extensions that are later promoted to the new versions of the core Vulkan API. To use them, it is your responsibility to validate if they are available on the current system and if so, enable them while creating the Vulkan device object. You also need to pass appropriate VmaAllocatorCreateFlagBits to inform VMA that they are enabled. Then, the library will automatically take advantage of them. For more information and the full list of supported extensions, see Enabling extensions.

      +

      Among many extensions available for Vulkan, only a few interact with memory management. VMA can automatically take advantage of them. Some of them are: VK_EXT_memory_budget, VK_EXT_memory_priority, VK_KHR_external_memory_win32, and VK_KHR_maintenance* extensions that are later promoted to the new versions of the core Vulkan API. To use them, it is your responsibility to validate if they are available on the current system and if so, enable them while creating the Vulkan device object. You also need to pass appropriate VmaAllocatorCreateFlagBits to inform VMA that they are enabled. Then, the library will automatically take advantage of them. For more information and the full list of supported extensions, see Enabling extensions.

      Does it support other graphics APIs, like Microsoft DirectX(R) 12?

      No, but we offer an equivalent library for DirectX 12: D3D12 Memory Allocator. It uses the same core allocation algorithm. It also shares many features with VMA, like the support for custom pools and virtual allocator. However, it is not identical in terms of the features supported. Its API also looks different, because while the interface of VMA is similar in style to Vulkan, the interface of D3D12MA is similar to DirectX 12.

      Is the library lightweight?

      @@ -149,13 +149,13 @@
    2. Try making your allocation using pure Vulkan functions rather than VMA and see if the bug persists.

      3. I found some compilation warnings. How can we fix them?

      -

      Seeing compiler warnings may be annoying to some developers, but it is a design decision to not fix all of them. Due to the nature of the C++ language, certain preprocessor macros can 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. For more information, see Features not supported.

      +

      Seeing compiler warnings may be annoying to some developers, but it is a design decision to not fix all of them. Due to the nature of the C++ language, certain preprocessor macros can 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. For more information, see Features not supported.

      However, if you observe a warning that is really dangerous, e.g., about an implicit conversion from a larger to a smaller integer type, please report it and it will be fixed ASAP.

      -Generated by doxygen 1.14.0 +Generated by doxygen 1.16.1
      diff --git a/docs/html/files.html b/docs/html/files.html index 59195e77..b0e12362 100644 --- a/docs/html/files.html +++ b/docs/html/files.html @@ -3,7 +3,7 @@ - + Vulkan Memory Allocator: File List @@ -31,7 +31,7 @@ - + @@ -83,7 +83,7 @@
      -Generated by doxygen 1.14.0 +Generated by doxygen 1.16.1
      diff --git a/docs/html/functions.html b/docs/html/functions.html index 641dbf75..0930b3eb 100644 --- a/docs/html/functions.html +++ b/docs/html/functions.html @@ -3,7 +3,7 @@ - + Vulkan Memory Allocator: Class Members @@ -31,7 +31,7 @@ - + @@ -121,6 +121,7 @@

      - m -

    When this flag is set, you can create buffers with VK_BUFFER_USAGE_SHADER_DEVICE_ADDRESS_BIT using VMA. The library automatically adds VK_MEMORY_ALLOCATE_DEVICE_ADDRESS_BIT to allocated memory blocks wherever it might be needed.

    -

    For more information, see documentation chapter Enabling buffer device address.

    +

    For more information, see documentation chapter Enabling buffer device address.

    VMA_ALLOCATOR_CREATE_EXT_MEMORY_PRIORITY_BIT 

    Enables usage of VK_EXT_memory_priority extension in the library.

    You may set this flag only if you found available and enabled this device extension, along with VkPhysicalDeviceMemoryPriorityFeaturesEXT::memoryPriority == VK_TRUE, while creating Vulkan device passed as VmaAllocatorCreateInfo::device.

    @@ -357,7 +357,7 @@

    VmaAllocatorCreateInfo::device.

    VMA_ALLOCATOR_CREATE_KHR_EXTERNAL_MEMORY_WIN32_BIT 

    Enables usage of VK_KHR_external_memory_win32 extension in the library.

    -

    You should set this flag if you found available and enabled this device extension, while creating Vulkan device passed as VmaAllocatorCreateInfo::device. For more information, see Interop with other graphics APIs.

    +

    You should set this flag if you found available and enabled this device extension, while creating Vulkan device passed as VmaAllocatorCreateInfo::device. For more information, see Interop with other graphics APIs.

    VMA_ALLOCATOR_CREATE_FLAG_BITS_MAX_ENUM  @@ -608,7 +608,7 @@

    -Generated by doxygen 1.14.0 +Generated by doxygen 1.16.1
    diff --git a/docs/html/group__group__stats.html b/docs/html/group__group__stats.html index be757358..fe60bbbc 100644 --- a/docs/html/group__group__stats.html +++ b/docs/html/group__group__stats.html @@ -3,7 +3,7 @@ - + Vulkan Memory Allocator: Statistics @@ -31,7 +31,7 @@ - + @@ -79,52 +79,52 @@
    -

    API elements that query current status of the allocator, from memory usage, budget, to full dump of the internal state in JSON format. See documentation chapter: Statistics. +

    API elements that query current status of the allocator, from memory usage, budget, to full dump of the internal state in JSON format. See documentation chapter: Statistics. More...

    - + - + - + - +

    Classes

    struct  VmaStatistics
    struct  VmaStatistics
     Calculated statistics of memory usage e.g. in a specific memory type, heap, custom pool, or total. More...
    struct  VmaDetailedStatistics
    struct  VmaDetailedStatistics
     More detailed statistics than VmaStatistics. More...
    struct  VmaTotalStatistics
    struct  VmaTotalStatistics
     General statistics from current state of the Allocator - total memory usage across all memory heaps and types. More...
    struct  VmaBudget
    struct  VmaBudget
     Statistics of current memory usage and available budget for a specific memory heap. More...
    - + - + - + - +

    Typedefs

    typedef struct VmaStatistics VmaStatistics
    typedef struct VmaStatistics VmaStatistics
     Calculated statistics of memory usage e.g. in a specific memory type, heap, custom pool, or total.
    typedef struct VmaDetailedStatistics VmaDetailedStatistics
    typedef struct VmaDetailedStatistics VmaDetailedStatistics
     More detailed statistics than VmaStatistics.
    typedef struct VmaTotalStatistics VmaTotalStatistics
    typedef struct VmaTotalStatistics VmaTotalStatistics
     General statistics from current state of the Allocator - total memory usage across all memory heaps and types.
    typedef struct VmaBudget VmaBudget
    typedef struct VmaBudget VmaBudget
     Statistics of current memory usage and available budget for a specific memory heap.
    - + - + - + - + - + - + - + - +

    Functions

    void vmaCalculateStatistics (VmaAllocator allocator, VmaTotalStatistics *pStats)
    void vmaCalculateStatistics (VmaAllocator allocator, VmaTotalStatistics *pStats)
     Retrieves statistics from current state of the Allocator.
    void vmaGetHeapBudgets (VmaAllocator allocator, VmaBudget *pBudgets)
    void vmaGetHeapBudgets (VmaAllocator allocator, VmaBudget *pBudgets)
     Retrieves information about current memory usage and budget for all memory heaps.
    void vmaGetPoolStatistics (VmaAllocator allocator, VmaPool pool, VmaStatistics *pPoolStats)
    void vmaGetPoolStatistics (VmaAllocator allocator, VmaPool pool, VmaStatistics *pPoolStats)
     Retrieves statistics of existing VmaPool object.
    void vmaCalculatePoolStatistics (VmaAllocator allocator, VmaPool pool, VmaDetailedStatistics *pPoolStats)
    void vmaCalculatePoolStatistics (VmaAllocator allocator, VmaPool pool, VmaDetailedStatistics *pPoolStats)
     Retrieves detailed statistics of existing VmaPool object.
    void vmaBuildVirtualBlockStatsString (VmaVirtualBlock virtualBlock, char **ppStatsString, VkBool32 detailedMap)
    void vmaBuildVirtualBlockStatsString (VmaVirtualBlock virtualBlock, char **ppStatsString, VkBool32 detailedMap)
     Builds and returns a null-terminated string in JSON format with information about given VmaVirtualBlock.
    void vmaFreeVirtualBlockStatsString (VmaVirtualBlock virtualBlock, char *pStatsString)
    void vmaFreeVirtualBlockStatsString (VmaVirtualBlock virtualBlock, char *pStatsString)
     Frees a string returned by vmaBuildVirtualBlockStatsString().
    void vmaBuildStatsString (VmaAllocator allocator, char **ppStatsString, VkBool32 detailedMap)
    void vmaBuildStatsString (VmaAllocator allocator, char **ppStatsString, VkBool32 detailedMap)
     Builds and returns statistics as a null-terminated string in JSON format.
    void vmaFreeStatsString (VmaAllocator allocator, char *pStatsString)
    void vmaFreeStatsString (VmaAllocator allocator, char *pStatsString)

    Detailed Description

    -

    API elements that query current status of the allocator, from memory usage, budget, to full dump of the internal state in JSON format. See documentation chapter: Statistics.

    -

    Typedef Documentation

    +

    API elements that query current status of the allocator, from memory usage, budget, to full dump of the internal state in JSON format. See documentation chapter: Statistics.

    +

    Typedef Documentation

    ◆ VmaBudget

    @@ -448,7 +448,7 @@

    -Generated by doxygen 1.14.0 +Generated by doxygen 1.16.1

    diff --git a/docs/html/group__group__virtual.html b/docs/html/group__group__virtual.html index b5e23cc1..538bc6cf 100644 --- a/docs/html/group__group__virtual.html +++ b/docs/html/group__group__virtual.html @@ -3,7 +3,7 @@ - + Vulkan Memory Allocator: Virtual allocator @@ -31,7 +31,7 @@ - + @@ -80,47 +80,47 @@
    -

    API elements related to the mechanism of Virtual allocator - using the core allocation algorithm for user-defined purpose without allocating any real GPU memory. +

    API elements related to the mechanism of Virtual allocator - using the core allocation algorithm for user-defined purpose without allocating any real GPU memory. More...

    - + - + - + - + - +

    Classes

    struct  VmaVirtualBlockCreateInfo
    struct  VmaVirtualBlockCreateInfo
     Parameters of created VmaVirtualBlock object to be passed to vmaCreateVirtualBlock(). More...
    struct  VmaVirtualAllocationCreateInfo
    struct  VmaVirtualAllocationCreateInfo
     Parameters of created virtual allocation to be passed to vmaVirtualAllocate(). More...
    struct  VmaVirtualAllocationInfo
    struct  VmaVirtualAllocationInfo
     Parameters of an existing virtual allocation, returned by vmaGetVirtualAllocationInfo(). More...
    struct  VmaVirtualAllocation
    struct  VmaVirtualAllocation
     Represents single memory allocation done inside VmaVirtualBlock. More...
    struct  VmaVirtualBlock
    struct  VmaVirtualBlock
     Handle to a virtual block object that allows to use core allocation algorithm without allocating any real GPU memory. More...
    - + - + - + - + - + - + - +

    Typedefs

    typedef enum VmaVirtualBlockCreateFlagBits VmaVirtualBlockCreateFlagBits
    typedef enum VmaVirtualBlockCreateFlagBits VmaVirtualBlockCreateFlagBits
     Flags to be passed as VmaVirtualBlockCreateInfo::flags.
    typedef VkFlags VmaVirtualBlockCreateFlags
    typedef VkFlags VmaVirtualBlockCreateFlags
     Flags to be passed as VmaVirtualBlockCreateInfo::flags. See VmaVirtualBlockCreateFlagBits.
    typedef enum VmaVirtualAllocationCreateFlagBits VmaVirtualAllocationCreateFlagBits
    typedef enum VmaVirtualAllocationCreateFlagBits VmaVirtualAllocationCreateFlagBits
     Flags to be passed as VmaVirtualAllocationCreateInfo::flags.
    typedef VkFlags VmaVirtualAllocationCreateFlags
    typedef VkFlags VmaVirtualAllocationCreateFlags
     Flags to be passed as VmaVirtualAllocationCreateInfo::flags. See VmaVirtualAllocationCreateFlagBits.
    typedef struct VmaVirtualBlockCreateInfo VmaVirtualBlockCreateInfo
    typedef struct VmaVirtualBlockCreateInfo VmaVirtualBlockCreateInfo
     Parameters of created VmaVirtualBlock object to be passed to vmaCreateVirtualBlock().
    typedef struct VmaVirtualAllocationCreateInfo VmaVirtualAllocationCreateInfo
    typedef struct VmaVirtualAllocationCreateInfo VmaVirtualAllocationCreateInfo
     Parameters of created virtual allocation to be passed to vmaVirtualAllocate().
    typedef struct VmaVirtualAllocationInfo VmaVirtualAllocationInfo
    typedef struct VmaVirtualAllocationInfo VmaVirtualAllocationInfo
     Parameters of an existing virtual allocation, returned by vmaGetVirtualAllocationInfo().
    - -

    Enumerations

    enum  VmaVirtualBlockCreateFlagBits { VMA_VIRTUAL_BLOCK_CREATE_LINEAR_ALGORITHM_BIT = 0x00000001 +
    enum  VmaVirtualBlockCreateFlagBits { VMA_VIRTUAL_BLOCK_CREATE_LINEAR_ALGORITHM_BIT = 0x00000001 , VMA_VIRTUAL_BLOCK_CREATE_ALGORITHM_MASK , VMA_VIRTUAL_BLOCK_CREATE_FLAG_BITS_MAX_ENUM = 0x7FFFFFFF }
     Flags to be passed as VmaVirtualBlockCreateInfo::flags. More...
    enum  VmaVirtualAllocationCreateFlagBits {
    +
    enum  VmaVirtualAllocationCreateFlagBits {
      VMA_VIRTUAL_ALLOCATION_CREATE_UPPER_ADDRESS_BIT = VMA_ALLOCATION_CREATE_UPPER_ADDRESS_BIT , VMA_VIRTUAL_ALLOCATION_CREATE_STRATEGY_MIN_MEMORY_BIT = VMA_ALLOCATION_CREATE_STRATEGY_MIN_MEMORY_BIT , VMA_VIRTUAL_ALLOCATION_CREATE_STRATEGY_MIN_TIME_BIT = VMA_ALLOCATION_CREATE_STRATEGY_MIN_TIME_BIT @@ -134,30 +134,30 @@
    - + - + - + - + - + - + - + - + - + - +

    Functions

    VkResult vmaCreateVirtualBlock (const VmaVirtualBlockCreateInfo *pCreateInfo, VmaVirtualBlock *pVirtualBlock)
    VkResult vmaCreateVirtualBlock (const VmaVirtualBlockCreateInfo *pCreateInfo, VmaVirtualBlock *pVirtualBlock)
     Creates new VmaVirtualBlock object.
    void vmaDestroyVirtualBlock (VmaVirtualBlock virtualBlock)
    void vmaDestroyVirtualBlock (VmaVirtualBlock virtualBlock)
     Destroys VmaVirtualBlock object.
    VkBool32 vmaIsVirtualBlockEmpty (VmaVirtualBlock virtualBlock)
    VkBool32 vmaIsVirtualBlockEmpty (VmaVirtualBlock virtualBlock)
     Returns true of the VmaVirtualBlock is empty - contains 0 virtual allocations and has all its space available for new allocations.
    void vmaGetVirtualAllocationInfo (VmaVirtualBlock virtualBlock, VmaVirtualAllocation allocation, VmaVirtualAllocationInfo *pVirtualAllocInfo)
    void vmaGetVirtualAllocationInfo (VmaVirtualBlock virtualBlock, VmaVirtualAllocation allocation, VmaVirtualAllocationInfo *pVirtualAllocInfo)
     Returns information about a specific virtual allocation within a virtual block, like its size and pUserData pointer.
    VkResult vmaVirtualAllocate (VmaVirtualBlock virtualBlock, const VmaVirtualAllocationCreateInfo *pCreateInfo, VmaVirtualAllocation *pAllocation, VkDeviceSize *pOffset)
    VkResult vmaVirtualAllocate (VmaVirtualBlock virtualBlock, const VmaVirtualAllocationCreateInfo *pCreateInfo, VmaVirtualAllocation *pAllocation, VkDeviceSize *pOffset)
     Allocates new virtual allocation inside given VmaVirtualBlock.
    void vmaVirtualFree (VmaVirtualBlock virtualBlock, VmaVirtualAllocation allocation)
    void vmaVirtualFree (VmaVirtualBlock virtualBlock, VmaVirtualAllocation allocation)
     Frees virtual allocation inside given VmaVirtualBlock.
    void vmaClearVirtualBlock (VmaVirtualBlock virtualBlock)
    void vmaClearVirtualBlock (VmaVirtualBlock virtualBlock)
     Frees all virtual allocations inside given VmaVirtualBlock.
    void vmaSetVirtualAllocationUserData (VmaVirtualBlock virtualBlock, VmaVirtualAllocation allocation, void *pUserData)
    void vmaSetVirtualAllocationUserData (VmaVirtualBlock virtualBlock, VmaVirtualAllocation allocation, void *pUserData)
     Changes custom pointer associated with given virtual allocation.
    void vmaGetVirtualBlockStatistics (VmaVirtualBlock virtualBlock, VmaStatistics *pStats)
    void vmaGetVirtualBlockStatistics (VmaVirtualBlock virtualBlock, VmaStatistics *pStats)
     Calculates and returns statistics about virtual allocations and memory usage in given VmaVirtualBlock.
    void vmaCalculateVirtualBlockStatistics (VmaVirtualBlock virtualBlock, VmaDetailedStatistics *pStats)
    void vmaCalculateVirtualBlockStatistics (VmaVirtualBlock virtualBlock, VmaDetailedStatistics *pStats)
     Calculates and returns detailed statistics about virtual allocations and memory usage in given VmaVirtualBlock.

    Detailed Description

    -

    API elements related to the mechanism of Virtual allocator - using the core allocation algorithm for user-defined purpose without allocating any real GPU memory.

    -

    Typedef Documentation

    +

    API elements related to the mechanism of Virtual allocator - using the core allocation algorithm for user-defined purpose without allocating any real GPU memory.

    +

    Typedef Documentation

    ◆ VmaVirtualAllocationCreateFlagBits

    @@ -318,7 +318,7 @@

    EnumeratorVMA_VIRTUAL_BLOCK_CREATE_LINEAR_ALGORITHM_BIT 

    Enables alternative, linear allocation algorithm in this virtual block.

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

    -

    By using this flag, you can achieve behavior of free-at-once, stack, ring buffer, and double stack. For details, see documentation chapter Linear allocation algorithm.

    +

    By using this flag, you can achieve behavior of free-at-once, stack, ring buffer, and double stack. For details, see documentation chapter Linear allocation algorithm.

    VMA_VIRTUAL_BLOCK_CREATE_ALGORITHM_MASK 

    Bit mask to extract only ALGORITHM bits from entire set of flags.

    @@ -593,7 +593,7 @@

    -Generated by doxygen 1.14.0 +Generated by doxygen 1.16.1

    diff --git a/docs/html/index.html b/docs/html/index.html index a8297ef9..87e6a53d 100644 --- a/docs/html/index.html +++ b/docs/html/index.html @@ -3,7 +3,7 @@ - + Vulkan Memory Allocator: Vulkan Memory Allocator @@ -31,7 +31,7 @@ - + @@ -75,104 +75,104 @@

    Version 3.4.0-development

    -

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

    Copyright (c) 2017-2026 Advanced Micro Devices, Inc. All rights reserved.
    License: MIT
    See also: product page on GPUOpen, repository on GitHub

    API documentation divided into groups: Topics

    General documentation chapters:

    -Generated by doxygen 1.14.0 +Generated by doxygen 1.16.1
    diff --git a/docs/html/memory_mapping.html b/docs/html/memory_mapping.html index bdc0de94..ea1c337f 100644 --- a/docs/html/memory_mapping.html +++ b/docs/html/memory_mapping.html @@ -3,7 +3,7 @@ - + Vulkan Memory Allocator: Memory mapping @@ -31,7 +31,7 @@ - + @@ -157,9 +157,9 @@

    // Buffer is already mapped. You can access its memory.
    memcpy(allocInfo.pMappedData, &constantBufferData, sizeof(constantBufferData));
    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:613
    -
    VmaAllocationInfo
    Definition vk_mem_alloc.h:1413
    -
    VmaAllocationInfo::pMappedData
    void * pMappedData
    Pointer to the beginning of this allocation as mapped data.
    Definition vk_mem_alloc.h:1455
    -
    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.
    +
    VmaAllocationInfo
    Definition vk_mem_alloc.h:1432
    +
    VmaAllocationInfo::pMappedData
    void * pMappedData
    Pointer to the beginning of this allocation as mapped data.
    Definition vk_mem_alloc.h:1474
    +
    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

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

    @@ -169,7 +169,7 @@

    -Generated by doxygen 1.14.0 +Generated by doxygen 1.16.1
    diff --git a/docs/html/other_api_interop.html b/docs/html/other_api_interop.html index f978c7ec..c2ca2924 100644 --- a/docs/html/other_api_interop.html +++ b/docs/html/other_api_interop.html @@ -3,7 +3,7 @@ - + Vulkan Memory Allocator: Interop with other graphics APIs @@ -31,7 +31,7 @@ - + @@ -88,11 +88,11 @@

    #include <vulkan/vulkan_win32.h>

    2) Check if "VK_KHR_external_memory_win32" is available among device extensions. Enable it when creating the VkDevice object.

    3) Enable the usage of this extension in VMA by setting flag VMA_ALLOCATOR_CREATE_KHR_EXTERNAL_MEMORY_WIN32_BIT when calling vmaCreateAllocator().

    -

    4) Make sure that VMA has access to the vkGetMemoryWin32HandleKHR function by either enabling VMA_DYNAMIC_VULKAN_FUNCTIONS macro or setting VmaVulkanFunctions::vkGetMemoryWin32HandleKHR explicitly. For more information, see Importing Vulkan functions.

    +

    4) Make sure that VMA has access to the vkGetMemoryWin32HandleKHR function by either enabling VMA_DYNAMIC_VULKAN_FUNCTIONS macro or setting VmaVulkanFunctions::vkGetMemoryWin32HandleKHR explicitly. For more information, see Importing Vulkan functions.

    Preparations

    You can find example usage among tests, in file "Tests.cpp", function TestWin32Handles().

    -

    To use the extenion, buffers need to be created with VkExternalMemoryBufferCreateInfoKHR attached to their pNext chain, and memory allocations need to be made with VkExportMemoryAllocateInfoKHR attached to their pNext chain. To make use of them, you need to use Custom memory pools. Example:

    +

    To use the extenion, buffers need to be created with VkExternalMemoryBufferCreateInfoKHR attached to their pNext chain, and memory allocations need to be made with VkExportMemoryAllocateInfoKHR attached to their pNext chain. To make use of them, you need to use Custom memory pools. Example:

    constexpr VkExternalMemoryHandleTypeFlagsKHR handleType =
    VK_EXTERNAL_MEMORY_HANDLE_TYPE_OPAQUE_WIN32_BIT_KHR;
    @@ -140,9 +140,9 @@

    VMA_MEMORY_USAGE_AUTO
    @ VMA_MEMORY_USAGE_AUTO
    Definition vk_mem_alloc.h:553

    VmaAllocationCreateInfo
    Parameters of new VmaAllocation.
    Definition vk_mem_alloc.h:1294
    VmaAllocationCreateInfo::usage
    VmaMemoryUsage usage
    Intended usage of memory.
    Definition vk_mem_alloc.h:1302
    -
    VmaPoolCreateInfo
    Describes parameter of created VmaPool.
    Definition vk_mem_alloc.h:1345
    -
    VmaPoolCreateInfo::memoryTypeIndex
    uint32_t memoryTypeIndex
    Vulkan memory type index to allocate this pool from.
    Definition vk_mem_alloc.h:1348
    -
    VmaPoolCreateInfo::pMemoryAllocateNext
    void *VkMemoryAllocateInfo pMemoryAllocateNext
    Additional pNext chain to be attached to VkMemoryAllocateInfo used for every allocation made by this ...
    Definition vk_mem_alloc.h:1397
    +
    VmaPoolCreateInfo
    Describes parameter of created VmaPool.
    Definition vk_mem_alloc.h:1358
    +
    VmaPoolCreateInfo::memoryTypeIndex
    uint32_t memoryTypeIndex
    Vulkan memory type index to allocate this pool from.
    Definition vk_mem_alloc.h:1361
    +
    VmaPoolCreateInfo::pMemoryAllocateNext
    void *VkMemoryAllocateInfo pMemoryAllocateNext
    Additional pNext chain to be attached to VkMemoryAllocateInfo used for every allocation made by this ...
    Definition vk_mem_alloc.h:1416
    VmaPool
    Represents custom memory pool.

    Note that the structure passed as VmaPoolCreateInfo::pMemoryAllocateNext must remain alive and unchanged for the whole lifetime of the custom pool, because it will be used when the pool allocates a new device memory block. No copy is made internally. This is why variable exportMemAllocInfo is defined as static.

    If you want to export all memory allocated by VMA from certain memory types, including dedicated allocations and allocations made from default pools, an alternative solution is to fill in VmaAllocatorCreateInfo::pTypeExternalMemoryHandleTypes. It should point to an array with VkExternalMemoryHandleTypeFlagsKHR to be automatically passed by the library through VkExportMemoryAllocateInfoKHR on each allocation made from a specific memory type. You should not mix these two methods in a way that allows to apply both to the same memory type. Otherwise, VkExportMemoryAllocateInfoKHR structure would be attached twice to the pNext chain of VkMemoryAllocateInfo.

    @@ -176,6 +176,7 @@

    VmaAllocationCreateInfo::pool
    VmaPool pool
    Pool that this allocation should be created in.
    Definition vk_mem_alloc.h:1326
    VmaAllocation
    Represents single memory allocation.

    If you need each allocation to have its own device memory block and start at offset 0, you can still do by using VMA_ALLOCATION_CREATE_DEDICATED_MEMORY_BIT flag. It works also with custom pools.

    +

    Alternatively, you can use convenient functions vmaCreateDedicatedBuffer(), vmaCreateDedicatedImage() that always allocate dedicated memory for the buffer/image created, and also allow specifying custom pNext chain for the VkMemoryAllocateInfo structure.

    Exporting Win32 handle

    After the allocation is created, you can acquire a Win32 HANDLE to the VkDeviceMemory block it belongs to. VMA function vmaGetMemoryWin32Handle2() is a replacement of the Vulkan function vkGetMemoryWin32HandleKHR.

    @@ -196,8 +197,8 @@

    Custom alignment

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

    -

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

    -

    If you want to create a buffer with a specific minimum alignment out of default pools, you can use special function vmaCreateBufferWithAlignment(), which takes additional parameter minAlignment.

    +

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

    +

    If you want to create a buffer/image/allocate memory with a specific minimum alignment out of default pools, you can use VmaAllocationCreateInfo::minAlignment.

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

    Extended allocation information

    @@ -236,7 +237,7 @@

    -Generated by doxygen 1.14.0 +Generated by doxygen 1.16.1
    diff --git a/docs/html/pages.html b/docs/html/pages.html index a32f44bd..ff608a58 100644 --- a/docs/html/pages.html +++ b/docs/html/pages.html @@ -3,7 +3,7 @@ - + Vulkan Memory Allocator: Related Pages @@ -31,7 +31,7 @@ - + @@ -82,7 +82,7 @@
    -Generated by doxygen 1.14.0 +Generated by doxygen 1.16.1
    diff --git a/docs/html/quick_start.html b/docs/html/quick_start.html index d4f1c90a..aa775942 100644 --- a/docs/html/quick_start.html +++ b/docs/html/quick_start.html @@ -3,7 +3,7 @@ - + Vulkan Memory Allocator: Quick start @@ -31,7 +31,7 @@ - + @@ -106,7 +106,7 @@

    Selecting Vulkan version

    VMA supports Vulkan version down to 1.0, for backward compatibility. If you want to use higher version, you need to inform the library about it. This is a two-step process.

    -

    Step 1: Compile time. By default, VMA compiles with code supporting the highest Vulkan version found in the included <vulkan/vulkan.h> that is also supported by the library. If this is OK, you don't need to do anything. However, if you want to compile VMA as if only some lower Vulkan version was available, define macro VMA_VULKAN_VERSION before every #include "vk_mem_alloc.h". It should have decimal numeric value in form of ABBBCCC, where A = major, BBB = minor, CCC = patch Vulkan version. For example, to compile against Vulkan 1.2:

    +

    Step 1: Compile time. By default, VMA compiles with code supporting the highest Vulkan version found in the included <vulkan/vulkan.h> that is also supported by the library. If this is OK, you don't need to do anything. However, if you want to compile VMA as if only some lower Vulkan version was available, define macro VMA_VULKAN_VERSION before every #include "vk_mem_alloc.h". It should have decimal numeric value in form of ABBBCCC, where A = major, BBB = minor, CCC = patch Vulkan version. For example, to compile against Vulkan 1.2:

    #define VMA_VULKAN_VERSION 1002000 // Vulkan 1.2
    #include "vk_mem_alloc.h"

    Step 2: Runtime. Even when compiled with higher Vulkan version available, VMA can use only features of a lower version, which is configurable during creation of the VmaAllocator object. By default, only Vulkan 1.0 is used. To initialize the allocator with support for higher Vulkan version, you need to set member VmaAllocatorCreateInfo::vulkanApiVersion to an appropriate value, e.g. using constants like VK_API_VERSION_1_2. See code sample below.

    @@ -200,7 +200,7 @@

    VmaAllocator
    Represents main object of this library initialized.

    Other configuration options

    -

    There are additional configuration options available through preprocessor macros that you can define before including VMA header and through parameters passed in VmaAllocatorCreateInfo. They include a possibility to use your own callbacks for host memory allocations (VkAllocationCallbacks), callbacks for device memory allocations (instead of vkAllocateMemory, vkFreeMemory), or your custom VMA_ASSERT macro, among others. For more information, see: Configuration.

    +

    There are additional configuration options available through preprocessor macros that you can define before including VMA header and through parameters passed in VmaAllocatorCreateInfo. They include a possibility to use your own callbacks for host memory allocations (VkAllocationCallbacks), callbacks for device memory allocations (instead of vkAllocateMemory, vkFreeMemory), or your custom VMA_ASSERT macro, among others. For more information, see: Configuration.

    Resource allocation

    When you want to create a buffer or image:

    @@ -227,12 +227,12 @@

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

    vmaDestroyBuffer(allocator, buffer, allocation);
    vmaDestroyBuffer
    void vmaDestroyBuffer(VmaAllocator allocator, VkBuffer buffer, VmaAllocation allocation)
    Destroys Vulkan buffer and frees allocated memory.
    -

    If you need to map the buffer, you must set flag VMA_ALLOCATION_CREATE_HOST_ACCESS_SEQUENTIAL_WRITE_BIT or VMA_ALLOCATION_CREATE_HOST_ACCESS_RANDOM_BIT in VmaAllocationCreateInfo::flags. There are many additional parameters that can control the choice of memory type to be used for the allocation and other features. For more information, see documentation chapters: Choosing memory type, Memory mapping.

    +

    If you need to map the buffer, you must set flag VMA_ALLOCATION_CREATE_HOST_ACCESS_SEQUENTIAL_WRITE_BIT or VMA_ALLOCATION_CREATE_HOST_ACCESS_RANDOM_BIT in VmaAllocationCreateInfo::flags. There are many additional parameters that can control the choice of memory type to be used for the allocation and other features. For more information, see documentation chapters: Choosing memory type, Memory mapping.

    -Generated by doxygen 1.14.0 +Generated by doxygen 1.16.1
    diff --git a/docs/html/resource_aliasing.html b/docs/html/resource_aliasing.html index 30e90324..efa0a320 100644 --- a/docs/html/resource_aliasing.html +++ b/docs/html/resource_aliasing.html @@ -3,7 +3,7 @@ - + Vulkan Memory Allocator: Resource aliasing (overlap) @@ -31,7 +31,7 @@ - + @@ -164,7 +164,7 @@
    -Generated by doxygen 1.14.0 +Generated by doxygen 1.16.1
    diff --git a/docs/html/search/all_b.js b/docs/html/search/all_b.js index e32840de..91730511 100644 --- a/docs/html/search/all_b.js +++ b/docs/html/search/all_b.js @@ -25,8 +25,9 @@ var searchData= ['memorytype_22',['memoryType',['../struct_vma_total_statistics.html#acb70e5b7fe543813ed8ba9282640969d',1,'VmaTotalStatistics::memoryType'],['../struct_vma_allocation_info.html#a7f6b0aa58c135e488e6b40a388dad9d5',1,'VmaAllocationInfo::memoryType']]], ['memorytypebits_23',['memoryTypeBits',['../struct_vma_allocation_create_info.html#a3bf940c0271d85d6ba32a4d820075055',1,'VmaAllocationCreateInfo']]], ['memorytypeindex_24',['memoryTypeIndex',['../struct_vma_pool_create_info.html#a596fa76b685d3f1f688f84a709a5b319',1,'VmaPoolCreateInfo']]], - ['minallocationalignment_25',['minAllocationAlignment',['../struct_vma_pool_create_info.html#ade3eca546f0c6ab4e8fbf20eb6d854cb',1,'VmaPoolCreateInfo']]], - ['minblockcount_26',['minBlockCount',['../struct_vma_pool_create_info.html#ad8006fb803185c0a699d30f3e9a865ae',1,'VmaPoolCreateInfo']]], - ['more_20information_27',['More information',['../vk_amd_device_coherent_memory.html#vk_amd_device_coherent_memory_more_information',1,'More information'],['../enabling_buffer_device_address.html#enabling_buffer_device_address_more_information',1,'More information']]], - ['movecount_28',['moveCount',['../struct_vma_defragmentation_pass_move_info.html#a1b3e18c23f9691f35baf183e615c4408',1,'VmaDefragmentationPassMoveInfo']]] + ['minalignment_25',['minAlignment',['../struct_vma_allocation_create_info.html#a4fa1895486efac8c128dcffad46706a0',1,'VmaAllocationCreateInfo']]], + ['minallocationalignment_26',['minAllocationAlignment',['../struct_vma_pool_create_info.html#ade3eca546f0c6ab4e8fbf20eb6d854cb',1,'VmaPoolCreateInfo']]], + ['minblockcount_27',['minBlockCount',['../struct_vma_pool_create_info.html#ad8006fb803185c0a699d30f3e9a865ae',1,'VmaPoolCreateInfo']]], + ['more_20information_28',['More information',['../vk_amd_device_coherent_memory.html#vk_amd_device_coherent_memory_more_information',1,'More information'],['../enabling_buffer_device_address.html#enabling_buffer_device_address_more_information',1,'More information']]], + ['movecount_29',['moveCount',['../struct_vma_defragmentation_pass_move_info.html#a1b3e18c23f9691f35baf183e615c4408',1,'VmaDefragmentationPassMoveInfo']]] ]; diff --git a/docs/html/search/search.css b/docs/html/search/search.css index 956f31f9..043d32d9 100644 --- a/docs/html/search/search.css +++ b/docs/html/search/search.css @@ -291,7 +291,6 @@ iframe#MSearchResults { div.SRPage { margin: 5px 2px; - /*background-color: var(--search-results-background-color);*/ } .SRChildren { diff --git a/docs/html/search/variables_5.js b/docs/html/search/variables_5.js index a9e9f976..e5b2ec1a 100644 --- a/docs/html/search/variables_5.js +++ b/docs/html/search/variables_5.js @@ -7,7 +7,8 @@ var searchData= ['memorytype_4',['memoryType',['../struct_vma_total_statistics.html#acb70e5b7fe543813ed8ba9282640969d',1,'VmaTotalStatistics::memoryType'],['../struct_vma_allocation_info.html#a7f6b0aa58c135e488e6b40a388dad9d5',1,'VmaAllocationInfo::memoryType']]], ['memorytypebits_5',['memoryTypeBits',['../struct_vma_allocation_create_info.html#a3bf940c0271d85d6ba32a4d820075055',1,'VmaAllocationCreateInfo']]], ['memorytypeindex_6',['memoryTypeIndex',['../struct_vma_pool_create_info.html#a596fa76b685d3f1f688f84a709a5b319',1,'VmaPoolCreateInfo']]], - ['minallocationalignment_7',['minAllocationAlignment',['../struct_vma_pool_create_info.html#ade3eca546f0c6ab4e8fbf20eb6d854cb',1,'VmaPoolCreateInfo']]], - ['minblockcount_8',['minBlockCount',['../struct_vma_pool_create_info.html#ad8006fb803185c0a699d30f3e9a865ae',1,'VmaPoolCreateInfo']]], - ['movecount_9',['moveCount',['../struct_vma_defragmentation_pass_move_info.html#a1b3e18c23f9691f35baf183e615c4408',1,'VmaDefragmentationPassMoveInfo']]] + ['minalignment_7',['minAlignment',['../struct_vma_allocation_create_info.html#a4fa1895486efac8c128dcffad46706a0',1,'VmaAllocationCreateInfo']]], + ['minallocationalignment_8',['minAllocationAlignment',['../struct_vma_pool_create_info.html#ade3eca546f0c6ab4e8fbf20eb6d854cb',1,'VmaPoolCreateInfo']]], + ['minblockcount_9',['minBlockCount',['../struct_vma_pool_create_info.html#ad8006fb803185c0a699d30f3e9a865ae',1,'VmaPoolCreateInfo']]], + ['movecount_10',['moveCount',['../struct_vma_defragmentation_pass_move_info.html#a1b3e18c23f9691f35baf183e615c4408',1,'VmaDefragmentationPassMoveInfo']]] ]; diff --git a/docs/html/statistics.html b/docs/html/statistics.html index 14547b78..61c48205 100644 --- a/docs/html/statistics.html +++ b/docs/html/statistics.html @@ -3,7 +3,7 @@ - + Vulkan Memory Allocator: Statistics @@ -31,7 +31,7 @@ - + @@ -81,7 +81,7 @@

    This library contains several functions that return information about its internal state, especially the amount of memory allocated from Vulkan.

    Numeric statistics

    -

    If you need to obtain basic statistics about memory usage per heap, together with current budget, you can call function vmaGetHeapBudgets() and inspect structure VmaBudget. This is useful to keep track of memory usage and stay within budget (see also Staying within budget). Example:

    +

    If you need to obtain basic statistics about memory usage per heap, together with current budget, you can call function vmaGetHeapBudgets() and inspect structure VmaBudget. This is useful to keep track of memory usage and stay within budget (see also Staying within budget). Example:

    uint32_t heapIndex = ...
    VmaBudget budgets[VK_MAX_MEMORY_HEAPS];
    @@ -102,14 +102,14 @@

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

    JSON dump

    -

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

    +

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

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

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

    -Generated by doxygen 1.14.0 +Generated by doxygen 1.16.1
    diff --git a/docs/html/staying_within_budget.html b/docs/html/staying_within_budget.html index 03b5b3ec..6c898ffc 100644 --- a/docs/html/staying_within_budget.html +++ b/docs/html/staying_within_budget.html @@ -3,7 +3,7 @@ - + Vulkan Memory Allocator: Staying within budget @@ -31,7 +31,7 @@ - + @@ -103,12 +103,12 @@

    VMA_ALLOCATION_CREATE_WITHIN_BUDGET_BIT flag. With it, the allocation is not made if it would exceed the budget or if the budget is already exceeded. VMA then tries to make the allocation from the next eligible Vulkan memory type. If all of them fail, the call then fails with VK_ERROR_OUT_OF_DEVICE_MEMORY. Example usage pattern may be to pass the VMA_ALLOCATION_CREATE_WITHIN_BUDGET_BIT flag when creating resources that are not essential for the application (e.g. the texture of a specific object) and not to pass it when creating critically important resources (e.g. render targets).

    On AMD graphics cards there is a custom vendor extension available: VK_AMD_memory_overallocation_behavior that allows to control the behavior of the Vulkan implementation in out-of-memory cases - whether it should fail with an error code or still allow the allocation. Usage of this extension involves only passing extra structure on Vulkan device creation, so it is out of scope of this library.

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

    -
    Note
    Creating Custom memory pools with VmaPoolCreateInfo::minBlockCount set to more than 0 will currently try to allocate memory blocks without checking whether they fit within budget.
    +
    Note
    Creating Custom memory pools with VmaPoolCreateInfo::minBlockCount set to more than 0 will currently try to allocate memory blocks without checking whether they fit within budget.
    -Generated by doxygen 1.14.0 +Generated by doxygen 1.16.1
    diff --git a/docs/html/struct_vma_allocation.html b/docs/html/struct_vma_allocation.html index 19298f14..a3e4990e 100644 --- a/docs/html/struct_vma_allocation.html +++ b/docs/html/struct_vma_allocation.html @@ -3,7 +3,7 @@ - + Vulkan Memory Allocator: VmaAllocation Struct Reference @@ -31,7 +31,7 @@ - + @@ -80,7 +80,7 @@

    Detailed Description

    Represents single memory allocation.

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

    -

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

    +

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

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

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

    The documentation for this struct was generated from the following file: