memkit-gpu 0.1.0-alpha.1

# memkit-gpu


**Backend-agnostic GPU memory management for the memkit ecosystem.**

> **Version:** 0.1.0-alpha.1

[![Crates.io](https://img.shields.io/crates/v/memkit-gpu.svg)](https://crates.io/crates/memkit-gpu)
[![Documentation](https://docs.rs/memkit-gpu/badge.svg)](https://docs.rs/memkit-gpu)
[![License: MPL-2.0](https://img.shields.io/badge/License-MPL%202.0-brightgreen.svg)](https://opensource.org/licenses/MPL-2.0)

## Overview


memkit-gpu provides a unified GPU memory management API that works across different graphics backends. Write your code once, run it on Vulkan, Metal, or DirectX 12.

## Features


- **Backend-Agnostic** — Same API works across all GPU backends
- **Staging Buffers** — Efficient CPU → GPU data transfers
- **Device Buffers** — Fast device-local memory
- **Batch Transfers** — Coalesce multiple transfers for efficiency
- **Memory Pools** — Reuse GPU buffers to reduce allocation overhead

## Quick Start


```rust
use memkit_gpu::{MkGpu, MkBufferUsage, DummyBackend};

// Create GPU allocator (using dummy backend for testing)
let gpu = MkGpu::new(DummyBackend::new());

// Create staging buffer and upload data
let vertices: &[f32] = &[0.0, 1.0, 0.0, 1.0, 0.0, 0.0];
let staging = gpu.staging_buffer_with_data(vertices).unwrap();

// Create device-local buffer
let device = gpu.create_device_buffer(
    std::mem::size_of_val(vertices),
    MkBufferUsage::VERTEX | MkBufferUsage::TRANSFER_DST,
).unwrap();

// Transfer data
gpu.transfer(&staging, &device).unwrap();
```

## Backend-Agnostic Code


```rust
use memkit_gpu::{MkGpu, MkGpuBackend, MkBufferUsage};

// Generic function works with ANY backend
fn upload_mesh<B: MkGpuBackend>(
    gpu: &MkGpu<B>,
    vertices: &[Vertex],
) -> Result<MkDeviceBuffer<B>, B::Error> {
    let staging = gpu.staging_buffer_with_data(vertices)?;
    let device = gpu.create_device_buffer(
        std::mem::size_of_val(vertices),
        MkBufferUsage::VERTEX | MkBufferUsage::TRANSFER_DST,
    )?;
    gpu.transfer(&staging, &device)?;
    Ok(device)
}
```

## Backends


| Backend | Feature Flag | Status |
|---------|--------------|--------|
| Dummy (CPU simulation) | (default) | ✅ Ready |
| Vulkan | `vulkan` | ✅ Ready |
| Metal | `metal` | 🚧 Planned |
| DirectX 12 | `dx12` | 🚧 Planned |

### Dummy Backend


The dummy backend simulates GPU operations in CPU memory. Useful for:
- Unit testing without a GPU
- Running on systems without GPU support
- Prototyping before implementing a real backend

```rust
use memkit_gpu::{DummyBackend, DummyBackendConfig};

// Default config
let backend = DummyBackend::new();

// Custom config
let config = DummyBackendConfig {
    max_buffer_size: 64 * 1024 * 1024, // 64 MB
    simulate_device_local: true,       // Device-local buffers not mappable
    transfer_delay_us: 0,              // Simulate transfer latency
};
let backend = DummyBackend::with_config(config);
```

### Vulkan Backend


Requires the `vulkan` feature flag. Uses `ash` and `gpu-allocator`.

```toml
[dependencies]
memkit-gpu = { version = "0.1.0-alpha.1", features = ["vulkan"] }
```

```rust
use memkit_gpu::{MkGpu, VulkanBackend, VulkanConfig};

let config = VulkanConfig {
    app_name: "My App".to_string(),
    validation: cfg!(debug_assertions),
    ..Default::default()
};

let backend = VulkanBackend::new(config)?;
let gpu = MkGpu::new(backend);
```

## Types


| Type | Description |
|------|-------------|
| `MkGpu<B>` | Main GPU allocator, generic over backend |
| `MkDeviceBuffer<B>` | Device-local buffer |
| `MkStagingBuffer<B>` | CPU-accessible staging buffer |
| `MkGpuTransfer` | Pending transfer operation |
| `MkGpuPool<B>` | Buffer pool for reuse |
| `MkMemoryType` | Memory type classification |
| `MkBufferUsage` | Buffer usage flags |

## License


This project is licensed under the Mozilla Public License 2.0 - see the [LICENSE.md](../LICENSE.md) file for details.