<divclass="textblock"><p>To "map memory" in Vulkan means to obtain a CPU pointer to <code>VkDeviceMemory</code>, to be able to read from it or write to it in CPU code. Mapping is possible only of memory allocated from a memory type that has <code>VK_MEMORY_PROPERTY_HOST_VISIBLE_BIT</code> flag. Functions <code>vkMapMemory()</code>, <code>vkUnmapMemory()</code> are designed for this purpose. You can use them directly with memory allocated by this library, but it is not recommended because of following issue: Mapping the same <code>VkDeviceMemory</code> block multiple times is illegal - only one mapping at a time is allowed. This includes mapping disjoint regions. Mapping is not reference-counted internally by Vulkan. Because of this, Vulkan Memory Allocator provides following facilities:</p>
<dlclass="section note"><dt>Note</dt><dd>If you want to be able to map an allocation, you need to specify one of the flags <aclass="el"href="group__group__alloc.html#ggad9889c10c798b040d59c92f257cae597a9be224df3bfc1cfa06203aed689a30c5">VMA_ALLOCATION_CREATE_HOST_ACCESS_SEQUENTIAL_WRITE_BIT</a> or <aclass="el"href="group__group__alloc.html#ggad9889c10c798b040d59c92f257cae597add61238d98e20917b9a06c617763f492">VMA_ALLOCATION_CREATE_HOST_ACCESS_RANDOM_BIT</a> in <aclass="el"href="struct_vma_allocation_create_info.html#add09658ac14fe290ace25470ddd6d41b"title="Use VmaAllocationCreateFlagBits enum.">VmaAllocationCreateInfo::flags</a>. These flags are required for an allocation to be mappable when using <aclass="el"href="group__group__alloc.html#ggaa5846affa1e9da3800e3e78fae2305cca27cde9026a84d34d525777baa41fce6e">VMA_MEMORY_USAGE_AUTO</a> or other <code>VMA_MEMORY_USAGE_AUTO*</code> enum values. For other usage values they are ignored and every such allocation made in <code>HOST_VISIBLE</code> memory type is mappable, but they can still be used for consistency.</dd></dl>
<p>The library provides following functions for mapping of a specific <aclass="el"href="struct_vma_allocation.html"title="Represents single memory allocation.">VmaAllocation</a>: <aclass="el"href="group__group__alloc.html#gad5bd1243512d099706de88168992f069"title="Maps memory represented by given allocation and returns pointer to it.">vmaMapMemory()</a>, <aclass="el"href="group__group__alloc.html#ga9bc268595cb33f6ec4d519cfce81ff45"title="Unmaps memory represented by given allocation, mapped previously using vmaMapMemory().">vmaUnmapMemory()</a>. They are safer and more convenient to use than standard Vulkan functions. You can map an allocation multiple times simultaneously - mapping is reference-counted internally. You can also map different allocations simultaneously regardless of whether they use the same <code>VkDeviceMemory</code> block. The way it is implemented is that the library always maps entire memory block, not just region of the allocation. For further details, see description of <aclass="el"href="group__group__alloc.html#gad5bd1243512d099706de88168992f069"title="Maps memory represented by given allocation and returns pointer to it.">vmaMapMemory()</a> function. Example:</p>
<divclass="ttc"id="agroup__group__alloc_html_ga9bc268595cb33f6ec4d519cfce81ff45"><divclass="ttname"><ahref="group__group__alloc.html#ga9bc268595cb33f6ec4d519cfce81ff45">vmaUnmapMemory</a></div><divclass="ttdeci">void vmaUnmapMemory(VmaAllocator allocator, VmaAllocation allocation)</div><divclass="ttdoc">Unmaps memory represented by given allocation, mapped previously using vmaMapMemory().</div></div>
<divclass="ttc"id="agroup__group__alloc_html_gad5bd1243512d099706de88168992f069"><divclass="ttname"><ahref="group__group__alloc.html#gad5bd1243512d099706de88168992f069">vmaMapMemory</a></div><divclass="ttdeci">VkResult vmaMapMemory(VmaAllocator allocator, VmaAllocation allocation, void **ppData)</div><divclass="ttdoc">Maps memory represented by given allocation and returns pointer to it.</div></div>
</div><!-- fragment --><p>When mapping, you may see a warning from Vulkan validation layer similar to this one:</p>
<p><em>Mapping an image with layout VK_IMAGE_LAYOUT_DEPTH_STENCIL_ATTACHMENT_OPTIMAL can result in undefined behavior if this memory is used by the device. Only GENERAL or PREINITIALIZED should be used.</em></p>
<p>It happens because the library maps entire <code>VkDeviceMemory</code> block, where different types of images and buffers may end up together, especially on GPUs with unified memory like Intel. You can safely ignore it if you are sure you access only memory of the intended object that you wanted to map.</p>
<p>Kepping your memory persistently mapped is generally OK in Vulkan. You don't need to unmap it before using its data on the GPU. The library provides a special feature designed for that: Allocations made with <aclass="el"href="group__group__alloc.html#ggad9889c10c798b040d59c92f257cae597a11da372cc3a82931c5e5d6146cd9dd1f"title="Set this flag to use a memory that will be persistently mapped and retrieve pointer to it.">VMA_ALLOCATION_CREATE_MAPPED_BIT</a> flag set in <aclass="el"href="struct_vma_allocation_create_info.html#add09658ac14fe290ace25470ddd6d41b"title="Use VmaAllocationCreateFlagBits enum.">VmaAllocationCreateInfo::flags</a> stay mapped all the time, so you can just access CPU pointer to it any time without a need to call any "map" or "unmap" function. Example:</p>
<divclass="ttc"id="agroup__group__alloc_html_ggad9889c10c798b040d59c92f257cae597a11da372cc3a82931c5e5d6146cd9dd1f"><divclass="ttname"><ahref="group__group__alloc.html#ggad9889c10c798b040d59c92f257cae597a11da372cc3a82931c5e5d6146cd9dd1f">VMA_ALLOCATION_CREATE_MAPPED_BIT</a></div><divclass="ttdeci">@ VMA_ALLOCATION_CREATE_MAPPED_BIT</div><divclass="ttdoc">Set this flag to use a memory that will be persistently mapped and retrieve pointer to it.</div><divclass="ttdef"><b>Definition:</b> vk_mem_alloc.h:546</div></div>
<divclass="ttc"id="astruct_vma_allocation_html"><divclass="ttname"><ahref="struct_vma_allocation.html">VmaAllocation</a></div><divclass="ttdoc">Represents single memory allocation.</div></div>
<divclass="ttc"id="astruct_vma_allocation_info_html"><divclass="ttname"><ahref="struct_vma_allocation_info.html">VmaAllocationInfo</a></div><divclass="ttdoc">Parameters of VmaAllocation objects, that can be retrieved using function vmaGetAllocationInfo().</div><divclass="ttdef"><b>Definition:</b> vk_mem_alloc.h:1326</div></div>
<divclass="ttc"id="astruct_vma_allocation_info_html_a5eeffbe2d2f30f53370ff14aefbadbe2"><divclass="ttname"><ahref="struct_vma_allocation_info.html#a5eeffbe2d2f30f53370ff14aefbadbe2">VmaAllocationInfo::pMappedData</a></div><divclass="ttdeci">void * pMappedData</div><divclass="ttdoc">Pointer to the beginning of this allocation as mapped data.</div><divclass="ttdef"><b>Definition:</b> vk_mem_alloc.h:1368</div></div>
</div><!-- fragment --><dlclass="section note"><dt>Note</dt><dd><aclass="el"href="group__group__alloc.html#ggad9889c10c798b040d59c92f257cae597a11da372cc3a82931c5e5d6146cd9dd1f"title="Set this flag to use a memory that will be persistently mapped and retrieve pointer to it.">VMA_ALLOCATION_CREATE_MAPPED_BIT</a> by itself doesn't guarantee that the allocation will end up in a mappable memory type. For this, you need to also specify <aclass="el"href="group__group__alloc.html#ggad9889c10c798b040d59c92f257cae597a9be224df3bfc1cfa06203aed689a30c5">VMA_ALLOCATION_CREATE_HOST_ACCESS_SEQUENTIAL_WRITE_BIT</a> or <aclass="el"href="group__group__alloc.html#ggad9889c10c798b040d59c92f257cae597add61238d98e20917b9a06c617763f492">VMA_ALLOCATION_CREATE_HOST_ACCESS_RANDOM_BIT</a>. <aclass="el"href="group__group__alloc.html#ggad9889c10c798b040d59c92f257cae597a11da372cc3a82931c5e5d6146cd9dd1f"title="Set this flag to use a memory that will be persistently mapped and retrieve pointer to it.">VMA_ALLOCATION_CREATE_MAPPED_BIT</a> only guarantees that if the memory is <code>HOST_VISIBLE</code>, the allocation will be mapped on creation. For an example of how to make use of this fact, see section <aclass="el"href="usage_patterns.html#usage_patterns_advanced_data_uploading">Advanced data uploading</a>.</dd></dl>
<p>Memory in Vulkan doesn't need to be unmapped before using it on GPU, but unless a memory types has <code>VK_MEMORY_PROPERTY_HOST_COHERENT_BIT</code> flag set, you need to manually <b>invalidate</b> cache before reading of mapped pointer and <b>flush</b> cache after writing to mapped pointer. Map/unmap operations don't do that automatically. Vulkan provides following functions for this purpose <code>vkFlushMappedMemoryRanges()</code>, <code>vkInvalidateMappedMemoryRanges()</code>, but this library provides more convenient functions that refer to given allocation object: <aclass="el"href="group__group__alloc.html#ga30c37c1eec6025f397be41644f48490f"title="Flushes memory of given allocation.">vmaFlushAllocation()</a>, <aclass="el"href="group__group__alloc.html#gaaa8412919139ef413a4215ac6a290fae"title="Invalidates memory of given allocation.">vmaInvalidateAllocation()</a>, or multiple objects at once: <aclass="el"href="group__group__alloc.html#gac3dd00da721875ed99fa8a881922bdfc"title="Flushes memory of given set of allocations.">vmaFlushAllocations()</a>, <aclass="el"href="group__group__alloc.html#gab25b558d75f7378ec944a1522fdcc3c5"title="Invalidates memory of given set of allocations.">vmaInvalidateAllocations()</a>.</p>
<p>Regions of memory specified for flush/invalidate must be aligned to <code>VkPhysicalDeviceLimits::nonCoherentAtomSize</code>. This is automatically ensured by the library. In any memory type that is <code>HOST_VISIBLE</code> but not <code>HOST_COHERENT</code>, all allocations within blocks are aligned to this value, so their offsets are always multiply of <code>nonCoherentAtomSize</code> and two different allocations never share same "line" of this size.</p>
<p>Also, Windows drivers from all 3 PC GPU vendors (AMD, Intel, NVIDIA) currently provide <code>HOST_COHERENT</code> flag on all memory types that are <code>HOST_VISIBLE</code>, so on PC you may not need to bother. </p>
