From 08d42fdd3a2810502adba00779c32ac3786be6df Mon Sep 17 00:00:00 2001 From: Graham Wihlidal Date: Tue, 11 Dec 2018 22:13:52 +0100 Subject: [PATCH] Added to readme, and bumped to 0.1.1 --- CHANGES.md | 5 +++ Cargo.toml | 2 +- README.md | 116 ++++++++++++++++++++++++++++++++++++++++++++++++++++- 3 files changed, 120 insertions(+), 3 deletions(-) diff --git a/CHANGES.md b/CHANGES.md index 02ec43e..4d317fa 100644 --- a/CHANGES.md +++ b/CHANGES.md @@ -1,5 +1,10 @@ # Changes +## 0.1.1 (2018-12-11) + +* Major refactors +* Full documentation pass + ## 0.1.0 (2018-12-11) * First release \ No newline at end of file diff --git a/Cargo.toml b/Cargo.toml index 708365d..1bc1992 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -1,6 +1,6 @@ [package] name = "vk-mem" -version = "0.1.0" +version = "0.1.1" authors = ["Graham Wihlidal "] description = "Rust ffi bindings and idiomatic wrapper for AMD Vulkan Memory Allocator (VMA)" homepage = "https://github.com/gwihlidal/vk-mem-rs" diff --git a/README.md b/README.md index 963e2e8..cf86c0f 100644 --- a/README.md +++ b/README.md @@ -8,13 +8,109 @@ vk-mem ![MIT](https://img.shields.io/badge/license-MIT-blue.svg) ![APACHE2](https://img.shields.io/badge/license-APACHE2-blue.svg) -This crate provides an FFI layer and idiomatic rust wrappers for the excellent [AMD Vulkan Memory Allocator (VMA)](https://github.com/GPUOpen-LibrariesAndSDKs/VulkanMemoryAllocator) C/C++ library. +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-1/) +## 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 allocation_info = vk_mem::AllocationCreateInfo { + usage: vk_mem::MemoryUsage::GpuOnly, + ..Default::default() +}; + +let (buffer, allocation) = allocator + .create_buffer( + &ash::vk::BufferCreateInfo::builder() + .size(16 * 1024) + .usage(ash::vk::BufferUsageFlags::VERTEX_BUFFER | ash::vk::BufferUsageFlags::TRANSFER_DST) + .build(), + &allocation_info, + ) + .unwrap(); + +// Do stuff with buffer! (type is ash::vk::Buffer) + +// Destroy the buffer +allocator.destroy_buffer(buffer, &allocation).unwrap(); +``` + +## 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.92.0 @@ -24,6 +120,21 @@ 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.1.1" +``` + +and add this to your crate root: + +```rust +extern crate vk_mem; +``` + ## License Licensed under either of @@ -35,7 +146,8 @@ at your option. ## Credits and Special Thanks -- [Adam Sawicki](https://github.com/adam-sawicki-amd) (Author of C/C++ library) +- [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) ## Contribution