Commit: a819523dffebc9cc3865107c2c426a298d8154fd Author: Jeroen Bakker Date: Wed Nov 23 14:42:11 2022 +0100 Branches: master https://developer.blender.org/rBa819523dffebc9cc3865107c2c426a298d8154fd
Vulkan: Add VK memory allocator 3.0.1 to extern. Vulkan doesn't have a memory allocator builtin. The application should provide the memory allocator at runtime. Vulkan Memory Allocator is a widely used implementation. Vulkan Memory Allocator is a header only implementation, but the using application should compile a part in a CPP compile unit. The file `vk_mem_alloc_impl.cc` and `extern_vulkan_memory_allocator` library is therefore introduced. Reviewed By: fclem Differential Revision: https://developer.blender.org/D16572 =================================================================== M extern/CMakeLists.txt A extern/vulkan_memory_allocator/CMakeLists.txt A extern/vulkan_memory_allocator/LICENSE.txt A extern/vulkan_memory_allocator/README.blender A extern/vulkan_memory_allocator/README.md A extern/vulkan_memory_allocator/vk_mem_alloc.h A extern/vulkan_memory_allocator/vk_mem_alloc_impl.cc M source/blender/gpu/CMakeLists.txt M source/blender/gpu/vulkan/vk_backend.cc M source/blender/gpu/vulkan/vk_context.cc M source/blender/gpu/vulkan/vk_context.hh =================================================================== diff --git a/extern/CMakeLists.txt b/extern/CMakeLists.txt index 57a8f977517..9723fe92ff9 100644 --- a/extern/CMakeLists.txt +++ b/extern/CMakeLists.txt @@ -91,3 +91,7 @@ endif() if(WITH_COMPOSITOR_CPU) add_subdirectory(smaa_areatex) endif() + +if(WITH_VULKAN_BACKEND) + add_subdirectory(vulkan_memory_allocator) +endif() diff --git a/extern/vulkan_memory_allocator/CMakeLists.txt b/extern/vulkan_memory_allocator/CMakeLists.txt new file mode 100644 index 00000000000..0b709e8dda1 --- /dev/null +++ b/extern/vulkan_memory_allocator/CMakeLists.txt @@ -0,0 +1,24 @@ +# SPDX-License-Identifier: GPL-2.0-or-later +# Copyright 2022 Blender Foundation. All rights reserved. + +set(INC + . +) + +set(INC_SYS + ${VULKAN_INCLUDE_DIRS} +) + +set(SRC + vk_mem_alloc_impl.cc + + vk_mem_alloc.h +) + +blender_add_lib(extern_vulkan_memory_allocator "${SRC}" "${INC}" "${INC_SYS}" "${LIB}") + +if(CMAKE_COMPILER_IS_GNUCC OR CMAKE_C_COMPILER_ID MATCHES "Clang") + target_compile_options(extern_vulkan_memory_allocator + PRIVATE "-Wno-nullability-completeness" + ) +endif() diff --git a/extern/vulkan_memory_allocator/LICENSE.txt b/extern/vulkan_memory_allocator/LICENSE.txt new file mode 100644 index 00000000000..b74bf4a854d --- /dev/null +++ b/extern/vulkan_memory_allocator/LICENSE.txt @@ -0,0 +1,19 @@ +Copyright (c) 2017-2022 Advanced Micro Devices, Inc. All rights reserved. + +Permission is hereby granted, free of charge, to any person obtaining a copy +of this software and associated documentation files (the "Software"), to deal +in the Software without restriction, including without limitation the rights +to use, copy, modify, merge, publish, distribute, sublicense, and/or sell +copies of the Software, and to permit persons to whom the Software is +furnished to do so, subject to the following conditions: + +The above copyright notice and this permission notice shall be included in +all copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN +THE SOFTWARE. \ No newline at end of file diff --git a/extern/vulkan_memory_allocator/README.blender b/extern/vulkan_memory_allocator/README.blender new file mode 100644 index 00000000000..7877ccf3f7b --- /dev/null +++ b/extern/vulkan_memory_allocator/README.blender @@ -0,0 +1,5 @@ +Project: VulkanMemoryAllocator +URL: https://github.com/GPUOpen-LibrariesAndSDKs/VulkanMemoryAllocator +License: MIT +Upstream version: a6bfc23 +Local modifications: None diff --git a/extern/vulkan_memory_allocator/README.md b/extern/vulkan_memory_allocator/README.md new file mode 100644 index 00000000000..0096ab68141 --- /dev/null +++ b/extern/vulkan_memory_allocator/README.md @@ -0,0 +1,175 @@ +# Vulkan Memory Allocator + +Easy to integrate Vulkan memory allocation library. + +**Documentation:** Browse online: [Vulkan Memory Allocator](https://gpuopen-librariesandsdks.github.io/VulkanMemoryAllocator/html/) (generated from Doxygen-style comments in [include/vk_mem_alloc.h](include/vk_mem_alloc.h)) + +**License:** MIT. See [LICENSE.txt](LICENSE.txt) + +**Changelog:** See [CHANGELOG.md](CHANGELOG.md) + +**Product page:** [Vulkan Memory Allocator on GPUOpen](https://gpuopen.com/gaming-product/vulkan-memory-allocator/) + +**Build status:** + +- Windows: [](https://ci.appveyor.com/project/adam-sawicki-amd/vulkanmemoryallocator/branch/master) +- Linux: [](https://app.travis-ci.com/GPUOpen-LibrariesAndSDKs/VulkanMemoryAllocator) + +[](http://isitmaintained.com/project/GPUOpen-LibrariesAndSDKs/VulkanMemoryAllocator "Average time to resolve an issue") + +# Problem + +Memory allocation and resource (buffer and image) creation in Vulkan is difficult (comparing to older graphics APIs, like D3D11 or OpenGL) for several reasons: + +- It requires a lot of boilerplate code, just like everything else in Vulkan, because it is a low-level and high-performance API. +- There is additional level of indirection: `VkDeviceMemory` is allocated separately from creating `VkBuffer`/`VkImage` and they must be bound together. +- Driver must be queried for supported memory heaps and memory types. Different GPU vendors provide different types of it. +- It is recommended to allocate bigger chunks of memory and assign parts of them to particular resources, as there is a limit on maximum number of memory blocks that can be allocated. + +# Features + +This library can help game developers to manage memory allocations and resource creation by offering some higher-level functions: + +1. Functions that help to choose correct and optimal memory type based on intended usage of the memory. + - Required or preferred traits of the memory are expressed using higher-level description comparing to Vulkan flags. +2. Functions that allocate memory blocks, reserve and return parts of them (`VkDeviceMemory` + offset + size) to the user. + - Library keeps track of allocated memory blocks, used and unused ranges inside them, finds best matching unused ranges for new allocations, respects all the rules of alignment and buffer/image granularity. +3. Functions that can create an image/buffer, allocate memory for it and bind them together - all in one call. + +Additional features: + +- Well-documented - description of all functions and structures provided, along with chapters that contain general description and example code. +- 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. +- Configuration: Fill optional members of `VmaAllocatorCreateInfo` structure to provide custom CPU memory allocator, pointers to Vulkan functions and other parameters. +- Customization and integration with custom engines: Predefine appropriate macros to provide your own implementation of all external facilities used by the library like assert, mutex, atomic. +- Support for memory mapping, reference-counted internally. Support for persistently mapped memory: Just allocate with appropriate flag and access the pointer to already mapped memory. +- Support for non-coherent memory. Functions that flush/invalidate memory. `nonCoherentAtomSize` is respected automatically. +- Support for resource aliasing (overlap). +- Support for sparse binding and sparse residency: Convenience functions that allocate or free multiple memory pages at once. +- Custom memory pools: Create a pool with desired parameters (e.g. fixed or limited maximum size) and allocate memory out of it. +- 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. +- Support for Vulkan 1.0, 1.1, 1.2, 1.3. +- Support for extensions (and equivalent functionality included in new Vulkan versions): + - VK_KHR_dedicated_allocation: Just enable it and it will be used automatically by the library. + - VK_KHR_buffer_device_address: Flag `VK_MEMORY_ALLOCATE_DEVICE_ADDRESS_BIT_KHR` is automatically added to memory allocations where needed. + - 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. + - VK_EXT_memory_priority: Set `priority` of allocations or custom pools and it will be set automatically using this extension. + - VK_AMD_device_coherent_memory +- Defragmentation of GPU and CPU memory: Let the library move data around to free some memory blocks and make your allocations better compacted. +- Statistics: Obtain brief or 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. +- Debug annotations: Associate custom `void* pUserData` and debug `char* pName` with each allocation. +- JSON dump: Obtain a string in JSON format with detailed map of internal state, including list of allocations, their string names, and gaps between them. +- Convert this JSON dump into a picture to visualize your memory. See [tools/GpuMemDumpVis](tools/GpuMemDumpVis/README.md). +- Debugging incorrect memory usage: Enable initialization of all allocated memory with a bit pattern to detect usage of uninitialized or freed memory. Enable validation of a magic number after every allocation to detect out-of-bounds memory corruption. +- Support for interoperability with OpenGL. +- Virtual allocator: Interface for using core allocation algorithm to allocate any custom data, e.g. pieces of one large buffer. + +# Prerequisites + +- 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, RTTI, or C++ exceptions are not used. +- Public interface in C, in same convention as Vulkan API. Implementation in C++. +- Error handling implemented by returning `VkResult` error codes - same way as in Vulkan. +- Interface documented using Doxygen-style comments. +- Platform-independent, but developed and tested on Windows using Visual Studio. Continuous integration setup for Windows and Linux. Used also on Android, MacOS, and other platforms. + +# Example + +Basic usage of this library is very simple. Advanced features are optional. After you created global `VmaAllocator` object, a complete code needed to create a buffer may look like this: + +```cpp +VkBufferCreateInfo bufferInfo = { VK_STRUCTURE_TYP @@ Diff output truncated at 10240 characters. @@ _______________________________________________ Bf-blender-cvs mailing list [email protected] List details, subscription details or unsubscribe: https://lists.blender.org/mailman/listinfo/bf-blender-cvs
