Added documentation for VK_KHR_dedicated_allocation extension.

This commit is contained in:
Adam Sawicki 2017-10-17 11:57:56 +02:00
parent d08dc0cd6a
commit c005a84e37
6 changed files with 279 additions and 111 deletions

View File

@ -0,0 +1,98 @@
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://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=9"/>
<meta name="generator" content="Doxygen 1.8.13"/>
<meta name="viewport" content="width=device-width, initial-scale=1"/>
<title>Vulkan Memory Allocator: VK_KHR_dedicated_allocation</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.8.13 -->
<script type="text/javascript">
var searchBox = new SearchBox("searchBox", "search",false,'Search');
</script>
<script type="text/javascript" src="menudata.js"></script>
<script type="text/javascript" src="menu.js"></script>
<script type="text/javascript">
$(function() {
initMenu('',true,false,'search.php','Search');
$(document).ready(function() { init_search(); });
});
</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 class="header">
<div class="headertitle">
<div class="title">VK_KHR_dedicated_allocation </div> </div>
</div><!--header-->
<div class="contents">
<div class="textblock"><p>VK_KHR_dedicated_allocation is a Vulkan extension which can be used to improve performance on some GPUs. It augments Vulkan API with possibility to query driver whether it prefers particular buffer or image to have its own, dedicated allocation (separate <code>VkDeviceMemory</code> block) for better efficiency - to be able to do some internal optimizations.</p>
<p>The extension is supported by this library. It will be used automatically when enabled. To enable it:</p>
<p>1 . When creating Vulkan device, check if following 2 device extensions are supported (call <code>vkEnumerateDeviceExtensionProperties()</code>). If yes, enable them (fill <code>VkDeviceCreateInfo::ppEnabledExtensionNames</code>).</p>
<ul>
<li>VK_KHR_get_memory_requirements2</li>
<li>VK_KHR_dedicated_allocation</li>
</ul>
<p>If you enabled these extensions:</p>
<p>2 . Query device for pointers to following 2 extension functions, using <code>vkGetDeviceProcAddr()</code>. Pass them in structure <a class="el" href="struct_vma_vulkan_functions.html" title="Pointers to some Vulkan functions - a subset used by the library. ">VmaVulkanFunctions</a> while creating your <code>VmaAllocator</code>.</p>
<ul>
<li><code>vkGetBufferMemoryRequirements2KHR</code></li>
<li><code>vkGetImageMemoryRequirements2KHR</code></li>
</ul>
<p>Other members of this structure can be null as long as you leave <code>VMA_STATIC_VULKAN_FUNCTIONS</code> defined to 1, which is the default.</p>
<div class="fragment"><div class="line"><a class="code" href="struct_vma_vulkan_functions.html">VmaVulkanFunctions</a> vulkanFunctions = {};</div><div class="line">vulkanFunctions.<a class="code" href="struct_vma_vulkan_functions.html#a9d8d1b05d2b1e7e1d9b27f6f585acf9c">vkGetBufferMemoryRequirements2KHR</a> =</div><div class="line"> (PFN_vkGetBufferMemoryRequirements2KHR)vkGetDeviceProcAddr(device, <span class="stringliteral">&quot;vkGetBufferMemoryRequirements2KHR&quot;</span>);</div><div class="line">vulkanFunctions.<a class="code" href="struct_vma_vulkan_functions.html#a9cdcdc1e2b2ea7c571f7d27e30ba6875">vkGetImageMemoryRequirements2KHR</a> =</div><div class="line"> (PFN_vkGetImageMemoryRequirements2KHR)vkGetDeviceProcAddr(device, <span class="stringliteral">&quot;vkGetImageMemoryRequirements2KHR&quot;</span>);</div><div class="line"> </div><div class="line"><a class="code" href="struct_vma_allocator_create_info.html">VmaAllocatorCreateInfo</a> allocatorInfo = {};</div><div class="line">allocatorInfo.<a class="code" href="struct_vma_allocator_create_info.html#a3dc197be3227da7338b1643f70db36bd">pVulkanFunctions</a> = &amp;vulkanFunctions;</div><div class="line"><span class="comment">// Fill other members of allocatorInfo...</span></div></div><!-- fragment --><p>3 . Use <code>VMA_ALLOCATOR_CREATE_KHR_DEDICATED_ALLOCATION_BIT</code> flag when creating your <code>VmaAllocator</code> to inform the library that you enabled required extensions and you want the library to use them.</p>
<div class="fragment"><div class="line">allocatorInfo.<a class="code" href="struct_vma_allocator_create_info.html#a392ea2ecbaff93f91a7c49f735ad4346">flags</a> |= <a class="code" href="vk__mem__alloc_8h.html#a4f87c9100d154a65a4ad495f7763cf7cace7da7cc6e71a625dfa763c55a597878">VMA_ALLOCATOR_CREATE_KHR_DEDICATED_ALLOCATION_BIT</a>;</div><div class="line"></div><div class="line"><a class="code" href="vk__mem__alloc_8h.html#a200692051ddb34240248234f5f4c17bb">vmaCreateAllocator</a>(&amp;allocatorInfo, &amp;allocator);</div></div><!-- fragment --><p>That's all. The extension will be automatically used whenever you create a buffer using <a class="el" href="vk__mem__alloc_8h.html#ac72ee55598617e8eecca384e746bab51">vmaCreateBuffer()</a> or image using <a class="el" href="vk__mem__alloc_8h.html#a02a94f25679275851a53e82eacbcfc73" title="Function similar to vmaCreateBuffer(). ">vmaCreateImage()</a>.</p>
<p>To learn more about this extension, see:</p>
<ul>
<li><a href="https://www.khronos.org/registry/vulkan/specs/1.0-extensions/html/vkspec.html#VK_KHR_dedicated_allocation">VK_KHR_dedicated_allocation in Vulkan specification</a></li>
<li><a href="http://asawicki.info/articles/VK_KHR_dedicated_allocation.php5">VK_KHR_dedicated_allocation unofficial manual</a> </li>
</ul>
</div></div><!-- contents -->
<!-- start footer part -->
<hr class="footer"/><address class="footer"><small>
Generated by &#160;<a href="http://www.doxygen.org/index.html">
<img class="footer" src="doxygen.png" alt="doxygen"/>
</a> 1.8.13
</small></address>
</body>
</html>

View File

@ -76,7 +76,10 @@ License: MIT</p>
<li><a class="el" href="lost_allocations.html">Lost allocations</a></li>
</ul>
</li>
<li><a class="el" href="configuration.html">Configuration</a></li>
<li><a class="el" href="configuration.html">Configuration</a><ul>
<li><a class="el" href="_v_k__k_h_r_dedicated_allocation.html">VK_KHR_dedicated_allocation</a></li>
</ul>
</li>
<li><a class="el" href="thread_safety.html">Thread safety</a></li>
</ul>
<p>See also:</p>

View File

@ -1,6 +1,7 @@
var searchData=
[
['vulkan_20memory_20allocator',['Vulkan Memory Allocator',['../index.html',1,'']]],
['vk_5fkhr_5fdedicated_5fallocation',['VK_KHR_dedicated_allocation',['../_v_k__k_h_r_dedicated_allocation.html',1,'index']]],
['vk_5fmem_5falloc_2eh',['vk_mem_alloc.h',['../vk__mem__alloc_8h.html',1,'']]],
['vkallocatememory',['vkAllocateMemory',['../struct_vma_vulkan_functions.html#a2943bf99dfd784a0e8f599d987e22e6c',1,'VmaVulkanFunctions']]],
['vkbindbuffermemory',['vkBindBufferMemory',['../struct_vma_vulkan_functions.html#a94fc4f3a605d9880bb3c0ba2c2fc80b2',1,'VmaVulkanFunctions']]],

View File

@ -1,4 +1,5 @@
var searchData=
[
['vulkan_20memory_20allocator',['Vulkan Memory Allocator',['../index.html',1,'']]]
['vulkan_20memory_20allocator',['Vulkan Memory Allocator',['../index.html',1,'']]],
['vk_5fkhr_5fdedicated_5fallocation',['VK_KHR_dedicated_allocation',['../_v_k__k_h_r_dedicated_allocation.html',1,'index']]]
];

File diff suppressed because one or more lines are too long

View File

@ -45,6 +45,7 @@ Table of contents:
- \subpage defragmentation
- \subpage lost_allocations
- \subpage configuration
- \subpage VK_KHR_dedicated_allocation
- \subpage thread_safety
See also:
@ -390,6 +391,70 @@ To do it, fill optional member VmaAllocatorCreateInfo::pHeapSizeLimit.
\page VK_KHR_dedicated_allocation VK_KHR_dedicated_allocation
VK_KHR_dedicated_allocation is a Vulkan extension which can be used to improve
performance on some GPUs. It augments Vulkan API with possibility to query
driver whether it prefers particular buffer or image to have its own, dedicated
allocation (separate `VkDeviceMemory` block) for better efficiency - to be able
to do some internal optimizations.
The extension is supported by this library. It will be used automatically when
enabled. To enable it:
1 . When creating Vulkan device, check if following 2 device extensions are
supported (call `vkEnumerateDeviceExtensionProperties()`).
If yes, enable them (fill `VkDeviceCreateInfo::ppEnabledExtensionNames`).
- VK_KHR_get_memory_requirements2
- VK_KHR_dedicated_allocation
If you enabled these extensions:
2 . Query device for pointers to following 2 extension functions, using
`vkGetDeviceProcAddr()`. Pass them in structure VmaVulkanFunctions while creating
your `VmaAllocator`.
- `vkGetBufferMemoryRequirements2KHR`
- `vkGetImageMemoryRequirements2KHR`
Other members of this structure can be null as long as you leave
`VMA_STATIC_VULKAN_FUNCTIONS` defined to 1, which is the default.
\code
VmaVulkanFunctions vulkanFunctions = {};
vulkanFunctions.vkGetBufferMemoryRequirements2KHR =
(PFN_vkGetBufferMemoryRequirements2KHR)vkGetDeviceProcAddr(device, "vkGetBufferMemoryRequirements2KHR");
vulkanFunctions.vkGetImageMemoryRequirements2KHR =
(PFN_vkGetImageMemoryRequirements2KHR)vkGetDeviceProcAddr(device, "vkGetImageMemoryRequirements2KHR");
VmaAllocatorCreateInfo allocatorInfo = {};
allocatorInfo.pVulkanFunctions = &vulkanFunctions;
// Fill other members of allocatorInfo...
\endcode
3 . Use `VMA_ALLOCATOR_CREATE_KHR_DEDICATED_ALLOCATION_BIT` flag when creating
your `VmaAllocator` to inform the library that you enabled required extensions
and you want the library to use them.
\code
allocatorInfo.flags |= VMA_ALLOCATOR_CREATE_KHR_DEDICATED_ALLOCATION_BIT;
vmaCreateAllocator(&allocatorInfo, &allocator);
\endcode
That's all. The extension will be automatically used whenever you create a
buffer using vmaCreateBuffer() or image using vmaCreateImage().
To learn more about this extension, see:
- [VK_KHR_dedicated_allocation in Vulkan specification](https://www.khronos.org/registry/vulkan/specs/1.0-extensions/html/vkspec.html#VK_KHR_dedicated_allocation)
- [VK_KHR_dedicated_allocation unofficial manual](http://asawicki.info/articles/VK_KHR_dedicated_allocation.php5)
\page thread_safety Thread safety
- The library has no global state, so separate `VmaAllocator` objects can be used