Struct vulkano::buffer::device_local::DeviceLocalBuffer

pub struct DeviceLocalBuffer<T, A = PotentialDedicatedAllocation<StandardMemoryPoolAlloc>>where
    T: BufferContents + ?Sized,{ /* private fields */ }

Buffer whose content is in device-local memory.

This buffer type is useful in order to store intermediary data. For example you execute a compute shader that writes to this buffer, then read the content of the buffer in a following compute or graphics pipeline.

The DeviceLocalBuffer will be in device-local memory, unless the device doesn’t provide any device-local memory.

Usage

Since a DeviceLocalBuffer can only be directly accessed by the GPU, data cannot be transfered between the host process and the buffer alone. One must use additional buffers which are accessible to the CPU as staging areas, then use command buffers to execute the necessary data transfers.

Despite this, if one knows in advance that a buffer will not need to be frequently accessed by the host, then there may be significant performance gains by using a DeviceLocalBuffer over a buffer type which allows host access.

Example

The following example outlines the general strategy one may take when initializing a DeviceLocalBuffer.

use vulkano::buffer::{BufferUsage, CpuAccessibleBuffer, DeviceLocalBuffer};
use vulkano::command_buffer::{AutoCommandBufferBuilder, CommandBufferUsage, CopyBufferInfo, PrimaryCommandBuffer};
use vulkano::sync::GpuFuture;

// Simple iterator to construct test data.
let data = (0..10_000).map(|i| i as f32);

// Create a CPU accessible buffer initialized with the data.
let temporary_accessible_buffer = CpuAccessibleBuffer::from_iter(
    device.clone(),
    BufferUsage { transfer_src: true, ..BufferUsage::empty() }, // Specify this buffer will be used as a transfer source.
    false,
    data,
)
.unwrap();

// Create a buffer array on the GPU with enough space for `10_000` floats.
let device_local_buffer = DeviceLocalBuffer::<[f32]>::array(
    device.clone(),
    10_000 as vulkano::DeviceSize,
    BufferUsage {
        storage_buffer: true,
        transfer_dst: true,
        ..BufferUsage::empty()
    }, // Specify use as a storage buffer and transfer destination.
    device.active_queue_family_indices().iter().copied(),
)
.unwrap();

// Create a one-time command to copy between the buffers.
let mut cbb = AutoCommandBufferBuilder::primary(
    device.clone(),
    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 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<T> DeviceLocalBuffer<T>where
    T: BufferContents,

pub fn new(
    device: Arc<Device>,
    usage: BufferUsage,
    queue_family_indices: impl IntoIterator<Item = u32>
) -> Result<Arc<DeviceLocalBuffer<T>>, DeviceMemoryError>

Builds a new buffer. Only allowed for sized data.

Panics

• Panics if T has zero size.

impl<T> DeviceLocalBuffer<T>where
    T: BufferContents + ?Sized,

pub fn from_buffer<B>(
    source: Arc<B>,
    usage: BufferUsage,
    queue: Arc<Queue>
) -> Result<(Arc<DeviceLocalBuffer<T>>, CommandBufferExecFuture<NowFuture, PrimaryAutoCommandBuffer>), DeviceLocalBufferCreationError>where
    B: TypedBufferAccess<Content = T> + 'static,

Builds a DeviceLocalBuffer that copies its data from another buffer.

This function returns two objects: the newly-created buffer, and a future representing the initial upload operation. In order to be allowed to use the DeviceLocalBuffer, you must either submit your operation after this future, or execute this future and wait for it to be finished before submitting your own operation.

impl<T> DeviceLocalBuffer<T>where
    T: BufferContents,

pub fn from_data(
    data: T,
    usage: BufferUsage,
    queue: Arc<Queue>
) -> Result<(Arc<DeviceLocalBuffer<T>>, CommandBufferExecFuture<NowFuture, PrimaryAutoCommandBuffer>), DeviceLocalBufferCreationError>

Builds an DeviceLocalBuffer from some data.

This function builds a memory-mapped intermediate buffer, writes the data to it, builds a command buffer that copies from this intermediate buffer to the final buffer, and finally submits the command buffer as a future.

This function returns two objects: the newly-created buffer, and a future representing the initial upload operation. In order to be allowed to use the DeviceLocalBuffer, you must either submit your operation after this future, or execute this future and wait for it to be finished before submitting your own operation.

Panics

• Panics if T has zero size.

impl<T> DeviceLocalBuffer<[T]>where
    [T]: BufferContents,

pub fn from_iter<D>(
    data: D,
    usage: BufferUsage,
    queue: Arc<Queue>
) -> Result<(Arc<DeviceLocalBuffer<[T]>>, CommandBufferExecFuture<NowFuture, PrimaryAutoCommandBuffer>), DeviceLocalBufferCreationError>where
    D: IntoIterator<Item = T>,
    D::IntoIter: ExactSizeIterator,

Panics

• Panics if T has zero size.
• Panics if data is empty.

impl<T> DeviceLocalBuffer<[T]>where
    [T]: BufferContents,

pub fn array(
    device: Arc<Device>,
    len: DeviceSize,
    usage: BufferUsage,
    queue_family_indices: impl IntoIterator<Item = u32>
) -> Result<Arc<DeviceLocalBuffer<[T]>>, DeviceMemoryError>

Builds a new buffer. Can be used for arrays.

Panics

• Panics if T has zero size.
• Panics if len is zero.

impl<T> DeviceLocalBuffer<T>where
    T: BufferContents + ?Sized,

pub unsafe fn raw(
    device: Arc<Device>,
    size: DeviceSize,
    usage: BufferUsage,
    queue_family_indices: impl IntoIterator<Item = u32>
) -> Result<Arc<DeviceLocalBuffer<T>>, DeviceMemoryError>

Builds a new buffer without checking the size.

Safety

• You must ensure that the size that you pass is correct for T.

Panics

• Panics if size is zero.

pub unsafe fn raw_with_exportable_fd(
    device: Arc<Device>,
    size: DeviceSize,
    usage: BufferUsage,
    queue_family_indices: impl IntoIterator<Item = u32>
) -> Result<Arc<DeviceLocalBuffer<T>>, DeviceMemoryError>

Same as raw but with exportable fd option for the allocated memory on Linux/BSD

Panics

• Panics if size is zero.

pub fn export_posix_fd(&self) -> Result<File, DeviceMemoryError>

Exports posix file descriptor for the allocated memory requires khr_external_memory_fd and khr_external_memory extensions to be loaded. Only works on Linux/BSD.

impl<T, A> DeviceLocalBuffer<T, A>where
    T: BufferContents + ?Sized,

pub fn queue_family_indices(&self) -> &[u32]

Returns the queue families this buffer can be used on.

Trait Implementations

impl<T, A> BufferAccess for DeviceLocalBuffer<T, A>where
    T: BufferContents + ?Sized,
    A: Send + Sync,

fn inner(&self) -> BufferInner<'_>

Returns the inner information about this buffer.

fn size(&self) -> DeviceSize

Returns the size of the buffer in bytes.

fn usage(&self) -> &BufferUsage

Returns the usage the buffer was created with.

fn into_buffer_slice(self: &Arc<Self>) -> Arc<BufferSlice<Self::Content, Self>>where
    Self: Sized + TypedBufferAccess,

Returns a BufferSlice covering the whole buffer.

fn slice<T>(
    self: &Arc<Self>,
    range: Range<DeviceSize>
) -> Option<Arc<BufferSlice<[T], Self>>>where
    Self: Sized + TypedBufferAccess<Content = [T]>,

Returns a BufferSlice for a subrange of elements in the buffer. Returns None if out of range.

fn index<T>(
    self: &Arc<Self>,
    index: DeviceSize
) -> Option<Arc<BufferSlice<T, Self>>>where
    Self: Sized + TypedBufferAccess<Content = [T]>,

Returns a BufferSlice for a single element in the buffer. Returns None if out of range.

fn raw_device_address(&self) -> Result<NonZeroU64, BufferDeviceAddressError>

Gets the device address for this buffer.

impl<T: Debug, A: Debug> Debug for DeviceLocalBuffer<T, A>where
    T: BufferContents + ?Sized,

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

Formats the value using the given formatter.

impl<T, A> DeviceOwned for DeviceLocalBuffer<T, A>where
    T: BufferContents + ?Sized,

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

Returns the device that owns Self.

impl<T, A> Hash for DeviceLocalBuffer<T, A>where
    T: BufferContents + ?Sized,
    A: Send + Sync,

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,

Feeds a slice of this type into the given Hasher.

impl<T, A> PartialEq<DeviceLocalBuffer<T, A>> for DeviceLocalBuffer<T, A>where
    T: BufferContents + ?Sized,
    A: Send + Sync,

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<T, A> TypedBufferAccess for DeviceLocalBuffer<T, A>where
    T: BufferContents + ?Sized,
    A: Send + Sync,

type Content = T

The type of the content.

fn len(&self) -> DeviceSize

Returns the length of the buffer in number of elements.

impl<T, A> Eq for DeviceLocalBuffer<T, A>where
    T: BufferContents + ?Sized,
    A: Send + Sync,