Struct vulkano::memory::MappedDeviceMemory

source ·

pub struct MappedDeviceMemory { /* private fields */ }

👎Deprecated since 0.34.0: use the methods provided directly on DeviceMemory instead

Expand 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

source

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.

source

pub fn unmap(self) -> DeviceMemory

Unmaps the memory. It will no longer be accessible from the CPU.

source

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.

source

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.

source

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.

source

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.