Struct vk_mem_erupt::Allocator

pub struct Allocator { /* fields omitted */ }

Main allocator object

Implementations

impl Allocator

pub fn new(create_info: &AllocatorCreateInfo) -> Result<Self>

Constructor a new Allocator using the provided options.

pub fn get_physical_device_properties(&self) -> Result<PhysicalDeviceProperties>

The allocator fetches erupt::vk::PhysicalDeviceProperties from the physical device. You can get it here, without fetching it again on your own.

pub fn get_memory_properties(&self) -> Result<PhysicalDeviceMemoryProperties>

The allocator fetches erupt::vk::PhysicalDeviceMemoryProperties from the physical device. You can get it here, without fetching it again on your own.

pub fn get_memory_type_properties(
    &self,
    memory_type_index: u32
) -> Result<MemoryPropertyFlags>

Given a memory type index, returns erupt::vk::MemoryPropertyFlags of this memory type.

This is just a convenience function; the same information can be obtained using Allocator::get_memory_properties.

pub fn set_current_frame_index(&self, frame_index: u32)

Sets index of the current frame.

This function must be used if you make allocations with AllocationCreateFlags::CAN_BECOME_LOST and AllocationCreateFlags::CAN_MAKE_OTHER_LOST flags to inform the allocator when a new frame begins. Allocations queried using Allocator::get_allocation_info cannot become lost in the current frame.

pub fn calculate_stats(&self) -> Result<VmaStats>

Retrieves statistics from current state of the Allocator.

pub fn build_stats_string(&self, detailed_map: bool) -> Result<String>

Builds and returns statistics in JSON format.

pub fn find_memory_type_index(
    &self,
    memory_type_bits: u32,
    allocation_info: &AllocationCreateInfo
) -> Result<u32>

Helps to find memory type index, given memory type bits and allocation info.

This algorithm tries to find a memory type that:

• Is allowed by memory type bits.
• Contains all the flags from allocation_info.required_flags.
• Matches intended usage.
• Has as many flags from allocation_info.preferred_flags as possible.

Returns erupt::vk::Result::ERROR_FEATURE_NOT_PRESENT if not found. Receiving such a result from this function or any other allocating function probably means that your device doesn’t support any memory type with requested features for the specific type of resource you want to use it for. Please check parameters of your resource, like image layout (OPTIMAL versus LINEAR) or mip level count.

pub fn find_memory_type_index_for_buffer_info(
    &self,
    buffer_info: &BufferCreateInfo,
    allocation_info: &AllocationCreateInfo
) -> Result<u32>

Helps to find memory type index, given buffer info and allocation info.

It can be useful e.g. to determine value to be used as AllocatorPoolCreateInfo::memory_type_index. It internally creates a temporary, dummy buffer that never has memory bound. It is just a convenience function, equivalent to calling:

• erupt::vk::Device::create_buffer
• erupt::vk::Device::get_buffer_memory_requirements
• Allocator::find_memory_type_index
• erupt::vk::Device::destroy_buffer

pub fn find_memory_type_index_for_image_info(
    &self,
    image_info: &ImageCreateInfo,
    allocation_info: &AllocationCreateInfo
) -> Result<u32>

Helps to find memory type index, given image info and allocation info.

It can be useful e.g. to determine value to be used as AllocatorPoolCreateInfo::memory_type_index. It internally creates a temporary, dummy image that never has memory bound. It is just a convenience function, equivalent to calling:

• erupt::vk::Device::create_image
• erupt::vk::Device::get_image_memory_requirements
• Allocator::find_memory_type_index
• erupt::vk::Device::destroy_image

pub fn create_pool(
    &self,
    pool_info: &AllocatorPoolCreateInfo
) -> Result<AllocatorPool>

Allocates Vulkan device memory and creates AllocatorPool object.

pub fn destroy_pool(&self, pool: &AllocatorPool)

Destroys AllocatorPool object and frees Vulkan device memory.

pub fn get_pool_stats(&self, pool: &AllocatorPool) -> Result<VmaPoolStats>

Retrieves statistics of existing AllocatorPool object.

pub fn make_pool_allocations_lost(
    &self,
    pool: &mut AllocatorPool
) -> Result<usize>

Marks all allocations in given pool as lost if they are not used in current frame or AllocatorPoolCreateInfo::frame_in_use_count` back from now.

Returns the number of allocations marked as lost.

pub fn check_pool_corruption(&self, pool: &AllocatorPool) -> Result<()>

Checks magic number in margins around all allocations in given memory pool in search for corruptions.

Corruption detection is enabled only when VMA_DEBUG_DETECT_CORRUPTION macro is defined to nonzero, VMA_DEBUG_MARGIN is defined to nonzero and the pool is created in memory type that is erupt::vk::MemoryPropertyFlags::HOST_VISIBLE and erupt::vk::MemoryPropertyFlags::HOST_COHERENT.

Possible error values:

• erupt::vk::Result::ERROR_FEATURE_NOT_PRESENT - corruption detection is not enabled for specified pool.
• erupt::vk::Result::ERROR_VALIDATION_FAILED_EXT - corruption detection has been performed and found memory corruptions around one of the allocations. VMA_ASSERT is also fired in that case.
• Other value: Error returned by Vulkan, e.g. memory mapping failure.

pub fn allocate_memory(
    &self,
    memory_requirements: &MemoryRequirements,
    allocation_info: &AllocationCreateInfo
) -> Result<(Allocation, AllocationInfo)>

General purpose memory allocation.

You should free the memory using Allocator::free_memory or ‘Allocator::free_memory_pages’.

It is recommended to use Allocator::allocate_memory_for_buffer, Allocator::allocate_memory_for_image, Allocator::create_buffer, Allocator::create_image instead whenever possible.

pub fn allocate_memory_pages(
    &self,
    memory_requirements: &MemoryRequirements,
    allocation_info: &AllocationCreateInfo,
    allocation_count: usize
) -> Result<Vec<(Allocation, AllocationInfo)>>

General purpose memory allocation for multiple allocation objects at once.

You should free the memory using Allocator::free_memory or Allocator::free_memory_pages.

Word “pages” is just a suggestion to use this function to allocate pieces of memory needed for sparse binding. It is just a general purpose allocation function able to make multiple allocations at once. It may be internally optimized to be more efficient than calling Allocator::allocate_memory allocations.len() times.

All allocations are made using same parameters. All of them are created out of the same memory pool and type.

pub fn allocate_memory_for_buffer(
    &self,
    buffer: Buffer,
    allocation_info: &AllocationCreateInfo
) -> Result<(Allocation, AllocationInfo)>

Buffer specialized memory allocation.

You should free the memory using Allocator::free_memory or ‘Allocator::free_memory_pages’.

pub fn allocate_memory_for_image(
    &self,
    image: Image,
    allocation_info: &AllocationCreateInfo
) -> Result<(Allocation, AllocationInfo)>

Image specialized memory allocation.

You should free the memory using Allocator::free_memory or ‘Allocator::free_memory_pages’.

pub fn free_memory(&self, allocation: &Allocation)

Frees memory previously allocated using Allocator::allocate_memory, Allocator::allocate_memory_for_buffer, or Allocator::allocate_memory_for_image.

pub fn free_memory_pages(&self, allocations: &[Allocation])

Frees memory and destroys multiple allocations.

Word “pages” is just a suggestion to use this function to free pieces of memory used for sparse binding. It is just a general purpose function to free memory and destroy allocations made using e.g. Allocator::allocate_memory', 'Allocator::allocate_memory_pages and other functions.

It may be internally optimized to be more efficient than calling ’Allocator::free_memory allocations.len()` times.

Allocations in ‘allocations’ slice can come from any memory pools and types.

pub fn get_allocation_info(
    &self,
    allocation: &Allocation
) -> Result<AllocationInfo>

Returns current information about specified allocation and atomically marks it as used in current frame.

Current parameters of given allocation are returned in the result object, available through accessors.

This function also atomically “touches” allocation - marks it as used in current frame, just like Allocator::touch_allocation.

If the allocation is in lost state, allocation.get_device_memory returns erupt::vk::DeviceMemory::null().

Although this function uses atomics and doesn’t lock any mutex, so it should be quite efficient, you can avoid calling it too often.

If you just want to check if allocation is not lost, Allocator::touch_allocation will work faster.

pub fn touch_allocation(&self, allocation: &Allocation) -> Result<bool>

Returns true if allocation is not lost and atomically marks it as used in current frame.

If the allocation has been created with AllocationCreateFlags::CAN_BECOME_LOST flag, this function returns true if it’s not in lost state, so it can still be used. It then also atomically “touches” the allocation - marks it as used in current frame, so that you can be sure it won’t become lost in current frame or next frame_in_use_count frames.

If the allocation is in lost state, the function returns false. Memory of such allocation, as well as buffer or image bound to it, should not be used. Lost allocation and the buffer/image still need to be destroyed.

If the allocation has been created without AllocationCreateFlags::CAN_BECOME_LOST flag, this function always returns true.

pub unsafe fn set_allocation_user_data(
    &self,
    allocation: &Allocation,
    user_data: *mut c_void
)

Sets user data in given allocation to new value.

If the allocation was created with AllocationCreateFlags::USER_DATA_COPY_STRING, user_data must be either null, or pointer to a null-terminated string. The function makes local copy of the string and sets it as allocation’s user data. String passed as user data doesn’t need to be valid for whole lifetime of the allocation - you can free it after this call. String previously pointed by allocation’s user data is freed from memory.

If the flag was not used, the value of pointer user_data is just copied to allocation’s user data. It is opaque, so you can use it however you want - e.g. as a pointer, ordinal number or some handle to you own data.

pub fn create_lost_allocation(&self) -> Result<Allocation>

Creates new allocation that is in lost state from the beginning.

It can be useful if you need a dummy, non-null allocation.

You still need to destroy created object using Allocator::free_memory.

Returned allocation is not tied to any specific memory pool or memory type and not bound to any image or buffer. It has size = 0. It cannot be turned into a real, non-empty allocation.

pub fn map_memory(&self, allocation: &Allocation) -> Result<*mut u8>

Maps memory represented by given allocation and returns pointer to it.

Maps memory represented by given allocation to make it accessible to CPU code. When succeeded, result is a pointer to first byte of this memory.

If the allocation is part of bigger erupt::vk::DeviceMemory block, the pointer is correctly offseted to the beginning of region assigned to this particular allocation.

Mapping is internally reference-counted and synchronized, so despite raw Vulkan function erupt::vk::Device::MapMemory cannot be used to map same block of erupt::vk::DeviceMemory multiple times simultaneously, it is safe to call this function on allocations assigned to the same memory block. Actual Vulkan memory will be mapped on first mapping and unmapped on last unmapping.

If the function succeeded, you must call Allocator::unmap_memory to unmap the allocation when mapping is no longer needed or before freeing the allocation, at the latest.

It also safe to call this function multiple times on the same allocation. You must call Allocator::unmap_memory same number of times as you called Allocator::map_memory.

It is also safe to call this function on allocation created with AllocationCreateFlags::MAPPED flag. Its memory stays mapped all the time. You must still call Allocator::unmap_memory same number of times as you called Allocator::map_memory. You must not call Allocator::unmap_memory additional time to free the “0-th” mapping made automatically due to AllocationCreateFlags::MAPPED flag.

This function fails when used on allocation made in memory type that is not erupt::vk::MemoryPropertyFlags::HOST_VISIBLE.

This function always fails when called for allocation that was created with AllocationCreateFlags::CAN_BECOME_LOST flag. Such allocations cannot be mapped.

pub fn unmap_memory(&self, allocation: &Allocation)

Unmaps memory represented by given allocation, mapped previously using Allocator::map_memory.

pub fn flush_allocation(
    &self,
    allocation: &Allocation,
    offset: usize,
    size: usize
)

Flushes memory of given allocation.

Calls erupt::vk::Device::FlushMappedMemoryRanges for memory associated with given range of given allocation.

• offset must be relative to the beginning of allocation.
• size can be erupt::vk::WHOLE_SIZE. It means all memory from offset the the end of given allocation.
• offset and size don’t have to be aligned; hey are internally rounded down/up to multiple of nonCoherentAtomSize.
• If size is 0, this call is ignored.
• If memory type that the allocation belongs to is not erupt::vk::MemoryPropertyFlags::HOST_VISIBLE or it is erupt::vk::MemoryPropertyFlags::HOST_COHERENT, this call is ignored.

pub fn invalidate_allocation(
    &self,
    allocation: &Allocation,
    offset: usize,
    size: usize
)

Invalidates memory of given allocation.

Calls erupt::vk::Device::invalidate_mapped_memory_ranges for memory associated with given range of given allocation.

• offset must be relative to the beginning of allocation.
• size can be erupt::vk::WHOLE_SIZE. It means all memory from offset the the end of given allocation.
• offset and size don’t have to be aligned. They are internally rounded down/up to multiple of nonCoherentAtomSize.
• If size is 0, this call is ignored.
• If memory type that the allocation belongs to is not erupt::vk::MemoryPropertyFlags::HOST_VISIBLE or it is erupt::vk::MemoryPropertyFlags::HOST_COHERENT, this call is ignored.

pub fn check_corruption(&self, memory_types: MemoryPropertyFlags) -> Result<()>

Checks magic number in margins around all allocations in given memory types (in both default and custom pools) in search for corruptions.

memory_type_bits bit mask, where each bit set means that a memory type with that index should be checked.

Corruption detection is enabled only when VMA_DEBUG_DETECT_CORRUPTION macro is defined to nonzero, VMA_DEBUG_MARGIN is defined to nonzero and only for memory types that are HOST_VISIBLE and HOST_COHERENT.

Possible error values:

• erupt::vk::Result::ERROR_FEATURE_NOT_PRESENT - corruption detection is not enabled for any of specified memory types.
• erupt::vk::Result::ERROR_VALIDATION_FAILED_EXT - corruption detection has been performed and found memory corruptions around one of the allocations. VMA_ASSERT is also fired in that case.
• Other value: Error returned by Vulkan, e.g. memory mapping failure.

pub fn defragmentation_begin(
    &self,
    info: &DefragmentationInfo2<'_>
) -> Result<DefragmentationContext>

Begins defragmentation process.

Use this function instead of old, deprecated Allocator::defragment.

Warning! Between the call to Allocator::defragmentation_begin and Allocator::defragmentation_end.

• You should not use any of allocations passed as allocations or any allocations that belong to pools passed as pools, including calling Allocator::get_allocation_info, Allocator::touch_allocation, or access their data.

• Some mutexes protecting internal data structures may be locked, so trying to make or free any allocations, bind buffers or images, map memory, or launch another simultaneous defragmentation in between may cause stall (when done on another thread) or deadlock (when done on the same thread), unless you are 100% sure that defragmented allocations are in different pools.

• Information returned via stats and info.allocations_changed are undefined. They become valid after call to Allocator::defragmentation_end.

• If info.command_buffer is not null, you must submit that command buffer and make sure it finished execution before calling Allocator::defragmentation_end.

pub fn defragmentation_end(
    &self,
    context: &mut DefragmentationContext
) -> Result<(DefragmentationStats, Vec<bool>)>

Ends defragmentation process.

Use this function to finish defragmentation started by Allocator::defragmentation_begin.

pub fn defragment(
    &self,
    allocations: &[Allocation],
    defrag_info: Option<&DefragmentationInfo>
) -> Result<(DefragmentationStats, Vec<bool>)>

👎 Deprecated since 0.1.3:

This is a part of the old interface. It is recommended to use structure DefragmentationInfo2 and function Allocator::defragmentation_begin instead.

Compacts memory by moving allocations.

allocations is a slice of allocations that can be moved during this compaction. defrag_info optional configuration parameters. Returns statistics from the defragmentation, and an associated array to allocations which indicates which allocations were changed (if any).

Possible error values:

• erupt::vk::Result::INCOMPLETE if succeeded but didn’t make all possible optimizations because limits specified in defrag_info have been reached, negative error code in case of error.

This function works by moving allocations to different places (different erupt::vk::DeviceMemory objects and/or different offsets) in order to optimize memory usage. Only allocations that are in allocations slice can be moved. All other allocations are considered nonmovable in this call. Basic rules:

• Only allocations made in memory types that have erupt::vk::MemoryPropertyFlags::HOST_VISIBLE and erupt::vk::MemoryPropertyFlags::HOST_COHERENT flags can be compacted. You may pass other allocations but it makes no sense - these will never be moved.

• Custom pools created with AllocatorPoolCreateFlags::LINEAR_ALGORITHM or AllocatorPoolCreateFlags::BUDDY_ALGORITHM flag are not defragmented. Allocations passed to this function that come from such pools are ignored.

• Allocations created with AllocationCreateFlags::DEDICATED_MEMORY or created as dedicated allocations for any other reason are also ignored.

• Both allocations made with or without AllocationCreateFlags::MAPPED flag can be compacted. If not persistently mapped, memory will be mapped temporarily inside this function if needed.

• You must not pass same allocation object multiple times in allocations slice.

The function also frees empty erupt::vk::DeviceMemory blocks.

Warning: This function may be time-consuming, so you shouldn’t call it too often (like after every resource creation/destruction). You can call it on special occasions (like when reloading a game level or when you just destroyed a lot of objects). Calling it every frame may be OK, but you should measure that on your platform.

pub fn bind_buffer_memory(
    &self,
    buffer: Buffer,
    allocation: &Allocation
) -> Result<()>

Binds buffer to allocation.

Binds specified buffer to region of memory represented by specified allocation. Gets erupt::vk::DeviceMemory handle and offset from the allocation.

If you want to create a buffer, allocate memory for it and bind them together separately, you should use this function for binding instead of erupt::vk::Device::bind_buffer_memory, because it ensures proper synchronization so that when a erupt::vk::DeviceMemory object is used by multiple allocations, calls to erupt::vk::Device::bind_buffer_memory() or erupt::vk::Device::map_memory() won’t happen from multiple threads simultaneously (which is illegal in Vulkan).

It is recommended to use function Allocator::create_buffer instead of this one.

pub fn bind_image_memory(
    &self,
    image: Image,
    allocation: &Allocation
) -> Result<()>

Binds image to allocation.

Binds specified image to region of memory represented by specified allocation. Gets erupt::vk::DeviceMemory handle and offset from the allocation.

If you want to create a image, allocate memory for it and bind them together separately, you should use this function for binding instead of erupt::vk::Device::bind_image_memory, because it ensures proper synchronization so that when a erupt::vk::DeviceMemory object is used by multiple allocations, calls to erupt::vk::Device::bind_image_memory() or erupt::vk::Device::map_memory() won’t happen from multiple threads simultaneously (which is illegal in Vulkan).

It is recommended to use function Allocator::create_image instead of this one.

pub fn create_buffer(
    &self,
    buffer_info: &BufferCreateInfo,
    allocation_info: &AllocationCreateInfo
) -> Result<(Buffer, Allocation, AllocationInfo)>

This function automatically creates a buffer, allocates appropriate memory for it, and binds the buffer with the memory.

If the function succeeded, you must destroy both buffer and allocation when you no longer need them using either convenience function Allocator::destroy_buffer or separately, using erupt::Device::destroy_buffer and Allocator::free_memory.

If AllocatorCreateFlags::KHR_DEDICATED_ALLOCATION flag was used, VK_KHR_dedicated_allocation extension is used internally to query driver whether it requires or prefers the new buffer to have dedicated allocation. If yes, and if dedicated allocation is possible (AllocationCreateInfo::pool is null and AllocationCreateFlags::NEVER_ALLOCATE is not used), it creates dedicated allocation for this buffer, just like when using AllocationCreateFlags::DEDICATED_MEMORY.

pub fn destroy_buffer(&self, buffer: Buffer, allocation: &Allocation)

Destroys Vulkan buffer and frees allocated memory.

This is just a convenience function equivalent to:

erupt::vk::Device::destroy_buffer(buffer, None);
Allocator::free_memory(allocator, allocation);

It it safe to pass null as buffer and/or allocation.

pub fn create_image(
    &self,
    image_info: &ImageCreateInfo,
    allocation_info: &AllocationCreateInfo
) -> Result<(Image, Allocation, AllocationInfo)>

This function automatically creates an image, allocates appropriate memory for it, and binds the image with the memory.

If the function succeeded, you must destroy both image and allocation when you no longer need them using either convenience function Allocator::destroy_image or separately, using erupt::Device::destroy_image and Allocator::free_memory.

If AllocatorCreateFlags::KHR_DEDICATED_ALLOCATION flag was used, VK_KHR_dedicated_allocation extension is used internally to query driver whether it requires or prefers the new image to have dedicated allocation. If yes, and if dedicated allocation is possible (AllocationCreateInfo::pool is null and AllocationCreateFlags::NEVER_ALLOCATE is not used), it creates dedicated allocation for this image, just like when using AllocationCreateFlags::DEDICATED_MEMORY.

If VK_ERROR_VALIDAITON_FAILED_EXT is returned, VMA may have encountered a problem that is not caught by the validation layers. One example is if you try to create a 0x0 image, a panic will occur and VK_ERROR_VALIDAITON_FAILED_EXT is thrown.

pub fn destroy_image(&self, image: Image, allocation: &Allocation)

Destroys Vulkan image and frees allocated memory.

This is just a convenience function equivalent to:

erupt::vk::Device::destroy_image(image, None);
Allocator::free_memory(allocator, allocation);

It it safe to pass null as image and/or allocation.

pub fn destroy(&mut self)

Destroys the internal allocator instance. After this has been called, no other functions may be called. Useful for ensuring a specific destruction order (for example, if an Allocator is a member of something that owns the Vulkan instance and destroys it in its own Drop).

Trait Implementations

impl Drop for Allocator

Custom Drop implementation to clean up internal allocation instance

fn drop(&mut self)

Executes the destructor for this type.

impl Send for Allocator

impl Sync for Allocator