Struct vma::Allocator

pub struct Allocator { /* private fields */ }

Main allocator object

Implementations

impl Allocator

pub unsafe fn begin_defragmentation( &self, info: &VmaDefragmentationInfo ) -> VkResult<DefragmentationContext<'_>>

Begins defragmentation process.

Returns

VK_SUCCESS if defragmentation can begin. VK_ERROR_FEATURE_NOT_PRESENT if defragmentation is not supported.

impl Allocator

pub fn create_pool( self: &Arc<Self>, create_info: &PoolCreateInfo<'_> ) -> VkResult<AllocatorPool>

Allocates Vulkan device memory and creates AllocatorPool object.

pub fn default_pool(self: &Arc<Self>) -> AllocatorPool

impl Allocator

pub fn new(create_info: AllocatorCreateInfo<'_>) -> VkResult<Self>

Constructor a new Allocator using the provided options.

pub unsafe fn get_physical_device_properties( &self ) -> VkResult<PhysicalDeviceProperties>

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

pub unsafe fn get_memory_properties(&self) -> &PhysicalDeviceMemoryProperties

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

pub unsafe 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_statistics(&self) -> VkResult<VmaTotalStatistics>

Retrieves statistics from current state of the Allocator.

pub fn get_heap_budgets(&self) -> VkResult<Vec<VmaBudget>>

Retrieves information about current memory usage and budget for all memory heaps.

This function is called “get” not “calculate” because it is very fast, suitable to be called every frame or every allocation. For more detailed statistics use vmaCalculateStatistics().

Note that when using allocator from multiple threads, returned information may immediately become outdated.

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

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

pub unsafe fn free_memory_pages(&self, allocations: &mut [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) -> 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 ash::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 unsafe fn set_allocation_user_data( &self, allocation: &mut 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 unsafe fn map_memory( &self, allocation: &mut Allocation ) -> VkResult<*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 ash::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 ash::vk::Device::MapMemory cannot be used to map same block of ash::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 ash::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 unsafe fn unmap_memory(&self, allocation: &mut Allocation)

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

pub fn flush_allocation( &self, allocation: &Allocation, offset: usize, size: usize ) -> VkResult<()>

Flushes memory of given allocation.

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

• offset must be relative to the beginning of allocation.
• size can be ash::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 ash::vk::MemoryPropertyFlags::HOST_VISIBLE or it is ash::vk::MemoryPropertyFlags::HOST_COHERENT, this call is ignored.

pub fn invalidate_allocation( &self, allocation: &Allocation, offset: usize, size: usize ) -> VkResult<()>

Invalidates memory of given allocation.

Calls ash::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 ash::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 ash::vk::MemoryPropertyFlags::HOST_VISIBLE or it is ash::vk::MemoryPropertyFlags::HOST_COHERENT, this call is ignored.

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

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:

• ash::vk::Result::ERROR_FEATURE_NOT_PRESENT - corruption detection is not enabled for any of specified memory types.
• ash::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 unsafe fn bind_buffer_memory( &self, allocation: &Allocation, buffer: Buffer ) -> VkResult<()>

Binds buffer to allocation.

Binds specified buffer to region of memory represented by specified allocation. Gets ash::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 ash::vk::Device::bind_buffer_memory, because it ensures proper synchronization so that when a ash::vk::DeviceMemory object is used by multiple allocations, calls to ash::vk::Device::bind_buffer_memory() or ash::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 unsafe fn bind_buffer_memory2( &self, allocation: &Allocation, allocation_local_offset: DeviceSize, buffer: Buffer, next: *const c_void ) -> VkResult<()>

Binds buffer to allocation with additional parameters.

• allocation
• allocation_local_offset - Additional offset to be added while binding, relative to the beginning of the allocation. Normally it should be 0.
• buffer
• next - A chain of structures to be attached to VkBindImageMemoryInfoKHR structure used internally. Normally it should be null.

This function is similar to vmaBindImageMemory(), but it provides additional parameters.

If pNext is not null, #VmaAllocator object must have been created with #VMA_ALLOCATOR_CREATE_KHR_BIND_MEMORY2_BIT flag or with VmaAllocatorCreateInfo::vulkanApiVersion >= VK_API_VERSION_1_1. Otherwise the call fails.

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

Binds image to allocation.

Binds specified image to region of memory represented by specified allocation. Gets ash::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 ash::vk::Device::bind_image_memory, because it ensures proper synchronization so that when a ash::vk::DeviceMemory object is used by multiple allocations, calls to ash::vk::Device::bind_image_memory() or ash::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 unsafe fn bind_image_memory2( &self, allocation: &Allocation, allocation_local_offset: DeviceSize, image: Image, next: *const c_void ) -> VkResult<()>

Binds image to allocation with additional parameters.

• allocation
• allocation_local_offset - Additional offset to be added while binding, relative to the beginning of the allocation. Normally it should be 0.
• image
• next - A chain of structures to be attached to VkBindImageMemoryInfoKHR structure used internally. Normally it should be null.

This function is similar to vmaBindImageMemory(), but it provides additional parameters.

If pNext is not null, #VmaAllocator object must have been created with #VMA_ALLOCATOR_CREATE_KHR_BIND_MEMORY2_BIT flag or with VmaAllocatorCreateInfo::vulkanApiVersion >= VK_API_VERSION_1_1. Otherwise the call fails.

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

Destroys Vulkan buffer and frees allocated memory.

This is just a convenience function equivalent to:

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

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

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

Destroys Vulkan image and frees allocated memory.

This is just a convenience function equivalent to:

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

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

pub unsafe fn flush_allocations<'a>( &self, allocations: impl IntoIterator<Item = &'a Allocation>, offsets: Option<&[DeviceSize]>, sizes: Option<&[DeviceSize]> ) -> VkResult<()>

Flushes memory of given set of allocations.“]

Calls vkFlushMappedMemoryRanges() for memory associated with given ranges of given allocations.“] For more information, see documentation of vmaFlushAllocation().”]

• allocations
• offsets - If not None, it must be a slice of offsets of regions to flush, relative to the beginning of respective allocations. None means all ofsets are zero.
• sizes - If not None, it must be a slice of sizes of regions to flush in respective allocations. None means VK_WHOLE_SIZE for all allocations.

pub unsafe fn invalidate_allocations<'a>( &self, allocations: impl IntoIterator<Item = &'a Allocation>, offsets: Option<&[DeviceSize]>, sizes: Option<&[DeviceSize]> ) -> VkResult<()>

Invalidates memory of given set of allocations.“]

Calls vkInvalidateMappedMemoryRanges() for memory associated with given ranges of given allocations.“] For more information, see documentation of vmaInvalidateAllocation().”]

• allocations
• offsets - If not None, it must be a slice of offsets of regions to flush, relative to the beginning of respective allocations. None means all ofsets are zero.
• sizes - If not None, it must be a slice of sizes of regions to flush in respective allocations. None means VK_WHOLE_SIZE for all allocations.

Trait Implementations

impl Alloc for Allocator

fn allocator(&self) -> &Allocator

fn pool(&self) -> PoolHandle

unsafe fn find_memory_type_index( &self, memory_type_bits: u32, allocation_info: &AllocationCreateInfo ) -> VkResult<u32>

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

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

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

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

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

unsafe fn allocate_memory( &self, memory_requirements: &MemoryRequirements, create_info: &AllocationCreateInfo ) -> VkResult<Allocation>

General purpose memory allocation.

unsafe fn allocate_memory_pages( &self, memory_requirements: &MemoryRequirements, create_info: &AllocationCreateInfo, allocation_count: usize ) -> VkResult<Vec<Allocation>>

General purpose memory allocation for multiple allocation objects at once.

unsafe fn allocate_memory_for_buffer( &self, buffer: Buffer, create_info: &AllocationCreateInfo ) -> VkResult<Allocation>

Buffer specialized memory allocation.

unsafe fn allocate_memory_for_image( &self, image: Image, create_info: &AllocationCreateInfo ) -> VkResult<Allocation>

Image specialized memory allocation.

unsafe fn create_buffer( &self, buffer_info: &BufferCreateInfo, create_info: &AllocationCreateInfo ) -> VkResult<(Buffer, Allocation)>

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

unsafe fn create_buffer_with_alignment( &self, buffer_info: &BufferCreateInfo, create_info: &AllocationCreateInfo, min_alignment: DeviceSize ) -> VkResult<(Buffer, Allocation)>

brief Creates a buffer with additional minimum alignment.

unsafe fn create_image( &self, image_info: &ImageCreateInfo, create_info: &AllocationCreateInfo ) -> VkResult<(Image, Allocation)>

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

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