diff --git a/README.md b/README.md index 31928c3..3c778a2 100644 --- a/README.md +++ b/README.md @@ -42,6 +42,7 @@ Additional features: - Customization: Predefine appropriate macros to provide your own implementation of all external facilities used by the library, from assert, mutex, and atomic, to vector and linked list. - Support for memory mapping, reference-counted internally. Support for persistently mapped memory: Just allocate with appropriate flag and you get access to mapped pointer. - Support for non-coherent memory. Functions that flush/invalidate memory. `nonCoherentAtomSize` is respected automatically. +- Support for resource aliasing (overlap). - Support for sparse binding and sparse residency: Convenience functions that allocate or free multiple memory pages at once. - Custom memory pools: Create a pool with desired parameters (e.g. fixed or limited maximum size) and allocate memory out of it. - Linear allocator: Create a pool with linear algorithm and use it for much faster allocations and deallocations in free-at-once, stack, double stack, or ring buffer fashion. diff --git a/docs/gfx/Aliasing.png b/docs/gfx/Aliasing.png new file mode 100644 index 0000000..5f37edb Binary files /dev/null and b/docs/gfx/Aliasing.png differ diff --git a/docs/html/allocation_annotation.html b/docs/html/allocation_annotation.html index ee85a63..b111945 100644 --- a/docs/html/allocation_annotation.html +++ b/docs/html/allocation_annotation.html @@ -116,18 +116,18 @@ Allocation names
+ Vulkan Memory Allocator
+
+ |
+
New explicit graphics APIs (Vulkan and Direct3D 12), thanks to manual memory management, give an opportunity to alias (overlap) multiple resources in the same region of memory - a feature not available in the old APIs (Direct3D 11, OpenGL). It can be useful to save video memory, but it must be used with caution.
+For example, if you know the flow of your whole render frame in advance, you are going to use some intermediate textures or buffers only during a small range of render passes, and you know these ranges don't overlap in time, you can bind these resources to the same place in memory, even if they have completely different parameters (width, height, format etc.).
+ +Such scenario is possible using VMA, but you need to create your images manually. Then you need to calculate parameters of an allocation to be made using formula:
+Following example shows two different images bound to the same place in memory, allocated to fit largest of them.
+Remember that using resouces that alias in memory requires proper synchronization. You need to issue a memory barrier to make sure commands that use img1
and img2
don't overlap on GPU timeline. You also need to treat a resource after aliasing as uninitialized - containing garbage data. For example, if you use img1
and then want to use img2
, you need to issue an image memory barrier for img2
with oldLayout
= VK_IMAGE_LAYOUT_UNDEFINED
.
Additional considerations:
+VK_IMAGE_CREATE_ALIAS_BIT
flag.memoryTypeBits
returned in memory requirements of each resource to make sure the bits overlap. Some GPUs may expose multiple memory types suitable e.g. only for buffers or images with COLOR_ATTACHMENT
usage, so the sets of memory types supported by your resources may be disjoint. Aliasing them is not possible in that case. This function is similar to vmaBindBufferMemory(), but it provides additional parameters.
-If pNext
is not null, VmaAllocator object must have been created with VMA_ALLOCATOR_CREATE_KHR_BIND_MEMORY2_BIT flag or with VmaAllocatorCreateInfo::vulkanApiVersion == VK_API_VERSION_1_1
. Otherwise the call fails.
If pNext
is not null, VmaAllocator object must have been created with VMA_ALLOCATOR_CREATE_KHR_BIND_MEMORY2_BIT flag or with VmaAllocatorCreateInfo::vulkanApiVersion >= VK_API_VERSION_1_1
. Otherwise the call fails.
This function is similar to vmaBindImageMemory(), but it provides additional parameters.
-If pNext
is not null, VmaAllocator object must have been created with VMA_ALLOCATOR_CREATE_KHR_BIND_MEMORY2_BIT flag or with VmaAllocatorCreateInfo::vulkanApiVersion == VK_API_VERSION_1_1
. Otherwise the call fails.
If pNext
is not null, VmaAllocator object must have been created with VMA_ALLOCATOR_CREATE_KHR_BIND_MEMORY2_BIT flag or with VmaAllocatorCreateInfo::vulkanApiVersion >= VK_API_VERSION_1_1
. Otherwise the call fails.