Added to readme, and bumped to 0.1.1

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

Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "vk-mem"
-version = "0.1.0"
+version = "0.1.1"
 authors = ["Graham Wihlidal <graham@wihlidal.ca>"]
 description = "Rust ffi bindings and idiomatic wrapper for AMD Vulkan Memory Allocator (VMA)"
 homepage = "https://github.com/gwihlidal/vk-mem-rs"

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