Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/gwihlidal/vk-mem-rs
Rust bindings for AMD Vulkan Memory Allocator (VMA)
https://github.com/gwihlidal/vk-mem-rs
Last synced: 3 days ago
JSON representation
Rust bindings for AMD Vulkan Memory Allocator (VMA)
- Host: GitHub
- URL: https://github.com/gwihlidal/vk-mem-rs
- Owner: gwihlidal
- License: apache-2.0
- Created: 2018-12-10T04:33:44.000Z (about 6 years ago)
- Default Branch: master
- Last Pushed: 2024-07-26T04:48:30.000Z (7 months ago)
- Last Synced: 2025-01-31T18:34:23.272Z (10 days ago)
- Language: Rust
- Size: 480 KB
- Stars: 170
- Watchers: 11
- Forks: 71
- Open Issues: 2
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGES.md
- License: LICENSE-APACHE
- Code of conduct: CODE_OF_CONDUCT.md
Awesome Lists containing this project
README
vk-mem
========
[](https://travis-ci.com/gwihlidal/vk-mem-rs)
[](https://crates.io/crates/vk-mem)
[](https://docs.rs/vk-mem)
[](https://github.com/gwihlidal/vk-mem-rs)
This crate provides an FFI layer and idiomatic rust wrappers for the excellent AMD Vulkan Memory Allocator (VMA) C/C++ library.
- [Documentation](https://docs.rs/vk-mem)
- [Release Notes](https://github.com/gwihlidal/vk-mem-rs/releases)
- [VMA GitHub](https://github.com/GPUOpen-LibrariesAndSDKs/VulkanMemoryAllocator)
- [VMA Documentation](https://gpuopen-librariesandsdks.github.io/VulkanMemoryAllocator/html/)
- [GPU Open Announce](https://gpuopen.com/gaming-product/vulkan-memory-allocator/)
- [GPU Open Update](https://gpuopen.com/vulkan-memory-allocator-2-3-0/)
## Problem
Memory allocation and resource (buffer and image) creation in Vulkan is difficult (comparing to older graphics API-s, 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. The binding cannot be changed later - resource must be recreated.
- Driver must be queried for supported memory heaps and memory types. Different IHVs provide different types of it.
- It is recommended practice to allocate bigger chunks of memory and assign parts of them to particular resources.
## Features
This crate can help game developers to manage memory allocations and resource creation by offering some higher-level functions:
- 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.
- 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.
- Functions that can create an image/buffer, allocate memory for it and bind them together - all in one call.
Additional features:
- Cross-platform
- Windows
- Linux
- macOS (MoltenVK)
- Well tested and documented API
- Underlying library ships in a number of commerical game titles.
- Extensive documentation (including full algorithm descriptions in the VMA repository)
- Support for custom memory pools:
- Create a pool with desired parameters (e.g. fixed or limited maximum size)
- Allocate memory out of it.
- Support for a linear or buddy allocation strategy
- 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.
- Detailed statistics:
- Globally, per memory heap, and per memory type.
- Amount of memory used
- Amount of memory unused
- Number of allocated blocks
- Number of allocations
- etc.
- Debug annotations:
- Associate string with name or opaque pointer to your own data with every allocation.
- JSON dump:
- Obtain a string in JSON format with detailed map of internal state, including list of allocations and gaps between them.
- Convert this JSON dump into a picture to visualize your memory. See [tools/VmaDumpVis](https://github.com/GPUOpen-LibrariesAndSDKs/VulkanMemoryAllocator/blob/master/tools/VmaDumpVis/README.md).
- Support for memory mapping:
- Reference-counted internally.
- Support for persistently mapped memory; just allocate with appropriate flag and you get access to mapped pointer.
- Support for defragmenting allocations:
- Call one function and let the library move data around to free some memory blocks and make your allocations better compacted.
- Support for lost allocations:
- Allocate memory with appropriate flags and let the library remove allocations that are not used for many frames to make room for new ones.
- Support for non-coherent memory and flushing allocations:
- `nonCoherentAtomSize` is respected automatically.
- Supporting for attempting to detect incorrect mapped 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 before and after every allocation to detect out-of-bounds memory corruption.
## Planned Features
- Extensive unit tests and examples.
- Some unit tests already, but not full coverage
- Example isn't written - likely will port the VMA sample to `ash` and `vk_mem`
- Record and replay allocations, for in-depth analysis of memory usage, resource transitions, etc
- Check for correctness, measure performance, and gather statistics.
## Example
Basic usage of this crate is very simple; advanced features are optional.
After you create a `vk_mem::Allocator` instance, very little code is needed to create a buffer:
```rust
// Create the buffer (GPU only, 16KiB in this example)
let create_info = vk_mem::AllocationCreateInfo {
usage: vk_mem::MemoryUsage::GpuOnly,
..Default::default()
};
let (buffer, allocation, allocation_info) = allocator
.create_buffer(
&ash::vk::BufferCreateInfo::builder()
.size(16 * 1024)
.usage(ash::vk::BufferUsageFlags::VERTEX_BUFFER | ash::vk::BufferUsageFlags::TRANSFER_DST)
.build(),
&create_info,
)
.unwrap();
// Do stuff with buffer! (type is ash::vk::Buffer)
// Destroy the buffer
allocator.destroy_buffer(buffer, &allocation).unwrap();
```
With this one function call (`vk_mem::Allocator::create_buffer`):
- `ash::vk::Buffer` (`VkBuffer`) is created.
- `ash::vk::DeviceMemory` (`VkDeviceMemory`) block is allocated if needed.
- An unused region of the memory block is bound to this buffer.
- `vk_mem::Allocation` is created that represents memory assigned to this buffer. It can be queried for parameters like Vulkan memory handle and offset.
## MoltenVK
For MoltenVK on macOS, you need to have the proper environment variables set. Something like:
```bash
export SDK_PATH=/path/to/vulkansdk-macos-1.1.106.0
export DYLD_LIBRARY_PATH=$SDK_PATH/macOS/lib
export VK_ICD_FILENAMES=$SDK_PATH/macOS/etc/vulkan/icd.d/MoltenVK_icd.json
export VK_LAYER_PATH=$SDK_PATH/macOS/etc/vulkan/explicit_layer.d
cargo test
```
## Usage
Add this to your `Cargo.toml`:
```toml
[dependencies]
vk-mem = "0.3.0"
```
and add this to your crate root:
```rust
extern crate vk_mem;
```
## Compiling using MinGW W64
Vulkan Memory Allocator requires C++11 threads.
MinGW W64 does not support these by default, so you need to switch to the posix build.
For example, on debian you need to run the following:
```bash
update-alternatives --set x86_64-w64-mingw32-gcc /usr/bin/x86_64-w64-mingw32-gcc-posix
update-alternatives --set x86_64-w64-mingw32-g++ /usr/bin/x86_64-w64-mingw32-g++-posix
update-alternatives --set i686-w64-mingw32-gcc /usr/bin/i686-w64-mingw32-gcc-posix
update-alternatives --set i686-w64-mingw32-g++ /usr/bin/i686-w64-mingw32-g++-posix
```
## License
Licensed under either of
- Apache License, Version 2.0 ([LICENSE-APACHE](LICENSE-APACHE) or http://www.apache.org/licenses/LICENSE-2.0)
- MIT license ([LICENSE-MIT](LICENSE-MIT) or http://opensource.org/licenses/MIT)
at your option.
## Credits and Special Thanks
- [Adam Sawicki - AMD](https://github.com/adam-sawicki-amd) (Author of C/C++ library)
- [Maik Klein](https://github.com/MaikKlein) (Author of ash - Vulkan rust bindings)
- [Johan Andersson](https://github.com/repi) (Contributions)
- [Patrick Minogue](https://github.com/afpatmin) (Contributions)
- [Layl Conway](https://github.com/LaylConway) (Contributions)
- [aloucks](https://github.com/aloucks) (Contributions)
- [Henrik Rydgård](https://github.com/hrydgard) (Contributions)
- [msiglreith](https://github.com/msiglreith) (Contributions)
- [Maksym Pavlenko](https://github.com/mxpv) (Contributions)
- [Brandon Pollack](https://github.com/brandonpollack23) (Contributions)
## Contribution
Unless you explicitly state otherwise, any contribution intentionally submitted
for inclusion in this crate by you, as defined in the Apache-2.0 license, shall
be dual licensed as above, without any additional terms or conditions.
Contributions are always welcome; please look at the [issue tracker](https://github.com/gwihlidal/vk-mem-rs/issues) to see what known improvements are documented.
## Code of Conduct
Contribution to the vk-mem crate is organized under the terms of the
Contributor Covenant, the maintainer of vk-mem, @Neo-Zhixing, promises to
intervene to uphold that code of conduct.