You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: README.md
+10-10Lines changed: 10 additions & 10 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -39,9 +39,9 @@ This library can help game developers to manage memory allocations and resource
39
39
Additional features:
40
40
41
41
- Well-documented - description of all functions and structures provided, along with chapters that contain general description and example code.
42
-
- Thread-safety: Library is designed to be used in multithreaded code. Access to a single device memory block referred by different buffers and textures (binding, mapping) is synchronized internally.
43
-
- Configuration: Fill optional members of CreateInfo structure to provide custom CPU memory allocator, pointers to Vulkan functions and other parameters.
44
-
- Customization: Predefine appropriate macros to provide your own implementation of all external facilities used by the library, from assert, mutex, and atomic, to vector and linked list.
42
+
- Thread-safety: Library is designed to be used in multithreaded code. Access to a single device memory block referred by different buffers and textures (binding, mapping) is synchronized internally. Memory mapping is reference-counted.
43
+
- Configuration: Fill optional members of `VmaAllocatorCreateInfo` structure to provide custom CPU memory allocator, pointers to Vulkan functions and other parameters.
44
+
- Customization: Predefine appropriate macros to provide your own implementation of all external facilities used by the library like assert, mutex, atomic.
45
45
- Support for memory mapping, reference-counted internally. Support for persistently mapped memory: Just allocate with appropriate flag and you get access to mapped pointer.
46
46
- Support for non-coherent memory. Functions that flush/invalidate memory. `nonCoherentAtomSize` is respected automatically.
47
47
- Support for resource aliasing (overlap).
@@ -50,10 +50,11 @@ Additional features:
50
50
- Linear allocator: Create a pool with linear algorithm and use it for much faster allocations and deallocations in free-at-once, stack, double stack, or ring buffer fashion.
51
51
- Support for Vulkan 1.0, 1.1, 1.2, 1.3.
52
52
- Support for extensions (and equivalent functionality included in new Vulkan versions):
53
-
- VK_EXT_memory_budget: Used internally if available to query for current usage and budget. If not available, it falls back to an estimation based on memory heap sizes.
54
53
- VK_KHR_dedicated_allocation: Just enable it and it will be used automatically by the library.
54
+
- VK_KHR_buffer_device_address: Flag `VK_MEMORY_ALLOCATE_DEVICE_ADDRESS_BIT_KHR` is automatically added to memory allocations where needed.
55
+
- VK_EXT_memory_budget: Used internally if available to query for current usage and budget. If not available, it falls back to an estimation based on memory heap sizes.
56
+
- VK_EXT_memory_priority: Set `priority` of allocations or custom pools and it will be set automatically using this extension.
55
57
- VK_AMD_device_coherent_memory
56
-
- VK_KHR_buffer_device_address
57
58
- Defragmentation of GPU and CPU memory: Let the library move data around to free some memory blocks and make your allocations better compacted.
58
59
- Statistics: Obtain detailed statistics about the amount of memory used, unused, number of allocated blocks, number of allocations etc. - globally, per memory heap, and per memory type.
59
60
- Debug annotations: Associate string with name or opaque pointer to your own data with every allocation.
@@ -65,7 +66,7 @@ Additional features:
65
66
66
67
# Prequisites
67
68
68
-
- Self-contained C++ library in single header file. No external dependencies other than standard C and C++ library and of course Vulkan. Some features of C++14 used. STL containers are not used.
69
+
- Self-contained C++ library in single header file. No external dependencies other than standard C and C++ library and of course Vulkan. Some features of C++14 used. STL containers or C++ exceptions are not used.
69
70
- Public interface in C, in same convention as Vulkan API. Implementation in C++.
70
71
- Error handling implemented by returning `VkResult` error codes - same way as in Vulkan.
71
72
- Interface documented using Doxygen-style comments.
@@ -94,7 +95,7 @@ With this one function call:
94
95
2. `VkDeviceMemory` block is allocated if needed.
95
96
3. An unused region of the memory block is bound to this buffer.
96
97
97
-
`VmaAllocation` is an object that represents memory assigned to this buffer. It can be queried for parameters like Vulkan memory handle and offset.
98
+
`VmaAllocation` is an object that represents memory assigned to this buffer. It can be queried for parameters like `VkDeviceMemory` handle and offset.
98
99
99
100
# How to build
100
101
@@ -115,9 +116,8 @@ The following targets are available
Please note that while VulkanMemoryAllocator library is supported on other platforms besides Windows, VmaSample and VmaReplay are not.
120
+
Please note that while VulkanMemoryAllocator library is supported on other platforms besides Windows, VmaSample is not.
121
121
122
122
These CMake options are available
123
123
@@ -134,7 +134,7 @@ These CMake options are available
134
134
135
135
# Binaries
136
136
137
-
The release comes with precompiled binary executables for "VulkanSample" application which contains test suite and "VmaReplay" tool. They are compiled using Visual Studio 2019, so they require appropriate libraries to work, including "MSVCP140.dll", "VCRUNTIME140.dll", "VCRUNTIME140_1.dll". If their launch fails with error message telling about those files missing, please download and install [Microsoft Visual C++ Redistributable for Visual Studio 2015, 2017 and 2019](https://support.microsoft.com/en-us/help/2977003/the-latest-supported-visual-c-downloads), "x64" version.
137
+
The release comes with precompiled binary executable for "VulkanSample" application which contains test suite. It is compiled using Visual Studio 2019, so it requires appropriate libraries to work, including "MSVCP140.dll", "VCRUNTIME140.dll", "VCRUNTIME140_1.dll". If the launch fails with error message telling about those files missing, please download and install [Microsoft Visual C++ Redistributable for Visual Studio 2015, 2017 and 2019](https://support.microsoft.com/en-us/help/2977003/the-latest-supported-visual-c-downloads), "x64" version.
<divclass="ttc" id="astruct_vma_allocation_create_info_html_a8259e85c272683434f4abb4ddddffe19"><divclass="ttname"><ahref="struct_vma_allocation_create_info.html#a8259e85c272683434f4abb4ddddffe19">VmaAllocationCreateInfo::pUserData</a></div><divclass="ttdeci">void * pUserData</div><divclass="ttdoc">Custom general-purpose pointer that will be stored in VmaAllocation, can be read as VmaAllocationInfo...</div><divclass="ttdef"><b>Definition:</b> vk_mem_alloc.h:1250</div></div>
90
-
<divclass="ttc" id="astruct_vma_allocation_create_info_html_accb8b06b1f677d858cb9af20705fa910"><divclass="ttname"><ahref="struct_vma_allocation_create_info.html#accb8b06b1f677d858cb9af20705fa910">VmaAllocationCreateInfo::usage</a></div><divclass="ttdeci">VmaMemoryUsage usage</div><divclass="ttdoc">Intended usage of memory.</div><divclass="ttdef"><b>Definition:</b> vk_mem_alloc.h:1219</div></div>
<divclass="ttc" id="astruct_vma_allocation_create_info_html_a8259e85c272683434f4abb4ddddffe19"><divclass="ttname"><ahref="struct_vma_allocation_create_info.html#a8259e85c272683434f4abb4ddddffe19">VmaAllocationCreateInfo::pUserData</a></div><divclass="ttdeci">void * pUserData</div><divclass="ttdoc">Custom general-purpose pointer that will be stored in VmaAllocation, can be read as VmaAllocationInfo...</div><divclass="ttdef"><b>Definition:</b> vk_mem_alloc.h:1251</div></div>
90
+
<divclass="ttc" id="astruct_vma_allocation_create_info_html_accb8b06b1f677d858cb9af20705fa910"><divclass="ttname"><ahref="struct_vma_allocation_create_info.html#accb8b06b1f677d858cb9af20705fa910">VmaAllocationCreateInfo::usage</a></div><divclass="ttdeci">VmaMemoryUsage usage</div><divclass="ttdoc">Intended usage of memory.</div><divclass="ttdef"><b>Definition:</b> vk_mem_alloc.h:1220</div></div>
91
91
<divclass="ttc" id="astruct_vma_allocation_html"><divclass="ttname"><ahref="struct_vma_allocation.html">VmaAllocation</a></div><divclass="ttdoc">Represents single memory allocation.</div></div>
92
92
</div><!-- fragment --><p>The pointer may be later retrieved as <aclass="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>
<divclass="ttc" id="agroup__group__alloc_html_ga86dd08aba8633bfa4ad0df2e76481d8b"><divclass="ttname"><ahref="group__group__alloc.html#ga86dd08aba8633bfa4ad0df2e76481d8b">vmaGetAllocationInfo</a></div><divclass="ttdeci">void vmaGetAllocationInfo(VmaAllocator allocator, VmaAllocation allocation, VmaAllocationInfo *pAllocationInfo)</div><divclass="ttdoc">Returns current information about specified allocation.</div></div>
97
-
<divclass="ttc" id="astruct_vma_allocation_info_html"><divclass="ttname"><ahref="struct_vma_allocation_info.html">VmaAllocationInfo</a></div><divclass="ttdoc">Parameters of VmaAllocation objects, that can be retrieved using function vmaGetAllocationInfo().</div><divclass="ttdef"><b>Definition:</b> vk_mem_alloc.h:1326</div></div>
98
-
<divclass="ttc" id="astruct_vma_allocation_info_html_adc507656149c04de7ed95d0042ba2a13"><divclass="ttname"><ahref="struct_vma_allocation_info.html#adc507656149c04de7ed95d0042ba2a13">VmaAllocationInfo::pUserData</a></div><divclass="ttdeci">void * pUserData</div><divclass="ttdoc">Custom general-purpose pointer that was passed as VmaAllocationCreateInfo::pUserData or set using vma...</div><divclass="ttdef"><b>Definition:</b> vk_mem_alloc.h:1373</div></div>
97
+
<divclass="ttc" id="astruct_vma_allocation_info_html"><divclass="ttname"><ahref="struct_vma_allocation_info.html">VmaAllocationInfo</a></div><divclass="ttdoc">Parameters of VmaAllocation objects, that can be retrieved using function vmaGetAllocationInfo().</div><divclass="ttdef"><b>Definition:</b> vk_mem_alloc.h:1327</div></div>
98
+
<divclass="ttc" id="astruct_vma_allocation_info_html_adc507656149c04de7ed95d0042ba2a13"><divclass="ttname"><ahref="struct_vma_allocation_info.html#adc507656149c04de7ed95d0042ba2a13">VmaAllocationInfo::pUserData</a></div><divclass="ttdeci">void * pUserData</div><divclass="ttdoc">Custom general-purpose pointer that was passed as VmaAllocationCreateInfo::pUserData or set using vma...</div><divclass="ttdef"><b>Definition:</b> vk_mem_alloc.h:1374</div></div>
99
99
</div><!-- fragment --><p>It can also be changed using function <aclass="el" href="group__group__alloc.html#gaf9147d31ffc11d62fc187bde283ed14f" title="Sets pUserData in given allocation to new value.">vmaSetAllocationUserData()</a>.</p>
100
100
<p>Values of (non-zero) allocations' <code>pUserData</code> are printed in JSON report created by <aclass="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>
</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>
0 commit comments