From 66afe099f1cf1f79c270471e9c0f02139072057d Mon Sep 17 00:00:00 2001
From: Adam Sawicki <adam.sawicki@amd.com>
Date: Mon, 6 Mar 2023 11:43:13 +0100
Subject: [PATCH] Improved documentation chapter "Resource aliasing (overlap)"

---
 docs/html/resource_aliasing.html | 3 ++-
 include/vk_mem_alloc.h           | 6 ++++++
 2 files changed, 8 insertions(+), 1 deletion(-)

diff --git a/docs/html/resource_aliasing.html b/docs/html/resource_aliasing.html
index bc03b30..c941d03 100644
--- a/docs/html/resource_aliasing.html
+++ b/docs/html/resource_aliasing.html
@@ -150,7 +150,8 @@ $(function() {
 <div class="ttc" id="astruct_vma_allocation_create_info_html"><div class="ttname"><a href="struct_vma_allocation_create_info.html">VmaAllocationCreateInfo</a></div><div class="ttdoc">Parameters of new VmaAllocation.</div><div class="ttdef"><b>Definition:</b> vk_mem_alloc.h:1219</div></div>
 <div class="ttc" id="astruct_vma_allocation_create_info_html_a7fe8d81a1ad10b2a2faacacee5b15d6d"><div class="ttname"><a href="struct_vma_allocation_create_info.html#a7fe8d81a1ad10b2a2faacacee5b15d6d">VmaAllocationCreateInfo::preferredFlags</a></div><div class="ttdeci">VkMemoryPropertyFlags preferredFlags</div><div class="ttdoc">Flags that preferably should be set in a memory type chosen for an allocation.</div><div class="ttdef"><b>Definition:</b> vk_mem_alloc.h:1237</div></div>
 <div class="ttc" id="astruct_vma_allocation_html"><div class="ttname"><a href="struct_vma_allocation.html">VmaAllocation</a></div><div class="ttdoc">Represents single memory allocation.</div></div>
-</div><!-- fragment --><p >Remember that using resources that alias in memory requires proper synchronization. You need to issue a memory barrier to make sure commands that use <code>img1</code> and <code>img2</code> 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 <code>img1</code> and then want to use <code>img2</code>, you need to issue an image memory barrier for <code>img2</code> with <code>oldLayout</code> = <code>VK_IMAGE_LAYOUT_UNDEFINED</code>.</p>
+</div><!-- fragment --><p >VMA also provides convenience functions that create a buffer or image and bind it to memory represented by an existing <a class="el" href="struct_vma_allocation.html" title="Represents single memory allocation.">VmaAllocation</a>: <a class="el" href="group__group__alloc.html#ga60d5d4803e3c82505a2bfddb929adb03" title="Creates a new VkBuffer, binds already created memory for it.">vmaCreateAliasingBuffer()</a>, <a class="el" href="group__group__alloc.html#gaf0cf014344213e117bd9f9cf5f928122" title="Creates a new VkBuffer, binds already created memory for it.">vmaCreateAliasingBuffer2()</a>, <a class="el" href="group__group__alloc.html#gaebc4db1f94b53dba2338b4c0fd80d0dc" title="Function similar to vmaCreateAliasingBuffer() but for images.">vmaCreateAliasingImage()</a>, <a class="el" href="group__group__alloc.html#ga69ac829f5bb0737449fa92c2d971f1bb" title="Function similar to vmaCreateAliasingBuffer2() but for images.">vmaCreateAliasingImage2()</a>. Versions with "2" offer additional parameter <code>allocationLocalOffset</code>.</p>
+<p >Remember that using resources that alias in memory requires proper synchronization. You need to issue a memory barrier to make sure commands that use <code>img1</code> and <code>img2</code> 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 <code>img1</code> and then want to use <code>img2</code>, you need to issue an image memory barrier for <code>img2</code> with <code>oldLayout</code> = <code>VK_IMAGE_LAYOUT_UNDEFINED</code>.</p>
 <p >Additional considerations:</p>
 <ul>
 <li>Vulkan also allows to interpret contents of memory between aliasing resources consistently in some cases. See chapter 11.8. "Memory Aliasing" of Vulkan specification or <code>VK_IMAGE_CREATE_ALIAS_BIT</code> flag.</li>
diff --git a/include/vk_mem_alloc.h b/include/vk_mem_alloc.h
index 77a603f..40c1f7c 100644
--- a/include/vk_mem_alloc.h
+++ b/include/vk_mem_alloc.h
@@ -18208,6 +18208,12 @@ vkDestroyImage(allocator, img2, nullptr);
 vkDestroyImage(allocator, img1, nullptr);
 \endcode
 
+VMA also provides convenience functions that create a buffer or image and bind it to memory
+represented by an existing #VmaAllocation:
+vmaCreateAliasingBuffer(), vmaCreateAliasingBuffer2(),
+vmaCreateAliasingImage(), vmaCreateAliasingImage2().
+Versions with "2" offer additional parameter `allocationLocalOffset`.
+
 Remember that using resources that alias in memory requires proper synchronization.
 You need to issue a memory barrier to make sure commands that use `img1` and `img2`
 don't overlap on GPU timeline.