gpu-allocator

To use gpu-allocator in a no_std environment:

1. Disable default features and enable the hashbrown feature in your Cargo.toml to provide required Hash collections.

[dependencies]
gpu-allocator = { version = "0.28.0", default-features = false, features = ["hashbrown"] }

Note: no_std support requires Rust 1.81 or higher due to dependencies on core::error::Error.

To support both std and no_std builds in a single workspace, you can define features in your Cargo.toml like this:

[features]
default = ["std", "other features"]

std = ["gpu-allocator/std"]
hashbrown = ["gpu-allocator/hashbrown"]
other_features = []

[dependencies]
gpu-allocator = { version = "0.28.0", default-features = false }

[dependencies]
gpu-allocator = { version = "0.28.0", default-features = false, features = ["hashbrown", "other features"] }

If you enabled create_residency_set during allocator initialization, you can retrieve the MTLResidencySet via Allocator::residency_set().

This set contains all live heaps managed by the allocator. You can attach this set to command buffers or queues to make all allocated resources resident at once.

Note: You must manually call MTLResidencySet::commit() whenever these resources are used to ensure changes are visible to Metal (e.g., before committing a command buffer).

if let Some(residency_set) = allocator.residency_set() {
    // Attach residency_set to your command buffer or queue
    // and call commit() before use.
}

The AllocationScheme enum determines how the underlying Vulkan memory is handled:

• DedicatedBuffer(vk::Buffer): Performs a dedicated, driver-managed allocation for a specific buffer. This allows the driver to apply specific optimizations.
• DedicatedImage(vk::Image): Performs a dedicated, driver-managed allocation for a specific image.
• GpuAllocatorManaged: The memory is allocated and managed by gpu-allocator (standard sub-allocation behavior).

#[derive(Copy, Clone, Debug, Eq, PartialEq)]
pub enum AllocationScheme {
    DedicatedBuffer(vk::Buffer),
    DedicatedImage(vk::Image),
    GpuAllocatorManaged,
}

The AllocationType enum categorizes how memory is being used. This is useful for debugging and visualizers to distinguish between different allocation strategies.

• Free: Unallocated or free memory.
• Linear: Memory allocated in a linear/sequential fashion.
• NonLinear: Memory allocated in a non-sequential fashion.

To use the D3D12 allocator, create an Allocator instance using Allocator::new(). You must provide an AllocatorCreateDesc which includes:

• device: An ID3D12DeviceVersion (supports ID3D12Device, ID3D12Device10, or ID3D12Device12).
• debug_settings: An AllocatorDebugSettings object.
• allocation_sizes: An AllocationSizes object defining block sizes.

The allocator automatically handles different memory locations (GpuOnly, CpuToGpu, GpuToCpu) and manages heap categories based on the device's resource heap tier.

// Note: This is a conceptual sketch based on the API
let desc = AllocatorCreateDesc {
    device: ID3D12DeviceVersion::Device(my_device),
    debug_settings: my_debug_settings,
    allocation_sizes: my_allocation_sizes,
};
let mut allocator = Allocator::new(&desc)?;

To use the Metal allocator, create an Allocator instance using Allocator::new(). You must provide an AllocatorCreateDesc which requires a MTLDevice.

Key configuration options in AllocatorCreateDesc:

• device: The Metal device to allocate from.
• debug_settings: Configuration for logging and stack traces.
• allocation_sizes: Settings for memory block sizes.
• create_residency_set: If set to true, the allocator will manage a MTLResidencySet containing all live heaps. This is only supported on MacOS 15.0+ or iOS 18.0+.

let desc = AllocatorCreateDesc {
    device: my_mtl_device.clone(),
    debug_settings: AllocatorDebugSettings::default(),
    allocation_sizes: my_allocation_sizes,
    create_residency_set: true,
};
let mut allocator = Allocator::new(&desc).expect("Failed to create allocator");

To use the Vulkan allocator, create an Allocator instance using Allocator::new(). You must provide an AllocatorCreateDesc containing the necessary Vulkan handles and configuration settings.

Required fields in AllocatorCreateDesc:

• instance: An ash::Instance.
• device: An ash::Device.
• physical_device: A vk::PhysicalDevice.
• debug_settings: AllocatorDebugSettings for logging and stack traces.
• buffer_device_address: Boolean indicating if buffer device address support is needed.
• allocation_sizes: AllocationSizes for managing block sizes.

let allocator = Allocator::new(&AllocatorCreateDesc {
    instance,
    device,
    physical_device,
    debug_settings,
    buffer_device_address: true,
    allocation_sizes,
});

Add gpu-allocator to your Cargo.toml dependencies to use the library in your Rust project.

[dependencies]
gpu-allocator = "0.28.0"