mirror of
https://github.com/GPUOpen-LibrariesAndSDKs/VulkanMemoryAllocator.git
synced 2025-05-15 01:08:31 +00:00
Rebuilt the docs
This commit is contained in:
Adam Sawicki
parent
aee61b1d25
commit
c168e42de4
49 changed files with 645 additions and 587 deletions
|
|
@ -69,63 +69,179 @@ $(function() {
|
|||
<div class="headertitle"><div class="title">Recommended usage patterns </div></div>
|
||||
</div><!--header-->
|
||||
<div class="contents">
|
||||
<div class="textblock"><p >See also slides from talk: <a href="https://www.gdcvault.com/play/1025458/Advanced-Graphics-Techniques-Tutorial-New">Sawicki, Adam. Advanced Graphics Techniques Tutorial: Memory management in Vulkan and DX12. Game Developers Conference, 2018</a></p>
|
||||
<h1><a class="anchor" id="usage_patterns_common_mistakes"></a>
|
||||
Common mistakes</h1>
|
||||
<p ><b>Use of CPU_TO_GPU instead of CPU_ONLY memory</b></p>
|
||||
<p ><a class="el" href="group__group__alloc.html#ggaa5846affa1e9da3800e3e78fae2305cca9066b52c5a7079bb74a69aaf8b92ff67">VMA_MEMORY_USAGE_CPU_TO_GPU</a> is recommended only for resources that will be mapped and written by the CPU, as well as read directly by the GPU - like some buffers or textures updated every frame (dynamic). If you create a staging copy of a resource to be written by CPU and then used as a source of transfer to another resource placed in the GPU memory, that staging resource should be created with <a class="el" href="group__group__alloc.html#ggaa5846affa1e9da3800e3e78fae2305cca40bdf4cddeffeb12f43d45ca1286e0a5">VMA_MEMORY_USAGE_CPU_ONLY</a>. Please read the descriptions of these enums carefully for details.</p>
|
||||
<p ><b>Unnecessary use of custom pools</b></p>
|
||||
<p ><a class="el" href="custom_memory_pools.html">Custom memory pools</a> may be useful for special purposes - when you want to keep certain type of resources separate e.g. to reserve minimum amount of memory for them or limit maximum amount of memory they can occupy. For most resources this is not needed and so it is not recommended to create <a class="el" href="struct_vma_pool.html" title="Represents custom memory pool.">VmaPool</a> objects and allocations out of them. Allocating from the default pool is sufficient.</p>
|
||||
<h1><a class="anchor" id="usage_patterns_simple"></a>
|
||||
Simple patterns</h1>
|
||||
<h2><a class="anchor" id="usage_patterns_simple_render_targets"></a>
|
||||
Render targets</h2>
|
||||
<div class="textblock"><p >Vulkan gives great flexibility in memory allocation. This chapter shows the most common patterns.</p>
|
||||
<p >See also slides from talk: <a href="https://www.gdcvault.com/play/1025458/Advanced-Graphics-Techniques-Tutorial-New">Sawicki, Adam. Advanced Graphics Techniques Tutorial: Memory management in Vulkan and DX12. Game Developers Conference, 2018</a></p>
|
||||
<h1><a class="anchor" id="usage_patterns_gpu_only"></a>
|
||||
GPU-only resource</h1>
|
||||
<p ><b>When:</b> Any resources that you frequently write and read on GPU, e.g. images used as color attachments (aka "render targets"), depth-stencil attachments, images/buffers used as storage image/buffer (aka "Unordered Access View (UAV)").</p>
|
||||
<p ><b>What to do:</b> Create them in video memory that is fastest to access from GPU using <a class="el" href="group__group__alloc.html#ggaa5846affa1e9da3800e3e78fae2305ccac6b5dc1432d88647aa4cd456246eadf7">VMA_MEMORY_USAGE_GPU_ONLY</a>.</p>
|
||||
<p >Consider using <a class="el" href="vk_khr_dedicated_allocation.html">VK_KHR_dedicated_allocation</a> extension and/or manually creating them as dedicated allocations using <a class="el" href="group__group__alloc.html#ggad9889c10c798b040d59c92f257cae597a3fc311d855c2ff53f1090ef5c722b38f" title="Set this flag if the allocation should have its own memory block.">VMA_ALLOCATION_CREATE_DEDICATED_MEMORY_BIT</a>, especially if they are large or if you plan to destroy and recreate them e.g. when display resolution changes. Prefer to create such resources first and all other GPU resources (like textures and vertex buffers) later.</p>
|
||||
<h2><a class="anchor" id="usage_patterns_simple_immutable_resources"></a>
|
||||
Immutable resources</h2>
|
||||
<p ><b>When:</b> Any resources that you fill on CPU only once (aka "immutable") or infrequently and then read frequently on GPU, e.g. textures, vertex and index buffers, constant buffers that don't change often.</p>
|
||||
<p ><b>What to do:</b> Create them in video memory that is fastest to access from GPU using <a class="el" href="group__group__alloc.html#ggaa5846affa1e9da3800e3e78fae2305ccac6b5dc1432d88647aa4cd456246eadf7">VMA_MEMORY_USAGE_GPU_ONLY</a>.</p>
|
||||
<p >To initialize content of such resource, create a CPU-side (aka "staging") copy of it in system memory - <a class="el" href="group__group__alloc.html#ggaa5846affa1e9da3800e3e78fae2305cca40bdf4cddeffeb12f43d45ca1286e0a5">VMA_MEMORY_USAGE_CPU_ONLY</a>, map it, fill it, and submit a transfer from it to the GPU resource. You can keep the staging copy if you need it for another upload transfer in the future. If you don't, you can destroy it or reuse this buffer for uploading different resource after the transfer finishes.</p>
|
||||
<p >Prefer to create just buffers in system memory rather than images, even for uploading textures. Use <code>vkCmdCopyBufferToImage()</code>. Dont use images with <code>VK_IMAGE_TILING_LINEAR</code>.</p>
|
||||
<h2><a class="anchor" id="usage_patterns_dynamic_resources"></a>
|
||||
Dynamic resources</h2>
|
||||
<p ><b>When:</b> Any resources that change frequently (aka "dynamic"), e.g. every frame or every draw call, written on CPU, read on GPU.</p>
|
||||
<p ><b>What to do:</b> Create them using <a class="el" href="group__group__alloc.html#ggaa5846affa1e9da3800e3e78fae2305cca9066b52c5a7079bb74a69aaf8b92ff67">VMA_MEMORY_USAGE_CPU_TO_GPU</a>. You can map it and write to it directly on CPU, as well as read from it on GPU.</p>
|
||||
<p >This is a more complex situation. Different solutions are possible, and the best one depends on specific GPU type, but you can use this simple approach for the start. Prefer to write to such resource sequentially (e.g. using <code>memcpy</code>). Don't perform random access or any reads from it on CPU, as it may be very slow. Also note that textures written directly from the host through a mapped pointer need to be in LINEAR not OPTIMAL layout.</p>
|
||||
<h2><a class="anchor" id="usage_patterns_readback"></a>
|
||||
Readback</h2>
|
||||
<p ><b>When:</b> Resources that contain data written by GPU that you want to read back on CPU, e.g. results of some computations.</p>
|
||||
<p ><b>What to do:</b> Create them using <a class="el" href="group__group__alloc.html#ggaa5846affa1e9da3800e3e78fae2305cca7b586d2fdaf82a463b58f581ed72be27">VMA_MEMORY_USAGE_GPU_TO_CPU</a>. You can write to them directly on GPU, as well as map and read them on CPU.</p>
|
||||
<h1><a class="anchor" id="usage_patterns_advanced"></a>
|
||||
Advanced patterns</h1>
|
||||
<h2><a class="anchor" id="usage_patterns_integrated_graphics"></a>
|
||||
Detecting integrated graphics</h2>
|
||||
<p >You can support integrated graphics (like Intel HD Graphics, AMD APU) better by detecting it in Vulkan. To do it, call <code>vkGetPhysicalDeviceProperties()</code>, inspect <code>VkPhysicalDeviceProperties::deviceType</code> and look for <code>VK_PHYSICAL_DEVICE_TYPE_INTEGRATED_GPU</code>. When you find it, you can assume that memory is unified and all memory types are comparably fast to access from GPU, regardless of <code>VK_MEMORY_PROPERTY_DEVICE_LOCAL_BIT</code>.</p>
|
||||
<p >You can then sum up sizes of all available memory heaps and treat them as useful for your GPU resources, instead of only <code>DEVICE_LOCAL</code> ones. You can also prefer to create your resources in memory types that are <code>HOST_VISIBLE</code> to map them directly instead of submitting explicit transfer (see below).</p>
|
||||
<h2><a class="anchor" id="usage_patterns_direct_vs_transfer"></a>
|
||||
Direct access versus transfer</h2>
|
||||
<p >For resources that you frequently write on CPU and read on GPU, many solutions are possible:</p>
|
||||
<p ><b>What to do:</b> Let the library select the optimal memory type, which will likely have <code>VK_MEMORY_PROPERTY_DEVICE_LOCAL_BIT</code>.</p>
|
||||
<div class="fragment"><div class="line">VkImageCreateInfo imgCreateInfo = { VK_STRUCTURE_TYPE_IMAGE_CREATE_INFO };</div>
|
||||
<div class="line">imgCreateInfo.imageType = VK_IMAGE_TYPE_2D;</div>
|
||||
<div class="line">imgCreateInfo.extent.width = 3840;</div>
|
||||
<div class="line">imgCreateInfo.extent.height = 2160;</div>
|
||||
<div class="line">imgCreateInfo.extent.depth = 1;</div>
|
||||
<div class="line">imgCreateInfo.mipLevels = 1;</div>
|
||||
<div class="line">imgCreateInfo.arrayLayers = 1;</div>
|
||||
<div class="line">imgCreateInfo.format = VK_FORMAT_R8G8B8A8_UNORM;</div>
|
||||
<div class="line">imgCreateInfo.tiling = VK_IMAGE_TILING_OPTIMAL;</div>
|
||||
<div class="line">imgCreateInfo.initialLayout = VK_IMAGE_LAYOUT_UNDEFINED;</div>
|
||||
<div class="line">imgCreateInfo.usage = VK_IMAGE_USAGE_SAMPLED_BIT | VK_IMAGE_USAGE_COLOR_ATTACHMENT_BIT;</div>
|
||||
<div class="line">imgCreateInfo.samples = VK_SAMPLE_COUNT_1_BIT;</div>
|
||||
<div class="line"> </div>
|
||||
<div class="line"><a class="code hl_struct" href="struct_vma_allocation_create_info.html">VmaAllocationCreateInfo</a> allocCreateInfo = {};</div>
|
||||
<div class="line">allocCreateInfo.<a class="code hl_variable" href="struct_vma_allocation_create_info.html#accb8b06b1f677d858cb9af20705fa910">usage</a> = <a class="code hl_enumvalue" href="group__group__alloc.html#ggaa5846affa1e9da3800e3e78fae2305cca27cde9026a84d34d525777baa41fce6e">VMA_MEMORY_USAGE_AUTO</a>;</div>
|
||||
<div class="line">allocCreateInfo.<a class="code hl_variable" href="struct_vma_allocation_create_info.html#add09658ac14fe290ace25470ddd6d41b">flags</a> = <a class="code hl_enumvalue" href="group__group__alloc.html#ggad9889c10c798b040d59c92f257cae597a3fc311d855c2ff53f1090ef5c722b38f">VMA_ALLOCATION_CREATE_DEDICATED_MEMORY_BIT</a>;</div>
|
||||
<div class="line"> </div>
|
||||
<div class="line">VkImage img;</div>
|
||||
<div class="line"><a class="code hl_struct" href="struct_vma_allocation.html">VmaAllocation</a> alloc;</div>
|
||||
<div class="line"><a class="code hl_function" href="group__group__alloc.html#ga02a94f25679275851a53e82eacbcfc73">vmaCreateImage</a>(allocator, &imgCreateInfo, &allocCreateInfo, &img, &alloc, <span class="keyword">nullptr</span>);</div>
|
||||
<div class="ttc" id="agroup__group__alloc_html_ga02a94f25679275851a53e82eacbcfc73"><div class="ttname"><a href="group__group__alloc.html#ga02a94f25679275851a53e82eacbcfc73">vmaCreateImage</a></div><div class="ttdeci">VkResult vmaCreateImage(VmaAllocator allocator, const VkImageCreateInfo *pImageCreateInfo, const VmaAllocationCreateInfo *pAllocationCreateInfo, VkImage *pImage, VmaAllocation *pAllocation, VmaAllocationInfo *pAllocationInfo)</div><div class="ttdoc">Function similar to vmaCreateBuffer().</div></div>
|
||||
<div class="ttc" id="agroup__group__alloc_html_ggaa5846affa1e9da3800e3e78fae2305cca27cde9026a84d34d525777baa41fce6e"><div class="ttname"><a href="group__group__alloc.html#ggaa5846affa1e9da3800e3e78fae2305cca27cde9026a84d34d525777baa41fce6e">VMA_MEMORY_USAGE_AUTO</a></div><div class="ttdeci">@ VMA_MEMORY_USAGE_AUTO</div><div class="ttdef"><b>Definition:</b> vk_mem_alloc.h:492</div></div>
|
||||
<div class="ttc" id="agroup__group__alloc_html_ggad9889c10c798b040d59c92f257cae597a3fc311d855c2ff53f1090ef5c722b38f"><div class="ttname"><a href="group__group__alloc.html#ggad9889c10c798b040d59c92f257cae597a3fc311d855c2ff53f1090ef5c722b38f">VMA_ALLOCATION_CREATE_DEDICATED_MEMORY_BIT</a></div><div class="ttdeci">@ VMA_ALLOCATION_CREATE_DEDICATED_MEMORY_BIT</div><div class="ttdoc">Set this flag if the allocation should have its own memory block.</div><div class="ttdef"><b>Definition:</b> vk_mem_alloc.h:528</div></div>
|
||||
<div class="ttc" id="astruct_vma_allocation_create_info_html"><div class="ttname"><a href="struct_vma_allocation_create_info.html">VmaAllocationCreateInfo</a></div><div class="ttdef"><b>Definition:</b> vk_mem_alloc.h:1168</div></div>
|
||||
<div class="ttc" id="astruct_vma_allocation_create_info_html_accb8b06b1f677d858cb9af20705fa910"><div class="ttname"><a href="struct_vma_allocation_create_info.html#accb8b06b1f677d858cb9af20705fa910">VmaAllocationCreateInfo::usage</a></div><div class="ttdeci">VmaMemoryUsage usage</div><div class="ttdoc">Intended usage of memory.</div><div class="ttdef"><b>Definition:</b> vk_mem_alloc.h:1176</div></div>
|
||||
<div class="ttc" id="astruct_vma_allocation_create_info_html_add09658ac14fe290ace25470ddd6d41b"><div class="ttname"><a href="struct_vma_allocation_create_info.html#add09658ac14fe290ace25470ddd6d41b">VmaAllocationCreateInfo::flags</a></div><div class="ttdeci">VmaAllocationCreateFlags flags</div><div class="ttdoc">Use VmaAllocationCreateFlagBits enum.</div><div class="ttdef"><b>Definition:</b> vk_mem_alloc.h:1170</div></div>
|
||||
<div class="ttc" id="astruct_vma_allocation_html"><div class="ttname"><a href="struct_vma_allocation.html">VmaAllocation</a></div><div class="ttdoc">Represents single memory allocation.</div></div>
|
||||
</div><!-- fragment --><p ><b>Also consider:</b> Consider creating them as dedicated allocations using <a class="el" href="group__group__alloc.html#ggad9889c10c798b040d59c92f257cae597a3fc311d855c2ff53f1090ef5c722b38f" title="Set this flag if the allocation should have its own memory block.">VMA_ALLOCATION_CREATE_DEDICATED_MEMORY_BIT</a>, especially if they are large or if you plan to destroy and recreate them with different sizes e.g. when display resolution changes. Prefer to create such resources first and all other GPU resources (like textures and vertex buffers) later.</p>
|
||||
<h1><a class="anchor" id="usage_patterns_staging_copy_upload"></a>
|
||||
Staging copy for upload</h1>
|
||||
<p ><b>When:</b> A "staging" buffer than you want to map and fill from CPU code, then use as a source od transfer to some GPU resource.</p>
|
||||
<p ><b>What to do:</b> Use flag <a class="el" href="group__group__alloc.html#ggad9889c10c798b040d59c92f257cae597a9be224df3bfc1cfa06203aed689a30c5">VMA_ALLOCATION_CREATE_HOST_ACCESS_SEQUENTIAL_WRITE_BIT</a>. Let the library select the optimal memory type, which will always have <code>VK_MEMORY_PROPERTY_HOST_VISIBLE_BIT</code>.</p>
|
||||
<div class="fragment"><div class="line">VkBufferCreateInfo bufCreateInfo = { VK_STRUCTURE_TYPE_BUFFER_CREATE_INFO };</div>
|
||||
<div class="line">bufCreateInfo.size = 65536;</div>
|
||||
<div class="line">bufCreateInfo.usage = VK_BUFFER_USAGE_TRANSFER_SRC_BIT;</div>
|
||||
<div class="line"> </div>
|
||||
<div class="line"><a class="code hl_struct" href="struct_vma_allocation_create_info.html">VmaAllocationCreateInfo</a> allocCreateInfo = {};</div>
|
||||
<div class="line">allocCreateInfo.<a class="code hl_variable" href="struct_vma_allocation_create_info.html#accb8b06b1f677d858cb9af20705fa910">usage</a> = <a class="code hl_enumvalue" href="group__group__alloc.html#ggaa5846affa1e9da3800e3e78fae2305cca27cde9026a84d34d525777baa41fce6e">VMA_MEMORY_USAGE_AUTO</a>;</div>
|
||||
<div class="line">allocCreateInfo.<a class="code hl_variable" href="struct_vma_allocation_create_info.html#add09658ac14fe290ace25470ddd6d41b">flags</a> = <a class="code hl_enumvalue" href="group__group__alloc.html#ggad9889c10c798b040d59c92f257cae597a9be224df3bfc1cfa06203aed689a30c5">VMA_ALLOCATION_CREATE_HOST_ACCESS_SEQUENTIAL_WRITE_BIT</a> |</div>
|
||||
<div class="line"> <a class="code hl_enumvalue" href="group__group__alloc.html#ggad9889c10c798b040d59c92f257cae597a11da372cc3a82931c5e5d6146cd9dd1f">VMA_ALLOCATION_CREATE_MAPPED_BIT</a>;</div>
|
||||
<div class="line"> </div>
|
||||
<div class="line">VkBuffer buf;</div>
|
||||
<div class="line"><a class="code hl_struct" href="struct_vma_allocation.html">VmaAllocation</a> alloc;</div>
|
||||
<div class="line"><a class="code hl_struct" href="struct_vma_allocation_info.html">VmaAllocationInfo</a> allocInfo;</div>
|
||||
<div class="line"><a class="code hl_function" href="group__group__alloc.html#gac72ee55598617e8eecca384e746bab51">vmaCreateBuffer</a>(allocator, &bufCreateInfo, &allocCreateInfo, &buf, &alloc, &allocInfo);</div>
|
||||
<div class="line"> </div>
|
||||
<div class="line">...</div>
|
||||
<div class="line"> </div>
|
||||
<div class="line">memcpy(allocInfo.<a class="code hl_variable" href="struct_vma_allocation_info.html#a5eeffbe2d2f30f53370ff14aefbadbe2">pMappedData</a>, myData, myDataSize);</div>
|
||||
<div class="ttc" id="agroup__group__alloc_html_gac72ee55598617e8eecca384e746bab51"><div class="ttname"><a href="group__group__alloc.html#gac72ee55598617e8eecca384e746bab51">vmaCreateBuffer</a></div><div class="ttdeci">VkResult vmaCreateBuffer(VmaAllocator allocator, const VkBufferCreateInfo *pBufferCreateInfo, const VmaAllocationCreateInfo *pAllocationCreateInfo, VkBuffer *pBuffer, VmaAllocation *pAllocation, VmaAllocationInfo *pAllocationInfo)</div></div>
|
||||
<div class="ttc" id="agroup__group__alloc_html_ggad9889c10c798b040d59c92f257cae597a11da372cc3a82931c5e5d6146cd9dd1f"><div class="ttname"><a href="group__group__alloc.html#ggad9889c10c798b040d59c92f257cae597a11da372cc3a82931c5e5d6146cd9dd1f">VMA_ALLOCATION_CREATE_MAPPED_BIT</a></div><div class="ttdeci">@ VMA_ALLOCATION_CREATE_MAPPED_BIT</div><div class="ttdoc">Set this flag to use a memory that will be persistently mapped and retrieve pointer to it.</div><div class="ttdef"><b>Definition:</b> vk_mem_alloc.h:550</div></div>
|
||||
<div class="ttc" id="agroup__group__alloc_html_ggad9889c10c798b040d59c92f257cae597a9be224df3bfc1cfa06203aed689a30c5"><div class="ttname"><a href="group__group__alloc.html#ggad9889c10c798b040d59c92f257cae597a9be224df3bfc1cfa06203aed689a30c5">VMA_ALLOCATION_CREATE_HOST_ACCESS_SEQUENTIAL_WRITE_BIT</a></div><div class="ttdeci">@ VMA_ALLOCATION_CREATE_HOST_ACCESS_SEQUENTIAL_WRITE_BIT</div><div class="ttdef"><b>Definition:</b> vk_mem_alloc.h:597</div></div>
|
||||
<div class="ttc" id="astruct_vma_allocation_info_html"><div class="ttname"><a href="struct_vma_allocation_info.html">VmaAllocationInfo</a></div><div class="ttdoc">Parameters of VmaAllocation objects, that can be retrieved using function vmaGetAllocationInfo().</div><div class="ttdef"><b>Definition:</b> vk_mem_alloc.h:1310</div></div>
|
||||
<div class="ttc" id="astruct_vma_allocation_info_html_a5eeffbe2d2f30f53370ff14aefbadbe2"><div class="ttname"><a href="struct_vma_allocation_info.html#a5eeffbe2d2f30f53370ff14aefbadbe2">VmaAllocationInfo::pMappedData</a></div><div class="ttdeci">void * pMappedData</div><div class="ttdoc">Pointer to the beginning of this allocation as mapped data.</div><div class="ttdef"><b>Definition:</b> vk_mem_alloc.h:1352</div></div>
|
||||
</div><!-- fragment --><p ><b>Also consider:</b> You can map the allocation using <a class="el" href="group__group__alloc.html#gad5bd1243512d099706de88168992f069" title="Maps memory represented by given allocation and returns pointer to it.">vmaMapMemory()</a> or you can create it as persistenly mapped using <a class="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>, as in the example above.</p>
|
||||
<h1><a class="anchor" id="usage_patterns_readback"></a>
|
||||
Readback</h1>
|
||||
<p ><b>When:</b> Buffers for data written by or transferred from the GPU that you want to read back on the CPU, e.g. results of some computations.</p>
|
||||
<p ><b>What to do:</b> Use flag <a class="el" href="group__group__alloc.html#ggad9889c10c798b040d59c92f257cae597add61238d98e20917b9a06c617763f492">VMA_ALLOCATION_CREATE_HOST_ACCESS_RANDOM_BIT</a>. Let the library select the optimal memory type, which will always have <code>VK_MEMORY_PROPERTY_HOST_VISIBLE_BIT</code> and <code>VK_MEMORY_PROPERTY_HOST_CACHED_BIT</code>.</p>
|
||||
<div class="fragment"><div class="line">VkBufferCreateInfo bufCreateInfo = { VK_STRUCTURE_TYPE_BUFFER_CREATE_INFO };</div>
|
||||
<div class="line">bufCreateInfo.size = 65536;</div>
|
||||
<div class="line">bufCreateInfo.usage = VK_BUFFER_USAGE_TRANSFER_DST_BIT;</div>
|
||||
<div class="line"> </div>
|
||||
<div class="line"><a class="code hl_struct" href="struct_vma_allocation_create_info.html">VmaAllocationCreateInfo</a> allocCreateInfo = {};</div>
|
||||
<div class="line">allocCreateInfo.<a class="code hl_variable" href="struct_vma_allocation_create_info.html#accb8b06b1f677d858cb9af20705fa910">usage</a> = <a class="code hl_enumvalue" href="group__group__alloc.html#ggaa5846affa1e9da3800e3e78fae2305cca27cde9026a84d34d525777baa41fce6e">VMA_MEMORY_USAGE_AUTO</a>;</div>
|
||||
<div class="line">allocCreateInfo.<a class="code hl_variable" href="struct_vma_allocation_create_info.html#add09658ac14fe290ace25470ddd6d41b">flags</a> = <a class="code hl_enumvalue" href="group__group__alloc.html#ggad9889c10c798b040d59c92f257cae597add61238d98e20917b9a06c617763f492">VMA_ALLOCATION_CREATE_HOST_ACCESS_RANDOM_BIT</a> |</div>
|
||||
<div class="line"> <a class="code hl_enumvalue" href="group__group__alloc.html#ggad9889c10c798b040d59c92f257cae597a11da372cc3a82931c5e5d6146cd9dd1f">VMA_ALLOCATION_CREATE_MAPPED_BIT</a>;</div>
|
||||
<div class="line"> </div>
|
||||
<div class="line">VkBuffer buf;</div>
|
||||
<div class="line"><a class="code hl_struct" href="struct_vma_allocation.html">VmaAllocation</a> alloc;</div>
|
||||
<div class="line"><a class="code hl_struct" href="struct_vma_allocation_info.html">VmaAllocationInfo</a> allocInfo;</div>
|
||||
<div class="line"><a class="code hl_function" href="group__group__alloc.html#gac72ee55598617e8eecca384e746bab51">vmaCreateBuffer</a>(allocator, &bufCreateInfo, &allocCreateInfo, &buf, &alloc, &allocInfo);</div>
|
||||
<div class="line"> </div>
|
||||
<div class="line">...</div>
|
||||
<div class="line"> </div>
|
||||
<div class="line">const <span class="keywordtype">float</span>* downloadedData = (<span class="keyword">const</span> <span class="keywordtype">float</span>*)allocInfo.<a class="code hl_variable" href="struct_vma_allocation_info.html#a5eeffbe2d2f30f53370ff14aefbadbe2">pMappedData</a>;</div>
|
||||
<div class="ttc" id="agroup__group__alloc_html_ggad9889c10c798b040d59c92f257cae597add61238d98e20917b9a06c617763f492"><div class="ttname"><a href="group__group__alloc.html#ggad9889c10c798b040d59c92f257cae597add61238d98e20917b9a06c617763f492">VMA_ALLOCATION_CREATE_HOST_ACCESS_RANDOM_BIT</a></div><div class="ttdeci">@ VMA_ALLOCATION_CREATE_HOST_ACCESS_RANDOM_BIT</div><div class="ttdef"><b>Definition:</b> vk_mem_alloc.h:609</div></div>
|
||||
</div><!-- fragment --><h1><a class="anchor" id="usage_patterns_advanced_data_uploading"></a>
|
||||
Advanced data uploading</h1>
|
||||
<p >For resources that you frequently write on CPU via mapped pointer and freqnently read on GPU e.g. as a uniform buffer (also called "dynamic"), multiple options are possible:</p>
|
||||
<ol type="1">
|
||||
<li>Create one copy in video memory using <a class="el" href="group__group__alloc.html#ggaa5846affa1e9da3800e3e78fae2305ccac6b5dc1432d88647aa4cd456246eadf7">VMA_MEMORY_USAGE_GPU_ONLY</a>, second copy in system memory using <a class="el" href="group__group__alloc.html#ggaa5846affa1e9da3800e3e78fae2305cca40bdf4cddeffeb12f43d45ca1286e0a5">VMA_MEMORY_USAGE_CPU_ONLY</a> and submit explicit transfer each time.</li>
|
||||
<li>Create just a single copy using <a class="el" href="group__group__alloc.html#ggaa5846affa1e9da3800e3e78fae2305cca9066b52c5a7079bb74a69aaf8b92ff67">VMA_MEMORY_USAGE_CPU_TO_GPU</a>, map it and fill it on CPU, read it directly on GPU.</li>
|
||||
<li>Create just a single copy using <a class="el" href="group__group__alloc.html#ggaa5846affa1e9da3800e3e78fae2305cca40bdf4cddeffeb12f43d45ca1286e0a5">VMA_MEMORY_USAGE_CPU_ONLY</a>, map it and fill it on CPU, read it directly on GPU.</li>
|
||||
</ol>
|
||||
<p >Which solution is the most efficient depends on your resource and especially on the GPU. It is best to measure it and then make the decision. Some general recommendations:</p>
|
||||
<ul>
|
||||
<li>On integrated graphics use (2) or (3) to avoid unnecessary time and memory overhead related to using a second copy and making transfer.</li>
|
||||
<li>For small resources (e.g. constant buffers) use (2). Discrete AMD cards have special 256 MiB pool of video memory that is directly mappable. Even if the resource ends up in system memory, its data may be cached on GPU after first fetch over PCIe bus.</li>
|
||||
<li>For larger resources (e.g. textures), decide between (1) and (2). You may want to differentiate NVIDIA and AMD, e.g. by looking for memory type that is both <code>DEVICE_LOCAL</code> and <code>HOST_VISIBLE</code>. When you find it, use (2), otherwise use (1).</li>
|
||||
<li>Easiest solution is to have one copy of the resource in <code>HOST_VISIBLE</code> memory, even if it means system RAM (not <code>DEVICE_LOCAL</code>) on systems with a discrete graphics card, and make the device reach out to that resource directly.<ul>
|
||||
<li>Reads performed by the device will then go through PCI Express bus. The performace of this access may be limited, but it may be fine depending on the size of this resource (whether it is small enough to quickly end up in GPU cache) and the sparsity of access.</li>
|
||||
</ul>
|
||||
<p >Similarly, for resources that you frequently write on GPU and read on CPU, multiple solutions are possible:</p>
|
||||
<ol type="1">
|
||||
<li>Create one copy in video memory using <a class="el" href="group__group__alloc.html#ggaa5846affa1e9da3800e3e78fae2305ccac6b5dc1432d88647aa4cd456246eadf7">VMA_MEMORY_USAGE_GPU_ONLY</a>, second copy in system memory using <a class="el" href="group__group__alloc.html#ggaa5846affa1e9da3800e3e78fae2305cca7b586d2fdaf82a463b58f581ed72be27">VMA_MEMORY_USAGE_GPU_TO_CPU</a> and submit explicit tranfer each time.</li>
|
||||
<li>Create just single copy using <a class="el" href="group__group__alloc.html#ggaa5846affa1e9da3800e3e78fae2305cca7b586d2fdaf82a463b58f581ed72be27">VMA_MEMORY_USAGE_GPU_TO_CPU</a>, write to it directly on GPU, map it and read it on CPU.</li>
|
||||
</li>
|
||||
<li>On systems with unified memory (e.g. AMD APU or Intel integrated graphics, mobile chips), a memory type may be available that is both <code>HOST_VISIBLE</code> (available for mapping) and <code>DEVICE_LOCAL</code> (fast to access from the GPU). Then, it is likely the best choice for such type of resource.</li>
|
||||
<li>Systems with a discrete graphics card and separate video memory may or may not expose a memory type that is both <code>HOST_VISIBLE</code> and <code>DEVICE_LOCAL</code>, also known as Base Address Register (BAR). If they do, it represents a piece of VRAM (or entire VRAM, if ReBAR is enabled in the motherboard BIOS) that is available to CPU for mapping.<ul>
|
||||
<li>Writes performed by the host to that memory go through PCI Express bus. The performance of these writes may be limited, but it may be fine, especially on PCIe 4.0, as long as rules of using uncached and write-combined memory are followed - only sequential writes and no reads.</li>
|
||||
</ul>
|
||||
</li>
|
||||
<li>Finally, you may need or prefer to create a separate copy of the resource in <code>DEVICE_LOCAL</code> memory, a separate "staging" copy in <code>HOST_VISIBLE</code> memory and perform an explicit transfer command between them.</li>
|
||||
</ol>
|
||||
<p >You should take some measurements to decide which option is faster in case of your specific resource.</p>
|
||||
<p >Note that textures accessed directly from the host through a mapped pointer need to be in LINEAR layout, which may slow down their usage on the device. Textures accessed only by the device and transfer operations can use OPTIMAL layout.</p>
|
||||
<p >If you don't want to specialize your code for specific types of GPUs, you can still make an simple optimization for cases when your resource ends up in mappable memory to use it directly in this case instead of creating CPU-side staging copy. For details see <a class="el" href="memory_mapping.html#memory_mapping_finding_if_memory_mappable">Finding out if memory is mappable</a>. </p>
|
||||
<p >Thankfully, VMA offers an aid to create and use such resources in the the way optimal for the current Vulkan device. To help the library make the best choice, use flag <a class="el" href="group__group__alloc.html#ggad9889c10c798b040d59c92f257cae597a9be224df3bfc1cfa06203aed689a30c5">VMA_ALLOCATION_CREATE_HOST_ACCESS_SEQUENTIAL_WRITE_BIT</a> together with <a class="el" href="group__group__alloc.html#ggad9889c10c798b040d59c92f257cae597a11337f96eacf34c1016c339eac165cad">VMA_ALLOCATION_CREATE_HOST_ACCESS_ALLOW_TRANSFER_INSTEAD_BIT</a>. It will then prefer a memory type that is both <code>DEVICE_LOCAL</code> and <code>HOST_VISIBLE</code> (integrated memory or BAR), but if no such memory type is available or allocation from it fails (PC graphics cards have only 256 MB of BAR by default, unless ReBAR is supported and enabled in BIOS), it will fall back to <code>DEVICE_LOCAL</code> memory for fast GPU access. It is then up to you to detect that the allocation ended up in a memory type that is not <code>HOST_VISIBLE</code>, so you need to create another "staging" allocation and perform explicit transfers.</p>
|
||||
<div class="fragment"><div class="line">VkBufferCreateInfo bufCreateInfo = { VK_STRUCTURE_TYPE_BUFFER_CREATE_INFO };</div>
|
||||
<div class="line">bufCreateInfo.size = 65536;</div>
|
||||
<div class="line">bufCreateInfo.usage = VK_BUFFER_USAGE_UNIFORM_BUFFER_BIT | VK_BUFFER_USAGE_TRANSFER_DST_BIT;</div>
|
||||
<div class="line"> </div>
|
||||
<div class="line"><a class="code hl_struct" href="struct_vma_allocation_create_info.html">VmaAllocationCreateInfo</a> allocCreateInfo = {};</div>
|
||||
<div class="line">allocCreateInfo.<a class="code hl_variable" href="struct_vma_allocation_create_info.html#accb8b06b1f677d858cb9af20705fa910">usage</a> = <a class="code hl_enumvalue" href="group__group__alloc.html#ggaa5846affa1e9da3800e3e78fae2305cca27cde9026a84d34d525777baa41fce6e">VMA_MEMORY_USAGE_AUTO</a>;</div>
|
||||
<div class="line">allocCreateInfo.<a class="code hl_variable" href="struct_vma_allocation_create_info.html#add09658ac14fe290ace25470ddd6d41b">flags</a> = <a class="code hl_enumvalue" href="group__group__alloc.html#ggad9889c10c798b040d59c92f257cae597a9be224df3bfc1cfa06203aed689a30c5">VMA_ALLOCATION_CREATE_HOST_ACCESS_SEQUENTIAL_WRITE_BIT</a> |</div>
|
||||
<div class="line"> <a class="code hl_enumvalue" href="group__group__alloc.html#ggad9889c10c798b040d59c92f257cae597a11337f96eacf34c1016c339eac165cad">VMA_ALLOCATION_CREATE_HOST_ACCESS_ALLOW_TRANSFER_INSTEAD_BIT</a> |</div>
|
||||
<div class="line"> <a class="code hl_enumvalue" href="group__group__alloc.html#ggad9889c10c798b040d59c92f257cae597a11da372cc3a82931c5e5d6146cd9dd1f">VMA_ALLOCATION_CREATE_MAPPED_BIT</a>;</div>
|
||||
<div class="line"> </div>
|
||||
<div class="line">VkBuffer buf;</div>
|
||||
<div class="line"><a class="code hl_struct" href="struct_vma_allocation.html">VmaAllocation</a> alloc;</div>
|
||||
<div class="line"><a class="code hl_struct" href="struct_vma_allocation_info.html">VmaAllocationInfo</a> allocInfo;</div>
|
||||
<div class="line"><a class="code hl_function" href="group__group__alloc.html#gac72ee55598617e8eecca384e746bab51">vmaCreateBuffer</a>(allocator, &bufCreateInfo, &allocCreateInfo, &buf, &alloc, &allocInfo);</div>
|
||||
<div class="line"> </div>
|
||||
<div class="line">VkMemoryPropertyFlags memPropFlags;</div>
|
||||
<div class="line"><a class="code hl_function" href="group__group__alloc.html#ga571e87dd38e552249b56b1b0b982fad1">vmaGetAllocationMemoryProperties</a>(allocator, alloc, &memPropFlags);</div>
|
||||
<div class="line"> </div>
|
||||
<div class="line"><span class="keywordflow">if</span>(memPropFlags & VK_MEMORY_PROPERTY_HOST_VISIBLE_BIT)</div>
|
||||
<div class="line">{</div>
|
||||
<div class="line"> <span class="comment">// Allocation ended up in a mappable memory and is already mapped - write to it directly.</span></div>
|
||||
<div class="line"> </div>
|
||||
<div class="line"> <span class="comment">// [Executed in runtime]:</span></div>
|
||||
<div class="line"> memcpy(allocInfo.<a class="code hl_variable" href="struct_vma_allocation_info.html#a5eeffbe2d2f30f53370ff14aefbadbe2">pMappedData</a>, myData, myDataSize);</div>
|
||||
<div class="line">}</div>
|
||||
<div class="line"><span class="keywordflow">else</span></div>
|
||||
<div class="line">{</div>
|
||||
<div class="line"> <span class="comment">// Allocation ended up in a non-mappable memory - need to transfer.</span></div>
|
||||
<div class="line"> VkBufferCreateInfo stagingBufCreateInfo = { VK_STRUCTURE_TYPE_BUFFER_CREATE_INFO };</div>
|
||||
<div class="line"> stagingBufCreateInfo.size = 65536;</div>
|
||||
<div class="line"> stagingBufCreateInfo.usage = VK_BUFFER_USAGE_TRANSFER_SRC_BIT;</div>
|
||||
<div class="line"> </div>
|
||||
<div class="line"> <a class="code hl_struct" href="struct_vma_allocation_create_info.html">VmaAllocationCreateInfo</a> stagingAllocCreateInfo = {};</div>
|
||||
<div class="line"> stagingAllocCreateInfo.<a class="code hl_variable" href="struct_vma_allocation_create_info.html#accb8b06b1f677d858cb9af20705fa910">usage</a> = <a class="code hl_enumvalue" href="group__group__alloc.html#ggaa5846affa1e9da3800e3e78fae2305cca27cde9026a84d34d525777baa41fce6e">VMA_MEMORY_USAGE_AUTO</a>;</div>
|
||||
<div class="line"> stagingAllocCreateInfo.<a class="code hl_variable" href="struct_vma_allocation_create_info.html#add09658ac14fe290ace25470ddd6d41b">flags</a> = <a class="code hl_enumvalue" href="group__group__alloc.html#ggad9889c10c798b040d59c92f257cae597a9be224df3bfc1cfa06203aed689a30c5">VMA_ALLOCATION_CREATE_HOST_ACCESS_SEQUENTIAL_WRITE_BIT</a> |</div>
|
||||
<div class="line"> <a class="code hl_enumvalue" href="group__group__alloc.html#ggad9889c10c798b040d59c92f257cae597a11da372cc3a82931c5e5d6146cd9dd1f">VMA_ALLOCATION_CREATE_MAPPED_BIT</a>;</div>
|
||||
<div class="line"> </div>
|
||||
<div class="line"> VkBuffer stagingBuf;</div>
|
||||
<div class="line"> <a class="code hl_struct" href="struct_vma_allocation.html">VmaAllocation</a> stagingAlloc;</div>
|
||||
<div class="line"> <a class="code hl_struct" href="struct_vma_allocation_info.html">VmaAllocationInfo</a> stagingAllocInfo;</div>
|
||||
<div class="line"> <a class="code hl_function" href="group__group__alloc.html#gac72ee55598617e8eecca384e746bab51">vmaCreateBuffer</a>(allocator, &stagingBufCreateInfo, &stagingAllocCreateInfo,</div>
|
||||
<div class="line"> &stagingBuf, &stagingAlloc, stagingAllocInfo);</div>
|
||||
<div class="line"> </div>
|
||||
<div class="line"> <span class="comment">// [Executed in runtime]:</span></div>
|
||||
<div class="line"> memcpy(stagingAllocInfo.<a class="code hl_variable" href="struct_vma_allocation_info.html#a5eeffbe2d2f30f53370ff14aefbadbe2">pMappedData</a>, myData, myDataSize);</div>
|
||||
<div class="line"> VkBufferCopy bufCopy = {</div>
|
||||
<div class="line"> 0, <span class="comment">// srcOffset</span></div>
|
||||
<div class="line"> 0, <span class="comment">// dstOffset,</span></div>
|
||||
<div class="line"> myDataSize); <span class="comment">// size</span></div>
|
||||
<div class="line"> vkCmdCopyBuffer(cmdBuf, stagingBuf, buf, 1, &bufCopy);</div>
|
||||
<div class="line">}</div>
|
||||
<div class="ttc" id="agroup__group__alloc_html_ga571e87dd38e552249b56b1b0b982fad1"><div class="ttname"><a href="group__group__alloc.html#ga571e87dd38e552249b56b1b0b982fad1">vmaGetAllocationMemoryProperties</a></div><div class="ttdeci">void vmaGetAllocationMemoryProperties(VmaAllocator allocator, VmaAllocation allocation, VkMemoryPropertyFlags *pFlags)</div><div class="ttdoc">Given an allocation, returns Property Flags of its memory type.</div></div>
|
||||
<div class="ttc" id="agroup__group__alloc_html_ggad9889c10c798b040d59c92f257cae597a11337f96eacf34c1016c339eac165cad"><div class="ttname"><a href="group__group__alloc.html#ggad9889c10c798b040d59c92f257cae597a11337f96eacf34c1016c339eac165cad">VMA_ALLOCATION_CREATE_HOST_ACCESS_ALLOW_TRANSFER_INSTEAD_BIT</a></div><div class="ttdeci">@ VMA_ALLOCATION_CREATE_HOST_ACCESS_ALLOW_TRANSFER_INSTEAD_BIT</div><div class="ttdef"><b>Definition:</b> vk_mem_alloc.h:621</div></div>
|
||||
</div><!-- fragment --><h1><a class="anchor" id="usage_patterns_other_use_cases"></a>
|
||||
Other use cases</h1>
|
||||
<p >Here are some other, less obvious use cases and their recommended settings:</p>
|
||||
<ul>
|
||||
<li>An image that is used only as transfer source and destination, but it should stay on the device, as it is used to temporarily store a copy of some texture, e.g. from the current to the next frame, for temporal antialiasing or other temporal effects.<ul>
|
||||
<li>Use <code>VkImageCreateInfo::usage = VK_IMAGE_USAGE_TRANSFER_SRC_BIT | VK_IMAGE_USAGE_TRANSFER_DST_BIT</code></li>
|
||||
<li>Use <a class="el" href="struct_vma_allocation_create_info.html#accb8b06b1f677d858cb9af20705fa910" title="Intended usage of memory.">VmaAllocationCreateInfo::usage</a> = <a class="el" href="group__group__alloc.html#ggaa5846affa1e9da3800e3e78fae2305cca27cde9026a84d34d525777baa41fce6e">VMA_MEMORY_USAGE_AUTO</a></li>
|
||||
</ul>
|
||||
</li>
|
||||
<li>An image that is used only as transfer source and destination, but it should be placed in the system RAM despite it doesn't need to be mapped, because it serves as a "swap" copy to evict least recently used textures from VRAM.<ul>
|
||||
<li>Use <code>VkImageCreateInfo::usage = VK_IMAGE_USAGE_TRANSFER_SRC_BIT | VK_IMAGE_USAGE_TRANSFER_DST_BIT</code></li>
|
||||
<li>Use <a class="el" href="struct_vma_allocation_create_info.html#accb8b06b1f677d858cb9af20705fa910" title="Intended usage of memory.">VmaAllocationCreateInfo::usage</a> = <a class="el" href="group__group__alloc.html#ggaa5846affa1e9da3800e3e78fae2305cca9b422585242160b8ed3418310ee6664d">VMA_MEMORY_USAGE_AUTO_PREFER_HOST</a>, as VMA needs a hint here to differentiate from the previous case.</li>
|
||||
</ul>
|
||||
</li>
|
||||
<li>A buffer that you want to map and write from the CPU, directly read from the GPU (e.g. as a uniform or vertex buffer), but you have a clear preference to place it in device or host memory due to its large size.<ul>
|
||||
<li>Use <code>VkBufferCreateInfo::usage = VK_BUFFER_USAGE_UNIFORM_BUFFER_BIT</code></li>
|
||||
<li>Use <a class="el" href="struct_vma_allocation_create_info.html#accb8b06b1f677d858cb9af20705fa910" title="Intended usage of memory.">VmaAllocationCreateInfo::usage</a> = <a class="el" href="group__group__alloc.html#ggaa5846affa1e9da3800e3e78fae2305ccae2adb696d6a73c18bb20c23666661327">VMA_MEMORY_USAGE_AUTO_PREFER_DEVICE</a> or <a class="el" href="group__group__alloc.html#ggaa5846affa1e9da3800e3e78fae2305cca9b422585242160b8ed3418310ee6664d">VMA_MEMORY_USAGE_AUTO_PREFER_HOST</a></li>
|
||||
<li>Use <a class="el" href="struct_vma_allocation_create_info.html#add09658ac14fe290ace25470ddd6d41b" title="Use VmaAllocationCreateFlagBits enum.">VmaAllocationCreateInfo::flags</a> = <a class="el" href="group__group__alloc.html#ggad9889c10c798b040d59c92f257cae597a9be224df3bfc1cfa06203aed689a30c5">VMA_ALLOCATION_CREATE_HOST_ACCESS_SEQUENTIAL_WRITE_BIT</a> </li>
|
||||
</ul>
|
||||
</li>
|
||||
</ul>
|
||||
</div></div><!-- contents -->
|
||||
</div><!-- PageDoc -->
|
||||
<!-- start footer part -->
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue