clarify documentation regarding limitations of defragmentation

#59

docs/html/defragmentation.html

@@ -103,9 +103,14 @@ Defragmenting GPU memory</h1>
 <p>You may try not to block your entire program to wait until defragmentation finishes, but do it in the background, as long as you carefully fullfill requirements described in function <a class="el" href="vk__mem__alloc_8h.html#a36ba776fd7fd5cb1e9359fdc0d8e6e8a" title="Begins defragmentation process.">vmaDefragmentationBegin()</a>.</p>
 <h1><a class="anchor" id="defragmentation_additional_notes"></a>
 Additional notes</h1>
+<p>It is only legal to defragment allocations bound to:</p>
+<ul>
+<li>buffers</li>
+<li>images created with <code>VK_IMAGE_CREATE_ALIAS_BIT</code>, <code>VK_IMAGE_TILING_LINEAR</code>, and being currently in <code>VK_IMAGE_LAYOUT_GENERAL</code> or <code>VK_IMAGE_LAYOUT_PREINITIALIZED</code>.</li>
+</ul>
+<p>Defragmentation of images created with <code>VK_IMAGE_TILING_OPTIMAL</code> or in any other layout may give undefined results.</p>
+<p>If you defragment allocations bound to images, new images to be bound to new memory region after defragmentation should be created with <code>VK_IMAGE_LAYOUT_PREINITIALIZED</code> and then transitioned to their original layout from before defragmentation if needed using an image memory barrier.</p>
 <p>While using defragmentation, you may experience validation layer warnings, which you just need to ignore. See <a class="el" href="general_considerations.html#general_considerations_validation_layer_warnings">Validation layer warnings</a>.</p>
-<p>If you defragment allocations bound to images, these images should be created with <code>VK_IMAGE_CREATE_ALIAS_BIT</code> flag, to make sure that new image created with same parameters and pointing to data copied to another memory region will interpret its contents consistently. Otherwise you may experience corrupted data on some implementations, e.g. due to different pixel swizzling used internally by the graphics driver.</p>
-<p>If you defragment allocations bound to images, new images to be bound to new memory region after defragmentation should be created with <code>VK_IMAGE_LAYOUT_PREINITIALIZED</code> and then transitioned to their original layout from before defragmentation using an image memory barrier.</p>
 <p>Please don't expect memory to be fully compacted after defragmentation. Algorithms inside are based on some heuristics that try to maximize number of Vulkan memory blocks to make totally empty to release them, as well as to maximimze continuous empty space inside remaining blocks, while minimizing the number and size of allocations that need to be moved. Some fragmentation may still remain - this is normal.</p>
 <h1><a class="anchor" id="defragmentation_custom_algorithm"></a>
 Writing custom defragmentation algorithm</h1>

docs/html/vk__mem__alloc_8h.html

@@ -1889,8 +1889,9 @@ Functions</h2></td></tr>
 <li>You should not use any of allocations passed as <code>pInfo-&gt;pAllocations</code> or any allocations that belong to pools passed as <code>pInfo-&gt;pPools</code>, including calling <a class="el" href="vk__mem__alloc_8h.html#a86dd08aba8633bfa4ad0df2e76481d8b" title="Returns current information about specified allocation and atomically marks it as used in current fra...">vmaGetAllocationInfo()</a>, <a class="el" href="vk__mem__alloc_8h.html#a43d8ba9673c846f049089a5029d5c73a" title="Returns VK_TRUE if allocation is not lost and atomically marks it as used in current frame.">vmaTouchAllocation()</a>, or access their data.</li>
 <li>Some mutexes protecting internal data structures may be locked, so trying to make or free any allocations, bind buffers or images, map memory, or launch another simultaneous defragmentation in between may cause stall (when done on another thread) or deadlock (when done on the same thread), unless you are 100% sure that defragmented allocations are in different pools.</li>
 <li>Information returned via <code>pStats</code> and <code>pInfo-&gt;pAllocationsChanged</code> are undefined. They become valid after call to <a class="el" href="vk__mem__alloc_8h.html#a8774e20e91e245aae959ba63efa15dd2" title="Ends defragmentation process.">vmaDefragmentationEnd()</a>.</li>
-<li>If <code>pInfo-&gt;commandBuffer</code> is not null, you must submit that command buffer and make sure it finished execution before calling <a class="el" href="vk__mem__alloc_8h.html#a8774e20e91e245aae959ba63efa15dd2" title="Ends defragmentation process.">vmaDefragmentationEnd()</a>. </li>
+<li>If <code>pInfo-&gt;commandBuffer</code> is not null, you must submit that command buffer and make sure it finished execution before calling <a class="el" href="vk__mem__alloc_8h.html#a8774e20e91e245aae959ba63efa15dd2" title="Ends defragmentation process.">vmaDefragmentationEnd()</a>.</li>
 </ul>
+<p>For more information and important limitations regarding defragmentation, see documentation chapter: <a class="el" href="defragmentation.html">Defragmentation</a>. </p>
 
 </div>
 </div>

src/vk_mem_alloc.h

@@ -907,19 +907,22 @@ in function vmaDefragmentationBegin().
 
 \section defragmentation_additional_notes Additional notes
 
-While using defragmentation, you may experience validation layer warnings, which you just need to ignore.
+It is only legal to defragment allocations bound to:
-See [Validation layer warnings](@ref general_considerations_validation_layer_warnings).
 
-If you defragment allocations bound to images, these images should be created with
+- buffers
-`VK_IMAGE_CREATE_ALIAS_BIT` flag, to make sure that new image created with same
+- images created with `VK_IMAGE_CREATE_ALIAS_BIT`, `VK_IMAGE_TILING_LINEAR`, and
-parameters and pointing to data copied to another memory region will interpret
+  being currently in `VK_IMAGE_LAYOUT_GENERAL` or `VK_IMAGE_LAYOUT_PREINITIALIZED`.
-its contents consistently. Otherwise you may experience corrupted data on some
+
-implementations, e.g. due to different pixel swizzling used internally by the graphics driver.
+Defragmentation of images created with `VK_IMAGE_TILING_OPTIMAL` or in any other
+layout may give undefined results.
 
 If you defragment allocations bound to images, new images to be bound to new
 memory region after defragmentation should be created with `VK_IMAGE_LAYOUT_PREINITIALIZED`
-and then transitioned to their original layout from before defragmentation using
+and then transitioned to their original layout from before defragmentation if
-an image memory barrier.
+needed using an image memory barrier.
+
+While using defragmentation, you may experience validation layer warnings, which you just need to ignore.
+See [Validation layer warnings](@ref general_considerations_validation_layer_warnings).
 
 Please don't expect memory to be fully compacted after defragmentation.
 Algorithms inside are based on some heuristics that try to maximize number of Vulkan
@@ -2937,6 +2940,9 @@ Warning! Between the call to vmaDefragmentationBegin() and vmaDefragmentationEnd
   They become valid after call to vmaDefragmentationEnd().
 - If `pInfo->commandBuffer` is not null, you must submit that command buffer
   and make sure it finished execution before calling vmaDefragmentationEnd().
+
+For more information and important limitations regarding defragmentation, see documentation chapter:
+[Defragmentation](@ref defragmentation).
 */
 VkResult vmaDefragmentationBegin(
     VmaAllocator allocator,