Improved documentation of function vmaCreateBuffer
diff --git a/docs/html/group__group__alloc.html b/docs/html/group__group__alloc.html index 9712e0a..680918e 100644 --- a/docs/html/group__group__alloc.html +++ b/docs/html/group__group__alloc.html
@@ -1631,12 +1631,12 @@ <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 @@ <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 >= 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>
diff --git a/include/vk_mem_alloc.h b/include/vk_mem_alloc.h index 1cab24d..ef84cdf 100644 --- a/include/vk_mem_alloc.h +++ b/include/vk_mem_alloc.h
@@ -2605,12 +2605,13 @@ /** \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 @@ -# 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 @@ \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,