Struct vulkano::buffer::cpu_pool::CpuBufferPool

pub struct CpuBufferPool<T, A = Arc<StdMemoryPool>> where
    A: MemoryPool,  { /* private fields */ }

Ring buffer from which “sub-buffers” can be individually allocated.

This buffer is especially suitable when you want to upload or download some data regularly (for example, at each frame for a video game).

Usage

A CpuBufferPool is similar to a ring buffer. You start by creating an empty pool, then you grab elements from the pool and use them, and if the pool is full it will automatically grow in size.

Contrary to a Vec, elements automatically free themselves when they are dropped (ie. usually when you call cleanup_finished() on a future, or when you drop that future).

Arc-like

The CpuBufferPool struct internally contains an Arc. You can clone the CpuBufferPool for a cheap cost, and all the clones will share the same underlying buffer.

Example

use vulkano::buffer::CpuBufferPool;
use vulkano::command_buffer::AutoCommandBufferBuilder;
use vulkano::command_buffer::CommandBufferUsage;
use vulkano::command_buffer::PrimaryCommandBuffer;
use vulkano::sync::GpuFuture;

// Create the ring buffer.
let buffer = CpuBufferPool::upload(device.clone());

for n in 0 .. 25u32 {
    // Each loop grabs a new entry from that ring buffer and stores ` data` in it.
    let data: [f32; 4] = [1.0, 0.5, n as f32 / 24.0, 0.0];
    let sub_buffer = buffer.next(data).unwrap();

    // You can then use `sub_buffer` as if it was an entirely separate buffer.
    AutoCommandBufferBuilder::primary(device.clone(), queue.family(), CommandBufferUsage::OneTimeSubmit)
        .unwrap()
        // For the sake of the example we just call `update_buffer` on the buffer, even though
        // it is pointless to do that.
        .update_buffer(sub_buffer.clone(), &[0.2, 0.3, 0.4, 0.5])
        .unwrap()
        .build().unwrap()
        .execute(queue.clone())
        .unwrap()
        .then_signal_fence_and_flush()
        .unwrap();
}

Implementations

impl<T> CpuBufferPool<T>

pub fn new(device: Arc<Device>, usage: BufferUsage) -> CpuBufferPool<T>

Builds a CpuBufferPool.

pub fn upload(device: Arc<Device>) -> CpuBufferPool<T>

Builds a CpuBufferPool meant for simple uploads.

Shortcut for a pool that can only be used as transfer source and with exclusive queue family accesses.

pub fn download(device: Arc<Device>) -> CpuBufferPool<T>

Builds a CpuBufferPool meant for simple downloads.

Shortcut for a pool that can only be used as transfer destination and with exclusive queue family accesses.

pub fn uniform_buffer(device: Arc<Device>) -> CpuBufferPool<T>

Builds a CpuBufferPool meant for usage as a uniform buffer.

Shortcut for a pool that can only be used as uniform buffer and with exclusive queue family accesses.

pub fn vertex_buffer(device: Arc<Device>) -> CpuBufferPool<T>

Builds a CpuBufferPool meant for usage as a vertex buffer.

Shortcut for a pool that can only be used as vertex buffer and with exclusive queue family accesses.

pub fn indirect_buffer(device: Arc<Device>) -> CpuBufferPool<T>

Builds a CpuBufferPool meant for usage as a indirect buffer.

Shortcut for a pool that can only be used as indirect buffer and with exclusive queue family accesses.

impl<T, A> CpuBufferPool<T, A> where
    A: MemoryPool, 

pub fn capacity(&self) -> DeviceSize

Returns the current capacity of the pool, in number of elements.

pub fn reserve(
    &self,
    capacity: DeviceSize
) -> Result<(), DeviceMemoryAllocError>

Makes sure that the capacity is at least capacity. Allocates memory if it is not the case.

Since this can involve a memory allocation, an OomError can happen.

pub fn next(
    &self,
    data: T
) -> Result<Arc<CpuBufferPoolSubbuffer<T, A>>, DeviceMemoryAllocError>

Grants access to a new subbuffer and puts data in it.

If no subbuffer is available (because they are still in use by the GPU), a new buffer will automatically be allocated.

Note: You can think of it like a Vec. If you insert an element and the Vec is not large enough, a new chunk of memory is automatically allocated.

pub fn chunk<I>(
    &self,
    data: I
) -> Result<Arc<CpuBufferPoolChunk<T, A>>, DeviceMemoryAllocError> where
    I: IntoIterator<Item = T>,
    I::IntoIter: ExactSizeIterator, 

Grants access to a new subbuffer and puts data in it.

If no subbuffer is available (because they are still in use by the GPU), a new buffer will automatically be allocated.

Note: You can think of it like a Vec. If you insert elements and the Vec is not large enough, a new chunk of memory is automatically allocated.

Panic

Panics if the length of the iterator didn’t match the actual number of element.

pub fn try_next(&self, data: T) -> Option<Arc<CpuBufferPoolSubbuffer<T, A>>>

Grants access to a new subbuffer and puts data in it.

Returns None if no subbuffer is available.

A CpuBufferPool is always empty the first time you use it, so you shouldn’t use try_next the first time you use it.

Trait Implementations

impl<T, A> Clone for CpuBufferPool<T, A> where
    A: MemoryPool + Clone, 

fn clone(&self) -> Self

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl<T, A> DeviceOwned for CpuBufferPool<T, A> where
    A: MemoryPool, 

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

Returns the device that owns Self.