More documentation. Refactored table of contents.

This commit is contained in:
Adam Sawicki 2018-03-12 15:34:32 +01:00
parent ec421f8763
commit 727e8b269f
13 changed files with 405 additions and 138 deletions

View File

@ -0,0 +1,104 @@
<!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: General considerations</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">General considerations </div> </div>
</div><!--header-->
<div class="contents">
<div class="textblock"><h1><a class="anchor" id="general_considerations_thread_safety"></a>
Thread safety</h1>
<ul>
<li>The library has no global state, so separate <code>VmaAllocator</code> objects can be used independently. There should be no need to create multiple such objects though - one per <code>VkDevice</code> is enough.</li>
<li>By default, all calls to functions that take <code>VmaAllocator</code> as first parameter are safe to call from multiple threads simultaneously because they are synchronized internally when needed.</li>
<li>When the allocator is created with <a class="el" href="vk__mem__alloc_8h.html#a4f87c9100d154a65a4ad495f7763cf7ca4816ddaed324ba110172ca608a20f29d" title="Allocator and all objects created from it will not be synchronized internally, so you must guarantee ...">VMA_ALLOCATOR_CREATE_EXTERNALLY_SYNCHRONIZED_BIT</a> flag, calls to functions that take such <code>VmaAllocator</code> object must be synchronized externally.</li>
<li>Access to a <code>VmaAllocation</code> object must be externally synchronized. For example, you must not call <a class="el" href="vk__mem__alloc_8h.html#a86dd08aba8633bfa4ad0df2e76481d8b" title="Returns current information about specified allocation and atomically marks it as used in current fra...">vmaGetAllocationInfo()</a> and <a class="el" href="vk__mem__alloc_8h.html#ad5bd1243512d099706de88168992f069" title="Maps memory represented by given allocation and returns pointer to it. ">vmaMapMemory()</a> from different threads at the same time if you pass the same <code>VmaAllocation</code> object to these functions.</li>
</ul>
<h1><a class="anchor" id="general_considerations_allocation_algorithm"></a>
Allocation algorithm</h1>
<p>The library uses following algorithm for allocation, in order:</p>
<ol type="1">
<li>Try to find free range of memory in existing blocks.</li>
<li>If failed, try to create a new block of <code>VkDeviceMemory</code>, with preferred block size.</li>
<li>If failed, try to create such block with size/2, size/4, size/8.</li>
<li>If failed and <a class="el" href="vk__mem__alloc_8h.html#ad9889c10c798b040d59c92f257cae597a68686d0ce9beb0d4d1b9f2b8b1389a7e">VMA_ALLOCATION_CREATE_CAN_MAKE_OTHER_LOST_BIT</a> flag was specified, try to find space in existing blocks, possilby making some other allocations lost.</li>
<li>If failed, try to allocate separate <code>VkDeviceMemory</code> for this allocation, just like when you use <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>.</li>
<li>If failed, choose other memory type that meets the requirements specified in <a class="el" href="struct_vma_allocation_create_info.html">VmaAllocationCreateInfo</a> and go to point 1.</li>
<li>If failed, return <code>VK_ERROR_OUT_OF_DEVICE_MEMORY</code>.</li>
</ol>
<h1><a class="anchor" id="general_considerations_features_not_supported"></a>
Features not supported</h1>
<p>Features deliberately excluded from the scope of this library:</p>
<ul>
<li>Data transfer - issuing commands that transfer data between buffers or images, any usage of <code>VkCommandList</code> or <code>VkCommandQueue</code> and related synchronization is responsibility of the user.</li>
<li>Support for any programming languages other than C/C++. Bindings to other languages are welcomed as external projects. </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

@ -66,29 +66,63 @@ $(function() {
<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>
<p>Table of contents:</p>
<h1><a class="anchor" id="main_table_of_contents"></a>
Table of contents</h1>
<ul>
<li>User guide<ul>
<li><a class="el" href="quick_start.html">Quick start</a></li>
<li><a class="el" href="choosing_memory_type.html">Choosing memory type</a></li>
<li><a class="el" href="memory_mapping.html">Memory mapping</a></li>
<li><a class="el" href="custom_memory_pools.html">Custom memory pools</a></li>
<li><b>User guide</b><ul>
<li><a class="el" href="quick_start.html">Quick start</a><ul>
<li><a class="el" href="quick_start.html#quick_start_project_setup">Project setup</a></li>
<li><a class="el" href="quick_start.html#quick_start_initialization">Initialization</a></li>
<li><a class="el" href="quick_start.html#quick_start_resource_allocation">Resource allocation</a></li>
</ul>
</li>
<li><a class="el" href="choosing_memory_type.html">Choosing memory type</a><ul>
<li><a class="el" href="choosing_memory_type.html#choosing_memory_type_usage">Usage</a></li>
<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>
</ul>
</li>
<li><a class="el" href="memory_mapping.html">Memory mapping</a><ul>
<li><a class="el" href="memory_mapping.html#memory_mapping_mapping_functions">Mapping functions</a></li>
<li><a class="el" href="memory_mapping.html#memory_mapping_persistently_mapped_memory">Persistently mapped memory</a></li>
<li><a class="el" href="memory_mapping.html#memory_mapping_cache_control">Cache control</a></li>
<li><a class="el" href="memory_mapping.html#memory_mapping_finding_if_memory_mappable">Finding out if memory is mappable</a></li>
</ul>
</li>
<li><a class="el" href="custom_memory_pools.html">Custom memory pools</a><ul>
<li><a class="el" href="custom_memory_pools.html#custom_memory_pools_MemTypeIndex">Choosing memory type index</a></li>
</ul>
</li>
<li><a class="el" href="defragmentation.html">Defragmentation</a></li>
<li><a class="el" href="lost_allocations.html">Lost allocations</a></li>
<li><a class="el" href="allocation_annotation.html">Allocation names and user data</a></li>
<li><a class="el" href="allocation_annotation.html">Allocation names and user data</a><ul>
<li><a class="el" href="allocation_annotation.html#allocation_user_data">Allocation user data</a></li>
<li><a class="el" href="allocation_annotation.html#allocation_names">Allocation names</a></li>
</ul>
</li>
</ul>
</li>
<li><a class="el" href="configuration.html">Configuration</a><ul>
<li><a class="el" href="configuration.html#config_Vulkan_functions">Pointers to Vulkan functions</a></li>
<li><a class="el" href="configuration.html#custom_memory_allocator">Custom host memory allocator</a></li>
<li><a class="el" href="configuration.html#allocation_callbacks">Device memory allocation callbacks</a></li>
<li><a class="el" href="configuration.html#heap_memory_limit">Device heap memory limit</a></li>
<li><a class="el" href="vk_khr_dedicated_allocation.html">VK_KHR_dedicated_allocation</a></li>
</ul>
</li>
<li><a class="el" href="thread_safety.html">Thread safety</a></li>
<li><a class="el" href="general_considerations.html">General considerations</a></li>
<li><a class="el" href="general_considerations.html">General considerations</a><ul>
<li><a class="el" href="general_considerations.html#general_considerations_thread_safety">Thread safety</a></li>
<li><a class="el" href="general_considerations.html#general_considerations_allocation_algorithm">Allocation algorithm</a></li>
<li><a class="el" href="general_considerations.html#general_considerations_features_not_supported">Features not supported</a></li>
</ul>
<p>See also:</p>
</li>
</ul>
<h1><a class="anchor" id="main_see_also"></a>
See also</h1>
<ul>
<li><a href="https://github.com/GPUOpen-LibrariesAndSDKs/VulkanMemoryAllocator">Source repository on GitHub</a></li>
<li><a href="https://gpuopen.com/gaming-product/vulkan-memory-allocator/">Product page on GPUOpen</a> </li>
<li><a href="https://gpuopen.com/gaming-product/vulkan-memory-allocator/">Product page on GPUOpen</a></li>
<li><a href="https://github.com/GPUOpen-LibrariesAndSDKs/VulkanMemoryAllocator">Source repository on GitHub</a> </li>
</ul>
</div></div><!-- contents -->
<!-- start footer part -->

View File

@ -64,6 +64,7 @@ $(function() {
<div class="contents">
<div class="textblock">Here is a list of all related documentation pages:</div><div class="directory">
<table class="directory">
<tr id="row_0_" class="even"><td class="entry"><span style="width:16px;display:inline-block;">&#160;</span><a class="el" href="statistics.html" target="_self">Statistics</a></td><td class="desc"></td></tr>
</table>
</div><!-- directory -->
</div><!-- contents -->

View File

@ -76,14 +76,14 @@ Project setup</h1>
<li>In exacly one CPP file define following macro before this include. It enables also internal definitions.</li>
</ol>
<div class="fragment"><div class="line"><span class="preprocessor">#define VMA_IMPLEMENTATION</span></div><div class="line"><span class="preprocessor">#include &quot;vk_mem_alloc.h&quot;</span></div></div><!-- fragment --><p>It may be a good idea to create dedicated CPP file just for this purpose.</p>
<h1><a class="anchor" id="initialization"></a>
<h1><a class="anchor" id="quick_start_initialization"></a>
Initialization</h1>
<p>At program startup:</p>
<ol type="1">
<li>Initialize Vulkan to have <code>VkPhysicalDevice</code> and <code>VkDevice</code> object.</li>
<li>Fill <a class="el" href="struct_vma_allocator_create_info.html" title="Description of a Allocator to be created. ">VmaAllocatorCreateInfo</a> structure and create <code>VmaAllocator</code> object by calling <a class="el" href="vk__mem__alloc_8h.html#a200692051ddb34240248234f5f4c17bb" title="Creates Allocator object. ">vmaCreateAllocator()</a>.</li>
</ol>
<div class="fragment"><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#a08230f04ae6ccf8a78150a9e829a7156">physicalDevice</a> = physicalDevice;</div><div class="line">allocatorInfo.<a class="code" href="struct_vma_allocator_create_info.html#ad924ddd77b04039c88d0c09b0ffcd500">device</a> = device;</div><div class="line"></div><div class="line">VmaAllocator allocator;</div><div class="line"><a class="code" href="vk__mem__alloc_8h.html#a200692051ddb34240248234f5f4c17bb">vmaCreateAllocator</a>(&amp;allocatorInfo, &amp;allocator);</div></div><!-- fragment --><h1><a class="anchor" id="resource_allocation"></a>
<div class="fragment"><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#a08230f04ae6ccf8a78150a9e829a7156">physicalDevice</a> = physicalDevice;</div><div class="line">allocatorInfo.<a class="code" href="struct_vma_allocator_create_info.html#ad924ddd77b04039c88d0c09b0ffcd500">device</a> = device;</div><div class="line"></div><div class="line">VmaAllocator allocator;</div><div class="line"><a class="code" href="vk__mem__alloc_8h.html#a200692051ddb34240248234f5f4c17bb">vmaCreateAllocator</a>(&amp;allocatorInfo, &amp;allocator);</div></div><!-- fragment --><h1><a class="anchor" id="quick_start_resource_allocation"></a>
Resource allocation</h1>
<p>When you want to create a buffer or image:</p>
<ol type="1">

View File

@ -1,4 +1,5 @@
var searchData=
[
['size',['size',['../struct_vma_pool_stats.html#a326807b2de2b0931cee4ed9a5f2e420c',1,'VmaPoolStats::size()'],['../struct_vma_allocation_info.html#aac76d113a6a5ccbb09fea00fb25fd18f',1,'VmaAllocationInfo::size()']]]
['size',['size',['../struct_vma_pool_stats.html#a326807b2de2b0931cee4ed9a5f2e420c',1,'VmaPoolStats::size()'],['../struct_vma_allocation_info.html#aac76d113a6a5ccbb09fea00fb25fd18f',1,'VmaAllocationInfo::size()']]],
['statistics',['Statistics',['../statistics.html',1,'']]]
];

View File

@ -1,5 +1,4 @@
var searchData=
[
['thread_20safety',['Thread safety',['../thread_safety.html',1,'index']]],
['total',['total',['../struct_vma_stats.html#a2e8f5b3353f2fefef3c27f29e245a1f9',1,'VmaStats']]]
];

View File

@ -1,4 +1,4 @@
var searchData=
[
['thread_20safety',['Thread safety',['../thread_safety.html',1,'index']]]
['statistics',['Statistics',['../statistics.html',1,'']]]
];

View File

@ -0,0 +1,26 @@
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html><head><title></title>
<meta http-equiv="Content-Type" content="text/xhtml;charset=UTF-8"/>
<meta name="generator" content="Doxygen 1.8.13"/>
<link rel="stylesheet" type="text/css" href="search.css"/>
<script type="text/javascript" src="pages_9.js"></script>
<script type="text/javascript" src="search.js"></script>
</head>
<body class="SRPage">
<div id="SRIndex">
<div class="SRStatus" id="Loading">Loading...</div>
<div id="SRResults"></div>
<script type="text/javascript"><!--
createResults();
--></script>
<div class="SRStatus" id="Searching">Searching...</div>
<div class="SRStatus" id="NoMatches">No Matches</div>
<script type="text/javascript"><!--
document.getElementById("Loading").style.display="none";
document.getElementById("NoMatches").style.display="none";
var searchResults = new SearchResults("searchResults");
searchResults.Search();
--></script>
</div>
</body>
</html>

View File

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

View File

@ -9,7 +9,7 @@ var indexSectionsWithContent =
6: "v",
7: "v",
8: "v",
9: "acdglmqtv"
9: "acdglmqsv"
};
var indexSectionNames =

73
docs/html/statistics.html Normal file
View File

@ -0,0 +1,73 @@
<!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: Statistics</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><!-- top -->
<div class="header">
<div class="headertitle">
<div class="title">Statistics </div> </div>
</div><!--header-->
<div class="contents">
<div class="textblock"></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>

File diff suppressed because one or more lines are too long

View File

@ -36,25 +36,45 @@ License: MIT
Documentation of all members: vk_mem_alloc.h
Table of contents:
\section main_table_of_contents Table of contents
- User guide
- <b>User guide</b>
- \subpage quick_start
- [Project setup](@ref quick_start_project_setup)
- [Initialization](@ref quick_start_initialization)
- [Resource allocation](@ref quick_start_resource_allocation)
- \subpage choosing_memory_type
- [Usage](@ref choosing_memory_type_usage)
- [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)
- \subpage memory_mapping
- [Mapping functions](@ref memory_mapping_mapping_functions)
- [Persistently mapped memory](@ref memory_mapping_persistently_mapped_memory)
- [Cache control](@ref memory_mapping_cache_control)
- [Finding out if memory is mappable](@ref memory_mapping_finding_if_memory_mappable)
- \subpage custom_memory_pools
- [Choosing memory type index](@ref custom_memory_pools_MemTypeIndex)
- \subpage defragmentation
- \subpage lost_allocations
- \subpage allocation_annotation
- [Allocation user data](@ref allocation_user_data)
- [Allocation names](@ref allocation_names)
- \subpage configuration
- [Pointers to Vulkan functions](@ref config_Vulkan_functions)
- [Custom host memory allocator](@ref custom_memory_allocator)
- [Device memory allocation callbacks](@ref allocation_callbacks)
- [Device heap memory limit](@ref heap_memory_limit)
- \subpage vk_khr_dedicated_allocation
- \subpage thread_safety
- \subpage general_considerations
- [Thread safety](@ref general_considerations_thread_safety)
- [Allocation algorithm](@ref general_considerations_allocation_algorithm)
- [Features not supported](@ref general_considerations_features_not_supported)
See also:
\section main_see_also See also
- [Source repository on GitHub](https://github.com/GPUOpen-LibrariesAndSDKs/VulkanMemoryAllocator)
- [Product page on GPUOpen](https://gpuopen.com/gaming-product/vulkan-memory-allocator/)
- [Source repository on GitHub](https://github.com/GPUOpen-LibrariesAndSDKs/VulkanMemoryAllocator)
@ -86,7 +106,7 @@ To do it properly:
It may be a good idea to create dedicated CPP file just for this purpose.
\section initialization Initialization
\section quick_start_initialization Initialization
At program startup:
@ -103,7 +123,7 @@ VmaAllocator allocator;
vmaCreateAllocator(&allocatorInfo, &allocator);
\endcode
\section resource_allocation Resource allocation
\section quick_start_resource_allocation Resource allocation
When you want to create a buffer or image:
@ -651,6 +671,11 @@ images. This is still valid as long as you implement proper handling of lost
allocations (like in the example above) and don't use them.
\page statistics Statistics
\page allocation_annotation Allocation names and user data
\section allocation_user_data Allocation user data
@ -820,7 +845,9 @@ To learn more about this extension, see:
\page thread_safety Thread safety
\page general_considerations General considerations
\section general_considerations_thread_safety Thread safety
- The library has no global state, so separate `VmaAllocator` objects can be used
independently.
@ -836,9 +863,6 @@ To learn more about this extension, see:
threads at the same time if you pass the same `VmaAllocation` object to these
functions.
\page general_considerations General considerations
\section general_considerations_allocation_algorithm Allocation algorithm
The library uses following algorithm for allocation, in order: