mirror/VulkanMemoryAllocator
1
0
Fork 0
mirror of https://github.com/GPUOpen-LibrariesAndSDKs/VulkanMemoryAllocator.git synced 2024-11-22 15:04:34 +00:00
Code Issues Packages Projects Releases Wiki Activity
caf27e0428
VulkanMemoryAllocator/docs/html/allocation_annotation.html
Adam Sawicki caf27e0428 Made allocation Name and UserData separate. COMPATIBILITY BREAKING! 
Added function vmaSetAllocationName. Added member VmaAllocationInfo::pName.
VMA_ALLOCATION_CREATE_USER_DATA_COPY_STRING_BIT is now deprecated but still works.

Code mostly by @medranSolus
2022-03-03 11:23:14 +01:00

135 lines
16 KiB
HTML
Raw Blame History

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "https://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/xhtml;charset=UTF-8"/>
<meta http-equiv="X-UA-Compatible" content="IE=11"/>
<meta name="generator" content="Doxygen 1.9.2"/>
<meta name="viewport" content="width=device-width, initial-scale=1"/>
<title>Vulkan Memory Allocator: Allocation names and user data</title>
<link href="tabs.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="jquery.js"></script>
<script type="text/javascript" src="dynsections.js"></script>
<link href="search/search.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="search/searchdata.js"></script>
<script type="text/javascript" src="search/search.js"></script>
<link href="doxygen.css" rel="stylesheet" type="text/css" />
</head>
<body>
<div id="top"><!-- do not remove this div, it is closed by doxygen! -->
<div id="titlearea">
<table cellspacing="0" cellpadding="0">
<tbody>
<tr style="height: 56px;">
<td id="projectalign" style="padding-left: 0.5em;">
<div id="projectname">Vulkan Memory Allocator
</div>
</td>
</tr>
</tbody>
</table>
</div>
<!-- end header part -->
<!-- Generated by Doxygen 1.9.2 -->
<script type="text/javascript">
/* @license magnet:?xt=urn:btih:d3d9a9a6595521f9666a5e94cc830dab83b65699&amp;dn=expat.txt MIT */
var searchBox = new SearchBox("searchBox", "search",'Search','.html');
/* @license-end */
</script>
<script type="text/javascript" src="menudata.js"></script>
<script type="text/javascript" src="menu.js"></script>
<script type="text/javascript">
/* @license magnet:?xt=urn:btih:d3d9a9a6595521f9666a5e94cc830dab83b65699&amp;dn=expat.txt MIT */
$(function() {
initMenu('',true,false,'search.php','Search');
$(document).ready(function() { init_search(); });
});
/* @license-end */
</script>
<div id="main-nav"></div>
<!-- window showing the filter options -->
<div id="MSearchSelectWindow"
onmouseover="return searchBox.OnSearchSelectShow()"
onmouseout="return searchBox.OnSearchSelectHide()"
onkeydown="return searchBox.OnSearchSelectKey(event)">
</div>
<!-- iframe showing the search results (closed by default) -->
<div id="MSearchResultsWindow">
<iframe src="javascript:void(0)" frameborder="0"
name="MSearchResults" id="MSearchResults">
</iframe>
</div>
<div id="nav-path" class="navpath">
<ul>
<li class="navelem"><a class="el" href="index.html">Vulkan Memory Allocator</a></li> </ul>
</div>
</div><!-- top -->
<div><div class="header">
<div class="headertitle"><div class="title">Allocation names and user data </div></div>
</div><!--header-->
<div class="contents">
<div class="textblock"><h1><a class="anchor" id="allocation_user_data"></a>
Allocation user data</h1>
<p >You can annotate allocations with your own information, e.g. for debugging purposes. To do that, fill <a class="el" href="struct_vma_allocation_create_info.html#a8259e85c272683434f4abb4ddddffe19" title="Custom general-purpose pointer that will be stored in VmaAllocation, can be read as VmaAllocationInfo...">VmaAllocationCreateInfo::pUserData</a> field when creating an allocation. It is an opaque <code>void*</code> pointer. You can use it e.g. as a pointer, some handle, index, key, ordinal number or any other value that would associate the allocation with your custom metadata.</p>
<div class="fragment"><div class="line">VkBufferCreateInfo bufCreateInfo = ...</div>
<div class="line"> </div>
<div class="line">MyBufferMetadata* pMetadata = CreateBufferMetadata();</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#a8259e85c272683434f4abb4ddddffe19">pUserData</a> = pMetadata;</div>
<div class="line"> </div>
<div class="line">VkBuffer buffer;</div>
<div class="line"><a class="code hl_struct" href="struct_vma_allocation.html">VmaAllocation</a> allocation;</div>
<div class="line"><a class="code hl_function" href="group__group__alloc.html#gac72ee55598617e8eecca384e746bab51">vmaCreateBuffer</a>(allocator, &amp;bufCreateInfo, &amp;allocCreateInfo, &amp;buffer, &amp;allocation, <span class="keyword">nullptr</span>);</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 class="ttdoc">Creates a new VkBuffer, allocates and binds memory for it.</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="astruct_vma_allocation_create_info_html"><div class="ttname"><a href="struct_vma_allocation_create_info.html">VmaAllocationCreateInfo</a></div><div class="ttdoc">Parameters of new VmaAllocation.</div><div class="ttdef"><b>Definition:</b> vk_mem_alloc.h:1223</div></div>
<div class="ttc" id="astruct_vma_allocation_create_info_html_a8259e85c272683434f4abb4ddddffe19"><div class="ttname"><a href="struct_vma_allocation_create_info.html#a8259e85c272683434f4abb4ddddffe19">VmaAllocationCreateInfo::pUserData</a></div><div class="ttdeci">void * pUserData</div><div class="ttdoc">Custom general-purpose pointer that will be stored in VmaAllocation, can be read as VmaAllocationInfo...</div><div class="ttdef"><b>Definition:</b> vk_mem_alloc.h:1262</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:1231</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 >The pointer may be later retrieved as <a class="el" href="struct_vma_allocation_info.html#adc507656149c04de7ed95d0042ba2a13" title="Custom general-purpose pointer that was passed as VmaAllocationCreateInfo::pUserData or set using vma...">VmaAllocationInfo::pUserData</a>:</p>
<div class="fragment"><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#ga86dd08aba8633bfa4ad0df2e76481d8b">vmaGetAllocationInfo</a>(allocator, allocation, &amp;allocInfo);</div>
<div class="line">MyBufferMetadata* pMetadata = (MyBufferMetadata*)allocInfo.<a class="code hl_variable" href="struct_vma_allocation_info.html#adc507656149c04de7ed95d0042ba2a13">pUserData</a>;</div>
<div class="ttc" id="agroup__group__alloc_html_ga86dd08aba8633bfa4ad0df2e76481d8b"><div class="ttname"><a href="group__group__alloc.html#ga86dd08aba8633bfa4ad0df2e76481d8b">vmaGetAllocationInfo</a></div><div class="ttdeci">void vmaGetAllocationInfo(VmaAllocator allocator, VmaAllocation allocation, VmaAllocationInfo *pAllocationInfo)</div><div class="ttdoc">Returns current information about specified allocation.</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:1338</div></div>
<div class="ttc" id="astruct_vma_allocation_info_html_adc507656149c04de7ed95d0042ba2a13"><div class="ttname"><a href="struct_vma_allocation_info.html#adc507656149c04de7ed95d0042ba2a13">VmaAllocationInfo::pUserData</a></div><div class="ttdeci">void * pUserData</div><div class="ttdoc">Custom general-purpose pointer that was passed as VmaAllocationCreateInfo::pUserData or set using vma...</div><div class="ttdef"><b>Definition:</b> vk_mem_alloc.h:1385</div></div>
</div><!-- fragment --><p >It can also be changed using function <a class="el" href="group__group__alloc.html#gaf9147d31ffc11d62fc187bde283ed14f" title="Sets pUserData in given allocation to new value.">vmaSetAllocationUserData()</a>.</p>
<p >Values of (non-zero) allocations' <code>pUserData</code> are printed in JSON report created by <a class="el" href="group__group__stats.html#gaa4fee7eb5253377599ef4fd38c93c2a0" title="Builds and returns statistics as a null-terminated string in JSON format.">vmaBuildStatsString()</a> in hexadecimal form.</p>
<h1><a class="anchor" id="allocation_names"></a>
Allocation names</h1>
<p >There is alternative mode available where <code>pUserData</code> pointer is used to point to a null-terminated string, giving a name to the allocation. To use this mode, set <a class="el" href="group__group__alloc.html#ggad9889c10c798b040d59c92f257cae597aa6f24f821cd6a7c5e4a443f7bf59c520">VMA_ALLOCATION_CREATE_USER_DATA_COPY_STRING_BIT</a> flag in <a class="el" href="struct_vma_allocation_create_info.html#add09658ac14fe290ace25470ddd6d41b" title="Use VmaAllocationCreateFlagBits enum.">VmaAllocationCreateInfo::flags</a>. Then <code>pUserData</code> passed as <a class="el" href="struct_vma_allocation_create_info.html#a8259e85c272683434f4abb4ddddffe19" title="Custom general-purpose pointer that will be stored in VmaAllocation, can be read as VmaAllocationInfo...">VmaAllocationCreateInfo::pUserData</a> or argument to <a class="el" href="group__group__alloc.html#gaf9147d31ffc11d62fc187bde283ed14f" title="Sets pUserData in given allocation to new value.">vmaSetAllocationUserData()</a> must be either null or a pointer to a null-terminated string. The library creates internal copy of the string, so the pointer you pass doesn't need to be valid for whole lifetime of the allocation. You can free it after the call.</p>
<div class="fragment"><div class="line">VkImageCreateInfo imageInfo = ...</div>
<div class="line"> </div>
<div class="line">std::string imageName = <span class="stringliteral">&quot;Texture: &quot;</span>;</div>
<div class="line">imageName += fileName;</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#ggad9889c10c798b040d59c92f257cae597aa6f24f821cd6a7c5e4a443f7bf59c520">VMA_ALLOCATION_CREATE_USER_DATA_COPY_STRING_BIT</a>;</div>
<div class="line">allocCreateInfo.<a class="code hl_variable" href="struct_vma_allocation_create_info.html#a8259e85c272683434f4abb4ddddffe19">pUserData</a> = imageName.c_str();</div>
<div class="line"> </div>
<div class="line">VkImage image;</div>
<div class="line"><a class="code hl_struct" href="struct_vma_allocation.html">VmaAllocation</a> allocation;</div>
<div class="line"><a class="code hl_function" href="group__group__alloc.html#ga02a94f25679275851a53e82eacbcfc73">vmaCreateImage</a>(allocator, &amp;imageInfo, &amp;allocCreateInfo, &amp;image, &amp;allocation, <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_ggad9889c10c798b040d59c92f257cae597aa6f24f821cd6a7c5e4a443f7bf59c520"><div class="ttname"><a href="group__group__alloc.html#ggad9889c10c798b040d59c92f257cae597aa6f24f821cd6a7c5e4a443f7bf59c520">VMA_ALLOCATION_CREATE_USER_DATA_COPY_STRING_BIT</a></div><div class="ttdeci">@ VMA_ALLOCATION_CREATE_USER_DATA_COPY_STRING_BIT</div><div class="ttdef"><b>Definition:</b> vk_mem_alloc.h:562</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:1225</div></div>
</div><!-- fragment --><p >The value of <code>pUserData</code> pointer of the allocation will be different than the one you passed when setting allocation's name - pointing to a buffer managed internally that holds copy of the string.</p>
<div class="fragment"><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#ga86dd08aba8633bfa4ad0df2e76481d8b">vmaGetAllocationInfo</a>(allocator, allocation, &amp;allocInfo);</div>
<div class="line"><span class="keyword">const</span> <span class="keywordtype">char</span>* imageName = (<span class="keyword">const</span> <span class="keywordtype">char</span>*)allocInfo.<a class="code hl_variable" href="struct_vma_allocation_info.html#adc507656149c04de7ed95d0042ba2a13">pUserData</a>;</div>
<div class="line">printf(<span class="stringliteral">&quot;Image name: %s\n&quot;</span>, imageName);</div>
</div><!-- fragment --><p >That string is also printed in JSON report created by <a class="el" href="group__group__stats.html#gaa4fee7eb5253377599ef4fd38c93c2a0" title="Builds and returns statistics as a null-terminated string in JSON format.">vmaBuildStatsString()</a>.</p>
<dl class="section note"><dt>Note</dt><dd>Passing string name to VMA allocation doesn't automatically set it to the Vulkan buffer or image created with it. You must do it manually using an extension like VK_EXT_debug_utils, which is independent of this library. </dd></dl>
</div></div><!-- contents -->
</div><!-- PageDoc -->
<!-- start footer part -->
<hr class="footer"/><address class="footer"><small>
Generated by&#160;<a href="https://www.doxygen.org/index.html"><img class="footer" src="doxygen.svg" width="104" height="31" alt="doxygen"/></a> 1.9.2
</small></address>
</body>
</html>
Reference in New Issue View Git Blame Copy Permalink