Struct vulkano::memory::allocator::suballocator::MemoryAlloc

pub struct MemoryAlloc { /* private fields */ }

Memory allocations are portions of memory that are reserved for a specific resource or purpose.

There’s a few ways you can obtain a MemoryAlloc in Vulkano. Most commonly you will probably want to use a memory allocator. If you already have a DeviceMemory block on hand that you would like to turn into an allocation, you can use the constructor. Lastly, you can use a suballocator if you want to create multiple smaller allocations out of a bigger one.

Implementations

impl MemoryAlloc

pub fn new(device_memory: DeviceMemory) -> Result<Self, AllocationCreationError>

Creates a new MemoryAlloc.

The memory is mapped automatically if it’s host-visible.

pub fn offset(&self) -> DeviceSize

Returns the offset of the allocation within the DeviceMemory block.

pub fn size(&self) -> DeviceSize

Returns the size of the allocation.

pub fn allocation_type(&self) -> AllocationType

Returns the type of resources that can be bound to this allocation.

pub fn mapped_ptr(&self) -> Option<NonNull<c_void>>

Returns the mapped pointer to the start of the allocation if the memory is host-visible, otherwise returns None.

pub unsafe fn mapped_slice(&self) -> Option<&[u8]>

Returns a mapped slice to the data within the allocation if the memory is host-visible, otherwise returns None.

Safety

• While the returned slice exists, there must be no operations pending or executing in a GPU queue that write to the same memory.

pub unsafe fn mapped_slice_mut(&mut self) -> Option<&mut [u8]>

Returns a mapped mutable slice to the data within the allocation if the memory is host-visible, otherwise returns None.

Safety

• While the returned slice exists, there must be no operations pending or executing in a GPU queue that access the same memory.

pub unsafe fn invalidate_range(
    &self,
    range: Range<DeviceSize>
) -> Result<(), OomError>

Invalidates the host (CPU) cache for a range of the allocation.

You must call this method before the memory is read by the host, if the device previously wrote to the memory. It has no effect if the memory is not mapped or if the memory is host-coherent.

range is specified in bytes relative to the start of the allocation. The start and end of range must be a multiple of the non_coherent_atom_size device property, but range.end can also equal to self.size().

Safety

• If there are memory writes by the GPU that have not been propagated into the CPU cache, then there must not be any references in Rust code to the specified range of the memory.

Panics

• Panics if range is empty.
• Panics if range.end exceeds self.size.
• Panics if range.start or range.end are not a multiple of the non_coherent_atom_size.

pub unsafe fn flush_range(
    &self,
    range: Range<DeviceSize>
) -> Result<(), OomError>

Flushes the host (CPU) cache for a range of the allocation.

You must call this method after writing to the memory from the host, if the device is going to read the memory. It has no effect if the memory is not mapped or if the memory is host-coherent.

range is specified in bytes relative to the start of the allocation. The start and end of range must be a multiple of the non_coherent_atom_size device property, but range.end can also equal to self.size().

Safety

• There must be no operations pending or executing in a GPU queue that access the specified range of the memory.

Panics

• Panics if range is empty.
• Panics if range.end exceeds self.size.
• Panics if range.start or range.end are not a multiple of the non_coherent_atom_size.

pub fn device_memory(&self) -> &DeviceMemory

Returns the underlying block of DeviceMemory.

pub fn parent_allocation(&self) -> Option<&Self>

Returns the parent allocation if this allocation is a suballocation, otherwise returns None.

pub fn is_root(&self) -> bool

Returns true if this allocation is the root of the memory hierarchy.

pub fn is_dedicated(&self) -> bool

Returns true if this allocation is a dedicated allocation.

pub fn try_unwrap(self) -> Result<DeviceMemory, Self>

Returns the underlying block of DeviceMemory if this allocation is the root allocation and is not aliased, otherwise returns the allocation back wrapped in Err.

pub unsafe fn alias(&self) -> Option<Self>

Duplicates the allocation, creating aliased memory. Returns None if the allocation is a dedicated allocation.

You might consider using this method if you want to optimize memory usage by aliasing render targets for example, in which case you will have to double and triple check that the memory is not used concurrently unless it only involves reading. You are highly discouraged from doing this unless you have a reason to.

Safety

• You must ensure memory accesses are synchronized yourself.

pub fn shift(&mut self, amount: DeviceSize)

Increases the offset of the allocation by the specified amount and shrinks its size by the same amount.

Panics

• Panics if the amount exceeds the size of the allocation.

pub fn shrink(&mut self, new_size: DeviceSize)

Shrinks the size of the allocation to the specified new_size.

Panics

• Panics if the new_size exceeds the current size of the allocation.

pub unsafe fn set_offset(&mut self, new_offset: DeviceSize)

Sets the offset of the allocation without checking for memory aliasing.

See also shift, which moves the offset safely.

Safety

• You must ensure that the allocation doesn’t alias any other allocations within the DeviceMemory block, and if it does, then you must ensure memory accesses are synchronized yourself.
• You must ensure the allocation still fits inside the DeviceMemory block.

pub unsafe fn set_size(&mut self, new_size: DeviceSize)

Sets the size of the allocation without checking for memory aliasing.

See also shrink, which sets the size safely.

Safety

• You must ensure that the allocation doesn’t alias any other allocations within the DeviceMemory block, and if it does, then you must ensure memory accesses are synchronized yourself.
• You must ensure the allocation still fits inside the DeviceMemory block.

pub unsafe fn set_allocation_type(&mut self, new_type: AllocationType)

Sets the allocation type.

This might cause memory aliasing due to buffer-image granularity conflicts if the allocation type is Linear or NonLinear and is changed to a different one.

Safety

• You must ensure that the allocation doesn’t alias any other allocations within the DeviceMemory block, and if it does, then you must ensure memory accesses are synchronized yourself.

Trait Implementations

impl Debug for MemoryAlloc

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl DeviceOwned for MemoryAlloc

fn device(&self) -> &Arc<Device>

Returns the device that owns Self.

impl Drop for MemoryAlloc

fn drop(&mut self)

Executes the destructor for this type.

impl Send for MemoryAlloc

impl Sync for MemoryAlloc