# volcanic-mem

A Vulkan 1.4 memory allocator for devices with `VK_EXT_descriptor_heap`, built on [volcanic](https://github.com/alexdesander/volcanic).

- **Fast:** TLSF sub-allocation, so allocating and freeing take constant time.
- **Ready-to-use resources:** creates buffers, images and descriptor heaps with memory already bound.
- **Thread safe:** each memory type has its own lock.
- **Correct by default:** follows `bufferImageGranularity`, `nonCoherentAtomSize`, and the descriptor heap alignment and reserved-range limits.
- **Budget aware:** can use `VK_EXT_memory_budget` when it is enabled.
- **`VirtualBlock`:** the same allocator over a plain number range, e.g. for slots in a descriptor heap.

## Requirements

A Vulkan 1.4 device with `VK_EXT_descriptor_heap` and these features enabled: `bufferDeviceAddress`, `maintenance5` and `descriptorHeap`.

## Usage

```toml
[dependencies]
volcanic-mem = { version = "0.1", registry = "sourcelagoon" }
```

```rust
use volcanic::*;
use volcanic_mem::*;

let allocator = unsafe {
    Allocator::new(&instance, physical_device, &device_cmds, device, &AllocatorConfig::default())?
};

let mut buffer = allocator.create_buffer(&BufferDesc {
    size: 1 << 20,
    usage: VkBufferUsageFlags2::STORAGE_BUFFER,
    location: MemoryLocation::CpuToGpu,
})?;
buffer.mapped_slice_mut().unwrap().fill(0);
let range = buffer.range(); // pass to VkResourceDescriptorInfoEXT

allocator.destroy_buffer(buffer);
```

## Testing

```sh
cargo test
```

The GPU tests need a device that meets the requirements above. They use the Khronos validation layer if it is installed. Set `NO_VALIDATION=1` to turn it off.

`bench/` compares volcanic-mem with VMA and gpu-allocator:

```sh
cd bench && cargo run --release -- [virtual|device|reserved|fragmentation]
```

## License

MIT