Struct vulkano::memory::allocator::suballocator::MemoryAlloc
source · pub struct MemoryAlloc { /* private fields */ }
Expand description
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§
source§impl MemoryAlloc
impl MemoryAlloc
sourcepub fn new(device_memory: DeviceMemory) -> Result<Self, AllocationCreationError>
pub fn new(device_memory: DeviceMemory) -> Result<Self, AllocationCreationError>
Creates a new MemoryAlloc
.
The memory is mapped automatically if it’s host-visible.
sourcepub fn offset(&self) -> DeviceSize
pub fn offset(&self) -> DeviceSize
Returns the offset of the allocation within the DeviceMemory
block.
sourcepub fn size(&self) -> DeviceSize
pub fn size(&self) -> DeviceSize
Returns the size of the allocation.
sourcepub fn allocation_type(&self) -> AllocationType
pub fn allocation_type(&self) -> AllocationType
Returns the type of resources that can be bound to this allocation.
sourcepub fn mapped_ptr(&self) -> Option<NonNull<c_void>>
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
.
sourcepub unsafe fn mapped_slice(&self) -> Option<&[u8]>
pub unsafe fn mapped_slice(&self) -> Option<&[u8]>
sourcepub unsafe fn mapped_slice_mut(&mut self) -> Option<&mut [u8]>
pub unsafe fn mapped_slice_mut(&mut self) -> Option<&mut [u8]>
sourcepub unsafe fn invalidate_range(
&self,
range: Range<DeviceSize>
) -> Result<(), VulkanError>
pub unsafe fn invalidate_range( &self, range: Range<DeviceSize> ) -> Result<(), VulkanError>
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
exceedsself.size
. - Panics if
range.start
orrange.end
are not a multiple of thenon_coherent_atom_size
.
sourcepub unsafe fn flush_range(
&self,
range: Range<DeviceSize>
) -> Result<(), VulkanError>
pub unsafe fn flush_range( &self, range: Range<DeviceSize> ) -> Result<(), VulkanError>
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
exceedsself.size
. - Panics if
range.start
orrange.end
are not a multiple of thenon_coherent_atom_size
.
sourcepub fn device_memory(&self) -> &DeviceMemory
pub fn device_memory(&self) -> &DeviceMemory
Returns the underlying block of DeviceMemory
.
sourcepub fn parent_allocation(&self) -> Option<&Self>
pub fn parent_allocation(&self) -> Option<&Self>
Returns the parent allocation if this allocation is a suballocation, otherwise returns
None
.
sourcepub fn is_root(&self) -> bool
pub fn is_root(&self) -> bool
Returns true
if this allocation is the root of the memory hierarchy.
sourcepub fn is_dedicated(&self) -> bool
pub fn is_dedicated(&self) -> bool
Returns true
if this allocation is a dedicated allocation.
sourcepub fn try_unwrap(self) -> Result<DeviceMemory, Self>
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
.
sourcepub unsafe fn alias(&self) -> Option<Self>
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.
sourcepub fn shift(&mut self, amount: DeviceSize)
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.
sourcepub fn shrink(&mut self, new_size: DeviceSize)
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.
sourcepub unsafe fn set_offset(&mut self, new_offset: DeviceSize)
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.
sourcepub unsafe fn set_size(&mut self, new_size: DeviceSize)
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.
sourcepub unsafe fn set_allocation_type(&mut self, new_type: AllocationType)
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.