Fixed major bug, made few smaller fixes and additions in documentation.

docs/html/choosing_memory_type.html

@@ -71,10 +71,10 @@ $(function() {
 <div class="contents">
 <div class="textblock"><p>Physical devices in Vulkan support various combinations of memory heaps and types. Help with choosing correct and optimal memory type for your specific resource is one of the key features of this library. You can use it by filling appropriate members of <a class="el" href="struct_vma_allocation_create_info.html">VmaAllocationCreateInfo</a> structure, as described below. You can also combine multiple methods.</p>
 <ol type="1">
-<li>If you just want to find memory type index that meets your requirements, you can use function <a class="el" href="vk__mem__alloc_8h.html#aef15a94b58fbcb0fe706d5720e84a74a" title="Helps to find memoryTypeIndex, given memoryTypeBits and VmaAllocationCreateInfo. ">vmaFindMemoryTypeIndex()</a>.</li>
+<li>If you just want to find memory type index that meets your requirements, you can use function: <a class="el" href="vk__mem__alloc_8h.html#aef15a94b58fbcb0fe706d5720e84a74a" title="Helps to find memoryTypeIndex, given memoryTypeBits and VmaAllocationCreateInfo. ">vmaFindMemoryTypeIndex()</a>, <a class="el" href="vk__mem__alloc_8h.html#ae790ab9ffaf7667fb8f62523e6897888" title="Helps to find memoryTypeIndex, given VkBufferCreateInfo and VmaAllocationCreateInfo. ">vmaFindMemoryTypeIndexForBufferInfo()</a>, <a class="el" href="vk__mem__alloc_8h.html#a088da83d8eaf3ce9056d9ea0b981d472" title="Helps to find memoryTypeIndex, given VkImageCreateInfo and VmaAllocationCreateInfo. ">vmaFindMemoryTypeIndexForImageInfo()</a>.</li>
-<li>If you want to allocate a region of device memory without association with any specific image or buffer, you can use function <a class="el" href="vk__mem__alloc_8h.html#abf28077dbf82d0908b8acbe8ee8dd9b8" title="General purpose memory allocation. ">vmaAllocateMemory()</a>. Usage of this function is not recommended and usually not needed.</li>
+<li>If you want to allocate a region of device memory without association with any specific image or buffer, you can use function <a class="el" href="vk__mem__alloc_8h.html#abf28077dbf82d0908b8acbe8ee8dd9b8" title="General purpose memory allocation. ">vmaAllocateMemory()</a>. Usage of this function is not recommended and usually not needed. <a class="el" href="vk__mem__alloc_8h.html#ad37e82e492b3de38fc3f4cffd9ad0ae1" title="General purpose memory allocation for multiple allocation objects at once. ">vmaAllocateMemoryPages()</a> function is also provided for creating multiple allocations at once, which may be useful for sparse binding.</li>
 <li>If you already have a buffer or an image created, you want to allocate memory for it and then you will bind it yourself, you can use function <a class="el" href="vk__mem__alloc_8h.html#a7fdf64415b6c3d83c454f28d2c53df7b">vmaAllocateMemoryForBuffer()</a>, <a class="el" href="vk__mem__alloc_8h.html#a0faa3f9e5fb233d29d1e00390650febb" title="Function similar to vmaAllocateMemoryForBuffer(). ">vmaAllocateMemoryForImage()</a>. For binding you should use functions: <a class="el" href="vk__mem__alloc_8h.html#a6b0929b914b60cf2d45cac4bf3547470" title="Binds buffer to allocation. ">vmaBindBufferMemory()</a>, <a class="el" href="vk__mem__alloc_8h.html#a3d3ca45799923aa5d138e9e5f9eb2da5" title="Binds image to allocation. ">vmaBindImageMemory()</a>.</li>
-<li>If you want to create a buffer or an image, allocate memory for it and bind them together, all in one call, you can use function <a class="el" href="vk__mem__alloc_8h.html#ac72ee55598617e8eecca384e746bab51">vmaCreateBuffer()</a>, <a class="el" href="vk__mem__alloc_8h.html#a02a94f25679275851a53e82eacbcfc73" title="Function similar to vmaCreateBuffer(). ">vmaCreateImage()</a>. This is the recommended way to use this library.</li>
+<li>If you want to create a buffer or an image, allocate memory for it and bind them together, all in one call, you can use function <a class="el" href="vk__mem__alloc_8h.html#ac72ee55598617e8eecca384e746bab51">vmaCreateBuffer()</a>, <a class="el" href="vk__mem__alloc_8h.html#a02a94f25679275851a53e82eacbcfc73" title="Function similar to vmaCreateBuffer(). ">vmaCreateImage()</a>. This is the easiest and recommended way to use this library.</li>
 </ol>
 <p>When using 3. or 4., the library internally queries Vulkan for memory types supported for that buffer or image (function <code>vkGetBufferMemoryRequirements()</code>) and uses only one of these types.</p>
 <p>If no memory type can be found that meets all the requirements, these functions return <code>VK_ERROR_FEATURE_NOT_PRESENT</code>.</p>
@@ -95,6 +95,14 @@ Explicit memory types</h1>
 <div class="fragment"><div class="line">uint32_t memoryTypeIndex = 2;</div><div class="line"></div><div class="line"><a class="code" href="struct_vma_allocation_create_info.html">VmaAllocationCreateInfo</a> allocInfo = {};</div><div class="line">allocInfo.<a class="code" href="struct_vma_allocation_create_info.html#a3bf940c0271d85d6ba32a4d820075055">memoryTypeBits</a> = 1u &lt;&lt; memoryTypeIndex;</div><div class="line"></div><div class="line">VkBuffer buffer;</div><div class="line"><a class="code" href="struct_vma_allocation.html">VmaAllocation</a> allocation;</div><div class="line"><a class="code" href="vk__mem__alloc_8h.html#ac72ee55598617e8eecca384e746bab51">vmaCreateBuffer</a>(allocator, &amp;bufferInfo, &amp;allocInfo, &amp;buffer, &amp;allocation, <span class="keyword">nullptr</span>);</div></div><!-- fragment --><h1><a class="anchor" id="choosing_memory_type_custom_memory_pools"></a>
 Custom memory pools</h1>
 <p>If you allocate from custom memory pool, all the ways of specifying memory requirements described above are not applicable and the aforementioned members of <a class="el" href="struct_vma_allocation_create_info.html">VmaAllocationCreateInfo</a> structure are ignored. Memory type is selected explicitly when creating the pool and then used to make all the allocations from that pool. For further details, see <a class="el" href="custom_memory_pools.html">Custom memory pools</a>.</p>
+<h1><a class="anchor" id="choosing_memory_type_dedicated_allocations"></a>
+Dedicated allocations</h1>
+<p>Memory for allocations is reserved out of larger block of <code>VkDeviceMemory</code> allocated from Vulkan internally. That's the main feature of this whole library. You can still request a separate memory block to be created for an allocation, just like you would do in a trivial solution without using any allocator. In that case, a buffer or image is always bound to that memory at offset 0. This is called a "dedicated allocation". You can explicitly request it by using flag <a class="el" href="vk__mem__alloc_8h.html#ad9889c10c798b040d59c92f257cae597a3fc311d855c2ff53f1090ef5c722b38f" title="Set this flag if the allocation should have its own memory block. ">VMA_ALLOCATION_CREATE_DEDICATED_MEMORY_BIT</a>. The library can also internally decide to use dedicated allocation in some cases, e.g.:</p>
+<ul>
+<li>When the size of the allocation is large.</li>
+<li>When <a class="el" href="vk_khr_dedicated_allocation.html">VK_KHR_dedicated_allocation</a> extension is enabled and it reports that dedicated allocation is required or recommended for the resource.</li>
+<li>When allocation of next big memory block fails due to not enough device memory, but allocation with the exact requested size succeeds. </li>
+</ul>
 </div></div><!-- contents -->
 <!-- start footer part -->
 <hr class="footer"/><address class="footer"><small>

docs/html/index.html

@@ -65,7 +65,7 @@ $(function() {
 <div class="title">Vulkan Memory Allocator </div>  </div>
 </div><!--header-->
 <div class="contents">
-<div class="textblock"><p><b>Version 2.2.0</b> (2018-12-13)</p>
+<div class="textblock"><p><b>Version 2.2.1-development</b> (2018-12-14)</p>
 <p>Copyright (c) 2017-2018 Advanced Micro Devices, Inc. All rights reserved. <br />
 License: MIT</p>
 <p>Documentation of all members: <a class="el" href="vk__mem__alloc_8h.html">vk_mem_alloc.h</a></p>
@@ -84,6 +84,7 @@ Table of contents</h1>
 <li><a class="el" href="choosing_memory_type.html#choosing_memory_type_required_preferred_flags">Required and preferred flags</a></li>
 <li><a class="el" href="choosing_memory_type.html#choosing_memory_type_explicit_memory_types">Explicit memory types</a></li>
 <li><a class="el" href="choosing_memory_type.html#choosing_memory_type_custom_memory_pools">Custom memory pools</a></li>
+<li><a class="el" href="choosing_memory_type.html#choosing_memory_type_dedicated_allocations">Dedicated allocations</a></li>
 </ul>
 </li>
 <li><a class="el" href="memory_mapping.html">Memory mapping</a><ul>

docs/html/quick_start.html

@@ -71,7 +71,7 @@ $(function() {
 <div class="contents">
 <div class="textblock"><h1><a class="anchor" id="quick_start_project_setup"></a>
 Project setup</h1>
-<p>Vulkan Memory Allocator comes in form of a single header file. You don't need to build it as a separate library project. You can add this file directly to your project and submit it to code repository next to your other source files.</p>
+<p>Vulkan Memory Allocator comes in form of a "stb-style" single header file. You don't need to build it as a separate library project. You can add this file directly to your project and submit it to code repository next to your other source files.</p>
 <p>"Single header" doesn't mean that everything is contained in C/C++ declarations, like it tends to be in case of inline functions or C++ templates. It means that implementation is bundled with interface in a single file and needs to be extracted using preprocessor macro. If you don't do it properly, you will get linker errors.</p>
 <p>To do it properly:</p>
 <ol type="1">

docs/html/vk__mem__alloc_8h.html

@@ -870,7 +870,6 @@ Functions</h2></td></tr>
 <table class="fieldtable">
 <tr><th colspan="2">Enumerator</th></tr><tr><td class="fieldname"><a id="ad9889c10c798b040d59c92f257cae597a3fc311d855c2ff53f1090ef5c722b38f"></a>VMA_ALLOCATION_CREATE_DEDICATED_MEMORY_BIT&#160;</td><td class="fielddoc"><p>Set this flag if the allocation should have its own memory block. </p>
 <p>Use it for special, big resources, like fullscreen images used as attachments.</p>
-<p>This flag must also be used for host visible resources that you want to map simultaneously because otherwise they might end up as regions of the same <code>VkDeviceMemory</code>, while mapping same <code>VkDeviceMemory</code> multiple times simultaneously is illegal.</p>
 <p>You should not use this flag if <a class="el" href="struct_vma_allocation_create_info.html#a6272c0555cfd1fe28bff1afeb6190150" title="Pool that this allocation should be created in. ">VmaAllocationCreateInfo::pool</a> is not null. </p>
 </td></tr>
 <tr><td class="fieldname"><a id="ad9889c10c798b040d59c92f257cae597a89759603401014eb325eb22a3839f2ff"></a>VMA_ALLOCATION_CREATE_NEVER_ALLOCATE_BIT&#160;</td><td class="fielddoc"><p>Set this flag to only try to allocate from existing <code>VkDeviceMemory</code> blocks and never create new such block. </p>

src/vk_mem_alloc.h

@@ -29,7 +29,7 @@ extern "C" {
 
 /** \mainpage Vulkan Memory Allocator
 
-<b>Version 2.2.0</b> (2018-12-13)
+<b>Version 2.2.1-development</b> (2018-12-14)
 
 Copyright (c) 2017-2018 Advanced Micro Devices, Inc. All rights reserved. \n
 License: MIT
@@ -48,6 +48,7 @@ Documentation of all members: vk_mem_alloc.h
     - [Required and preferred flags](@ref choosing_memory_type_required_preferred_flags)
     - [Explicit memory types](@ref choosing_memory_type_explicit_memory_types)
     - [Custom memory pools](@ref choosing_memory_type_custom_memory_pools)
+    - [Dedicated allocations](@ref choosing_memory_type_dedicated_allocations)
   - \subpage memory_mapping
     - [Mapping functions](@ref memory_mapping_mapping_functions)
     - [Persistently mapped memory](@ref memory_mapping_persistently_mapped_memory)
@@ -105,7 +106,7 @@ Documentation of all members: vk_mem_alloc.h
 
 \section quick_start_project_setup Project setup
 
-Vulkan Memory Allocator comes in form of a single header file.
+Vulkan Memory Allocator comes in form of a "stb-style" single header file.
 You don't need to build it as a separate library project.
 You can add this file directly to your project and submit it to code repository next to your other source files.
 
@@ -195,17 +196,20 @@ appropriate members of VmaAllocationCreateInfo structure, as described below.
 You can also combine multiple methods.
 
 -# If you just want to find memory type index that meets your requirements, you
-   can use function vmaFindMemoryTypeIndex().
+   can use function: vmaFindMemoryTypeIndex(), vmaFindMemoryTypeIndexForBufferInfo(),
+   vmaFindMemoryTypeIndexForImageInfo().
 -# If you want to allocate a region of device memory without association with any
    specific image or buffer, you can use function vmaAllocateMemory(). Usage of
    this function is not recommended and usually not needed.
+   vmaAllocateMemoryPages() function is also provided for creating multiple allocations at once,
+   which may be useful for sparse binding.
 -# If you already have a buffer or an image created, you want to allocate memory
    for it and then you will bind it yourself, you can use function
    vmaAllocateMemoryForBuffer(), vmaAllocateMemoryForImage().
    For binding you should use functions: vmaBindBufferMemory(), vmaBindImageMemory().
 -# If you want to create a buffer or an image, allocate memory for it and bind
    them together, all in one call, you can use function vmaCreateBuffer(),
-   vmaCreateImage(). This is the recommended way to use this library.
+   vmaCreateImage(). This is the easiest and recommended way to use this library.
 
 When using 3. or 4., the library internally queries Vulkan for memory types
 supported for that buffer or image (function `vkGetBufferMemoryRequirements()`)
@@ -301,6 +305,23 @@ of VmaAllocationCreateInfo structure are ignored. Memory type is selected
 explicitly when creating the pool and then used to make all the allocations from
 that pool. For further details, see \ref custom_memory_pools.
 
+\section choosing_memory_type_dedicated_allocations Dedicated allocations
+
+Memory for allocations is reserved out of larger block of `VkDeviceMemory`
+allocated from Vulkan internally. That's the main feature of this whole library.
+You can still request a separate memory block to be created for an allocation,
+just like you would do in a trivial solution without using any allocator.
+In that case, a buffer or image is always bound to that memory at offset 0.
+This is called a "dedicated allocation".
+You can explicitly request it by using flag #VMA_ALLOCATION_CREATE_DEDICATED_MEMORY_BIT.
+The library can also internally decide to use dedicated allocation in some cases, e.g.:
+
+- When the size of the allocation is large.
+- When [VK_KHR_dedicated_allocation](@ref vk_khr_dedicated_allocation) extension is enabled
+  and it reports that dedicated allocation is required or recommended for the resource.
+- When allocation of next big memory block fails due to not enough device memory,
+  but allocation with the exact requested size succeeds.
+
 
 \page memory_mapping Memory mapping
 
@@ -2016,11 +2037,6 @@ typedef enum VmaAllocationCreateFlagBits {
     
     Use it for special, big resources, like fullscreen images used as attachments.
    
-    This flag must also be used for host visible resources that you want to map
-    simultaneously because otherwise they might end up as regions of the same
-    `VkDeviceMemory`, while mapping same `VkDeviceMemory` multiple times
-    simultaneously is illegal.
-
     You should not use this flag if VmaAllocationCreateInfo::pool is not null.
     */
     VMA_ALLOCATION_CREATE_DEDICATED_MEMORY_BIT = 0x00000001,