pub struct Buffer { /* private fields */ }
Expand description
A storage for raw bytes.
Unlike RawBuffer
, a Buffer
has memory backing it, and can be used normally.
See the module-level documentation for more information about buffers.
Examples
Sometimes, you need a buffer that is rarely accessed by the host. To get the best performance in this case, one should use a buffer in device-local memory, that is inaccessible from the host. As such, to initialize or otherwise access such a buffer, we need a staging buffer.
The following example outlines the general strategy one may take when initializing a device-local buffer.
use vulkano::{
buffer::{BufferUsage, Buffer, BufferCreateInfo},
command_buffer::{
AutoCommandBufferBuilder, CommandBufferUsage, CopyBufferInfo,
PrimaryCommandBufferAbstract,
},
memory::allocator::{AllocationCreateInfo, MemoryTypeFilter},
sync::GpuFuture,
DeviceSize,
};
// Simple iterator to construct test data.
let data = (0..10_000).map(|i| i as f32);
// Create a host-accessible buffer initialized with the data.
let temporary_accessible_buffer = Buffer::from_iter(
memory_allocator.clone(),
BufferCreateInfo {
// Specify that this buffer will be used as a transfer source.
usage: BufferUsage::TRANSFER_SRC,
..Default::default()
},
AllocationCreateInfo {
// Specify use for upload to the device.
memory_type_filter: MemoryTypeFilter::PREFER_HOST
| MemoryTypeFilter::HOST_SEQUENTIAL_WRITE,
..Default::default()
},
data,
)
.unwrap();
// Create a buffer in device-local memory with enough space for a slice of `10_000` floats.
let device_local_buffer = Buffer::new_slice::<f32>(
memory_allocator.clone(),
BufferCreateInfo {
// Specify use as a storage buffer and transfer destination.
usage: BufferUsage::STORAGE_BUFFER | BufferUsage::TRANSFER_DST,
..Default::default()
},
AllocationCreateInfo {
// Specify use by the device only.
memory_type_filter: MemoryTypeFilter::PREFER_DEVICE,
..Default::default()
},
10_000 as DeviceSize,
)
.unwrap();
// Create a one-time command to copy between the buffers.
let mut cbb = AutoCommandBufferBuilder::primary(
&command_buffer_allocator,
queue.queue_family_index(),
CommandBufferUsage::OneTimeSubmit,
)
.unwrap();
cbb.copy_buffer(CopyBufferInfo::buffers(
temporary_accessible_buffer,
device_local_buffer.clone(),
))
.unwrap();
let cb = cbb.build().unwrap();
// Execute the copy command and wait for completion before proceeding.
cb.execute(queue.clone())
.unwrap()
.then_signal_fence_and_flush()
.unwrap()
.wait(None /* timeout */)
.unwrap()
Implementations§
source§impl Buffer
impl Buffer
sourcepub fn from_data<T>(
allocator: Arc<dyn MemoryAllocator>,
create_info: BufferCreateInfo,
allocation_info: AllocationCreateInfo,
data: T
) -> Result<Subbuffer<T>, Validated<AllocateBufferError>>where
T: BufferContents,
pub fn from_data<T>( allocator: Arc<dyn MemoryAllocator>, create_info: BufferCreateInfo, allocation_info: AllocationCreateInfo, data: T ) -> Result<Subbuffer<T>, Validated<AllocateBufferError>>where T: BufferContents,
Creates a new Buffer
and writes data
in it. Returns a Subbuffer
spanning the whole
buffer.
Note: This only works with memory types that are host-visible. If you want to upload data to a buffer allocated in device-local memory, you will need to create a staging buffer and copy the contents over.
Panics
- Panics if
create_info.size
is not zero. - Panics if the chosen memory type is not host-visible.
sourcepub fn from_iter<T, I>(
allocator: Arc<dyn MemoryAllocator>,
create_info: BufferCreateInfo,
allocation_info: AllocationCreateInfo,
iter: I
) -> Result<Subbuffer<[T]>, Validated<AllocateBufferError>>where
T: BufferContents,
I: IntoIterator<Item = T>,
I::IntoIter: ExactSizeIterator,
pub fn from_iter<T, I>( allocator: Arc<dyn MemoryAllocator>, create_info: BufferCreateInfo, allocation_info: AllocationCreateInfo, iter: I ) -> Result<Subbuffer<[T]>, Validated<AllocateBufferError>>where T: BufferContents, I: IntoIterator<Item = T>, I::IntoIter: ExactSizeIterator,
Creates a new Buffer
and writes all elements of iter
in it. Returns a Subbuffer
spanning the whole buffer.
Note: This only works with memory types that are host-visible. If you want to upload data to a buffer allocated in device-local memory, you will need to create a staging buffer and copy the contents over.
Panics
- Panics if
create_info.size
is not zero. - Panics if the chosen memory type is not host-visible.
- Panics if
iter
is empty.
sourcepub fn new_sized<T>(
allocator: Arc<dyn MemoryAllocator>,
create_info: BufferCreateInfo,
allocation_info: AllocationCreateInfo
) -> Result<Subbuffer<T>, Validated<AllocateBufferError>>where
T: BufferContents,
pub fn new_sized<T>( allocator: Arc<dyn MemoryAllocator>, create_info: BufferCreateInfo, allocation_info: AllocationCreateInfo ) -> Result<Subbuffer<T>, Validated<AllocateBufferError>>where T: BufferContents,
sourcepub fn new_slice<T>(
allocator: Arc<dyn MemoryAllocator>,
create_info: BufferCreateInfo,
allocation_info: AllocationCreateInfo,
len: DeviceSize
) -> Result<Subbuffer<[T]>, Validated<AllocateBufferError>>where
T: BufferContents,
pub fn new_slice<T>( allocator: Arc<dyn MemoryAllocator>, create_info: BufferCreateInfo, allocation_info: AllocationCreateInfo, len: DeviceSize ) -> Result<Subbuffer<[T]>, Validated<AllocateBufferError>>where T: BufferContents,
sourcepub fn new_unsized<T>(
allocator: Arc<dyn MemoryAllocator>,
create_info: BufferCreateInfo,
allocation_info: AllocationCreateInfo,
len: DeviceSize
) -> Result<Subbuffer<T>, Validated<AllocateBufferError>>where
T: BufferContents + ?Sized,
pub fn new_unsized<T>( allocator: Arc<dyn MemoryAllocator>, create_info: BufferCreateInfo, allocation_info: AllocationCreateInfo, len: DeviceSize ) -> Result<Subbuffer<T>, Validated<AllocateBufferError>>where T: BufferContents + ?Sized,
sourcepub fn new(
allocator: Arc<dyn MemoryAllocator>,
create_info: BufferCreateInfo,
allocation_info: AllocationCreateInfo,
layout: DeviceLayout
) -> Result<Arc<Self>, Validated<AllocateBufferError>>
pub fn new( allocator: Arc<dyn MemoryAllocator>, create_info: BufferCreateInfo, allocation_info: AllocationCreateInfo, layout: DeviceLayout ) -> Result<Arc<Self>, Validated<AllocateBufferError>>
Creates a new uninitialized Buffer
with the given layout
.
Panics
- Panics if
create_info.size
is not zero. - Panics if
layout.alignment()
is greater than 64.
sourcepub fn memory(&self) -> &BufferMemory
pub fn memory(&self) -> &BufferMemory
Returns the type of memory that is backing this buffer.
sourcepub fn memory_requirements(&self) -> &MemoryRequirements
pub fn memory_requirements(&self) -> &MemoryRequirements
Returns the memory requirements for this buffer.
sourcepub fn flags(&self) -> BufferCreateFlags
pub fn flags(&self) -> BufferCreateFlags
Returns the flags the buffer was created with.
sourcepub fn size(&self) -> DeviceSize
pub fn size(&self) -> DeviceSize
Returns the size of the buffer in bytes.
sourcepub fn usage(&self) -> BufferUsage
pub fn usage(&self) -> BufferUsage
Returns the usage the buffer was created with.
sourcepub fn sharing(&self) -> &Sharing<SmallVec<[u32; 4]>>
pub fn sharing(&self) -> &Sharing<SmallVec<[u32; 4]>>
Returns the sharing the buffer was created with.
sourcepub fn external_memory_handle_types(&self) -> ExternalMemoryHandleTypes
pub fn external_memory_handle_types(&self) -> ExternalMemoryHandleTypes
Returns the external memory handle types that are supported with this buffer.
sourcepub fn device_address(
&self
) -> Result<NonNullDeviceAddress, Box<ValidationError>>
pub fn device_address( &self ) -> Result<NonNullDeviceAddress, Box<ValidationError>>
Returns the device address for this buffer.