Skip to content

Commit 727e8b2

Browse files
adam-sawicki-aadam-sawicki-a
committed
More documentation. Refactored table of contents.
1 parent ec421f8 commit 727e8b2

13 files changed

+405
-138
lines changed

‎docs/html/general_considerations.html

Lines changed: 104 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,104 @@
1+
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
2+
<html xmlns="http://www.w3.org/1999/xhtml">
3+
<head>
4+
<meta http-equiv="Content-Type" content="text/xhtml;charset=UTF-8"/>
5+
<meta http-equiv="X-UA-Compatible" content="IE=9"/>
6+
<meta name="generator" content="Doxygen 1.8.13"/>
7+
<meta name="viewport" content="width=device-width, initial-scale=1"/>
8+
<title>Vulkan Memory Allocator: General considerations</title>
9+
<link href="tabs.css" rel="stylesheet" type="text/css"/>
10+
<script type="text/javascript" src="jquery.js"></script>
11+
<script type="text/javascript" src="dynsections.js"></script>
12+
<link href="search/search.css" rel="stylesheet" type="text/css"/>
13+
<script type="text/javascript" src="search/searchdata.js"></script>
14+
<script type="text/javascript" src="search/search.js"></script>
15+
<link href="doxygen.css" rel="stylesheet" type="text/css" />
16+
</head>
17+
<body>
18+
<div id="top"><!-- do not remove this div, it is closed by doxygen! -->
19+
<div id="titlearea">
20+
<table cellspacing="0" cellpadding="0">
21+
<tbody>
22+
<tr style="height: 56px;">
23+
<td id="projectalign" style="padding-left: 0.5em;">
24+
<div id="projectname">Vulkan Memory Allocator
25+
</div>
26+
</td>
27+
</tr>
28+
</tbody>
29+
</table>
30+
</div>
31+
<!-- end header part -->
32+
<!-- Generated by Doxygen 1.8.13 -->
33+
<script type="text/javascript">
34+
var searchBox = new SearchBox("searchBox", "search",false,'Search');
35+
</script>
36+
<script type="text/javascript" src="menudata.js"></script>
37+
<script type="text/javascript" src="menu.js"></script>
38+
<script type="text/javascript">
39+
$(function() {
40+
initMenu('',true,false,'search.php','Search');
41+
$(document).ready(function() { init_search(); });
42+
});
43+
</script>
44+
<div id="main-nav"></div>
45+
<!-- window showing the filter options -->
46+
<div id="MSearchSelectWindow"
47+
onmouseover="return searchBox.OnSearchSelectShow()"
48+
onmouseout="return searchBox.OnSearchSelectHide()"
49+
onkeydown="return searchBox.OnSearchSelectKey(event)">
50+
</div>
51+
52+
<!-- iframe showing the search results (closed by default) -->
53+
<div id="MSearchResultsWindow">
54+
<iframe src="javascript:void(0)" frameborder="0"
55+
name="MSearchResults" id="MSearchResults">
56+
</iframe>
57+
</div>
58+
59+
<div id="nav-path" class="navpath">
60+
<ul>
61+
<li class="navelem"><a class="el" href="index.html">Vulkan Memory Allocator</a></li> </ul>
62+
</div>
63+
</div><!-- top -->
64+
<div class="header">
65+
<div class="headertitle">
66+
<div class="title">General considerations </div> </div>
67+
</div><!--header-->
68+
<div class="contents">
69+
<div class="textblock"><h1><a class="anchor" id="general_considerations_thread_safety"></a>
70+
Thread safety</h1>
71+
<ul>
72+
<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>
73+
<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>
74+
<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>
75+
<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>
76+
</ul>
77+
<h1><a class="anchor" id="general_considerations_allocation_algorithm"></a>
78+
Allocation algorithm</h1>
79+
<p>The library uses following algorithm for allocation, in order:</p>
80+
<ol type="1">
81+
<li>Try to find free range of memory in existing blocks.</li>
82+
<li>If failed, try to create a new block of <code>VkDeviceMemory</code>, with preferred block size.</li>
83+
<li>If failed, try to create such block with size/2, size/4, size/8.</li>
84+
<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>
85+
<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>
86+
<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>
87+
<li>If failed, return <code>VK_ERROR_OUT_OF_DEVICE_MEMORY</code>.</li>
88+
</ol>
89+
<h1><a class="anchor" id="general_considerations_features_not_supported"></a>
90+
Features not supported</h1>
91+
<p>Features deliberately excluded from the scope of this library:</p>
92+
<ul>
93+
<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>
94+
<li>Support for any programming languages other than C/C++. Bindings to other languages are welcomed as external projects. </li>
95+
</ul>
96+
</div></div><!-- contents -->
97+
<!-- start footer part -->
98+
<hr class="footer"/><address class="footer"><small>
99+
Generated by &#160;<a href="http://www.doxygen.org/index.html">
100+
<img class="footer" src="doxygen.png" alt="doxygen"/>
101+
</a> 1.8.13
102+
</small></address>
103+
</body>
104+
</html>

‎docs/html/index.html

Lines changed: 46 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -66,29 +66,63 @@
6666
<p>Copyright (c) 2017-2018 Advanced Micro Devices, Inc. All rights reserved. <br />
6767
License: MIT</p>
6868
<p>Documentation of all members: <a class="el" href="vk__mem__alloc_8h.html">vk_mem_alloc.h</a></p>
69-
<p>Table of contents:</p>
69+
<h1><a class="anchor" id="main_table_of_contents"></a>
70+
Table of contents</h1>
7071
<ul>
71-
<li>User guide<ul>
72-
<li><a class="el" href="quick_start.html">Quick start</a></li>
73-
<li><a class="el" href="choosing_memory_type.html">Choosing memory type</a></li>
74-
<li><a class="el" href="memory_mapping.html">Memory mapping</a></li>
75-
<li><a class="el" href="custom_memory_pools.html">Custom memory pools</a></li>
72+
<li><b>User guide</b><ul>
73+
<li><a class="el" href="quick_start.html">Quick start</a><ul>
74+
<li><a class="el" href="quick_start.html#quick_start_project_setup">Project setup</a></li>
75+
<li><a class="el" href="quick_start.html#quick_start_initialization">Initialization</a></li>
76+
<li><a class="el" href="quick_start.html#quick_start_resource_allocation">Resource allocation</a></li>
77+
</ul>
78+
</li>
79+
<li><a class="el" href="choosing_memory_type.html">Choosing memory type</a><ul>
80+
<li><a class="el" href="choosing_memory_type.html#choosing_memory_type_usage">Usage</a></li>
81+
<li><a class="el" href="choosing_memory_type.html#choosing_memory_type_required_preferred_flags">Required and preferred flags</a></li>
82+
<li><a class="el" href="choosing_memory_type.html#choosing_memory_type_explicit_memory_types">Explicit memory types</a></li>
83+
<li><a class="el" href="choosing_memory_type.html#choosing_memory_type_custom_memory_pools">Custom memory pools</a></li>
84+
</ul>
85+
</li>
86+
<li><a class="el" href="memory_mapping.html">Memory mapping</a><ul>
87+
<li><a class="el" href="memory_mapping.html#memory_mapping_mapping_functions">Mapping functions</a></li>
88+
<li><a class="el" href="memory_mapping.html#memory_mapping_persistently_mapped_memory">Persistently mapped memory</a></li>
89+
<li><a class="el" href="memory_mapping.html#memory_mapping_cache_control">Cache control</a></li>
90+
<li><a class="el" href="memory_mapping.html#memory_mapping_finding_if_memory_mappable">Finding out if memory is mappable</a></li>
91+
</ul>
92+
</li>
93+
<li><a class="el" href="custom_memory_pools.html">Custom memory pools</a><ul>
94+
<li><a class="el" href="custom_memory_pools.html#custom_memory_pools_MemTypeIndex">Choosing memory type index</a></li>
95+
</ul>
96+
</li>
7697
<li><a class="el" href="defragmentation.html">Defragmentation</a></li>
7798
<li><a class="el" href="lost_allocations.html">Lost allocations</a></li>
78-
<li><a class="el" href="allocation_annotation.html">Allocation names and user data</a></li>
99+
<li><a class="el" href="allocation_annotation.html">Allocation names and user data</a><ul>
100+
<li><a class="el" href="allocation_annotation.html#allocation_user_data">Allocation user data</a></li>
101+
<li><a class="el" href="allocation_annotation.html#allocation_names">Allocation names</a></li>
102+
</ul>
103+
</li>
79104
</ul>
80105
</li>
81106
<li><a class="el" href="configuration.html">Configuration</a><ul>
107+
<li><a class="el" href="configuration.html#config_Vulkan_functions">Pointers to Vulkan functions</a></li>
108+
<li><a class="el" href="configuration.html#custom_memory_allocator">Custom host memory allocator</a></li>
109+
<li><a class="el" href="configuration.html#allocation_callbacks">Device memory allocation callbacks</a></li>
110+
<li><a class="el" href="configuration.html#heap_memory_limit">Device heap memory limit</a></li>
82111
<li><a class="el" href="vk_khr_dedicated_allocation.html">VK_KHR_dedicated_allocation</a></li>
83112
</ul>
84113
</li>
85-
<li><a class="el" href="thread_safety.html">Thread safety</a></li>
86-
<li><a class="el" href="general_considerations.html">General considerations</a></li>
114+
<li><a class="el" href="general_considerations.html">General considerations</a><ul>
115+
<li><a class="el" href="general_considerations.html#general_considerations_thread_safety">Thread safety</a></li>
116+
<li><a class="el" href="general_considerations.html#general_considerations_allocation_algorithm">Allocation algorithm</a></li>
117+
<li><a class="el" href="general_considerations.html#general_considerations_features_not_supported">Features not supported</a></li>
118+
</ul>
119+
</li>
87120
</ul>
88-
<p>See also:</p>
121+
<h1><a class="anchor" id="main_see_also"></a>
122+
See also</h1>
89123
<ul>
90-
<li><a href="https://github.com/GPUOpen-LibrariesAndSDKs/VulkanMemoryAllocator">Source repository on GitHub</a></li>
91-
<li><a href="https://gpuopen.com/gaming-product/vulkan-memory-allocator/">Product page on GPUOpen</a> </li>
124+
<li><a href="https://gpuopen.com/gaming-product/vulkan-memory-allocator/">Product page on GPUOpen</a></li>
125+
<li><a href="https://github.com/GPUOpen-LibrariesAndSDKs/VulkanMemoryAllocator">Source repository on GitHub</a> </li>
92126
</ul>
93127
</div></div><!-- contents -->
94128
<!-- start footer part -->

‎docs/html/pages.html

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -64,6 +64,7 @@
6464
<div class="contents">
6565
<div class="textblock">Here is a list of all related documentation pages:</div><div class="directory">
6666
<table class="directory">
67+
<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>
6768
</table>
6869
</div><!-- directory -->
6970
</div><!-- contents -->

‎docs/html/quick_start.html

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -76,14 +76,14 @@
7676
<li>In exacly one CPP file define following macro before this include. It enables also internal definitions.</li>
7777
</ol>
7878
<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>
79-
<h1><a class="anchor" id="initialization"></a>
79+
<h1><a class="anchor" id="quick_start_initialization"></a>
8080
Initialization</h1>
8181
<p>At program startup:</p>
8282
<ol type="1">
8383
<li>Initialize Vulkan to have <code>VkPhysicalDevice</code> and <code>VkDevice</code> object.</li>
8484
<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>
8585
</ol>
86-
<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>
86+
<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>
8787
Resource allocation</h1>
8888
<p>When you want to create a buffer or image:</p>
8989
<ol type="1">

‎docs/html/search/all_c.js

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,5 @@
11
var searchData=
22
[
3-
['size',['size',['../struct_vma_pool_stats.html#a326807b2de2b0931cee4ed9a5f2e420c',1,'VmaPoolStats::size()'],['../struct_vma_allocation_info.html#aac76d113a6a5ccbb09fea00fb25fd18f',1,'VmaAllocationInfo::size()']]]
3+
['size',['size',['../struct_vma_pool_stats.html#a326807b2de2b0931cee4ed9a5f2e420c',1,'VmaPoolStats::size()'],['../struct_vma_allocation_info.html#aac76d113a6a5ccbb09fea00fb25fd18f',1,'VmaAllocationInfo::size()']]],
4+
['statistics',['Statistics',['../statistics.html',1,'']]]
45
];

‎docs/html/search/all_d.js

Lines changed: 0 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,4 @@
11
var searchData=
22
[
3-
['thread_20safety',['Thread safety',['../thread_safety.html',1,'index']]],
43
['total',['total',['../struct_vma_stats.html#a2e8f5b3353f2fefef3c27f29e245a1f9',1,'VmaStats']]]
54
];

‎docs/html/search/pages_7.js

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
11
var searchData=
22
[
3-
['thread_20safety',['Thread safety',['../thread_safety.html',1,'index']]]
3+
['statistics',['Statistics',['../statistics.html',1,'']]]
44
];

‎docs/html/search/pages_9.html

Lines changed: 26 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,26 @@
1+
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
2+
<html><head><title></title>
3+
<meta http-equiv="Content-Type" content="text/xhtml;charset=UTF-8"/>
4+
<meta name="generator" content="Doxygen 1.8.13"/>
5+
<link rel="stylesheet" type="text/css" href="search.css"/>
6+
<script type="text/javascript" src="pages_9.js"></script>
7+
<script type="text/javascript" src="search.js"></script>
8+
</head>
9+
<body class="SRPage">
10+
<div id="SRIndex">
11+
<div class="SRStatus" id="Loading">Loading...</div>
12+
<div id="SRResults"></div>
13+
<script type="text/javascript"><!--
14+
createResults();
15+
--></script>
16+
<div class="SRStatus" id="Searching">Searching...</div>
17+
<div class="SRStatus" id="NoMatches">No Matches</div>
18+
<script type="text/javascript"><!--
19+
document.getElementById("Loading").style.display="none";
20+
document.getElementById("NoMatches").style.display="none";
21+
var searchResults = new SearchResults("searchResults");
22+
searchResults.Search();
23+
--></script>
24+
</div>
25+
</body>
26+
</html>

‎docs/html/search/pages_9.js

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
var searchData=
2+
[
3+
['vulkan_20memory_20allocator',['Vulkan Memory Allocator',['../index.html',1,'']]],
4+
['vk_5fkhr_5fdedicated_5fallocation',['VK_KHR_dedicated_allocation',['../vk_khr_dedicated_allocation.html',1,'index']]]
5+
];

‎docs/html/search/searchdata.js

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -9,7 +9,7 @@ var indexSectionsWithContent =
99
6: "v",
1010
7: "v",
1111
8: "v",
12-
9: "acdglmqtv"
12+
9: "acdglmqsv"
1313
};
1414

1515
var indexSectionNames =

0 commit comments

Comments
 (0)