Improved documentation of function vmaCreateBuffer

Author: sawickiap

docs/html/group__group__alloc.html

@@ -1631,12 +1631,12 @@ <h2 class="memtitle"><span class="permalink"><a href="#gac72ee55598617e8eecca384
 <p>Creates a new <span class="tt">VkBuffer</span>, allocates and binds memory for it. </p>
 <dl class="params"><dt>Parameters</dt><dd>
   <table class="params">
-    <tr><td class="paramdir"></td><td class="paramname">allocator</td><td></td></tr>
-    <tr><td class="paramdir"></td><td class="paramname">pBufferCreateInfo</td><td></td></tr>
-    <tr><td class="paramdir"></td><td class="paramname">pAllocationCreateInfo</td><td></td></tr>
+    <tr><td class="paramdir"></td><td class="paramname">allocator</td><td>The main allocator object. </td></tr>
+    <tr><td class="paramdir"></td><td class="paramname">pBufferCreateInfo</td><td>Buffer creation parameters. </td></tr>
+    <tr><td class="paramdir"></td><td class="paramname">pAllocationCreateInfo</td><td>Allocation creation parameters. </td></tr>
     <tr><td class="paramdir">[out]</td><td class="paramname">pBuffer</td><td>Buffer that was created. </td></tr>
     <tr><td class="paramdir">[out]</td><td class="paramname">pAllocation</td><td>Allocation that was created. </td></tr>
-    <tr><td class="paramdir">[out]</td><td class="paramname">pAllocationInfo</td><td>Optional. Information about allocated memory. It can be later fetched using function <a class="el" href="#ga86dd08aba8633bfa4ad0df2e76481d8b" title="Returns current information about specified allocation.">vmaGetAllocationInfo()</a>.</td></tr>
+    <tr><td class="paramdir">[out]</td><td class="paramname">pAllocationInfo</td><td>Optional, can be null. Information about allocated memory. It can be also fetched later using <a class="el" href="#ga86dd08aba8633bfa4ad0df2e76481d8b" title="Returns current information about specified allocation.">vmaGetAllocationInfo()</a>.</td></tr>
   </table>
   </dd>
 </dl>
@@ -1646,10 +1646,11 @@ <h2 class="memtitle"><span class="permalink"><a href="#gac72ee55598617e8eecca384
 <li>Allocates appropriate memory for it.</li>
 <li>Binds the buffer with the memory.</li>
 </ol>
-<p>If any of these operations fail, buffer and allocation are not created, returned value is negative error code, <span class="tt">*pBuffer</span> and <span class="tt">*pAllocation</span> are null.</p>
+<p>If any of these operations fail, buffer and allocation are not created, returned value is negative error code, <span class="tt">*pBuffer</span> and <span class="tt">*pAllocation</span> are returned as null.</p>
 <p>If the function succeeded, you must destroy both buffer and allocation when you no longer need them using either convenience function <a class="el" href="#ga0d9f4e4ba5bf9aab1f1c746387753d77" title="Destroys Vulkan buffer and frees allocated memory.">vmaDestroyBuffer()</a> or separately, using <span class="tt">vkDestroyBuffer()</span> and <a class="el" href="#ga11f0fbc034fa81a4efedd73d61ce7568" title="Frees memory previously allocated using vmaAllocateMemory(), vmaAllocateMemoryForBuffer(),...">vmaFreeMemory()</a>.</p>
-<p>If <a class="el" href="group__group__init.html#gga4f87c9100d154a65a4ad495f7763cf7cace7da7cc6e71a625dfa763c55a597878" title="Enables usage of VK_KHR_dedicated_allocation extension.">VMA_ALLOCATOR_CREATE_KHR_DEDICATED_ALLOCATION_BIT</a> flag was used, VK_KHR_dedicated_allocation extension is used internally to query driver whether it requires or prefers the new buffer to have dedicated allocation. If yes, and if dedicated allocation is possible (<a class="el" href="#ggad9889c10c798b040d59c92f257cae597a89759603401014eb325eb22a3839f2ff" title="Set this flag to only try to allocate from existing VkDeviceMemory blocks and never create new such b...">VMA_ALLOCATION_CREATE_NEVER_ALLOCATE_BIT</a> is not used), it creates dedicated allocation for this buffer, just like when using <a class="el" href="#ggad9889c10c798b040d59c92f257cae597a3fc311d855c2ff53f1090ef5c722b38f" title="Set this flag if the allocation should have its own memory block.">VMA_ALLOCATION_CREATE_DEDICATED_MEMORY_BIT</a>.</p>
-<dl class="section note"><dt>Note</dt><dd>This function creates a new <span class="tt">VkBuffer</span>. Sub-allocation of parts of one large buffer, although recommended as a good practice, is out of scope of this library and could be implemented by the user as a higher-level logic on top of VMA. </dd></dl>
+<p>If VK_KHR_dedicated_allocation extenion or Vulkan version &gt;= 1.1 is used, the function queries the driver whether it requires or prefers the new buffer to have dedicated allocation. If yes, and if dedicated allocation is possible (<a class="el" href="#ggad9889c10c798b040d59c92f257cae597a89759603401014eb325eb22a3839f2ff" title="Set this flag to only try to allocate from existing VkDeviceMemory blocks and never create new such b...">VMA_ALLOCATION_CREATE_NEVER_ALLOCATE_BIT</a> is not used), it creates dedicated allocation for this buffer, just like when using <a class="el" href="#ggad9889c10c798b040d59c92f257cae597a3fc311d855c2ff53f1090ef5c722b38f" title="Set this flag if the allocation should have its own memory block.">VMA_ALLOCATION_CREATE_DEDICATED_MEMORY_BIT</a>.</p>
+<dl class="section note"><dt>Note</dt><dd>This function creates a new <span class="tt">VkBuffer</span>. Sub-allocation of parts of one large buffer, although recommended as a good practice, is out of scope of this library and could be implemented by the user as a higher-level logic on top of VMA.</dd></dl>
+<p>There is also an extended version of this function available with additional parameter <span class="tt">minAlignment</span> - see <a class="el" href="#gaa06a690013a0d01e60894ac378083834" title="Creates a buffer with additional minimum alignment.">vmaCreateBufferWithAlignment()</a>. </p>
 
 </div>
 </div>

include/vk_mem_alloc.h

@@ -2605,12 +2605,13 @@ VMA_CALL_PRE VkResult VMA_CALL_POST vmaBindImageMemory2(
 
 /** \brief Creates a new `VkBuffer`, allocates and binds memory for it.
 
-\param allocator
-\param pBufferCreateInfo
-\param pAllocationCreateInfo
+\param allocator The main allocator object.
+\param pBufferCreateInfo Buffer creation parameters.
+\param pAllocationCreateInfo Allocation creation parameters.
 \param[out] pBuffer Buffer that was created.
 \param[out] pAllocation Allocation that was created.
-\param[out] pAllocationInfo Optional. Information about allocated memory. It can be later fetched using function vmaGetAllocationInfo().
+\param[out] pAllocationInfo Optional, can be null. Information about allocated memory.
+    It can be also fetched later using vmaGetAllocationInfo().
 
 This function automatically:
 
@@ -2619,14 +2620,14 @@ This function automatically:
 -# Binds the buffer with the memory.
 
 If any of these operations fail, buffer and allocation are not created,
-returned value is negative error code, `*pBuffer` and `*pAllocation` are null.
+returned value is negative error code, `*pBuffer` and `*pAllocation` are returned as null.
 
 If the function succeeded, you must destroy both buffer and allocation when you
 no longer need them using either convenience function vmaDestroyBuffer() or
 separately, using `vkDestroyBuffer()` and vmaFreeMemory().
 
-If #VMA_ALLOCATOR_CREATE_KHR_DEDICATED_ALLOCATION_BIT flag was used,
-VK_KHR_dedicated_allocation extension is used internally to query driver whether
+If VK_KHR_dedicated_allocation extenion or Vulkan version >= 1.1 is used,
+the function queries the driver whether
 it requires or prefers the new buffer to have dedicated allocation. If yes,
 and if dedicated allocation is possible
 (#VMA_ALLOCATION_CREATE_NEVER_ALLOCATE_BIT is not used), it creates dedicated
@@ -2636,6 +2637,9 @@ allocation for this buffer, just like when using
 \note This function creates a new `VkBuffer`. Sub-allocation of parts of one large buffer,
 although recommended as a good practice, is out of scope of this library and could be implemented
 by the user as a higher-level logic on top of VMA.
+
+There is also an extended version of this function available with additional parameter `minAlignment` -
+see vmaCreateBufferWithAlignment().
 */
 VMA_CALL_PRE VkResult VMA_CALL_POST vmaCreateBuffer(
     VmaAllocator VMA_NOT_NULL allocator,