Struct vulkano::buffer::Buffer

pub struct Buffer { /* private fields */ }

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

impl Buffer

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.

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.

pub fn new_sized<T>( allocator: Arc<dyn MemoryAllocator>, create_info: BufferCreateInfo, allocation_info: AllocationCreateInfo ) -> Result<Subbuffer<T>, Validated<AllocateBufferError>>where T: BufferContents,

Creates a new uninitialized Buffer for sized data. Returns a Subbuffer spanning the whole buffer.

Panics

• Panics if create_info.size is not zero.

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,

Creates a new uninitialized Buffer for a slice. Returns a Subbuffer spanning the whole buffer.

Panics

• Panics if create_info.size is not zero.
• Panics if len is zero.

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,

Creates a new uninitialized Buffer for unsized data. Returns a Subbuffer spanning the whole buffer.

Panics

• Panics if create_info.size is not zero.
• Panics if len is zero.

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.

pub fn memory(&self) -> &BufferMemory

Returns the type of memory that is backing this buffer.

pub fn memory_requirements(&self) -> &MemoryRequirements

Returns the memory requirements for this buffer.

pub fn flags(&self) -> BufferCreateFlags

Returns the flags the buffer was created with.

pub fn size(&self) -> DeviceSize

Returns the size of the buffer in bytes.

pub fn usage(&self) -> BufferUsage

Returns the usage the buffer was created with.

pub fn sharing(&self) -> &Sharing<SmallVec<[u32; 4]>>

Returns the sharing the buffer was created with.

pub fn external_memory_handle_types(&self) -> ExternalMemoryHandleTypes

Returns the external memory handle types that are supported with this buffer.

pub fn device_address( &self ) -> Result<NonNullDeviceAddress, Box<ValidationError>>

Returns the device address for this buffer.

Trait Implementations

impl Debug for Buffer

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

Formats the value using the given formatter.

impl DeviceOwned for Buffer

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

Returns the device that owns self.

impl Hash for Buffer

fn hash<H: Hasher>(&self, state: &mut H)

Feeds this value into the given Hasher.

fn hash_slice<H>(data: &[Self], state: &mut H)where H: Hasher, Self: Sized,

Feeds a slice of this type into the given Hasher.

impl PartialEq for Buffer

fn eq(&self, other: &Self) -> bool

This method tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

This method tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl VulkanObject for Buffer

type Handle = Buffer

The type of the object.

fn handle(&self) -> Self::Handle

Returns the raw Vulkan handle of the object.

impl Eq for Buffer