Struct vulkano::memory::MappedDeviceMemory
source · pub struct MappedDeviceMemory { /* private fields */ }
DeviceMemory
insteadExpand description
Represents device memory that has been mapped in a CPU-accessible space.
In order to access the contents of the allocated memory, you can use the read
and write
methods.
Examples
use vulkano::memory::{DeviceMemory, MappedDeviceMemory, MemoryAllocateInfo, MemoryPropertyFlags};
// The memory type must be mappable.
let memory_type_index = device
.physical_device()
.memory_properties()
.memory_types
.iter()
.position(|t| t.property_flags.intersects(MemoryPropertyFlags::HOST_VISIBLE))
.map(|i| i as u32)
.unwrap(); // Vk specs guarantee that this can't fail
// Allocates 1KB of memory.
let memory = DeviceMemory::allocate(
device.clone(),
MemoryAllocateInfo {
allocation_size: 1024,
memory_type_index,
..Default::default()
},
)
.unwrap();
let mapped_memory = MappedDeviceMemory::new(memory, 0..1024).unwrap();
// Get access to the content.
// Note that this is very unsafe because the access is unsynchronized.
unsafe {
let content = mapped_memory.write(0..1024).unwrap();
content[12] = 54;
}
Implementations§
source§impl MappedDeviceMemory
impl MappedDeviceMemory
sourcepub fn new(
memory: DeviceMemory,
range: Range<DeviceSize>
) -> Result<Self, Validated<VulkanError>>
pub fn new( memory: DeviceMemory, range: Range<DeviceSize> ) -> Result<Self, Validated<VulkanError>>
Maps a range of memory to be accessed by the CPU.
memory
must be allocated from host-visible memory.
range
is specified in bytes relative to the start of the memory allocation, and must fall
within the range of the allocation (0..allocation_size
). If memory
was not allocated
from host-coherent memory, then the start and end of range
must be a multiple of the
non_coherent_atom_size
device
property, but range.end
can also the memory’s allocation_size
.
Panics
- Panics if
range
is empty.
sourcepub fn unmap(self) -> DeviceMemory
pub fn unmap(self) -> DeviceMemory
Unmaps the memory. It will no longer be accessible from the CPU.
sourcepub unsafe fn invalidate_range(
&self,
range: Range<DeviceSize>
) -> Result<(), Validated<VulkanError>>
pub unsafe fn invalidate_range( &self, range: Range<DeviceSize> ) -> Result<(), Validated<VulkanError>>
Invalidates the host (CPU) cache for a range of mapped memory.
If the mapped memory is not host-coherent, you must call this function before the memory is read by the host, if the device previously wrote to the memory. It has no effect if the mapped memory is host-coherent.
range
is specified in bytes relative to the start of the memory allocation, and must fall
within the range of the memory mapping given to new
. If the memory was not allocated
from host-coherent memory, then the start and end of range
must be a multiple of the
non_coherent_atom_size
device
property, but range.end
can also equal the memory’s allocation_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.
sourcepub unsafe fn flush_range(
&self,
range: Range<DeviceSize>
) -> Result<(), Validated<VulkanError>>
pub unsafe fn flush_range( &self, range: Range<DeviceSize> ) -> Result<(), Validated<VulkanError>>
Flushes the host (CPU) cache for a range of mapped memory.
If the mapped memory is not host-coherent, you must call this function after writing to the memory, if the device is going to read the memory. It has no effect if the mapped memory is host-coherent.
range
is specified in bytes relative to the start of the memory allocation, and must fall
within the range of the memory mapping given to map
. If the memory was not allocated
from host-coherent memory, then the start and end of range
must be a multiple of the
non_coherent_atom_size
device
property, but range.end
can also equal the memory’s allocation_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.
sourcepub unsafe fn read(
&self,
range: Range<DeviceSize>
) -> Result<&[u8], Box<ValidationError>>
pub unsafe fn read( &self, range: Range<DeviceSize> ) -> Result<&[u8], Box<ValidationError>>
Returns a reference to bytes in the mapped memory.
range
is specified in bytes relative to the start of the memory allocation, and must fall
within the range of the memory mapping given to map
. If the memory was not allocated
from host-coherent memory, then the start and end of range
must be a multiple of the
non_coherent_atom_size
device
property, but range.end
can also equal the memory’s allocation_size
.
Safety
- While the returned reference exists, there must not be any mutable references in Rust code to the same memory.
- While the returned reference exists, there must be no operations pending or executing in a GPU queue, that write to the same memory.
Panics
- Panics if
range
is empty.
sourcepub unsafe fn write(
&self,
range: Range<DeviceSize>
) -> Result<&mut [u8], Box<ValidationError>>
pub unsafe fn write( &self, range: Range<DeviceSize> ) -> Result<&mut [u8], Box<ValidationError>>
Returns a mutable reference to bytes in the mapped memory.
range
is specified in bytes relative to the start of the memory allocation, and must fall
within the range of the memory mapping given to map
. If the memory was not allocated
from host-coherent memory, then the start and end of range
must be a multiple of the
non_coherent_atom_size
device
property, but range.end
can also equal the memory’s allocation_size
.
Safety
- While the returned reference exists, there must not be any other references in Rust code to the same memory.
- While the returned reference exists, there must be no operations pending or executing in a GPU queue, that access the same memory.
Panics
- Panics if
range
is empty.